zrb 1.15.3__py3-none-any.whl → 1.21.29__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 memory shared across ALL sessions and projects.
+
+    CRITICAL: Consult this first for 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 memory.
+
+    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.
+
+    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 memory specific to a file or 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 file or directory.
+
+    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.
+
+    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,49 +45,40 @@ def create_rag_from_directory(
     openai_embedding_model: str | None = None,
 ):
     """
-    Creates a powerful RAG tool for querying a local knowledge base.
-
-    This factory function generates a tool that can perform semantic searches
-    over a directory of documents. It automatically indexes the documents into
-    a vector database, keeping it updated as files change. The generated tool
-    is ideal for answering questions based on a specific set of documents,
-    such as project documentation, research papers, or internal wikis.
-
-    The created tool will:
-    1.  Monitor a specified directory for file changes.
-    2.  Automatically update a vector database (ChromaDB) with the latest
-        content.
-    3.  Accept a user query, embed it, and perform a similarity search against
-        the document vectors.
-    4.  Return the most relevant document chunks that match the query.
+    Create a powerful RAG (Retrieval-Augmented Generation) tool for querying a local
+    knowledge base.
+
+    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 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
+        tool_name (str): The name for the generated RAG tool (e.g., "search_project_docs").
+        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.
-        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
+        max_result_count (int, optional): The maximum number of search results to return.
+        file_reader (list[RAGFileReader], optional): A list of custom file readers for
             specific file types.
-        openai_api_key (str, optional): OpenAI API key for embeddings.
-        openai_base_url (str, optional): OpenAI base URL for embeddings.
+        openai_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
@@ -201,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(
@@ -210,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/sub_agent.py

@@ -4,12 +4,18 @@ 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
@@ -24,43 +30,43 @@ def create_sub_agent_tool(
     model: "str | Model | None" = None,
     model_settings: "ModelSettings | None" = None,
     tools: "list[ToolOrCallable]" = [],
-    toolsets: list["AbstractToolset[Agent]"] = [],
-    is_yolo_mode: bool | None = None,
-) -> Callable[[AnyContext, str], Coroutine[Any, Any, str]]:
+    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.
+    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.
-        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.
+        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 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.
         """
@@ -79,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,
@@ -98,27 +103,35 @@ def create_sub_agent_tool(
             model_settings=resolved_model_settings,
             tools=tools,
             toolsets=toolsets,
-            is_yolo_mode=is_yolo_mode,
+            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 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
@@ -130,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()
 

zrb/builtin/llm/tool/web.py

@@ -1,142 +1,118 @@
-import json
 from collections.abc import Callable
+from typing import Any
 from urllib.parse import urljoin
 
+from zrb.config.config import CFG
+from zrb.config.llm_config import llm_config
 
-async def open_web_page(url: str) -> str:
+_DEFAULT_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
+
+
+async def open_web_page(url: str) -> dict[str, Any]:
     """
-    Fetches, parses, and converts the content of a web page to Markdown.
+    Fetches, parses, and converts a web page to readable Markdown.
+    Preserves semantic structure, removes non-essentials, and extracts all absolute links.
 
-    This tool "reads" a web page by fetching its content, stripping away
-    non-essential elements like scripts and styles, and then converting the
-    cleaned HTML into Markdown format. This preserves the semantic structure
-    of the content (headings, lists, etc.) while removing clutter. It also
-    extracts all hyperlinks and resolves them to absolute URLs.
+    Example:
+    open_web_page(url='https://www.example.com/article')
 
     Args:
-        url (str): The full URL of the web page to open (e.g.,
-            "https://example.com/article").
+        url (str): The full URL of the web page.
 
     Returns:
-        str: A JSON object containing the page's content in Markdown format
-            and a list of all absolute links found on the page.
+        dict: Markdown content and a list of absolute links.
     """
     html_content, links = await _fetch_page_content(url)
     markdown_content = _convert_html_to_markdown(html_content)
-    return json.dumps({"content": markdown_content, "links_on_page": links})
-
-
-def create_search_internet_tool(serp_api_key: str) -> Callable[[str, int], str]:
-    """
-    Creates a tool that searches the internet using the SerpAPI Google Search
-    API.
-
-    This factory returns a function that can be used to find information on the
-    web. The generated tool is the primary way to answer general knowledge
-    questions or to find information on topics you are unfamiliar with.
+    return {"content": markdown_content, "links_on_page": links}
 
-    Args:
-        serp_api_key (str): The API key for SerpAPI.
 
-    Returns:
-        Callable: A function that takes a search query and returns a list of
-            search results.
-    """
+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, num_results: int = 10) -> str:
+    def search_internet(query: str, page: int = 1) -> dict[str, Any]:
         """
-        Performs an internet search using Google and returns a summary of the results.
+        Performs an internet search using a search engine.
+        Use to find information, answer general knowledge, or research topics.
 
-        Use this tool to find information on the web, answer general knowledge questions, or research topics.
+        Example:
+        search_internet(query='latest AI advancements', page=1)
 
         Args:
             query (str): The search query.
-            num_results (int, optional): The desired number of search results. Defaults to 10.
+            page (int, optional): Search result page number. Defaults to 1.
 
         Returns:
-            str: A formatted string summarizing the search results, including titles, links, and snippets.
+            dict: Summary of search results (titles, links, snippets).
         """
         import requests
 
