Init project

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+storage/
+data/
+exports/

app.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+
+from src.config import settings
+from src.export import export
+from src.filters import MetadataFilter, filters_to_dict
+from src.indexing import save_and_ingest_pdf
+from src.learning import generate_flashcards, generate_quiz, summarize
+from src.llm import set_runtime_gemini_api_key
+from src.rag import answer
+from src.store import list_documents
+
+_INFO_NOTE_HTML = """
+<div class="info-card">
+  <div class="info-card-title">⚠️ Lưu ý sử dụng</div>
+  <ul class="info-card-list">
+    <li>Đây là ứng dụng demo phục vụ mục đích học tập và minh hoạ cho bài toán RAG.</li>
+    <li>Ứng dụng dùng <b>Gemini API</b>. Hãy nhập <b>Gemini API Key</b> trước khi chạy (key chỉ dùng trong phiên hiện tại, không lưu).</li>
+    <li>Hãy tải PDF trước, đợi hệ thống index xong, rồi mới dùng các tab Hỏi đáp, Tóm tắt, Quiz và Flashcards.</li>
+  </ul>
+</div>
+"""
+
+_USAGE_MARKDOWN = """
+1. **Tải PDF** ở khối bên trái rồi bấm **Nạp & Index**.  
+2. **Chọn tài liệu** muốn học trong danh sách đã index.  
+3. Dùng các tab để **hỏi đáp**, **tóm tắt**, **tạo quiz** hoặc **flashcards**.  
+4. Nếu chỉ chọn đúng 1 tài liệu, bạn có thể lọc thêm theo **trang**.
+
+**Mẹo:** Khi đặt câu hỏi rõ ràng theo chủ đề, kết quả RAG thường sát và dễ học hơn.
+"""
+
+_CSS = Path("static/style.css").read_text(encoding="utf-8")
+
+
+def _img_b64(path: str) -> str:
+    with open(path, "rb") as file_obj:
+        return base64.b64encode(file_obj.read()).decode("utf-8")
+
+
+def _status_html(message: str) -> str:
+    return f'<div class="status-bar">{message}</div>'
+
+def _read_uploaded_pdf(file_obj: object) -> tuple[bytes, str]:
+    """Normalize Gradio file payload into (bytes, filename).
+
+    Gradio may pass:
+    - `str` / `NamedString`: a local filepath
+    - `FileData`: object with `.path` and optional `.orig_name`
+    - `dict`: with keys like `path` / `orig_name`
+    """
+    if isinstance(file_obj, str):
+        p = Path(file_obj)
+        return p.read_bytes(), p.name
+
+    path = getattr(file_obj, "path", None)
+    orig = getattr(file_obj, "orig_name", None)
+    if isinstance(path, str) and path:
+        p = Path(path)
+        name = str(orig).strip() if isinstance(orig, str) and orig.strip() else p.name
+        return p.read_bytes(), name
+
+    if isinstance(file_obj, dict):
+        raw_path = file_obj.get("path")
+        raw_name = file_obj.get("orig_name") or file_obj.get("name")
+        if isinstance(raw_path, str) and raw_path:
+            p = Path(raw_path)
+            name = str(raw_name).strip() if isinstance(raw_name, str) and raw_name.strip() else p.name
+            return p.read_bytes(), name
+
+    raise TypeError(f"Unsupported uploaded file type: {type(file_obj).__name__}")
+
+
+def _filters(filenames: list[str] | None, page: int | None) -> dict[str, object] | None:
+    payload: dict[str, object] = {}
+    if filenames:
+        payload["filenames"] = filenames
+    if page is not None:
+        payload["page"] = page
+    return filters_to_dict(MetadataFilter.model_validate(payload)) if payload else None
+
+
+def _refresh_docs() -> tuple[object, dict[str, Any], object, str, str]:
+    docs = list_documents()
+    choices = [d["filename"] for d in docs]
+    doc_map = {d["filename"]: d for d in docs}
+    if docs:
+        summary = (
+            f"**{len(docs)}** tài liệu đã index · "
+            f"**{sum(int(d['chunk_count']) for d in docs)}** đoạn văn"
+        )
+    else:
+        summary = "Chưa có tài liệu nào được index."
+    filenames_text = "\n".join(f"- `{name}`" for name in choices) if choices else "_Danh sách trống_"
+    return (
+        gr.update(choices=choices, value=[]),
+        doc_map,
+        gr.update(choices=["(Tất cả trang)"], value="(Tất cả trang)", interactive=True),
+        summary,
+        filenames_text,
+    )
+
+
+def _pages_for_selection(doc_map: dict[str, Any], selected: list[str]) -> gr.Dropdown:
+    if len(selected) != 1:
+        return gr.update(choices=["(Tất cả trang)"], value="(Tất cả trang)", interactive=False)
+    doc = doc_map.get(selected[0]) or {}
+    pages = doc.get("pages") or []
+    page_choices = ["(Tất cả trang)", *[str(p) for p in pages]]
+    return gr.update(choices=page_choices, value="(Tất cả trang)", interactive=True)
+
+
+def _upload_pdf(
+    file: object | None,
+) -> tuple[str, object, dict[str, Any], object, str, str]:
+    if file is None:
+        choices, doc_map, page_dropdown, summary, filenames_text = _refresh_docs()
+        return (
+            _status_html("⚠️ Vui lòng chọn file PDF."),
+            choices,
+            doc_map,
+            page_dropdown,
+            summary,
+            filenames_text,
+        )
+    file_bytes, filename = _read_uploaded_pdf(file)
+    info = save_and_ingest_pdf(file_bytes, filename)
+    message = _status_html(f"✅ Đã nạp **{info['filename']}** · {info['chunks_indexed']} đoạn")
+    choices, doc_map, page_dropdown, summary, filenames_text = _refresh_docs()
+    return message, choices, doc_map, page_dropdown, summary, filenames_text
+
+
+def _ask(question: str, k: int, selected_docs: list[str], page: str, gemini_key: str) -> tuple[str, str]:
+    if not question or not question.strip():
+        return "Vui lòng nhập câu hỏi.", ""
+    page_num = None if page == "(Tất cả trang)" else int(page)
+    set_runtime_gemini_api_key(gemini_key)
+    res = answer(question.strip(), k=int(k), filters=_filters(selected_docs, page_num))
+    return res.answer, json.dumps(res.model_dump(), ensure_ascii=False, indent=2)
+
+
+def _summarize(query: str, k: int, selected_docs: list[str], page: str, gemini_key: str) -> tuple[str, str]:
+    page_num = None if page == "(Tất cả trang)" else int(page)
+    set_runtime_gemini_api_key(gemini_key)
+    res = summarize(query=query.strip() or None, filters=_filters(selected_docs, page_num), k=int(k))
+    return export(res, fmt="md"), res.model_dump_json(indent=2)
+
+
+def _quiz(
+    query: str,
+    count: int,
+    k: int,
+    selected_docs: list[str],
+    page: str,
+    gemini_key: str,
+) -> tuple[str, str]:
+    page_num = None if page == "(Tất cả trang)" else int(page)
+    set_runtime_gemini_api_key(gemini_key)
+    res = generate_quiz(
+        query=query.strip() or None,
+        count=int(count),
+        filters=_filters(selected_docs, page_num),
+        k=int(k),
+    )
+    return export(res, fmt="md"), res.model_dump_json(indent=2)
+
+
+def _flashcards(
+    query: str,
+    count: int,
+    k: int,
+    selected_docs: list[str],
+    page: str,
+    gemini_key: str,
+) -> tuple[str, str]:
+    page_num = None if page == "(Tất cả trang)" else int(page)
+    set_runtime_gemini_api_key(gemini_key)
+    res = generate_flashcards(
+        query=query.strip() or None,
+        count=int(count),
+        filters=_filters(selected_docs, page_num),
+        k=int(k),
+    )
+    return export(res, fmt="md"), res.model_dump_json(indent=2)
+
+
+def _write_export(md_text: str, filename: str) -> str | None:
+    if not md_text or md_text.startswith("Lỗi:"):
+        return None
+    output_path = Path("exports") / filename
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(md_text, encoding="utf-8")
+    return str(output_path)
+
+
+_theme = gr.themes.Base().set(
+    background_fill_primary="#eef1fb",
+    background_fill_secondary="#e4e9f7",
+    block_background_fill="transparent",
+    block_border_color="transparent",
+    block_border_width="0px",
+    input_background_fill="#ffffff",
+)
+
+with gr.Blocks(title="RAG Learning System", fill_width=True, fill_height=True) as demo:
+    with gr.Row(elem_classes="header-row"):
+        logo_b64 = _img_b64("static/aivn_logo.png")
+        gr.HTML(f'<img src="data:image/png;base64,{logo_b64}" alt="AIVN">')
+        gr.HTML(
+            '<div class="header-meta">'
+            '<p class="header-title">📚 RAG Learning System</p>'
+            '<p class="header-sub">AIO2025 — Hỏi đáp · Tóm tắt · Quiz · Flashcards có trích dẫn nguồn</p>'
+            '</div>'
+        )
+
+    gr.HTML(_INFO_NOTE_HTML)
+
+    doc_map_state = gr.State({})
+
+    with gr.Row(equal_height=False, elem_classes="main-layout"):
+        with gr.Column(scale=4, min_width=340, elem_classes="control-stack"):
+            gr.Markdown("### 📥 Nạp tài liệu PDF")
+            upload = gr.File(
+                label="Chọn PDF",
+                file_types=[".pdf"],
+                file_count="single",
+                type="filepath",
+            )
+            upload_btn = gr.Button("Nạp & Index", elem_classes="gen-btn")
+            upload_status = gr.HTML(_status_html("Sẵn sàng."))
+
+            # with gr.Group(elem_classes="control-card"):
+            with gr.Accordion("🔑 Gemini API Key (tuỳ chọn)", open=False):
+                gr.Markdown(
+                    "API key chỉ dùng trong phiên hiện tại và **không được lưu**.",
+                    elem_classes="help-markdown",
+                )
+                gemini_key_input = gr.Textbox(
+                    label="Gemini API Key",
+                    type="password",
+                    placeholder="AIza...",
+                    lines=1,
+                    max_lines=1,
+                )
+
+            with gr.Accordion("❓ Hướng dẫn sử dụng", open=False):
+                gr.Markdown(_USAGE_MARKDOWN, elem_classes="help-markdown")
+
+            with gr.Accordion("🔐 Cấu hình chạy trên Space", open=False):
+                gr.Markdown(
+                    f"""
+                    - LLM model: `{settings.llm_model}`
+                    - Embedding model: `{settings.embedding_model}`
+                    - Collection: `{settings.qdrant_collection}`
+                    - Data dir: `{settings.data_dir}`
+                    - Storage dir: `{settings.storage_dir}`
+                    """,
+                    elem_classes="help-markdown",
+                )
+
+        with gr.Column(scale=7, min_width=560, elem_classes="preview-col"):
+            gr.HTML(
+                '<div class="preview-header"><div>'
+                '<p class="preview-title">🗂️ Tài liệu đã index</p>'
+                '<p class="preview-sub">Làm mới danh sách sau khi tải PDF, rồi chọn phạm vi học tập trước khi truy vấn.</p>'
+                '</div></div>'
+            )
+
+            refresh_btn = gr.Button("Làm mới danh sách tài liệu")
+            doc_summary = gr.Markdown("Chưa có tài liệu nào được index.", elem_classes="doc-summary")
+            docs = gr.CheckboxGroup(label="Chọn tài liệu", choices=[], value=[])
+            page = gr.Dropdown(
+                label="Trang (chỉ áp dụng khi chọn đúng 1 tài liệu)",
+                choices=["(Tất cả trang)"],
+                value="(Tất cả trang)",
+            )
+            doc_list_md = gr.Markdown("_Danh sách trống_")
+
+    with gr.Tabs():
+        with gr.Tab("💬 Hỏi đáp"):
+            q = gr.Textbox(
+                label="Câu hỏi",
+                lines=2,
+                placeholder="Ví dụ: LoRA fine-tuning là gì và tài liệu giải thích điều này ra sao?",
+            )
+            k_ask = gr.Slider(1, 32, value=6, step=1, label="Top-k retrieval")
+            ask_btn = gr.Button("Trả lời", elem_classes="gen-btn")
+            ask_md = gr.Markdown(elem_classes="result-markdown")
+            with gr.Accordion("JSON debug", open=False):
+                ask_raw = gr.Code(label="", language="json")
+
+        with gr.Tab("📝 Tóm tắt"):
+            s_query = gr.Textbox(label="Chủ đề hướng dẫn (tuỳ chọn)", lines=1)
+            s_k = gr.Slider(1, 64, value=10, step=1, label="Số đoạn truy xuất (k)")
+            s_btn = gr.Button("Tạo tóm tắt", elem_classes="gen-btn")
+            s_md = gr.Markdown(elem_classes="result-markdown")
+            s_download = gr.File(label="Tải Markdown", interactive=False)
+            with gr.Accordion("JSON debug", open=False):
+                s_raw = gr.Code(label="", language="json")
+
+        with gr.Tab("📋 Quiz"):
+            z_query = gr.Textbox(label="Chủ đề (tuỳ chọn)", lines=1)
+            z_count = gr.Slider(1, 30, value=3, step=1, label="Số câu hỏi")
+            z_k = gr.Slider(1, 64, value=10, step=1, label="Số đoạn truy xuất (k)")
+            z_btn = gr.Button("Tạo quiz", elem_classes="gen-btn")
+            z_md = gr.Markdown(elem_classes="result-markdown")
+            z_download = gr.File(label="Tải Markdown", interactive=False)
+            with gr.Accordion("JSON debug", open=False):
+                z_raw = gr.Code(label="", language="json")
+
+        with gr.Tab("🃏 Flashcards"):
+            f_query = gr.Textbox(label="Chủ đề (tuỳ chọn)", lines=1)
+            f_count = gr.Slider(1, 40, value=15, step=1, label="Số thẻ")
+            f_k = gr.Slider(1, 64, value=16, step=1, label="Số đoạn truy xuất (k)")
+            f_btn = gr.Button("Tạo flashcards", elem_classes="gen-btn")
+            f_md = gr.Markdown(elem_classes="result-markdown")
+            f_download = gr.File(label="Tải Markdown", interactive=False)
+            with gr.Accordion("JSON debug", open=False):
+                f_raw = gr.Code(label="", language="json")
+
+    gr.HTML(
+        '<div class="footer-text">'
+        'Created by <a href="https://vlai.aivietnam.edu.vn/" target="_blank">VLAI</a>'
+        ' &bull; <a href="https://aivietnam.edu.vn/" target="_blank">AI VIETNAM</a>'
+        '</div>'
+    )
+
+    refresh_btn.click(
+        fn=_refresh_docs,
+        inputs=[],
+        outputs=[docs, doc_map_state, page, doc_summary, doc_list_md],
+    )
+    docs.change(fn=_pages_for_selection, inputs=[doc_map_state, docs], outputs=[page])
+    upload_btn.click(
+        fn=_upload_pdf,
+        inputs=[upload],
+        outputs=[upload_status, docs, doc_map_state, page, doc_summary, doc_list_md],
+    )
+
+    ask_btn.click(fn=_ask, inputs=[q, k_ask, docs, page, gemini_key_input], outputs=[ask_md, ask_raw])
+    s_btn.click(fn=_summarize, inputs=[s_query, s_k, docs, page, gemini_key_input], outputs=[s_md, s_raw]).then(
+        fn=lambda text: _write_export(text, "summary.md"),
+        inputs=[s_md],
+        outputs=[s_download],
+    )
+    z_btn.click(fn=_quiz, inputs=[z_query, z_count, z_k, docs, page, gemini_key_input], outputs=[z_md, z_raw]).then(
+        fn=lambda text: _write_export(text, "quiz.md"),
+        inputs=[z_md],
+        outputs=[z_download],
+    )
+    f_btn.click(
+        fn=_flashcards,
+        inputs=[f_query, f_count, f_k, docs, page, gemini_key_input],
+        outputs=[f_md, f_raw],
+    ).then(
+        fn=lambda text: _write_export(text, "flashcards.md"),
+        inputs=[f_md],
+        outputs=[f_download],
+    )
+
+if __name__ == "__main__":
+    demo.queue(default_concurrency_limit=2).launch(
+        allowed_paths=["static/aivn_logo.png"],
+        css=_CSS, theme=_theme
+    )
+

