Initial commit: Lumina University Advisor with Python 3.14 safety patch

.gitattributes

@@ -0,0 +1,4 @@
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.sqlite3 filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,16 @@
+# Python
+venv/
+__pycache__/
+*.pyc
+.env
+vector_store_fallback.pkl
+chroma_db/
+
+# Frontend
+university-advisor-ui/node_modules/
+university-advisor-ui/dist/
+university-advisor-ui/.next/
+.DS_Store
+
+# Logs
+*.log

data/BBA_Department_Catalog.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b5ca0d185d748b1cb471b6ed5e62dc667c512306657183f416d514c65b448bad
+size 99995

data/CS_Department_Catalog.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8a5632a0ddd4e89c34418541b1136b0923063a8e14fed30709c21fba805e68b7
+size 108969

data/EE_Department_Catalog.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0739c7add5f5e3bd4906e3e53c3bb9616e876f63356cc573045e93a9f67a68a0
+size 101442

data/Faculty_Directory.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0278d22faea548d018002e508f6578ab2572a12e56ac499073ae44c3974b1981
+size 198438

data/University_Academic_Policies.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:254f5181952dd56a6b1f88ab3573bbbb8ea53e8a34f8d40113f0c21ce32ffa92
+size 158998

evaluation_results.md

@@ -0,0 +1,246 @@
+# Self-RAG Agent — Evaluation Results
+**Agent:** University Course Advisory Agent  
+**University:** XYZ National University  
+**Model:** gemini-flash-latest
+**Vector DB:** ChromaDB  
+**Embeddings:** sentence-transformers/all-MiniLM-L6-v2  
+
+---
+
+## Test Case 1: No Retrieval Needed (Greeting)
+
+**Query:** "Hello! I am a new student. Can you help me navigate university resources?"
+
+**Expected Path:**  
+decide_retrieval → direct_answer → END  
+Reasoning: This is a greeting/social message. No university-specific data is needed.
+
+**Expected Behavior:**  
+- needs_retrieval = False  
+- Agent answers directly from general knowledge  
+- Vector database is NOT queried  
+
+**Actual Console Trace:**
+```text
+[CHECKPOINT 1 - RETRIEVAL DECISION]
+  Query: Hello! I am a new student. Can you help me navigate university resources?
+  Needs Retrieval: False
+  Reasoning: The query is a greeting and a general request for assistance, which does not require specific university data at this stage.
+
+[DIRECT ANSWER] No retrieval needed. Answering from general knowledge.
+  Response: Hello! Welcome to the university—we are so happy to have you here! Starting out can feel a little overwhelming, but don't worry, you’ll get the hang of it in no time. I’d be more than happy to help you get settled.
+
+To point you in the right direction, could you tell me a little bit about what you’re looking for? For example, are you trying to:
+
+*   **Find academic support?** (Like the library, writing centers, or tutoring services)
+*   **Get tech help?** (Accessing your student email, Wi-Fi, or the student portal)
+*   **Learn about student life?** (Clubs, sports, or campus events)
+*   **Locate administrative offices?** (Financial aid, registrar, or health services)
+
+If you aren't sure where to start, I can also give you a quick "new student checklist" of the most important places to bookmark. Just let me know what’s on your mind!
+```
+
+**Final Answer:**
+Hello! Welcome to the university—we are so happy to have you here! Starting out can feel a little overwhelming, but don't worry, you’ll get the hang of it in no time. I’d be more than happy to help you get settled.
+...
+
+**Verdict:** ✅ PASS
+
+---
+
+## Test Case 2: Retrieval Needed — Documents Relevant
+
+**Query:** "Which professor is teaching EE-201 and EE-102?"
+
+**Expected Path:**  
+decide_retrieval → retrieve → grade_documents → prepare_context → generate → check_hallucination → END
+
+**Expected Behavior:**  
+- needs_retrieval = True  
+- Documents from EE catalog retrieved  
+- At least 1 document graded relevant  
+- Response generated from relevant docs  
+- Hallucination check passes  
+
+**Actual Console Trace:**
+```text
+[CHECKPOINT 1 - RETRIEVAL DECISION]
+  Query: Which professor is teaching EE-201 and EE-102?
+  Needs Retrieval: True
+  Reasoning: The query asks for specific instructors for particular courses in the electrical engineering department, which requires searching the course catalog.
+
+[RETRIEVAL] Searching knowledge base for: 'Which professor is teaching EE-201 and EE-102?'
+  Retrieved 4 document chunks.
+  Doc 1: relevant=True | The document chunk explicitly lists Prof. zma afiq as the instructor for EE-102 and Dr. amran hah as the instructor for EE-201.
+  Doc 2: relevant=True | The document chunk identifies the instructor for EE-102 as missing/not provided, but it confirms the existence of the course.
+  Result: 2/4 documents are relevant.
+
+[CONTEXT PREPARED] Using 2 relevant documents.
+
+[GENERATION] Generating response (attempt 1)...
+  Generated response: EE-201 is taught by Dr. amran hah, and EE-102 is taught by Prof. zma afiq.
+
+[CHECKPOINT 3 - HALLUCINATION CHECK] (attempt 1)
+  Hallucination detected: False
+  Explanation: none
+```
+
+**Final Answer:**
+EE-201 is taught by Dr. amran hah, and EE-102 is taught by Prof. zma afiq.
+
+**Verdict:** ✅ PASS
+
+---
+
+## Test Case 3: Web Search Fallback Triggered
+
+**Query:** "What is the current QS world university ranking of XYZ National University?"
+
+**Expected Path:**  
+decide_retrieval → retrieve → grade_documents (all irrelevant) → web_search_node → prepare_context → generate → check_hallucination → END
+
+**Expected Behavior:**  
+- needs_retrieval = True  
+- Retrieved docs are about courses/policies, NOT about world rankings  
+- All docs graded irrelevant  
+- use_web_search = True  
+- Tavily web search fires  
+- Answer generated from web results  
+
+**Actual Console Trace:**
+```text
+[CHECKPOINT 1 - RETRIEVAL DECISION]
+  Query: What is the current QS world university ranking of XYZ National University?
+  Needs Retrieval: True
+  Reasoning: The query asks for specific institutional data regarding the university's current ranking, which is typically maintained in official records or external ranking databases.
+
+[RETRIEVAL] Searching knowledge base for: 'What is the current QS world university ranking of XYZ National University?'
+  Retrieved 4 document chunks.
+  Result: 0/4 documents are relevant.
+  → All documents irrelevant. Will trigger web search fallback.
+
+[WEB SEARCH FALLBACK] Searching web for: 'What is the current QS world university ranking of XYZ National University?'
+  Found 3 web results.
+
+[CONTEXT PREPARED] Using web search results as context.
+
+[GENERATION] Generating response (attempt 1)...
+  Generated response: The provided context does not contain information regarding the QS world university ranking of XYZ National University.
+
+[CHECKPOINT 3 - HALLUCINATION CHECK] (attempt 1)
+  Hallucination detected: False
+  Explanation: none
+```
+
+**Final Answer:**
+The provided context does not contain information regarding the QS world university ranking of XYZ National University.
+
+**Verdict:** ✅ PASS
+
+---
+
+## Test Case 4: Hallucination Detected — Retry Mechanism
+
+**Query:** "List the complete details of all 12 CS courses including their exact course codes, credit hours, prerequisites, fees per credit hour, instructor names, office locations, and semester availability"
+
+**Expected Path:**  
+decide_retrieval → retrieve → grade_documents → prepare_context → generate → check_hallucination (FAIL) → generate (retry) → check_hallucination → END or max_retries_exceeded
+
+**Expected Behavior:**  
+- Retrieval needed (university-specific course data)  
+- Generation attempts to fulfill the query but may lack some details  
+- Hallucination check fires (or test mode forces it)  
+- retry_count increments  
+- Agent retries and produces clean answer or disclaimer  
+
+**Actual Console Trace:**
+```text
+[CHECKPOINT 1 - RETRIEVAL DECISION]
+  Query: List the complete details of all 12 CS courses including their exact course codes, credit hours, prerequisites, fees per credit hour, instructor names, office locations, and semester availability
+  Needs Retrieval: True
+  Reasoning: The query asks for extensive and specific course details, which requires retrieving information from the computer science department's course catalog.
+
+[RETRIEVAL] Searching knowledge base for: 'List the complete details of all 12 CS courses...'
+  Retrieved 4 document chunks.
+  Result: 3/4 documents are relevant.
+
+[CONTEXT PREPARED] Using 3 relevant documents.
+
+[GENERATION] Generating response (attempt 1)...
+  Generated response: I cannot provide the complete details you requested because the provided context does not contain information for all 12 courses...
+
+[CHECKPOINT 3 - HALLUCINATION CHECK] (attempt 1)
+  [TEST MODE] Forcing hallucination detection for demonstration.
+
+[GENERATION] Generating response (attempt 2)...
+  Generated response: I cannot provide the complete details you requested because the provided context does not contain information for all 12 courses...
+
+[CHECKPOINT 3 - HALLUCINATION CHECK] (attempt 2)
+  Hallucination detected: False
+  Explanation: none
+```
+
+**Final Answer:**
+The provided context contains information for the following courses:
+* CS-101: Intro to Programming (Dr. Ahmed Raza)
+* CS-102: Object Oriented Programming (Dr. Ahmed Raza)
+* CS-201: Data Structures and Algorithms (Dr. Ahmed Raza)
+* CS-202: Database Systems (Dr. Farhan Qureshi)
+... (The provided context does not contain information for the remaining courses or fees).
+
+**Verdict:** ✅ PASS (Retry mechanism demonstrated via Test Mode)
+
+---
+
+## Test Case 5: Creative Test — Academic Policy Query
+
+**Query:** "What is the minimum CGPA a student needs to maintain to avoid academic probation at XYZ National University?"
+
+**Expected Path:**  
+decide_retrieval → retrieve → grade_documents → prepare_context → generate → check_hallucination → END
+
+**Expected Behavior:**  
+- Retrieval needed (university-specific policy)  
+- University_Academic_Policies.pdf chunks retrieved  
+- Relevant chunks about GPA/probation graded as relevant  
+- Clean answer generated from policy document  
+- Hallucination check passes (updated rules allow university name)  
+
+**Actual Console Trace:**
+```text
+[CHECKPOINT 1 - RETRIEVAL DECISION]
+  Query: What is the minimum CGPA a student needs to maintain to avoid academic probation at XYZ National University?
+  Needs Retrieval: True
+  Reasoning: The query asks for specific university policy regarding academic probation and CGPA requirements, which requires searching the academic policies document.
+
+[RETRIEVAL] Searching knowledge base for: 'What is the minimum CGPA a student needs to maintain to avoid academic probation at XYZ National University?'
+  Retrieved 4 document chunks.
+  Doc 1: relevant=True | The document explicitly states that students are placed on academic probation if their CGPA falls below 1.50 for two consecutive semesters.
+  Result: 1/4 documents are relevant.
+
+[CONTEXT PREPARED] Using 1 relevant documents.
+
+[GENERATION] Generating response (attempt 1)...
+  Generated response: To avoid academic probation at XYZ National University, a student must ensure their CGPA does not fall below 1.50 for two consecutive semesters.
+
+[CHECKPOINT 3 - HALLUCINATION CHECK] (attempt 1)
+  Hallucination detected: False
+  Explanation: none
+```
+
+**Final Answer:**
+To avoid academic probation at XYZ National University, a student must ensure their CGPA does not fall below 1.50 for two consecutive semesters.
+
+**Verdict:** ✅ PASS
+
+---
+
+## Summary Table
+
+| # | Scenario | Query (short) | Path Taken | Result |
+|---|---|---|---|---|
+| 1 | No retrieval | Greeting | direct_answer | ✅ PASS |
+| 2 | Retrieval + relevant | EE professors | retrieve→grade→generate | ✅ PASS |
+| 3 | Web search fallback | World ranking | retrieve→grade→web→generate | ✅ PASS |
+| 4 | Hallucination retry | CS course list | retrieve→generate→retry | ✅ PASS |
+| 5 | Policy question | CGPA probation | retrieve→grade→generate | ✅ PASS |

