zrb 1.16.5__py3-none-any.whl → 1.17.1__py3-none-any.whl

zrb/builtin/__init__.py

@@ -16,6 +16,7 @@ from zrb.builtin.project.add.fastapp.fastapp_task import add_fastapp_to_project
 from zrb.builtin.project.create.project_task import create_project
 from zrb.builtin.python import format_python_code
 from zrb.builtin.random import shuffle_values, throw_dice
+from zrb.builtin.searxng.start import start_searxng
 from zrb.builtin.setup.asdf.asdf import setup_asdf
 from zrb.builtin.setup.latex.ubuntu import setup_latex_on_ubuntu
 from zrb.builtin.setup.tmux.tmux import setup_tmux

zrb/builtin/group.py

@@ -41,7 +41,7 @@ todo_group = _maybe_add_group(Group(name="todo", description="✅ Todo managemen
 shell_group = _maybe_add_group(
     Group(name="shell", description="💬 Shell related commands")
 )
-shell_autocomplete_group: Group = shell_group.add_group(
+shell_autocomplete_group = shell_group.add_group(
     Group(name="autocomplete", description="⌨️ Shell autocomplete related commands")
 )
 
@@ -59,3 +59,7 @@ setup_group = _maybe_add_group(Group(name="setup", description="🔧 Setup"))
 setup_latex_group = setup_group.add_group(
     Group(name="latex", description="✍️ Setup LaTeX")
 )
+
+searxng_group = _maybe_add_group(
+    Group(name="searxng", description="🔎 Searxng related command")
+)

zrb/builtin/llm/llm_ask.py

@@ -6,7 +6,10 @@ from zrb.builtin.group import llm_group
 from zrb.builtin.llm.chat_session import get_llm_ask_input_mapping, read_user_prompt
 from zrb.builtin.llm.history import read_chat_conversation, write_chat_conversation
 from zrb.builtin.llm.input import PreviousSessionInput
-from zrb.builtin.llm.tool.api import get_current_location, get_current_weather
+from zrb.builtin.llm.tool.api import (
+    create_get_current_location,
+    create_get_current_weather,
+)
 from zrb.builtin.llm.tool.cli import run_shell_command
 from zrb.builtin.llm.tool.code import analyze_repo
 from zrb.builtin.llm.tool.file import (
@@ -28,8 +31,6 @@ from zrb.builtin.llm.tool.note import (
 from zrb.builtin.llm.tool.web import (
     create_search_internet_tool,
     open_web_page,
-    search_arxiv,
-    search_wikipedia,
 )
 from zrb.callback.callback import Callback
 from zrb.config.config import CFG
@@ -85,16 +86,12 @@ def _get_tool(ctx: AnyContext) -> list["ToolOrCallable"]:
         tools.append(run_shell_command)
     if CFG.LLM_ALLOW_OPEN_WEB_PAGE:
         tools.append(open_web_page)
-    if CFG.LLM_ALLOW_SEARCH_WIKIPEDIA:
-        tools.append(search_wikipedia)
-    if CFG.LLM_ALLOW_SEARCH_ARXIV:
-        tools.append(search_arxiv)
     if CFG.LLM_ALLOW_GET_CURRENT_LOCATION:
-        tools.append(get_current_location)
+        tools.append(create_get_current_location())
     if CFG.LLM_ALLOW_GET_CURRENT_WEATHER:
-        tools.append(get_current_weather)
+        tools.append(create_get_current_weather())
     if CFG.SERPAPI_KEY != "" and CFG.LLM_ALLOW_SEARCH_INTERNET:
-        tools.append(create_search_internet_tool(CFG.SERPAPI_KEY))
+        tools.append(create_search_internet_tool())
     return tools
 
 

zrb/builtin/llm/tool/api.py

@@ -1,71 +1,85 @@
-from typing import Any, Literal
-
-
-def get_current_location() -> dict[str, float]:
-    """
-    Fetches the user's current geographical location based on their IP address.
-
-    Use this tool when the user asks "Where am I?", "What is my current
-    location?", or has a query that requires knowing their location to be
-    answered.
-
-    Returns:
-        dict[str, float]: A dictionary containing the 'lat' and 'lon' of the current
-            location.
-            Example: {"lat": 48.8584, "lon": 2.2945}
-    Raises:
-        requests.RequestException: If the API request to the location service
-            fails.
-    """
-    import requests
-
-    try:
-        response = requests.get("http://ip-api.com/json?fields=lat,lon", timeout=5)
-        response.raise_for_status()
-        return dict(response.json())
-    except requests.RequestException as e:
-        raise requests.RequestException(f"Failed to get location: {e}") from None
-
-
-def get_current_weather(
-    latitude: float,
-    longitude: float,
-    temperature_unit: Literal["celsius", "fahrenheit"],
-) -> dict[str, Any]:
-    """
-    Retrieves the current weather conditions for a given geographical location.
-
-    Use this tool when the user asks about the weather. If the user does not
-    provide a location, first use the `get_current_location` tool to
-    determine their location.
-
-    Args:
-        latitude (float): The latitude of the location.
-        longitude (float): The longitude of the location.
-        temperature_unit (Literal["celsius", "fahrenheit"]): The desired unit
-            for the temperature reading.
-
-    Returns:
-        dict[str, Any]: A dictionary containing detailed weather data, including
-            temperature, wind speed, and weather code.
-    Raises:
-        requests.RequestException: If the API request to the weather service
-            fails.
-    """
-    import requests
-
-    try:
-        response = requests.get(
-            "https://api.open-meteo.com/v1/forecast",
-            params={
-                "latitude": latitude,
-                "longitude": longitude,
-                "temperature_unit": temperature_unit,
-                "current_weather": True,
-            },
-            timeout=5,
-        )
-        response.raise_for_status()
-        return dict(response.json())
-    except requests.RequestException as e:
-        raise requests.RequestException(f"Failed to get weather data: {e}") from None
+from typing import Any, Callable, Literal
+
+from zrb.config.llm_config import llm_config
+
+
+def create_get_current_location() -> Callable:
+    if llm_config.default_current_location_tool is not None:
+        return llm_config.default_current_location_tool
+
+    def get_current_location() -> dict[str, float]:
+        """
+        Fetches the user's current geographical location based on their IP address.
+
+        Use this tool when the user asks "Where am I?", "What is my current
+        location?", or has a query that requires knowing their location to be
+        answered.
+
+        Returns:
+            dict[str, float]: A dictionary containing the 'lat' and 'lon' of the current
+                location.
+                Example: {"lat": 48.8584, "lon": 2.2945}
+        Raises:
+            requests.RequestException: If the API request to the location service
+                fails.
+        """
+        import requests
+
+        try:
+            response = requests.get("http://ip-api.com/json?fields=lat,lon", timeout=5)
+            response.raise_for_status()
+            return dict(response.json())
+        except requests.RequestException as e:
+            raise requests.RequestException(f"Failed to get location: {e}")
+
+    return get_current_location
+
+
+def create_get_current_weather() -> Callable:
+    if llm_config.default_current_weather_tool is not None:
+        return llm_config.default_current_weather_tool
+
+    def get_current_weather(
+        latitude: float,
+        longitude: float,
+        temperature_unit: Literal["celsius", "fahrenheit"],
+    ) -> dict[str, Any]:
+        """
+        Retrieves the current weather conditions for a given geographical location.
+
+        Use this tool when the user asks about the weather. If the user does not
+        provide a location, first use the `get_current_location` tool to
+        determine their location.
+
+        Args:
+            latitude (float): The latitude of the location.
+            longitude (float): The longitude of the location.
+            temperature_unit (Literal["celsius", "fahrenheit"]): The desired unit
+                for the temperature reading.
+
+        Returns:
+            dict[str, Any]: A dictionary containing detailed weather data, including
+                temperature, wind speed, and weather code.
+        Raises:
+            requests.RequestException: If the API request to the weather service
+                fails.
+        """
+        import requests
+
+        try:
+            response = requests.get(
+                "https://api.open-meteo.com/v1/forecast",
+                params={
+                    "latitude": latitude,
+                    "longitude": longitude,
+                    "temperature_unit": temperature_unit,
+                    "current_weather": True,
+                },
+                timeout=5,
+            )
+            response.raise_for_status()
+            return dict(response.json())
+        except requests.RequestException as e:
+            raise requests.RequestException(f"Failed to get weather data: {e}")
+
+    return get_current_weather

zrb/builtin/llm/tool/file.py

@@ -100,34 +100,19 @@ def list_files(
     excluded_patterns: Optional[list[str]] = None,
 ) -> dict[str, list[str]]:
     """
-    Lists the files and directories within a specified path.
+    Lists files and directories within a specified path, providing a map of the filesystem.
 
-    This is a fundamental tool for exploring the file system. Use it to
-    discover the structure of a directory, find specific files, or get a
-    general overview of the project layout before performing other operations.
-    **NOTE:**
-    User might provide inaccurate file path, so if you failed to read a file,
-    it is a good idea to list the files to get the accurate file path.
+    Use this tool to explore and understand the directory structure of the project. It's essential for finding files before reading or modifying them. If you receive an error about a file not being found, use this tool to verify the correct path.
 
     Args:
-        path (str, optional): The directory path to list. Defaults to the
-            current directory (".").
-        recursive (bool, optional): If True, lists files and directories
-            recursively. If False, lists only the top-level contents.
-            Defaults to True.
-        include_hidden (bool, optional): If True, includes hidden files and
-            directories (those starting with a dot). Defaults to False.
-        excluded_patterns (list[str], optional): A list of glob patterns to
-            exclude from the listing. This is useful for ignoring irrelevant
-            files like build artifacts or virtual environments. Defaults to a
-            standard list of common exclusion patterns.
+        path (str, optional): The directory path to list, preferably an absolute path. Defaults to the current directory (".").
+        recursive (bool, optional): If True, lists contents recursively. Defaults to True.
+        include_hidden (bool, optional): If True, includes hidden files (e.g., .gitignore). Defaults to False.
+        excluded_patterns (list[str], optional): A list of glob patterns to ignore (e.g., ["*.log", "node_modules/"]). Defaults to a standard list of ignores.
 
     Returns:
-        dict[str, list[str]]: A dictionary containing a list of file and directory paths
-            relative to the input path.
-            Example: {"files": ["src/main.py", "README.md"]}
-    Raises:
-        FileNotFoundError: If the specified path does not exist.
+        dict[str, list[str]]: A dictionary with a single key "files" containing a sorted list of file and directory paths relative to the input path.
+        Example: {"files": ["README.md", "src/main.py", "src/utils/helpers.py"]}
     """
     all_files: list[str] = []
     abs_path = os.path.abspath(os.path.expanduser(path))
@@ -226,59 +211,24 @@ def read_from_file(
     end_line: Optional[int] = None,
 ) -> dict[str, Any]:
     """
-    Reads the content of a file, optionally from a specific start line to an
-    end line.
-
-    This tool is essential for inspecting file contents. It can read both text
-    and PDF files. The `content` field in the returned dictionary is **always**
-    prefixed with line numbers (`line_number | `) for each line. These prefixes
-    are added by the tool for internal processing and to provide contextual
-    information to the AI agent (e.g., for accurately applying diffs or for
-    referencing specific lines). They are **not** part of the actual file content.
-
-    When presenting the file content to a user, the AI agent **MUST** omit these
-    line number prefixes by default for better readability. They should only
-    be included if explicitly requested by the user or if the request inherently
-    requires line number context (e.g., 'show me lines 10-20').
+    Reads the content of a single file.
 
-    Use this tool to:
-    - Examine the source code of a file.
-    - Read configuration files.
-    - Check the contents of a document.
+    Use this tool to inspect the contents of a specific file. You can read the entire file or specify a range of lines. The content returned will include line numbers, which are useful for other tools like `replace_in_file`.
 
     Args:
-        path (str): The path to the file to read.
-        start_line (int, optional): The 1-based line number to start reading
-            from. If omitted, reading starts from the beginning of the file.
-        end_line (int, optional): The 1-based line number to stop reading at
-            (inclusive). If omitted, reads to the end of the file.
+        path (str): The absolute path to the file to read.
+        start_line (int, optional): The 1-based line number to start reading from. Defaults to the beginning of the file.
+        end_line (int, optional): The 1-based line number to stop reading at (inclusive). Defaults to the end of the file.
 
     Returns:
-        dict[str, Any]: A dictionary containing the file path, the requested content
-            (always with line numbers), the start and end lines, and the total number
-            of lines in the file.
-            Example:
-            ```
-            {
-                "path": "src/main.py",
-                "content": "1| import os\n2|\n3| print(\"Hello, World!\")",
-                "start_line": 1,
-                "end_line": 3,
-                "total_lines": 3
-            }
-            ```
-            If the file 'src/main.py' contains:
-            ```
-            import os
-
-            print("Hello, World!")
-            ```
-            The 'content' field in the returned dictionary will be:
-            `"1| import os\n2|\n3| print(\"Hello, World!\")"`
-            **IMPORTANT:** The "1|", "2|", "3|" prefixes are NOT part of the
-            original file. They are for internal agent use.
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
+        dict[str, Any]: A dictionary containing the file path and its content with line numbers.
+        Example: {
+            "path": "src/main.py",
+            "content": "1| import os\n2|\n3| print(\"Hello, World!\")",
+            "start_line": 1,
+            "end_line": 3,
+            "total_lines": 3
+        }
     """
 
     abs_path = os.path.abspath(os.path.expanduser(path))
@@ -318,24 +268,19 @@ def read_from_file(
 def write_to_file(
     path: str,
     content: str,
-) -> dict[str, Any]:
+) -> str:
     """
-    Writes content to a file, completely overwriting it if it exists or
-    creating it if it doesn't.
+    Writes content to a file, creating it or completely overwriting it.
 
-    Use this tool to create new files or to overwrite the entire content of
-    existing files. This is a destructive operation, so be certain of your
-    actions. Always read the file first to understand its contents before
-    overwriting it, unless you are creating a new file.
+    Use this tool to create a new file or replace an existing file's entire content.
+    **WARNING:** This is a destructive operation and will overwrite the file if it exists. Use `replace_in_file` for safer, targeted changes.
 
     Args:
-        path (str): The path to the file to write to.
-        content (str): The full, complete content to be written to the file.
-            Do not use partial content or omit any lines.
+        path (str): The absolute path of the file to write to.
+        content (str): The full content to be written to the file.
 
     Returns:
-        dict[str, Any]: A dictionary indicating success or failure.
-             Example: {"success": true, "path": "new_file.txt"}
+        str: A confirmation message indicating the file was written successfully.
     """
     try:
         abs_path = os.path.abspath(os.path.expanduser(path))
@@ -344,7 +289,7 @@ def write_to_file(
         if directory and not os.path.exists(directory):
             os.makedirs(directory, exist_ok=True)
         write_file(abs_path, content)
-        return {"success": True, "path": path}
+        return f"Successfully wrote to file: {path}"
     except (OSError, IOError) as e:
         raise OSError(f"Error writing file {path}: {e}")
     except Exception as e:
@@ -470,29 +415,19 @@ def replace_in_file(
     path: str,
     old_string: str,
     new_string: str,
-) -> dict[str, Any]:
+) -> str:
     """
     Replaces the first occurrence of a string in a file.
 
-    This tool is for making targeted modifications to a file. It is a
-    single-step operation that is generally safer and more ergonomic than
-    `write_to_file` for small changes.
-
-    To ensure the replacement is applied correctly and to avoid ambiguity, the
-    `old_string` parameter should be a unique, multi-line string that includes
-    context from before and after the code you want to change.
+    This tool is for making targeted modifications to a file. It is safer than `write_to_file` for small changes. First, use `read_from_file` to get the exact text block you want to change. Then, use that block as the `old_string`.
 
     Args:
-        path (str): The path of the file to modify.
-        old_string (str): The exact, verbatim string to search for and replace.
-            This should be a unique, multi-line block of text.
+        path (str): The absolute path of the file to modify.
+        old_string (str): The exact, verbatim string to replace. This should be a unique, multi-line block of text copied from the file.
         new_string (str): The new string that will replace the `old_string`.
 
     Returns:
-        dict[str, Any]: A dictionary indicating the success or failure of the operation.
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
-        ValueError: If the `old_string` is not found in the file.
+        str: A confirmation message on success.
     """
     abs_path = os.path.abspath(os.path.expanduser(path))
     if not os.path.exists(abs_path):
@@ -503,7 +438,7 @@ def replace_in_file(
             raise ValueError(f"old_string not found in file: {path}")
         new_content = content.replace(old_string, new_string, 1)
         write_file(abs_path, new_content)
-        return {"success": True, "path": path}
+        return f"Successfully replaced content in {path}"
     except ValueError as e:
         raise e
     except (OSError, IOError) as e:

zrb/builtin/llm/tool/note.py

@@ -17,12 +17,12 @@ def read_long_term_note() -> str:
 
 def write_long_term_note(content: str) -> str:
     """
-    Writes content to the global long-term note.
-    The content of this note is intended to be read by the AI Agent in the future.
-    It should contain global information/preference.
+    Writes or overwrites the global long-term note for the user.
+
+    Use this to remember key user preferences, goals, or facts that should apply to all future conversations (e.g., "The user prefers TypeScript," "The user's favorite color is read"). This note is persistent across all projects.
 
     Args:
-        content: The content to write to the long-term note (overwriting the existing one).
+        content: The information to save. This will overwrite the entire note.
 
     Returns:
         A confirmation message.
@@ -52,19 +52,16 @@ def read_contextual_note(path: str | None = None) -> str:
 
 def write_contextual_note(content: str, path: str | None = None) -> str:
     """
-    Writes a contextual note for a specific path.
-    The content of this note is intended to be read by the AI Agent in the future.
-    The content should contain contextual information.
+    Writes or overwrites a note for a specific file or directory.
 
-    If no path is provided, it defaults to the current working directory.
+    Use this to save your findings, summaries, or conclusions about a specific part of the project. This note will be available in the future when you are working within that same context.
 
     Args:
-        content: The new content of the note (overwriting the existing one).
-        path: The file or directory path to associate the note with.
-              Defaults to the current working directory.
+        content: The information to save about the path. This overwrites any existing note for this path.
+        path (str, optional): The absolute file or directory path to associate the note with. Defaults to the current working directory.
 
     Returns:
-        A confirmation message indicating where the note was saved.
+        A confirmation message.
     """
     if path is None:
         path = os.getcwd()

zrb/builtin/llm/tool/web.py

@@ -2,6 +2,9 @@ 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
+
 _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
 
 
@@ -28,26 +31,11 @@ async def open_web_page(url: str) -> dict[str, Any]:
     return {"content": markdown_content, "links_on_page": links}
 
 
-def create_search_internet_tool(
-    serp_api_key: str,
-) -> Callable[[str, int], dict[str, Any]]:
-    """
-    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.
-
-    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) -> dict[str, Any]:
+    def search_internet(query: str, page: int = 1) -> dict[str, Any]:
         """
         Performs an internet search using Google and returns a summary of the results.
 
@@ -56,7 +44,7 @@ def create_search_internet_tool(
 
         Args:
             query (str): The search query.
-            num_results (int, optional): The desired number of search results. Defaults to 10.
+            Page (int, optional): The search page number, default to 1.
 
         Returns:
             dict[str, Any]: A formatted string summarizing the search results,
@@ -64,17 +52,29 @@ def create_search_internet_tool(
         """
         import requests
 
-        response = requests.get(
-            "https://serpapi.com/search",
-            headers={"User-Agent": _DEFAULT_USER_AGENT},
-            params={
-                "q": query,
-                "num": num_results,
-                "hl": "en",
-                "safe": "off",
-                "api_key": serp_api_key,
-            },
-        )
+        if CFG.SEARCH_INTERNET_METHOD.strip() == "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": "en",
+                    "safe": "off",
+                    "api_key": CFG.SERPAPI_KEY,
+                },
+            )
+        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": 0,
+                },
+            )
         if response.status_code != 200:
             raise Exception(
                 f"Error: Unable to retrieve search results (status code: {response.status_code})"  # noqa
@@ -84,62 +84,6 @@ def create_search_internet_tool(
     return search_internet
 
 
-def search_wikipedia(query: str) -> dict[str, Any]:
-    """
-    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:
-        dict[str, Any]: 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",
-        headers={"User-Agent": _DEFAULT_USER_AGENT},
-        params=params,
-    )
-    return response.json()
-
-
-def search_arxiv(query: str, num_results: int = 10) -> dict[str, Any]:
-    """
-    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:
-        dict[str, Any]: The raw XML response from the ArXiv API, containing a list of
-            matching papers.
-    """
-    import requests
-    import xmltodict
-
-    params = {"search_query": f"all:{query}", "start": 0, "max_results": num_results}
-    response = requests.get(
-        "http://export.arxiv.org/api/query",
-        headers={"User-Agent": _DEFAULT_USER_AGENT},
-        params=params,
-    )
-    return xmltodict.parse(response.content)
-
-
 async def _fetch_page_content(url: str) -> tuple[str, list[str]]:
     """Fetches the HTML content and all absolute links from a URL."""
     try: