@sylphx/image-reader-mcp 0.1.0 → 0.1.2

package/src/utils/layout.ts

@@ -0,0 +1,114 @@
+/**
+ * Deterministic layout structure from OCR line boxes (no generative model).
+ */
+
+export type BBox = { x: number; y: number; width: number; height: number };
+
+export type LayoutLine = {
+  text: string;
+  bbox: BBox;
+  confidence?: number;
+};
+
+export type LayoutBlock = {
+  id: string;
+  kind: 'text_block';
+  text: string;
+  bbox: BBox;
+  line_count: number;
+  reading_order: number;
+};
+
+export type ImageLayout = {
+  policy: string;
+  block_count: number;
+  blocks: LayoutBlock[];
+  full_text: string;
+  warnings: string[];
+};
+
+const unionBBox = (boxes: BBox[]): BBox => {
+  const minX = Math.min(...boxes.map((b) => b.x));
+  const minY = Math.min(...boxes.map((b) => b.y));
+  const maxX = Math.max(...boxes.map((b) => b.x + b.width));
+  const maxY = Math.max(...boxes.map((b) => b.y + b.height));
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+};
+
+const median = (values: number[], fallback: number): number => {
+  if (values.length === 0) return fallback;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? fallback;
+};
+
+const shouldMerge = (prev: LayoutLine, next: LayoutLine, yGap: number, xSlop: number): boolean => {
+  const verticalClose = next.bbox.y - (prev.bbox.y + prev.bbox.height) <= yGap;
+  const prevRight = prev.bbox.x + prev.bbox.width;
+  const nextRight = next.bbox.x + next.bbox.width;
+  const horizontalOverlap =
+    Math.min(prevRight, nextRight) - Math.max(prev.bbox.x, next.bbox.x) > -xSlop;
+  return verticalClose && horizontalOverlap;
+};
+
+const toBlock = (lines: LayoutLine[], index: number): LayoutBlock => {
+  const ordered = [...lines].sort((a, b) => a.bbox.y - b.bbox.y || a.bbox.x - b.bbox.x);
+  const text = ordered
+    .map((l) => l.text.trim())
+    .filter(Boolean)
+    .join('\n');
+  return {
+    id: `block-${index + 1}`,
+    kind: 'text_block',
+    text,
+    bbox: unionBBox(ordered.map((l) => l.bbox)),
+    line_count: ordered.length,
+    reading_order: index + 1,
+  };
+};
+
+export function buildLayoutFromOcrLines(lines: LayoutLine[]): ImageLayout {
+  if (lines.length === 0) {
+    return {
+      policy: 'ocr_line_cluster_v1',
+      block_count: 0,
+      blocks: [],
+      full_text: '',
+      warnings: ['No OCR lines available for layout clustering.'],
+    };
+  }
+
+  const sorted = [...lines].sort((a, b) => a.bbox.y - b.bbox.y || a.bbox.x - b.bbox.x);
+  const medianHeight = median(
+    sorted.map((l) => l.bbox.height).filter((h) => h > 0),
+    16
+  );
+  const yGap = Math.max(8, medianHeight * 1.4);
+  const xSlop = medianHeight * 2;
+
+  const clusters: LayoutLine[][] = [];
+  for (const line of sorted) {
+    const last = clusters[clusters.length - 1];
+    const prev = last?.[last.length - 1];
+    if (last && prev && shouldMerge(prev, line, yGap, xSlop)) {
+      last.push(line);
+    } else {
+      clusters.push([line]);
+    }
+  }
+
+  const blocks = clusters.map((cluster, index) => toBlock(cluster, index));
+  const warnings: string[] = [];
+  if (blocks.length === 1 && lines.length > 8) {
+    warnings.push(
+      'Layout collapsed to a single block; image may be dense continuous text or OCR line geometry is coarse.'
+    );
+  }
+
+  return {
+    policy: 'ocr_line_cluster_v1',
+    block_count: blocks.length,
+    blocks,
+    full_text: blocks.map((b) => b.text).join('\n\n'),
+    warnings,
+  };
+}

package/src/utils/metadata.ts

