NetAssist AI

Agentic Telecom Incident Resolution Copilot

NetAssist AI is an independent telecom-support prototype developed for The Talent Hack. It analyzes customer complaints, runs simulated diagnostic checks, retrieves relevant support knowledge, produces grounded responses with citations, and creates a structured human-support ticket when escalation is required.

This is not an official Deutsche Telekom product. All customer identifiers, outages, diagnostics, and support documents used in the prototype are synthetic.

Live Demo

Streamlit: https://netassist-ai.streamlit.app/

The public demo runs in a quota-safe mode. Local development can run either with Gemini and vector retrieval or in a fully offline fallback mode.

---

Problem

Telecom support teams receive large numbers of vague or incomplete complaints such as:

“My internet is not working and the DSL light keeps blinking.”

A basic chatbot may respond with generic troubleshooting steps without checking whether:

• a regional outage is active,
• the customer line has lost signal,
• the account is restricted,
• the complaint is missing critical information,
• or human intervention is required.

This can lead to repeated troubleshooting, unnecessary router resets, inconsistent responses, and poor escalation quality.

Solution

NetAssist AI combines:

• LLM-based incident understanding,
• deterministic telecom diagnostic tools,
• Retrieval-Augmented Generation,
• LangGraph workflow orchestration,
• grounded answers with evidence references,
• clarification routing,
• human escalation,
• structured ticket generation,
• privacy-aware masking,
• local usage telemetry,
• and offline fallback behavior.

The system does not diagnose from free text alone. It combines the complaint with diagnostic evidence and retrieved knowledge before generating a response.

---

Workflow

flowchart TD
    A[Customer Complaint] --> B[Intake / Structured Extraction]
    B --> C{Enough Information?}

    C -- No --> D[Clarification Question]
    D --> Z[End]

    C -- Yes --> E[Diagnostic Tools]
    E --> E1[Regional Outage Check]
    E --> E2[Line Test]
    E --> E3[Account Status Check]

    E1 --> F[Knowledge Retrieval]
    E2 --> F
    E3 --> F

    F --> G[Grounded RAG Answer]
    G --> H{Human Escalation Required?}

    H -- No --> I[Complete]
    H -- Yes --> J[Structured Support Ticket]
    J --> K[Human Support Handoff]

Loading

Main LangGraph execution paths

Clarification path

intake → clarification

Successful completion path

intake → diagnostics → grounded_answer → complete

Escalation path

intake → diagnostics → grounded_answer → escalation

---

Main Features

AI intake

The customer can write a complaint in natural language. The system extracts structured information such as:

• detected language,
• service type,
• issue category,
• router-light state,
• reported duration,
• symptoms,
• confidence,
• and whether clarification is required.

Simulated diagnostic tools

The backend contains deterministic mock tools for:

• regional outage checks,
• line tests,
• account and activation status.

These tools simulate production integrations without using real customer or operator systems.

Retrieval-Augmented Generation

Synthetic telecom support articles are:

1. loaded from Markdown files,
2. split into chunks,
3. converted into embeddings,
4. stored in Chroma,
5. retrieved according to semantic similarity.

Grounded responses

Generated answers are based only on:

• current diagnostic evidence,
• and retrieved support documents.

The system uses evidence markers such as:

[D1] Current diagnostic tool results
[S1] Retrieved support article

Unavailable or invented citation IDs are rejected.

Clarification routing

When the complaint is too vague, the workflow stops before diagnostics and asks a concise follow-up question in the customer’s language.

Example:

Does the problem affect DSL, fiber or mobile service,
and is the connection unavailable, slow or unstable?

Structured escalation

When human support is required, the workflow creates a ticket containing:

• masked customer identifier,
• incident and workflow IDs,
• detected service,
• probable cause,
• priority,
• completed checks,
• evidence sources,
• escalation reason,
• recommended support team,
• and a handoff summary.

Privacy-aware handling

• Synthetic identifiers are used in demos.
• Customer IDs are masked in support tickets.
• Real personal information should not be entered.
• API keys are loaded through environment variables and are excluded from Git.

Offline fallback mode

If Gemini, embeddings, internet access, or API quota is unavailable, the system can continue with:

• local rule-based incident extraction,
• keyword-based document retrieval,
• deterministic support responses,
• and the same LangGraph routing and ticket workflow.

---

Technology Stack

Area	Technology
Language	Python 3.12
Backend API	FastAPI
User Interface	Streamlit
LLM	Google Gemini
Structured Output	Pydantic
Agent Orchestration	LangGraph
RAG Components	LangChain
Vector Database	Chroma
Embeddings	Gemini Embeddings
Testing	Pytest
Version Control	Git and GitHub
Deployment	Streamlit Community Cloud

---

Project Structure

netassist-ai/
│
├── app/
│   ├── main.py
│   ├── models.py
│   ├── config.py
│   │
│   ├── services/
│   │   ├── diagnostic_service.py
│   │   ├── fallback_service.py
│   │   ├── gemini_service.py
│   │   ├── mock_telecom.py
│   │   ├── rag_answer_service.py
│   │   ├── rag_service.py
│   │   ├── ticket_service.py
│   │   └── usage_tracker.py
│   │
│   └── workflows/
│       └── incident_graph.py
│
├── data/
│   └── knowledge/
│
├── frontend/
│   ├── langgraph_app.py
│   └── streamlit_app.py
│
├── scripts/
│   ├── build_knowledge_base.py
│   ├── reset_usage.py
│   └── seed_knowledge_docs.py
│
├── tests/
├── .env.example
├── .gitignore
├── pytest.ini
├── requirements.txt
└── README.md

