Trisul AI CLI

Conversational AI for Next-Generation Network Monitoring

Overview

Trisul AI CLI is a conversational AI interface for Trisul Network Analytics 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)

Setup

1. Update system and install dependencies (Debian/Ubuntu):

   sudo apt update && sudo apt install python3-pip python3.12-venv -y
   

2. Create and activate virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install Trisul AI CLI:

   pip install trisul_ai_cli
   

4. Launch the CLI:

   trisul_ai_cli
   

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

Usage

Basic Queries

👤 (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        |
...
+---------------------+----------------+

👤 (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]

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

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

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

👤 (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)

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).

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).

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:

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

Error: ZMQ timeout - no response from ipc://...

Solution: Verify Trisul Network Analytics is running and the context exists.

API Key Issues

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
• Issues: GitHub Issues

Trisul AI CLI - Because your network should talk back.

Built with care and precision 🔬 by Unleash Networks