@echofiles/echo-pdf 0.9.0 → 0.10.1

package/README.md

@@ -58,17 +58,21 @@ echo-pdf page ./sample.pdf --page 1
 echo-pdf render ./sample.pdf --page 1 --scale 2
 ```
 
-To run the VL-first semantic path locally, configure a provider key and model once, then run `semantic`:
+To run provider-required primitives, configure a provider key and model once:
 
 ```bash
 echo-pdf provider set --provider openai --api-key "$OPENAI_API_KEY"
 echo-pdf model set --provider openai --model gpt-4.1-mini
+
 echo-pdf semantic ./sample.pdf
+echo-pdf tables ./sample.pdf --page 1
+echo-pdf formulas ./sample.pdf --page 1
+echo-pdf understanding ./sample.pdf --page 1
 ```
 
-`echo-pdf semantic` now uses the CLI profile's provider/model/api-key settings. If the selected provider or model is missing, it fails early with a clear setup error instead of quietly dropping back to a weaker path.
+Provider-required primitives (`semantic`, `tables`, `formulas`, `understanding`) use the CLI profile's provider/model/api-key settings. If the selected provider or model is missing, they fail early with a clear setup error.
 
-For a local OpenAI-compatible LLM server, point a provider at `http://localhost:...` and leave `apiKeyEnv` empty in `echo-pdf.config.json`. Then configure the CLI profile without a dummy key:
+The CLI ships with a built-in `ollama` provider alias pointing at `http://127.0.0.1:11434/v1`. To use a local Ollama server:
 
 ```bash
 echo-pdf provider set --provider ollama --api-key ""
@@ -76,7 +80,7 @@ echo-pdf model set --provider ollama --model llava:13b
 echo-pdf semantic ./sample.pdf --provider ollama
 ```
 
-This works for local OpenAI-compatible servers such as Ollama, llama.cpp, vLLM, LM Studio, or LocalAI, as long as the selected model supports vision input.
+The built-in provider aliases are `openai`, `vercel_gateway`, `openrouter`, and `ollama`. Other local OpenAI-compatible servers (llama.cpp, vLLM, LM Studio, LocalAI) can be configured by overriding the config via the `ECHO_PDF_CONFIG_JSON` environment variable or by editing the bundled `echo-pdf.config.json` in a source checkout. The selected model must support vision input.
 
 What these commands map to:
 
@@ -146,8 +150,9 @@ const understanding = await get_page_understanding({ pdfPath: "./sample.pdf", pa
 Notes:
 
 - `get_document_structure()` returns the stable page index: `document -> pages[]`
-- `get_semantic_document_structure()` returns a separate semantic structure layer; it does not replace `pages[]`
+- `get_semantic_document_structure()` returns a heading/section tree plus optional cross-page merged `tables[]`, `formulas[]`, and `figures[]`; it does not replace `pages[]`
 - `get_page_render()` materializes a reusable PNG plus render metadata and is the mainline visual input path
+- `get_page_understanding()` extracts tables, formulas, and figures from a single page in one LLM call
 
 Migration note:
 

package/dist/local/semantic.js

@@ -1,12 +1,12 @@
 /// <reference path="../node/compat.d.ts" />
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { resolveModelForProvider, resolveProviderAlias } from "../agent-defaults.js";
+import { resolveModelForProvider, resolveProviderAlias } from "../provider-defaults.js";
 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";
+import { normalizeFigureItems, normalizeUnderstandingFormulas, normalizeUnderstandingTables } from "./understanding.js";
 const resolveSemanticExtractionBudget = (input) => ({
     pageSelection: "all",
     chunkMaxChars: typeof input?.chunkMaxChars === "number" && Number.isFinite(input.chunkMaxChars) && input.chunkMaxChars > 400
@@ -59,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}`,
         "",
@@ -131,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,
@@ -146,14 +149,26 @@ 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 = [];
@@ -262,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,
@@ -271,28 +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);
             }
         }
-    }
-    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);
+        pageElements.push(result.elements);
     }
     const aggregated = await generateText({
         config,
@@ -304,9 +306,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 mergedTables = mergeCrossPageTables(pageElements);
+    const mergedFormulas = mergeCrossPageFormulas(pageElements);
+    const mergedFigures = mergeCrossPageFigures(pageElements);
     const artifact = {
         documentId: record.documentId,
         generatedAt: new Date().toISOString(),

package/dist/local/shared.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { resolveModelForProvider, resolveProviderAlias } from "../agent-defaults.js";
+import { resolveModelForProvider, resolveProviderAlias } from "../provider-defaults.js";
 import { loadEchoPdfConfig } from "../pdf-config.js";
 export const defaultWorkspaceDir = () => path.resolve(process.cwd(), ".echo-pdf-workspace");
 export const resolveWorkspaceDir = (workspaceDir) => path.resolve(process.cwd(), workspaceDir?.trim() || defaultWorkspaceDir());

package/dist/local/understanding.d.ts

@@ -1,2 +1,5 @@
-import type { LocalPageUnderstandingArtifact, LocalPageUnderstandingRequest } from "./types.js";
+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

@@ -20,7 +20,7 @@ const DEFAULT_UNDERSTANDING_PROMPT = [
     "- 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) => {
+export const normalizeFigureItems = (value) => {
     if (!Array.isArray(value))
         return [];
     return value.flatMap((item, index) => {
@@ -37,7 +37,7 @@ const normalizeFigureItems = (value) => {
             }];
     });
 };
-const normalizeUnderstandingTables = (value) => {
+export const normalizeUnderstandingTables = (value) => {
     if (!Array.isArray(value))
         return [];
     return value.flatMap((item, index) => {
@@ -54,7 +54,7 @@ const normalizeUnderstandingTables = (value) => {
             }];
     });
 };
-const normalizeUnderstandingFormulas = (value) => {
+export const normalizeUnderstandingFormulas = (value) => {
     if (!Array.isArray(value))
         return [];
     return value.flatMap((item, index) => {

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.9.0",
+  "version": "0.10.1",
   "type": "module",
   "homepage": "https://pdf.echofile.ai/",
   "repository": {