#!/usr/bin/env python3 """Serve a local live-query prototype for the FinRAG GraphRAG demo.""" from __future__ import annotations import argparse import json import os import re import sys import threading import time from collections import defaultdict from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer from pathlib import Path import numpy as np from rank_bm25 import BM25Okapi from sentence_transformers import CrossEncoder, SentenceTransformer DEMO_DIR = Path(__file__).resolve().parent PROJECT_ROOT = DEMO_DIR.parents[1] sys.path.insert(0, str(PROJECT_ROOT)) CORPUS_FILE = PROJECT_ROOT / "results" / "02_eval_corpus" / "eval_corpus.jsonl" CACHE_DIR = PROJECT_ROOT / "results" / "05_dense" / "cache" GRAPH_DIR = PROJECT_ROOT / "results" / "11_graph" E5_MODEL = "intfloat/e5-large-v2" RERANKER_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2" METRIC_TERMS = { "capital_expenditure": ["capital expenditure", "capex", "investment", "investments"], "cash_flow": ["cash flow", "cash flows", "free cash flow"], "cost": ["cost", "costs", "expense", "expenses"], "emissions": ["emission", "emissions", "co2", "carbon", "greenhouse"], "net_debt": ["net debt", "debt ratio", "debt"], "production": ["production", "produced", "barrels", "boe", "mboe"], "profit": ["profit", "profits", "earnings", "ebit", "income"], "renewables": ["renewable", "renewables", "wind", "solar", "ccs"], "reserves": ["reserve", "reserves"], "revenue": ["revenue", "revenues", "sales"], "safety": ["safety", "injury", "injuries", "incident", "incidents"], "tax": ["tax", "taxes", "tax rate"], } def load_json(path: Path): return json.loads(path.read_text(encoding="utf-8")) def load_jsonl(path: Path) -> list[dict]: with path.open(encoding="utf-8") as handle: return [json.loads(line) for line in handle if line.strip()] def tokenize(text: str) -> list[str]: return [token for token in re.findall(r"[a-z0-9]+", text.lower()) if len(token) > 2] def query_terms(text: str) -> set[str]: stop = {"the", "and", "for", "with", "from", "what", "which", "how", "why", "according", "report"} return {token for token in tokenize(text) if token not in stop} def lexical_overlap(terms: set[str], text: str) -> float: if not terms: return 0.0 return len(terms & set(tokenize(text))) / len(terms) class LiveGraphRAG: def __init__(self) -> None: os.environ.setdefault("TRANSFORMERS_OFFLINE", "1") self.lock = threading.Lock() self.corpus = load_jsonl(CORPUS_FILE) self.by_id = {row["object_id"]: row for row in self.corpus} self.ids = load_json(CACHE_DIR / "intfloat__e5-large-v2__corpus_ids.json") if self.ids != [row["object_id"] for row in self.corpus]: raise RuntimeError("E5 embedding cache does not match the evaluation corpus.") self.embeddings = np.load(CACHE_DIR / "intfloat__e5-large-v2__corpus_embeddings.npy", mmap_mode="r") self.e5 = SentenceTransformer(E5_MODEL) self.reranker = CrossEncoder(RERANKER_MODEL) self.page_to_objects = load_json(GRAPH_DIR / "page_to_objects.json") self.entity_to_objects = load_json(GRAPH_DIR / "entity_to_objects.json") self.metric_to_objects = load_json(GRAPH_DIR / "metric_to_objects.json") self.object_to_entities = load_json(GRAPH_DIR / "object_to_entities.json") self.object_to_metrics = load_json(GRAPH_DIR / "object_to_metrics.json") from scripts.common.entity_extraction import DomainEntityExtractor graph_summary = load_json(GRAPH_DIR / "graph_summary.json") self.entity_extractor = DomainEntityExtractor(known_entities=graph_summary.get("known_entities", [])) self.year_indices: dict[int, np.ndarray] = {} self.year_documents: dict[int, str] = {} self.bm25: dict[int, BM25Okapi] = {} grouped: dict[int, list[int]] = defaultdict(list) for index, row in enumerate(self.corpus): year = int(row["report_year"]) grouped[year].append(index) self.year_documents[year] = row["document_id"] for year, indices in grouped.items(): array = np.asarray(indices, dtype=np.int64) self.year_indices[year] = array self.bm25[year] = BM25Okapi([tokenize(self.corpus[i]["text"]) for i in array]) @property def years(self) -> list[int]: return sorted(self.year_indices) def _rerank(self, question: str, candidates: list[dict], limit: int = 10) -> list[dict]: if not candidates: return [] pairs = [(question, item["text"]) for item in candidates] with self.lock: scores = self.reranker.predict(pairs, batch_size=32, show_progress_bar=False) ranked = sorted(zip(candidates, scores), key=lambda pair: float(pair[1]), reverse=True) output = [] for rank, (item, score) in enumerate(ranked[:limit], 1): row = dict(item) row["rank"] = rank row["reranker_score"] = round(float(score), 4) output.append(row) return output def _candidate(self, object_id: str, reasons: set[str]) -> dict: obj = self.by_id[object_id] return {"object_id": object_id, "document_id": obj.get("document_id"), "report_year": obj.get("report_year"), "page": obj.get("page"), "object_type": obj.get("object_type"), "page_type": obj.get("page_type"), "text": obj.get("text", "")[:1400], "reasons": sorted(reasons)} def _hybrid(self, question: str, year: int) -> tuple[list[dict], list[str]]: indices = self.year_indices[year] tokens = tokenize(question) bm25_scores = np.asarray(self.bm25[year].get_scores(tokens), dtype=float) bm25_order = np.argsort(bm25_scores)[::-1][:100] with self.lock: query_embedding = self.e5.encode(["query: " + question], convert_to_numpy=True, normalize_embeddings=True, show_progress_bar=False)[0] dense_scores = np.asarray(self.embeddings[indices] @ query_embedding, dtype=float) dense_order = np.argsort(dense_scores)[::-1][:100] rrf: dict[int, float] = defaultdict(float) reasons: dict[int, set[str]] = defaultdict(set) for rank, local in enumerate(bm25_order, 1): idx = int(indices[int(local)]) rrf[idx] += 1.0 / (60 + rank) reasons[idx].add("BM25") for rank, local in enumerate(dense_order, 1): idx = int(indices[int(local)]) rrf[idx] += 1.0 / (60 + rank) reasons[idx].add("E5") ordered = sorted(rrf, key=rrf.get, reverse=True)[:50] candidates = [self._candidate(self.corpus[idx]["object_id"], reasons[idx]) for idx in ordered] seed_ids = [self.corpus[idx]["object_id"] for idx in ordered[:10]] return candidates, seed_ids def _selected_graph(self, seed_ids: list[str], year: int, question: str) -> list[dict]: target_doc = self.year_documents[year] terms = query_terms(question) scores: dict[str, float] = defaultdict(float) reasons: dict[str, set[str]] = defaultdict(set) def add(oid: str, score: float, reason: str) -> None: obj = self.by_id.get(oid) if not obj or obj.get("document_id") != target_doc: return scores[oid] += score + 0.15 * lexical_overlap(terms, obj.get("text", "")) reasons[oid].add(reason) for seed in seed_ids: obj = self.by_id[seed] add(seed, 2.0, "Hybrid seed") page_key = f"{target_doc}:{int(obj['page'])}" for oid in self.page_to_objects.get(page_key, []): add(oid, 0.8, f"Same page as {seed}") for entity in self.object_to_entities.get(seed, []): for oid in self.entity_to_objects.get(entity, []): add(oid, 0.55, f"Same entity: {entity}") for metric in self.object_to_metrics.get(seed, []): for oid in self.metric_to_objects.get(metric, []): add(oid, 0.45, f"Same metric: {metric}") ordered = sorted(scores, key=lambda oid: (scores[oid], lexical_overlap(terms, self.by_id[oid]["text"])), reverse=True)[:50] return [self._candidate(oid, reasons[oid]) for oid in ordered] def _path_candidates(self, question: str, year: int) -> tuple[list[dict], dict]: target_doc = self.year_documents[year] lowered = question.lower() terms = query_terms(question) metrics = [name for name, variants in METRIC_TERMS.items() if any(term in lowered for term in variants)] with self.lock: entities = self.entity_extractor.graph_entities(question, limit=10) entity_keys = [entity.lower().replace(" ", "_") for entity in entities] scores: dict[str, float] = defaultdict(float) reasons: dict[str, set[str]] = defaultdict(set) def add(oid: str, score: float, reason: str) -> None: obj = self.by_id.get(oid) if not obj or obj.get("document_id") != target_doc: return scores[oid] += score + lexical_overlap(terms, obj.get("text", "")) reasons[oid].add(reason) for metric in metrics: ranked = sorted(self.metric_to_objects.get(metric, []), key=lambda oid: lexical_overlap(terms, self.by_id.get(oid, {}).get("text", "")), reverse=True) for oid in ranked[:120]: add(oid, 1.2, f"Query metric: {metric}") for entity, entity_key in zip(entities, entity_keys): ranked = sorted(self.entity_to_objects.get(entity_key, []), key=lambda oid: lexical_overlap(terms, self.by_id.get(oid, {}).get("text", "")), reverse=True) for oid in ranked[:80]: add(oid, 0.9, f"Query entity: {entity}") if not scores: for idx in self.year_indices[year]: oid = self.corpus[int(idx)]["object_id"] overlap = lexical_overlap(terms, self.by_id[oid].get("text", "")) if overlap: add(oid, overlap, "Document lexical path seed") seeds = sorted(scores, key=scores.get, reverse=True)[:20] for seed in seeds: obj = self.by_id[seed] page_key = f"{target_doc}:{int(obj['page'])}" for oid in self.page_to_objects.get(page_key, []): add(oid, 0.35, f"Path via page {obj['page']}") ordered = sorted(scores, key=lambda oid: (scores[oid], lexical_overlap(terms, self.by_id[oid]["text"])), reverse=True)[:80] return [self._candidate(oid, reasons[oid]) for oid in ordered], {"year": year, "entities": entities, "metrics": metrics, "path_seed_count": len(seeds)} def query(self, question: str, year: int, method: str) -> dict: started = time.perf_counter() hybrid_pool, seed_ids = self._hybrid(question, year) hybrid_ranked = self._rerank(question, hybrid_pool) after_hybrid = time.perf_counter() graph_ranked: list[dict] = [] path_ranked: list[dict] = [] trace = {"year": year, "entities": [], "metrics": [], "path_seed_count": 0} if method in {"graph", "both"}: graph_ranked = self._rerank(question, self._selected_graph(seed_ids, year, question)) if method in {"paths", "both"}: path_pool, trace = self._path_candidates(question, year) path_ranked = self._rerank(question, path_pool) after_graph = time.perf_counter() sources = [(hybrid_ranked, "Retained hybrid")] if graph_ranked: sources.append((graph_ranked, "Selected graph")) if path_ranked: sources.append((path_ranked, "Graph path")) merged: dict[str, dict] = {} for rows, source in sources: for row in rows: oid = row["object_id"] if oid not in merged: merged[oid] = dict(row) merged[oid]["reasons"] = [] merged[oid]["reasons"] = sorted(set(merged[oid]["reasons"] + row.get("reasons", []) + [source])) final = self._rerank(question, list(merged.values())[:80]) finished = time.perf_counter() return {"question": question, "year": year, "method": method, "trace": trace, "seed_object_ids": seed_ids, "timings": {"hybrid_seconds": round(after_hybrid - started, 3), "graph_seconds": round(after_graph - after_hybrid, 3), "final_rerank_seconds": round(finished - after_graph, 3), "total_seconds": round(finished - started, 3)}, "results": final, "note": "Live prototype result; paper metrics are reproduced separately from saved benchmark rankings."} class Handler(SimpleHTTPRequestHandler): engine: LiveGraphRAG def __init__(self, *args, **kwargs): super().__init__(*args, directory=str(DEMO_DIR), **kwargs) def do_GET(self): if self.path == "/api/health": self._json({"status": "ready", "years": self.engine.years}) return if self.path in {"/live", "/live/"}: self.path = "/live.html" super().do_GET() def do_POST(self): if self.path != "/api/live-query": self.send_error(404) return try: length = int(self.headers.get("Content-Length", "0")) payload = json.loads(self.rfile.read(length).decode("utf-8")) question = str(payload.get("question", "")).strip() year = int(payload.get("year")) method = str(payload.get("method", "both")) if len(question) < 5: raise ValueError("Enter a complete question.") if year not in self.engine.years: raise ValueError("Choose a valid report year.") if method not in {"hybrid", "graph", "paths", "both"}: raise ValueError("Choose a valid retrieval method.") self._json(self.engine.query(question, year, method)) except Exception as exc: self._json({"error": str(exc)}, status=400) def _json(self, payload: dict, status: int = 200): data = json.dumps(payload, ensure_ascii=False).encode("utf-8") self.send_response(status) self.send_header("Content-Type", "application/json; charset=utf-8") self.send_header("Content-Length", str(len(data))) self.end_headers() self.wfile.write(data) def main() -> None: parser = argparse.ArgumentParser() parser.add_argument("--host", default="127.0.0.1") parser.add_argument("--port", type=int, default=8766) args = parser.parse_args() print("Loading live retrieval models and indexes...") engine = LiveGraphRAG() Handler.engine = engine server = ThreadingHTTPServer((args.host, args.port), Handler) print(f"Live GraphRAG demo: http://{args.host}:{args.port}/live") server.serve_forever() if __name__ == "__main__": main()