@undefineds.co/xpod 0.3.57 → 0.3.61

package/dist/document/L0SourceSummary.d.ts

@@ -0,0 +1,103 @@
+import type { ReaderExpectedUse } from './ReaderPolicy';
+export type SourceUsageSurface = 'chat' | 'task' | 'run' | 'message' | 'tool-call' | 'upload' | 'ui-open';
+export type SourceUsageConfidence = 'low' | 'medium' | 'high';
+export type L0SourceSummaryMode = 'context-inferred' | 'lightweight-preview' | 'old-cache';
+export type L0SourceEvidence = 'path' | 'mime' | 'message-context' | 'tool-history' | 'user-description' | 'neighbor-files' | 'old-cache' | 'local-preview';
+export interface SourceUsageMention {
+    surface: SourceUsageSurface;
+    resource: string;
+    title?: string;
+    excerpt?: string;
+    mentionedAs?: string;
+    actor?: string;
+    timestamp: string;
+    confidence: SourceUsageConfidence;
+}
+export interface SourceRecentAction {
+    action: 'uploaded' | 'opened' | 'edited' | 'moved' | 'renamed' | 'attached' | 'referenced' | 'generated';
+    resource: string;
+    timestamp: string;
+    actor?: string;
+}
+export interface RelatedSource {
+    source: string;
+    relation: 'same-folder' | 'linked-from-message' | 'generated-from' | 'attached-together' | 'referenced-by-same-run';
+}
+export interface SourceUsageRecord {
+    surface: SourceUsageSurface;
+    resource: string;
+    text?: string;
+    title?: string;
+    actor?: string;
+    timestamp: string;
+    action?: SourceRecentAction['action'];
+    attachment?: {
+        name?: string;
+        url?: string;
+        id?: string;
+    };
+}
+export interface BuildSourceUsageContextInput {
+    source: string;
+    records: SourceUsageRecord[];
+    maxExcerptLength?: number;
+}
+export interface SourceUsageContext {
+    source: string;
+    mentions: SourceUsageMention[];
+    recentActions: SourceRecentAction[];
+    relatedSources?: RelatedSource[];
+}
+export type L0GenerationAction = 'create-l0' | 'reader-required' | 'skip';
+export interface L0SourceSummaryPlan {
+    action: L0GenerationAction;
+    mode?: L0SourceSummaryMode;
+    evidence: L0SourceEvidence[];
+    confidence: SourceUsageConfidence;
+    previewSuggestion?: {
+        pages?: string;
+        bytes?: number;
+        lines?: string;
+    };
+    reason: string;
+}
+export interface L0SourceSummaryInput {
+    source: string;
+    sourceUsageContext: SourceUsageContext;
+    requestedEvidence?: ReaderExpectedUse;
+    oldCacheFresh?: boolean;
+    lightweightPreviewAvailable?: boolean;
+    pathHint?: string;
+}
+export interface L0SourceSummary {
+    source: string;
+    summary?: string;
+    mode: L0SourceSummaryMode;
+    confidence: SourceUsageConfidence;
+    evidence: L0SourceEvidence[];
+    previewRange?: {
+        pages?: string;
+        bytes?: number;
+        lines?: string;
+    };
+    readerConfirmed: false;
+    sourceUsageContext?: SourceUsageContext;
+}
+export interface CreateL0SourceSummaryInput {
+    source: string;
+    summary?: string;
+    mode: L0SourceSummaryMode;
+    confidence: SourceUsageConfidence;
+    evidence: L0SourceEvidence[];
+    previewRange?: {
+        pages?: string;
+        bytes?: number;
+        lines?: string;
+    };
+    sourceUsageContext?: SourceUsageContext;
+    maxExcerptLength?: number;
+}
+export declare function chooseL0SourceSummaryPlan(input: L0SourceSummaryInput): L0SourceSummaryPlan;
+export declare function createL0SourceSummary(input: CreateL0SourceSummaryInput): L0SourceSummary;
+export declare function boundSourceUsageContext(context: SourceUsageContext, maxExcerptLength?: number): SourceUsageContext;
+export declare function buildSourceUsageContext(input: BuildSourceUsageContextInput): SourceUsageContext;

