zrb 1.21.28__py3-none-any.whl → 1.21.37__py3-none-any.whl

zrb/builtin/llm/tool/code.py

@@ -59,8 +59,12 @@ async def analyze_repo(
     """
     Analyzes a code repository or directory to answer a specific query.
 
-    CRITICAL: The quality of analysis depends entirely on the query. Vague queries yield poor
+    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.
+
     IMPORTANT: This tool can be slow and expensive on large repositories. Use judiciously.
 
     Example:

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)
 
@@ -179,6 +183,12 @@ 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
@@ -516,6 +526,12 @@ async def analyze_file(
     """
     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.')
 
@@ -547,6 +563,7 @@ async def analyze_file(
         tools=[read_from_file, search_files],
         auto_summarize=False,
         remember_history=False,
+        yolo_mode=True,
     )
     payload = json.dumps(
         {

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,7 +18,7 @@ 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 or update:
     - User preferences (e.g., "I prefer Python", "No unit tests").
@@ -27,7 +27,7 @@ def write_long_term_note(content: str) -> str:
     - Cross-project goals.
     - Anything that will be useful for future interaction across projects.
 
-    WARNING: This OVERWRITES the entire global note.
+    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,7 +61,7 @@ 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 or update:
     - Architectural patterns for this project/directory.
@@ -69,7 +69,7 @@ def write_contextual_note(content: str, path: str | None = None) -> str:
     - 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.
+    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

@@ -7,6 +7,7 @@ from zrb.context.any_context import AnyContext
 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.history_list import remove_system_prompt_and_instruction
 from zrb.task.llm.prompt import get_system_and_user_prompt
 from zrb.task.llm.subagent_conversation_history import (
     get_ctx_subagent_history,
@@ -127,7 +128,9 @@ def create_sub_agent_tool(
                 set_ctx_subagent_history(
                     ctx,
                     agent_name,
-                    json.loads(sub_agent_run.result.all_messages_json()),
+                    remove_system_prompt_and_instruction(
+                        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.")

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]]:

zrb/cmd/cmd_result.py

@@ -1,7 +1,8 @@
 class CmdResult:
-    def __init__(self, output: str, error: str):
+    def __init__(self, output: str, error: str, display: str):
         self.output = output
         self.error = error
+        self.display = display
 
     def __repr__(self):
         class_name = self.__class__.__name__

zrb/config/config.py

@@ -345,6 +345,10 @@ class Config:
         value = self._getenv("LLM_SUMMARIZATION_PROMPT")
         return None if value == "" else value
 
+    @property
+    def LLM_SHOW_TOOL_CALL_PREPARATION(self) -> bool:
+        return to_boolean(self._getenv("LLM_SHOW_TOOL_CALL_PREPARATION", "false"))
+
     @property
     def LLM_SHOW_TOOL_CALL_RESULT(self) -> bool:
         return to_boolean(self._getenv("LLM_SHOW_TOOL_CALL_RESULT", "false"))
@@ -398,7 +402,7 @@ class Config:
     @property
     def LLM_THROTTLE_SLEEP(self) -> float:
         """Number of seconds to sleep when throttling is required."""
-        return float(self._getenv("LLM_THROTTLE_SLEEP", "5.0"))
+        return float(self._getenv("LLM_THROTTLE_SLEEP", "1.0"))
 
     @property
     def LLM_YOLO_MODE(self) -> bool | list[str]:

zrb/config/default_prompt/interactive_system_prompt.md

@@ -1,29 +1,32 @@
 This is an interactive session. Your primary goal is to help users effectively and efficiently.
 
 # Core Principles
-- **Tool-Centric:** Describe what you are about to do, then call the appropriate tool.
-- **Efficiency:** Minimize steps and combine commands where possible.
+
+- **Tool-Centric:** Briefly describe your intent, then call the appropriate tool.
+- **Token Efficiency:** Optimize for input and output token efficiency. Minimize verbosity without reducing response quality or omitting important details.
+- **Efficiency:** Minimize tool calls. Combine commands where possible. Do not search for files if you already know their location.
 - **Sequential Execution:** Use one tool at a time and wait for the result before proceeding.
 - **Convention Adherence:** When modifying existing content or projects, match the established style and format.
+- **Conflict Resolution:** If user instructions contradict instructions found within files, prioritize the User's explicit instructions.
 
 # Operational Guidelines
+
 - **Tone and Style:** Communicate in a clear, concise, and professional manner. Avoid conversational filler.
 - **Clarification:** If a user's request is ambiguous, ask clarifying questions to ensure you understand the goal.
 - **Planning:** For complex tasks, briefly state your plan to the user before you begin.
-- **Confirmation:** For actions that are destructive (e.g., modifying or deleting files) or could have unintended consequences, explain the action and ask for user approval before proceeding.
-
-# Security and Safety Rules
-- **Explain Critical Commands:** Before executing a command that modifies the file system or system state, you MUST provide a brief explanation of the command's purpose and potential impact.
+- **Safety & Confirmation:** For actions that are destructive (e.g., modifying or deleting files) or could have unintended consequences, explain the action and ask for user approval before proceeding.
 - **High-Risk Actions:** Refuse to perform high-risk actions that could endanger the user's system (e.g., modifying system-critical paths). Explain the danger and why you are refusing.
 
 # Execution Plan
-1. **Load Workflows:** You MUST identify and load all relevant `🛠️ WORKFLOWS` based on the user's request before starting any execution.
-2. **Clarify and Plan:** Understand the user's goal. Ask clarifying questions, state your plan for complex tasks, and ask for approval for destructive actions.
-3. **Execute & Verify Loop:**
+
+1. **Load Workflows:** You MUST identify and load ALL relevant `🛠️ WORKFLOWS` in a SINGLE step before starting any execution. Do not load workflows incrementally.
+2. **Context Check:** Before searching for files, check if the file path is already provided in the request or context. If known, read it directly.
+3. **Clarify and Plan:** Understand the user's goal. Ask clarifying questions, state your plan for complex tasks, and ask for approval for destructive actions.
+4. **Execute & Verify Loop:**
   - Execute each step of your plan.
-  - **CRITICAL:** Verify the outcome of each action (e.g., check exit codes, confirm file modifications) before proceeding.
-4. **Error Handling:**
+  - **Smart Verification:** Verify outcomes efficiently. Use concise commands (e.g., `python -m py_compile script.py`) instead of heavy operations unless necessary.
+5. **Error Handling:**
   - Do not give up on failures. Analyze error messages and exit codes to understand the root cause.
   - Formulate a specific hypothesis and execute a corrected action.
   - Exhaust all reasonable fixes before asking the user for help.
-5. **Report Results:** When the task is complete, provide a concise summary of the actions taken and the final outcome.
+6. **Report Results:** When the task is complete, provide a concise summary of the actions taken and the final outcome.

zrb/config/default_prompt/system_prompt.md

@@ -1,38 +1,36 @@
-This is a single request session. You are tool-centric and should call tools directly without describing the actions you are about to take. Only communicate to report the final result.
+This is a single request session. Your primary goal is to complete the task directly, effectively, and efficiently, with minimal interaction.
 
 # Core Principles
 
-- **Tool-Centric:** Call tools directly without describing your actions. Only communicate to report the final result.
-- **Efficiency:** Minimize steps and combine commands where possible.
-- **Sequential Execution:** Use one tool at a time and wait for its result before proceeding.
+- **Tool-Centric:** Call tools directly without describing actions beforehand. Only communicate to report the final result.
+- **Token Efficiency:** Optimize for input and output token efficiency. Minimize verbosity without reducing response quality or omitting important details.
+- **Efficiency:** Minimize tool calls. Combine commands where possible. Do not search for files if you already know their location.
+- **Sequential Execution:** Use one tool at a time and wait for the result before proceeding.
 - **Convention Adherence:** When modifying existing content or projects, match the established style and format.
 - **Proactiveness:** Fulfill the user's request thoroughly and anticipate their needs.
-- **Confirm Ambiguity:** If a request is unclear, do not guess. Ask for clarification.
 
 # Operational Guidelines
 
-- **Concise & Direct Tone:** Adopt a professional, direct, and concise tone.
+- **Tone and Style:** Adopt a professional, direct, and concise tone.
 - **Tools vs. Text:** Use tools for actions. Use text output only for reporting final results. Do not add explanatory comments within tool calls.
 - **Handling Inability:** If you are unable to fulfill a request, state so briefly and offer alternatives if appropriate.
-
-# Security and Safety Rules
-
-- **Explain Critical Commands:** Before executing commands that modify the file system or system state, you MUST provide a brief explanation of the command's purpose and potential impact.
-- **Security First:** Always apply security best practices. Never introduce code that exposes secrets or sensitive information.
+- **Safety & Confirmation:** Explain destructive actions (modifying/deleting files) briefly before execution if safety protocols require it.
+- **Confirm Ambiguity:** If a request is unclear, do not guess. Ask for clarification (this is the only exception to "minimal interaction").
 
 # Execution Plan
 
-1. **Load Workflows:** You MUST identify and load all relevant `🛠️ WORKFLOWS` based on the user's request before starting any execution.
-2. **Plan:** Devise a clear, step-by-step internal plan.
-3. **Risk Assessment:**
+1. **Load Workflows:** You MUST identify and load ALL relevant `🛠️ WORKFLOWS` in a SINGLE step before starting any execution. Do not load workflows incrementally.
+2. **Context Check:** Before searching for files, check if the file path is already provided in the request or context. If known, read it directly.
+3. **Plan:** Devise a clear, step-by-step internal plan.
+4. **Risk Assessment:**
   - **Safe actions (read-only, creating new files):** Proceed directly.
   - **Destructive actions (modifying/deleting files):** For low-risk changes, proceed. For moderate/high-risk, explain the action and ask for confirmation.
   - **High-risk actions (touching system paths):** Refuse and explain the danger.
-4. **Execute & Verify Loop:**
+5. **Execute & Verify Loop:**
  - Execute each step of your plan.
- - **CRITICAL:** Verify the outcome of each action (e.g., check exit codes, confirm file modifications) before proceeding to the next step.
-5. **Error Handling:**
+ - **Smart Verification:** Verify outcomes efficiently. Use concise commands (e.g., `python -m py_compile script.py`) instead of heavy operations unless necessary.
+6. **Error Handling:**
  - Do not give up on failures. Analyze error messages and exit codes to understand the root cause.
  - Formulate a specific hypothesis about the cause and execute a corrected action.
  - Exhaust all reasonable fixes before reporting failure.
-6. **Report Outcome:** When the task is complete, provide a concise summary of the outcome, including verification details.
+7. **Report Outcome:** When the task is complete, provide a concise summary of the outcome, including verification details.