Enhance PDF reading capabilities and improve agent response handling

- Introduced a new `PdfReadRequest` model to facilitate explicit PDF read actions from the UI, ensuring structured input for PDF-related queries.
- Updated the agent's request handling to incorporate `pdf_read_request`, allowing for better management of user intent regarding PDF reading.
- Enhanced the `build_agent_request_turn_context` function to process PDF read requests, integrating them into the agent's decision-making process.
- Implemented fallback mechanisms for handling PDF read failures, improving user feedback and citation enrichment based on PDF read results.
- Updated various components to support the new PDF reading features, including state management and response generation, ensuring a cohesive user experience.

Author: xabarov

docs/analysis/external-research-tools-implementation-review-2026-05-15.md

@@ -634,3 +634,15 @@ The architecture is in good shape. The next improvement should be either:
 
 **Execution detail:** Phase 3 **closeout** (optional OpenAlex live smoke, diagnostics `status` decision) and Phase 4 **staged delivery** (PDF artifact pipeline → SSE → trust → Ask UI → live matrix) are spelled out in `docs/analysis/external-research-tools-workplan-2026-05-15.md` (Phase 3 **Remaining / Closeout**, Phase 4 Stages 1–8, PR slicing PR 4b–PR 9).
 
+## Phase 4 honest closure (2026-05-15) — shipped in repo
+
+- **Typed API:** `PdfReadRequest` + relaxed `question` when `pdf_read_request` is present; machine token `__sg_pdf_read_action__` replaces legacy `"[pdf-read-action]"` in the canonical path.
+- **Orchestrator:** `pdf_read_orchestrator.execute_pdf_read` is the single fetch/parse/cache path for `read_external_pdf` and optional SSE prefetch (`pdf_read_validating` / `pdf_read_downloading` / `pdf_read_extracting`) before the LangGraph stream.
+- **Pipeline/cache:** `pdf_read_pipeline` (policy + fetch + parse), `BoundedTtlPdfReadCache` (LRU + TTL), operator knob `agent_pdf_read_cache_max_entries` (Settings + snapshot + PATCH allowlist).
+- **Policy:** `EXTERNAL_RESEARCH_WEB_TOOL_NAMES` vs `read_external_pdf`; explicit `pdf_read_request` bypasses web-research denylist for PDF only; `pdf_reading_mode=off` blocks agent PDF unless explicit request; LLM `allowed_domains` / `blocked_domains` on the tool are ignored (server policy).
+- **Evidence:** PDF success uses `evidence_quality=variable`; failed `read_external_pdf` hydrates citations like `web_fetch` / `unpaywall` failures.
+- **UI:** Native token + i18n user-turn label; pdf-only submit; product-step strings for PDF prefetch.
+- **Live matrix:** Operator checklist in `scripts/live_check/pdf_read_live_matrix.md` (after `make dev-up` + `config-check`).
+
+**Residual:** durable artifact store / DB-backed job IDs beyond in-process cache — see `docs/backlog/refactor-backend.md` for follow-up.
+

docs/analysis/external-research-tools-workplan-2026-05-15.md

@@ -355,6 +355,8 @@ flowchart TD
 
 ### Acceptance (Phase 4)
 
+**Status (2026-05-15):** Core backend+UI path shipped — typed `pdf_read_request`, `execute_pdf_read` orchestrator, bounded LRU+TTL cache, SSE prefetch steps, denylist/`pdf_reading_mode` alignment, citation hydration on PDF failures, variable evidence quality, Ask UI token+i18n. Durable cross-process artifact persistence remains backlog (see implementation review “Phase 4 honest closure”).
+
 - Explicit PDF read produces visible progress + persisted artifact + answer grounded in extracted evidence with correct trust labels.
 - Agent never silently claims full-text reading when extraction did not run or failed.
 

docs/backlog/refactor-backend.md

