zrb 1.21.28__py3-none-any.whl → 1.21.31__py3-none-any.whl

zrb/builtin/llm/chat_completion.py

@@ -1,7 +1,5 @@
 import os
-
-from prompt_toolkit.completion import CompleteEvent, Completer, Completion
-from prompt_toolkit.document import Document
+from typing import TYPE_CHECKING
 
 from zrb.builtin.llm.chat_session_cmd import (
     ADD_SUB_CMD,
@@ -36,239 +34,254 @@ from zrb.builtin.llm.chat_session_cmd import (
     YOLO_SET_TRUE_CMD_DESC,
 )
 
+if TYPE_CHECKING:
+    from prompt_toolkit.completion import Completer
+
+
+def get_chat_completer() -> "Completer":
+
+    from prompt_toolkit.completion import CompleteEvent, Completer, Completion
+    from prompt_toolkit.document import Document
 
-class ChatCompleter(Completer):
+    class ChatCompleter(Completer):
 
-    def get_completions(self, document: Document, complete_event: CompleteEvent):
-        # Slash command
-        for completion in self._complete_slash_command(document):
-            yield completion
-        for completion in self._complete_slash_file_command(document):
-            yield completion
-        # Appendix
-        for completion in self._complete_appendix(document):
-            yield completion
+        def get_completions(self, document: Document, complete_event: CompleteEvent):
+            # Slash command
+            for completion in self._complete_slash_command(document):
+                yield completion
+            for completion in self._complete_slash_file_command(document):
+                yield completion
+            # Appendix
+            for completion in self._complete_appendix(document):
+                yield completion
 
-    def _complete_slash_file_command(self, document: Document):
-        text = document.text_before_cursor
-        prefixes = []
-        for cmd in ATTACHMENT_CMD:
-            for subcmd in ADD_SUB_CMD:
-                prefixes.append(f"{cmd} {subcmd} ")
-        for prefix in prefixes:
-            if text.startswith(prefix):
-                pattern = text[len(prefix) :]
-                potential_options = self._fuzzy_path_search(pattern, dirs=False)
-                for prefixed_option in [
-                    f"{prefix}{option}" for option in potential_options
-                ]:
+        def _complete_slash_file_command(self, document: Document):
+            text = document.text_before_cursor
+            prefixes = []
+            for cmd in ATTACHMENT_CMD:
+                for subcmd in ADD_SUB_CMD:
+                    prefixes.append(f"{cmd} {subcmd} ")
+            for prefix in prefixes:
+                if text.startswith(prefix):
+                    pattern = text[len(prefix) :]
+                    potential_options = self._fuzzy_path_search(pattern, dirs=False)
+                    for prefixed_option in [
+                        f"{prefix}{option}" for option in potential_options
+                    ]:
+                        yield Completion(
+                            prefixed_option,
+                            start_position=-len(text),
+                        )
+
+        def _complete_slash_command(self, document: Document):
+            text = document.text_before_cursor
+            if not text.startswith("/"):
+                return
+            for command, description in self._get_cmd_options().items():
+                if command.lower().startswith(text.lower()):
                     yield Completion(
-                        prefixed_option,
+                        command,
                         start_position=-len(text),
+                        display_meta=description,
                     )
 
-    def _complete_slash_command(self, document: Document):
-        text = document.text_before_cursor
-        if not text.startswith("/"):
-            return
-        for command, description in self._get_cmd_options().items():
-            if command.lower().startswith(text.lower()):
+        def _complete_appendix(self, document: Document):
+            token = document.get_word_before_cursor(WORD=True)
+            prefix = "@"
+            if not token.startswith(prefix):
+                return
+            pattern = token[len(prefix) :]
+            potential_options = self._fuzzy_path_search(pattern, dirs=False)
+            for prefixed_option in [
+                f"{prefix}{option}" for option in potential_options
+            ]:
                 yield Completion(
-                    command,
-                    start_position=-len(text),
-                    display_meta=description,
+                    prefixed_option,
+                    start_position=-len(token),
                 )
 
-    def _complete_appendix(self, document: Document):
-        token = document.get_word_before_cursor(WORD=True)
-        prefix = "@"
-        if not token.startswith(prefix):
-            return
-        pattern = token[len(prefix) :]
-        potential_options = self._fuzzy_path_search(pattern, dirs=False)
-        for prefixed_option in [f"{prefix}{option}" for option in potential_options]:
-            yield Completion(
-                prefixed_option,
-                start_position=-len(token),
-            )
-
-    def _get_cmd_options(self):
-        cmd_options = {}
-        # Add all commands with their descriptions
-        for cmd in MULTILINE_START_CMD:
-            cmd_options[cmd] = MULTILINE_START_CMD_DESC
-        for cmd in MULTILINE_END_CMD:
-            cmd_options[cmd] = MULTILINE_END_CMD_DESC
-        for cmd in QUIT_CMD:
-            cmd_options[cmd] = QUIT_CMD_DESC
-        for cmd in WORKFLOW_CMD:
-            cmd_options[cmd] = WORKFLOW_CMD_DESC
-            for subcmd in ADD_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd}"] = WORKFLOW_ADD_SUB_CMD_DESC
-            for subcmd in CLEAR_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd}"] = WORKFLOW_CLEAR_SUB_CMD_DESC
-            for subcmd in SET_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd}"] = WORKFLOW_SET_SUB_CMD_DESC
-        for cmd in SAVE_CMD:
-            cmd_options[cmd] = SAVE_CMD_DESC
-        for cmd in ATTACHMENT_CMD:
-            cmd_options[cmd] = ATTACHMENT_CMD_DESC
-            for subcmd in ADD_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd}"] = ATTACHMENT_ADD_SUB_CMD_DESC
-            for subcmd in CLEAR_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd}"] = ATTACHMENT_CLEAR_SUB_CMD_DESC
-            for subcmd in SET_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd}"] = ATTACHMENT_SET_SUB_CMD_DESC
-        for cmd in YOLO_CMD:
-            cmd_options[cmd] = YOLO_CMD_DESC
-            for subcmd in SET_SUB_CMD:
-                cmd_options[f"{cmd} {subcmd} true"] = YOLO_SET_TRUE_CMD_DESC
-                cmd_options[f"{cmd} {subcmd} false"] = YOLO_SET_FALSE_CMD_DESC
-                cmd_options[f"{cmd} {subcmd}"] = YOLO_SET_CMD_DESC
-        for cmd in HELP_CMD:
-            cmd_options[cmd] = HELP_CMD_DESC
-        for cmd in RUN_CLI_CMD:
-            cmd_options[cmd] = RUN_CLI_CMD_DESC
-        return dict(sorted(cmd_options.items()))
+        def _get_cmd_options(self):
+            cmd_options = {}
+            # Add all commands with their descriptions
+            for cmd in MULTILINE_START_CMD:
+                cmd_options[cmd] = MULTILINE_START_CMD_DESC
+            for cmd in MULTILINE_END_CMD:
+                cmd_options[cmd] = MULTILINE_END_CMD_DESC
+            for cmd in QUIT_CMD:
+                cmd_options[cmd] = QUIT_CMD_DESC
+            for cmd in WORKFLOW_CMD:
+                cmd_options[cmd] = WORKFLOW_CMD_DESC
+                for subcmd in ADD_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd}"] = WORKFLOW_ADD_SUB_CMD_DESC
+                for subcmd in CLEAR_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd}"] = WORKFLOW_CLEAR_SUB_CMD_DESC
+                for subcmd in SET_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd}"] = WORKFLOW_SET_SUB_CMD_DESC
+            for cmd in SAVE_CMD:
+                cmd_options[cmd] = SAVE_CMD_DESC
+            for cmd in ATTACHMENT_CMD:
+                cmd_options[cmd] = ATTACHMENT_CMD_DESC
+                for subcmd in ADD_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd}"] = ATTACHMENT_ADD_SUB_CMD_DESC
+                for subcmd in CLEAR_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd}"] = ATTACHMENT_CLEAR_SUB_CMD_DESC
+                for subcmd in SET_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd}"] = ATTACHMENT_SET_SUB_CMD_DESC
+            for cmd in YOLO_CMD:
+                cmd_options[cmd] = YOLO_CMD_DESC
+                for subcmd in SET_SUB_CMD:
+                    cmd_options[f"{cmd} {subcmd} true"] = YOLO_SET_TRUE_CMD_DESC
+                    cmd_options[f"{cmd} {subcmd} false"] = YOLO_SET_FALSE_CMD_DESC
+                    cmd_options[f"{cmd} {subcmd}"] = YOLO_SET_CMD_DESC
+            for cmd in HELP_CMD:
+                cmd_options[cmd] = HELP_CMD_DESC
+            for cmd in RUN_CLI_CMD:
+                cmd_options[cmd] = RUN_CLI_CMD_DESC
+            return dict(sorted(cmd_options.items()))
 
