@echofiles/echo-pdf 0.8.0 → 0.10.0

package/README.md

@@ -87,6 +87,7 @@ What these commands map to:
 - `render` -> `get_page_render`
 - `tables` -> `get_page_tables_latex`
 - `formulas` -> `get_page_formulas_latex`
+- `understanding` -> `get_page_understanding`
 
 By default, `echo-pdf` writes reusable artifacts into a local workspace:
 
@@ -107,6 +108,8 @@ By default, `echo-pdf` writes reusable artifacts into a local workspace:
       0001.scale-2.provider-openai.model-gpt-4.1-mini.prompt-<hash>.json
     formulas/
       0001.scale-2.provider-openai.model-gpt-4.1-mini.prompt-<hash>.json
+    understanding/
+      0001.scale-2.provider-openai.model-gpt-4.1-mini.prompt-<hash>.json
 ```
 
 These artifacts are meant to be inspected, cached, and reused by downstream local tools.
@@ -123,6 +126,7 @@ import {
   get_page_render,
   get_page_tables_latex,
   get_page_formulas_latex,
+  get_page_understanding,
 } from "@echofiles/echo-pdf/local"
 
 const document = await get_document({ pdfPath: "./sample.pdf" })
@@ -136,6 +140,7 @@ const page1 = await get_page_content({ pdfPath: "./sample.pdf", pageNumber: 1 })
 const render1 = await get_page_render({ pdfPath: "./sample.pdf", pageNumber: 1, scale: 2 })
 const tables = await get_page_tables_latex({ pdfPath: "./sample.pdf", pageNumber: 1, provider: "openai", model: "gpt-4.1-mini" })
 const formulas = await get_page_formulas_latex({ pdfPath: "./sample.pdf", pageNumber: 1, provider: "openai", model: "gpt-4.1-mini" })
+const understanding = await get_page_understanding({ pdfPath: "./sample.pdf", pageNumber: 1, provider: "openai", model: "gpt-4.1-mini" })
 ```
 
 Notes:

package/bin/echo-pdf.js

@@ -215,7 +215,7 @@ const loadLocalDocumentApi = async () => {
   return import(LOCAL_DOCUMENT_DIST_ENTRY.href)
 }
 
-const LOCAL_PRIMITIVE_COMMANDS = ["document", "structure", "semantic", "page", "render", "tables", "formulas"]
+const LOCAL_PRIMITIVE_COMMANDS = ["document", "structure", "semantic", "page", "render", "tables", "formulas", "understanding"]
 const REMOVED_DOCUMENT_ALIAS_TO_PRIMITIVE = {
   index: "document",
   get: "document",
@@ -336,6 +336,23 @@ const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
     return
   }
 
+  if (primitive === "understanding") {
+    const semanticContext = resolveLocalSemanticContext(flags)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_page_understanding({
+      pdfPath,
+      workspaceDir,
+      forceRefresh,
+      pageNumber,
+      renderScale,
+      provider: semanticContext.provider,
+      model: semanticContext.model,
+      providerApiKeys: semanticContext.providerApiKeys,
+      prompt: typeof flags.prompt === "string" ? flags.prompt : undefined,
+    }))
+    return
+  }
+
   throw new Error(`Unsupported local primitive command: ${primitive}`)
 }
 
