@echofiles/echo-pdf 0.4.0 → 0.4.2

package/dist/pdf-agent.js

@@ -0,0 +1,217 @@
+import { resolveModelForProvider, resolveProviderAlias } from "./agent-defaults.js";
+import { fromBase64, normalizeReturnMode, toDataUrl } from "./file-utils.js";
+import { badRequest, notFound, unprocessable } from "./http-error.js";
+import { extractPdfPageText, getPdfPageCount, renderPdfPageToPng, toBytes } from "./pdfium-engine.js";
+import { visionRecognize } from "./provider-client.js";
+const traceStep = (opts, phase, name, payload, level) => {
+    if (!opts.trace)
+        return;
+    opts.trace({ kind: "step", phase, name, payload, level });
+};
+const ensurePages = (pages, pageCount, maxPages) => {
+    if (pages.length === 0)
+        throw badRequest("PAGES_REQUIRED", "At least one page is required");
+    if (pages.length > maxPages) {
+        throw badRequest("TOO_MANY_PAGES", `Page count exceeds maxPagesPerRequest (${maxPages})`, {
+            maxPagesPerRequest: maxPages,
+            providedPages: pages.length,
+        });
+    }
+    for (const page of pages) {
+        if (!Number.isInteger(page) || page < 1 || page > pageCount) {
+            throw badRequest("PAGE_OUT_OF_RANGE", `Page ${page} out of range 1..${pageCount}`, {
+                page,
+                min: 1,
+                max: pageCount,
+            });
+        }
+    }
+    return [...new Set(pages)].sort((a, b) => a - b);
+};
+export const ingestPdfFromPayload = async (config, input, opts) => {
+    if (input.fileId) {
+        const existing = await opts.fileStore.get(input.fileId);
+        if (!existing) {
+            throw notFound("FILE_NOT_FOUND", `File not found: ${input.fileId}`, { fileId: input.fileId });
+        }
+        return {
+            id: existing.id,
+            filename: existing.filename,
+            bytes: existing.bytes,
+        };
+    }
+    let bytes = null;
+    let filename = input.filename ?? "document.pdf";
+    if (input.url) {
+        traceStep(opts, "start", "file.fetch.url", { url: input.url });
+        try {
+            bytes = await toBytes(input.url);
+        }
+        catch (error) {
+            throw badRequest("URL_FETCH_FAILED", `Unable to fetch PDF from url: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        try {
+            const u = new URL(input.url);
+            filename = decodeURIComponent(u.pathname.split("/").pop() || filename);
+        }
+        catch {
+            // ignore URL parse failure
+        }
+        traceStep(opts, "end", "file.fetch.url", { sizeBytes: bytes.byteLength });
+    }
+    else if (input.base64) {
+        traceStep(opts, "start", "file.decode.base64");
+        bytes = fromBase64(input.base64);
+        traceStep(opts, "end", "file.decode.base64", { sizeBytes: bytes.byteLength });
+    }
+    if (!bytes) {
+        throw badRequest("MISSING_FILE_INPUT", "Missing file input. Provide fileId, url or base64");
+    }
+    if (bytes.byteLength > config.service.maxPdfBytes) {
+        throw badRequest("PDF_TOO_LARGE", `PDF exceeds max size (${config.service.maxPdfBytes} bytes)`, {
+            maxPdfBytes: config.service.maxPdfBytes,
+            sizeBytes: bytes.byteLength,
+        });
+    }
+    const meta = await opts.fileStore.put({
+        filename,
+        mimeType: "application/pdf",
+        bytes,
+    });
+    traceStep(opts, "end", "file.stored", { fileId: meta.id, sizeBytes: meta.sizeBytes });
+    return {
+        id: meta.id,
+        filename: meta.filename,
+        bytes,
+    };
+};
+const resolveReturnMode = (value) => normalizeReturnMode(value);
+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;
+};
+const extractTabularLatex = (value) => {
+    const text = stripCodeFences(value);
+    const blocks = text.match(/\\begin\{tabular\}[\s\S]*?\\end\{tabular\}/g);
+    if (!blocks || blocks.length === 0)
+        return "";
+    return blocks.map((b) => b.trim()).join("\n\n");
+};
+export const runPdfAgent = async (config, env, request, opts) => {
+    traceStep(opts, "start", "pdf.operation", { operation: request.operation });
+    const file = await ingestPdfFromPayload(config, request, opts);
+    const pageCount = await getPdfPageCount(config, file.bytes);
+    traceStep(opts, "log", "pdf.meta", { fileId: file.id, pageCount });
+    const pages = ensurePages(request.pages, pageCount, config.service.maxPagesPerRequest);
+    const scale = request.renderScale ?? config.service.defaultRenderScale;
+    const returnMode = resolveReturnMode(request.returnMode);
+    if (request.operation === "extract_pages") {
+        const images = [];
+        for (const page of pages) {
+            traceStep(opts, "start", "render.page", { page });
+            const rendered = await renderPdfPageToPng(config, file.bytes, page - 1, scale);
+            if (returnMode === "file_id") {
+                const stored = await opts.fileStore.put({
+                    filename: `${file.filename}-p${page}.png`,
+                    mimeType: "image/png",
+                    bytes: rendered.png,
+                });
+                images.push({ page, mimeType: "image/png", fileId: stored.id });
+            }
+            else if (returnMode === "url") {
+                const stored = await opts.fileStore.put({
+                    filename: `${file.filename}-p${page}.png`,
+                    mimeType: "image/png",
+                    bytes: rendered.png,
+                });
+                images.push({
+                    page,
+                    mimeType: "image/png",
+                    fileId: stored.id,
+                    url: `/api/files/get?fileId=${encodeURIComponent(stored.id)}`,
+                });
+            }
+            else {
+                images.push({
+                    page,
+                    mimeType: "image/png",
+                    data: toDataUrl(rendered.png, "image/png"),
+                });
+            }
+            traceStep(opts, "end", "render.page", { page, width: rendered.width, height: rendered.height });
+        }
+        const result = { fileId: file.id, pageCount, returnMode, images };
+        traceStep(opts, "end", "pdf.operation", { operation: request.operation });
+        return result;
+    }
+    const providerAlias = resolveProviderAlias(config, request.provider);
+    const model = resolveModelForProvider(config, providerAlias, request.model);
+    if (!model) {
+        throw badRequest("MODEL_REQUIRED", "model is required for OCR or table extraction; set agent.defaultModel");
+    }
+    if (request.operation === "ocr_pages") {
+        const results = [];
+        for (const page of pages) {
+            traceStep(opts, "start", "ocr.page", { page });
+            const rendered = await renderPdfPageToPng(config, file.bytes, page - 1, scale);
+            const imageDataUrl = toDataUrl(rendered.png, "image/png");
+            const fallbackText = await extractPdfPageText(config, file.bytes, page - 1);
+            const prompt = request.prompt?.trim() || config.agent.ocrPrompt;
+            const llmText = await visionRecognize({
+                config,
+                env,
+                providerAlias,
+                model,
+                prompt,
+                imageDataUrl,
+                runtimeApiKeys: request.providerApiKeys,
+            });
+            const text = stripCodeFences(llmText || fallbackText || "");
+            results.push({ page, text });
+            traceStep(opts, "end", "ocr.page", { page, chars: text.length });
+        }
+        const result = {
+            fileId: file.id,
+            pageCount,
+            provider: providerAlias,
+            model,
+            pages: results,
+        };
+        traceStep(opts, "end", "pdf.operation", { operation: request.operation });
+        return result;
+    }
+    const tables = [];
+    for (const page of pages) {
+        traceStep(opts, "start", "table.page", { page });
+        const rendered = await renderPdfPageToPng(config, file.bytes, page - 1, scale);
+        const imageDataUrl = toDataUrl(rendered.png, "image/png");
+        const prompt = request.prompt?.trim() || config.agent.tablePrompt;
+        const rawLatex = await visionRecognize({
+            config,
+            env,
+            providerAlias,
+            model,
+            prompt,
+            imageDataUrl,
+            runtimeApiKeys: request.providerApiKeys,
+        });
+        const latex = extractTabularLatex(rawLatex);
+        if (!latex) {
+            throw unprocessable("TABLE_LATEX_MISSING", `table extraction did not return valid LaTeX tabular for page ${page}`, {
+                page,
+            });
+        }
+        tables.push({ page, latex });
+        traceStep(opts, "end", "table.page", { page, chars: latex.length });
+    }
+    const result = {
+        fileId: file.id,
+        pageCount,
+        provider: providerAlias,
+        model,
+        pages: tables,
+    };
+    traceStep(opts, "end", "pdf.operation", { operation: request.operation });
+    return result;
+};

package/dist/pdf-config.d.ts

@@ -0,0 +1,4 @@
+import type { Env } from "./types.js";
+import type { EchoPdfConfig } from "./pdf-types.js";
+export declare const loadEchoPdfConfig: (env: Env) => EchoPdfConfig;
+export declare const readRequiredEnv: (env: Env, key: string) => string;

package/dist/pdf-config.js

@@ -0,0 +1,130 @@
+import rawConfig from "../echo-pdf.config.json" with { type: "json" };
+const ENV_PATTERN = /\$\{([A-Z0-9_]+)\}/g;
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const interpolateEnv = (input, env) => input.replace(ENV_PATTERN, (_, name) => {
+    const value = env[name];
+    return typeof value === "string" ? value : `\${${name}}`;
+});
+const resolveEnvRefs = (value, env) => {
+    if (typeof value === "string")
+        return interpolateEnv(value, env);
+    if (Array.isArray(value))
+        return value.map((item) => resolveEnvRefs(item, env));
+    if (isObject(value)) {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            out[key] = resolveEnvRefs(nested, env);
+        }
+        return out;
+    }
+    return value;
+};
+const validateConfig = (config) => {
+    if (!config.service?.name)
+        throw new Error("service.name is required");
+    if (!config.pdfium?.wasmUrl)
+        throw new Error("pdfium.wasmUrl is required");
+    if (!config.service?.storage)
+        throw new Error("service.storage is required");
+    if (typeof config.service.publicBaseUrl === "string" &&
+        config.service.publicBaseUrl.length > 0 &&
+        !/^https?:\/\//.test(config.service.publicBaseUrl)) {
+        throw new Error("service.publicBaseUrl must start with http:// or https://");
+    }
+    if (typeof config.service.fileGet?.cacheTtlSeconds === "number" && config.service.fileGet.cacheTtlSeconds < 0) {
+        throw new Error("service.fileGet.cacheTtlSeconds must be >= 0");
+    }
+    if (!Number.isFinite(config.service.storage.maxFileBytes) || config.service.storage.maxFileBytes <= 0) {
+        throw new Error("service.storage.maxFileBytes must be positive");
+    }
+    if (config.service.storage.maxFileBytes < config.service.maxPdfBytes) {
+        throw new Error("service.storage.maxFileBytes must be >= service.maxPdfBytes");
+    }
+    if (!Number.isFinite(config.service.storage.maxTotalBytes) || config.service.storage.maxTotalBytes <= 0) {
+        throw new Error("service.storage.maxTotalBytes must be positive");
+    }
+    if (config.service.storage.maxTotalBytes < config.service.storage.maxFileBytes) {
+        throw new Error("service.storage.maxTotalBytes must be >= maxFileBytes");
+    }
+    if (!Number.isFinite(config.service.storage.ttlHours) || config.service.storage.ttlHours <= 0) {
+        throw new Error("service.storage.ttlHours must be positive");
+    }
+    if (!Number.isFinite(config.service.storage.cleanupBatchSize) || config.service.storage.cleanupBatchSize <= 0) {
+        throw new Error("service.storage.cleanupBatchSize must be positive");
+    }
+    if (!config.agent?.defaultProvider)
+        throw new Error("agent.defaultProvider is required");
+    if (!config.providers?.[config.agent.defaultProvider]) {
+        throw new Error(`default provider "${config.agent.defaultProvider}" missing`);
+    }
+    if (typeof config.agent.defaultModel !== "string") {
+        throw new Error("agent.defaultModel must be a string");
+    }
+    return config;
+};
+export const loadEchoPdfConfig = (env) => {
+    const fromEnv = env.ECHO_PDF_CONFIG_JSON?.trim();
+    const configJson = fromEnv ? JSON.parse(fromEnv) : rawConfig;
+    const resolved = resolveEnvRefs(configJson, env);
+    const providerOverride = env.ECHO_PDF_DEFAULT_PROVIDER;
+    const modelOverride = env.ECHO_PDF_DEFAULT_MODEL;
+    const publicBaseUrlOverride = env.ECHO_PDF_PUBLIC_BASE_URL;
+    const fileGetAuthHeaderOverride = env.ECHO_PDF_FILE_GET_AUTH_HEADER;
+    const fileGetAuthEnvOverride = env.ECHO_PDF_FILE_GET_AUTH_ENV;
+    const fileGetCacheTtlOverride = env.ECHO_PDF_FILE_GET_CACHE_TTL_SECONDS;
+    const withOverrides = {
+        ...resolved,
+        service: {
+            ...resolved.service,
+            publicBaseUrl: typeof publicBaseUrlOverride === "string" && publicBaseUrlOverride.trim().length > 0
+                ? publicBaseUrlOverride.trim()
+                : resolved.service.publicBaseUrl,
+            fileGet: {
+                authHeader: typeof fileGetAuthHeaderOverride === "string" && fileGetAuthHeaderOverride.trim().length > 0
+                    ? fileGetAuthHeaderOverride.trim()
+                    : resolved.service.fileGet?.authHeader,
+                authEnv: typeof fileGetAuthEnvOverride === "string" && fileGetAuthEnvOverride.trim().length > 0
+                    ? fileGetAuthEnvOverride.trim()
+                    : resolved.service.fileGet?.authEnv,
+                cacheTtlSeconds: (() => {
+                    if (typeof fileGetCacheTtlOverride === "string" && fileGetCacheTtlOverride.trim().length > 0) {
+                        const value = Number(fileGetCacheTtlOverride);
+                        return Number.isFinite(value) && value >= 0 ? Math.floor(value) : resolved.service.fileGet?.cacheTtlSeconds;
+                    }
+                    return resolved.service.fileGet?.cacheTtlSeconds;
+                })(),
+            },
+        },
+        agent: {
+            ...resolved.agent,
+            defaultProvider: typeof providerOverride === "string" && providerOverride.trim().length > 0
+                ? providerOverride.trim()
+                : resolved.agent.defaultProvider,
+            defaultModel: typeof modelOverride === "string" && modelOverride.trim().length > 0
+                ? modelOverride.trim()
+                : resolved.agent.defaultModel,
+        },
+    };
+    return validateConfig(withOverrides);
+};
+export const readRequiredEnv = (env, key) => {
+    const read = (name) => {
+        const value = env[name];
+        return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+    };
+    const direct = read(key);
+    if (direct)
+        return direct;
+    // Backward compatibility: allow *_KEY and *_API_KEY aliases.
+    if (key.endsWith("_API_KEY")) {
+        const alt = read(key.replace(/_API_KEY$/, "_KEY"));
+        if (alt)
+            return alt;
+    }
+    if (key.endsWith("_KEY")) {
+        const alt = read(key.replace(/_KEY$/, "_API_KEY"));
+        if (alt)
+            return alt;
+    }
+    throw new Error(`Missing required env var "${key}"`);
+};

package/dist/pdf-storage.d.ts

@@ -0,0 +1,8 @@
+import type { EchoPdfConfig } from "./pdf-types.js";
+import type { Env, FileStore } from "./types.js";
+export interface RuntimeFileStoreBundle {
+    readonly store: FileStore;
+    stats: () => Promise<unknown>;
+    cleanup: () => Promise<unknown>;
+}
+export declare const getRuntimeFileStore: (env: Env, config: EchoPdfConfig) => RuntimeFileStoreBundle;

package/dist/pdf-storage.js

@@ -0,0 +1,86 @@
+import { DurableObjectFileStore } from "./file-store-do.js";
+import { R2FileStore } from "./r2-file-store.js";
+class InMemoryFileStore {
+    store = new Map();
+    async put(input) {
+        const id = crypto.randomUUID();
+        const record = {
+            id,
+            filename: input.filename,
+            mimeType: input.mimeType,
+            sizeBytes: input.bytes.byteLength,
+            createdAt: new Date().toISOString(),
+            bytes: input.bytes,
+        };
+        this.store.set(id, record);
+        return this.toMeta(record);
+    }
+    async get(fileId) {
+        return this.store.get(fileId) ?? null;
+    }
+    async list() {
+        return [...this.store.values()].map((record) => this.toMeta(record));
+    }
+    async delete(fileId) {
+        return this.store.delete(fileId);
+    }
+    toMeta(record) {
+        return {
+            id: record.id,
+            filename: record.filename,
+            mimeType: record.mimeType,
+            sizeBytes: record.sizeBytes,
+            createdAt: record.createdAt,
+        };
+    }
+}
+const fallbackStore = new InMemoryFileStore();
+const DO_SAFE_MAX_FILE_BYTES = 1_200_000;
+export const getRuntimeFileStore = (env, config) => {
+    if (env.FILE_STORE_BUCKET) {
+        const store = new R2FileStore(env.FILE_STORE_BUCKET, config.service.storage);
+        return {
+            store,
+            stats: async () => store.stats(),
+            cleanup: async () => store.cleanup(),
+        };
+    }
+    if (env.FILE_STORE_DO) {
+        if (config.service.storage.maxFileBytes > DO_SAFE_MAX_FILE_BYTES) {
+            throw new Error(`service.storage.maxFileBytes=${config.service.storage.maxFileBytes} exceeds DO backend limit ${DO_SAFE_MAX_FILE_BYTES}; bind FILE_STORE_BUCKET (R2) or reduce maxFileBytes`);
+        }
+        const store = new DurableObjectFileStore(env.FILE_STORE_DO, config.service.storage);
+        return {
+            store,
+            stats: async () => store.stats(),
+            cleanup: async () => store.cleanup(),
+        };
+    }
+    return {
+        store: fallbackStore,
+        stats: async () => {
+            const files = await fallbackStore.list();
+            const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0);
+            return {
+                backend: "memory",
+                policy: config.service.storage,
+                stats: {
+                    fileCount: files.length,
+                    totalBytes,
+                },
+            };
+        },
+        cleanup: async () => ({
+            backend: "memory",
+            deletedExpired: 0,
+            deletedEvicted: 0,
+            stats: await (async () => {
+                const files = await fallbackStore.list();
+                return {
+                    fileCount: files.length,
+                    totalBytes: files.reduce((sum, file) => sum + file.sizeBytes, 0),
+                };
+            })(),
+        }),
+    };
+};

package/dist/pdf-types.d.ts

@@ -0,0 +1,79 @@
+import type { ProviderType, ReturnMode } from "./types.js";
+export interface EchoPdfProviderConfig {
+    readonly type: ProviderType;
+    readonly apiKeyEnv: string;
+    readonly baseUrl?: string;
+    readonly headers?: Record<string, string>;
+    readonly timeoutMs?: number;
+    readonly endpoints?: {
+        readonly chatCompletionsPath?: string;
+        readonly modelsPath?: string;
+    };
+}
+export interface StoragePolicy {
+    readonly maxFileBytes: number;
+    readonly maxTotalBytes: number;
+    readonly ttlHours: number;
+    readonly cleanupBatchSize: number;
+}
+export interface EchoPdfConfig {
+    readonly service: {
+        readonly name: string;
+        readonly publicBaseUrl?: string;
+        readonly fileGet?: {
+            readonly authHeader?: string;
+            readonly authEnv?: string;
+            readonly cacheTtlSeconds?: number;
+        };
+        readonly maxPdfBytes: number;
+        readonly maxPagesPerRequest: number;
+        readonly defaultRenderScale: number;
+        readonly storage: StoragePolicy;
+    };
+    readonly pdfium: {
+        readonly wasmUrl: string;
+    };
+    readonly agent: {
+        readonly defaultProvider: string;
+        readonly defaultModel: string;
+        readonly ocrPrompt: string;
+        readonly tablePrompt: string;
+    };
+    readonly providers: Record<string, EchoPdfProviderConfig>;
+    readonly mcp: {
+        readonly serverName: string;
+        readonly version: string;
+        readonly authHeader?: string;
+        readonly authEnv?: string;
+    };
+}
+export interface AgentTraceEvent {
+    readonly kind: "step";
+    readonly phase: "start" | "end" | "log";
+    readonly name: string;
+    readonly level?: "info" | "error";
+    readonly payload?: unknown;
+}
+export interface PdfOperationRequest {
+    readonly operation: "extract_pages" | "ocr_pages" | "tables_to_latex";
+    readonly fileId?: string;
+    readonly url?: string;
+    readonly base64?: string;
+    readonly filename?: string;
+    readonly pages: ReadonlyArray<number>;
+    readonly renderScale?: number;
+    readonly provider?: string;
+    readonly model: string;
+    readonly providerApiKeys?: Record<string, string>;
+    readonly returnMode?: ReturnMode;
+    readonly prompt?: string;
+}
+export interface ToolSchema {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly source: {
+        readonly kind: "local";
+        readonly toolName: string;
+    };
+}

package/dist/pdf-types.js

@@ -0,0 +1 @@
+export {};

package/dist/pdfium-engine.d.ts

@@ -0,0 +1,9 @@
+import type { EchoPdfConfig } from "./pdf-types.js";
+export declare const getPdfPageCount: (config: EchoPdfConfig, bytes: Uint8Array) => Promise<number>;
+export declare const renderPdfPageToPng: (config: EchoPdfConfig, bytes: Uint8Array, pageIndex: number, scale?: number) => Promise<{
+    width: number;
+    height: number;
+    png: Uint8Array;
+}>;
+export declare const extractPdfPageText: (config: EchoPdfConfig, bytes: Uint8Array, pageIndex: number) => Promise<string>;
+export declare const toBytes: (value: string) => Promise<Uint8Array>;