Add knowledge graph search over extracted text

app.py

@@ -106,6 +106,10 @@ async def capabilities():
         # True when this deployment provides a shared Gemini key (a Space secret),
         # so the front-end can offer online OCR without the visitor's own key.
         "online_demo": bool(os.environ.get("DEMO_GEMINI_KEY", "").strip()),
+        # Knowledge-graph search is always supported by the backend (stdlib +
+        # numpy, no torch/networkx). It needs a Gemini key at build time — the
+        # user's own key or, where present, the demo key (online_demo above).
+        "knowledge_graph": True,
     }
 
 
@@ -348,3 +352,179 @@ async def page_image(job_id: str, n: int, dpi: int = 150):
         # 500 — the frontend <img> onerror handles a non-image response.
         raise HTTPException(status_code=404, detail="could not render page")
     return StreamingResponse(io.BytesIO(png), media_type="image/png")
+
+
+# ---------------------------------------------------------------------------
+# Knowledge graph (opt-in, online) — build a per-document graph from the
+# already-extracted text, then answer queries with hybrid semantic + graph-
+# traversal retrieval. These endpoints touch NO fitz/PaddleOCR, so they run on
+# the DEFAULT thread pool (run_in_executor(None, ...)) — putting them on the
+# single OCR worker would needlessly serialize them behind live extraction.
+# ---------------------------------------------------------------------------
+def _resolve_kg_key(explicit: str, job) -> str:
+    """Pick the Gemini key for KG: explicit (browser) -> the job's own key -> demo."""
+    return (
+        (explicit or "").strip()
+        or (getattr(job, "online_key", "") or "").strip()
+        or os.environ.get("DEMO_GEMINI_KEY", "").strip()
+    )
+
+
+@app.post("/api/graph/build")
+async def graph_build(
+    job_id: str = Form(...),
+    online_key: str = Form(""),
+    online_model: str = Form(""),
+    embed: str = Form("true"),
+    max_pages: str = Form(""),
+):
+    """Build a knowledge graph from a finished job's extracted text."""
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    if job.status not in ("done", "error"):
+        raise HTTPException(
+            status_code=409,
+            detail="Extraction is still running; wait for it to finish first.",
+        )
+    if job.kg_status == "building":
+        raise HTTPException(
+            status_code=409,
+            detail="A knowledge graph is already being built for this document.",
+        )
+
+    okey = _resolve_kg_key(online_key, job)
+    if not okey:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "Building a knowledge graph needs a Gemini API key. Enter your "
+                "free key from aistudio.google.com (the same key online OCR uses)."
+            ),
+        )
+
+    pages = [
+        (p.page, p.text)
+        for p in job.pages
+        if p.status == "done" and (p.text or "").strip()
+    ]
+    if not pages:
+        raise HTTPException(
+            status_code=400, detail="No extracted text to build a graph from."
+        )
+
+    mp = None
+    if (max_pages or "").strip():
+        try:
+            mp = max(0, int(max_pages))
+        except ValueError:
+            mp = None
+    do_embed = _parse_bool(embed)
+
+    from pipeline import kg as kgmod
+
+    job.kg_status = "building"
+    job.kg_error = None
+    loop = asyncio.get_running_loop()
+    try:
+        graph = await loop.run_in_executor(
+            None,
+            lambda: kgmod.build_graph(
+                pages,
+                api_key=okey,
+                triple_model=(online_model or None),
+                max_pages=mp,
+                embed=do_embed,
+            ),
+        )
+    except RuntimeError as exc:
+        # A Gemini/key/quota/network failure — actionable, single-line message.
+        job.kg_status = "error"
+        job.kg_error = str(exc)
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception:
+        job.kg_status = "error"
+        job.kg_error = "Knowledge-graph build failed unexpectedly."
+        raise HTTPException(
+            status_code=502, detail="Knowledge-graph build failed unexpectedly."
+        )
+
+    job.knowledge_graph = graph
+    job.kg_status = "ready"
+    return {
+        "job_id": job_id,
+        "status": "ready",
+        "nodes": graph.num_nodes,
+        "edges": graph.num_edges,
+        "has_vectors": graph.has_vectors,
+    }
+
+
+@app.post("/api/graph/query")
+async def graph_query(
+    job_id: str = Form(...),
+    query: str = Form(...),
+    online_key: str = Form(""),
+    top_k: int = Form(6),
+    hops: int = Form(2),
+):
+    """Answer a query against a built graph: ranked entities + supporting paths."""
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    graph = job.knowledge_graph
+    if graph is None:
+        raise HTTPException(
+            status_code=409, detail="No knowledge graph has been built for this document yet."
+        )
+    q = (query or "").strip()
+    if not q:
+        raise HTTPException(status_code=400, detail="Enter a question to search the graph.")
+
+    okey = _resolve_kg_key(online_key, job)  # optional: enables semantic search
+    loop = asyncio.get_running_loop()
+    try:
+        result = await loop.run_in_executor(
+            None,
+            lambda: graph.search(
+                q,
+                api_key=(okey or None),
+                top_k=max(1, min(20, int(top_k))),
+                hops=max(0, min(3, int(hops))),
+            ),
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception:
+        raise HTTPException(status_code=502, detail="Graph query failed unexpectedly.")
+    return result
+
+
+@app.get("/api/graph/{job_id}")
+async def graph_get(job_id: str, full: bool = False):
+    """Return the built graph.
+
+    Default: compact node/edge lists for the canvas visualization (capped).
+    ``?full=1``: the complete entities + triples + provenance for .json export.
+    """
+    job = manager.get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    graph = job.knowledge_graph
+    if graph is None:
+        return {
+            "status": job.kg_status,
+            "error": job.kg_error,
+            "nodes": [],
+            "edges": [],
+            "total_nodes": 0,
+            "total_edges": 0,
+            "truncated": False,
+        }
+    if full:
+        data = graph.to_export_dict()
+        data["status"] = "ready"
+        return data
+    data = graph.to_viz_dict()
+    data["status"] = "ready"
+    return data

pipeline/jobs.py

@@ -85,6 +85,16 @@ class Job:
     processed_pages: int = 0
     error: Optional[str] = None
 
+    # Optional knowledge graph (opt-in, online). Built on demand from this job's
+    # extracted pages and attached here, so it is reclaimed with the job by the
+    # TTL/LRU eviction below and — because to_dict() is an explicit allow-list —
+    # is NEVER serialized to the client or broadcast over SSE (same protection
+    # the API key gets). Held loosely as ``object`` to keep jobs.py free of the
+    # kg / numpy import at module load.
+    knowledge_graph: object = field(default=None, repr=False)
+    kg_status: str = field(default="none", repr=False)  # none|building|ready|error
+    kg_error: Optional[str] = field(default=None, repr=False)
+
     # Internals (not serialized). One asyncio.Queue per live SSE subscriber so
     # progress is broadcast (fan-out), not consumed once — reconnects are safe.
     subscribers: list = field(default_factory=list, repr=False)

pipeline/kg.py

@@ -0,0 +1,802 @@
+"""Optional knowledge-graph + embedding search over EXTRACTED text (Gemini).
+
+After a PDF is extracted, this module turns its per-page text into a small
+**knowledge graph** — typed entities (nodes) joined by ``(subject, predicate,
+object)`` triples (edges) — embeds every node into a vector space, and answers a
+query by combining **semantic vector search** (conceptually-related entities)
+with **explicit graph traversal** (following the facts). The answer is
+*explainable*: every result carries the supporting triples and the page each
+came from.
+
+DESIGN / IDENTITY
+- This is an OPT-IN, online feature. Like ``online_ocr.py`` it sends text to
+  Google's Gemini API, so it is OFF by default and only runs when the caller
+  passes a Gemini API key. The page text leaves this machine.
+- ZERO new pip dependencies: the REST calls use the Python standard library
+  only (``urllib.request`` + ``json``); the graph is a plain in-memory
+  adjacency structure; ``numpy`` (already a core dep) holds the node vectors.
+  This keeps the feature working on the lean hosted build too (no torch /
+  sentence-transformers / networkx required).
+- The security-critical key sanitization and the HTTP error mapping are REUSED
+  from ``online_ocr`` so the "never echo the key, only raise a single-line
+  RuntimeError" contract holds here as well.
+
+Importing this module performs NO network call and has no import-time side
+effects.
+
+Public API
+----------
+``extract_triples(text, *, api_key, model=None, timeout=...) -> dict``
+    Pull ``{"entities": [...], "triples": [...]}`` out of one page of text.
+``embed_texts(texts, *, api_key, model=None, task_type=..., timeout=...) -> np.ndarray``
+    Embed a list of strings to an ``(n, dim)`` float32 matrix.
+``build_graph(pages, *, api_key, ...) -> KnowledgeGraph``
+    Build a per-document graph from ``[(page_number, text), ...]``.
+``KnowledgeGraph``
+    Holds the graph + node vectors; ``.search(query, ...)`` does hybrid
+    retrieval and returns ranked, explainable results.
+"""
+
+import json
+import re
+import time
+import urllib.error
+import urllib.request
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+# Reuse the verified, security-tested helpers from the OCR client so the key is
+# sanitized identically and HTTP errors never leak it.
+from pipeline.online_ocr import (
+    _API_BASE,
+    _API_KEY_HEADER,
+    _clean_key,
+    _friendly_http_error,
+    is_configured,
+)
+
+# ---------------------------------------------------------------------------
+# Gemini REST endpoints (same base/host as online_ocr; different methods).
+# ---------------------------------------------------------------------------
+_GENERATE_URL = _API_BASE + "/{model}:generateContent"
+_BATCH_EMBED_URL = _API_BASE + "/{model}:batchEmbedContents"
+
+# Triple extraction must default to a FREE-TIER model (Flash). Pro/preview
+# models return HTTP 429 limit:0 on the free tier — see online_ocr notes.
+DEFAULT_TRIPLE_MODEL = "gemini-2.5-flash"
+# Embeddings: text-embedding-004 is the stable, free, 768-dim model. The wire
+# format wants the "models/" prefix in the per-request "model" field.
+DEFAULT_EMBED_MODEL = "text-embedding-004"
+
+# Gemini caps batchEmbedContents at 100 requests per call; chunk to stay under.
+_EMBED_BATCH = 100
+
+# Defensive cap on per-page text sent for triple extraction. A single PDF page
+# is tiny next to Flash's context window, but a pathological page (e.g. a giant
+# embedded text dump) shouldn't balloon the request.
+_MAX_PAGE_CHARS = 100_000
+
+# Transient-failure backoff. Free-tier embedding/generate limits are real, so a
+# 429/503 is retried a few times with exponential backoff before giving up.
+_RETRY_STATUSES = frozenset({429, 503})
+_RETRY_ATTEMPTS = 4
+_RETRY_BASE_DELAY = 1.5  # seconds; doubled each attempt
+
+# Instruction for triple extraction. We ask for typed entities AND triples and
+# force a JSON response via responseSchema for deterministic parsing.
+_TRIPLE_PROMPT = (
+    "You are building a knowledge graph from a document. From the TEXT below, "
+    "extract the key entities and the factual relationships between them.\n"
+    "- entities: the important named things (people, organizations, places, "
+    "dates, IDs, amounts, concepts). Give each a short canonical name and a "
+    "TYPE (e.g. PERSON, ORG, PLACE, DATE, ID, AMOUNT, CONCEPT, OTHER).\n"
+    "- triples: factual (subject, predicate, object) statements stated or "
+    "clearly implied by the text. Use concise predicates (e.g. 'works at', "
+    "'located in', 'has id', 'dated'). Subject and object should be entity "
+    "names. Do NOT invent facts that are not supported by the text.\n"
+    "Return only what the text supports; if the text is empty or has no "
+    "extractable facts, return empty lists.\n\nTEXT:\n"
+)
+
+# Response schema for generateContent — keeps output a strict JSON object.
+_TRIPLE_SCHEMA = {
+    "type": "OBJECT",
+    "properties": {
+        "entities": {
+            "type": "ARRAY",
+            "items": {
+                "type": "OBJECT",
+                "properties": {
+                    "name": {"type": "STRING"},
+                    "type": {"type": "STRING"},
+                },
+                "required": ["name"],
+            },
+        },
+        "triples": {
+            "type": "ARRAY",
+            "items": {
+                "type": "OBJECT",
+                "properties": {
+                    "subject": {"type": "STRING"},
+                    "predicate": {"type": "STRING"},
+                    "object": {"type": "STRING"},
+                },
+                "required": ["subject", "predicate", "object"],
+            },
+        },
+    },
+    "required": ["triples"],
+}
+
+
+# ---------------------------------------------------------------------------
+# Low-level HTTP (stdlib) — mirrors online_ocr's request/error handling.
+# ---------------------------------------------------------------------------
+def _post_json(url: str, body: dict, api_key: str, *, timeout: float) -> dict:
+    """POST a JSON body to Gemini and return the parsed JSON response.
+
+    ``api_key`` must already be sanitized via ``_clean_key``. Retries 429/503
+    with exponential backoff, then maps any HTTP/network/non-JSON failure to a
+    single-line RuntimeError (never echoing the key — ``_friendly_http_error``
+    reads only the API's own error body).
+    """
+    data = json.dumps(body).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            _API_KEY_HEADER: api_key,
+        },
+    )
+
+    last_http_err: Optional[urllib.error.HTTPError] = None
+    for attempt in range(_RETRY_ATTEMPTS):
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                raw = response.read()
+            break
+        except urllib.error.HTTPError as err:
+            last_http_err = err
+            if err.code in _RETRY_STATUSES and attempt < _RETRY_ATTEMPTS - 1:
+                time.sleep(_RETRY_BASE_DELAY * (2 ** attempt))
+                continue
+            raise _friendly_http_error(err) from None
+        except urllib.error.URLError as err:
+            raise RuntimeError(
+                "Could not reach the Gemini API ({}). Check your internet "
+                "connection.".format(err.reason)
+            ) from None
+        except TimeoutError:
+            raise RuntimeError(
+                "The Gemini request timed out after {}s.".format(timeout)
+            ) from None
+    else:  # pragma: no cover - loop always breaks or raises
+        raise _friendly_http_error(last_http_err)
+
+    try:
+        payload = json.loads(raw.decode("utf-8", "replace"))
+    except (ValueError, AttributeError) as err:
+        raise RuntimeError(
+            "Gemini returned a response that was not valid JSON ({}). The "
+            "service may be having problems; retry shortly.".format(err)
+        ) from None
+    if not isinstance(payload, dict):
+        raise RuntimeError(
+            "Gemini returned an unexpected response (not a JSON object); "
+            "retry shortly."
+        )
+    return payload
+
+
+def _resolve_model(model, default: str) -> str:
+    """Return a clean bare model id (no ``models/`` prefix), defaulting when unset."""
+    name = (str(model).strip() if model else "") or default
+    if name.startswith("models/"):
+        name = name[len("models/"):]
+    return name or default
+
+
+# ---------------------------------------------------------------------------
+# Response parsers (pure functions — unit-tested with canned dicts, no network).
+# ---------------------------------------------------------------------------
+def _response_text(payload: dict) -> str:
+    """Concatenate the text parts of a generateContent response.
+
+    Handles a prompt-level block or a non-STOP finishReason by raising an
+    actionable RuntimeError, and tolerates an explicit ``{"text": null}`` part.
+    """
+    feedback = payload.get("promptFeedback") or {}
+    block_reason = feedback.get("blockReason")
+    candidates = payload.get("candidates") or []
+    if not candidates:
+        if block_reason:
+            raise RuntimeError(
+                "Gemini blocked the request (blockReason={}). The text tripped "
+                "a safety filter; knowledge-graph extraction is unavailable for "
+                "this page.".format(block_reason)
+            )
+        raise RuntimeError(
+            "Gemini returned no candidates for knowledge-graph extraction."
+        )
+    candidate = candidates[0] or {}
+    content = candidate.get("content") or {}
+    parts = content.get("parts") or []
+    return "".join(
+        str(part.get("text") or "") for part in parts if isinstance(part, dict)
+    )
+
+
+def _parse_triple_payload(payload: dict) -> dict:
+    """Parse a generateContent response into ``{"entities": [...], "triples": [...]}``.
+
+    The model is asked to return a JSON object (responseMimeType=application/json),
+    so the candidate text is itself a JSON string. We parse it and coerce every
+    field to clean strings, dropping malformed/empty rows. Never raises on a
+    merely-empty or slightly-malformed result — returns empty lists instead, so
+    one odd page can't fail the whole build.
+    """
+    text = _response_text(payload).strip()
+    if not text:
+        return {"entities": [], "triples": []}
+    # Strip an accidental ```json ... ``` fence if the model added one.
+    if text.startswith("```"):
+        text = text.strip("`")
+        if text[:4].lower() == "json":
+            text = text[4:]
+        text = text.strip()
+    try:
+        obj = json.loads(text)
+    except (ValueError, TypeError):
+        return {"entities": [], "triples": []}
+    if not isinstance(obj, dict):
+        # Some models return a bare array of triples.
+        obj = {"triples": obj} if isinstance(obj, list) else {}
+
+    entities = []
+    for e in obj.get("entities") or []:
+        if not isinstance(e, dict):
+            continue
+        name = str(e.get("name") or "").strip()
+        if not name:
+            continue
+        etype = str(e.get("type") or "").strip().upper() or "OTHER"
+        entities.append({"name": name, "type": etype})
+
+    triples = []
+    for t in obj.get("triples") or []:
+        if not isinstance(t, dict):
+            continue
+        subj = str(t.get("subject") or "").strip()
+        pred = str(t.get("predicate") or "").strip()
+        obj_ = str(t.get("object") or "").strip()
+        if subj and pred and obj_:
+            triples.append({"subject": subj, "predicate": pred, "object": obj_})
+    return {"entities": entities, "triples": triples}
+
+
+def _parse_embed_payload(payload: dict, expected: int) -> list:
+    """Parse a batchEmbedContents response into a list of float vectors.
+
+    Response shape: ``{"embeddings": [{"values": [...]}, ...]}`` in request
+    order. Raises if the count doesn't match what we sent (a silent mismatch
+    would misalign vectors with nodes).
+    """
+    embeddings = payload.get("embeddings")
+    if not isinstance(embeddings, list):
+        raise RuntimeError(
+            "Gemini embedding response had no 'embeddings' list; cannot build "
+            "the vector index."
+        )
+    if len(embeddings) != expected:
+        raise RuntimeError(
+            "Gemini returned {} embeddings for {} inputs (count mismatch).".format(
+                len(embeddings), expected
+            )
+        )
+    out = []
+    for item in embeddings:
+        values = (item or {}).get("values") if isinstance(item, dict) else None
+        if not isinstance(values, list) or not values:
+            raise RuntimeError("Gemini returned an empty embedding vector.")
+        out.append([float(v) for v in values])
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Public extraction / embedding calls.
+# ---------------------------------------------------------------------------
+def extract_triples(text: str, *, api_key, model=None, timeout: float = 120) -> dict:
+    """Extract typed entities + ``(subject, predicate, object)`` triples from text.
+
+    Returns ``{"entities": [{"name","type"}], "triples":
+    [{"subject","predicate","object"}]}``. Provenance (the source page) is NOT
+    returned by the model — the caller attaches it.
+    """
+    if not is_configured(api_key):
+        raise RuntimeError(
+            "Knowledge-graph extraction needs a Gemini API key but none was "
+            "provided. Get a free key from https://aistudio.google.com/."
+        )
+    clean = str(text or "").strip()
+    if not clean:
+        return {"entities": [], "triples": []}
+    if len(clean) > _MAX_PAGE_CHARS:
+        clean = clean[:_MAX_PAGE_CHARS]
+
+    api_key = _clean_key(api_key)
+    model_id = _resolve_model(model, DEFAULT_TRIPLE_MODEL)
+    body = {
+        "contents": [{"parts": [{"text": _TRIPLE_PROMPT + clean}]}],
+        "generationConfig": {
+            "temperature": 0,
+            "responseMimeType": "application/json",
+            "responseSchema": _TRIPLE_SCHEMA,
+        },
+    }
+    payload = _post_json(
+        _GENERATE_URL.format(model=model_id), body, api_key, timeout=timeout
+    )
+    return _parse_triple_payload(payload)
+
+
+def embed_texts(
+    texts,
+    *,
+    api_key,
+    model=None,
+    task_type: str = "RETRIEVAL_DOCUMENT",
+    timeout: float = 120,
+) -> np.ndarray:
+    """Embed a list of strings into an ``(n, dim)`` float32 matrix via Gemini.
+
+    ``task_type`` should be ``RETRIEVAL_DOCUMENT`` for the graph's nodes and
+    ``RETRIEVAL_QUERY`` for the search query — text-embedding-004 uses it to
+    tune the vectors for retrieval, a real accuracy win. Batches at 100 inputs
+    per request (Gemini's cap) and concatenates in order.
+    """
+    if not is_configured(api_key):
+        raise RuntimeError(
+            "Knowledge-graph search needs a Gemini API key but none was provided."
+        )
+    items = [str(t or "") for t in texts]
+    if not items:
+        return np.zeros((0, 0), dtype=np.float32)
+
+    api_key = _clean_key(api_key)
+    model_id = _resolve_model(model, DEFAULT_EMBED_MODEL)
+    wire_model = "models/" + model_id
+    url = _BATCH_EMBED_URL.format(model=model_id)
+
+    vectors: list = []
+    for start in range(0, len(items), _EMBED_BATCH):
+        chunk = items[start:start + _EMBED_BATCH]
+        body = {
+            "requests": [
+                {
+                    "model": wire_model,
+                    "content": {"parts": [{"text": t}]},
+                    "taskType": task_type,
+                }
+                for t in chunk
+            ]
+        }
+        payload = _post_json(url, body, api_key, timeout=timeout)
+        vectors.extend(_parse_embed_payload(payload, len(chunk)))
+
+    return np.asarray(vectors, dtype=np.float32)
+
+
+# ---------------------------------------------------------------------------
+# Graph data structures + builder.
+# ---------------------------------------------------------------------------
+def _norm_key(name: str) -> str:
+    """Canonical key for entity de-duplication (case/space-insensitive)."""
+    return re.sub(r"\s+", " ", str(name or "").strip()).casefold()
+
+
+_WORD_RE = re.compile(r"[^\W\d_]+|\d+", re.UNICODE)
+
+
+def _tokens(text: str) -> set:
+    return {t for t in _WORD_RE.findall(str(text or "").casefold()) if len(t) > 1}
+
+
+@dataclass
+class KnowledgeGraph:
+    """A per-document knowledge graph + node embeddings, held in RAM.
+
+    Nodes are entities; edges are ``(subject, predicate, object)`` triples, each
+    carrying the page it came from (provenance). Node vectors live in a parallel
+    float32 matrix (L2-normalized for cosine). Everything is plain Python +
+    numpy — no networkx, no external store — so it evicts with its ``Job`` and
+    serializes only via the explicit ``to_*`` methods (never leaked by accident).
+    """
+
+    # Parallel arrays indexed by node id (0..n-1).
+    nodes: list = field(default_factory=list)        # [{name, type, pages, degree}]
+    triples: list = field(default_factory=list)      # [{subject_id, predicate, object_id, subject, object, page}]
+    adjacency: dict = field(default_factory=dict)     # node_id -> [(neighbor_id, triple_index)]
+    _index: dict = field(default_factory=dict, repr=False)  # norm_key -> node_id
+    vectors: Optional[np.ndarray] = field(default=None, repr=False)  # (n, dim) L2-normalized
+    embed_model: Optional[str] = None
+
+    # --- construction helpers ------------------------------------------------
+    def _add_node(self, name: str, etype: str = "OTHER", page: Optional[int] = None) -> int:
+        key = _norm_key(name)
+        if not key:
+            return -1
+        nid = self._index.get(key)
+        if nid is None:
+            nid = len(self.nodes)
+            self._index[key] = nid
+            self.nodes.append(
+                {"name": str(name).strip(), "type": (etype or "OTHER"), "pages": [], "degree": 0}
+            )
+            self.adjacency[nid] = []
+        node = self.nodes[nid]
+        # Prefer a known type over OTHER if a later mention supplies one.
+        if (not node["type"] or node["type"] == "OTHER") and etype and etype != "OTHER":
+            node["type"] = etype
+        if page is not None and page not in node["pages"]:
+            node["pages"].append(page)
+        return nid
+
+    def _add_triple(self, subject: str, predicate: str, obj: str, page: Optional[int]) -> None:
+        s_id = self._add_node(subject, page=page)
+        o_id = self._add_node(obj, page=page)
+        if s_id < 0 or o_id < 0 or s_id == o_id:
+            return
+        tindex = len(self.triples)
+        self.triples.append(
+            {
+                "subject_id": s_id,
+                "object_id": o_id,
+                "predicate": str(predicate).strip(),
+                "subject": self.nodes[s_id]["name"],
+                "object": self.nodes[o_id]["name"],
+                "page": page,
+            }
+        )
+        # Undirected adjacency for traversal; direction is kept in the triple.
+        self.adjacency[s_id].append((o_id, tindex))
+        self.adjacency[o_id].append((s_id, tindex))
+        self.nodes[s_id]["degree"] += 1
+        self.nodes[o_id]["degree"] += 1
+
+    def _node_embed_text(self, nid: int) -> str:
+        """Text used to embed a node: its name/type + a little fact context."""
+        node = self.nodes[nid]
+        bits = ["{} ({})".format(node["name"], node["type"])]
+        # Up to a few connected facts give the embedding semantic context.
+        ctx = [
+            "{} {} {}".format(t["subject"], t["predicate"], t["object"])
+            for _, tindex in self.adjacency[nid][:3]
+            for t in (self.triples[tindex],)
+        ]
+        if ctx:
+            bits.append(". ".join(ctx))
+        return ". ".join(bits)
+
+    def set_vectors(self, vectors: Optional[np.ndarray], model: Optional[str] = None) -> None:
+        """Attach (and L2-normalize) the node-vector matrix."""
+        if vectors is None or getattr(vectors, "size", 0) == 0:
+            self.vectors = None
+            return
+        v = np.asarray(vectors, dtype=np.float32)
+        norms = np.linalg.norm(v, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        self.vectors = v / norms
+        self.embed_model = model
+
+    # --- public properties ---------------------------------------------------
+    @property
+    def num_nodes(self) -> int:
+        return len(self.nodes)
+
+    @property
+    def num_edges(self) -> int:
+        return len(self.triples)
+
+    @property
+    def has_vectors(self) -> bool:
+        return self.vectors is not None and self.vectors.shape[0] == len(self.nodes)
+
+    # --- retrieval -----------------------------------------------------------
+    def _semantic_scores(self, query: str, query_vec: Optional[np.ndarray]) -> np.ndarray:
+        """Per-node relevance to the query in [0,1].
+
+        Uses cosine similarity when vectors + a query vector are available;
+        otherwise falls back to lexical token overlap so the feature still works
+        offline / when embeddings are unavailable.
+        """
+        n = len(self.nodes)
+        if n == 0:
+            return np.zeros((0,), dtype=np.float32)
+        if self.has_vectors and query_vec is not None and query_vec.size:
+            q = np.asarray(query_vec, dtype=np.float32).reshape(-1)
+            qn = np.linalg.norm(q)
+            if qn > 0:
+                q = q / qn
+                if q.shape[0] == self.vectors.shape[1]:
+                    sims = self.vectors @ q  # cosine; both are L2-normalized
+                    return ((sims + 1.0) / 2.0).astype(np.float32)  # map [-1,1]->[0,1]
+        # Lexical fallback.
+        q_tokens = _tokens(query)
+        scores = np.zeros((n,), dtype=np.float32)
+        if not q_tokens:
+            return scores
+        for i, node in enumerate(self.nodes):
+            nt = _tokens(node["name"])
+            if nt:
+                scores[i] = len(q_tokens & nt) / float(len(q_tokens | nt))
+        return scores
+
+    def _multi_source_paths(self, seeds: list, hops: int) -> dict:
+        """Multi-source BFS from ``seeds`` up to ``hops``.
+
+        Returns ``{node_id: (distance, source_seed_id, [triple_index,...])}``
+        where the triple list is the chain of edges from the nearest seed to the
+        node (empty for the seeds themselves).
+        """
+        result: dict = {}
+        prev: dict = {}
+        queue: deque = deque()
+        for s in seeds:
+            if s not in result:
+                result[s] = (0, s, [])
+                queue.append(s)
+        while queue:
+            u = queue.popleft()
+            dist, src, _ = result[u]
+            if dist >= hops:
+                continue
+            for nb_id, tindex in self.adjacency.get(u, []):
+                if nb_id not in result:
+                    prev[nb_id] = (u, tindex)
+                    result[nb_id] = (dist + 1, src, [])
+                    queue.append(nb_id)
+        # Reconstruct triple chains via predecessors.
+        for nid in list(result.keys()):
+            dist, src, _ = result[nid]
+            chain = []
+            cur = nid
+            while cur in prev:
+                u, tindex = prev[cur]
+                chain.append(tindex)
+                cur = u
+            chain.reverse()
+            result[nid] = (dist, src, chain)
+        return result
+
+    def search(
+        self,
+        query: str,
+        *,
+        api_key=None,
+        query_vec: Optional[np.ndarray] = None,
+        embed_model=None,
+        top_k: int = 6,
+        hops: int = 2,
+        max_results: int = 10,
+        timeout: float = 60,
+    ) -> dict:
+        """Hybrid retrieval: semantic seeds + graph traversal -> explainable answers.
+
+        1. Score every node's semantic relevance to ``query`` (cosine over
+           embeddings, else lexical).
+        2. Take the ``top_k`` strongest as SEED nodes.
+        3. Traverse up to ``hops`` from the seeds to gather connected entities +
+           the linking triples.
+        4. Rank candidates by ``semantic + graph-proximity`` and return each
+           answer with its supporting path (chain of triples) and page refs.
+
+        If ``query_vec`` is given it is used directly; otherwise, when an
+        ``api_key`` is supplied and the graph has vectors, the query is embedded
+        via Gemini (RETRIEVAL_QUERY). With neither, search degrades to lexical.
+        """
+        query = str(query or "").strip()
+        out = {
+            "query": query,
+            "answers": [],
+            "seeds": [],
+            "triples": [],
+            "mode": "lexical",
+        }
+        if not query or not self.nodes:
+            return out
+
+        # Obtain a query vector if we can (don't fail search if embedding fails).
+        if query_vec is None and self.has_vectors and is_configured(api_key):
+            try:
+                mat = embed_texts(
+                    [query],
+                    api_key=api_key,
+                    model=embed_model or self.embed_model,
+                    task_type="RETRIEVAL_QUERY",
+                    timeout=timeout,
+                )
+                if mat.size:
+                    query_vec = mat[0]
+            except RuntimeError:
+                query_vec = None
+
+        sem = self._semantic_scores(query, query_vec)
+        out["mode"] = "semantic" if (self.has_vectors and query_vec is not None) else "lexical"
+        if sem.size == 0 or float(sem.max()) <= 0:
+            return out
+
+        # Seeds = strongest semantic matches.
+        order = np.argsort(-sem)
+        seeds = [int(i) for i in order[:max(1, top_k)] if sem[int(i)] > 0]
+        out["seeds"] = [self.nodes[i]["name"] for i in seeds]
+
+        reach = self._multi_source_paths(seeds, hops=max(0, hops))
+
+        # Rank reachable candidates.
+        W_SEM, W_GRAPH, DECAY = 0.6, 0.4, 0.55
+        scored = []
+        for nid, (dist, src, chain) in reach.items():
+            sim = float(sem[nid])
+            graph_term = float(sem[src]) * (DECAY ** dist)
+            score = W_SEM * sim + W_GRAPH * graph_term
+            scored.append((score, dist, nid, src, chain))
+        scored.sort(key=lambda x: (-x[0], x[1]))
+
+        used_triples: dict = {}
+        for score, dist, nid, src, chain in scored[:max(1, max_results)]:
+            node = self.nodes[nid]
+            path_triples = [self._triple_view(t) for t in chain]
+            path_pages = sorted({t["page"] for t in path_triples if t["page"] is not None})
+            # The entity's own incident facts make even a seed (empty path)
+            # explainable; cap a few of the highest-information ones.
+            fact_idx = [tindex for _, tindex in self.adjacency.get(nid, [])][:6]
+            facts = [self._triple_view(t) for t in fact_idx]
+            for t in list(chain) + fact_idx:
+                used_triples[t] = self._triple_view(t)
+            out["answers"].append(
+                {
+                    "entity": node["name"],
+                    "type": node["type"],
+                    "score": round(float(score), 4),
+                    "similarity": round(float(sem[nid]), 4),
+                    "hops": int(dist),
+                    "pages": sorted(node["pages"]),
+                    "path": path_triples,
+                    "path_pages": path_pages,
+                    "facts": facts,
+                }
+            )
+
+        # Flat, de-duplicated list of every supporting triple referenced above.
+        out["triples"] = list(used_triples.values())
+        return out
+
+    def _triple_view(self, tindex: int) -> dict:
+        t = self.triples[tindex]
+        return {
+            "subject": t["subject"],
+            "predicate": t["predicate"],
+            "object": t["object"],
+            "page": t["page"],
+        }
+
+    # --- serialization (explicit; the graph is NEVER auto-serialized) --------
+    def to_viz_dict(self, max_nodes: int = 120) -> dict:
+        """Compact node/edge lists for the vanilla-canvas visualization.
+
+        Caps to the highest-degree ``max_nodes`` so a huge graph stays drawable
+        (and the dropped count is reported, never silently truncated).
+        """
+        order = sorted(
+            range(len(self.nodes)), key=lambda i: self.nodes[i]["degree"], reverse=True
+        )
+        keep = set(order[:max_nodes])
+        nodes = [
+            {
+                "id": i,
+                "name": self.nodes[i]["name"],
+                "type": self.nodes[i]["type"],
+                "pages": sorted(self.nodes[i]["pages"]),
+                "degree": self.nodes[i]["degree"],
+            }
+            for i in sorted(keep)
+        ]
+        edges = [
+            {
+                "source": t["subject_id"],
+                "target": t["object_id"],
+                "predicate": t["predicate"],
+                "page": t["page"],
+            }
+            for t in self.triples
+            if t["subject_id"] in keep and t["object_id"] in keep
+        ]
+        return {
+            "nodes": nodes,
+            "edges": edges,
+            "total_nodes": len(self.nodes),
+            "total_edges": len(self.triples),
+            "truncated": len(self.nodes) > len(keep),
+        }
+
+    def to_export_dict(self) -> dict:
+        """Full graph for the .kg.json export (entities + triples + provenance)."""
+        return {
+            "entities": [
+                {"name": n["name"], "type": n["type"], "pages": sorted(n["pages"])}
+                for n in self.nodes
+            ],
+            "triples": [self._triple_view(i) for i in range(len(self.triples))],
+            "node_count": len(self.nodes),
+            "triple_count": len(self.triples),
+            "embed_model": self.embed_model,
+        }
+
+
+def build_graph(
+    pages,
+    *,
+    api_key,
+    triple_model=None,
+    embed_model=None,
+    max_pages: Optional[int] = None,
+    embed: bool = True,
+    timeout: float = 120,
+) -> KnowledgeGraph:
+    """Build a per-document :class:`KnowledgeGraph` from extracted page text.
+
+    Parameters
+    ----------
+    pages : list[tuple[int, str]]
+        ``(page_number, text)`` pairs — typically
+        ``[(p.page, p.text) for p in job.pages if p.status == "done"]``.
+    api_key : str
+        A Gemini API key (required; this is the opt-in online feature).
+    triple_model, embed_model : str, optional
+        Model overrides; default to Flash + text-embedding-004.
+    max_pages : int, optional
+        Cap the number of non-empty pages processed (cost control). None = all.
+    embed : bool
+        If True (default) also embed the nodes so semantic search works; if
+        False the graph supports lexical search only (cheaper).
+
+    Returns a graph (possibly empty if the document yields no facts). Raises a
+    single-line RuntimeError only for a missing key or a hard Gemini failure.
+    """
+    if not is_configured(api_key):
+        raise RuntimeError(
+            "Building a knowledge graph needs a Gemini API key. Enter your free "
+            "key from https://aistudio.google.com/, or use the demo key."
+        )
+
+    usable = [(int(pn), str(txt or "")) for pn, txt in pages if str(txt or "").strip()]
+    if max_pages is not None and max_pages > 0:
+        usable = usable[:max_pages]
+
+    graph = KnowledgeGraph()
+    for page_no, text in usable:
+        data = extract_triples(text, api_key=api_key, model=triple_model, timeout=timeout)
+        # Register typed entities first so types are known, then triples.
+        for e in data.get("entities", []):
+            graph._add_node(e["name"], e.get("type", "OTHER"), page=page_no)
+        for t in data.get("triples", []):
+            graph._add_triple(t["subject"], t["predicate"], t["object"], page=page_no)
+
+    if embed and graph.num_nodes:
+        node_texts = [graph._node_embed_text(i) for i in range(graph.num_nodes)]
+        vectors = embed_texts(
+            node_texts,
+            api_key=api_key,
+            model=embed_model,
+            task_type="RETRIEVAL_DOCUMENT",
+            timeout=timeout,
+        )
+        graph.set_vectors(vectors, model=_resolve_model(embed_model, DEFAULT_EMBED_MODEL))
+
+    return graph

static/app.js

@@ -724,6 +724,22 @@
       progressLabel: frag.querySelector('[data-role="progressLabel"]'),
       fileError: frag.querySelector('[data-role="fileError"]'),
       pages: frag.querySelector('[data-role="pages"]'),
+      // Knowledge graph hooks (all optional; present only in newer markup).
+      kgPanel: frag.querySelector('[data-role="kgPanel"]'),
+      kgStatus: frag.querySelector('[data-role="kgStatus"]'),
+      kgBuildBtn: frag.querySelector('[data-role="kgBuildBtn"]'),
+      kgBuildNote: frag.querySelector('[data-role="kgBuildNote"]'),
+      kgQueryWrap: frag.querySelector('[data-role="kgQueryWrap"]'),
+      kgQueryInput: frag.querySelector('[data-role="kgQueryInput"]'),
+      kgAskBtn: frag.querySelector('[data-role="kgAskBtn"]'),
+      kgResults: frag.querySelector('[data-role="kgResults"]'),
+      kgTools: frag.querySelector('[data-role="kgVizToggle"]'),
+      kgVizToggle: frag.querySelector('[data-role="kgVizToggle"]'),
+      kgExportBtn: frag.querySelector('[data-role="kgExportBtn"]'),
+      kgRebuildBtn: frag.querySelector('[data-role="kgRebuildBtn"]'),
+      kgVizWrap: frag.querySelector('[data-role="kgVizWrap"]'),
+      kgCanvas: frag.querySelector('[data-role="kgCanvas"]'),
+      kgVizNote: frag.querySelector('[data-role="kgVizNote"]'),
     };
     el.fileName.textContent = meta.filename;
 
