Download app.py from pdmdp/finalign: direct link, hf CLI and curl.
- Browser
- Download file 16.9 kB
-
https://huggingface.co/spaces/pdmdp/finalign/resolve/main/app.py
- Command line
-
hf download hf://spaces/pdmdp/finalign/app.py
-
curl -L -o app.py https://huggingface.co/spaces/pdmdp/finalign/resolve/main/app.py
16.9 kB
| """Gradio entry point. Models are loaded before ZeroGPU allocates a worker.""" | |
| # ruff: noqa: I001 | |
| import json | |
| import logging | |
| import os | |
| import time | |
| from pathlib import Path | |
| # Install ZeroGPU's CUDA emulation before libraries that may import torch. | |
| import spaces | |
| import gradio as gr | |
| from finalign.core import Options, ranked, validate_query | |
| from finalign.index import Index, LexicalSearch, unpack | |
| from finalign.neural import NeuralSearch | |
| from finalign.preparation import finish_index, prepare_batch | |
| from finalign.presentation import ( | |
| CSS, | |
| board_html, | |
| details_html, | |
| esc, | |
| notice_html, | |
| summary_html, | |
| ) | |
| ROOT = Path(__file__).resolve().parent | |
| index_dir = os.environ.get("FINALIGN_INDEX_DIR") | |
| if index_dir is None: | |
| archive = ROOT / "data" / "fiqa-index.zip" | |
| if not archive.exists(): | |
| archive = ROOT / "data" / "fiqa-corpus.zip" | |
| if not archive.exists(): | |
| raise RuntimeError("Upload data/fiqa-corpus.zip alongside the application files. See DEPLOY.md.") | |
| index_dir = unpack(archive, ROOT / ".index") | |
| INDEX = Index(index_dir) | |
| LEXICAL = LexicalSearch(INDEX) | |
| DEVICE = os.environ.get("FINALIGN_DEVICE", "cuda" if os.environ.get("SPACE_ID") else "cpu") | |
| ENCODER_ONLY = os.environ.get("FINALIGN_ENCODER_ONLY", "0") == "1" | |
| NEURAL = NeuralSearch(INDEX, device=DEVICE, encoder_only=ENCODER_ONLY) | |
| def build_passages(profile: gr.OAuthProfile | None): | |
| owner = os.environ.get("SPACE_ID", "pdmdp/finalign").split("/")[0] | |
| if os.environ.get("SPACE_ID") and (profile is None or profile.username != owner): | |
| raise gr.Error("Sign in as the Space owner to prepare the index.") | |
| return prepare_batch(INDEX, NEURAL.encoder, device=DEVICE) | |
| def complete_preparation(progress): | |
| if not progress["done"]: | |
| message = (f"**{progress['completed']:,} / {progress['total']:,} passages prepared.** " | |
| "Click Prepare / continue index again. Progress is saved between calls. " | |
| "If the free GPU quota is exhausted, resume when it resets; no paid hardware is needed.") | |
| return message, gr.update(), gr.update(visible=False), gr.update() | |
| archive = finish_index(INDEX, ROOT / "data" / "fiqa-index.zip") | |
| return (("**The index is ready.** Download fiqa-index.zip below and upload it to the Space鈥檚 " | |
| "data folder to preserve it across rebuilds. You can now use the search interface."), | |
| gr.update(value=archive, visible=True), gr.update(visible=True), gr.update(visible=False)) | |
| def refresh_page(): | |
| INDEX.refresh_dense() | |
| archive = ROOT / "data" / "fiqa-index.zip" | |
| if INDEX.ready: | |
| return (("**The index is ready.** Save the completed ZIP in the Space鈥檚 data folder if it " | |
| "has not been uploaded yet."), | |
| gr.update(value=str(archive) if archive.exists() else None, visible=archive.exists()), | |
| gr.update(visible=True), gr.update(visible=False)) | |
| progress_path = INDEX.path / "indexing-progress.json" | |
| count = json.loads(progress_path.read_text())["completed"] if progress_path.exists() else 0 | |
| return ((f"**{count:,} / {len(INDEX.passage_ids):,} passages prepared.** " | |
| "Sign in as the Space owner and prepare the next batch."), | |
| gr.update(visible=False), gr.update(visible=False), gr.update(visible=True)) | |
| def theme(): | |
| """The Space's original palette (slate and blue), with contrast raised to AA in both modes.""" | |
| return gr.themes.Base(primary_hue="blue", neutral_hue="slate").set( | |
| body_text_color_subdued="*neutral_600", body_text_color_subdued_dark="*neutral_400", | |
| button_primary_background_fill="*primary_600", button_primary_background_fill_dark="*primary_600", | |
| button_primary_background_fill_hover="*primary_700", button_primary_background_fill_hover_dark="*primary_700", | |
| button_primary_text_color="white", button_primary_text_color_dark="white", | |
| button_secondary_background_fill="transparent", button_secondary_background_fill_dark="transparent", | |
| button_secondary_background_fill_hover="transparent", button_secondary_background_fill_hover_dark="transparent", | |
| checkbox_background_color_selected="*primary_600", checkbox_background_color_selected_dark="*primary_500", | |
| checkbox_border_color_selected="*primary_600", checkbox_border_color_selected_dark="*primary_500") | |
| def gpu_failure(error): | |
| """Turn a ZeroGPU or model failure into an inline notice; BM25 results stay visible.""" | |
| message = str(getattr(error, "message", "") or error).strip()[:300] | |
| lowered = message.lower() | |
| if any(word in lowered for word in ("zerogpu", "quota", "exceeded", "runs limit")): | |
| return ("quota", "GPU quota reached", | |
| "The BM25 ranking is complete. FinAlign needs a ZeroGPU slot, and the free allowance " | |
| "for this visitor is used up. Signed-in Hugging Face users receive a larger daily " | |
| f"allowance; otherwise, try again after it resets.<small>{esc(message)}</small>") | |
| return ("error", "FinAlign could not finish this search", | |
| "The BM25 ranking is complete. Try again in a moment; the Space logs contain details." | |
| + (f"<small>{esc(message)}</small>" if message else "")) | |
| def prepare(query, keywords, hyde, lexical, rerank): | |
| started = time.perf_counter() | |
| skip = gr.update() | |
| INDEX.refresh_dense() | |
| if not INDEX.ready: | |
| return (None, notice_html("error", "The search index is not ready yet.", | |
| "The Space owner is still preparing the passage embeddings."), skip, skip, skip) | |
| try: | |
| query = validate_query(query) | |
| except ValueError as error: | |
| return (None, notice_html("error", esc(error)), skip, skip, skip) | |
| scores, elapsed = LEXICAL.search(query) | |
| options = Options(keywords, hyde, lexical, rerank) | |
| known = INDEX.known_query(query) | |
| state = {"query": query, "lexical": scores, "lexical_ms": elapsed, "options": options.to_dict(), | |
| "started": started} | |
| ranking = ranked(scores) | |
| return (state, "", | |
| summary_html(query, known, ranking, state="waiting", lexical_ms=elapsed), | |
| board_html(INDEX, query, ranking, known=known, options=options.to_dict(), state="waiting", | |
| lexical_ms=elapsed), | |
| details_html()) | |
| def neural_search(state): | |
| return NEURAL.search(state["query"], state["lexical"], state["options"]) | |
| def search(state): | |
| if not state: | |
| return (gr.update(),) * 3 | |
| query, options = state["query"], state["options"] | |
| known = INDEX.known_query(query) | |
| lexical = ranked(state["lexical"]) | |
| try: | |
| result = neural_search(state) | |
| except Exception as error: # Shown inline instead of a toast and per-component error badges. | |
| logging.exception("FinAlign search failed") | |
| return (summary_html(query, known, lexical, state="failed", lexical_ms=state["lexical_ms"]), | |
| board_html(INDEX, query, lexical, known=known, options=options, state="failed", | |
| lexical_ms=state["lexical_ms"], notice=gpu_failure(error)), | |
| gr.update()) | |
| neural = result["ranking"] | |
| timings = {"BM25": state["lexical_ms"], **result["timings_ms"]} | |
| elapsed = sum(timings.values()) / 1000 | |
| server_elapsed = time.perf_counter() - state["started"] | |
| return (summary_html(query, known, lexical, neural, state="done", lexical_ms=state["lexical_ms"], | |
| timings=result["timings_ms"], server_s=server_elapsed), | |
| board_html(INDEX, query, lexical, neural, result["passages"], known, options, state="done", | |
| lexical_ms=state["lexical_ms"], neural_ms=sum(result["timings_ms"].values())), | |
| details_html(timings, result["variants"], elapsed, server_elapsed)) | |
| def make_app(): | |
| with gr.Blocks(title="FinAlign 路 Financial document retrieval", analytics_enabled=False) as app: | |
| gr.HTML('<header id="fa-masthead" class="fa"><div class="fa-top"><span class="fa-kicker">Financial document ' | |
| 'retrieval</span><nav aria-label="Project links">' | |
| '<a href="https://github.com/pdmdp/FinAlign">Code & report</a>' | |
| '<a href="https://huggingface.co/datasets/BeIR/fiqa">Dataset</a></nav></div>' | |
| '<h1>FinAlign</h1>' | |
| '<p class="fa-lede">Ask a financial question in English and compare two top-10 rankings of ' | |
| 'FiQA documents: BM25 keyword search and FinAlign, a BGE passage retriever with optional ' | |
| 'query expansion, score fusion and reranking.</p>' | |
| f'<ul class="fa-meta"><li><b>{INDEX.manifest["documents"]:,}</b> documents</li>' | |
| f'<li><b>{INDEX.manifest["passages"]:,}</b> passages</li><li>FiQA / BEIR</li>' | |
| '<li>English</li></ul></header>', padding=False) | |
| with gr.Group(visible=not INDEX.ready): | |
| gr.Markdown("### Prepare the passage index") | |
| setup_status = gr.Markdown( | |
| "The corpus and BM25 index are ready. The Space owner can prepare BGE embeddings " | |
| "using the free GPU in short, resumable batches. This is needed only once.") | |
| if os.environ.get("SPACE_ID"): | |
| gr.LoginButton() | |
| build_button = gr.Button("Prepare / continue index", variant="primary") | |
| archive_download = gr.File(label="Save the completed index", visible=False, interactive=False) | |
| build_state = gr.State() | |
| with gr.Column(visible=INDEX.ready, elem_id="fa-app") as search_panel: | |
| with gr.Row(elem_id="fa-searchbar"): | |
| query = gr.Textbox(label="Question", show_label=False, container=False, | |
| placeholder="Why does a bond鈥檚 price fall when interest rates rise?", | |
| lines=1, max_lines=4, max_length=600, elem_id="fa-query", scale=1) | |
| submit = gr.Button("Compare rankings", variant="primary", elem_id="fa-submit", scale=0, | |
| min_width=176) | |
| with gr.Row(elem_id="fa-examples"): | |
| gr.HTML('<div class="fa"><span class="fa-label">Try a FiQA question</span></div>', padding=False, | |
| elem_classes="fa-inline") | |
| # Fixed questions from the dev split; selected for readable wording, not scores. | |
| example_ids = {"1952", "1718", "469"} | |
| example_texts = [r["query"] for r in INDEX.queries["dev"] if r["qid"] in example_ids] | |
| example_buttons = [(gr.Button(text, size="sm", variant="secondary"), text) | |
| for text in example_texts] | |
| notice = gr.HTML("", padding=False, elem_id="fa-notice-slot") | |
| with gr.Column(elem_id="fa-pipe"): | |
| with gr.Row(elem_id="fa-pipe-head"): | |
| gr.HTML('<div class="fa"><span class="fa-label">FinAlign pipeline</span><span class="fa-pipe-hint">' | |
| 'Switch stages on to see what each one changes. BM25 is not affected.</span></div>', | |
| padding=False, elem_classes="fa-inline") | |
| bge_only = gr.Button("BGE only", size="sm", variant="secondary", scale=0, min_width=0) | |
| all_four = gr.Button("All stages", size="sm", variant="secondary", scale=0, min_width=0) | |
| with gr.Row(elem_id="fa-stages"): | |
| keywords = gr.Checkbox(label="Keyword expansion", value=False, | |
| info="Qwen adds financial terms as an extra query.", | |
| interactive=not ENCODER_ONLY, elem_classes="fa-stage") | |
| hyde = gr.Checkbox(label="Hypothetical answer", value=False, | |
| info="Qwen drafts an answer, searched as an extra query.", | |
| interactive=not ENCODER_ONLY, elem_classes="fa-stage") | |
| gr.HTML('<div class="fa fa-stage-fixed"><span class="fa-stage-title">BGE passage search' | |
| '</span><span class="fa-stage-info">Ranks each document by its ' | |
| 'best 250-word passage.</span></div>', padding=False, elem_classes="fa-stage-core") | |
| lexical = gr.Checkbox(label="BM25 fusion", value=False, | |
| info="Adds normalized BM25 and BGE scores, equal weight.", | |
| elem_classes="fa-stage") | |
| rerank = gr.Checkbox(label="monoT5 rerank", value=False, | |
| info="Rescores the first 50 candidates.", | |
| interactive=not ENCODER_ONLY, elem_classes="fa-stage") | |
| summary = gr.HTML("", padding=False, elem_id="fa-summary-slot") | |
| board = gr.HTML(board_html(INDEX), padding=False, elem_id="fa-board-slot") | |
| with gr.Accordion("Run details 路 latency by stage and query variants", open=False, | |
| elem_classes="fa-accordion"): | |
| details = gr.HTML(details_html(), padding=False) | |
| with gr.Accordion("About the experiment", open=False, elem_classes="fa-accordion"): | |
| gr.Markdown( | |
| "BGE retrieves up to 400 non-overlapping, 250-word passages per query variant. " | |
| "Variant scores are normalized and combined (original 0.70, keywords 0.15, " | |
| "hypothetical 0.15); the best passage represents each document. Disabled variants " | |
| "contribute zero. BM25 and dense document scores receive equal weight when blended. " | |
| "monoT5 reranks the first 50 candidates.\n\n" | |
| "This interactive version follows the course notebook鈥檚 method and fixes model revisions " | |
| "and the expansion seed. Its timings and rankings are new runs. The recorded course " | |
| "results and their limitations remain in the [GitHub repository](https://github.com/pdmdp/FinAlign). " | |
| "A single query is not an ablation study across a benchmark.\n\n" | |
| "FiQA is a historical research collection. Its posts and generated query expansions " | |
| "are not current financial guidance.") | |
| archive = ROOT / "data" / "fiqa-index.zip" | |
| if archive.exists(): | |
| gr.File(value=str(archive), label="Prepared index 路 CC BY-SA 4.0", interactive=False) | |
| gr.Markdown( | |
| "[Code & report](https://github.com/pdmdp/FinAlign) 路 " | |
| "[FiQA / BEIR dataset](https://huggingface.co/datasets/BeIR/fiqa) 路 " | |
| "[Data license: CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)\n\n" | |
| "Original project: Matteo Pietro Di Pilato, Lorenzo Cinquemani and Lorenzo Marchioni. " | |
| "Interactive adaptation: Matteo Pietro Di Pilato.", elem_id="fa-footer") | |
| build_button.click(build_passages, None, build_state, concurrency_limit=1, | |
| concurrency_id="search", api_visibility="private").success( | |
| complete_preparation, build_state, [setup_status, archive_download, search_panel, build_button], | |
| concurrency_limit=1, concurrency_id="search", api_visibility="private") | |
| app.load(refresh_page, None, [setup_status, archive_download, search_panel, build_button], | |
| queue=False, api_visibility="private") | |
| options = [keywords, hyde, lexical, rerank] | |
| bge_only.click(lambda: [False] * 4, None, options, queue=False, api_visibility="private") | |
| full = not ENCODER_ONLY | |
| all_four.click(lambda: [full, full, True, full], None, options, queue=False, api_visibility="private") | |
| state = gr.State() | |
| inputs = [query, *options] | |
| prep_outputs = [state, notice, summary, board, details] | |
| search_outputs = [summary, board, details] | |
| # The board's own skeleton and status replace Gradio's overlay while FinAlign waits for a GPU. | |
| shared = {"concurrency_limit": 1, "concurrency_id": "search", "api_visibility": "private", | |
| "show_progress": "hidden"} | |
| gr.on([submit.click, query.submit], prepare, inputs, prep_outputs, **shared).success( | |
| search, state, search_outputs, **shared) | |
| # An example fills the question and runs the comparison in one click. | |
| for button, text in example_buttons: | |
| button.click(lambda text=text: text, None, query, queue=False, api_visibility="private").then( | |
| prepare, inputs, prep_outputs, **shared).success(search, state, search_outputs, **shared) | |
| return app | |
| if __name__ == "__main__": | |
| make_app().queue(max_size=12).launch(theme=theme(), css=CSS, show_error=False, ssr_mode=False) | |