@eigenpal/cli 0.17.4 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @eigenpal/cli
 
+## 0.17.5
+
+### Patch Changes
+
+- e3c0246: CLI skill reference documents the new `ai.figure-crops` workflow step for cropping and captioning figures from parsed PDFs.
+
 ## 0.16.12
 
 ### Patch Changes

package/dist/cli.js

@@ -7800,8 +7800,10 @@ var init_ids = __esm(() => {
     CLASSIFY_PAGES: "builtin/classify-pages",
     VISION: "builtin/vision",
     SEARCH_FILES: "builtin/search-files",
+    FIGURE_CROPS: "builtin/figure-crops",
     TEMPLATE: "builtin/template",
     PDF_EMBEDDER: "builtin/pdf-embedder",
+    CROP_REGIONS: "builtin/crop-regions",
     XLSX_TO_JSON: "builtin/xlsx-to-json",
     JSON_TO_XLSX: "builtin/json-to-xlsx",
     ARCHIVE_LIST: "builtin/archive-list",
@@ -8163,7 +8165,8 @@ var init_parser = __esm(() => {
   ParseUsageSchema = object({
     pageCount: number2(),
     processingTimeMs: number2().optional(),
-    ocrPagesProcessed: number2().int().nonnegative().optional()
+    ocrPagesProcessed: number2().int().nonnegative().optional(),
+    cached: boolean2().optional()
   });
   StructuredDocumentSchema = record(string2(), unknown());
   CoordinateUnitSchema = _enum(["pixel", "inch", "point", "normalized"]);
@@ -8349,7 +8352,8 @@ var init_document_parser = __esm(() => {
     describeFigures: boolean2().optional().describe("Opt-in (default off). After text extraction, detect figure pages with a layout model and caption them with a vision model, appending `<figure>description</figure>` to their text. Skipped for plaintext. The caption vision calls are billed."),
     figureInstructions: string2().optional().describe("Custom instruction for the figure-description pass."),
     languages: array(string2()).optional().describe('OCR language hints (e.g., ["en", "de"])'),
-    outputFormat: ParseOutputFormatSchema.default("markdown").optional().describe(PARSE_OUTPUT_FORMAT_DESCRIPTION)
+    outputFormat: ParseOutputFormatSchema.default("markdown").optional().describe(PARSE_OUTPUT_FORMAT_DESCRIPTION),
+    cache: boolean2().default(false).optional().describe("When true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off.")
   }).superRefine(refineNativeParseModeConflicts).superRefine(refineLayoutOutputFormat).prefault({});
 });
 
@@ -53679,7 +53683,8 @@ var init_steps = __esm(() => {
     "ai.classify",
     "ai.classify-pages",
     "ai.vision",
-    "ai.search-files"
+    "ai.search-files",
+    "ai.figure-crops"
   ];
   TRANSFORM_STEP_TYPES = [
     "transform.set",
@@ -53689,6 +53694,7 @@ var init_steps = __esm(() => {
     "transform.merge",
     "transform.template",
     "transform.pdf-embed",
+    "transform.crop-regions",
     "transform.xlsx-to-json",
     "transform.json-to-xlsx",
     "transform.script",
@@ -53837,7 +53843,7 @@ function getStepSchema(stepType) {
 function listStepTypes() {
   return [...STEP_TYPES];
 }
-var OptionalReasoningEffortSchema, AiParseConfigSchema, AiParseOutputSchema, AiExtractConfigSchema, AiExtractOutputSchema, VisionPageRangeSchema, AiVisionConfigSchema, AiVisionOutputSchema, AI_SEARCH_FILES_DEFAULT_MAX_ITERATIONS = 12, AI_SEARCH_FILES_MAX_ITERATIONS = 50, AI_SEARCH_FILES_DEFAULT_MAX_FILES = 50, AI_SEARCH_FILES_MAX_FILES = 200, AI_SEARCH_FILES_MAX_CITATION_EXCERPT_CHARS = 2000, AiSearchFilesConfigSchema, AiSearchFilesCitationSchema, AiSearchFilesOutputSchema, AiSplitConfigSchema, AiSplitSectionSchema, AiSplitOutputSchema, AiSegmentConfigSchema, AiSegmentOutputSchema, AiClassifyConfigSchema, AiClassifyOutputSchema, ClassifyPagesLabelSchema2, AiClassifyPagesConfigSchema, AiClassifyPagesOutputSchema, TransformSetConfigSchema, TransformSetOutputSchema, TransformRemoveConfigSchema, TransformRemoveOutputSchema, TransformCombineConfigSchema, TransformCombineOutputSchema, TransformSplitConfigSchema, TransformSplitOutputSchema, TransformMergeConfigSchema, TransformMergeOutputSchema, TransformTemplateConfigSchema, TransformTemplateOutputSchema, TransformPdfEmbedConfigSchema, TransformPdfEmbedOutputSchema, TransformXlsxToJsonConfigSchema, TransformXlsxToJsonOutputSchema, JsonToXlsxAuthoringRowsSchema, JsonToXlsxSheetConfigSchema, TransformJsonToXlsxConfigSchema, TransformJsonToXlsxOutputSchema, ARCHIVE_LIST_MAX_ENTRIES = 1e4, TransformArchiveListConfigSchema, TransformArchiveListEntrySchema, TransformArchiveListOutputSchema, TransformArchiveExtractConfigSchema, TransformArchiveExtractOutputSchema, TransformScriptConfigSchema, TransformScriptOutputSchema, ParsedDocPageSchema, TransformTextChunkerConfigSchema, TransformTextChunkerOutputSchema, RegexNormalizerSchema, RegexFormatSchema, REGEX_FLAGS, RegexFieldSchema, TransformRegexExtractConfigSchema, TransformRegexExtractOutputSchema, ActionHttpConfigSchema, ActionHttpOutputSchema, ActionInvokeWorkflowConfigSchema, ActionInvokeWorkflowOutputSchema, ActionWebsiteReaderConfigSchema, ActionWebsiteReaderOutputSchema, ACTION_EMAIL_MAX_ATTACHMENTS = 10, ACTION_EMAIL_MAX_ATTACHMENT_BYTES, ACTION_EMAIL_BODY_MAX_BYTES, emailBodyMaxBytes = (value) => new TextEncoder().encode(value).byteLength <= ACTION_EMAIL_BODY_MAX_BYTES, ActionEmailRecipientListSchema, ActionEmailToSchema, ActionEmailOptionalRecipientsSchema, ActionEmailAttachmentSchema, ActionEmailConfigSchema, ActionEmailOutputSchema, ControlIfConfigSchema, ControlIfOutputSchema, ControlSwitchConfigSchema, ControlSwitchOutputSchema, ControlForeachConfigSchema, ControlForeachOutputSchema, ControlParallelMapConfigSchema, ControlParallelMapOutputSchema, ControlParallelConfigSchema, ControlParallelOutputSchema, ControlWaitConfigSchema, ControlWaitOutputSchema, ControlHumanReviewConfigSchema, ControlHumanReviewOutputSchema, ControlFailConfigSchema, ControlFailOutputSchema, STEP_SCHEMAS;
+var OptionalReasoningEffortSchema, AiParseConfigSchema, AiParseOutputSchema, AiFigureCropsConfigSchema, AiFigureCropsFigureSchema, AiFigureCropsOutputSchema, AiExtractConfigSchema, AiExtractOutputSchema, VisionPageRangeSchema, AiVisionConfigSchema, AiVisionOutputSchema, AI_SEARCH_FILES_DEFAULT_MAX_ITERATIONS = 12, AI_SEARCH_FILES_MAX_ITERATIONS = 50, AI_SEARCH_FILES_DEFAULT_MAX_FILES = 50, AI_SEARCH_FILES_MAX_FILES = 200, AI_SEARCH_FILES_MAX_CITATION_EXCERPT_CHARS = 2000, AiSearchFilesConfigSchema, AiSearchFilesCitationSchema, AiSearchFilesOutputSchema, AiSplitConfigSchema, AiSplitSectionSchema, AiSplitOutputSchema, AiSegmentConfigSchema, AiSegmentOutputSchema, AiClassifyConfigSchema, AiClassifyOutputSchema, ClassifyPagesLabelSchema2, AiClassifyPagesConfigSchema, AiClassifyPagesOutputSchema, TransformSetConfigSchema, TransformSetOutputSchema, TransformRemoveConfigSchema, TransformRemoveOutputSchema, TransformCombineConfigSchema, TransformCombineOutputSchema, TransformSplitConfigSchema, TransformSplitOutputSchema, TransformMergeConfigSchema, TransformMergeOutputSchema, TransformTemplateConfigSchema, TransformTemplateOutputSchema, TransformPdfEmbedConfigSchema, TransformPdfEmbedOutputSchema, CropRegionBboxSchema, CropRegionSpecSchema, CropRegionSpecListSchema, CropRegionSpecListResolvedSchema, TransformCropRegionsConfigSchema, TransformCropRegionsCropSchema, TransformCropRegionsOutputSchema, CropRegionsProcessorConfigSchema, TransformXlsxToJsonConfigSchema, TransformXlsxToJsonOutputSchema, JsonToXlsxAuthoringRowsSchema, JsonToXlsxSheetConfigSchema, TransformJsonToXlsxConfigSchema, TransformJsonToXlsxOutputSchema, ARCHIVE_LIST_MAX_ENTRIES = 1e4, TransformArchiveListConfigSchema, TransformArchiveListEntrySchema, TransformArchiveListOutputSchema, TransformArchiveExtractConfigSchema, TransformArchiveExtractOutputSchema, TransformScriptConfigSchema, TransformScriptOutputSchema, ParsedDocPageSchema, TransformTextChunkerConfigSchema, TransformTextChunkerOutputSchema, RegexNormalizerSchema, RegexFormatSchema, REGEX_FLAGS, RegexFieldSchema, TransformRegexExtractConfigSchema, TransformRegexExtractOutputSchema, ActionHttpConfigSchema, ActionHttpOutputSchema, ActionInvokeWorkflowConfigSchema, ActionInvokeWorkflowOutputSchema, ActionWebsiteReaderConfigSchema, ActionWebsiteReaderOutputSchema, ACTION_EMAIL_MAX_ATTACHMENTS = 10, ACTION_EMAIL_MAX_ATTACHMENT_BYTES, ACTION_EMAIL_BODY_MAX_BYTES, emailBodyMaxBytes = (value) => new TextEncoder().encode(value).byteLength <= ACTION_EMAIL_BODY_MAX_BYTES, ActionEmailRecipientListSchema, ActionEmailToSchema, ActionEmailOptionalRecipientsSchema, ActionEmailAttachmentSchema, ActionEmailConfigSchema, ActionEmailOutputSchema, ControlIfConfigSchema, ControlIfOutputSchema, ControlSwitchConfigSchema, ControlSwitchOutputSchema, ControlForeachConfigSchema, ControlForeachOutputSchema, ControlParallelMapConfigSchema, ControlParallelMapOutputSchema, ControlParallelConfigSchema, ControlParallelOutputSchema, ControlWaitConfigSchema, ControlWaitOutputSchema, ControlHumanReviewConfigSchema, ControlHumanReviewOutputSchema, ControlFailConfigSchema, ControlFailOutputSchema, STEP_SCHEMAS;
 var init_step_configs = __esm(() => {
   init_zod();
   init_ai_client();
@@ -53868,9 +53874,38 @@ var init_step_configs = __esm(() => {
     outputFormat: ParseOutputFormatSchema.default("markdown").optional().describe(PARSE_OUTPUT_FORMAT_DESCRIPTION),
     nativeText: boolean2().default(false).optional().describe("Extract native/embedded text from PDFs without OCR/VLM. Faster and uses no credits. Falls back to OCR/VLM if the PDF has no embedded text."),
     describeFigures: boolean2().optional().describe("Opt-in (default off). After text extraction, detect which pages contain figures with an in-worker layout model, then caption those pages with a vision model and append `<figure>description</figure>` to their text — so image-only pages (property photos, signatures, charts) become findable by text-based steps like ai.split. Note: the layout scan runs over all pages, and the caption step and its vision calls are billed. Skipped for plaintext."),
-    figureInstructions: string2().optional().describe('Custom instruction for the figure-description pass, e.g. "Describe each figure; label a handwritten signature as `<figure>signature</figure>` and a stamp as `<figure>stamp</figure>`; for property photos note the room or exterior shown." Applied only when describeFigures runs.')
+    figureInstructions: string2().optional().describe('Custom instruction for the figure-description pass, e.g. "Describe each figure; label a handwritten signature as `<figure>signature</figure>` and a stamp as `<figure>stamp</figure>`; for property photos note the room or exterior shown." Applied only when describeFigures runs.'),
+    cache: boolean2().default(false).optional().describe("When true, reuse a prior parse for identical file bytes and parse settings. Skips OCR/vision on cache hit. Stored in tenant blob storage with no automatic expiry (TTL/lifecycle is a follow-up). Default off.")
   }).superRefine(refineNativeParseModeConflicts).superRefine(refineLayoutOutputFormat);
   AiParseOutputSchema = ParseResultSchema.omit({ rawResponse: true });
+  AiFigureCropsConfigSchema = object({
+    input: string2().describe("Storage reference or template expression for the source PDF"),
+    parseOutput: unknown().describe("ai.parse output object (template {{steps.<parse>.output}}); figure elements are read from its `elements` array"),
+    model: string2().optional().describe("Vision model for captions (defaults to workspace model)"),
+    figureInstructions: string2().optional().describe("Custom caption instruction; applied per figure crop"),
+    maxFigures: number2().int().min(1).max(100).default(40).optional().describe("Cap on figures processed per document"),
+    minAreaFrac: number2().min(0).max(1).default(0).optional().describe("Skip figures below this page-area fraction (logos/decorations)"),
+    includeCrops: boolean2().default(false).optional().describe("Include base64 JPEG crops in output (heavy; default off — captions + bboxes only)"),
+    renderScale: number2().min(1).max(4).default(1).optional().describe("Scale factor for rendering PDF pages before cropping"),
+    imageQuality: number2().int().min(1).max(100).default(85).optional().describe("JPEG quality for crops"),
+    llmReasoningEffort: OptionalReasoningEffortSchema
+  });
+  AiFigureCropsFigureSchema = object({
+    id: string2(),
+    page: number2(),
+    bboxNorm: tuple([number2(), number2(), number2(), number2()]).nullable(),
+    areaFrac: number2(),
+    caption: string2().nullable(),
+    cropJpegBase64: string2().optional()
+  });
+  AiFigureCropsOutputSchema = object({
+    figures: array(AiFigureCropsFigureSchema),
+    _figureCrops: object({
+      pages: array(number2()),
+      model: string2().optional(),
+      skippedSmall: number2()
+    })
+  });
   AiExtractConfigSchema = object({
     input: string2().describe("Text content or template expression"),
     schema: object({
@@ -54190,6 +54225,55 @@ var init_step_configs = __esm(() => {
     wordCount: number2().describe("Number of words embedded"),
     text: string2().describe("Extracted text from the document")
   });
+  CropRegionBboxSchema = tuple([
+    number2().min(0).max(1),
+    number2().min(0).max(1),
+    number2().min(0).max(1),
+    number2().min(0).max(1)
+  ]);
+  CropRegionSpecSchema = object({
+    id: string2().optional().describe("Stable region id used in output and crop filenames (defaults to region-N)"),
+    pageIndex: number2().int().min(0).default(0).optional().describe("0-based page index to crop from (images use page 0)"),
+    bbox: CropRegionBboxSchema.describe("Normalized axis-aligned bbox [x0, y0, x1, y1]")
+  });
+  CropRegionSpecListSchema = array(CropRegionSpecSchema).min(1).describe("Regions to crop from the rendered document");
+  CropRegionSpecListResolvedSchema = array(CropRegionSpecSchema).describe("Regions to crop from the rendered document (may be empty)");
+  TransformCropRegionsConfigSchema = object({
+    input: string2().describe("File input — template expression e.g. {{ input.document }} resolving to a PDF or image"),
+    regions: union([
+      string2().min(1).describe("Template expression resolving to a region array, e.g. {{ steps.list-figures.output.regions }}"),
+      CropRegionSpecListSchema
+    ]).describe("Regions to crop — pageIndex + normalized bbox per entry"),
+    renderScale: number2().min(0.5).max(4).default(1).optional().describe("Scale factor when rasterizing PDF pages before cropping"),
+    imageQuality: number2().int().min(1).max(100).default(85).optional().describe("JPEG quality for cropped outputs"),
+    paddingFrac: number2().min(0).max(0.2).default(0.02).optional().describe("Padding around each bbox as a fraction of the shorter page edge"),
+    minCropPx: number2().int().min(1).default(8).optional().describe("Minimum crop width/height in pixels; smaller crops fall back to the full page"),
+    maxRegions: number2().int().min(1).max(200).default(100).optional().describe("Maximum regions processed per invocation")
+  });
+  TransformCropRegionsCropSchema = object({
+    id: string2().describe("Region id (from input or auto-generated)"),
+    pageIndex: number2().int().min(0).describe("0-based page index the crop was taken from"),
+    bbox: CropRegionBboxSchema.describe("Normalized bbox that was cropped"),
+    width: number2().int().min(1).describe("Crop width in pixels"),
+    height: number2().int().min(1).describe("Crop height in pixels"),
+    fileId: string2().describe("Run output file id for the JPEG crop"),
+    filename: string2().describe("Stored crop filename"),
+    mimeType: literal("image/jpeg").describe("Always image/jpeg"),
+    size: number2().int().min(0).describe("JPEG size in bytes")
+  });
+  TransformCropRegionsOutputSchema = object({
+    regions: array(TransformCropRegionsCropSchema).describe("Successfully cropped regions"),
+    skipped: number2().int().min(0).optional().describe("Regions skipped (invalid bbox or missing page)")
+  });
+  CropRegionsProcessorConfigSchema = TransformCropRegionsConfigSchema.omit({
+    input: true,
+    regions: true
+  }).extend({
+    regions: union([
+      string2().min(1).describe("Template expression resolving to a region array, e.g. {{ steps.list-figures.output.regions }}"),
+      CropRegionSpecListResolvedSchema
+    ]).describe("Regions to crop — may be empty when upstream scripts find no figures")
+  });
   TransformXlsxToJsonConfigSchema = object({
     input: string2().min(1, "Input is required").describe("File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime")
   }).extend(XlsxToJsonConfigSchema.shape).extend({
@@ -54596,6 +54680,15 @@ var init_step_configs = __esm(() => {
       outputSchema: AiSearchFilesOutputSchema,
       configInWith: true
     },
+    "ai.figure-crops": {
+      type: "ai.figure-crops",
+      category: "ai",
+      name: "Figure Crops",
+      description: "Crop and caption figure elements from a parsed PDF. Renders the source document, crops each kind=figure bbox from ai.parse output, and describes the crop with a vision model. Output is captions plus normalized bboxes for evidence viewers.",
+      configSchema: AiFigureCropsConfigSchema,
+      outputSchema: AiFigureCropsOutputSchema,
+      configInWith: true
+    },
     "transform.set": {
       type: "transform.set",
       category: "transform",
@@ -54659,6 +54752,15 @@ var init_step_configs = __esm(() => {
       outputSchema: TransformPdfEmbedOutputSchema,
       configInWith: true
     },
+    "transform.crop-regions": {
+      type: "transform.crop-regions",
+      category: "transform",
+      name: "Crop Regions",
+      description: "Render a PDF or image and crop normalized bounding boxes into JPEG run output artifacts. Pair with transform.script (bbox lists from ai.parse layout) and ai.extract or ai.vision for captions.",
+      configSchema: TransformCropRegionsConfigSchema,
+      outputSchema: TransformCropRegionsOutputSchema,
+      configInWith: true
+    },
     "transform.xlsx-to-json": {
       type: "transform.xlsx-to-json",
       category: "transform",
@@ -206278,7 +206380,7 @@ import { fileURLToPath as fileURLToPath8 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.17.4",
+  version: "0.18.0",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",