graph.py

@@ -0,0 +1,538 @@
+import warnings
+warnings.filterwarnings("ignore")
+
+from typing import TypedDict, List, Optional, Annotated
+from langgraph.graph import StateGraph, END
+from langchain_groq import ChatGroq
+from langchain_core.documents import Document
+from tools import retrieve_documents, web_search
+import operator
+import json
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Set to True only for Test Case 4 demonstration
+HALLUCINATION_TEST_MODE = False 
+
+import re
+
+def safe_json_parse(text: str) -> dict:
+    """Safely parse JSON from LLM response, handling markdown and extra text."""
+    try:
+        # First attempt: direct parse
+        return json.loads(text.strip())
+    except json.JSONDecodeError:
+        # Second attempt: extract JSON block using regex
+        match = re.search(r'(\{.*\})|(\[.*\])', text, re.DOTALL)
+        if match:
+            json_str = match.group(0)
+            try:
+                return json.loads(json_str)
+            except json.JSONDecodeError:
+                # Third attempt: clean common markdown issues
+                clean_text = text.replace("```json", "").replace("```", "").strip()
+                try:
+                    return json.loads(clean_text)
+                except json.JSONDecodeError:
+                    return None
+        return None
+
+# --- STATE CLASS ---
+class AgentState(TypedDict):
+    query: str                          # The user's original question
+    needs_retrieval: bool               # Checkpoint 1 result: does this need retrieval?
+    retrieval_reasoning: str            # Why we decided to retrieve or not
+    retrieved_docs: List[dict]          # Raw documents from vector store
+    relevant_docs: List[dict]           # Filtered: only the relevant documents
+    use_web_search: bool                # True if all docs were irrelevant
+    web_results: List[dict]             # Results from Tavily web search
+    generation_context: str             # The final context string used for generation
+    response: str                       # The generated response
+    hallucination_detected: bool        # True if hallucination check failed
+    retry_count: int                    # How many times we've retried generation
+    final_answer: str                   # The final answer returned to the user
+    memory_context: str                 # Context from previous 2 exchanges
+    trace_steps: List[dict]             # List of checkpoint trace data
+    agent_path: str                     # String representing the logic flow
+
+# --- LLM INITIALIZATION ---
+llm = ChatGroq(
+    model="llama-3.3-70b-versatile",
+    temperature=0,
+    groq_api_key=os.getenv("GROQ_API")
+)
+
+# --- NODE 1: decide_retrieval ---
+def decide_retrieval(state: AgentState) -> dict:
+    query = state["query"]
+    
+    prompt = f"""You are a routing assistant for a university advisory system.
+    
+    Your job: Decide if the following query requires searching the university knowledge base 
+    (course catalogs, academic policies, faculty directory) OR if it can be answered directly 
+    from general knowledge or is a greeting/chitchat.
+    
+    Query: "{query}"
+    
+    Rules:
+    - If the query is a greeting, introduction, or social message → NO retrieval needed
+    - If the query asks about general concepts (e.g., "What does GPA stand for?") → NO retrieval needed
+    - If the query is about a specific course, prerequisite, credit hours, schedule → YES retrieval needed
+    - If the query is about university policies (grading, fees, attendance, withdrawal) → YES retrieval needed
+    - If the query is about a specific faculty member → YES retrieval needed
+    
+    Respond in this EXACT JSON format (no other text):
+    {{
+      "needs_retrieval": true or false,
+      "reasoning": "one sentence explanation"
+    }}
+    """
+    
+    response = llm.invoke(prompt)
+    data = safe_json_parse(response.content)
+    if data is None:
+        data = {"needs_retrieval": True, "reasoning": "Parsing error, defaulting to retrieval"}
+    
+    checkpoint_data = {
+        "checkpoint": 1,
+        "label": "RETRIEVAL DECISION",
+        "status": "pass" if data["needs_retrieval"] else "skip",
+        "detail": f"Needs Retrieval: {data['needs_retrieval']}",
+        "reasoning": data["reasoning"]
+    }
+    
+    return {
+        "needs_retrieval": data["needs_retrieval"],
+        "retrieval_reasoning": data["reasoning"],
+        "agent_path": "decide_retrieval",
+        "trace_steps": [checkpoint_data]
+    }
+
+# --- NODE 2: retrieve ---
+def retrieve(state: AgentState) -> dict:
+    query = state["query"]
+    print(f"\n[RETRIEVAL] Searching knowledge base for: '{query}'")
+    
+    docs = retrieve_documents.invoke({"query": query})
+    
+    print(f"  Retrieved {len(docs)} document chunks.")
+    for i, doc in enumerate(docs):
+        print(f"  Doc {i+1}: {doc['content'][:100]}... [Source: {doc['metadata'].get('source_file','unknown')}]")
+    
+    return {
+        "retrieved_docs": docs,
+        "agent_path": state["agent_path"] + " → retrieve"
+    }
+
+import asyncio
+
+# --- NODE 3: grade_documents ---
+async def grade_documents(state: AgentState) -> dict:
+    query = state["query"]
+    docs = state.get("retrieved_docs", [])
+    relevant_docs = []
+    
+    if not docs:
+        return {
+            "relevant_docs": [],
+            "use_web_search": True,
+            "agent_path": state["agent_path"] + " → grade_documents (no docs)",
+            "trace_steps": state["trace_steps"]
+        }
+
+    print(f"\n[CHECKPOINT 2 - RELEVANCE GRADING] Parallel batch grading {len(docs)} documents in 2 batches...")
+    
+    # Split into batches of 5 (for a total of 10 docs)
+    batch1 = docs[:5]
+    batch2 = docs[5:10]
+
+    async def grade_batch(batch, batch_num):
+        if not batch:
+            return []
+        
+        print(f"  → Batch {batch_num}: Processing {len(batch)} docs via Groq...")
+        batch_text = ""
+        for i, doc in enumerate(batch):
+            batch_text += f"\n--- DOCUMENT {i+1} ---\n{doc['content']}\n"
+            
+        prompt = f"""You are a relevance grader.
+        Query: "{query}"
+        Docs: {batch_text}
+        
+        CRITICAL: If a document contains information about a course, teacher, or university policy that MIGHT be related to the query, mark it as relevant. Be generous.
+        
+        Respond ONLY in JSON:
+        {{ "results": [ {{ "index": 1, "relevant": true }}, ... ] }}
+        """
+        
+        try:
+            response = await llm.ainvoke(prompt)
+            parsed = safe_json_parse(response.content)
+            
+            batch_relevant = []
+            if parsed and "results" in parsed:
+                for res in parsed["results"]:
+                    idx = res.get("index", 0) - 1
+                    if 0 <= idx < len(batch) and res.get("relevant"):
+                        batch_relevant.append(batch[idx])
+            
+            print(f"  ✓ Batch {batch_num} Finished.")
+            return batch_relevant
+        except Exception as e:
+            print(f"  × Batch {batch_num} Error: {e}")
+            return []
+
+    # Run 2 batches in parallel
+    results = await asyncio.gather(
+        grade_batch(batch1, 1),
+        grade_batch(batch2, 2)
+    )
+    
+    # Flatten results
+    for batch_result in results:
+        relevant_docs.extend(batch_result)
+    
+    relevant_count = len(relevant_docs)
+    total_count = len(docs)
+    
+    checkpoint_data = {
+        "checkpoint": 2,
+        "label": "RELEVANCE GRADING",
+        "status": "pass" if relevant_count > 0 else "fail",
+        "detail": f"{relevant_count}/{total_count} documents relevant (Parallel Batched)",
+        "docs_graded": total_count,
+        "docs_relevant": relevant_count,
+        "web_search_triggered": relevant_count == 0
+    }
+    
+    return {
+        "relevant_docs": relevant_docs,
+        "use_web_search": relevant_count == 0,
+        "agent_path": state["agent_path"] + " → grade_documents",
+        "trace_steps": state["trace_steps"] + [checkpoint_data]
+    }
+
+# --- NODE 4: web_search_node ---
+def web_search_node(state: AgentState) -> dict:
+    query = state["query"]
+    print(f"\n[WEB SEARCH FALLBACK] Searching web for: '{query}'")
+    
+    results = web_search.invoke({"query": query})
+    
+    print(f"  Found {len(results)} web results.")
+    
+    return {
+        "web_results": results,
+        "agent_path": state["agent_path"] + " → web_search_node"
+    }
+
+# --- NODE 5: prepare_context ---
+def prepare_context(state: AgentState) -> dict:
+    if state.get("use_web_search") and state.get("web_results"):
+        context_parts = []
+        for result in state["web_results"]:
+            context_parts.append(f"[Web Source: {result.get('url', 'unknown')}]\n{result.get('content', '')}")
+        context = "\n\n---\n\n".join(context_parts)
+        print(f"\n[CONTEXT PREPARED] Using web search results as context.")
+    elif state.get("relevant_docs"):
+        context_parts = []
+        for doc in state["relevant_docs"]:
+            meta = doc["metadata"]
+            source_label = f"[Source: {meta.get('source_file','?')} | Dept: {meta.get('department','?')}]"
+            context_parts.append(f"{source_label}\n{doc['content']}")
+        context = "\n\n---\n\n".join(context_parts)
+        print(f"\n[CONTEXT PREPARED] Using {len(state['relevant_docs'])} relevant documents.")
+    else:
+        context = ""
+        print(f"\n[CONTEXT PREPARED] No context available.")
+    
+    return {
+        "generation_context": context,
+        "agent_path": state["agent_path"] + " → prepare_context"
+    }
+
+# --- NODE 6: generate ---
+def generate(state: AgentState) -> dict:
+    query = state["query"]
+    context = state.get("generation_context", "")
+    retry_count = state.get("retry_count", 0)
+    
+    print(f"\n[GENERATION] Generating response (attempt {retry_count + 1})...")
+    if context:
+        print(f"  → Using {len(context)} characters of retrieved context.")
+    else:
+        print(f"  → No context available, using general knowledge.")
+    
+    memory_context = state.get("memory_context", "")
+    
+    if context:
+        prompt = f"""You are a helpful university course advisory assistant for XYZ National University.
+      
+      Previous conversation context:
+      {memory_context}
+      
+      CRITICAL INSTRUCTIONS:
+      1. EXHAUSTIVE LISTING: You must list EACH AND EVERY course found in the context. Search the context thoroughly for every mention of a course code or title.
+      2. CLEAN FORMATTING: Do NOT use asterisks (*) for bullets or bolding. Use numbered headers (e.g., 1., 2., 3.) for main courses and plain text for details.
+      3. STRUCTURE: For each course, provide: Name, Credits, Prerequisites, Instructor, and a brief Description.
+      4. ACCURACY: If a course mentions 'CS-501' but the context says 'Advanced Machine Learning', use the title from the context.
+      
+      Context:
+      {context}
+      
+      Student Question: {query}
+      
+      Answer clearly and professionally:
+      """
+    else:
+        prompt = f"""You are a helpful university course advisory assistant.
+      
+      Previous conversation context:
+      {memory_context}
+      
+      Answer the following question from your general knowledge.
+      
+      Question: {query}
+      
+      Provide a clear and helpful answer:
+      """
+    
+    response = llm.invoke(prompt)
+    generated = response.content
+    
+    print(f"  Generated response: {generated[:200]}...")
+    
+    return {
+        "response": generated,
+        "agent_path": state["agent_path"] + " → generate"
+    }
+
+# --- NODE 7: check_hallucination ---
+def check_hallucination(state: AgentState) -> dict:
+    response = state["response"]
+    context = state.get("generation_context", "")
+    retry_count = state.get("retry_count", 0)
+    use_web = state.get("use_web_search", False)
+    
+    print(f"\n[CHECKPOINT 3 - HALLUCINATION CHECK] (attempt {retry_count + 1})")
+    
+    # Force hallucination detection for demonstration purposes
+    if HALLUCINATION_TEST_MODE and retry_count == 0:
+        print("  [TEST MODE] Forcing hallucination detection for demonstration.")
+        return {
+            "hallucination_detected": True,
+            "retry_count": 1,
+            "hallucination_explanation": "TEST MODE: Forced hallucination for demonstration."
+        }
+        
+    # Skip check if no retrieval was used (direct general knowledge answer)
+    if not state.get("needs_retrieval", True):
+      print("  → No retrieval was used. Skipping hallucination check.")
+      return {
+        "hallucination_detected": False,
+        "final_answer": response
+      }
+    
+    # Skip check if no context is available
+    if not context:
+      print("  → No context available. Skipping hallucination check.")
+      return {
+        "hallucination_detected": False,
+        "final_answer": response
+      }
+    
+    # Use DIFFERENT strictness levels based on source type
+    if use_web:
+      strictness_instruction = """
+  This response was generated from WEB SEARCH RESULTS, not official documents.
+  Apply LENIENT checking:
+  - Only flag it if the response invents completely fabricated facts with 
+    no basis whatsoever in the web results.
+  - Reasonable inference, summarization, and synthesis from web results is ALLOWED.
+  - Minor extrapolation (e.g., inferring a rank number from ranking context) is OK.
+  - Do NOT flag responses that reasonably summarize or paraphrase web results.
+  - Only return hallucination_detected=true if the response contains a specific 
+    claim that directly contradicts the web results."""
+    else:
+      strictness_instruction = """
+  This response was generated from OFFICIAL UNIVERSITY DOCUMENTS.
+  Apply STRICT checking:
+  - Flag any specific fact (number, name, policy, fee, grade, course code) 
+    that is NOT present in the context.
+  - Do NOT flag the university name "XYZ National University" as a hallucination.
+  - Do NOT flag polite conversational phrases or general framing.
+  - Do NOT flag minor rephrasing or summarization of document content."""
+    
+    prompt = f"""You are a hallucination detector for a university advisory AI.
+    
+  {strictness_instruction}
+  
+  Context:
+  ---
+  {context}
+  ---
+  
+  Generated Response:
+  ---
+  {response}
+  ---
+  
+  Respond in this EXACT JSON format (no other text):
+  {{
+    "hallucination_detected": true or false,
+    "explanation": "specific invented fact found, or 'none' if clean"
+  }}
+  """
+    
+    result = llm.invoke(prompt)
+    data = safe_json_parse(result.content)
+    if data is None:
+      data = {"hallucination_detected": False, "explanation": "Parsing error, assuming clean"}
+    
+    print(f"  Hallucination detected: {data['hallucination_detected']}")
+    print(f"  Explanation: {data['explanation']}")
+    
+    checkpoint_data = {
+        "checkpoint": 3,
+        "label": "HALLUCINATION CHECK",
+        "status": "fail" if data["hallucination_detected"] else "pass",
+        "detail": data["explanation"],
+        "retries_used": retry_count
+    }
+    
+    if data["hallucination_detected"]:
+      new_retry_count = retry_count + 1
+      print(f"  → Hallucination found! Retry count: {new_retry_count}")
+      
+      return {
+        "hallucination_detected": True,
+        "retry_count": new_retry_count,
+        "agent_path": state["agent_path"] + " → check_hallucination",
+        "trace_steps": state["trace_steps"] + [checkpoint_data]
+      }
+    else:
+      return {
+        "hallucination_detected": False,
+        "final_answer": response,
+        "agent_path": state["agent_path"] + " → check_hallucination → END",
+        "trace_steps": state["trace_steps"] + [checkpoint_data]
+      }
+
+# --- NODE 8: direct_answer ---
+def direct_answer(state: AgentState) -> dict:
+    query = state["query"]
+    memory_context = state.get("memory_context", "")
+    
+    print(f"\n[DIRECT ANSWER] No retrieval needed. Answering from general knowledge.")
+    
+    prompt = f"""You are a friendly and helpful university course advisory assistant.
+    
+    Previous conversation context:
+    {memory_context}
+    
+    Answer the following message naturally and helpfully.
+    
+    Message: {query}
+    """
+    
+    response = llm.invoke(prompt)
+    print(f"  Response: {response.content[:200]}...")
+    
+    return {
+        "final_answer": response.content,
+        "needs_retrieval": False,
+        "agent_path": state["agent_path"] + " → direct_answer → END"
+    }
+
+# --- NODE 9: max_retries_exceeded ---
+MAX_RETRIES = 2
+
+def max_retries_exceeded(state: AgentState) -> dict:
+    print(f"\n[MAX RETRIES EXCEEDED] Could not generate a verified response after {MAX_RETRIES} attempts.")
+    disclaimer = (
+        "I was unable to generate a verified response for your query. "
+        "The information I found may be incomplete or inconsistent. "
+        "Please contact the university directly or visit the official university portal for accurate information."
+    )
+    return {
+        "final_answer": disclaimer,
+        "agent_path": state["agent_path"] + " → max_retries_exceeded → END"
+    }
+
+# --- CONDITIONAL EDGE FUNCTIONS ---
+def route_after_retrieval_decision(state: AgentState) -> str:
+    if state["needs_retrieval"]:
+        return "retrieve"
+    else:
+        return "direct_answer"
+
+def route_after_grading(state: AgentState) -> str:
+    if state["use_web_search"]:
+        return "web_search_node"
+    else:
+        return "prepare_context"
+
+def route_after_hallucination_check(state: AgentState) -> str:
+    if not state["hallucination_detected"]:
+        return END
+    elif state.get("retry_count", 0) >= MAX_RETRIES:
+        return "max_retries_exceeded"
+    else:
+        return "generate"
+
+# --- BUILD THE STATEGRAPH ---
+def build_graph():
+    graph = StateGraph(AgentState)
+    
+    graph.add_node("decide_retrieval", decide_retrieval)
+    graph.add_node("retrieve", retrieve)
+    graph.add_node("grade_documents", grade_documents)
+    graph.add_node("web_search_node", web_search_node)
+    graph.add_node("prepare_context", prepare_context)
+    graph.add_node("generate", generate)
+    graph.add_node("check_hallucination", check_hallucination)
+    graph.add_node("direct_answer", direct_answer)
+    graph.add_node("max_retries_exceeded", max_retries_exceeded)
+    
+    graph.set_entry_point("decide_retrieval")
+    
+    graph.add_edge("retrieve", "grade_documents")
+    graph.add_edge("web_search_node", "prepare_context")
+    graph.add_edge("prepare_context", "generate")
+    graph.add_edge("generate", "check_hallucination")
+    graph.add_edge("max_retries_exceeded", END)
+    graph.add_edge("direct_answer", END)
+    
+    graph.add_conditional_edges(
+        "decide_retrieval",
+        route_after_retrieval_decision,
+        {
+            "retrieve": "retrieve",
+            "direct_answer": "direct_answer"
+        }
+    )
+    
+    graph.add_conditional_edges(
+        "grade_documents",
+        route_after_grading,
+        {
+            "web_search_node": "web_search_node",
+            "prepare_context": "prepare_context"
+        }
+    )
+    
+    graph.add_conditional_edges(
+        "check_hallucination",
+        route_after_hallucination_check,
+        {
+            END: END,
+            "max_retries_exceeded": "max_retries_exceeded",
+            "generate": "generate"
+        }
+    )
+    
+    return graph.compile()
+
+app = build_graph()

