@agent-native/core 0.103.1 → 0.104.0

package/corpus/core/src/ingestion/media.ts

@@ -0,0 +1,264 @@
+import { createHash } from "node:crypto";
+
+export interface MediaFingerprint {
+  sha256: string;
+  byteLength: number;
+  mimeType?: string;
+}
+
+export function fingerprintMedia(
+  data: Uint8Array,
+  mimeType?: string,
+): MediaFingerprint {
+  return {
+    sha256: createHash("sha256").update(data).digest("hex"),
+    byteLength: data.byteLength,
+    ...(mimeType ? { mimeType } : {}),
+  };
+}
+
+export function extractCssColors(value: string): string[] {
+  const colors = new Set<string>();
+  const pattern =
+    /(?:#[0-9a-f]{3,8}\b|(?:rgb|hsl)a?\([^)]*\)|\b(?:transparent|currentColor)\b)/gi;
+  for (const match of value.match(pattern) ?? []) colors.add(match.trim());
+  return [...colors];
+}
+
+export function rankColorSamples(
+  samples: readonly string[],
+  limit = 24,
+): string[] {
+  const counts = new Map<string, number>();
+  for (const sample of samples) {
+    const normalized = sample.trim().replace(/\s+/g, " ").toLowerCase();
+    if (
+      !normalized ||
+      normalized === "rgba(0, 0, 0, 0)" ||
+      normalized === "transparent"
+    )
+      continue;
+    counts.set(normalized, (counts.get(normalized) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, Math.max(1, limit))
+    .map(([color]) => color);
+}
+
+export async function extractDominantColors(
+  data: Uint8Array,
+  limit = 6,
+): Promise<string[]> {
+  const sharp = await loadSharp();
+  if (!sharp) {
+    throw new Error(
+      "Image palette extraction requires the optional sharp dependency.",
+    );
+  }
+  const output = await sharp(Buffer.from(data), { failOn: "none" })
+    .resize(64, 64, { fit: "inside" })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const buckets = new Map<string, number>();
+  for (let index = 0; index < output.data.length; index += 3) {
+    const key = [
+      output.data[index],
+      output.data[index + 1],
+      output.data[index + 2],
+    ]
+      .map((channel) => Math.round(channel / 32) * 32)
+      .map((channel) =>
+        Math.max(0, Math.min(255, channel)).toString(16).padStart(2, "0"),
+      )
+      .join("");
+    buckets.set(key, (buckets.get(key) ?? 0) + 1);
+  }
+  return [...buckets.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, Math.max(1, limit))
+    .map(([hex]) => `#${hex.toUpperCase()}`);
+}
+
+export interface CroppedImageRegion {
+  data: Uint8Array;
+  mimeType: "image/png";
+  width: number;
+  height: number;
+}
+
+export async function compareRasterImages(input: {
+  source: Uint8Array;
+  rendered: Uint8Array;
+  maxInputBytes?: number;
+}): Promise<{ meanAbsoluteDifference: number; width: number; height: number }> {
+  const maxInputBytes = input.maxInputBytes ?? 20 * 1024 * 1024;
+  if (
+    input.source.byteLength > maxInputBytes ||
+    input.rendered.byteLength > maxInputBytes
+  ) {
+    throw new Error(`Image comparison input exceeds ${maxInputBytes} bytes.`);
+  }
+  const sharp = await loadSharp();
+  if (!sharp) {
+    throw new Error("Image comparison requires the optional sharp dependency.");
+  }
+  const source = sharp(Buffer.from(input.source), { failOn: "none" });
+  const rendered = sharp(Buffer.from(input.rendered), { failOn: "none" });
+  const [sourceMetadata, renderedMetadata] = await Promise.all([
+    source.metadata(),
+    rendered.metadata(),
+  ]);
+  if (
+    !sourceMetadata.width ||
+    !sourceMetadata.height ||
+    sourceMetadata.width !== renderedMetadata.width ||
+    sourceMetadata.height !== renderedMetadata.height ||
+    sourceMetadata.channels !== renderedMetadata.channels
+  ) {
+    throw new Error(
+      "Image comparison requires identical dimensions and channels.",
+    );
+  }
+  const [sourcePixels, renderedPixels] = await Promise.all([
+    source.raw().toBuffer(),
+    rendered.raw().toBuffer(),
+  ]);
+  if (sourcePixels.byteLength !== renderedPixels.byteLength) {
+    throw new Error("Image comparison buffers have different lengths.");
+  }
+  let difference = 0;
+  for (let index = 0; index < sourcePixels.length; index++) {
+    difference += Math.abs(sourcePixels[index]! - renderedPixels[index]!);
+  }
+  return {
+    meanAbsoluteDifference: difference / sourcePixels.length,
+    width: sourceMetadata.width,
+    height: sourceMetadata.height,
+  };
+}
+
+/** Crops a bounded raster region without retaining the source image. */
+export async function cropImageRegion(input: {
+  data: Uint8Array;
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  maxInputBytes?: number;
+  maxOutputPixels?: number;
+}): Promise<CroppedImageRegion> {
+  const maxInputBytes = input.maxInputBytes ?? 20 * 1024 * 1024;
+  const maxOutputPixels = input.maxOutputPixels ?? 16_000_000;
+  if (input.data.byteLength > maxInputBytes) {
+    throw new Error(`Image crop input exceeds ${maxInputBytes} bytes.`);
+  }
+  const region = Object.fromEntries(
+    (["left", "top", "width", "height"] as const).map((key) => [
+      key,
+      Math.round(input[key]),
+    ]),
+  ) as { left: number; top: number; width: number; height: number };
+  if (
+    region.left < 0 ||
+    region.top < 0 ||
+    region.width <= 0 ||
+    region.height <= 0 ||
+    region.width * region.height > maxOutputPixels
+  ) {
+    throw new Error("Image crop region is invalid or exceeds the pixel limit.");
+  }
+  const sharp = await loadSharp();
+  if (!sharp) {
+    throw new Error("Image cropping requires the optional sharp dependency.");
+  }
+  const pipeline = sharp(Buffer.from(input.data), { failOn: "none" });
+  const metadata = await pipeline.metadata();
+  if (
+    !metadata.width ||
+    !metadata.height ||
+    region.left + region.width > metadata.width ||
+    region.top + region.height > metadata.height
+  ) {
+    throw new Error("Image crop region falls outside the source image.");
+  }
+  const data = await pipeline.extract(region).png().toBuffer();
+  return {
+    data: new Uint8Array(data),
+    mimeType: "image/png",
+    width: region.width,
+    height: region.height,
+  };
+}
+
+export async function readBoundedResponseBytes(
+  response: Response,
+  maxBytes: number,
+): Promise<Uint8Array> {
+  if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+    throw new Error("maxBytes must be a positive integer.");
+  }
+  const contentLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw new Error(`Remote artifact exceeds ${maxBytes} bytes.`);
+  }
+  if (!response.body) return new Uint8Array(await response.arrayBuffer());
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error(`Remote artifact exceeds ${maxBytes} bytes.`);
+    }
+    chunks.push(value);
+  }
+  const joined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    joined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return joined;
+}
+
+interface SharpPipeline {
+  resize(
+    width: number,
+    height: number,
+    options: { fit: "inside" },
+  ): SharpPipeline;
+  removeAlpha(): SharpPipeline;
+  metadata(): Promise<{ width?: number; height?: number; channels?: number }>;
+  extract(region: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): SharpPipeline;
+  png(): SharpPipeline;
+  toBuffer(): Promise<Buffer>;
+  raw(): SharpPipeline;
+  toBuffer(options: { resolveWithObject: true }): Promise<{ data: Uint8Array }>;
+}
+
+type SharpFactory = (
+  data: Buffer,
+  options: { failOn: "none" },
+) => SharpPipeline;
+
+async function loadSharp(): Promise<SharpFactory | null> {
+  const specifier = "sharp";
+  try {
+    const module = (await import(/* @vite-ignore */ specifier)) as {
+      default?: SharpFactory;
+    };
+    return module.default ?? (module as unknown as SharpFactory);
+  } catch {
+    return null;
+  }
+}

