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

zrb/builtin/llm/tool/note.py

@@ -0,0 +1,84 @@
+import os
+
+from zrb.config.llm_context.config import llm_context_config
+
+
+def read_long_term_note() -> str:
+    """
+    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 current global note content.
+    """
+    contexts = llm_context_config.get_notes()
+    return contexts.get("/", "")
+
+
+def write_long_term_note(content: str) -> str:
+    """
+    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 text to strictly memorize.
+
+    Returns:
+        str: Confirmation message.
+    """
+    llm_context_config.write_note(content, "/")
+    return "Global long-term note saved."
+
+
+def read_contextual_note(path: str | None = None) -> str:
+    """
+    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): Target file/dir. Defaults to current working directory (CWD).
+
+    Returns:
+        str: The local note content for the path.
+    """
+    if path is None:
+        path = os.getcwd()
+    abs_path = os.path.abspath(path)
+    contexts = llm_context_config.get_notes(cwd=abs_path)
+    return contexts.get(abs_path, "")
+
+
+def write_contextual_note(content: str, path: str | None = None) -> str:
+    """
+    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 text to memorize for this location.
+        path (str | None): Target file/dir. Defaults to CWD.
+
+    Returns:
+        str: Confirmation message.
+    """
+    if path is None:
+        path = os.getcwd()
+    llm_context_config.write_note(content, path)
+    return f"Contextual note saved for: {path}"

zrb/builtin/llm/tool/rag.py

@@ -5,6 +5,7 @@ import os
 import sys
 from collections.abc import Callable
 from textwrap import dedent
+from typing import Any
 
 import ulid
 
@@ -44,35 +45,40 @@ def create_rag_from_directory(
     openai_embedding_model: str | None = None,
 ):
     """
-    Creates a powerful Retrieval-Augmented Generation (RAG) tool for querying a local knowledge base.
+    Create a powerful RAG (Retrieval-Augmented Generation) 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.
+    This factory function generates a tool that performs semantic search over a directory of
+    documents. It automatically indexes the documents into a vector database (ChromaDB) and
+    keeps it updated as files change.
 
-    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.
+    The generated tool is ideal for answering questions based on a specific set of documents,
+    such as project documentation or internal wikis.
 
     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.
+        tool_description (str): A clear description of what the tool does and when to use it.
+            This is what the LLM will see.
+        document_dir_path (str, optional): The path to the directory containing the documents
+            to be indexed.
+        vector_db_path (str, optional): The path where the ChromaDB vector database will be
+            stored.
+        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.
+        file_reader (list[RAGFileReader], optional): A list of custom file readers for
+            specific file types.
+        openai_api_key (str, optional): Your OpenAI API key for generating embeddings.
+        openai_base_url (str, optional): An optional base URL for the OpenAI API.
         openai_embedding_model (str, optional): The embedding model to use.
 
     Returns:
-        Callable: An asynchronous function that serves as the RAG tool.
+        An asynchronous function that serves as the RAG tool.
     """
 
-    async def retrieve(query: str) -> str:
+    async def retrieve(query: str) -> dict[str, Any]:
         # Docstring will be set dynamically below
         from chromadb import PersistentClient
         from chromadb.config import Settings
@@ -187,7 +193,7 @@ def create_rag_from_directory(
             query_embeddings=query_vector,
             n_results=max_result_count_val,
         )
-        return json.dumps(results)
+        return dict(results)
 
     retrieve.__name__ = tool_name
     retrieve.__doc__ = dedent(
@@ -196,7 +202,8 @@ def create_rag_from_directory(
         Args:
             query (str): The user query to search for in documents.
         Returns:
-            str: JSON string with search results: {{"ids": [...], "documents": [...], ...}}
+            dict[str, Any]: dictionary with search results:
+                {{"ids": [...], "documents": [...], ...}}
         """
     ).strip()
     return retrieve

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

@@ -4,19 +4,23 @@ 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 Agent, Tool
+    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
 
     ToolOrCallable = Tool | Callable
-else:
-    ToolOrCallable = Any
 
 
 def create_sub_agent_tool(
@@ -25,30 +29,44 @@ def create_sub_agent_tool(
     system_prompt: str | None = None,
     model: "str | Model | None" = None,
     model_settings: "ModelSettings | None" = None,
-    tools: list[ToolOrCallable] = [],
-    toolsets: list["AbstractToolset[Agent]"] = [],
-) -> Callable[[AnyContext, str], Coroutine[Any, Any, str]]:
+    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,
+    agent_name: str | None = None,
+    auto_summarize: bool = True,
+    remember_history: bool = True,
+) -> Callable[[AnyContext, str], Coroutine[Any, Any, Any]]:
     """
-    Creates a "tool that is another AI agent," capable of handling complex, multi-step sub-tasks.
+    Create a tool that is another AI agent, capable of handling complex, multi-step sub-tasks.
 
-    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 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 on accomplishing a specific task without being distracted by the main conversation.
 
     This is ideal for delegating complex tasks like analyzing a file or a repository.
 
     Args:
         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.
+        tool_description (str): A clear description of the sub-agent's purpose and when to
+            use it. This is what the LLM will see.
+        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.
-        toolsets (list, optional): A list of Toolset for the sub-agent.
+        tools (list, optional): A list of tools that will be exclusively available to the
+            sub-agent.
+        toolsets (list, optional): A list of Toolsets for the sub-agent.
 
     Returns:
-        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.
+        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) -> str:
+    async def run_sub_agent(ctx: AnyContext, query: str) -> Any:
         """
         Runs the sub-agent with the given query.
         """
@@ -67,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,
@@ -86,25 +103,35 @@ def create_sub_agent_tool(
             model_settings=resolved_model_settings,
             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,
-            history_list=[],  # Start with empty history for the sub-agent
+            attachments=[],
+            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 as a string
-            return json.dumps({"result": sub_agent_run.result.output})
-        else:
-            ctx.log_warning("Sub-agent run did not produce a result.")
-            return "Sub-agent failed to produce a result."
+            # Return the final message content
+            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")
 
     # Set the name and docstring for the callable function
     run_sub_agent.__name__ = tool_name
@@ -116,7 +143,7 @@ def create_sub_agent_tool(
             query (str): The query or task for the sub-agent.
 
         Returns:
-            str: The final response or result from the sub-agent.
+            Any: The final response or result from the sub-agent.
         """
     ).strip()