@echofiles/echo-pdf 0.8.0 → 0.9.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 { get_page_understanding } from "./understanding.js";
 const resolveSemanticExtractionBudget = (input) => ({
     pageSelection: "all",
     chunkMaxChars: typeof input?.chunkMaxChars === "number" && Number.isFinite(input.chunkMaxChars) && input.chunkMaxChars > 400
@@ -154,6 +155,88 @@ const extractSemanticCandidatesFromRenderedPage = async (input) => {
         .map((candidate) => normalizeSemanticAgentCandidate(candidate, input.page.pageNumber))
         .filter((candidate) => candidate !== null);
 };
+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);
     const config = resolveConfig(request.config, env);
@@ -196,6 +279,21 @@ const ensureSemanticStructureArtifact = async (request) => {
             }
         }
     }
+    const understandings = [];
+    for (const page of pages) {
+        const pu = await get_page_understanding({
+            pdfPath: request.pdfPath,
+            workspaceDir: request.workspaceDir,
+            forceRefresh: request.forceRefresh,
+            config,
+            pageNumber: page.pageNumber,
+            provider,
+            model,
+            env,
+            providerApiKeys: request.providerApiKeys,
+        });
+        understandings.push(pu);
+    }
     const aggregated = await generateText({
         config,
         env,
@@ -206,6 +304,9 @@ const ensureSemanticStructureArtifact = async (request) => {
     });
     const parsed = parseJsonObject(aggregated);
     const sections = toSemanticTree(parsed?.sections, pageArtifactPaths);
+    const mergedTables = mergeCrossPageTables(understandings);
+    const mergedFormulas = mergeCrossPageFormulas(understandings);
+    const mergedFigures = mergeCrossPageFigures(understandings);
     const artifact = {
         documentId: record.documentId,
         generatedAt: new Date().toISOString(),
@@ -221,6 +322,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,2 @@
+import type { LocalPageUnderstandingArtifact, LocalPageUnderstandingRequest } from "./types.js";
+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");
+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,
+            }];
+    });
+};
+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,
+            }];
+    });
+};
+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.9.0",
   "type": "module",
   "homepage": "https://pdf.echofile.ai/",
   "repository": {