> ## Documentation Index
> Fetch the complete documentation index at: https://claritylabs.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CL SDK TypeScript Type and Interface Reference Guide

> TypeScript type and interface reference for CL SDK, covering provider callbacks, extraction, documents, source grounding, storage, agents, and PCE.

All types below are exported from `@claritylabs/cl-sdk` unless otherwise noted. Import them as named type imports to avoid bundling issues.

```typescript theme={"system"}
import type { SourceSpan, AgentContext, ExtractionResult } from "@claritylabs/cl-sdk";
```

***

## Provider Callback Types

These types define the function signatures your application must implement and pass to CL SDK factory functions. CL SDK is provider-agnostic — you supply the LLM and embedding calls.

**GenerateText** `(params: GenerateTextParams) =\> Promise\<GenerateTextResult\>`

Calls your LLM provider to generate a text completion. Used by query agents, application pipeline, and classification prompts.

**GenerateObject\<T>** `(params: GenerateObjectParams\<T\>) =\> Promise\<\{ object: T \}\>`

Calls your LLM provider to generate a structured JSON object conforming to schema `T`. Used by the extractor, PCE agent, and all structured output steps.

**EmbedText** `(text: string) =\> Promise\<number[]\>`

Calls your embedding provider to produce a vector representation of a text string. Required by `createSqliteStore` and any `SourceStore` that uses vector search.

**TokenUsage** `\{ inputTokens: number; outputTokens: number \}`

Reported by the `onTokenUsage` callback passed to factory functions. Track costs per extraction or query call.

**LogFn** `(message: string) =\> Promise\<void\>`

Optional async logging callback accepted by factory functions. Wire it to your application logger.

***

## Core Extraction Types

**ExtractorConfig** `object`

Configuration passed to `createExtractor`. Includes `generateObject` (required), `sourceStore` (optional), `concurrency`, `onTokenUsage`, and `onProgress`.

**ExtractionInput** `string | URL | Uint8Array | \{ fileId: string \} | \{ kind: 'docling_document'; document: DoclingDocument; sourceKind?: string \}`

Union type for all accepted extraction inputs. Strings are treated as base64-encoded PDFs.

**ExtractOptions** `object`

Options passed to `extractor.extract()`. Includes `sourceSpans`, `documentId`, and `coverageRecovery`.

**ExtractionResult** `object`

The output of a successful extraction. Includes the extracted `InsuranceDocument` (compatibility projection), `sourceSpans`, `sourceChunks`, `sourceTree` (canonical source hierarchy), `operationalProfile`, optional `coverageRecovery` diagnostics, `tokenUsage`, `performanceReport`, and `reviewReport`.

**PolicyOperationalProfile** `object`

A source-backed projection of product-critical facts: `documentType`, `linesOfBusiness` (ACORD codes), `policyNumber`, `namedInsured`, `insurer`, `broker`, `effectiveDate`, `expirationDate`, `retroactiveDate`, `premium`, `operationsDescription`, `declarationFacts`, `coverages`, `coverageSchedules`, `premiumBreakdown`, `taxesAndFees`, `totalCost`, `parties`, and `endorsementSupport`. Every value field is a `SourceBackedValue`.

**SourceBackedValue** `\{ value: string; normalizedValue?: string; confidence?: 'low' | 'medium' | 'high'; sourceNodeIds: string[]; sourceSpanIds: string[] \}`

A wrapper type that pairs an extracted value with its source span and node IDs. `normalizedValue` holds the display-safe canonical form for identity fields such as named insured, insurer, and policy number.

***

## Document Types

**InsuranceDocument** `PolicyDocument | QuoteDocument`

Top-level union type for all extracted documents. Discriminated by the `type` field: `"policy"` or `"quote"`.

**PolicyDocument** `object`

A bound insurance policy. Includes `id`, `type: 'policy'`, `metadata`, `coverages`, `endorsements`, `exclusions`, `conditions`, and `operationalProfile`.

**QuoteDocument** `object`

An insurance quote. Includes `id`, `type: 'quote'`, `metadata`, `coverages`, and `operationalProfile`. Quote documents may have incomplete coverage details.

**Coverage** `object`

Represents a single coverage line. Includes `type` (ACORD LOB code), `limit`, `deductible`, `retention`, `description`, and `sourceSpanId`.

**DocumentMetadata** `object`

Common metadata fields: `carrier`, `insuredName`, `policyNumber`, `quoteNumber`, `effectiveDate`, `expirationDate`, `formNumbers`, and `namedInsureds`.

