README.md

metadata

title: Network State Assistant
emoji: 🌐
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false

Network State Assistant — demo

Text-to-SQL chatbot over a simulated network state database. Ask questions in plain English about device status, traffic, alerts, and performance.

All files sit in one flat directory — no subfolders — so this uploads cleanly to a Hugging Face Space via drag-and-drop with no folder handling.

What's in here

schema.sql          table DDL (devices, interfaces, traffic_flows, alerts, metrics_timeseries)
seed_from_csv.py     seeds network.db — synthetic data by default, or a real NetFlow CSV
network.db           the seeded SQLite database (commit this so data exists on boot)
prompt_template.py   schema context + few-shot examples for the text-to-SQL prompt
infer.py             llama-cpp-python wrapper around a small GGUF model (Qwen2.5-3B-Instruct)
guardrail.py         validates generated SQL is a safe, whitelisted SELECT before it runs
simulator.py         background thread that inserts new rows to fake a live feed
app.py               Gradio chat app tying it all together
requirements.txt     gradio, llama-cpp-python

Run locally

pip install -r requirements.txt
python seed_from_csv.py      # creates network.db with synthetic data
python app.py

First run downloads the quantized model from the Hugging Face Hub (a few GB) and caches it — expect the first question to be slow, subsequent ones fast.

To seed from a real NetFlow dataset instead of synthetic data (e.g. NF-UNSW-NB15-v2 from https://staff.itee.uq.edu.au/marius/NIDS_datasets/):

python seed_from_csv.py --csv path/to/nf_unsw_nb15_v2.csv --limit 20000

Deploy to Hugging Face Spaces

1. Create a new Space → SDK: Gradio, hardware: CPU basic.
2. On the Space's Files tab → Add file → Upload files, drag in every file listed above — they're all flat, no folders to worry about.
3. Commit. The Space builds automatically from app.py + requirements.txt.
4. The model downloads from the Hub on first launch via Llama.from_pretrained(...) in infer.py — no manual upload needed.

Swapping the model

infer.py reads MODEL_REPO / MODEL_FILE from environment variables (set them in the Space's settings), defaulting to:

• Qwen/Qwen2.5-3B-Instruct-GGUF, qwen2.5-3b-instruct-q4_k_m.gguf

If the 3B model feels slow on the free CPU tier, drop to Qwen/Qwen2.5-1.5B-Instruct-GGUF — noticeably faster, somewhat weaker on complex joins/aggregations.

Safety notes (demo-grade, not production)

• The DB connection in app.py opens SQLite in read-only URI mode (mode=ro) as a second line of defense behind the guardrail.
• guardrail.py rejects anything that isn't a single whitelisted-table SELECT statement — no INSERT/UPDATE/DELETE/DROP/etc., no multiple statements.
• This is enough for a live demo. Before any production use: move to Postgres with a dedicated read-only role, add query timeouts, and add logging/eval on generated SQL accuracy.

Example questions

• "Which devices are currently down?"
• "What are the top 5 talkers by bandwidth in the last hour?"
• "Any unresolved critical alerts right now?"
• "Which interfaces have packet loss above 2% right now?"
• "How many devices are in a degraded state right now?"
• "List all alerts on the core switch in the last 24 hours"
• "Show total traffic volume by protocol today"