requirements.txt

@@ -0,0 +1,19 @@
+gradio[mcp,oauth]==6.13.0
+
+jinja2>=3.1,<4
+loguru>=0.7.3,<0.8
+
+pydantic>=2.11.10,<=2.12.5
+pydantic-settings>=2.13,<3
+python-dotenv>=1.2,<2
+
+pypdf>=5,<6
+qdrant-client>=1.16,<2
+
+langchain-core>=1.3,<2
+langchain-community>=0.4,<0.5
+langchain-text-splitters>=1.1,<2
+langchain-qdrant>=1.1,<2
+
+google-genai>=1.0.0
+sentence-transformers>=5.0.0

src/__init__.py

@@ -0,0 +1,2 @@
+"""RAG Learning System core modules for Hugging Face Spaces."""
+

src/config.py

@@ -0,0 +1,61 @@
+"""Application configuration for Hugging Face Spaces.
+
+Defaults live in code; a small set of values can be overridden via env vars.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="RAG_",
+        extra="ignore",
+    )
+
+    data_dir: Path = Path("data")
+    storage_dir: Path = Path("storage/qdrant")
+    qdrant_collection: str = "rag_chunks"
+
+    chunk_size: int = Field(default=1000, ge=100)
+    chunk_overlap: int = Field(default=150, ge=0)
+    top_k: int = Field(default=5, ge=1, le=64)
+
+    llm_provider: Literal["gemini"] = "gemini"
+    llm_model: str = "gemini-flash-lite-latest"
+    llm_temperature: float = Field(default=0.1, ge=0.0, le=2.0)
+    llm_max_new_tokens: int = Field(default=10000, ge=1, le=20000)
+
+    embedding_provider: Literal["local"] = "local"
+    embedding_model: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+
+    gemini_api_key: str | None = Field(default=None, validation_alias="GEMINI_API_KEY")
+
+    summarize_batch_size: int = Field(default=10, ge=1)
+    summarize_retrieval_k: int = Field(default=12, ge=1, le=128)
+    generation_retrieval_k: int = Field(default=16, ge=1, le=128)
+    quiz_default_count: int = Field(default=8, ge=1, le=50)
+    flashcards_default_count: int = Field(default=15, ge=1, le=100)
+
+    @model_validator(mode="after")
+    def validate_config(self) -> "Settings":
+        if self.chunk_overlap >= self.chunk_size:
+            raise ValueError("chunk_overlap must be smaller than chunk_size.")
+
+        return self
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()
+
+
+settings = get_settings()
+

src/embeddings.py

@@ -0,0 +1,32 @@
+"""Local embeddings via Sentence-Transformers (no inference provider)."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from langchain_core.embeddings import Embeddings
+from sentence_transformers import SentenceTransformer
+
+from src.config import settings
+
+
+@lru_cache(maxsize=1)
+def _model() -> SentenceTransformer:
+    return SentenceTransformer(settings.embedding_model)
+
+
+class LocalSentenceTransformerEmbeddings(Embeddings):
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:  # type: ignore[override]
+        vecs = _model().encode(texts, normalize_embeddings=True)
+        tolist = getattr(vecs, "tolist", None)
+        return tolist() if callable(tolist) else [list(map(float, v)) for v in vecs]
+
+    def embed_query(self, text: str) -> list[float]:  # type: ignore[override]
+        vec = _model().encode([text], normalize_embeddings=True)[0]
+        tolist = getattr(vec, "tolist", None)
+        return tolist() if callable(tolist) else [float(x) for x in vec]
+
+
+def get_embeddings() -> Embeddings:
+    return LocalSentenceTransformerEmbeddings()
+

