@echofiles/echo-pdf 0.5.0 → 0.6.0

package/dist/local/semantic.js

@@ -0,0 +1,231 @@
+/// <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 { 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";
+const resolveSemanticExtractionBudget = (input) => ({
+    pageSelection: "all",
+    chunkMaxChars: typeof input?.chunkMaxChars === "number" && Number.isFinite(input.chunkMaxChars) && input.chunkMaxChars > 400
+        ? Math.floor(input.chunkMaxChars)
+        : 4000,
+    chunkOverlapChars: typeof input?.chunkOverlapChars === "number" && Number.isFinite(input.chunkOverlapChars) && input.chunkOverlapChars >= 0
+        ? Math.floor(input.chunkOverlapChars)
+        : 300,
+});
+const normalizeSemanticAgentCandidate = (value, pageNumber) => {
+    const candidate = value;
+    const title = typeof candidate?.title === "string" ? candidate.title.trim() : "";
+    const level = typeof candidate?.level === "number" && Number.isInteger(candidate.level) && candidate.level > 0
+        ? candidate.level
+        : 0;
+    const confidence = typeof candidate?.confidence === "number" && Number.isFinite(candidate.confidence)
+        ? Math.max(0, Math.min(1, candidate.confidence))
+        : 0;
+    if (!title || level <= 0 || confidence < 0.6)
+        return null;
+    return {
+        title,
+        level,
+        pageNumber,
+        excerpt: typeof candidate?.excerpt === "string" ? candidate.excerpt.trim() : undefined,
+        confidence,
+    };
+};
+const toSemanticTree = (value, pageArtifactPaths) => {
+    if (!Array.isArray(value))
+        return [];
+    const nodes = [];
+    value.forEach((item, index) => {
+        const node = item;
+        const title = typeof node.title === "string" ? node.title.trim() : "";
+        const level = typeof node.level === "number" && Number.isInteger(node.level) && node.level > 0 ? node.level : undefined;
+        const pageNumber = typeof node.pageNumber === "number" && Number.isInteger(node.pageNumber) && node.pageNumber > 0 ? node.pageNumber : undefined;
+        if (!title || typeof level !== "number" || typeof pageNumber !== "number")
+            return;
+        nodes.push({
+            id: `semantic-node-${index + 1}-${pageNumber}-${level}`,
+            type: "section",
+            title,
+            level,
+            pageNumber,
+            pageArtifactPath: pageArtifactPaths.get(pageNumber),
+            excerpt: typeof node.excerpt === "string" ? node.excerpt.trim() : undefined,
+            children: toSemanticTree(node.children, pageArtifactPaths),
+        });
+    });
+    return nodes;
+};
+const buildSemanticPageUnderstandingPrompt = (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.",
+        "Return JSON only.",
+        "Schema:",
+        "{",
+        '  "candidates": [',
+        "    {",
+        '      "title": "string",',
+        '      "level": 1,',
+        '      "excerpt": "short evidence string",',
+        '      "confidence": 0.0',
+        "    }",
+        "  ]",
+        "}",
+        "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":[]}.',
+        `Page number: ${page.pageNumber}`,
+        `Render scale: ${renderScale}`,
+        "",
+        "Extracted page text:",
+        page.text,
+    ].join("\n");
+};
+const buildSemanticAggregationPrompt = (record, candidates) => {
+    const candidateDump = JSON.stringify({ candidates }, null, 2);
+    return [
+        "You assemble semantic document structure from page-understanding heading candidates.",
+        "Return JSON only.",
+        "Schema:",
+        "{",
+        '  "sections": [',
+        "    {",
+        '      "title": "string",',
+        '      "level": 1,',
+        '      "pageNumber": 1,',
+        '      "excerpt": "short evidence string",',
+        '      "children": []',
+        "    }",
+        "  ]",
+        "}",
+        "Rules:",
+        "- Preserve hierarchy with nested children.",
+        "- Use only candidate headings that form a reliable document structure.",
+        "- Favor candidates with strong confidence and clear section semantics; drop visually prominent noise.",
+        "- Deduplicate repeated headings from overlapping segments.",
+        "- Do not invent sections not present in the candidates.",
+        '- If no reliable semantic structure is detectable, return {"sections":[]}.',
+        `Document filename: ${record.filename}`,
+        `Page count: ${record.pageCount}`,
+        "",
+        candidateDump,
+    ].join("\n");
+};
+const resolveSemanticAgentContext = (config, request) => {
+    const provider = resolveProviderAlias(config, request.provider);
+    const model = resolveModelForProvider(config, provider, request.model);
+    if (!provider || !model) {
+        throw new Error([
+            "semantic extraction requires a configured provider and model.",
+            "Pass `provider` and `model` to `get_semantic_document_structure()`",
+            "or configure them first with `echo-pdf provider use --provider <alias>` and `echo-pdf model set --provider <alias> --model <model-id>`.",
+        ].join(" "));
+    }
+    return { provider, model };
+};
+const extractSemanticCandidatesFromRenderedPage = async (input) => {
+    const renderArtifact = await ensureRenderArtifact({
+        pdfPath: input.request.pdfPath,
+        workspaceDir: input.request.workspaceDir,
+        forceRefresh: input.request.forceRefresh,
+        config: input.config,
+        pageNumber: input.page.pageNumber,
+    });
+    const imageBytes = new Uint8Array(await readFile(renderArtifact.imagePath));
+    const imageDataUrl = toDataUrl(imageBytes, renderArtifact.mimeType);
+    const response = await visionRecognize({
+        config: input.config,
+        env: input.env,
+        providerAlias: input.provider,
+        model: input.model,
+        prompt: buildSemanticPageUnderstandingPrompt(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 ensureSemanticStructureArtifact = async (request) => {
+    const env = resolveEnv(request.env);
+    const config = resolveConfig(request.config, env);
+    const { record } = await indexDocumentInternal(request);
+    const artifactPath = record.artifactPaths.semanticStructureJsonPath;
+    const semanticBudget = resolveSemanticExtractionBudget(request.semanticExtraction);
+    const { provider, model } = resolveSemanticAgentContext(config, request);
+    const strategyKey = `agent::page-understanding-v1::${provider}::${model}::${config.service.defaultRenderScale}::${semanticBudget.pageSelection}::${semanticBudget.chunkMaxChars}::${semanticBudget.chunkOverlapChars}`;
+    if (!request.forceRefresh && await fileExists(artifactPath)) {
+        const cached = await readJson(artifactPath);
+        if (matchesSourceSnapshot(cached, record) && matchesStrategyKey(cached, strategyKey)) {
+            return {
+                ...cached,
+                cacheStatus: "reused",
+            };
+        }
+    }
+    const pages = [];
+    for (let pageNumber = 1; pageNumber <= record.pageCount; pageNumber += 1) {
+        const pagePath = path.join(record.artifactPaths.pagesDir, `${pageLabel(pageNumber)}.json`);
+        const page = await readJson(pagePath);
+        pages.push(page);
+    }
+    const pageArtifactPaths = new Map(pages.map((page) => [page.pageNumber, page.artifactPath]));
+    const candidateMap = new Map();
+    for (const page of pages) {
+        const candidates = await extractSemanticCandidatesFromRenderedPage({
+            page,
+            request,
+            config,
+            env,
+            provider,
+            model,
+        });
+        for (const candidate of 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 aggregated = await generateText({
+        config,
+        env,
+        providerAlias: provider,
+        model,
+        prompt: buildSemanticAggregationPrompt(record, [...candidateMap.values()]),
+        runtimeApiKeys: request.providerApiKeys,
+    });
+    const parsed = parseJsonObject(aggregated);
+    const sections = toSemanticTree(parsed?.sections, pageArtifactPaths);
+    const artifact = {
+        documentId: record.documentId,
+        generatedAt: new Date().toISOString(),
+        detector: "agent-structured-v1",
+        strategyKey,
+        sourceSizeBytes: record.sizeBytes,
+        sourceMtimeMs: record.mtimeMs,
+        pageIndexArtifactPath: record.artifactPaths.structureJsonPath,
+        artifactPath,
+        root: {
+            id: `semantic-${record.documentId}`,
+            type: "document",
+            title: record.filename,
+            children: sections,
+        },
+    };
+    await writeJson(artifactPath, artifact);
+    return {
+        ...artifact,
+        cacheStatus: "fresh",
+    };
+};
+export const get_semantic_document_structure = async (request) => ensureSemanticStructureArtifact(request);

package/dist/local/shared.d.ts

@@ -0,0 +1,50 @@
+import type { EchoPdfConfig } from "../pdf-types.js";
+import type { Env } from "../types.js";
+import type { InternalDocumentArtifactPaths, LocalDocumentArtifactPaths, LocalFormulaArtifactItem, LocalTableArtifactItem, StoredDocumentRecord } from "./types.js";
+export declare const defaultWorkspaceDir: () => string;
+export declare const resolveWorkspaceDir: (workspaceDir?: string) => string;
+export declare const toDocumentId: (absolutePdfPath: string) => string;
+export declare const hashFragment: (value: string, length?: number) => string;
+export declare const sanitizeSegment: (value: string) => string;
+export declare const scaleLabel: (value: number) => string;
+export declare const pageLabel: (pageNumber: number) => string;
+export declare const buildArtifactPaths: (workspaceDir: string, documentId: string) => InternalDocumentArtifactPaths;
+export declare const toPublicArtifactPaths: (paths: InternalDocumentArtifactPaths) => LocalDocumentArtifactPaths;
+export declare const buildRenderArtifactPaths: (paths: LocalDocumentArtifactPaths, pageNumber: number, renderScale: number) => {
+    artifactPath: string;
+    imagePath: string;
+};
+export declare const buildStructuredArtifactPath: (baseDir: string, pageNumber: number, renderScale: number, provider: string, model: string, prompt: string) => string;
+export declare const createPreview: (text: string) => string;
+export declare const createPageTitle: (pageNumber: number, text: string) => string;
+export declare const stripCodeFences: (value: string) => string;
+export declare const parseJsonObject: (value: string) => unknown;
+export declare const normalizeTableItems: (value: unknown) => LocalTableArtifactItem[];
+export declare const normalizeFormulaItems: (value: unknown) => LocalFormulaArtifactItem[];
+export declare const resolveEnv: (env?: Env) => Env;
+export declare const resolveConfig: (config?: EchoPdfConfig, env?: Env) => EchoPdfConfig;
+export declare const resolveAgentSelection: (config: EchoPdfConfig, input: {
+    provider?: string;
+    model?: string;
+}) => {
+    provider: string;
+    model: string;
+};
+export declare const resolveRenderScale: (config: EchoPdfConfig, requestedScale?: number) => number;
+export declare const fileExists: (targetPath: string) => Promise<boolean>;
+export declare const readJson: <T>(targetPath: string) => Promise<T>;
+export declare const loadStoredDocument: (paths: InternalDocumentArtifactPaths) => Promise<StoredDocumentRecord | null>;
+export declare const isReusableRecord: (record: StoredDocumentRecord, sourceStats: {
+    sizeBytes: number;
+    mtimeMs: number;
+}, paths: InternalDocumentArtifactPaths) => Promise<boolean>;
+export declare const writeJson: (targetPath: string, data: unknown) => Promise<void>;
+export declare const readSourceBytes: (sourcePath: string) => Promise<Uint8Array>;
+export declare const matchesSourceSnapshot: (artifact: {
+    sourceSizeBytes?: unknown;
+    sourceMtimeMs?: unknown;
+}, record: StoredDocumentRecord) => boolean;
+export declare const matchesStrategyKey: (artifact: {
+    strategyKey?: unknown;
+}, strategyKey: string) => boolean;
+export declare const ensurePageNumber: (pageCount: number, pageNumber: number) => void;

package/dist/local/shared.js

@@ -0,0 +1,173 @@
+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 { 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());
+export const toDocumentId = (absolutePdfPath) => createHash("sha256").update(absolutePdfPath).digest("hex").slice(0, 16);
+export const hashFragment = (value, length = 12) => createHash("sha256").update(value).digest("hex").slice(0, length);
+export const sanitizeSegment = (value) => value.replace(/[^a-zA-Z0-9._-]+/g, "_");
+export const scaleLabel = (value) => sanitizeSegment(String(value));
+export const pageLabel = (pageNumber) => String(pageNumber).padStart(4, "0");
+export const buildArtifactPaths = (workspaceDir, documentId) => {
+    const documentDir = path.join(workspaceDir, "documents", documentId);
+    return {
+        workspaceDir,
+        documentDir,
+        documentJsonPath: path.join(documentDir, "document.json"),
+        structureJsonPath: path.join(documentDir, "structure.json"),
+        semanticStructureJsonPath: path.join(documentDir, "semantic-structure.json"),
+        pagesDir: path.join(documentDir, "pages"),
+        rendersDir: path.join(documentDir, "renders"),
+    };
+};
+export const toPublicArtifactPaths = (paths) => ({
+    workspaceDir: paths.workspaceDir,
+    documentDir: paths.documentDir,
+    documentJsonPath: paths.documentJsonPath,
+    structureJsonPath: paths.structureJsonPath,
+    semanticStructureJsonPath: paths.semanticStructureJsonPath,
+    pagesDir: paths.pagesDir,
+    rendersDir: paths.rendersDir,
+});
+export const buildRenderArtifactPaths = (paths, pageNumber, renderScale) => {
+    const key = `${pageLabel(pageNumber)}.scale-${scaleLabel(renderScale)}`;
+    return {
+        artifactPath: path.join(paths.rendersDir, `${key}.json`),
+        imagePath: path.join(paths.rendersDir, `${key}.png`),
+    };
+};
+export const buildStructuredArtifactPath = (baseDir, pageNumber, renderScale, provider, model, prompt) => {
+    const key = [
+        pageLabel(pageNumber),
+        `scale-${scaleLabel(renderScale)}`,
+        `provider-${sanitizeSegment(provider)}`,
+        `model-${sanitizeSegment(model)}`,
+        `prompt-${hashFragment(prompt, 10)}`,
+    ].join(".");
+    return path.join(baseDir, `${key}.json`);
+};
+export const createPreview = (text) => text.replace(/\s+/g, " ").trim().slice(0, 160);
+export const createPageTitle = (pageNumber, text) => {
+    const firstLine = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    return firstLine ? `Page ${pageNumber}: ${firstLine.slice(0, 80)}` : `Page ${pageNumber}`;
+};
+export const stripCodeFences = (value) => {
+    const text = value.trim();
+    const fenced = text.match(/^```[a-zA-Z0-9_-]*\n([\s\S]*?)\n```$/);
+    return typeof fenced?.[1] === "string" ? fenced[1].trim() : text;
+};
+export const parseJsonObject = (value) => {
+    const trimmed = stripCodeFences(value).trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        const start = trimmed.indexOf("{");
+        const end = trimmed.lastIndexOf("}");
+        if (start >= 0 && end > start) {
+            return JSON.parse(trimmed.slice(start, end + 1));
+        }
+        throw new Error("model output was not valid JSON");
+    }
+};
+export const normalizeTableItems = (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,
+                evidenceText: typeof table.evidenceText === "string" ? table.evidenceText.trim() : undefined,
+            }];
+    });
+};
+export const normalizeFormulaItems = (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,
+                evidenceText: typeof formula.evidenceText === "string" ? formula.evidenceText.trim() : undefined,
+            }];
+    });
+};
+export const resolveEnv = (env) => env ?? process.env;
+export const resolveConfig = (config, env) => config ?? loadEchoPdfConfig(resolveEnv(env));
+export const resolveAgentSelection = (config, input) => {
+    const provider = resolveProviderAlias(config, input.provider);
+    const model = resolveModelForProvider(config, provider, input.model);
+    if (!model) {
+        throw new Error(`model is required for VL-first structured artifacts; pass \`model\` or set agent.defaultModel for provider "${provider}"`);
+    }
+    return { provider, model };
+};
+export const resolveRenderScale = (config, requestedScale) => {
+    if (typeof requestedScale === "number" && Number.isFinite(requestedScale) && requestedScale > 0) {
+        return requestedScale;
+    }
+    return config.service.defaultRenderScale;
+};
+export const fileExists = async (targetPath) => {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const readJson = async (targetPath) => {
+    const raw = await readFile(targetPath, "utf-8");
+    return JSON.parse(raw);
+};
+export const loadStoredDocument = async (paths) => {
+    if (!await fileExists(paths.documentJsonPath))
+        return null;
+    const raw = await readJson(paths.documentJsonPath);
+    return {
+        ...raw,
+        artifactPaths: paths,
+    };
+};
+export const isReusableRecord = async (record, sourceStats, paths) => {
+    if (record.sizeBytes !== sourceStats.sizeBytes || record.mtimeMs !== sourceStats.mtimeMs)
+        return false;
+    if (!await fileExists(paths.structureJsonPath))
+        return false;
+    for (let pageNumber = 1; pageNumber <= record.pageCount; pageNumber += 1) {
+        const pagePath = path.join(paths.pagesDir, `${pageLabel(pageNumber)}.json`);
+        if (!await fileExists(pagePath))
+            return false;
+    }
+    return true;
+};
+export const writeJson = async (targetPath, data) => {
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+};
+export const readSourceBytes = async (sourcePath) => new Uint8Array(await readFile(sourcePath));
+export const matchesSourceSnapshot = (artifact, record) => artifact.sourceSizeBytes === record.sizeBytes && artifact.sourceMtimeMs === record.mtimeMs;
+export const matchesStrategyKey = (artifact, strategyKey) => artifact.strategyKey === strategyKey;
+export const ensurePageNumber = (pageCount, pageNumber) => {
+    if (!Number.isInteger(pageNumber) || pageNumber < 1 || pageNumber > pageCount) {
+        throw new Error(`pageNumber must be within 1..${pageCount}`);
+    }
+};

package/dist/local/types.d.ts

@@ -0,0 +1,183 @@
+import type { EchoPdfConfig } from "../pdf-types.js";
+import type { Env } from "../types.js";
+export interface LocalDocumentArtifactPaths {
+    readonly workspaceDir: string;
+    readonly documentDir: string;
+    readonly documentJsonPath: string;
+    readonly structureJsonPath: string;
+    readonly semanticStructureJsonPath: string;
+    readonly pagesDir: string;
+    readonly rendersDir: string;
+}
+export interface InternalDocumentArtifactPaths extends LocalDocumentArtifactPaths {
+}
+export interface LocalDocumentMetadata {
+    readonly documentId: string;
+    readonly sourcePath: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly mtimeMs: number;
+    readonly pageCount: number;
+    readonly indexedAt: string;
+    readonly cacheStatus: "fresh" | "reused";
+    readonly artifactPaths: LocalDocumentArtifactPaths;
+}
+export interface LocalDocumentStructureNode {
+    readonly id: string;
+    readonly type: "document" | "page";
+    readonly title: string;
+    readonly pageNumber?: number;
+    readonly preview?: string;
+    readonly artifactPath?: string;
+    readonly children?: ReadonlyArray<LocalDocumentStructureNode>;
+}
+export interface LocalDocumentStructure {
+    readonly documentId: string;
+    readonly generatedAt: string;
+    readonly root: LocalDocumentStructureNode;
+}
+export interface LocalSemanticStructureNode {
+    readonly id: string;
+    readonly type: "document" | "section";
+    readonly title: string;
+    readonly level?: number;
+    readonly pageNumber?: number;
+    readonly pageArtifactPath?: string;
+    readonly excerpt?: string;
+    readonly children?: ReadonlyArray<LocalSemanticStructureNode>;
+}
+export interface LocalSemanticDocumentStructure {
+    readonly documentId: string;
+    readonly generatedAt: string;
+    readonly detector: "agent-structured-v1";
+    readonly strategyKey: string;
+    readonly sourceSizeBytes: number;
+    readonly sourceMtimeMs: number;
+    readonly pageIndexArtifactPath: string;
+    readonly artifactPath: string;
+    readonly root: LocalSemanticStructureNode;
+    readonly cacheStatus: "fresh" | "reused";
+}
+export interface LocalPageContent {
+    readonly documentId: string;
+    readonly pageNumber: number;
+    readonly title: string;
+    readonly preview: string;
+    readonly text: string;
+    readonly chars: number;
+    readonly artifactPath: string;
+}
+export interface LocalPageRenderArtifact {
+    readonly documentId: string;
+    readonly pageNumber: number;
+    readonly renderScale: number;
+    readonly sourceSizeBytes: number;
+    readonly sourceMtimeMs: number;
+    readonly width: number;
+    readonly height: number;
+    readonly mimeType: "image/png";
+    readonly imagePath: string;
+    readonly artifactPath: string;
+    readonly generatedAt: string;
+    readonly cacheStatus: "fresh" | "reused";
+}
+export interface LocalTableArtifactItem {
+    readonly id: string;
+    readonly latexTabular: string;
+    readonly caption?: string;
+    readonly evidenceText?: string;
+}
+export interface LocalFormulaArtifactItem {
+    readonly id: string;
+    readonly latexMath: string;
+    readonly label?: string;
+    readonly evidenceText?: string;
+}
+export interface LocalPageTablesArtifact {
+    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<LocalTableArtifactItem>;
+    readonly cacheStatus: "fresh" | "reused";
+}
+export interface LocalPageFormulasArtifact {
+    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 formulas: ReadonlyArray<LocalFormulaArtifactItem>;
+    readonly cacheStatus: "fresh" | "reused";
+}
+export interface LocalDocumentRequest {
+    readonly pdfPath: string;
+    readonly workspaceDir?: string;
+    readonly forceRefresh?: boolean;
+    readonly config?: EchoPdfConfig;
+}
+export interface LocalPageContentRequest extends LocalDocumentRequest {
+    readonly pageNumber: number;
+}
+export interface LocalSemanticDocumentRequest extends LocalDocumentRequest {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly semanticExtraction?: {
+        readonly pageSelection?: "all";
+        readonly chunkMaxChars?: number;
+        readonly chunkOverlapChars?: number;
+    };
+    readonly env?: Env;
+    readonly providerApiKeys?: Record<string, string>;
+}
+export interface LocalPageRenderRequest extends LocalPageContentRequest {
+    readonly renderScale?: number;
+}
+export interface LocalPageTablesRequest extends LocalPageRenderRequest {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly prompt?: string;
+    readonly env?: Env;
+    readonly providerApiKeys?: Record<string, string>;
+}
+export interface LocalPageFormulasRequest extends LocalPageRenderRequest {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly prompt?: string;
+    readonly env?: Env;
+    readonly providerApiKeys?: Record<string, string>;
+}
+export interface StoredDocumentRecord {
+    readonly documentId: string;
+    readonly sourcePath: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly mtimeMs: number;
+    readonly pageCount: number;
+    readonly indexedAt: string;
+    readonly artifactPaths: InternalDocumentArtifactPaths;
+}
+export type SemanticAgentCandidate = {
+    title: string;
+    level: number;
+    pageNumber: number;
+    excerpt?: string;
+    confidence: number;
+};

package/dist/local/types.js

@@ -0,0 +1,2 @@
+/// <reference path="../node/compat.d.ts" />
+export {};