BGP RAG cloud chatbot — initial commit

README.md

@@ -0,0 +1,154 @@
+# BGP Troubleshooting RAG Chatbot — Cloud Deployment
+
+Domain-specific RAG chatbot for Cisco BGP troubleshooting, deployed on HuggingFace Spaces with Groq cloud LLM inference. No local setup required — visit the URL and start asking questions.
+
+🔗 **Live Demo:** [huggingface.co/spaces/VP21/bgp-rag-groq](https://huggingface.co/spaces/VP21/bgp-rag-groq)  
+📁 **Local Version (nettune):** [github.com/vanip3/bgp-rag-chatbot](https://github.com/vanip3/bgp-rag-chatbot)
+
+---
+
+## Architecture
+
+```
+User (Browser)
+     │
+     ▼
+HuggingFace Spaces
+(Streamlit App — app.py)
+     │
+     ├──► FAISS Vector Store ◄── HuggingFace Embeddings
+     │    (Pre-built index,        (all-MiniLM-L6-v2)
+     │     committed to repo)
+     │
+     ├──► Top-4 Relevant Chunks
+     │
+     ▼
+Groq Cloud API
+(llama-3.1-8b-instant)
+     │
+     ▼
+Answer + Source Documents
+```
+
+The user's question is embedded locally using `all-MiniLM-L6-v2`, compared against the pre-built FAISS index to retrieve the 4 most relevant document chunks, then passed to Llama 3.1 8B via the Groq API for answer generation. Source attribution shows which documents informed each answer.
+
+---
+
+## Local vs Cloud Version Comparison
+
+|                  | Local (Project 2)               | Cloud (This Project)         |
+|------------------|---------------------------------|------------------------------|
+| **LLM**          | nettune (fine-tuned, Ollama)    | Llama 3.1 8B (Groq API)      |
+| **Embeddings**   | all-MiniLM-L6-v2                | all-MiniLM-L6-v2             |
+| **Vector Store** | FAISS (built at runtime)        | FAISS (pre-built index)      |
+| **Access**       | Local only                      | Public URL                   |
+| **Cost**         | Free (local GPU/CPU)            | Free (Groq free tier)        |
+| **Setup needed** | Ollama + model download         | None — visit URL             |
+
+---
+
+## Key Concepts Demonstrated
+
+**RAG pipeline cloud deployment** — the same retrieval-augmented generation pattern from the local version runs on a public URL with zero infrastructure management. HuggingFace Spaces handles the server, networking, and TLS.
+
+**Secure API key management** — `GROQ_API_KEY` is stored in HF Spaces Secrets (encrypted at rest, injected as an environment variable at runtime). It never appears in code or git history. This is the same pattern used in AWS Secrets Manager, GCP Secret Manager, and Azure Key Vault.
+
+**Pre-built vector index strategy** — the FAISS index is built once locally (`python ingest.py`) and committed to the repo as binary files (`faiss_index/index.faiss`, `faiss_index/index.pkl`). The Space loads these files in ~3 seconds instead of spending 3-5 minutes building the index on every cold start — a critical optimization for serverless deployments with CPU limits.
+
+**Cloud LLM inference via Groq API** — Groq's LPU (Language Processing Unit) hardware delivers ~500 tokens/second on Llama 3.1 8B, free tier, no credit card required. The API is OpenAI-compatible, making it a drop-in for any LangChain LLM component.
+
+**Production Streamlit deployment** — explicit API key validation at startup, graceful error messaging for operators who fork without setting secrets, persistent chat history via `st.session_state`, and source document attribution on every response.
+
+---
+
+## Knowledge Base
+
+Six documents indexed from Cisco BGP documentation and production telemetry:
+
+| File | Content |
+|------|---------|
+| `bgp_states_guide.txt` | BGP FSM states (IDLE → ESTABLISHED), causes, and verification commands |
+| `bgp_troubleshooting_guide.txt` | Systematic methodology for session failures, flapping, route issues |
+| `bgp_show_commands.txt` | Complete `show` command reference with output interpretation |
+| `bgp_error_messages.txt` | Syslog message reference with NOTIFICATION error codes and remediation |
+| `bgp_configuration_guide.txt` | iBGP, Route Reflectors, authentication, filtering, timers |
+| `bgp_telemetry_logs.txt` | 30-day production syslog data with incident analysis |
+
+---
+
+## How to Deploy Your Own Copy
+
+1. Fork this repo (or create a new HuggingFace Space and push directly)
+2. Create a new HuggingFace Space — select **Streamlit** as the SDK
+3. Push this repo to the Space:
+   ```bash
+   git remote add space https://huggingface.co/spaces/YOUR-USERNAME/YOUR-SPACE-NAME
+   git push space main
+   ```
+4. In Space Settings → **Variables and Secrets**, add:
+   - **Name:** `GROQ_API_KEY`
+   - **Value:** your key from [console.groq.com](https://console.groq.com)
+5. The Space auto-builds and deploys — your public URL is live in ~2 minutes
+
+---
+
+## Local Development
+
+```bash
+# 1. Clone
+git clone https://github.com/vanip3/bgp-rag-groq
+cd bgp-rag-groq
+
+# 2. Install dependencies
+pip install -r requirements.txt
+
+# 3. Build FAISS index (one-time)
+python ingest.py
+
+# 4. Set API key
+export GROQ_API_KEY=gsk_...         # Linux/macOS
+# or: set GROQ_API_KEY=gsk_...      # Windows CMD
+
+# 5. Run the app
+streamlit run app.py
+```
+
+To verify the RAG chain works before launching the UI:
+```bash
+python rag_chain.py
+```
+
+---
+
+## File Structure
+
+```
+bgp-rag-groq/
+├── app.py                          # Streamlit UI (HF Spaces entry point)
+├── rag_chain.py                    # RAG chain: Groq LLM + FAISS retrieval
+├── ingest.py                       # Build FAISS index (run once locally)
+├── requirements.txt                # Auto-installed by HF Spaces
+├── data/
+│   ├── docs/
+│   │   ├── bgp_states_guide.txt
+│   │   ├── bgp_troubleshooting_guide.txt
+│   │   ├── bgp_show_commands.txt
+│   │   ├── bgp_error_messages.txt
+│   │   └── bgp_configuration_guide.txt
+│   └── telemetry/
+│       └── bgp_telemetry_logs.txt
+└── faiss_index/                    # Pre-built index — committed to repo
+    ├── index.faiss
+    └── index.pkl
+```
+
+---
+
+## Tech Stack
+
+- **[LangChain](https://langchain.com)** — RAG chain orchestration (`RetrievalQA`, `PromptTemplate`)
+- **[Groq API](https://groq.com)** — Cloud LLM inference (`llama-3.1-8b-instant`, free tier)
+- **[HuggingFace Embeddings](https://huggingface.co)** — `sentence-transformers/all-MiniLM-L6-v2` (local, CPU)
+- **[FAISS](https://github.com/facebookresearch/faiss)** — Vector similarity search (Facebook AI Research)
+- **[Streamlit](https://streamlit.io)** — Web UI (auto-detected by HF Spaces)
+- **[HuggingFace Spaces](https://huggingface.co/spaces)** — Free cloud deployment platform

app.py

@@ -0,0 +1,188 @@
+"""
+app.py — BGP Troubleshooting RAG Chatbot (Cloud Edition)
+Deployed on HuggingFace Spaces. Run: streamlit run app.py
+
+HuggingFace Spaces auto-detects app.py and runs it as the entry point.
+The GROQ_API_KEY must be set in Space Settings → Variables and Secrets.
+
+WHY ERROR HANDLING FOR MISSING API KEY MATTERS:
+  In cloud deployments, environment variables are set by operators, not users.
+  If someone forks your Space and forgets to add their GROQ_API_KEY, the app
+  will crash with an ugly traceback. Explicit error handling with st.error()
+  gives them a clear, actionable message instead of a 500 error. This is the
+  difference between a hobby script and a production app.
+"""
+
+import os
+from dotenv import load_dotenv
+load_dotenv()  # loads .env locally; no-op on HF Spaces (key comes from Secrets instead)
+
+import streamlit as st
+from rag_chain import query_bgp, get_chunk_count, get_vectorstore, get_embeddings
+
+# ── Page Configuration ────────────────────────────────────────────────────────
+
+st.set_page_config(
+    page_title="BGP Troubleshooting RAG — Cloud Edition",
+    page_icon="🌐",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+# ── API Key Guard (must be first — stops execution if key missing) ─────────────
+
+if not os.environ.get("GROQ_API_KEY"):
+    st.error(
+        "⚠️ **GROQ_API_KEY not set.**\n\n"
+        "To deploy your own copy:\n"
+        "1. Go to your HuggingFace Space\n"
+        "2. Click **Settings** → **Variables and Secrets**\n"
+        "3. Add a new Secret: `GROQ_API_KEY` = your key from [console.groq.com](https://console.groq.com)\n\n"
+        "For local development: `export GROQ_API_KEY=gsk_...`"
+    )
+    st.stop()  # Halts rendering — nothing below this runs without the key
+
+# ── Session State Initialization ──────────────────────────────────────────────
+
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+if "chain_loaded" not in st.session_state:
+    st.session_state.chain_loaded = False
+
+# ── Example Questions ─────────────────────────────────────────────────────────
+
+EXAMPLE_QUESTIONS = [
+    "Why is my BGP neighbor stuck in IDLE state?",
+    "What does %BGP-5-ADJCHANGE neighbor Down mean?",
+    "How do I verify BGP authentication is working?",
+    "My BGP session keeps flapping — what should I check?",
+    "Based on the telemetry logs, what is the most common failure?",
+]
+
+# ── Sidebar ───────────────────────────────────────────────────────────────────
+
+with st.sidebar:
+    st.title("🌐 BGP RAG Chatbot")
+    st.caption("Cloud Edition")
+
+    # Deployment info
+    st.markdown("### 🚀 Deployment")
+    st.markdown(
+        """
+| Component | Value |
+|-----------|-------|
+| **LLM** | Groq API — llama-3.1-8b-instant |
+| **Embeddings** | all-MiniLM-L6-v2 (Local) |
+| **Vector DB** | FAISS (Pre-built index) |
+| **Hosted on** | HuggingFace Spaces |
+        """
+    )
+
+    # Knowledge base stats
+    st.markdown("### 📚 Knowledge Base")
+    chunk_count = get_chunk_count()
+    if chunk_count > 0:
+        st.success(f"✅ Index loaded — **{chunk_count:,}** chunks")
+    else:
+        st.warning("⚠️ Index not loaded yet")
+
+    st.markdown(
+        """
+**Documents indexed:**
+- bgp_states_guide.txt
+- bgp_troubleshooting_guide.txt
+- bgp_show_commands.txt
+- bgp_error_messages.txt
+- bgp_configuration_guide.txt
+- bgp_telemetry_logs.txt
+        """
+    )
+
+    # Example questions
+    st.markdown("### 💡 Example Questions")
+    st.caption("Click to populate the input")
+
+    for q in EXAMPLE_QUESTIONS:
+        if st.button(q, key=f"example_{q[:20]}", use_container_width=True):
+            st.session_state["pending_question"] = q
+
+    # Footer
+    st.divider()
+    st.caption(
+        "🔗 [Local Version (nettune)](https://github.com/vanip3/bgp-rag-chatbot)  \n"
+        "Powered by [Groq](https://groq.com) · [LangChain](https://langchain.com) · [FAISS](https://github.com/facebookresearch/faiss)"
+    )
+
+    if st.button("🗑️ Clear Chat History", use_container_width=True):
+        st.session_state.messages = []
+        st.rerun()
+
+# ── Main Area ─────────────────────────────────────────────────────────────────
+
+st.title("🌐 BGP Troubleshooting RAG Chatbot")
+st.markdown(
+    "**Powered by Groq (Llama 3.1) + FAISS + Cisco BGP Knowledge Base** "
+    "| Deployed on HuggingFace Spaces  \n"
+    "Ask any BGP troubleshooting question — answers grounded in Cisco documentation and real telemetry logs."
+)
+st.divider()
+
+# Display chat history
+for message in st.session_state.messages:
+    with st.chat_message(message["role"]):
+        st.markdown(message["content"])
+        if message["role"] == "assistant" and "sources" in message:
+            with st.expander("📄 Sources retrieved"):
+                for src in message["sources"]:
+                    st.markdown(f"- `{src}`")
+
+# Handle example question button clicks (populates input via session state)
+pending = st.session_state.pop("pending_question", None)
+
+# Chat input
+user_input = st.chat_input("Ask a BGP troubleshooting question...")
+
+# Use the pending example question if a button was clicked, otherwise use typed input
+question = pending or user_input
+
+if question:
+    # Show user message
+    st.session_state.messages.append({"role": "user", "content": question})
+    with st.chat_message("user"):
+        st.markdown(question)
+
+    # Generate response
+    with st.chat_message("assistant"):
+        with st.spinner("🔍 Searching knowledge base and querying Groq..."):
+            try:
+                result = query_bgp(question)
+                answer = result["answer"]
+                sources = result["sources"]
+
+                st.markdown(answer)
+
+                if sources:
+                    with st.expander("📄 Sources retrieved"):
+                        for src in sources:
+                            st.markdown(f"- `{src}`")
+
+                # Save to history with sources
+                st.session_state.messages.append({
+                    "role": "assistant",
+                    "content": answer,
+                    "sources": sources,
+                })
+
+            except Exception as e:
+                error_msg = f"❌ Error generating response: {str(e)}"
+                st.error(error_msg)
+                st.session_state.messages.append({
+                    "role": "assistant",
+                    "content": error_msg,
+                    "sources": [],
+                })
+
+    # Re-run to clear the pending question state cleanly
+    if pending:
+        st.rerun()

data/docs/bgp_configuration_guide.txt

@@ -0,0 +1,258 @@
+BGP CONFIGURATION GUIDE — CISCO IOS / IOS-XE
+=============================================
+
+BASIC BGP CONFIGURATION
+------------------------
+
+Minimum configuration to start BGP process and establish a peer:
+
+router bgp <local-AS-number>
+ bgp router-id <x.x.x.x>              ! Best practice: always set manually
+ bgp log-neighbor-changes              ! Enable logging of state changes (CRITICAL)
+ !
+ ! eBGP peer (different AS)
+ neighbor <peer-ip> remote-as <peer-AS>
+ neighbor <peer-ip> description <text>
+ !
+ ! Advertise a network
+ network <prefix> mask <subnet-mask>
+
+Verify: show ip bgp summary
+        show bgp neighbors <peer-ip>
+
+
+iBGP CONFIGURATION (SAME AS)
+------------------------------
+
+Key principle: iBGP peers must be fully meshed OR use Route Reflectors / Confederations.
+iBGP does NOT loop prevention via split-horizon: routes learned from iBGP peer
+are not forwarded to another iBGP peer (prevents loops but requires full mesh).
+
+Full mesh iBGP (N routers = N*(N-1)/2 sessions — doesn't scale):
+
+router bgp 65001
+ neighbor 10.0.0.2 remote-as 65001      ! same AS = iBGP
+ neighbor 10.0.0.2 update-source Loopback0  ! use stable source IP
+ neighbor 10.0.0.2 next-hop-self        ! fix next-hop for iBGP
+ !
+ neighbor 10.0.0.3 remote-as 65001
+ neighbor 10.0.0.3 update-source Loopback0
+ neighbor 10.0.0.3 next-hop-self
+
+Important iBGP rules:
+  - Always use loopbacks for iBGP peering (more stable than physical IPs)
+  - Always configure: neighbor <ip> update-source Loopback0
+  - Always configure: neighbor <ip> next-hop-self (especially for eBGP-learned routes)
+  - Ensure loopback reachability via IGP (OSPF/EIGRP)
+
+
+ROUTE REFLECTOR CONFIGURATION
+-------------------------------
+
+Route Reflector eliminates full-mesh iBGP requirement.
+RR reflects iBGP routes to clients — clients only need session to RR.
+
+On Route Reflector:
+router bgp 65001
+ bgp cluster-id 1                      ! Required if multiple RRs in same cluster
+ !
+ neighbor 10.0.1.1 remote-as 65001
+ neighbor 10.0.1.1 route-reflector-client    ! Mark as RR client
+ !
+ neighbor 10.0.1.2 remote-as 65001
+ neighbor 10.0.1.2 route-reflector-client
+ !
+ neighbor 10.0.2.1 remote-as 65001     ! This peer is NOT an RR client
+ ! (peer-to-peer iBGP, e.g., another RR)
+
+On RR Client (standard iBGP config — client doesn't know it's a client):
+router bgp 65001
+ neighbor 10.0.0.1 remote-as 65001     ! Points to RR
+ neighbor 10.0.0.1 update-source Loopback0
+
+Verify: show ip bgp <prefix> — ORIGINATOR_ID and CLUSTER_LIST will be present
+        show bgp neighbors <ip> | include reflector
+
+
+PEER GROUPS (SCALING CONFIGURATION)
+--------------------------------------
+
+Peer groups reduce config duplication and improve performance.
+Peers in a group share policy — UPDATE generation done once for group.
+
+router bgp 65001
+ !
+ neighbor IBGP-PEERS peer-group
+ neighbor IBGP-PEERS remote-as 65001
+ neighbor IBGP-PEERS update-source Loopback0
+ neighbor IBGP-PEERS next-hop-self
+ neighbor IBGP-PEERS soft-reconfiguration inbound
+ !
+ neighbor 10.0.0.2 peer-group IBGP-PEERS
+ neighbor 10.0.0.3 peer-group IBGP-PEERS
+ neighbor 10.0.0.4 peer-group IBGP-PEERS
+
+Verify: show ip bgp peer-group
+
+
+BGP AUTHENTICATION (MD5)
+--------------------------
+
+Configure identical passwords on both sides:
+
+Router A:
+ neighbor 10.1.1.2 password Cisco123!
+
+Router B:
+ neighbor 10.1.1.1 password Cisco123!
+
+Notes:
+  - Password is case-sensitive
+  - No spaces allowed at beginning or end
+  - Hashed in show running-config (type 7 or encrypted)
+  - Session must be reset after adding authentication:
+    clear ip bgp 10.1.1.2
+
+Verify: show bgp neighbors 10.1.1.2 | include password
+        (shows "MD5 is configured" — never shows actual password)
+
+
+INBOUND/OUTBOUND ROUTE FILTERING
+----------------------------------
+
+Method 1: Prefix-list (recommended — most efficient)
+
+ip prefix-list ALLOW-ONLY-DEFAULT permit 0.0.0.0/0
+ip prefix-list ALLOW-ONLY-DEFAULT deny 0.0.0.0/0 le 32
+
+router bgp 65001
+ neighbor <ip> prefix-list ALLOW-ONLY-DEFAULT in
+
+Method 2: Route-map (most flexible)
+
+route-map SET-LOCAL-PREF permit 10
+ match ip address prefix-list CUSTOMER-ROUTES
+ set local-preference 200
+route-map SET-LOCAL-PREF permit 20
+
+router bgp 65001
+ neighbor <ip> route-map SET-LOCAL-PREF in
+
+Method 3: AS-path filter
+
+ip as-path access-list 1 permit ^65100_
+ip as-path access-list 1 deny .*
+
+router bgp 65001
+ neighbor <ip> filter-list 1 in
+
+
+BGP TIMER CONFIGURATION
+-------------------------
+
+Default timers (RFC 4271):
+  Keepalive: 60 seconds
+  Hold time: 180 seconds
+
+Modify timers (both sides should match for predictability):
+ timers bgp <keepalive> <holdtime>
+
+Examples:
+ timers bgp 10 30          ! Fast convergence (test/datacenter)
+ timers bgp 60 180         ! Default (most WAN deployments)
+ timers bgp 0 0            ! Disable hold timer (NOT recommended)
+
+Per-neighbor override:
+ neighbor <ip> timers <keepalive> <holdtime>
+
+Verify: show bgp neighbors <ip> | include Hold|Keepalive
+
+
+BGP GRACEFUL RESTART
+---------------------
+
+Allows BGP to maintain forwarding during a restart event (NSF/NSR).
+
+router bgp 65001
+ bgp graceful-restart
+ bgp graceful-restart restart-time 120    ! Default 120s
+ bgp graceful-restart stalepath-time 360  ! Default 360s
+
+Verify: show bgp neighbors <ip> | include graceful
+
+
+MAXIMUM PREFIX CONFIGURATION
+------------------------------
+
+Protects router from accepting too many routes (route leak protection):
+
+router bgp 65001
+ ! Tear down session if peer sends > 500000 prefixes
+ neighbor <ip> maximum-prefix 500000
+
+ ! Warn at 80% of limit, tear down at 100%
+ neighbor <ip> maximum-prefix 500000 80
+
+ ! Warning only — never tear down session
+ neighbor <ip> maximum-prefix 500000 warning-only
+
+Verify: show bgp neighbors <ip> | include prefix
+
+
+SOFT RECONFIGURATION
+---------------------
+
+Required to use "show ip bgp neighbors <ip> received-routes":
+
+router bgp 65001
+ neighbor <ip> soft-reconfiguration inbound
+
+Note: Stores a copy of all received routes before policy application.
+Uses additional memory. Consider carefully on high-prefix-count sessions.
+
+Alternatively, use Route Refresh (if supported by both peers):
+ clear ip bgp <ip> soft in    ! Requests peer to resend routes
+
+
+WEIGHT, LOCAL-PREFERENCE, MED CONFIGURATION
+---------------------------------------------
+
+WEIGHT (Cisco proprietary — not advertised to peers, local only):
+  route-map SET-WEIGHT permit 10
+   match ip address prefix-list PREFERRED-ROUTES
+   set weight 200
+  router bgp 65001
+   neighbor <ip> route-map SET-WEIGHT in
+
+LOCAL-PREFERENCE (advertised within AS, higher = preferred):
+  route-map SET-LP permit 10
+   set local-preference 150
+  router bgp 65001
+   neighbor <ip> route-map SET-LP in
+
+  Default local-pref: bgp default local-preference <value>  (default 100)
+
+MED (Multi-Exit Discriminator — advertised to external peers, lower = preferred):
+  route-map SET-MED permit 10
+   set metric 100
+  router bgp 65001
+   neighbor <ip> route-map SET-MED out
+
+AS-PATH PREPENDING (make path look longer to influence inbound traffic):
+  route-map PREPEND permit 10
+   set as-path prepend 65001 65001 65001   ! Prepend our ASN 3 times
+  router bgp 65001
+   neighbor <ip> route-map PREPEND out
+
+
+CONFEDERATIONS
+--------------
+
+Alternative to full-mesh iBGP for large AS. Splits AS into sub-ASs.
+Less common than Route Reflectors in modern networks.
+
+router bgp 65100              ! Sub-AS number
+ bgp confederation identifier 65001   ! Public-facing AS number
+ bgp confederation peers 65101 65102  ! Other sub-ASs in confederation
+ !
+ neighbor <ip> remote-as 65101       ! Peer in another sub-AS

data/docs/bgp_error_messages.txt

@@ -0,0 +1,223 @@
+BGP ERROR MESSAGES AND SYSLOG REFERENCE — CISCO IOS
+=====================================================
+
+This guide covers the most common BGP syslog messages, their meaning,
+severity levels, and recommended remediation steps.
+
+FORMAT: %FACILITY-SEVERITY-MNEMONIC: description
+Severity: 0=Emergency, 1=Alert, 2=Critical, 3=Error, 4=Warning, 5=Notice, 6=Info, 7=Debug
+
+=============================================================================
+SESSION STATE CHANGE MESSAGES
+=============================================================================
+
+%BGP-5-ADJCHANGE: neighbor <ip> Down <reason>
+Severity: 5 (Notice)
+Meaning: BGP adjacency has gone down.
+The <reason> field is critical — common values:
+
+  "Hold Timer Expired"
+  → No KEEPALIVE received within hold-time seconds
+  → Check: CPU utilization on both routers (show processes cpu)
+  → Check: Interface drops (show interfaces | include drops)
+  → Check: Routing to peer (ping with source IP)
+  → Fix: May need to increase hold timer (timers bgp 60 180)
+
+  "BGP Notification sent"
+  → Local router sent a NOTIFICATION (error) to peer
+  → Follow-up: check logs for %BGP-3-NOTIFICATION line
+  → That will identify the specific error code
+
+  "BGP Notification received"
+  → Remote peer sent a NOTIFICATION to us
+  → Follow-up: check logs for the NOTIFICATION code
+  → May indicate our UPDATE was malformed
+
+  "Peer closed the session"
+  → Remote router closed TCP connection cleanly
+  → May be deliberate (peer reset the session) or process restart
+
+  "Interface flap"
+  → Underlying interface went down, pulling BGP TCP session with it
+  → Check: show interfaces <int> for line protocol changes
+  → Consider BFD for faster failure detection
+
+  "Reset requested by peer"
+  → Remote operator ran: clear ip bgp <ip>
+  → Normal operational event
+
+  "Neighbor deleted"
+  → BGP neighbor statement removed from configuration
+
+%BGP-5-ADJCHANGE: neighbor <ip> Up
+Severity: 5 (Notice)
+Meaning: BGP adjacency established. Normal operational message.
+Log this to verify expected peering.
+
+=============================================================================
+NOTIFICATION MESSAGES
+=============================================================================
+
+%BGP-3-NOTIFICATION: sent to neighbor <ip> <error-code>/<sub-code> (<reason>) <data>
+%BGP-3-NOTIFICATION: received from neighbor <ip> <error-code>/<sub-code> (<reason>) <data>
+Severity: 3 (Error)
+Meaning: BGP NOTIFICATION message sent/received — session will reset.
+
+Error Code 1 — Message Header Error
+  Subcode 1: Connection Not Synchronized
+  Subcode 2: Bad Message Length
+  Subcode 3: Bad Message Type
+  → Usually indicates implementation bug or packet corruption
+  → Check for MTU mismatches causing BGP message truncation
+
+Error Code 2 — OPEN Message Error
+  Subcode 1: Unsupported Version Number
+  → One side is not running BGP4 (extremely rare)
+
+  Subcode 2: Bad Peer AS
+  → neighbor remote-as configured incorrectly on one side
+  → Verify ASNs match on both routers: show bgp neighbors | include remote AS
+
+  Subcode 3: Bad BGP Identifier
+  → Router ID conflict (same Router ID on both peers)
+  → Fix: bgp router-id <unique-id> on one router
+
+  Subcode 4: Unsupported Optional Parameter
+  → Capability mismatch (rare on modern IOS)
+
+  Subcode 5: Authentication Failure
+  → MD5 password mismatch
+  → Also look for: %TCP-6-BADAUTH messages
+
+  Subcode 6: Unacceptable Hold Time
+  → Hold time < 3 seconds (RFC requirement)
+  → Check: timers bgp configuration on both sides
+
+Error Code 3 — UPDATE Message Error
+  Subcode 1: Malformed Attribute List
+  Subcode 2: Unrecognized Well-known Attribute
+  Subcode 3: Missing Well-known Attribute
+  Subcode 4: Attribute Flags Error
+  Subcode 5: Attribute Length Error
+  Subcode 6: Invalid ORIGIN Attribute
+  Subcode 8: Invalid NEXT_HOP Attribute
+  → These indicate a routing protocol implementation bug
+  → Collect: debug ip bgp <ip> updates, capture the problematic UPDATE
+  → May need to contact Cisco TAC with packet capture
+
+Error Code 4 — Hold Timer Expired
+  → Same as "Hold Timer Expired" reason in ADJCHANGE
+  → Session reset because no KEEPALIVE within hold-time
+
+Error Code 5 — Finite State Machine Error
+  → BGP received unexpected event for current state
+  → Often indicates a software bug or packet corruption
+
+Error Code 6 — Cease
+  Subcode 1: Maximum Number of Prefixes Reached
+  → Peer exceeded maximum-prefix limit
+  → Fix: Increase limit or fix routing policy on peer
+
+  Subcode 2: Administrative Shutdown
+  → Peer ran: neighbor <ip> shutdown
+  → Normal operational event
+
+  Subcode 3: Peer De-configured
+  → Neighbor statement removed on remote side
+
+  Subcode 4: Administrative Reset
+  → Peer ran: clear ip bgp <ip>
+
+  Subcode 7: Connection Collision Resolution
+  → Both routers initiated TCP connection simultaneously
+  → One session kept, one dropped. Normal behavior.
+
+=============================================================================
+AUTHENTICATION MESSAGES
+=============================================================================
+
+%TCP-6-BADAUTH: No MD5 digest from <ip>(<port>) to <ip>(<port>)
+Meaning: We expect MD5 authentication but peer is NOT sending it.
+Fix: Add authentication on the peer: neighbor <local-ip> password <key>
+
+%TCP-6-BADAUTH: Invalid MD5 digest from <ip>(<port>) to <ip>(<port>)
+Meaning: Both sides are using MD5 but the passwords do NOT match.
+Fix: Verify identical passwords. Check for:
+  - Trailing whitespace in password
+  - Case sensitivity errors
+  - Type-0 vs Type-7 password confusion in config
+
+=============================================================================
+PREFIX LIMIT MESSAGES
+=============================================================================
+
+%BGP-3-MAXPFXEXCEED: No. of prefix received from <ip> (<count>) exceeds limit <limit>
+Severity: 3 (Error)
+Meaning: Peer sent more prefixes than maximum-prefix allows.
+Action depends on configuration:
+  - Default: session torn down with NOTIFICATION (Cease/Max-Prefix)
+  - With warning-only: session stays up, alert generated
+  - With threshold: warning at percentage of limit
+
+Fix:
+  a) Investigate why peer is sending unexpected volume
+  b) Adjust limit: neighbor <ip> maximum-prefix <new-limit>
+  c) Reset session: clear ip bgp <ip>
+
+%BGP-4-MAXPFX: No. of prefix received from <ip> (<count>) reaches <threshold>%
+Severity: 4 (Warning)
+Meaning: Prefix count approaching limit — warning only, session intact.
+Action: Monitor; consider adjusting limit or investigating route growth.
+
+=============================================================================
+ROUTE FLAP / DAMPENING MESSAGES
+=============================================================================
+
+%BGP-6-ASPATH: Long AS path <path> received — truncated
+Severity: 6 (Informational)
+Meaning: Received an AS_PATH exceeding 255 ASNs (virtually impossible in real networks).
+Typically indicates a routing loop or AS_PATH prepending misconfiguration.
+
+%BGP-5-DAMP: Prefix <prefix> now suppressed, penalty <n>
+Meaning: Route flap dampening suppressed this prefix.
+Fix: Either wait for suppression to lift (show ip bgp dampened-paths)
+     or clear: clear ip bgp dampening <prefix>
+
+=============================================================================
+MEMORY AND RESOURCE MESSAGES
+=============================================================================
+
+%BGP-4-MEMNOMEM: No memory available for <resource>
+Severity: 4 (Warning)
+Meaning: Router running low on memory for BGP operations.
+Immediate actions:
+  1. show processes memory sorted — identify memory consumers
+  2. show ip bgp summary — how many routes/peers?
+  3. Consider prefix filtering to reduce table size
+  4. May require hardware upgrade if persistent
+
+%SYS-2-MALLOCFAIL: Memory allocation of <n> bytes failed from <location>
+Severity: 2 (Critical)
+Meaning: System-wide memory exhaustion. BGP will likely flap.
+Action: Emergency — contact NOC, consider graceful shutdown of non-critical BGP peers.
+
+=============================================================================
+QUICK REFERENCE: MOST COMMON MESSAGES
+=============================================================================
+
+Most frequently seen in production:
+
+1. %BGP-5-ADJCHANGE: neighbor x.x.x.x Down Hold Timer Expired
+   → Check CPU, interface drops, routing path to peer
+
+2. %BGP-5-ADJCHANGE: neighbor x.x.x.x Down BGP Notification sent
+   → Find the matching NOTIFICATION message for error details
+
+3. %TCP-6-BADAUTH: Invalid MD5 digest
+   → Password mismatch — verify both sides
+
+4. %BGP-3-NOTIFICATION: Error Code 2 / Subcode 2 (Bad Peer AS)
+   → AS number mismatch in neighbor configuration
+
+5. %BGP-3-MAXPFXEXCEED
+   → Prefix limit hit — peer sending unexpected volume of routes

data/docs/bgp_show_commands.txt

@@ -0,0 +1,178 @@
+BGP SHOW COMMANDS REFERENCE — CISCO IOS / IOS-XE
+==================================================
+
+SUMMARY AND OVERVIEW COMMANDS
+-------------------------------
+
+show ip bgp summary
+  Purpose: Quick overview of all BGP neighbors, their state, prefixes received
+  Output fields:
+    Neighbor    — Peer IP address
+    V           — BGP version (always 4)
+    AS          — Remote AS number
+    MsgRcvd     — Total messages received since session start
+    MsgSent     — Total messages sent
+    TblVer      — Table version (increments with each routing change)
+    InQ/OutQ    — Messages queued (should be 0; if non-zero, session overloaded)
+    Up/Down     — Session uptime (or time since last state change if down)
+    State/PfxRcd — Session state or prefix count if ESTABLISHED
+
+  Key interpretation:
+    State = Idle/Active/Connect → session NOT established
+    State = numeric (e.g., 145032) → ESTABLISHED, showing prefix count
+    State = 0 → ESTABLISHED but no prefixes received
+
+show ip bgp
+  Purpose: Full BGP routing table
+  Output columns:
+    Status codes: s=suppressed, d=damped, h=history, *=valid, >=best, i=internal
+    Origin codes: i=IGP, e=EGP, ?=incomplete
+  Common filters:
+    show ip bgp <prefix>             — specific prefix detail
+    show ip bgp regexp <regex>       — filter by AS_PATH
+    show ip bgp community <value>    — filter by community
+    show ip bgp prefix-list <name>   — filter by prefix-list
+
+show bgp neighbors <ip>  (or show ip bgp neighbors <ip>)
+  Purpose: Detailed per-neighbor information
+  Key fields to check:
+    BGP state = <state>              — current FSM state
+    Hold time is <n>, keepalive is <n> — negotiated timers
+    Configured hold time is <n>      — locally configured value
+    BGP version = 4                  — should always be 4
+    Neighbor capabilities:           — supported features
+    Message statistics:              — counts by message type
+    Prefix activity:                 — prefixes accepted/denied
+    Local host: <ip>, Local port: <port>
+    Foreign host: <ip>, Foreign port: <port>
+    Connections established <n>; dropped <n>
+    Last reset <time> ago, due to: <reason>   ← CRITICAL FOR TROUBLESHOOTING
+
+PREFIX AND ROUTE COMMANDS
+--------------------------
+
+show ip bgp neighbors <ip> advertised-routes
+  Purpose: Show routes being sent TO this neighbor
+  Use case: Verify outbound policy is working correctly
+  Note: Does not require soft-reconfiguration inbound
+
+show ip bgp neighbors <ip> received-routes
+  Purpose: Show ALL routes received FROM neighbor (before inbound policy)
+  Prerequisite: neighbor <ip> soft-reconfiguration inbound must be configured
+  Use case: Verify what peer is actually sending before filters
+
+show ip bgp neighbors <ip> routes
+  Purpose: Show routes accepted after inbound policy
+  Use case: Verify filtered routes are being applied
+
+show ip bgp <prefix>
+  Purpose: Detailed path information for a specific prefix
+  Shows: All paths, best path selection reason, full attributes
+  Example output interpretation:
+    BGP routing table entry for 10.0.0.0/8, version 45
+    Paths: (2 available, best #1, table Default-IP-Routing-Table)
+    Advertised to update-groups: 1
+    Path #1: <best>
+      10.1.1.1 from 10.1.1.1 (192.168.1.1)
+        Origin IGP, metric 0, localpref 100, valid, external, best
+        Community: 65000:100
+
+show ip bgp <prefix> longer-prefixes
+  Purpose: Show all more-specific routes within a prefix block
+  Use case: Check for more-specifics competing with aggregate
+
+POLICY AND FILTERING COMMANDS
+-------------------------------
+
+show route-map [name]
+  Purpose: Display route-map configuration and match/set statistics
+  Counter field: Policy routing matches — shows how many routes hit each clause
+
+show ip prefix-list [name]
+  Purpose: Display prefix-list and hit counters
+  Use case: Verify prefix-lists are matching expected routes
+
+show ip community-list [number|name]
+  Purpose: Display community-list configuration
+
+show bgp neighbors <ip> policy
+  Purpose: Show inbound and outbound policies applied to this neighbor
+  Requires: BGP policy accounting enabled, or IOS-XE enhanced policy view
+
+ATTRIBUTE MANIPULATION VERIFICATION
+-------------------------------------
+
+show ip bgp | include LOCAL_PREF
+  Purpose: Verify LOCAL_PREFERENCE values in table
+
+show ip bgp detail | include community
+  Purpose: Show community values on prefixes
+
+show ip bgp <prefix> detail
+  Purpose: Full attribute dump including:
+    - LOCAL_PREF, MED, WEIGHT, AS_PATH
+    - COMMUNITIES, ORIGINATOR_ID, CLUSTER_LIST
+    - NEXT_HOP and IGP metric to next-hop
+    - Path selection reason
+
+STATISTICS AND MONITORING
+--------------------------
+
+show bgp neighbors <ip> | include notifications
+  Purpose: Check for NOTIFICATION messages (errors sent/received)
+  Non-zero notifications indicate session resets with error codes
+
+show bgp neighbors <ip> | include drops
+  Purpose: Count session drops/resets
+
+show bgp summary | include Down
+  Purpose: Quick filter to see which peers are down
+
+show tcp brief
+  Purpose: Verify TCP session exists for BGP (port 179)
+  Look for: <peer-ip>.bgp ESTABLISHED
+
+show ip route bgp
+  Purpose: Show only BGP-installed routes in routing table
+  Use case: Verify BGP routes are being used for forwarding
+
+DEBUG COMMANDS (USE WITH CAUTION IN PRODUCTION)
+-------------------------------------------------
+
+debug ip bgp <neighbor-ip> events
+  Shows: Session state changes, timer events, connection attempts
+  Safe to use briefly in production
+
+debug ip bgp <neighbor-ip> updates
+  Shows: Every UPDATE message sent and received
+  WARNING: Very verbose if many prefixes; can impact router performance
+  Best practice: Use with specific neighbor IP, not "debug ip bgp *"
+
+debug ip bgp all
+  WARNING: NEVER use in production. Shows ALL BGP events for ALL peers.
+  Use only in lab environment.
+
+Undebug all: undebug all  (or: no debug all)
+
+USEFUL SHOW COMMAND SEQUENCES FOR COMMON SCENARIOS
+----------------------------------------------------
+
+Scenario: BGP session down, need to know why
+  1. show ip bgp summary                    — confirm state
+  2. show bgp neighbors <ip> | include state — current state
+  3. show bgp neighbors <ip> | include reset — last reset reason
+  4. ping <ip> source <source-ip>            — test reachability
+  5. show log | include BGP                  — check syslog history
+
+Scenario: Routes not appearing in BGP table
+  1. show ip bgp summary                    — confirm ESTABLISHED
+  2. show bgp neighbors <ip> received-routes — what did peer send?
+  3. show bgp neighbors <ip> routes          — what survived filtering?
+  4. show bgp neighbors <ip> policy          — what policy is applied?
+  5. show route-map <name>                   — check policy config
+
+Scenario: Suboptimal routing (wrong path selected)
+  1. show ip bgp <prefix>                   — see all paths
+  2. show ip bgp <prefix> detail             — see attribute comparison
+  3. show bgp neighbors <ip> advertised-routes — verify what you're sending
+  4. Check: weight, local-pref, AS-path, MED in order of preference

data/docs/bgp_states_guide.txt

@@ -0,0 +1,143 @@
+BGP NEIGHBOR STATE MACHINE — CISCO IOS REFERENCE GUIDE
+=======================================================
+
+BGP uses a finite state machine (FSM) with six states to manage neighbor relationships.
+Understanding each state is critical for troubleshooting peering issues.
+
+STATE 1: IDLE
+-------------
+Description:
+  The router is not attempting BGP connections. This is the initial state.
+
+Common causes of being stuck in IDLE:
+  - BGP process not started or neighbor statement missing
+  - Administrative shutdown: neighbor <ip> shutdown
+  - Route to neighbor unreachable (no IGP path)
+  - TCP port 179 blocked by ACL or firewall
+  - Incorrect neighbor IP address configured
+
+Verification commands:
+  show bgp neighbors <ip>
+  show ip bgp summary
+  ping <neighbor-ip> source <local-ip>
+  telnet <neighbor-ip> 179
+
+Transition: IDLE → CONNECT when BGP initiates TCP connection
+
+STATE 2: CONNECT
+----------------
+Description:
+  BGP is waiting for the TCP three-way handshake to complete on port 179.
+
+Common issues:
+  - TCP SYN sent but no SYN-ACK received (firewall blocking)
+  - Wrong source IP for TCP session (use update-source loopback for iBGP)
+  - MTU mismatch causing TCP fragmentation issues
+
+Verification commands:
+  debug ip bgp <neighbor-ip> events
+  show tcp brief
+  show ip interface brief (verify source interface)
+
+Transition: CONNECT → OPENSENT when TCP session established
+
+STATE 3: ACTIVE
+---------------
+Description:
+  TCP connection failed; BGP is actively retrying. The router alternates
+  between CONNECT and ACTIVE states while attempting to establish TCP.
+
+ACTIVE state is one of the most common "stuck" states and indicates:
+  - TCP connectivity problem (most common)
+  - Incorrect neighbor IP address
+  - Missing or wrong update-source configuration for loopback peers
+  - Interface down on one side
+
+Key distinction: ACTIVE means BGP is TRYING but failing at TCP layer.
+
+Verification commands:
+  show bgp neighbors <ip> | include BGP state
+  debug ip tcp transactions
+  show ip route <neighbor-ip>
+
+STATE 4: OPENSENT
+-----------------
+Description:
+  TCP connection established. Local router sent OPEN message and is waiting
+  for the remote router's OPEN message.
+
+OPEN message contains:
+  - BGP version (must be 4 on both sides)
+  - AS number
+  - Hold time
+  - BGP Router ID
+  - Optional capabilities (route refresh, 4-byte ASN, etc.)
+
+Common errors at this stage:
+  - AS number mismatch
+  - BGP version incompatibility (rare, always version 4)
+  - Unsupported capability causing NOTIFICATION
+
+Verification commands:
+  debug ip bgp <neighbor-ip> updates
+  show bgp neighbors <ip>
+
+STATE 5: OPENCONFIRM
+--------------------
+Description:
+  Both OPEN messages exchanged. BGP is waiting for KEEPALIVE to confirm
+  the session. Hold timer negotiation occurs here.
+
+Hold time negotiation: lower value of the two routers wins.
+  Default hold time: 180 seconds
+  Default keepalive interval: 60 seconds (1/3 of hold time)
+
+Common issues:
+  - Hold time mismatch (one side configured with timers bgp 10 30,
+    other side uses default 60 180 — the lower 30 will be selected)
+  - NOTIFICATION sent by remote (check logs)
+
+Verification commands:
+  show bgp neighbors <ip> | include Hold time
+  show bgp neighbors <ip> | include Keepalive
+
+STATE 6: ESTABLISHED
+--------------------
+Description:
+  BGP session is fully up. KEEPALIVE messages exchanged every keepalive
+  interval. UPDATE messages carry routing information.
+
+Monitoring an ESTABLISHED session:
+  show ip bgp summary          — shows prefixes received, uptime, state
+  show bgp neighbors <ip>      — detailed session info
+  show ip bgp                  — full BGP table
+  show ip bgp neighbors <ip> advertised-routes
+  show ip bgp neighbors <ip> received-routes
+
+Session going DOWN from ESTABLISHED indicates:
+  - Hold timer expired (no KEEPALIVE received in hold-time seconds)
+  - NOTIFICATION message received
+  - TCP session reset (interface flap, carrier drop)
+  - BFD failure (if configured)
+  - Peer reset (clear ip bgp executed on remote)
+
+BGP TIMER REFERENCE
+-------------------
+Default keepalive:     60 seconds
+Default hold time:    180 seconds
+Minimum hold time:      0 (hold timer disabled — not recommended)
+ConnectRetry timer:    32 seconds (wait before retrying TCP after failure)
+
+Recommended for fast convergence (data center):
+  timers bgp 3 9
+  (keepalive 3s, hold 9s — aggressive but supported)
+
+BGP ROUTER ID SELECTION
+------------------------
+BGP Router ID is selected in this order:
+  1. Manually configured: bgp router-id <x.x.x.x>
+  2. Highest loopback IP address
+  3. Highest physical interface IP address (if no loopback)
+
+Router ID conflict causes OPEN message rejection.
+Two iBGP peers cannot have same Router ID.

data/docs/bgp_troubleshooting_guide.txt

@@ -0,0 +1,205 @@
+BGP TROUBLESHOOTING GUIDE — SYSTEMATIC METHODOLOGY
+====================================================
+
+GOLDEN RULE: Always start at Layer 3 (IP reachability) before debugging BGP.
+BGP runs over TCP port 179 — if TCP fails, BGP fails.
+
+TROUBLESHOOTING FRAMEWORK
+--------------------------
+Step 1: Verify physical/logical connectivity
+Step 2: Verify IP reachability to BGP peer
+Step 3: Verify BGP configuration matches on both sides
+Step 4: Check BGP state machine and error messages
+Step 5: Verify prefix exchange and routing policies
+
+SECTION 1: BGP SESSION NOT FORMING
+------------------------------------
+
+Symptom: "show ip bgp summary" shows neighbor in ACTIVE or IDLE state
+
+Checklist:
+[ ] Can you ping the neighbor IP from the correct source?
+    ping <neighbor-ip> source <update-source-ip>
+
+[ ] Is TCP 179 reachable?
+    telnet <neighbor-ip> 179
+
+[ ] Is the neighbor statement correct?
+    neighbor <ip> remote-as <asn>
+
+[ ] For iBGP with loopbacks: is update-source configured?
+    neighbor <loopback-ip> update-source Loopback0
+
+[ ] Is there a route to the neighbor in the routing table?
+    show ip route <neighbor-ip>
+
+[ ] Is port 179 blocked?
+    show ip access-lists (check for deny tcp any any eq 179)
+
+[ ] Are both sides using the same MD5 password?
+    neighbor <ip> password <key>
+    — Password mismatch causes TCP session to silently fail
+
+Commands to run:
+  show ip bgp summary
+  show bgp neighbors <ip>
+  debug ip bgp <ip> events (use with caution in production)
+
+
+SECTION 2: BGP SESSION FLAPPING
+---------------------------------
+
+Symptom: BGP neighbor goes up and down repeatedly
+Syslog: %BGP-5-ADJCHANGE: neighbor <ip> Down
+
+Root causes and remediation:
+
+1. HOLD TIMER EXPIRY (most common flapping cause)
+   - Symptoms: "BGP notification sent or received" in logs
+   - Cause: KEEPALIVE messages not arriving within hold-time
+   - Often caused by: high CPU on router, interface congestion,
+     route processor overload
+   - Fix:
+     a) Check CPU: show processes cpu sorted
+     b) Check input queue drops: show interfaces <int> | include drops
+     c) Consider increasing hold timer: timers bgp 60 180
+     d) Consider BFD as alternative failure detection
+
+2. INTERFACE FLAPPING
+   - Verify: show interfaces <int> | include line protocol
+   - Check error counters: show interfaces <int>
+   - Look for CRC errors, input errors indicating physical layer issue
+
+3. ROUTE REFLECTOR / CONFEDERATION ISSUES
+   - Verify RR cluster-id matches across all RR clients
+   - Check for routing loops caused by missing cluster-id
+
+4. MEMORY EXHAUSTION
+   - show processes memory sorted
+   - BGP table too large for available memory
+   - Consider prefix-list filtering: neighbor <ip> prefix-list FILTER in
+
+5. BFD TRIGGERED FAILOVER
+   - show bfd neighbors
+   - BFD more sensitive than BGP hold timer — may trigger false positives
+   - Tune: bfd interval 300 min_rx 300 multiplier 3
+
+
+SECTION 3: ROUTES NOT BEING RECEIVED
+--------------------------------------
+
+Symptom: BGP session is ESTABLISHED but expected prefixes missing
+
+Checklist:
+[ ] Does the remote side have the route to advertise?
+    show ip bgp <prefix> (on remote router)
+
+[ ] Is the route being advertised?
+    show ip bgp neighbors <ip> advertised-routes
+
+[ ] Is an inbound route policy filtering it?
+    show ip bgp neighbors <ip> policy
+    show route-map <name>
+
+[ ] Is the prefix blocked by a prefix-list?
+    show ip prefix-list <name>
+
+[ ] Is soft-reconfiguration enabled (to see received routes)?
+    neighbor <ip> soft-reconfiguration inbound
+    show ip bgp neighbors <ip> received-routes
+
+
+SECTION 4: ROUTES NOT BEING ADVERTISED
+----------------------------------------
+
+Symptom: Local prefixes not appearing in peer's BGP table
+
+Common causes:
+
+1. NETWORK STATEMENT MISSING OR WRONG
+   - network <prefix> mask <mask> must exactly match routing table entry
+   - network 10.0.0.0 mask 255.255.0.0 will only work if 10.0.0.0/16
+     exists exactly in the routing table (not just a subnet of it)
+
+2. REDISTRIBUTE NOT CONFIGURED
+   - If redistributing from OSPF/EIGRP:
+     redistribute ospf 1 metric 100 route-map EXPORT
+
+3. NEXT-HOP NOT REACHABLE
+   - iBGP: next-hop-self required when advertising eBGP-learned routes to iBGP
+   - neighbor <ip> next-hop-self
+
+4. OUTBOUND ROUTE POLICY BLOCKING
+   - show bgp neighbors <ip> policy
+   - show route-map <name> (check for deny statements)
+
+5. MAXIMUM-PREFIX LIMIT HIT
+   - neighbor <ip> maximum-prefix <number> [threshold] [warning-only]
+   - show ip bgp neighbors <ip> | include prefix
+
+
+SECTION 5: BGP PATH SELECTION ISSUES
+--------------------------------------
+
+When multiple paths exist, BGP selects best path using this ordered criteria:
+
+1.  Highest WEIGHT (Cisco proprietary, local to router)
+2.  Highest LOCAL_PREFERENCE (within AS, default 100)
+3.  Locally originated (network/redistribute > iBGP learned)
+4.  Shortest AS_PATH length
+5.  Lowest ORIGIN (IGP < EGP < incomplete)
+6.  Lowest MED (when paths come from same neighboring AS)
+7.  eBGP path over iBGP path
+8.  Lowest IGP metric to BGP next-hop
+9.  Oldest eBGP path (most stable)
+10. Lowest BGP Router ID
+11. Lowest neighbor IP address
+
+Debug path selection:
+  show ip bgp <prefix>         — shows all paths, best marked with >
+  show ip bgp <prefix> detail  — full attribute dump
+
+
+SECTION 6: AUTHENTICATION FAILURES
+-------------------------------------
+
+BGP MD5 authentication:
+  neighbor <ip> password <key>
+
+Symptoms of mismatch:
+  - TCP session never establishes (stays in ACTIVE)
+  - Syslog: %TCP-6-BADAUTH: No MD5 digest from <ip>
+  - Syslog: %TCP-6-BADAUTH: Invalid MD5 digest from <ip>
+
+Verification:
+  show bgp neighbors <ip> | include password
+  (will show "MD5 is configured" but NOT the password itself)
+
+Common mistakes:
+  - Trailing space in password string
+  - Case sensitivity error
+  - One side has password, other does not
+  - Password configured but TCP session pre-dates authentication config
+    (requires session reset: clear ip bgp <ip> soft)
+
+
+SECTION 7: HIGH CPU FROM BGP
+------------------------------
+
+Symptoms: Router sluggish, BGP sessions flapping, high CPU
+
+Commands:
+  show processes cpu sorted | head 20
+  show bgp process detail (XE/XR)
+
+Common causes:
+  1. Full internet BGP table (800k+ routes) — normal during convergence
+  2. Route policy with complex regex (avoid regex in large deployments)
+  3. Peer sending malformed updates (check: show ip bgp neighbors <ip> | include notifications)
+  4. BGP scanner running (every 60s, unavoidable but brief)
+  5. Soft reset in progress: clear ip bgp <ip> soft in
+
+Mitigation:
+  - Prefix filtering: only accept needed prefixes
+  - Outbound route filtering (ORF)
+  - BGP route dampening (use carefully — deprecated in some designs)

data/telemetry/bgp_telemetry_logs.txt

@@ -0,0 +1,187 @@
+BGP TELEMETRY AND SYSLOG DATA — PRODUCTION NETWORK SAMPLES
+============================================================
+Collection period: 30 days
+Network: Enterprise dual-homed AS65001 (iBGP + 2x eBGP upstreams)
+Routers: CORE-RTR-01, CORE-RTR-02, EDGE-RTR-01, EDGE-RTR-02
+
+=============================================================================
+WEEK 1 — NORMAL OPERATIONS + AUTHENTICATION INCIDENT
+=============================================================================
+
+2024-01-02 00:01:15 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Up
+2024-01-02 00:01:16 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 172.16.0.1 Up
+2024-01-02 00:01:18 UTC EDGE-RTR-01: %BGP-5-ADJCHANGE: neighbor 203.0.113.1 Up
+
+2024-01-02 00:15:30 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Down Hold Timer Expired
+2024-01-02 00:15:30 UTC CORE-RTR-01: %BGP-3-NOTIFICATION: sent to neighbor 10.0.0.2 4/0 (hold time expired) 0 bytes
+2024-01-02 00:15:47 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Up
+  # Analysis: Brief hold timer expiry — likely high CPU spike. Recovered quickly.
+  # Action taken: Monitored; CPU was at 92% during BGP scanner run.
+
+2024-01-03 09:22:11 UTC EDGE-RTR-01: %TCP-6-BADAUTH: No MD5 digest from 198.51.100.1(179) to 198.51.100.2(49821)
+2024-01-03 09:22:11 UTC EDGE-RTR-01: %TCP-6-BADAUTH: No MD5 digest from 198.51.100.1(179) to 198.51.100.2(49821)
+2024-01-03 09:22:12 UTC EDGE-RTR-01: %TCP-6-BADAUTH: No MD5 digest from 198.51.100.1(179) to 198.51.100.2(49821)
+  # Analysis: ISP-01 (198.51.100.1) not sending MD5 authentication.
+  # Opened ticket with ISP — they had removed auth after maintenance window.
+  # ISP added auth back at 09:45. Session re-established at 09:47.
+
+2024-01-03 09:47:03 UTC EDGE-RTR-01: %BGP-5-ADJCHANGE: neighbor 198.51.100.1 Up
+
+2024-01-04 14:33:22 UTC EDGE-RTR-02: %BGP-5-ADJCHANGE: neighbor 203.0.113.5 Down BGP Notification received
+2024-01-04 14:33:22 UTC EDGE-RTR-02: %BGP-3-NOTIFICATION: received from neighbor 203.0.113.5 2/2 (open error/bad peer AS) 2 bytes
+  # Analysis: ISP-02 (203.0.113.5) sent Open Error — Bad Peer AS.
+  # Investigation: ISP changed our peer configuration to wrong ASN after circuit upgrade.
+  # ISP corrected at 15:10.
+
+2024-01-04 15:10:44 UTC EDGE-RTR-02: %BGP-5-ADJCHANGE: neighbor 203.0.113.5 Up
+
+=============================================================================
+WEEK 2 — HOLD TIMER EXPIRY INCIDENTS (MOST COMMON ISSUE TYPE)
+=============================================================================
+
+# Hold timer expiry accounted for 67% of all BGP resets this month.
+# Primary cause: CPU spikes during BGP table scan (every 60 seconds).
+
+2024-01-08 02:14:55 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Down Hold Timer Expired
+2024-01-08 02:14:55 UTC CORE-RTR-01: show processes cpu sorted output:
+  CPU utilization for five seconds: 98%/62%; one minute: 78%; five minutes: 45%
+  PID  Runtime(ms)   Invoked    uSecs    5Sec   1Min   5Min TTY Process
+  170   8234901     291034     28290   72.45% 41.23% 18.12%   0 BGP Scanner
+  045   1923044      82341     23360   14.22%  8.44%  4.21%   0 BGP Router
+  # BGP Scanner consuming 72% CPU — causing keepalive packet drops.
+
+2024-01-08 02:15:22 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Up
+
+2024-01-09 03:45:11 UTC CORE-RTR-02: %BGP-5-ADJCHANGE: neighbor 10.0.0.1 Down Hold Timer Expired
+2024-01-09 03:45:34 UTC CORE-RTR-02: %BGP-5-ADJCHANGE: neighbor 10.0.0.1 Up
+  # Same pattern on CORE-RTR-02. Hold timer expiry at 03:45, recovered at 03:45.
+  # Duration: 23 seconds.
+
+2024-01-10 03:44:58 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Down Hold Timer Expired
+  # Third consecutive night at ~03:45 UTC. Correlates with nightly backup job.
+  # Backup script was causing 80% CPU spike on management plane.
+  # Resolution: Rescheduled backup to 05:00 UTC. No further occurrences.
+
+2024-01-11 05:00:00 UTC — Backup rescheduled
+2024-01-11 onwards — No Hold Timer Expiry events on CORE-RTR-01/02
+
+=============================================================================
+WEEK 2 — INTERFACE FLAP CAUSING BGP RESET
+=============================================================================
+
+2024-01-09 11:22:33 UTC EDGE-RTR-01: %LINK-3-UPDOWN: Interface GigabitEthernet0/0, changed state to down
+2024-01-09 11:22:33 UTC EDGE-RTR-01: %BGP-5-ADJCHANGE: neighbor 203.0.113.1 Down Interface flap
+2024-01-09 11:22:33 UTC EDGE-RTR-01: %LINK-3-UPDOWN: Interface GigabitEthernet0/0, changed state to up
+2024-01-09 11:22:35 UTC EDGE-RTR-01: %BGP-5-ADJCHANGE: neighbor 203.0.113.1 Up
+  # Physical layer flap on upstream interface. Duration: 2 seconds.
+  # Cause: Fiber patch cable reseated during data center maintenance.
+  # BGP convergence time: 2 seconds (BFD not configured on this link).
+
+2024-01-09 11:22:33 UTC CORE-RTR-01: show ip bgp summary excerpt:
+  Neighbor        V    AS MsgRcvd MsgSent   TblVer  InQ OutQ Up/Down  State/PfxRcd
+  10.0.0.2        4 65001   45231   45219   982345    0    0 3d14h         145032
+  172.16.0.1      4 65001   12043   12039   982345    0    0 3d14h          45231
+  203.0.113.1     4 65002   89321   89315   982345    0    0 00:00:03       312045
+  198.51.100.1    4 65003   67234   67228   982345    0    0 5d02h          289034
+  # Note 203.0.113.1 shows uptime 00:00:03 — just reestablished after flap.
+
+=============================================================================
+WEEK 3 — PREFIX LIMIT INCIDENT
+=============================================================================
+
+2024-01-15 08:45:22 UTC EDGE-RTR-02: %BGP-4-MAXPFX: No. of prefix received from 203.0.113.5 (267812) reaches 80% of limit 325000
+  # Warning: Prefix count at 80% of limit. ISP-02 prefix count growing.
+
+2024-01-15 08:46:11 UTC EDGE-RTR-02: %BGP-4-MAXPFX: No. of prefix received from 203.0.113.5 (289034) reaches 89% of limit 325000
+
+2024-01-15 08:47:03 UTC EDGE-RTR-02: %BGP-3-MAXPFXEXCEED: No. of prefix received from 203.0.113.5 (332411) exceeds limit 325000
+2024-01-15 08:47:03 UTC EDGE-RTR-02: %BGP-5-ADJCHANGE: neighbor 203.0.113.5 Down MAXPFX exceeded
+  # Session torn down! ISP-02 leaked a full routing table.
+  # Full internet BGP table: ~900K+ routes. Our limit was 325K.
+  # Investigation: ISP-02 suffered route leak from their upstream — all routes redistributed.
+
+2024-01-15 09:15:00 UTC — ISP-02 fixed route leak, prefix count normalized
+2024-01-15 09:15:44 UTC EDGE-RTR-02: clear ip bgp 203.0.113.5 executed
+2024-01-15 09:15:50 UTC EDGE-RTR-02: %BGP-5-ADJCHANGE: neighbor 203.0.113.5 Up
+  # Session reestablished. Lesson: maximum-prefix saved us from memory exhaustion.
+
+=============================================================================
+WEEK 3 — BGP AUTHENTICATION MISMATCH
+=============================================================================
+
+2024-01-16 14:22:45 UTC CORE-RTR-01: %TCP-6-BADAUTH: Invalid MD5 digest from 10.0.0.2(49301) to 10.0.0.1(179)
+2024-01-16 14:22:45 UTC CORE-RTR-01: %TCP-6-BADAUTH: Invalid MD5 digest from 10.0.0.2(49301) to 10.0.0.1(179)
+2024-01-16 14:22:45 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Down BGP authentication failure
+  # Invalid MD5 — passwords don't match. CORE-RTR-02 had a password change.
+  # Change management error: password updated on RTR-02 but not RTR-01.
+  # Fix: Updated password on RTR-01 to match.
+
+2024-01-16 14:35:12 UTC CORE-RTR-01: clear ip bgp 10.0.0.2
+2024-01-16 14:35:18 UTC CORE-RTR-01: %BGP-5-ADJCHANGE: neighbor 10.0.0.2 Up
+
+=============================================================================
+WEEK 4 — ROUTE REFLECTOR CLUSTER-ID ISSUE
+=============================================================================
+
+2024-01-22 09:11:22 UTC CORE-RTR-01: %BGP-3-CLUSTER_LIST_LOOP: Cluster list loop detected for prefix 192.168.0.0/16
+2024-01-22 09:11:22 UTC CORE-RTR-01: %BGP-3-CLUSTER_LIST_LOOP: Cluster list loop detected for prefix 192.168.1.0/24
+  # RR loop detection triggered. Missing cluster-id on one of the RRs.
+  # CORE-RTR-02 was acting as RR but had no cluster-id configured.
+  # Without cluster-id, multiple RRs in the same cluster cause duplicate originator loops.
+  # Fix: Added bgp cluster-id 1 to CORE-RTR-02.
+  # Reference: RFC 4456 Section 8
+
+2024-01-22 09:45:00 UTC — cluster-id added to CORE-RTR-02
+2024-01-22 09:45:11 UTC CORE-RTR-01: clear ip bgp * soft
+2024-01-22 09:45:30 UTC — Cluster list loop messages ceased
+
+=============================================================================
+MONTHLY SUMMARY — INCIDENT STATISTICS
+=============================================================================
+
+Total BGP session resets: 23 events over 30 days
+
+Breakdown by cause:
+  Hold Timer Expired:          11 events (47.8%) — MOST COMMON
+  Interface flap:               4 events (17.4%)
+  Authentication mismatch:      3 events (13.0%)
+  Administrative reset (clear): 3 events (13.0%)
+  Peer AS mismatch:             1 event  ( 4.3%)
+  Maximum prefix exceeded:      1 event  ( 4.3%)
+
+Average session downtime by cause:
+  Hold Timer Expired:    28 seconds
+  Interface flap:         8 seconds
+  Authentication issue:  12 minutes (requires manual fix)
+  Peer AS mismatch:      37 minutes (requires ISP coordination)
+  Max prefix exceeded:   28 minutes (requires ISP to fix leak)
+
+Most stable peers (no resets):
+  - 10.0.0.2 CORE-RTR-02 iBGP: 1 reset (timer) + 1 reset (auth mismatch)
+  - 198.51.100.1 ISP-01 eBGP: 1 reset (auth incident)
+
+Most problematic peers:
+  - 203.0.113.5 ISP-02 eBGP: 3 resets (AS mismatch, max-prefix, auth)
+  - 203.0.113.1 ISP-03 eBGP: 4 resets (all interface flap related)
+
+Recommendations from 30-day analysis:
+  1. Increase hold timer from 30s to 90s to reduce false Hold Timer Expiry
+  2. Configure BFD on physical eBGP links for faster failure detection
+  3. Increase max-prefix limit on ISP-02 to 500K with 80% warning threshold
+  4. Schedule backup jobs at 05:00 UTC — CPU impact confirmed during 03:45 UTC slot
+  5. Implement change management procedure for BGP auth password updates (both sides simultaneously)
+  6. Add cluster-id to all Route Reflectors immediately
+
+BGP Table Statistics (end of month):
+  Total prefixes in RIB: 487,231
+  iBGP learned: 45,032
+  eBGP learned (ISP-01): 289,034
+  eBGP learned (ISP-02): 312,045
+  eBGP learned (ISP-03): 145,231
+  Locally originated: 12
+
+Router Memory Usage:
+  CORE-RTR-01: 4.2GB / 8GB (BGP table: 1.8GB)
+  CORE-RTR-02: 4.1GB / 8GB (BGP table: 1.8GB)
+  EDGE-RTR-01: 2.8GB / 8GB (BGP table: 1.2GB)
+  EDGE-RTR-02: 3.1GB / 8GB (BGP table: 1.4GB)

ingest.py

@@ -0,0 +1,123 @@
+"""
+ingest.py — Build FAISS vector index from BGP documentation.
+
+Run this ONCE locally before deploying to HuggingFace Spaces:
+    python ingest.py
+
+Output: faiss_index/index.faiss + faiss_index/index.pkl
+Commit both files to your repo — the Space loads them at startup.
+
+WHY PRE-BUILD?
+- Building the index requires downloading ~90MB sentence-transformers model
+  and embedding every chunk. On HF free CPU tier this takes 3-5 minutes
+  and risks OOM errors. Pre-building means the Space starts in ~3 seconds.
+- Pattern: compute expensive artifacts locally, ship the result.
+"""
+
+import os
+from pathlib import Path
+
+from langchain_community.document_loaders import TextLoader, DirectoryLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+
+
+# ── Configuration ────────────────────────────────────────────────────────────
+
+DATA_DIRS = ["data/docs", "data/telemetry"]
+INDEX_DIR = "faiss_index"
+EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+CHUNK_SIZE = 500
+CHUNK_OVERLAP = 50
+
+
+# ── Load documents ────────────────────────────────────────────────────────────
+
+def load_documents(data_dirs: list[str]) -> list:
+    """Load all .txt files from the given directories."""
+    all_docs = []
+    for data_dir in data_dirs:
+        if not os.path.exists(data_dir):
+            print(f"  ⚠️  Directory not found, skipping: {data_dir}")
+            continue
+        loader = DirectoryLoader(
+            data_dir,
+            glob="**/*.txt",
+            loader_cls=TextLoader,
+            loader_kwargs={"encoding": "utf-8"},
+            show_progress=False,
+        )
+        docs = loader.load()
+        print(f"  📂 {data_dir}: {len(docs)} file(s) loaded")
+        all_docs.extend(docs)
+    return all_docs
+
+
+# ── Main ──────────────────────────────────────────────────────────────────────
+
+def main():
+    print("=" * 60)
+    print("BGP RAG — FAISS Index Builder")
+    print("=" * 60)
+
+    # 1. Load raw documents
+    print("\n[1/4] Loading documents...")
+    docs = load_documents(DATA_DIRS)
+    if not docs:
+        raise RuntimeError("No documents found. Check data/ directory.")
+    print(f"  ✅ Total documents loaded: {len(docs)}")
+
+    # 2. Split into chunks
+    print(f"\n[2/4] Splitting into chunks (size={CHUNK_SIZE}, overlap={CHUNK_OVERLAP})...")
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        length_function=len,
+        separators=["\n\n", "\n", " ", ""],
+    )
+    chunks = splitter.split_documents(docs)
+    print(f"  ✅ Chunks created: {len(chunks)}")
+    print(f"  📊 Avg chunk size: {sum(len(c.page_content) for c in chunks) // len(chunks)} chars")
+
+    # 3. Create embeddings
+    print(f"\n[3/4] Loading embedding model: {EMBEDDING_MODEL}")
+    print("  (First run downloads ~90MB model — subsequent runs use cache)")
+    embeddings = HuggingFaceEmbeddings(
+        model_name=EMBEDDING_MODEL,
+        model_kwargs={"device": "cpu"},
+        encode_kwargs={"normalize_embeddings": True},
+    )
+    print("  ✅ Embedding model loaded")
+
+    # 4. Build and save FAISS index
+    print(f"\n[4/4] Building FAISS index and saving to {INDEX_DIR}/...")
+    os.makedirs(INDEX_DIR, exist_ok=True)
+    vectorstore = FAISS.from_documents(chunks, embeddings)
+    vectorstore.save_local(INDEX_DIR)
+
+    # Verify files were written
+    index_file = Path(INDEX_DIR) / "index.faiss"
+    pkl_file = Path(INDEX_DIR) / "index.pkl"
+    if index_file.exists() and pkl_file.exists():
+        size_mb = (index_file.stat().st_size + pkl_file.stat().st_size) / (1024 * 1024)
+        print(f"  ✅ Saved: {INDEX_DIR}/index.faiss")
+        print(f"  ✅ Saved: {INDEX_DIR}/index.pkl")
+        print(f"  📦 Total index size: {size_mb:.2f} MB")
+    else:
+        raise RuntimeError("Index files not found after save — check permissions.")
+
+    print("\n" + "=" * 60)
+    print("✅ FAISS index built successfully!")
+    print(f"   Documents: {len(docs)}")
+    print(f"   Chunks:    {len(chunks)}")
+    print(f"   Location:  {INDEX_DIR}/")
+    print("\nNext steps:")
+    print("  1. git add faiss_index/")
+    print("  2. git commit -m 'Add pre-built FAISS index'")
+    print("  3. Push to HuggingFace Space")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

rag_chain.py

@@ -0,0 +1,203 @@
+"""
+rag_chain.py — RAG chain using Groq (Llama 3.1) + pre-built FAISS index.
+
+HOW API KEY INJECTION WORKS:
+  os.environ.get("GROQ_API_KEY") reads the key from the process environment.
+  On HuggingFace Spaces, you set this in:
+    Space Settings → Variables and Secrets → New Secret → GROQ_API_KEY
+  HF injects it as an environment variable at container startup.
+  The key NEVER appears in your code or git history — only in HF's encrypted vault.
+  This is identical to how AWS Secrets Manager, GCP Secret Manager, and
+  Azure Key Vault work: code references a name, runtime provides the value.
+"""
+
+import os
+from pathlib import Path
+
+from langchain_groq import ChatGroq
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.runnables import RunnablePassthrough, RunnableParallel
+
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+
+INDEX_DIR = "faiss_index"
+EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+GROQ_MODEL = "llama-3.1-8b-instant"
+TOP_K_CHUNKS = 4
+
+BGP_PROMPT = ChatPromptTemplate.from_messages([
+    ("system",
+     "You are a Cisco network engineer specialising in BGP troubleshooting.\n"
+     "Answer questions based only on the provided documentation and telemetry logs.\n"
+     "Always suggest the relevant show command to verify the issue.\n"
+     "If the answer is not in the context, say clearly: "
+     "'This information is not in the knowledge base.'\n\n"
+     "Context:\n{context}"),
+    ("human", "{input}"),
+])
+
+
+# ── Load embeddings (cached after first call) ─────────────────────────────────
+
+_embeddings = None
+
+def get_embeddings() -> HuggingFaceEmbeddings:
+    """Return cached HuggingFaceEmbeddings instance."""
+    global _embeddings
+    if _embeddings is None:
+        _embeddings = HuggingFaceEmbeddings(
+            model_name=EMBEDDING_MODEL,
+            model_kwargs={"device": "cpu"},
+            encode_kwargs={"normalize_embeddings": True},
+        )
+    return _embeddings
+
+
+# ── Load FAISS vector store ───────────────────────────────────────────────────
+
+_vectorstore = None
+
+def _build_index():
+    """Build FAISS index from data/ files. Called automatically if index is missing."""
+    from langchain_community.document_loaders import DirectoryLoader, TextLoader
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+    print("Building FAISS index from documents...")
+    all_docs = []
+    for data_dir in ["data/docs", "data/telemetry"]:
+        if not os.path.exists(data_dir):
+            continue
+        loader = DirectoryLoader(
+            data_dir, glob="**/*.txt", loader_cls=TextLoader,
+            loader_kwargs={"encoding": "utf-8"}, show_progress=False,
+        )
+        all_docs.extend(loader.load())
+
+    splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
+    chunks = splitter.split_documents(all_docs)
+
+    vs = FAISS.from_documents(chunks, get_embeddings())
+    os.makedirs(INDEX_DIR, exist_ok=True)
+    vs.save_local(INDEX_DIR)
+    print(f"Index built — {len(chunks)} chunks saved to {INDEX_DIR}/")
+    return vs
+
+
+def get_vectorstore() -> FAISS:
+    """Load FAISS index, building it first if it doesn't exist."""
+    global _vectorstore
+    if _vectorstore is None:
+        if not Path(INDEX_DIR).exists():
+            # Auto-build on first run (e.g. HF Spaces where binary files can't be committed)
+            _vectorstore = _build_index()
+        else:
+            _vectorstore = FAISS.load_local(
+                INDEX_DIR,
+                get_embeddings(),
+                allow_dangerous_deserialization=True,
+            )
+    return _vectorstore
+
+
+# ── Build RAG chain ───────────────────────────────────────────────────────────
+
+_qa_chain = None
+
+def _format_docs(docs: list) -> str:
+    """Concatenate document chunks into a single context string."""
+    return "\n\n".join(doc.page_content for doc in docs)
+
+
+def get_qa_chain():
+    """Build and cache the RAG chain using pure LCEL (langchain-core only)."""
+    global _qa_chain
+    if _qa_chain is None:
+        llm = ChatGroq(
+            model=GROQ_MODEL,
+            api_key=os.environ.get("GROQ_API_KEY"),
+            temperature=0.1,
+            max_tokens=1024,
+        )
+
+        retriever = get_vectorstore().as_retriever(
+            search_type="similarity",
+            search_kwargs={"k": TOP_K_CHUNKS},
+        )
+
+        # LCEL chain — runs retriever and passthrough in parallel, then calls LLM
+        # RunnableParallel fetches context docs AND passes the question through simultaneously
+        # Result: {"answer": "...", "context": [doc, doc, ...]}
+        _qa_chain = RunnableParallel(
+            answer=(
+                {"context": retriever | _format_docs, "input": RunnablePassthrough()}
+                | BGP_PROMPT
+                | llm
+                | StrOutputParser()
+            ),
+            context=retriever,
+        )
+    return _qa_chain
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def query_bgp(question: str) -> dict:
+    """
+    Run a BGP question through the RAG pipeline.
+
+    Returns:
+        {
+            "answer": str,
+            "sources": list[str],   # Unique filenames of retrieved docs
+            "source_documents": list # Raw LangChain Document objects
+        }
+    """
+    chain = get_qa_chain()
+    # LCEL chain takes the question string directly
+    # Returns {"answer": str, "context": list[Document]}
+    result = chain.invoke(question)
+
+    source_docs = result.get("context", [])
+    sources = list(dict.fromkeys(
+        Path(doc.metadata.get("source", "unknown")).name
+        for doc in source_docs
+    ))
+
+    return {
+        "answer": result["answer"],
+        "sources": sources,
+        "source_documents": source_docs,
+    }
+
+
+def get_chunk_count() -> int:
+    """Return total number of chunks in the FAISS index (for sidebar display)."""
+    try:
+        vs = get_vectorstore()
+        return vs.index.ntotal
+    except Exception:
+        return 0
+
+
+# ── Quick test ────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+
+    if not os.environ.get("GROQ_API_KEY"):
+        print("❌ GROQ_API_KEY not set.")
+        print("   Export it: export GROQ_API_KEY=gsk_...")
+        sys.exit(1)
+
+    print("Loading RAG chain...")
+    test_question = "Why is my BGP neighbor stuck in IDLE state?"
+    print(f"\nQuestion: {test_question}\n")
+
+    result = query_bgp(test_question)
+    print("Answer:")
+    print(result["answer"])
+    print(f"\nSources retrieved: {result['sources']}")

requirements.txt

@@ -0,0 +1,34 @@
+# BGP RAG Chatbot — Cloud Edition
+# HuggingFace Spaces auto-installs these from requirements.txt at deploy time.
+#
+# WHY torch AND transformers?
+# sentence-transformers (used for HuggingFaceEmbeddings) is built on top of
+# the transformers library, which in turn requires PyTorch as its compute backend.
+# Even though we're not running a local LLM — Groq handles inference remotely —
+# the embedding model (all-MiniLM-L6-v2) runs locally inside the Space to convert
+# questions and documents into vectors. That local embedding step needs torch.
+# torch on CPU (faiss-cpu) is sufficient; no GPU required.
+
+# ── LangChain core ────────────────────────────────────────────────────────────
+langchain>=0.2.0
+langchain-community>=0.2.0
+langchain-text-splitters>=0.2.0
+langchain-groq>=0.1.6
+langchain-huggingface>=0.0.3
+
+# ── LLM inference (cloud) ────────────────────────────────────────────────────
+groq>=0.9.0
+
+# ── Embeddings (local, CPU) ──────────────────────────────────────────────────
+sentence-transformers>=2.7.0
+transformers>=4.40.0
+torch>=2.2.0
+torchvision>=0.17.0
+
+# ── Vector store ─────────────────────────────────────────────────────────────
+faiss-cpu>=1.8.0
+
+# ── UI ────────────────────────────────────────────────────────────────────────
+streamlit>=1.35.0
+python-dotenv>=1.0.0
+python-dotenv