ingest.py

@@ -0,0 +1,96 @@
+from langchain_community.document_loaders import PyPDFLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_community.vectorstores import Chroma
+from langchain_huggingface import HuggingFaceEmbeddings
+import os
+
+# --- EMBEDDING MODEL ---
+embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
+
+# --- PDF LIST ---
+PDF_SOURCES = [
+    {
+      "path": "data/CS_Department_Catalog.pdf",
+      "department": "Computer Science",
+      "doc_type": "course_catalog",
+      "course_level": "undergraduate_graduate"
+    },
+    {
+      "path": "data/EE_Department_Catalog.pdf",
+      "department": "Electrical Engineering",
+      "doc_type": "course_catalog",
+      "course_level": "undergraduate"
+    },
+    {
+      "path": "data/BBA_Department_Catalog.pdf",
+      "department": "Business Administration",
+      "doc_type": "course_catalog",
+      "course_level": "undergraduate"
+    },
+    {
+      "path": "data/University_Academic_Policies.pdf",
+      "department": "University",
+      "doc_type": "academic_policy",
+      "course_level": "all"
+    },
+    {
+      "path": "data/Faculty_Directory.pdf",
+      "department": "All",
+      "doc_type": "faculty_directory",
+      "course_level": "all"
+    }
+]
+
+import shutil
+
+def create_vector_store():
+    """
+    Creates a pure-Python vector store (pickle) to bypass ChromaDB/Python 3.14 crashes.
+    """
+    print("Initializing embeddings...")
+    from langchain_huggingface import HuggingFaceEmbeddings
+    embeddings_model = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
+    
+    all_chunks = []
+    # Increase size and overlap to keep headers with content
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=1500,
+        chunk_overlap=400,
+        separators=["\n\n", "\n", ".", " ", ""]
+    )
+    
+    for source in PDF_SOURCES:
+        if not os.path.exists(source["path"]):
+            print(f"Warning: File not found {source['path']}")
+            continue
+            
+        print(f"Processing: {source['path']}")
+        loader = PyPDFLoader(source["path"])
+        pages = loader.load()
+        
+        # Inject metadata directly into text to ensure context is never lost
+        for doc in pages:
+            prefix = f"[DEPARTMENT: {source['department']}] [DOC: {source['doc_type']}]\n"
+            doc.page_content = prefix + doc.page_content
+            
+            doc.metadata["department"] = source["department"]
+            doc.metadata["doc_type"] = source["doc_type"]
+            doc.metadata["course_level"] = source["course_level"]
+            doc.metadata["source_file"] = source["path"]
+            
+        chunks = splitter.split_documents(pages)
+        all_chunks.extend(chunks)
+        
+    print(f"Embedding {len(all_chunks)} chunks (Pure Python)...")
+    texts = [chunk.page_content for chunk in all_chunks]
+    embeddings = embeddings_model.embed_documents(texts)
+    
+    db_path = "vector_store_fallback.pkl"
+    import pickle
+    with open(db_path, "wb") as f:
+        pickle.dump({"chunks": all_chunks, "embeddings": embeddings}, f)
+        
+    print(f"Saved {len(all_chunks)} chunks to {db_path}")
+
+if __name__ == "__main__":
+    create_vector_store()

