@saibolla/ada 0.1.2

package/extensions/docparser/schema.ts

@@ -0,0 +1,82 @@
+import { StringEnum, Type } from "@mariozechner/pi-ai";
+
+export const DocumentParseSchema = Type.Object({
+  path: Type.String({
+    description:
+      "Path to the document file to parse (PDF, DOCX, PPTX, XLSX, CSV, PNG, JPG, TIFF, WebP, etc.)",
+  }),
+  format: Type.Optional(
+    StringEnum(["text", "json"] as const, {
+      description: "Output format for the parsed document (default: text)",
+    }),
+  ),
+  targetPages: Type.Optional(
+    Type.String({
+      description: 'Optional page selection for parsing, e.g. "1-5,10,15-20"',
+    }),
+  ),
+  screenshotPages: Type.Optional(
+    Type.String({
+      description:
+        'Optional PDF page selection for screenshots, e.g. "1-3,8" or "all". Screenshots are currently generated only for PDF inputs and are saved as PNG files.',
+    }),
+  ),
+  ocr: Type.Optional(
+    StringEnum(["auto", "off"] as const, {
+      description:
+        "OCR mode: auto uses LiteParse OCR behavior, off disables OCR for faster parsing",
+    }),
+  ),
+  ocrLanguage: Type.Optional(
+    Type.String({
+      description:
+        "Optional single OCR language code. Built-in Tesseract typically uses ISO 639-3 codes such as eng, deu, fra, jpn. Many HTTP OCR servers instead expect ISO 639-1 codes such as en, de, fr, ja.",
+    }),
+  ),
+  ocrLanguages: Type.Optional(
+    Type.Array(Type.String(), {
+      minItems: 1,
+      description:
+        "Optional multiple OCR language codes. For built-in Tesseract they are joined into a multilingual language string. For HTTP OCR servers, only the first code is forwarded.",
+    }),
+  ),
+  ocrServerUrl: Type.Optional(
+    Type.String({
+      description: "Optional HTTP OCR server URL implementing the LiteParse OCR API",
+    }),
+  ),
+  numWorkers: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Optional OCR worker count (default: CPU cores - 1)",
+    }),
+  ),
+  maxPages: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Maximum number of pages to parse (default: 10000)",
+    }),
+  ),
+  dpi: Type.Optional(
+    Type.Integer({
+      minimum: 72,
+      description: "Rendering DPI for OCR and screenshots (default: 150)",
+    }),
+  ),
+  preciseBoundingBox: Type.Optional(
+    Type.Boolean({
+      description: "Whether to compute precise bounding boxes (default: true)",
+    }),
+  ),
+  preserveSmallText: Type.Optional(
+    Type.Boolean({
+      description: "Whether to preserve very small text that would otherwise be filtered out",
+    }),
+  ),
+  preserveLayoutAlignmentAcrossPages: Type.Optional(
+    Type.Boolean({
+      description:
+        "Whether to preserve text alignment consistently across page boundaries (default: false)",
+    }),
+  ),
+});

package/extensions/docparser/tool.ts