@@ -0,0 +1,108 @@
+const GPS_FIELD_PATTERN = /^(gps|geo|location|latitude|longitude|altitude|coordinates)/i;
+
+const GPS_NESTED_KEYS = new Set([
+  'latitude',
+  'longitude',
+  'altitude',
+  'lat',
+  'lon',
+  'lng',
+  'GPSLatitude',
+  'GPSLongitude',
+  'GPSAltitude',
+  'GPSLatitudeRef',
+  'GPSLongitudeRef',
+  'GPSAltitudeRef',
+  'GPSDateStamp',
+  'GPSTimeStamp',
+  'GPSProcessingMethod',
+  'GPSAreaInformation',
+  'GPSDOP',
+  'GPSMapDatum',
+  'GPSDestLatitude',
+  'GPSDestLongitude',
+  'GPSDestBearing',
+  'GPSDestDistance',
+  'GPSHPositioningError',
+]);
+
+const isGpsKey = (key: string): boolean => GPS_FIELD_PATTERN.test(key) || GPS_NESTED_KEYS.has(key);
+
+const redactValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item));
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return redactGpsFields(value as Record<string, unknown>).metadata;
+  }
+
+  return '[redacted]';
+};
+
+export const redactGpsFields = (
+  metadata: Record<string, unknown>
+): { metadata: Record<string, unknown>; hadGps: boolean } => {
+  let hadGps = false;
+  const redacted: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(metadata)) {
+    if (key.toLowerCase() === 'gps' && value !== null && typeof value === 'object') {
+      hadGps = true;
+      redacted[key] = '[redacted]';
+      continue;
+    }
+
+    if (isGpsKey(key)) {
+      hadGps = true;
+      redacted[key] = redactValue(value);
+      continue;
+    }
+
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      const nested = redactGpsFields(value as Record<string, unknown>);
+      if (nested.hadGps) hadGps = true;
+      redacted[key] = nested.metadata;
+      continue;
+    }
+
+    redacted[key] = value;
+  }
+
+  return { metadata: redacted, hadGps };
+};
+
+export const collectTrustWarnings = (
+  metadata: Record<string, unknown>,
+  hadGps: boolean
+): string[] => {
+  const warnings: string[] = [];
+
+  if (hadGps) {
+    warnings.push(
+      'GPS coordinates were present in metadata and have been redacted from the response.'
+    );
+  }
+
+  const software = metadata['Software'] ?? metadata['software'];
+  if (
+    typeof software === 'string' &&
+    /photoshop|gimp|ai|generative|midjourney|stable diffusion/i.test(software)
+  ) {
+    warnings.push(
+      `EXIF Software field suggests possible editing or synthetic origin: "${software}".`
+    );
+  }
+
+  const make = metadata['Make'] ?? metadata['make'];
+  const model = metadata['Model'] ?? metadata['model'];
+  if (
+    typeof make === 'string' &&
+    typeof model === 'string' &&
+    /unknown|fake|synthetic/i.test(`${make} ${model}`)
+  ) {
+    warnings.push('Camera make/model metadata looks inconsistent or synthetic.');
+  }
+
+  return warnings;
+};

package/src/utils/ocr.ts

