@claritylabs/cl-sdk 1.1.0 → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 # CL-SDK
 
-Deterministic insurance intelligence primitives for regulated AI agents. Pure TypeScript, provider-agnostic — bring any LLM, any embedding model, any storage backend.
+Deterministic insurance intelligence primitives for regulated AI agents.
 
 **[Documentation](https://cl-sdk.claritylabs.inc/docs)** | **[npm](https://www.npmjs.com/package/@claritylabs/cl-sdk)** | **[GitHub](https://github.com/claritylabs-inc/cl-sdk)**
 
@@ -12,7 +12,7 @@ npm install @claritylabs/cl-sdk pdf-lib zod
 
 ## What It Does
 
-- **Document Extraction** — Deterministic extraction pipeline with focused model calls that turns insurance PDFs into structured data with page-level provenance, quality gates, first-class definitions and covered reasons, referential coverage resolution, cost-aware formatting, and automatic declarations-to-schema promotion (limits, deductibles, locations, broker, loss payees, premium, taxes/fees, summary)
+- **Document Extraction** — Deterministic extraction pipeline with focused model calls that turns insurance PDFs or host-provided Docling documents into structured data with page-level provenance, quality gates, first-class definitions and covered reasons, referential coverage resolution, cost-aware formatting, and automatic declarations-to-schema promotion (limits, deductibles, locations, broker, loss payees, premium, taxes/fees, summary)
 - **Source Grounding** — Shared source spans, source chunks, source stores, quoted evidence validation, and deterministic evidence ordering across extraction, query, application, PCE, and case workflows
 - **Query Agent** — Citation-backed question answering over stored documents, source spans, and inbound photos/PDFs/text with sub-question decomposition, bounded retrieval planning, attachment-only reasoning when retrieval is unnecessary, and grounding verification
 - **Application Processing** — Bounded workflows handle intake with deterministic planning — field extraction, prior-answer backfill, context auto-fill, document lookup gating, topic-based question batching, reply parsing, source-backed field provenance, and PDF mapping
@@ -50,6 +50,18 @@ console.log(result.sourceSpans);  // SourceSpan[] when supplied by the host
 console.log(result.reviewReport); // Quality gate results
 ```
 
+### Optional Docling input
+
+If your host pre-processes a PDF with [Docling](https://github.com/docling-project/docling), pass the serialized `DoclingDocument` JSON instead of a PDF. CL-SDK does not install or run Python Docling; it consumes the parsed document, builds source spans, and runs the same focused structuring pipeline over Docling page text.
+
+```typescript
+const result = await extractor.extract({
+  kind: "docling_document",
+  document: doclingDocumentJson,
+  sourceKind: "policy_pdf",
+}, "policy-123");
+```
+
 ## Source Grounding
 
 Source spans are the v1 evidence layer. Build spans from PDF text, OCR, emails, attachments, or structured fields, then pass them into extraction and downstream workflows:
@@ -68,6 +80,8 @@ const extractor = createExtractor({ generateText, generateObject, sourceStore })
 const result = await extractor.extract(pdfBase64, "policy-123", { sourceSpans });
 ```
 
+When source spans are available, section and endorsement extraction returns a compact index with page ranges, short excerpts, and `sourceSpanIds`/`sourceTextHash` instead of asking the model to reproduce full policy wording. Store `result.sourceSpans`/source chunks as the canonical evidence corpus for Q&A and source viewers; use `result.chunks` for structured facts and navigation metadata.
+
 See the [full documentation](https://cl-sdk.claritylabs.inc/docs) for architecture, provider setup, API reference, and more.
 
 ## Multimodal Querying
@@ -116,13 +130,14 @@ Important: your `generateObject` callback must actually forward multimodal paylo
 - `providerOptions.attachments` for generic image/pdf/text inputs
 - `providerOptions.pdfBase64` for PDF inputs
 - `providerOptions.images` for image inputs
+- `providerOptions.doclingText` for host-provided Docling document inputs
 - `providerOptions.sourceSpans` and `providerOptions.sourceChunks` for source evidence when your host passes them through
 
 If your callback ignores those fields, the model will only see the text prompt.
 
 ## Model routing metadata
 
-Every SDK model callback may receive `taskKind` and `budgetDiagnostics`. Hosts can use these provider-agnostic fields for cheap-first routing, fallback, and telemetry without the SDK hardcoding model names. Example task kinds include `extraction_classify`, `extraction_focused`, `extraction_review`, `query_reason`, `application_extract_fields`, and `pce_impact_analysis`. `budgetDiagnostics` includes the resolved max-token budget and truncation-risk warnings for the current subtask.
+Every SDK model callback may receive `taskKind`, `budgetDiagnostics`, and `trace`. Hosts can use these provider-agnostic fields for cheap-first routing, fallback, and telemetry without the SDK hardcoding model names. Example task kinds include `extraction_classify`, `extraction_focused`, `extraction_review`, `query_reason`, `application_extract_fields`, and `pce_impact_analysis`. `budgetDiagnostics` includes the resolved max-token budget and truncation-risk warnings for the current subtask. `trace` identifies the current extractor, page range, format batch, or source-backed call so host logs can show what was being generated instead of a generic model-call label.
 
 ## Bounded Agentic Workflows