requirements.txt

@@ -0,0 +1,14 @@
+langchain==0.2.16
+langchain-community==0.2.16
+langchain-google-genai==1.0.10
+langgraph==0.2.28
+chromadb==0.5.5
+pypdf==4.3.1
+tiktoken>=0.7.0
+pydantic==2.8.2
+tavily-python==0.3.3
+python-dotenv==1.0.1
+sentence-transformers==3.0.1
+langchain-huggingface==0.0.3
+fastapi==0.111.0
+uvicorn==0.30.1

scratch/check_retrieval.py

@@ -0,0 +1,17 @@
+from ingest import get_retriever
+import sys
+
+def check_query(query):
+    retriever = get_retriever()
+    docs = retriever.invoke(query)
+    print(f"\n--- Search results for: '{query}' ---\n")
+    for i, doc in enumerate(docs):
+        print(f"Result {i+1} (Source: {doc.metadata.get('source_file')}):")
+        print(f"{doc.page_content}\n")
+        print("-" * 50)
+
+if __name__ == "__main__":
+    teacher_query = "Farhan Qureshi"
+    if len(sys.argv) > 1:
+        teacher_query = sys.argv[1]
+    check_query(teacher_query)

self_rag_agent.py

@@ -0,0 +1,111 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from typing import List, Optional
+import uvicorn
+from dotenv import load_dotenv
+import os
+
+# Load environment variables
+load_dotenv()
+
+from graph import app as langgraph_app
+
+class MemoryItem(BaseModel):
+    role: str
+    content: str
+
+class ChatRequest(BaseModel):
+    query: str
+    window_memory: List[MemoryItem] = []
+
+class CheckpointData(BaseModel):
+    checkpoint: int
+    label: str
+    status: str
+    detail: str
+    reasoning: Optional[str] = None
+    docs_graded: Optional[int] = None
+    docs_relevant: Optional[int] = None
+    web_search_triggered: Optional[bool] = False
+    retries_used: Optional[int] = 0
+
+class ChatResponse(BaseModel):
+    answer: str
+    path: str
+    trace: List[CheckpointData]
+    used_web_search: bool
+    retry_count: int
+
+app_api = FastAPI(title="XYZ University Advisory Agent API")
+
+app_api.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://localhost:3000"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+@app_api.post("/chat", response_model=ChatResponse)
+async def chat_endpoint(request: ChatRequest):
+    try:
+        # Build initial state including window memory as context
+        memory_context = ""
+        if request.window_memory:
+            memory_context = "\n\nRecent conversation context:\n"
+            for item in request.window_memory:
+                role_label = "Student" if item.role == "user" else "Advisor"
+                memory_context += f"{role_label}: {item.content}\n"
+        
+        initial_state = {
+            "query": request.query,
+            "memory_context": memory_context,
+            "needs_retrieval": False,
+            "retrieval_reasoning": "",
+            "retrieved_docs": [],
+            "relevant_docs": [],
+            "use_web_search": False,
+            "web_results": [],
+            "generation_context": "",
+            "response": "",
+            "hallucination_detected": False,
+            "retry_count": 0,
+            "final_answer": "",
+            "trace_steps": [],
+            "agent_path": ""
+        }
+        
+        final_state = await langgraph_app.ainvoke(initial_state)
+        
+        # Build trace from final_state
+        trace = final_state.get("trace_steps", [])
+        
+        return ChatResponse(
+            answer=final_state.get("final_answer", "No answer generated."),
+            path=final_state.get("agent_path", "unknown"),
+            trace=trace,
+            used_web_search=final_state.get("use_web_search", False),
+            retry_count=final_state.get("retry_count", 0)
+        )
+    except Exception as e:
+        print(f"Error in chat endpoint: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app_api.get("/health")
+async def health():
+    return {"status": "online", "agent": "XYZ University Advisory Agent"}
+
+# --- SILENCE EXTERNAL NOISE ---
+# These endpoints are added to stop 404 logs from external dashboards (VPTQ)
+@app_api.get("/api/pipeline/status")
+@app_api.get("/api/stats/pipeline-status")
+async def pipeline_status():
+    return {"status": "idle", "message": "University Advisor Active"}
+
+@app_api.post("/api/stats/run-pipeline")
+async def run_pipeline():
+    return {"status": "skipped", "message": "Pipeline logic not applicable to RAG Agent"}
+
+if __name__ == "__main__":
+    uvicorn.run("self_rag_agent:app_api", host="0.0.0.0", port=8000, reload=True)

tools.py

@@ -0,0 +1,71 @@
+from langchain.tools import tool
+from pydantic import BaseModel, Field
+from langchain_community.tools.tavily_search import TavilySearchResults
+import os
+from dotenv import load_dotenv
+import numpy as np
+from langchain_huggingface import HuggingFaceEmbeddings
+
+load_dotenv()
+
+# Initialize embeddings once
+embeddings_model = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
+
+# --- TOOL 1: retrieve_documents ---
+
+class RetrieveInput(BaseModel):
+    query: str = Field(description="The user's question to search for in the university knowledge base")
+
+@tool(args_schema=RetrieveInput)
+def retrieve_documents(query: str, k: int = 15) -> list[dict]:
+    """
+    Retrieves relevant document chunks using Python 3.14 safe similarity search.
+    """
+    import pickle
+    db_path = "vector_store_fallback.pkl"
+    if not os.path.exists(db_path):
+        print(f"Error: {db_path} not found.")
+        return []
+
+    with open(db_path, "rb") as f:
+        data = pickle.load(f)
+        
+    chunks = data["chunks"]
+    chunk_embeddings = np.array(data["embeddings"])
+    
+    # Embed the query
+    query_embedding = np.array(embeddings_model.embed_query(query))
+    
+    # Calculate cosine similarity: (A . B) / (||A|| * ||B||)
+    dot_products = np.dot(chunk_embeddings, query_embedding)
+    norms_chunks = np.linalg.norm(chunk_embeddings, axis=1)
+    norm_query = np.linalg.norm(query_embedding)
+    similarities = dot_products / (norms_chunks * norm_query)
+    
+    # Get top k indices
+    top_indices = np.argsort(similarities)[::-1][:k]
+    
+    results = []
+    for idx in top_indices:
+        results.append({
+            "content": chunks[idx].page_content,
+            "metadata": chunks[idx].metadata
+        })
+    return results
+
+# --- TOOL 2: web_search ---
+
+class WebSearchInput(BaseModel):
+    query: str = Field(description="Search query for finding information on the web when the knowledge base does not have the answer")
+
+@tool(args_schema=WebSearchInput)
+def web_search(query: str) -> list[dict]:
+    """
+    Performs a web search using Tavily to find information not available in the 
+    university's internal knowledge base. Use this as a FALLBACK tool only when 
+    all retrieved documents from the knowledge base were graded as irrelevant.
+    Returns a list of web search results with title, content, and URL.
+    """
+    search = TavilySearchResults(max_results=3, tavily_api_key=os.getenv("TAVILY_API_KEY"))
+    results = search.invoke(query)
+    return results

university-advisor-ui/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>XYZ University Advisory Agent</title>
+  </head>
+  <body class="bg-brand-bg font-body text-brand-text antialiased">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

university-advisor-ui/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "university-advisor-ui",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "lucide-react": "^0.383.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@typescript-eslint/eslint-plugin": "^7.13.1",
+    "@typescript-eslint/parser": "^7.13.1",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "eslint": "^8.57.0",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "eslint-plugin-react-refresh": "^0.4.7",
+    "postcss": "^8.4.38",
+    "tailwindcss": "^3.4.4",
+    "typescript": "^5.2.2",
+    "vite": "^5.3.1"
+  }
+}