-    def _fuzzy_path_search(
-        self,
-        pattern: str,
-        root: str | None = None,
-        max_results: int = 20,
-        include_hidden: bool = False,
-        case_sensitive: bool = False,
-        dirs: bool = True,
-        files: bool = True,
-    ) -> list[str]:
-        """
-        Return a list of filesystem paths under `root` that fuzzy-match `pattern`.
-        - pattern: e.g. "./some/x" or "proj util/io"
-        - include_hidden: if False skip files/dirs starting with '.'
-        - dirs/files booleans let you restrict results
-        - returns list of relative paths (from root), sorted best-first
-        """
-        search_pattern = pattern
-        if root is None:
-            # Determine root and adjust pattern if necessary
-            expanded_pattern = os.path.expanduser(pattern)
-            if os.path.isabs(expanded_pattern) or pattern.startswith("~"):
-                # For absolute paths, find the deepest existing directory
-                if os.path.isdir(expanded_pattern):
-                    root = expanded_pattern
-                    search_pattern = ""
-                else:
-                    root = os.path.dirname(expanded_pattern)
-                    while root and not os.path.isdir(root) and len(root) > 1:
-                        root = os.path.dirname(root)
-                    if not os.path.isdir(root):
-                        root = "."  # Fallback
-                        search_pattern = pattern
+        def _fuzzy_path_search(
+            self,
+            pattern: str,
+            root: str | None = None,
+            max_results: int = 20,
+            include_hidden: bool = False,
+            case_sensitive: bool = False,
+            dirs: bool = True,
+            files: bool = True,
+        ) -> list[str]:
+            """
+            Return a list of filesystem paths under `root` that fuzzy-match `pattern`.
+            - pattern: e.g. "./some/x" or "proj util/io"
+            - include_hidden: if False skip files/dirs starting with '.'
+            - dirs/files booleans let you restrict results
+            - returns list of relative paths (from root), sorted best-first
+            """
+            search_pattern = pattern
+            if root is None:
+                # Determine root and adjust pattern if necessary
+                expanded_pattern = os.path.expanduser(pattern)
+                if os.path.isabs(expanded_pattern) or pattern.startswith("~"):
+                    # For absolute paths, find the deepest existing directory
+                    if os.path.isdir(expanded_pattern):
+                        root = expanded_pattern
+                        search_pattern = ""
                     else:
