zrb 1.21.17__py3-none-any.whl → 1.21.33__py3-none-any.whl

zrb/builtin/llm/tool/file.py

@@ -89,6 +89,10 @@ def list_files(
     """
     Lists files recursively up to a specified depth.
 
+    **EFFICIENCY TIP:**
+    Do NOT use this tool if you already know the file path (e.g., from the user's prompt).
+    Use `read_from_file` directly in that case. Only use this to explore directory structures.
+
     Example:
     list_files(path='src', include_hidden=False, depth=2)
 
@@ -128,7 +132,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
@@ -180,7 +183,14 @@ def read_from_file(
     """
     Reads content from one or more files, optionally specifying line ranges.
 
+    **EFFICIENCY TIP:**
+    For source code or configuration files, prefer reading the **entire file** at once
+    to ensure you have full context (imports, class definitions, etc.).
+    Only use `start_line` and `end_line` for extremely large files (like logs) or
+    when you are certain only a specific section is needed.
+
     Examples:
+    ```
     # Read entire content of a single file
     read_from_file(file={'path': 'path/to/file.txt'})
 
@@ -193,6 +203,7 @@ 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.
@@ -267,6 +278,7 @@ def write_to_file(
        - 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.'})
 
@@ -278,6 +290,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.
@@ -434,6 +447,7 @@ def replace_in_file(
     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'},
@@ -453,6 +467,7 @@ def replace_in_file(
             'new_text': '    def new_fn():\n        pass'
         }
     )
+    ```
 
     Args:
         file: Single replacement config or list of them.
@@ -506,11 +521,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.')
 
@@ -519,13 +540,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}")
@@ -540,12 +561,17 @@ async def analyze_file(
         ),
         system_prompt=CFG.LLM_FILE_EXTRACTOR_SYSTEM_PROMPT,
         tools=[read_from_file, search_files],
+        auto_summarize=False,
+        remember_history=False,
+        yolo_mode=True,
     )
     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,9 +5,9 @@ from zrb.config.llm_context.config import llm_context_config
 
 def read_long_term_note() -> str:
     """
-    Retrieves the GLOBAL long-term memory shared across ALL sessions and projects.
+    Retrieves the GLOBAL 🧠 Long Term Note shared across ALL sessions and projects.
 
-    CRITICAL: Consult this first for user preferences, facts, and cross-project context.
+    Use this to recall user preferences, facts, and cross-project context.
 
     Returns:
         str: The current global note content.
@@ -18,16 +18,16 @@ def read_long_term_note() -> str:
 
 def write_long_term_note(content: str) -> str:
     """
-    Persists CRITICAL facts to the GLOBAL long-term memory.
+    Persists CRITICAL facts to the GLOBAL 🧠 Long Term Note.
 
-    USE EAGERLY to save:
+    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 global note. Always read first.
+    WARNING: This OVERWRITES the entire Long Term Note.
 
     Args:
         content (str): The text to strictly memorize.
@@ -41,7 +41,7 @@ def write_long_term_note(content: str) -> str:
 
 def read_contextual_note(path: str | None = None) -> str:
     """
-    Retrieves LOCAL memory specific to a file or directory path.
+    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.
@@ -61,15 +61,15 @@ def read_contextual_note(path: str | None = None) -> str:
 
 def write_contextual_note(content: str, path: str | None = None) -> str:
     """
-    Persists LOCAL facts specific to a file or directory.
+    Persists LOCAL facts specific to a directory into 📝 Contextual Note.
 
-    USE EAGERLY to save:
+    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 note for the specific path. Always read first.
+    WARNING: This OVERWRITES the entire Contextual Note for a directory.
 
     Args:
         content (str): The text to memorize for this location.

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,66 @@
+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.
+
+    **EFFICIENCY TIP:**
+    Make your `query` specific and keyword-rich to get the best results in a single call.
+    Avoid vague queries that require follow-up searches.
+    Bad: "new python features"
+    Good: "python 3.12 new features list release date"
+
+    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,61 @@
+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.
+
+    **EFFICIENCY TIP:**
+    Make your `query` specific and keyword-rich to get the best results in a single call.
+    Avoid vague queries that require follow-up searches.
+    Bad: "new python features"
+    Good: "python 3.12 new features list release date"
+
+    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,61 @@
+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.
+
+    **EFFICIENCY TIP:**
+    Make your `query` specific and keyword-rich to get the best results in a single call.
+    Avoid vague queries that require follow-up searches.
+    Bad: "new python features"
+    Good: "python 3.12 new features list release date"
+
+    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()
 

