zijus-tools 0.0.2

Framework-agnostic UI tools for LLM Agents to send rich WebSocket messages to Zijus Chat UI.

🛠️ 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 - See examples of how to integrate the Zijus Chat Client with various Agentic frameworks.
• 🎨 Zijus Chat UI Customization - Learn how to style, theme, and customize the frontend client.

---

📦 Installation

To install the core UI tools:

pip install zijus-tools

If you plan to use the third-party integrations (Slack, Telegram), you can install the optional dependencies:

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.

# 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

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.