File size: 16,918 Bytes
c0f3416
 
 
 
 
2f7e4fa
c0f3416
 
 
 
 
 
 
 
 
 
 
2f7e4fa
 
de1f347
2f7e4fa
 
de1f347
2f7e4fa
 
c0f3416
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
de1f347
 
 
 
 
 
 
 
 
 
 
2f7e4fa
 
 
de1f347
2f7e4fa
 
 
 
de1f347
 
 
2f7e4fa
 
de1f347
2f7e4fa
 
c0f3416
 
2f7e4fa
c0f3416
 
de1f347
 
c0f3416
 
 
de1f347
c0f3416
 
 
 
 
de1f347
 
 
 
 
2f7e4fa
c0f3416
 
 
2f7e4fa
 
 
 
c0f3416
 
de1f347
 
 
 
2f7e4fa
 
 
 
de1f347
 
 
 
 
c0f3416
 
 
de1f347
 
 
 
2f7e4fa
c0f3416
 
 
 
de1f347
 
 
2f7e4fa
de1f347
2f7e4fa
 
 
de1f347
 
 
c0f3416
 
 
 
 
 
 
 
 
 
de1f347
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2f7e4fa
de1f347
c0f3416
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2f7e4fa
c0f3416
 
 
 
 
 
2f7e4fa
 
 
 
 
 
c0f3416
2f7e4fa
de1f347
 
 
 
 
 
 
2f7e4fa
 
 
de1f347
c0f3416
 
 
 
de1f347
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
"""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鈥檚 "
             "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())


@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('<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 &amp; 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)