Metadata-Version: 2.4
Name: zijus-tools
Version: 0.0.1
Summary: Framework-agnostic UI tools for LLM Agents to send rich WebSocket messages to Zijus Chat UI.
Author-email: Zijus <hello@zijus.com>
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

# 🛠️ 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.

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

```bash
pip install zijus-tools
```

*(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

We are constantly expanding the library of UI components. 

### `SendSlots`
Sends a list of selectable slots (buttons or checkboxes) to the chat interface. Perfect for multiple-choice questions, filtering, or guiding the user.

**Arguments:**
* `slots` *(Any)*: A list, comma-separated string, or JSON string of options. (e.g., `["Mining", "Cement"]` or `[{"label": "Yes", "value": "1"}]`)
* `content` *(str, optional)*: Text to display above the slots.
* `checkbox` *(bool, optional)*: If `True`, renders as multi-select checkboxes. Defaults to `False` (single-select buttons).
* `delay` *(float, optional)*: Delay rendering to match natural chat cadence.


---

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

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