bot

.gitignore

@@ -0,0 +1,12 @@
+# ChromaDB
+rag/chroma_db/
+memory/mem0_store/chroma_db/
+
+# SQLite
+*.sqlite3
+*.bin
+
+# Python
+__pycache__/
+.venv/
+.env

agents/comparison.py

@@ -0,0 +1,47 @@
+"""
+Comparison agent.
+
+Handles queries like "difference between BFS and DFS" — retrieves chunks
+per-topic (rather than pooled) so the prompt builder can present each
+topic's relevant sections side by side.
+"""
+
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def gather_comparison_context(topics: list, retriever, top_k_per_topic: int = None) -> dict:
+    """
+    Args:
+        topics: canonical topic names, e.g. ["Breadth-First Search", "Depth-First Search"].
+        retriever: a rag.retriever.Retriever instance.
+        top_k_per_topic: chunks to retrieve per topic (defaults to retriever/config default).
+
+    Returns:
+        {
+            "Breadth-First Search": [chunk, chunk, ...],
+            "Depth-First Search": [chunk, chunk, ...],
+        }
+        A topic with no chunks clearing the similarity threshold maps to [].
+    """
+    context = retriever.retrieve_topics(topics, top_k_per_topic=top_k_per_topic)
+
+    for topic, chunks in context.items():
+        if not chunks:
+            logger.warning(
+                "Comparison agent: no chunks passed the similarity threshold for topic %r",
+                topic,
+            )
+
+    return context
+
+
+def has_sufficient_context(comparison_context: dict) -> bool:
+    """
+    True only if every topic in the comparison has at least one retrieved
+    chunk. If any topic comes back empty, the caller should fall back to
+    the "insufficient information" response rather than comparing a topic
+    it knows nothing about against one it does.
+    """
+    return all(len(chunks) > 0 for chunks in comparison_context.values())

agents/followup.py

@@ -0,0 +1,68 @@
+"""
+Follow-up agent.
+
+Handles queries like "can you explain that again?" or "what about the
+space complexity?" that only make sense in light of recent conversation.
+
+Strategy: reuse recent conversation history as context by default, and
+only fall back to a fresh embedding-based retrieval if the follow-up
+mentions a topic that wasn't part of the recent conversation (e.g. user
+pivots to a new topic with a pronoun-only phrasing).
+"""
+
+from agents.intent_classifier import extract_topics,topics_in_recent_history
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+def gather_followup_context(
+    query: str,
+    recent_messages: list,
+    retriever,
+    top_k: int = None,
+) -> dict:
+    """
+    Args:
+        query: the current follow-up question.
+        recent_messages: recent conversation turns, oldest -> newest
+                         (see history/service.py for how these are fetched;
+                         bounded by config.MAX_RECENT_HISTORY_MESSAGES).
+        retriever: a rag.retriever.Retriever instance.
+        top_k: chunks to retrieve if a fresh lookup is needed.
+
+    Returns:
+        {
+            "reused_topics": [...],       # topics inferred from history
+            "additional_chunks": [...],   # only populated if a new topic
+                                           # was mentioned in `query` itself
+            "recent_messages": recent_messages,
+        }
+    """
+    reused_topics = topics_in_recent_history(recent_messages)
+
+    # Does the follow-up query itself introduce a topic not seen recently?
+    query_topics = extract_topics(query)
+    new_topics = [t for t in query_topics if t not in reused_topics]
+
+    additional_chunks = []
+    if new_topics:
+        logger.info(
+            "Follow-up query introduces new topic(s) not in recent history: %s",
+            new_topics,
+        )
+        for topic in new_topics:
+            additional_chunks.extend(
+                retriever.retrieve(query=query, top_k=top_k, topic_filter=[topic])
+            )
+    else:
+        logger.info(
+            "Follow-up query reuses existing conversation context (topics=%s); "
+            "skipping fresh retrieval.",
+            reused_topics,
+        )
+
+    return {
+        "reused_topics": reused_topics,
+        "additional_chunks": additional_chunks,
+        "recent_messages": recent_messages,
+    }

agents/intent_classifier.py

@@ -0,0 +1,208 @@
+"""
+Intent classification helpers used by the agent router.
+
+This module is intentionally rule-based (regex + fuzzy topic-name matching)
+rather than LLM-based, since the LLM provider abstraction (llm/) hasn't
+been wired in yet. It's isolated behind plain functions so it can be
+swapped for an LLM-based classifier later without changing router.py's
+interface — router.py only calls extract_topics(), is_comparison_query(),
+and is_followup_query().
+
+No keyword-based *retrieval* happens here — this only decides ROUTING.
+Actual knowledge retrieval is always embedding-based (see rag/retriever.py).
+"""
+
+import difflib
+import json
+import re
+
+import config
+
+# ---------------------------------------------------------------------------
+# Topic vocabulary (loaded once from topic_metadata.json)
+# ---------------------------------------------------------------------------
+
+_FUZZY_MATCH_CUTOFF = 0.85
+
+
+def _load_known_topics() -> list:
+    """Returns the list of canonical topic names, e.g. ['Binary Search', ...]."""
+    with open(config.TOPIC_METADATA_PATH, "r", encoding="utf-8") as f:
+        metadata = json.load(f)
+    return sorted({entry["topic"] for entry in metadata.values() if entry.get("topic")})
+
+
+_KNOWN_TOPICS = None
+
+
+def get_known_topics() -> list:
+    global _KNOWN_TOPICS
+    if _KNOWN_TOPICS is None:
+        _KNOWN_TOPICS = _load_known_topics()
+    return _KNOWN_TOPICS
+
+
+def refresh_known_topics() -> None:
+    """Call after topic_metadata.json changes (e.g. after a re-index) to
+    force reloading the topic vocabulary on next use."""
+    global _KNOWN_TOPICS
+    _KNOWN_TOPICS = None
+
+
+# ---------------------------------------------------------------------------
+# Comparison detection
+# ---------------------------------------------------------------------------
+
+_COMPARISON_PATTERNS = [
+    re.compile(r"\bdifference between\b", re.IGNORECASE),
+    re.compile(r"\bvs\.?\b", re.IGNORECASE),
+    re.compile(r"\bversus\b", re.IGNORECASE),
+    re.compile(r"\bcompare(d|s)?\b", re.IGNORECASE),
+    re.compile(r"\bwhich (one )?is (better|faster|more efficient)\b", re.IGNORECASE),
+    re.compile(r"\bpros and cons of\b", re.IGNORECASE),
+]
+
+
+def is_comparison_query(query: str) -> bool:
+    return any(p.search(query) for p in _COMPARISON_PATTERNS)
+
+
+# ---------------------------------------------------------------------------
+# Follow-up detection
+# ---------------------------------------------------------------------------
+
+_FOLLOWUP_PATTERNS = [
+    re.compile(r"^\s*(explain|say|show)?\s*(that|this|it)\b.*again\b", re.IGNORECASE),
+    re.compile(r"^\s*what (do you mean|about (that|it|this))\b", re.IGNORECASE),
+    re.compile(r"^\s*(can you|could you)\s+(clarify|elaborate|expand)\b", re.IGNORECASE),
+    re.compile(r"^\s*(and|so)\b", re.IGNORECASE),
+    re.compile(r"^\s*(why|how) (is that|does that work)\b", re.IGNORECASE),
+    re.compile(r"\b(more|another) example\b", re.IGNORECASE),
+    re.compile(r"^\s*(simpler|simplify|dumb it down|eli5)\b", re.IGNORECASE),
+]
+
+# Bare pronoun references with no topic name mentioned, e.g. "explain it",
+# "why is that", "tell me more"
+_PRONOUN_ONLY_PATTERN = re.compile(
+    r"\b(it|that|this|those|these)\b", re.IGNORECASE
+)
+
+_WORKED_EXAMPLE_PATTERN = re.compile(
+    r"\d+(?:\s*,\s*\d+){1,}.*\b(this|that|same)\b.*\b(search|sort|algorithm|method|approach|traversal)\b",
+    re.IGNORECASE,
+)
+
+def is_followup_query(query: str, has_conversation_history: bool) -> bool:
+    """
+    A query is treated as a follow-up when:
+      1. There IS prior conversation to follow up on, AND
+      2. Either it matches a known follow-up phrasing pattern, OR
+         it's short, contains a bare pronoun reference, and mentions no
+         known topic by name (i.e. it can't stand on its own).
+    """
+    if not has_conversation_history:
+        return False
+
+    if any(p.search(query) for p in _FOLLOWUP_PATTERNS):
+        return True
+
+    if _WORKED_EXAMPLE_PATTERN.search(query):
+        return True
+
+    word_count = len(query.strip().split())
+    has_pronoun = bool(_PRONOUN_ONLY_PATTERN.search(query))
+    mentions_topic = bool(extract_topics(query))
+
+    if has_pronoun and not mentions_topic and word_count <= 8:
+        return True
+
+    return False
+
+_GENERIC_COMPARISON_PATTERN = re.compile(
+    r"\b(compare|comparison|vs\.?|versus|difference|different from|how does .* (differ|compare))\b.*"
+    r"\b(other|similar|related|different|alternative)\b",
+    re.IGNORECASE,
+)
+
+
+def is_generic_comparison_followup(query: str) -> bool:
+    """
+    Matches comparison phrasing that references *other* algorithms without
+    naming a second one explicitly, e.g. "compare with other graph
+    algorithms", "how does this differ from similar approaches".
+    """
+    return bool(_GENERIC_COMPARISON_PATTERN.search(query))
+
+def topics_in_recent_history(recent_messages: list) -> list:
+    """
+    Scans recent conversation turns (both user and assistant messages) for
+    known topic mentions. Order preserved, most-recently-mentioned last.
+    """
+    topics = []
+    for message in recent_messages:
+        for topic in extract_topics(message.get("content", "")):
+            if topic not in topics:
+                topics.append(topic)
+            else:
+                topics.remove(topic)
+                topics.append(topic)  # bump to most-recent position
+    return topics
+
+
+# ---------------------------------------------------------------------------
+# Topic extraction (fuzzy match against known topic names)
+# ---------------------------------------------------------------------------
+
+def extract_topics(query: str) -> list:
+    """
+    Returns the list of known topic names mentioned in the query, matched
+    via substring + fuzzy matching (handles typos/casing/partial names like
+    "binary search" or "BFS traversal").
+
+    This is NOT used for retrieval (retrieval stays purely embedding-based)
+    — it's only used for ROUTING decisions: deciding single-topic vs.
+    comparison, and picking which topics a comparison should retrieve.
+    """
+    query_lower = query.lower()
+    found = []
+
+    for topic in get_known_topics():
+        topic_lower = topic.lower()
+        # Strip a trailing parenthetical, e.g. "Kruskal's Algorithm (MST)"
+        # -> "kruskal's algorithm", since people ask using the plain name,
+        # not the parenthetical qualifier.
+        topic_core = re.sub(r"\s*\([^)]*\)\s*$", "", topic_lower).strip()
+
+        # Direct substring match (full name or core name without qualifier)
+        if topic_lower in query_lower or (topic_core and topic_core in query_lower):
+            found.append(topic)
+            continue
+
+        # Acronym match, e.g. "Depth-First Search" -> "DFS", "Breadth-First
+        # Search" -> "BFS". Common in how people actually ask DSA questions.
+        acronym = "".join(w[0] for w in re.split(r"[\s\-]+", topic) if w).lower()
+        if len(acronym) >= 3 and re.search(rf"\b{re.escape(acronym)}\b", query_lower):
+            found.append(topic)
+            continue
+
+        # Fuzzy match against each sliding n-gram window of the query,
+        # sized to the topic's word count, to catch typos/near-matches.
+        topic_words = topic_lower.split()
+        query_words = query_lower.split()
+        window = len(topic_words)
+        for i in range(len(query_words) - window + 1):
+            candidate = " ".join(query_words[i : i + window])
+            ratio = difflib.SequenceMatcher(None, candidate, topic_lower).ratio()
+            if ratio >= _FUZZY_MATCH_CUTOFF:
+                found.append(topic)
+                break
+
+    # De-duplicate while preserving order
+    seen = set()
+    deduped = []
+    for t in found:
+        if t not in seen:
+            seen.add(t)
+            deduped.append(t)
+    return deduped
+

agents/router.py

@@ -0,0 +1,173 @@
+"""
+Agent router.
+
+Decides how each incoming query should be processed and gathers the
+context needed for the corresponding prompt builder (llm/prompts.py,
+built in a later layer). This module does NOT call the LLM — it only
+classifies + retrieves.
+
+Routes:
+    SINGLE_TOPIC  - e.g. "Explain Merge Sort"          -> retrieve one topic
+    COMPARISON    - e.g. "Difference between BFS/DFS"  -> retrieve multiple topics
+    FOLLOWUP      - e.g. "Can you explain that again?" -> reuse conversation context
+    OUT_OF_SCOPE  - e.g. "Who won the World Cup?"      -> reject politely
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from agents.comparison import gather_comparison_context, has_sufficient_context
+from agents.followup import gather_followup_context
+from agents.intent_classifier import (
+    extract_topics,
+    is_comparison_query,
+    is_followup_query,
+    is_generic_comparison_followup,
+    topics_in_recent_history,
+)
+from agents.topic_categories import get_sibling_topics
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class RouteType(str, Enum):
+    SINGLE_TOPIC = "single_topic"
+    COMPARISON = "comparison"
+    FOLLOWUP = "followup"
+    OUT_OF_SCOPE = "out_of_scope"
+
+
+@dataclass
+class RouteDecision:
+    route_type: RouteType
+    query: str
+    topics: list = field(default_factory=list)
+    # Populated by gather_context() below, per route type:
+    single_chunks: list = field(default_factory=list)
+    comparison_context: dict = field(default_factory=dict)
+    followup_context: dict = field(default_factory=dict)
+
+    def to_log_dict(self) -> dict:
+        return {
+            "route_type": self.route_type.value,
+            "query": self.query,
+            "topics": self.topics,
+        }
+
+
+def classify(query: str, has_conversation_history: bool = False, recent_topics: list = None) -> RouteDecision:
+    """
+    Pure classification step (no retrieval yet). Order matters:
+        1. Follow-up check first — a short pronoun-based query with existing
+            history should be treated as a follow-up even if it superficially
+            contains comparison words.
+        2. Comparison check — requires comparison phrasing AND 2+ topics.
+        3. Single topic — exactly one recognized topic mentioned.
+        4. Otherwise — out of scope.
+    """
+    recent_topics = recent_topics or []
+
+    if is_followup_query(query, has_conversation_history):
+        decision = RouteDecision(route_type=RouteType.FOLLOWUP, query=query)
+        logger.info("Routed to FOLLOWUP: %r", query)
+        return decision
+
+    topics = extract_topics(query)
+
+    if is_comparison_query(query) and len(topics) >= 2:
+        decision = RouteDecision(route_type=RouteType.COMPARISON, query=query, topics=topics)
+        logger.info("Routed to COMPARISON: %r | topics=%s", query, topics)
+        return decision
+
+    # NEW: comparison referencing the previous topic implicitly, e.g.
+    # "compare with other graph algorithms" after discussing BFS.
+    if is_generic_comparison_followup(query) and recent_topics:
+        anchor_topic = recent_topics[-1]
+        siblings = get_sibling_topics(anchor_topic, exclude=topics, limit=2)
+        combined = list(dict.fromkeys(topics + [anchor_topic] + siblings))
+        if len(combined) >= 2:
+            decision = RouteDecision(route_type=RouteType.COMPARISON, query=query, topics=combined)
+            logger.info(
+                "Routed to COMPARISON (category follow-up): %r | anchor=%s | topics=%s",
+                query, anchor_topic, combined,
+            )
+            return decision
+
+    if len(topics) >= 1:
+        decision = RouteDecision(route_type=RouteType.SINGLE_TOPIC, query=query, topics=topics[:1])
+        logger.info("Routed to SINGLE_TOPIC: %r | topic=%s", query, topics[0])
+        return decision
+
+    decision = RouteDecision(route_type=RouteType.OUT_OF_SCOPE, query=query)
+    logger.info("Routed to OUT_OF_SCOPE: %r", query)
+    return decision
+
+
+def gather_context(
+    decision: RouteDecision,
+    retriever,
+    recent_messages: list = None,
+) -> RouteDecision:
+    """
+    Populates the appropriate context field on `decision` based on its
+    route_type. Mutates and returns the same decision object.
+
+    Args:
+        decision: output of classify().
+        retriever: a rag.retriever.Retriever instance.
+        recent_messages: required for FOLLOWUP routes — recent conversation
+                          turns, oldest -> newest.
+    """
+    recent_messages = recent_messages or []
+
+    if decision.route_type == RouteType.SINGLE_TOPIC:
+        topic = decision.topics[0] if decision.topics else None
+        decision.single_chunks = retriever.retrieve(
+            query=decision.query,
+            topic_filter=[topic] if topic else None,
+            bypass_threshold_if_single_topic=True,  
+        )
+        if not decision.single_chunks:
+            logger.warning(
+                "SINGLE_TOPIC query had no chunks pass the similarity "
+                "threshold: %r",
+                decision.query,
+            )
+
+    elif decision.route_type == RouteType.COMPARISON:
+        decision.comparison_context = gather_comparison_context(decision.topics, retriever)
+        if not has_sufficient_context(decision.comparison_context):
+            logger.warning(
+                "COMPARISON query missing sufficient context for one or "
+                "more topics: %s",
+                decision.topics,
+            )
+
+    elif decision.route_type == RouteType.FOLLOWUP:
+        decision.followup_context = gather_followup_context(
+            query=decision.query,
+            recent_messages=recent_messages,
+            retriever=retriever,
+        )
+
+    # OUT_OF_SCOPE needs no retrieval.
+
+    return decision
+
+def route(query: str, retriever, recent_messages: list = None) -> RouteDecision:
+    """
+    Convenience entrypoint combining classify() + gather_context().
+
+    recent_messages: recent conversation turns (oldest -> newest). Presence
+    of any messages here signals "has_conversation_history=True" for
+    follow-up detection.
+    """
+    recent_messages = recent_messages or []
+    recent_topics = topics_in_recent_history(recent_messages)
+    decision = classify(
+        query,
+        has_conversation_history=len(recent_messages) > 0,
+        recent_topics=recent_topics,
+    )
+    return gather_context(decision, retriever, recent_messages=recent_messages)

agents/topic_categories.py

@@ -0,0 +1,56 @@
+"""
+Category lookups for topic_metadata.json.
+
+Used by the router to resolve "compare this with other X" style queries
+that reference the previous topic implicitly, without naming a second
+topic explicitly (e.g. "compare BFS with other graph algorithms").
+"""
+
+import json
+import os
+
+import config
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+_metadata_cache = None
+
+
+def _load_metadata() -> dict:
+    global _metadata_cache
+    if _metadata_cache is None:
+        if not os.path.exists(config.TOPIC_METADATA_PATH):
+            logger.warning("topic_metadata.json not found; category lookups disabled.")
+            _metadata_cache = {}
+        else:
+            with open(config.TOPIC_METADATA_PATH, "r", encoding="utf-8") as f:
+                _metadata_cache = json.load(f)
+    return _metadata_cache
+
+
+def get_category(topic_name: str) -> str | None:
+    """Returns the category string for a canonical topic name, or None."""
+    for entry in _load_metadata().values():
+        if entry.get("topic") == topic_name:
+            return entry.get("category")
+    return None
+
+
+def get_sibling_topics(topic_name: str, exclude: list = None, limit: int = 2) -> list:
+    """
+    Returns up to `limit` other topic names sharing the same category as
+    `topic_name` (e.g. siblings of "Breadth-First Search" in category
+    "Graph Traversal" -> ["Depth-First Search", "Dijkstra's Algorithm"]).
+    """
+    exclude = set(exclude or []) | {topic_name}
+    category = get_category(topic_name)
+    if not category:
+        return []
+
+    siblings = [
+        entry["topic"]
+        for entry in _load_metadata().values()
+        if entry.get("category") == category and entry.get("topic") not in exclude
+    ]
+    return siblings[:limit]

app.py

@@ -0,0 +1,94 @@
+"""
+Flask application entrypoint.
+
+At this stage of the build (Layer 1), only the database and authentication
+are wired up so this layer can be tested in isolation. Chat/RAG/agent
+routes will be added in later layers.
+"""
+# http://127.0.0.1:7860/
+
+
+import os
+import threading
+
+# Some corporate proxies / VPNs set HTTP_PROXY / HTTPS_PROXY, which makes
+# Gradio's internal "is localhost reachable" check fail even for 127.0.0.1.
+os.environ["NO_PROXY"] = "127.0.0.1,localhost," + os.environ.get("NO_PROXY", "")
+os.environ["no_proxy"] = os.environ["NO_PROXY"]
+
+# --- Workaround for a gradio_client bug (gradio 4.44.1 + newer pydantic) ---
+# When a schema (or a nested value like `additionalProperties`) is a plain
+# bool (True/False) rather than a dict, gradio_client's schema walker either
+# crashes with "TypeError: argument of type 'bool' is not iterable" or raises
+# "APIInfoParseError: Cannot parse schema True". This happens while Gradio
+# builds the page's embedded API info, unconditionally, on every request to
+# "/" - so it can't be avoided via show_api=False. Patch both entry points.
+import gradio_client.utils as _gc_utils
+
+_orig_get_type = _gc_utils.get_type
+_orig_json_schema_to_python_type = _gc_utils._json_schema_to_python_type
+
+
+def _safe_get_type(schema):
+    if isinstance(schema, bool):
+        return "Any"
+    return _orig_get_type(schema)
+
+
+def _safe_json_schema_to_python_type(schema, defs=None):
+    if isinstance(schema, bool):
+        return "Any"
+    return _orig_json_schema_to_python_type(schema, defs)
+
+
+_gc_utils.get_type = _safe_get_type
+_gc_utils._json_schema_to_python_type = _safe_json_schema_to_python_type
+# --- end workaround ---
+
+from flask import Flask
+
+import config
+from auth.db import init_db
+from auth.routes import auth_bp
+from chat_routes import chat_bp
+from ui.layout import build_ui
+
+
+def create_app():
+    app = Flask(__name__)
+
+    app.config["SECRET_KEY"] = config.SECRET_KEY
+    app.config["SQLALCHEMY_DATABASE_URI"] = config.SQLALCHEMY_DATABASE_URI
+    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = config.SQLALCHEMY_TRACK_MODIFICATIONS
+
+    init_db(app)
+
+    app.register_blueprint(auth_bp)
+    app.register_blueprint(chat_bp)
+
+    @app.route("/health")
+    def health():
+        return {"status": "ok"}
+
+    return app
+
+
+if __name__ == "__main__":
+    flask_app = create_app()
+
+    # Run the Flask REST API (auth + chat endpoints) on a background thread.
+    api_thread = threading.Thread(
+        target=lambda: flask_app.run(port=5000, debug=False, use_reloader=False),
+        daemon=True,
+    )
+    api_thread.start()
+
+    # Gradio UI is the main process. Its callbacks call into Flask
+    # in-process via app_context() (see ui/callbacks.py) rather than HTTP.
+    demo = build_ui(flask_app)
+    demo.queue().launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_api=False,
+        inbrowser=False,
+    )

auth/db.py

@@ -0,0 +1,22 @@
+"""
+Shared SQLAlchemy instance.
+
+Kept in its own module (rather than inside models.py or app.py) so that
+every part of the application — auth, history, etc. — can import the same
+`db` object without circular imports.
+"""
+
+from flask_sqlalchemy import SQLAlchemy
+
+db = SQLAlchemy()
+
+
+def init_db(app):
+    """Bind SQLAlchemy to the Flask app and create tables if they don't exist."""
+    db.init_app(app)
+    with app.app_context():
+        # Import models here so they're registered on db.metadata before create_all()
+        from auth.models import User  # noqa: F401
+        from history.models import ChatSession, ChatMessage  # noqa: F401
+
+        db.create_all()