src/export.py

@@ -0,0 +1,116 @@
+"""Export learning outputs to JSON or Markdown."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+from src.schemas import Citation, FlashcardSet, QuizSet, Summary
+
+ExportFormat = Literal["text", "md", "json"]
+
+
+def _citation_line(c: Citation) -> str:
+    parts = [f"[{c.source_marker}] {c.filename} p.{c.page}"]
+    if c.section:
+        parts.append(f"section: {c.section}")
+    if c.chunk_id:
+        parts.append(f"chunk: {c.chunk_id}")
+    return " | ".join(parts)
+
+
+def _citations_block(citations: list[Citation]) -> str:
+    if not citations:
+        return ""
+    lines = ["## Sources", ""]
+    lines.extend(f"- {_citation_line(c)}" for c in citations)
+    return "\n".join(lines) + "\n"
+
+
+def _to_markdown(model: BaseModel) -> str:
+    if isinstance(model, Summary):
+        title = "# Summary" + (f": {model.target}" if model.target else "")
+        lines: list[str] = [title, "", f"_Scope: {model.scope}_", ""]
+        if model.summary:
+            lines.extend([model.summary.strip(), ""])
+        if model.key_points:
+            lines.extend(["## Key Points", "", *[f"- {kp}" for kp in model.key_points], ""])
+        c = _citations_block(model.citations)
+        if c:
+            lines.append(c)
+        return "\n".join(lines).rstrip() + "\n"
+
+    if isinstance(model, QuizSet):
+        title = "# Quiz" + (f": {model.target}" if model.target else "")
+        lines = [title, "", f"_Scope: {model.scope} | Items: {len(model.items)}_", ""]
+        for idx, item in enumerate(model.items, start=1):
+            meta_parts: list[str] = []
+            if item.topic:
+                meta_parts.append(f"topic: {item.topic}")
+            if item.difficulty:
+                meta_parts.append(f"difficulty: {item.difficulty}")
+            meta_suffix = f" _({' | '.join(meta_parts)})_" if meta_parts else ""
+
+            lines.extend([f"## Q{idx}.{meta_suffix}", "", item.question.strip(), ""])
+            for opt_idx, option in enumerate(item.options):
+                lines.append(f"- {chr(ord('A') + opt_idx)}) {option}")
+            lines.append("")
+            lines.append(f"**Answer:** {chr(ord('A') + item.correct_index)}")
+            if item.explanation:
+                lines.append(f"**Explanation:** {item.explanation.strip()}")
+            if item.source_markers:
+                lines.append(f"**Sources:** {', '.join(item.source_markers)}")
+            lines.append("")
+
+        c = _citations_block(model.citations)
+        if c:
+            lines.append(c)
+        return "\n".join(lines).rstrip() + "\n"
+
+    if isinstance(model, FlashcardSet):
+        title = "# Flashcards" + (f": {model.target}" if model.target else "")
+        lines = [title, "", f"_Scope: {model.scope} | Cards: {len(model.cards)}_", ""]
+        for idx, card in enumerate(model.cards, start=1):
+            topic = f" — {card.topic}" if card.topic else ""
+            lines.extend([f"## Card {idx}{topic}", ""])
+            lines.append(f"**Front:** {card.front.strip()}")
+            lines.append(f"**Back:** {card.back.strip()}")
+            if card.hint:
+                lines.append(f"**Hint:** {card.hint.strip()}")
+            if card.source_markers:
+                lines.append(f"**Sources:** {', '.join(card.source_markers)}")
+            lines.append("")
+
+        c = _citations_block(model.citations)
+        if c:
+            lines.append(c)
+        return "\n".join(lines).rstrip() + "\n"
+
+    raise TypeError(f"Unsupported model type: {type(model).__name__}")
+
+
+def export(
+    model: BaseModel, *, fmt: ExportFormat = "text", output: Path | None = None
+) -> str | Path:
+    """Render model to a string, optionally writing it to disk.
+
+    Args: model, fmt, output (optional).
+    Returns: rendered string if output is None; otherwise the written path.
+    Raises: TypeError for unsupported model type; ValueError for unknown fmt.
+    """
+    if fmt == "json":
+        text = model.model_dump_json(indent=2) + "\n"
+    elif fmt in {"text", "md"}:
+        text = _to_markdown(model)
+    else:
+        raise ValueError(f"Unknown fmt '{fmt}'. Expected 'text' | 'md' | 'json'.")
+
+    if output is None:
+        return text
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text, encoding="utf-8")
+    return output
+

src/filters.py

@@ -0,0 +1,86 @@
+"""Shared metadata filtering utilities across the app."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, model_validator
+from qdrant_client.http import models as qmodels
+
+
+class MetadataFilter(BaseModel):
+    """Filter applied against indexed chunk metadata."""
+
+    filename: str | None = None
+    filenames: list[str] | None = None
+    page: int | None = None
+    section: str | None = None
+    document_id: str | None = None
+
+    @model_validator(mode="after")
+    def _normalize(self) -> "MetadataFilter":
+        names = [x for x in (self.filenames or []) if isinstance(x, str) and x.strip()]
+        names = [n.strip() for n in names if n.strip()]
+        if not names:
+            self.filenames = None
+        elif len(names) == 1:
+            self.filename, self.filenames = names[0], None
+        else:
+            # Multi-doc selection: page filter becomes ambiguous, so drop it.
+            self.filename, self.filenames, self.page = None, names, None
+        if self.filename is not None:
+            self.filename = self.filename.strip() or None
+        if self.section is not None:
+            self.section = self.section.strip() or None
+        if self.document_id is not None:
+            self.document_id = self.document_id.strip() or None
+        return self
+
+
+def coerce_filter(filters: MetadataFilter | dict[str, object] | None) -> MetadataFilter | None:
+    """Coerce a dict (or None) into a normalized `MetadataFilter`."""
+    if filters is None:
+        return None
+    if isinstance(filters, MetadataFilter):
+        return filters
+    if isinstance(filters, dict):
+        return MetadataFilter.model_validate(filters)
+    raise TypeError(f"Unsupported filters type: {type(filters).__name__}")
+
+
+def filters_to_dict(filters: MetadataFilter | dict[str, object] | None) -> dict[str, object] | None:
+    """Return normalized flat dict suitable for downstream filtering."""
+    f = coerce_filter(filters)
+    if f is None:
+        return None
+    return f.model_dump(exclude_none=True) or None
+
+
+def filters_to_qdrant(filters: MetadataFilter | dict[str, object] | None) -> qmodels.Filter | None:
+    """Build a Qdrant filter from normalized metadata filters."""
+    flat = filters_to_dict(filters)
+    if not flat:
+        return None
+
+    conditions: list[qmodels.FieldCondition] = []
+    for field, value in flat.items():
+        if value is None:
+            continue
+
+        if field == "filenames" and isinstance(value, list):
+            names = [x for x in value if isinstance(x, str) and x]
+            if names:
+                conditions.append(
+                    qmodels.FieldCondition(
+                        key="metadata.filename", match=qmodels.MatchAny(any=names)
+                    )
+                )
+            continue
+
+        if isinstance(value, (str, int)):
+            conditions.append(
+                qmodels.FieldCondition(
+                    key=f"metadata.{field}", match=qmodels.MatchValue(value=value)
+                )
+            )
+
+    return qmodels.Filter(must=conditions) if conditions else None
+

src/indexing.py