@@ -349,6 +366,7 @@ const usage = () => {
   process.stdout.write(`  render <file.pdf> --page <N> [--scale N] [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  tables <file.pdf> --page <N> [--provider alias] [--model model] [--scale N] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  formulas <file.pdf> --page <N> [--provider alias] [--model model] [--scale N] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  understanding <file.pdf> --page <N> [--provider alias] [--model model] [--scale N] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`\nLocal config commands:\n`)
   process.stdout.write(`  provider set --provider <${getProviderSetNames().join("|")}> --api-key <KEY> [--profile name]\n`)
   process.stdout.write(`  provider use --provider <${getProviderAliases().join("|")}> [--profile name]\n`)

package/dist/local/index.d.ts

@@ -1,5 +1,6 @@
-export type { LocalDocumentArtifactPaths, LocalDocumentMetadata, LocalDocumentRequest, LocalDocumentStructure, LocalDocumentStructureNode, LocalFormulaArtifactItem, LocalPageContent, LocalPageContentRequest, LocalPageFormulasArtifact, LocalPageFormulasRequest, LocalPageRenderArtifact, LocalPageRenderRequest, LocalPageTablesArtifact, LocalPageTablesRequest, LocalSemanticDocumentRequest, LocalSemanticDocumentStructure, LocalSemanticStructureNode, LocalTableArtifactItem, } from "./types.js";
+export type { LocalDocumentArtifactPaths, LocalDocumentMetadata, LocalDocumentRequest, LocalDocumentStructure, LocalDocumentStructureNode, LocalFigureArtifactItem, LocalFormulaArtifactItem, LocalPageContent, LocalPageContentRequest, LocalPageFormulasArtifact, LocalPageFormulasRequest, LocalPageRenderArtifact, LocalPageRenderRequest, LocalPageTablesArtifact, LocalPageTablesRequest, LocalPageUnderstandingArtifact, LocalPageUnderstandingRequest, LocalSemanticDocumentRequest, LocalSemanticDocumentStructure, LocalSemanticStructureNode, LocalTableArtifactItem, MergedFigureItem, MergedFormulaItem, MergedTableItem, } from "./types.js";
 export { get_document, get_document_structure, get_page_content, get_page_render } from "./document.js";
 export { get_page_formulas_latex } from "./formulas.js";
 export { get_semantic_document_structure } from "./semantic.js";
 export { get_page_tables_latex } from "./tables.js";
+export { get_page_understanding } from "./understanding.js";

package/dist/local/index.js

@@ -2,3 +2,4 @@ export { get_document, get_document_structure, get_page_content, get_page_render
 export { get_page_formulas_latex } from "./formulas.js";
 export { get_semantic_document_structure } from "./semantic.js";
 export { get_page_tables_latex } from "./tables.js";
+export { get_page_understanding } from "./understanding.js";

package/dist/local/semantic.js

@@ -6,6 +6,7 @@ import { toDataUrl } from "../file-utils.js";
 import { generateText, visionRecognize } from "../provider-client.js";
 import { ensureRenderArtifact, indexDocumentInternal } from "./document.js";
 import { fileExists, matchesSourceSnapshot, matchesStrategyKey, pageLabel, parseJsonObject, readJson, resolveConfig, resolveEnv, writeJson, } from "./shared.js";
+import { normalizeFigureItems, normalizeUnderstandingFormulas, normalizeUnderstandingTables } from "./understanding.js";
 const resolveSemanticExtractionBudget = (input) => ({
     pageSelection: "all",
     chunkMaxChars: typeof input?.chunkMaxChars === "number" && Number.isFinite(input.chunkMaxChars) && input.chunkMaxChars > 400
@@ -58,29 +59,32 @@ const toSemanticTree = (value, pageArtifactPaths) => {
     });
     return nodes;
 };
-const buildSemanticPageUnderstandingPrompt = (page, renderScale) => {
+const buildCombinedPagePrompt = (page, renderScale) => {
     return [
-        "You extract semantic heading candidates from one rendered PDF page.",
-        "Primary evidence is the page image layout. Use the extracted page text only as supporting context.",
+        "Analyze this rendered PDF page image. Extract headings, tables, formulas, and figures.",
+        "Primary evidence is the page image layout. Use the extracted page text as supporting context.",
         "Return JSON only.",
         "Schema:",
         "{",
-        '  "candidates": [',
-        "    {",
-        '      "title": "string",',
-        '      "level": 1,',
-        '      "excerpt": "short evidence string",',
-        '      "confidence": 0.0',
-        "    }",
-        "  ]",
+        '  "candidates": [{ "title": "string", "level": 1, "excerpt": "short evidence", "confidence": 0.0 }],',
+        '  "tables": [{ "latexTabular": "\\\\begin{tabular}...\\\\end{tabular}", "caption": "optional", "truncatedTop": false, "truncatedBottom": false }],',
+        '  "formulas": [{ "latexMath": "LaTeX expression", "label": "optional", "truncatedTop": false, "truncatedBottom": false }],',
+        '  "figures": [{ "figureType": "schematic|chart|photo|diagram|other", "caption": "optional", "description": "brief description", "truncatedTop": false, "truncatedBottom": false }]',
         "}",
-        "Rules:",
-        "- Use only true document headings/sections that are clearly supported by page layout plus text.",
-        "- Prefer conservative extraction over guessing.",
-        "- Do not include table column headers, field labels, figure labels, unit/value rows, worksheet fragments, or prose sentences.",
-        "- Do not infer hierarchy beyond the explicit heading numbering or structure visible on the page.",
-        "- Confidence should reflect how likely the candidate is to be a real navigational section heading in the document.",
-        '- If no reliable semantic structure is detectable, return {"candidates":[]}.',
+        "Heading rules:",
+        "- candidates: true document headings/sections supported by page layout plus text.",
+        "- Prefer conservative extraction. Do not include table headers, field labels, or prose sentences.",
+        "- Confidence reflects how likely the candidate is a real navigational section heading.",
+        "Table rules:",
+        "- Tables must be complete LaTeX tabular environments.",
+        "Formula rules:",
+        "- Use LaTeX math notation. Skip trivial inline math or single symbols.",
+        "Figure rules:",
+        "- Describe by type, caption, and brief visual description. Do not crop or encode images.",
+        "Truncation:",
+        "- Set truncatedTop/truncatedBottom to true if elements appear cut off at the page boundary.",
+        "Empty:",
+        '- If nothing found for a category, return an empty array for that key.',
         `Page number: ${page.pageNumber}`,
         `Render scale: ${renderScale}`,
         "",
@@ -130,7 +134,7 @@ const resolveSemanticAgentContext = (config, request) => {
     }
     return { provider, model };
 };
-const extractSemanticCandidatesFromRenderedPage = async (input) => {
+const extractCombinedPageData = async (input) => {
     const renderArtifact = await ensureRenderArtifact({
         pdfPath: input.request.pdfPath,
         workspaceDir: input.request.workspaceDir,
@@ -145,14 +149,108 @@ const extractSemanticCandidatesFromRenderedPage = async (input) => {
         env: input.env,
         providerAlias: input.provider,
         model: input.model,
-        prompt: buildSemanticPageUnderstandingPrompt(input.page, renderArtifact.renderScale),
+        prompt: buildCombinedPagePrompt(input.page, renderArtifact.renderScale),
         imageDataUrl,
         runtimeApiKeys: input.request.providerApiKeys,
     });
     const parsed = parseJsonObject(response);
-    return (Array.isArray(parsed?.candidates) ? parsed.candidates : [])
-        .map((candidate) => normalizeSemanticAgentCandidate(candidate, input.page.pageNumber))
-        .filter((candidate) => candidate !== null);
+    const candidates = (Array.isArray(parsed?.candidates) ? parsed.candidates : [])
+        .map((c) => normalizeSemanticAgentCandidate(c, input.page.pageNumber))
+        .filter((c) => c !== null);
+    const tables = normalizeUnderstandingTables(parsed?.tables);
+    const formulas = normalizeUnderstandingFormulas(parsed?.formulas);
+    const figures = normalizeFigureItems(parsed?.figures);
+    return {
+        candidates,
+        elements: {
+            pageNumber: input.page.pageNumber,
+            tables,
+            formulas,
+            figures,
+        },
+    };
+};
+const mergeCrossPageTables = (understandings) => {
+    const merged = [];
+    let nextId = 1;
+    for (const pu of understandings) {
+        for (const table of pu.tables) {
+            const prev = merged[merged.length - 1];
+            if (prev?.crossPageHint && table.truncatedTop) {
+                merged[merged.length - 1] = {
+                    ...prev,
+                    latexTabular: prev.latexTabular + "\n" + table.latexTabular,
+                    endPage: pu.pageNumber,
+                };
+            }
+            else {
+                merged.push({
+                    id: `merged-table-${nextId++}`,
+                    latexTabular: table.latexTabular,
+                    caption: table.caption,
+                    startPage: pu.pageNumber,
+                    endPage: pu.pageNumber,
+                    crossPageHint: table.truncatedBottom === true ? true : undefined,
+                });
+            }
+        }
+    }
+    return merged;
+};
+const mergeCrossPageFormulas = (understandings) => {
+    const merged = [];
+    let nextId = 1;
+    for (const pu of understandings) {
+        for (const formula of pu.formulas) {
+            const prev = merged[merged.length - 1];
+            if (prev?.crossPageHint && formula.truncatedTop) {
+                merged[merged.length - 1] = {
+                    ...prev,
+                    latexMath: prev.latexMath + " " + formula.latexMath,
+                    endPage: pu.pageNumber,
+                };
+            }
+            else {
+                merged.push({
+                    id: `merged-formula-${nextId++}`,
+                    latexMath: formula.latexMath,
+                    label: formula.label,
+                    startPage: pu.pageNumber,
+                    endPage: pu.pageNumber,
+                    crossPageHint: formula.truncatedBottom === true ? true : undefined,
+                });
+            }
+        }
+    }
+    return merged;
+};
+const mergeCrossPageFigures = (understandings) => {
+    const merged = [];
+    let nextId = 1;
+    for (const pu of understandings) {
+        for (const figure of pu.figures) {
+            const prev = merged[merged.length - 1];
+            if (prev?.crossPageHint && figure.truncatedTop) {
+                merged[merged.length - 1] = {
+                    ...prev,
+                    description: [prev.description, figure.description].filter(Boolean).join(" "),
+                    endPage: pu.pageNumber,
+                };
+            }
+            else {
+                merged.push({
+                    id: `merged-figure-${nextId++}`,
+                    figureType: figure.figureType,
+                    caption: figure.caption,
+                    description: figure.description,
+                    startPage: pu.pageNumber,
+                    endPage: pu.pageNumber,
+                    crossPageHint: figure.truncatedBottom === true ? true : undefined,
+                });
+            }
+        }
+    }
+    return merged;
 };
 const ensureSemanticStructureArtifact = async (request) => {
     const env = resolveEnv(request.env);
@@ -179,8 +277,9 @@ const ensureSemanticStructureArtifact = async (request) => {
     }
     const pageArtifactPaths = new Map(pages.map((page) => [page.pageNumber, page.artifactPath]));
     const candidateMap = new Map();
+    const pageElements = [];
     for (const page of pages) {
-        const candidates = await extractSemanticCandidatesFromRenderedPage({
+        const result = await extractCombinedPageData({
             page,
             request,
             config,
@@ -188,13 +287,14 @@ const ensureSemanticStructureArtifact = async (request) => {
             provider,
             model,
         });
-        for (const candidate of candidates) {
+        for (const candidate of result.candidates) {
             const key = `${candidate.pageNumber}:${candidate.level}:${candidate.title}`;
             const existing = candidateMap.get(key);
             if (!existing || candidate.confidence > existing.confidence) {
                 candidateMap.set(key, candidate);
             }
         }
+        pageElements.push(result.elements);
     }
     const aggregated = await generateText({
         config,
@@ -206,6 +306,9 @@ const ensureSemanticStructureArtifact = async (request) => {
     });
     const parsed = parseJsonObject(aggregated);
     const sections = toSemanticTree(parsed?.sections, pageArtifactPaths);
+    const mergedTables = mergeCrossPageTables(pageElements);
+    const mergedFormulas = mergeCrossPageFormulas(pageElements);
+    const mergedFigures = mergeCrossPageFigures(pageElements);
     const artifact = {
         documentId: record.documentId,
         generatedAt: new Date().toISOString(),
@@ -221,6 +324,9 @@ const ensureSemanticStructureArtifact = async (request) => {
             title: record.filename,
             children: sections,
         },
+        ...(mergedTables.length > 0 ? { tables: mergedTables } : {}),
+        ...(mergedFormulas.length > 0 ? { formulas: mergedFormulas } : {}),
+        ...(mergedFigures.length > 0 ? { figures: mergedFigures } : {}),
     };
     await writeJson(artifactPath, artifact);
     return {

package/dist/local/types.d.ts

@@ -56,6 +56,9 @@ export interface LocalSemanticDocumentStructure {
     readonly pageIndexArtifactPath: string;
     readonly artifactPath: string;
     readonly root: LocalSemanticStructureNode;
+    readonly tables?: ReadonlyArray<MergedTableItem>;
+    readonly formulas?: ReadonlyArray<MergedFormulaItem>;
+    readonly figures?: ReadonlyArray<MergedFigureItem>;
     readonly cacheStatus: "fresh" | "reused";
 }
 export interface LocalPageContent {
@@ -127,6 +130,79 @@ export interface LocalPageFormulasArtifact {
     readonly formulas: ReadonlyArray<LocalFormulaArtifactItem>;
     readonly cacheStatus: "fresh" | "reused";
 }
+export interface LocalFigureArtifactItem {
+    readonly id: string;
+    readonly figureType: "schematic" | "chart" | "photo" | "diagram" | "other";
+    readonly caption?: string;
+    readonly description?: string;
+    readonly truncatedTop?: boolean;
+    readonly truncatedBottom?: boolean;
+}
+export interface LocalPageUnderstandingTableItem {
+    readonly id: string;
+    readonly latexTabular: string;
+    readonly caption?: string;
+    readonly truncatedTop?: boolean;
+    readonly truncatedBottom?: boolean;
+}
+export interface LocalPageUnderstandingFormulaItem {
+    readonly id: string;
+    readonly latexMath: string;
+    readonly label?: string;
+    readonly truncatedTop?: boolean;
+    readonly truncatedBottom?: boolean;
+}
+export interface LocalPageUnderstandingArtifact {
+    readonly documentId: string;
+    readonly pageNumber: number;
+    readonly renderScale: number;
+    readonly sourceSizeBytes: number;
+    readonly sourceMtimeMs: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly prompt: string;
+    readonly imagePath: string;
+    readonly pageArtifactPath: string;
+    readonly renderArtifactPath: string;
+    readonly artifactPath: string;
+    readonly generatedAt: string;
+    readonly tables: ReadonlyArray<LocalPageUnderstandingTableItem>;
+    readonly formulas: ReadonlyArray<LocalPageUnderstandingFormulaItem>;
+    readonly figures: ReadonlyArray<LocalFigureArtifactItem>;
+    readonly cacheStatus: "fresh" | "reused";
+}
+export interface LocalPageUnderstandingRequest extends LocalPageRenderRequest {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly prompt?: string;
+    readonly env?: Env;
+    readonly providerApiKeys?: Record<string, string>;
+}
+export interface MergedTableItem {
+    readonly id: string;
+    readonly latexTabular: string;
+    readonly caption?: string;
+    readonly startPage: number;
+    readonly endPage: number;
+    readonly crossPageHint?: boolean;
+}
+export interface MergedFormulaItem {
+    readonly id: string;
+    readonly latexMath: string;
+    readonly label?: string;
+    readonly startPage: number;
+    readonly endPage: number;
+    readonly crossPageHint?: boolean;
+}
+export interface MergedFigureItem {
+    readonly id: string;
+    readonly figureType: "schematic" | "chart" | "photo" | "diagram" | "other";
+    readonly caption?: string;
+    readonly description?: string;
+    readonly startPage: number;
+    readonly endPage: number;
+    readonly crossPageHint?: boolean;
+}
 export interface LocalDocumentRequest {
     readonly pdfPath: string;
     readonly workspaceDir?: string;

package/dist/local/understanding.d.ts

@@ -0,0 +1,5 @@
+import type { LocalFigureArtifactItem, LocalPageUnderstandingArtifact, LocalPageUnderstandingFormulaItem, LocalPageUnderstandingRequest, LocalPageUnderstandingTableItem } from "./types.js";
+export declare const normalizeFigureItems: (value: unknown) => LocalFigureArtifactItem[];
+export declare const normalizeUnderstandingTables: (value: unknown) => LocalPageUnderstandingTableItem[];
+export declare const normalizeUnderstandingFormulas: (value: unknown) => LocalPageUnderstandingFormulaItem[];
+export declare const get_page_understanding: (request: LocalPageUnderstandingRequest) => Promise<LocalPageUnderstandingArtifact>;

package/dist/local/understanding.js

@@ -0,0 +1,136 @@
+/// <reference path="../node/compat.d.ts" />
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { toDataUrl } from "../file-utils.js";
+import { visionRecognize } from "../provider-client.js";
+import { ensureRenderArtifact, indexDocumentInternal } from "./document.js";
+import { buildStructuredArtifactPath, ensurePageNumber, fileExists, matchesSourceSnapshot, pageLabel, parseJsonObject, readJson, resolveAgentSelection, resolveConfig, resolveEnv, resolveRenderScale, stripCodeFences, writeJson, } from "./shared.js";
+const DEFAULT_UNDERSTANDING_PROMPT = [
+    "Analyze this rendered PDF page image. Extract all tables, displayed formulas, and figures.",
+    "Return JSON only. Schema:",
+    "{",
+    '  "tables": [{ "latexTabular": "\\\\begin{tabular}...\\\\end{tabular}", "caption": "optional", "truncatedTop": false, "truncatedBottom": false }],',
+    '  "formulas": [{ "latexMath": "LaTeX expression", "label": "optional", "truncatedTop": false, "truncatedBottom": false }],',
+    '  "figures": [{ "figureType": "schematic|chart|photo|diagram|other", "caption": "optional", "description": "brief visual description", "truncatedTop": false, "truncatedBottom": false }]',
+    "}",
+    "Rules:",
+    "- Tables must be complete LaTeX tabular environments.",
+    "- Formulas must use LaTeX math notation. Skip trivial inline math or single symbols.",
+    "- Figures should be described by type, caption, and a brief visual description. Do not crop or encode images.",
+    "- Set truncatedTop/truncatedBottom to true if the element appears cut off at the page boundary.",
+    '- If nothing is found for a category, return an empty array for that key.',
+].join("\n");
+export const normalizeFigureItems = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item, index) => {
+        const figure = item;
+        const figureType = typeof figure.figureType === "string" ? figure.figureType.trim() : "other";
+        const validTypes = new Set(["schematic", "chart", "photo", "diagram", "other"]);
+        return [{
+                id: `figure-${index + 1}`,
+                figureType: validTypes.has(figureType) ? figureType : "other",
+                caption: typeof figure.caption === "string" ? figure.caption.trim() : undefined,
+                description: typeof figure.description === "string" ? figure.description.trim() : undefined,
+                truncatedTop: figure.truncatedTop === true,
+                truncatedBottom: figure.truncatedBottom === true,
+            }];
+    });
+};
+export const normalizeUnderstandingTables = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item, index) => {
+        const table = item;
+        const latexTabular = typeof table.latexTabular === "string" ? stripCodeFences(table.latexTabular).trim() : "";
+        if (!latexTabular.includes("\\begin{tabular}") || !latexTabular.includes("\\end{tabular}"))
+            return [];
+        return [{
+                id: `table-${index + 1}`,
+                latexTabular,
+                caption: typeof table.caption === "string" ? table.caption.trim() : undefined,
+                truncatedTop: table.truncatedTop === true,
+                truncatedBottom: table.truncatedBottom === true,
+            }];
+    });
+};
+export const normalizeUnderstandingFormulas = (value) => {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item, index) => {
+        const formula = item;
+        const latexMath = typeof formula.latexMath === "string" ? stripCodeFences(formula.latexMath).trim() : "";
+        if (!latexMath)
+            return [];
+        return [{
+                id: `formula-${index + 1}`,
+                latexMath,
+                label: typeof formula.label === "string" ? formula.label.trim() : undefined,
+                truncatedTop: formula.truncatedTop === true,
+                truncatedBottom: formula.truncatedBottom === true,
+            }];
+    });
+};
+export const get_page_understanding = async (request) => {
+    const env = resolveEnv(request.env);
+    const config = resolveConfig(request.config, env);
+    const { record } = await indexDocumentInternal(request);
+    ensurePageNumber(record.pageCount, request.pageNumber);
+    const { provider, model } = resolveAgentSelection(config, request);
+    const renderScale = resolveRenderScale(config, request.renderScale);
+    const prompt = typeof request.prompt === "string" && request.prompt.trim().length > 0
+        ? request.prompt.trim()
+        : DEFAULT_UNDERSTANDING_PROMPT;
+    const understandingDir = path.join(record.artifactPaths.documentDir, "understanding");
+    const artifactPath = buildStructuredArtifactPath(understandingDir, request.pageNumber, renderScale, provider, model, prompt);
+    if (!request.forceRefresh && await fileExists(artifactPath)) {
+        const cached = await readJson(artifactPath);
+        if (matchesSourceSnapshot(cached, record)) {
+            return { ...cached, cacheStatus: "reused" };
+        }
+    }
+    const renderArtifact = await ensureRenderArtifact({
+        pdfPath: request.pdfPath,
+        workspaceDir: request.workspaceDir,
+        forceRefresh: request.forceRefresh,
+        config,
+        pageNumber: request.pageNumber,
+        renderScale: request.renderScale,
+    });
+    const imageBytes = new Uint8Array(await readFile(renderArtifact.imagePath));
+    const imageDataUrl = toDataUrl(imageBytes, renderArtifact.mimeType);
+    const response = await visionRecognize({
+        config,
+        env,
+        providerAlias: provider,
+        model,
+        prompt,
+        imageDataUrl,
+        runtimeApiKeys: request.providerApiKeys,
+    });
+    const parsed = parseJsonObject(response);
+    const tables = normalizeUnderstandingTables(parsed?.tables);
+    const formulas = normalizeUnderstandingFormulas(parsed?.formulas);
+    const figures = normalizeFigureItems(parsed?.figures);
+    const pageArtifactPath = path.join(record.artifactPaths.pagesDir, `${pageLabel(request.pageNumber)}.json`);
+    const artifact = {
+        documentId: record.documentId,
+        pageNumber: request.pageNumber,
+        renderScale,
+        sourceSizeBytes: record.sizeBytes,
+        sourceMtimeMs: record.mtimeMs,
+        provider,
+        model,
+        prompt,
+        imagePath: renderArtifact.imagePath,
+        pageArtifactPath,
+        renderArtifactPath: renderArtifact.artifactPath,
+        artifactPath,
+        generatedAt: new Date().toISOString(),
+        tables,
+        formulas,
+        figures,
+    };
+    await writeJson(artifactPath, artifact);
+    return { ...artifact, cacheStatus: "fresh" };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echofiles/echo-pdf",
   "description": "Local-first PDF document component core with CLI, workspace artifacts, and reusable page primitives.",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "homepage": "https://pdf.echofile.ai/",
   "repository": {