-                        try:
-                            search_pattern = os.path.relpath(expanded_pattern, root)
-                            if search_pattern == ".":
-                                search_pattern = ""
-                        except ValueError:
-                            search_pattern = os.path.basename(pattern)
+                        root = os.path.dirname(expanded_pattern)
+                        while root and not os.path.isdir(root) and len(root) > 1:
+                            root = os.path.dirname(root)
+                        if not os.path.isdir(root):
+                            root = "."  # Fallback
+                            search_pattern = pattern
+                        else:
+                            try:
+                                search_pattern = os.path.relpath(expanded_pattern, root)
+                                if search_pattern == ".":
+                                    search_pattern = ""
+                            except ValueError:
+                                search_pattern = os.path.basename(pattern)
+                else:
+                    root = "."
+                    search_pattern = pattern
+            # Normalize pattern -> tokens split on path separators or whitespace
+            search_pattern = search_pattern.strip()
+            if search_pattern:
+                raw_tokens = [t for t in search_pattern.split(os.path.sep) if t]
+            else:
+                raw_tokens = []
+            # prepare tokens (case)
+            if not case_sensitive:
+                tokens = [t.lower() for t in raw_tokens]
             else:
-                root = "."
-                search_pattern = pattern
-        # Normalize pattern -> tokens split on path separators or whitespace
-        search_pattern = search_pattern.strip()
-        if search_pattern:
-            raw_tokens = [t for t in search_pattern.split(os.path.sep) if t]
-        else:
-            raw_tokens = []
-        # prepare tokens (case)
-        if not case_sensitive:
-            tokens = [t.lower() for t in raw_tokens]
-        else:
-            tokens = raw_tokens
-        # specific ignore list
-        try:
-            is_recursive = os.path.abspath(os.path.expanduser(root)).startswith(
-                os.path.abspath(os.getcwd())
-            )
-        except Exception:
-            is_recursive = False
-        # walk filesystem
-        candidates: list[tuple[float, str]] = []
-        for dirpath, dirnames, filenames in os.walk(root):
-            # Filter directories
-            if not include_hidden:
-                dirnames[:] = [d for d in dirnames if not d.startswith(".")]
-            rel_dir = os.path.relpath(dirpath, root)
-            # treat '.' as empty prefix
-            if rel_dir == ".":
-                rel_dir = ""
-            # build list of entries to test depending on files/dirs flags
-            entries = []
-            if dirs:
-                entries.extend([os.path.join(rel_dir, d) for d in dirnames])
-            if files:
-                entries.extend([os.path.join(rel_dir, f) for f in filenames])
-            if not is_recursive:
-                dirnames[:] = []
-            for ent in entries:
-                # Normalize presentation: use ./ prefix for relative paths
-                display_path = ent if ent else "."
-                # Skip hidden entries unless requested (double check for rel path segments)
+                tokens = raw_tokens
+            # specific ignore list
+            try:
+                is_recursive = os.path.abspath(os.path.expanduser(root)).startswith(
+                    os.path.abspath(os.getcwd())
+                )
+            except Exception:
+                is_recursive = False
+            # walk filesystem
+            candidates: list[tuple[float, str]] = []
+            for dirpath, dirnames, filenames in os.walk(root):
+                # Filter directories
                 if not include_hidden:
-                    if any(
-                        seg.startswith(".") for seg in display_path.split(os.sep) if seg
-                    ):
-                        continue
-                cand = display_path.replace(os.sep, "/")  # unify separator
-                cand_cmp = cand if case_sensitive else cand.lower()
-                last_pos = 0
-                score = 0.0
-                matched_all = True
-                for token in tokens:
-                    # try contiguous substring search first
-                    idx = cand_cmp.find(token, last_pos)
-                    if idx != -1:
-                        # good match: reward contiguous early matches
-                        score += idx  # smaller idx preferred
-                        last_pos = idx + len(token)
-                    else:
-                        # fallback to subsequence matching
-                        pos = self._find_subsequence_pos(cand_cmp, token, last_pos)
-                        if pos is None:
-                            matched_all = False
-                            break
-                        # subsequence match is less preferred than contiguous substring
-                        score += pos + 0.5 * len(token)
-                        last_pos = pos + len(token)
-                if matched_all:
-                    # prefer shorter paths when score ties, so include length as tiebreaker
-                    score += 0.01 * len(cand)
-                    out = (
-                        cand
-                        if os.path.abspath(cand) == cand
-                        else os.path.join(root, cand)
-                    )
-                    candidates.append((score, out))
-        # sort by score then lexicographically and return top results
-        candidates.sort(key=lambda x: (x[0], x[1]))
-        return [p for _, p in candidates[:max_results]]
+                    dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+                rel_dir = os.path.relpath(dirpath, root)
+                # treat '.' as empty prefix
+                if rel_dir == ".":
+                    rel_dir = ""
+                # build list of entries to test depending on files/dirs flags
+                entries = []
+                if dirs:
+                    entries.extend([os.path.join(rel_dir, d) for d in dirnames])
+                if files:
+                    entries.extend([os.path.join(rel_dir, f) for f in filenames])
+                if not is_recursive:
+                    dirnames[:] = []
+                for ent in entries:
+                    # Normalize presentation: use ./ prefix for relative paths
+                    display_path = ent if ent else "."
+                    # Skip hidden entries unless requested (double check for rel path segments)
+                    if not include_hidden:
+                        if any(
+                            seg.startswith(".")
+                            for seg in display_path.split(os.sep)
+                            if seg
+                        ):
+                            continue
+                    cand = display_path.replace(os.sep, "/")  # unify separator
+                    cand_cmp = cand if case_sensitive else cand.lower()
+                    last_pos = 0
+                    score = 0.0
+                    matched_all = True
+                    for token in tokens:
+                        # try contiguous substring search first
+                        idx = cand_cmp.find(token, last_pos)
+                        if idx != -1:
+                            # good match: reward contiguous early matches
+                            score += idx  # smaller idx preferred
+                            last_pos = idx + len(token)
+                        else:
+                            # fallback to subsequence matching
+                            pos = self._find_subsequence_pos(cand_cmp, token, last_pos)
+                            if pos is None:
+                                matched_all = False
+                                break
+                            # subsequence match is less preferred than contiguous substring
+                            score += pos + 0.5 * len(token)
+                            last_pos = pos + len(token)
+                    if matched_all:
+                        # prefer shorter paths when score ties, so include length as tiebreaker
+                        score += 0.01 * len(cand)
+                        out = (
+                            cand
+                            if os.path.abspath(cand) == cand
+                            else os.path.join(root, cand)
+                        )
+                        candidates.append((score, out))
+            # sort by score then lexicographically and return top results
+            candidates.sort(key=lambda x: (x[0], x[1]))
+            return [p for _, p in candidates[:max_results]]
+
+        def _find_subsequence_pos(
+            self, hay: str, needle: str, start: int = 0
+        ) -> int | None:
+            """
+            Try to locate needle in hay as a subsequence starting at `start`.
+            Returns the index of the first matched character of the subsequence or None if not
+            match.
+            """
+            if not needle:
+                return start
+            i = start
+            j = 0
+            first_pos = None
+            while i < len(hay) and j < len(needle):
+                if hay[i] == needle[j]:
+                    if first_pos is None:
+                        first_pos = i
+                    j += 1
+                i += 1
+            return first_pos if j == len(needle) else None
 
-    def _find_subsequence_pos(
-        self, hay: str, needle: str, start: int = 0
-    ) -> int | None:
-        """
-        Try to locate needle in hay as a subsequence starting at `start`.
-        Returns the index of the first matched character of the subsequence or None if not match.
-        """
-        if not needle:
-            return start
-        i = start
-        j = 0
-        first_pos = None
-        while i < len(hay) and j < len(needle):
-            if hay[i] == needle[j]:
-                if first_pos is None:
-                    first_pos = i
-                j += 1
-            i += 1
-        return first_pos if j == len(needle) else None
+    return ChatCompleter()

zrb/builtin/llm/chat_trigger.py

@@ -3,6 +3,7 @@ import os
 from asyncio import StreamReader
 from typing import TYPE_CHECKING, Any, Callable, Coroutine
 
+from zrb.builtin.llm.chat_completion import get_chat_completer
 from zrb.context.any_context import AnyContext
 from zrb.util.run import run_async
 
@@ -57,13 +58,11 @@ class LLMChatTrigger:
         """Reads one line of input using the provided reader."""
         from prompt_toolkit import PromptSession
 
-        from zrb.builtin.llm.chat_completion import ChatCompleter
-
         try:
             if isinstance(reader, PromptSession):
                 bottom_toolbar = f"📁 Current directory: {os.getcwd()}"
                 return await reader.prompt_async(
-                    completer=ChatCompleter(), bottom_toolbar=bottom_toolbar
+                    completer=get_chat_completer(), bottom_toolbar=bottom_toolbar
                 )
             line_bytes = await reader.readline()
             if not line_bytes:

zrb/builtin/llm/tool/cli.py

@@ -22,7 +22,7 @@ class ShellCommandResult(TypedDict):
     stderr: str
 
 
-def run_shell_command(command: str) -> ShellCommandResult:
+def run_shell_command(command: str, timeout: int = 30) -> ShellCommandResult:
     """
     Executes a non-interactive shell command on the user's machine.
 
@@ -31,22 +31,34 @@ def run_shell_command(command: str) -> ShellCommandResult:
     IMPORTANT: Long-running processes should be run in the background (e.g., `command &`).
 
     Example:
-    run_shell_command(command='ls -l')
+    run_shell_command(command='ls -l', timeout=30)
 
     Args:
         command (str): The exact shell command to be executed.
+        timeout (int): The maximum time in seconds to wait for the command to finish.
+            Defaults to 30.
 
     Returns:
         dict: return_code, stdout, and stderr.
     """
-    result = subprocess.run(
-        command,
-        shell=True,
-        capture_output=True,
-        text=True,
-    )
-    return {
-        "return_code": result.returncode,
-        "stdout": result.stdout,
-        "stderr": result.stderr,
-    }
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        return {
+            "return_code": int(result.returncode),
+            "stdout": str(result.stdout or ""),
+            "stderr": str(result.stderr or ""),
+        }
+    except subprocess.TimeoutExpired as e:
+        stdout = e.stdout.decode() if isinstance(e.stdout, bytes) else (e.stdout or "")
+        stderr = e.stderr.decode() if isinstance(e.stderr, bytes) else (e.stderr or "")
+        return {
+            "return_code": 124,
+            "stdout": str(stdout),
+            "stderr": f"{stderr}\nError: Command timed out after {timeout} seconds".strip(),
+        }