zrb/builtin/llm/tool/web.py

@@ -2,6 +2,7 @@ from collections.abc import Callable
 from typing import Any
 from urllib.parse import urljoin
 
+from zrb.builtin.llm.tool.search import brave, searxng, serpapi
 from zrb.config.config import CFG
 from zrb.config.llm_config import llm_config
 
@@ -13,6 +14,11 @@ async def open_web_page(url: str) -> dict[str, Any]:
     Fetches, parses, and converts a web page to readable Markdown.
     Preserves semantic structure, removes non-essentials, and extracts all absolute links.
 
+    **EFFICIENCY TIP:**
+    Use this tool to read the full content of a specific search result or article.
+    It returns clean Markdown and a list of links, which is perfect for deep-diving
+    into a topic without navigating a browser UI.
+
     Example:
     open_web_page(url='https://www.example.com/article')
 
@@ -30,78 +36,17 @@ async def open_web_page(url: str) -> dict[str, Any]:
 def create_search_internet_tool() -> Callable:
     if llm_config.default_search_internet_tool is not None:
         return llm_config.default_search_internet_tool
-
-    def search_internet(query: str, page: int = 1) -> dict[str, Any]:
-        """
-        Performs an internet search using a search engine.
-        Use to find information, answer general knowledge, or research topics.
-
-        Example:
-        search_internet(query='latest AI advancements', page=1)
-
-        Args:
-            query (str): The search query.
-            page (int, optional): Search result page number. Defaults to 1.
-
-        Returns:
-            dict: Summary of search results (titles, links, snippets).
-        """
-        import requests
-
-        if (
-            CFG.SEARCH_INTERNET_METHOD.strip().lower() == "serpapi"
-            and CFG.SERPAPI_KEY != ""
-        ):
-            response = requests.get(
-                "https://serpapi.com/search",
-                headers={"User-Agent": _DEFAULT_USER_AGENT},
-                params={
-                    "q": query,
-                    "start": (page - 1) * 10,
-                    "hl": CFG.SERPAPI_LANG,
-                    "safe": CFG.SERPAPI_SAFE,
-                    "api_key": CFG.SERPAPI_KEY,
-                },
-            )
-        elif (
-            CFG.SEARCH_INTERNET_METHOD.strip().lower() == "brave"
-            and CFG.BRAVE_API_KEY != ""
-        ):
-            response = requests.get(
-                "https://api.search.brave.com/res/v1/web/search",
-                headers={
-                    "User-Agent": _DEFAULT_USER_AGENT,
-                    "Accept": "application/json",
-                    "x-subscription-token": CFG.BRAVE_API_KEY,
-                },
-                params={
-                    "q": query,
-                    "count": "10",
-                    "offset": (page - 1) * 10,
-                    "safesearch": CFG.BRAVE_API_SAFE,
-                    "search_lang": CFG.BRAVE_API_LANG,
-                    "summary": "true",
-                },
-            )
-        else:
-            response = requests.get(
-                url=f"{CFG.SEARXNG_BASE_URL}/search",
-                headers={"User-Agent": _DEFAULT_USER_AGENT},
-                params={
-                    "q": query,
-                    "format": "json",
-                    "pageno": page,
-                    "safesearch": CFG.SEARXNG_SAFE,
-                    "language": CFG.SEARXNG_LANG,
-                },
-            )
-        if response.status_code != 200:
-            raise Exception(
-                f"Error: Unable to retrieve search results (status code: {response.status_code})"  # noqa
-            )
-        return response.json()
-
-    return search_internet
+    if (
+        CFG.SEARCH_INTERNET_METHOD.strip().lower() == "serpapi"
+        and CFG.SERPAPI_KEY != ""
+    ):
+        return serpapi.search_internet
+    if (
+        CFG.SEARCH_INTERNET_METHOD.strip().lower() == "brave"
+        and CFG.BRAVE_API_KEY != ""
+    ):
+        return brave.search_internet
+    return searxng.search_internet
 
 
 async def _fetch_page_content(url: str) -> tuple[str, list[str]]: