Upload folder using huggingface_hub

1_cache/hollow_knight_bosses.pkl

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

2_cache/silksong_areas.pkl

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

2_cache/silksong_bosses.pkl

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

2_cache/silksong_game.pkl

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

2_cache/silksong_hornet.pkl

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

2_cache/silksong_items.pkl

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

2_cache/silksong_npcs.pkl

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

2_cache/silksong_tasks.pkl

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

2_cache/silksong_tools_and_skills.pkl

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

app.py

@@ -1,439 +1,22 @@
-import gradio as gr
-import requests
-import os
-import pickle
-import spaces
-import torch
-from bs4 import BeautifulSoup
-from html_to_markdown import convert_to_markdown
 from huggingface_hub import login
-from sentence_transformers import SentenceTransformer, util
-from transformers import pipeline, TextIteratorStreamer
-from threading import Thread
-from tqdm import tqdm
-
-# --- 1. CONFIGURATION ---
-# Centralized place for all settings and constants.
-
-# Hugging Face & Model Configuration
-HF_TOKEN = os.getenv('HF_TOKEN')
-EMBEDDING_MODEL_ID = "google/embeddinggemma-300M"
-LLM_MODEL_ID = "google/gemma-3-12B-it"
-
-# Data Source Configuration
-BASE_URL = "https://hollowknight.wiki"
-
-GAME_KNOWLEDGE_DATA = [
-    {
-        "title": "Hollow Knight",
-        "category_list": [
-            {
-                "entry": "/w/Category:Bosses_(Hollow_Knight)",
-                "cache": "hollow_knight_bosses.pkl",
-                "label": "Bosses",
-            },
-        ],
-    },
-    {
-        "title": "Silksong",
-        "category_list": [
-            {
-                "entry": "/w/Hornet_(Silksong)",
-                "cache": "silksong_hornet.pkl",
-                "label": "General",
-            },
-            {
-                "entry": "/w/Hollow_Knight:_Silksong",
-                "cache": "silksong_game.pkl",
-                "label": "General",
-            },
-            {
-                "entry": "/w/Category:Areas_(Silksong)",
-                "cache": "silksong_areas.pkl",
-                "label": "Areas",
-            },
-            {
-                "entry": "/w/Category:Bosses_(Silksong)",
-                "cache": "silksong_bosses.pkl",
-                "label": "Bosses",
-            },
-            {
-                "entry": "/w/Category:Items_(Silksong)",
-                "cache": "silksong_items.pkl",
-                "label": "Items",
-            },
-            {
-                "entry": "/w/Category:NPCs_(Silksong)",
-                "cache": "silksong_npcs.pkl",
-                "label": "NPCs",
-            },
-            {
-                "entry": "/w/Tasks",
-                "cache": "silksong_tasks.pkl",
-                "label": "Tasks",
-            },
-            {
-                "entry": "/w/Category:Tools_and_Skills_(Silksong)",
-                "cache": "silksong_tools_and_skills.pkl",
-                "label": "Tools and Skills",
-            },
-        ],
-    },
-]
-
-# Gradio App Configuration
-BASE_SIMILARITY_THRESHOLD = 0.2
-FOLLOWUP_SIMILARITY_THRESHOLD = 0.5
-DEFAULT_MESSAGE_NO_MATCH = "I'm sorry, I can't find a relevant document to answer that question."
-
-
-# --- 2. HELPER FUNCTIONS ---
-# Reusable functions for web scraping and data processing.
-
-def _get_html(url: str) -> str:
-    """Fetches HTML content from a URL."""
-    try:
-        response = requests.get(url)
-        response.raise_for_status()  # Raises an HTTPError for bad responses (4xx or 5xx)
-        return response.text
-    except requests.exceptions.RequestException as e:
-        print(f"Error fetching {url}: {e}")
-        return ""
-
-def _find_wiki_links(html_content: str) -> list[str]:
-    """Parses HTML to find all boss links within the 'mw-pages' div."""
-    soup = BeautifulSoup(html_content, 'html.parser')
-    mw_pages_div = soup.find('div', id='mw-pages')
-    if not mw_pages_div:
-        return []
-    return [a['href'] for a in mw_pages_div.find_all('a', href=True)]
-
-def _get_markdown_from_html(html: str) -> str:
-    if not html:
-        return ""
-
-    soup = BeautifulSoup(html, 'html.parser')
-    return convert_to_markdown(soup)
-
-def _get_markdown_from_url(url: str) -> str:
-    return _get_markdown_from_html(_get_html(url))
-
-
-# --- 3. DATA PROCESSING & CACHING ---
-# Scrapes data and generates embeddings, using a cache to avoid re-running.
-
-def _clean_text(text: str) -> str:
-    """Removes the references section from the raw text."""
-    return text.split("References\n----------\n", 1)[0].strip()
-
-@torch.no_grad()
-def _create_data_entry(text: str, doc_path: str, label: str, embedding_model) -> dict | None:
-    """Creates a single structured data entry with text, metadata, and embedding."""
-    cleaned_text = _clean_text(text)
-    if not cleaned_text:
-        return None
-
-    title = doc_path.split('/')[-1]
-    # Encode returns a numpy array; convert to tensor for stacking later.
-    embedding = embedding_model.encode(cleaned_text, prompt=f"title: {title} | text: ")
-    return {
-        "text": cleaned_text,
-        "embedding": torch.tensor(embedding), ### Store as tensor for faster processing
-        "metadata": {
-            "category": label,
-            "source": BASE_URL + doc_path,
-            "title": title
-        }
-    }
-
-def load_or_process_source(entry_point: str, cache_file: str, label: str, embedding_model):
-    """
-    Loads processed data from a cache file if it exists. Otherwise, scrapes,
-    processes, generates embeddings, and saves to the cache.
-    """
-    if os.path.exists(cache_file):
-        print(f"✅ Found cache for {label}. Loading data from '{cache_file}'...")
-        with open(cache_file, 'rb') as f:
-            return pickle.load(f)
-
-    print(f"ℹ️ No cache for {label}. Starting data scraping and processing...")
-    processed_data = []
-
-    main_page_html = _get_html(BASE_URL + entry_point)
-    data_entry = _create_data_entry(_get_markdown_from_html(main_page_html), entry_point, label, embedding_model)
-    if (data_entry):
-        processed_data.append(data_entry)
-
-    extracted_links = _find_wiki_links(main_page_html)
-
-    for doc_path in tqdm(extracted_links, desc=f"Processing {label} Pages"):
-        full_url = BASE_URL + doc_path
-        text = _get_markdown_from_url(full_url)
-
-        data_entry = _create_data_entry(text, doc_path, label, embedding_model)
-        if data_entry:
-            processed_data.append(data_entry)
-
-    print(f"✅ {label} processing complete. Saving {len(processed_data)} entries to '{cache_file}'...")
-    with open(cache_file, 'wb') as f:
-        pickle.dump(processed_data, f)
-
-    return processed_data
-
-
-# --- 4. CORE AI LOGIC ---
-# Functions for finding context and generating a response.
-
-@torch.no_grad()
-def find_best_context(model: SentenceTransformer, query: str, contents: list[dict], similarity_threshold: float) -> int:
-    """Finds the most relevant document index based on semantic similarity."""
-    if not query or not contents:
-        return -1
-        
-    query_embedding = model.encode(query, prompt_name="query", convert_to_tensor=True).to(model.device)
-
-    try:
-        # Stack pre-computed tensors from our knowledge base
-        contents_embeddings = torch.stack([item["embedding"] for item in contents]).to(model.device)
-    except (RuntimeError, IndexError, TypeError) as e:
-        print(f"Warning: Could not stack content embeddings. Error: {e}")
-        return -1
-
-    # Compute cosine similarity between the 1 query embedding and N content embeddings
-    similarities = util.pytorch_cos_sim(query_embedding, contents_embeddings)
+from config import HF_TOKEN, GAME_KNOWLEDGE_DATA, EMBEDDING_MODEL_ID, LLM_MODEL_ID
+from rag_service import RAGService
+from ui import build_gradio_ui
+
+def main():
+    """Main function to initialize and launch the chatbot application."""
+    print("Logging into Hugging Face Hub...")
+    login(token=HF_TOKEN)
     
-    if similarities.numel() == 0:
-        print("Warning: Similarity computation returned an empty tensor.")
-        return -1
-        
-    # Get the index and score of the top match
-    best_index = similarities.argmax().item()
-    best_score = similarities[0, best_index].item()
-
-    print(f"Best score: {best_score:.4f} (Threshold: {similarity_threshold})")
-    if best_score >= similarity_threshold:
-        print(f"Using \"{contents[best_index]['metadata']['source']}\"...")
-        return best_index
-
-    print("No context met the similarity threshold.")
-    return -1
-
-
-class ChatContext(object):
-    context_index = -1
-    base_similarity = BASE_SIMILARITY_THRESHOLD
-    followup_similarity = FOLLOWUP_SIMILARITY_THRESHOLD
-
-default_context = ChatContext()
-
-@spaces.GPU
-def respond(message: str, history: list, game: str, chat_context: ChatContext):
-    """Generates a streaming response from the LLM based on the best context found."""
-    default_threshold = chat_context.base_similarity
-    followup_threshold = chat_context.followup_similarity
-
-    contents = _select_content(game)
-    if not contents:
-        print(f"No content found for {game}")
-        chat_context.context_index = -1 # Return -1 to reset context
-        yield DEFAULT_MESSAGE_NO_MATCH, chat_context
-        return
-        
-    if len(history) == 0:
-        # Clear context on a new conversation
-        print("New conversation started. Clearing context.")
-        chat_context.context_index = -1
-
-    # Determine threshold: Use follow-up ONLY if we have a valid previous context.
-    similarity_threshold = followup_threshold if chat_context.context_index != -1 else default_threshold
-    print(f"Using {'follow-up' if chat_context.context_index != -1 else 'default'} threshold: {similarity_threshold}")
-
-    # Find the best new context based on the current message
-    found_context_index = find_best_context(embedding_model, message, contents, similarity_threshold)
-
-    if found_context_index >= 0:
-        chat_context.context_index = found_context_index  # A new, relevant context was found and set
-    elif chat_context.context_index >= 0:
-        # PASS: A follow-up question, but no new context. Reuse the old one.
-        print("No new context found, reusing previous context for follow-up.")
-    else:
-        # FAILURE: No new context was found AND no previous context exists.
-        print("No context found and no previous context. Yielding no match.")
-        yield DEFAULT_MESSAGE_NO_MATCH, chat_context
-        return
-
-    system_prompt = f"Answer the following QUESTION based only on the CONTEXT provided. If the answer cannot be found in the CONTEXT, write \"{DEFAULT_MESSAGE_NO_MATCH}\"\n---\nCONTEXT:\n{contents[chat_context.context_index]['text']}\n"
-    user_prompt = f"QUESTION:\n{message}"
-
-    messages = [{"role": "system", "content": system_prompt}]
-    # Add previous turns (history) after the system prompt but before the current question
-    messages.extend(history)
-    messages.append({"role": "user", "content": user_prompt})
-
-    # Debug print the conversation being sent (excluding the large system prompt)
-    for item in messages[1:]:
-        print(f"[{item['role']}] {item['content']}")
-
-    streamer = TextIteratorStreamer(llm_pipeline.tokenizer, skip_prompt=True, skip_special_tokens=True)
-
-    thread = Thread(
-        target=llm_pipeline,
-        kwargs=dict(
-            text_inputs=messages,
-            streamer=streamer,
-            max_new_tokens=512,
-            do_sample=True,
-            top_p=0.95,
-            temperature=0.7,
-        )
-    )
-    thread.start()
-
-    response = ""
-    for new_text in streamer:
-        response += new_text
-        # Yield the partial response AND the current state
-        yield response, chat_context
-
-
-# --- 5. INITIALIZATION ---
-# Login, load models, and process data.
-
-print("Logging into Hugging Face Hub...")
-login(token=HF_TOKEN)
-
-print("Initializing embedding model...")
-embedding_model = SentenceTransformer(EMBEDDING_MODEL_ID)
-
-print("Initializing language model...")
-llm_pipeline = pipeline(
-    "text-generation",
-    model=LLM_MODEL_ID,
-    device_map="auto",
-    dtype="auto",
-)
-
-print("\n--- Processing Game Data ---")
-knowledge_base = {}
-
-for item in GAME_KNOWLEDGE_DATA:
-    knowledge_base[item['title']] = []
-    for category in item['category_list']:
-        knowledge_base[item['title']] += load_or_process_source(category['entry'], category['cache'], category['label'], embedding_model)
-
-def _select_content(game: str):
-    return knowledge_base[game]
-
-
-# --- 6. GRADIO UI ---
-# Defines the web interface for the chatbot.
-gr.set_static_paths(paths=["assets/"])
-
-# Theme and CSS for the Silksong aesthetic
-silksong_theme = gr.themes.Default(
-    primary_hue=gr.themes.colors.red,
-    secondary_hue=gr.themes.colors.zinc,
-    neutral_hue=gr.themes.colors.zinc,
-    font=[gr.themes.GoogleFont("IM Fell English"), "ui-sans-serif", "system-ui", "sans-serif"],
-)
-
-silksong_css="""
-.gradio-container {
-    background-image: linear-gradient(rgba(255,255,255, 0.5), rgba(255, 255, 255, 1.0)), url("/gradio_api/file=assets/background.jpg");
-    background-size: 100%;
-    background-repeat: no-repeat;
-    background-position: top center;
-}
-body.dark .gradio-container {
-    background-image: linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 1.0)), url("/gradio_api/file=assets/background.jpg");
-}
-.header-text { text-align: center; text-shadow: 2px 2px 5px #000; }
-.header-text h1 { font-size: 2.5em; color: #dc2626; }
-.dark .header-text { text-shadow: 2px 2px 5px #FFF; }
-.context { text-align: center; color: var(--body-text-color-subdued); }
-.context a { color: #dc2626; }
-.disclaimer { text-align: center; color: var(--body-text-color-subdued); font-size: 0.9em; padding: 20px; }
-.disclaimer ul { list-style: none; padding: 0; }
-.disclaimer a { color: #dc2626; }
-"""
-
-
-def _index_changed(context_state: ChatContext, game_title: str):
-    """Updates the HTML context display when the context_index state changes."""
-    context_index = context_state.context_index
-    if context_index < 0:
-        return """<div class="context">Context: None</div>"""
-
-    contents = _select_content(game_title)
-    if not contents or context_index >= len(contents):
-        return """<div class="context">Context: Error</div>"""
-        
-    url = contents[context_index]['metadata']['source']
-    title = contents[context_index]['metadata']['title']
-    return f"""<div class="context">Context: <a href="{url}" target="_blank">{title}</a></div>"""
-
-def _title_changed(context_state: ChatContext):
-    """Resets the context display and the context state when the game is changed."""
-    context_state.context_index = -1
-    return """<div class="context">Context: None</div>""", context_state
-
-def _sim_changed(context_state: ChatContext, base_sim: float, followup_sim: float):
-    context_state.base_similarity = base_sim
-    context_state.followup_similarity = followup_sim
-    return context_state
-
-with gr.Blocks(theme=silksong_theme, css=silksong_css) as demo:
-    gr.HTML("""
-        <div class="header-text">
-            <h1>A Weaver's Counsel</h1>
-            <p>Speak, little traveler. What secrets of Pharloom do you seek?</p>
-            <p style="font-style: italic;">(Note: This bot has a limited knowledge.)</p>
-        </div>
-    """)
-
-    game_title = gr.Dropdown(["Hollow Knight", "Silksong"], label="Game", value="Silksong")
-
-    output = gr.HTML("""<div class="context">Context: None</div>""")
-
-    # Link the state object to the UI elements
-    context_state = gr.State(default_context)
-    context_state.change(_index_changed, [context_state, game_title], output)
-    game_title.change(_title_changed, context_state, [output, context_state])
-
-    gr.ChatInterface(
-        respond,
-        type="messages",
-        chatbot=gr.Chatbot(type="messages", label=LLM_MODEL_ID),
-        textbox=gr.Textbox(placeholder="Ask about the haunted kingdom...", container=False, submit_btn=True, scale=7),
-        additional_inputs=[
-            game_title,
-            context_state, ### Pass the state object as an input
-        ],
-        additional_outputs=[context_state], ### Receive the updated state as an output
-        examples=[
-            ["Where can I find the Moorwing?", "Silksong"],
-            ["Who is the voice of Lace?", "Silksong"],
-            ["How can I beat the False Knight?", "Hollow Knight"],
-            ["Any achievement for Hornet Protector?", "Hollow Knight"],
-        ],
-        cache_examples=False,
-    )
-
-    base_sim = gr.Slider(minimum=0.1, maximum=1.0, value=BASE_SIMILARITY_THRESHOLD, step=0.1, label="Base Similarity Threshold")
-    followup_sim = gr.Slider(minimum=0.1, maximum=1.0, value=FOLLOWUP_SIMILARITY_THRESHOLD, step=0.1, label="Similarity Threshold with follow-up questions (multi-turn)")
-    base_sim.release(_sim_changed, [context_state, base_sim, followup_sim], context_state)
-    followup_sim.release(_sim_changed, [context_state, base_sim, followup_sim], context_state)
-
-    gr.HTML("""
-        <div class="disclaimer">
-            <p><strong>Disclaimer:</strong></p>
-            <ul style="list-style: none; padding: 0;">
-                <li>This is a fan-made personal demonstration and not affiliated with any organization.<br>The bot is for entertainment purposes only.</li>
-                <li>Factual information is sourced from the <a href="https://hollowknight.wiki" target="_blank">Hollow Knight Wiki</a>.<br>Content is available under <a href="https://creativecommons.org/licenses/by-sa/3.0/" target="_blank">Commons Attribution-ShareAlike</a> unless otherwise noted.</li>
-                <li>Built by <a href="https://huggingface.co/bebechien" target="_blank">bebechien</a> with a 💖 for the world of Hollow Knight.</li>
-            </ul>
-        </div>
-    """)
+    # 1. Create the single service instance. This loads all models and data.
+    rag_service = RAGService(GAME_KNOWLEDGE_DATA, EMBEDDING_MODEL_ID, LLM_MODEL_ID)
+    
+    # 2. Build the UI, passing the service instance to it.
+    demo = build_gradio_ui(rag_service)
+    
+    # 3. Launch the application.
+    print("Launching Gradio demo...")
+    demo.launch()
 
 if __name__ == "__main__":
-    demo.launch()
+    main()

chat_context.py

@@ -0,0 +1,8 @@
+from config import BASE_SIMILARITY_THRESHOLD, FOLLOWUP_SIMILARITY_THRESHOLD
+
+class ChatContext:
+    """Holds the conversational state, including the current context and thresholds."""
+    def __init__(self):
+        self.context_index = -1
+        self.base_similarity = BASE_SIMILARITY_THRESHOLD
+        self.followup_similarity = FOLLOWUP_SIMILARITY_THRESHOLD

config.py

@@ -0,0 +1,187 @@
+import os
+import gradio as gr
+import pickle
+import torch
+from tqdm import tqdm
+
+from web_helper import get_html, find_wiki_links, get_markdown_from_html, get_markdown_from_url
+
+# --- Hugging Face & Model Configuration ---
+HF_TOKEN = os.getenv('HF_TOKEN')
+EMBEDDING_MODEL_ID = "google/embeddinggemma-300M"
+LLM_MODEL_ID = "google/gemma-3-12B-it"
+
+# --- Data Source Configuration ---
+BASE_URL = "https://hollowknight.wiki"
+GAME_KNOWLEDGE_DATA = [
+    {
+        "title": "Hollow Knight",
+        "cache_folder": "1_cache",
+        "category_list": [
+            {
+                "entry": "/w/Category:Bosses_(Hollow_Knight)",
+                "cache": "hollow_knight_bosses.pkl",
+                "label": "Bosses",
+            },
+        ],
+    },
+    {
+        "title": "Silksong",
+        "cache_folder": "2_cache",
+        "category_list": [
+            {
+                "entry": "/w/Hornet_(Silksong)",
+                "cache": "silksong_hornet.pkl",
+                "label": "General",
+            },
+            {
+                "entry": "/w/Hollow_Knight:_Silksong",
+                "cache": "silksong_game.pkl",
+                "label": "General",
+            },
+            {
+                "entry": "/w/Category:Areas_(Silksong)",
+                "cache": "silksong_areas.pkl",
+                "label": "Areas",
+            },
+            {
+                "entry": "/w/Category:Bosses_(Silksong)",
+                "cache": "silksong_bosses.pkl",
+                "label": "Bosses",
+            },
+            {
+                "entry": "/w/Category:Items_(Silksong)",
+                "cache": "silksong_items.pkl",
+                "label": "Items",
+            },
+            {
+                "entry": "/w/Category:NPCs_(Silksong)",
+                "cache": "silksong_npcs.pkl",
+                "label": "NPCs",
+            },
+            {
+                "entry": "/w/Tasks",
+                "cache": "silksong_tasks.pkl",
+                "label": "Tasks",
+            },
+            {
+                "entry": "/w/Category:Tools_and_Skills_(Silksong)",
+                "cache": "silksong_tools_and_skills.pkl",
+                "label": "Tools and Skills",
+            },
+        ],
+    },
+]
+
+def get_all_game_data(embedding_model):
+    """Loops through the config and processes/loads all knowledge sources."""
+    print("\n--- Processing Game Data ---")
+    knowledge_base = {}
+
+    for item in GAME_KNOWLEDGE_DATA:
+        title = item['title']
+        knowledge_base[title] = []
+        for category in item['category_list']:
+            cache_path = f"""{item["cache_folder"]}/{category["cache"]}"""
+            knowledge_base[title] += _load_or_process_source(
+                category['entry'], 
+                cache_path, 
+                category['label'],
+                embedding_model
+            )
+    
+    return knowledge_base
+
+# --- DATA PROCESSING & CACHING ---
+# Scrapes data and generates embeddings, using a cache to avoid re-running.
+def _clean_text(text: str) -> str:
+    """Removes the references section from the raw text."""
+    return text.split("References\n----------\n", 1)[0].strip()
+
+@torch.no_grad()
+def _create_data_entry(text: str, doc_path: str, label: str, embedding_model) -> dict | None:
+    """Creates a single structured data entry with text, metadata, and embedding."""
+    cleaned_text = _clean_text(text)
+    if not cleaned_text:
+        return None
+
+    title = doc_path.split('/')[-1]
+    # Encode returns a numpy array; convert to tensor for stacking later.
+    embedding = embedding_model.encode(cleaned_text, prompt=f"title: {title} | text: ")
+    return {
+        "text": cleaned_text,
+        "embedding": torch.tensor(embedding), ### Store as tensor for faster processing
+        "metadata": {
+            "category": label,
+            "source": BASE_URL + doc_path,
+            "title": title
+        }
+    }
+
+def _load_or_process_source(entry_point: str, cache_file: str, label: str, embedding_model):
+    """
+    Loads processed data from a cache file if it exists. Otherwise, scrapes,
+    processes, generates embeddings, and saves to the cache.
+    """
+    if os.path.exists(cache_file):
+        print(f"✅ Found cache for {label}. Loading data from '{cache_file}'...")
+        with open(cache_file, 'rb') as f:
+            return pickle.load(f)
+
+    print(f"ℹ️ No cache for {label}. Starting data scraping and processing...")
+    processed_data = []
+
+    main_page_html = get_html(BASE_URL + entry_point)
+    data_entry = _create_data_entry(get_markdown_from_html(main_page_html), entry_point, label, embedding_model)
+    if (data_entry):
+        processed_data.append(data_entry)
+
+    extracted_links = find_wiki_links(main_page_html)
+
+    for doc_path in tqdm(extracted_links, desc=f"Processing {label} Pages"):
+        full_url = BASE_URL + doc_path
+        text = get_markdown_from_url(full_url)
+
+        data_entry = _create_data_entry(text, doc_path, label, embedding_model)
+        if data_entry:
+            processed_data.append(data_entry)
+
+    print(f"✅ {label} processing complete. Saving {len(processed_data)} entries to '{cache_file}'...")
+    with open(cache_file, 'wb') as f:
+        pickle.dump(processed_data, f)
+
+    return processed_data
+
+# --- App Logic Configuration ---
+BASE_SIMILARITY_THRESHOLD = 0.2
+FOLLOWUP_SIMILARITY_THRESHOLD = 0.5
+DEFAULT_MESSAGE_NO_MATCH = "I'm sorry, I can't find a relevant document to answer that question."
+
+
+# --- Gradio UI Configuration ---
+silksong_theme = gr.themes.Default(
+    primary_hue=gr.themes.colors.red,
+    secondary_hue=gr.themes.colors.zinc,
+    neutral_hue=gr.themes.colors.zinc,
+    font=[gr.themes.GoogleFont("IM Fell English"), "ui-sans-serif", "system-ui", "sans-serif"],
+)
+
+silksong_css="""
+.gradio-container {
+    background-image: linear-gradient(rgba(255,255,255, 0.5), rgba(255, 255, 255, 1.0)), url("/gradio_api/file=assets/background.jpg");
+    background-size: 100%;
+    background-repeat: no-repeat;
+    background-position: top center;
+}
+body.dark .gradio-container {
+    background-image: linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 1.0)), url("/gradio_api/file=assets/background.jpg");
+}
+.header-text { text-align: center; text-shadow: 2px 2px 5px #000; }
+.header-text h1 { font-size: 2.5em; color: #dc2626; }
+.dark .header-text { text-shadow: 2px 2px 5px #FFF; }
+.context { text-align: center; color: var(--body-text-color-subdued); }
+.context a { color: #dc2626; }
+.disclaimer { text-align: center; color: var(--body-text-color-subdued); font-size: 0.9em; padding: 20px; }
+.disclaimer ul { list-style: none; padding: 0; }
+.disclaimer a { color: #dc2626; }
+"""

rag_service.py

@@ -0,0 +1,165 @@
+import spaces
+import torch
+from sentence_transformers import SentenceTransformer, util
+from transformers import pipeline, TextIteratorStreamer
+from threading import Thread
+
+# Import project-specific modules
+from config import BASE_URL, DEFAULT_MESSAGE_NO_MATCH, get_all_game_data
+from chat_context import ChatContext
+
+class RAGService:
+    """Manages model loading, data processing, and chat generation logic."""
+    def __init__(self, data_config: list[dict], embedding_model_id: str, llm_model_id: str):
+        print("Initializing RAG Service...")
+        self.data_config = data_config
+
+        print("Initializing embedding model...")
+        self.embedding_model = SentenceTransformer(embedding_model_id)
+
+        print("Initializing language model...")
+        self.llm_pipeline = pipeline(
+            "text-generation",
+            model=llm_model_id,
+            device_map="auto",
+            dtype="auto",
+        )
+
+        self.knowledge_base: dict[str, list[dict]] = get_all_game_data(self.embedding_model)
+    
+    def _select_content(self, title: str) -> list[dict]:
+        """Helper to safely get the knowledge base for a specific title."""
+        return self.knowledge_base.get(title, [])
+    
+    @torch.no_grad()
+    def find_best_context(self, query: str, contents: list[dict], similarity_threshold: float) -> int:
+        """Finds the most relevant document index based on semantic similarity."""
+        if not query or not contents:
+            return -1
+
+        query_embedding = self.embedding_model.encode(query, prompt_name="query", convert_to_tensor=True).to(self.embedding_model.device)
+
+        try:
+            # Stack pre-computed tensors from our knowledge base
+            contents_embeddings = torch.stack([item["embedding"] for item in contents]).to(self.embedding_model.device)
+        except (RuntimeError, IndexError, TypeError) as e:
+            print(f"Warning: Could not stack content embeddings. Error: {e}")
+            return -1
+
+        # Compute cosine similarity between the 1 query embedding and N content embeddings
+        similarities = util.pytorch_cos_sim(query_embedding, contents_embeddings)
+
+        if similarities.numel() == 0:
+            print("Warning: Similarity computation returned an empty tensor.")
+            return -1
+
+        # Get the index and score of the top match
+        best_index = similarities.argmax().item()
+        best_score = similarities[0, best_index].item()
+
+        print(f"Best score: {best_score:.4f} (Threshold: {similarity_threshold})")
+        if best_score >= similarity_threshold:
+            print(f"Using \"{contents[best_index]['metadata']['source']}\"...")
+            return best_index
+
+        print("No context met the similarity threshold.")
+        return -1
+    
+    @spaces.GPU
+    def respond(self, message: str, history: list, title: str, chat_context: ChatContext):
+        """Generates a streaming response from the LLM based on the best context found."""
+        default_threshold = chat_context.base_similarity
+        followup_threshold = chat_context.followup_similarity
+
+        contents = self._select_content(title)
+        if not contents:
+            print(f"No content found for {title}")
+            chat_context.context_index = -1 # Return -1 to reset context
+            yield DEFAULT_MESSAGE_NO_MATCH, chat_context
+            return
+
+        if len(history) == 0:
+            # Clear context on a new conversation
+            print("New conversation started. Clearing context.")
+            chat_context.context_index = -1
+
+        # Determine threshold: Use follow-up ONLY if we have a valid previous context.
+        similarity_threshold = followup_threshold if chat_context.context_index != -1 else default_threshold
+        print(f"Using {'follow-up' if chat_context.context_index != -1 else 'default'} threshold: {similarity_threshold}")
+
+        # Find the best new context based on the current message
+        found_context_index = self.find_best_context(message, contents, similarity_threshold)
+
+        if found_context_index >= 0:
+            chat_context.context_index = found_context_index  # A new, relevant context was found and set
+        elif chat_context.context_index >= 0:
+            # PASS: A follow-up question, but no new context. Reuse the old one.
+            print("No new context found, reusing previous context for follow-up.")
+        else:
+            # FAILURE: No new context was found AND no previous context exists.
+            print("No context found and no previous context. Yielding no match.")
+            yield DEFAULT_MESSAGE_NO_MATCH, chat_context
+            return
+
+        system_prompt = f"Answer the following QUESTION based only on the CONTEXT provided. If the answer cannot be found in the CONTEXT, write \"{DEFAULT_MESSAGE_NO_MATCH}\"\n---\nCONTEXT:\n{contents[chat_context.context_index]['text']}\n"
+        user_prompt = f"QUESTION:\n{message}"
+
+        messages = [{"role": "system", "content": system_prompt}]
+        # Add previous turns (history) after the system prompt but before the current question
+        messages.extend(history)
+        messages.append({"role": "user", "content": user_prompt})
+
+        # Debug print the conversation being sent (excluding the large system prompt)
+        for item in messages[1:]:
+            print(f"[{item['role']}] {item['content']}")
+
+        streamer = TextIteratorStreamer(self.llm_pipeline.tokenizer, skip_prompt=True, skip_special_tokens=True)
+
+        thread = Thread(
+            target=self.llm_pipeline,
+            kwargs=dict(
+                text_inputs=messages,
+                streamer=streamer,
+                max_new_tokens=512,
+                do_sample=True,
+                top_p=0.95,
+                temperature=0.7,
+            )
+        )
+        thread.start()
+
+        response = ""
+        for new_text in streamer:
+            response += new_text
+            # Yield the partial response AND the current state
+            yield response, chat_context
+
+    # --- Gradio UI Callback Methods ---
+    
+    def on_context_changed(self, context_state: ChatContext, title: str) -> str:
+        """Updates the HTML context display when the context_index state changes."""
+        context_index = context_state.context_index
+        if context_index < 0:
+            return """<div class="context">Context: None</div>"""
+
+        contents = self._select_content(title)
+        if not contents or context_index >= len(contents):
+            return """<div class="context">Context: Error</div>"""
+            
+        url = contents[context_index]['metadata']['source']
+        title = contents[context_index]['metadata']['title']
+        return f"""<div class="context">Context: <a href="{url}" target="_blank">{title}</a></div>"""
+
+    @staticmethod
+    def on_title_changed(context_state: ChatContext) -> tuple[str, ChatContext]:
+        """Resets the context display and state when the game is changed."""
+        context_state.context_index = -1
+        return """<div class="context">Context: None</div>""", context_state
+
+    @staticmethod
+    def on_sim_changed(context_state: ChatContext, base_sim: float, followup_sim: float) -> ChatContext:
+        """Updates the similarity thresholds in the context state."""
+        context_state.base_similarity = base_sim
+        context_state.followup_similarity = followup_sim
+        return context_state
+

ui.py

@@ -0,0 +1,71 @@
+import gradio as gr
+from rag_service import RAGService
+from chat_context import ChatContext
+from config import (
+    silksong_theme, 
+    silksong_css, 
+    LLM_MODEL_ID, 
+    BASE_SIMILARITY_THRESHOLD, 
+    FOLLOWUP_SIMILARITY_THRESHOLD
+)
+
+def build_gradio_ui(rag_service: RAGService) -> gr.Blocks:
+    """Creates and configures the Gradio Blocks UI."""
+    
+    gr.set_static_paths(paths=["assets/"])
+
+    with gr.Blocks(theme=silksong_theme, css=silksong_css) as demo:
+        gr.HTML("""
+            <div class="header-text">
+                <h1>A Weaver's Counsel</h1>
+                <p>Speak, little traveler. What secrets of Pharloom do you seek?</p>
+                <p style="font-style: italic;">(Note: This bot has a limited knowledge.)</p>
+            </div>
+        """)
+
+        game_title = gr.Dropdown(["Hollow Knight", "Silksong"], label="Game", value="Silksong")
+
+        output = gr.HTML("""<div class="context">Context: None</div>""")
+
+        # Link the state object to the UI elements
+        context_state = gr.State(ChatContext())
+        context_state.change(rag_service.on_context_changed, [context_state, game_title], output)
+        game_title.change(rag_service.on_title_changed, context_state, [output, context_state])
+
+        gr.ChatInterface(
+            rag_service.respond,
+            type="messages",
+            chatbot=gr.Chatbot(type="messages", label=LLM_MODEL_ID),
+            textbox=gr.Textbox(placeholder="Ask about the haunted kingdom...", container=False, submit_btn=True, scale=7),
+            additional_inputs=[
+                game_title,
+                context_state, ### Pass the state object as an input
+            ],
+            additional_outputs=[context_state], ### Receive the updated state as an output
+            examples=[
+                ["Where can I find the Moorwing?", "Silksong"],
+                ["Who is the voice of Lace?", "Silksong"],
+                ["How can I beat the False Knight?", "Hollow Knight"],
+                ["Any achievement for Hornet Protector?", "Hollow Knight"],
+            ],
+            cache_examples=False,
+        )
+
+        base_sim = gr.Slider(minimum=0.1, maximum=1.0, value=BASE_SIMILARITY_THRESHOLD, step=0.1, label="Base Similarity Threshold")
+        followup_sim = gr.Slider(minimum=0.1, maximum=1.0, value=FOLLOWUP_SIMILARITY_THRESHOLD, step=0.1, label="Similarity Threshold with follow-up questions (multi-turn)")
+
+        base_sim.release(rag_service.on_sim_changed, [context_state, base_sim, followup_sim], context_state)
+        followup_sim.release(rag_service.on_sim_changed, [context_state, base_sim, followup_sim], context_state)
+
+        gr.HTML("""
+            <div class="disclaimer">
+                <p><strong>Disclaimer:</strong></p>
+                <ul style="list-style: none; padding: 0;">
+                    <li>This is a fan-made personal demonstration and not affiliated with any organization.<br>The bot is for entertainment purposes only.</li>
+                    <li>Factual information is sourced from the <a href="https://hollowknight.wiki" target="_blank">Hollow Knight Wiki</a>.<br>Content is available under <a href="https://creativecommons.org/licenses/by-sa/3.0/" target="_blank">Commons Attribution-ShareAlike</a> unless otherwise noted.</li>
+                    <li>Built by <a href="https://huggingface.co/bebechien" target="_blank">bebechien</a> with a 💖 for the world of Hollow Knight.</li>
+                </ul>
+            </div>
+        """)
+    
+    return demo

