llmbic 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-04-16
+
+Non-breaking. Unblocks hybrid workflows that rely on nested schemas, agreement/conflict detection, and extractor-level merge options.
+
+### Added
+
+- `prompt.build` now supports `z.array(...)`, `z.object(...)`, `z.optional(...)` and `z.default(...)` in the response JSON Schema. Optional fields are preserved in `properties` but excluded from `required`.
+- Cross-check mode on `prompt.build` and `ExtractorLlmConfig`: `mode: 'cross-check'` asks the LLM about every schema field, not just `partial.missing`, enabling the per-field agreement / conflict machinery in `merge.apply`. `crossCheckHints: 'bias' | 'unbiased'` (default `unbiased`) controls whether rule values are surfaced to the LLM as hints.
+- `ExtractorConfig` now accepts `normalizers`, `validators`, `policy` and `logger` directly; previously these had to be threaded into a manual `merge.apply` call. The options are forwarded to every internal merge, so `extract`, `extractSync` and `extractor.merge` all honor them.
+- Zod `.describe("...")` (equivalent to `.meta({ description })`) is now propagated to the generated JSON Schema at the level it was declared; providers' structured-output features consume it natively, so per-field prompt guidance no longer requires an expanded system prompt.
+- README "Batch / async mode" section expanded with a worked OpenAI Batch API example (JSONL shape, upload / poll / download / merge), plus a full runnable script at `examples/openai-batch.ts`.
+
+### Fixed
+
+- Object schemas emitted by `prompt.build` now carry `additionalProperties: false`, matching the requirement of OpenAI Chat Completions Structured Outputs with `strict: true`. Other providers (Anthropic tool use, Ollama JSON Schema) ignore the extra key. Aligned with `prompt.parse` which already drops unexpected fields with a warning.
+- `createExtractor` was not forwarding the configured `logger` to `rule.apply`, so schema-rejection warnings from the rules pass were silently dropped. The logger is now plumbed through every phase.
+
+### Public types
+
+- `PromptBuildMode`, `CrossCheckHints`, `PromptBuildOptions` exported from the package root.
+- `ExtractorConfig<S>` gains optional `normalizers`, `validators`, `policy`, `logger`.
+- `ExtractorLlmConfig` gains optional `mode`, `crossCheckHints`.
+
 ## [1.0.0] — 2026-04-15
 
 Initial public release.

package/README.md

