@hraness/kb 0.17.1

package/src/pdf/markdown.ts

@@ -0,0 +1,154 @@
+import { redactSensitiveText } from "../clip/persist.js";
+import { sanitizeTerminalText } from "../clip/terminal.js";
+import { yamlString } from "../clip/lib.js";
+import type {
+  PdfCaptureStatus,
+  PdfDocumentMetadata,
+  PdfImageCandidate,
+  PdfImageSemanticMetadata,
+} from "./model.js";
+import type { PdfLayoutBlock } from "./layout.js";
+import { pdfImageAssetPath } from "./persist.js";
+
+export type ResolvedPdfImage = {
+  readonly image: PdfImageCandidate;
+  readonly kind: "text" | "mixed" | "visual";
+  readonly method: "agent" | "manual" | "tesseract" | "unclassified";
+  readonly markdown: string;
+  readonly alt: string | null;
+  readonly confidence: number | null;
+  readonly wordCount: number;
+  readonly metadata: PdfImageSemanticMetadata | null;
+};
+
+function escapeInline(value: string): string {
+  return sanitizeTerminalText(value)
+    .replace(/\\/gu, "\\\\")
+    .replace(/([`*_[\]{}<>#])/gu, "\\$1")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
+function metadataLine(metadata: PdfImageSemanticMetadata | null): string | null {
+  if (metadata === null) return null;
+  const values = [
+    metadata.platform === undefined ? null : `platform: ${metadata.platform}`,
+    metadata.contentType === undefined ? null : `type: ${metadata.contentType}`,
+    metadata.channel === undefined ? null : `channel: ${metadata.channel}`,
+    metadata.author === undefined ? null : `author: ${metadata.author}`,
+    metadata.timestamp === undefined ? null : `timestamp: ${metadata.timestamp}`,
+    metadata.participants === undefined ? null : `participants: ${metadata.participants.join(", ")}`,
+  ].filter((value): value is string => value !== null);
+  return values.length === 0 ? null : `*Image metadata — ${escapeInline(values.join("; "))}*`;
+}
+
+function imageMarkdown(image: ResolvedPdfImage): string {
+  const assetPath = pdfImageAssetPath(image.image);
+  const semantic = image.metadata?.contentType ?? image.metadata?.platform;
+  const fallbackAlt = semantic === undefined
+    ? `PDF image from page ${image.image.page}`
+    : `${semantic} from page ${image.image.page}`;
+  const alt = escapeInline(image.alt ?? fallbackAlt);
+  const lines = [`![${alt}](${assetPath})`];
+  const metadata = metadataLine(image.metadata);
+  if (metadata !== null) lines.push("", metadata);
+  if (image.kind === "text" || image.kind === "mixed") {
+    const heading = image.metadata?.platform === undefined
+      ? "Text visible in image"
+      : `Text visible in ${escapeInline(image.metadata.platform)} image`;
+    lines.push("", `#### ${heading}`, "", image.markdown.trim());
+  }
+  return lines.join("\n");
+}
+
+function markdownContent(
+  blocks: readonly PdfLayoutBlock[],
+  images: ReadonlyMap<string, ResolvedPdfImage>,
+): { readonly content: string; readonly headingCount: number; readonly textBlockCount: number } {
+  const lines: string[] = [];
+  let currentPage: number | null = null;
+  let headingCount = 0;
+  let textBlockCount = 0;
+  for (const block of blocks) {
+    if (currentPage !== block.page) {
+      if (lines.length > 0) lines.push("");
+      lines.push(`<!-- pdf-page: ${block.page} -->`, "");
+      currentPage = block.page;
+    }
+    if (block.kind === "image") {
+      const resolved = images.get(block.image.id);
+      if (resolved === undefined) continue;
+      lines.push(imageMarkdown(resolved), "");
+      continue;
+    }
+    if (block.kind === "heading") {
+      headingCount += 1;
+      lines.push(`${"#".repeat(Math.max(2, Math.min(6, block.level)))} ${escapeInline(block.text)}`, "");
+      continue;
+    }
+    textBlockCount += 1;
+    if (block.kind === "list-item") lines.push(`- ${escapeInline(block.text)}`, "");
+    else lines.push(escapeInline(block.text), "");
+  }
+  return {
+    content: lines.join("\n").trim(),
+    headingCount,
+    textBlockCount,
+  };
+}
+
+export type BuildPdfMarkdownOptions = {
+  readonly slug: string;
+  readonly originalFilename: string;
+  readonly sourceSha256: string;
+  readonly sourceUrl?: string;
+  readonly capturedDate: string;
+  readonly status: PdfCaptureStatus;
+  readonly metadata: PdfDocumentMetadata;
+  readonly blocks: readonly PdfLayoutBlock[];
+  readonly images: ReadonlyMap<string, ResolvedPdfImage>;
+  readonly embeddedPlatforms: readonly string[];
+};
+
+/** Build one deterministic PDF note; only capturedDate varies between reruns. */
+export function buildPdfMarkdown(options: BuildPdfMarkdownOptions): {
+  readonly markdown: string;
+  readonly headingCount: number;
+  readonly textBlockCount: number;
+} {
+  const filenameTitle = options.originalFilename.replace(/\.pdf$/iu, "").trim();
+  const title = options.metadata.title ?? (filenameTitle === "" ? options.slug : filenameTitle);
+  const body = markdownContent(options.blocks, options.images);
+  const frontmatter = [
+    "---",
+    `title: ${yamlString(title)}`,
+    `source: ${yamlString("source.pdf")}`,
+    `source_type: ${yamlString("pdf")}`,
+    `source_original_filename: ${yamlString(options.originalFilename)}`,
+    `source_sha256: ${yamlString(options.sourceSha256)}`,
+    ...(options.sourceUrl === undefined ? [] : [`source_url: ${yamlString(options.sourceUrl)}`]),
+    `pages: ${options.metadata.pageCount}`,
+    `clipped: ${yamlString(options.capturedDate)}`,
+    `capture_status: ${yamlString(options.status)}`,
+    `capture_method: ${yamlString("poppler")}`,
+    ...(options.metadata.author === null ? [] : [`author: ${yamlString(options.metadata.author)}`]),
+    ...(options.metadata.subject === null ? [] : [`description: ${yamlString(options.metadata.subject)}`]),
+    ...(options.metadata.createdAt === null ? [] : [`created: ${yamlString(options.metadata.createdAt)}`]),
+    ...(options.embeddedPlatforms.length === 0
+      ? []
+      : [`embedded_platforms: [${options.embeddedPlatforms.map(yamlString).join(", ")}]`]),
+    "---",
+    "",
+    `# ${escapeInline(title)}`,
+    "",
+    "[Open the source PDF](source.pdf)",
+    "",
+    body.content,
+    "",
+  ].join("\n");
+  return {
+    markdown: `${redactSensitiveText(frontmatter).trimEnd()}\n`,
+    headingCount: body.headingCount,
+    textBlockCount: body.textBlockCount,
+  };
+}

package/src/pdf/model.ts

@@ -0,0 +1,234 @@
+export const PDF_CAPTURE_MANIFEST_SCHEMA_VERSION = 1 as const;
+export const PDF_CAPTURE_MANIFEST_FILENAME = "capture.json";
+export const PDF_CAPTURE_SOURCE_FILENAME = "source.pdf";
+export const PDF_CAPTURE_ANNOTATIONS_FILENAME = "annotations.json";
+
+export type PdfCaptureStatus = "complete" | "partial";
+
+export type PdfBounds = {
+  readonly top: number;
+  readonly left: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+export type PdfDocumentMetadata = {
+  readonly title: string | null;
+  readonly author: string | null;
+  readonly subject: string | null;
+  readonly keywords: string | null;
+  readonly creator: string | null;
+  readonly producer: string | null;
+  readonly createdAt: string | null;
+  readonly modifiedAt: string | null;
+  readonly pageCount: number;
+  readonly encrypted: boolean;
+};
+
+export type PdfRemoteSource = {
+  readonly requestedUrl: string;
+  readonly finalUrl: string;
+};
+
+export type PdfTextFragment = PdfBounds & {
+  readonly text: string;
+  readonly fontId: string;
+  readonly fontSize: number;
+  readonly bold: boolean;
+  readonly italic: boolean;
+};
+
+export type PdfImageCandidate = PdfBounds & {
+  readonly id: string;
+  readonly page: number;
+  readonly sourcePath: string;
+  readonly bytes: number;
+  readonly sha256: string;
+  readonly mimeType: string;
+};
+
+export type PdfPageLayout = {
+  readonly page: number;
+  readonly width: number;
+  readonly height: number;
+  readonly text: readonly PdfTextFragment[];
+  readonly images: readonly PdfImageCandidate[];
+};
+
+export type PdfInspection = {
+  readonly inputPath: string;
+  readonly originalFilename: string;
+  readonly sourceBytes: number;
+  readonly sourceSha256: string;
+  readonly metadata: PdfDocumentMetadata;
+  readonly processedPages: number;
+  readonly pages: readonly PdfPageLayout[];
+  readonly popplerVersion: string | null;
+  readonly warnings: readonly string[];
+  /**
+   * The caller owns this directory. Image candidate paths remain valid until
+   * the caller removes it.
+   */
+  readonly workspaceDirectory: string;
+};
+
+export type PdfImageSemanticMetadata = {
+  readonly platform?: string;
+  readonly contentType?: string;
+  readonly channel?: string;
+  readonly author?: string;
+  readonly timestamp?: string;
+  readonly participants?: readonly string[];
+};
+
+export type PdfImageInterpretation =
+  | {
+      readonly id: string;
+      readonly sha256: string;
+      readonly kind: "text" | "mixed";
+      readonly markdown: string;
+      readonly metadata?: PdfImageSemanticMetadata;
+      readonly method?: "agent" | "manual";
+    }
+  | {
+      readonly id: string;
+      readonly sha256: string;
+      readonly kind: "visual";
+      readonly alt?: string;
+      readonly metadata?: PdfImageSemanticMetadata;
+      readonly method?: "agent" | "manual";
+    };
+
+export type PdfOcrResult = {
+  readonly kind: "mixed" | "visual";
+  readonly text: string;
+  readonly markdown: string;
+  readonly confidence: number | null;
+  readonly wordCount: number;
+  readonly warnings: readonly string[];
+};
+
+export type PdfManifestAsset = {
+  readonly path: string;
+  readonly mimeType: string;
+  readonly bytes: number;
+  readonly sha256: string;
+};
+
+export type PdfManifestImage = PdfBounds & {
+  readonly id: string;
+  readonly page: number;
+  readonly asset: PdfManifestAsset;
+  readonly kind: "text" | "mixed" | "visual";
+  readonly method: "agent" | "manual" | "tesseract" | "unclassified";
+  readonly confidence: number | null;
+  readonly wordCount: number;
+  readonly metadata: PdfImageSemanticMetadata | null;
+};
+
+export type PdfCaptureManifest = {
+  readonly schemaVersion: typeof PDF_CAPTURE_MANIFEST_SCHEMA_VERSION;
+  readonly kind: "pdf";
+  readonly capturedAt: string;
+  readonly status: PdfCaptureStatus;
+  readonly source: {
+    readonly originalFilename: string;
+    readonly path: typeof PDF_CAPTURE_SOURCE_FILENAME;
+    readonly mimeType: "application/pdf";
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly requestedUrl?: string;
+    readonly finalUrl?: string;
+  };
+  readonly document: PdfDocumentMetadata & {
+    readonly processedPages: number;
+  };
+  readonly extraction: {
+    readonly layout: "pdftohtml-xml";
+    readonly popplerVersion: string | null;
+    readonly ocr: "tesseract" | "annotations" | "mixed" | "unavailable";
+    readonly headingCount: number;
+    readonly textBlockCount: number;
+    readonly imageCount: number;
+    readonly textImageCount: number;
+    readonly mixedImageCount: number;
+    readonly visualImageCount: number;
+  };
+  readonly images: readonly PdfManifestImage[];
+  readonly annotations: {
+    readonly path: typeof PDF_CAPTURE_ANNOTATIONS_FILENAME;
+    readonly count: number;
+    readonly bytes: number;
+    readonly sha256: string;
+  } | null;
+  readonly embeddedPlatforms: readonly string[];
+  readonly warnings: readonly string[];
+};
+
+export type PdfCaptureOptions = {
+  readonly inputPath: string;
+  readonly outputBase: string;
+  readonly remoteSource?: PdfRemoteSource;
+  readonly slug?: string;
+  readonly force?: boolean;
+  readonly interpretations?: readonly PdfImageInterpretation[];
+  readonly timeoutMs?: number;
+  readonly maxPdfBytes?: number;
+  readonly maxPages?: number;
+  readonly maxImages?: number;
+  readonly maxAssetBytes?: number;
+  readonly maxTotalAssetBytes?: number;
+  readonly workspaceDirectory?: string;
+};
+
+export type PdfInspectOptions = Pick<
+  PdfCaptureOptions,
+  "inputPath" | "timeoutMs" | "maxPdfBytes" | "maxPages" | "maxImages" | "maxAssetBytes" | "maxTotalAssetBytes"
+> & {
+  readonly workspaceDirectory: string;
+};
+
+export type PdfCaptureOutcome = {
+  readonly status: PdfCaptureStatus;
+  readonly slug: string;
+  readonly outputDirectory: string;
+  readonly markdownPath: string;
+  readonly sourcePath: string;
+  readonly wordCount: number;
+  readonly pageCount: number;
+  readonly processedPages: number;
+  readonly imageCount: number;
+  readonly warnings: readonly string[];
+  readonly markdown: string;
+  readonly manifest: PdfCaptureManifest;
+};
+
+export type PdfToolCommand = {
+  readonly command: readonly string[];
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+  readonly cwd?: string;
+  readonly environment?: Readonly<Record<string, string | undefined>>;
+};
+
+export type PdfToolCommandResult = {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+};
+
+export type PdfToolRunner = (specification: PdfToolCommand) => Promise<PdfToolCommandResult>;
+
+export type PdfToolPaths = {
+  readonly pdfinfo: string;
+  readonly pdftohtml: string;
+  readonly tesseract: string | null;
+};
+
+export type PdfCaptureDependencies = {
+  readonly runTool?: PdfToolRunner;
+  readonly tools?: Partial<PdfToolPaths>;
+  readonly which?: (name: string) => string | null;
+  readonly exists?: (path: string) => boolean;
+  readonly now?: () => Date;
+};

package/src/pdf/ocr.ts

@@ -0,0 +1,190 @@
+import { redactSensitiveText } from "../clip/persist.js";
+import { sanitizeTerminalText } from "../clip/terminal.js";
+import type {
+  PdfImageCandidate,
+  PdfOcrResult,
+  PdfToolRunner,
+} from "./model.js";
+
+type OcrWord = {
+  readonly page: number;
+  readonly block: number;
+  readonly paragraph: number;
+  readonly line: number;
+  readonly word: number;
+  readonly text: string;
+  readonly confidence: number;
+};
+
+function parseInteger(value: string | undefined): number | null {
+  if (value === undefined || !/^-?\d+$/u.test(value)) return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+
+function parseConfidence(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 100 ? parsed : null;
+}
+
+function escapeMarkdownText(value: string): string {
+  return value
+    .replace(/\\/gu, "\\\\")
+    .replace(/([`*_[\]{}<>#])/gu, "\\$1");
+}
+
+export type ParsedTesseractTsv = {
+  readonly text: string;
+  readonly markdown: string;
+  readonly confidence: number | null;
+  readonly wordCount: number;
+  readonly substantive: boolean;
+};
+
+/** Parse Tesseract TSV into stable reading-order text and a quoted Markdown block. */
+export function parseTesseractTsv(value: string): ParsedTesseractTsv {
+  const lines = value.split(/\r?\n/gu);
+  const header = lines[0]?.split("\t") ?? [];
+  const positions = new Map(header.map((name, index) => [name, index]));
+  const required = ["page_num", "block_num", "par_num", "line_num", "word_num", "conf", "text"] as const;
+  if (!required.every((name) => positions.has(name))) {
+    throw new Error("Tesseract TSV is missing required columns");
+  }
+  const words: OcrWord[] = [];
+  for (const row of lines.slice(1)) {
+    if (row === "") continue;
+    const fields = row.split("\t");
+    const at = (name: typeof required[number]): string | undefined => {
+      const index = positions.get(name);
+      return index === undefined ? undefined : fields[index];
+    };
+    const text = sanitizeTerminalText(at("text") ?? "").trim();
+    const confidence = parseConfidence(at("conf"));
+    const word = parseInteger(at("word_num"));
+    const page = parseInteger(at("page_num"));
+    const block = parseInteger(at("block_num"));
+    const paragraph = parseInteger(at("par_num"));
+    const line = parseInteger(at("line_num"));
+    if (
+      text === ""
+      || confidence === null
+      || word === null
+      || page === null
+      || block === null
+      || paragraph === null
+      || line === null
+    ) continue;
+    words.push({
+      page,
+      block,
+      paragraph,
+      line,
+      word,
+      text,
+      confidence,
+    });
+    if (words.length >= 100_000) break;
+  }
+  words.sort((left, right) =>
+    left.page - right.page
+    || left.block - right.block
+    || left.paragraph - right.paragraph
+    || left.line - right.line
+    || left.word - right.word);
+  const grouped = new Map<string, string[]>();
+  for (const word of words) {
+    const lineIdentity = `${word.page}:${word.block}:${word.paragraph}:${word.line}`;
+    const current = grouped.get(lineIdentity) ?? [];
+    current.push(word.text);
+    grouped.set(lineIdentity, current);
+  }
+  const textLines = [...grouped.values()]
+    .map((entries) => entries.join(" ").replace(/\s+/gu, " ").trim())
+    .filter(Boolean);
+  const text = redactSensitiveText(textLines.join("\n"));
+  const weightedCharacters = words.reduce((sum, word) => sum + word.text.length, 0);
+  const confidence = weightedCharacters === 0
+    ? null
+    : words.reduce((sum, word) => sum + word.confidence * word.text.length, 0) / weightedCharacters;
+  const alphanumericCount = [...text].filter((character) => /[\p{Letter}\p{Number}]/u.test(character)).length;
+  const substantive = words.length >= 3
+    && alphanumericCount >= 12
+    && confidence !== null
+    && confidence >= 35;
+  const markdown = substantive
+    ? text.split("\n").map((line) => `> ${escapeMarkdownText(line)}`).join("\n")
+    : "";
+  return {
+    text,
+    markdown,
+    confidence,
+    wordCount: words.length,
+    substantive,
+  };
+}
+
+/** Classify one image with local OCR; substantive results remain mixed visual/text evidence. */
+export async function ocrPdfImage(
+  image: PdfImageCandidate,
+  options: {
+    readonly tesseractPath: string | null;
+    readonly timeoutMs: number;
+    readonly runTool: PdfToolRunner;
+  },
+): Promise<PdfOcrResult> {
+  if (options.tesseractPath === null) {
+    return {
+      kind: "visual",
+      text: "",
+      markdown: "",
+      confidence: null,
+      wordCount: 0,
+      warnings: ["Tesseract is unavailable; retained the image without OCR text."],
+    };
+  }
+  try {
+    const result = await options.runTool({
+      command: [
+        options.tesseractPath,
+        image.sourcePath,
+        "stdout",
+        "--psm",
+        "6",
+        "tsv",
+      ],
+      timeoutMs: options.timeoutMs,
+      maxOutputBytes: 16 * 1024 * 1024,
+    });
+    if (result.exitCode !== 0) {
+      return {
+        kind: "visual",
+        text: "",
+        markdown: "",
+        confidence: null,
+        wordCount: 0,
+        warnings: ["Tesseract could not read this image; retained it as visual evidence."],
+      };
+    }
+    const parsed = parseTesseractTsv(result.stdout);
+    return {
+      kind: parsed.substantive ? "mixed" : "visual",
+      text: parsed.text,
+      markdown: parsed.markdown,
+      confidence: parsed.confidence,
+      wordCount: parsed.wordCount,
+      warnings: parsed.substantive
+        ? []
+        : ["Tesseract did not find sufficiently confident text; retained the image as visual evidence."],
+    };
+  } catch {
+    return {
+      kind: "visual",
+      text: "",
+      markdown: "",
+      confidence: null,
+      wordCount: 0,
+      warnings: ["Tesseract OCR failed; retained the image as visual evidence."],
+    };
+  }
+}