auth/models.py

@@ -0,0 +1,41 @@
+"""
+User model for email/password authentication.
+
+No OAuth. No plaintext passwords — only Werkzeug password hashes are stored.
+"""
+
+from datetime import datetime
+
+from werkzeug.security import generate_password_hash, check_password_hash
+
+from auth.db import db
+
+
+class User(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    email = db.Column(db.String(255), unique=True, nullable=False, index=True)
+    password_hash = db.Column(db.String(255), nullable=False)
+    created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
+
+    # Relationship to chat sessions (defined in history/models.py)
+    chat_sessions = db.relationship(
+        "ChatSession", backref="user", lazy=True, cascade="all, delete-orphan"
+    )
+
+    def set_password(self, raw_password: str) -> None:
+        self.password_hash = generate_password_hash(raw_password)
+
+    def check_password(self, raw_password: str) -> bool:
+        return check_password_hash(self.password_hash, raw_password)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "email": self.email,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    def __repr__(self) -> str:
+        return f"<User id={self.id} email={self.email}>"

auth/routes.py

@@ -0,0 +1,87 @@
+"""
+Authentication REST endpoints.
+
+Routes:
+    POST /signup  -> create a new user account
+    POST /login   -> start a session-cookie-based login
+    POST /logout  -> clear the session
+    GET  /me      -> return the currently authenticated user, if any
+
+Session-based auth only: Flask's signed session cookie stores the user id.
+No tokens, no OAuth.
+"""
+
+import re
+
+from flask import Blueprint, request, jsonify, session
+
+from auth.db import db
+from auth.models import User
+
+auth_bp = Blueprint("auth", __name__)
+
+EMAIL_REGEX = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+MIN_PASSWORD_LENGTH = 8
+
+
+def _current_user():
+    user_id = session.get("user_id")
+    if user_id is None:
+        return None
+    return User.query.get(user_id)
+
+
+@auth_bp.route("/signup", methods=["POST"])
+def signup():
+    data = request.get_json(silent=True) or {}
+    email = (data.get("email") or "").strip().lower()
+    password = data.get("password") or ""
+
+    if not email or not EMAIL_REGEX.match(email):
+        return jsonify({"error": "A valid email is required."}), 400
+
+    if len(password) < MIN_PASSWORD_LENGTH:
+        return jsonify({
+            "error": f"Password must be at least {MIN_PASSWORD_LENGTH} characters."
+        }), 400
+
+    if User.query.filter_by(email=email).first() is not None:
+        return jsonify({"error": "An account with this email already exists."}), 409
+
+    user = User(email=email)
+    user.set_password(password)
+    db.session.add(user)
+    db.session.commit()
+
+    session["user_id"] = user.id
+
+    return jsonify({"message": "Account created.", "user": user.to_dict()}), 201
+
+
+@auth_bp.route("/login", methods=["POST"])
+def login():
+    data = request.get_json(silent=True) or {}
+    email = (data.get("email") or "").strip().lower()
+    password = data.get("password") or ""
+
+    user = User.query.filter_by(email=email).first()
+    if user is None or not user.check_password(password):
+        return jsonify({"error": "Invalid email or password."}), 401
+
+    session["user_id"] = user.id
+
+    return jsonify({"message": "Logged in.", "user": user.to_dict()}), 200
+
+
+@auth_bp.route("/logout", methods=["POST"])
+def logout():
+    session.pop("user_id", None)
+    return jsonify({"message": "Logged out."}), 200
+
+
+@auth_bp.route("/me", methods=["GET"])
+def me():
+    user = _current_user()
+    if user is None:
+        return jsonify({"user": None}), 200
+    return jsonify({"user": user.to_dict()}), 200

chat_routes.py

@@ -0,0 +1,82 @@
+"""
+Chat + session-history REST endpoints.
+
+Routes:
+    POST   /chat                 -> send a message, get a response
+    GET    /sessions             -> list the logged-in user's chat sessions
+    GET    /sessions/<id>        -> full transcript of one session
+    DELETE /sessions/<id>        -> delete a session
+
+Anonymous users can POST /chat (no persistence, no session panel per spec)
+but cannot access /sessions endpoints.
+"""
+
+from flask import Blueprint, jsonify, request, session
+
+from auth.models import User
+from chat_service import handle_chat_message
+from history import service as history_service
+
+chat_bp = Blueprint("chat", __name__)
+
+
+def _current_user():
+    user_id = session.get("user_id")
+    if user_id is None:
+        return None
+    return User.query.get(user_id)
+
+
+@chat_bp.route("/chat", methods=["POST"])
+def chat():
+    data = request.get_json(silent=True) or {}
+    query = (data.get("query") or "").strip()
+
+    if not query:
+        return jsonify({"error": "query is required."}), 400
+
+    user = _current_user()
+    session_id = data.get("session_id")
+    anonymous_history = data.get("history") if user is None else None
+
+    result = handle_chat_message(
+        query=query,
+        user=user,
+        session_id=session_id,
+        anonymous_history=anonymous_history,
+    )
+    return jsonify(result), 200
+
+
+@chat_bp.route("/sessions", methods=["GET"])
+def list_sessions():
+    user = _current_user()
+    if user is None:
+        return jsonify({"error": "Login required."}), 401
+    return jsonify({"sessions": history_service.list_sessions(user.id)}), 200
+
+
+@chat_bp.route("/sessions/<int:session_id>", methods=["GET"])
+def get_session_route(session_id):
+    user = _current_user()
+    if user is None:
+        return jsonify({"error": "Login required."}), 401
+
+    full_session = history_service.get_full_session(session_id, user.id)
+    if full_session is None:
+        return jsonify({"error": "Session not found."}), 404
+
+    return jsonify({"session": full_session}), 200
+
+
+@chat_bp.route("/sessions/<int:session_id>", methods=["DELETE"])
+def delete_session_route(session_id):
+    user = _current_user()
+    if user is None:
+        return jsonify({"error": "Login required."}), 401
+
+    deleted = history_service.delete_session(session_id, user.id)
+    if not deleted:
+        return jsonify({"error": "Session not found."}), 404
+
+    return jsonify({"message": "Session deleted."}), 200

chat_service.py

@@ -0,0 +1,126 @@
+"""
+Chat orchestration service.
+
+This is the single place that wires together everything built in the
+previous layers for one chat turn:
+
+    agents.router      -> classify + retrieve context
+    llm.prompts        -> build the right prompt for the route
+    llm.generate        -> call the configured LLM provider
+    memory.mem0_client  -> pull/store long-term preference memory (logged-in only)
+    history.service     -> persist the transcript (logged-in only)
+
+Kept separate from app.py so Flask routes stay thin, and so the same logic
+can be reused by the Gradio UI layer later without going through HTTP.
+"""
+
+import config
+from agents.router import RouteType, route
+from history import service as history_service
+from history.session_manager import resolve_session
+from llm.generate import generate
+from llm.prompts import (
+    build_comparison_prompt,
+    build_followup_prompt,
+    build_reject_prompt,
+    build_single_prompt,
+)
+from logs.logger import get_logger
+from memory.mem0_client import get_mem0_client
+from rag.retriever import get_retriever
+
+logger = get_logger(__name__)
+
+
+def _build_prompt(decision, mem0_context, recent_messages):
+    if decision.route_type == RouteType.SINGLE_TOPIC:
+        return build_single_prompt(
+            decision.single_chunks, mem0_context, recent_messages, decision.query
+        )
+    if decision.route_type == RouteType.COMPARISON:
+        return build_comparison_prompt(
+            decision.comparison_context, mem0_context, recent_messages, decision.query
+        )
+    if decision.route_type == RouteType.FOLLOWUP:
+        return build_followup_prompt(
+            decision.followup_context, mem0_context, recent_messages, decision.query
+        )
+    # OUT_OF_SCOPE
+    return build_reject_prompt(decision.query)
+
+
+def handle_chat_message(
+    query: str,
+    user=None,
+    session_id: int = None,
+    anonymous_history: list = None,
+) -> dict:
+    """
+    Args:
+        query: the user's message.
+        user: the authenticated auth.models.User, or None if anonymous.
+        session_id: existing chat session id (logged-in users only, optional).
+        anonymous_history: client-managed recent history for anonymous users
+                            (no server-side persistence — see spec: "when
+                            not logged in, chat works normally, no
+                            persistence, no history panel"). Ignored for
+                            logged-in users, whose history is read from
+                            SQLite instead.
+
+    Returns:
+        {
+            "response": "...",
+            "route_type": "single_topic" | "comparison" | "followup" | "out_of_scope",
+            "topics": [...],
+            "session_id": int | None,   # None for anonymous users
+        }
+    """
+    is_logged_in = user is not None
+    session_obj = None
+
+    if is_logged_in:
+        session_obj = resolve_session(user.id, session_id, first_message=query)
+        recent_messages = history_service.get_recent_messages(session_obj.id)
+    else:
+        recent_messages = (anonymous_history or [])[-config.MAX_RECENT_HISTORY_MESSAGES :]
+
+    retriever = get_retriever()
+    decision = route(query, retriever, recent_messages=recent_messages)
+
+    mem0_context = []
+    if is_logged_in:
+        mem0_context = get_mem0_client().get_relevant_context(str(user.id), query)
+
+    prompt = _build_prompt(decision, mem0_context, recent_messages)
+    response_text = generate(prompt)
+
+    if is_logged_in:
+        history_service.add_message(
+            session_obj.id,
+            role="user",
+            content=query,
+            route_type=decision.route_type.value,
+            retrieved_topics=decision.topics,
+        )
+        history_service.add_message(
+            session_obj.id,
+            role="assistant",
+            content=response_text,
+            route_type=decision.route_type.value,
+        )
+        get_mem0_client().add_interaction(str(user.id), query, response_text)
+
+    logger.info(
+        "Chat turn complete | user_id=%s | route=%s | topics=%s | session_id=%s",
+        user.id if is_logged_in else None,
+        decision.route_type.value,
+        decision.topics,
+        session_obj.id if session_obj else None,
+    )
+
+    return {
+        "response": response_text,
+        "route_type": decision.route_type.value,
+        "topics": decision.topics,
+        "session_id": session_obj.id if session_obj else None,
+    }

config.py

@@ -0,0 +1,90 @@
+"""
+Central configuration for the DSA RAG Chatbot.
+No magic numbers should be hardcoded anywhere else in the codebase — import from here.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+# ---------------------------------------------------------------------------
+# Flask / App
+# ---------------------------------------------------------------------------
+SECRET_KEY = os.getenv("SECRET_KEY", "dev-secret-key-change-me")
+SESSION_COOKIE_NAME = "dsa_chatbot_session"
+SESSION_LIFETIME_MINUTES = int(os.getenv("SESSION_LIFETIME_MINUTES", 60 * 24 * 7))  # 7 days
+
+# ---------------------------------------------------------------------------
+# Database (SQLite via SQLAlchemy)
+# ---------------------------------------------------------------------------
+DATABASE_PATH = os.path.join(BASE_DIR, "database", "app.db")
+SQLALCHEMY_DATABASE_URI = f"sqlite:///{DATABASE_PATH}"
+SQLALCHEMY_TRACK_MODIFICATIONS = False
+
+# ---------------------------------------------------------------------------
+# RAG / Knowledge base
+# ---------------------------------------------------------------------------
+KNOWLEDGE_BASE_DIR = os.path.join(BASE_DIR, "rag", "knowledge_base")
+TOPIC_METADATA_PATH = os.path.join(BASE_DIR, "rag", "knowledge_base", "topic_metadata.json")
+CHROMA_DB_DIR = os.path.join(BASE_DIR, "rag", "chroma_db")
+CHROMA_COLLECTION_NAME = "dsa_knowledge_base"
+
+EMBEDDING_MODEL_NAME = "all-MiniLM-L6-v2"
+
+# Sections expected inside each knowledge-base .txt file. Used by the chunker
+# to split on structure rather than arbitrary fixed-size windows.
+KB_SECTION_HEADERS = [
+    "DEFINITION",
+    "TIME_COMPLEXITY",
+    "SPACE_COMPLEXITY",
+    "USE_WHEN",
+    "EXAMPLE",
+]
+
+# ---------------------------------------------------------------------------
+# Retrieval pipeline
+# ---------------------------------------------------------------------------
+INITIAL_RETRIEVAL_K = int(os.getenv("INITIAL_RETRIEVAL_K", 15))
+TOP_K = int(os.getenv("TOP_K", 5))
+SIMILARITY_THRESHOLD = float(os.getenv("SIMILARITY_THRESHOLD", 0.45))
+
+# ---------------------------------------------------------------------------
+# Memory (mem0)
+# ---------------------------------------------------------------------------
+USE_MEM0 = os.getenv("USE_MEM0", "True") == "True"
+MEM0_LOCAL_STORAGE_DIR = os.path.join(BASE_DIR, "memory", "mem0_store")
+
+# ---------------------------------------------------------------------------
+# History / conversation
+# ---------------------------------------------------------------------------
+MAX_RECENT_HISTORY_MESSAGES = int(os.getenv("MAX_RECENT_HISTORY_MESSAGES", 6))
+
+# ---------------------------------------------------------------------------
+# LLM Provider
+# ---------------------------------------------------------------------------
+# "local" -> Mistral-7B-Instruct-v0.2 via transformers/bitsandbytes
+# "groq"  -> future Groq-hosted provider
+# "openai"-> future OpenAI provider
+# LLM_PROVIDER = os.getenv("LLM_PROVIDER", "local")
+LLM_PROVIDER = os.getenv("LLM_PROVIDER", "groq")
+
+LOCAL_MODEL_NAME = os.getenv("LOCAL_MODEL_NAME", "mistralai/Mistral-7B-Instruct-v0.2")
+LOCAL_MODEL_MAX_NEW_TOKENS = int(os.getenv("LOCAL_MODEL_MAX_NEW_TOKENS", 512))
+LOCAL_MODEL_TEMPERATURE = float(os.getenv("LOCAL_MODEL_TEMPERATURE", 0.3))
+LOCAL_MODEL_LOAD_IN_4BIT = os.getenv("LOCAL_MODEL_LOAD_IN_4BIT", "True") == "True"
+
+GROQ_API_KEY = os.getenv("GROQ_API_KEY")
+GROQ_MODEL_NAME = os.getenv("GROQ_MODEL_NAME", "llama-3.3-70b-versatile")
+
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
+OPENAI_MODEL_NAME = os.getenv("OPENAI_MODEL_NAME", "")
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+LOG_DIR = os.path.join(BASE_DIR, "logs")
+LOG_FILE_PATH = os.path.join(LOG_DIR, "app.log")
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")

evaluation/evaluate.py

@@ -0,0 +1,222 @@
+"""
+Evaluation harness for the DSA RAG chatbot.
+
+Runs the predefined question set (evaluation/questions.json) through the
+agent router + retriever (and optionally the full LLM pipeline) and reports:
+
+    - routing accuracy        (predicted route_type vs expected_route)
+    - retrieval topic recall  (expected topics found among retrieved chunks)
+    - retrieval latency       (avg / p95, ms)
+    - generation latency      (avg / p95, ms) -- only with --with-llm
+
+Usage:
+    python -m evaluation.evaluate
+    python -m evaluation.evaluate --with-llm
+    python -m evaluation.evaluate --questions evaluation/questions.json
+
+Run from the project root (dsa-rag-chatbot/) so `config` and the app
+packages resolve correctly.
+"""
+
+import argparse
+import json
+import os
+import statistics
+import time
+
+import config
+from agents.followup import gather_followup_context
+from agents.router import RouteType, classify, gather_context
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_QUESTIONS_PATH = os.path.join(os.path.dirname(__file__), "questions.json")
+
+# A tiny bit of fake prior conversation so the follow-up route can actually
+# be exercised (is_followup_query requires has_conversation_history=True).
+_FAKE_HISTORY_FOR_FOLLOWUPS = [
+    {"role": "user", "content": "Explain merge sort"},
+    {"role": "assistant", "content": "Merge sort is a divide-and-conquer sorting algorithm..."},
+]
+
+
+def _load_questions(path: str) -> list:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _percentile(values: list, pct: float) -> float:
+    if not values:
+        return 0.0
+    values = sorted(values)
+    k = (len(values) - 1) * (pct / 100)
+    f, c = int(k), min(int(k) + 1, len(values) - 1)
+    if f == c:
+        return values[f]
+    return values[f] + (k - f) * (values[c] - values[f])
+
+
+def _retrieved_topics(chunks: list) -> set:
+    return {c.get("metadata", {}).get("topic") for c in chunks if c.get("metadata", {}).get("topic")}
+
+
+def _topic_recall(expected_topics: list, retrieved: set) -> float:
+    if not expected_topics:
+        return 1.0  # nothing expected (e.g. out_of_scope) => trivially satisfied
+    hits = sum(1 for t in expected_topics if t in retrieved)
+    return hits / len(expected_topics)
+
+
+def evaluate_one(item: dict, retriever, with_llm: bool) -> dict:
+    query = item["query"]
+    expected_route = item["expected_route"]
+    expected_topics = item.get("expected_topics", [])
+    recent_messages = _FAKE_HISTORY_FOR_FOLLOWUPS if item.get("requires_history") else []
+
+    t0 = time.perf_counter()
+    decision = classify(query, has_conversation_history=len(recent_messages) > 0)
+    decision = gather_context(decision, retriever, recent_messages=recent_messages)
+    retrieval_latency_ms = (time.perf_counter() - t0) * 1000
+
+    if decision.route_type == RouteType.SINGLE_TOPIC:
+        retrieved = _retrieved_topics(decision.single_chunks)
+    elif decision.route_type == RouteType.COMPARISON:
+        retrieved = set()
+        for chunks in decision.comparison_context.values():
+            retrieved |= _retrieved_topics(chunks)
+    elif decision.route_type == RouteType.FOLLOWUP:
+        retrieved = _retrieved_topics(decision.followup_context.get("additional_chunks", []))
+    else:
+        retrieved = set()
+
+    route_correct = decision.route_type.value == expected_route
+    topic_recall = _topic_recall(expected_topics, retrieved)
+
+    result = {
+        "id": item.get("id"),
+        "query": query,
+        "expected_route": expected_route,
+        "predicted_route": decision.route_type.value,
+        "route_correct": route_correct,
+        "expected_topics": expected_topics,
+        "retrieved_topics": sorted(t for t in retrieved if t),
+        "topic_recall": round(topic_recall, 3),
+        "retrieval_latency_ms": round(retrieval_latency_ms, 2),
+    }
+
+    if with_llm:
+        from llm.generate import generate
+        from llm.prompts import (
+            build_comparison_prompt,
+            build_followup_prompt,
+            build_reject_prompt,
+            build_single_prompt,
+        )
+
+        if decision.route_type == RouteType.SINGLE_TOPIC:
+            prompt = build_single_prompt(decision.single_chunks, [], recent_messages, query)
+        elif decision.route_type == RouteType.COMPARISON:
+            prompt = build_comparison_prompt(decision.comparison_context, [], recent_messages, query)
+        elif decision.route_type == RouteType.FOLLOWUP:
+            prompt = build_followup_prompt(decision.followup_context, [], recent_messages, query)
+        else:
+            prompt = build_reject_prompt(query)
+
+        t1 = time.perf_counter()
+        try:
+            response_text = generate(prompt)
+            gen_error = None
+        except Exception as exc:  # keep the run going even if the LLM call fails
+            response_text = None
+            gen_error = str(exc)
+        generation_latency_ms = (time.perf_counter() - t1) * 1000
+
+        result["generation_latency_ms"] = round(generation_latency_ms, 2)
+        result["response_preview"] = (response_text or "")[:200]
+        if gen_error:
+            result["generation_error"] = gen_error
+
+    return result
+
+
+def run(questions_path: str = DEFAULT_QUESTIONS_PATH, with_llm: bool = False) -> dict:
+    from rag.retriever import get_retriever
+
+    questions = _load_questions(questions_path)
+    retriever = get_retriever()
+
+    results = [evaluate_one(item, retriever, with_llm) for item in questions]
+
+    route_accuracy = sum(r["route_correct"] for r in results) / len(results)
+    avg_topic_recall = statistics.mean(r["topic_recall"] for r in results)
+    retrieval_latencies = [r["retrieval_latency_ms"] for r in results]
+
+    summary = {
+        "total_questions": len(results),
+        "route_accuracy": round(route_accuracy, 3),
+        "avg_topic_recall": round(avg_topic_recall, 3),
+        "retrieval_latency_ms_avg": round(statistics.mean(retrieval_latencies), 2),
+        "retrieval_latency_ms_p95": round(_percentile(retrieval_latencies, 95), 2),
+    }
+
+    if with_llm:
+        gen_latencies = [r["generation_latency_ms"] for r in results if "generation_latency_ms" in r]
+        if gen_latencies:
+            summary["generation_latency_ms_avg"] = round(statistics.mean(gen_latencies), 2)
+            summary["generation_latency_ms_p95"] = round(_percentile(gen_latencies, 95), 2)
+        summary["generation_errors"] = sum(1 for r in results if r.get("generation_error"))
+
+    report = {"summary": summary, "results": results}
+
+    logger.info("Evaluation complete: %s", summary)
+    return report
+
+
+def _print_report(report: dict) -> None:
+    summary = report["summary"]
+    print("\n=== DSA RAG Chatbot — Evaluation Summary ===")
+    for key, value in summary.items():
+        print(f"  {key}: {value}")
+
+    print("\n=== Per-question results ===")
+    header = f"{'id':<5} {'route (exp->got)':<28} {'recall':<8} {'ret_ms':<8} query"
+    print(header)
+    print("-" * len(header))
+    for r in report["results"]:
+        route_str = f"{r['expected_route']} -> {r['predicted_route']}"
+        mark = "OK" if r["route_correct"] else "MISS"
+        print(
+            f"{r['id']:<5} {route_str:<28} {r['topic_recall']:<8} "
+            f"{r['retrieval_latency_ms']:<8} [{mark}] {r['query']}"
+        )
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Evaluate DSA RAG chatbot retrieval + routing.")
+    parser.add_argument(
+        "--questions", default=DEFAULT_QUESTIONS_PATH, help="Path to questions.json"
+    )
+    parser.add_argument(
+        "--with-llm",
+        action="store_true",
+        help="Also call the configured LLM provider end-to-end (uses API quota).",
+    )
+    parser.add_argument(
+        "--out",
+        default=None,
+        help="Path to write the full JSON report (default: evaluation/last_report.json)",
+    )
+    args = parser.parse_args()
+
+    report = run(questions_path=args.questions, with_llm=args.with_llm)
+    _print_report(report)
+
+    out_path = args.out or os.path.join(os.path.dirname(__file__), "last_report.json")
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(report, f, indent=2)
+    print(f"\nFull report written to: {out_path}")
+
+
+if __name__ == "__main__":
+    main()

evaluation/last_report.json

@@ -0,0 +1,302 @@
+{
+  "summary": {
+    "total_questions": 20,
+    "route_accuracy": 1.0,
+    "avg_topic_recall": 1.0,
+    "retrieval_latency_ms_avg": 46.26,
+    "retrieval_latency_ms_p95": 101.1
+  },
+  "results": [
+    {
+      "id": "q01",
+      "query": "Explain how binary search works",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Binary Search"
+      ],
+      "retrieved_topics": [
+        "Binary Search"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 144.79
+    },
+    {
+      "id": "q02",
+      "query": "What is the time complexity of merge sort?",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Merge Sort"
+      ],
+      "retrieved_topics": [
+        "Merge Sort"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 30.63
+    },
+    {
+      "id": "q03",
+      "query": "Explain quick sort with an example",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Quick Sort"
+      ],
+      "retrieved_topics": [
+        "Quick Sort"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 33.24
+    },
+    {
+      "id": "q04",
+      "query": "What is a Trie used for?",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Trie"
+      ],
+      "retrieved_topics": [
+        "Trie"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 31.99
+    },
+    {
+      "id": "q05",
+      "query": "What is a doubly linked list?",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Doubly Linked List"
+      ],
+      "retrieved_topics": [
+        "Doubly Linked List"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 34.44
+    },
+    {
+      "id": "q06",
+      "query": "Explain how a stack works",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Stack"
+      ],
+      "retrieved_topics": [
+        "Stack"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 28.98
+    },
+    {
+      "id": "q07",
+      "query": "What is topological sort used for?",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Topological Sort"
+      ],
+      "retrieved_topics": [
+        "Topological Sort"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 33.71
+    },
+    {
+      "id": "q08",
+      "query": "Explain Dijkstra's Algorithm",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Dijkstra's Algorithm"
+      ],
+      "retrieved_topics": [
+        "Dijkstra's Algorithm"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 27.78
+    },
+    {
+      "id": "q09",
+      "query": "What is a segment tree?",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Segment Tree"
+      ],
+      "retrieved_topics": [
+        "Segment Tree"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 35.57
+    },
+    {
+      "id": "q10",
+      "query": "Explain the sliding window technique",
+      "expected_route": "single_topic",
+      "predicted_route": "single_topic",
+      "route_correct": true,
+      "expected_topics": [
+        "Sliding Window Technique"
+      ],
+      "retrieved_topics": [
+        "Sliding Window Technique"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 34.67
+    },
+    {
+      "id": "q11",
+      "query": "What is the difference between BFS and DFS?",
+      "expected_route": "comparison",
+      "predicted_route": "comparison",
+      "route_correct": true,
+      "expected_topics": [
+        "Breadth-First Search",
+        "Depth-First Search"
+      ],
+      "retrieved_topics": [
+        "Breadth-First Search",
+        "Depth-First Search"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 51.73
+    },
+    {
+      "id": "q12",
+      "query": "Compare merge sort vs quick sort",
+      "expected_route": "comparison",
+      "predicted_route": "comparison",
+      "route_correct": true,
+      "expected_topics": [
+        "Merge Sort",
+        "Quick Sort"
+      ],
+      "retrieved_topics": [
+        "Merge Sort",
+        "Quick Sort"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 63.2
+    },
+    {
+      "id": "q13",
+      "query": "Difference between a stack and a queue",
+      "expected_route": "comparison",
+      "predicted_route": "comparison",
+      "route_correct": true,
+      "expected_topics": [
+        "Stack",
+        "Queue"
+      ],
+      "retrieved_topics": [
+        "Queue",
+        "Stack"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 66.79
+    },
+    {
+      "id": "q14",
+      "query": "Which one is better, Prim's Algorithm or Kruskal's Algorithm, for MST?",
+      "expected_route": "comparison",
+      "predicted_route": "comparison",
+      "route_correct": true,
+      "expected_topics": [
+        "Prim's Algorithm (MST)",
+        "Kruskal's Algorithm (MST)"
+      ],
+      "retrieved_topics": [
+        "Kruskal's Algorithm (MST)",
+        "Prim's Algorithm (MST)"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 98.8
+    },
+    {
+      "id": "q15",
+      "query": "Compare AVL Tree and Binary Search Tree",
+      "expected_route": "comparison",
+      "predicted_route": "comparison",
+      "route_correct": true,
+      "expected_topics": [
+        "AVL Tree",
+        "Binary Search Tree"
+      ],
+      "retrieved_topics": [
+        "AVL Tree",
+        "Binary Search",
+        "Binary Search Tree"
+      ],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 84.79
+    },
+    {
+      "id": "q16",
+      "query": "Who won the football World Cup in 2022?",
+      "expected_route": "out_of_scope",
+      "predicted_route": "out_of_scope",
+      "route_correct": true,
+      "expected_topics": [],
+      "retrieved_topics": [],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 23.85
+    },
+    {
+      "id": "q17",
+      "query": "What's a good recipe for chocolate cake?",
+      "expected_route": "out_of_scope",
+      "predicted_route": "out_of_scope",
+      "route_correct": true,
+      "expected_topics": [],
+      "retrieved_topics": [],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 16.91
+    },
+    {
+      "id": "q18",
+      "query": "What is the capital of France?",
+      "expected_route": "out_of_scope",
+      "predicted_route": "out_of_scope",
+      "route_correct": true,
+      "expected_topics": [],
+      "retrieved_topics": [],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 14.83
+    },
+    {
+      "id": "q19",
+      "query": "Can you explain that again?",
+      "expected_route": "followup",
+      "predicted_route": "followup",
+      "route_correct": true,
+      "expected_topics": [],
+      "retrieved_topics": [],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 44.24
+    },
+    {
+      "id": "q20",
+      "query": "Give me another example",
+      "expected_route": "followup",
+      "predicted_route": "followup",
+      "route_correct": true,
+      "expected_topics": [],
+      "retrieved_topics": [],
+      "topic_recall": 1.0,
+      "retrieval_latency_ms": 24.32
+    }
+  ]
+}

evaluation/questions.json

@@ -0,0 +1,124 @@
+[
+  {
+    "id": "q01",
+    "query": "Explain how binary search works",
+    "expected_route": "single_topic",
+    "expected_topics": ["Binary Search"]
+  },
+  {
+    "id": "q02",
+    "query": "What is the time complexity of merge sort?",
+    "expected_route": "single_topic",
+    "expected_topics": ["Merge Sort"]
+  },
+  {
+    "id": "q03",
+    "query": "Explain quick sort with an example",
+    "expected_route": "single_topic",
+    "expected_topics": ["Quick Sort"]
+  },
+  {
+    "id": "q04",
+    "query": "What is a Trie used for?",
+    "expected_route": "single_topic",
+    "expected_topics": ["Trie"]
+  },
+  {
+    "id": "q05",
+    "query": "What is a doubly linked list?",
+    "expected_route": "single_topic",
+    "expected_topics": ["Doubly Linked List"]
+  },
+  {
+    "id": "q06",
+    "query": "Explain how a stack works",
+    "expected_route": "single_topic",
+    "expected_topics": ["Stack"]
+  },
+  {
+    "id": "q07",
+    "query": "What is topological sort used for?",
+    "expected_route": "single_topic",
+    "expected_topics": ["Topological Sort"]
+  },
+  {
+    "id": "q08",
+    "query": "Explain Dijkstra's Algorithm",
+    "expected_route": "single_topic",
+    "expected_topics": ["Dijkstra's Algorithm"]
+  },
+  {
+    "id": "q09",
+    "query": "What is a segment tree?",
+    "expected_route": "single_topic",
+    "expected_topics": ["Segment Tree"]
+  },
+  {
+    "id": "q10",
+    "query": "Explain the sliding window technique",
+    "expected_route": "single_topic",
+    "expected_topics": ["Sliding Window Technique"]
+  },
+  {
+    "id": "q11",
+    "query": "What is the difference between BFS and DFS?",
+    "expected_route": "comparison",
+    "expected_topics": ["Breadth-First Search", "Depth-First Search"]
+  },
+  {
+    "id": "q12",
+    "query": "Compare merge sort vs quick sort",
+    "expected_route": "comparison",
+    "expected_topics": ["Merge Sort", "Quick Sort"]
+  },
+  {
+    "id": "q13",
+    "query": "Difference between a stack and a queue",
+    "expected_route": "comparison",
+    "expected_topics": ["Stack", "Queue"]
+  },
+  {
+    "id": "q14",
+    "query": "Which one is better, Prim's Algorithm or Kruskal's Algorithm, for MST?",
+    "expected_route": "comparison",
+    "expected_topics": ["Prim's Algorithm (MST)", "Kruskal's Algorithm (MST)"]
+  },
+  {
+    "id": "q15",
+    "query": "Compare AVL Tree and Binary Search Tree",
+    "expected_route": "comparison",
+    "expected_topics": ["AVL Tree", "Binary Search Tree"]
+  },
+  {
+    "id": "q16",
+    "query": "Who won the football World Cup in 2022?",
+    "expected_route": "out_of_scope",
+    "expected_topics": []
+  },
+  {
+    "id": "q17",
+    "query": "What's a good recipe for chocolate cake?",
+    "expected_route": "out_of_scope",
+    "expected_topics": []
+  },
+  {
+    "id": "q18",
+    "query": "What is the capital of France?",
+    "expected_route": "out_of_scope",
+    "expected_topics": []
+  },
+  {
+    "id": "q19",
+    "query": "Can you explain that again?",
+    "expected_route": "followup",
+    "expected_topics": [],
+    "requires_history": true
+  },
+  {
+    "id": "q20",
+    "query": "Give me another example",
+    "expected_route": "followup",
+    "expected_topics": [],
+    "requires_history": true
+  }
+]

history/models.py

@@ -0,0 +1,71 @@
+"""
+Chat history models.
+
+SQLite here is used ONLY for exact transcript storage (raw messages,
+timestamps, sessions). It must never store embeddings (that's ChromaDB)
+or user preference/long-term memory (that's mem0).
+"""
+
+from datetime import datetime
+
+from auth.db import db
+
+
+class ChatSession(db.Model):
+    __tablename__ = "chat_sessions"
+
+    id = db.Column(db.Integer, primary_key=True)
+    user_id = db.Column(db.Integer, db.ForeignKey("users.id"), nullable=False, index=True)
+    title = db.Column(db.String(255), nullable=True)  # e.g. first user message, truncated
+    created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = db.Column(
+        db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False
+    )
+
+    messages = db.relationship(
+        "ChatMessage",
+        backref="chat_session",
+        lazy=True,
+        order_by="ChatMessage.created_at",
+        cascade="all, delete-orphan",
+    )
+
+    def to_dict(self, include_messages: bool = False) -> dict:
+        result = {
+            "id": self.id,
+            "user_id": self.user_id,
+            "title": self.title,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }
+        if include_messages:
+            result["messages"] = [m.to_dict() for m in self.messages]
+        return result
+
+
+class ChatMessage(db.Model):
+    __tablename__ = "chat_messages"
+
+    id = db.Column(db.Integer, primary_key=True)
+    session_id = db.Column(
+        db.Integer, db.ForeignKey("chat_sessions.id"), nullable=False, index=True
+    )
+    role = db.Column(db.String(20), nullable=False)  # "user" or "assistant"
+    content = db.Column(db.Text, nullable=False)
+
+    # Optional debugging/eval metadata about how this response was produced.
+    route_type = db.Column(db.String(50), nullable=True)  # single/comparison/followup/reject
+    retrieved_topics = db.Column(db.Text, nullable=True)  # JSON-encoded list
+
+    created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "session_id": self.session_id,
+            "role": self.role,
+            "content": self.content,
+            "route_type": self.route_type,
+            "retrieved_topics": self.retrieved_topics,
+            "created_at": self.created_at.isoformat(),
+        }

history/service.py

@@ -0,0 +1,91 @@
+"""
+Chat history service.
+
+The only module that reads/writes history.models (ChatSession, ChatMessage).
+Callers (chat_service.py, chat_routes.py, the Gradio UI layer) go through
+these functions instead of touching the ORM directly, so persistence
+behavior stays in one place.
+
+Reminder of the scope boundary (see history/models.py): SQLite here is for
+exact transcript storage only — no embeddings, no long-term preference
+memory (that's ChromaDB / mem0 respectively).
+"""
+
+import json
+
+from auth.db import db
+from history.models import ChatMessage, ChatSession
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def add_message(
+    session_id: int,
+    role: str,
+    content: str,
+    route_type: str = None,
+    retrieved_topics: list = None,
+) -> ChatMessage:
+    """Append one message (user or assistant) to a session's transcript."""
+    message = ChatMessage(
+        session_id=session_id,
+        role=role,
+        content=content,
+        route_type=route_type,
+        retrieved_topics=json.dumps(retrieved_topics) if retrieved_topics else None,
+    )
+    db.session.add(message)
+    db.session.commit()
+    return message
+
+
+def get_recent_messages(session_id: int, limit: int = None) -> list:
+    """
+    Returns the most recent messages for a session, oldest -> newest, as
+    plain dicts ({"role": ..., "content": ...}) — the shape llm/prompts.py
+    and the follow-up agent expect.
+    """
+    import config
+
+    limit = limit or config.MAX_RECENT_HISTORY_MESSAGES
+
+    messages = (
+        ChatMessage.query.filter_by(session_id=session_id)
+        .order_by(ChatMessage.created_at.desc())
+        .limit(limit)
+        .all()
+    )
+    messages.reverse()
+    return [{"role": m.role, "content": m.content} for m in messages]
+
+
+def list_sessions(user_id: int) -> list:
+    """Returns a summary (no messages) of every chat session for a user,
+    most recently updated first — used for the history panel."""
+    sessions = (
+        ChatSession.query.filter_by(user_id=user_id)
+        .order_by(ChatSession.updated_at.desc())
+        .all()
+    )
+    return [s.to_dict(include_messages=False) for s in sessions]
+
+
+def get_full_session(session_id: int, user_id: int) -> dict:
+    """Returns the full transcript of one session, or None if it doesn't
+    exist or doesn't belong to this user."""
+    session_obj = ChatSession.query.filter_by(id=session_id, user_id=user_id).first()
+    if session_obj is None:
+        return None
+    return session_obj.to_dict(include_messages=True)
+
+
+def delete_session(session_id: int, user_id: int) -> bool:
+    """Deletes a session (and its messages, via cascade) if it belongs to
+    this user. Returns True if something was deleted."""
+    session_obj = ChatSession.query.filter_by(id=session_id, user_id=user_id).first()
+    if session_obj is None:
+        return False
+    db.session.delete(session_obj)
+    db.session.commit()
+    return True

history/session_manager.py

@@ -0,0 +1,46 @@
+"""
+Session resolution helper.
+
+Given a logged-in user and an optional client-supplied session_id, decides
+whether to reuse an existing ChatSession or create a new one. Kept separate
+from history/service.py so chat_service.py has one obvious entrypoint for
+"which session am I writing to?" without duplicating that logic per caller.
+"""
+
+from auth.db import db
+from history.models import ChatSession
+
+TITLE_MAX_LENGTH = 60
+
+
+def _make_title(first_message: str) -> str:
+    first_message = (first_message or "").strip()
+    if not first_message:
+        return "New chat"
+    if len(first_message) <= TITLE_MAX_LENGTH:
+        return first_message
+    return first_message[: TITLE_MAX_LENGTH - 1].rstrip() + "…"
+
+
+def resolve_session(user_id: int, session_id: int = None, first_message: str = "") -> ChatSession:
+    """
+    Args:
+        user_id: the authenticated user's id.
+        session_id: an existing session id the client wants to continue.
+                    Ignored (falls back to creating a new session) if it
+                    doesn't exist or doesn't belong to this user.
+        first_message: used as the auto-generated title when a new session
+                        is created.
+
+    Returns:
+        The ChatSession to append messages to (already committed, has .id).
+    """
+    if session_id is not None:
+        existing = ChatSession.query.filter_by(id=session_id, user_id=user_id).first()
+        if existing is not None:
+            return existing
+
+    session_obj = ChatSession(user_id=user_id, title=_make_title(first_message))
+    db.session.add(session_obj)
+    db.session.commit()
+    return session_obj

llm/generate.py

@@ -0,0 +1,64 @@
+"""
+Provider factory.
+
+This is the ONLY module the rest of the application should import to talk
+to an LLM. It picks the concrete provider based on config.LLM_PROVIDER and
+exposes a single generate(prompt) function. Swapping providers is a
+config change only.
+"""
+
+import config
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+_PROVIDER_SINGLETON = None
+
+
+def _build_provider():
+    provider_name = config.LLM_PROVIDER.lower()
+
+    if provider_name == "local":
+        from llm.local_provider import LocalMistralProvider
+
+        return LocalMistralProvider()
+
+    if provider_name == "groq":
+        from llm.groq_provider import GroqProvider
+
+        return GroqProvider()
+
+    if provider_name == "openai":
+        from llm.openai_provider import OpenAIProvider
+
+        return OpenAIProvider()
+
+    raise ValueError(
+        f"Unknown LLM_PROVIDER={provider_name!r} in config.py. "
+        "Expected one of: 'local', 'groq', 'openai'."
+    )
+
+
+def get_provider():
+    """Module-level singleton so the local model (if used) loads only once."""
+    global _PROVIDER_SINGLETON
+    if _PROVIDER_SINGLETON is None:
+        _PROVIDER_SINGLETON = _build_provider()
+        logger.info("LLM provider initialized: %s", _PROVIDER_SINGLETON.name())
+    return _PROVIDER_SINGLETON
+
+
+def generate(prompt: str, stream: bool = False):
+    """
+    The single entrypoint the rest of the app (Flask routes, agents,
+    evaluation) should call. Never import a provider class directly outside
+    of this module.
+    """
+    provider = get_provider()
+    return provider.generate(prompt, stream=stream)
+
+
+def reset_provider():
+    """Mainly for tests: force re-reading config.LLM_PROVIDER on next call."""
+    global _PROVIDER_SINGLETON
+    _PROVIDER_SINGLETON = None

llm/groq_provider.py

@@ -0,0 +1,82 @@
+"""
+Groq-hosted LLM provider.
+
+Implements the same generate(prompt, stream=False) interface as
+LocalMistralProvider, using Groq's OpenAI-compatible chat completions API.
+Nothing outside llm/generate.py should import this class directly — always
+go through llm.generate.generate().
+"""
+
+import config
+from llm.provider import LLMProvider
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class GroqProvider(LLMProvider):
+    def __init__(self):
+        if not config.GROQ_API_KEY:
+            raise ValueError(
+                "GROQ_API_KEY is not set in config/.env. Set it before using "
+                "LLM_PROVIDER=groq."
+            )
+
+        from groq import Groq
+
+        self._client = Groq(api_key=config.GROQ_API_KEY)
+        self._model = config.GROQ_MODEL_NAME
+
+    def generate(self, prompt: str, stream: bool = False):
+        """
+        Args:
+            prompt: the fully-constructed prompt string from llm/prompts.py.
+            stream: if True, returns a generator yielding text chunks as
+                    Groq streams them back. If False, returns the full
+                    response as a single string.
+        """
+        messages = [{"role": "user", "content": prompt}]
+
+        if stream:
+            return self._generate_stream(messages)
+        return self._generate_sync(messages)
+
+    def _generate_sync(self, messages) -> str:
+        try:
+            response = self._client.chat.completions.create(
+                model=self._model,
+                messages=messages,
+                temperature=config.LOCAL_MODEL_TEMPERATURE,
+                max_tokens=config.LOCAL_MODEL_MAX_NEW_TOKENS,
+                stream=False,
+            )
+        except Exception:
+            logger.exception("Groq API call failed (model=%s)", self._model)
+            return (
+                "Sorry, I couldn't reach the language model service right now. "
+                "Please try again in a moment."
+            )
+
+        return response.choices[0].message.content.strip()
+
+    def _generate_stream(self, messages):
+        try:
+            stream = self._client.chat.completions.create(
+                model=self._model,
+                messages=messages,
+                temperature=config.LOCAL_MODEL_TEMPERATURE,
+                max_tokens=config.LOCAL_MODEL_MAX_NEW_TOKENS,
+                stream=True,
+            )
+        except Exception:
+            logger.exception("Groq streaming API call failed (model=%s)", self._model)
+            yield (
+                "Sorry, I couldn't reach the language model service right now. "
+                "Please try again in a moment."
+            )
+            return
+
+        for chunk in stream:
+            delta = chunk.choices[0].delta.content if chunk.choices else None
+            if delta:
+                yield delta

llm/local_provider.py

@@ -0,0 +1,98 @@
+"""
+Local Mistral-7B-Instruct-v0.2 provider.
+
+Loads the model lazily (on first generate() call, not at import time) so
+importing this module never requires a GPU or downloaded weights — this
+keeps the rest of the codebase importable/testable without the model
+present.
+
+Requires: transformers, bitsandbytes, torch, accelerate (see requirements.txt)
+"""
+
+import config
+from llm.provider import LLMProvider
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class LocalMistralProvider(LLMProvider):
+    def __init__(self):
+        self._model = None
+        self._tokenizer = None
+
+    def _load(self):
+        """Lazy-load the model + tokenizer on first use."""
+        if self._model is not None:
+            return
+
+        logger.info("Loading local model %s ...", config.LOCAL_MODEL_NAME)
+
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
+
+        quantization_config = None
+        if config.LOCAL_MODEL_LOAD_IN_4BIT:
+            quantization_config = BitsAndBytesConfig(
+                load_in_4bit=True,
+                bnb_4bit_quant_type="nf4",
+                bnb_4bit_compute_dtype=torch.float16,
+                bnb_4bit_use_double_quant=True,
+            )
+
+        self._tokenizer = AutoTokenizer.from_pretrained(config.LOCAL_MODEL_NAME)
+        self._model = AutoModelForCausalLM.from_pretrained(
+            config.LOCAL_MODEL_NAME,
+            quantization_config=quantization_config,
+            device_map="auto",
+        )
+
+        logger.info("Local model loaded.")
+
+    def generate(self, prompt: str, stream: bool = False):
+        self._load()
+
+        import torch
+
+        inputs = self._tokenizer(prompt, return_tensors="pt").to(self._model.device)
+
+        if not stream:
+            with torch.no_grad():
+                output_ids = self._model.generate(
+                    **inputs,
+                    max_new_tokens=config.LOCAL_MODEL_MAX_NEW_TOKENS,
+                    temperature=config.LOCAL_MODEL_TEMPERATURE,
+                    do_sample=config.LOCAL_MODEL_TEMPERATURE > 0,
+                )
+            full_text = self._tokenizer.decode(
+                output_ids[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True
+            )
+            return full_text.strip()
+
+        return self._generate_streaming(inputs)
+
+    def _generate_streaming(self, inputs):
+        import threading
+
+        import torch
+        from transformers import TextIteratorStreamer
+
+        streamer = TextIteratorStreamer(
+            self._tokenizer, skip_prompt=True, skip_special_tokens=True
+        )
+
+        generation_kwargs = dict(
+            **inputs,
+            max_new_tokens=config.LOCAL_MODEL_MAX_NEW_TOKENS,
+            temperature=config.LOCAL_MODEL_TEMPERATURE,
+            do_sample=config.LOCAL_MODEL_TEMPERATURE > 0,
+            streamer=streamer,
+        )
+
+        thread = threading.Thread(target=self._model.generate, kwargs=generation_kwargs)
+        thread.start()
+
+        for text_chunk in streamer:
+            yield text_chunk
+
+        thread.join()

llm/prompts.py

@@ -0,0 +1,203 @@
+"""
+Prompt builders.
+
+Every prompt follows this fixed order:
+
+    System Prompt
+    -> Retrieved Context
+    -> Relevant mem0 Context
+    -> Recent Conversation History
+    -> Current User Question
+
+One builder per route type, so each route's prompt shape can evolve
+independently:
+
+    build_single_prompt()
+    build_comparison_prompt()
+    build_followup_prompt()
+    build_direct_prompt()
+    build_reject_prompt()
+
+These builders only assemble strings — they never call the LLM themselves
+(see llm/generate.py for that).
+"""
+
+SYSTEM_PROMPT = (
+    "You are a patient, precise Data Structures and Algorithms (DSA) tutor. "
+    "Answer using ONLY the information provided in the retrieved context below. "
+    "If the retrieved context does not contain enough information to answer "
+    "confidently, say so explicitly rather than guessing or inventing details. "
+    "Explain concepts clearly, use the time/space complexity and examples given "
+    "when relevant, and adapt your explanation style to any user preferences "
+    "provided in the memory context."
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared formatting helpers
+# ---------------------------------------------------------------------------
+
+def _format_chunks(chunks: list, heading: str = None) -> str:
+    if not chunks:
+        return ""
+    lines = []
+    if heading:
+        lines.append(f"### {heading}")
+    for chunk in chunks:
+        meta = chunk.get("metadata", {})
+        section = meta.get("section", "")
+        topic = meta.get("topic", "")
+        lines.append(f"[{topic} - {section}]\n{chunk.get('text', '')}")
+    return "\n\n".join(lines)
+
+
+def _format_mem0_context(mem0_context) -> str:
+    if not mem0_context:
+        return ""
+    if isinstance(mem0_context, str):
+        body = mem0_context
+    else:
+        # list of preference strings/facts returned by memory/mem0_client.py
+        body = "\n".join(f"- {item}" for item in mem0_context)
+    return f"### User Preferences / Memory\n{body}"
+
+
+def _format_history(recent_messages: list) -> str:
+    if not recent_messages:
+        return ""
+    lines = ["### Recent Conversation"]
+    for message in recent_messages:
+        role = message.get("role", "user").capitalize()
+        content = message.get("content", "")
+        lines.append(f"{role}: {content}")
+    return "\n".join(lines)
+
+
+def _assemble(*sections: str) -> str:
+    """Joins non-empty sections with blank lines, preserving fixed order."""
+    return "\n\n".join(s for s in sections if s)
+
+
+# ---------------------------------------------------------------------------
+# Per-route builders
+# ---------------------------------------------------------------------------
+
+def build_single_prompt(
+    chunks: list,
+    mem0_context=None,
+    recent_history: list = None,
+    query: str = "",
+) -> str:
+    """Single-topic route, e.g. 'Explain Merge Sort'."""
+    retrieved = _format_chunks(chunks, heading="Retrieved Context")
+    mem0_section = _format_mem0_context(mem0_context)
+    history_section = _format_history(recent_history)
+    question_section = f"### Current Question\n{query}"
+
+    return _assemble(
+        SYSTEM_PROMPT, retrieved, mem0_section, history_section, question_section
+    )
+
+
+def build_comparison_prompt(
+    comparison_context: dict,
+    mem0_context=None,
+    recent_history: list = None,
+    query: str = "",
+) -> str:
+    """Comparison route, e.g. 'Difference between BFS and DFS'."""
+    retrieved_sections = []
+    for topic, chunks in comparison_context.items():
+        retrieved_sections.append(_format_chunks(chunks, heading=f"Retrieved Context: {topic}"))
+    retrieved = "\n\n".join(s for s in retrieved_sections if s)
+
+    mem0_section = _format_mem0_context(mem0_context)
+    history_section = _format_history(recent_history)
+    question_section = f"### Current Question\n{query}"
+
+    instruction = (
+        "Compare the topics above directly: highlight the key differences in "
+        "definition, time/space complexity, and when to use each."
+    )
+
+    return _assemble(
+        SYSTEM_PROMPT, instruction, retrieved, mem0_section, history_section, question_section
+    )
+
+
+def build_followup_prompt(
+    followup_context: dict,
+    mem0_context=None,
+    recent_history: list = None,
+    query: str = "",
+) -> str:
+    """
+    Follow-up route, e.g. 'Can you explain that again?'. Reuses recent
+    conversation as primary context; only includes `additional_chunks` if
+    the follow-up agent decided a fresh retrieval was necessary.
+    """
+    additional_chunks = followup_context.get("additional_chunks", [])
+    retrieved = _format_chunks(additional_chunks, heading="Additional Retrieved Context")
+
+    mem0_section = _format_mem0_context(mem0_context)
+    # Prefer the followup_context's own recent_messages if the caller didn't
+    # pass a separate recent_history override.
+    history_section = _format_history(
+        recent_history or followup_context.get("recent_messages", [])
+    )
+    question_section = f"### Current Question\n{query}"
+
+    instruction = (
+        "This is a follow-up question. Use the recent conversation above to "
+        "understand what the user is referring to before answering."
+    )
+
+    WORKED_EXAMPLE_INSTRUCTION = (
+        "If the user provides their own concrete data (a list, array, or set of "
+        "numbers) and asks you to apply a search/sort/algorithm to it, walk "
+        "through the exact steps of the algorithm from the retrieved context "
+        "on their data. Do not substitute a different algorithm than the one "
+        "being discussed, even if their data doesn't perfectly fit it (e.g. "
+        "note if the list isn't sorted, but still apply the same algorithm's "
+        "logic unless the user explicitly asks for a different one)."
+    )
+
+    return _assemble(
+        SYSTEM_PROMPT, instruction, WORKED_EXAMPLE_INSTRUCTION, retrieved, mem0_section, history_section, question_section,
+    )
+
+
+def build_direct_prompt(
+    mem0_context=None,
+    recent_history: list = None,
+    query: str = "",
+) -> str:
+    """
+    Fallback builder for cases with no retrieved KB context at all (e.g. a
+    general greeting, or a follow-up so light it needs no context beyond
+    conversation history). Still follows the same section ordering, simply
+    omitting the "Retrieved Context" section.
+    """
+    mem0_section = _format_mem0_context(mem0_context)
+    history_section = _format_history(recent_history)
+    question_section = f"### Current Question\n{query}"
+
+    return _assemble(SYSTEM_PROMPT, mem0_section, history_section, question_section)
+
+
+def build_reject_prompt(query: str = "") -> str:
+    """
+    Out-of-scope route, e.g. 'Who won the World Cup?'. Kept deliberately
+    simple/static — no retrieved context, no memory, no history — since the
+    goal is just a polite, on-brand refusal, not a reasoned answer.
+    """
+    instruction = (
+        "The user's question is outside the scope of this DSA tutor "
+        "(it isn't a data structures / algorithms question, or the knowledge "
+        "base has no relevant information). Politely explain that you can "
+        "only help with Data Structures and Algorithms topics, and invite "
+        "them to ask a DSA-related question instead. Keep it brief and friendly."
+    )
+    question_section = f"### User's Message\n{query}"
+
+    return _assemble(SYSTEM_PROMPT, instruction, question_section)

llm/provider.py

@@ -0,0 +1,33 @@
+"""
+LLM provider interface.
+
+The rest of the application (router, chat endpoints, evaluation) must
+NEVER call a specific model directly. Everything goes through
+generate(prompt) on whatever provider is configured via
+config.LLM_PROVIDER. Switching from local Mistral to Groq or OpenAI later
+should require changing config only — no changes to callers.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class LLMProvider(ABC):
+    """Base interface every provider (local, groq, openai, ...) must implement."""
+
+    @abstractmethod
+    def generate(self, prompt: str, stream: bool = False):
+        """
+        Args:
+            prompt: the fully-constructed prompt string (see llm/prompts.py).
+            stream: if True, returns a generator yielding text chunks as
+                    they're produced, instead of a single string. Providers
+                    that can't stream should fall back to yielding the full
+                    response once.
+
+        Returns:
+            str if stream=False, otherwise a generator[str].
+        """
+        raise NotImplementedError
+
+    def name(self) -> str:
+        return self.__class__.__name__

logs/app.log

@@ -0,0 +1,440 @@
+2026-08-02 13:43:39,527 | INFO     | dsa_chatbot.__main__ | Loading embedding model: all-MiniLM-L6-v2
+2026-08-02 13:44:07,549 | WARNING  | dsa_chatbot.__main__ | The following KB files have no topic_metadata.json entry and will be skipped: ['01_knapsack.txt', 'activity_selection_problem.txt', 'backtracking_overview.txt', 'bit_manipulation_basics.txt', 'coin_change_problem.txt', 'dijkstras_algorithm.txt', 'dynamic_programming_overview.txt', 'edit_distance.txt', 'fractional_knapsack.txt', 'greedy_algorithms_overview.txt', 'hash_set_vs_hash_map.txt', 'hash_table.txt', 'kruskals_algorithm_mst.txt', 'longest_common_subsequence.txt', 'longest_increasing_subsequence.txt', 'n-queens_problem.txt', 'prims_algorithm_mst.txt', 'recursion_overview.txt', 'subset_sum_power_set_generation.txt', 'xor_tricks.txt']
+2026-08-02 13:44:08,102 | INFO     | dsa_chatbot.__main__ | Built 98 chunks from 54 knowledge-base files.
+2026-08-02 13:44:08,102 | INFO     | dsa_chatbot.__main__ | Embedding 98 chunks...
+2026-08-02 13:44:13,562 | INFO     | dsa_chatbot.__main__ | Index build complete. Collection 'dsa_knowledge_base' now has 98 chunks.
+2026-08-02 13:45:19,505 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how binary search works' | topic=Binary Search
+2026-08-02 13:45:19,648 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how binary search works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:19,658 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is the time complexity of merge sort?' | topic=Insertion Sort
+2026-08-02 13:45:19,680 | INFO     | dsa_chatbot.rag.retriever | Query='What is the time complexity of merge sort?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:19,681 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is the time complexity of merge sort?'
+2026-08-02 13:45:19,688 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain quick sort with an example' | topic=Bucket Sort
+2026-08-02 13:45:19,718 | INFO     | dsa_chatbot.rag.retriever | Query='Explain quick sort with an example' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:19,727 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a Trie used for?' | topic=Insertion Sort
+2026-08-02 13:45:19,752 | INFO     | dsa_chatbot.rag.retriever | Query='What is a Trie used for?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:19,753 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is a Trie used for?'
+2026-08-02 13:45:19,763 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a doubly linked list?' | topic=Doubly Linked List
+2026-08-02 13:45:19,791 | INFO     | dsa_chatbot.rag.retriever | Query='What is a doubly linked list?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:19,796 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how a stack works' | topic=Stack
+2026-08-02 13:45:19,817 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how a stack works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:19,825 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is topological sort used for?' | topic=Insertion Sort
+2026-08-02 13:45:19,848 | INFO     | dsa_chatbot.rag.retriever | Query='What is topological sort used for?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:19,852 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: "Explain Dijkstra's Algorithm" | topic=Dijkstra's Algorithm
+2026-08-02 13:45:19,899 | INFO     | dsa_chatbot.rag.retriever | Query="Explain Dijkstra's Algorithm" | candidates=0 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:19,899 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: "Explain Dijkstra's Algorithm"
+2026-08-02 13:45:19,905 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a segment tree?' | topic=Insertion Sort
+2026-08-02 13:45:19,929 | INFO     | dsa_chatbot.rag.retriever | Query='What is a segment tree?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:19,929 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is a segment tree?'
+2026-08-02 13:45:19,935 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain the sliding window technique' | topic=Sliding Window Technique
+2026-08-02 13:45:19,958 | INFO     | dsa_chatbot.rag.retriever | Query='Explain the sliding window technique' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:19,966 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'What is the difference between BFS and DFS?' | topics=['Breadth-First Search', 'Depth-First Search', 'Insertion Sort']
+2026-08-02 13:45:19,995 | INFO     | dsa_chatbot.rag.retriever | Query='Breadth-First Search' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 13:45:20,013 | INFO     | dsa_chatbot.rag.retriever | Query='Depth-First Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,033 | INFO     | dsa_chatbot.rag.retriever | Query='Insertion Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,042 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare merge sort vs quick sort' | topics=['Bucket Sort', 'Merge Sort', 'Quick Sort']
+2026-08-02 13:45:20,062 | INFO     | dsa_chatbot.rag.retriever | Query='Bucket Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,087 | INFO     | dsa_chatbot.rag.retriever | Query='Merge Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,107 | INFO     | dsa_chatbot.rag.retriever | Query='Quick Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,115 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Difference between a stack and a queue' | topics=['Queue', 'Stack']
+2026-08-02 13:45:20,168 | INFO     | dsa_chatbot.rag.retriever | Query='Queue' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 13:45:20,190 | INFO     | dsa_chatbot.rag.retriever | Query='Stack' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,215 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: "Which one is better, Prim's Algorithm or Kruskal's Algorithm, for MST?" | topics=["Dijkstra's Algorithm", 'Insertion Sort', "Kruskal's Algorithm (MST)", "Prim's Algorithm (MST)"]
+2026-08-02 13:45:20,245 | INFO     | dsa_chatbot.rag.retriever | Query="Dijkstra's Algorithm" | candidates=0 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:20,271 | INFO     | dsa_chatbot.rag.retriever | Query='Insertion Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,305 | INFO     | dsa_chatbot.rag.retriever | Query="Kruskal's Algorithm (MST)" | candidates=0 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:20,330 | INFO     | dsa_chatbot.rag.retriever | Query="Prim's Algorithm (MST)" | candidates=0 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:20,330 | WARNING  | dsa_chatbot.agents.comparison | Comparison agent: no chunks passed the similarity threshold for topic "Dijkstra's Algorithm"
+2026-08-02 13:45:20,330 | WARNING  | dsa_chatbot.agents.comparison | Comparison agent: no chunks passed the similarity threshold for topic "Kruskal's Algorithm (MST)"
+2026-08-02 13:45:20,330 | WARNING  | dsa_chatbot.agents.comparison | Comparison agent: no chunks passed the similarity threshold for topic "Prim's Algorithm (MST)"
+2026-08-02 13:45:20,331 | WARNING  | dsa_chatbot.agents.router | COMPARISON query missing sufficient context for one or more topics: ["Dijkstra's Algorithm", 'Insertion Sort', "Kruskal's Algorithm (MST)", "Prim's Algorithm (MST)"]
+2026-08-02 13:45:20,341 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare AVL Tree and Binary Search Tree' | topics=['AVL Tree', 'Binary Search', 'Binary Search Tree', 'Linear Search', 'Trie']
+2026-08-02 13:45:20,362 | INFO     | dsa_chatbot.rag.retriever | Query='AVL Tree' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 13:45:20,380 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,403 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search Tree' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,426 | INFO     | dsa_chatbot.rag.retriever | Query='Linear Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 13:45:20,448 | INFO     | dsa_chatbot.rag.retriever | Query='Trie' | candidates=5 | passed_threshold=4 | threshold=0.45
+2026-08-02 13:45:20,459 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'Who won the football World Cup in 2022?'
+2026-08-02 13:45:20,466 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: "What's a good recipe for chocolate cake?"
+2026-08-02 13:45:20,474 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is the capital of France?' | topic=Insertion Sort
+2026-08-02 13:45:20,495 | INFO     | dsa_chatbot.rag.retriever | Query='What is the capital of France?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 13:45:20,495 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is the capital of France?'
+2026-08-02 13:45:20,499 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'Can you explain that again?'
+2026-08-02 13:45:20,517 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Merge Sort', 'Insertion Sort']); skipping fresh retrieval.
+2026-08-02 13:45:20,530 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'Give me another example'
+2026-08-02 13:45:20,531 | INFO     | dsa_chatbot.__main__ | Evaluation complete: {'total_questions': 20, 'route_accuracy': 0.9, 'avg_topic_recall': 0.65, 'retrieval_latency_ms_avg': 51.74, 'retrieval_latency_ms_p95': 140.89}
+2026-08-02 13:59:25,086 | INFO     | dsa_chatbot.__main__ | Loading embedding model: all-MiniLM-L6-v2
+2026-08-02 13:59:31,186 | INFO     | dsa_chatbot.__main__ | Existing collection 'dsa_knowledge_base' deleted.
+2026-08-02 13:59:31,554 | INFO     | dsa_chatbot.__main__ | Built 150 chunks from 54 knowledge-base files.
+2026-08-02 13:59:31,555 | INFO     | dsa_chatbot.__main__ | Embedding 150 chunks...
+2026-08-02 13:59:39,737 | INFO     | dsa_chatbot.__main__ | Index build complete. Collection 'dsa_knowledge_base' now has 150 chunks.
+2026-08-02 14:00:37,066 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how binary search works' | topic=Binary Search
+2026-08-02 14:00:37,234 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how binary search works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,248 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is the time complexity of merge sort?' | topic=Insertion Sort
+2026-08-02 14:00:37,273 | INFO     | dsa_chatbot.rag.retriever | Query='What is the time complexity of merge sort?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 14:00:37,274 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is the time complexity of merge sort?'
+2026-08-02 14:00:37,288 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain quick sort with an example' | topic=Bucket Sort
+2026-08-02 14:00:37,310 | INFO     | dsa_chatbot.rag.retriever | Query='Explain quick sort with an example' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,321 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a Trie used for?' | topic=Insertion Sort
+2026-08-02 14:00:37,345 | INFO     | dsa_chatbot.rag.retriever | Query='What is a Trie used for?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 14:00:37,346 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is a Trie used for?'
+2026-08-02 14:00:37,357 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a doubly linked list?' | topic=Doubly Linked List
+2026-08-02 14:00:37,378 | INFO     | dsa_chatbot.rag.retriever | Query='What is a doubly linked list?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,386 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how a stack works' | topic=Stack
+2026-08-02 14:00:37,405 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how a stack works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,415 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is topological sort used for?' | topic=Insertion Sort
+2026-08-02 14:00:37,433 | INFO     | dsa_chatbot.rag.retriever | Query='What is topological sort used for?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,439 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: "Explain Dijkstra's Algorithm" | topic=Dijkstra's Algorithm
+2026-08-02 14:00:37,463 | INFO     | dsa_chatbot.rag.retriever | Query="Explain Dijkstra's Algorithm" | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,471 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a segment tree?' | topic=Insertion Sort
+2026-08-02 14:00:37,493 | INFO     | dsa_chatbot.rag.retriever | Query='What is a segment tree?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 14:00:37,494 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is a segment tree?'
+2026-08-02 14:00:37,501 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain the sliding window technique' | topic=Sliding Window Technique
+2026-08-02 14:00:37,521 | INFO     | dsa_chatbot.rag.retriever | Query='Explain the sliding window technique' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,539 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'What is the difference between BFS and DFS?' | topics=['Breadth-First Search', 'Depth-First Search', 'Insertion Sort']
+2026-08-02 14:00:37,597 | INFO     | dsa_chatbot.rag.retriever | Query='Breadth-First Search' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:00:37,624 | INFO     | dsa_chatbot.rag.retriever | Query='Depth-First Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,647 | INFO     | dsa_chatbot.rag.retriever | Query='Insertion Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,666 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare merge sort vs quick sort' | topics=['Bucket Sort', 'Merge Sort', 'Quick Sort']
+2026-08-02 14:00:37,699 | INFO     | dsa_chatbot.rag.retriever | Query='Bucket Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,725 | INFO     | dsa_chatbot.rag.retriever | Query='Merge Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,751 | INFO     | dsa_chatbot.rag.retriever | Query='Quick Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,767 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Difference between a stack and a queue' | topics=['Queue', 'Stack']
+2026-08-02 14:00:37,821 | INFO     | dsa_chatbot.rag.retriever | Query='Queue' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:00:37,851 | INFO     | dsa_chatbot.rag.retriever | Query='Stack' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,892 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: "Which one is better, Prim's Algorithm or Kruskal's Algorithm, for MST?" | topics=["Dijkstra's Algorithm", 'Insertion Sort', "Kruskal's Algorithm (MST)", "Prim's Algorithm (MST)"]
+2026-08-02 14:00:37,919 | INFO     | dsa_chatbot.rag.retriever | Query="Dijkstra's Algorithm" | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,944 | INFO     | dsa_chatbot.rag.retriever | Query='Insertion Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:37,977 | INFO     | dsa_chatbot.rag.retriever | Query="Kruskal's Algorithm (MST)" | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:00:38,005 | INFO     | dsa_chatbot.rag.retriever | Query="Prim's Algorithm (MST)" | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:00:38,022 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare AVL Tree and Binary Search Tree' | topics=['AVL Tree', 'Binary Search', 'Binary Search Tree', 'Linear Search', 'Trie']
+2026-08-02 14:00:38,043 | INFO     | dsa_chatbot.rag.retriever | Query='AVL Tree' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:00:38,058 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:38,081 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search Tree' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:38,109 | INFO     | dsa_chatbot.rag.retriever | Query='Linear Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:00:38,126 | INFO     | dsa_chatbot.rag.retriever | Query='Trie' | candidates=5 | passed_threshold=4 | threshold=0.45
+2026-08-02 14:00:38,138 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'Who won the football World Cup in 2022?'
+2026-08-02 14:00:38,152 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: "What's a good recipe for chocolate cake?"
+2026-08-02 14:00:38,164 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is the capital of France?' | topic=Insertion Sort
+2026-08-02 14:00:38,186 | INFO     | dsa_chatbot.rag.retriever | Query='What is the capital of France?' | candidates=1 | passed_threshold=0 | threshold=0.45
+2026-08-02 14:00:38,186 | WARNING  | dsa_chatbot.agents.router | SINGLE_TOPIC query had no chunks pass the similarity threshold: 'What is the capital of France?'
+2026-08-02 14:00:38,195 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'Can you explain that again?'
+2026-08-02 14:00:38,226 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Merge Sort', 'Insertion Sort']); skipping fresh retrieval.
+2026-08-02 14:00:38,236 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'Give me another example'
+2026-08-02 14:00:38,237 | INFO     | dsa_chatbot.__main__ | Evaluation complete: {'total_questions': 20, 'route_accuracy': 0.9, 'avg_topic_recall': 0.75, 'retrieval_latency_ms_avg': 59.26, 'retrieval_latency_ms_p95': 155.61}
+2026-08-02 14:03:52,099 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how binary search works' | topic=Binary Search
+2026-08-02 14:03:52,274 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how binary search works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,288 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is the time complexity of merge sort?' | topic=Merge Sort
+2026-08-02 14:03:52,311 | INFO     | dsa_chatbot.rag.retriever | Query='What is the time complexity of merge sort?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,324 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain quick sort with an example' | topic=Quick Sort
+2026-08-02 14:03:52,350 | INFO     | dsa_chatbot.rag.retriever | Query='Explain quick sort with an example' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,362 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a Trie used for?' | topic=Trie
+2026-08-02 14:03:52,384 | INFO     | dsa_chatbot.rag.retriever | Query='What is a Trie used for?' | candidates=5 | passed_threshold=4 | threshold=0.45
+2026-08-02 14:03:52,398 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a doubly linked list?' | topic=Doubly Linked List
+2026-08-02 14:03:52,419 | INFO     | dsa_chatbot.rag.retriever | Query='What is a doubly linked list?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,430 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how a stack works' | topic=Stack
+2026-08-02 14:03:52,450 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how a stack works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,462 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is topological sort used for?' | topic=Topological Sort
+2026-08-02 14:03:52,483 | INFO     | dsa_chatbot.rag.retriever | Query='What is topological sort used for?' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:03:52,490 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: "Explain Dijkstra's Algorithm" | topic=Dijkstra's Algorithm
+2026-08-02 14:03:52,516 | INFO     | dsa_chatbot.rag.retriever | Query="Explain Dijkstra's Algorithm" | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,522 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a segment tree?' | topic=Segment Tree
+2026-08-02 14:03:52,547 | INFO     | dsa_chatbot.rag.retriever | Query='What is a segment tree?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,561 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain the sliding window technique' | topic=Sliding Window Technique
+2026-08-02 14:03:52,582 | INFO     | dsa_chatbot.rag.retriever | Query='Explain the sliding window technique' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,605 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'What is the difference between BFS and DFS?' | topics=['Breadth-First Search', 'Depth-First Search']
+2026-08-02 14:03:52,627 | INFO     | dsa_chatbot.rag.retriever | Query='Breadth-First Search' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:03:52,649 | INFO     | dsa_chatbot.rag.retriever | Query='Depth-First Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,662 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare merge sort vs quick sort' | topics=['Merge Sort', 'Quick Sort']
+2026-08-02 14:03:52,685 | INFO     | dsa_chatbot.rag.retriever | Query='Merge Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,706 | INFO     | dsa_chatbot.rag.retriever | Query='Quick Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,722 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Difference between a stack and a queue' | topics=['Queue', 'Stack']
+2026-08-02 14:03:52,749 | INFO     | dsa_chatbot.rag.retriever | Query='Queue' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:03:52,767 | INFO     | dsa_chatbot.rag.retriever | Query='Stack' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,793 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: "Which one is better, Prim's Algorithm or Kruskal's Algorithm, for MST?"
+2026-08-02 14:03:52,814 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare AVL Tree and Binary Search Tree' | topics=['AVL Tree', 'Binary Search', 'Binary Search Tree']
+2026-08-02 14:03:52,836 | INFO     | dsa_chatbot.rag.retriever | Query='AVL Tree' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:03:52,852 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,873 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search Tree' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:03:52,886 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'Who won the football World Cup in 2022?'
+2026-08-02 14:03:52,904 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: "What's a good recipe for chocolate cake?"
+2026-08-02 14:03:52,917 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'What is the capital of France?'
+2026-08-02 14:03:52,924 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'Can you explain that again?'
+2026-08-02 14:03:52,949 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Merge Sort']); skipping fresh retrieval.
+2026-08-02 14:03:52,950 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'Give me another example'
+2026-08-02 14:03:52,973 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Merge Sort']); skipping fresh retrieval.
+2026-08-02 14:03:52,974 | INFO     | dsa_chatbot.__main__ | Evaluation complete: {'total_questions': 20, 'route_accuracy': 0.95, 'avg_topic_recall': 0.95, 'retrieval_latency_ms_avg': 44.4, 'retrieval_latency_ms_p95': 85.11}
+2026-08-02 14:06:23,677 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how binary search works' | topic=Binary Search
+2026-08-02 14:06:23,808 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how binary search works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:23,820 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is the time complexity of merge sort?' | topic=Merge Sort
+2026-08-02 14:06:23,838 | INFO     | dsa_chatbot.rag.retriever | Query='What is the time complexity of merge sort?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:23,848 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain quick sort with an example' | topic=Quick Sort
+2026-08-02 14:06:23,872 | INFO     | dsa_chatbot.rag.retriever | Query='Explain quick sort with an example' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:23,881 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a Trie used for?' | topic=Trie
+2026-08-02 14:06:23,904 | INFO     | dsa_chatbot.rag.retriever | Query='What is a Trie used for?' | candidates=5 | passed_threshold=4 | threshold=0.45
+2026-08-02 14:06:23,917 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a doubly linked list?' | topic=Doubly Linked List
+2026-08-02 14:06:23,938 | INFO     | dsa_chatbot.rag.retriever | Query='What is a doubly linked list?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:23,946 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain how a stack works' | topic=Stack
+2026-08-02 14:06:23,968 | INFO     | dsa_chatbot.rag.retriever | Query='Explain how a stack works' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:23,980 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is topological sort used for?' | topic=Topological Sort
+2026-08-02 14:06:24,001 | INFO     | dsa_chatbot.rag.retriever | Query='What is topological sort used for?' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:06:24,007 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: "Explain Dijkstra's Algorithm" | topic=Dijkstra's Algorithm
+2026-08-02 14:06:24,029 | INFO     | dsa_chatbot.rag.retriever | Query="Explain Dijkstra's Algorithm" | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,038 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'What is a segment tree?' | topic=Segment Tree
+2026-08-02 14:06:24,065 | INFO     | dsa_chatbot.rag.retriever | Query='What is a segment tree?' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,076 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'Explain the sliding window technique' | topic=Sliding Window Technique
+2026-08-02 14:06:24,099 | INFO     | dsa_chatbot.rag.retriever | Query='Explain the sliding window technique' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,113 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'What is the difference between BFS and DFS?' | topics=['Breadth-First Search', 'Depth-First Search']
+2026-08-02 14:06:24,134 | INFO     | dsa_chatbot.rag.retriever | Query='Breadth-First Search' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:06:24,151 | INFO     | dsa_chatbot.rag.retriever | Query='Depth-First Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,166 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare merge sort vs quick sort' | topics=['Merge Sort', 'Quick Sort']
+2026-08-02 14:06:24,190 | INFO     | dsa_chatbot.rag.retriever | Query='Merge Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,215 | INFO     | dsa_chatbot.rag.retriever | Query='Quick Sort' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,229 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Difference between a stack and a queue' | topics=['Queue', 'Stack']
+2026-08-02 14:06:24,253 | INFO     | dsa_chatbot.rag.retriever | Query='Queue' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:06:24,281 | INFO     | dsa_chatbot.rag.retriever | Query='Stack' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,320 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: "Which one is better, Prim's Algorithm or Kruskal's Algorithm, for MST?" | topics=["Kruskal's Algorithm (MST)", "Prim's Algorithm (MST)"]
+2026-08-02 14:06:24,354 | INFO     | dsa_chatbot.rag.retriever | Query="Kruskal's Algorithm (MST)" | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:06:24,380 | INFO     | dsa_chatbot.rag.retriever | Query="Prim's Algorithm (MST)" | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:06:24,395 | INFO     | dsa_chatbot.agents.router | Routed to COMPARISON: 'Compare AVL Tree and Binary Search Tree' | topics=['AVL Tree', 'Binary Search', 'Binary Search Tree']
+2026-08-02 14:06:24,419 | INFO     | dsa_chatbot.rag.retriever | Query='AVL Tree' | candidates=5 | passed_threshold=5 | threshold=0.45
+2026-08-02 14:06:24,444 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,465 | INFO     | dsa_chatbot.rag.retriever | Query='Binary Search Tree' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 14:06:24,489 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'Who won the football World Cup in 2022?'
+2026-08-02 14:06:24,503 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: "What's a good recipe for chocolate cake?"
+2026-08-02 14:06:24,521 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'What is the capital of France?'
+2026-08-02 14:06:24,533 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'Can you explain that again?'
+2026-08-02 14:06:24,565 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Merge Sort']); skipping fresh retrieval.
+2026-08-02 14:06:24,566 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'Give me another example'
+2026-08-02 14:06:24,590 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Merge Sort']); skipping fresh retrieval.
+2026-08-02 14:06:24,590 | INFO     | dsa_chatbot.__main__ | Evaluation complete: {'total_questions': 20, 'route_accuracy': 1.0, 'avg_topic_recall': 1.0, 'retrieval_latency_ms_avg': 46.26, 'retrieval_latency_ms_p95': 101.1}
+2026-08-02 16:00:13,397 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'explain binary search' | topic=Binary Search
+2026-08-02 16:00:14,003 | INFO     | dsa_chatbot.rag.retriever | Query='explain binary search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 16:00:15,631 | INFO     | dsa_chatbot.llm.generate | LLM provider initialized: GroqProvider
+2026-08-02 16:00:17,326 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=single_topic | topics=['Binary Search'] | session_id=None
+2026-08-02 16:00:56,629 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: '2,3,1,6,5,4 find 5 this using this search step by step'
+2026-08-02 16:00:57,493 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=out_of_scope | topics=[] | session_id=None
+2026-08-02 16:07:37,423 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'explain binary search' | topic=Binary Search
+2026-08-02 16:07:37,480 | INFO     | dsa_chatbot.rag.retriever | Query='explain binary search' | candidates=1 | passed_threshold=1 | threshold=0.45
+2026-08-02 16:07:41,129 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:07:51,945 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 get_relevant_context failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 110, in get_relevant_context
+    results = self._get_memory().search(query, user_id=user_id, limit=limit)
+              ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:07:53,458 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:07:57,115 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 add_interaction failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 93, in add_interaction
+    self._get_memory().add(messages, user_id=user_id, infer=self.infer)
+    ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:07:57,120 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=1 | route=single_topic | topics=['Binary Search'] | session_id=1
+2026-08-02 16:31:21,411 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'explain binary search' | topic=Binary Search
+2026-08-02 16:31:21,670 | INFO     | dsa_chatbot.rag.retriever | Query='explain binary search' | candidates=1 | passed_threshold=1 | threshold=-1.00
+2026-08-02 16:31:24,341 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:31:29,511 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 get_relevant_context failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 110, in get_relevant_context
+    results = self._get_memory().search(query, user_id=user_id, limit=limit)
+              ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:31:30,363 | INFO     | dsa_chatbot.llm.generate | LLM provider initialized: GroqProvider
+2026-08-02 16:31:31,945 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:31:35,540 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 add_interaction failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 93, in add_interaction
+    self._get_memory().add(messages, user_id=user_id, infer=self.infer)
+    ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:31:35,545 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=1 | route=single_topic | topics=['Binary Search'] | session_id=2
+2026-08-02 16:32:22,442 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'in this array [65,32,43,23,78,96] how will you find 23 using this search'
+2026-08-02 16:32:24,207 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Binary Search', 'Linear Search']); skipping fresh retrieval.
+2026-08-02 16:32:24,208 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:32:27,835 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 get_relevant_context failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 110, in get_relevant_context
+    results = self._get_memory().search(query, user_id=user_id, limit=limit)
+              ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:32:29,805 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:32:33,863 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 add_interaction failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 93, in add_interaction
+    self._get_memory().add(messages, user_id=user_id, infer=self.infer)
+    ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:32:33,869 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=1 | route=followup | topics=[] | session_id=2
+2026-08-02 16:33:48,648 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'compare this search with linear search' | topic=Linear Search
+2026-08-02 16:33:48,715 | INFO     | dsa_chatbot.rag.retriever | Query='compare this search with linear search' | candidates=1 | passed_threshold=1 | threshold=-1.00
+2026-08-02 16:33:48,716 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:33:52,390 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 get_relevant_context failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 110, in get_relevant_context
+    results = self._get_memory().search(query, user_id=user_id, limit=limit)
+              ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:33:54,095 | INFO     | dsa_chatbot.memory.mem0_client | Initializing mem0 (local chroma + huggingface embedder)...
+2026-08-02 16:33:58,206 | ERROR    | dsa_chatbot.memory.mem0_client | mem0 add_interaction failed for user_id=1
+Traceback (most recent call last):
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 93, in add_interaction
+    self._get_memory().add(messages, user_id=user_id, infer=self.infer)
+    ~~~~~~~~~~~~~~~~^^
+  File "D:\scratch\chatbot\chatbot\memory\mem0_client.py", line 72, in _get_memory
+    self._memory = Memory.from_config(_build_config_dict())
+                   ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 59, in from_config
+    return cls(config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\memory\main.py", line 37, in __init__
+    self.llm = LlmFactory.create(self.config.llm.provider, self.config.llm.config)
+               ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\utils\factory.py", line 34, in create
+    return llm_instance(base_config)
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\mem0\llms\openai.py", line 28, in __init__
+    self.client = OpenAI(api_key=api_key, base_url=base_url)
+                  ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "D:\scratch\chatbot\chatbot\venv\Lib\site-packages\openai\_client.py", line 135, in __init__
+    raise OpenAIError(
+        "The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable"
+    )
+openai.OpenAIError: The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable
+2026-08-02 16:33:58,212 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=1 | route=single_topic | topics=['Linear Search'] | session_id=2
+2026-08-02 19:53:48,973 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'how are you'
+2026-08-02 19:53:49,894 | INFO     | dsa_chatbot.llm.generate | LLM provider initialized: GroqProvider
+2026-08-02 19:53:51,450 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=out_of_scope | topics=[] | session_id=None
+2026-08-02 22:34:22,716 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: "explain dijikstra's algorithm" | topic=Dijkstra's Algorithm
+2026-08-02 22:34:23,350 | INFO     | dsa_chatbot.rag.retriever | Query="explain dijikstra's algorithm" | candidates=1 | passed_threshold=1 | threshold=-1.00
+2026-08-02 22:34:24,785 | INFO     | dsa_chatbot.llm.generate | LLM provider initialized: GroqProvider
+2026-08-02 22:34:26,608 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=single_topic | topics=["Dijkstra's Algorithm"] | session_id=None
+2026-08-02 22:41:13,334 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'explain bfs' | topic=Breadth-First Search
+2026-08-02 22:41:13,572 | INFO     | dsa_chatbot.rag.retriever | Query='explain bfs' | candidates=5 | passed_threshold=5 | threshold=-1.00
+2026-08-02 22:41:14,419 | INFO     | dsa_chatbot.llm.generate | LLM provider initialized: GroqProvider
+2026-08-02 22:41:15,798 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=single_topic | topics=['Breadth-First Search'] | session_id=None
+2026-08-02 22:41:56,906 | INFO     | dsa_chatbot.agents.router | Routed to OUT_OF_SCOPE: 'compare with other graph parsing algorithms'
+2026-08-02 22:41:57,470 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=out_of_scope | topics=[] | session_id=None
+2026-08-02 22:51:55,471 | INFO     | dsa_chatbot.agents.router | Routed to SINGLE_TOPIC: 'explain dfs' | topic=Depth-First Search
+2026-08-02 22:51:55,687 | INFO     | dsa_chatbot.rag.retriever | Query='explain dfs' | candidates=1 | passed_threshold=1 | threshold=-1.00
+2026-08-02 22:51:56,559 | INFO     | dsa_chatbot.llm.generate | LLM provider initialized: GroqProvider
+2026-08-02 22:51:57,814 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=single_topic | topics=['Depth-First Search'] | session_id=None
+2026-08-02 22:52:27,161 | INFO     | dsa_chatbot.agents.router | Routed to FOLLOWUP: 'compare it with other graph traversal algorithms'
+2026-08-02 22:52:28,250 | INFO     | dsa_chatbot.agents.followup | Follow-up query reuses existing conversation context (topics=['Depth-First Search', 'Stack']); skipping fresh retrieval.
+2026-08-02 22:52:29,862 | INFO     | dsa_chatbot.chat_service | Chat turn complete | user_id=None | route=followup | topics=[] | session_id=None

logs/logger.py

@@ -0,0 +1,48 @@
+"""
+Centralized logging setup.
+
+Every module does `from logs.logger import get_logger` and
+`logger = get_logger(__name__)` rather than configuring logging itself.
+Writes to both console and logs/app.log (paths from config.py).
+"""
+
+import logging
+import os
+import sys
+
+import config
+
+_CONFIGURED = False
+
+
+def _configure_root():
+    global _CONFIGURED
+    if _CONFIGURED:
+        return
+
+    os.makedirs(config.LOG_DIR, exist_ok=True)
+
+    root = logging.getLogger("dsa_chatbot")
+    root.setLevel(config.LOG_LEVEL)
+    root.propagate = False
+
+    formatter = logging.Formatter(
+        "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+    )
+
+    if not root.handlers:
+        stream_handler = logging.StreamHandler(sys.stdout)
+        stream_handler.setFormatter(formatter)
+        root.addHandler(stream_handler)
+
+        file_handler = logging.FileHandler(config.LOG_FILE_PATH, encoding="utf-8")
+        file_handler.setFormatter(formatter)
+        root.addHandler(file_handler)
+
+    _CONFIGURED = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Returns a named logger nested under the shared 'dsa_chatbot' root."""
+    _configure_root()
+    return logging.getLogger(f"dsa_chatbot.{name}")

memory/mem0_client.py

@@ -0,0 +1,137 @@
+"""
+mem0 client wrapper.
+
+Responsibility boundary (do not blur this):
+    - mem0       -> user preferences + long-term conversational memory
+                    (e.g. "prefers beginner explanations", "likes step-by-step examples")
+    - ChromaDB   -> DSA knowledge embeddings (rag/retriever.py) — NEVER touched here
+    - SQLite     -> raw message/session transcripts (history/) — NEVER touched here
+
+mem0 runs in local/open-source mode: a local Chroma vector store (separate
+collection from the knowledge base) + a local sentence-transformers
+embedder (same model as the KB for consistency, configurable independently
+if needed).
+
+Fact extraction (infer=True) would use an LLM to summarize what to
+remember. To avoid depending on the (expensive, 4-bit-quantized) local
+Mistral model just to log a preference, this wrapper uses infer=False by
+default — messages are stored as-is and semantic search over them still
+works for retrieval. Set infer=True if you want mem0 to run LLM-based
+fact extraction using the same provider configured in llm/generate.py.
+"""
+
+import os
+
+import config
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+_MEM0_COLLECTION_NAME = "user_preferences_memory"
+
+
+def _build_config_dict() -> dict:
+    os.makedirs(config.MEM0_LOCAL_STORAGE_DIR, exist_ok=True)
+    return {
+        "vector_store": {
+            "provider": "chroma",
+            "config": {
+                "collection_name": _MEM0_COLLECTION_NAME,
+                "path": os.path.join(config.MEM0_LOCAL_STORAGE_DIR, "chroma_db"),
+            },
+        },
+        "embedder": {
+            "provider": "huggingface",
+            "config": {
+                "model": f"sentence-transformers/{config.EMBEDDING_MODEL_NAME}",
+            },
+        },
+        "history_db_path": os.path.join(config.MEM0_LOCAL_STORAGE_DIR, "mem0_history.db"),
+    }
+
+
+class Mem0Client:
+    """
+    Thin wrapper around mem0.Memory scoped to a single responsibility:
+    user preferences and long-term conversational memory.
+    """
+
+    def __init__(self, infer: bool = False):
+        self.infer = infer
+        self._memory = None
+        self._enabled = config.USE_MEM0
+
+        if not self._enabled:
+            logger.info("USE_MEM0 is False — Mem0Client will be a no-op.")
+
+    def _get_memory(self):
+        if self._memory is None:
+            from mem0 import Memory
+
+            logger.info("Initializing mem0 (local chroma + huggingface embedder)...")
+            self._memory = Memory.from_config(_build_config_dict())
+        return self._memory
+
+    def add_interaction(self, user_id: str, user_message: str, assistant_message: str = None) -> None:
+        """
+        Store a turn of conversation for long-term memory purposes (NOT
+        transcript storage — that's history/service.py + SQLite).
+
+        Only call this for things worth remembering long-term (preferences,
+        recurring topics of interest, stated skill level) — not every raw
+        message. The router/chat layer decides when this is worth calling;
+        this wrapper doesn't filter content itself.
+        """
+        if not self._enabled:
+            return
+
+        messages = [{"role": "user", "content": user_message}]
+        if assistant_message:
+            messages.append({"role": "assistant", "content": assistant_message})
+
+        try:
+            self._get_memory().add(messages, user_id=user_id, infer=self.infer)
+        except Exception:
+            logger.exception("mem0 add_interaction failed for user_id=%s", user_id)
+
+    def get_relevant_context(self, user_id: str, query: str, limit: int = 5) -> list:
+        """
+        Returns a list of plain-text memory strings relevant to `query`,
+        ready to hand to llm/prompts.py's mem0_context parameter.
+
+        Returns [] if mem0 is disabled, the user has no memories yet, or a
+        lookup error occurs — callers should treat that as "no memory
+        context available", not as an error condition.
+        """
+        if not self._enabled:
+            return []
+
+        try:
+            results = self._get_memory().search(query, user_id=user_id, limit=limit)
+        except Exception:
+            logger.exception("mem0 get_relevant_context failed for user_id=%s", user_id)
+            return []
+
+        # mem0's search() returns {"results": [{"memory": "...", "score": ...}, ...]}
+        # in v2, or a plain list in some versions — handle both.
+        items = results.get("results", results) if isinstance(results, dict) else results
+        return [item.get("memory", "") for item in items if item.get("memory")]
+
+    def delete_all_for_user(self, user_id: str) -> None:
+        """Useful for account deletion / a 'forget me' feature."""
+        if not self._enabled:
+            return
+        try:
+            self._get_memory().delete_all(user_id=user_id)
+        except Exception:
+            logger.exception("mem0 delete_all_for_user failed for user_id=%s", user_id)
+
+
+_CLIENT_SINGLETON = None
+
+
+def get_mem0_client() -> Mem0Client:
+    global _CLIENT_SINGLETON
+    if _CLIENT_SINGLETON is None:
+        _CLIENT_SINGLETON = Mem0Client()
+    return _CLIENT_SINGLETON

rag/build_index.py

@@ -0,0 +1,211 @@
+"""
+RAG index builder.
+
+Reads every knowledge-base .txt file, splits it into semantic chunks based
+on the existing structural headings (DEFINITION, TIME_COMPLEXITY,
+SPACE_COMPLEXITY, USE_WHEN, EXAMPLE) rather than arbitrary fixed-size
+windows, attaches per-topic metadata from topic_metadata.json, embeds each
+chunk with sentence-transformers, and stores everything in a persistent
+ChromaDB collection.
+
+This script NEVER modifies the source .txt files. They are treated as
+immutable. Run it whenever the knowledge base or topic_metadata.json
+changes:
+
+    python -m rag.build_index
+"""
+
+import json
+import os
+import re
+import sys
+
+import chromadb
+from sentence_transformers import SentenceTransformer
+
+# Allow running as a standalone script (python rag/build_index.py) as well
+# as a module (python -m rag.build_index).
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import config
+from logs.logger import get_logger
+
+logger = get_logger(__name__)
+
+# Matches a section header line, e.g. "DEFINITION:" or "TIME_COMPLEXITY:"
+_HEADER_PATTERN = re.compile(
+    r"^(" + "|".join(config.KB_SECTION_HEADERS) + r"):\s*$", re.MULTILINE
+)
+
+_TOPIC_LINE_PATTERN = re.compile(r"^TOPIC:\s*(.+)$", re.MULTILINE)
+
+
+def _parse_sections(file_text: str) -> dict:
+    """
+    Split a KB file's text into {section_name: section_body} using the
+    structural headers defined in config.KB_SECTION_HEADERS.
+
+    Any text before the first recognized header (e.g. a "TOPIC:" line) is
+    ignored here — the topic name is expected to come from
+    topic_metadata.json, not parsed out of the file body.
+    """
+    matches = list(_HEADER_PATTERN.finditer(file_text))
+    sections = {}
+
+    for i, match in enumerate(matches):
+        header = match.group(1)
+        start = match.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(file_text)
+        body = file_text[start:end].strip()
+        if body:
+            sections[header] = body
+
+    return sections
+
+
+def _load_topic_metadata() -> dict:
+    if not os.path.exists(config.TOPIC_METADATA_PATH):
+        raise FileNotFoundError(
+            f"topic_metadata.json not found at {config.TOPIC_METADATA_PATH}. "
+            "Every knowledge-base file must have a matching entry."
+        )
+    with open(config.TOPIC_METADATA_PATH, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _list_kb_files() -> list:
+    if not os.path.isdir(config.KNOWLEDGE_BASE_DIR):
+        raise FileNotFoundError(
+            f"Knowledge base directory not found: {config.KNOWLEDGE_BASE_DIR}"
+        )
+    return sorted(
+        f
+        for f in os.listdir(config.KNOWLEDGE_BASE_DIR)
+        if f.endswith(".txt")
+    )
+
+
+def build_chunks() -> list:
+    """
+    Returns a list of dicts, each representing one chunk ready for embedding:
+        {
+            "id": "binary_search.txt::DEFINITION",
+            "text": "...",
+            "metadata": {
+                "topic": "...",
+                "category": "...",
+                "section": "...",
+                "difficulty": "...",
+                "source": "binary_search.txt",
+                "chunk_id": 0
+            }
+        }
+    """
+    topic_metadata = _load_topic_metadata()
+    kb_files = _list_kb_files()
+
+    missing_metadata = [f for f in kb_files if f not in topic_metadata]
+    if missing_metadata:
+        logger.warning(
+            "The following KB files have no topic_metadata.json entry and "
+            "will be skipped: %s",
+            missing_metadata,
+        )
+
+    chunks = []
+    chunk_counter = 0
+
+    for filename in kb_files:
+        if filename not in topic_metadata:
+            continue
+
+        file_path = os.path.join(config.KNOWLEDGE_BASE_DIR, filename)
+        with open(file_path, "r", encoding="utf-8") as f:
+            file_text = f.read()
+
+        sections = _parse_sections(file_text)
+        if not sections:
+            logger.warning(
+                "No recognized section headers (%s) found in %s. Skipping.",
+                config.KB_SECTION_HEADERS,
+                filename,
+            )
+            continue
+
+        meta = topic_metadata[filename]
+
+        for section_name, section_body in sections.items():
+            chunk = {
+                "id": f"{filename}::{section_name}",
+                "text": f"{meta.get('topic', filename)} - {section_name}: {section_body}",
+                "metadata": {
+                    "topic": meta.get("topic", ""),
+                    "category": meta.get("category", ""),
+                    "section": section_name,
+                    "difficulty": meta.get("difficulty", ""),
+                    "source": filename,
+                    "prerequisites": ", ".join(meta.get("prerequisites", [])),
+                    "chunk_id": chunk_counter,
+                },
+            }
+            chunks.append(chunk)
+            chunk_counter += 1
+
+    logger.info("Built %d chunks from %d knowledge-base files.", len(chunks), len(kb_files))
+    return chunks
+
+
+def build_index(reset: bool = True) -> None:
+    """
+    Embed all chunks and persist them into the ChromaDB collection.
+
+    Args:
+        reset: if True, drops and recreates the collection so the index is
+               rebuilt from scratch (safe default whenever the KB or
+               metadata changes). If False, upserts into the existing
+               collection.
+    """
+    os.makedirs(config.CHROMA_DB_DIR, exist_ok=True)
+
+    logger.info("Loading embedding model: %s", config.EMBEDDING_MODEL_NAME)
+    embedder = SentenceTransformer(config.EMBEDDING_MODEL_NAME)
+
+    client = chromadb.PersistentClient(path=config.CHROMA_DB_DIR)
+
+    if reset:
+        try:
+            client.delete_collection(config.CHROMA_COLLECTION_NAME)
+            logger.info("Existing collection '%s' deleted.", config.CHROMA_COLLECTION_NAME)
+        except Exception:
+            pass  # collection didn't exist yet
+
+    collection = client.get_or_create_collection(name=config.CHROMA_COLLECTION_NAME)
+
+    chunks = build_chunks()
+    if not chunks:
+        logger.warning("No chunks produced — index will be empty.")
+        return
+
+    texts = [c["text"] for c in chunks]
+    ids = [c["id"] for c in chunks]
+    metadatas = [c["metadata"] for c in chunks]
+
+    logger.info("Embedding %d chunks...", len(texts))
+    embeddings = embedder.encode(texts, show_progress_bar=False).tolist()
+
+    collection.upsert(
+        ids=ids,
+        embeddings=embeddings,
+        documents=texts,
+        metadatas=metadatas,
+    )
+
+    logger.info(
+        "Index build complete. Collection '%s' now has %d chunks.",
+        config.CHROMA_COLLECTION_NAME,
+        collection.count(),
+    )
+
+
+if __name__ == "__main__":
+    build_index(reset=True)

rag/generate.py

@@ -0,0 +1,147 @@
+"""
+Batch-generates DSA knowledge base .txt files using the Groq API.
+
+Setup:
+    pip install groq python-dotenv
+    Create a .env file with: GROQ_API_KEY=your_key_here
+
+Run:
+    python generate_knowledge_base.py
+
+Output:
+    Files are written to ./knowledge_base/<topic_snake_case>.txt
+"""
+
+import os
+import re
+import time
+from dotenv import load_dotenv
+from groq import Groq
+
+load_dotenv()
+
+client = Groq(api_key=os.environ.get("GROQ_API_KEY"))
+MODEL = "llama-3.3-70b-versatile"   # swap for another Groq-hosted model if you prefer
+OUTPUT_DIR = "knowledge_base"
+DELAY_BETWEEN_CALLS = 1.5  # seconds, be nice to rate limits
+
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+# ── PROMPT TEMPLATE ─────────────────────────────────────────────────────────
+PROMPT_TEMPLATE = """You are writing a knowledge base entry for a DSA (Data Structures & Algorithms)
+tutoring RAG chatbot. Write in your own original words — do NOT copy verbatim from
+GeeksforGeeks, textbooks, or any other source. Paraphrase and synthesize instead.
+Keep explanations beginner-friendly but technically accurate.
+
+Generate the entry for this topic: {topic}
+
+Output ONLY in the exact following plain text structure, no markdown formatting,
+no extra commentary before or after:
+
+TOPIC: {topic}
+
+DEFINITION:
+<2-3 sentence clear definition of what it is and what problem it solves>
+
+TIME_COMPLEXITY:
+<Best/Average/Worst case if they differ, otherwise a single Big-O with brief justification>
+
+SPACE_COMPLEXITY:
+<Big-O with brief note on what's using the space>
+
+USE_WHEN:
+<1-2 sentences: scenarios/conditions where this is the right tool>
+
+AVOID_WHEN:
+<1-2 sentences: scenarios where this is a poor choice, and what to use instead>
+
+EXAMPLE:
+<A small, concrete worked example (3-6 elements/nodes max), shown as a step-by-step
+walkthrough with intermediate states, ending in a clear result marked with a checkmark.
+Use simple ASCII/text formatting (arrows, brackets, indentation) — no images.>
+
+REAL_WORLD_ANALOGY:
+<1-2 sentence relatable comparison to something non-technical>
+
+SOURCE_NOTE:
+<Optional: e.g. "Concepts referenced from CLRS Introduction to Algorithms" or
+"GeeksforGeeks - {topic} (paraphrased, no verbatim text used)". Leave blank if not applicable.>
+"""
+
+# ── TOPIC LIST ───────────────────────────────────────────────────────────────
+TOPICS = [
+    # Arrays & Searching
+    "Linear Search", "Binary Search", "Two Pointer Technique", "Sliding Window Technique",
+    # Sorting
+    "Bubble Sort", "Selection Sort", "Insertion Sort", "Merge Sort", "Quick Sort",
+    "Heap Sort", "Counting Sort","radix sort","bucket sort",
+    # Linked Lists
+    "Singly Linked List", "Doubly Linked List", "Circular Linked List",
+    # Stacks & Queues
+    "Stack", "Queue", "Circular Queue", "Deque", "Monotonic Stack",
+    # Trees
+    "Binary Tree", "Binary Search Tree", "AVL Tree", "Heap (Min/Max)", "Trie",
+    "Segment Tree", "Fenwick Tree (Binary Indexed Tree)",
+    # Graphs
+    "BFS", "DFS", "Dijkstra's Algorithm", "Bellman-Ford Algorithm",
+    "Floyd-Warshall Algorithm", "Kruskal's Algorithm (MST)", "Prim's Algorithm (MST)",
+    "Topological Sort", "Union-Find (Disjoint Set)",
+    # Dynamic Programming
+    "Dynamic Programming Overview", "0/1 Knapsack", "Longest Common Subsequence",
+    "Longest Increasing Subsequence", "Coin Change Problem", "Edit Distance",
+    # Greedy
+    "Greedy Algorithms Overview", "Activity Selection Problem", "Fractional Knapsack",
+    # Hashing
+    "Hash Table", "Hash Set vs Hash Map",
+    # Recursion & Backtracking
+    "Recursion Overview", "Backtracking Overview", "N-Queens Problem",
+    "Subset Sum / Power Set Generation",
+    # Bit Manipulation
+    "Bit Manipulation Basics", "XOR Tricks",
+]
+
+
+def to_snake_case(topic: str) -> str:
+    """Converts a topic name into a safe snake_case filename."""
+    cleaned = re.sub(r"[^\w\s-]", "", topic)          # strip punctuation like ()/,'
+    cleaned = re.sub(r"\s+", "_", cleaned.strip())     # spaces -> underscores
+    return cleaned.lower()
+
+
+def generate_entry(topic: str) -> str:
+    prompt = PROMPT_TEMPLATE.format(topic=topic)
+    response = client.chat.completions.create(
+        model=MODEL,
+        messages=[{"role": "user", "content": prompt}],
+        temperature=0.4,
+        max_tokens=1024,
+    )
+    return response.choices[0].message.content.strip()
+
+
+def main():
+    print(f"Generating {len(TOPICS)} knowledge base files into ./{OUTPUT_DIR}/\n")
+
+    for i, topic in enumerate(TOPICS, start=1):
+        filename = to_snake_case(topic) + ".txt"
+        filepath = os.path.join(OUTPUT_DIR, filename)
+
+        if os.path.exists(filepath):
+            print(f"[{i}/{len(TOPICS)}] SKIP (already exists): {filename}")
+            continue
+
+        print(f"[{i}/{len(TOPICS)}] Generating: {topic} -> {filename}")
+        try:
+            content = generate_entry(topic)
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(content)
+        except Exception as e:
+            print(f"    ERROR generating '{topic}': {e}")
+
+        time.sleep(DELAY_BETWEEN_CALLS)
+
+    print("\nDone. Review files in ./knowledge_base/ before indexing into ChromaDB.")
+
+
+if __name__ == "__main__":
+    main()

rag/knowledge_base/01_knapsack.txt

@@ -0,0 +1,37 @@
+TOPIC: 0/1 Knapsack
+
+DEFINITION: 
+The 0/1 Knapsack problem is a classic problem in computer science where you have a set of items, each with a weight and a value, and you need to determine the subset of items to include in a knapsack of limited capacity such that the total value is maximized. This problem solves the issue of optimizing the selection of items when resources are limited. The "0/1" refers to the fact that each item is either included or excluded from the knapsack, with no partial inclusions allowed.
+
+TIME_COMPLEXITY: 
+The time complexity of the 0/1 Knapsack problem is O(nW), where n is the number of items and W is the capacity of the knapsack. This is because the problem is typically solved using dynamic programming, which involves filling up a 2D table of size n x W.
+
+SPACE_COMPLEXITY: 
+The space complexity of the 0/1 Knapsack problem is O(nW), which is used to store the 2D table that keeps track of the maximum value that can be obtained with a given capacity and number of items.
+
+USE_WHEN: 
+The 0/1 Knapsack problem is useful when you need to make a selection from a set of items, each with its own value and cost, and you have limited resources. This problem is particularly relevant in scenarios such as budgeting, resource allocation, and investment decisions.
+
+AVOID_WHEN: 
+You should avoid using the 0/1 Knapsack problem when the items can be divided or when the cost of an item is not directly proportional to its value, in which case other problems like the Fractional Knapsack problem may be more suitable.
+
+EXAMPLE: 
+Suppose we have a knapsack with a capacity of 5 units and the following items: 
+  - Item A: weight 2, value 10
+  - Item B: weight 3, value 8
+  - Item C: weight 1, value 5
+We can solve this problem using dynamic programming as follows:
+  - Initialize a table with zeros: 
+    [0, 0, 0, 0, 0, 0]
+  - Fill up the table:
+    - For Item A: [0, 0, 10, 10, 10, 10]
+    - For Item B: [0, 0, 10, 10, 10, 18]
+    - For Item C: [0, 5, 10, 15, 15, 18]
+  The maximum value we can get is 18, which is obtained by including Item B and Item C: 
+
+CHECKMARK: 
+
+REAL_WORLD_ANALOGY: 
+The 0/1 Knapsack problem is similar to going on a trip and having to pack a suitcase with limited space, where you need to decide which items to bring and which to leave behind in order to maximize your overall satisfaction.
+
+SOURCE_NOTE:

rag/knowledge_base/activity_selection_problem.txt

@@ -0,0 +1,41 @@
+TOPIC: Activity Selection Problem
+
+DEFINITION: The Activity Selection Problem is a classic problem in computer science and operations research that involves selecting the maximum number of activities that can be performed by a single person or resource, given a set of activities with start and end times. The goal is to choose the activities that do not conflict with each other, meaning that the end time of one activity is less than or equal to the start time of the next activity. This problem is useful in a variety of real-world scenarios, such as scheduling meetings or tasks.
+
+TIME_COMPLEXITY: O(n log n) due to the sorting of activities by their end times, which is necessary to apply the greedy algorithm that solves the problem.
+
+SPACE_COMPLEXITY: O(n) for storing the list of activities, where n is the number of activities.
+
+USE_WHEN: This problem is the right tool when you need to schedule a set of tasks or activities that have specific start and end times, and you want to maximize the number of activities that can be performed without any conflicts. It is particularly useful when the activities are mutually exclusive, meaning that only one activity can be performed at a time.
+
+AVOID_WHEN: This problem is a poor choice when the activities are not mutually exclusive, or when there are additional constraints that need to be considered, such as resource availability or priority levels. In such cases, more advanced scheduling algorithms or techniques, such as dynamic programming or integer programming, may be more suitable.
+
+EXAMPLE:
+Consider the following set of activities with their start and end times:
+  [1] (1, 4)
+  [2] (3, 5)
+  [3] (0, 6)
+  [4] (5, 7)
+  [5] (3, 8)
+  [6] (5, 9)
+  [7] (6, 10)
+First, sort the activities by their end times:
+  [1] (1, 4)
+  [2] (3, 5)
+  [4] (5, 7)
+  [7] (6, 10)
+  [5] (3, 8)
+  [6] (5, 9)
+  [3] (0, 6)
+Then, apply the greedy algorithm:
+  Select [1] (1, 4)
+  Select [4] (5, 7)
+  Select [7] (6, 10) is not selected because it conflicts with [4]
+The final selected activities are: 
+  [1] (1, 4)
+  [4] (5, 7)
+  Checkmark: The maximum number of non-conflicting activities is 2.
+
+REAL_WORLD_ANALOGY: The Activity Selection Problem is similar to scheduling meetings in a conference room, where you want to maximize the number of meetings that can be held without any conflicts or overlaps.
+
+SOURCE_NOTE: Concepts referenced from general knowledge of greedy algorithms and scheduling problems.

rag/knowledge_base/avl_tree.txt

@@ -0,0 +1,63 @@
+TOPIC: AVL Tree
+
+DEFINITION: 
+An AVL tree is a self-balancing binary search tree that ensures the height of the tree remains relatively small by rotating nodes when the balance factor becomes too large, thus solving the problem of maintaining efficient search, insertion, and deletion operations. This balance is crucial for preventing the tree from becoming skewed, which would lead to reduced performance. 
+
+TIME_COMPLEXITY: 
+The time complexity for search, insertion, and deletion in an AVL tree is O(log n) in all cases, as the tree's height is kept logarithmic by the self-balancing mechanism.
+
+SPACE_COMPLEXITY: 
+The space complexity of an AVL tree is O(n), where n is the number of nodes in the tree, as each node requires a constant amount of space to store its value, child pointers, and balance factor.
+
+USE_WHEN: 
+Use an AVL tree when you need to frequently insert, delete, and search for elements in a dataset while maintaining an efficient order, such as in database indexing or file systems. This data structure is particularly useful when the dataset is constantly changing.
+
+AVOID_WHEN: 
+Avoid using an AVL tree when the dataset is mostly static or when memory is extremely limited, as the overhead of maintaining the balance factor and performing rotations can be unnecessary or too costly; in such cases, a simpler binary search tree or even an array might be more suitable.
+
+EXAMPLE: 
+Let's insert elements 5, 2, 8, 3, 9 into an AVL tree step by step:
+  - Start with an empty tree.
+  - Insert 5:        [5]
+  - Insert 2:      [5]
+             / 
+           [2]
+  - Insert 8:      [5]
+             / \
+           [2] [8]
+  - Insert 3: Since 3 is between 2 and 5, we insert it as the right child of 2.
+           [5]
+             / \
+           [2] [8]
+               \
+               [3]
+  - Insert 9: The tree becomes unbalanced, so we rotate:
+           [5]
+             / \
+           [2] [8]
+               \   \
+               [3] [9]
+           After rotation: 
+           [5]
+             / \
+           [2] [8]
+             \   / \
+            [3] [9]
+           Final balanced tree: 
+                 [5]
+               /     \
+             [2]     [8]
+               \       \
+               [3]     [9]
+  Result: 
+  The final balanced AVL tree is: 
+                 [5]
+               /     \
+             [2]     [8]
+               \       \
+               [3]     [9] 
+
+REAL_WORLD_ANALOGY: 
+An AVL tree can be thought of like a librarian who constantly rearranges books on shelves to ensure that the shelves remain balanced and it's easy to find any book, similar to how the tree balances itself to maintain efficient data retrieval.
+
+SOURCE_NOTE:

rag/knowledge_base/backtracking_overview.txt

@@ -0,0 +1,42 @@
+TOPIC: Backtracking Overview
+
+DEFINITION: 
+Backtracking is a problem-solving strategy used in algorithms to find a solution by exploring all possible options in a systematic way. It involves recursively trying different paths until a valid solution is found, and if a path does not lead to a solution, it backtracks to the previous step and tries another path. This approach is particularly useful for solving constraint satisfaction problems.
+
+TIME_COMPLEXITY: 
+The time complexity of backtracking algorithms can vary, but in the worst case, it is typically O(n!), where n is the number of options to choose from, because it may need to explore all possible combinations. The average and best cases depend on the specific problem and the order in which options are explored.
+
+SPACE_COMPLEXITY: 
+The space complexity of backtracking algorithms is usually O(n), where n is the maximum depth of the recursion tree, because that's how much space is needed to store the current path being explored.
+
+USE_WHEN: 
+Backtracking is the right tool to use when dealing with problems that have multiple possible solutions and require exploring all options in a systematic way, such as puzzles, scheduling, or resource allocation problems. It's particularly useful when the problem can be broken down into smaller sub-problems and solved recursively.
+
+AVOID_WHEN: 
+Backtracking is a poor choice for problems that have a very large solution space or require finding the optimal solution quickly, because it can be slow and inefficient. In such cases, other algorithms like dynamic programming or greedy algorithms may be more suitable.
+
+EXAMPLE: 
+Suppose we want to find all possible ways to arrange the letters A, B, and C. We can use backtracking to solve this problem:
+  Start with an empty string: []
+  Try adding A: [A]
+    Try adding B: [A, B]
+      Try adding C: [A, B, C] 
+    Try adding C: [A, C]
+      Try adding B: [A, C, B] 
+  Try adding B: [B]
+    Try adding A: [B, A]
+      Try adding C: [B, A, C] 
+    Try adding C: [B, C]
+      Try adding A: [B, C, A] 
+  Try adding C: [C]
+    Try adding A: [C, A]
+      Try adding B: [C, A, B] 
+    Try adding B: [C, B]
+      Try adding A: [C, B, A] 
+The final solutions are: [A, B, C] , [A, C, B] , [B, A, C] , [B, C, A] , [C, A, B] , [C, B, A] 
+
+REAL_WORLD_ANALOGY: 
+Backtracking is similar to trying different routes to reach a destination, where you explore each path until you find the one that leads you to your goal, and if a path doesn't work out, you go back to the previous intersection and try another route.
+
+SOURCE_NOTE: 
+Concepts referenced from general knowledge of algorithms and problem-solving strategies.

rag/knowledge_base/bellman-ford_algorithm.txt

@@ -0,0 +1,49 @@
+TOPIC: Bellman-Ford Algorithm
+
+DEFINITION: The Bellman-Ford algorithm is a graph search algorithm that finds the shortest path from a source vertex to all other vertices in a weighted graph. It can handle negative weight edges and can detect negative weight cycles, making it a versatile tool for solving various graph-related problems. This algorithm is particularly useful for finding the shortest path in graphs where the edge weights can be negative.
+
+TIME_COMPLEXITY: The time complexity of the Bellman-Ford algorithm is O(VE), where V is the number of vertices and E is the number of edges, because it relaxes all edges V-1 times.
+
+SPACE_COMPLEXITY: The space complexity is O(V), as the algorithm needs to store the distance to each vertex from the source vertex.
+
+USE_WHEN: The Bellman-Ford algorithm is the right tool when you need to find the shortest path in a graph with negative weight edges, or when you need to detect negative weight cycles. It's particularly useful in scenarios where other algorithms like Dijkstra's may fail due to negative weights.
+
+AVOID_WHEN: You should avoid using the Bellman-Ford algorithm when the graph is very large and dense, as its O(VE) time complexity can be slow, and in such cases, more efficient algorithms like Dijkstra's or A* may be more suitable for graphs with non-negative weights.
+
+EXAMPLE:
+  Let's consider a graph with 4 vertices (A, B, C, D) and 5 edges:
+    A -> B (weight: -1)
+    A -> C (weight: 4)
+    B -> C (weight: 3)
+    B -> D (weight: 2)
+    C -> D (weight: 2)
+  Initially, the distance to all vertices is infinity, except for A which is 0.
+    A: 0
+    B: inf
+    C: inf
+    D: inf
+  After the first iteration:
+    A: 0
+    B: -1
+    C: inf
+    D: inf
+  After the second iteration:
+    A: 0
+    B: -1
+    C: 2
+    D: inf
+  After the third iteration:
+    A: 0
+    B: -1
+    C: 2
+    D: 1
+  After the fourth iteration, no changes occur, so we stop.
+  The shortest distances are: 
+    A to B: -1
+    A to C: 2
+    A to D: 1 
+  Checkmark: The shortest path from A to D is A -> B -> D with a total weight of 1.
+
+REAL_WORLD_ANALOGY: The Bellman-Ford algorithm can be thought of as finding the cheapest route to travel between cities, where the cost of traveling between cities can sometimes be negative, such as getting a refund for a part of the journey.
+
+SOURCE_NOTE: Concepts referenced from general knowledge of graph algorithms and data structures.

rag/knowledge_base/bfs.txt

@@ -0,0 +1,29 @@
+TOPIC: BFS
+
+DEFINITION: 
+Breadth-First Search (BFS) is a graph traversal algorithm that explores all the nodes at a given depth level before moving on to the next level, solving the problem of finding the shortest path between two nodes in an unweighted graph. It's particularly useful for searching graphs or trees level by level, starting from a given source node. This approach ensures that the algorithm visits all the nodes closest to the source before moving further away.
+
+TIME_COMPLEXITY: 
+The time complexity of BFS is O(V + E), where V represents the number of vertices (nodes) and E represents the number of edges, because in the worst case, the algorithm visits every node and edge once.
+
+SPACE_COMPLEXITY: 
+The space complexity of BFS is O(V), as the algorithm uses a queue to store nodes to be visited, and in the worst case, the queue can hold all the nodes at the deepest level.
+
+USE_WHEN: 
+BFS is the right tool when you need to find the shortest path in an unweighted graph or when you want to traverse a graph level by level, such as in web crawlers or social network friend suggestions. It's particularly useful when the graph is very large and you want to avoid the overhead of more complex algorithms.
+
+AVOID_WHEN: 
+BFS is a poor choice when dealing with very deep graphs or trees, as it can be slow and memory-intensive, and in such cases, a depth-first search (DFS) or more specialized algorithms like Dijkstra's or A* might be more suitable.
+
+EXAMPLE: 
+Consider a graph with nodes A, B, C, D, and E, where A is connected to B and C, B is connected to D, and C is connected to E. A BFS traversal starting from A would visit the nodes in the following order:
+  A
+  -> B, C
+  -> D, E
+The final result is a visited set {A, B, C, D, E} 
+
+REAL_WORLD_ANALOGY: 
+BFS can be thought of as exploring a city by first visiting all the neighboring houses, then moving on to the next block, and so on, similar to how a fire department might search a neighborhood.
+
+SOURCE_NOTE: 
+Concepts referenced from general knowledge of graph traversal algorithms.

rag/knowledge_base/binary_search.txt

@@ -0,0 +1,25 @@
+TOPIC: Binary Search
+
+DEFINITION: Binary search is an efficient algorithm for finding an item from a sorted list of items. It works by repeatedly dividing in half the portion of the list that could contain the item, until you've narrowed the possible locations to just one. This approach solves the problem of quickly locating a specific element within a large sorted dataset.
+
+TIME_COMPLEXITY: The time complexity of binary search is O(log n), where n is the number of items in the list. This is because with each comparison, the algorithm effectively halves the search space, leading to a logarithmic number of steps.
+
+SPACE_COMPLEXITY: The space complexity is O(1), as binary search only requires a constant amount of additional space to store the indices and the target value, regardless of the size of the input list.
+
+USE_WHEN: Use binary search when you need to find an item in a large sorted list, and speed is crucial. This is particularly useful in scenarios where the list is too large to search linearly, and the data is already sorted or can be sorted efficiently.
+
+AVOID_WHEN: Avoid using binary search when the list is unsorted, as the algorithm relies on the data being sorted to work correctly. In such cases, a linear search or a different sorting algorithm followed by binary search might be more appropriate.
+
+EXAMPLE:
+  Suppose we have a sorted list [2, 5, 8, 12, 16, 23] and we're looking for the number 12.
+  Start with the entire list: [2, 5, 8, 12, 16, 23]
+    -> Compare the middle element (8) with the target (12). Since 12 > 8, we know 12 must be in the right half.
+  Narrow down to the right half: [12, 16, 23]
+    -> Compare the middle element (16) with the target (12). Since 12 < 16, we know 12 must be in the left half of this subset.
+  Narrow down further: [12]
+    -> The only element left is 12, which matches our target: 
+ 
+
+REAL_WORLD_ANALOGY: Binary search is similar to finding a specific book in a library where the books are arranged alphabetically by title. You start by looking at the middle shelf, then move to the left or right half depending on whether the book you're looking for comes before or after the middle book alphabetically, repeating this process until you find the book.
+
+SOURCE_NOTE:

rag/knowledge_base/binary_search_tree.txt

@@ -0,0 +1,35 @@
+TOPIC: Binary Search Tree
+
+DEFINITION: A Binary Search Tree (BST) is a data structure in which each node has at most two children (i.e., left child and right child) and each node represents a value. This structure allows for efficient storage and retrieval of data by ensuring that all values to the left of a node are less than the node's value, and all values to the right are greater. This property enables fast searching, inserting, and deleting of nodes.
+
+TIME_COMPLEXITY: The time complexity of a Binary Search Tree is O(log n) for best and average cases, and O(n) for the worst case, which occurs when the tree becomes a skewed tree (essentially a linked list).
+
+SPACE_COMPLEXITY: The space complexity of a Binary Search Tree is O(n), where n is the number of nodes in the tree, as each node requires a constant amount of space to store its value and references to its children.
+
+USE_WHEN: Use a Binary Search Tree when you need to store and retrieve large amounts of data efficiently, and the data needs to be ordered or searchable. This is particularly useful in scenarios where data is constantly being inserted or deleted.
+
+AVOID_WHEN: Avoid using a Binary Search Tree when the data is mostly static or when the tree may become heavily unbalanced, as this can lead to poor performance; in such cases, a self-balancing binary search tree like an AVL tree or a Red-Black tree may be more suitable.
+
+EXAMPLE:
+Suppose we have a BST with the following nodes:
+      5
+     / \
+    3   7
+   / \   \
+  2   4   8
+We want to insert the value 6. 
+  First, we start at the root node (5) and compare it to the value we want to insert (6). 
+  Since 6 is greater than 5, we move to the right child (7). 
+  Then, we compare 6 to 7; since 6 is less than 7, we move to the left child (which doesn't exist), 
+  so we create a new node with the value 6 as the left child of 7.
+  The resulting tree is:
+      5
+     / \
+    3   7
+   / \ / \
+  2   4 6  8 
+  The insertion is successful 
+
+REAL_WORLD_ANALOGY: A Binary Search Tree can be thought of as a phonebook where each entry is a person's name, and the names are arranged alphabetically; when you look up a name, you can quickly find it by comparing it to the names on either side of the current page.
+
+SOURCE_NOTE: Concepts referenced from general knowledge of data structures and algorithms.

rag/knowledge_base/binary_tree.txt

@@ -0,0 +1,43 @@
+TOPIC: Binary Tree
+
+DEFINITION: 
+A binary tree is a data structure in which each node has at most two children, referred to as the left child and the right child. This structure allows for efficient storage and retrieval of data, particularly when the data has a hierarchical relationship. It solves the problem of organizing and searching large amounts of data by providing a systematic way to traverse and access the data.
+
+TIME_COMPLEXITY: 
+The time complexity of binary tree operations such as search, insert, and delete can vary: O(1) for the best case when the tree is balanced and the operation is performed at the root, O(log n) for the average case when the tree is balanced, and O(n) for the worst case when the tree is skewed.
+
+SPACE_COMPLEXITY: 
+The space complexity of a binary tree is O(n), where n is the number of nodes in the tree, since each node requires a constant amount of space to store its value and references to its children.
+
+USE_WHEN: 
+Use a binary tree when you need to store and retrieve data efficiently, especially when the data has a natural hierarchical structure, such as a file system or a database index. It's also useful when you need to perform operations like insertion, deletion, and search frequently.
+
+AVOID_WHEN: 
+Avoid using a binary tree when the data is too large to fit into memory or when the tree becomes severely unbalanced, leading to poor performance. In such cases, consider using other data structures like hash tables or self-balancing trees like AVL or Red-Black trees.
+
+EXAMPLE: 
+Suppose we have a binary tree with the following nodes: 
+        4
+       / \
+      2   6
+     / \   \
+    1   3   5
+To insert a new node with value 7, we start at the root (4) and move to the right child (6), then to the right child again (which doesn't exist), so we create a new node (7) as the right child of 6:
+        4
+       / \
+      2   6
+     / \   / \
+    1   3 5   7 
+The resulting tree is now: 
+        4
+       / \
+      2   6
+     / \   / \
+    1   3 5   7 
+Result: 
+
+REAL_WORLD_ANALOGY: 
+A binary tree can be thought of as a family tree, where each person (node) has at most two children, and the relationships between family members are organized in a hierarchical structure.
+
+SOURCE_NOTE: 
+Concepts referenced from general knowledge of data structures and algorithms.

rag/knowledge_base/bit_manipulation_basics.txt

@@ -0,0 +1,24 @@
+TOPIC: Bit Manipulation Basics
+
+DEFINITION: Bit manipulation is a technique used to perform operations on the binary representation of numbers, allowing for efficient and low-level control over data. It solves problems that require direct access and modification of individual bits or groups of bits within a binary number. This is particularly useful in situations where memory or computational resources are limited.
+
+TIME_COMPLEXITY: O(1) - Bit manipulation operations are typically constant time because they involve simple bitwise operations that do not depend on the size of the input.
+
+SPACE_COMPLEXITY: O(1) - The space complexity is constant because bit manipulation operations usually only require a small, fixed amount of space to store the input and output values.
+
+USE_WHEN: Bit manipulation is the right tool when working with low-level data representations, such as flags, masks, or bit fields, and when performing operations like setting, clearing, or toggling individual bits. It is also useful when optimizing code for performance or memory usage.
+
+AVOID_WHEN: Bit manipulation is a poor choice when working with high-level abstractions or complex data structures, and when readability and maintainability are more important than performance. In such cases, using higher-level constructs and libraries may be more appropriate.
+
+EXAMPLE:
+  Start with the binary number: 1010
+  Apply a bitwise AND operation with the mask: 1100
+    1010
+&   1100
+  ----
+    1000 
+  The result is: 1000 
+
+REAL_WORLD_ANALOGY: Bit manipulation is similar to working with a combination lock, where each bit represents a specific switch that can be turned on or off to achieve a desired outcome.
+
+SOURCE_NOTE: Concepts referenced from general knowledge of computer science and programming principles.

rag/knowledge_base/bubble_sort.txt

@@ -0,0 +1,33 @@
+TOPIC: Bubble Sort
+
+DEFINITION: 
+Bubble sort is a simple sorting algorithm that repeatedly steps through the list, compares adjacent elements, and swaps them if they are in the wrong order. This process is repeated until the list is sorted, solving the problem of arranging elements in ascending or descending order. It works by iteratively "bubbling" the largest or smallest element to the end or beginning of the list.
+
+TIME_COMPLEXITY: 
+The time complexity of bubble sort is O(n) in the best case, O(n^2) on average, and O(n^2) in the worst case, because in the best case the list is already sorted and only one pass is needed, while in the average and worst cases, the algorithm needs to make multiple passes through the list to sort it.
+
+SPACE_COMPLEXITY: 
+The space complexity of bubble sort is O(1), because it only uses a constant amount of additional space to store temporary swaps, and does not require any extra space that scales with the size of the input list.
+
+USE_WHEN: 
+Bubble sort can be useful when the list is small or nearly sorted, as it has a simple implementation and can be efficient in these cases. It can also be a good teaching tool for introducing the concept of sorting algorithms.
+
+AVOID_WHEN: 
+Bubble sort is a poor choice for large lists or lists that are in reverse order, as its average and worst-case time complexities are high, and other algorithms like quicksort or mergesort are generally more efficient and should be used instead.
+
+EXAMPLE: 
+Suppose we have the list [5, 2, 8, 3, 1] and we want to sort it in ascending order using bubble sort. 
+  Initial list: [5, 2, 8, 3, 1]
+  Compare 5 and 2, swap: [2, 5, 8, 3, 1]
+  Compare 5 and 8, no swap: [2, 5, 8, 3, 1]
+  Compare 8 and 3, swap: [2, 5, 3, 8, 1]
+  Compare 8 and 1, swap: [2, 5, 3, 1, 8]
+  Repeat the process until the list is sorted: 
+    [2, 5, 3, 1, 8] -> [2, 3, 5, 1, 8] -> [2, 3, 1, 5, 8] -> [2, 1, 3, 5, 8] -> [1, 2, 3, 5, 8]
+  Final sorted list: [1, 2, 3, 5, 8] 
+
+REAL_WORLD_ANALOGY: 
+Bubble sort is similar to rearranging a set of books on a shelf, where you compare each book to the one next to it and swap them if they are in the wrong order, repeating the process until the books are in the correct order.
+
+SOURCE_NOTE: 
+Concepts referenced from general knowledge of sorting algorithms and data structures.