Metadata-Version: 2.4
Name: zijus-tools
Version: 0.0.2
Summary: Framework-agnostic UI tools for LLM Agents to send rich WebSocket messages to Zijus Chat UI.
Author-email: Zijus <hello@zijus.com>
License: MIT
Project-URL: Homepage, https://www.zijus.com/zijus-chat-ui
Project-URL: Repository, https://github.com/zijus/zijus-tools
Project-URL: Bug Tracker, https://github.com/zijus/zijus-tools/issues
Keywords: llm,agents,ui,websockets,chat,agno,autogen,google-adk
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: integrations
Requires-Dist: slack_sdk>=3.41.0; extra == "integrations"
Requires-Dist: requests>=2.33.1; extra == "integrations"
Dynamic: license-file

# 🛠️ Zijus Tools

**Zijus Tools** is a Python library containing pre-built, framework-agnostic tools for LLM Agents. It enables agents to send rich, interactive UI components directly to your frontend over WebSockets, as well as perform common external integrations (like Web Search, Slack, and Telegram).

Designed to work seamlessly with **any** Agentic Framework—including **Agno, AutoGen, Microsoft Agent Framework, Google Agent Development Kit (ADK), LangChain,** and more—alongside the **Zijus Chat UI**. This library abstracts away the complexity of WebSocket context management, allowing your LLM agents to render dynamic interfaces with a single function call.

---

## 🔗 Important Links

To get the most out of `zijus-tools`, you will need the frontend client:
* 🖥️ **[Zijus Chat UI GitHub Repo](https://github.com/zijus/zijus-chat-ui)** - See examples of how to integrate the Zijus Chat Client with various Agentic frameworks.
* 🎨 **[Zijus Chat UI Customization](https://www.zijus.com/zijus-chat-ui)** - Learn how to style, theme, and customize the frontend client.

---

## 📦 Installation

To install the core UI tools:
```bash
pip install zijus-tools
```

If you plan to use the third-party integrations (Slack, Telegram), you can install the optional dependencies:
```bash
pip install zijus-tools[integrations]
# Or manually: pip install slack_sdk requests
```

*(Note: Requires Python 3.8+)*

---

## 🚀 Quick Start

Using `zijus-tools` is a simple two-step process:
1. Register your WebSocket sender in your server app (FastAPI, Django, etc.).
2. Provide the tools to your chosen LLM Agent framework.

### Step 1: Configure the Server
Because `zijus-tools` is web-framework-agnostic, you just need to tell it *how* to send JSON messages. We use Python's built-in `contextvars` to ensure thread-safe message delivery for concurrent users.

```python
# main.py (Example using FastAPI)
from fastapi import FastAPI, WebSocket
from zijus_tools import set_websocket_sender # 1. Import the setup function

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    # 2. Define a simple async wrapper that sends a dict over the websocket
    async def sender(msg: dict):
        await websocket.send_json(msg)

    # 3. Inject the sender for this specific user's connection
    set_websocket_sender(sender)

    # ... initialize and run your Agent (Agno, AutoGen, ADK, etc.) ...
    while True:
        data = await websocket.receive_text()
        # Handle incoming data...
```

### Step 2: Add Tools to your Agent
Because Zijus Tools are standard Python asynchronous functions, you can pass them as tools to **any** agent framework. The tool automatically handles formatting the UI payload and emitting the message behind the scenes!

**Example: Google ADK**
```python
from google.adk.agents import LlmAgent
from zijus_tools import SendSlots 

agent = LlmAgent(
    name="root_agent",
    tools=[SendSlots],  # Just drop it in the tools list
    model="gemini-2.5-flash",
    instruction="Whenever the user asks for options, use the SendSlots tool."
)
```

---

## 🧰 Available Tools

### 🎨 UI Components
These tools broadcast JSON payloads to your frontend UI via the configured WebSocket sender.

#### `SendSlots`
Sends a list of selectable slots (buttons or checkboxes). Perfect for multiple-choice selections, filtering, or guiding the user.
* **`slots`** *(Any)*: A list, comma-separated string, or JSON string of options.
* **`content`** *(str, optional)*: Text to display above the slots.
* **`checkbox`** *(bool, optional)*: If `True`, renders multi-select checkboxes. Defaults to `False`.
* **`delay`** *(float, optional)*: Delay rendering to match natural chat cadence.

#### `SendMCQ`
Builds and broadcasts a robust Multiple-Choice Question block, supporting data shuffling.
* **`content`** *(str)*: The question to display above the options.
* **`options`** *(List)*: A list of string options or label/value dictionaries.
* **`randomize`** *(bool, optional)*: Shuffles the options if `True`.
* **`checkbox`** *(bool, optional)*: Allows multiple selections if `True`.
* **`delay`** *(float, optional)*: Broadcast delay.

#### `SendSlider`
Renders an interactive numeric slider component for the user to select a value within a range.
* **`min_value`** *(int)*: The minimum integer value.
* **`max_value`** *(int)*: The maximum integer value.
* **`default_value`** *(int)*: The starting position of the slider.
* **`content`** *(str, optional)*: Accompanying text message.
* **`delay`** *(float, optional)*: Broadcast delay.

#### `SendDatePicker`
Displays a calendar or time picker interface for the user to select dates.
* **`type`** *(str, optional)*: `"date"`, `"time"`, or `"datetime"`.
* **`min_date`** *(str, optional)*: Minimum selectable ISO date.
* **`max_date`** *(str, optional)*: Maximum selectable ISO date.
* **`content`** *(str, optional)*: Accompanying text message.
* **`response_format`** *(str, optional)*: Desired standard date formatting (e.g., `"%d/%m/%Y"`).
* **`delay`** *(float, optional)*: Broadcast delay.

#### `SendLockMessage`
Sends a lock signal to the client to disable the chat typing area. Useful for preventing interruptions while the agent is processing complex, multi-step actions or when you want to take some input from the user via a form
* **`reason`** *(str, optional)*: A short message explaining why the UI is locked (e.g., "Processing data...").
* **`delay`** *(float, optional)*: Broadcast delay.

#### `SendTextMessage`
Sends a standard distinct text message bubble to the user interface.
* **`message`** *(str)*: The text content to display.
* **`delay`** *(float, optional)*: Broadcast delay.


### 🌍 Integrations & Utilities
These tools perform external network requests to expand your Agent's capabilities.

#### `WebSearchWithSerperDev`
Allows the agent to search the live web for up-to-date information. *(Requires `WEBSEARCH_API_KEY` to be set in the environment).*
* **`query`** *(str)*: The search term.
* **`number_of_pages`** *(int, optional)*: Maximum results to return (default 5).
* **`country_code`** *(str, optional)*: Two-letter country code for localization (e.g., "us").

#### `SlackMessenger`
Posts a message directly into a Slack channel. *(Requires `slack_sdk`)*.
* **`slack_bot_token`** *(str)*: Your Slack bot application token.
* **`channel_id`** *(str)*: The target Slack channel ID.
* **`message`** *(str)*: The message to send.

#### `SendTelegramMessage`
Sends a Markdown-formatted message via a Telegram bot. *(Requires `requests`)*.
* **`markdown_message`** *(str)*: The content of the message.
* **`bot_token`** *(str)*: Your Telegram bot token.
* **`chat_id`** *(str)*: The target chat or channel ID.

--- 

## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request if you have a new tool you'd like to add. Ensure that your UI tools rely on `emit_message()` from `zijus_tools.context` to remain framework-agnostic.

## 📄 License
This project is open-sourced under the MIT License.
