Metadata-Version: 2.4
Name: trisul_ai_cli
Version: 1.0.0
Summary: Trisul AI CLI that starts a local MCP server and a client.
Author: Parthasarathy B
Author-email: partha@unleashnetworks.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: nest_asyncio
Requires-Dist: mcp
Requires-Dist: chromadb
Requires-Dist: pyzmq
Requires-Dist: protobuf
Requires-Dist: matplotlib
Requires-Dist: python-dotenv
Requires-Dist: reportlab
Requires-Dist: openpyxl
Requires-Dist: stdiomask
Requires-Dist: langchain>=1.1
Requires-Dist: langchain-core>=1.1.2
Requires-Dist: langchain-google-genai>=4.0.0
Requires-Dist: langchain-openai>=1.0
Requires-Dist: langchain-anthropic>=1.0
Requires-Dist: langchain-voyageai>=0.4.1
Requires-Dist: aiohttp>=3.10
Requires-Dist: voyageai
Requires-Dist: fastapi
Requires-Dist: uvicorn[standard]

# Trisul AI CLI

> Conversational AI for Next-Generation Network Monitoring 

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)


## Overview

Trisul AI CLI is a conversational AI interface for [Trisul Network Analytics](https://www.trisul.org/) that transforms network monitoring from complex dashboards and CLI commands into natural language conversations. Simply ask questions about your network in plain English, and get actionable insights instantly.

**Think ChatGPT, but for your network.**

Instead of navigating through menus, logs, and reports, just ask:
- *"What's the traffic trend on this interface in the last 24 hours?"*
- *"Which ASNs pushed the most traffic this week?"*
- *"Show me top IPs on the Airtel WAN"*

Trisul AI handles data retrieval, analysis, and visualization—returning clear answers, tables, charts, and insights directly in your terminal.

## Key Features

- **Natural Language Queries**: Ask questions in plain English, no need to remember commands or menu paths
- **Intelligent Context**: Remembers conversation history and user preferences
- **Multi-Source Data**: Connects to local or remote Trisul servers via IPC or TCP/ZMQ
- **Rich Visualizations**: Generates tables, charts, and traffic graphs with interactive tooltips
- **RAG-Powered Knowledge**: Uses Retrieval-Augmented Generation with Trisul's complete documentation
- **MCP Server Architecture**: Leverages Model Context Protocol for structured tool execution
- **Real-Time Analytics**: Query live network data, toppers, traffic trends, and anomalies

## Architecture

Trisul AI CLI combines several cutting-edge technologies:

```
┌─────────────────────────────────────────────────────────┐
│                    User Query (NL)                      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Gemini AI (Google LLM)                     │
│        • Query Understanding                            │
│        • Function Calling                               │
│        • Response Generation                            │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│          MCP Server (FastMCP)                           │
│        • Tool Execution Layer                           │
│        • ZMQ Communication                              │
│        • Data Transformation                            │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
        ▼            ▼            ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ Trisul   │  │   RAG    │  │  SQLite  │
│ TRP API  │  │ ChromaDB │  │  Config  │
│ (ZMQ)    │  │ Gemini   │  │   DB     │
└──────────┘  └──────────┘  └──────────┘
```

### Components

- **Gemini AI**: Google's large language model for natural language understanding
- **MCP Server**: Model Context Protocol server with specialized Trisul tools
- **Trisul TRP API**: Low-level network analytics API via ZeroMQ
- **RAG System**: ChromaDB + Gemini embeddings for documentation retrieval
- **Visualization**: Matplotlib for interactive traffic charts

## Installation

### Prerequisites

- Python 3.8 or higher
- Trisul Network Analytics installed and running
- Gemini API key ([Get one here](https://aistudio.google.com/app/api-keys))

### Setup

1. **Update system and install dependencies** (Debian/Ubuntu):
   ```bash
   sudo apt update && sudo apt install python3-pip python3.12-venv -y
   ```

2. **Create and activate virtual environment**:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   ```

3. **Install Trisul AI CLI**:
   ```bash
   pip install trisul_ai_cli
   ```

4. **Launch the CLI**:
   ```bash
   trisul_ai_cli
   ```

5. **Enter your Gemini API key** when prompted (stored securely in `.env`)

## Usage

### Basic Queries

```bash
👤 (You): Show top 10 hosts by traffic in the last hour

🤖 (Bot): Here are the top 10 hosts by traffic:
+---------------------+----------------+
| Host IP             | Traffic (GB)   |
+---------------------+----------------+
| 10.25.30.151        | 2.42 GB        |
| 10.26.12.104        | 1.89 GB        |
| 192.168.1.50        | 1.23 GB        |
...
+---------------------+----------------+
```

```bash
👤 (You): Top 5 IPs in last 10 minutes

🤖 (Bot): Here are the top 5 hosts by traffic:
[Returns formatted table with IPs and traffic volumes]
```


```bash
👤 (You): How much HTTPS traffic did we see today?

🤖 (Bot): Total HTTPS traffic today: 127.45 GB
Upload: 45.23 GB, Download: 82.22 GB
```




### Traffic Charts

```bash
👤 (You): Show HTTPS traffic trend for 192.168.10.25 over last 6 hours with a chart

🤖 (Bot): [Generates interactive matplotlib chart in popup window]

+---------------------+---------------------+----------------------+
| Time (IST)          | HTTPS Total Traffic | HTTPS Upload Traffic |
|---------------------+---------------------+----------------------|
| 2025-01-27 15:00:00 | 5.51 MB             | 4.51 MB              |
| 2025-01-27 15:01:00 | 3.46 MB             | 3.22 MB              |
...
+---------------------+---------------------+----------------------+

Peak traffic occurred at 15:23:00 with 8.91 MB total.
```

### Connecting to Remote Servers

```bash
👤 (You): Connect to the remote server with IP address 10.16.8.44 and port 5008.

🤖 (Bot): OK. I will use the ZMQ endpoint 'tcp://10.16.8.44:5008' for all subsequent queries.

👤 (You): Show top apps by traffic

🤖 (Bot): [Retrieves data from remote server...]
```

### Knowledge Queries

```bash
👤 (You): What is a crosskey counter group?

🤖 (Bot): Crosskey is a feature in Trisul that allows you to combine 
multiple counter groups to create a new composite counter group. For 
example, you can create a crosskey counter group that combines 'Source IP' 
and 'Destination IP' counter groups to track traffic between specific IP pairs...
```

## Available Commands

### MCP Tools (Automatically Called)

| Tool | Purpose |
|------|---------|
| `list_all_available_counter_groups` | List all available counter groups |
| `get_cginfo_from_countergroup_name` | Get counter group details by name |
| `get_counter_group_topper` | Fetch top N items by traffic/metrics |
| `get_key_traffic_data` | Get time-series traffic for specific keys |
| `create_crosskey_counter_group` | Propose, confirm, then create custom multi-dimensional counter groups |
| `create_filter_counter_group` | Propose, confirm, then create filtered counter groups (parent + filter keys) |
| `create_keyset_counter_group` | Propose, confirm, then create keyset counter groups (parent + named key buckets) |
| `list_derived_counter_group_types` | Catalog of crosskey / filter / keyset: when to use, how to create, scenarios, which dashboard module shows them |
| `list_dashboard_module_types` | Browse dashboard module templates and their accepted options |
| `generate_dashboard_json` | Validate against live Trisul, preview, then write an importable dashboard JSON under `/tmp` |
| `rag_query` | Search Trisul documentation and knowledge base |
| `generate_and_show_chart` | Generate interactive traffic visualizations |

#### Filtered counter groups (`create_filter_counter_group`)

Creates a filtered counter group by writing to the Trisul config SQLite DB (same pattern as `create_crosskey_counter_group`). Filter keys are stored in **DB key format** (e.g. `p-0035` for DNS port 53, or `p-0050,p-01BB,p-0019` for multiple ports).

| User provides | Tool behavior |
|---------------|---------------|
| Explicit or partial keys | With `confirm=False`, returns `pending_confirmation` with the complete resolved proposal; no DB write |
| Proposal | Includes arguments/rules, `creation_reason`, and the exact `dashboard_usage` |
| User confirms | Call again with `confirm=True` and identical parameters; returns the created GUID |

Example: Parent=FlowIntfs, Filter=Apps, name=`DNSPorts`, keys=`Port-53` → saved as `FilterKeyList=p-0035`.

#### Keyset counter groups (`create_keyset_counter_group`)

Groups keys from a parent counter group into named buckets (KeysetKey → KeyFrom). Keys in KeyFrom are stored in **DB key format** (e.g. `p-0050,p-01BB,p-1F90`).

| User provides | Tool behavior |
|---------------|---------------|
| Name + parent, explicit keys, or partial keys | With `confirm=False`, returns the complete proposal; no DB write |
| Proposal | Includes resolved KeysetKey/KeyFrom rules, why it is needed, and where the dashboard uses it |
| User confirms | Call again with `confirm=True` and identical parameters; returns the created GUID |

Example: Parent=Apps, name=`P2P Traffic`, keyset_key=`p2ptraffic`, keys_from=`Port-6890,Port-6891,...` → saved as comma-separated `p-XXXX` keys.

#### Derived counter groups catalog (`list_derived_counter_group_types`)

Static catalog (not live inventory) covering **crosskey**, **filter**, and **keyset**: what each is, create-tool arguments and confirm workflow, example scenarios, and which dashboard template receives the created GUID (109/110 for crosskey; ordinary toppers/charts for filter and keyset). Always resolve GUIDs from live `list_all_available_counter_groups` — never copy examples from the catalog.

#### Dashboard JSON generation

Dashboard generation never trusts a static counter-group GUID map. It always sends a
live `COUNTER_GROUP_INFO` request and validates every key with `SEARCH_KEYS`. If the
requested data requires a new crosskey, filter, or keyset group, the assistant first
shows the proposed type, name, arguments/rules, reason, and dashboard module usage.
Creation begins only after explicit confirmation.

Each module also carries an `intent` holding the user's own words for that one panel.
Every catalog template declares the `presentation` it renders (table, time-series chart,
single-value badge, tree, sankey, embedded page, alert feed), and
validation rejects a module whose template contradicts the presentation those words ask
for — so "https traffic chart" cannot be generated as a toppers list. An option the
template does not accept is an error too, and the hint names the templates that do
accept it.

`generate_dashboard_json(confirm=False)` returns a layout preview that states the shape
each panel renders and the words it was built from. After approval,
`generate_dashboard_json(confirm=True)` writes the package to `/tmp` and returns the
complete absolute path including the JSON filename.

### User Commands

- **`exit`** or **`quit`**: Exit the CLI
- **`change_api_key`**: Update your Gemini API key

## Configuration

### Default Context

By default, Trisul AI connects to `context0` (local IPC socket). You can specify:
- **Context name**: `context_XYZ`, `default`, `context0`
- **ZMQ endpoint**: `tcp://<ip>:<port>` for remote servers

### Environment Variables

The CLI stores your API key in `.env`:
```bash
TRISUL_GEMINI_API_KEY=your_api_key_here
```



## Logging

Detailed logs are written to `trisul_ai_cli.log` in the installation directory, including:
- Query history
- Function calls and responses
- Error messages and debugging information

## Troubleshooting

### Connection Issues
```bash
Error: ZMQ timeout - no response from ipc://...
```
**Solution**: Verify Trisul Network Analytics is running and the context exists.

### API Key Issues
```bash
Error: Invalid API key
```
**Solution**: Run `change_api_key` command and enter a valid Gemini API key.

### Empty Responses
If the bot returns empty responses, check:
1. Query clarity (be specific about timeframes and entities)
2. Counter group availability (`list_all_available_counter_groups`)
3. Log file for detailed error messages

## Roadmap

- Support for additional LLMs (Claude, GPT-4, local models)
- PDF report generation
- Multi-user conversation history
- Advanced filtering and correlation queries
- Integration with alerting systems
- Web-based UI alongside CLI



## Acknowledgments

- **Trisul Network Analytics** team for the robust TRP API
- **Google Gemini** for powering the conversational AI
- **Anthropic** for MCP inspiration

## Support

- **Documentation**: [https://www.trisul.org/docs](https://www.trisul.org/docs)
- **Issues**: [GitHub Issues](https://github.com/trisulnsm/trisul-ai-cli/issues)

---

**Trisul AI CLI** - Because your network should talk back.

*Built with care and precision 🔬 by [Unleash Networks](https://www.unleashnetworks.com/)*