@@ -0,0 +1,279 @@
+import { spawnSync } from 'node:child_process';
+import type { OcrLine } from '../schemas/readImage.js';
+
+const OCR_HEALTHCHECK_TIMEOUT_MS = 2_500;
+const OCR_TIMEOUT_MS = 60_000;
+
+export interface OcrWord {
+  text: string;
+  bbox: { x: number; y: number; width: number; height: number };
+  confidence?: number;
+}
+
+export interface OcrResult {
+  available: boolean;
+  skipped_reason?: string;
+  /** Adapter route for evidence contract honesty */
+  route?: string;
+  languages?: string[];
+  languages_warning?: string;
+  line_count?: number;
+  dropped_low_confidence?: number;
+  lines: OcrLine[];
+  words?: OcrWord[];
+}
+
+export interface ParseTesseractOptions {
+  minConfidence?: number;
+  includeWords?: boolean;
+}
+
+/** Pure TSV parser — offline-testable evidence path for OCR bbox lines. */
+export const parseTesseractTsv = (
+  raw: string,
+  options: ParseTesseractOptions = {}
+): { lines: OcrLine[]; words: OcrWord[]; dropped_low_confidence: number } => {
+  const minConfidence = options.minConfidence ?? 0;
+  const includeWords = options.includeWords ?? false;
+  const linesRaw = raw.split(/\r?\n/).filter((line) => line.length > 0);
+  if (linesRaw.length <= 1) {
+    return { lines: [], words: [], dropped_low_confidence: 0 };
+  }
+
+  const rows = linesRaw.slice(1).map((line) => line.split('\t'));
+  const lineMap = new Map<
+    number,
+    {
+      words: Array<{
+        text: string;
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+        conf: number;
+      }>;
+    }
+  >();
+
+  let dropped = 0;
+  const flatWords: OcrWord[] = [];
+
+  for (const columns of rows) {
+    if (columns.length < 12) continue;
+    const level = Number.parseInt(columns[0] ?? '', 10);
+    if (level !== 5) continue;
+
+    const text = columns[11]?.trim() ?? '';
+    if (text.length === 0) continue;
+
+    const lineNum = Number.parseInt(columns[4] ?? '', 10);
+    const left = Number.parseInt(columns[6] ?? '', 10);
+    const top = Number.parseInt(columns[7] ?? '', 10);
+    const width = Number.parseInt(columns[8] ?? '', 10);
+    const height = Number.parseInt(columns[9] ?? '', 10);
+    const conf = Number.parseFloat(columns[10] ?? '');
+
+    if (!Number.isFinite(lineNum) || !Number.isFinite(left) || !Number.isFinite(top)) continue;
+
+    const confVal = Number.isFinite(conf) ? conf : 0;
+    if (confVal < minConfidence) {
+      dropped += 1;
+      continue;
+    }
+
+    const bucket = lineMap.get(lineNum) ?? { words: [] };
+    bucket.words.push({
+      text,
+      left,
+      top,
+      width: Number.isFinite(width) ? width : 0,
+      height: Number.isFinite(height) ? height : 0,
+      conf: confVal,
+    });
+    lineMap.set(lineNum, bucket);
+
+    if (includeWords) {
+      flatWords.push({
+        text,
+        bbox: {
+          x: left,
+          y: top,
+          width: Number.isFinite(width) ? width : 0,
+          height: Number.isFinite(height) ? height : 0,
+        },
+        confidence: confVal,
+      });
+    }
+  }
+
+  const ocrLines: OcrLine[] = [];
+
+  for (const bucket of lineMap.values()) {
+    if (bucket.words.length === 0) continue;
+
+    const sorted = [...bucket.words].sort((a, b) => a.left - b.left);
+    const text = sorted
+      .map((word) => word.text)
+      .join(' ')
+      .trim();
+    if (text.length === 0) continue;
+
+    const left = Math.min(...sorted.map((word) => word.left));
+    const top = Math.min(...sorted.map((word) => word.top));
+    const right = Math.max(...sorted.map((word) => word.left + word.width));
+    const bottom = Math.max(...sorted.map((word) => word.top + word.height));
+    const confidenceValues = sorted.map((word) => word.conf).filter((value) => value >= 0);
+    const confidence =
+      confidenceValues.length > 0
+        ? confidenceValues.reduce((sum, value) => sum + value, 0) / confidenceValues.length
+        : undefined;
+
+    ocrLines.push({
+      text,
+      bbox: {
+        x: left,
+        y: top,
+        width: Math.max(0, right - left),
+        height: Math.max(0, bottom - top),
+      },
+      ...(confidence !== undefined ? { confidence } : {}),
+    });
+  }
+
+  return {
+    lines: ocrLines.sort((a, b) => a.bbox.y - b.bbox.y || a.bbox.x - b.bbox.x),
+    words: includeWords ? flatWords.sort((a, b) => a.bbox.y - b.bbox.y || a.bbox.x - b.bbox.x) : [],
+    dropped_low_confidence: dropped,
+  };
+};
+
+export const isTesseractAvailable = (): boolean => {
+  const result = spawnSync('tesseract', ['--version'], {
+    timeout: OCR_HEALTHCHECK_TIMEOUT_MS,
+    windowsHide: true,
+    stdio: 'ignore',
+  });
+  return result.status === 0;
+};
+
+/** List installed Tesseract traineddata languages (honest empty when unavailable). */
+export const listTesseractLanguages = (): {
+  available: boolean;
+  languages: string[];
+  warning?: string;
+} => {
+  if (!isTesseractAvailable()) {
+    return {
+      available: false,
+      languages: [],
+      warning: 'Tesseract is not installed or not available on PATH.',
+    };
+  }
+  const result = spawnSync('tesseract', ['--list-langs'], {
+    encoding: 'utf8',
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+    return {
+      available: false,
+      languages: [],
+      warning: stderr || 'tesseract --list-langs failed',
+    };
+  }
+  const out = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+  const languages = out
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(
+      (l) => l && !l.toLowerCase().includes('list of available languages') && !l.startsWith('Error')
+    );
+  return { available: true, languages };
+};
+
+export type RunOcrOptions = {
+  languages?: string[];
+  minConfidence?: number;
+  includeWords?: boolean;
+};
+
+export const runTesseractOcr = (
+  imagePath: string,
+  languagesOrOptions: string[] | RunOcrOptions = ['eng']
+): OcrResult => {
+  const options: RunOcrOptions = Array.isArray(languagesOrOptions)
+    ? { languages: languagesOrOptions }
+    : languagesOrOptions;
+  const languages = options.languages?.length ? options.languages : ['eng'];
+  const minConfidence = options.minConfidence ?? 0;
+  const includeWords = options.includeWords ?? false;
+
+  if (!isTesseractAvailable()) {
+    return {
+      available: false,
+      skipped_reason: 'Tesseract is not installed or not available on PATH.',
+      route: 'tesseract_tsv',
+      languages,
+      lines: [],
+      line_count: 0,
+      dropped_low_confidence: 0,
+    };
+  }
+
+  const installed = listTesseractLanguages();
+  const missingLangs = languages.filter(
+    (lang) => installed.available && !installed.languages.includes(lang)
+  );
+
+  const languageArg = languages.join('+');
+  const result = spawnSync('tesseract', [imagePath, 'stdout', '-l', languageArg, 'tsv'], {
+    encoding: 'utf8',
+    timeout: OCR_TIMEOUT_MS,
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  if (result.error) {
+    return {
+      available: false,
+      skipped_reason: `Tesseract failed to start: ${result.error.message}`,
+      route: 'tesseract_tsv',
+      languages,
+      lines: [],
+      line_count: 0,
+      dropped_low_confidence: 0,
+    };
+  }
+
+  if (result.status !== 0) {
+    const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+    return {
+      available: false,
+      skipped_reason:
+        stderr.length > 0 ? stderr : `Tesseract exited with status ${String(result.status)}.`,
+      route: 'tesseract_tsv',
+      languages,
+      lines: [],
+      line_count: 0,
+      dropped_low_confidence: 0,
+    };
+  }
+
+  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+  const parsed = parseTesseractTsv(stdout, { minConfidence, includeWords });
+  return {
+    available: true,
+    route: 'tesseract_tsv',
+    languages,
+    lines: parsed.lines,
+    line_count: parsed.lines.length,
+    dropped_low_confidence: parsed.dropped_low_confidence,
+    ...(missingLangs.length
+      ? {
+          languages_warning: `Requested OCR language(s) not listed by tesseract --list-langs: ${missingLangs.join(', ')}. Installed: ${installed.languages.join(', ') || '(none)'}.`,
+        }
+      : {}),
+    ...(includeWords ? { words: parsed.words } : {}),
+  };
+};

package/src/utils/optionalLlm.ts

@@ -0,0 +1,67 @@
+/**
+ * Optional local/remote vision caption — OFF by default (local-first).
+ * Set IRIS_OPTIONAL_LLM_URL to a POST endpoint that accepts JSON
+ * { path, mime, purpose: "image_caption" } and returns { caption: string }.
+ * Never treated as authority over OCR/layout evidence.
+ */
+
+export type OptionalLlmResult = {
+  available: boolean;
+  skipped_reason?: string;
+  route?: string;
+  caption?: string;
+};
+
+export async function maybeOptionalImageCaption(input: {
+  path: string;
+  mime: string;
+  enabled: boolean;
+}): Promise<OptionalLlmResult> {
+  if (!input.enabled) {
+    return { available: false, skipped_reason: 'include_optional_llm is false (default).' };
+  }
+  const url = process.env['IRIS_OPTIONAL_LLM_URL'];
+  if (!url) {
+    return {
+      available: false,
+      skipped_reason:
+        'IRIS_OPTIONAL_LLM_URL is not set. Local OCR/layout remain the evidence authority.',
+    };
+  }
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        path: input.path,
+        mime: input.mime,
+        purpose: 'image_caption',
+      }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+      return {
+        available: false,
+        skipped_reason: `optional LLM HTTP ${res.status}`,
+        route: url,
+      };
+    }
+    const body = (await res.json()) as { caption?: string };
+    if (!body.caption || typeof body.caption !== 'string') {
+      return {
+        available: false,
+        skipped_reason: 'optional LLM response missing caption string',
+        route: url,
+      };
+    }
+    return {
+      available: true,
+      route: `optional-llm:${url}`,
+      caption: body.caption.slice(0, 4000),
+    };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'optional LLM failed';
+    return { available: false, skipped_reason: message, route: url };
+  }
+}

