zrb 1.21.29__py3-none-any.whl → 2.0.0a4__py3-none-any.whl

zrb/llm/tool/note.py

@@ -0,0 +1,70 @@
+import os
+from typing import Callable, List
+
+from zrb.llm.note.manager import NoteManager
+
+
+def create_note_tools(note_manager: NoteManager) -> List[Callable]:
+    async def read_long_term_note() -> str:
+        """
+        Retrieves your GLOBAL 🧠 Long-Term Memory.
+        This contains established preferences, personal facts, and context spanning multiple projects.
+        ALWAYS check this at the start of a session.
+        """
+        return note_manager.read("~")
+
+    read_long_term_note.__name__ = "read_long_term_note"
+
+    async def write_long_term_note(content: str) -> str:
+        """
+        Updates your GLOBAL 🧠 Long-Term Memory with CRITICAL information.
+        Use this to persist user preferences, personal facts, and cross-project rules.
+
+        **WARNING:** This COMPLETELY OVERWRITES the existing Long-Term Note.
+
+        **ARGS:**
+        - `content`: The full text to store in the global memory.
+        """
+        note_manager.write("~", content)
+        return "Global long-term note saved."
+
+    write_long_term_note.__name__ = "write_long_term_note"
+
+    async def read_contextual_note(path: str | None = None) -> str:
+        """
+        Retrieves LOCAL 📝 Contextual Notes for a specific project or directory.
+        Use this to recall architectural decisions or project-specific guidelines.
+
+        **ARGS:**
+        - `path`: Target file/dir path. Defaults to current working directory.
+        """
+        if path is None:
+            path = os.getcwd()
+        return note_manager.read(path)
+
+    read_contextual_note.__name__ = "read_contextual_note"
+
+    async def write_contextual_note(content: str, path: str | None = None) -> str:
+        """
+        Persists LOCAL 📝 Contextual Notes for a specific project or directory.
+        Use this to save architectural patterns or progress markers for the current task.
+
+        **WARNING:** This COMPLETELY OVERWRITES the contextual note for the specified path.
+
+        **ARGS:**
+        - `content`: The full text to store in the local memory.
+        - `path`: Target file/dir path. Defaults to current working directory.
+        """
+        if path is None:
+            path = os.getcwd()
+        note_manager.write(path, content)
+        return f"Contextual note saved for: {path}"
+
+    write_contextual_note.__name__ = "write_contextual_note"
+
+    return [
+        read_long_term_note,
+        write_long_term_note,
+        read_contextual_note,
+        write_contextual_note,
+    ]

zrb/{builtin/llm → llm}/tool/rag.py