-        response = requests.get(
-            "https://serpapi.com/search",
-            headers={
-                "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"
-            },
-            params={
-                "q": query,
-                "num": num_results,
-                "hl": "en",
-                "safe": "off",
-                "api_key": serp_api_key,
-            },
-        )
+        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})"
+                f"Error: Unable to retrieve search results (status code: {response.status_code})"  # noqa
             )
         return response.json()
 
     return search_internet
 
 
-def search_wikipedia(query: str) -> str:
-    """
-    Searches for articles on Wikipedia.
-
-    This is a specialized search tool for querying Wikipedia. It's best for
-    when the user is asking for definitions, historical information, or
-    biographical details that are likely to be found on an encyclopedia.
-
-    Args:
-        query (str): The search term or question.
-
-    Returns:
-        str: The raw JSON response from the Wikipedia API, containing a list of
-            search results.
-    """
-    import requests
-
-    params = {"action": "query", "list": "search", "srsearch": query, "format": "json"}
-    response = requests.get("https://en.wikipedia.org/w/api.php", params=params)
-    return response.json()
-
-
-def search_arxiv(query: str, num_results: int = 10) -> str:
-    """
-    Searches for academic papers and preprints on ArXiv.
-
-    Use this tool when the user's query is scientific or technical in nature
-    and they are likely looking for research papers, articles, or academic
-    publications.
-
-    Args:
-        query (str): The search query, which can include keywords, author
-            names, or titles.
-        num_results (int, optional): The maximum number of results to return.
-            Defaults to 10.
-
-    Returns:
-        str: The raw XML response from the ArXiv API, containing a list of
-            matching papers.
-    """
-    import requests
-
-    params = {"search_query": f"all:{query}", "start": 0, "max_results": num_results}
-    response = requests.get("http://export.arxiv.org/api/query", params=params)
-    return response.content
-
-
 async def _fetch_page_content(url: str) -> tuple[str, list[str]]:
     """Fetches the HTML content and all absolute links from a URL."""
-    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"
     try:
         from playwright.async_api import async_playwright
 
         async with async_playwright() as p:
             browser = await p.chromium.launch(headless=True)
             page = await browser.new_page()
-            await page.set_extra_http_headers({"User-Agent": user_agent})
+            await page.set_extra_http_headers({"User-Agent": _DEFAULT_USER_AGENT})
             try:
                 await page.goto(url, wait_until="networkidle", timeout=30000)
                 await page.wait_for_load_state("domcontentloaded")
