A multi-agent, retrieval-augmented (RAG) tutor for networking, IoT, Linux, and subnetting.
Ask a networking question → NetTutor retrieves the relevant chunks from your own PDF notes, reasons over them step by step, and returns a grounded explanation plus three practice quiz questions. It also tracks weak topics, scores quizzes, and ships deterministic tools for subnetting math, packet-flow tracing, and Linux command help.
Students learning networking juggle scattered material — lecture PDFs, lab reports, cheat sheets, man pages. Subnetting, TCP/IP, routing, STP, Linux networking commands, and IoT protocols like MQTT are hard to self-quiz on, and generic chatbots hallucinate addresses and command flags. NetTutor AI grounds every answer in trusted, user-supplied notes, falls back to exact deterministic math for subnetting/packet questions, and turns each answer into adaptive practice.
User Interface (Streamlit) / REST API (FastAPI)
|
v
Question Classifier Agent
|
v
Retriever Agent ──► ChromaDB Vector DB ──► PDF notes / lab reports
|
+---------------+----------------+
| |
v v
Reasoning Agent Debug Agent (deterministic tools)
(grounded step-by-step answer) subnet solver · packet-flow · Linux cmds
| |
+---------------+----------------+
v
Quiz Agent + Feedback Agent
|
v
Final answer · 3 practice questions · score · weak-topic tracking
The agents are wired together with a LangGraph state machine
(classify → retrieve → reason|debug → quiz → end). Student history, quiz scores, and
weak topics persist in SQLite.
Every external dependency has a built-in fallback so the project runs end-to-end with zero API keys and no model downloads, then transparently upgrades to the production stack when those are available:
| Layer | Production | Offline fallback |
|---|---|---|
| Embeddings | sentence-transformers (MiniLM) |
deterministic hashing embedder (stdlib) |
| Reasoning | Anthropic Claude (claude-sonnet-4-6) |
template reasoner over retrieved context |
| Workflow | LangGraph StateGraph |
equivalent plain-Python graph |
Selection is automatic at startup; the tools (subnet/packet/Linux) are always exact.
- RAG question answering grounded in your PDF notes, with source + page citations.
- Multi-agent workflow — Classifier, Retriever, Reasoning, Quiz, Feedback, Debug.
- Subnetting solver — network/broadcast/usable range, CIDR, masks, host counts,
/30–/32edge cases, and subnet planning by host count. - Packet-flow explainer — same-subnet vs. cross-subnet ARP/switching/routing steps with encapsulation layers.
- Linux command explainer —
ping,traceroute,ip,route,netstat,ss,tcpdump,scp,nslookup,dig. - Adaptive quizzes — one easy, one medium, one applied/lab-style question per answer, auto-scored.
- Weak-topic tracker + dashboard — per-student progress, scores, and recommended next topic, persisted in SQLite.
- Evaluation harness — fixed question set measuring retrieval accuracy, topic routing, quiz quality, and latency.
Python 3.12 · FastAPI · LangGraph · ChromaDB · Sentence-Transformers · Anthropic API · SQLite · Streamlit · PyPDF · pytest.
# 1. Clone and enter the project
git clone <your-repo-url> nettutor-ai
cd nettutor-ai
# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. (Optional) configure secrets / models
cp .env.example .env # add ANTHROPIC_API_KEY for LLM answersNo key and no model download? It still works — NetTutor falls back to the offline hashing embedder and template reasoner so you can demo immediately.
Drop any networking / IoT / Linux PDFs into:
data/raw_pdfs/
The repo ships with five sample note sets (subnetting, TCP/IP, routing & switching,
Linux networking, MQTT/IoT) so it works out of the box. Regenerate them anytime with
python scripts/make_sample_notes.py.
python -m app.ingest --reset # chunk + embed + store every PDF in ChromaDB
# or: ./run.sh ingestThis extracts text, cleans and chunks it, detects each chunk's topic, embeds it, and
upserts into ChromaDB with {source, page, topic, chunk} metadata.
REST API
uvicorn app.main:app --reload # or: ./run.sh apicurl -s -X POST localhost:8000/chat \
-H 'Content-Type: application/json' \
-d '{"student_id":"alice","question":"How many usable hosts in a /26?"}'Other endpoints: POST /quiz/generate, POST /quiz/grade, POST /upload,
POST /ingest, GET /progress/{student_id}, POST /tools/subnet,
POST /tools/command, POST /tools/packet-flow.
Streamlit UI
streamlit run frontend/streamlit_app.py # or: ./run.sh uiTabs: Ask · Quiz · Tools · Dashboard · Upload.
Python
from app.graph import run_tutor
out = run_tutor("What is the broadcast address of 192.168.1.0/24?")
print(out["answer"], out["sources"])Add screenshots under
docs/and reference them here, e.g.·. The Streamlit UI exposes Ask / Quiz / Tools / Dashboard / Upload tabs.
Run the harness:
python -m scripts.evaluate # or: ./run.sh eval
python -m scripts.evaluate --k 5 --json data/eval_results.jsonIt scores the fixed set in data/eval_questions.json (59 questions across subnetting,
TCP/IP, routing, Linux, STP, MQTT/IoT, ARP, and packet flow). Measured on the offline
hashing embedder (no model download, worst-case baseline):
| Metric | Result |
|---|---|
| Retrieval accuracy@5 | 88.1 % |
| Quiz quality (3 Qs, easy/med/applied) | 100 % |
| Topic-routing accuracy | 57.6 % |
| Latency (avg) | ~0.015 s |
The deterministic tools (subnet/packet/Linux) are 100 % accurate and unit-tested.
Topic routing is the metric most sensitive to embedding quality — swapping in
sentence-transformers (set FORCE_FALLBACK_EMBEDDINGS=false and install the package)
raises semantic separation between lexically similar topics (e.g. STP vs. Linux) well
above the hashing baseline. All 31 unit tests pass (pytest).
nettutor-ai/
├── app/
│ ├── main.py # FastAPI app + endpoints
│ ├── config.py # env-driven settings
│ ├── embeddings.py # sentence-transformer + hashing fallback
│ ├── llm.py # Anthropic + template fallback
│ ├── ingest.py # PDF → chunk → embed → ChromaDB
│ ├── retriever.py # similarity search + citations
│ ├── prompts.py # agent prompts
│ ├── agents.py # Classifier/Retriever/Reasoning/Quiz/Debug agents
│ ├── graph.py # LangGraph workflow (+ fallback graph)
│ ├── quiz.py # quiz generation + scoring
│ ├── feedback.py # scoring, weak-topic tracking, recommendations
│ ├── database.py # SQLite persistence
│ └── tools/ # subnet · linux_commands · packet_flow
├── data/
│ ├── raw_pdfs/ # your notes (5 samples included)
│ ├── processed_chunks/
│ └── eval_questions.json
├── vector_db/chroma/ # ChromaDB store (generated)
├── notebooks/rag_experiments.ipynb
├── tests/ # test_subnet · test_retriever · test_quiz
├── scripts/ # make_sample_notes.py · evaluate.py
├── frontend/streamlit_app.py
├── requirements.txt · Dockerfile · docker-compose.yml · .env.example · run.sh
docker compose up --build # API on :8000, Streamlit UI on :8501
# pass your key: ANTHROPIC_API_KEY=sk-... docker compose up --buildpytest -q # or: ./run.sh test- Adaptive quiz engine that shifts difficulty from live performance.
- CloudLab lab-helper agent that walks students through uploaded lab PDFs.
- Reranking + hybrid (keyword + vector) retrieval for tougher queries.
- Voice input/output for hands-free tutoring.
- Faithfulness scoring via LLM-as-judge in the eval harness.
- Postgres + auth for multi-user classroom deployment.
- Developed NetTutor AI, a multi-agent RAG technical tutor for networking and IoT using LangGraph, ChromaDB, FastAPI, and transformer-based language models.
- Designed specialized agents for retrieval, reasoning, quiz generation, and feedback to support adaptive learning across subnetting, TCP/IP, Linux commands, routing, and IoT protocols.
- Built a vector knowledge base from PDF notes and lab reports, enabling context-grounded question answering with source-aware retrieval and citations.
- Implemented evaluation workflows measuring retrieval accuracy, answer faithfulness, quiz quality, and response latency, plus a graceful-degradation architecture that runs fully offline or on a production LLM/embedding stack.