@@ -0,0 +1,173 @@
+"""Load PDFs, split into chunks with metadata, and index into Qdrant."""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from collections import defaultdict
+from pathlib import Path
+from typing import Protocol
+
+from langchain_community.document_loaders import PyPDFLoader
+from langchain_core.documents import Document
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from loguru import logger
+
+from src.config import settings
+from src.schemas import ChunkMetadata
+from src.store import ensure_collection, get_vector_store
+
+
+class Chunker(Protocol):
+    def split_documents(self, documents: list[Document]) -> list[Document]:
+        """Split page-level documents into chunk-level documents."""
+
+
+def _splitter(
+    chunk_size: int | None = None, chunk_overlap: int | None = None
+) -> RecursiveCharacterTextSplitter:
+    size = chunk_size or settings.chunk_size
+    overlap = chunk_overlap or settings.chunk_overlap
+
+    return RecursiveCharacterTextSplitter(
+        chunk_size=size,
+        chunk_overlap=overlap,
+        separators=["\n\n", "\n", ". ", " ", ""],
+        keep_separator=False,
+    )
+
+
+def _document_id(path: Path) -> str:
+    raw = f"{path.name}:{path.stat().st_size}"
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16]
+
+
+def _chunk_id(doc_id: str, page: int, index: int) -> str:
+    return f"{doc_id}:{page}:{index}"
+
+
+def _load_pdf(path: Path) -> list[Document]:
+    loader = PyPDFLoader(str(path))
+    pages = loader.load()
+    doc_id = _document_id(path)
+    for doc in pages:
+        page_number = int(doc.metadata.get("page", 0)) + 1
+        doc.metadata = {
+            "document_id": doc_id,
+            "filename": path.name,
+            "source": str(path.resolve()),
+            "page": page_number,
+            "section": doc.metadata.get("section"),
+        }
+    return pages
+
+
+def discover_pdfs(data_dir: Path | None = None) -> list[Path]:
+    directory = data_dir or settings.data_dir
+    if not directory.exists():
+        return []
+    return sorted(p for p in directory.iterdir() if p.is_file() and p.suffix.lower() == ".pdf")
+
+
+def build_chunks(
+    pdf_paths: list[Path],
+    chunk_size: int | None = None,
+    chunk_overlap: int | None = None,
+    chunker: Chunker | None = None,
+) -> list[Document]:
+    page_docs: list[Document] = []
+    for path in pdf_paths:
+        logger.info("Loading PDF: {}", path.name)
+        page_docs.extend(_load_pdf(path))
+
+    if chunker is None:
+        chunks = _splitter(chunk_size, chunk_overlap).split_documents(page_docs)
+    else:
+        chunks = chunker.split_documents(page_docs)
+
+    per_doc_counter: dict[str, int] = defaultdict(int)
+    for chunk in chunks:
+        doc_id = chunk.metadata["document_id"]
+        idx = per_doc_counter[doc_id]
+        per_doc_counter[doc_id] += 1
+        meta = ChunkMetadata(
+            document_id=doc_id,
+            filename=chunk.metadata["filename"],
+            source=chunk.metadata["source"],
+            page=chunk.metadata["page"],
+            chunk_id=_chunk_id(doc_id, chunk.metadata["page"], idx),
+            section=chunk.metadata.get("section"),
+        )
+        chunk.metadata = meta.model_dump()
+    return chunks
+
+
+def index_chunks(chunks: list[Document], collection_name: str | None = None) -> int:
+    """Compute deterministic UUIDs and add chunks to the vector store.
+
+    Re-ingesting the same content upserts instead of creating duplicates.
+    """
+    if not chunks:
+        return 0
+    ids = [str(uuid.uuid5(uuid.NAMESPACE_DNS, c.metadata["chunk_id"])) for c in chunks]
+    get_vector_store(collection_name=collection_name).add_documents(chunks, ids=ids)
+    return len(chunks)
+
+
+def ingest(
+    recreate: bool = False,
+    collection_name: str | None = None,
+    chunker: Chunker | None = None,
+    chunk_size: int | None = None,
+    chunk_overlap: int | None = None,
+) -> int:
+    pdfs = discover_pdfs()
+    if not pdfs:
+        logger.warning("No PDF files found in {}", settings.data_dir)
+        return 0
+
+    ensure_collection(recreate=recreate, collection_name=collection_name)
+    chunks = build_chunks(
+        pdfs,
+        chunker=chunker,
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+    )
+
+    if not chunks:
+        logger.warning("No chunks produced from {} PDF(s)", len(pdfs))
+        return 0
+
+    count = index_chunks(chunks, collection_name=collection_name)
+    logger.info("Ingested {} chunks from {} PDF(s)", count, len(pdfs))
+    return count
+
+
+def save_and_ingest_pdf(file_bytes: bytes, filename: str) -> dict[str, object]:
+    """Save an uploaded PDF to `data_dir` and ingest it into Qdrant.
+
+    Args: file_bytes, filename. Returns: {"filename", "chunks_indexed"}. Raises: ValueError.
+    """
+    if not filename:
+        raise ValueError("Filename is required.")
+    if not filename.lower().endswith(".pdf"):
+        raise ValueError("Only PDF files are accepted.")
+    if not file_bytes:
+        raise ValueError("Uploaded file is empty.")
+
+    safe_name = Path(filename).name
+    settings.data_dir.mkdir(parents=True, exist_ok=True)
+    dest = settings.data_dir / safe_name
+    dest.write_bytes(file_bytes)
+    logger.info("Saved uploaded PDF: {}", dest)
+
+    ensure_collection(recreate=False)
+    chunks = build_chunks([dest])
+    if not chunks:
+        logger.warning("No chunks produced for uploaded file {}", safe_name)
+        return {"filename": safe_name, "chunks_indexed": 0}
+
+    count = index_chunks(chunks)
+    logger.info("Indexed {} chunks from {}", count, safe_name)
+    return {"filename": safe_name, "chunks_indexed": count}
+

src/learning.py

@@ -0,0 +1,227 @@
+"""Grounded learning features: summarization, quiz, and flashcard generation."""
+
+from __future__ import annotations
+
+import json
+
+from loguru import logger
+from pydantic import ValidationError
+
+from src.config import settings
+from src.llm import invoke_llm
+from src.rag import fetch_all_chunks, format_citations, render_prompt, retrieve
+from src.schemas import Flashcard, FlashcardSet, QuizItem, QuizSet, RetrievedChunk, Summary
+
+SUMMARY_SINGLE_TEMPLATE = "summary_single.jinja2"
+SUMMARY_MAP_TEMPLATE = "summary_map.jinja2"
+SUMMARY_REDUCE_TEMPLATE = "summary_reduce.jinja2"
+QUIZ_TEMPLATE = "quiz.jinja2"
+FLASHCARDS_TEMPLATE = "flashcards.jinja2"
+
+
+def _parse_json(text: str) -> dict | list:
+    """Parse JSON object/array from model output, allowing optional markdown code fences."""
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        cleaned = cleaned.split("\n", 1)[-1].removesuffix("```").strip()
+
+    try:
+        obj = json.loads(cleaned)
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"Invalid JSON from model output: {cleaned}") from e
+
+    if not isinstance(obj, (dict, list)):
+        raise RuntimeError(f"Expected JSON object or array, got {type(obj).__name__}.")
+
+    return obj
+
+
+def _resolve_target(
+    document: str | None,
+    query: str | None,
+    filters: dict[str, object] | None,
+    k: int | None,
+    retrieval_k: int,
+) -> tuple[list[RetrievedChunk], str, str | None]:
+    """Resolve input options into (chunks, scope, target_label)."""
+    effective_filters: dict[str, object] = dict(filters or {})
+    if document:
+        effective_filters["filename"] = document
+
+    if query:
+        chunks = retrieve(query, k=k or retrieval_k, filters=effective_filters)
+        target: str | None = query
+        scope = "query"
+    elif effective_filters:
+        chunks = fetch_all_chunks(filters=effective_filters)
+        target = ", ".join(f"{fk}={fv}" for fk, fv in effective_filters.items())
+        scope = "document" if document else "filter"
+    else:
+        chunks = fetch_all_chunks(filters=None)
+        target = None
+        scope = "corpus"
+
+    return chunks, scope, target
+
+
+def _validate_items(
+    payload: object,
+    key: str,
+    model_class: type,
+    dedup_field: str,
+    label: str,
+    valid_markers: set[str],
+) -> list:
+    if not isinstance(payload, dict):
+        raise RuntimeError(f"Expected JSON object for {label}.")
+    raw_items = payload.get(key)
+    if not isinstance(raw_items, list):
+        raise RuntimeError(f"Expected '{key}' to be a list for {label}.")
+
+    items: list = []
+    seen: set[str] = set()
+    for raw in raw_items:
+        if not isinstance(raw, dict):
+            continue
+        try:
+            item = model_class.model_validate(raw)
+        except ValidationError as e:
+            logger.warning("Dropping invalid {}: {}", label, e)
+            continue
+        norm = str(getattr(item, dedup_field, "")).strip().lower()
+        if not norm or norm in seen:
+            continue
+        seen.add(norm)
+        markers = [m for m in item.source_markers if m in valid_markers]
+        items.append(item.model_copy(update={"source_markers": markers}))
+
+    if not items:
+        raise RuntimeError(f"No valid {label} produced.")
+    return items
+
+
+def _validate_summary_payload(payload: object) -> tuple[str, list[str]]:
+    if not isinstance(payload, dict):
+        raise RuntimeError("Expected a JSON object for summary.")
+    summary = payload.get("summary")
+    key_points = payload.get("key_points", [])
+    if not isinstance(summary, str):
+        raise RuntimeError("Summary payload missing 'summary' string.")
+    if not isinstance(key_points, list) or not all(isinstance(x, str) for x in key_points):
+        raise RuntimeError("Summary payload 'key_points' must be a list of strings.")
+    return summary.strip(), [kp.strip() for kp in key_points if kp.strip()]
+
+
+def summarize(
+    document: str | None = None,
+    query: str | None = None,
+    filters: dict[str, object] | None = None,
+    k: int | None = None,
+) -> Summary:
+    """Grounded summary; uses map-reduce when chunk count exceeds batch size."""
+    chunks, scope, target = _resolve_target(
+        document=document,
+        query=query,
+        filters=filters,
+        k=k,
+        retrieval_k=settings.summarize_retrieval_k,
+    )
+
+    if not chunks:
+        raise RuntimeError("No chunks available for summarization.")
+
+    batch_size = settings.summarize_batch_size
+    if len(chunks) <= batch_size:
+        prompt = render_prompt(SUMMARY_SINGLE_TEMPLATE, chunks=chunks)
+        payload = _parse_json(invoke_llm(prompt))
+        summary_text, key_points = _validate_summary_payload(payload)
+    else:
+        n_batches = (len(chunks) + batch_size - 1) // batch_size
+        partials: list[dict] = []
+
+        for batch_index, start in enumerate(range(0, len(chunks), batch_size), start=1):
+            logger.info("Summarizing batch {}/{}", batch_index, n_batches)
+            batch = chunks[start : start + batch_size]
+            prompt = render_prompt(SUMMARY_MAP_TEMPLATE, chunks=batch)
+            payload = _parse_json(invoke_llm(prompt))
+            summary_text, key_points = _validate_summary_payload(payload)
+            partials.append({"summary": summary_text, "key_points": key_points})
+
+        reduce_prompt = render_prompt(SUMMARY_REDUCE_TEMPLATE, partials=partials)
+        payload = _parse_json(invoke_llm(reduce_prompt))
+        summary_text, key_points = _validate_summary_payload(payload)
+
+    return Summary(
+        scope=scope,
+        target=target,
+        summary=summary_text,
+        key_points=key_points,
+        citations=format_citations(chunks),
+    )
+
+
+def generate_quiz(
+    document: str | None = None,
+    query: str | None = None,
+    filters: dict[str, object] | None = None,
+    count: int | None = None,
+    k: int | None = None,
+) -> QuizSet:
+    """Grounded multiple-choice quiz; raises RuntimeError if output is unparseable."""
+    chunks, scope, target = _resolve_target(
+        document=document,
+        query=query,
+        filters=filters,
+        k=k,
+        retrieval_k=settings.generation_retrieval_k,
+    )
+    if not chunks:
+        raise RuntimeError("No chunks available for quiz generation.")
+
+    n = count or settings.quiz_default_count
+    valid_markers = {f"S{i}" for i in range(1, len(chunks) + 1)}
+
+    prompt = render_prompt(QUIZ_TEMPLATE, chunks=chunks, count=n)
+    payload = _parse_json(invoke_llm(prompt))
+    items = _validate_items(payload, "items", QuizItem, "question", "quiz items", valid_markers)
+
+    return QuizSet(
+        scope=scope,
+        target=target,
+        items=items,
+        citations=format_citations(chunks),
+    )
+
+
+def generate_flashcards(
+    document: str | None = None,
+    query: str | None = None,
+    filters: dict[str, object] | None = None,
+    count: int | None = None,
+    k: int | None = None,
+) -> FlashcardSet:
+    """Grounded flashcard set for spaced repetition; raises RuntimeError if output is unparseable."""
+    chunks, scope, target = _resolve_target(
+        document=document,
+        query=query,
+        filters=filters,
+        k=k,
+        retrieval_k=settings.generation_retrieval_k,
+    )
+    if not chunks:
+        raise RuntimeError("No chunks available for flashcard generation.")
+
+    n = count or settings.flashcards_default_count
+    valid_markers = {f"S{i}" for i in range(1, len(chunks) + 1)}
+
+    prompt = render_prompt(FLASHCARDS_TEMPLATE, chunks=chunks, count=n)
+    payload = _parse_json(invoke_llm(prompt))
+    cards = _validate_items(payload, "cards", Flashcard, "front", "flashcards", valid_markers)
+
+    return FlashcardSet(
+        scope=scope,
+        target=target,
+        cards=cards,
+        citations=format_citations(chunks),
+    )
+