---

Local Setup

1. Clone the repository

git clone <YOUR_REPOSITORY_URL>
cd netassist-ai

2. Create a virtual environment

Windows PowerShell:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

4. Create the environment file

Copy .env.example to .env:

Copy-Item .env.example .env

For full AI mode:

GEMINI_API_KEY=YOUR_API_KEY
GEMINI_MODEL=gemini-3.1-flash-lite
EMBEDDING_MODEL=gemini-embedding-2

CHROMA_DIRECTORY=chroma_db
KNOWLEDGE_DIRECTORY=data/knowledge

AI_MODE=auto
EXECUTION_MODE=api
API_BASE_URL=http://127.0.0.1:8000
MAX_WORKFLOW_RUNS_PER_SESSION=5

For fully offline mode:

GEMINI_API_KEY=
AI_MODE=offline
EXECUTION_MODE=direct
MAX_WORKFLOW_RUNS_PER_SESSION=5

Never commit the .env file.

---

Running the Application

Option A — Local FastAPI architecture

Terminal 1:

fastapi dev app/main.py

Terminal 2:

streamlit run frontend/langgraph_app.py

Open:

http://localhost:8501

FastAPI documentation:

http://127.0.0.1:8000/docs

Option B — Direct Streamlit mode

This mode runs the LangGraph workflow inside the Streamlit process and does not require a separate FastAPI server.

Set:

EXECUTION_MODE=direct

Then run:

streamlit run frontend/langgraph_app.py

---

Knowledge Base

Create the synthetic support articles:

python -m scripts.seed_knowledge_docs

Build the Chroma vector database:

python -m scripts.build_knowledge_base

The knowledge base contains synthetic articles for scenarios such as:

• blinking DSL light,
• complete internet loss,
• slow connections,
• fiber signal loss,
• mobile-data failure,
• account activation,
• regional outages,
• and human escalation.

---

Demo Scenarios

1. Regional outage

Customer ID: CUSTOMER123
Location: Berlin-Mitte

My home internet is unavailable and the DSL light is blinking.

Expected behavior:

• regional outage is identified,
• repeated router restarts are not recommended,
• outage guidance is shown.

2. Line signal loss

Customer ID: CUSTOMER127
Location: Munich

My DSL connection is completely unavailable and the DSL light keeps blinking.

Expected behavior:

• failed line test,
• grounded DSL troubleshooting,
• human escalation,
• structured fixed-network support ticket.

3. Degraded connection

Customer ID: CUSTOMER125
Location: Munich

My DSL internet is extremely slow.

Expected behavior:

• degraded line quality,
• performance troubleshooting guidance.

4. Account restriction

Customer ID: CUSTOMER129
Location: Munich

My mobile data is not working.

Expected behavior:

• account or activation restriction,
• routing to billing or activation support,
• no unnecessary router replacement recommendation.

5. Clarification

İnternet kötü.

Expected behavior:

• diagnostics do not run,
• RAG does not run,
• the system asks for missing service and symptom information.

---

Testing

Run all tests without making live Gemini calls:

python -m pytest -q

The test suite covers:

• local fallback extraction,
• Turkish duration extraction,
• keyword retrieval,
• clarification routing,
• escalation routing,
• support-ticket generation,
• customer-ID masking,
• and local usage telemetry.

---

Reliability and Safety

NetAssist AI includes:

• Pydantic input and output validation,
• low-temperature structured generation,
• evidence-ID validation,
• prompt-injection resistance instructions,
• deterministic diagnostic tools,
• clarification before uncertain diagnosis,
• human escalation for risky or unresolved cases,
• local fallback behavior,
• session-based demo limits,
• masked identifiers,
• and synthetic data only.

---

Usage and Cost Control

The project includes local telemetry for:

• generation-call count,
• prompt tokens,
• output tokens,
• total tokens,
• and embedding operations.

This telemetry is for local development only. It is not an invoice or authoritative billing record.

The public demo is configured to avoid uncontrolled paid usage. Offline mode does not call Gemini or embedding APIs.

---

Limitations

This project is a hackathon prototype, not a production telecom platform.

Current limitations include:

• mock diagnostic and account APIs,
• synthetic support documents,
• no real telecom-network integration,
• rule-based offline language detection,
• no persistent customer conversation history,
• no authentication or authorization layer,
• and no production observability platform.

---

Production Evolution

A production version could add:

• authenticated operator APIs,
• real outage and network telemetry,
• persistent workflow checkpoints,
• role-based access control,
• multilingual evaluation datasets,
• centralized monitoring,
• response-quality evaluation,
• rate limiting,
• Redis-backed session state,
• human approval controls,
• and containerized cloud deployment.

---

Disclaimer

NetAssist AI is an independent prototype created for a hackathon. It is not affiliated with, endorsed by, or deployed by Deutsche Telekom. No real customer data or real telecom-network data is used.