zrb/builtin/llm/tool/code.py

@@ -59,8 +59,12 @@ async def analyze_repo(
     """
     Analyzes a code repository or directory to answer a specific query.
 
-    CRITICAL: The quality of analysis depends entirely on the query. Vague queries yield poor
+    CRITICAL: The query must contain ALL necessary context, instructions, and information.
+        The sub-agent performing the analysis does NOT share your current conversation
+        history, memory, or global context.
+        The quality of analysis depends entirely on the query. Vague queries yield poor
         results.
+
     IMPORTANT: This tool can be slow and expensive on large repositories. Use judiciously.
 
     Example:

zrb/builtin/llm/tool/file.py

@@ -516,6 +516,12 @@ async def analyze_file(
     """
     Analyzes a file using a sub-agent for complex questions.
 
+    CRITICAL: The query must contain ALL necessary context, instructions, and information.
+        The sub-agent performing the analysis does NOT share your current conversation
+        history, memory, or global context.
+        The quality of analysis depends entirely on the query. Vague queries yield poor
+        results.
+
     Example:
     analyze_file(path='src/main.py', query='Summarize the main function.')
 

zrb/builtin/llm/tool/note.py

@@ -5,9 +5,9 @@ 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.
+    Retrieves the GLOBAL 🧠 Long Term Note shared across ALL sessions and projects.
 
-    CRITICAL: Consult this first for user preferences, facts, and cross-project context.
+    Use this to recall user preferences, facts, and cross-project context.
 
     Returns:
         str: The current global note content.
@@ -18,7 +18,7 @@ def read_long_term_note() -> str:
 
 def write_long_term_note(content: str) -> str:
     """
-    Persists CRITICAL facts to the GLOBAL long-term memory.
+    Persists CRITICAL facts to the GLOBAL 🧠 Long Term Note.
 
     USE EAGERLY to save or update:
     - User preferences (e.g., "I prefer Python", "No unit tests").
@@ -27,7 +27,7 @@ def write_long_term_note(content: str) -> str:
     - Cross-project goals.
     - Anything that will be useful for future interaction across projects.
 
-    WARNING: This OVERWRITES the entire global note.
+    WARNING: This OVERWRITES the entire Long Term Note.
 
     Args:
         content (str): The text to strictly memorize.
@@ -41,7 +41,7 @@ def write_long_term_note(content: str) -> str:
 
 def read_contextual_note(path: str | None = None) -> str:
     """
-    Retrieves LOCAL memory specific to a file or directory path.
+    Retrieves LOCAL 📝 Contextual Note specific to a directory path.
 
     Use to recall project-specific architecture, code summaries, or past decisions
     relevant to the current working location.
@@ -61,7 +61,7 @@ def read_contextual_note(path: str | None = None) -> str:
 
 def write_contextual_note(content: str, path: str | None = None) -> str:
     """
-    Persists LOCAL facts specific to a file or directory.
+    Persists LOCAL facts specific to a directory into 📝 Contextual Note.
 
     USE EAGERLY to save or update:
     - Architectural patterns for this project/directory.
@@ -69,7 +69,7 @@ def write_contextual_note(content: str, path: str | None = None) -> str:
     - 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.
+    WARNING: This OVERWRITES the entire Contextual Note for a directory.
 
     Args:
         content (str): The text to memorize for this location.

zrb/builtin/llm/tool/search/__init__.py

@@ -0,0 +1 @@
+# This file makes the directory a Python package

zrb/builtin/llm/tool/search/brave.py

@@ -0,0 +1,60 @@
+from typing import Any
+
+import requests
+
+from zrb.config.config import CFG
+
+
+def search_internet(
+    query: str,
+    page: int = 1,
+    safe_search: str | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """
+    Performs an internet search using Brave Search.
+
+    Use this tool to find up-to-date information, answer questions about current events,
+    or research topics using a search engine.
+
+    Args:
+        query (str): The natural language search query (e.g., 'Soto Madura').
+            Do NOT include instructions, meta-talk, or internal reasoning.
+            Use concise terms as a human would in a search engine.
+        page (int): Search result page number. Defaults to 1.
+        safe_search (str | None): Safety setting. 'strict', 'moderate', or 'off'.
+            If None, uses the system default configuration.
+        language (str | None): Language code (e.g., 'en').
+            If None, uses the system default configuration.
+
+    Returns:
+        dict: Summary of search results (titles, links, snippets).
+    """
+    if safe_search is None:
+        safe_search = CFG.BRAVE_API_SAFE
+    if language is None:
+        language = CFG.BRAVE_API_LANG
+
+    user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"  # noqa
+
+    response = requests.get(
+        "https://api.search.brave.com/res/v1/web/search",
+        headers={
+            "User-Agent": user_agent,
+            "Accept": "application/json",
+            "x-subscription-token": CFG.BRAVE_API_KEY,
+        },
+        params={
+            "q": query,
+            "count": "10",
+            "offset": (page - 1) * 10,
+            "safesearch": safe_search,
+            "search_lang": language,
+            "summary": "true",
+        },
+    )
+    if response.status_code != 200:
+        raise Exception(
+            f"Error: Unable to retrieve search results (status code: {response.status_code})"
+        )
+    return response.json()

zrb/builtin/llm/tool/search/searxng.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+import requests
+
+from zrb.config.config import CFG
+
+
+def search_internet(
+    query: str,
+    page: int = 1,
+    safe_search: int | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """
+    Performs an internet search using SearXNG.
+
+    Use this tool to find up-to-date information, answer questions about current events,
+    or research topics using a search engine.
+
+    Args:
+        query (str): The natural language search query (e.g., 'Soto Madura').
+            Do NOT include instructions, meta-talk, or internal reasoning.
+            Use concise terms as a human would in a search engine.
+        page (int): Search result page number. Defaults to 1.
+        safe_search (int | None): Safety setting. 0 (None), 1 (Moderate), 2 (Strict).
+            If None, uses the system default configuration.
+        language (str | None): Language code (e.g., 'en').
+            If None, uses the system default configuration.
+
+    Returns:
+        dict: Summary of search results (titles, links, snippets).
+    """
+    if safe_search is None:
+        safe_search = CFG.SEARXNG_SAFE
+    if language is None:
+        language = CFG.SEARXNG_LANG
+
+    user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"  # noqa
+
+    response = requests.get(
+        url=f"{CFG.SEARXNG_BASE_URL}/search",
+        headers={"User-Agent": user_agent},
+        params={
+            "q": query,
+            "format": "json",
+            "pageno": page,
+            "safesearch": safe_search,
+            "language": language,
+        },
+    )
+    if response.status_code != 200:
+        raise Exception(
+            f"Error: Unable to retrieve search results (status code: {response.status_code})"
+        )
+    return response.json()

zrb/builtin/llm/tool/search/serpapi.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+import requests
+
+from zrb.config.config import CFG
+
+
+def search_internet(
+    query: str,
+    page: int = 1,
+    safe_search: str | None = None,
+    language: str | None = None,
+) -> dict[str, Any]:
+    """
+    Performs an internet search using SerpApi (Google).
+
+    Use this tool to find up-to-date information, answer questions about current events,
+    or research topics using a search engine.
+
+    Args:
+        query (str): The natural language search query (e.g., 'Soto Madura').
+            Do NOT include instructions, meta-talk, or internal reasoning.
+            Use concise terms as a human would in a search engine.
+        page (int): Search result page number. Defaults to 1.
+        safe_search (str | None): Safety setting. 'active' or 'off'.
+            If None, uses the system default configuration.
+        language (str | None): Two-letter language code (e.g., 'en', 'id').
+            If None, uses the system default configuration.
+
+    Returns:
+        dict: Summary of search results (titles, links, snippets).
+    """
+    if safe_search is None:
+        safe_search = CFG.SERPAPI_SAFE
+    if language is None:
+        language = CFG.SERPAPI_LANG
+
+    user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"  # noqa
+
+    response = requests.get(
+        "https://serpapi.com/search",
+        headers={"User-Agent": user_agent},
+        params={
+            "q": query,
+            "start": (page - 1) * 10,
+            "hl": language,
+            "safe": safe_search,
+            "api_key": CFG.SERPAPI_KEY,
+        },
+    )
+    if response.status_code != 200:
+        raise Exception(
+            f"Error: Unable to retrieve search results (status code: {response.status_code})"
+        )
+    return response.json()

zrb/builtin/llm/tool/web.py

@@ -2,6 +2,7 @@ from collections.abc import Callable
 from typing import Any
 from urllib.parse import urljoin
 
+from zrb.builtin.llm.tool.search import brave, searxng, serpapi
 from zrb.config.config import CFG
 from zrb.config.llm_config import llm_config
 
@@ -30,78 +31,17 @@ async def open_web_page(url: str) -> dict[str, Any]:
 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, page: int = 1) -> dict[str, Any]:
-        """
-        Performs an internet search using a search engine.
-        Use to find information, answer general knowledge, or research topics.
-
-        Example:
-        search_internet(query='latest AI advancements', page=1)
-
-        Args:
-            query (str): The search query.
-            page (int, optional): Search result page number. Defaults to 1.
-
-        Returns:
-            dict: Summary of search results (titles, links, snippets).
-        """
-        import requests
-
-        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})"  # noqa
-            )
-        return response.json()
-
-    return search_internet
+    if (
+        CFG.SEARCH_INTERNET_METHOD.strip().lower() == "serpapi"
+        and CFG.SERPAPI_KEY != ""
+    ):
+        return serpapi.search_internet
+    if (
+        CFG.SEARCH_INTERNET_METHOD.strip().lower() == "brave"
+        and CFG.BRAVE_API_KEY != ""
+    ):
+        return brave.search_internet
+    return searxng.search_internet
 
 
 async def _fetch_page_content(url: str) -> tuple[str, list[str]]:

zrb/task/llm/tool_confirmation_completer.py

@@ -0,0 +1,41 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prompt_toolkit.completion import Completer
+
+
+def get_tool_confirmation_completer(
+    options: list[str], meta_dict: dict[str, str]
+) -> "Completer":
+    from prompt_toolkit.completion import Completer, Completion
+
+    class ToolConfirmationCompleter(Completer):
+        """Custom completer for tool confirmation that doesn't auto-complete partial words."""
+
+        def __init__(self, options, meta_dict):
+            self.options = options
+            self.meta_dict = meta_dict
+
+        def get_completions(self, document, complete_event):
+            text = document.text.strip()
+            # 1. Input is empty, OR
+            # 2. Input exactly matches the beginning of an option
+            if text == "":
+                # Show all options when nothing is typed
+                for option in self.options:
+                    yield Completion(
+                        option,
+                        start_position=0,
+                        display_meta=self.meta_dict.get(option, ""),
+                    )
+                return
+            # Only complete if text exactly matches the beginning of an option
+            for option in self.options:
+                if option.startswith(text):
+                    yield Completion(
+                        option,
+                        start_position=-len(text),
+                        display_meta=self.meta_dict.get(option, ""),
+                    )
+
+    return ToolConfirmationCompleter(options, meta_dict)

zrb/task/llm/tool_wrapper.py

@@ -11,11 +11,11 @@ from zrb.config.llm_rate_limitter import llm_rate_limitter
 from zrb.context.any_context import AnyContext
 from zrb.task.llm.error import ToolExecutionError
 from zrb.task.llm.file_replacement import edit_replacement, is_single_path_replacement
+from zrb.task.llm.tool_confirmation_completer import get_tool_confirmation_completer
 from zrb.util.callable import get_callable_name
 from zrb.util.cli.markdown import render_markdown
 from zrb.util.cli.style import (
     stylize_blue,
-    stylize_error,
     stylize_faint,
     stylize_green,
     stylize_yellow,
@@ -296,7 +296,6 @@ def _truncate_arg(arg: str, length: int = 19) -> str:
 
 async def _read_line(args: list[Any] | tuple[Any], kwargs: dict[str, Any]):
     from prompt_toolkit import PromptSession
-    from prompt_toolkit.completion import WordCompleter
 
     options = ["yes", "no", "edit"]
     meta_dict = {
@@ -307,7 +306,7 @@ async def _read_line(args: list[Any] | tuple[Any], kwargs: dict[str, Any]):
     for key in kwargs:
         options.append(f"edit {key}")
         meta_dict[f"edit {key}"] = f"Edit tool execution parameter: {key}"
-    completer = WordCompleter(options, ignore_case=True, meta_dict=meta_dict)
+    completer = get_tool_confirmation_completer(options, meta_dict)
     reader = PromptSession()
     return await reader.prompt_async(completer=completer)
 

{zrb-1.21.28.dist-info → zrb-1.21.31.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zrb
-Version: 1.21.28
+Version: 1.21.31
 Summary: Your Automation Powerhouse
 License: AGPL-3.0-or-later
 Keywords: Automation,Task Runner,Code Generator,Monorepo,Low Code

{zrb-1.21.28.dist-info → zrb-1.21.31.dist-info}/RECORD

@@ -10,23 +10,27 @@ zrb/builtin/group.py,sha256=W_IA_4414c8Wi8QazqcT6Gq6UftrKwy95yMF114EJtI,2677
 zrb/builtin/http.py,sha256=L6RE73c65wWwG5iHFN-tpOhyh56KsrgVskDd3c3YXtk,4246
 zrb/builtin/jwt.py,sha256=3M5uaQhJZbKQLjTUft1OwPz_JxtmK-xtkjxWjciOQho,2859
 zrb/builtin/llm/attachment.py,sha256=UwhOGtZY9Px9aebsKfTTw2_ZIpbsqx0XgoAonk6Ewkc,1344
-zrb/builtin/llm/chat_completion.py,sha256=ybOo-LZaoUjhEBd1N8R-ZpN7MCV88VHGG9Phs3yLi1w,11060
+zrb/builtin/llm/chat_completion.py,sha256=cWVju5ApC2OPGM3ZWGaXwSgLwgT9leKS_TbV4z610zc,12252
 zrb/builtin/llm/chat_session.py,sha256=TmXL7IkVT22blgWqG625qpr2_BnDMIm7ERYbR61BL4Q,9154
 zrb/builtin/llm/chat_session_cmd.py,sha256=lGiN-YNtv957wYuuF_mXV0opbRN61U9pyxVVq-_Gwv8,10842
-zrb/builtin/llm/chat_trigger.py,sha256=TZ4u5oQ4W7RGJB2yNrmGRfSEaBbMj4SXEGZHJrYjiJo,2672
+zrb/builtin/llm/chat_trigger.py,sha256=i6_lej2xYfY8k5-CMIUsdYQdUvBV9ma_DM6ZmgLaQIU,2673
 zrb/builtin/llm/history.py,sha256=qNRYq6SlJH5iuzdra_FOJxevWXCDh5YMvN2qPNLjI8I,3099
 zrb/builtin/llm/input.py,sha256=Nw-26uTWp2QhUgKJcP_IMHmtk-b542CCSQ_vCOjhvhM,877
 zrb/builtin/llm/llm_ask.py,sha256=6fUbCFjgjFiTVf-88WJZ1RD5wgOzmsVEpD3dR16Jl_8,8598
 zrb/builtin/llm/previous-session.js,sha256=xMKZvJoAbrwiyHS0OoPrWuaKxWYLoyR5sguePIoCjTY,816
 zrb/builtin/llm/tool/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 zrb/builtin/llm/tool/api.py,sha256=ItGJLr_1vhmLcitfIKeVDrnJEWdsyqucDnQ7enIC8fQ,2394
-zrb/builtin/llm/tool/cli.py,sha256=iwQtiyPgd5RibUHEtO38c4KS6D4_oCdLqv_bZZqM160,1257
-zrb/builtin/llm/tool/code.py,sha256=GdMKCc3Z3bllly0tgtUXMoWdIA9WDjyNcoKftNksJTk,7699
-zrb/builtin/llm/tool/file.py,sha256=ktGWwGMl1nYtHFw1go10kuvKCbrtkjPkQ4bvDgWM5iY,19294
-zrb/builtin/llm/tool/note.py,sha256=HD7qRldvZUpfHW0i4Dev6UZba5j5r4Z3CugB5umL3Wk,2566
+zrb/builtin/llm/tool/cli.py,sha256=eNmNgNR5H57idYAIXJ50mipAs2KzYGiN44h7xFHvF-k,1917
+zrb/builtin/llm/tool/code.py,sha256=1sErE5tsticXGNhiE0bTjI21Zq6zHMgS2hVM6dsAcww,7916
+zrb/builtin/llm/tool/file.py,sha256=LLdkE_hTZYDm9x3EwAo9Xsp7T_OV6ljmGLJksr-e4CM,19622
+zrb/builtin/llm/tool/note.py,sha256=USDQe8F1ddQp5dhv2u35rUN9EfJQl5BaWJIs6Xg9ZZY,2597
 zrb/builtin/llm/tool/rag.py,sha256=lmoA42IWHcBOWTsWzYGklLs1YoiEldvu_Bi5bp6gbts,9439
+zrb/builtin/llm/tool/search/__init__.py,sha256=wiMaie_IYt00fak-LrioC1qEZDs0SwYz4UWwidHfpFU,49
+zrb/builtin/llm/tool/search/brave.py,sha256=WDRki3UZ9KnzZ15QxCube6LcgnC8G1bTTv-MWfowwe8,2013
+zrb/builtin/llm/tool/search/searxng.py,sha256=0XzcegO1cO3r926z0O8ostD-R-8ysLQCJXLB4RTQ0J0,1834
+zrb/builtin/llm/tool/search/serpapi.py,sha256=UxRzLqKZGcNhvOzj6CRWQFgtYTN3OCWpyT9w9OKlytc,1843
 zrb/builtin/llm/tool/sub_agent.py,sha256=UNgsvZvSQ1b5ybB0nRzTiFCJpZG3g2RLj_nzjRZzXMY,5808
-zrb/builtin/llm/tool/web.py,sha256=x7iHaGRr71yU3qjfKsoyHvht5SB_S3kWPXX2qliyy6k,6278
+zrb/builtin/llm/tool/web.py,sha256=xtfbGNEW9KYfTg-mTp0wpVziQ5NFi6rslNzR_hvS67s,4122
 zrb/builtin/md5.py,sha256=690RV2LbW7wQeTFxY-lmmqTSVEEZv3XZbjEUW1Q3XpE,1480
 zrb/builtin/project/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 zrb/builtin/project/add/fastapp/fastapp_input.py,sha256=MKlWR_LxWhM_DcULCtLfL_IjTxpDnDBkn9KIqNmajFs,310
@@ -378,7 +382,8 @@ zrb/task/llm/history_summarization.py,sha256=YqLm9Q5xzFVTL5XwnWu3XwaMgSxKskDFvoi
 zrb/task/llm/print_node.py,sha256=d7OMOJ2kj6iXZS2cC5cyuDF1QDFsA9FxDGX-xfirvxs,8674
 zrb/task/llm/prompt.py,sha256=jlFNWa1IMCYNQh9Ccq9DB1dq9964IOQJ5jNSC9rMpkw,11366
 zrb/task/llm/subagent_conversation_history.py,sha256=y8UbKF2GpjB-r1bc2xCpzepriVEq0wfdyFuHOwfpPfk,1647
-zrb/task/llm/tool_wrapper.py,sha256=1kKXtZ9Wk6gSZJUpXuccdBZH-8RaQ91lTcTrum1nLog,12440
+zrb/task/llm/tool_confirmation_completer.py,sha256=rOYZdq5No9DfLUG889cr99cUX6XmoO29Yh9FUcdMMio,1534
+zrb/task/llm/tool_wrapper.py,sha256=FfW2JcZ8vUVie0pekpwpQABQ8DhIv8EG7_kPSYGwsVw,12440
 zrb/task/llm/typing.py,sha256=c8VAuPBw_4A3DxfYdydkgedaP-LU61W9_wj3m3CAX1E,58
 zrb/task/llm/workflow.py,sha256=eGpUXoIKgbPFPZJ7hHy_HkGYnGWWx9-B9FNjjNm3_8I,2968
 zrb/task/llm_task.py,sha256=8tNtyufjsWUu5jJQEo9-dpl1N6fycA1ugllaKgLvOao,16571
@@ -432,7 +437,7 @@ zrb/util/truncate.py,sha256=eSzmjBpc1Qod3lM3M73snNbDOcARHukW_tq36dWdPvc,921
 zrb/util/yaml.py,sha256=MXcqQTOYzx16onFxxg6HNdavxDK4RQjvKUi2NMKd19Y,6510
 zrb/xcom/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 zrb/xcom/xcom.py,sha256=W5BOF9w5fVX2ZBlbOTMsXHbY0yU8Advm-_oWJ3DJvDM,1824
-zrb-1.21.28.dist-info/METADATA,sha256=fs0DhOtJarqSf8NvHERj0DK3yKjhNV902bLKYvuLa5w,10622
-zrb-1.21.28.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-zrb-1.21.28.dist-info/entry_points.txt,sha256=-Pg3ElWPfnaSM-XvXqCxEAa-wfVI6BEgcs386s8C8v8,46
-zrb-1.21.28.dist-info/RECORD,,
+zrb-1.21.31.dist-info/METADATA,sha256=LQK_9dOC8LRBm3Paivofzrd3MUWzaTIpXYpMk8p0suk,10622
+zrb-1.21.31.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+zrb-1.21.31.dist-info/entry_points.txt,sha256=-Pg3ElWPfnaSM-XvXqCxEAa-wfVI6BEgcs386s8C8v8,46
+zrb-1.21.31.dist-info/RECORD,,