src/llm.py

@@ -0,0 +1,42 @@
+"""LLM invocation through Gemini API (google-genai)."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+from google import genai
+from google.genai import types
+
+from src.config import settings
+
+
+_runtime_api_key: ContextVar[str | None] = ContextVar("runtime_gemini_api_key", default=None)
+
+def set_runtime_gemini_api_key(api_key: str | None) -> None:
+    _runtime_api_key.set(api_key.strip() if isinstance(api_key, str) else None)
+
+def invoke_llm(prompt: str) -> str:
+    """Invoke the configured chat model and return plain text.
+
+    Args: prompt.
+    Returns: assistant text content.
+    Raises: RuntimeError if the API key is missing or response is empty.
+    """
+    api_key = _runtime_api_key.get() or settings.gemini_api_key
+    if not api_key:
+        raise RuntimeError("Missing Gemini API key. Please provide it in the UI (or set GEMINI_API_KEY).")
+
+    client = genai.Client(api_key=api_key)
+    resp = client.models.generate_content(
+        model=settings.llm_model,
+        contents=prompt,
+        config=types.GenerateContentConfig(
+            temperature=settings.llm_temperature,
+            max_output_tokens=settings.llm_max_new_tokens,
+        ),
+    )
+    text = (resp.text or "").strip()
+    if not text:
+        raise RuntimeError("Empty response from Gemini.")
+    return text
+

src/prompts/answer.jinja2

@@ -0,0 +1,22 @@
+You are a precise assistant. Answer the user's question using ONLY the context below.
+
+Rules:
+- Use only facts explicitly supported by the context. Do not invent details.
+- If the context is insufficient, reply exactly: "Tôi không có đủ thông tin trong ngữ cảnh được cung cấp để trả lời."
+- Be concise and direct.
+- Write your answer in Vietnamese.
+- Cite support inline using source markers like [S1], [S2].
+- Use only the source markers provided in the context.
+- Do not write filenames, page numbers, or chunk IDs in the answer body.
+
+Context:
+{% for c in chunks %}
+---
+[source={{ "S" ~ loop.index }}]
+{{ c.text }}
+{% endfor %}
+
+Question: {{ question }}
+
+Answer:
+

src/prompts/flashcards.jinja2

@@ -0,0 +1,35 @@
+You are generating study flashcards grounded in the provided context.
+
+Rules:
+- Generate exactly {{ count }} flashcards.
+- Fronts should ask for a concept, term, distinction, formula, process, or short explanation.
+- Backs must be concise but complete enough for revision.
+- Ground every card in the context. Do not invent facts.
+- Avoid low-value cards that only restate section headings.
+- Avoid duplicate or overly similar cards.
+- Provide at least one [S#] source marker per card when possible.
+- If the context is insufficient for {{ count }} useful cards, produce fewer rather than pad.
+- Write all fronts, backs, hints, and topic labels in Vietnamese.
+
+Output STRICTLY valid JSON and no other text, with this exact shape:
+{
+  "cards": [
+    {
+      "front": "string",
+      "back": "string",
+      "hint": "optional string or null",
+      "topic": "optional short topic label or null",
+      "source_markers": ["S1"]
+    }
+  ]
+}
+
+Context:
+{% for c in chunks %}
+---
+[source=S{{ loop.index }}] ({{ c.metadata.filename }} p.{{ c.metadata.page }})
+{{ c.text }}
+{% endfor %}
+
+Respond with ONLY the JSON object.
+

src/prompts/quiz.jinja2

@@ -0,0 +1,37 @@
+You are generating high-quality multiple-choice quiz items grounded in the provided context.
+
+Rules:
+- Generate exactly {{ count }} items.
+- Every question must be answerable from the context alone.
+- Provide exactly 4 options per question with exactly one correct answer.
+- Test understanding: concepts, distinctions, reasoning, and factual recall.
+- Avoid duplicates or near-duplicates.
+- Avoid trick questions or ambiguous wording.
+- Explanations must be concise and cite at least one [S#] marker from the context.
+- If the context is insufficient to create {{ count }} high-quality items, generate fewer. Never fabricate facts.
+- Write all questions, options, explanations, and topic labels in Vietnamese.
+
+Output STRICTLY valid JSON and no other text, with this exact shape:
+{
+  "items": [
+    {
+      "question": "string",
+      "options": ["string", "string", "string", "string"],
+      "correct_index": 0,
+      "explanation": "grounded explanation with [S1] style citations",
+      "source_markers": ["S1"],
+      "difficulty": "easy|medium|hard",
+      "topic": "short topic label"
+    }
+  ]
+}
+
+Context:
+{% for c in chunks %}
+---
+[source=S{{ loop.index }}] ({{ c.metadata.filename }} p.{{ c.metadata.page }})
+{{ c.text }}
+{% endfor %}
+
+Respond with ONLY the JSON object.
+

src/prompts/summary_map.jinja2

@@ -0,0 +1,24 @@
+You are summarizing a portion of a learning document for later synthesis.
+
+Rules:
+- Summarize only what the passages actually say.
+- Preserve concepts, definitions, processes, and reasoning.
+- Do not add outside knowledge. Do not speculate.
+- Keep it dense but readable; aim for 4-8 sentences.
+- Write the summary and key points in Vietnamese.
+
+Output STRICTLY valid JSON with this shape and no extra text:
+{
+  "summary": "dense paragraph summary",
+  "key_points": ["fact", "fact"]
+}
+
+Passages:
+{% for c in chunks %}
+---
+[source=S{{ loop.index }}] ({{ c.metadata.filename }} p.{{ c.metadata.page }})
+{{ c.text }}
+{% endfor %}
+
+Respond with ONLY the JSON object.
+

src/prompts/summary_reduce.jinja2

@@ -0,0 +1,29 @@
+You are synthesizing partial summaries of a learning document into one coherent study summary.
+
+Rules:
+- Use only information present in the partial summaries.
+- Do not add outside knowledge. Do not invent details.
+- Merge duplicated points; preserve distinctions between related concepts.
+- Write for a learner who wants to understand and remember the material.
+- Write the summary and key points in Vietnamese.
+
+Output STRICTLY valid JSON with this shape and no extra text:
+{
+  "summary": "A coherent multi-paragraph study summary.",
+  "key_points": ["concise learnable fact", "concise learnable fact"]
+}
+
+Partial summaries:
+{% for p in partials %}
+---
+Summary: {{ p.summary }}
+{% if p.key_points %}
+Key points:
+{% for kp in p.key_points %}
+- {{ kp }}
+{% endfor %}
+{% endif %}
+{% endfor %}
+
+Respond with ONLY the JSON object.
+

src/prompts/summary_single.jinja2

@@ -0,0 +1,25 @@
+You are writing a study-oriented summary grounded strictly in the provided context.
+
+Rules:
+- Use only facts explicitly supported by the context. Do not invent details.
+- Do not add outside knowledge.
+- Focus on concepts, definitions, relationships, and reasoning a learner should retain.
+- Keep the tone clear, neutral, and practical for study.
+- Write the summary and key points in Vietnamese.
+- If the context is empty or unrelated, return an empty summary and an empty list of key points.
+
+Output STRICTLY valid JSON with this shape and no extra text:
+{
+  "summary": "A coherent multi-paragraph study summary.",
+  "key_points": ["concise learnable fact", "concise learnable fact"]
+}
+
+Context:
+{% for c in chunks %}
+---
+[source=S{{ loop.index }}] ({{ c.metadata.filename }} p.{{ c.metadata.page }})
+{{ c.text }}
+{% endfor %}
+
+Respond with ONLY the JSON object.
+

src/rag.py

@@ -0,0 +1,119 @@
+"""Retrieval, prompts, citations, and grounded answers."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from src.config import settings
+from src.filters import filters_to_qdrant
+from src.llm import invoke_llm
+from src.schemas import ChunkMetadata, Citation, RagAnswer, RetrievedChunk
+from src.store import get_vector_store, scroll_all
+
+PROMPTS_DIR = Path(__file__).parent / "prompts"
+ANSWER_TEMPLATE = "answer.jinja2"
+
+
+def retrieve(
+    query: str,
+    k: int | None = None,
+    filters: dict[str, object] | None = None,
+    collection_name: str | None = None,
+) -> list[RetrievedChunk]:
+    store = get_vector_store(collection_name=collection_name)
+    hits = store.similarity_search_with_score(
+        query=query,
+        k=k or settings.top_k,
+        filter=filters_to_qdrant(filters),
+    )
+    return [
+        RetrievedChunk(
+            text=doc.page_content,
+            score=float(score),
+            metadata=ChunkMetadata(**doc.metadata),
+        )
+        for doc, score in hits
+    ]
+
+
+def fetch_all_chunks(
+    filters: dict[str, object] | None = None,
+    collection_name: str | None = None,
+) -> list[RetrievedChunk]:
+    """Scroll every chunk matching the filter, ordered by filename → page → index."""
+    name = collection_name or settings.qdrant_collection
+    results: list[RetrievedChunk] = []
+    for page in scroll_all(name, scroll_filter=filters_to_qdrant(filters)):
+        for point in page:
+            payload = point.payload or {}
+            meta = payload.get("metadata") or {}
+            text = payload.get("page_content") or ""
+            if not meta or not text:
+                continue
+            results.append(RetrievedChunk(text=text, score=0.0, metadata=ChunkMetadata(**meta)))
+    results.sort(
+        key=lambda r: (
+            r.metadata.filename,
+            r.metadata.page,
+            int(r.metadata.chunk_id.rsplit(":", 1)[-1]),
+        )
+    )
+    return results
+
+
+@lru_cache(maxsize=1)
+def _jinja_env() -> Environment:
+    return Environment(
+        loader=FileSystemLoader(str(PROMPTS_DIR)),
+        autoescape=False,
+        undefined=StrictUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def render_prompt(template_name: str, **context: object) -> str:
+    """Render an arbitrary Jinja template from the prompts directory."""
+    return _jinja_env().get_template(template_name).render(**context)
+
+
+def format_citations(chunks: list[RetrievedChunk]) -> list[Citation]:
+    return [
+        Citation(
+            source_index=i,
+            source_marker=f"S{i}",
+            filename=c.metadata.filename,
+            page=c.metadata.page,
+            section=c.metadata.section,
+            chunk_id=c.metadata.chunk_id,
+        )
+        for i, c in enumerate(chunks, start=1)
+    ]
+
+
+def answer(
+    question: str,
+    k: int | None = None,
+    filters: dict[str, object] | None = None,
+    collection_name: str | None = None,
+) -> RagAnswer:
+    chunks = retrieve(question, k=k, filters=filters, collection_name=collection_name)
+    if not chunks:
+        return RagAnswer(
+            question=question,
+            answer="Tôi không có đủ thông tin trong ngữ cảnh được cung cấp để trả lời.",
+        )
+
+    prompt = render_prompt(ANSWER_TEMPLATE, question=question, chunks=chunks)
+    text = invoke_llm(prompt)
+
+    return RagAnswer(
+        question=question,
+        answer=text.strip(),
+        citations=format_citations(chunks),
+        chunks=chunks,
+    )
+

src/schemas.py

@@ -0,0 +1,105 @@
+"""Pydantic schemas for chunks, answers, and learning outputs."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class ChunkMetadata(BaseModel):
+    """Stable metadata attached to every chunk stored in Qdrant."""
+
+    document_id: str
+    filename: str
+    source: str
+    page: int
+    chunk_id: str
+    section: str | None = None
+
+
+class RetrievedChunk(BaseModel):
+    """A retrieved chunk with its score and metadata."""
+
+    text: str
+    score: float
+    metadata: ChunkMetadata
+
+
+class Citation(BaseModel):
+    """Citation extracted from a retrieved chunk's metadata."""
+
+    source_index: int
+    source_marker: str
+    filename: str
+    page: int
+    section: str | None = None
+    chunk_id: str | None = None
+
+
+class RagAnswer(BaseModel):
+    """Final grounded answer returned to the caller."""
+
+    question: str
+    answer: str
+    citations: list[Citation] = Field(default_factory=list)
+    chunks: list[RetrievedChunk] = Field(default_factory=list)
+
+
+class Summary(BaseModel):
+    """Grounded study-oriented summary of a document or subset."""
+
+    scope: Literal["query", "document", "filter", "corpus"]
+    target: str | None = None
+    summary: str
+    key_points: list[str] = Field(default_factory=list)
+    citations: list[Citation] = Field(default_factory=list)
+
+
+class QuizItem(BaseModel):
+    """A single multiple-choice quiz item grounded in the source material."""
+
+    question: str
+    options: list[str] = Field(min_length=4, max_length=4)
+    correct_index: int
+    explanation: str
+    source_markers: list[str] = Field(default_factory=list)
+    difficulty: str | None = None
+    topic: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_correct_index(self) -> "QuizItem":
+        if not 0 <= self.correct_index < len(self.options):
+            raise ValueError(
+                f"correct_index {self.correct_index} out of range for {len(self.options)} options"
+            )
+        return self
+
+
+class QuizSet(BaseModel):
+    """A reusable set of grounded quiz items with resolved citations."""
+
+    scope: Literal["query", "document", "filter", "corpus"]
+    target: str | None = None
+    items: list[QuizItem] = Field(default_factory=list)
+    citations: list[Citation] = Field(default_factory=list)
+
+
+class Flashcard(BaseModel):
+    """A single study flashcard grounded in the source material."""
+
+    front: str
+    back: str
+    hint: str | None = None
+    topic: str | None = None
+    source_markers: list[str] = Field(default_factory=list)
+
+
+class FlashcardSet(BaseModel):
+    """A reusable set of grounded flashcards with resolved citations."""
+
+    scope: Literal["query", "document", "filter", "corpus"]
+    target: str | None = None
+    cards: list[Flashcard] = Field(default_factory=list)
+    citations: list[Citation] = Field(default_factory=list)
+

src/store.py

@@ -0,0 +1,152 @@
+"""Embeddings, Qdrant client, collection setup, and vector store."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from functools import lru_cache
+
+from langchain_qdrant import QdrantVectorStore
+from qdrant_client import QdrantClient
+from qdrant_client.http import models as qmodels
+
+from src.config import settings
+from src.embeddings import get_embeddings
+
+_SCROLL_PAGE_SIZE = 256
+
+INDEXED_PAYLOAD_FIELDS = {
+    "metadata.document_id": qmodels.PayloadSchemaType.KEYWORD,
+    "metadata.filename": qmodels.PayloadSchemaType.KEYWORD,
+    "metadata.page": qmodels.PayloadSchemaType.INTEGER,
+}
+
+
+def close_client() -> None:
+    if get_client.cache_info().currsize == 0:
+        return
+    client = get_client()
+    client.close()
+    get_client.cache_clear()
+
+
+@lru_cache(maxsize=1)
+def get_client() -> QdrantClient:
+    """Return a cached local Qdrant client backed by on-disk storage."""
+    settings.storage_dir.mkdir(parents=True, exist_ok=True)
+    return QdrantClient(path=str(settings.storage_dir))
+
+
+def ensure_collection(recreate: bool = False, collection_name: str | None = None) -> None:
+    """Create the collection and payload indexes if they do not exist."""
+    client = get_client()
+    name = collection_name or settings.qdrant_collection
+
+    exists = client.collection_exists(name)
+    if exists and recreate:
+        client.delete_collection(name)
+        exists = False
+
+    if not exists:
+        dim = len(get_embeddings().embed_query("dimension probe"))
+        client.create_collection(
+            collection_name=name,
+            vectors_config=qmodels.VectorParams(
+                size=dim,
+                distance=qmodels.Distance.COSINE,
+            ),
+        )
+
+    payload_schema = client.get_collection(name).payload_schema or {}
+
+    for field_name, field_schema in INDEXED_PAYLOAD_FIELDS.items():
+        existing = payload_schema.get(field_name)
+        if existing is None:
+            client.create_payload_index(
+                collection_name=name,
+                field_name=field_name,
+                field_schema=field_schema,
+            )
+            continue
+
+        existing_schema = getattr(existing, "data_type", None)
+        if existing_schema != field_schema:
+            raise ValueError(
+                f"Payload index for '{field_name}' has schema "
+                f"{existing_schema!r}, expected {field_schema!r}."
+            )
+
+
+def scroll_all(
+    collection_name: str,
+    scroll_filter: qmodels.Filter | None = None,
+    with_payload: bool | list[str] = True,
+    limit: int = _SCROLL_PAGE_SIZE,
+) -> Iterator[list]:
+    """Yield pages of Qdrant points (no vectors) until the collection is exhausted."""
+    client = get_client()
+    offset = None
+    while True:
+        try:
+            points, next_offset = client.scroll(
+                collection_name=collection_name,
+                scroll_filter=scroll_filter,
+                limit=limit,
+                offset=offset,
+                with_payload=with_payload,
+                with_vectors=False,
+            )
+        except ValueError as exc:
+            # Local Qdrant raises ValueError when collection doesn't exist yet.
+            if "not found" in str(exc).lower():
+                return
+            raise
+        yield points
+        if next_offset is None:
+            break
+        offset = next_offset
+
+
+def get_vector_store(collection_name: str | None = None) -> QdrantVectorStore:
+    return QdrantVectorStore(
+        client=get_client(),
+        collection_name=collection_name or settings.qdrant_collection,
+        embedding=get_embeddings(),
+    )
+
+
+def list_documents() -> list[dict[str, object]]:
+    """List indexed documents with filename, document_id, pages, and chunk counts.
+
+    Returns one entry per filename matching the API `DocumentInfo` shape.
+    """
+    pages_map: dict[str, set[int]] = {}
+    doc_id_map: dict[str, str] = {}
+    count_map: dict[str, int] = {}
+
+    for batch in scroll_all(settings.qdrant_collection, with_payload=["metadata"]):
+        for point in batch:
+            meta = (point.payload or {}).get("metadata") or {}
+            filename = meta.get("filename")
+            document_id = meta.get("document_id")
+            pg = meta.get("page")
+            if not filename or not document_id or not isinstance(pg, int):
+                continue
+            fn = str(filename)
+            doc_id_map.setdefault(fn, str(document_id))
+            pages_map.setdefault(fn, set()).add(pg)
+            count_map[fn] = count_map.get(fn, 0) + 1
+
+    return sorted(
+        [
+            {
+                "filename": fn,
+                "document_id": doc_id_map[fn],
+                "pages": sorted(pages_map[fn]),
+                "page_count": len(pages_map[fn]),
+                "chunk_count": count_map[fn],
+            }
+            for fn in doc_id_map
+        ],
+        key=lambda d: str(d["filename"]),
+    )
+

static/style.css

@@ -0,0 +1,567 @@
+/* ==========================================================
+   RAG Learning System — Design Tokens
+   ========================================================== */
+:root, #gradio-app {
+  --c-bg:           #eef1fb;
+  --c-bg-2:         #e4e9f7;
+  --c-surface:      #ffffff;
+  --c-surface-2:    #f2f5ff;
+  --c-surface-tint: rgba(255, 255, 255, 0.72);
+
+  --c-primary:      #3d5af1;
+  --c-primary-dk:   #2945d4;
+  --c-primary-pale: #dde4fd;
+
+  --c-accent:       #6c3de0;
+
+  --c-text:         #181c2e;
+  --c-text-2:       #3d4460;
+  --c-text-muted:   #6370a0;
+
+  /* Border needs to be darker than background for legibility */
+  --c-border:       #b6c0e6;
+  --c-border-strong:#9faee0;
+
+  --c-note-bg:      #fffbeb;
+  --c-note-bd:      #f5c842;
+  --c-note-txt:     #7a5200;
+
+  --c-status-bg:    #f0f4ff;
+
+  --r-lg: 16px;
+  --r-md: 12px;
+  --r-sm:  8px;
+  --r-xs:  6px;
+
+  --shadow-card: 0 3px 16px rgba(40,55,130,.12), 0 1px 5px rgba(40,55,130,.07);
+  --shadow-panel: 0 6px 24px rgba(40,55,130,.10), 0 2px 8px rgba(40,55,130,.06);
+  --shadow-btn:  0 4px 14px rgba(61,90,241,.30);
+  --shadow-foc:  0 0 0 3px rgba(61,90,241,.20);
+
+  --app-max-width: 1440px;
+}
+
+/* ==========================================================
+   Gradio variable bridge — all blocks transparent by default
+   ========================================================== */
+#gradio-app {
+  --background-fill-primary:   var(--c-bg);
+  --background-fill-secondary: var(--c-bg-2);
+  --block-background-fill:     transparent;
+  --block-border-color:        transparent;
+  --block-border-width:        0px;
+  --input-background-fill:     var(--c-surface);
+}
+
+/* ==========================================================
+   Page shell
+   ========================================================== */
+html, body {
+  margin: 0; padding: 0;
+  background: linear-gradient(155deg, var(--c-bg) 0%, var(--c-bg-2) 100%) !important;
+  color: var(--c-text);
+  min-height: 100vh;
+}
+
+/* strip only safe wrappers, NOT .column / .row (Gradio needs those for flex) */
+#gradio-app,
+.gradio-container,
+.main,
+.contain,
+.html-container {
+  background: transparent !important;
+}
+
+.gradio-container {
+  max-width: var(--app-max-width) !important;
+  margin: 0 auto !important;
+  padding: 12px 18px 10px !important;
+}
+
+/* ==========================================================
+   Header
+   ========================================================== */
+.header-row {
+  gap: 14px !important;
+  padding: 4px 0 10px !important;
+  align-items: center !important;
+  background: transparent !important;
+}
+
+.header-row img {
+  height: 96px;
+  width: auto;
+  object-fit: contain;
+}
+
+.header-meta {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  min-width: 0;
+}
+
+.header-title {
+  margin: 0;
+  font-size: 1.8rem;
+  line-height: 1.15;
+  font-weight: 800;
+  color: var(--c-text);
+  letter-spacing: -0.025em;
+}
+
+.header-sub {
+  margin: 5px 0 0;
+  font-size: 0.95rem;
+  color: var(--c-text-muted);
+  font-weight: 500;
+}
+
+/* ==========================================================
+   Info card (warning note)
+   ========================================================== */
+.info-card {
+  background: var(--c-note-bg) !important;
+  border: 1px solid var(--c-note-bd) !important;
+  border-left: 4px solid var(--c-note-bd) !important;
+  border-radius: var(--r-md);
+  padding: 10px 14px;
+  margin: 0 0 10px;
+}
+
+.info-card-title,
+.info-card-list,
+.info-card-list li { color: var(--c-note-txt) !important; }
+
+.info-card-title { margin-bottom: 6px; font-size: 0.95rem; font-weight: 700; }
+
+.info-card-list {
+  margin: 0;
+  padding-left: 18px;
+  font-size: 0.90rem;
+  line-height: 1.65;
+}
+
+.info-card-list li + li { margin-top: 3px; }
+
+/* ==========================================================
+   2-Column main layout — EXPLICIT flex, do not rely solely on Gradio
+   ========================================================== */
+.main-layout {
+  display: flex !important;
+  flex-direction: row !important;
+  flex-wrap: wrap !important;
+  gap: 12px !important;
+  align-items: flex-start !important;
+  background: transparent !important;
+}
+
+.control-stack {
+  display: flex !important;
+  flex-direction: column !important;
+  gap: 10px !important;
+  flex: 4 1 320px !important;
+  min-width: 300px !important;
+  background: var(--c-surface-tint) !important;
+  border: 1.5px solid var(--c-border-strong) !important;
+  border-radius: var(--r-lg) !important;
+  box-shadow: var(--shadow-panel) !important;
+  padding: 14px 16px !important;
+}
+
+.preview-col {
+  display: flex !important;
+  flex-direction: column !important;
+  gap: 10px !important;
+  flex: 7 1 480px !important;
+  min-width: 420px !important;
+  background: var(--c-surface-tint) !important;
+  border: 1.5px solid var(--c-border-strong) !important;
+  border-radius: var(--r-lg) !important;
+  box-shadow: var(--shadow-panel) !important;
+  padding: 14px 16px !important;
+}
+
+/* ==========================================================
+   Cards (control-card)
+   — These are gr.Group, which Gradio renders as .block.gr-group
+   — We give them explicit white surface + shadow
+   ========================================================== */
+.control-card {
+  background: var(--c-surface) !important;
+  border: 1.5px solid var(--c-border-strong) !important;
+  border-radius: var(--r-lg) !important;
+  box-shadow: var(--shadow-card) !important;
+  padding: 14px 16px !important;
+}
+
+/* accent top stripe */
+.control-card { border-top: 3px solid var(--c-primary) !important; }
+
+/* strip nested .block inside cards — theme transparent already handles most,
+   but belt-and-suspenders for sub-blocks that may carry inline styles */
+.control-card .block {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  padding: 0 !important;
+}
+
+/* ==========================================================
+   Typography
+   ========================================================== */
+label, .gr-label, .block-title {
+  color: var(--c-text-2) !important;
+  font-size: 0.93rem !important;
+  font-weight: 600 !important;
+}
+
+.help-markdown p,
+.help-markdown li,
+.doc-summary,
+.doc-summary p,
+.doc-summary li {
+  font-size: 0.91rem;
+  line-height: 1.65;
+  color: var(--c-text-2) !important;
+}
+
+/* standalone markdown outside cards (doc_list_md etc.) */
+.prose p,
+.prose li,
+.prose h1, .prose h2, .prose h3 {
+  color: var(--c-text) !important;
+}
+
+/* ==========================================================
+   Inputs & textareas
+   ========================================================== */
+textarea, input:not([type="range"]):not([type="checkbox"]) {
+  background: var(--c-surface) !important;
+  color: var(--c-text) !important;
+  font-weight: 500 !important;
+  border: 1.5px solid var(--c-border) !important;
+  border-radius: var(--r-sm) !important;
+  box-shadow: none !important;
+  transition: border-color 0.15s, box-shadow 0.15s !important;
+}
+
+select {
+  background: var(--c-surface) !important;
+  color: var(--c-text) !important;
+  font-weight: 600 !important;
+  border: 1.5px solid var(--c-border) !important;
+  border-radius: var(--r-sm) !important;
+  box-shadow: none !important;
+}
+
+select:focus {
+  border-color: var(--c-primary) !important;
+  box-shadow: var(--shadow-foc) !important;
+  outline: none !important;
+}
+
+textarea:focus, input:focus {
+  border-color: var(--c-primary) !important;
+  box-shadow: var(--shadow-foc) !important;
+  outline: none !important;
+}
+
+::placeholder { color: var(--c-text-muted) !important; opacity: 1 !important; }
+
+/* ==========================================================
+   Gradio form wrappers — remove default gray panels
+   ========================================================== */
+/* Many components render with fieldset/panel backgrounds that ignore theme vars */
+.gradio-container fieldset,
+.gradio-container .fieldset,
+.gradio-container .panel,
+.gradio-container .gr-panel,
+.gradio-container .form,
+.gradio-container .gr-form,
+.gradio-container .wrap {
+  background: transparent !important;
+}
+
+/* CheckboxGroup / RadioGroup option panels */
+.gradio-container fieldset {
+  border: 1.5px solid var(--c-border-strong) !important;
+  border-radius: var(--r-md) !important;
+  padding: 12px 12px 10px !important;
+}
+
+.gradio-container fieldset legend {
+  color: var(--c-text-2) !important;
+  font-weight: 700 !important;
+  padding: 0 8px !important;
+}
+
+/* Make option rows readable and consistent */
+.gradio-container input[type="checkbox"] {
+  accent-color: var(--c-primary);
+}
+
+/* Dropdown wrapper surfaces */
+.gradio-container .gr-dropdown,
+.gradio-container .gr-checkboxgroup,
+.gradio-container .gr-radiogroup,
+.gradio-container .gr-slider,
+.gradio-container .gr-text-input,
+.gradio-container .gr-textbox,
+.gradio-container .gr-code {
+  background: transparent !important;
+}
+
+/* Tab content area sometimes renders as a gray block */
+.tabs,
+.tabs .tabitem,
+.tabs .tabitem > .block,
+.tabs .tabitem > .wrap,
+.tabs .tabitem > .panel {
+  background: transparent !important;
+}
+
+/* ==========================================================
+   Slider
+   ========================================================== */
+input[type="range"] {
+  border: none !important;
+  box-shadow: none !important;
+  accent-color: var(--c-primary);
+}
+
+/* ==========================================================
+   Primary button (.gen-btn)
+   ========================================================== */
+.gen-btn {
+  width: 100% !important;
+  height: 46px !important;
+  font-size: 15px !important;
+  font-weight: 700 !important;
+  border-radius: var(--r-md) !important;
+  border: none !important;
+  background: linear-gradient(135deg, #5771f5 0%, var(--c-primary) 55%, var(--c-primary-dk) 100%) !important;
+  color: #fff !important;
+  cursor: pointer !important;
+  box-shadow: var(--shadow-btn) !important;
+  transition: opacity 0.14s, box-shadow 0.14s, transform 0.10s !important;
+}
+
+.gen-btn:hover {
+  opacity: 0.88 !important;
+  box-shadow: 0 6px 22px rgba(61,90,241,.38) !important;
+  transform: translateY(-1px) !important;
+}
+
+.gen-btn:active {
+  transform: translateY(0) !important;
+  opacity: 1 !important;
+}
+
+/* Secondary buttons */
+button:not(.gen-btn) {
+  border-radius: var(--r-sm) !important;
+  border: 1.5px solid var(--c-border) !important;
+  background: var(--c-surface-2) !important;
+  color: var(--c-text-2) !important;
+  font-weight: 600 !important;
+  font-size: 0.92rem !important;
+  transition: background 0.14s, border-color 0.14s, color 0.14s !important;
+}
+
+button:not(.gen-btn):hover {
+  background: var(--c-primary-pale) !important;
+  border-color: var(--c-primary) !important;
+  color: var(--c-primary-dk) !important;
+}
+
+/* tab nav buttons must override secondary button rules */
+.tabs > .tab-nav button,
+.tabs > .tab-nav button:not(.gen-btn) {
+  border: none !important;
+  background: transparent !important;
+  border-bottom: 2px solid transparent !important;
+  border-radius: var(--r-xs) var(--r-xs) 0 0 !important;
+  color: var(--c-text-muted) !important;
+  font-weight: 600 !important;
+  font-size: 0.93rem !important;
+  padding: 9px 16px !important;
+  margin-bottom: -2px !important;
+  box-shadow: none !important;
+  transition: color 0.14s, border-color 0.14s, background 0.14s !important;
+}
+
+.tabs > .tab-nav button.selected,
+.tabs > .tab-nav button[aria-selected="true"] {
+  color: var(--c-primary) !important;
+  border-bottom-color: var(--c-primary) !important;
+  background: var(--c-primary-pale) !important;
+}
+
+.tabs > .tab-nav button:not(.selected):not([aria-selected="true"]):hover {
+  color: var(--c-text-2) !important;
+  background: var(--c-surface-2) !important;
+}
+
+/* ==========================================================
+   Status bar
+   ========================================================== */
+.status-bar {
+  background: var(--c-status-bg) !important;
+  border: 1.5px solid var(--c-border) !important;
+  border-left: 3px solid var(--c-primary) !important;
+  border-radius: var(--r-sm) !important;
+  padding: 9px 12px !important;
+  font-size: 0.90rem !important;
+  line-height: 1.5 !important;
+  color: var(--c-text-2) !important;
+}
+
+/* ==========================================================
+   Accordion
+   ========================================================== */
+.gradio-accordion,
+.gradio-accordion > div,
+.gradio-accordion details {
+  background: var(--c-surface-2) !important;
+  border: 1.5px solid var(--c-border) !important;
+  border-radius: var(--r-md) !important;
+  box-shadow: none !important;
+  overflow: hidden !important;
+}
+
+.gradio-accordion summary,
+.gradio-accordion button {
+  background: var(--c-surface-2) !important;
+  color: var(--c-text-2) !important;
+  font-weight: 700 !important;
+  font-size: 0.93rem !important;
+  border: none !important;
+  box-shadow: none !important;
+  padding: 10px 14px !important;
+  transition: background 0.14s !important;
+}
+
+.gradio-accordion summary:hover,
+.gradio-accordion button:not(.gen-btn):hover {
+  background: var(--c-primary-pale) !important;
+  border-color: transparent !important;
+}
+
+/* ==========================================================
+   Preview header
+   ========================================================== */
+.preview-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+  margin: 0 0 10px;
+  padding-bottom: 10px;
+  border-bottom: 1.5px solid var(--c-border);
+}
+
+.preview-title {
+  margin: 0;
+  font-size: 1.05rem;
+  font-weight: 700;
+  color: var(--c-text) !important;
+}
+
+.preview-sub {
+  margin: 3px 0 0;
+  font-size: 0.86rem;
+  color: var(--c-text-muted) !important;
+}
+
+/* ==========================================================
+   Result markdown
+   ========================================================== */
+.result-markdown {
+  background: var(--c-surface) !important;
+  border: 1.5px solid var(--c-border) !important;
+  border-radius: var(--r-md) !important;
+  padding: 14px 16px !important;
+  min-height: 60px;
+  box-shadow: none !important;
+}
+
+.result-markdown h1,
+.result-markdown h2,
+.result-markdown h3 { color: var(--c-primary-dk) !important; }
+
+.result-markdown p,
+.result-markdown li,
+.result-markdown strong { color: var(--c-text) !important; }
+
+.result-markdown a { color: var(--c-primary) !important; }
+
+.result-markdown code {
+  background: var(--c-surface-2) !important;
+  color: var(--c-accent) !important;
+  border-radius: 4px !important;
+  padding: 1px 5px !important;
+  font-size: 0.87em !important;
+}
+
+.result-markdown pre {
+  background: var(--c-surface-2) !important;
+  border-radius: var(--r-md) !important;
+}
+
+/* ==========================================================
+   Tabs nav bar
+   ========================================================== */
+.tabs {
+  background: var(--c-surface-tint) !important;
+  border: 1.5px solid var(--c-border-strong) !important;
+  border-radius: var(--r-lg) !important;
+  box-shadow: var(--shadow-panel) !important;
+  padding: 10px 12px 12px !important;
+}
+
+.tabs > .tab-nav {
+  border-bottom: 2px solid var(--c-border) !important;
+  gap: 2px !important;
+  padding: 0 2px !important;
+  background: transparent !important;
+}
+
+/* ==========================================================
+   Footer
+   ========================================================== */
+.footer-text {
+  text-align: center;
+  font-size: 0.88rem;
+  color: var(--c-text-muted) !important;
+  padding: 10px 0 6px;
+  margin-top: 14px;
+  border-top: 1px solid var(--c-border);
+}
+
+.footer-text a {
+  color: var(--c-primary) !important;
+  text-decoration: none;
+  font-weight: 600;
+}
+
+.footer-text a:hover { text-decoration: underline; }
+
+/* ==========================================================
+   Responsive
+   ========================================================== */
+@media (max-width: 860px) {
+  .main-layout { flex-direction: column !important; }
+  .control-stack, .preview-col {
+    flex: 1 1 100% !important;
+    min-width: 0 !important;
+    padding: 12px 12px !important;
+  }
+  .gradio-container { padding: 6px 8px !important; }
+  .header-row { gap: 8px !important; padding: 2px 0 6px !important; }
+  .header-row img { height: 56px; }
+  .header-title { font-size: 1.35rem; }
+  .header-sub { font-size: 0.87rem; }
+  .control-card { padding: 10px 12px !important; }
+  .tabs { padding: 8px 8px 10px !important; }
+}