@@ -164,7 +140,7 @@ async def _fetch_page_content(url: str) -> tuple[str, list[str]]:
         import requests
         from bs4 import BeautifulSoup
 
-        response = requests.get(url, headers={"User-Agent": user_agent})
+        response = requests.get(url, headers={"User-Agent": _DEFAULT_USER_AGENT})
         if response.status_code != 200:
             raise Exception(
                 f"Unable to retrieve page content. Status code: {response.status_code}"

zrb/builtin/project/add/fastapp/fastapp_template/my_app_name/_zrb/entity/add_entity_util.py

@@ -204,7 +204,7 @@ def update_migration_metadata_file(ctx: AnyContext, migration_metadata_file_path
     app_name = os.path.basename(APP_DIR)
     existing_migration_metadata_code = read_file(migration_metadata_file_path)
     write_file(
-        file_path=migration_metadata_file_path,
+        abs_file_path=migration_metadata_file_path,
         content=[
             _get_migration_import_schema_code(
                 existing_migration_metadata_code, app_name, ctx.input.entity
@@ -251,7 +251,7 @@ def update_client_file(ctx: AnyContext, client_file_path: str):
     snake_plural_entity_name = to_snake_case(ctx.input.plural)
     pascal_entity_name = to_pascal_case(ctx.input.entity)
     write_file(
-        file_path=client_file_path,
+        abs_file_path=client_file_path,
         content=[
             _get_import_schema_for_client_code(
                 existing_code=existing_client_code, entity_name=ctx.input.entity
@@ -305,7 +305,7 @@ def update_api_client_file(ctx: AnyContext, api_client_file_path: str):
     snake_module_name = to_snake_case(ctx.input.module)
     pascal_module_name = to_pascal_case(ctx.input.module)
     write_file(
-        file_path=api_client_file_path,
+        abs_file_path=api_client_file_path,
         content=[
             f"from {app_name}.module.{snake_module_name}.service.{snake_entity_name}.{snake_entity_name}_service_factory import {snake_entity_name}_service",  # noqa
             prepend_code_to_module(
@@ -327,7 +327,7 @@ def update_direct_client_file(ctx: AnyContext, direct_client_file_path: str):
     snake_module_name = to_snake_case(ctx.input.module)
     pascal_module_name = to_pascal_case(ctx.input.module)
     write_file(
-        file_path=direct_client_file_path,
+        abs_file_path=direct_client_file_path,
         content=[
             f"from {app_name}.module.{snake_module_name}.service.{snake_entity_name}.{snake_entity_name}_service_factory import {snake_entity_name}_service",  # noqa
             prepend_code_to_module(
@@ -348,7 +348,7 @@ def update_route_file(ctx: AnyContext, route_file_path: str):
     app_name = os.path.basename(APP_DIR)
     module_name = to_snake_case(ctx.input.module)
     write_file(
-        file_path=route_file_path,
+        abs_file_path=route_file_path,
         content=[
             f"from {app_name}.module.{module_name}.service.{entity_name}.{entity_name}_service_factory import {entity_name}_service",  # noqa
             append_code_to_function(
@@ -370,7 +370,7 @@ def update_gateway_subroute_file(ctx: AnyContext, module_gateway_subroute_path:
     pascal_entity_name = to_pascal_case(ctx.input.entity)
     existing_gateway_subroute_code = read_file(module_gateway_subroute_path)
     write_file(
-        file_path=module_gateway_subroute_path,
+        abs_file_path=module_gateway_subroute_path,
         content=[
             _get_import_client_for_gateway_subroute_code(
                 existing_gateway_subroute_code, module_name=ctx.input.module
@@ -456,7 +456,7 @@ def update_gateway_navigation_config_file(
         },
     ).strip()
     write_file(
-        file_path=gateway_navigation_config_file_path,
+        abs_file_path=gateway_navigation_config_file_path,
         content=[
             existing_gateway_navigation_config_code,
             new_navigation_config_code,