university-advisor-ui/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

university-advisor-ui/src/App.tsx

@@ -0,0 +1,161 @@
+import React, { useState, useRef, useEffect } from 'react';
+import Header from './components/Header';
+import Sidebar from './components/Sidebar';
+import MessageBubble from './components/MessageBubble';
+import TracePanel from './components/TracePanel';
+import InputBar from './components/InputBar';
+import { Message, TraceStep, WindowMemoryItem } from './types';
+import { sendMessage, ChatResponse } from './services/api';
+
+const App: React.FC = () => {
+  const [messages, setMessages] = useState<Message[]>([
+    {
+      id: 'welcome',
+      role: 'assistant',
+      content: "Welcome to the XYZ University advisory portal. How can I help you today?",
+      timestamp: new Date(),
+    }
+  ]);
+  const [windowMemory, setWindowMemory] = useState<WindowMemoryItem[]>([]);
+  const [inputText, setInputText] = useState("");
+  const [isLoading, setIsLoading] = useState(false);
+  const [sidebarOpen, setSidebarOpen] = useState(true);
+  const [traceOpen, setTraceOpen] = useState(false);
+  const [activeTrace, setActiveTrace] = useState<{ steps: TraceStep[], path: string }>({ steps: [], path: "" });
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+    }
+  }, [messages]);
+
+  const updateWindowMemory = (userMsg: string, botMsg: string) => {
+    setWindowMemory(prev => {
+      const newItems: WindowMemoryItem[] = [
+        { role: 'user', content: userMsg },
+        { role: 'assistant', content: botMsg }
+      ];
+      const combined = [...prev, ...newItems];
+      return combined.slice(-4);
+    });
+  };
+
+  const handleSend = async (forcedQuery?: string) => {
+    const query = forcedQuery || inputText;
+    if (!query.trim() || isLoading) return;
+
+    const userMessage: Message = {
+      id: Date.now().toString(),
+      role: 'user',
+      content: query,
+      timestamp: new Date(),
+    };
+
+    setMessages(prev => [...prev, userMessage]);
+    setInputText("");
+    setIsLoading(true);
+
+    const botPlaceholderId = (Date.now() + 1).toString();
+    const botLoadingMessage: Message = {
+      id: botPlaceholderId,
+      role: 'assistant',
+      content: "",
+      timestamp: new Date(),
+      isLoading: true
+    };
+    setMessages(prev => [...prev, botLoadingMessage]);
+
+    try {
+      const response: ChatResponse = await sendMessage({
+        query,
+        window_memory: windowMemory
+      });
+
+      const traceSteps: TraceStep[] = response.trace.map((t, i) => ({
+        ...t,
+        id: `t-${Date.now()}-${i}`,
+        timestamp: new Date()
+      }));
+
+      const botMessage: Message = {
+        id: botPlaceholderId,
+        role: 'assistant',
+        content: response.answer,
+        timestamp: new Date(),
+        trace: traceSteps,
+        path: response.path
+      };
+
+      setMessages(prev => prev.map(m => m.id === botPlaceholderId ? botMessage : m));
+      setActiveTrace({ steps: traceSteps, path: response.path });
+      updateWindowMemory(query, response.answer);
+      
+    } catch (error) {
+      const errorMessage: Message = {
+        id: botPlaceholderId,
+        role: 'assistant',
+        content: "System error: Failed to connect to university records.",
+        timestamp: new Date(),
+      };
+      setMessages(prev => prev.map(m => m.id === botPlaceholderId ? errorMessage : m));
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <div className="flex flex-col h-screen bg-[#070B14] text-slate-200 overflow-hidden font-body">
+      <Header onToggleSidebar={() => setSidebarOpen(!sidebarOpen)} />
+      
+      <div className="flex-1 flex overflow-hidden">
+        {/* Sidebar */}
+        <Sidebar 
+          isOpen={sidebarOpen} 
+          onQuickTopic={handleSend} 
+          windowMemory={windowMemory} 
+        />
+
+        {/* Main Chat Area */}
+        <main className="flex-1 flex flex-col relative overflow-hidden">
+          {/* Messages Feed */}
+          <div 
+            ref={scrollRef}
+            className="flex-1 overflow-y-auto px-4 py-6 scroll-smooth"
+          >
+            <div className="max-w-4xl mx-auto w-full">
+              {messages.map((msg) => (
+                <MessageBubble 
+                  key={msg.id} 
+                  message={msg} 
+                  onTraceClick={() => setTraceOpen(true)}
+                />
+              ))}
+            </div>
+          </div>
+
+          {/* Trace Panel */}
+          <TracePanel 
+            isOpen={traceOpen} 
+            onToggle={() => setTraceOpen(!traceOpen)} 
+            steps={activeTrace.steps}
+            path={activeTrace.path}
+          />
+
+          {/* Input Area */}
+          <div className="w-full">
+             <InputBar 
+              value={inputText} 
+              onChange={setInputText} 
+              onSend={() => handleSend()} 
+              isLoading={isLoading} 
+            />
+          </div>
+        </main>
+      </div>
+    </div>
+  );
+};
+
+export default App;