package/dist/document/L0SourceSummary.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chooseL0SourceSummaryPlan = chooseL0SourceSummaryPlan;
+exports.createL0SourceSummary = createL0SourceSummary;
+exports.boundSourceUsageContext = boundSourceUsageContext;
+exports.buildSourceUsageContext = buildSourceUsageContext;
+const ReaderPolicy_1 = require("./ReaderPolicy");
+const READER_REQUIRED_USES = new Set(['table-extraction', 'ocr', 'full-import']);
+function chooseL0SourceSummaryPlan(input) {
+    if (input.requestedEvidence && READER_REQUIRED_USES.has(input.requestedEvidence)) {
+        return {
+            action: 'reader-required',
+            evidence: [],
+            confidence: 'low',
+            reason: `Requested evidence ${input.requestedEvidence} needs reader output beyond L0.`,
+        };
+    }
+    if (input.oldCacheFresh) {
+        return {
+            action: 'create-l0',
+            mode: 'old-cache',
+            evidence: ['old-cache'],
+            confidence: 'high',
+            reason: 'Fresh old cache can be reused for source-level summary.',
+        };
+    }
+    const highContext = input.sourceUsageContext.mentions.some((mention) => mention.confidence === 'high');
+    const meaningfulPath = hasMeaningfulPath(input.pathHint ?? input.source);
+    if (highContext || meaningfulPath) {
+        const evidence = [];
+        if (meaningfulPath)
+            evidence.push('path');
+        if (highContext)
+            evidence.push('message-context');
+        return {
+            action: 'create-l0',
+            mode: 'context-inferred',
+            evidence,
+            confidence: highContext ? 'high' : 'medium',
+            reason: 'Path or product context is enough to infer an L0 source summary.',
+        };
+    }
+    if (input.lightweightPreviewAvailable) {
+        return {
+            action: 'create-l0',
+            mode: 'lightweight-preview',
+            evidence: ['local-preview'],
+            confidence: 'medium',
+            previewSuggestion: {
+                pages: String(ReaderPolicy_1.DEFAULT_DOCUMENT_READER_POLICY.l0.suggestion.localPreviewPages),
+                bytes: ReaderPolicy_1.DEFAULT_DOCUMENT_READER_POLICY.l0.suggestion.localPreviewBytes,
+            },
+            reason: 'Context is weak; read lightweight preview before writing L0.',
+        };
+    }
+    return {
+        action: 'skip',
+        evidence: [],
+        confidence: 'low',
+        reason: 'No reliable context or preview is available for L0.',
+    };
+}
+function createL0SourceSummary(input) {
+    return {
+        source: input.source,
+        summary: input.summary,
+        mode: input.mode,
+        confidence: input.confidence,
+        evidence: [...new Set(input.evidence)],
+        previewRange: input.previewRange,
+        readerConfirmed: false,
+        sourceUsageContext: input.sourceUsageContext
+            ? boundSourceUsageContext(input.sourceUsageContext, input.maxExcerptLength ?? 240)
+            : undefined,
+    };
+}
+function boundSourceUsageContext(context, maxExcerptLength = 240) {
+    return {
+        ...context,
+        mentions: context.mentions.map((mention) => ({
+            ...mention,
+            excerpt: mention.excerpt ? truncate(mention.excerpt, maxExcerptLength) : undefined,
+        })),
+        recentActions: [...context.recentActions],
+        relatedSources: context.relatedSources ? [...context.relatedSources] : undefined,
+    };
+}
+function buildSourceUsageContext(input) {
+    const sourceName = sourceBasename(input.source);
+    const maxExcerptLength = input.maxExcerptLength ?? 240;
+    const mentions = [];
+    const recentActions = [];
+    for (const record of input.records) {
+        const matchedAttachment = attachmentMatchesSource(record.attachment, input.source, sourceName);
+        const matchedText = textMentionsSource(record.text, input.source, sourceName);
+        if (matchedAttachment || matchedText) {
+            const excerptSource = record.text ?? record.title ?? record.attachment?.name ?? sourceName;
+            mentions.push({
+                surface: record.surface,
+                resource: record.resource,
+                title: record.title,
+                excerpt: truncate(excerptSource, maxExcerptLength),
+                mentionedAs: matchedAttachment ? (record.attachment?.name ?? sourceName) : sourceName,
+                actor: record.actor,
+                timestamp: record.timestamp,
+                confidence: matchedAttachment ? 'high' : 'medium',
+            });
+        }
+        if (record.action && (matchedAttachment || matchedText)) {
+            recentActions.push({
+                action: record.action,
+                resource: record.resource,
+                timestamp: record.timestamp,
+                actor: record.actor,
+            });
+        }
+    }
+    return {
+        source: input.source,
+        mentions,
+        recentActions,
+    };
+}
+function attachmentMatchesSource(attachment, source, sourceName) {
+    if (!attachment)
+        return false;
+    return attachment.url === source || attachment.id === source || attachment.name === sourceName;
+}
+function textMentionsSource(text, source, sourceName) {
+    if (!text)
+        return false;
+    return text.includes(source) || text.includes(sourceName);
+}
+function sourceBasename(source) {
+    try {
+        const parsed = new URL(source);
+        return decodeURIComponent(parsed.pathname.split('/').filter(Boolean).pop() ?? source);
+    }
+    catch {
+        return source.split(/[\/]/u).filter(Boolean).pop() ?? source;
+    }
+}
+function hasMeaningfulPath(path) {
+    const tail = path.split(/[/?#]/u).filter(Boolean).pop() ?? path;
+    const base = tail.replace(/\.[a-z0-9]+$/iu, '').toLowerCase();
+    if (!base || base.length < 4)
+        return false;
+    if (/^(scan|image|img|doc|file|untitled|new|tmp|temp)[-_ ]?\d*$/iu.test(base))
+        return false;
+    return /[a-z\u4e00-\u9fff]{3,}/iu.test(base);
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return value.slice(0, Math.max(0, maxLength - 1)) + '…';
+}
+//# sourceMappingURL=L0SourceSummary.js.map

package/dist/document/L0SourceSummary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"L0SourceSummary.js","sourceRoot":"","sources":["../../src/document/L0SourceSummary.ts"],"names":[],"mappings":"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","sourcesContent":["import { DEFAULT_DOCUMENT_READER_POLICY } from './ReaderPolicy';\nimport type { ReaderExpectedUse } from './ReaderPolicy';\n\nexport type SourceUsageSurface = 'chat' | 'task' | 'run' | 'message' | 'tool-call' | 'upload' | 'ui-open';\nexport type SourceUsageConfidence = 'low' | 'medium' | 'high';\nexport type L0SourceSummaryMode = 'context-inferred' | 'lightweight-preview' | 'old-cache';\nexport type L0SourceEvidence =\n  | 'path'\n  | 'mime'\n  | 'message-context'\n  | 'tool-history'\n  | 'user-description'\n  | 'neighbor-files'\n  | 'old-cache'\n  | 'local-preview';\n\nexport interface SourceUsageMention {\n  surface: SourceUsageSurface;\n  resource: string;\n  title?: string;\n  excerpt?: string;\n  mentionedAs?: string;\n  actor?: string;\n  timestamp: string;\n  confidence: SourceUsageConfidence;\n}\n\nexport interface SourceRecentAction {\n  action: 'uploaded' | 'opened' | 'edited' | 'moved' | 'renamed' | 'attached' | 'referenced' | 'generated';\n  resource: string;\n  timestamp: string;\n  actor?: string;\n}\n\nexport interface RelatedSource {\n  source: string;\n  relation: 'same-folder' | 'linked-from-message' | 'generated-from' | 'attached-together' | 'referenced-by-same-run';\n}\n\n\nexport interface SourceUsageRecord {\n  surface: SourceUsageSurface;\n  resource: string;\n  text?: string;\n  title?: string;\n  actor?: string;\n  timestamp: string;\n  action?: SourceRecentAction['action'];\n  attachment?: {\n    name?: string;\n    url?: string;\n    id?: string;\n  };\n}\n\nexport interface BuildSourceUsageContextInput {\n  source: string;\n  records: SourceUsageRecord[];\n  maxExcerptLength?: number;\n}\n\nexport interface SourceUsageContext {\n  source: string;\n  mentions: SourceUsageMention[];\n  recentActions: SourceRecentAction[];\n  relatedSources?: RelatedSource[];\n}\n\nexport type L0GenerationAction = 'create-l0' | 'reader-required' | 'skip';\n\nexport interface L0SourceSummaryPlan {\n  action: L0GenerationAction;\n  mode?: L0SourceSummaryMode;\n  evidence: L0SourceEvidence[];\n  confidence: SourceUsageConfidence;\n  previewSuggestion?: {\n    pages?: string;\n    bytes?: number;\n    lines?: string;\n  };\n  reason: string;\n}\n\nexport interface L0SourceSummaryInput {\n  source: string;\n  sourceUsageContext: SourceUsageContext;\n  requestedEvidence?: ReaderExpectedUse;\n  oldCacheFresh?: boolean;\n  lightweightPreviewAvailable?: boolean;\n  pathHint?: string;\n}\n\nexport interface L0SourceSummary {\n  source: string;\n  summary?: string;\n  mode: L0SourceSummaryMode;\n  confidence: SourceUsageConfidence;\n  evidence: L0SourceEvidence[];\n  previewRange?: {\n    pages?: string;\n    bytes?: number;\n    lines?: string;\n  };\n  readerConfirmed: false;\n  sourceUsageContext?: SourceUsageContext;\n}\n\nexport interface CreateL0SourceSummaryInput {\n  source: string;\n  summary?: string;\n  mode: L0SourceSummaryMode;\n  confidence: SourceUsageConfidence;\n  evidence: L0SourceEvidence[];\n  previewRange?: {\n    pages?: string;\n    bytes?: number;\n    lines?: string;\n  };\n  sourceUsageContext?: SourceUsageContext;\n  maxExcerptLength?: number;\n}\n\nconst READER_REQUIRED_USES = new Set<ReaderExpectedUse>(['table-extraction', 'ocr', 'full-import']);\n\nexport function chooseL0SourceSummaryPlan(input: L0SourceSummaryInput): L0SourceSummaryPlan {\n  if (input.requestedEvidence && READER_REQUIRED_USES.has(input.requestedEvidence)) {\n    return {\n      action: 'reader-required',\n      evidence: [],\n      confidence: 'low',\n      reason: `Requested evidence ${input.requestedEvidence} needs reader output beyond L0.`,\n    };\n  }\n\n  if (input.oldCacheFresh) {\n    return {\n      action: 'create-l0',\n      mode: 'old-cache',\n      evidence: ['old-cache'],\n      confidence: 'high',\n      reason: 'Fresh old cache can be reused for source-level summary.',\n    };\n  }\n\n  const highContext = input.sourceUsageContext.mentions.some((mention) => mention.confidence === 'high');\n  const meaningfulPath = hasMeaningfulPath(input.pathHint ?? input.source);\n  if (highContext || meaningfulPath) {\n    const evidence: L0SourceEvidence[] = [];\n    if (meaningfulPath) evidence.push('path');\n    if (highContext) evidence.push('message-context');\n    return {\n      action: 'create-l0',\n      mode: 'context-inferred',\n      evidence,\n      confidence: highContext ? 'high' : 'medium',\n      reason: 'Path or product context is enough to infer an L0 source summary.',\n    };\n  }\n\n  if (input.lightweightPreviewAvailable) {\n    return {\n      action: 'create-l0',\n      mode: 'lightweight-preview',\n      evidence: ['local-preview'],\n      confidence: 'medium',\n      previewSuggestion: {\n        pages: String(DEFAULT_DOCUMENT_READER_POLICY.l0.suggestion.localPreviewPages),\n        bytes: DEFAULT_DOCUMENT_READER_POLICY.l0.suggestion.localPreviewBytes,\n      },\n      reason: 'Context is weak; read lightweight preview before writing L0.',\n    };\n  }\n\n  return {\n    action: 'skip',\n    evidence: [],\n    confidence: 'low',\n    reason: 'No reliable context or preview is available for L0.',\n  };\n}\n\nexport function createL0SourceSummary(input: CreateL0SourceSummaryInput): L0SourceSummary {\n  return {\n    source: input.source,\n    summary: input.summary,\n    mode: input.mode,\n    confidence: input.confidence,\n    evidence: [...new Set(input.evidence)],\n    previewRange: input.previewRange,\n    readerConfirmed: false,\n    sourceUsageContext: input.sourceUsageContext\n      ? boundSourceUsageContext(input.sourceUsageContext, input.maxExcerptLength ?? 240)\n      : undefined,\n  };\n}\n\nexport function boundSourceUsageContext(context: SourceUsageContext, maxExcerptLength = 240): SourceUsageContext {\n  return {\n    ...context,\n    mentions: context.mentions.map((mention) => ({\n      ...mention,\n      excerpt: mention.excerpt ? truncate(mention.excerpt, maxExcerptLength) : undefined,\n    })),\n    recentActions: [...context.recentActions],\n    relatedSources: context.relatedSources ? [...context.relatedSources] : undefined,\n  };\n}\n\n\nexport function buildSourceUsageContext(input: BuildSourceUsageContextInput): SourceUsageContext {\n  const sourceName = sourceBasename(input.source);\n  const maxExcerptLength = input.maxExcerptLength ?? 240;\n  const mentions: SourceUsageMention[] = [];\n  const recentActions: SourceRecentAction[] = [];\n\n  for (const record of input.records) {\n    const matchedAttachment = attachmentMatchesSource(record.attachment, input.source, sourceName);\n    const matchedText = textMentionsSource(record.text, input.source, sourceName);\n\n    if (matchedAttachment || matchedText) {\n      const excerptSource = record.text ?? record.title ?? record.attachment?.name ?? sourceName;\n      mentions.push({\n        surface: record.surface,\n        resource: record.resource,\n        title: record.title,\n        excerpt: truncate(excerptSource, maxExcerptLength),\n        mentionedAs: matchedAttachment ? (record.attachment?.name ?? sourceName) : sourceName,\n        actor: record.actor,\n        timestamp: record.timestamp,\n        confidence: matchedAttachment ? 'high' : 'medium',\n      });\n    }\n\n    if (record.action && (matchedAttachment || matchedText)) {\n      recentActions.push({\n        action: record.action,\n        resource: record.resource,\n        timestamp: record.timestamp,\n        actor: record.actor,\n      });\n    }\n  }\n\n  return {\n    source: input.source,\n    mentions,\n    recentActions,\n  };\n}\n\nfunction attachmentMatchesSource(\n  attachment: SourceUsageRecord['attachment'] | undefined,\n  source: string,\n  sourceName: string,\n): boolean {\n  if (!attachment) return false;\n  return attachment.url === source || attachment.id === source || attachment.name === sourceName;\n}\n\nfunction textMentionsSource(text: string | undefined, source: string, sourceName: string): boolean {\n  if (!text) return false;\n  return text.includes(source) || text.includes(sourceName);\n}\n\nfunction sourceBasename(source: string): string {\n  try {\n    const parsed = new URL(source);\n    return decodeURIComponent(parsed.pathname.split('/').filter(Boolean).pop() ?? source);\n  } catch {\n    return source.split(/[\\/]/u).filter(Boolean).pop() ?? source;\n  }\n}\n\nfunction hasMeaningfulPath(path: string): boolean {\n  const tail = path.split(/[/?#]/u).filter(Boolean).pop() ?? path;\n  const base = tail.replace(/\\.[a-z0-9]+$/iu, '').toLowerCase();\n  if (!base || base.length < 4) return false;\n  if (/^(scan|image|img|doc|file|untitled|new|tmp|temp)[-_ ]?\\d*$/iu.test(base)) return false;\n  return /[a-z\\u4e00-\\u9fff]{3,}/iu.test(base);\n}\n\nfunction truncate(value: string, maxLength: number): string {\n  if (value.length <= maxLength) return value;\n  return value.slice(0, Math.max(0, maxLength - 1)) + '…';\n}\n"]}

package/dist/document/L0SourceSummary.jsonld

@@ -0,0 +1,326 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention",
+      "@type": "AbstractClass",
+      "requireElement": "SourceUsageMention",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_surface",
+          "memberFieldName": "surface"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_resource",
+          "memberFieldName": "resource"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_title",
+          "memberFieldName": "title"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_excerpt",
+          "memberFieldName": "excerpt"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_mentionedAs",
+          "memberFieldName": "mentionedAs"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_actor",
+          "memberFieldName": "actor"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_timestamp",
+          "memberFieldName": "timestamp"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageMention__member_confidence",
+          "memberFieldName": "confidence"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceRecentAction",
+      "@type": "AbstractClass",
+      "requireElement": "SourceRecentAction",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceRecentAction__member_action",
+          "memberFieldName": "action"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceRecentAction__member_resource",
+          "memberFieldName": "resource"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceRecentAction__member_timestamp",
+          "memberFieldName": "timestamp"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceRecentAction__member_actor",
+          "memberFieldName": "actor"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#RelatedSource",
+      "@type": "AbstractClass",
+      "requireElement": "RelatedSource",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#RelatedSource__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#RelatedSource__member_relation",
+          "memberFieldName": "relation"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord",
+      "@type": "AbstractClass",
+      "requireElement": "SourceUsageRecord",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_surface",
+          "memberFieldName": "surface"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_resource",
+          "memberFieldName": "resource"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_text",
+          "memberFieldName": "text"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_title",
+          "memberFieldName": "title"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_actor",
+          "memberFieldName": "actor"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_timestamp",
+          "memberFieldName": "timestamp"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_action",
+          "memberFieldName": "action"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageRecord__member_attachment",
+          "memberFieldName": "attachment"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#BuildSourceUsageContextInput",
+      "@type": "AbstractClass",
+      "requireElement": "BuildSourceUsageContextInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#BuildSourceUsageContextInput__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#BuildSourceUsageContextInput__member_records",
+          "memberFieldName": "records"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#BuildSourceUsageContextInput__member_maxExcerptLength",
+          "memberFieldName": "maxExcerptLength"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageContext",
+      "@type": "AbstractClass",
+      "requireElement": "SourceUsageContext",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageContext__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageContext__member_mentions",
+          "memberFieldName": "mentions"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageContext__member_recentActions",
+          "memberFieldName": "recentActions"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#SourceUsageContext__member_relatedSources",
+          "memberFieldName": "relatedSources"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan",
+      "@type": "AbstractClass",
+      "requireElement": "L0SourceSummaryPlan",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan__member_action",
+          "memberFieldName": "action"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan__member_mode",
+          "memberFieldName": "mode"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan__member_evidence",
+          "memberFieldName": "evidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan__member_confidence",
+          "memberFieldName": "confidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan__member_previewSuggestion",
+          "memberFieldName": "previewSuggestion"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryPlan__member_reason",
+          "memberFieldName": "reason"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput",
+      "@type": "AbstractClass",
+      "requireElement": "L0SourceSummaryInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput__member_sourceUsageContext",
+          "memberFieldName": "sourceUsageContext"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput__member_requestedEvidence",
+          "memberFieldName": "requestedEvidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput__member_oldCacheFresh",
+          "memberFieldName": "oldCacheFresh"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput__member_lightweightPreviewAvailable",
+          "memberFieldName": "lightweightPreviewAvailable"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummaryInput__member_pathHint",
+          "memberFieldName": "pathHint"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary",
+      "@type": "AbstractClass",
+      "requireElement": "L0SourceSummary",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_summary",
+          "memberFieldName": "summary"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_mode",
+          "memberFieldName": "mode"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_confidence",
+          "memberFieldName": "confidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_evidence",
+          "memberFieldName": "evidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_previewRange",
+          "memberFieldName": "previewRange"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_readerConfirmed",
+          "memberFieldName": "readerConfirmed"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#L0SourceSummary__member_sourceUsageContext",
+          "memberFieldName": "sourceUsageContext"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput",
+      "@type": "AbstractClass",
+      "requireElement": "CreateL0SourceSummaryInput",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_source",
+          "memberFieldName": "source"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_summary",
+          "memberFieldName": "summary"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_mode",
+          "memberFieldName": "mode"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_confidence",
+          "memberFieldName": "confidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_evidence",
+          "memberFieldName": "evidence"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_previewRange",
+          "memberFieldName": "previewRange"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_sourceUsageContext",
+          "memberFieldName": "sourceUsageContext"
+        },
+        {
+          "@id": "undefineds:dist/document/L0SourceSummary.jsonld#CreateL0SourceSummaryInput__member_maxExcerptLength",
+          "memberFieldName": "maxExcerptLength"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

package/dist/document/PaddleOcrReader.d.ts

@@ -0,0 +1,40 @@
+import type { DocumentReader, ReadDocument, ReadOptions } from './DocumentReader';
+export interface PaddleOcrClientReadInput {
+    fileUrl?: string;
+    filePath?: string;
+    token: string;
+    model: string;
+    pageRange?: string;
+    expectedUse?: string;
+    timeout?: number;
+}
+export interface PaddleOcrClientReadResult {
+    markdown?: string;
+    content?: string;
+    text?: string;
+    metadata?: Record<string, unknown>;
+    pages?: unknown[];
+}
+export interface PaddleOcrClientLike {
+    readDocument(input: PaddleOcrClientReadInput): Promise<PaddleOcrClientReadResult>;
+}
+export interface PaddleOcrReaderOptions {
+    token: string;
+    model: string;
+    client: PaddleOcrClientLike;
+    defaultTimeout?: number;
+}
+export interface PaddleOcrReadOptions extends ReadOptions {
+    pageRange?: string;
+    expectedUse?: string;
+}
+export declare class PaddleOcrReader implements DocumentReader {
+    protected readonly logger: import("global-logger-factory").Logger<unknown>;
+    private readonly token;
+    private readonly model;
+    private readonly client;
+    private readonly defaultTimeout;
+    constructor(options: PaddleOcrReaderOptions);
+    read(url: string, options?: PaddleOcrReadOptions): Promise<ReadDocument>;
+    supports(url: string): boolean;
+}