Ship chat UI, update project links, and add MIT license

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Islam Mamedov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -15,7 +15,7 @@ codebase and get answers grounded in its actual source code, documentation,
 and GitHub issues — with citations linking to the exact lines, and honest
 refusals when the corpus doesn't contain the answer.
 
-**Live demo:** https://huggingface.co/spaces/Pace200413/fastapi-codebase-qa
+**Live demo:** https://huggingface.co/spaces/islam-mamedov/fastapi-codebase-qa
 
 Every architectural decision in this project was made by measuring, not
 guessing: a hand-labeled 42-question eval set gates every change, and the
@@ -129,7 +129,7 @@ to FastAPI" from "answerable from FastAPI's corpus".
 ## Run it yourself
 
 ```bash
-git clone https://github.com/Pace200413/codebase-rag && cd codebase-rag
+git clone https://github.com/islam-mamedov/codebase-rag && cd codebase-rag
 python -m venv .venv && source .venv/bin/activate
 pip install -r requirements.txt PyGithub tree-sitter tree-sitter-python pytest
 echo "GROQ_API_KEY=gsk_..." > .env          # free key: console.groq.com

app.py

@@ -10,6 +10,7 @@ first boot (~3 min, cached afterwards).
 
 import os
 import sys
+import time
 from pathlib import Path
 
 from dotenv import load_dotenv
@@ -32,7 +33,24 @@ EXAMPLES = [
 ]
 
 st.set_page_config(page_title="FastAPI Codebase Q&A", page_icon="⚡",
-                   layout="wide")
+                   layout="centered")
+
+st.markdown("""
+<style>
+    .stButton > button {
+        border-radius: 12px;
+        border: 1px solid rgba(128, 128, 128, 0.35);
+        font-size: 0.85rem;
+        transition: border-color 0.2s;
+    }
+    .stButton > button:hover { border-color: #f0b429; color: #f0b429; }
+    [data-testid="stMetricValue"] { font-size: 1.4rem; }
+    [data-testid="stExpander"] {
+        border-radius: 10px;
+        border: 1px solid rgba(128, 128, 128, 0.25);
+    }
+</style>
+""", unsafe_allow_html=True)
 
 
 @st.cache_resource(show_spinner="First boot: building the search index "
@@ -53,13 +71,9 @@ def ensure_index() -> bool:
 
 ensure_index()
 
-st.title("⚡ FastAPI Codebase Q&A")
-st.caption("Retrieval-augmented answers over FastAPI's source code, docs, "
-           "and GitHub issues — every claim cited, honest refusals when "
-           "the corpus doesn't know.")
-
+# ---------------- sidebar ----------------
 with st.sidebar:
-    st.header("How it works")
+    st.header("⚙️ How it works")
     st.markdown(
         "1. Your question is embedded (`bge-small-en-v1.5`)\n"
         "2. Top-5 chunks retrieved from ~1,350 AST-aware chunks "
@@ -68,16 +82,30 @@ with st.sidebar:
         "4. Citations link to the exact GitHub lines"
     )
     mode = st.selectbox("Retrieval mode", ["dense", "dense_rw", "hybrid"],
-                        help="dense won the ablation; others shown for "
-                             "comparison")
+                        help="dense won a 7-configuration ablation; "
+                             "others shown for comparison")
     st.divider()
-    st.markdown(
-        "**Eval results (42-question set)**\n\n"
-        "recall@5 **0.91** · MRR **0.71**\n\n"
-        "faithful **0.89** · correct **0.91** · refusal **7/7**"
-    )
-    st.markdown("[Source & write-up]"
+    st.subheader("📊 Eval (42-question benchmark)")
+    c1, c2 = st.columns(2)
+    c1.metric("recall@5", "0.91")
+    c2.metric("MRR", "0.71")
+    c3, c4 = st.columns(2)
+    c3.metric("correct", "0.91")
+    c4.metric("refusal", "7/7")
+    st.divider()
+    st.markdown("[💻 Source & write-up]"
                 "(https://github.com/Pace200413/codebase-rag)")
+    if st.button("🗑 Clear conversation", use_container_width=True):
+        st.session_state.messages = []
+        st.rerun()
+
+# ---------------- header ----------------
+st.title("⚡ FastAPI Codebase Q&A")
+st.caption("Ask anything about FastAPI's source code, docs, and GitHub "
+           "issues. Every claim is cited. When the corpus doesn't know, "
+           "it says so.")
+
+# ---------------- helpers ----------------
 
 
 @st.cache_data(show_spinner=False)
@@ -85,49 +113,89 @@ def cached_retrieve(question: str, mode: str) -> list[dict]:
     return retrieve(question, k=5, mode=mode)
 
 
-def generate(question: str, hits: list[dict]) -> str:
+def stream_answer(question: str, hits: list[dict]):
+    """Yield the answer token by token (looks alive, no behavior change)."""
     from groq import Groq
     api_key = os.environ.get("GROQ_API_KEY")
     if not api_key:
         st.error("GROQ_API_KEY is not set.")
         st.stop()
     client = Groq(api_key=api_key)
-    response = client.chat.completions.create(
+    stream = client.chat.completions.create(
         model=LLM_MODEL,
         messages=[
             {"role": "system", "content": SYSTEM_PROMPT},
             {"role": "user", "content": build_prompt(question, hits)},
         ],
         temperature=0.1,
+        stream=True,
     )
-    return response.choices[0].message.content
-
-
-# --- example question buttons ---
-st.write("Try one:")
-cols = st.columns(len(EXAMPLES))
-for col, ex in zip(cols, EXAMPLES):
-    if col.button(ex, use_container_width=True):
-        st.session_state["question"] = ex
+    for chunk in stream:
+        delta = chunk.choices[0].delta.content
+        if delta:
+            yield delta
 
-question = st.text_input("Ask about FastAPI's codebase",
-                         key="question",
-                         placeholder="How do I handle file uploads?")
 
-if question:
-    with st.spinner("Searching the codebase..."):
-        hits = cached_retrieve(question, mode)
-    with st.spinner("Writing the answer..."):
-        answer = generate(question, hits)
-
-    st.markdown(answer)
-
-    st.divider()
-    st.subheader("Sources")
+def render_sources(hits: list[dict]) -> None:
+    st.markdown("##### 📎 Sources")
     for i, h in enumerate(hits, 1):
         meta = h["meta"]
-        label = (f"[{i}] {meta['source_type']} · {meta['path']}"
+        icon = {"code": "🧩", "doc": "📄", "issue": "🐛"}.get(
+            meta["source_type"], "📄")
+        label = (f"{icon} [{i}] {meta['path']}"
                  + (f" · {meta['symbol']}" if meta["symbol"] else ""))
         with st.expander(label):
-            st.markdown(f"[Open on GitHub]({meta['url']})")
-            st.code(h["text"][:1500])
+            st.markdown(f"[Open on GitHub ↗]({meta['url']})")
+            st.code(h["text"][:1200])
+
+
+# ---------------- conversation state ----------------
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+# render history
+for msg in st.session_state.messages:
+    with st.chat_message(msg["role"]):
+        st.markdown(msg["content"])
+        if msg.get("sources"):
+            render_sources(msg["sources"])
+        if msg.get("timing"):
+            st.caption(msg["timing"])
+
+# example buttons (only before the first question, to keep the video clean)
+pending = None
+if not st.session_state.messages:
+    st.write("**Try one:**")
+    cols = st.columns(2)
+    for i, ex in enumerate(EXAMPLES):
+        if cols[i % 2].button(ex, use_container_width=True):
+            pending = ex
+
+prompt = st.chat_input("Ask about FastAPI's codebase...") or pending
+
+if prompt:
+    st.session_state.messages.append({"role": "user", "content": prompt})
+    with st.chat_message("user"):
+        st.markdown(prompt)
+
+    with st.chat_message("assistant"):
+        t0 = time.perf_counter()
+        with st.spinner("Searching 1,352 chunks..."):
+            hits = cached_retrieve(prompt, mode)
+        t_retrieve = time.perf_counter() - t0
+
+        t1 = time.perf_counter()
+        answer = st.write_stream(stream_answer(prompt, hits))
+        t_answer = time.perf_counter() - t1
+
+        timing = (f"retrieved in {t_retrieve:.2f}s · "
+                  f"answered in {t_answer:.1f}s · mode: {mode}")
+        st.caption(timing)
+        render_sources(hits)
+
+    st.session_state.messages.append({
+        "role": "assistant",
+        "content": answer,
+        "sources": hits,
+        "timing": timing,
+    })