@@ -199,11 +199,14 @@ def create_rag_from_directory(
     retrieve.__doc__ = dedent(
         f"""
         {tool_description}
-        Args:
-            query (str): The user query to search for in documents.
-        Returns:
-            dict[str, Any]: dictionary with search results:
-                {{"ids": [...], "documents": [...], ...}}
+        This tool performs a semantic search across a curated knowledge base of documents.
+        It is highly effective for answering questions that require specific project knowledge not found in general training data.
+
+        **ARGS:**
+        - `query` (str): The semantic search query or question.
+
+        **RETURNS:**
+        - A dictionary containing matching document chunks ("documents") and their metadata.
         """
     ).strip()
     return retrieve

zrb/llm/tool/search/brave.py

@@ -0,0 +1,53 @@
+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 a live internet search using Brave Search to retrieve up-to-date information, news, or documentation.
+
+    **WHEN TO USE:**
+    - To find the latest information on rapidly changing topics (e.g., library updates, current events).
+    - To search for documentation or examples not present in the local codebase.
+    - To verify facts or find external resources.
+
+    **ARGS:**
+    - `query`: The search string or question.
+    - `page`: Result page number (default 1).
+    """
+    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"
+
+    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/llm/tool/search/searxng.py

@@ -0,0 +1,47 @@
+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 a live internet search using SearXNG, an aggregator that combines results from multiple search engines.
+
+    **WHEN TO USE:**
+    - To gather diverse perspectives or information from across the web.
+    - To retrieve the latest data, documentation, or public resources.
+
+    **ARGS:**
+    - `query`: The search string or question.
+    - `page`: Result page number (default 1).
+    """
+    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"
+
+    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/llm/tool/search/serpapi.py

@@ -0,0 +1,47 @@
+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 a live internet search using SerpApi (Google Search) to retrieve the most relevant and current information from the web.
+
+    **WHEN TO USE:**
+    - When you need precise, high-quality search results from Google.
+    - To find the latest official documentation, technical articles, or community discussions.
+
+    **ARGS:**
+    - `query`: The search string or question.
+    - `page`: Result page number (default 1).
+    """
+    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"
+
+    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/llm/tool/skill.py

@@ -0,0 +1,19 @@
+from zrb.llm.skill.manager import SkillManager
+
+
+def create_activate_skill_tool(skill_manager: SkillManager):
+    async def activate_skill_impl(name: str) -> str:
+        content = skill_manager.get_skill_content(name)
+        if content:
+            return f"<ACTIVATED_SKILL>\n{content}\n</ACTIVATED_SKILL>"
+        return f"Skill '{name}' not found."
+
+    activate_skill_impl.__name__ = "activate_skill"
+    activate_skill_impl.__doc__ = (
+        "Immediately activates a specialized expertise 'skill' to handle complex or domain-specific tasks. "
+        "Returns a set of authoritative instructions that YOU MUST follow to complete the task successfully. "
+        "Use this as soon as you identify a task that matches an available skill. "
+        "\n\n**ARGS:**"
+        "\n- `name`: The unique name of the skill to activate."
+    )
+    return activate_skill_impl

zrb/llm/tool/sub_agent.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+from zrb.llm.agent.agent import create_agent, run_agent
+from zrb.llm.config.config import LLMConfig
+from zrb.llm.config.config import llm_config as default_config
+from zrb.llm.config.limiter import LLMLimiter
+from zrb.llm.config.limiter import llm_limiter as default_limiter
+from zrb.llm.history_manager.any_history_manager import AnyHistoryManager
+from zrb.llm.history_manager.file_history_manager import FileHistoryManager
+
+
+def create_sub_agent_tool(
+    name: str,
+    description: str,
+    model: str | None = None,
+    system_prompt: str = "",
+    tools: list = [],
+    llm_config: LLMConfig | None = None,
+    llm_limitter: LLMLimiter | None = None,
+    history_manager: AnyHistoryManager | None = None,
+    conversation_name: str = "sub_agent_default",
+) -> Any:
+    """
+    Creates a Tool that invokes a sub-agent.
+    The sub-agent manages its own persistent history via HistoryManager
+    and handles approval via CLI fallback if needed.
+    """
+    config = llm_config or default_config
+    limiter = llm_limitter or default_limiter
+    manager = history_manager or FileHistoryManager(history_dir="~/.llm_chat/subagents")
+    final_model = model or config.model
+
+    agent_instance = None
+
+    async def run_sub_agent(prompt: str) -> str:
+        nonlocal agent_instance
+        if agent_instance is None:
+            agent_instance = create_agent(
+                model=final_model,
+                system_prompt=system_prompt,
+                tools=tools,
+                yolo=False,
+            )
+
+        # Load persistent history
+        history = manager.load(conversation_name)
+
+        # Execute agent with blocking confirmation loop for approvals
+        result, new_history = await run_agent(
+            agent=agent_instance,
+            message=prompt,
+            message_history=history,
+            limiter=limiter,
+        )
+
+        # Save updated history
+        manager.update(conversation_name, new_history)
+        manager.save(conversation_name)
+
+        return str(result)
+
+    run_sub_agent.__name__ = name
+    run_sub_agent.__doc__ = (
+        f"DELEGATION TOOL: {description}\n\n"
+        "Use this tool to delegate complex, multi-step sub-tasks to a specialized agent. "
+        "The sub-agent has its own memory and can perform its own tool calls."
+        "\n\n**ARGS:**"
+        "\n- `prompt`: The clear and detailed objective or instruction for the sub-agent."
+    )
+    return run_sub_agent

zrb/llm/tool/web.py

@@ -0,0 +1,97 @@
+from zrb.config.config import CFG
+
+
+async def open_web_page(url: str) -> dict:
+    """
+    Downloads and converts a web page into clean, readable Markdown.
+
+    **WHEN TO USE:**
+    - To read specific articles, documentation, or blog posts.
+    - To extract structured information from a known URL.
+
+    **ARGS:**
+    - `url`: The full web address to fetch.
+    """
+    html_content, links = await _fetch_page_content(url)
+    markdown_content = _convert_html_to_markdown(html_content)
+    return {"content": markdown_content, "links_on_page": links}
+
+
+async def search_internet(
+    query: str,
+    page: int = 1,
+) -> dict:
+    """
+    Performs a broad internet search.
+
+    **WHEN TO USE:**
+    - When you need to find information but don't have a specific URL.
+
+    **ARGS:**
+    - `query`: The search string or question.
+    - `page`: Result page number (default 1).
+    """
+    if (
+        CFG.SEARCH_INTERNET_METHOD.strip().lower() == "serpapi"
+        and CFG.SERPAPI_KEY != ""
+    ):
+        from zrb.llm.tool.search.serpapi import search_internet as serpapi_search
+
+        return serpapi_search(query, page=page)
+    if (
+        CFG.SEARCH_INTERNET_METHOD.strip().lower() == "brave"
+        and CFG.BRAVE_API_KEY != ""
+    ):
+        from zrb.llm.tool.search.brave import search_internet as brave_search
+
+        return brave_search(query, page=page)
+    from zrb.llm.tool.search.searxng import search_internet as searxng_search
+
+    return searxng_search(query, page=page)
+
+
+async def _fetch_page_content(url: str) -> tuple:
+    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.goto(url, wait_until="networkidle", timeout=30000)
+            content = await page.content()
+            links = await page.eval_on_selector_all(
+                "a[href]",
+                "(elements, baseUrl) => elements.map(el => { const href = el.getAttribute('href'); if (!href || href.startsWith('#')) return null; try { return new URL(href, baseUrl).href; } catch (e) { return null; } }).filter(href => href !== null)",
+                url,
+            )
+            await browser.close()
+            return content, links
+    except Exception:
+        from urllib.parse import urljoin
+
+        import requests
+        from bs4 import BeautifulSoup
+
+        response = requests.get(url, headers={"User-Agent": user_agent})
+        response.raise_for_status()
+        soup = BeautifulSoup(response.text, "html.parser")
+        links = [
+            urljoin(url, a["href"])
+            for a in soup.find_all("a", href=True)
+            if not a["href"].startswith("#")
+        ]
+        return response.text, links
+
+
+def _convert_html_to_markdown(html_text: str) -> str:
+    from bs4 import BeautifulSoup
+    from markdownify import markdownify as md
+
+    soup = BeautifulSoup(html_text, "html.parser")
+    for tag in soup(
+        ["script", "link", "meta", "style", "header", "footer", "nav", "aside"]
+    ):
+        tag.decompose()
+    return md(str(soup))

zrb/llm/tool/zrb_task.py

@@ -0,0 +1,66 @@
+from zrb.config.config import CFG
+from zrb.llm.tool.bash import run_shell_command
+from zrb.runner.cli import cli
+
+
+def create_list_zrb_task_tool():
+    def list_zrb_tasks_impl(group_name: str | None = None) -> str:
+        target_group = cli
+        if group_name:
+            parts = group_name.split()
+            for part in parts:
+                next_group = target_group.get_group_by_alias(part)
+                if not next_group:
+                    return f"Error: Group '{part}' not found in '{group_name}'."
+                target_group = next_group
+        output = [f"Tasks in '{target_group.name}':"]
+        # Subgroups
+        if target_group.subgroups:
+            output.append("\n  Groups:")
+            for alias, grp in target_group.subgroups.items():
+                output.append(f"    - {alias}: {grp.description}")
+        # Tasks
+        if target_group.subtasks:
+            output.append("\n  Tasks:")
+            for alias, task in target_group.subtasks.items():
+                output.append(f"    - {alias}: {task.description}")
+        return "\n".join(output)
+
+    zrb_cmd = CFG.ROOT_GROUP_NAME
+    list_zrb_tasks_impl.__name__ = f"list_{zrb_cmd}_tasks"
+    list_zrb_tasks_impl.__doc__ = (
+        f"Discovery tool to browse all available {zrb_cmd} tasks and automation groups. "
+        "Use this to understand what predefined workflows exist in the current project."
+        "\n\n**ARGS:**"
+        "\n- `group_name`: Optional name of the group to browse (e.g., 'server')."
+    )
+    return list_zrb_tasks_impl
+
+
+def create_run_zrb_task_tool():
+    async def run_zrb_task(
+        task_name: str, args: dict[str, str] = {}, timeout: int = 30
+    ) -> str:
+        """ """
+        # Construct command
+        cmd_parts = ["zrb"] + task_name.split()
+
+        for key, val in args.items():
+            cmd_parts.append(f"--{key}")
+            cmd_parts.append(str(val))
+
+        command = " ".join(cmd_parts)
+        return await run_shell_command(command, timeout=timeout)
+
+    zrb_cmd = CFG.ROOT_GROUP_NAME
+    run_zrb_task.__name__ = f"run_{zrb_cmd}_task"
+    run_zrb_task.__doc__ = (
+        f"Executes a predefined {zrb_cmd} automation task with specified arguments. "
+        "This is the preferred way to run project-specific workflows (e.g., deployments, scaffolding, specialized builds)."
+        "\n\n**IMPORTANT:** You must provide all required arguments."
+        "\n\n**ARGS:**"
+        "\n- `task_name`: The full alias path of the task (e.g., 'server start')."
+        "\n- `args`: Dictionary of arguments (e.g., {'port': '8080'})."
+        "\n- `timeout`: Maximum wait time in seconds (default 30)."
+    )
+    return run_zrb_task

zrb/llm/util/attachment.py

@@ -0,0 +1,101 @@
+from typing import TYPE_CHECKING, Any, Callable
+
+from zrb.context.any_context import AnyContext
+
+if TYPE_CHECKING:
+    from pydantic_ai.messages import UserContent
+
+
+def normalize_attachments(
+    attachments: "list[UserContent]", print_fn: Callable[[str], Any] = print
+) -> "list[UserContent]":
+    import os
+    from pathlib import Path
+
+    from pydantic_ai import BinaryContent
+
+    from zrb.llm.util.attachment import get_media_type
+
+    final_attachments = []
+    for item in attachments:
+        if isinstance(item, str):
+            # Treat as path
+            path = os.path.abspath(os.path.expanduser(item))
+            if os.path.exists(path):
+                media_type = get_media_type(path)
+                if media_type:
+                    try:
+                        data = Path(path).read_bytes()
+                        final_attachments.append(
+                            BinaryContent(data=data, media_type=media_type)
+                        )
+                    except Exception as e:
+                        print_fn(f"Failed to read attachment {path}: {e}")
+                else:
+                    print_fn(f"Unknown media type for {path}")
+            else:
+                print_fn(f"Attachment file not found: {path}")
+        else:
+            # Assume it's already a suitable object (e.g. BinaryContent)
+            final_attachments.append(item)
+    return final_attachments
+
+
+def get_attachments(
+    ctx: AnyContext,
+    attachment: "UserContent | list[UserContent] | Callable[[AnyContext], UserContent | list[UserContent]] | None" = None,  # noqa
+) -> "list[UserContent]":
+    if attachment is None:
+        return []
+    if callable(attachment):
+        result = attachment(ctx)
+        if result is None:
+            return []
+        if isinstance(result, list):
+            return result
+        return [result]
+    if isinstance(attachment, list):
+        return attachment
+    return [attachment]
+
+
+def get_media_type(filename: str) -> str | None:
+    """Guess media type string based on file extension."""
+    ext = filename.lower().rsplit(".", 1)[-1] if "." in filename else ""
+    mapping: dict[str, str] = {
+        # Audio
+        "wav": "audio/wav",
+        "mp3": "audio/mpeg",
+        "ogg": "audio/ogg",
+        "flac": "audio/flac",
+        "aiff": "audio/aiff",
+        "aac": "audio/aac",
+        # Image
+        "jpg": "image/jpeg",
+        "jpeg": "image/jpeg",
+        "png": "image/png",
+        "gif": "image/gif",
+        "webp": "image/webp",
+        # Document
+        "pdf": "application/pdf",
+        "txt": "text/plain",
+        "csv": "text/csv",
+        "docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "html": "text/html",
+        "htm": "text/html",
+        "md": "text/markdown",
+        "doc": "application/msword",
+        "xls": "application/vnd.ms-excel",
+        # Video
+        "mkv": "video/x-matroska",
+        "mov": "video/quicktime",
+        "mp4": "video/mp4",
+        "webm": "video/webm",
+        "flv": "video/x-flv",
+        "mpeg": "video/mpeg",
+        "mpg": "video/mpeg",
+        "wmv": "video/x-ms-wmv",
+        "3gp": "video/3gpp",
+    }
+    return mapping.get(ext)