Metadata-Version: 2.4
Name: zrb-extras
Version: 0.2.0
Summary: Collection of Zrb additional utilities
License: AGPL-3.0-or-later
Author: Go Frendi Gunawan
Author-email: gofrendiasgard@gmail.com
Requires-Python: >=3.11.0,<3.15.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: google-genai (>=1.32.0,<2.0.0)
Requires-Dist: numpy (>=2.3.2,<3.0.0)
Requires-Dist: scipy (>=1.16.1,<2.0.0)
Requires-Dist: simpleaudio (>=1.0.4,<2.0.0)
Requires-Dist: sounddevice (>=0.5.2,<0.6.0)
Requires-Dist: soundfile (>=0.13.1,<0.14.0)
Requires-Dist: zrb (>=1.21.2)
Project-URL: Documentation, https://github.com/goFrendiAsgard/zrb-extras
Project-URL: Homepage, https://github.com/goFrendiAsgard/zrb-extras
Project-URL: Repository, https://github.com/goFrendiAsgard/zrb-extras
Description-Content-Type: text/markdown

# Zrb extras

zrb-extras is a [pypi](https://pypi.org) package.

You can install zrb-extras by invoking the following command:

```bash
pip install zrb-extras
```

## Let your `LLMTask` `speak` and `listen`

### Prerequisites

#### Termux

> First of all, make sure termux has permission to access microphone/speaker

```bash
pkg update && pkg upgrade -y
pkg install pulseaudio termux-api -y
```

Run the following script or add it to `~/.bashrc`

```bash
# start PulseAudio daemon
pulseaudio --start --load="module-native-protocol-tcp auth-ip-acl=127.0.0.1 auth-anonymous=1" --exit-idle-time=-1

# load module now (if it errors, check you gave Termux:API mic permission and restart Termux)
pactl load-module module-sles-source
# confirm source exists
pactl list short sources

# Start proot-distro
proot-distro login ubuntu
```

#### Proot-distro (Ubuntu)

```bash
apt install libasound2-dev portaudio19-dev pulseaudio
```

### Create `zrb_init.py`

```python
import os
from zrb.builtin import llm_ask
from zrb import llm_config
from zrb_extras.llm.tool import create_listen_tool, create_speak_tool

API_KEY = os.getenv("GOOGLE_API_KEY", "")

llm_ask.add_tool(
    create_speak_tool(
        api_key=API_KEY,  # Optional, by default taken from GEMINI_API_KEY or GOOOGLE_API_KEY
        stt_model="gemini-2.5-flash-preview-tts",  # Optional
        voice_name="Sulafat",  # Optional (https://ai.google.dev/gemini-api/docs/speech-generation#voices)
        sample_rate_out=24000,  # Optional
    )
)
llm_ask.add_tool(
    create_listen_tool(
        api_key=API_KEY,  # Optional, by default taken from GEMINI_API_KEY or GOOOGLE_API_KEY
        tts_model="gemini-2.5-flash",  # Optional
        sample_rate=16000,  # Optional
        channels=1,  # Optional
        silence_threshold=0.01,  # Optional (smaller means more sensitive)
        max_silence=4.0,  # Optional (4 second silence before stop listening)
    )
)

# Optional: allow LLM to speak or listen without asking for user approval
if not llm_config.default_yolo_mode:
    llm_config.set_default_yolo_mode(["speak", "listen"])
```


# For maintainers

## Publish to pypi

To publish zrb-extras, you need to have a `Pypi` account:

- Log in or register to [https://pypi.org/](https://pypi.org/)
- Create an API token

You can also create a `TestPypi` account:

- Log in or register to [https://test.pypi.org/](https://test.pypi.org/)
- Create an API token

Once you have your API token, you need to configure poetry:

```
poetry config pypi-token.pypi <your-api-token>
```

To publish zrb-extras, you can do the following command:

```bash
poetry publish --build
```

## Updating version

You can update zrb-extras version by modifying the following section in `pyproject.toml`:

```toml
[project]
version = "0.0.2"
```

## Adding dependencies

To add zrb-extras dependencies, you can edit the following section in `pyproject.toml`:

```toml
[project]
dependencies = [
    "Jinja2==3.1.2",
    "jsons==1.6.3"
]
```

## Adding script

To make zrb-extras executable, you can edit the following section in `pyproject.toml`:

```toml
[project-scripts]
zrb-extras-hello = "zrb_extras.__main__:hello"
```

Now, whenever you run `zrb-extras-hello`, the `main` function on your `__main__.py` will be executed.

