@echofiles/echo-pdf 0.7.0 → 0.8.0

package/README.md

@@ -85,6 +85,8 @@ What these commands map to:
 - `semantic` -> `get_semantic_document_structure`
 - `page` -> `get_page_content`
 - `render` -> `get_page_render`
+- `tables` -> `get_page_tables_latex`
+- `formulas` -> `get_page_formulas_latex`
 
 By default, `echo-pdf` writes reusable artifacts into a local workspace:
 
@@ -101,6 +103,10 @@ By default, `echo-pdf` writes reusable artifacts into a local workspace:
     renders/
       0001.scale-2.json
       0001.scale-2.png
+    tables/
+      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
 ```
 
 These artifacts are meant to be inspected, cached, and reused by downstream local tools.
@@ -115,6 +121,8 @@ import {
   get_semantic_document_structure,
   get_page_content,
   get_page_render,
+  get_page_tables_latex,
+  get_page_formulas_latex,
 } from "@echofiles/echo-pdf/local"
 
 const document = await get_document({ pdfPath: "./sample.pdf" })
@@ -126,6 +134,8 @@ const semantic = await get_semantic_document_structure({
 })
 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" })
 ```
 
 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"]
+const LOCAL_PRIMITIVE_COMMANDS = ["document", "structure", "semantic", "page", "render", "tables", "formulas"]
 const REMOVED_DOCUMENT_ALIAS_TO_PRIMITIVE = {
   index: "document",
   get: "document",
@@ -302,6 +302,40 @@ const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
     return
   }
 
+  if (primitive === "tables") {
+    const semanticContext = resolveLocalSemanticContext(flags)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_page_tables_latex({
+      pdfPath,
+      workspaceDir,
+      forceRefresh,
+      pageNumber,
+      renderScale,
+      provider: semanticContext.provider,
+      model: semanticContext.model,
+      providerApiKeys: semanticContext.providerApiKeys,
+      prompt: typeof flags.prompt === "string" ? flags.prompt : undefined,
+    }))
+    return
+  }
+
+  if (primitive === "formulas") {
+    const semanticContext = resolveLocalSemanticContext(flags)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_page_formulas_latex({
+      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}`)
 }
 
@@ -313,6 +347,8 @@ const usage = () => {
   process.stdout.write(`  semantic <file.pdf> [--provider alias] [--model model] [--profile name] [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  page <file.pdf> --page <N> [--workspace DIR] [--force-refresh]\n`)
   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(`\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/formulas.d.ts

@@ -0,0 +1,2 @@
+import type { LocalPageFormulasArtifact, LocalPageFormulasRequest } from "./types.js";
+export declare const get_page_formulas_latex: (request: LocalPageFormulasRequest) => Promise<LocalPageFormulasArtifact>;

package/dist/local/formulas.js

@@ -0,0 +1,71 @@
+/// <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, normalizeFormulaItems, pageLabel, parseJsonObject, readJson, resolveAgentSelection, resolveConfig, resolveEnv, resolveRenderScale, writeJson, } from "./shared.js";
+const DEFAULT_FORMULA_PROMPT = "Detect all displayed mathematical formulas from this PDF page image. " +
+    "Return JSON only. Schema: " +
+    '{ "formulas": [{ "latexMath": "LaTeX math expression", "label": "optional equation label", "evidenceText": "optional" }] }. ' +
+    "Use LaTeX math notation. Do not include inline prose math or trivial single-symbol expressions. " +
+    "If no displayed formulas are found, return {\"formulas\":[]}.";
+export const get_page_formulas_latex = 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_FORMULA_PROMPT;
+    const formulasDir = path.join(record.artifactPaths.documentDir, "formulas");
+    const artifactPath = buildStructuredArtifactPath(formulasDir, 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 formulas = normalizeFormulaItems(parsed?.formulas);
+    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(),
+        formulas,
+    };
+    await writeJson(artifactPath, artifact);
+    return { ...artifact, cacheStatus: "fresh" };
+};

package/dist/local/index.d.ts

@@ -1,3 +1,5 @@
-export type { LocalDocumentArtifactPaths, LocalDocumentMetadata, LocalDocumentRequest, LocalDocumentStructure, LocalDocumentStructureNode, LocalPageContent, LocalPageContentRequest, LocalPageRenderArtifact, LocalPageRenderRequest, LocalSemanticDocumentRequest, LocalSemanticDocumentStructure, LocalSemanticStructureNode, } from "./types.js";
+export type { LocalDocumentArtifactPaths, LocalDocumentMetadata, LocalDocumentRequest, LocalDocumentStructure, LocalDocumentStructureNode, LocalFormulaArtifactItem, LocalPageContent, LocalPageContentRequest, LocalPageFormulasArtifact, LocalPageFormulasRequest, LocalPageRenderArtifact, LocalPageRenderRequest, LocalPageTablesArtifact, LocalPageTablesRequest, LocalSemanticDocumentRequest, LocalSemanticDocumentStructure, LocalSemanticStructureNode, LocalTableArtifactItem, } 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";

package/dist/local/index.js

@@ -1,2 +1,4 @@
 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";

package/dist/local/tables.d.ts

@@ -0,0 +1,2 @@
+import type { LocalPageTablesArtifact, LocalPageTablesRequest } from "./types.js";
+export declare const get_page_tables_latex: (request: LocalPageTablesRequest) => Promise<LocalPageTablesArtifact>;

package/dist/local/tables.js

@@ -0,0 +1,71 @@
+/// <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, normalizeTableItems, pageLabel, parseJsonObject, readJson, resolveAgentSelection, resolveConfig, resolveEnv, resolveRenderScale, writeJson, } from "./shared.js";
+const DEFAULT_TABLE_PROMPT = "Detect all tabular structures from this PDF page image. " +
+    "Return JSON only. Schema: " +
+    '{ "tables": [{ "latexTabular": "\\\\begin{tabular}...\\\\end{tabular}", "caption": "optional", "evidenceText": "optional" }] }. ' +
+    "Each table must be a complete LaTeX tabular environment. " +
+    "If no tables are found, return {\"tables\":[]}.";
+export const get_page_tables_latex = 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()
+        : (config.agent.tablePrompt || DEFAULT_TABLE_PROMPT);
+    const tablesDir = path.join(record.artifactPaths.documentDir, "tables");
+    const artifactPath = buildStructuredArtifactPath(tablesDir, 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 = normalizeTableItems(parsed?.tables);
+    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,
+    };
+    await writeJson(artifactPath, artifact);
+    return { ...artifact, cacheStatus: "fresh" };
+};

package/dist/pdf-types.d.ts

@@ -21,6 +21,7 @@ export interface EchoPdfConfig {
         readonly defaultProvider: string;
         readonly defaultModel: string;
         readonly tablePrompt: string;
+        readonly formulaPrompt?: string;
     };
     readonly providers: Record<string, EchoPdfProviderConfig>;
 }

package/echo-pdf.config.json

@@ -8,7 +8,8 @@
   "agent": {
     "defaultProvider": "openai",
     "defaultModel": "",
-    "tablePrompt": "Detect all tabular structures from this PDF page image. Output only valid LaTeX tabular environments, no explanations, no markdown fences."
+    "tablePrompt": "Detect all tabular structures from this PDF page image. Output only valid LaTeX tabular environments, no explanations, no markdown fences.",
+    "formulaPrompt": ""
   },
   "providers": {
     "openai": {

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