university-advisor-ui/src/components/Header.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { GraduationCap, Menu } from 'lucide-react';
+
+interface HeaderProps {
+  onToggleSidebar: () => void;
+}
+
+const Header: React.FC<HeaderProps> = ({ onToggleSidebar }) => {
+  return (
+    <header className="h-14 bg-[#040811] border-b border-slate-800 flex items-center justify-between px-4 shrink-0 z-50">
+      <div className="flex items-center gap-3">
+        <button 
+          onClick={onToggleSidebar} 
+          className="text-slate-500 hover:text-slate-300 transition-colors p-1"
+        >
+          <Menu size={18} />
+        </button>
+        <div className="flex items-center gap-2">
+          <GraduationCap size={18} className="text-amber-400" />
+          <span className="text-sm font-semibold text-slate-200"
+                style={{fontFamily: 'Playfair Display, serif'}}>
+            XYZ National University
+          </span>
+        </div>
+      </div>
+      
+      <div className="flex items-center gap-2.5 bg-slate-900/50 px-3 py-1.5 rounded-full border border-slate-800">
+        <div className="w-1.5 h-1.5 rounded-full bg-emerald-500 animate-pulse shadow-[0_0_8px_rgba(16,185,129,0.5)]" />
+        <span className="text-[10px] font-mono text-slate-500 uppercase tracking-widest font-bold">Agent Online</span>
+      </div>
+    </header>
+  );
+};
+
+export default Header;

university-advisor-ui/src/components/InputBar.tsx

