README.md

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

```bash
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/):

```bash
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"