package/src/utils/palette.ts

@@ -0,0 +1,36 @@
+import sharp from 'sharp';
+
+/** Cheap local palette sample via sharp stats (not ML segmentation). */
+export async function samplePalette(
+  filePath: string,
+  maxColors = 5
+): Promise<Array<{ hex: string; approx_share: number }>> {
+  const image = sharp(filePath, { failOn: 'none' }).resize(64, 64, { fit: 'inside' });
+  const stats = await image.stats();
+  const dominant = stats.dominant;
+  if (!dominant) return [];
+
+  const hex = (r: number, g: number, b: number) =>
+    `#${[r, g, b]
+      .map((v) =>
+        Math.max(0, Math.min(255, Math.round(v)))
+          .toString(16)
+          .padStart(2, '0')
+      )
+      .join('')}`;
+
+  const colors: Array<{ hex: string; approx_share: number }> = [
+    { hex: hex(dominant.r, dominant.g, dominant.b), approx_share: 0.55 },
+  ];
+
+  // Channel means as a second honest swatch (not true multi-color clustering).
+  const ch = stats.channels;
+  if (ch && ch.length >= 3) {
+    colors.push({
+      hex: hex(ch[0]?.mean ?? dominant.r, ch[1]?.mean ?? dominant.g, ch[2]?.mean ?? dominant.b),
+      approx_share: 0.45,
+    });
+  }
+
+  return colors.slice(0, maxColors);
+}