@@ -739,6 +755,7 @@
 
     el.cancelBtn.addEventListener("click", () => cancelJob(job));
     if (el.removeBtn) el.removeBtn.addEventListener("click", () => removeJob(job));
+    setupKnowledgeGraph(job);
 
     jobs.set(job.jobId, job);
     jobOrder.push(job.jobId);
@@ -778,6 +795,11 @@
     if (status === "done" || status === "error" || status === "cancelled") {
       job.el.cancelBtn.disabled = true;
     }
+    // Reveal the knowledge-graph panel once extraction has finished (there is
+    // now text to build from). Only on a successful run.
+    if (status === "done" && job.el && job.el.kgPanel) {
+      job.el.kgPanel.hidden = false;
+    }
   }
 
   function updateProgress(job, processed, total) {
@@ -1084,6 +1106,407 @@
     // Export/copy always available once there is at least one job; nothing to gate.
   }
 
+  // ---------- Knowledge graph (opt-in, online) ----------
+  // Colors per entity type; chosen to read on both light & dark themes. Used
+  // for the result-card dots/chips AND the canvas nodes so the two views match.
+  const KG_TYPE_COLORS = {
+    PERSON: "#7c3aed", ORG: "#0ea5b7", PLACE: "#0e9f6e", DATE: "#c2790f",
+    ID: "#e0455c", AMOUNT: "#2563eb", CONCEPT: "#9333ea", EVENT: "#db2777",
+    OTHER: "#8a8a99",
+  };
+  function kgTypeColor(t) {
+    return KG_TYPE_COLORS[String(t || "OTHER").toUpperCase()] || KG_TYPE_COLORS.OTHER;
+  }
+
+  function setupKnowledgeGraph(job) {
+    const el = job.el;
+    if (!el || !el.kgPanel) return; // older markup without the KG panel
+    job.kgBuilt = false;
+    job.kgViz = null;
+    job.kgLaidOut = false;
+
+    if (el.kgBuildBtn) el.kgBuildBtn.addEventListener("click", () => buildKG(job));
+    if (el.kgRebuildBtn) el.kgRebuildBtn.addEventListener("click", () => buildKG(job));
+    if (el.kgAskBtn) el.kgAskBtn.addEventListener("click", () => askKG(job));
+    if (el.kgQueryInput) {
+      el.kgQueryInput.addEventListener("keydown", (e) => {
+        if (e.key === "Enter") { e.preventDefault(); askKG(job); }
+      });
+    }
+    if (el.kgExportBtn) el.kgExportBtn.addEventListener("click", () => exportKG(job));
+    if (el.kgVizToggle) el.kgVizToggle.addEventListener("click", () => toggleKGViz(job));
+  }
+
+  function setKgStatus(job, msg, kind) {
+    const s = job.el.kgStatus;
+    if (!s) return;
+    s.textContent = msg || "";
+    s.className = "kg-summary-status" + (kind ? " " + kind : "");
+  }
+
+  async function buildKG(job) {
+    const el = job.el;
+    el.kgPanel.open = true;
+    if (el.kgBuildBtn) el.kgBuildBtn.disabled = true;
+    if (el.kgRebuildBtn) el.kgRebuildBtn.disabled = true;
+    setKgStatus(job, "Building…", "busy");
+    el.kgBuildNote.textContent = "Reading entities & facts with Gemini — this can take a moment on a long document…";
+
+    const form = new FormData();
+    form.append("job_id", job.jobId);
+    form.append("online_key", settings.online_key || "");
+    form.append("online_model", settings.online_model || "");
+    try {
+      const res = await fetch("/api/graph/build", { method: "POST", body: form });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        if (el.kgBuildBtn) { el.kgBuildBtn.disabled = false; el.kgBuildBtn.hidden = false; }
+        if (el.kgRebuildBtn) el.kgRebuildBtn.disabled = false;
+        setKgStatus(job, "Failed", "bad");
+        el.kgBuildNote.textContent = data.detail ? humanizeError(data.detail) : "Build failed.";
+        return;
+      }
+      job.kgBuilt = true;
+      job.kgViz = null;
+      job.kgLaidOut = false;
+      if (el.kgRebuildBtn) el.kgRebuildBtn.disabled = false;
+      // Hide any previously open viz so it re-fetches the new graph next open.
+      if (el.kgVizWrap) el.kgVizWrap.hidden = true;
+      if (el.kgVizToggle) el.kgVizToggle.textContent = "Show graph view";
+
+      if (!data.nodes) {
+        setKgStatus(job, "No entities found", "");
+        el.kgBuildNote.textContent =
+          "Gemini found no extractable entities/facts in this document's text.";
+        if (el.kgBuildBtn) { el.kgBuildBtn.disabled = false; el.kgBuildBtn.hidden = false; el.kgBuildBtn.textContent = "Try again"; }
+        el.kgQueryWrap.hidden = true;
+        return;
+      }
+      setKgStatus(job, data.nodes + " entities · " + data.edges + " facts", "good");
+      el.kgBuildNote.textContent =
+        data.has_vectors
+          ? "Graph ready — ask a question below (semantic + graph search)."
+          : "Graph ready — ask a question below (graph search).";
+      if (el.kgBuildBtn) el.kgBuildBtn.hidden = true;
+      el.kgQueryWrap.hidden = false;
+      showToast("Knowledge graph: " + data.nodes + " entities, " + data.edges + " facts");
+      if (el.kgQueryInput) el.kgQueryInput.focus();
+    } catch (e) {
+      if (el.kgBuildBtn) { el.kgBuildBtn.disabled = false; el.kgBuildBtn.hidden = false; }
+      if (el.kgRebuildBtn) el.kgRebuildBtn.disabled = false;
+      setKgStatus(job, "Failed", "bad");
+      el.kgBuildNote.textContent = "Network error during build.";
+    }
+  }
+
+  async function askKG(job) {
+    const el = job.el;
+    const q = (el.kgQueryInput.value || "").trim();
+    if (!q) return;
+    el.kgAskBtn.disabled = true;
+    el.kgResults.innerHTML = "";
+    const loading = document.createElement("p");
+    loading.className = "kg-empty";
+    loading.textContent = "Searching…";
+    el.kgResults.appendChild(loading);
+
+    const form = new FormData();
+    form.append("job_id", job.jobId);
+    form.append("query", q);
+    form.append("online_key", settings.online_key || "");
+    try {
+      const res = await fetch("/api/graph/query", { method: "POST", body: form });
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        renderKgMessage(job, data.detail ? humanizeError(data.detail) : "Query failed.");
+        return;
+      }
+      renderKGResults(job, data);
+    } catch (e) {
+      renderKgMessage(job, "Network error during search.");
+    } finally {
+      el.kgAskBtn.disabled = false;
+    }
+  }
+
+  function renderKgMessage(job, msg) {
+    const c = job.el.kgResults;
+    c.innerHTML = "";
+    const p = document.createElement("p");
+    p.className = "kg-empty";
+    p.textContent = msg;
+    c.appendChild(p);
+  }
+
+  // Build a "p.1, 2" provenance chip element.
+  function kgPageTag(pages) {
+    const tag = document.createElement("span");
+    tag.className = "kg-pages";
+    const list = (pages || []).filter((p) => p != null);
+    tag.textContent = list.length
+      ? (list.length === 1 ? "p." + list[0] : "p." + list.join(", "))
+      : "";
+    if (!list.length) tag.hidden = true;
+    return tag;
+  }
+
+  // Render one triple as "subject → predicate → object" with a page tag.
+  function kgTripleRow(t) {
+    const row = document.createElement("div");
+    row.className = "kg-triple";
+    const s = document.createElement("span"); s.className = "kg-subj"; s.textContent = t.subject;
+    const p = document.createElement("span"); p.className = "kg-pred"; p.textContent = t.predicate;
+    const o = document.createElement("span"); o.className = "kg-obj"; o.textContent = t.object;
+    const a1 = document.createElement("span"); a1.className = "kg-arrow"; a1.textContent = "→";
+    const a2 = document.createElement("span"); a2.className = "kg-arrow"; a2.textContent = "→";
+    row.appendChild(s); row.appendChild(a1); row.appendChild(p); row.appendChild(a2); row.appendChild(o);
+    if (t.page != null) {
+      const pg = document.createElement("span");
+      pg.className = "kg-pages kg-triple-page";
+      pg.textContent = "p." + t.page;
+      row.appendChild(pg);
+    }
+    return row;
+  }
+
+  function renderKGResults(job, data) {
+    const c = job.el.kgResults;
+    c.innerHTML = "";
+
+    const meta = document.createElement("div");
+    meta.className = "kg-resultmeta";
+    const modeTxt = data.mode === "semantic" ? "semantic + graph" : "graph (lexical)";
+    meta.textContent = (data.answers || []).length
+      ? "Top matches · " + modeTxt + " search"
+      : "";
+    if (meta.textContent) c.appendChild(meta);
+
+    if (!data.answers || !data.answers.length) {
+      renderKgMessage(job, "No matching entities found. Try different words.");
+      // keep the meta line removed for a clean empty state
+      return;
+    }
+
+    data.answers.forEach((a) => {
+      const card = document.createElement("div");
+      card.className = "kg-answer";
+
+      const head = document.createElement("div");
+      head.className = "kg-answer-head";
+      const dot = document.createElement("span");
+      dot.className = "kg-type-dot";
+      dot.style.background = kgTypeColor(a.type);
+      const name = document.createElement("span");
+      name.className = "kg-entity";
+      name.textContent = a.entity;
+      const chip = document.createElement("span");
+      chip.className = "kg-type-chip";
+      chip.textContent = (a.type || "OTHER").toLowerCase();
+      chip.style.color = kgTypeColor(a.type);
+      head.appendChild(dot);
+      head.appendChild(name);
+      head.appendChild(chip);
+      head.appendChild(kgPageTag(a.pages));
+      card.appendChild(head);
+
+      // Supporting facts (the entity's own triples) — the explainable evidence.
+      const facts = (a.facts && a.facts.length) ? a.facts : a.path;
+      if (facts && facts.length) {
+        const fwrap = document.createElement("div");
+        fwrap.className = "kg-facts";
+        facts.slice(0, 6).forEach((t) => fwrap.appendChild(kgTripleRow(t)));
+        card.appendChild(fwrap);
+      }
+
+      // If reached via traversal, show the connecting chain from the query seed.
+      if (a.hops > 0 && a.path && a.path.length) {
+        const link = document.createElement("div");
+        link.className = "kg-linkpath";
+        const lbl = document.createElement("span");
+        lbl.className = "kg-link-label";
+        lbl.textContent = "linked to your query via:";
+        link.appendChild(lbl);
+        a.path.forEach((t) => link.appendChild(kgTripleRow(t)));
+        card.appendChild(link);
+      }
+
+      c.appendChild(card);
+    });
+  }
+
+  // ----- Graph visualization (vanilla canvas; no external libs) -----
+  async function toggleKGViz(job) {
+    const el = job.el;
+    if (!el.kgVizWrap) return;
+    if (!el.kgVizWrap.hidden) {
+      el.kgVizWrap.hidden = true;
+      el.kgVizToggle.textContent = "Show graph view";
+      return;
+    }
+    el.kgVizWrap.hidden = false;
+    el.kgVizToggle.textContent = "Hide graph view";
+    if (!job.kgViz) {
+      el.kgVizNote.textContent = "Loading graph…";
+      try {
+        const res = await fetch("/api/graph/" + encodeURIComponent(job.jobId));
+        const data = await res.json();
+        if (!res.ok || !data.nodes) { el.kgVizNote.textContent = "No graph to show."; return; }
+        job.kgViz = data;
+        job.kgLaidOut = false;
+      } catch (e) {
+        el.kgVizNote.textContent = "Could not load the graph.";
+        return;
+      }
+    }
+    drawKGViz(job);
+  }
+
+  function layoutKG(viz) {
+    // Force-directed layout (Fruchterman–Reingold-ish) in a virtual unit box,
+    // deterministic init so the picture is stable across redraws.
+    const nodes = viz.nodes.map((n, i) => {
+      const ang = (2 * Math.PI * i) / Math.max(1, viz.nodes.length);
+      return { id: n.id, x: 0.5 + 0.35 * Math.cos(ang), y: 0.5 + 0.35 * Math.sin(ang),
+               vx: 0, vy: 0, deg: n.degree || 0, name: n.name, type: n.type };
+    });
+    const index = new Map(nodes.map((n) => [n.id, n]));
+    const edges = viz.edges
+      .map((e) => [index.get(e.source), index.get(e.target)])
+      .filter((p) => p[0] && p[1]);
+
+    const n = nodes.length || 1;
+    const k = 0.9 / Math.sqrt(n);   // ideal edge length
+    let temp = 0.10;
+    const ITER = 220;
+    for (let it = 0; it < ITER; it++) {
+      // repulsion (O(n^2); fine for the capped node count)
+      for (let i = 0; i < nodes.length; i++) {
+        let fx = 0, fy = 0;
+        const a = nodes[i];
+        for (let j = 0; j < nodes.length; j++) {
+          if (i === j) continue;
+          const b = nodes[j];
+          let dx = a.x - b.x, dy = a.y - b.y;
+          let d2 = dx * dx + dy * dy;
+          if (d2 < 1e-6) { dx = (i - j) * 1e-3; dy = 1e-3; d2 = 1e-6; }
+          const f = (k * k) / d2;
+          fx += dx * f; fy += dy * f;
+        }
+        // gravity toward center keeps disconnected nodes on-canvas
+        fx += (0.5 - a.x) * 0.02;
+        fy += (0.5 - a.y) * 0.02;
+        a.vx = fx; a.vy = fy;
+      }
+      // attraction along edges
+      edges.forEach(([a, b]) => {
+        let dx = a.x - b.x, dy = a.y - b.y;
+        const d = Math.sqrt(dx * dx + dy * dy) || 1e-4;
+        const f = (d * d) / k;
+        const ux = (dx / d) * f, uy = (dy / d) * f;
+        a.vx -= ux; a.vy -= uy;
+        b.vx += ux; b.vy += uy;
+      });
+      // integrate with cooling + clamp into the box
+      nodes.forEach((a) => {
+        const sp = Math.sqrt(a.vx * a.vx + a.vy * a.vy) || 1e-6;
+        const step = Math.min(sp, temp) / sp;
+        a.x = Math.max(0.04, Math.min(0.96, a.x + a.vx * step));
+        a.y = Math.max(0.05, Math.min(0.95, a.y + a.vy * step));
+      });
+      temp = Math.max(0.008, temp * 0.985);
+    }
+    return { nodes, edges };
+  }
+
+  function drawKGViz(job) {
+    const el = job.el;
+    const canvas = el.kgCanvas;
+    if (!canvas) return;
+    if (!job.kgLaidOut) {
+      job.kgLayout = layoutKG(job.kgViz);
+      job.kgLaidOut = true;
+    }
+    const layout = job.kgLayout;
+    const cssW = Math.max(280, canvas.clientWidth || canvas.parentElement.clientWidth || 640);
+    const cssH = 400;
+    const dpr = window.devicePixelRatio || 1;
+    canvas.width = Math.round(cssW * dpr);
+    canvas.height = Math.round(cssH * dpr);
+    canvas.style.height = cssH + "px";
+    const ctx = canvas.getContext("2d");
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, cssW, cssH);
+
+    const cs = getComputedStyle(canvas);
+    const textColor = cs.getPropertyValue("--text").trim() || "#222";
+    const edgeColor = cs.getPropertyValue("--border-strong").trim() || "#ccc";
+    const pad = 26;
+    const X = (nx) => pad + nx * (cssW - 2 * pad);
+    const Y = (ny) => pad + ny * (cssH - 2 * pad);
+
+    // edges
+    ctx.lineWidth = 1;
+    ctx.strokeStyle = edgeColor;
+    ctx.globalAlpha = 0.55;
+    layout.edges.forEach(([a, b]) => {
+      ctx.beginPath();
+      ctx.moveTo(X(a.x), Y(a.y));
+      ctx.lineTo(X(b.x), Y(b.y));
+      ctx.stroke();
+    });
+    ctx.globalAlpha = 1;
+
+    // label only the most-connected nodes to avoid clutter
+    const labelled = new Set(
+      layout.nodes.slice().sort((a, b) => b.deg - a.deg).slice(0, 26).map((n) => n.id)
+    );
+    ctx.font = "11px " + (cs.getPropertyValue("--sans").trim() || "sans-serif");
+    ctx.textAlign = "center";
+    ctx.textBaseline = "top";
+    layout.nodes.forEach((nd) => {
+      const r = 4 + Math.min(7, nd.deg * 1.4);
+      ctx.beginPath();
+      ctx.arc(X(nd.x), Y(nd.y), r, 0, 2 * Math.PI);
+      ctx.fillStyle = kgTypeColor(nd.type);
+      ctx.fill();
+      ctx.lineWidth = 1.5;
+      ctx.strokeStyle = "rgba(255,255,255,0.55)";
+      ctx.stroke();
+      if (labelled.has(nd.id)) {
+        const label = nd.name.length > 22 ? nd.name.slice(0, 21) + "…" : nd.name;
+        ctx.fillStyle = textColor;
+        ctx.fillText(label, X(nd.x), Y(nd.y) + r + 2);
+      }
+    });
+
+    const more = job.kgViz.truncated
+      ? " · showing top " + job.kgViz.nodes.length + " of " + job.kgViz.total_nodes
+      : "";
+    el.kgVizNote.textContent =
+      job.kgViz.total_nodes + " entities · " + job.kgViz.total_edges + " facts" + more +
+      " · labels on the most-connected entities";
+  }
+
+  async function exportKG(job) {
+    try {
+      const res = await fetch("/api/graph/" + encodeURIComponent(job.jobId) + "?full=1");
+      if (!res.ok) { showToast("Could not export the graph."); return; }
+      const data = await res.json();
+      const payload = {
+        filename: job.filename,
+        node_count: data.node_count,
+        triple_count: data.triple_count,
+        embed_model: data.embed_model,
+        entities: data.entities,
+        triples: data.triples,
+      };
+      download(baseName([job]) + ".kg.json", JSON.stringify(payload, null, 2), "application/json");
+      showToast("Knowledge graph exported");
+    } catch (e) {
+      showToast("Could not export the graph.");
+    }
+  }
+
   // ---------- Misc ----------
   function humanizeError(detail) {
     const d = String(detail).toLowerCase();

static/index.html

@@ -301,6 +301,42 @@
         <span class="progress-label" data-role="progressLabel">0 / 0</span>
       </div>
       <div class="file-error" data-role="fileError" hidden></div>
+
+      <details class="kg-panel" data-role="kgPanel" hidden>
+        <summary class="kg-summary">
+          <svg class="kg-summary-icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <circle cx="5" cy="6" r="2.4"></circle><circle cx="19" cy="6" r="2.4"></circle><circle cx="12" cy="18" r="2.4"></circle>
+            <line x1="6.9" y1="7.4" x2="10.4" y2="16.2"></line><line x1="17.1" y1="7.4" x2="13.6" y2="16.2"></line><line x1="7" y1="6" x2="17" y2="6"></line>
+          </svg>
+          <span>Knowledge graph &amp; search</span>
+          <span class="kg-summary-status" data-role="kgStatus"></span>
+          <svg class="accordion-chevron kg-chevron" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 9l6 6 6-6"></path></svg>
+        </summary>
+        <div class="kg-body">
+          <p class="hint kg-intro">Turn this document into a searchable graph of its entities &amp; facts, then ask questions and get answers traced back to the exact page. Uses <strong>Google Gemini</strong> (online &mdash; same key as Online OCR).</p>
+          <div class="kg-build-row">
+            <button type="button" class="btn btn-primary btn-sm" data-role="kgBuildBtn">Build knowledge graph</button>
+            <span class="kg-build-note hint" data-role="kgBuildNote"></span>
+          </div>
+          <div class="kg-query-wrap" data-role="kgQueryWrap" hidden>
+            <div class="kg-ask">
+              <input type="search" class="kg-query-input" data-role="kgQueryInput" placeholder="Ask about this document…" autocomplete="off" />
+              <button type="button" class="btn btn-primary btn-sm" data-role="kgAskBtn">Ask</button>
+            </div>
+            <div class="kg-results" data-role="kgResults"></div>
+            <div class="kg-tools">
+              <button type="button" class="btn btn-ghost btn-sm" data-role="kgVizToggle">Show graph view</button>
+              <button type="button" class="btn btn-ghost btn-sm" data-role="kgExportBtn">Export graph (.json)</button>
+              <button type="button" class="btn btn-ghost btn-sm" data-role="kgRebuildBtn">Rebuild</button>
+            </div>
+            <div class="kg-viz-wrap" data-role="kgVizWrap" hidden>
+              <canvas class="kg-canvas" data-role="kgCanvas" width="640" height="400"></canvas>
+              <p class="hint kg-viz-note" data-role="kgVizNote"></p>
+            </div>
+          </div>
+        </div>
+      </details>
+
       <div class="pages" data-role="pages"></div>
     </article>
   </template>

static/styles.css

@@ -531,6 +531,66 @@ html[data-theme="light"] .theme-toggle .icon-moon { display: block; }
 .btn-remove { color: var(--text-dim); font-size: 18px; line-height: 1; padding: 3px 9px; font-weight: 700; box-shadow: none; border-color: transparent; background: transparent; }
 .btn-remove:hover { color: var(--red); background: var(--red-soft); transform: none; }
 
+/* ---------------- Knowledge graph panel (per file card) ---------------- */
+.kg-panel { margin: 0 18px 16px; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface-3); overflow: hidden; }
+.kg-summary {
+  list-style: none; cursor: pointer; user-select: none;
+  display: flex; align-items: center; gap: 9px;
+  padding: 12px 14px; font-size: 13px; font-weight: 650; color: var(--text);
+}
+.kg-summary::-webkit-details-marker { display: none; }
+.kg-summary:hover { color: var(--accent); }
+.kg-summary-icon { color: var(--accent); flex: none; }
+.kg-chevron { color: var(--text-faint); margin-left: 2px; transition: transform var(--t); }
+.kg-panel[open] > .kg-summary .kg-chevron { transform: rotate(180deg); }
+.kg-summary-status { margin-left: auto; font-size: 11.5px; font-weight: 600; color: var(--text-faint); }
+.kg-summary-status.good { color: var(--green); }
+.kg-summary-status.bad { color: var(--red); }
+.kg-summary-status.busy { color: var(--accent); }
+
+.kg-body { padding: 4px 14px 14px; border-top: 1px solid var(--border-soft); }
+.kg-intro { margin: 10px 0 12px; }
+.kg-intro strong { color: var(--accent); }
+.kg-build-row { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; }
+.kg-build-note { margin: 0; flex: 1; min-width: 180px; }
+
+.kg-query-wrap { margin-top: 12px; }
+.kg-ask { display: flex; gap: 8px; }
+.kg-query-input {
+  flex: 1; background: var(--surface); border: 1px solid var(--border); color: var(--text);
+  font: inherit; font-size: 14px; padding: 9px 12px; border-radius: var(--radius-sm);
+  transition: border-color var(--t-fast), box-shadow var(--t-fast);
+}
+.kg-query-input::placeholder { color: var(--text-faint); }
+.kg-query-input:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+
+.kg-results { margin-top: 12px; display: flex; flex-direction: column; gap: 10px; }
+.kg-empty { margin: 4px 0; font-size: 12.5px; color: var(--text-faint); }
+.kg-resultmeta { font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--text-faint); font-weight: 700; }
+
+.kg-answer { border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); padding: 11px 13px; box-shadow: var(--shadow-sm); }
+.kg-answer-head { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.kg-type-dot { width: 9px; height: 9px; border-radius: 50%; flex: none; }
+.kg-entity { font-size: 14px; font-weight: 700; color: var(--text); }
+.kg-type-chip { font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em; border: 1px solid currentColor; border-radius: 999px; padding: 1px 7px; opacity: 0.9; }
+.kg-pages { font-size: 11px; font-weight: 650; color: var(--text-dim); background: var(--surface-3); border: 1px solid var(--border); border-radius: 999px; padding: 1px 8px; font-variant-numeric: tabular-nums; }
+
+.kg-facts { margin-top: 8px; display: flex; flex-direction: column; gap: 4px; }
+.kg-triple { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; font-size: 12.5px; line-height: 1.5; }
+.kg-subj { font-weight: 650; color: var(--text); }
+.kg-pred { color: var(--accent); font-style: italic; }
+.kg-obj { font-weight: 650; color: var(--text); }
+.kg-arrow { color: var(--text-faint); }
+.kg-triple-page { margin-left: 2px; }
+
+.kg-linkpath { margin-top: 9px; padding-top: 8px; border-top: 1px dashed var(--border); display: flex; flex-direction: column; gap: 4px; }
+.kg-link-label { font-size: 10.5px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--text-faint); font-weight: 700; }
+
+.kg-tools { display: flex; gap: 6px; flex-wrap: wrap; margin-top: 12px; }
+.kg-viz-wrap { margin-top: 10px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--surface); padding: 8px; }
+.kg-canvas { width: 100%; display: block; border-radius: var(--radius-sm); background: var(--surface-3); }
+.kg-viz-note { margin: 8px 2px 2px; text-align: center; }
+
 @media (prefers-reduced-motion: reduce) {
   * { transition: none !important; animation: none !important; }
 }