@@ -240,3 +240,9 @@ Sequencing after **SSE stream lifecycle split** (`stream_lifecycle.py` + `stream
 - **Acceptance:** httpx-mocked unit tests, manifest/registry sync tests, product_step mapping, documented per-tool denylist/toggle; optional live smoke when key/rate limits allow.
 - **Raised:** 2026-05-15, **updated:** 2026-05-15 (OpenAlex search split out as delivered; backlog tracks Semantic Scholar only)
 
+### [OPEN] Durable PDF read artifacts (cross-process)
+- **Area:** `science_graphrag/agent/tools/external/pdf_read_*`, future `stores/` or Postgres
+- **Issue:** Phase 4 ships in-process LRU+TTL cache and optional prefetch job bookkeeping only; workers lose cache on restart and there is no durable artifact row for audit/replay.
+- **Proposal:** add persisted artifact metadata (url hash, sizes, status, excerpt pointer) keyed by `parent_turn_id` / workspace; optional object storage for raw bytes; align GC with operator TTL knobs.
+- **Acceptance:** repeat read after cold start hits persisted excerpt or cleanly refetches; trace-review shows stable `artifact_id`; repository unit tests.
+- **Raised:** 2026-05-15

docs/specs/frontend-ui-api-contracts-v1.md

@@ -442,3 +442,22 @@ Implementation: [`science_graphrag/api/workspace_graph/router.py`](../../science
 
 - **`progress_pct`**: `float | null` (0..1) — взвешенный прогресс по стадиям (running = 0.5 веса), чтобы UI рисовал общий бар без «рваных» процентов.
 - **`stages[i].expected_duration_ms`**: `int | null` — средняя длительность стадии по последним успешным jobs (Postgres), подсказка для ETA на фронте.
+
+## 7) Settings — LLM snapshot (Settings page)
+
+Реализация: `GET/PATCH /v1/settings/llm`, `DELETE /v1/settings/llm/secret`, `DELETE /v1/settings/llm/vision-secret` в [`science_graphrag/api/settings.py`](../../science_graphrag/api/settings.py); снимок материализуется через [`science_graphrag/settings/snapshot_llm.py`](../../science_graphrag/settings/snapshot_llm.py) и [`science_graphrag/settings/llm_runtime.py`](../../science_graphrag/settings/llm_runtime.py).
+
+**`GET /v1/settings`** — в `llm` помимо `status`, `effective`, `advanced_controls` ожидаются:
+
+- **`tasks`**: нормализованные профили задач (`extraction`, `chat`, `vision`, `embeddings`) с полями модели и **masked** метаданными ключа (`source`, опционально `masked`).
+- **`diagnostics`**: операторский блок (`operator_env_variables`, `notes`) — для раскрываемой секции «для операторов», не для основного UX.
+
+**`PATCH /v1/settings/llm`** — тело включает обязательные поля провайдера (`base_url`, `model`, `temperature`, `timeout_seconds`) и опционально:
+
+- **`chat_model`**, **`vl_model`**, **`vl_base_url`** — клиент может опускать поля, если persisted значение не меняется (рекомендуемый контракт для UI: не «материализовать» унаследованные из env дефолты в JSON при сохранении несвязанных полей).
+- **`api_key`** — сохраняется в server secret store как основной OpenAI-compatible ключ.
+- **`vision_api_key`** — отдельный UI-managed ключ для PDF/Vision; пустая строка может трактоваться как сброс override (см. обработку в API).
+
+**`DELETE /v1/settings/llm/vision-secret`** — удаляет только vault-запись vision-ключа; основной `llm.api_key` и прочие поля не трогаются. После удаления effective vision снова наследует env/default по правилам resolver.
+
+Клиент: `ui/src/pages/SettingsPage/settingsApi.js` (`deleteLlmVisionSecret`, `updateLlmSettings`).

science_graphrag/agent/citation_enrichment.py

@@ -328,6 +328,60 @@ def _attach_unpaywall_lookup_failures_from_messages(
             c["fallback_message"] = msg_txt
 
 
+def _attach_read_external_pdf_failures_from_messages(
+    citations: list[dict[str, Any]],
+    messages: list[Any] | None,
+) -> None:
+    """Attach fallback hints when ``read_external_pdf`` failed (URL-keyed like ``web_fetch``)."""
+
+    failures: dict[str, tuple[str, str, str]] = {}
+    for payload in _iter_tool_payload_dicts(messages, tool_name="read_external_pdf"):
+        if payload.get("ok") is not False:
+            continue
+        err = payload.get("error")
+        reason = normalize_tool_error_to_fallback_reason(str(err) if err is not None else None)
+        if not reason:
+            reason = FALLBACK_UNKNOWN
+        msg_txt = human_fallback_message(reason)
+        url = str(payload.get("url") or "").strip()
+        hint = payload.get("sse_hint")
+        if isinstance(hint, dict) and not url:
+            url = str(hint.get("url") or "").strip()
+        if not url:
+            continue
+        failures[_url_match_key(url)] = (reason, msg_txt, url)
+
+    if not failures:
+        return
+
+    existing = {_url_match_key(str(c.get("url") or "")) for c in citations if isinstance(c, dict)}
+    for key, (reason, msg_txt, display_url) in failures.items():
+        if key and key not in existing:
+            citations.append(
+                {
+                    "source_type": "web",
+                    "url": display_url,
+                    "title": display_url,
+                    "source_tool": "read_external_pdf",
+                    "fallback_reason": reason,
+                    "fallback_message": msg_txt,
+                }
+            )
+            existing.add(key)
+
+    for c in citations:
+        if not isinstance(c, dict) or not citation_is_web_evidence(c):
+            continue
+        key = _url_match_key(str(c.get("url") or ""))
+        if not key or key not in failures:
+            continue
+        reason, msg_txt, _disp = failures[key]
+        if not str(c.get("fallback_reason") or "").strip():
+            c["fallback_reason"] = reason
+        if not str(c.get("fallback_message") or "").strip():
+            c["fallback_message"] = msg_txt
+
+
 def _attach_web_fetch_failures_from_messages(
     citations: list[dict[str, Any]],
     messages: list[Any] | None,
@@ -581,6 +635,7 @@ def hydrate_citations_for_ui(
     merge_paper_profile_abstracts_into_citations(merged, abstracts)
     _merge_web_sources_into_citations(merged, list(web_sources or []), max_web=8)
     _attach_web_fetch_failures_from_messages(merged, messages)
+    _attach_read_external_pdf_failures_from_messages(merged, messages)
     _attach_unpaywall_lookup_failures_from_messages(merged, messages)
     _attach_doi_resolver_provenance_from_messages(merged, messages)
     apply_trust_labels_to_citations(merged)

science_graphrag/agent/evidence_trust.py

@@ -121,6 +121,7 @@ def normalize_tool_error_to_fallback_reason(error: str | None) -> str | None:
         "doi_parse_failed": FALLBACK_METADATA_ONLY_FALLBACK,
         "invalid_doi": FALLBACK_METADATA_ONLY_FALLBACK,
         "host_not_allowed": FALLBACK_HOST_NOT_ALLOWED,
+        "private_host_not_allowed": FALLBACK_HOST_NOT_ALLOWED,
         "unsupported_scheme": FALLBACK_HOST_NOT_ALLOWED,
         "redirect_host_not_allowed": FALLBACK_REDIRECT_BLOCKED,
         "redirect_unsupported_scheme": FALLBACK_REDIRECT_BLOCKED,
@@ -160,9 +161,7 @@ def human_fallback_message(reason: str | None) -> str:
         FALLBACK_PDF_TOO_LARGE: "PDF exceeds configured size limit.",
         FALLBACK_PDF_PARSE_FAILED: "PDF text extraction failed.",
         FALLBACK_PDF_PAGE_LIMIT: "PDF exceeds configured page limit.",
-        FALLBACK_UNSUPPORTED_PDF_TEXT: (
-            "PDF full-text extraction is not available here."
-        ),
+        FALLBACK_UNSUPPORTED_PDF_TEXT: ("PDF full-text extraction is not available here."),
         FALLBACK_UNKNOWN: "A tool step failed; see trace for details.",
     }.get(reason, "Evidence step failed; see trace for details.")
 
@@ -204,7 +203,7 @@ def trust_fields_for_web_source_row(row: dict[str, Any]) -> dict[str, Any]:
     if st == "read_external_pdf":
         return {
             "provenance_kind": PROVENANCE_EXTRACTED_PDF_TEXT,
-            "evidence_quality": EVIDENCE_STRONG,
+            "evidence_quality": EVIDENCE_VARIABLE,
             "evidence_mode": MODE_PDF_READ,
             "is_external": True,
         }
@@ -289,7 +288,7 @@ def apply_trust_labels_to_citations(citations: list[dict[str, Any]]) -> None:
             or str(c.get("evidence_mode") or "").strip() == MODE_PDF_READ
         ):
             c.setdefault("provenance_kind", PROVENANCE_EXTRACTED_PDF_TEXT)
-            c.setdefault("evidence_quality", EVIDENCE_STRONG)
+            c.setdefault("evidence_quality", EVIDENCE_VARIABLE)
             c.setdefault("evidence_mode", MODE_PDF_READ)
             c.setdefault("is_external", False)
             continue

science_graphrag/agent/graph/state.py

@@ -11,6 +11,7 @@
 from langgraph.graph.message import add_messages
 
 from science_graphrag.agent.request_turn_policy import utc_now_iso_z
+from science_graphrag.agent.tools.external.pdf_read_pipeline import sanitize_pdf_url_for_prompt
 from science_graphrag.config import Settings, get_settings
 
 
@@ -135,10 +136,11 @@ def build_initial_agent_state(
     if isinstance(pdf_read_request, dict):
         pdf_url = str(pdf_read_request.get("pdf_url") or "").strip()
         if pdf_url:
+            safe = sanitize_pdf_url_for_prompt(pdf_url)
             pdf_read_block = (
                 "<pdf_read_request>\n"
                 "User explicitly requested reading this external PDF via tool call.\n"
-                f"- pdf_url: {pdf_url}\n"
+                f"- pdf_url: {safe}\n"
                 "</pdf_read_request>"
             )
     rp_block: str | None = None

science_graphrag/agent/pdf_read_contract.py

@@ -0,0 +1,12 @@
+"""Stable client/server contract tokens for explicit PDF-read turns (Ask UI + API v2)."""
+
+from __future__ import annotations
+
+# Machine token persisted as the user "question" for PDF-only turns; UI must not surface raw.
+PDF_READ_USER_MESSAGE_TOKEN = "__sg_pdf_read_action__"
+
+# Default excerpt budget for read_external_pdf (tool schema + API prefetch).
+# Keep aligned with ReadExternalPdfArgs defaults in pdf_read_tools.
+PDF_READ_DEFAULT_EXCERPT_CHARS = 6000
+
+__all__ = ["PDF_READ_DEFAULT_EXCERPT_CHARS", "PDF_READ_USER_MESSAGE_TOKEN"]

science_graphrag/agent/request_turn_policy.py

@@ -13,6 +13,7 @@
     seed_research_plan_if_empty,
 )
 from science_graphrag.agent.context.session_backend import get_session_memory_backend
+from science_graphrag.agent.pdf_read_contract import PDF_READ_USER_MESSAGE_TOKEN
 from science_graphrag.config import Settings
 from science_graphrag.external_intent_markers import (
     ARXIV_MARKERS,
@@ -30,6 +31,10 @@
         "read_external_pdf",
     }
 )
+# External HTTP tools denied when the user disables web research (PDF is gated separately).
+EXTERNAL_RESEARCH_WEB_TOOL_NAMES: frozenset[str] = frozenset(
+    EXTERNAL_RESEARCH_TOOL_NAMES - frozenset({"read_external_pdf"})
+)
 WEB_RESEARCH_TOOL_NAMES: frozenset[str] = EXTERNAL_RESEARCH_TOOL_NAMES
 
 AgentUiMode = Literal["agent", "plan"]
@@ -66,6 +71,7 @@ def build_agent_request_turn_context(
     question: str | None = None,
     web_research_enabled: bool | None,
     agent_mode: str,
+    pdf_read_request: dict[str, Any] | None = None,
 ) -> AgentRequestTurnContext:
     """Apply session plan_mode start-of-turn + compute denylist and transparency metadata."""
     mode = (agent_mode or "agent").strip().lower()
@@ -89,14 +95,27 @@ def build_agent_request_turn_context(
         default_when_unspecified=bool(settings.external_research_default_enabled),
     )
     warn_req.extend(compute_request_warnings(settings, web_research_user_enabled=user_web))
-    tdl = compute_turn_tool_denylist(settings, web_research_user_enabled=user_web)
+    explicit_pdf = bool(
+        isinstance(pdf_read_request, dict) and str(pdf_read_request.get("pdf_url") or "").strip()
+    )
+    q_raw = str(question or "").strip()
+    explicit_pdf_only_turn = explicit_pdf and (
+        not q_raw or q_raw == PDF_READ_USER_MESSAGE_TOKEN or q_raw == "[pdf-read-action]"
+    )
+    tdl = compute_turn_tool_denylist(
+        settings,
+        web_research_user_enabled=user_web,
+        explicit_pdf_read_request=explicit_pdf,
+        explicit_pdf_only_turn=explicit_pdf_only_turn,
+    )
     frag = build_request_run_metadata_fragment(
         settings,
         web_research_enabled=web_research_enabled,
         agent_mode=mode,
         turn_tool_denylist=tdl,
         request_warnings=warn_req,
         external_research_default_enabled=bool(settings.external_research_default_enabled),
+        request_pdf_reading_mode=str(getattr(settings, "pdf_reading_mode", "ask") or "ask"),
     )
     return AgentRequestTurnContext(
         mode=mode,
@@ -130,13 +149,23 @@ def compute_turn_tool_denylist(
     settings: Settings,
     *,
     web_research_user_enabled: bool,
+    explicit_pdf_read_request: bool = False,
+    explicit_pdf_only_turn: bool = False,
 ) -> list[str]:
-    """Tool names denied for this turn when the user disables external HTTP research.
-
-    Covers Crossref/arXiv/Unpaywall/OpenAlex tools (see ``EXTERNAL_RESEARCH_TOOL_NAMES``).
-    """
-    _ = settings
-    return sorted(EXTERNAL_RESEARCH_TOOL_NAMES) if not web_research_user_enabled else []
+    """Compute per-turn tool denylist (web research toggle + PDF policy + operator gates)."""
+    deny: set[str] = set()
+    if explicit_pdf_only_turn:
+        deny.update(EXTERNAL_RESEARCH_WEB_TOOL_NAMES)
+    if not web_research_user_enabled:
+        deny.update(EXTERNAL_RESEARCH_WEB_TOOL_NAMES)
+        if not explicit_pdf_read_request:
+            deny.add("read_external_pdf")
+    if not bool(getattr(settings, "agent_pdf_read_tool_enabled", True)):
+        deny.add("read_external_pdf")
+    pdf_mode = str(getattr(settings, "pdf_reading_mode", "ask") or "ask").strip().lower()
+    if pdf_mode == "off" and not explicit_pdf_read_request:
+        deny.add("read_external_pdf")
+    return sorted(deny)
 
 
 def compute_request_warnings(
@@ -210,25 +239,30 @@ def build_request_run_metadata_fragment(
     turn_tool_denylist: list[str],
     request_warnings: list[str],
     external_research_default_enabled: bool = True,
+    request_pdf_reading_mode: str | None = None,
 ) -> dict[str, Any]:
     """Small fragment merged into run_metadata for UI transparency."""
     user_on = effective_web_research_user_enabled(
         web_research_enabled,
         default_when_unspecified=bool(external_research_default_enabled),
     )
     _ = settings
-    return {
+    out: dict[str, Any] = {
         "request_web_research_enabled": web_research_enabled,
         "effective_web_research_user_enabled": user_on,
         "effective_web_research_tools": bool(user_on),
         "request_agent_mode": (agent_mode or "agent").strip().lower(),
         "turn_tool_denylist": list(turn_tool_denylist),
         "request_turn_warnings": list(request_warnings),
     }
+    if request_pdf_reading_mode:
+        out["request_pdf_reading_mode"] = str(request_pdf_reading_mode).strip().lower()
+    return out
 
 
 __all__ = [
     "EXTERNAL_RESEARCH_TOOL_NAMES",
+    "EXTERNAL_RESEARCH_WEB_TOOL_NAMES",
     "WEB_RESEARCH_TOOL_NAMES",
     "AgentRequestTurnContext",
     "AgentUiMode",

science_graphrag/agent/runtime.py

@@ -246,6 +246,7 @@ def _run_langgraph(  # pylint: disable=too-many-locals
             question=question,
             web_research_enabled=web_research_enabled,
             agent_mode=agent_mode,
+            pdf_read_request=pdf_read_request,
         )
         try:
             return self._run_langgraph_inner(