**DocumentNode** `object`

A node in the document's structural hierarchy (form, endorsement, section, schedule). Used by the parser-grounded source node tree.

***

## Source Grounding Types

**SourceSpan** `object`

The smallest addressable source unit. Fields: `id`, `documentId`, `sourceKind`, `kind`, `text`, `hash`, `pageStart`, `pageEnd`, `sectionId`, `formNumber`, `sourceUnit`, `parentSpanId`, `table`, `location`, `metadata`. See the [Source Spans](https://claritylabs.inc/docs/cl-sdk/source-grounding/source-spans.md) page for the full schema.

**SourceChunk** `object`

A retrieval window produced by `chunkSourceSpans`. Fields: `id`, `documentId`, `text`, `spanIds` (source span IDs included in this chunk), `pageStart`, `pageEnd`.

**DocumentSourceNode** `object`

A node in the parser-grounded document hierarchy. Fields: `id`, `documentId`, `parentId`, `kind`, `title`, `description`, `textExcerpt`, `sourceSpanIds`, `pageStart`, `pageEnd`, `bbox`, `order`, `path`, `metadata`.

**DocumentSourceNodeKind** `string enum`

One of: `"document"` | `"page_group"` | `"page"` | `"form"` | `"endorsement"` | `"section"` | `"schedule"` | `"clause"` | `"table"` | `"table_row"` | `"table_cell"` | `"text"`

***

## Storage Interfaces

**DocumentStore** `interface`

`save`, `get`, `query`, `delete`. See [Storage Overview](https://claritylabs.inc/docs/cl-sdk/storage/overview.md) for the full interface.

**MemoryStore** `interface`

`addChunks`, `search`, `addTurn`, `getHistory`, `searchHistory`. Handles document chunks and conversation history.

**SourceStore** `interface extends SourceRetriever`

`addSourceSpans`, `addSourceChunks`, `getSourceSpan`, `getSourceSpansByDocument`, `getSourceChunksByDocument`, `deleteDocumentSource`, plus all `SourceRetriever` methods.

**DocumentChunk** `object`

A chunk of document text stored in `MemoryStore`. Fields: `id`, `documentId`, `text`, `pageStart`, `pageEnd`, `metadata`.

**ConversationTurn** `object`

A single conversational exchange stored in `MemoryStore`. Fields: `id`, `conversationId`, `role` (`"user"` | `"assistant"` | `"tool"`), `content`, `toolName`, `toolResult`, `timestamp`.

***

## Agent Types

**AgentContext** `object`

Configuration for `buildAgentSystemPrompt`. See the [System Prompt](https://claritylabs.inc/docs/cl-sdk/agent/system-prompt.md) page for all fields.

**Platform** `string enum`

`"email"` | `"chat"` | `"sms"` | `"slack"` | `"discord"`

**CommunicationIntent** `string enum`

`"direct"` | `"mediated"` | `"observed"`

**ToolDefinition** `object`

Schema-only tool definition compatible with Claude `tool_use`. Fields: `name`, `description`, `input_schema` (`{ type: "object", properties, required? }`).

***

## PCE Types

**PceCaseState** `object`

Mutable state object managed by `createPceAgent`. Holds the list of `PolicyChangeItem` objects, retrieval evidence, validation issues, and the current execution phase.

**PolicyChangeItem** `object`

A single endorsed change: `id`, `changeType`, `description`, `evidence` (`PceEvidenceSource[]`), `validationIssues`, and `confidence`.

**PceSubmissionPacket** `object`

The final output of a PCE workflow. Fields: `caseId`, `createdAt`, `changeItems`, `evidenceSources`, `qualityReport`, and `submissionNarrative`.

**PceExecutionMode** `string enum`

`"auto"` | `"deterministic_tree"` | `"market_eval"` | `"hybrid"`

***

## Case Types

**CaseValidationIssue** `object`

A validation issue produced by `validatePceItems` or `validateQuotedEvidence`. Fields: `severity` (`"error"` | `"warning"` | `"info"`), `code`, `message`, `spanId`, `itemId`.

**CaseCitation** `object`

A quoted citation linking a case finding to a source span. Fields: `spanId`, `quote`, `pageStart`, `pageEnd`, `sectionId`.

**MissingInfoQuestion** `object`

A question generated when required information is absent from the source evidence. Fields: `id`, `question`, `context`, `requiredFor`, `priority`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.