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

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)

zrb/llm/util/prompt.py

@@ -0,0 +1,104 @@
+import os
+import re
+
+from zrb.util.file import list_files, read_file
+
+
+def expand_prompt(prompt: str) -> str:
+    """
+    Expands @reference patterns in the prompt into a Reference + Appendix style.
+    Example: "Check @main.py" -> "Check main.py (see Appendix)\n...[Appendix with content]..."
+    """
+    if not prompt:
+        return prompt
+
+    # Regex to capture @path.
+    # Matches @ followed by typical path chars.
+    # We'll allow alphanumeric, _, -, ., /, \, and ~ (home dir).
+    pattern = re.compile(r"@(?P<path>[\w~\-\./\\]+)")
+
+    matches = list(pattern.finditer(prompt))
+    if not matches:
+        return prompt
+
+    appendix_entries: list[str] = []
+    # We construct the new string by slicing.
+    last_idx = 0
+    parts = []
+
+    for match in matches:
+        # Add text before match
+        parts.append(prompt[last_idx : match.start()])
+
+        path_ref = match.group("path")
+        original_token = match.group(0)
+
+        # Check existence
+        expanded_path = os.path.expanduser(path_ref)
+        abs_path = os.path.abspath(expanded_path)
+
+        content = ""
+        header = ""
+        is_valid_ref = False
+
+        if os.path.isfile(abs_path):
+            try:
+                content = read_file(abs_path)
+                header = f"File Content: `{path_ref}`"
+                is_valid_ref = True
+            except Exception:
+                pass
+        elif os.path.isdir(abs_path):
+            try:
+                # Use list_files for directory structure
+                file_list = list_files(abs_path, depth=2)
+                content = "\n".join(file_list)
+                if not content:
+                    content = "(Empty directory)"
+                header = f"Directory Listing: `{path_ref}`"
+                is_valid_ref = True
+            except Exception:
+                pass
+
+        if not is_valid_ref:
+            # Fallback: leave original token if unreadable or not found
+            parts.append(original_token)
+            last_idx = match.end()
+            continue
+
+        # If we successfully got content
+        parts.append(f"`{path_ref}` (see Appendix)")
+
+        # Add to appendix with strict instructions
+        entry_lines = [
+            f"### {header}",
+            f"> **SYSTEM NOTE:** The content of `{path_ref}` is provided below.",
+            "> **DO NOT** use tools like `read_file` or `list_files` to read this path again.",
+            "> Use the content provided here directly.\n",
+            "```",
+            f"{content}",
+            "```",
+        ]
+        appendix_entries.append("\n".join(entry_lines))
+
+        last_idx = match.end()
+
+    # Add remaining text
+    parts.append(prompt[last_idx:])
+
+    new_prompt = "".join(parts)
+
+    if appendix_entries:
+        sep = "=" * 20
+        header_lines = [
+            f"\n\n{sep}APPENDIX: PRE-LOADED CONTEXT {sep}",
+            "⚠️ **SYSTEM INSTRUCTION**: The user has attached the following content.",
+            "You MUST use this provided content for your analysis.",
+            "**DO NOT** consume resources by calling `read_file` or `list_files`",
+            "or `run_shell_command` to read these specific paths again.\n",
+        ]
+        appendix_section = "\n".join(header_lines)
+        appendix_section += "\n\n".join(appendix_entries)
+        new_prompt += appendix_section
+
+    return new_prompt