@@ -0,0 +1,305 @@
+import { truncateHead, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { PREVIEW_MAX_BYTES, PREVIEW_MAX_LINES } from "./constants.ts";
+import {
+  appendDoctorHint,
+  getMissingHostDependencyMessage,
+  isDependencySetupMessage,
+} from "./deps.ts";
+import { resolveDocumentTarget } from "./input.ts";
+import { buildDocumentParsePlan } from "./request.ts";
+import { DocumentParseSchema } from "./schema.ts";
+import type {
+  DocumentParseDetails,
+  DocumentParseParams,
+  DocumentOutputFormat,
+  InputInspection,
+  ScreenshotSelection,
+} from "./types.ts";
+
+let liteParseModulePromise: Promise<typeof import("@llamaindex/liteparse")> | undefined;
+
+async function loadLiteParseModule(): Promise<typeof import("@llamaindex/liteparse")> {
+  liteParseModulePromise ??= import("@llamaindex/liteparse");
+  return liteParseModulePromise;
+}
+
+function buildFriendlyErrorMessage(
+  error: unknown,
+  stage: "parse" | "screenshot" = "parse",
+): string {
+  const message = error instanceof Error ? error.message : String(error);
+
+  if (stage === "parse") {
+    if (isDependencySetupMessage(message)) {
+      return appendDoctorHint(message);
+    }
+
+    return message || "Document parsing failed.";
+  }
+
+  return message.startsWith("Screenshot generation failed:")
+    ? message
+    : `Screenshot generation failed: ${message}`;
+}
+
+function buildPreview(output: string): { preview: string; truncated: boolean } {
+  const truncation = truncateHead(output, {
+    maxLines: PREVIEW_MAX_LINES,
+    maxBytes: PREVIEW_MAX_BYTES,
+  });
+
+  return {
+    preview: truncation.content.trim(),
+    truncated: truncation.truncated,
+  };
+}
+
+type ProgressEmitter = (text: string) => void;
+
+async function renderScreenshots(options: {
+  parser: {
+    screenshot(
+      filePath: string,
+      pageNumbers?: number[],
+      quiet?: boolean,
+    ): Promise<Array<{ pageNum: number; imageBuffer: Buffer }>>;
+  };
+  screenshotSelection?: ScreenshotSelection;
+  inspection: InputInspection;
+  resolvedPath: string;
+  outputDir: string;
+  signal?: AbortSignal;
+  emit: ProgressEmitter;
+}): Promise<{
+  screenshotCount: number;
+  screenshotDir?: string;
+  screenshotPathsPreview?: string[];
+  warnings: string[];
+}> {
+  const warnings: string[] = [];
+  const selection = options.screenshotSelection;
+
+  if (!selection) {
+    return { screenshotCount: 0, warnings };
+  }
+
+  if (options.signal?.aborted) {
+    warnings.push(
+      "Operation was aborted before screenshot rendering. Parsed output was still saved.",
+    );
+    return { screenshotCount: 0, warnings };
+  }
+
+  if (options.inspection.category !== "pdf") {
+    warnings.push(
+      "Screenshots were requested, but this extension currently generates screenshots only for PDF inputs. The document was parsed, but screenshots were skipped.",
+    );
+    return { screenshotCount: 0, warnings };
+  }
+
+  try {
+    options.emit(`Rendering screenshots for ${selection.description}...`);
+    const screenshots = await options.parser.screenshot(
+      options.resolvedPath,
+      selection.pageNumbers,
+      true,
+    );
+    const screenshotDir = join(options.outputDir, "screenshots");
+    await mkdir(screenshotDir, { recursive: true });
+
+    const allScreenshotPaths: string[] = [];
+    for (const screenshot of screenshots) {
+      const screenshotPath = join(screenshotDir, `page_${screenshot.pageNum}.png`);
+      await writeFile(screenshotPath, screenshot.imageBuffer);
+      allScreenshotPaths.push(screenshotPath);
+    }
+
+    const screenshotCount = allScreenshotPaths.length;
+    options.emit(
+      `Saved ${screenshotCount} screenshot${screenshotCount === 1 ? "" : "s"} to ${screenshotDir}`,
+    );
+
+    return {
+      screenshotCount,
+      screenshotDir,
+      screenshotPathsPreview: allScreenshotPaths.slice(0, 10),
+      warnings,
+    };
+  } catch (error) {
+    warnings.push(buildFriendlyErrorMessage(error, "screenshot"));
+    return { screenshotCount: 0, warnings };
+  }
+}
+
+function buildSummary(options: {
+  sourcePath: string;
+  resolvedPath: string;
+  outputFormat: DocumentOutputFormat;
+  outputPath: string;
+  pageCount: number;
+  screenshotCount: number;
+  screenshotDir?: string;
+  screenshotPathsPreview?: string[];
+  warnings: string[];
+  preview: string;
+  truncated: boolean;
+}): string {
+  const lines = [
+    `Parsed document: ${options.sourcePath}`,
+    `Resolved path: ${options.resolvedPath}`,
+    `Output format: ${options.outputFormat}`,
+    `Pages parsed: ${options.pageCount}`,
+    `Parsed output saved to: ${options.outputPath}`,
+  ];
+
+  if (options.screenshotDir) {
+    lines.push(`Screenshots saved to: ${options.screenshotDir}`);
+    lines.push(`Screenshot count: ${options.screenshotCount}`);
+
+    if (options.screenshotPathsPreview?.length) {
+      lines.push("Screenshot files:");
+      for (const screenshotPath of options.screenshotPathsPreview) {
+        lines.push(`- ${screenshotPath}`);
+      }
+
+      if (options.screenshotCount > options.screenshotPathsPreview.length) {
+        lines.push(
+          `- ...and ${options.screenshotCount - options.screenshotPathsPreview.length} more`,
+        );
+      }
+    }
+  }
+
+  if (options.warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const warning of options.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  if (options.preview.length > 0) {
+    lines.push("Preview:");
+    lines.push(options.preview);
+
+    if (options.truncated) {
+      lines.push("");
+      lines.push(
+        `Preview truncated. Use read on ${options.outputPath} for the full parsed output.`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function registerDocumentParseTool(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "document_parse",
+    label: "Document Parse",
+    description:
+      "Parse local documents with bundled LiteParse support. Supports PDF, DOCX, PPTX, XLSX, CSV, and common images. Returns parsed output saved to temp files plus metadata and optional PDF screenshots.",
+    promptSnippet:
+      "Parse local documents to text or JSON with OCR, bounding boxes, page ranges, and optional PDF screenshots. Full results are saved to temp files for follow-up inspection with read.",
+    promptGuidelines: [
+      "Use this tool instead of composing LiteParse CLI commands manually when the user wants local document parsing.",
+      "After this tool returns output or screenshot paths, use read on those files when you need the full parsed content or to inspect generated screenshots.",
+    ],
+    parameters: DocumentParseSchema,
+
+    async execute(_toolCallId, rawParams, signal, onUpdate, ctx) {
+      if (signal?.aborted) {
+        return {
+          content: [{ type: "text", text: "Document parsing was cancelled before it started." }],
+          details: {},
+        };
+      }
+
+      const emit: ProgressEmitter = (text) =>
+        onUpdate?.({
+          content: [{ type: "text", text }],
+          details: {},
+        });
+      const params = rawParams as DocumentParseParams;
+
+      try {
+        const input = await resolveDocumentTarget(params.path, ctx.cwd);
+        const plan = buildDocumentParsePlan(params);
+        const warnings = [...plan.warnings];
+
+        emit("Checking host dependencies...");
+        const missingHostDependencyMessage = await getMissingHostDependencyMessage(
+          input.inspection,
+        );
+        if (missingHostDependencyMessage) {
+          throw new Error(missingHostDependencyMessage);
+        }
+
+        emit("Loading LiteParse...");
+        const { LiteParse } = await loadLiteParseModule();
+        const parser = new LiteParse(plan.parserConfig);
+        const outputDir = await mkdtemp(join(tmpdir(), "pi-document-parse-"));
+
+        emit(`Parsing document: ${input.sourcePath}`);
+        const parseResult = await parser.parse(input.resolvedPath, true);
+        const outputFormat = plan.parserConfig.outputFormat ?? "text";
+        const outputText =
+          outputFormat === "json"
+            ? JSON.stringify(parseResult.json ?? { pages: [] }, null, 2)
+            : parseResult.text;
+        const outputPath = join(outputDir, outputFormat === "json" ? "parsed.json" : "parsed.txt");
+        await writeFile(outputPath, outputText, "utf8");
+        emit(`Saved parsed output to ${outputPath}`);
+
+        const screenshotResult = await renderScreenshots({
+          parser,
+          screenshotSelection: plan.screenshotSelection,
+          inspection: input.inspection,
+          resolvedPath: input.resolvedPath,
+          outputDir,
+          signal,
+          emit,
+        });
+        warnings.push(...screenshotResult.warnings);
+
+        const { preview, truncated } = buildPreview(outputText);
+        const content = buildSummary({
+          sourcePath: input.sourcePath,
+          resolvedPath: input.resolvedPath,
+          outputFormat,
+          outputPath,
+          pageCount: parseResult.pages.length,
+          screenshotCount: screenshotResult.screenshotCount,
+          screenshotDir: screenshotResult.screenshotDir,
+          screenshotPathsPreview: screenshotResult.screenshotPathsPreview,
+          warnings,
+          preview,
+          truncated,
+        });
+
+        const details: DocumentParseDetails = {
+          sourcePath: input.sourcePath,
+          resolvedPath: input.resolvedPath,
+          outputFormat,
+          outputPath,
+          outputDir,
+          pageCount: parseResult.pages.length,
+          screenshotCount: screenshotResult.screenshotCount,
+          screenshotDir: screenshotResult.screenshotDir,
+          screenshotPathsPreview: screenshotResult.screenshotPathsPreview,
+          warnings: warnings.length > 0 ? warnings : undefined,
+        };
+
+        return {
+          content: [{ type: "text", text: content }],
+          details,
+        };
+      } catch (error) {
+        throw new Error(buildFriendlyErrorMessage(error));
+      }
+    },
+  });
+}

package/extensions/docparser/types.ts

@@ -0,0 +1,99 @@
+import type { Static } from "@mariozechner/pi-ai";
+import type { LiteParseConfig } from "@llamaindex/liteparse";
+
+import { DocumentParseSchema } from "./schema.ts";
+
+export type DocumentParseParams = Static<typeof DocumentParseSchema>;
+export type DocumentOutputFormat = NonNullable<DocumentParseParams["format"]>;
+
+export interface DocumentParseDetails {
+  sourcePath: string;
+  resolvedPath: string;
+  outputFormat: DocumentOutputFormat;
+  outputPath: string;
+  outputDir: string;
+  pageCount: number;
+  screenshotCount: number;
+  screenshotDir?: string;
+  screenshotPathsPreview?: string[];
+  warnings?: string[];
+}
+
+export type InputCategory = "pdf" | "office" | "spreadsheet" | "image" | "other";
+export type DependencyName = "libreoffice" | "imagemagick" | "ghostscript";
+export type PackageManagerId =
+  | "brew"
+  | "apt-get"
+  | "dnf"
+  | "yum"
+  | "pacman"
+  | "zypper"
+  | "apk"
+  | "winget"
+  | "choco";
+
+export interface InputInspection {
+  extension: string;
+  category: InputCategory;
+}
+
+export interface DependencyDiagnosis {
+  name: DependencyName;
+  label: string;
+  installed: boolean;
+  detectedCommand?: string;
+  relevant: boolean;
+  summary: string;
+  missingMessage: string;
+}
+
+export interface InstallCommandSpec {
+  description: string;
+  command: string;
+  args: string[];
+  display: string;
+  timeoutMs?: number;
+}
+
+export interface InstallStrategy {
+  id: PackageManagerId;
+  label: string;
+  autoRunnable: boolean;
+  autoRunBlockedReason?: string;
+  commands: InstallCommandSpec[];
+}
+
+export interface UnixPrivilegeContext {
+  prefix: string[];
+  displayPrefix: string;
+  autoRunnable: boolean;
+  blockedReason?: string;
+}
+
+export interface ScreenshotSelection {
+  pageNumbers?: number[];
+  description: string;
+}
+
+export type LiteParseToolConfig = Partial<
+  Pick<
+    LiteParseConfig,
+    | "outputFormat"
+    | "ocrEnabled"
+    | "ocrLanguage"
+    | "ocrServerUrl"
+    | "numWorkers"
+    | "maxPages"
+    | "targetPages"
+    | "dpi"
+    | "preciseBoundingBox"
+    | "preserveVerySmallText"
+    | "preserveLayoutAlignmentAcrossPages"
+  >
+>;
+
+export interface DocumentParsePlan {
+  parserConfig: LiteParseToolConfig;
+  screenshotSelection?: ScreenshotSelection;
+  warnings: string[];
+}

package/extensions/research-tools/alpha.ts

@@ -0,0 +1,107 @@
+import {
+	askPaper,
+	annotatePaper,
+	clearPaperAnnotation,
+	getPaper,
+	listPaperAnnotations,
+	readPaperCode,
+	searchPapers,
+} from "@ada/alpha-hub/lib";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+function formatText(value: unknown): string {
+	if (typeof value === "string") return value;
+	return JSON.stringify(value, null, 2);
+}
+
+export function registerAlphaTools(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "alpha_search",
+		label: "Alpha Search",
+		description:
+			"Search research papers through alphaXiv. Modes: semantic (default, use 2-3 sentence queries), keyword (exact terms), agentic (broad multi-turn retrieval), both, or all.",
+		parameters: Type.Object({
+			query: Type.String({ description: "Search query." }),
+			mode: Type.Optional(
+				Type.String({ description: "Search mode: semantic, keyword, both, agentic, or all." }),
+			),
+		}),
+		async execute(_toolCallId, params) {
+			const result = await searchPapers(params.query, params.mode?.trim() || "semantic");
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_get_paper",
+		label: "Alpha Get Paper",
+		description: "Fetch a paper's AI-generated report (or raw full text) plus any local annotation.",
+		parameters: Type.Object({
+			paper: Type.String({ description: "arXiv ID, arXiv URL, or alphaXiv URL." }),
+			fullText: Type.Optional(Type.Boolean({ description: "Return raw full text instead of AI report." })),
+		}),
+		async execute(_toolCallId, params) {
+			const result = await getPaper(params.paper, { fullText: params.fullText });
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_ask_paper",
+		label: "Alpha Ask Paper",
+		description: "Ask a targeted question about a paper. Uses AI to analyze the PDF and answer.",
+		parameters: Type.Object({
+			paper: Type.String({ description: "arXiv ID, arXiv URL, or alphaXiv URL." }),
+			question: Type.String({ description: "Question about the paper." }),
+		}),
+		async execute(_toolCallId, params) {
+			const result = await askPaper(params.paper, params.question);
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_annotate_paper",
+		label: "Alpha Annotate Paper",
+		description: "Write or clear a persistent local annotation for a paper.",
+		parameters: Type.Object({
+			paper: Type.String({ description: "Paper ID (arXiv ID or URL)." }),
+			note: Type.Optional(Type.String({ description: "Annotation text. Omit when clear=true." })),
+			clear: Type.Optional(Type.Boolean({ description: "Clear the existing annotation." })),
+		}),
+		async execute(_toolCallId, params) {
+			const result = params.clear
+				? await clearPaperAnnotation(params.paper)
+				: params.note
+					? await annotatePaper(params.paper, params.note)
+					: (() => { throw new Error("Provide either note or clear=true."); })();
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_list_annotations",
+		label: "Alpha List Annotations",
+		description: "List all persistent local paper annotations.",
+		parameters: Type.Object({}),
+		async execute() {
+			const result = await listPaperAnnotations();
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_read_code",
+		label: "Alpha Read Code",
+		description: "Read files from a paper's GitHub repository. Use '/' for repo overview.",
+		parameters: Type.Object({
+			githubUrl: Type.String({ description: "GitHub repository URL." }),
+			path: Type.Optional(Type.String({ description: "File or directory path. Default: '/'" })),
+		}),
+		async execute(_toolCallId, params) {
+			const result = await readPaperCode(params.githubUrl, params.path?.trim() || "/");
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+}