zrb 1.21.9__py3-none-any.whl → 1.21.31__py3-none-any.whl

zrb/builtin/llm/tool/file.py

@@ -2,71 +2,15 @@ import fnmatch
 import json
 import os
 import re
-import sys
-from typing import Any, Literal, Optional
+from typing import Any, Optional
 
 from zrb.builtin.llm.tool.sub_agent import create_sub_agent_tool
 from zrb.config.config import CFG
 from zrb.config.llm_rate_limitter import llm_rate_limitter
 from zrb.context.any_context import AnyContext
+from zrb.task.llm.file_tool_model import FileReplacement, FileToRead, FileToWrite
 from zrb.util.file import read_file, read_file_with_line_numbers, write_file
 
-if sys.version_info >= (3, 12):
-    from typing import NotRequired, TypedDict
-else:
-    from typing_extensions import NotRequired, TypedDict
-
-
-class FileToRead(TypedDict):
-    """
-    Configuration for reading a file or file section.
-
-    Attributes:
-        path (str): Absolute or relative path to the file
-        start_line (int | None): Starting line number (1-based, inclusive).
-            If None, reads from beginning.
-        end_line (int | None): Ending line number (1-based, exclusive). If None, reads to end.
-    """
-
-    path: str
-    start_line: NotRequired[int | None]
-    end_line: NotRequired[int | None]
-
-
-class FileToWrite(TypedDict):
-    """
-    Configuration for writing content to a file.
-
-    Attributes:
-        path (str): Absolute or relative path where file will be written.
-        content (str): Content to write. CRITICAL: For JSON, ensure all special characters
-            in this string are properly escaped.
-        mode (str): Mode for writing:
-            'w' (overwrite, default), 'a' (append), 'x' (create exclusively).
-    """
-
-    path: str
-    content: str
-    mode: NotRequired[Literal["w", "wt", "tw", "a", "at", "ta", "x", "xt", "tx"]]
-
-
-class FileReplacement(TypedDict):
-    """
-    Configuration for a single text replacement operation in a file.
-
-    Attributes:
-        path (str): Absolute or relative path to the file
-        old_text (str): Exact text to find and replace (must match file content exactly)
-        new_text (str): New text to replace with
-        count (int): Optional. Number of occurrences to replace. Defaults to -1 (all).
-    """
-
-    path: str
-    old_text: str
-    new_text: str
-    count: NotRequired[int]
-
-
 DEFAULT_EXCLUDED_PATTERNS = [
     # Common Python artifacts
     "__pycache__",
@@ -184,7 +128,6 @@ def list_files(
                 if (include_hidden or not _is_hidden(d))
                 and not is_excluded(d, patterns_to_exclude)
             ]
-
             for filename in files:
                 if (include_hidden or not _is_hidden(filename)) and not is_excluded(
                     filename, patterns_to_exclude
@@ -237,10 +180,12 @@ def read_from_file(
     Reads content from one or more files, optionally specifying line ranges.
 
     Examples:
+    ```
     # Read entire content of a single file
     read_from_file(file={'path': 'path/to/file.txt'})
 
     # Read specific lines from a file
+    # The content will be returned with line numbers in the format: "LINE_NUMBER | line content"
     read_from_file(file={'path': 'path/to/large_file.log', 'start_line': 100, 'end_line': 150})
 
     # Read multiple files
@@ -248,12 +193,14 @@ def read_from_file(
         {'path': 'path/to/file1.txt'},
         {'path': 'path/to/file2.txt', 'start_line': 1, 'end_line': 5}
     ])
+    ```
 
     Args:
         file (FileToRead | list[FileToRead]): A single file configuration or a list of them.
 
     Returns:
         dict: Content and metadata for a single file, or a dict of results for multiple files.
+        The `content` field in the returned dictionary will have line numbers in the format: "LINE_NUMBER | line content"
     """
     is_list = isinstance(file, list)
     files = file if is_list else [file]
@@ -312,18 +259,20 @@ def write_to_file(
     Writes content to one or more files, with options for overwrite, append, or exclusive
     creation.
 
-    **CRITICAL:**
-    - The content for each file MUST NOT exceed 4000 characters.
-    - If your content is larger, you MUST split it into chunks and make multiple calls to this
-      tool.
-        - The first call should use 'w' mode.
-        - Then subsequent calls for the same file should use 'a' mode.
+    **CRITICAL - PREVENT JSON ERRORS:**
+    1. **ESCAPING:** Do NOT double-escape quotes.
+       - CORRECT: "content": "He said \"Hello\""
+       - WRONG:   "content": "He said \\"Hello\\""  <-- This breaks JSON parsing!
+    2. **SIZE LIMIT:** Content MUST NOT exceed 4000 characters.
+       - Exceeding this causes truncation and EOF errors.
+       - Split larger content into multiple sequential calls (first 'w', then 'a').
 
     Examples:
+    ```
     # Overwrite 'file.txt' with initial content
     write_to_file(file={'path': 'path/to/file.txt', 'content': 'Initial content.'})
 
-    # Append a second chunk to 'file.txt' (note the newline for separate lines)
+    # Append a second chunk to 'file.txt' (note the newline at the beginning of the content)
     write_to_file(file={'path': 'path/to/file.txt', 'content': '\nSecond chunk.', 'mode': 'a'})
 
     # Write to multiple files
@@ -331,6 +280,7 @@ def write_to_file(
         {'path': 'path/to/file1.txt', 'content': 'Content for file 1'},
         {'path': 'path/to/file2.txt', 'content': 'Content for file 2', 'mode': 'w'}
     ])
+    ```
 
     Args:
         file (FileToWrite | list[FileToWrite]): A single file configuration or a list of them.
@@ -481,18 +431,18 @@ def replace_in_file(
     **CRITICAL INSTRUCTIONS:**
     1. **READ FIRST:** Use `read_file` to get exact content. Do not guess.
     2. **EXACT MATCH:** `old_text` must match file content EXACTLY (whitespace, newlines).
-    3. **MINIMAL CONTEXT:** Keep `old_text` small (target lines + 2-3 context lines).
-       Large strings cause errors.
-    4. **DEFAULT:** Replaces **ALL** occurrences. Set `count=1` for first occurrence only.
+    3. **ESCAPING:** Do NOT double-escape quotes in `new_text`. Use `\"`, not `\\"`.
+    4. **SIZE LIMIT:** `new_text` MUST NOT exceed 4000 chars to avoid truncation/EOF errors.
+    5. **MINIMAL CONTEXT:** Keep `old_text` small (target lines + 2-3 context lines).
+    6. **DEFAULT:** Replaces **ALL** occurrences. Set `count=1` for first occurrence only.
 
     Examples:
+    ```
     # Replace ALL occurrences
-    replace_in_file(
-        file=[
-            {'path': 'file.txt', 'old_text': 'foo', 'new_text': 'bar'},
-            {'path': 'file.txt', 'old_text': 'baz', 'new_text': 'qux'}
-        ]
-    )
+    replace_in_file(file=[
+        {'path': 'file.txt', 'old_text': 'foo', 'new_text': 'bar'},
+        {'path': 'file.txt', 'old_text': 'baz', 'new_text': 'qux'}
+    ])
 
     # Replace ONLY the first occurrence
     replace_in_file(
@@ -507,6 +457,7 @@ def replace_in_file(
             'new_text': '    def new_fn():\n        pass'
         }
     )
+    ```
 
     Args:
         file: Single replacement config or list of them.
@@ -517,7 +468,7 @@ def replace_in_file(
     # Normalize to list
     file_replacements = file if isinstance(file, list) else [file]
     # Group replacements by file path to minimize file I/O
-    replacements_by_path = {}
+    replacements_by_path: dict[str, list[FileReplacement]] = {}
     for r in file_replacements:
         path = r["path"]
         if path not in replacements_by_path:
@@ -560,11 +511,17 @@ def replace_in_file(
 
 
 async def analyze_file(
-    ctx: AnyContext, path: str, query: str, token_limit: int | None = None
+    ctx: AnyContext, path: str, query: str, token_threshold: int | None = None
 ) -> dict[str, Any]:
     """
     Analyzes a file using a sub-agent for complex questions.
 
+    CRITICAL: The query must contain ALL necessary context, instructions, and information.
+        The sub-agent performing the analysis does NOT share your current conversation
+        history, memory, or global context.
+        The quality of analysis depends entirely on the query. Vague queries yield poor
+        results.
+
     Example:
     analyze_file(path='src/main.py', query='Summarize the main function.')
 
@@ -573,13 +530,13 @@ async def analyze_file(
         path (str): The path to the file to analyze.
         query (str): A specific analysis query with clear guidelines and
             necessary information.
-        token_limit (int | None): Max tokens.
+        token_threshold (int | None): Max tokens.
 
     Returns:
         Analysis results.
     """
-    if token_limit is None:
-        token_limit = CFG.LLM_FILE_ANALYSIS_TOKEN_LIMIT
+    if token_threshold is None:
+        token_threshold = CFG.LLM_FILE_ANALYSIS_TOKEN_THRESHOLD
     abs_path = os.path.abspath(os.path.expanduser(path))
     if not os.path.exists(abs_path):
         raise FileNotFoundError(f"File not found: {path}")
@@ -594,12 +551,16 @@ async def analyze_file(
         ),
         system_prompt=CFG.LLM_FILE_EXTRACTOR_SYSTEM_PROMPT,
         tools=[read_from_file, search_files],
+        auto_summarize=False,
+        remember_history=False,
     )
     payload = json.dumps(
         {
             "instruction": query,
             "file_path": abs_path,
-            "file_content": llm_rate_limitter.clip_prompt(file_content, token_limit),
+            "file_content": llm_rate_limitter.clip_prompt(
+                file_content, token_threshold
+            ),
         }
     )
     return await _analyze_file(ctx, payload)

zrb/builtin/llm/tool/note.py

@@ -5,10 +5,12 @@ from zrb.config.llm_context.config import llm_context_config
 
 def read_long_term_note() -> str:
     """
-    Reads the global long-term note, shared across all projects and conversations.
+    Retrieves the GLOBAL 🧠 Long Term Note shared across ALL sessions and projects.
+
+    Use this to recall user preferences, facts, and cross-project context.
 
     Returns:
-        str: The content of the long-term note.
+        str: The current global note content.
     """
     contexts = llm_context_config.get_notes()
     return contexts.get("/", "")
@@ -16,28 +18,39 @@ def read_long_term_note() -> str:
 
 def write_long_term_note(content: str) -> str:
     """
-    Writes or overwrites the global long-term note.
-    Use to remember key user preferences, goals, or facts relevant across all projects.
+    Persists CRITICAL facts to the GLOBAL 🧠 Long Term Note.
+
+    USE EAGERLY to save or update:
+    - User preferences (e.g., "I prefer Python", "No unit tests").
+    - User information (e.g., user name, user email address).
+    - Important facts (e.g., "My API key is in .env").
+    - Cross-project goals.
+    - Anything that will be useful for future interaction across projects.
+
+    WARNING: This OVERWRITES the entire Long Term Note.
 
     Args:
-        content (str): The information to save (overwrites entire note).
+        content (str): The text to strictly memorize.
 
     Returns:
-        str: A confirmation message.
+        str: Confirmation message.
     """
     llm_context_config.write_note(content, "/")
-    return "Long term note saved"
+    return "Global long-term note saved."
 
 
 def read_contextual_note(path: str | None = None) -> str:
     """
-    Reads a contextual note for a specific file or directory.
+    Retrieves LOCAL 📝 Contextual Note specific to a directory path.
+
+    Use to recall project-specific architecture, code summaries, or past decisions
+    relevant to the current working location.
 
     Args:
-        path (str | None): The file or directory path. Defaults to current working directory.
+        path (str | None): Target file/dir. Defaults to current working directory (CWD).
 
     Returns:
-        str: The content of the contextual note.
+        str: The local note content for the path.
     """
     if path is None:
         path = os.getcwd()
@@ -48,17 +61,24 @@ def read_contextual_note(path: str | None = None) -> str:
 
 def write_contextual_note(content: str, path: str | None = None) -> str:
     """
-    Writes or overwrites a note for a specific file or directory.
-    Use to save findings, summaries, or conclusions about a part of the project.
+    Persists LOCAL facts specific to a directory into 📝 Contextual Note.
+
+    USE EAGERLY to save or update:
+    - Architectural patterns for this project/directory.
+    - Summaries of large files or directories.
+    - Specific guidelines for this project.
+    - Anything related to this directory that will be useful for future interaction.
+
+    WARNING: This OVERWRITES the entire Contextual Note for a directory.
 
     Args:
-        content (str): The information to save (overwrites any existing note).
-        path (str | None): The file or directory path. Defaults to current working directory.
+        content (str): The text to memorize for this location.
+        path (str | None): Target file/dir. Defaults to CWD.
 
     Returns:
-        str: A confirmation message.
+        str: Confirmation message.
     """
     if path is None:
         path = os.getcwd()
     llm_context_config.write_note(content, path)
-    return f"Contextual note saved to {path}"
+    return f"Contextual note saved for: {path}"

zrb/builtin/llm/tool/search/__init__.py

@@ -0,0 +1 @@
+# This file makes the directory a Python package

zrb/builtin/llm/tool/search/brave.py

@@ -0,0 +1,60 @@
+from typing import Any
+
+import requests
+
+from zrb.config.config import CFG
+
+
+def search_internet(
+    query: str,
+    page: int = 1,
+    safe_search: str | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """
+    Performs an internet search using Brave Search.
+
+    Use this tool to find up-to-date information, answer questions about current events,
+    or research topics using a search engine.
+
+    Args:
+        query (str): The natural language search query (e.g., 'Soto Madura').
+            Do NOT include instructions, meta-talk, or internal reasoning.
+            Use concise terms as a human would in a search engine.
+        page (int): Search result page number. Defaults to 1.
+        safe_search (str | None): Safety setting. 'strict', 'moderate', or 'off'.
+            If None, uses the system default configuration.
+        language (str | None): Language code (e.g., 'en').
+            If None, uses the system default configuration.
+
+    Returns:
+        dict: Summary of search results (titles, links, snippets).
+    """
+    if safe_search is None:
+        safe_search = CFG.BRAVE_API_SAFE
+    if language is None:
+        language = CFG.BRAVE_API_LANG
+
+    user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"  # noqa
+
+    response = requests.get(
+        "https://api.search.brave.com/res/v1/web/search",
+        headers={
+            "User-Agent": user_agent,
+            "Accept": "application/json",
+            "x-subscription-token": CFG.BRAVE_API_KEY,
+        },
+        params={
+            "q": query,
+            "count": "10",
+            "offset": (page - 1) * 10,
+            "safesearch": safe_search,
+            "search_lang": language,
+            "summary": "true",
+        },
+    )
+    if response.status_code != 200:
+        raise Exception(
+            f"Error: Unable to retrieve search results (status code: {response.status_code})"
+        )
+    return response.json()

zrb/builtin/llm/tool/search/searxng.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+import requests
+
+from zrb.config.config import CFG
+
+
+def search_internet(
+    query: str,
+    page: int = 1,
+    safe_search: int | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """
+    Performs an internet search using SearXNG.
+
+    Use this tool to find up-to-date information, answer questions about current events,
+    or research topics using a search engine.
+
+    Args:
+        query (str): The natural language search query (e.g., 'Soto Madura').
+            Do NOT include instructions, meta-talk, or internal reasoning.
+            Use concise terms as a human would in a search engine.
+        page (int): Search result page number. Defaults to 1.
+        safe_search (int | None): Safety setting. 0 (None), 1 (Moderate), 2 (Strict).
+            If None, uses the system default configuration.
+        language (str | None): Language code (e.g., 'en').
+            If None, uses the system default configuration.
+
+    Returns:
+        dict: Summary of search results (titles, links, snippets).
+    """
+    if safe_search is None:
+        safe_search = CFG.SEARXNG_SAFE
+    if language is None:
+        language = CFG.SEARXNG_LANG
+
+    user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"  # noqa
+
+    response = requests.get(
+        url=f"{CFG.SEARXNG_BASE_URL}/search",
+        headers={"User-Agent": user_agent},
+        params={
+            "q": query,
+            "format": "json",
+            "pageno": page,
+            "safesearch": safe_search,
+            "language": language,
+        },
+    )
+    if response.status_code != 200:
+        raise Exception(
+            f"Error: Unable to retrieve search results (status code: {response.status_code})"
+        )
+    return response.json()

zrb/builtin/llm/tool/search/serpapi.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+import requests
+
+from zrb.config.config import CFG
+
+
+def search_internet(
+    query: str,
+    page: int = 1,
+    safe_search: str | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """
+    Performs an internet search using SerpApi (Google).
+
+    Use this tool to find up-to-date information, answer questions about current events,
+    or research topics using a search engine.
+
+    Args:
+        query (str): The natural language search query (e.g., 'Soto Madura').
+            Do NOT include instructions, meta-talk, or internal reasoning.
+            Use concise terms as a human would in a search engine.
+        page (int): Search result page number. Defaults to 1.
+        safe_search (str | None): Safety setting. 'active' or 'off'.
+            If None, uses the system default configuration.
+        language (str | None): Two-letter language code (e.g., 'en', 'id').
+            If None, uses the system default configuration.
+
+    Returns:
+        dict: Summary of search results (titles, links, snippets).
+    """
+    if safe_search is None:
+        safe_search = CFG.SERPAPI_SAFE
+    if language is None:
+        language = CFG.SERPAPI_LANG
+
+    user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"  # noqa
+
+    response = requests.get(
+        "https://serpapi.com/search",
+        headers={"User-Agent": user_agent},
+        params={
+            "q": query,
+            "start": (page - 1) * 10,
+            "hl": language,
+            "safe": safe_search,
+            "api_key": CFG.SERPAPI_KEY,
+        },
+    )
+    if response.status_code != 200:
+        raise Exception(
+            f"Error: Unable to retrieve search results (status code: {response.status_code})"
+        )
+    return response.json()

zrb/builtin/llm/tool/sub_agent.py

@@ -1,14 +1,21 @@
+import json
 from collections.abc import Callable
 from textwrap import dedent
 from typing import TYPE_CHECKING, Any, Coroutine
 
 from zrb.context.any_context import AnyContext
-from zrb.task.llm.agent import create_agent_instance, run_agent_iteration
+from zrb.task.llm.agent import create_agent_instance
+from zrb.task.llm.agent_runner import run_agent_iteration
 from zrb.task.llm.config import get_model, get_model_settings
 from zrb.task.llm.prompt import get_system_and_user_prompt
+from zrb.task.llm.subagent_conversation_history import (
+    get_ctx_subagent_history,
+    set_ctx_subagent_history,
+)
 
 if TYPE_CHECKING:
     from pydantic_ai import Tool
+    from pydantic_ai._agent_graph import HistoryProcessor
     from pydantic_ai.models import Model
     from pydantic_ai.settings import ModelSettings
     from pydantic_ai.toolsets import AbstractToolset
@@ -25,8 +32,12 @@ def create_sub_agent_tool(
     tools: "list[ToolOrCallable]" = [],
     toolsets: list["AbstractToolset[None]"] = [],
     yolo_mode: bool | list[str] | None = None,
+    history_processors: list["HistoryProcessor"] | None = None,
     log_indent_level: int = 2,
-) -> Callable[[AnyContext, str], Coroutine[Any, Any, dict[str, Any]]]:
+    agent_name: str | None = None,
+    auto_summarize: bool = True,
+    remember_history: bool = True,
+) -> Callable[[AnyContext, str], Coroutine[Any, Any, Any]]:
     """
     Create a tool that is another AI agent, capable of handling complex, multi-step sub-tasks.
 
@@ -52,8 +63,10 @@ def create_sub_agent_tool(
         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.
     """
+    if agent_name is None:
+        agent_name = f"{tool_name}_agent"
 
-    async def run_sub_agent(ctx: AnyContext, query: str) -> dict[str, Any]:
+    async def run_sub_agent(ctx: AnyContext, query: str) -> Any:
         """
         Runs the sub-agent with the given query.
         """
@@ -72,7 +85,6 @@ def create_sub_agent_tool(
             ctx=ctx,
             model_settings_attr=model_settings,
         )
-
         if system_prompt is None:
             resolved_system_prompt, query = get_system_and_user_prompt(
                 ctx=ctx,
@@ -92,24 +104,32 @@ def create_sub_agent_tool(
             tools=tools,
             toolsets=toolsets,
             yolo_mode=yolo_mode,
+            history_processors=history_processors,
+            auto_summarize=auto_summarize,
         )
-
         sub_agent_run = None
         # Run the sub-agent iteration
-        # Start with an empty history for the sub-agent
+        history_list = (
+            get_ctx_subagent_history(ctx, agent_name) if remember_history else []
+        )
         sub_agent_run = await run_agent_iteration(
             ctx=ctx,
             agent=sub_agent_agent,
             user_prompt=query,
             attachments=[],
-            history_list=[],
+            history_list=history_list,
             log_indent_level=log_indent_level,
         )
-
         # Return the sub-agent's final message content
         if sub_agent_run and sub_agent_run.result:
             # Return the final message content
-            return {"result": sub_agent_run.result.output}
+            if remember_history:
+                set_ctx_subagent_history(
+                    ctx,
+                    agent_name,
+                    json.loads(sub_agent_run.result.all_messages_json()),
+                )
+            return sub_agent_run.result.output
         ctx.log_warning("Sub-agent run did not produce a result.")
         raise ValueError(f"{tool_name} not returning any result")
 
@@ -123,7 +143,7 @@ def create_sub_agent_tool(
             query (str): The query or task for the sub-agent.
 
         Returns:
-            dict[str, Any]: The final response or result from the sub-agent.
+            Any: The final response or result from the sub-agent.
         """
     ).strip()