web_helper.py

@@ -0,0 +1,37 @@
+import requests
+from bs4 import BeautifulSoup
+from html_to_markdown import convert_to_markdown
+
+# --- Static Helper Functions (Web Scraping) ---
+
+@staticmethod
+def get_html(url: str) -> str:
+    """Fetches HTML content from a URL."""
+    try:
+        response = requests.get(url)
+        response.raise_for_status()  # Raises an HTTPError for bad responses (4xx or 5xx)
+        return response.text
+    except requests.exceptions.RequestException as e:
+        print(f"Error fetching {url}: {e}")
+        return ""
+
+@staticmethod
+def find_wiki_links(html_content: str) -> list[str]:
+    """Parses HTML to find all boss links within the 'mw-pages' div."""
+    soup = BeautifulSoup(html_content, 'html.parser')
+    mw_pages_div = soup.find('div', id='mw-pages')
+    if not mw_pages_div:
+        return []
+    return [a['href'] for a in mw_pages_div.find_all('a', href=True)]
+
+@staticmethod
+def get_markdown_from_html(html: str) -> str:
+    if not html:
+        return ""
+
+    soup = BeautifulSoup(html, 'html.parser')
+    return convert_to_markdown(soup)
+
+@staticmethod
+def get_markdown_from_url(url: str) -> str:
+    return get_markdown_from_html(get_html(url))