zrb


Namezrb JSON
Version 1.9.16 PyPI version JSON
download
home_pagehttps://github.com/state-alchemists/zrb
SummaryYour Automation Powerhouse
upload_time2025-07-13 23:24:40
maintainerNone
docs_urlNone
authorGo Frendi Gunawan
requires_python<4.0.0,>=3.10.0
licenseAGPL-3.0-or-later
keywords automation task runner code generator monorepo low code
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            ![](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)
            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/state-alchemists/zrb",
    "name": "zrb",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0.0,>=3.10.0",
    "maintainer_email": null,
    "keywords": "Automation, Task Runner, Code Generator, Monorepo, Low Code",
    "author": "Go Frendi Gunawan",
    "author_email": "gofrendiasgard@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/36/f4/bec2713bca3fbc580b4504075833e41f3c95078ceef8409b61c6537eee78/zrb-1.9.16.tar.gz",
    "platform": null,
    "description": "![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb/android-chrome-192x192.png)\n\n# \ud83e\udd16 Zrb: Your Automation Powerhouse\n\n**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.\n\nWhether 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.\n\n[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)\n\n---\n\n## \ud83d\udd25 Why Choose Zrb?\n\nZrb is designed to be powerful yet intuitive, offering a unique blend of features:\n\n-   \ud83e\udd16 **Built-in LLM Integration:** Go beyond simple automation. Leverage Large Language Models to generate code, create diagrams, produce documentation, and more.\n-   \ud83d\udc0d **Pure Python:** Write your tasks in Python. No complex DSLs or YAML configurations to learn.\n-   \ud83d\udd17 **Smart Task Chaining:** Define dependencies between tasks to build sophisticated, ordered workflows.\n-   \ud83d\udcbb **Dual-Mode Execution:** Run tasks from the command line for speed or use the built-in web UI for a more visual experience.\n-   \u2699\ufe0f **Flexible Configuration:** Manage inputs with defaults, prompts, or command-line arguments. Handle secrets and settings with environment variables from the system or `.env` files.\n-   \ud83d\udde3\ufe0f **Cross-Communication (XCom):** Allow tasks to safely exchange small pieces of data.\n-   \ud83c\udf0d **Open & Extensible:** Zrb is open-source. Feel free to contribute, customize, or extend it to meet your needs.\n\n---\n\n## \ud83d\ude80 Quick Start: Your First AI-Powered Workflow in 5 Minutes\n\nLet'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.\n\n### 1. Prerequisites: Get Your Tools Ready\n\nBefore you start, make sure you have the following:\n\n-   **An LLM API Key:** Zrb needs an API key to talk to an AI model.\n    ```bash\n    export OPENAI_API_KEY=\"your-key-here\"\n    ```\n    > 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.\n\n-   **Mermaid CLI:** This tool converts Mermaid diagram scripts into images.\n    ```bash\n    npm install -g @mermaid-js/mermaid-cli\n    ```\n\n### 2. Install Zrb\n\nThe easiest way to get Zrb is with `pip`.\n\n```bash\npip install zrb\n# Or for the latest pre-release version:\n# pip install --pre zrb\n```\n\nAlternatively, you can use an installation script that handles all prerequisites:\n```bash\nbash -c \"$(curl -fsSL https://raw.githubusercontent.com/state-alchemists/zrb/main/install.sh)\"\n```\n\n> For other installation methods, including **Docker \ud83d\udc0b** and **Android \ud83d\udcf1**, check out the full [Installation Guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation-and-configuration/README.md).\n\n### 3. Define Your Tasks\n\nCreate a file named `zrb_init.py` in your project directory. Zrb automatically discovers this file.\n\n> **\ud83d\udca1 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!\n\nAdd the following Python code to your `zrb_init.py`:\n\n```python\nfrom zrb import cli, LLMTask, CmdTask, StrInput, Group\nfrom zrb.builtin.llm.tool.code import analyze_repo\nfrom zrb.builtin.llm.tool.file import write_to_file\n\n\n# Create a group for Mermaid-related tasks\nmermaid_group = cli.add_group(Group(\n    name=\"mermaid\",\n    description=\"\ud83e\udddc Mermaid diagram related tasks\"\n))\n\n# Task 1: Generate a Mermaid script from your source code\nmake_mermaid_script = mermaid_group.add_task(\n    LLMTask(\n        name=\"make-script\",\n        description=\"Create a mermaid diagram from source code in the current directory\",\n        input=[\n            StrInput(name=\"dir\", default=\"./\"),\n            StrInput(name=\"diagram\", default=\"state-diagram\"),\n        ],\n        message=(\n            \"Read all necessary files in {ctx.input.dir}, \"\n            \"make a {ctx.input.diagram} in mermaid format. \"\n            \"Write the script into `{ctx.input.dir}/{ctx.input.diagram}.mmd`\"\n        ),\n        tools=[\n            analyze_repo, write_to_file\n        ],\n    )\n)\n\n# Task 2: Convert the Mermaid script into a PNG image\nmake_mermaid_image = mermaid_group.add_task(\n    CmdTask(\n        name=\"make-image\",\n        description=\"Create a PNG from a mermaid script\",\n        input=[\n            StrInput(name=\"dir\", default=\"./\"),\n            StrInput(name=\"diagram\", default=\"state-diagram\"),\n        ],\n        cmd=\"mmdc -i '{ctx.input.diagram}.mmd' -o '{ctx.input.diagram}.png'\",\n        cwd=\"{ctx.input.dir}\",\n    )\n)\n\n# Set up the dependency: the image task runs after the script is created\nmake_mermaid_script >> make_mermaid_image\n```\n\n### 4. Run Your Workflow!\n\nNow, navigate to any project with source code. For example:\n\n```bash\ngit clone git@github.com:jjinux/gotetris.git\ncd gotetris\n```\n\nRun your new task to generate the diagram:\n\n```bash\nzrb mermaid make-image --diagram \"state-diagram\" --dir ./\n```\n\nYou can also run it interactively and let Zrb prompt you for inputs:\n```bash\nzrb mermaid make-image\n```\nZrb will ask for the directory and diagram name\u2014just press **Enter** to accept the defaults.\n\nIn moments, you'll have a beautiful state diagram of your code!\n\n![State Diagram](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/state-diagram.png)\n\n---\n\n## \ud83d\udda5\ufe0f Try the Web UI\n\nPrefer a graphical interface? Zrb has you covered. Start the web server:\n\n```bash\nzrb server start\n```\n\nThen open your browser to `http://localhost:21213` to see your tasks in a clean, user-friendly interface.\n\n![Zrb Web UI](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb-web-ui.png)\n\n---\n\n## \ud83d\udcac Interact with an LLM Directly\n\nZrb brings AI capabilities right to your command line.\n\n### Interactive Chat\n\nStart a chat session with an LLM to ask questions, brainstorm ideas, or get coding help.\n\n```bash\nzrb llm chat\n```\n\n### Quick Questions\n\nFor a single question, use the `ask` command for a fast response.\n\n```bash\nzrb llm ask \"What is the capital of Indonesia?\"\n```\n\n---\n\n## \ud83c\udfa5 Demo & Documentation\n\n-   **Dive Deeper:** [**Explore the Full Zrb Documentation**](https://github.com/state-alchemists/zrb/blob/main/docs/README.md)\n-   **Watch the Video Demo:**\n\n    [![Video Title](https://img.youtube.com/vi/W7dgk96l__o/0.jpg)](https://www.youtube.com/watch?v=W7dgk96l__o)\n\n---\n\n## \ud83e\udd1d Join the Community & Support the Project\n\n-   **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.\n-   **Contributions:** We love pull requests! See our [contribution guidelines](https://github.com/state-alchemists/zrb/pulls) to get started.\n-   **Support Zrb:** If you find Zrb valuable, please consider showing your support.\n\n    [![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/donator.png)](https://stalchmst.com)\n\n---\n\n## \ud83c\udf89 Fun Fact\n\n**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.\n\n> *Madou Ring Zaruba (\u9b54\u5c0e\u8f2a\u30b6\u30eb\u30d0, Mad\u014drin Zaruba) is a Madougu which supports bearers of the Garo Armor.* [(Garo Wiki | Fandom)](https://garo.fandom.com/wiki/Zaruba)\n\n![Madou Ring Zaruba on Kouga's Hand](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/madou-ring-zaruba.jpg)",
    "bugtrack_url": null,
    "license": "AGPL-3.0-or-later",
    "summary": "Your Automation Powerhouse",
    "version": "1.9.16",
    "project_urls": {
        "Documentation": "https://github.com/state-alchemists/zrb",
        "Homepage": "https://github.com/state-alchemists/zrb",
        "Repository": "https://github.com/state-alchemists/zrb"
    },
    "split_keywords": [
        "automation",
        " task runner",
        " code generator",
        " monorepo",
        " low code"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3fff6721472cf717ef50dd90c2aad322969d5f770be3fca1822a286a93a21340",
                "md5": "f8887dcb84316c7e575a038debe8ef61",
                "sha256": "e07ed2e9abd644ac44d90a569d18e48f53c4f84f2001a24f64fcbb5b36806a9a"
            },
            "downloads": -1,
            "filename": "zrb-1.9.16-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f8887dcb84316c7e575a038debe8ef61",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0.0,>=3.10.0",
            "size": 878874,
            "upload_time": "2025-07-13T23:24:38",
            "upload_time_iso_8601": "2025-07-13T23:24:38.020447Z",
            "url": "https://files.pythonhosted.org/packages/3f/ff/6721472cf717ef50dd90c2aad322969d5f770be3fca1822a286a93a21340/zrb-1.9.16-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "36f4bec2713bca3fbc580b4504075833e41f3c95078ceef8409b61c6537eee78",
                "md5": "1aae264b7ef7471ba42aec7317f1c6de",
                "sha256": "53f696f5be147482730f73f249109fa01b9f8b6dec364a702d782d298d94cb0b"
            },
            "downloads": -1,
            "filename": "zrb-1.9.16.tar.gz",
            "has_sig": false,
            "md5_digest": "1aae264b7ef7471ba42aec7317f1c6de",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0.0,>=3.10.0",
            "size": 724438,
            "upload_time": "2025-07-13T23:24:40",
            "upload_time_iso_8601": "2025-07-13T23:24:40.826518Z",
            "url": "https://files.pythonhosted.org/packages/36/f4/bec2713bca3fbc580b4504075833e41f3c95078ceef8409b61c6537eee78/zrb-1.9.16.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-13 23:24:40",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "state-alchemists",
    "github_project": "zrb",
    "travis_ci": false,
    "coveralls": true,
    "github_actions": true,
    "lcname": "zrb"
}
        
Elapsed time: 0.41547s