upload gradio project to HuggingFace Spaces

README.md

@@ -1,14 +1,49 @@
 ---
-title: SemanticBookSearch
-emoji: 🌖
-colorFrom: indigo
-colorTo: blue
+title: Semantic Book Search (2.4M)
+emoji: 📚
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.0.2
+sdk_version: 4.0.0
 app_file: app.py
 pinned: false
-license: apache-2.0
-short_description: 'An AI-powered semantic search engine for 2.4M+ books. '
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 📚 Semantic Book Search Engine
+
+Welcome to the **AI-powered Book Search Engine**.
+Stop searching by exact keywords. This tool allows you to search for books by **describing the plot, the atmosphere, or the emotions** you are looking for.
+
+The system indexes over **2.4 million books**, allowing you to uncover hidden gems using state-of-the-art Natural Language Processing.
+
+## 🚀 How to use it
+
+### 1. 🔎 Search by Plot (Semantic Search)
+Can't remember the title? Looking for a specific vibe?
+* Try: *"A dystopian novel where books are banned and burned by firemen"*
+* Try: *"A psychological thriller set in Victorian London with a plot twist"*
+* The model understands the **concept** and retrieves the most semantically similar books.
+
+### 2. 📖 I liked... (Recommendation)
+Did you love a specific book?
+* Switch to the second tab.
+* Search for a title (e.g., *"Harry Potter"*).
+* The system retrieves the existing vector from the database and recommends books that are mathematically closest in the latent space (similar style, genre, and plot).
+
+---
+
+## 🛠️ Under the Hood (Technical Architecture)
+
+This project is a showcase of **End-to-End AI Engineering**, designed to handle large-scale datasets in a **Low-Resource Environment**.
+
+* **Dataset:** ~2.4 Million books processed and indexed.
+* **AI Embedding Model:** `intfloat/multilingual-e5-small`.
+* **Hybrid Retrieval Architecture:**
+    * 🧠 **Qdrant (Vector DB):** Handles semantic similarity search. Vectors are compressed using **INT8 Scalar Quantization**.
+    * 🗄️ **Turso (LibSQL):** Relational database for low-latency metadata retrieval (Title, Author, Year, Rating), keeping the vector payload lightweight.
+
+### 👨‍💻 Author
+**Antonio Gagliostro**
+* [GitHub Profile](https://github.com/ninooo96)
+* [LinkedIn](https://www.linkedin.com/in/antonio-gagliostro-1b4751121)

app.py

@@ -0,0 +1,284 @@
+import gradio as gr
+import os
+import libsql_experimental as libsql
+from qdrant_client import QdrantClient, models
+from sentence_transformers import SentenceTransformer
+import time
+
+# --- SETUP ---
+model = SentenceTransformer("intfloat/multilingual-e5-small", device="cpu")
+
+QDRANT_URL = os.environ.get("QDRANT_URL")
+QDRANT_API_KEY = os.environ.get("QDRANT_API_KEY")
+TURSO_URL = os.environ.get("TURSO_URL")
+TURSO_TOKEN = os.environ.get("TURSO_TOKEN")
+
+try:
+    client = QdrantClient(
+        url=QDRANT_URL,
+        api_key=QDRANT_API_KEY
+    )
+except Exception as e:
+    print(f"Errore Qdrant: {e}")
+
+def get_turso_conn():
+    return libsql.connect(TURSO_URL, auth_token=TURSO_TOKEN)
+
+COLLECTION_NAME = "books_collection"
+VECTOR_SIZE = 256
+
+# --- CSS GLOBALE ---
+GLOBAL_CSS = """
+/* Animazione Spinner */
+.loader {
+  border: 6px solid #f3f3f3;
+  border-radius: 50%;
+  border-top: 6px solid #3498db;
+  border-bottom: 6px solid #e74c3c;
+  width: 40px;
+  height: 40px;
+  -webkit-animation: spin 1s linear infinite;
+  animation: spin 1s linear infinite;
+  margin: 0 auto;
+}
+
+@keyframes spin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+
+#book_cards button {
+    background-color: #f0f2f5 !important;
+    color: #1f2937 !important;
+    border: 1px solid #d1d5db !important;
+    text-align: left;
+    padding: 10px !important;
+}
+#book_cards button:hover {
+    background-color: #e5e7eb !important;
+    border-color: #3b82f6 !important;
+}
+#book_cards .text-sm {
+    color: #4b5563 !important;
+}
+
+.card-force-dark {
+    color: #000000 !important;
+}
+.card-force-dark h3 {
+    color: #1f2937 !important; 
+    margin-top: 0 !important;
+}
+.card-force-dark p,
+.card-force-dark b,
+.card-force-dark span,
+.card-force-dark div {
+    color: #000000 !important; 
+.card-force-dark summary {
+    color: #007bff !important; 
+}
+"""
+
+# HTML dello spinner
+LOADING_HTML = """
+<div style="display: flex; justify-content: center; align-items: center; height: 100px; width: 100%; flex-direction: column;">
+    <div class="loader"></div>
+    <p style="margin-top: 10px; color: #666; font-size: 0.9em;">Ricerca libri...</p>
+</div>
+"""
+
+# --- FUNZIONI DI SUPPORTO ---
+
+def render_results_from_ids(ids, scores):
+    """Genera l'HTML dai risultati."""
+    if not ids: return "Nessun risultato trovato."
+
+    conn = None
+    ordered_books = []
+    try:
+        conn = get_turso_conn()
+        placeholders = ", ".join(["?"] * len(ids))
+        sql_query = f"SELECT id, title, author, year, rating, summary FROM books WHERE id IN ({placeholders})"
+        cursor = conn.execute(sql_query, tuple(ids))
+        rows = cursor.fetchall()
+        books_map = {row[0]: row for row in rows}
+
+        for uid in ids:
+            if uid in books_map:
+                ordered_books.append(books_map[uid])
+    except Exception as e:
+        return f"Errore Database Turso: {str(e)}"
+    finally:
+        if conn: conn.close()
+
+    html_output = "<div style='font-family: sans-serif; gap: 10px; display: flex; flex-direction: column;'>"
+    for row in ordered_books:
+        score = scores.get(row[0], 0.0)
+
+        autore_clean = str(row[2]).replace('"', '').replace("[","").replace("]", "")
+
+        html_output += f"""
+        <div class="card-force-dark" style="border: 1px solid #ddd; padding: 15px; border-radius: 8px; background-color: #ffffff;">
+            <h3>{row[1]}</h3>
+
+            <p style="font-size: 0.9em; margin-bottom: 5px;">
+                <b>✍️ {autore_clean}</b> | 📅 {row[3]} | ⭐ {row[4]}
+            </p>
+
+            <p style="margin-top: 0;">
+                <b>🎯 Similarità:</b> {score:.3f}
+            </p>
+
+            <details>
+                <summary style="cursor: pointer;">Leggi Trama</summary>
+                <p style="margin-top: 5px;">{row[5]}</p>
+            </details>
+        </div>
+        """
+    html_output += "</div>"
+    return html_output
+
+def search_free_text_animated(query_text, max_results):
+    yield gr.update(visible=True), gr.update(visible=False)
+    time.sleep(0.2)
+
+    if not query_text:
+        yield gr.update(visible=False), "Inserisci una richiesta!"
+        return
+
+    try:
+        vec = model.encode(f"query: {query_text}")[:VECTOR_SIZE]
+        hits_response = client.query_points(
+            collection_name=COLLECTION_NAME,
+            query=vec,
+            limit=int(max_results),
+            search_params=models.SearchParams(quantization=models.QuantizationSearchParams(rescore=True))
+        )
+        hits = hits_response.points
+        ids = [hit.id for hit in hits]
+        scores = {hit.id: hit.score for hit in hits}
+
+        final_html = render_results_from_ids(ids, scores)
+
+        yield gr.update(visible=False), gr.update(value=final_html, visible=True)
+
+    except Exception as e:
+        yield gr.update(visible=False), f"Errore: {e}"
+
+
+def find_book_cards_animated(partial_title):
+    # FASE 1: Spinner ON, Dataset OFF
+    yield gr.update(visible=True), gr.update(visible=False), []
+    time.sleep(0.3)
+
+    if not partial_title or len(partial_title) < 2:
+        yield gr.update(visible=False), gr.update(samples=[], visible=False), []
+        return
+
+    conn = None
+    try:
+        conn = get_turso_conn()
+        query = f"SELECT id, title, author, year FROM books WHERE title LIKE '%{partial_title}%' LIMIT 10"
+        rows = conn.execute(query).fetchall()
+
+        card_data = [[str(row[1]), str(row[2]).replace('"', '').replace("'", "").replace("[","").replace("]",""), str(row[3]).split('.')[0]] for row in rows]
+        full_data_state = [{"id": row[0], "title": row[1]} for row in rows]
+
+        # FASE 2: Spinner OFF, Dataset ON
+        yield gr.update(visible=False), gr.update(samples=card_data, visible=True), full_data_state
+
+    except Exception as e:
+        print(f"Error: {e}")
+        yield gr.update(visible=False), gr.update(visible=False), []
+    finally:
+        if conn: conn.close()
+
+
+def on_card_click_animated(selected_index, books_state_list, max_results):
+    yield gr.update(visible=True), gr.update(visible=False)
+    time.sleep(0.2)
+
+    if selected_index >= len(books_state_list):
+        yield gr.update(visible=False), "Errore selezione."
+        return
+
+    book_obj = books_state_list[selected_index]
+    source_id = book_obj["id"]
+
+    try:
+        points = client.retrieve(collection_name=COLLECTION_NAME, ids=[source_id], with_vectors=True)
+        if not points:
+            yield gr.update(visible=False), "ID non trovato."
+            return
+
+        existing_vector = points[0].vector
+        hits_response = client.query_points(
+            collection_name=COLLECTION_NAME,
+            query=existing_vector,
+            limit=int(max_results),
+            query_filter=models.Filter(must_not=[models.HasIdCondition(has_id=[source_id])]),
+            search_params=models.SearchParams(quantization=models.QuantizationSearchParams(rescore=True))
+        )
+        ids = [hit.id for hit in hits_response.points]
+        scores = {hit.id: hit.score for hit in hits_response.points}
+        final_html = render_results_from_ids(ids, scores)
+
+        yield gr.update(visible=False), gr.update(value=final_html, visible=True)
+
+    except Exception as e:
+        yield gr.update(visible=False), f"Errore Backend: {e}"
+
+
+# --- INTERFACCIA ---
+with gr.Blocks(theme=gr.themes.Soft(), css=GLOBAL_CSS) as demo:
+    gr.Markdown("# 📚 AI Book Finder")
+
+    books_state = gr.State([])
+
+    with gr.Row():
+        num_results = gr.Slider(1, 10, value=5, step=1, label="Quanti consigli vuoi?")
+
+    with gr.Tabs():
+        # TAB 1: Ricerca Libera
+        with gr.Tab("🔎 Ricerca per Trama"):
+            with gr.Row():
+                txt_input = gr.Textbox(placeholder="Descrivi la trama, l'atmosfera o le emozioni che cerchi...", show_label=False, scale=4)
+                btn_search = gr.Button("Cerca", variant="primary", scale=1)
+
+        # TAB 2: Ricerca per Libro
+        with gr.Tab("📖 Mi è piaciuto..."):
+            with gr.Row():
+                txt_title = gr.Textbox(placeholder="Scrivi il titolo, anche parziale", show_label=False, scale=4)
+                btn_find = gr.Button("Trova", scale=1)
+
+            loader_cards = gr.HTML(value=LOADING_HTML, visible=False)
+
+            # DATASET
+            cards_view = gr.Dataset(
+                elem_id="book_cards",
+                label="Seleziona il libro corretto:",
+                components=[gr.Textbox(visible=False), gr.Textbox(visible=False), gr.Textbox(visible=False)],
+                headers=["Titolo", "Autore", "Anno"],
+                samples=[],
+                visible=False,
+                type="index"
+            )
+
+    loader_results = gr.HTML(value=LOADING_HTML, visible=False)
+    out_results = gr.HTML(label="Consigli", visible=True)
+
+    # EVENTI
+    btn_search.click(fn=search_free_text_animated, inputs=[txt_input, num_results], outputs=[loader_results, out_results])
+    txt_input.submit(fn=search_free_text_animated, inputs=[txt_input, num_results], outputs=[loader_results, out_results])
+
+    btn_find.click(fn=find_book_cards_animated, inputs=[txt_title], outputs=[loader_cards, cards_view, books_state])
+    txt_title.submit(fn=find_book_cards_animated, inputs=[txt_title], outputs=[loader_cards, cards_view, books_state])
+
+    cards_view.click(
+        fn=on_card_click_animated,
+        inputs=[cards_view, books_state, num_results],
+        outputs=[loader_results, out_results]
+    )
+
+print("Avvio Gradio...")
+demo.launch(share=True, debug=True)

requirements.txt

@@ -0,0 +1,5 @@
+gradio
+pandas
+qdrant-client
+sentence-transformers
+libsql-experimental