"""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)
@spaces.GPU(duration=60)
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’s "
"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’s 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.{esc(message)}")
return ("error", "FinAlign could not finish this search",
"The BM25 ranking is complete. Try again in a moment; the Space logs contain details."
+ (f"{esc(message)}" 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())
@spaces.GPU(duration=60)
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(' 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.FinAlign
'
'