@@ -0,0 +1,57 @@
+import React, { useRef, useEffect } from 'react';
+import { Send, Loader2 } from 'lucide-react';
+
+interface InputBarProps {
+  value: string;
+  onChange: (value: string) => void;
+  onSend: () => void;
+  isLoading: boolean;
+}
+
+const InputBar: React.FC<InputBarProps> = ({ value, onChange, onSend, isLoading }) => {
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  useEffect(() => {
+    if (textareaRef.current) {
+      textareaRef.current.style.height = 'auto';
+      textareaRef.current.style.height = `${Math.min(textareaRef.current.scrollHeight, 120)}px`;
+    }
+  }, [value]);
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      onSend();
+    }
+  };
+
+  return (
+    <div className="p-3 border-t border-slate-800 bg-[#040811] shrink-0">
+      <div className="flex gap-2 items-end max-w-4xl mx-auto w-full">
+        <textarea
+          ref={textareaRef}
+          value={value}
+          onChange={e => onChange(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Ask about courses, faculty, policies..."
+          rows={2}
+          disabled={isLoading}
+          className="flex-1 bg-slate-900 border border-slate-800 rounded-xl px-4 py-3 text-sm text-slate-200 placeholder-slate-600 focus:outline-none focus:ring-1 focus:ring-blue-600 resize-none font-body transition-all disabled:opacity-50"
+        />
+        <button
+          onClick={onSend}
+          disabled={isLoading || !value.trim()}
+          className="w-12 h-12 bg-blue-600 hover:bg-blue-700 disabled:bg-slate-800 disabled:text-slate-600 text-white rounded-xl flex items-center justify-center transition-all shrink-0 shadow-lg shadow-blue-900/10 hover:shadow-blue-900/30 active:scale-95"
+        >
+          {isLoading ? (
+            <Loader2 size={18} className="animate-spin" />
+          ) : (
+            <Send size={18} />
+          )}
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default InputBar;

university-advisor-ui/src/components/MessageBubble.tsx

@@ -0,0 +1,132 @@
+import React from 'react';
+import { GraduationCap, Loader2 } from 'lucide-react';
+import { Message } from '../types';
+
+interface MessageBubbleProps {
+  message: Message;
+  onTraceClick: (checkpoint: number) => void;
+}
+
+const MessageBubble: React.FC<MessageBubbleProps> = ({ message, onTraceClick }) => {
+  const isUser = message.role === "user";
+  const formatTime = (date: Date) => {
+    return new Date(date).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+  };
+
+  if (message.isLoading) {
+    return (
+      <div className="flex justify-start mb-6 animate-fade-slide-up">
+        <div className="max-w-[75%]">
+          <div className="flex items-center gap-1.5 mb-1.5 pl-1">
+            <GraduationCap size={12} className="text-amber-400" />
+            <span className="text-xs text-amber-400/80 font-semibold tracking-wide">XYZ Advisor</span>
+          </div>
+          <div className="bg-slate-900 border border-slate-800 rounded-2xl rounded-tl-sm px-4 py-3 border-l-2 border-l-blue-600 flex items-center gap-3">
+             <div className="flex gap-1">
+              <div className="w-1.5 h-1.5 rounded-full bg-blue-500 animate-typing-bounce" style={{ animationDelay: '0ms' }}></div>
+              <div className="w-1.5 h-1.5 rounded-full bg-blue-500 animate-typing-bounce" style={{ animationDelay: '150ms' }}></div>
+              <div className="w-1.5 h-1.5 rounded-full bg-blue-500 animate-typing-bounce" style={{ animationDelay: '300ms' }}></div>
+            </div>
+            <span className="text-xs text-slate-500 font-mono italic">Analyzing...</span>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  if (isUser) {
+    return (
+      <div className="flex justify-end mb-4 animate-fade-slide-up">
+        <div className="max-w-[70%] bg-blue-900/40 border border-blue-800/50 rounded-2xl rounded-tr-sm px-4 py-3">
+          <p className="text-sm text-slate-200 leading-relaxed font-body">
+            {message.content}
+          </p>
+          <p className="text-xs text-slate-600 mt-1.5 text-right font-mono">
+            {formatTime(message.timestamp)}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const trace = message.trace;
+
+  return (
+    <div className="flex justify-start mb-6 animate-fade-slide-up">
+      <div className="max-w-[75%]">
+        {/* Advisor label */}
+        <div className="flex items-center gap-1.5 mb-1.5 pl-1">
+          <GraduationCap size={12} className="text-amber-400" />
+          <span className="text-xs text-amber-400/80 font-semibold tracking-wide">
+            XYZ Advisor
+          </span>
+          <span className="text-xs text-slate-700 font-mono ml-4">
+            {formatTime(message.timestamp)}
+          </span>
+        </div>
+        
+        {/* Message content */}
+        <div className="bg-slate-900 border border-slate-800 rounded-2xl rounded-tl-sm px-4 py-3 border-l-2 border-l-blue-600 shadow-sm">
+          <p className="text-sm text-slate-200 leading-relaxed whitespace-pre-wrap font-body">
+            {message.content}
+          </p>
+        </div>
+        
+        {/* Minimal checkpoint row */}
+        {trace && (
+          <div className="flex items-center gap-2 mt-2 pl-1">
+            {/* Checkpoint 1 - Retrieval */}
+            <div className="flex items-center gap-1.5">
+              <div className={`w-2 h-2 rounded-full ${
+                trace?.find(t => t.checkpoint === 1)?.status === 'pass' 
+                  ? 'bg-emerald-500' : 'bg-slate-600'
+              }`} />
+              <span className="text-[10px] font-mono text-slate-500 uppercase tracking-tight">
+                {trace?.find(t => t.checkpoint === 1)?.status === 'skip' 
+                  ? 'direct' : 'retrieved'}
+              </span>
+            </div>
+            
+            <span className="text-slate-800 text-[10px]">•</span>
+            
+            {/* Checkpoint 2 - Grading */}
+            <div className="flex items-center gap-1.5">
+              <div className={`w-2 h-2 rounded-full ${
+                trace?.find(t => t.checkpoint === 2)?.web_search_triggered 
+                  ? 'bg-amber-500' 
+                  : trace?.find(t => t.checkpoint === 2)?.status === 'pass'
+                    ? 'bg-emerald-500' : 'bg-slate-600'
+              }`} />
+              <span className="text-[10px] font-mono text-slate-500 uppercase tracking-tight">
+                {trace?.find(t => t.checkpoint === 2)?.web_search_triggered 
+                  ? 'web' 
+                  : `${trace?.find(t => t.checkpoint === 2)?.docs_relevant ?? 0}/${trace?.find(t => t.checkpoint === 2)?.docs_graded ?? 0} docs`}
+              </span>
+            </div>
+            
+            <span className="text-slate-800 text-[10px]">•</span>
+            
+            {/* Checkpoint 3 - Hallucination */}
+            <div className="flex items-center gap-1.5">
+              <div className={`w-2 h-2 rounded-full ${
+                (trace?.find(t => t.checkpoint === 3)?.retries_used ?? 0) > 0 
+                  ? 'bg-amber-500' : 'bg-emerald-500'
+              }`} />
+              <span className="text-[10px] font-mono text-slate-500 uppercase tracking-tight">verified</span>
+            </div>
+            
+            {/* Expand trace button */}
+            <button 
+              onClick={() => onTraceClick(0)} // Pass 0 or any dummy, trace panel handles active message
+              className="ml-auto text-[10px] text-slate-600 hover:text-blue-400 font-mono transition-colors uppercase tracking-wider"
+            >
+              view trace ›
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default MessageBubble;

university-advisor-ui/src/components/Sidebar.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { 
+  BookOpen, 
+  Users, 
+  ShieldCheck, 
+  CreditCard, 
+  Calendar, 
+  GraduationCap
+} from 'lucide-react';
+import { WindowMemoryItem } from '../types';
+
+interface SidebarProps {
+  onQuickTopic: (topic: string) => void;
+  windowMemory: WindowMemoryItem[];
+  isOpen: boolean;
+}
+
+const Sidebar: React.FC<SidebarProps> = ({ onQuickTopic, windowMemory, isOpen }) => {
+  if (!isOpen) return null;
+
+  const quickTopics = [
+    { label: "Prerequisites", icon: <BookOpen size={14} />, query: "What are the prerequisites for Advanced Algorithms?" },
+    { label: "Faculty", icon: <Users size={14} />, query: "Who are the professors in the Computer Science department?" },
+    { label: "Policies", icon: <ShieldCheck size={14} />, query: "What is the policy for academic probation?" },
+    { label: "Fee Structure", icon: <CreditCard size={14} />, query: "What are the tuition fees for the BSCS program?" },
+    { label: "Schedule", icon: <Calendar size={14} />, query: "When does the Fall 2025 semester start?" },
+    { label: "Requirements", icon: <GraduationCap size={14} />, query: "What are the total credit hours required for graduation?" },
+  ];
+
+  return (
+    <aside className="w-64 h-full bg-[#0D1117] border-r border-slate-800 flex flex-col relative shrink-0 transition-all duration-150">
+      <div className="p-4">
+        {/* Logo area */}
+        <div className="mb-6">
+          <div className="flex items-center gap-2 mb-1">
+            <GraduationCap size={18} className="text-amber-400" />
+            <span className="text-sm font-semibold text-slate-200" 
+                  style={{fontFamily: 'Playfair Display, serif'}}>
+              XYZ Advisory
+            </span>
+          </div>
+          <p className="text-xs text-slate-600 pl-6 font-body">
+            Self-RAG Course Agent
+          </p>
+        </div>
+        
+        {/* Divider */}
+        <div className="border-t border-slate-800 mb-4" />
+        
+        {/* Quick Topics */}
+        <p className="text-[10px] text-slate-600 uppercase tracking-[0.2em] mb-3 font-mono">
+          Quick Topics
+        </p>
+        <div className="flex flex-col gap-1">
+          {quickTopics.map(topic => (
+            <button
+              key={topic.label}
+              onClick={() => onQuickTopic(topic.query)}
+              className="flex items-center gap-3 text-left px-3 py-2 rounded-lg text-xs text-slate-400 
+                         hover:bg-slate-800 hover:text-slate-200 
+                         transition-colors duration-150 font-body"
+            >
+              <span className="opacity-50">{topic.icon}</span>
+              {topic.label}
+            </button>
+          ))}
+        </div>
+        
+        {/* Context indicator at bottom */}
+        <div className="absolute bottom-4 left-4 right-4">
+          <div className="bg-slate-900 rounded-lg p-3 border border-slate-800 shadow-sm">
+            <p className="text-[10px] font-mono text-slate-600 mb-1 uppercase tracking-wider">
+              💬 Memory window
+            </p>
+            <p className="text-[11px] text-slate-500 font-body">
+              {windowMemory.length > 0 
+                ? `${windowMemory.length / 2} exchange(s) in context`
+                : 'No context yet'}
+            </p>
+          </div>
+        </div>
+      </div>
+    </aside>
+  );
+};
+
+export default Sidebar;

university-advisor-ui/src/components/TracePanel.tsx

@@ -0,0 +1,135 @@
+import React, { useRef, useEffect } from 'react';
+import { 
+  Terminal, 
+  ChevronUp, 
+  ChevronDown, 
+  CheckCircle2, 
+  XCircle, 
+  FastForward, 
+  Loader2, 
+  Globe,
+  RefreshCcw,
+  ArrowRight
+} from 'lucide-react';
+import { TraceStep } from '../types';
+
+interface TracePanelProps {
+  isOpen: boolean;
+  onToggle: () => void;
+  steps: TraceStep[];
+  path: string;
+}
+
+const TracePanel: React.FC<TracePanelProps> = ({ isOpen, onToggle, steps, path }) => {
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isOpen && panelRef.current) {
+      panelRef.current.scrollTop = panelRef.current.scrollHeight;
+    }
+  }, [isOpen, steps]);
+
+  return (
+    <div className={`w-full bg-[#050810] border-t border-brand-border transition-all duration-300 flex flex-col ${isOpen ? 'h-52' : 'h-10'}`}>
+      {/* Header Toggle */}
+      <button 
+        onClick={onToggle}
+        className="h-10 px-6 flex items-center justify-between hover:bg-brand-border/30 transition-colors shrink-0 group"
+      >
+        <div className="flex items-center gap-3">
+          <Terminal size={14} className="text-brand-muted group-hover:text-brand-accent transition-colors" />
+          <span className="text-[11px] font-mono font-bold text-brand-muted group-hover:text-brand-text uppercase tracking-widest">
+            Agent Execution Trace
+          </span>
+          {path && isOpen && (
+             <div className="hidden md:flex items-center gap-2 ml-4 px-3 py-0.5 bg-brand-accent/10 rounded-full border border-brand-accent/20">
+                <span className="text-[9px] font-mono text-brand-accent/80 font-bold uppercase">Flow Path:</span>
+                <span className="text-[9px] font-mono text-brand-muted tracking-tighter overflow-hidden whitespace-nowrap max-w-[400px]">
+                  {path}
+                </span>
+             </div>
+          )}
+        </div>
+        <div className="flex items-center gap-4">
+           {steps.length > 0 && !isOpen && (
+            <span className="text-[10px] font-mono text-brand-success/60 font-bold uppercase animate-pulse">
+              {steps.length} Steps Logged
+            </span>
+          )}
+          {isOpen ? <ChevronDown size={14} className="text-brand-muted" /> : <ChevronUp size={14} className="text-brand-muted" />}
+        </div>
+      </button>
+
+      {/* Content Area */}
+      <div 
+        ref={panelRef}
+        className={`flex-1 overflow-y-auto px-6 py-4 space-y-4 font-mono text-xs ${isOpen ? 'opacity-100' : 'opacity-0 pointer-events-none'}`}
+      >
+        {steps.length === 0 ? (
+          <div className="h-full flex items-center justify-center text-brand-muted/20 flex-col gap-2">
+            <Terminal size={24} strokeWidth={1} />
+            <span className="text-[10px] uppercase tracking-[0.2em]">Awaiting execution data...</span>
+          </div>
+        ) : (
+          steps.map((step, idx) => {
+            const statusConfig = {
+              pass: { icon: <CheckCircle2 size={12} className="text-brand-success" />, color: 'text-brand-success' },
+              fail: { icon: <XCircle size={12} className="text-brand-danger" />, color: 'text-brand-danger' },
+              skip: { icon: <FastForward size={12} className="text-brand-muted" />, color: 'text-brand-muted' },
+              pending: { icon: <Loader2 size={12} className="text-brand-muted animate-spin" />, color: 'text-brand-muted' }
+            };
+
+            const checkpointConfig = {
+              1: { label: 'C1', color: 'bg-brand-accent/20 text-brand-accent border-brand-accent/40' },
+              2: { label: 'C2', color: 'bg-brand-warning/20 text-brand-warning border-brand-warning/40' },
+              3: { label: 'C3', color: 'bg-brand-checkpoint/20 text-brand-checkpoint border-brand-checkpoint/40' }
+            };
+
+            const cp = checkpointConfig[step.checkpoint as 1|2|3];
+            const sc = statusConfig[step.status];
+
+            return (
+              <div key={idx} className="space-y-1.5 animate-fade-slide-up" style={{ animationDelay: `${idx * 50}ms` }}>
+                <div className="flex items-center gap-3">
+                  <span className="text-brand-muted/40 tabular-nums">[{new Date(step.timestamp).toLocaleTimeString([], { hour12: false })}]</span>
+                  <span className={`text-[9px] px-1.5 py-0.5 rounded border font-black ${cp.color}`}>{cp.label}</span>
+                  <div className="shrink-0">{sc.icon}</div>
+                  <span className="text-brand-text font-bold uppercase tracking-tight">{step.label}:</span>
+                  <span className="text-brand-muted truncate">{step.detail}</span>
+                </div>
+                
+                {step.reasoning && (
+                  <div className="pl-24 flex gap-2">
+                    <ArrowRight size={10} className="mt-1 text-brand-gold/40 shrink-0" />
+                    <p className="text-brand-goldLight/70 italic leading-relaxed text-[11px] font-body">
+                      {step.reasoning}
+                    </p>
+                  </div>
+                )}
+
+                {(step.web_search_triggered || step.retries_used! > 0) && (
+                  <div className="pl-24 flex gap-2 pt-1">
+                    {step.web_search_triggered && (
+                      <span className="flex items-center gap-1.5 bg-brand-warning/10 text-brand-warning px-2 py-0.5 rounded border border-brand-warning/20 text-[9px] font-black uppercase">
+                        <Globe size={10} />
+                        Web Search Fallback
+                      </span>
+                    )}
+                    {step.retries_used! > 0 && (
+                      <span className="flex items-center gap-1.5 bg-brand-danger/10 text-brand-danger px-2 py-0.5 rounded border border-brand-danger/20 text-[9px] font-black uppercase">
+                        <RefreshCcw size={10} />
+                        Retry Count: {step.retries_used}
+                      </span>
+                    )}
+                  </div>
+                )}
+              </div>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default TracePanel;

university-advisor-ui/src/index.css

@@ -0,0 +1,51 @@
+@import url('https://fonts.googleapis.com/css2?family=Syne:wght@400..800&family=Bricolage+Grotesque:opsz,wght@12..96,200..800&family=Azeret+Mono:ital,wght@0,100..900;1,100..900&display=swap');
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  body {
+    @apply bg-[#070B14] text-slate-200 font-body overflow-hidden selection:bg-blue-500/30;
+  }
+  
+  h1, h2, h3, h4, h5, h6 {
+    @apply font-display tracking-tight;
+  }
+}
+
+@keyframes fadeSlideUp {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes typingBounce {
+  0%, 80%, 100% { transform: translateY(0); }
+  40%           { transform: translateY(-4px); }
+}
+
+.animate-fade-slide-up {
+  animation: fadeSlideUp 0.2s ease-out forwards;
+}
+
+.animate-typing-bounce {
+  animation: typingBounce 1s infinite;
+}
+
+/* Transitions */
+* {
+  @apply transition-colors duration-150 ease-out;
+}
+
+/* Custom Scrollbar */
+::-webkit-scrollbar {
+  width: 4px;
+}
+
+::-webkit-scrollbar-track {
+  @apply bg-transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  @apply bg-slate-800 rounded-full hover:bg-slate-700;
+}

university-advisor-ui/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

university-advisor-ui/src/services/api.ts

@@ -0,0 +1,63 @@
+import { WindowMemoryItem } from "../types"
+
+const API_BASE = "http://localhost:8000"
+const MOCK_MODE = false // Set to false when backend is running
+
+export interface ChatRequest {
+  query: string
+  window_memory: WindowMemoryItem[]
+}
+
+export interface CheckpointData {
+  checkpoint: number
+  label: string
+  status: "pass" | "fail" | "skip"
+  detail: string
+  reasoning?: string
+  docs_graded?: number
+  docs_relevant?: number
+  web_search_triggered?: boolean
+  retries_used?: number
+}
+
+export interface ChatResponse {
+  answer: string
+  path: string
+  trace: CheckpointData[]
+  used_web_search: boolean
+  retry_count: number
+}
+
+export const sendMessage = async (request: ChatRequest): Promise<ChatResponse> => {
+  if (MOCK_MODE) {
+    await new Promise(resolve => setTimeout(resolve, 1500))
+    return {
+      answer: "Based on the university catalog, CS-301 Advanced Algorithms requires CS-201 Data Structures as a prerequisite. The course is offered every Fall semester and carries 3 credit hours. The instructor is Dr. Ahmad Khan from the CS department.",
+      path: "decide_retrieval → retrieve → grade_documents → prepare_context → generate → check_hallucination → END",
+      trace: [
+        { checkpoint: 1, label: "RETRIEVAL DECISION", status: "pass", 
+          detail: "Needs Retrieval: True", 
+          reasoning: "Query asks about specific course prerequisites requiring KB search." },
+        { checkpoint: 2, label: "RELEVANCE GRADING", status: "pass", 
+          detail: "3/4 documents relevant", docs_graded: 4, docs_relevant: 3,
+          web_search_triggered: false },
+        { checkpoint: 3, label: "HALLUCINATION CHECK", status: "pass", 
+          detail: "No hallucinations detected", retries_used: 0 }
+      ],
+      used_web_search: false,
+      retry_count: 0
+    }
+  }
+
+  const response = await fetch(`${API_BASE}/chat`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request)
+  })
+  
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`)
+  }
+  
+  return response.json()
+}

university-advisor-ui/src/types.ts

@@ -0,0 +1,32 @@
+export type MessageRole = "user" | "assistant" | "system"
+
+export type CheckpointStatus = "pass" | "fail" | "skip" | "pending"
+
+export interface TraceStep {
+  id: string
+  checkpoint: number         // 1, 2, or 3
+  label: string              // e.g. "RETRIEVAL DECISION"
+  status: CheckpointStatus
+  detail: string             // e.g. "Needs Retrieval: True"
+  reasoning?: string         // The reasoning text from the agent
+  docs_graded?: number       // How many docs were graded (checkpoint 2)
+  docs_relevant?: number     // How many were relevant (checkpoint 2)
+  web_search_triggered?: boolean
+  retries_used?: number
+  timestamp: Date
+}
+
+export interface Message {
+  id: string
+  role: MessageRole
+  content: string
+  timestamp: Date
+  trace?: TraceStep[]        // Only bot messages have traces
+  isLoading?: boolean        // True while streaming
+  path?: string              // e.g. "retrieve → grade → generate"
+}
+
+export interface WindowMemoryItem {
+  role: MessageRole
+  content: string
+}

university-advisor-ui/tailwind.config.ts

@@ -0,0 +1,39 @@
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          bg:        "#0A0E1A",   // Deep navy — main background
+          surface:   "#111827",   // Slightly lighter — card/panel background
+          border:    "#1E2D45",   // Subtle border color
+          accent:    "#2563EB",   // Electric blue — primary action color
+          accentHov: "#1D4ED8",   // Darker blue on hover
+          gold:      "#F59E0B",   // Amber gold — university branding accent
+          goldLight: "#FDE68A",   // Light gold — for subtle highlights
+          text:      "#F1F5F9",   // Near white — primary text
+          muted:     "#94A3B8",   // Slate gray — secondary text, timestamps
+          user:      "#1E3A5F",   // Dark blue — user message bubble background
+          bot:       "#0F1F35",   // Darker navy — advisor message bubble background
+          success:   "#10B981",   // Emerald — checkpoint pass indicators
+          warning:   "#F59E0B",   // Amber — hallucination detected indicators
+          danger:    "#EF4444",   // Red — error states
+          checkpoint:"#7C3AED",   // Purple — checkpoint badge backgrounds
+        }
+      },
+      fontFamily: {
+        display: ["Syne", "sans-serif"],
+        body: ["Bricolage Grotesque", "sans-serif"],
+        mono: ["Azeret Mono", "monospace"],
+      },
+    },
+  },
+  plugins: [],
+}
+
+export default config

university-advisor-ui/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

university-advisor-ui/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

university-advisor-ui/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})