@@ -29,7 +29,7 @@ Llmbic has a single dependency: [Zod](https://zod.dev). No vendor SDK is pulled
 
 ```typescript
 import { z } from 'zod';
-import { createExtractor, rule, confidence } from 'llmbic';
+import { createExtractor, rule } from 'llmbic';
 
 const InvoiceSchema = z.object({
   total: z.number().nullable(),
@@ -41,14 +41,14 @@ const InvoiceSchema = z.object({
 const extractor = createExtractor({
   schema: InvoiceSchema,
   rules: [
-    rule('total', (text) => {
+    rule.create('total', (text) => {
       const m = text.match(/Total[:\s]*(\d[\d.,\s]+)\s*€/i);
       if (!m) return null;
-      return confidence(parseFloat(m[1].replace(/[\s.]/g, '').replace(',', '.')), 1.0);
+      return rule.confidence(parseFloat(m[1].replace(/[\s.]/g, '').replace(',', '.')), 1.0);
     }),
-    rule('currency', (text) => {
-      if (/€|EUR/i.test(text)) return confidence('EUR', 1.0);
-      if (/\$|USD/i.test(text)) return confidence('USD', 1.0);
+    rule.create('currency', (text) => {
+      if (/€|EUR/i.test(text)) return rule.confidence('EUR', 1.0);
+      if (/\$|USD/i.test(text)) return rule.confidence('USD', 1.0);
       return null;
     }),
   ],
@@ -69,7 +69,7 @@ console.log(result.missing);
 ### Rules + LLM
 
 ```typescript
-import { createExtractor, rule, confidence } from 'llmbic';
+import { createExtractor, rule } from 'llmbic';
 import type { LlmProvider } from 'llmbic';
 import OpenAI from 'openai';
 
@@ -135,6 +135,48 @@ const llmResult = extractor.parse(rawJsonResponse);
 const result = extractor.merge(partial, llmResult, markdown);
 ```
 
+Steps 1, 2 and 4 are pure and synchronous: persist `partial` between (2) and (4); the merge re-runs the rules internally so no private state leaks across the async gap.
+
+#### Worked example: OpenAI Batch API
+
+The Batch API expects a JSONL file where each line is a Chat Completions request. Using `extractor.prompt(...)` as the per-document payload builder maps 1:1 onto that format:
+
+```typescript
+// For each document, build one JSONL line:
+const partial = extractor.extractSync(doc.markdown);
+const request = extractor.prompt(doc.markdown, partial);
+
+const line = JSON.stringify({
+  custom_id: doc.id,                         // how you'll re-match later
+  method: 'POST',
+  url: '/v1/chat/completions',
+  body: {
+    model: 'gpt-4o-mini',
+    messages: [
+      { role: 'system', content: request.systemPrompt },
+      { role: 'user',   content: request.userContent },
+    ],
+    response_format: {
+      type: 'json_schema',
+      json_schema: { name: 'extraction', strict: true, schema: request.responseSchema },
+    },
+  },
+});
+```
+
+Upload the JSONL, create the batch, poll until `status === 'completed'`, download the output file. Each output line carries the same `custom_id` so you can map back to the `partial` you kept in memory (or in Redis, or on disk):
+
+```typescript
+for (const entry of prepared) {
+  const raw = responsesById.get(entry.id);           // from output JSONL
+  const llmResult = extractor.parse(raw);
+  const result = extractor.merge(entry.partial, llmResult, entry.markdown);
+  // ... persist result ...
+}
+```
+
+End-to-end runnable example (upload + poll + download + merge): [`examples/openai-batch.ts`](./examples/openai-batch.ts). At current OpenAI pricing the Batch API is ~50% cheaper than realtime Chat Completions, with a 24h completion window.
+
 ## Features
 
 ### Per-field confidence scoring
@@ -161,6 +203,35 @@ result.conflicts;
 
 Three conflict strategies: `'flag'` (default — keep rule value, record conflict), `'prefer-rule'`, or `'prefer-llm'`.
 
+In the default `'fill-gaps'` mode the LLM is only asked about fields the rules could not resolve, so conflicts are impossible. To actually trigger conflict detection, opt into cross-check (see below).
+
+### Cross-check mode
+
+Switch the LLM call from fill-gaps (ask only about missing fields) to cross-check (ask about every schema field, whether the rules resolved it or not):
+
+```typescript
+const extractor = createExtractor({
+  schema: InvoiceSchema,
+  rules: [...],
+  llm: {
+    provider,
+    mode: 'cross-check',
+    crossCheckHints: 'unbiased', // default; hides rule values from the LLM
+  },
+});
+```
+
+The merge step now sees two candidates per field and surfaces real disagreements through `result.conflicts`. `crossCheckHints: 'bias'` re-exposes the rule values as hints to save tokens, at the cost of confirmation bias (the LLM tends to agree with what it was shown).
+
+### Rich schemas
+
+The JSON Schema handed to the LLM supports the Zod constructs that show up in real-world extraction targets:
+
+- Primitives: `z.string()`, `z.number()`, `z.boolean()`, `z.enum([...])`.
+- Composition: `z.array(...)`, `z.object({...})`, nested arbitrarily.
+- Wrappers: `.nullable()`, `.optional()`, `.default(...)`.
+- Descriptions: `z.string().describe("price in EUR, tax included")` propagates to the JSON Schema `description` at the declared level (array root vs items, object root vs property), and providers' structured-output features consume it natively. No need to inflate the system prompt with per-field hints.
+
 ### Normalizers
 
 Post-merge transformations. Run in sequence, receive the merged data + original content:
@@ -184,9 +255,9 @@ const extractor = createExtractor({
 Check the final output for logical consistency:
 
 ```typescript
-import { validators } from 'llmbic';
+import { validator } from 'llmbic';
 
-const { field, crossField } = validators<MySchemaShape>();
+const { field, crossField } = validator.of<MySchemaShape>();
 
 const extractor = createExtractor({
   schema: MySchema,
@@ -227,7 +298,7 @@ const provider: LlmProvider = {
 
 Ready-made snippets for common backends:
 
-**OpenAI** (Chat Completions + Structured Outputs):
+**OpenAI** (Chat Completions + Structured Outputs). The response schema llmbic emits always carries `additionalProperties: false`, so `strict: true` works out of the box:
 
 ```typescript
 const client = new OpenAI();
@@ -307,28 +378,38 @@ Creates an extractor instance. Config:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `schema` | `ZodObject` | yes | Output schema |
-| `rules` | `ExtractionRule[]` | yes | Deterministic extraction rules |
-| `llm` | `{ provider, systemPrompt, defaultConfidence? }` | no | LLM configuration. Omit for rules-only mode. |
-| `normalizers` | `Normalizer[]` | no | Post-merge transformations |
-| `validators` | `Validator[]` | no | Output invariants |
-| `conflictStrategy` | `'flag' \| 'prefer-rule' \| 'prefer-llm'` | no | Default: `'flag'` |
-| `logger` | `Logger` | no | Injectable logger (compatible with Pino, Winston, console) |
+| `schema` | `ZodObject` | yes | Output schema (drives field enumeration and re-validation). |
+| `rules` | `ExtractionRule[]` | yes | Deterministic extraction rules. |
+| `llm` | `ExtractorLlmConfig` | no | LLM fallback. Omit for rules-only mode. See below. |
+| `normalizers` | `Normalizer<T>[]` | no | Post-merge transformations, run in declared order. |
+| `validators` | `Validator<ExtractedData<T>>[]` | no | Invariants populating `result.validation`. |
+| `policy` | `Partial<FieldMergePolicy>` | no | Overrides the per-field merge policy (conflict strategy, confidence defaults, equality). |
+| `logger` | `Logger` | no | Pino/Winston/console-compatible. Warnings from `rule.apply` and `merge.apply` flow through. |
 
-### `rule(field, extractFn)`
+`ExtractorLlmConfig`:
 
-Factory to create an `ExtractionRule`.
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `provider` | `LlmProvider` | yes | Single-method adapter the extractor calls. |
+| `systemPrompt` | `string` | no | Overrides the built-in system prompt. |
+| `mode` | `'fill-gaps' \| 'cross-check'` | no | `'fill-gaps'` (default) asks the LLM only about fields the rules did not resolve. `'cross-check'` asks about every schema field so `merge.apply` can surface agreements / conflicts. |
+| `crossCheckHints` | `'bias' \| 'unbiased'` | no | In cross-check mode only. `'unbiased'` (default) hides rule values from the LLM for genuine disagreement detection; `'bias'` re-exposes them to save tokens. |
 
-### `confidence(value, score)`
+### `rule` namespace
 
-Factory to create a `RuleMatch` with a confidence score.
+| Member | Signature | Description |
+|---|---|---|
+| `rule.create` | `(field, extract) => ExtractionRule` | Declare a rule. `extract(content)` returns a `RuleMatch` or `null`. |
+| `rule.regex` | `(field, pattern, score, transform?) => ExtractionRule` | Regex-based rule. On match, capture group 1 (or the full match) is fed to `transform`. |
+| `rule.confidence` | `(value, score) => RuleMatch` | Wrap a value and a confidence score; sugar for custom `extract` callbacks. |
+| `rule.apply` | `(content, rules, schema, logger?) => RulesResult` | Run every rule, pick the highest-confidence match per field, type-check against the schema. |
 
-### `validators<T>()`
+### `validator.of<T>()`
 
-Factory bound to the data shape `T`. Returns `{ field, crossField }`:
+Binds a target data shape `T` and returns two validator builders:
 
-- `field(name, rule, checkFn, message, severity?)` — single-field validator. `checkFn` receives the precise type of the field (`T[name]`).
-- `crossField(rule, checkFn, message, severity?)` — whole-object validator, produces a violation without a `field` property.
+- `field(name, ruleName, check, message, severity?)`: single-field validator. `check(value, data)` receives the precise type of the field (`T[name]`) as first argument.
+- `crossField(ruleName, check, message, severity?)`: whole-object validator, produces a violation without a `field` property.
 
 Binding `T` once lets TypeScript infer each field's type from the field name, so predicates are fully typed without manual annotations.
 
@@ -336,10 +417,10 @@ Binding `T` once lets TypeScript infer each field's type from the field name, so
 
 | Method | Sync | Description |
 |--------|------|-------------|
-| `extract(content)` | async | Full pipeline: rules → LLM → merge → validate |
-| `extractSync(content)` | sync | Rules only. Returns partial result + missing fields. |
-| `prompt(content, partial)` | sync | Builds LLM prompt for missing fields only. |
-| `parse(raw)` | sync | Parses raw LLM JSON response. |
+| `extract(content)` | async | Full pipeline: rules -> LLM (if configured) -> merge -> normalize -> validate. |
+| `extractSync(content)` | sync | Rules only. Returns the partial result + `missing` fields. |
+| `prompt(content, partial)` | sync | Builds the LLM request. Covers `partial.missing` in fill-gaps mode, every schema field in cross-check mode. |
+| `parse(raw)` | sync | Parses a raw LLM JSON response, validating each field individually. Never throws. |
 | `merge(partial, llmResult, content)` | sync | Merges rules + LLM, detects conflicts, normalizes, validates. |
 
 ## License

package/dist/extractor.d.ts

@@ -1,18 +1,24 @@
 import type { z } from 'zod';
 import type { Extractor, ExtractorConfig } from './types/extractor.types.js';
 /**
- * Bind a schema, deterministic rules and an optional LLM fallback into an
+ * Bind a schema, deterministic rules and their merge-time options into an
  * {@link Extractor}. The returned object exposes the extraction pipeline as
  * pre-configured methods; call sites stop having to thread `schema`,
- * `rules` and provider wiring through every step.
+ * `rules`, `policy`, normalizers/validators and provider wiring through
+ * every step.
  *
- * {@link Extractor.extract} runs {@link rule.apply}, then — when an LLM is
- * configured and some fields are still missing — asks the provider for those
- * fields only, parses the response with {@link prompt.parse} and fuses
- * everything through {@link merge.apply}.
+ * {@link Extractor.extract} runs {@link rule.apply}, then - when an LLM is
+ * configured - asks the provider either for the missing fields only
+ * (`mode: 'fill-gaps'`, default) or for every schema field
+ * (`mode: 'cross-check'`, which always triggers the LLM call so conflicts
+ * can be detected even when the rules resolved every field). The response
+ * is parsed with {@link prompt.parse} and fused through {@link merge.apply}.
  *
  * @typeParam S - A Zod object schema describing the target data shape.
- * @param config - Schema, deterministic rules, and optional LLM fallback.
+ * @param config - Schema, deterministic rules, and optional LLM fallback,
+ *   plus `policy`, `normalizers`, `validators` and `logger` forwarded to
+ *   every internal {@link merge.apply} call. The logger is also forwarded
+ *   to {@link rule.apply} so schema-rejection warnings stay visible.
  * @returns An {@link Extractor} bound to `config.schema`.
  */
 export declare function createExtractor<S extends z.ZodObject<z.ZodRawShape>>(config: ExtractorConfig<S>): Extractor<z.infer<S>>;

package/dist/extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AA8C7E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAClE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAuDvB"}
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AA8C7E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAClE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAqEvB"}

package/dist/extractor.js

@@ -36,18 +36,24 @@ function stampDuration(result, startedAt) {
     };
 }
 /**
- * Bind a schema, deterministic rules and an optional LLM fallback into an
+ * Bind a schema, deterministic rules and their merge-time options into an
  * {@link Extractor}. The returned object exposes the extraction pipeline as
  * pre-configured methods; call sites stop having to thread `schema`,
- * `rules` and provider wiring through every step.
+ * `rules`, `policy`, normalizers/validators and provider wiring through
+ * every step.
  *
- * {@link Extractor.extract} runs {@link rule.apply}, then — when an LLM is
- * configured and some fields are still missing — asks the provider for those
- * fields only, parses the response with {@link prompt.parse} and fuses
- * everything through {@link merge.apply}.
+ * {@link Extractor.extract} runs {@link rule.apply}, then - when an LLM is
+ * configured - asks the provider either for the missing fields only
+ * (`mode: 'fill-gaps'`, default) or for every schema field
+ * (`mode: 'cross-check'`, which always triggers the LLM call so conflicts
+ * can be detected even when the rules resolved every field). The response
+ * is parsed with {@link prompt.parse} and fused through {@link merge.apply}.
  *
  * @typeParam S - A Zod object schema describing the target data shape.
- * @param config - Schema, deterministic rules, and optional LLM fallback.
+ * @param config - Schema, deterministic rules, and optional LLM fallback,
+ *   plus `policy`, `normalizers`, `validators` and `logger` forwarded to
+ *   every internal {@link merge.apply} call. The logger is also forwarded
+ *   to {@link rule.apply} so schema-rejection warnings stay visible.
  * @returns An {@link Extractor} bound to `config.schema`.
  */
 export function createExtractor(config) {
@@ -55,32 +61,42 @@ export function createExtractor(config) {
     if (allFields.length === 0) {
         throw new Error('createExtractor: schema must declare at least one field');
     }
+    const buildOptions = {
+        systemPrompt: config.llm?.systemPrompt,
+        mode: config.llm?.mode ?? 'fill-gaps',
+        crossCheckHints: config.llm?.crossCheckHints ?? 'unbiased',
+    };
+    const mergeOptions = {
+        policy: config.policy,
+        normalizers: config.normalizers,
+        validators: config.validators,
+        logger: config.logger,
+    };
     return {
         async extract(content) {
             const startedAt = performance.now();
-            const rulesResult = rule.apply(content, config.rules, config.schema);
-            const partial = merge.apply(config.schema, rulesResult, null, content);
-            if (!config.llm || partial.missing.length === 0) {
+            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger);
+            const partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions);
+            const shouldCallLlm = config.llm !== undefined &&
+                (buildOptions.mode === 'cross-check' || partial.missing.length > 0);
+            if (!shouldCallLlm) {
                 return stampDuration(partial, startedAt);
             }
-            const request = prompt.build(config.schema, partial, content, {
-                systemPrompt: config.llm.systemPrompt,
-            });
+            const request = prompt.build(config.schema, partial, content, buildOptions);
             const completion = await config.llm.provider.complete(request);
-            const llmResult = prompt.parse(config.schema, partial.missing, completion.values);
-            const final = merge.apply(config.schema, rulesResult, llmResult, content);
+            const llmTargetFields = buildOptions.mode === 'cross-check' ? allFields : partial.missing;
+            const llmResult = prompt.parse(config.schema, llmTargetFields, completion.values);
+            const final = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions);
             return stampDuration(final, startedAt);
         },
         extractSync(content) {
             const startedAt = performance.now();
-            const rulesResult = rule.apply(content, config.rules, config.schema);
-            const partial = merge.apply(config.schema, rulesResult, null, content);
+            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger);
+            const partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions);
             return stampDuration(partial, startedAt);
         },
         prompt(content, partial) {
-            return prompt.build(config.schema, partial, content, {
-                systemPrompt: config.llm?.systemPrompt,
-            });
+            return prompt.build(config.schema, partial, content, buildOptions);
         },
         parse(raw) {
             return prompt.parse(config.schema, allFields, raw);
@@ -88,7 +104,7 @@ export function createExtractor(config) {
         merge(partial, llmResult, content) {
             const startedAt = performance.now();
             const rulesResult = rulesResultFromPartial(partial, allFields);
-            const result = merge.apply(config.schema, rulesResult, llmResult, content);
+            const result = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions);
             return stampDuration(result, startedAt);
         },
     };

package/dist/extractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { prompt } from './prompt.js';
 export { validator } from './validate.js';
 export type { ExtractionRule, RuleMatch, RulesResult, } from './types/rule.types.js';
 export type { Extractor, ExtractorConfig, ExtractorLlmConfig, } from './types/extractor.types.js';
-export type { LlmRequest } from './types/prompt.types.js';
+export type { CrossCheckHints, LlmRequest, PromptBuildMode, PromptBuildOptions, } from './types/prompt.types.js';
 export type { LlmProvider } from './types/provider.types.js';
 export type { Logger } from './types/logger.types.js';
 export type { Severity, Violation, Validator, } from './types/validate.types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,YAAY,EACV,cAAc,EACd,SAAS,EACT,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,SAAS,EACT,eAAe,EACf,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,YAAY,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,YAAY,EACV,QAAQ,EACR,SAAS,EACT,SAAS,GACV,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,YAAY,EACV,cAAc,EACd,SAAS,EACT,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,SAAS,EACT,eAAe,EACf,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,eAAe,EACf,UAAU,EACV,eAAe,EACf,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,YAAY,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,YAAY,EACV,QAAQ,EACR,SAAS,EACT,SAAS,GACV,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/prompt.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
 import type { ExtractionResult, LlmResult } from './types/merge.types.js';
-import type { LlmRequest } from './types/prompt.types.js';
+import type { LlmRequest, PromptBuildOptions } from './types/prompt.types.js';
 /**
  * Prompt-building primitives that turn a partial extraction result into an
  * {@link LlmRequest} targeted at the fields the deterministic pass could not
@@ -8,27 +8,34 @@ import type { LlmRequest } from './types/prompt.types.js';
  */
 export declare const prompt: {
     /**
-     * Build an LLM request restricted to `partial.missing`. The response schema
-     * is a JSON Schema covering only those fields, and values already produced
-     * by the deterministic pass are surfaced both as `knownValues` and as a
-     * hint block prepended to `userContent`.
+     * Build an LLM request targeting a subset of the schema's fields.
      *
-     * Orchestration only — the four phases (response-schema build, known-values
+     * - In `'fill-gaps'` mode (default) the response schema covers only
+     *   `partial.missing`, and rule values flow back to the LLM as hints both
+     *   through `knownValues` and a prepended "Already extracted" block in
+     *   `userContent`.
+     * - In `'cross-check'` mode the response schema covers every schema field,
+     *   so {@link merge.apply} can surface agreements or disagreements with
+     *   the rule pass. `crossCheckHints: 'unbiased'` (default) drops the hint
+     *   block and empties `knownValues` so the LLM re-extracts from scratch;
+     *   `'bias'` keeps the hints to save tokens at the cost of confirmation
+     *   bias.
+     *
+     * Orchestration only: the four phases (response-schema build, known-values
      * collection, user-content formatting, request assembly) each live in their
      * own private helper above.
      *
      * @typeParam S - A Zod object schema describing the full target shape.
      * @param schema - Zod object schema that drives the field selection.
      * @param partial - Output of {@link merge.apply} (or any equivalent partial)
-     *   — only `data` and `missing` are read.
+     *   `data` is always read; `missing` drives the fill-gaps schema and the
+     *   hint block.
      * @param content - Original text the request will refer to.
-     * @param options - Optional behavior overrides (custom system prompt).
-     * @throws When a missing field uses a Zod kind outside the supported
-     *   whitelist; the error message names the offending field.
+     * @param options - Optional overrides: `systemPrompt`, `mode`, `crossCheckHints`.
+     * @throws When a target field uses an unsupported Zod kind; the error
+     *   message names the offending field.
      */
-    build<S extends z.ZodObject<z.ZodRawShape>>(schema: S, partial: Pick<ExtractionResult<z.infer<S>>, "data" | "missing">, content: string, options?: {
-        systemPrompt?: string;
-    }): LlmRequest;
+    build<S extends z.ZodObject<z.ZodRawShape>>(schema: S, partial: Pick<ExtractionResult<z.infer<S>>, "data" | "missing">, content: string, options?: PromptBuildOptions): LlmRequest;
     /**
      * Parse a raw LLM response permissively. Accepts either an already-decoded
      * object or a JSON-encoded string. Each field listed in `missing` is

package/dist/prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAEV,gBAAgB,EAChB,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAuK1D;;;;GAIG;AACH,eAAO,MAAM,MAAM;IACjB;;;;;;;;;;;;;;;;;;OAkBG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAChC,CAAC,WACA,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,WACtD,MAAM,YACL;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAClC,UAAU;IAcb;;;;;;;;;;;;;;;OAeG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAChC,CAAC,WACA,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OACjC,OAAO,GACX,SAAS;CAiBb,CAAC"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAEV,gBAAgB,EAChB,SAAS,EACV,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAuN9E;;;;GAIG;AACH,eAAO,MAAM,MAAM;IACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAChC,CAAC,WACA,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,WACtD,MAAM,YACL,kBAAkB,GAC3B,UAAU;IAsBb;;;;;;;;;;;;;;;OAeG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAChC,CAAC,WACA,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OACjC,OAAO,GACX,SAAS;CAiBb,CAAC"}

package/dist/prompt.js

@@ -1,41 +1,80 @@
 const DEFAULT_SYSTEM_PROMPT = 'Extract the listed fields from the content as a JSON object.';
 /**
- * Convert a single Zod field schema to JSON Schema. Throws on any Zod kind
- * outside the documented whitelist (`string`, `number`, `boolean`, `enum`,
- * `nullable`), naming the offending field so the caller can restructure
- * their schema.
+ * Convert a `z.nullable(inner)` into JSON Schema by recursing into `inner`
+ * and widening its `type` to `[innerType, 'null']`. Refuses nested nullables
+ * whose inner already carries a tuple `type`.
  */
-function zodFieldToJsonSchema(zodType, field) {
-    const def = zodType.def;
-    const kind = def.type;
-    if (kind === 'string') {
-        return { type: 'string' };
-    }
-    if (kind === 'number') {
-        return { type: 'number' };
-    }
-    if (kind === 'boolean') {
-        return { type: 'boolean' };
-    }
-    if (kind === 'enum') {
-        const entries = def.entries;
-        return { type: 'string', enum: Object.values(entries) };
+function nullableToJsonSchema(def, field) {
+    const inner = zodFieldToJsonSchema(def.innerType, field);
+    const innerType = inner.type;
+    if (typeof innerType !== 'string') {
+        throw new Error(`Unsupported nested nullable on field "${field}"`);
     }
-    if (kind === 'nullable') {
-        const inner = zodFieldToJsonSchema(def.innerType, field);
-        if (typeof inner.type !== 'string') {
-            throw new Error(`Unsupported nested nullable on field "${field}"`);
+    return { ...inner, type: [innerType, 'null'] };
+}
+/**
+ * Convert a `z.object(shape)` into JSON Schema by recursing over every
+ * property. Children wrapped in `z.optional(...)` are kept in `properties`
+ * but excluded from the object-level `required` list.
+ */
+function objectToJsonSchema(def, field) {
+    const shape = def.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, child] of Object.entries(shape)) {
+        properties[key] = zodFieldToJsonSchema(child, `${field}.${key}`);
+        if (child.def.type !== 'optional') {
+            required.push(key);
         }
-        return { ...inner, type: [inner.type, 'null'] };
     }
-    throw new Error(`Unsupported Zod type "${kind}" on field "${field}"`);
+    return { type: 'object', properties, required, additionalProperties: false };
+}
+/**
+ * Dispatch the conversion by Zod kind. Primitives short-circuit, wrappers
+ * (`optional`, `default`, `nullable`, `array`, `object`) recurse, unsupported
+ * kinds throw with the offending `field` named so the caller can restructure
+ * their schema.
+ */
+function zodKindToJsonSchema(def, kind, field) {
+    switch (kind) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return { type: kind };
+        case 'enum':
+            return { type: 'string', enum: Object.values(def.entries) };
+        case 'nullable':
+            return nullableToJsonSchema(def, field);
+        case 'optional':
+        case 'default':
+            return zodFieldToJsonSchema(def.innerType, field);
+        case 'array':
+            return { type: 'array', items: zodFieldToJsonSchema(def.element, field) };
+        case 'object':
+            return objectToJsonSchema(def, field);
+        default:
+            throw new Error(`Unsupported Zod type "${kind}" on field "${field}"`);
+    }
+}
+/**
+ * Convert a single Zod field schema to JSON Schema. Wraps the kind-level
+ * dispatch with a `description` pass so `.describe()` / `.meta({ description })`
+ * registered at this recursion level flows through to the output; providers'
+ * structured-output features consume it natively.
+ */
+function zodFieldToJsonSchema(zodType, field) {
+    const schema = zodKindToJsonSchema(zodType.def, zodType.def.type, field);
+    const description = zodType.description;
+    return description ? { ...schema, description } : schema;
 }
 /**
  * Build the JSON Schema handed to the LLM, restricted to the fields the
- * deterministic pass could not produce.
+ * deterministic pass could not produce. Optional top-level fields are kept
+ * in `properties` but excluded from `required`.
  */
 function buildResponseSchema(schema, missing) {
     const properties = {};
+    const required = [];
     const shape = schema.shape;
     for (const field of missing) {
         const zodField = shape[field];
@@ -43,8 +82,11 @@ function buildResponseSchema(schema, missing) {
             continue;
         }
         properties[field] = zodFieldToJsonSchema(zodField, field);
+        if (zodField.def.type !== 'optional') {
+            required.push(field);
+        }
     }
-    return { type: 'object', properties, required: [...missing] };
+    return { type: 'object', properties, required, additionalProperties: false };
 }
 /**
  * Pick the non-null, non-missing entries of the partial result — the values
@@ -142,28 +184,44 @@ function collectUnexpectedKeys(object, missing) {
  */
 export const prompt = {
     /**
-     * Build an LLM request restricted to `partial.missing`. The response schema
-     * is a JSON Schema covering only those fields, and values already produced
-     * by the deterministic pass are surfaced both as `knownValues` and as a
-     * hint block prepended to `userContent`.
+     * Build an LLM request targeting a subset of the schema's fields.
+     *
+     * - In `'fill-gaps'` mode (default) the response schema covers only
+     *   `partial.missing`, and rule values flow back to the LLM as hints both
+     *   through `knownValues` and a prepended "Already extracted" block in
+     *   `userContent`.
+     * - In `'cross-check'` mode the response schema covers every schema field,
+     *   so {@link merge.apply} can surface agreements or disagreements with
+     *   the rule pass. `crossCheckHints: 'unbiased'` (default) drops the hint
+     *   block and empties `knownValues` so the LLM re-extracts from scratch;
+     *   `'bias'` keeps the hints to save tokens at the cost of confirmation
+     *   bias.
      *
-     * Orchestration only — the four phases (response-schema build, known-values
+     * Orchestration only: the four phases (response-schema build, known-values
      * collection, user-content formatting, request assembly) each live in their
      * own private helper above.
      *
      * @typeParam S - A Zod object schema describing the full target shape.
      * @param schema - Zod object schema that drives the field selection.
      * @param partial - Output of {@link merge.apply} (or any equivalent partial)
-     *   — only `data` and `missing` are read.
+     *   `data` is always read; `missing` drives the fill-gaps schema and the
+     *   hint block.
      * @param content - Original text the request will refer to.
-     * @param options - Optional behavior overrides (custom system prompt).
-     * @throws When a missing field uses a Zod kind outside the supported
-     *   whitelist; the error message names the offending field.
+     * @param options - Optional overrides: `systemPrompt`, `mode`, `crossCheckHints`.
+     * @throws When a target field uses an unsupported Zod kind; the error
+     *   message names the offending field.
      */
     build(schema, partial, content, options) {
-        const missing = partial.missing;
-        const responseSchema = buildResponseSchema(schema, missing);
-        const knownValues = collectKnownValues(partial.data, partial.missing);
+        const mode = options?.mode ?? 'fill-gaps';
+        const crossCheckHints = options?.crossCheckHints ?? 'unbiased';
+        const targetFields = mode === 'cross-check'
+            ? Object.keys(schema.shape)
+            : partial.missing;
+        const responseSchema = buildResponseSchema(schema, targetFields);
+        const exposeHints = mode === 'fill-gaps' || crossCheckHints === 'bias';
+        const knownValues = exposeHints
+            ? collectKnownValues(partial.data, partial.missing)
+            : {};
         const userContent = formatUserContent(content, knownValues);
         return {
             systemPrompt: options?.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,

package/dist/prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAQA,MAAM,qBAAqB,GACzB,8DAA8D,CAAC;AAKjE;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,GAAgB,EAAE,KAAa;IAC3D,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,SAAoB,EAAE,KAAK,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC;IAC7B,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,yCAAyC,KAAK,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,GAAgB,EAAE,KAAa;IACzD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAgC,CAAC;IACnD,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,UAAU,CAAC,GAAG,CAAC,GAAG,oBAAoB,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC;QACjE,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAC1B,GAAgB,EAChB,IAAY,EACZ,KAAa;IAEb,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAA0C,CAAC,EAAE,CAAC;QACjG,KAAK,UAAU;YACb,OAAO,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1C,KAAK,UAAU,CAAC;QAChB,KAAK,SAAS;YACZ,OAAO,oBAAoB,CAAC,GAAG,CAAC,SAAoB,EAAE,KAAK,CAAC,CAAC;QAC/D,KAAK,OAAO;YACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,CAAC,GAAG,CAAC,OAAkB,EAAE,KAAK,CAAC,EAAE,CAAC;QACvF,KAAK,QAAQ;YACX,OAAO,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACxC;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,IAAI,eAAe,KAAK,GAAG,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,OAAgB,EAAE,KAAa;IAC3D,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACxC,OAAO,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAC1B,MAAkC,EAClC,OAA0B;IAE1B,MAAM,UAAU,GAA4C,EAAE,CAAC;IAC/D,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,KAA2C,CAAC;IACjE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QACD,UAAU,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC1D,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACrC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CACzB,IAAsB,EACtB,OAA6B;IAE7B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,OAA4B,CAAC,CAAC;IACjE,MAAM,KAAK,GAA4B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,SAAS;QACX,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,OAAe,EAAE,WAAoC;IAC9E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAClF,OAAO,uBAAuB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAChB,GAAY;IAEZ,IAAI,SAAS,GAAY,GAAG,CAAC;IAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC;QACnD,CAAC;IACH,CAAC;IACD,IACE,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,KAAK,QAAQ;QAC7B,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACxB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAoC,EAAE,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAC5B,MAAkC,EAClC,OAA0B,EAC1B,MAA+B;IAE/B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAkC,CAAC;IACxD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC;YACvB,SAAS;QACX,CAAC;QACD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,eAAe,CAAC;YAClE,QAAQ,CAAC,IAAI,CAAC,SAAS,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAC5B,MAA+B,EAC/B,OAA0B;IAE1B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CACH,MAAS,EACT,OAA+D,EAC/D,OAAe,EACf,OAA4B;QAG5B,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,WAAW,CAAC;QAC1C,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,UAAU,CAAC;QAC/D,MAAM,YAAY,GAChB,IAAI,KAAK,aAAa;YACpB,CAAC,CAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAuB;YAClD,CAAC,CAAE,OAAO,CAAC,OAA6B,CAAC;QAC7C,MAAM,cAAc,GAAG,mBAAmB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjE,MAAM,WAAW,GAAG,IAAI,KAAK,WAAW,IAAI,eAAe,KAAK,MAAM,CAAC;QACvE,MAAM,WAAW,GAAG,WAAW;YAC7B,CAAC,CAAC,kBAAkB,CAAO,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC;YACzD,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,WAAW,GAAG,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC5D,OAAO;YACL,YAAY,EAAE,OAAO,EAAE,YAAY,IAAI,qBAAqB;YAC5D,WAAW;YACX,cAAc;YACd,WAAW;SACZ,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CACH,MAAS,EACT,OAAsC,EACtC,GAAY;QAEZ,MAAM,WAAW,GAAG,OAA4B,CAAC;QACjD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;YACzB,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACrD,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,qBAAqB,CAChD,MAAM,EACN,WAAW,EACX,OAAO,CAAC,MAAM,CACf,CAAC;QACF,MAAM,UAAU,GAAG,qBAAqB,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACtE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,8BAA8B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IACjE,CAAC;CACF,CAAC"}

package/dist/types/extractor.types.d.ts

@@ -1,8 +1,10 @@
 import type { z } from 'zod';
 import type { ExtractionRule } from './rule.types.js';
-import type { ExtractionResult, LlmResult } from './merge.types.js';
+import type { ExtractedData, ExtractionResult, FieldMergePolicy, LlmResult, Normalizer } from './merge.types.js';
 import type { LlmProvider } from './provider.types.js';
-import type { LlmRequest } from './prompt.types.js';
+import type { Logger } from './logger.types.js';
+import type { Validator } from './validate.types.js';
+import type { CrossCheckHints, LlmRequest, PromptBuildMode } from './prompt.types.js';
 /**
  * LLM-fallback section of {@link ExtractorConfig}. When present, the
  * extractor hands the fields the deterministic rules could not produce to
@@ -13,6 +15,18 @@ export type ExtractorLlmConfig = {
     provider: LlmProvider;
     /** Optional override for {@link LlmRequest.systemPrompt}; defaults to the {@link prompt.build} built-in. */
     systemPrompt?: string;
+    /**
+     * Field-selection strategy passed to {@link prompt.build}. In
+     * `'cross-check'` mode the extractor always calls the LLM (even when the
+     * rules resolved every field) so the merge step can surface agreements or
+     * conflicts. Defaults to `'fill-gaps'`.
+     */
+    mode?: PromptBuildMode;
+    /**
+     * Hint-exposure policy for cross-check mode. Defaults to `'unbiased'`.
+     * Ignored when `mode !== 'cross-check'`.
+     */
+    crossCheckHints?: CrossCheckHints;
 };
 /**
  * Configuration accepted by {@link createExtractor}. A schema describes the
@@ -28,6 +42,14 @@ export type ExtractorConfig<S extends z.ZodObject<z.ZodRawShape>> = {
     rules: ExtractionRule[];
     /** Optional LLM fallback invoked for fields the rules could not produce. */
     llm?: ExtractorLlmConfig;
+    /** Post-merge transformations, forwarded to every `merge.apply` call. */
+    normalizers?: Normalizer<z.infer<S>>[];
+    /** Invariants checked on the normalized data; populate `result.validation`. */
+    validators?: Validator<ExtractedData<z.infer<S>>>[];
+    /** Overrides for the per-field merge policy (conflict strategy, confidences, compare). */
+    policy?: Partial<FieldMergePolicy>;
+    /** Logger propagated through the merge pipeline for warnings and fallbacks. */
+    logger?: Logger;
 };
 /**
  * Public surface returned by {@link createExtractor}. Methods are added to
@@ -50,8 +72,11 @@ export type Extractor<T> = {
      */
     extractSync(content: string): ExtractionResult<T>;
     /**
-     * Build the LLM request for the fields still missing in `partial`.
-     * Delegates to {@link prompt.build} with the bound schema.
+     * Build the LLM request for `partial`. The target field set depends on the
+     * configured `llm.mode`: `'fill-gaps'` (default) covers only
+     * `partial.missing`; `'cross-check'` covers every schema field. Delegates
+     * to {@link prompt.build} with the bound schema and the configured
+     * `systemPrompt` / `crossCheckHints`.
      */
     prompt(content: string, partial: ExtractionResult<T>): LlmRequest;
     /**

package/dist/types/extractor.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.types.d.ts","sourceRoot":"","sources":["../../src/types/extractor.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,WAAW,CAAC;IACtB,4GAA4G;IAC5G,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI;IAClE,2FAA2F;IAC3F,MAAM,EAAE,CAAC,CAAC;IACV,qFAAqF;IACrF,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,kBAAkB,CAAC;CAC1B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClD;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;IAClE;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B;;;;;OAKG;IACH,KAAK,CACH,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,MAAM,GACd,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACxB,CAAC"}
+{"version":3,"file":"extractor.types.d.ts","sourceRoot":"","sources":["../../src/types/extractor.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,UAAU,EACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEtF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE,WAAW,CAAC;IACtB,4GAA4G;IAC5G,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI;IAClE,2FAA2F;IAC3F,MAAM,EAAE,CAAC,CAAC;IACV,qFAAqF;IACrF,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,kBAAkB,CAAC;IACzB,yEAAyE;IACzE,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpD,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC;IAClE;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B;;;;;OAKG;IACH,KAAK,CACH,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,MAAM,GACd,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACxB,CAAC"}

package/dist/types/prompt.types.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Selects whether the LLM is asked only about fields the deterministic pass
+ * could not produce (`'fill-gaps'`, default) or about every schema field
+ * (`'cross-check'`, enabling agreement/conflict detection with the rules).
+ */
+export type PromptBuildMode = 'fill-gaps' | 'cross-check';
+/**
+ * Whether a cross-check request exposes the rule values to the LLM as hints.
+ *
+ * - `'unbiased'` (default): no hints, the LLM re-extracts every field from
+ *   scratch, enabling genuine disagreement detection.
+ * - `'bias'`: prepend the rule values as an "Already extracted" block, same
+ *   shape as fill-gaps. Saves tokens when the caller trusts the rules and
+ *   only wants a quick sanity check.
+ *
+ * Ignored when `mode !== 'cross-check'`.
+ */
+export type CrossCheckHints = 'bias' | 'unbiased';
+/**
+ * Optional behavior overrides for `prompt.build`.
+ */
+export type PromptBuildOptions = {
+    /** Custom system prompt sent to the provider; falls back to a built-in. */
+    systemPrompt?: string;
+    /** Field-selection strategy. Defaults to `'fill-gaps'`. */
+    mode?: PromptBuildMode;
+    /** Hint-exposure policy in cross-check mode. Defaults to `'unbiased'`. */
+    crossCheckHints?: CrossCheckHints;
+};
 /**
  * A fully-built request ready to be handed to an LLM provider. Produced by
  * {@link prompt.build} from a schema and a partial extraction result.

package/dist/types/prompt.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.types.d.ts","sourceRoot":"","sources":["../../src/types/prompt.types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC"}
+{"version":3,"file":"prompt.types.d.ts","sourceRoot":"","sources":["../../src/types/prompt.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,aAAa,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,CAAC;AAElD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmbic",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Hybrid data extraction — deterministic rules + LLM fallback, with per-field confidence scoring.",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "example:ollama": "tsx examples/ollama.ts",
+    "example:openai-batch": "tsx examples/openai-batch.ts",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {
@@ -37,6 +38,7 @@
   "devDependencies": {
     "@types/node": "^25.6.0",
     "ollama": "^0.5.0",
+    "openai": "^6.34.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
     "vitest": "^4.0.0",