zrb 1.9.5__tar.gz → 1.9.7__tar.gz

zrb-1.9.7/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.1
+Name: zrb
+Version: 1.9.7
+Summary: Your Automation Powerhouse
+Home-page: https://github.com/state-alchemists/zrb
+License: AGPL-3.0-or-later
+Keywords: Automation,Task Runner,Code Generator,Monorepo,Low Code
+Author: Go Frendi Gunawan
+Author-email: gofrendiasgard@gmail.com
+Requires-Python: >=3.10.0,<4.0.0
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: all
+Provides-Extra: playwright
+Provides-Extra: rag
+Requires-Dist: beautifulsoup4 (>=4.13.3,<5.0.0)
+Requires-Dist: black (>=25.1.0,<25.2.0)
+Requires-Dist: chromadb (>=0.6.3,<0.7.0) ; extra == "rag" or extra == "all"
+Requires-Dist: fastapi[standard] (>=0.115.14,<0.116.0)
+Requires-Dist: isort (>=6.0.1,<6.1.0)
+Requires-Dist: libcst (>=1.7.0,<2.0.0)
+Requires-Dist: openai (>=1.86.0,<2.0.0) ; extra == "rag" or extra == "all"
+Requires-Dist: pdfplumber (>=0.11.6,<0.12.0) ; extra == "rag" or extra == "all"
+Requires-Dist: playwright (>=1.53.0,<2.0.0) ; extra == "playwright" or extra == "all"
+Requires-Dist: prompt-toolkit (>=3.0.51,<4.0.0)
+Requires-Dist: psutil (>=7.0.0,<8.0.0)
+Requires-Dist: pydantic-ai (>=0.3.4,<0.4.0)
+Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
+Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
+Requires-Dist: python-jose[cryptography] (>=3.4.0,<4.0.0)
+Requires-Dist: requests (>=2.32.4,<3.0.0)
+Requires-Dist: rich (>=14.0.0,<15.0.0)
+Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
+Requires-Dist: ulid-py (>=1.1.0,<2.0.0)
+Project-URL: Documentation, https://github.com/state-alchemists/zrb
+Project-URL: Repository, https://github.com/state-alchemists/zrb
+Description-Content-Type: text/markdown
+
+![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb/android-chrome-192x192.png)
+
+# 🤖 Zrb: Your Automation Powerhouse
+
+**Zrb (Zaruba) is a Python-based tool that makes it easy to create, organize, and run automation tasks.** Think of it as a command-line sidekick, ready to handle everything from simple scripts to complex, AI-powered workflows.
+
+Whether you're running tasks from the terminal or a sleek web UI, Zrb streamlines your process with task dependencies, environment management, and even inter-task communication.
+
+[Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) | [Contribution Guidelines](https://github.com/state-alchemists/zrb/pulls) | [Report an Issue](https://github.com/state-alchemists/zrb/issues)
+
+---
+
+## 🔥 Why Choose Zrb?
+
+Zrb is designed to be powerful yet intuitive, offering a unique blend of features:
+
+-   🤖 **Built-in LLM Integration:** Go beyond simple automation. Leverage Large Language Models to generate code, create diagrams, produce documentation, and more.
+-   🐍 **Pure Python:** Write your tasks in Python. No complex DSLs or YAML configurations to learn.
+-   🔗 **Smart Task Chaining:** Define dependencies between tasks to build sophisticated, ordered workflows.
+-   💻 **Dual-Mode Execution:** Run tasks from the command line for speed or use the built-in web UI for a more visual experience.
+-   ⚙️ **Flexible Configuration:** Manage inputs with defaults, prompts, or command-line arguments. Handle secrets and settings with environment variables from the system or `.env` files.
+-   🗣️ **Cross-Communication (XCom):** Allow tasks to safely exchange small pieces of data.
+-   🌍 **Open & Extensible:** Zrb is open-source. Feel free to contribute, customize, or extend it to meet your needs.
+
+---
+
+## 🚀 Quick Start: Your First AI-Powered Workflow in 5 Minutes
+
+Let's create a two-step workflow that uses an LLM to analyze your code and generate a Mermaid diagram, then converts that diagram into a PNG image.
+
+### 1. Prerequisites: Get Your Tools Ready
+
+Before you start, make sure you have the following:
+
+-   **An LLM API Key:** Zrb needs an API key to talk to an AI model.
+    ```bash
+    export OPENAI_API_KEY="your-key-here"
+    ```
+    > Zrb defaults to OpenAI, but you can easily configure it for other providers like **Deepseek, Ollama, etc.** See the [LLM Integration Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/configuration/llm-integration.md) for details.
+
+-   **Mermaid CLI:** This tool converts Mermaid diagram scripts into images.
+    ```bash
+    npm install -g @mermaid-js/mermaid-cli
+    ```
+
+### 2. Install Zrb
+
+The easiest way to get Zrb is with `pip`.
+
+```bash
+pip install zrb
+# Or for the latest pre-release version:
+# pip install --pre zrb
+```
+
+Alternatively, you can use an installation script that handles all prerequisites:
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/state-alchemists/zrb/main/install.sh)"
+```
+
+> For other installation methods, including **Docker 🐋** and **Android 📱**, check out the full [Installation Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/README.md).
+
+### 3. Define Your Tasks
+
+Create a file named `zrb_init.py` in your project directory. Zrb automatically discovers this file.
+
+> **💡 Pro Tip:** You can place `zrb_init.py` in your home directory (`~/zrb_init.py`), and the tasks you define will be available globally across all your projects!
+
+Add the following Python code to your `zrb_init.py`:
+
+```python
+from zrb import cli, LLMTask, CmdTask, StrInput, Group
+from zrb.builtin.llm.tool.code import analyze_repo
+from zrb.builtin.llm.tool.file import write_to_file
+
+
+# Create a group for Mermaid-related tasks
+mermaid_group = cli.add_group(Group(
+    name="mermaid",
+    description="🧜 Mermaid diagram related tasks"
+))
+
+# Task 1: Generate a Mermaid script from your source code
+make_mermaid_script = mermaid_group.add_task(
+    LLMTask(
+        name="make-script",
+        description="Create a mermaid diagram from source code in the current directory",
+        input=[
+            StrInput(name="dir", default="./"),
+            StrInput(name="diagram", default="state-diagram"),
+        ],
+        message=(
+            "Read all necessary files in {ctx.input.dir}, "
+            "make a {ctx.input.diagram} in mermaid format. "
+            "Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`"
+        ),
+        tools=[
+            analyze_repo, write_to_file
+        ],
+    )
+)
+
+# Task 2: Convert the Mermaid script into a PNG image
+make_mermaid_image = mermaid_group.add_task(
+    CmdTask(
+        name="make-image",
+        description="Create a PNG from a mermaid script",
+        input=[
+            StrInput(name="dir", default="./"),
+            StrInput(name="diagram", default="state-diagram"),
+        ],
+        cmd="mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'",
+        cwd="{ctx.input.dir}",
+    )
+)
+
+# Set up the dependency: the image task runs after the script is created
+make_mermaid_script >> make_mermaid_image
+```
+
+### 4. Run Your Workflow!
+
+Now, navigate to any project with source code. For example:
+
+```bash
+git clone git@github.com:jjinux/gotetris.git
+cd gotetris
+```
+
+Run your new task to generate the diagram:
+
+```bash
+zrb mermaid make-image --diagram "state-diagram" --dir ./
+```
+
+You can also run it interactively and let Zrb prompt you for inputs:
+```bash
+zrb mermaid make-image
+```
+Zrb will ask for the directory and diagram name—just press **Enter** to accept the defaults.
+
+In moments, you'll have a beautiful state diagram of your code!
+
+![State Diagram](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/state-diagram.png)
+
+---
+
+## 🖥️ Try the Web UI
+
+Prefer a graphical interface? Zrb has you covered. Start the web server:
+
+```bash
+zrb server start
+```
+
+Then open your browser to `http://localhost:21213` to see your tasks in a clean, user-friendly interface.
+
+![Zrb Web UI](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb-web-ui.png)
+
+---
+
+## 💬 Interact with an LLM Directly
+
+Zrb brings AI capabilities right to your command line.
+
+### Interactive Chat
+
+Start a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.
+
+```bash
+zrb llm chat
+```
+
+### Quick Questions
+
+For a single question, use the `ask` command for a fast response.
+
+```bash
+zrb llm ask "What is the capital of Indonesia?"
+```
+
+---
+
+## 🎥 Demo & Documentation
+
+-   **Dive Deeper:** [**Explore the Full Zrb Documentation**](https://github.com/state-alchemists/zrb/blob/main/docs/README.md)
+-   **Watch the Video Demo:**
+
+    [![Video Title](https://img.youtube.com/vi/W7dgk96l__o/0.jpg)](https://www.youtube.com/watch?v=W7dgk96l__o)
+
+---
+
+## 🤝 Join the Community & Support the Project
+
+-   **Bugs & Feature Requests:** Found a bug or have a great idea? [Open an issue](https://github.com/state-alchemists/zrb/issues). Please include your Zrb version (`zrb version`) and steps to reproduce the issue.
+-   **Contributions:** We love pull requests! See our [contribution guidelines](https://github.com/state-alchemists/zrb/pulls) to get started.
+-   **Support Zrb:** If you find Zrb valuable, please consider showing your support.
+
+    [![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/donator.png)](https://stalchmst.com)
+
+---
+
+## 🎉 Fun Fact
+
+**Did you know?** Zrb is named after `Zaruba`, a powerful, sentient Madou Ring that acts as a guide and support tool in the *Garo* universe.
+
+> *Madou Ring Zaruba (魔導輪ザルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor.* [(Garo Wiki | Fandom)](https://garo.fandom.com/wiki/Zaruba)
+
+![Madou Ring Zaruba on Kouga's Hand](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/madou-ring-zaruba.jpg)

zrb-1.9.7/README.md

@@ -0,0 +1,209 @@
+![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb/android-chrome-192x192.png)
+
+# 🤖 Zrb: Your Automation Powerhouse
+
+**Zrb (Zaruba) is a Python-based tool that makes it easy to create, organize, and run automation tasks.** Think of it as a command-line sidekick, ready to handle everything from simple scripts to complex, AI-powered workflows.
+
+Whether you're running tasks from the terminal or a sleek web UI, Zrb streamlines your process with task dependencies, environment management, and even inter-task communication.
+
+[Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) | [Contribution Guidelines](https://github.com/state-alchemists/zrb/pulls) | [Report an Issue](https://github.com/state-alchemists/zrb/issues)
+
+---
+
+## 🔥 Why Choose Zrb?
+
+Zrb is designed to be powerful yet intuitive, offering a unique blend of features:
+
+-   🤖 **Built-in LLM Integration:** Go beyond simple automation. Leverage Large Language Models to generate code, create diagrams, produce documentation, and more.
+-   🐍 **Pure Python:** Write your tasks in Python. No complex DSLs or YAML configurations to learn.
+-   🔗 **Smart Task Chaining:** Define dependencies between tasks to build sophisticated, ordered workflows.
+-   💻 **Dual-Mode Execution:** Run tasks from the command line for speed or use the built-in web UI for a more visual experience.
+-   ⚙️ **Flexible Configuration:** Manage inputs with defaults, prompts, or command-line arguments. Handle secrets and settings with environment variables from the system or `.env` files.
+-   🗣️ **Cross-Communication (XCom):** Allow tasks to safely exchange small pieces of data.
+-   🌍 **Open & Extensible:** Zrb is open-source. Feel free to contribute, customize, or extend it to meet your needs.
+
+---
+
+## 🚀 Quick Start: Your First AI-Powered Workflow in 5 Minutes
+
+Let's create a two-step workflow that uses an LLM to analyze your code and generate a Mermaid diagram, then converts that diagram into a PNG image.
+
+### 1. Prerequisites: Get Your Tools Ready
+
+Before you start, make sure you have the following:
+
+-   **An LLM API Key:** Zrb needs an API key to talk to an AI model.
+    ```bash
+    export OPENAI_API_KEY="your-key-here"
+    ```
+    > Zrb defaults to OpenAI, but you can easily configure it for other providers like **Deepseek, Ollama, etc.** See the [LLM Integration Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/configuration/llm-integration.md) for details.
+
+-   **Mermaid CLI:** This tool converts Mermaid diagram scripts into images.
+    ```bash
+    npm install -g @mermaid-js/mermaid-cli
+    ```
+
+### 2. Install Zrb
+
+The easiest way to get Zrb is with `pip`.
+
+```bash
+pip install zrb
+# Or for the latest pre-release version:
+# pip install --pre zrb
+```
+
+Alternatively, you can use an installation script that handles all prerequisites:
+```bash
+bash -c "$(curl -fsSL https://raw.githubusercontent.com/state-alchemists/zrb/main/install.sh)"
+```
+
+> For other installation methods, including **Docker 🐋** and **Android 📱**, check out the full [Installation Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/README.md).
+
+### 3. Define Your Tasks
+
+Create a file named `zrb_init.py` in your project directory. Zrb automatically discovers this file.
+
+> **💡 Pro Tip:** You can place `zrb_init.py` in your home directory (`~/zrb_init.py`), and the tasks you define will be available globally across all your projects!
+
+Add the following Python code to your `zrb_init.py`:
+
+```python
+from zrb import cli, LLMTask, CmdTask, StrInput, Group
+from zrb.builtin.llm.tool.code import analyze_repo
+from zrb.builtin.llm.tool.file import write_to_file
+
+
+# Create a group for Mermaid-related tasks
+mermaid_group = cli.add_group(Group(
+    name="mermaid",
+    description="🧜 Mermaid diagram related tasks"
+))
+
+# Task 1: Generate a Mermaid script from your source code
+make_mermaid_script = mermaid_group.add_task(
+    LLMTask(
+        name="make-script",
+        description="Create a mermaid diagram from source code in the current directory",
+        input=[
+            StrInput(name="dir", default="./"),
+            StrInput(name="diagram", default="state-diagram"),
+        ],
+        message=(
+            "Read all necessary files in {ctx.input.dir}, "
+            "make a {ctx.input.diagram} in mermaid format. "
+            "Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`"
+        ),
+        tools=[
+            analyze_repo, write_to_file
+        ],
+    )
+)
+
+# Task 2: Convert the Mermaid script into a PNG image
+make_mermaid_image = mermaid_group.add_task(
+    CmdTask(
+        name="make-image",
+        description="Create a PNG from a mermaid script",
+        input=[
+            StrInput(name="dir", default="./"),
+            StrInput(name="diagram", default="state-diagram"),
+        ],
+        cmd="mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'",
+        cwd="{ctx.input.dir}",
+    )
+)
+
+# Set up the dependency: the image task runs after the script is created
+make_mermaid_script >> make_mermaid_image
+```
+
+### 4. Run Your Workflow!
+
+Now, navigate to any project with source code. For example:
+
+```bash
+git clone git@github.com:jjinux/gotetris.git
+cd gotetris
+```
+
+Run your new task to generate the diagram:
+
+```bash
+zrb mermaid make-image --diagram "state-diagram" --dir ./
+```
+
+You can also run it interactively and let Zrb prompt you for inputs:
+```bash
+zrb mermaid make-image
+```
+Zrb will ask for the directory and diagram name—just press **Enter** to accept the defaults.
+
+In moments, you'll have a beautiful state diagram of your code!
+
+![State Diagram](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/state-diagram.png)
+
+---
+
+## 🖥️ Try the Web UI
+
+Prefer a graphical interface? Zrb has you covered. Start the web server:
+
+```bash
+zrb server start
+```
+
+Then open your browser to `http://localhost:21213` to see your tasks in a clean, user-friendly interface.
+
+![Zrb Web UI](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb-web-ui.png)
+
+---
+
+## 💬 Interact with an LLM Directly
+
+Zrb brings AI capabilities right to your command line.
+
+### Interactive Chat
+
+Start a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.
+
+```bash
+zrb llm chat
+```
+
+### Quick Questions
+
+For a single question, use the `ask` command for a fast response.
+
+```bash
+zrb llm ask "What is the capital of Indonesia?"
+```
+
+---
+
+## 🎥 Demo & Documentation
+
+-   **Dive Deeper:** [**Explore the Full Zrb Documentation**](https://github.com/state-alchemists/zrb/blob/main/docs/README.md)
+-   **Watch the Video Demo:**
+
+    [![Video Title](https://img.youtube.com/vi/W7dgk96l__o/0.jpg)](https://www.youtube.com/watch?v=W7dgk96l__o)
+
+---
+
+## 🤝 Join the Community & Support the Project
+
+-   **Bugs & Feature Requests:** Found a bug or have a great idea? [Open an issue](https://github.com/state-alchemists/zrb/issues). Please include your Zrb version (`zrb version`) and steps to reproduce the issue.
+-   **Contributions:** We love pull requests! See our [contribution guidelines](https://github.com/state-alchemists/zrb/pulls) to get started.
+-   **Support Zrb:** If you find Zrb valuable, please consider showing your support.
+
+    [![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/donator.png)](https://stalchmst.com)
+
+---
+
+## 🎉 Fun Fact
+
+**Did you know?** Zrb is named after `Zaruba`, a powerful, sentient Madou Ring that acts as a guide and support tool in the *Garo* universe.
+
+> *Madou Ring Zaruba (魔導輪ザルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor.* [(Garo Wiki | Fandom)](https://garo.fandom.com/wiki/Zaruba)
+
+![Madou Ring Zaruba on Kouga's Hand](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/madou-ring-zaruba.jpg)

{zrb-1.9.5 → zrb-1.9.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zrb"
-version = "1.9.5"
+version = "1.9.7"
 description = "Your Automation Powerhouse"
 authors = ["Go Frendi Gunawan <gofrendiasgard@gmail.com>"]
 license = "AGPL-3.0-or-later"
@@ -83,4 +83,3 @@ zrb = "zrb.__main__:serve_cli"
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"
-

{zrb-1.9.5 → zrb-1.9.7}/src/zrb/builtin/llm/llm_ask.py

@@ -7,10 +7,10 @@ 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 (
     analyze_file,
-    apply_diff,
     list_files,
     read_from_file,
     read_many_files,
+    replace_in_file,
     search_files,
     write_many_files,
     write_to_file,
@@ -135,7 +135,7 @@ if CFG.LLM_ALLOW_ACCESS_LOCAL_FILE:
         list_files,
         read_from_file,
         read_many_files,
-        apply_diff,
+        replace_in_file,
         write_to_file,
         write_many_files,
     )

{zrb-1.9.5 → zrb-1.9.7}/src/zrb/builtin/llm/tool/api.py

@@ -3,11 +3,16 @@ from typing import Literal
 
 
 def get_current_location() -> str:
-    """Get current location (latitude, longitude) based on IP address.
+    """
+    Fetches the user's current geographical location (latitude and longitude) 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:
-        str: JSON string representing latitude and longitude.
+        str: A JSON string containing the 'lat' and 'lon' of the current location.
+             Example: '{"lat": 48.8584, "lon": 2.2945}'
     Raises:
-        requests.RequestException: If the API request fails.
+        requests.RequestException: If the API request to the location service fails.
     """
     import requests
 
@@ -24,15 +29,20 @@ def get_current_weather(
     longitude: float,
     temperature_unit: Literal["celsius", "fahrenheit"],
 ) -> str:
-    """Get current weather for a specific location.
+    """
+    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): Latitude coordinate.
-        longitude (float): Longitude coordinate.
-        temperature_unit (Literal["celsius", "fahrenheit"]): Temperature unit.
+        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:
-        str: JSON string with weather data.
+        str: A JSON string containing detailed weather data, including temperature, wind speed, and weather code.
     Raises:
-        requests.RequestException: If the API request fails.
+        requests.RequestException: If the API request to the weather service fails.
     """
     import requests
 

zrb-1.9.7/src/zrb/builtin/llm/tool/cli.py

@@ -0,0 +1,29 @@
+import subprocess
+
+
+def run_shell_command(command: str) -> str:
+    """
+    Executes a shell command on the user's local machine and returns the output.
+
+    This tool is powerful and should be used for tasks that require interacting with the command line, such as running scripts, managing system processes, or using command-line tools.
+
+    **Security Warning:** This tool executes commands with the same permissions as the user running the assistant. Before executing any command that could modify files or system state (e.g., `git`, `npm`, `pip`, `docker`), you MUST explain what the command does and ask the user for confirmation.
+
+    Args:
+        command (str): The exact shell command to execute.
+
+    Returns:
+        str: The combined standard output (stdout) and standard error (stderr) from the command. If the command fails, this will contain the error message.
+    Raises:
+        subprocess.CalledProcessError: If the command returns a non-zero exit code, indicating an error.
+    """
+    try:
+        output = subprocess.check_output(
+            command, shell=True, stderr=subprocess.STDOUT, text=True
+        )
+        return output
+    except subprocess.CalledProcessError as e:
+        # Include the error output in the exception message
+        raise subprocess.CalledProcessError(
+            e.returncode, e.cmd, e.output, e.stderr
+        ) from None

{zrb-1.9.5 → zrb-1.9.7}/src/zrb/builtin/llm/tool/code.py

@@ -86,29 +86,29 @@ async def analyze_repo(
     summarization_token_limit: int = 40000,
 ) -> str:
     """
-    Extract and summarize information from any directory.
-    You should state the goal specifically so that the tool can return relevant informations.
+    Performs a deep, goal-oriented analysis of a code repository or directory.
+
+    This powerful tool recursively reads all relevant files in a directory, extracts key information, and then summarizes that information in relation to a specific goal. It uses intelligent sub-agents for extraction and summarization, making it ideal for complex tasks that require a holistic understanding of a codebase.
+
     Use this tool for:
-    - summarization
-    - outline/structure extraction
-    - code review
-    - create diagram as code
-    - other tasks
+    - Understanding a large or unfamiliar codebase.
+    - Generating high-level summaries of a project's architecture.
+    - Performing a preliminary code review.
+    - Creating documentation or diagrams (e.g., "Generate a Mermaid C4 diagram for this service").
+    - Answering broad questions like "How does the authentication in this project work?".
+
     Args:
-        path (str): File path to be analyze. Pass exactly as provided, including '~'.
-        goal(str): Goal of extracting information (for example creating C4 diagram)
-        extensions(Optional[list[str]]): List of extension to be included
-            while reading resources. Defaults to common programming languages and config files.
-        exclude_patterns(Optional[list[str]]): List of patterns to exclude from analysis.
-            Common patterns like '.venv', 'node_modules' should be excluded by default.
-        extraction_token_limit(Optional[int]): Max resource content char length
-            the extraction assistant able to handle. Defaults to 150000
-        summarization_token_limit(Optional[int]): Max resource content char length
-            the summarization assistant able to handle. Defaults to 150000
+        path (str): The path to the directory or repository to analyze.
+        goal (str): A clear and specific description of what you want to achieve. A good goal is critical for getting a useful result. For example: "Understand the database schema by analyzing all the .sql files" or "Create a summary of all the API endpoints defined in the 'api' directory".
+        extensions (list[str], optional): A list of file extensions to include in the analysis. Defaults to a comprehensive list of common code and configuration files.
+        exclude_patterns (list[str], optional): A list of glob patterns for files and directories to exclude from the analysis. Defaults to common patterns like '.git', 'node_modules', and '.venv'.
+        extraction_token_limit (int, optional): The maximum token limit for the extraction sub-agent.
+        summarization_token_limit (int, optional): The maximum token limit for the summarization sub-agent.
+
     Returns:
-        str: The analysis result
+        str: A detailed, markdown-formatted analysis and summary of the repository, tailored to the specified goal.
     Raises:
-        Exception: If an error occurs.
+        Exception: If an error occurs during the analysis.
     """
     abs_path = os.path.abspath(os.path.expanduser(path))
     file_metadatas = _get_file_metadatas(abs_path, extensions, exclude_patterns)