package/corpus/core/src/ingestion/notion.ts

@@ -0,0 +1,121 @@
+export interface NotionMarkdownSection {
+  heading: string | null;
+  headingLevel: number | null;
+  markdown: string;
+}
+
+export interface NotionMarkdownResult {
+  markdown: string;
+  sections: NotionMarkdownSection[];
+}
+
+export function notionBlocksToMarkdown(
+  blocks: readonly unknown[],
+): NotionMarkdownResult {
+  const sections: NotionMarkdownSection[] = [];
+  let current: NotionMarkdownSection = {
+    heading: null,
+    headingLevel: null,
+    markdown: "",
+  };
+  const flush = () => {
+    const markdown = current.markdown.trim();
+    if (markdown) sections.push({ ...current, markdown });
+  };
+  for (const value of blocks) {
+    const block = asRecord(value);
+    const type = stringValue(block?.type);
+    if (!block || !type) continue;
+    const line = notionBlockToMarkdown(block, type);
+    if (!line) continue;
+    const heading = type.match(/^heading_([1-3])$/);
+    if (heading) {
+      flush();
+      const headingLevel = Number(heading[1]);
+      current = {
+        heading: richText(asRecord(block[type])?.rich_text),
+        headingLevel,
+        markdown: line,
+      };
+    } else {
+      current.markdown += `${current.markdown ? "\n\n" : ""}${line}`;
+    }
+  }
+  flush();
+  return {
+    markdown: sections.map((section) => section.markdown).join("\n\n"),
+    sections,
+  };
+}
+
+export function notionBlockToMarkdown(
+  block: Record<string, unknown>,
+  type = stringValue(block.type) ?? "",
+): string {
+  const payload = asRecord(block[type]) ?? {};
+  const text = richText(payload.rich_text);
+  switch (type) {
+    case "heading_1":
+    case "heading_2":
+    case "heading_3":
+      return `${"#".repeat(Number(type.slice(-1)))} ${text}`.trim();
+    case "bulleted_list_item":
+      return `- ${text}`.trim();
+    case "numbered_list_item":
+      return `1. ${text}`.trim();
+    case "to_do":
+      return `- [${payload.checked === true ? "x" : " "}] ${text}`.trim();
+    case "quote":
+      return text
+        .split("\n")
+        .map((line) => `> ${line}`)
+        .join("\n");
+    case "code":
+      return `\`\`\`${stringValue(payload.language) ?? ""}\n${text}\n\`\`\``;
+    case "divider":
+      return "---";
+    case "bookmark":
+    case "embed": {
+      const url = stringValue(payload.url);
+      return url ? `[${url}](${url})` : "";
+    }
+    case "child_page":
+      return `## ${stringValue(payload.title) ?? "Untitled page"}`;
+    case "image":
+    case "video":
+    case "audio":
+    case "file":
+    case "pdf": {
+      const file = asRecord(payload.file) ?? asRecord(payload.external);
+      const url = stringValue(file?.url);
+      const caption = richText(payload.caption) || type;
+      return url ? `![${caption}](${url})` : caption;
+    }
+    default:
+      return text;
+  }
+}
+
+function richText(value: unknown): string {
+  return (Array.isArray(value) ? value : [])
+    .map((part) => {
+      const record = asRecord(part);
+      return (
+        stringValue(record?.plain_text) ??
+        stringValue(asRecord(record?.text)?.content) ??
+        ""
+      );
+    })
+    .join("")
+    .trim();
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/corpus/core/src/ingestion/office.ts

@@ -0,0 +1,214 @@
+export type OfficeDocumentType = "pptx" | "docx" | "pdf" | "txt" | "md" | "csv";
+
+export interface ParseOfficeDocumentInput {
+  data: Uint8Array;
+  fileName: string;
+  mimeType?: string;
+  signal?: AbortSignal;
+}
+
+export interface ParsedOfficeDocument {
+  text: string;
+  fileType: OfficeDocumentType;
+  title: string;
+  parser:
+    | "structured-pptx"
+    | "mammoth-docx"
+    | "officeparser-pdf"
+    | "plain-text";
+  parts: OfficeDocumentPart[];
+  metadata: Record<string, unknown>;
+  warnings: string[];
+}
+
+export interface OfficeDocumentPart {
+  kind: "slide" | "section" | "page" | "document";
+  index: number;
+  title: string;
+  text: string;
+  notes?: string;
+  textRuns?: ParsedPptxTextRun[];
+  images?: ParsedPptxImage[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface OfficeDocumentAst {
+  type?: string;
+  metadata?: Record<string, unknown>;
+  warnings?: unknown[];
+  toText(): string | Promise<string>;
+}
+
+export interface OfficeDocumentParser {
+  parseOffice(
+    data: Uint8Array,
+    options: {
+      fileType: OfficeDocumentType;
+      abortSignal?: AbortSignal;
+      extractAttachments: boolean;
+      ignoreNotes: boolean;
+    },
+  ): Promise<OfficeDocumentAst>;
+}
+
+export async function parseOfficeDocument(
+  input: ParseOfficeDocumentInput,
+  parser?: OfficeDocumentParser,
+): Promise<ParsedOfficeDocument> {
+  const fileType = detectOfficeDocumentType(input.fileName, input.mimeType);
+  if (fileType === "txt" || fileType === "md" || fileType === "csv") {
+    const text = normalizeDocumentText(new TextDecoder().decode(input.data));
+    return {
+      text,
+      fileType,
+      title: input.fileName,
+      parser: "plain-text",
+      parts: [{ kind: "document", index: 0, title: input.fileName, text }],
+      metadata: {},
+      warnings: [],
+    };
+  }
+  if (fileType === "pptx") {
+    const presentation = await parsePptxPresentation(input.data);
+    const parts = presentation.slides.map((slide, index) => {
+      const body = normalizeDocumentText(
+        slide.texts.map((run) => run.content).join("\n"),
+      );
+      return {
+        kind: "slide" as const,
+        index,
+        title:
+          slide.texts
+            .find((run) => run.content.trim())
+            ?.content.trim()
+            .slice(0, 160) ?? `Slide ${index + 1}`,
+        text: normalizeDocumentText(
+          [body, slide.notes ? `Speaker notes\n${slide.notes}` : ""]
+            .filter(Boolean)
+            .join("\n\n"),
+        ),
+        notes: slide.notes,
+        textRuns: slide.texts,
+        images: slide.images,
+        metadata: {
+          layoutHint: slide.layoutHint,
+          theme: presentation.theme,
+        },
+      };
+    });
+    return {
+      text: parts.map((part) => part.text).join("\n\n"),
+      fileType,
+      title: presentation.title,
+      parser: "structured-pptx",
+      parts,
+      metadata: { theme: presentation.theme, slideCount: parts.length },
+      warnings: [],
+    };
+  }
+  if (fileType === "docx") {
+    const document = await parseDocxDocument(input.data);
+    const parts = document.sections.map((section, index) => {
+      const html = sanitizeInertDocumentHtml(section.html);
+      return {
+        kind: "section" as const,
+        index,
+        title: section.heading || `Section ${index + 1}`,
+        text: normalizeDocumentText(
+          [section.heading, section.text].filter(Boolean).join("\n\n"),
+        ),
+        metadata: { html },
+      };
+    });
+    return {
+      text: normalizeDocumentText(document.text),
+      fileType,
+      title: document.title,
+      parser: "mammoth-docx",
+      parts,
+      metadata: { sectionCount: parts.length },
+      warnings: [],
+    };
+  }
+  const resolvedParser = parser ?? (await loadOfficeParser());
+  if (!resolvedParser) {
+    throw new Error(
+      `Parsing ${fileType.toUpperCase()} uploads requires the optional officeparser dependency.`,
+    );
+  }
+  const ast = await resolvedParser.parseOffice(input.data, {
+    fileType,
+    abortSignal: input.signal,
+    extractAttachments: false,
+    ignoreNotes: false,
+  });
+  const text = normalizeDocumentText(await ast.toText());
+  const pages = text.split(/\f+/).map(normalizeDocumentText).filter(Boolean);
+  const parts = (pages.length > 0 ? pages : [text]).map((page, index) => ({
+    kind: "page" as const,
+    index,
+    title: `Page ${index + 1}`,
+    text: page,
+  }));
+  return {
+    text,
+    fileType: isOfficeDocumentType(ast.type) ? ast.type : fileType,
+    title: input.fileName,
+    parser: "officeparser-pdf",
+    parts,
+    metadata: ast.metadata ?? {},
+    warnings: (ast.warnings ?? []).map(String),
+  };
+}
+
+export function detectOfficeDocumentType(
+  fileName: string,
+  mimeType?: string,
+): OfficeDocumentType {
+  const mime = mimeType?.toLowerCase() ?? "";
+  if (mime.includes("presentationml")) return "pptx";
+  if (mime.includes("wordprocessingml")) return "docx";
+  if (mime.includes("pdf")) return "pdf";
+  if (mime.includes("markdown")) return "md";
+  if (mime.includes("csv")) return "csv";
+  if (mime.startsWith("text/")) return "txt";
+  const extension = fileName.toLowerCase().match(/\.([a-z0-9]+)$/)?.[1];
+  if (isOfficeDocumentType(extension)) return extension;
+  throw new Error(
+    `Unsupported upload type ${mimeType ?? extension ?? "unknown"}; supported formats are PPTX, DOCX, PDF, and text.`,
+  );
+}
+
+export function normalizeDocumentText(value: string): string {
+  return value
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\t\f\v ]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+async function loadOfficeParser(): Promise<OfficeDocumentParser | null> {
+  const specifier = "officeparser";
+  try {
+    const module = (await import(specifier)) as {
+      OfficeParser?: OfficeDocumentParser;
+    };
+    return module.OfficeParser ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isOfficeDocumentType(value: unknown): value is OfficeDocumentType {
+  return (
+    typeof value === "string" &&
+    (["pptx", "docx", "pdf", "txt", "md", "csv"] as string[]).includes(value)
+  );
+}
+import { parseDocxDocument, sanitizeInertDocumentHtml } from "./docx.js";
+import {
+  parsePptxPresentation,
+  type ParsedPptxImage,
+  type ParsedPptxTextRun,
+} from "./pptx.js";