package/src/utils/pathUtils.ts

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ErrorCode, ImageError } from './errors.js';
+
+export const PROJECT_ROOT = process.cwd();
+
+const canonicalize = (p: string): string => {
+  try {
+    return fs.realpathSync(p);
+  } catch (err: unknown) {
+    if (
+      typeof err === 'object' &&
+      err !== null &&
+      'code' in err &&
+      (err.code === 'ENOENT' || err.code === 'ENOTDIR')
+    ) {
+      const parent = path.dirname(p);
+      if (parent === p) return p;
+      return path.join(canonicalize(parent), path.basename(p));
+    }
+    throw err;
+  }
+};
+
+/**
+ * Resolves a user-provided path, accepting both absolute and relative paths.
+ * Relative paths are resolved against the current working directory.
+ */
+export const resolvePath = (userPath: string): string => {
+  if (typeof userPath !== 'string') {
+    throw new ImageError(ErrorCode.InvalidParams, 'Path must be a string.');
+  }
+
+  const normalizedUserPath = path.normalize(userPath);
+  const resolved = path.isAbsolute(normalizedUserPath)
+    ? normalizedUserPath
+    : path.resolve(PROJECT_ROOT, normalizedUserPath);
+
+  return canonicalize(resolved);
+};

package/src/utils/safety.ts

@@ -0,0 +1,29 @@
+import { ErrorCode, ImageError } from './errors.js';
+
+export const IMAGE_SAFETY_LIMITS = {
+  maxFileBytes: 32 * 1024 * 1024,
+  maxPixels: 64 * 1024 * 1024,
+} as const;
+
+export function validateImageSafety(input: {
+  fileSizeBytes: number;
+  width?: number | undefined;
+  height?: number | undefined;
+}): void {
+  if (input.fileSizeBytes > IMAGE_SAFETY_LIMITS.maxFileBytes) {
+    throw new ImageError(
+      ErrorCode.InvalidRequest,
+      `Image exceeds the ${IMAGE_SAFETY_LIMITS.maxFileBytes} byte safety limit.`
+    );
+  }
+
+  if (input.width !== undefined && input.height !== undefined) {
+    const pixels = input.width * input.height;
+    if (pixels > IMAGE_SAFETY_LIMITS.maxPixels) {
+      throw new ImageError(
+        ErrorCode.InvalidRequest,
+        `Image exceeds the ${IMAGE_SAFETY_LIMITS.maxPixels} pixel safety budget (${input.width}x${input.height}).`
+      );
+    }
+  }
+}