@claritylabs/cl-sdk 0.7.5 → 0.8.1

package/README.md

@@ -31,14 +31,22 @@ CL-SDK extracts structured data from insurance PDFs using a multi-agent pipeline
 import { createExtractor } from "@claritylabs/cl-sdk";
 
 const extractor = createExtractor({
-  generateText: async ({ prompt, system, maxTokens }) => {
+  generateText: async ({ prompt, system, maxTokens, providerOptions }) => {
     // Wrap your preferred LLM provider
-    const result = await yourProvider.generate({ prompt, system, maxTokens });
+    const result = await yourProvider.generate({ prompt, system, maxTokens, providerOptions });
     return { text: result.text, usage: result.usage };
   },
-  generateObject: async ({ prompt, system, schema, maxTokens }) => {
+  generateObject: async ({ prompt, system, schema, maxTokens, providerOptions }) => {
     // schema is a Zod schema — use it for structured output
-    const result = await yourProvider.generateStructured({ prompt, system, schema, maxTokens });
+    // IMPORTANT: pass providerOptions.pdfBase64 and/or providerOptions.images
+    // through to your model as file/image message parts.
+    const result = await yourProvider.generateStructured({
+      prompt,
+      system,
+      schema,
+      maxTokens,
+      providerOptions,
+    });
     return { object: result.object, usage: result.usage };
   },
 });
@@ -87,6 +95,13 @@ type GenerateObject<T> = (params: {
 }) => Promise<{ object: T; usage?: { inputTokens: number; outputTokens: number } }>;
 ```
 
+For extraction calls, `providerOptions` can carry document content:
+
+- `providerOptions.pdfBase64` — the PDF to send as a file part
+- `providerOptions.images` — page images to send as image parts
+
+The coordinator passes the full PDF to classify and plan. Worker extractors pass a page-scoped PDF produced by `extractPageRange()` unless `convertPdfToImages` is enabled, in which case they pass page images instead. Your callback must include that content in the actual model request; the prompt text alone is not sufficient.
+
 Works with any provider: Anthropic, OpenAI, Google, Mistral, Bedrock, Azure, Ollama, etc. You write the adapter once; the SDK calls it throughout the pipeline.
 
 > **Strict structured output compatibility:** The SDK automatically transforms Zod schemas before passing them to `generateObject` — converting `.optional()` fields to `.nullable()` so all properties appear in the JSON Schema `required` array. This ensures compatibility with providers like OpenAI that enforce strict structured output validation. No adapter changes needed on your end.
@@ -131,10 +146,14 @@ The coordinator sends the document to `generateObject` with the `ClassifyResultS
 - **Policy types** — one or more lines of business (e.g., `general_liability`, `workers_comp`)
 - **Confidence score**
 
+The full document is passed through `providerOptions.pdfBase64` for this step, so your callback must attach that PDF to the model request as a real document/file part.
+
 #### Phase 2: Plan
 
 Based on the classification, the coordinator selects a **line-of-business template** (e.g., `workers_comp`, `cyber`, `homeowners_ho3`) that defines expected sections and page hints. It then generates an **extraction plan** — a list of tasks that map specific extractors to page ranges within the PDF.
 
+The planner also receives the full document through `providerOptions.pdfBase64`, not just prompt text.
+
 #### Phase 3: Extract
 
 Focused extractor agents are dispatched **in parallel** (concurrency-limited, default 2). Each extractor targets a specific data domain against its assigned page range. The 11 extractor types are:
@@ -155,6 +174,8 @@ Focused extractor agents are dispatched **in parallel** (concurrency-limited, de
 
 Each extractor writes its results to an in-memory `Map`. Results accumulate across all extractors.
 
+Before each worker call, the SDK slices the requested page range with `extractPageRange()` and passes that page-scoped PDF through `providerOptions.pdfBase64`. If `convertPdfToImages` is configured, it passes `providerOptions.images` instead. The callback layer is responsible for actually including that content in the model input.
+
 #### Phase 4: Review
 
 After initial extraction, a review loop (up to `maxReviewRounds`, default 2) checks completeness against the template's expected sections. If gaps are found, additional extractor tasks are dispatched to fill missing data. This iterative refinement ensures comprehensive extraction.

package/dist/index.d.mts

@@ -12,7 +12,16 @@ type GenerateText = (params: {
     text: string;
     usage?: TokenUsage;
 }>;
-/** Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic. */
+/**
+ * Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic.
+ *
+ * The extraction pipeline passes document content via `providerOptions`:
+ * - `providerOptions.pdfBase64` — base64-encoded PDF to include as document context
+ * - `providerOptions.images` — `Array<{ imageBase64: string; mimeType: string }>` page images
+ *
+ * Your callback should check for these fields and include them as multi-part
+ * message content (e.g. file/image parts) when calling your AI provider.
+ */
 type GenerateObject<T = unknown> = (params: {
     prompt: string;
     system?: string;

package/dist/index.d.ts

@@ -12,7 +12,16 @@ type GenerateText = (params: {
     text: string;
     usage?: TokenUsage;
 }>;
-/** Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic. */
+/**
+ * Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic.
+ *
+ * The extraction pipeline passes document content via `providerOptions`:
+ * - `providerOptions.pdfBase64` — base64-encoded PDF to include as document context
+ * - `providerOptions.images` — `Array<{ imageBase64: string; mimeType: string }>` page images
+ *
+ * Your callback should check for these fields and include them as multi-part
+ * message content (e.g. file/image parts) when calling your AI provider.
+ */
 type GenerateObject<T = unknown> = (params: {
     prompt: string;
     system?: string;

package/dist/index.js

@@ -1758,19 +1758,28 @@ async function runExtractor(params) {
     maxTokens = 4096,
     providerOptions
   } = params;
-  const pagesPdf = await extractPageRange(pdfBase64, startPage, endPage);
-  const fullPrompt = convertPdfToImages ? `${prompt}
-
-[Document pages ${startPage}-${endPage} are provided as images above.]` : `${prompt}
+  const extractorProviderOptions = { ...providerOptions };
+  let fullPrompt;
+  if (convertPdfToImages) {
+    const images = await convertPdfToImages(pdfBase64, startPage, endPage);
+    extractorProviderOptions.images = images;
+    fullPrompt = `${prompt}
+
+[Document pages ${startPage}-${endPage} are provided as images.]`;
+  } else {
+    const pagesPdf = await extractPageRange(pdfBase64, startPage, endPage);
+    extractorProviderOptions.pdfBase64 = pagesPdf;
+    fullPrompt = `${prompt}
 
-[Document pages ${startPage}-${endPage} are provided as a PDF file above.]`;
+[Document pages ${startPage}-${endPage} are provided as a PDF file.]`;
+  }
   const strictSchema = toStrictSchema(schema);
   const result = await withRetry(
     () => generateObject({
       prompt: fullPrompt,
       schema: strictSchema,
       maxTokens,
-      providerOptions
+      providerOptions: extractorProviderOptions
     })
   );
   return {
@@ -3590,7 +3599,7 @@ function createExtractor(config) {
           prompt: buildClassifyPrompt(),
           schema: ClassifyResultSchema,
           maxTokens: 512,
-          providerOptions
+          providerOptions: { ...providerOptions, pdfBase64 }
         },
         {
           fallback: { documentType: "policy", policyTypes: ["other"], confidence: 0 },
@@ -3634,7 +3643,7 @@ function createExtractor(config) {
           prompt: buildPlanPrompt(templateHints),
           schema: ExtractionPlanSchema,
           maxTokens: 2048,
-          providerOptions
+          providerOptions: { ...providerOptions, pdfBase64 }
         },
         {
           fallback: {