llmbic 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.3.0] - 2026-04-18
+
+Non-breaking. Rules can now read a caller-provided `context` object alongside `content`, so per-call metadata (locale, tenant configuration, feature flags) no longer has to be captured in rule closures at declaration time.
+
+### Added
+
+- `ExtractionRule<TContext = unknown>` - optional generic type parameter describing the shape of a per-call context forwarded to `extract`. Defaults to `unknown`, so context-unaware rules and legacy code compile unchanged.
+- `ExtractionRule.extract(content, context?)` - second optional argument, forwarded verbatim by `rule.apply` / `Extractor.extract` / `Extractor.extractSync`. Left `undefined` when the caller passes no context.
+- `rule.create<TContext>(field, extract, options?)` - `create` is now generic over `TContext`, so typed contexts flow from the callback signature to the returned `ExtractionRule<TContext>`. `rule.regex` stays context-unaware and remains assignable to any `ExtractionRule<TContext>[]` via contextual parameter contravariance.
+- `rule.apply<S, TContext>(content, rules, schema, logger?, context?)` - fifth optional argument passed through to every rule's `extract` callback.
+- `ExtractorConfig<S, TContext = unknown>` and `Extractor<T, TContext = unknown>` - second optional generic parameter shared with the rules array. `Extractor.extract(content, context?)` and `Extractor.extractSync(content, context?)` forward `context` to `rule.apply`. `Extractor.merge` does not re-evaluate rules and accepts no `context`.
+
+### Docs
+
+- `CONTRIBUTING.md` - documents the 5-step release procedure (tests, bump, doc, tag, publish) to keep future releases aligned with the SemVer + npm publish lifecycle.
+
+## [1.2.0] - 2026-04-16
+
+Non-breaking. Production-readiness pass: per-field provenance, per-field merge policy, and pre/post LLM transformers. Token / cost tracking deliberately stays out of scope - `LlmProvider` keeps observability as a caller concern; wrap your `complete` for telemetry.
+
+### Added
+
+- `ExtractionResult.sources` - per-field origin of the kept value, as a `FieldSource` discriminated union (`'rule' | 'llm' | 'agreement' | 'flag'`). Variants involving a rule carry the `ruleId` of the rule that produced the match. Use it to attribute extractions back to specific rules, monitor rule quality at scale, or filter results on agreement vs LLM-only fields.
+- `ExtractionRule.id` and `rule.create` / `rule.regex` `options.id` - declare a stable identifier surfaced in `ExtractionResult.sources`. When omitted, `rule.apply` auto-generates `${field}#${declarationIndex}` based on the rule's position in the array.
+- `MergeApplyOptions.policyByField` and `ExtractorConfig.policyByField` - per-field overrides of `FieldMergePolicy` (strategy, confidences, compare). Precedence: defaults < `policy` < `policyByField[field]`. TypeScript validates field names against the schema. Lets a single extractor flag conflicts on critical fields, prefer rules on parser-friendly fields, and prefer the LLM on free-form fields without writing custom merge code.
+- `ExtractorLlmConfig.transformRequest` / `transformResponse` - async hooks called around `provider.complete`. `transformRequest` rewrites the built `LlmRequest` (PII redaction, locale tagging); `transformResponse` rewrites the parsed `LlmResult` before the merge step (PII restoration, post-processing). Errors propagate, no implicit catch.
+- `examples/pii-redaction.ts` - runnable, offline demo of the redact-then-restore pattern using `transformRequest` + `transformResponse` (also wired as `npm run example:pii-redaction`).
+
+### Public types
+
+- `FieldSource` exported from the package root.
+- `RulesResult.sourceIds` (optional) - populated by `rule.apply`, consumed by `merge.apply` to compute `ExtractionResult.sources`. External callers building `RulesResult` by hand can omit it; provenance simply falls back to an empty `ruleId`.
+- `ExtractionRule` gains optional `id`. `RuleMatch`, `FieldMergeResult` and `merge.field`'s signature are unchanged - provenance is computed from the merge outcome plus the policy, not stored on the per-field primitive.
+
 ## [1.1.0] - 2026-04-16
 
 Non-breaking. Unblocks hybrid workflows that rely on nested schemas, agreement/conflict detection, and extractor-level merge options.
@@ -28,18 +62,18 @@ Non-breaking. Unblocks hybrid workflows that rely on nested schemas, agreement/c
 - `ExtractorConfig<S>` gains optional `normalizers`, `validators`, `policy`, `logger`.
 - `ExtractorLlmConfig` gains optional `mode`, `crossCheckHints`.
 
-## [1.0.0] — 2026-04-15
+## [1.0.0] - 2026-04-15
 
 Initial public release.
 
 ### Added
 
-- `createExtractor(config)` — factory binding a Zod schema, deterministic rules and an optional LLM fallback into an extractor with `extract`, `extractSync`, `prompt`, `parse` and `merge` methods. Covers both one-shot async extraction and 4-step batch flows (extractSync → prompt → external LLM call → parse → merge).
-- `rule` namespace — `rule.create(field, extractFn)`, `rule.regex(field, pattern, score, transform?)`, `rule.confidence(value, score)`, `rule.apply(content, rules, schema, logger?)`. Deterministic rules are pure synchronous functions returning typed matches with a confidence score in `[0, 1]`.
-- `merge` namespace — `merge.apply(schema, rulesResult, llmResult, content, options?)` fuses rules output with LLM output, detects per-field conflicts, runs normalizers, re-validates against the Zod schema, and runs custom validators. `merge.defaultFieldPolicy` exposes the built-in fusion rules.
-- `prompt` namespace — `prompt.build(schema, partial, options?)` emits an `LlmRequest` (`systemPrompt`, `userContent`, `responseSchema`, `knownValues`) restricted to fields missing from the deterministic pass. `prompt.parse(raw, missing, schema)` is a permissive parser that validates each field individually via Zod, drops invalid or unexpected keys, and never throws.
-- `validator` namespace — `validator.of<T>()` returns `{ field, crossField }` factories bound to the data shape `T`, so predicates are fully typed from the field name.
-- `LlmProvider` contract — single-method interface (`complete(request) → { values }`) consumers implement to wire any backend (OpenAI, Anthropic, Ollama, custom HTTP, ...). No vendor SDK is pulled into the import graph.
+- `createExtractor(config)` - factory binding a Zod schema, deterministic rules and an optional LLM fallback into an extractor with `extract`, `extractSync`, `prompt`, `parse` and `merge` methods. Covers both one-shot async extraction and 4-step batch flows (extractSync -> prompt -> external LLM call -> parse -> merge).
+- `rule` namespace - `rule.create(field, extractFn)`, `rule.regex(field, pattern, score, transform?)`, `rule.confidence(value, score)`, `rule.apply(content, rules, schema, logger?)`. Deterministic rules are pure synchronous functions returning typed matches with a confidence score in `[0, 1]`.
+- `merge` namespace - `merge.apply(schema, rulesResult, llmResult, content, options?)` fuses rules output with LLM output, detects per-field conflicts, runs normalizers, re-validates against the Zod schema, and runs custom validators. `merge.defaultFieldPolicy` exposes the built-in fusion rules.
+- `prompt` namespace - `prompt.build(schema, partial, options?)` emits an `LlmRequest` (`systemPrompt`, `userContent`, `responseSchema`, `knownValues`) restricted to fields missing from the deterministic pass. `prompt.parse(raw, missing, schema)` is a permissive parser that validates each field individually via Zod, drops invalid or unexpected keys, and never throws.
+- `validator` namespace - `validator.of<T>()` returns `{ field, crossField }` factories bound to the data shape `T`, so predicates are fully typed from the field name.
+- `LlmProvider` contract - single-method interface (`complete(request) -> { values }`) consumers implement to wire any backend (OpenAI, Anthropic, Ollama, custom HTTP, ...). No vendor SDK is pulled into the import graph.
 - Per-field confidence scoring, conflict detection (`flag` / `prefer-rule` / `prefer-llm` strategies), and extraction metadata (`durationMs`, rule/LLM field counts).
 - Full TypeScript `.d.ts` output with JSDoc on every public type, method and configuration field.
 - Example wiring a local Ollama runtime under `examples/ollama.ts`.

package/README.md

@@ -5,13 +5,13 @@
 [![license](https://img.shields.io/npm/l/llmbic.svg)](./LICENSE)
 [![node](https://img.shields.io/node/v/llmbic.svg)](https://nodejs.org)
 
-Hybrid data extraction — deterministic rules + LLM fallback, with per-field confidence scoring.
+Hybrid data extraction - deterministic rules + LLM fallback, with per-field confidence scoring.
 
 The name folds **LLM** into [*lambic*](https://en.wikipedia.org/wiki/Lambic), the Belgian beer made by blending wild fermentation with a controlled process. Same idea here: LLMs are unpredictable, rules are rigid, and the mix produces something reliable.
 
 ## Why
 
-Extracting structured data from unstructured text is a solved problem — until you need it to be *reliable*. Rules (regex, parsers) are deterministic but brittle. LLMs understand context but hallucinate. Neither is enough alone.
+Extracting structured data from unstructured text is a solved problem - until you need it to be *reliable*. Rules (regex, parsers) are deterministic but brittle. LLMs understand context but hallucinate. Neither is enough alone.
 
 Llmbic combines both: deterministic rules extract what they can with full confidence, the LLM fills in the gaps, and a merge layer detects conflicts between the two. Every field carries a confidence score. You know exactly what's trustworthy and what needs review.
 
@@ -21,7 +21,7 @@ Llmbic combines both: deterministic rules extract what they can with full confid
 npm install llmbic
 ```
 
-Llmbic has a single dependency: [Zod](https://zod.dev). No vendor SDK is pulled in — you bring your own LLM provider via the 1-method `LlmProvider` interface (see "Writing a provider" below).
+Llmbic has a single dependency: [Zod](https://zod.dev). No vendor SDK is pulled in - you bring your own LLM provider via the 1-method `LlmProvider` interface (see "Writing a provider" below).
 
 ## Quick start
 
@@ -111,7 +111,7 @@ console.log(result.confidence);
 // { total: 1.0, currency: 1.0, vendor: 0.7, date: 0.7 }
 
 console.log(result.conflicts);
-// [] — no disagreement between rules and LLM
+// [] - no disagreement between rules and LLM
 ```
 
 ### Batch / async mode (for OpenAI Batch API, job queues, etc.)
@@ -119,19 +119,19 @@ console.log(result.conflicts);
 When you manage the LLM call yourself (batching, polling, custom transport), use the 4-step API:
 
 ```typescript
-// Step 1 — Deterministic extraction (sync, instant)
+// Step 1 - Deterministic extraction (sync, instant)
 const partial = extractor.extractSync(markdown);
 
-// Step 2 — Build the LLM request (you send it however you want)
+// Step 2 - Build the LLM request (you send it however you want)
 const llmRequest = extractor.prompt(markdown, partial);
-// → { systemPrompt, userContent, responseSchema, knownValues }
+// -> { systemPrompt, userContent, responseSchema, knownValues }
 
 // ... submit to OpenAI Batch API, poll later, get the response ...
 
-// Step 3 — Parse the raw LLM response
+// Step 3 - Parse the raw LLM response
 const llmResult = extractor.parse(rawJsonResponse);
 
-// Step 4 — Merge everything (fusion + conflict detection + validation)
+// Step 4 - Merge everything (fusion + conflict detection + validation)
 const result = extractor.merge(partial, llmResult, markdown);
 ```
 
@@ -181,17 +181,39 @@ End-to-end runnable example (upload + poll + download + merge): [`examples/opena
 
 ### Per-field confidence scoring
 
-Every field in the result carries a confidence score (0.0–1.0):
+Every field in the result carries a confidence score (0.0-1.0):
 
 | Source | Confidence |
 |--------|-----------|
 | Deterministic rule, exact match | 1.0 |
-| Deterministic rule, partial match | 0.7–0.9 (you decide) |
+| Deterministic rule, partial match | 0.7-0.9 (you decide) |
 | LLM only | configurable default (0.7) |
 | Rule + LLM agree | 1.0 |
 | Rule + LLM disagree | 0.3 (flagged as conflict) |
 | No source | `null` |
 
+### Per-field provenance
+
+Alongside `confidence`, every field carries a `source` describing where the kept value came from. Useful for attributing extractions back to the rule that produced them, monitoring rule quality at scale, or filtering on agreement vs LLM-only fields:
+
+```typescript
+result.sources;
+// {
+//   total:    { kind: 'agreement', ruleId: 'total-eur' },  // rule + LLM agreed
+//   currency: { kind: 'rule',      ruleId: 'currency#1' }, // only the rule produced a value
+//   vendor:   { kind: 'llm' },                              // only the LLM produced a value
+//   date:     { kind: 'flag',      ruleId: 'date-iso' },   // rule and LLM disagreed under flag strategy
+//   notes:    null,                                         // missing
+// }
+```
+
+`ruleId` defaults to `${field}#${declarationIndex}` based on the rule's position in the array - stable as long as you don't reorder. For long-lived production code, declare ids explicitly so refactors don't break observability:
+
+```typescript
+rule.create('total', extractTotal, { id: 'total-eur' });
+rule.regex('date', /(\d{4}-\d{2}-\d{2})/, 0.95, undefined, { id: 'date-iso' });
+```
+
 ### Conflict detection
 
 When a rule and the LLM extract different values for the same field, Llmbic flags it:
@@ -201,10 +223,28 @@ result.conflicts;
 // [{ field: 'total', ruleValue: 1250, ruleConfidence: 1.0, llmValue: 1520 }]
 ```
 
-Three conflict strategies: `'flag'` (default — keep rule value, record conflict), `'prefer-rule'`, or `'prefer-llm'`.
+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).
 
+#### Per-field strategies
+
+`policy` is a single strategy applied to every field. When fields have different criticality (a `price` you want to flag vs a `postal_code` your regex always nails vs a free-form `description` you'd rather defer to the LLM), use `policyByField` to override per field. Precedence: library defaults < `policy` < `policyByField[field]`.
+
+```typescript
+const extractor = createExtractor({
+  schema: ListingSchema,
+  rules: [...],
+  policy: { strategy: 'flag' },          // default for every field
+  policyByField: {
+    postal_code: { strategy: 'prefer-rule' },
+    description: { strategy: 'prefer-llm' },
+  },
+});
+```
+
+You can override any subset of `FieldMergePolicy` per field - strategy, confidences, even the `compare` callback (e.g. fuzzy equality for free-form strings). TypeScript validates field names against your schema, so typos surface at compile time.
+
 ### 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):
@@ -223,6 +263,35 @@ const extractor = createExtractor({
 
 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).
 
+### Per-call context
+
+Rules can accept a second, caller-provided argument alongside `content` so they can read per-call metadata (locale, tenant configuration, feature flags) without having to capture it in a closure at declaration time:
+
+```typescript
+import { createExtractor, rule } from 'llmbic';
+import { z } from 'zod';
+
+type Region = { region: 'us' | 'uk' };
+
+const schema = z.object({ price: z.string() });
+
+const priceRule = rule.create<Region>('price', (content, context) => {
+  const pattern = context?.region === 'uk' ? /£\s*(\d+)/ : /\$\s*(\d+)/;
+  const match = content.match(pattern);
+  return match ? rule.confidence(match[1]!, 1) : null;
+});
+
+const extractor = createExtractor<typeof schema, Region>({
+  schema,
+  rules: [priceRule],
+});
+
+await extractor.extract('Listed at £42', { region: 'uk' });
+// -> { price: '42' }
+```
+
+The type parameter on `rule.create<TContext>` flows to the generic on `createExtractor<Schema, TContext>` and is enforced at every call site. `context` is forwarded verbatim to every rule's `extract` callback; rules that ignore the argument still compile and work. `extractSync(content, context?)` behaves the same way for batch workflows. `Extractor.merge` reuses the partial's values and does not re-evaluate rules, so it takes no `context`.
+
 ### Rich schemas
 
 The JSON Schema handed to the LLM supports the Zod constructs that show up in real-world extraction targets:
@@ -273,9 +342,33 @@ result.validation;
 // or { valid: false, violations: [{ field: 'price', rule: 'price_positive', message: '...', severity: 'error' }] }
 ```
 
+### Request / response transformers
+
+Two optional hooks let you intercept the LLM exchange without wrapping the provider yourself: `transformRequest` runs after `prompt.build` and before `provider.complete`; `transformResponse` runs after `prompt.parse` and before the merge. Both can be async; errors propagate.
+
+```typescript
+const extractor = createExtractor({
+  schema: ContactSchema,
+  rules: [...],
+  llm: {
+    provider,
+    transformRequest: (request, content) => ({
+      ...request,
+      systemPrompt: `Language: ${detectLocale(content)}\n${request.systemPrompt}`,
+    }),
+  },
+});
+```
+
+Common patterns:
+
+- **PII redaction (RGPD)**: replace emails / phones / IDs with placeholders in `userContent`, stash the originals in `knownValues` under a private key, restore them in `transformResponse`. Worked example: [`examples/pii-redaction.ts`](./examples/pii-redaction.ts).
+- **Locale tagging**: prepend `Language: ...` to `systemPrompt` after caller-side detection.
+- **Caching**: wrap your `LlmProvider.complete` directly - cleaner than short-circuiting in a hook, since it sits at the actual transport boundary.
+
 ## Writing a provider
 
-Llmbic does not ship vendor-specific adapters. The `LlmProvider` contract is a single method — wiring to any backend (OpenAI, Anthropic, Ollama, vLLM, Gemini, custom HTTP, ...) is ~10 lines you write and own.
+Llmbic does not ship vendor-specific adapters. The `LlmProvider` contract is a single method - wiring to any backend (OpenAI, Anthropic, Ollama, vLLM, Gemini, custom HTTP, ...) is ~10 lines you write and own.
 
 ```typescript
 import type { LlmProvider } from 'llmbic';
@@ -340,7 +433,7 @@ const provider: LlmProvider = {
 };
 ```
 
-**Ollama** (native `format` — JSON Schema, requires Ollama 0.5+):
+**Ollama** (native `format` - JSON Schema, requires Ollama 0.5+):
 
 ```typescript
 const client = new Ollama();
@@ -359,31 +452,32 @@ const provider: LlmProvider = {
 };
 ```
 
-Observability (token usage, latency, cost accounting) is out of scope — wrap the `complete` call in whatever telemetry you already use.
+Observability (token usage, latency, cost accounting) is out of scope - wrap the `complete` call in whatever telemetry you already use.
 
 ## Design decisions
 
-- **One dependency** — Zod only. No vendor SDK ever enters the import graph; you bring your own LLM provider (see "Writing a provider").
-- **No retry** — If the LLM returns invalid data, `parse()` does best-effort parsing (valid fields kept, invalid ignored). Retry is an orchestration concern.
-- **No streaming** — Llmbic works with complete results. Streaming is a transport concern.
-- **No chunking** — One content = one extraction. If your content is too long, split it before calling Llmbic.
-- **Normalizers mutate** — For pragmatic reasons, normalizers receive and return the same object. The `merge()` function copies the data first, so the original is never modified.
-- **Rules are sync** — Extraction rules are pure synchronous functions. If you need async lookups, do them before creating the rule.
+- **One dependency** - Zod only. No vendor SDK ever enters the import graph; you bring your own LLM provider (see "Writing a provider").
+- **No retry** - If the LLM returns invalid data, `parse()` does best-effort parsing (valid fields kept, invalid ignored). Retry is an orchestration concern.
+- **No streaming** - Llmbic works with complete results. Streaming is a transport concern.
+- **No chunking** - One content = one extraction. If your content is too long, split it before calling Llmbic.
+- **Normalizers mutate** - For pragmatic reasons, normalizers receive and return the same object. The `merge()` function copies the data first, so the original is never modified.
+- **Rules are sync** - Extraction rules are pure synchronous functions. If you need async lookups, do them before creating the rule.
 
 ## API reference
 
 ### `createExtractor(config)`
 
-Creates an extractor instance. Config:
+Creates an extractor instance. Signature: `createExtractor<S, TContext = unknown>(config)`. `TContext` is optional and describes the per-call context passed to `Extractor.extract(content, context?)`; see [Per-call context](#per-call-context). Config:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `schema` | `ZodObject` | yes | Output schema (drives field enumeration and re-validation). |
-| `rules` | `ExtractionRule[]` | yes | Deterministic extraction rules. |
+| `rules` | `ExtractionRule<TContext>[]` | 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). |
+| `policy` | `Partial<FieldMergePolicy>` | no | Overrides the per-field merge policy (conflict strategy, confidence defaults, equality) for every field. |
+| `policyByField` | `{ [K in keyof T]?: Partial<FieldMergePolicy> }` | no | Per-field overrides applied on top of `policy`. Precedence: defaults < `policy` < `policyByField[field]`. |
 | `logger` | `Logger` | no | Pino/Winston/console-compatible. Warnings from `rule.apply` and `merge.apply` flow through. |
 
 `ExtractorLlmConfig`:
@@ -394,15 +488,17 @@ Creates an extractor instance. Config:
 | `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. |
+| `transformRequest` | `(request, content) => LlmRequest \| Promise<LlmRequest>` | no | Hook called with the built request before `provider.complete`. PII redaction, locale tagging, etc. |
+| `transformResponse` | `(result, request) => LlmResult \| Promise<LlmResult>` | no | Hook called with the parsed LLM result before the merge. PII restoration, post-processing, etc. |
 
 ### `rule` namespace
 
 | 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.create` | `<TContext = unknown>(field, extract, options?) => ExtractionRule<TContext>` | Declare a rule. `extract(content, context?)` returns a `RuleMatch` or `null`. `options.id` sets the stable identifier surfaced in `result.sources`. `TContext` is inferred from the callback when present. |
+| `rule.regex` | `(field, pattern, score, transform?, options?) => ExtractionRule` | Regex-based rule. On match, capture group 1 (or the full match) is fed to `transform`. `options.id` sets the stable identifier surfaced in `result.sources`. |
 | `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. |
+| `rule.apply` | `<S, TContext = unknown>(content, rules, schema, logger?, context?) => RulesResult` | Run every rule, pick the highest-confidence match per field, type-check against the schema. `context` is forwarded verbatim to each rule's `extract` callback. |
 
 ### `validator.of<T>()`
 
@@ -417,11 +513,11 @@ 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 (if configured) -> merge -> normalize -> validate. |
-| `extractSync(content)` | sync | Rules only. Returns the partial result + `missing` fields. |
+| `extract(content, context?)` | async | Full pipeline: rules -> LLM (if configured) -> merge -> normalize -> validate. `context` is forwarded verbatim to every rule's `extract` callback. |
+| `extractSync(content, context?)` | sync | Rules only. Returns the partial result + `missing` fields. `context` is forwarded verbatim to every rule's `extract` callback. |
 | `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. |
+| `merge(partial, llmResult, content)` | sync | Merges rules + LLM, detects conflicts, normalizes, validates. Does not re-evaluate rules, so takes no `context`. |
 
 ## License
 

package/dist/extractor.d.ts

@@ -15,11 +15,13 @@ import type { Extractor, ExtractorConfig } from './types/extractor.types.js';
  * is parsed with {@link prompt.parse} and fused through {@link merge.apply}.
  *
  * @typeParam S - A Zod object schema describing the target data shape.
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   every rule's `extract` callback. Defaults to `unknown`.
  * @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>>;
+export declare function createExtractor<S extends z.ZodObject<z.ZodRawShape>, TContext = unknown>(config: ExtractorConfig<S, TContext>): Extractor<z.infer<S>, TContext>;
 //# sourceMappingURL=extractor.d.ts.map

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;;;;;;;;;;;;;;;;;;;;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"}
+{"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;AAmD7E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EACpC,QAAQ,GAAG,OAAO,EAElB,MAAM,EAAE,eAAe,CAAC,CAAC,EAAE,QAAQ,CAAC,GACnC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CA4EjC"}

package/dist/extractor.js

@@ -10,6 +10,7 @@ import { prompt } from './prompt.js';
 function rulesResultFromPartial(partial, allFields) {
     const values = {};
     const confidence = {};
+    const sourceIds = {};
     for (const field of allFields) {
         const value = partial.data[field];
         if (value === null) {
@@ -20,8 +21,12 @@ function rulesResultFromPartial(partial, allFields) {
         if (fieldConfidence !== null) {
             confidence[field] = fieldConfidence;
         }
+        const source = partial.sources[field];
+        if (source !== null && 'ruleId' in source) {
+            sourceIds[field] = source.ruleId;
+        }
     }
-    return { values, confidence, missing: [...partial.missing] };
+    return { values, confidence, sourceIds, missing: [...partial.missing] };
 }
 /**
  * Stamp `result.meta.durationMs` with the wall-clock elapsed since `startedAt`.
@@ -50,6 +55,8 @@ function stampDuration(result, startedAt) {
  * is parsed with {@link prompt.parse} and fused through {@link merge.apply}.
  *
  * @typeParam S - A Zod object schema describing the target data shape.
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   every rule's `extract` callback. Defaults to `unknown`.
  * @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
@@ -68,30 +75,37 @@ export function createExtractor(config) {
     };
     const mergeOptions = {
         policy: config.policy,
+        policyByField: config.policyByField,
         normalizers: config.normalizers,
         validators: config.validators,
         logger: config.logger,
     };
     return {
-        async extract(content) {
+        async extract(content, context) {
             const startedAt = performance.now();
-            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger);
+            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger, context);
             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, buildOptions);
+            const builtRequest = prompt.build(config.schema, partial, content, buildOptions);
+            const request = config.llm.transformRequest
+                ? await config.llm.transformRequest(builtRequest, content)
+                : builtRequest;
             const completion = await config.llm.provider.complete(request);
             const llmTargetFields = buildOptions.mode === 'cross-check' ? allFields : partial.missing;
-            const llmResult = prompt.parse(config.schema, llmTargetFields, completion.values);
+            const parsedLlmResult = prompt.parse(config.schema, llmTargetFields, completion.values);
+            const llmResult = config.llm.transformResponse
+                ? await config.llm.transformResponse(parsedLlmResult, request)
+                : parsedLlmResult;
             const final = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions);
             return stampDuration(final, startedAt);
         },
-        extractSync(content) {
+        extractSync(content, context) {
             const startedAt = performance.now();
-            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger);
+            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger, context);
             const partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions);
             return stampDuration(partial, 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

@@ -1,5 +1,5 @@
 /**
- * Llmbic — public entry point.
+ * Llmbic - public entry point.
  *
  * Re-exports the five namespaces that make up the library (`createExtractor`,
  * `rule`, `merge`, `prompt`, `validator`) and every public type consumers need
@@ -20,5 +20,5 @@ export type { CrossCheckHints, LlmRequest, PromptBuildMode, PromptBuildOptions,
 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';
-export type { Conflict, ConflictStrategy, ExtractedData, ExtractionMeta, ExtractionResult, FieldCompare, FieldMergePolicy, FieldMergeResult, LlmResult, MergeApplyOptions, Normalizer, ValidationResult, } from './types/merge.types.js';
+export type { Conflict, ConflictStrategy, ExtractedData, ExtractionMeta, ExtractionResult, FieldCompare, FieldMergePolicy, FieldMergeResult, FieldSource, LlmResult, MergeApplyOptions, Normalizer, ValidationResult, } from './types/merge.types.js';
 //# sourceMappingURL=index.d.ts.map

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,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"}
+{"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,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * Llmbic — public entry point.
+ * Llmbic - public entry point.
  *
  * Re-exports the five namespaces that make up the library (`createExtractor`,
  * `rule`, `merge`, `prompt`, `validator`) and every public type consumers need

package/dist/merge.d.ts

@@ -43,7 +43,7 @@ export declare const merge: {
      * @param field - Name of the field being merged.
      * @param ruleMatch - Value proposed by a deterministic rule, or `null` if none.
      * @param llmValue - Value proposed by the LLM, or `null` if none. Cast to `T`
-     *   without runtime type-check — callers that expose `merge.field` via
+     *   without runtime type-check - callers that expose `merge.field` via
      *   `merge.apply` rely on the final Zod re-validation to reject invalid LLM values.
      * @param policy - Optional strategy and confidence overrides.
      * @param logger - Optional logger notified of unexpected runtime situations
@@ -58,7 +58,7 @@ export declare const merge: {
      * Passing `llmResult = null` runs in rules-only mode: every field keeps
      * whatever the rules produced and `meta.llmCalled` is `false`.
      *
-     * Orchestration only — the three phases (fusion, normalization, validation)
+     * Orchestration only - the three phases (fusion, normalization, validation)
      * each live in their own private helper above.
      *
      * Runtime fields of `meta` (`durationMs`, `tokensUsed`) are populated by

package/dist/merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,KAAK,EAGV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EAElB,MAAM,wBAAwB,CAAC;AA+GhC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;QAED,6CAA6C;;QAE7C,yDAAyD;;QAEzD,sDAAsD;;QAEtD,wDAAwD;;QAExD,qGAAqG;qBACxF,OAAO,KAAK,OAAO,KAAG,OAAO;;IAQ5C;;;;;;;;;;;;;;;;;;;;OAoBG;UACG,CAAC,SACE,MAAM,aACF,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,YACpB,OAAO,WACR,OAAO,CAAC,gBAAgB,CAAC,WACzB,MAAM,GACd,gBAAgB,CAAC,CAAC,CAAC;IAgEtB;;;;;;;;;;;;;;;;;;;;OAoBG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAChC,CAAC,eACI,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aACzB,SAAS,GAAG,IAAI,WAClB,MAAM,YACL,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GACtC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAmChC,CAAC"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,KAAK,EAGV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAEhB,SAAS,EACT,iBAAiB,EAElB,MAAM,wBAAwB,CAAC;AAuKhC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;QAED,6CAA6C;;QAE7C,yDAAyD;;QAEzD,sDAAsD;;QAEtD,wDAAwD;;QAExD,qGAAqG;qBACxF,OAAO,KAAK,OAAO,KAAG,OAAO;;IAQ5C;;;;;;;;;;;;;;;;;;;;OAoBG;UACG,CAAC,SACE,MAAM,aACF,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,YACpB,OAAO,WACR,OAAO,CAAC,gBAAgB,CAAC,WACzB,MAAM,GACd,gBAAgB,CAAC,CAAC,CAAC;IAgEtB;;;;;;;;;;;;;;;;;;;;OAoBG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,UAChC,CAAC,eACI,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,aACzB,SAAS,GAAG,IAAI,WAClB,MAAM,YACL,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GACtC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAqChC,CAAC"}

package/dist/merge.js

@@ -3,15 +3,16 @@
  * value, fuse it with the LLM candidate via {@link merge.field}, and collect
  * per-field outcomes. Invoked once at the top of {@link merge.apply}.
  */
-function fuseAllFields(schemaKeys, rulesResult, llmResult, policy, logger) {
+function fuseAllFields(schemaKeys, rulesResult, llmResult, policy, policyByField, logger) {
     const data = {};
     const confidence = {};
+    const sources = {};
     const conflicts = [];
     const missing = [];
     let rulesMatched = 0;
     for (const field of schemaKeys) {
         const hasRuleValue = field in rulesResult.values;
-        // hasRuleValue implies confidence[field] is defined — rule.apply only writes
+        // hasRuleValue implies confidence[field] is defined - rule.apply only writes
         // to `confidence` when it also writes to `values`.
         const ruleMatch = hasRuleValue
             ? {
@@ -23,9 +24,13 @@ function fuseAllFields(schemaKeys, rulesResult, llmResult, policy, logger) {
             rulesMatched += 1;
         }
         const llmValue = llmResult?.values[field] ?? null;
-        const fused = merge.field(field, ruleMatch, llmValue, policy, logger);
+        const fieldOverride = policyByField?.[field];
+        const resolvedPolicy = fieldOverride === undefined ? policy : { ...policy, ...fieldOverride };
+        const ruleId = rulesResult.sourceIds?.[field];
+        const fused = merge.field(field, ruleMatch, llmValue, resolvedPolicy, logger);
         data[field] = fused.value;
         confidence[field] = fused.confidence;
+        sources[field] = deriveSource(fused, ruleMatch, llmValue, resolvedPolicy, ruleId);
         if (fused.conflict !== undefined) {
             conflicts.push(fused.conflict);
         }
@@ -33,7 +38,47 @@ function fuseAllFields(schemaKeys, rulesResult, llmResult, policy, logger) {
             missing.push(field);
         }
     }
-    return { data, confidence, conflicts, missing, rulesMatched };
+    return { data, confidence, sources, conflicts, missing, rulesMatched };
+}
+/**
+ * Classify the origin of a fused value into a {@link FieldSource}. Mirrors
+ * the decision tree of {@link merge.field} without re-running the strategy:
+ *
+ * - rule alone -> `'rule'`
+ * - LLM alone -> `'llm'`
+ * - both null -> `null`
+ * - both present, conflict recorded -> `'flag'` (only the `'flag'` strategy
+ *   produces a conflict)
+ * - both present, no conflict, kept value differs from the rule -> `'llm'`
+ *   (only `'prefer-llm'` reaches this case)
+ * - both present, no conflict, kept value matches the rule -> `'agreement'`
+ *   when the policy's `compare` returns true, else `'rule'` (`'prefer-rule'`
+ *   silent path)
+ *
+ * `ruleId` is `''` when the rule provided no declared id and `rule.apply`
+ * was bypassed by the caller.
+ */
+function deriveSource(fused, ruleMatch, llmValue, policy, ruleId) {
+    if (fused.value === null) {
+        return null;
+    }
+    const id = ruleId ?? '';
+    if (ruleMatch === null) {
+        return { kind: 'llm' };
+    }
+    if (llmValue === null || llmValue === undefined) {
+        return { kind: 'rule', ruleId: id };
+    }
+    if (fused.conflict !== undefined) {
+        return { kind: 'flag', ruleId: id };
+    }
+    if (fused.value !== ruleMatch.value) {
+        return { kind: 'llm' };
+    }
+    const compare = policy?.compare ?? merge.defaultFieldPolicy.compare;
+    return compare(ruleMatch.value, llmValue)
+        ? { kind: 'agreement', ruleId: id }
+        : { kind: 'rule', ruleId: id };
 }
 /**
  * Apply every configured {@link Normalizer} to the merged data in declared
@@ -122,7 +167,7 @@ export const merge = {
      * @param field - Name of the field being merged.
      * @param ruleMatch - Value proposed by a deterministic rule, or `null` if none.
      * @param llmValue - Value proposed by the LLM, or `null` if none. Cast to `T`
-     *   without runtime type-check — callers that expose `merge.field` via
+     *   without runtime type-check - callers that expose `merge.field` via
      *   `merge.apply` rely on the final Zod re-validation to reject invalid LLM values.
      * @param policy - Optional strategy and confidence overrides.
      * @param logger - Optional logger notified of unexpected runtime situations
@@ -194,7 +239,7 @@ export const merge = {
      * Passing `llmResult = null` runs in rules-only mode: every field keeps
      * whatever the rules produced and `meta.llmCalled` is `false`.
      *
-     * Orchestration only — the three phases (fusion, normalization, validation)
+     * Orchestration only - the three phases (fusion, normalization, validation)
      * each live in their own private helper above.
      *
      * Runtime fields of `meta` (`durationMs`, `tokensUsed`) are populated by
@@ -209,13 +254,14 @@ export const merge = {
      */
     apply(schema, rulesResult, llmResult, content, options) {
         const schemaKeys = Object.keys(schema.shape);
-        const fusion = fuseAllFields(schemaKeys, rulesResult, llmResult, options?.policy, options?.logger);
+        const fusion = fuseAllFields(schemaKeys, rulesResult, llmResult, options?.policy, options?.policyByField, options?.logger);
         const normalized = runNormalizers(fusion.data, options?.normalizers, content);
         const violations = collectViolations(schema, normalized, fusion.missing, options?.validators);
         const valid = !violations.some((v) => v.severity === 'error');
         return {
             data: normalized,
             confidence: fusion.confidence,
+            sources: fusion.sources,
             conflicts: fusion.conflicts,
             missing: fusion.missing,
             validation: { valid, violations },

package/dist/merge.js.map

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

package/dist/prompt.d.ts

@@ -39,7 +39,7 @@ export declare const prompt: {
     /**
      * Parse a raw LLM response permissively. Accepts either an already-decoded
      * object or a JSON-encoded string. Each field listed in `missing` is
-     * validated individually against its Zod schema — valid fields flow into
+     * validated individually against its Zod schema - valid fields flow into
      * `values`, invalid ones are dropped and surfaced as warnings. Keys outside
      * `missing` are dropped as well, with a single aggregated warning so the
      * caller can spot a prompt/provider mismatch.
@@ -50,7 +50,7 @@ export declare const prompt: {
      * @param schema - Zod object schema whose fields back the validation.
      * @param missing - Fields the LLM was expected to produce (typically
      *   {@link ExtractionResult.missing}).
-     * @param raw - The provider response — object or JSON string.
+     * @param raw - The provider response - object or JSON string.
      */
     parse<S extends z.ZodObject<z.ZodRawShape>>(schema: S, missing: readonly (keyof z.infer<S>)[], raw: unknown): LlmResult;
 };

package/dist/prompt.js

@@ -89,7 +89,7 @@ function buildResponseSchema(schema, missing) {
     return { type: 'object', properties, required, additionalProperties: false };
 }
 /**
- * Pick the non-null, non-missing entries of the partial result — the values
+ * Pick the non-null, non-missing entries of the partial result - the values
  * the deterministic pass has already resolved.
  */
 function collectKnownValues(data, missing) {
@@ -233,7 +233,7 @@ export const prompt = {
     /**
      * Parse a raw LLM response permissively. Accepts either an already-decoded
      * object or a JSON-encoded string. Each field listed in `missing` is
-     * validated individually against its Zod schema — valid fields flow into
+     * validated individually against its Zod schema - valid fields flow into
      * `values`, invalid ones are dropped and surfaced as warnings. Keys outside
      * `missing` are dropped as well, with a single aggregated warning so the
      * caller can spot a prompt/provider mismatch.
@@ -244,7 +244,7 @@ export const prompt = {
      * @param schema - Zod object schema whose fields back the validation.
      * @param missing - Fields the LLM was expected to produce (typically
      *   {@link ExtractionResult.missing}).
-     * @param raw - The provider response — object or JSON string.
+     * @param raw - The provider response - object or JSON string.
      */
     parse(schema, missing, raw) {
         const missingKeys = missing;

package/dist/rules.d.ts

@@ -10,13 +10,23 @@ export declare const rule: {
      * Declare a deterministic extraction rule targeting a single schema field.
      *
      * The `extract` callback receives the raw content and must return either a
-     * {@link RuleMatch} or `null` when the rule does not apply.
+     * {@link RuleMatch} or `null` when the rule does not apply. It may also
+     * accept an optional caller-defined `context` forwarded verbatim by
+     * {@link rule.apply} / {@link Extractor.extract}.
      *
+     * @typeParam TContext - Shape of the optional context forwarded to
+     *   `extract`. Defaults to `unknown`.
      * @param field - Name of the schema field the rule writes to.
-     * @param extract - Callback that inspects the content and proposes a value.
+     * @param extract - Callback that inspects the content (and optional context)
+     *   and proposes a value.
+     * @param options - Optional rule metadata. `id` is surfaced in
+     *   `ExtractionResult.sources` when this rule produces the kept value;
+     *   defaults to `${field}#${declarationIndex}`.
      * @returns An {@link ExtractionRule} ready to be passed to {@link rule.apply}.
      */
-    create(field: string, extract: (content: string) => RuleMatch<unknown> | null): ExtractionRule;
+    create<TContext = unknown>(field: string, extract: (content: string, context?: TContext) => RuleMatch<unknown> | null, options?: {
+        id?: string;
+    }): ExtractionRule<TContext>;
     /**
      * Shortcut to build a regex-based {@link ExtractionRule}. On match, the
      * value is taken from capture group 1 (or the full match if none), then
@@ -29,7 +39,9 @@ export declare const rule: {
      * @param transform - Optional mapper from the raw `RegExpMatchArray` to a value.
      * @returns An {@link ExtractionRule} ready to be passed to {@link rule.apply}.
      */
-    regex<T = string>(field: string, pattern: RegExp, confidenceScore: number, transform?: (match: RegExpMatchArray) => T): ExtractionRule;
+    regex<T = string>(field: string, pattern: RegExp, confidenceScore: number, transform?: (match: RegExpMatchArray) => T, options?: {
+        id?: string;
+    }): ExtractionRule;
     /**
      * Build a {@link RuleMatch} from a value and a confidence score. Syntactic
      * sugar used inside custom rule callbacks to avoid writing the object literal
@@ -61,13 +73,21 @@ export declare const rule: {
      * - Values failing the per-field Zod `safeParse` are discarded and the
      *   field falls back to `missing`. An optional logger receives a warning.
      *
+     * The optional `context` is forwarded verbatim to every rule's `extract`
+     * callback. Rules that declare a narrower `ExtractionRule<TContext>` than
+     * the one passed here still compile thanks to contextual parameter
+     * contravariance; rules that ignore `context` keep working unchanged.
+     *
      * @typeParam S - A Zod object schema.
+     * @typeParam TContext - Shape of the optional context forwarded to rules.
      * @param content - Raw content to extract from (typically markdown or text).
      * @param rules - Deterministic rules to evaluate.
      * @param schema - Zod object schema describing the target data shape.
      * @param logger - Optional logger notified when a value is rejected.
+     * @param context - Optional caller-defined value forwarded to every rule's
+     *   `extract` callback. Left `undefined` when omitted.
      * @returns The deterministic extraction result (values, confidence, missing).
      */
-    apply<S extends z.ZodObject<z.ZodRawShape>>(content: string, rules: ExtractionRule[], schema: S, logger?: Logger): RulesResult<z.infer<S>>;
+    apply<S extends z.ZodObject<z.ZodRawShape>, TContext = unknown>(content: string, rules: ExtractionRule<TContext>[], schema: S, logger?: Logger, context?: TContext): RulesResult<z.infer<S>>;
 };
 //# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;;OASG;kBAEM,MAAM,WACJ,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,GACtD,cAAc;IAIjB;;;;;;;;;;;OAWG;UACG,CAAC,kBACE,MAAM,WACJ,MAAM,mBACE,MAAM,cACX,CAAC,KAAK,EAAE,gBAAgB,KAAK,CAAC,GACzC,cAAc;IAcjB;;;;;;;;;;;;;;;;;OAiBG;eACQ,CAAC,SAAS,CAAC,SAAS,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAIpD;;;;;;;;;;;;;;;;;;OAkBG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,WAC/B,MAAM,SACR,cAAc,EAAE,UACf,CAAC,WACA,MAAM,GACd,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAqC3B,CAAC"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;;;;;;;;;;OAiBG;WACI,QAAQ,mBACN,MAAM,WACJ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,YACjE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,cAAc,CAAC,QAAQ,CAAC;IAI3B;;;;;;;;;;;OAWG;UACG,CAAC,kBACE,MAAM,WACJ,MAAM,mBACE,MAAM,cACX,CAAC,KAAK,EAAE,gBAAgB,KAAK,CAAC,YAChC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,cAAc;IAYjB;;;;;;;;;;;;;;;;;OAiBG;eACQ,CAAC,SAAS,CAAC,SAAS,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,QAAQ,qBACzC,MAAM,SACR,cAAc,CAAC,QAAQ,CAAC,EAAE,UACzB,CAAC,WACA,MAAM,YACL,QAAQ,GACjB,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAwC3B,CAAC"}

package/dist/rules.js

@@ -7,14 +7,22 @@ export const rule = {
      * Declare a deterministic extraction rule targeting a single schema field.
      *
      * The `extract` callback receives the raw content and must return either a
-     * {@link RuleMatch} or `null` when the rule does not apply.
+     * {@link RuleMatch} or `null` when the rule does not apply. It may also
+     * accept an optional caller-defined `context` forwarded verbatim by
+     * {@link rule.apply} / {@link Extractor.extract}.
      *
+     * @typeParam TContext - Shape of the optional context forwarded to
+     *   `extract`. Defaults to `unknown`.
      * @param field - Name of the schema field the rule writes to.
-     * @param extract - Callback that inspects the content and proposes a value.
+     * @param extract - Callback that inspects the content (and optional context)
+     *   and proposes a value.
+     * @param options - Optional rule metadata. `id` is surfaced in
+     *   `ExtractionResult.sources` when this rule produces the kept value;
+     *   defaults to `${field}#${declarationIndex}`.
      * @returns An {@link ExtractionRule} ready to be passed to {@link rule.apply}.
      */
-    create(field, extract) {
-        return { field, extract };
+    create(field, extract, options) {
+        return options?.id !== undefined ? { id: options.id, field, extract } : { field, extract };
     },
     /**
      * Shortcut to build a regex-based {@link ExtractionRule}. On match, the
@@ -28,18 +36,16 @@ export const rule = {
      * @param transform - Optional mapper from the raw `RegExpMatchArray` to a value.
      * @returns An {@link ExtractionRule} ready to be passed to {@link rule.apply}.
      */
-    regex(field, pattern, confidenceScore, transform) {
-        return {
-            field,
-            extract: (content) => {
-                const match = content.match(pattern);
-                if (!match) {
-                    return null;
-                }
-                const value = transform ? transform(match) : (match[1] ?? match[0]);
-                return { value, confidence: confidenceScore };
-            },
+    regex(field, pattern, confidenceScore, transform, options) {
+        const extract = (content) => {
+            const match = content.match(pattern);
+            if (!match) {
+                return null;
+            }
+            const value = transform ? transform(match) : (match[1] ?? match[0]);
+            return { value, confidence: confidenceScore };
         };
+        return options?.id !== undefined ? { id: options.id, field, extract } : { field, extract };
     },
     /**
      * Build a {@link RuleMatch} from a value and a confidence score. Syntactic
@@ -74,23 +80,33 @@ export const rule = {
      * - Values failing the per-field Zod `safeParse` are discarded and the
      *   field falls back to `missing`. An optional logger receives a warning.
      *
+     * The optional `context` is forwarded verbatim to every rule's `extract`
+     * callback. Rules that declare a narrower `ExtractionRule<TContext>` than
+     * the one passed here still compile thanks to contextual parameter
+     * contravariance; rules that ignore `context` keep working unchanged.
+     *
      * @typeParam S - A Zod object schema.
+     * @typeParam TContext - Shape of the optional context forwarded to rules.
      * @param content - Raw content to extract from (typically markdown or text).
      * @param rules - Deterministic rules to evaluate.
      * @param schema - Zod object schema describing the target data shape.
      * @param logger - Optional logger notified when a value is rejected.
+     * @param context - Optional caller-defined value forwarded to every rule's
+     *   `extract` callback. Left `undefined` when omitted.
      * @returns The deterministic extraction result (values, confidence, missing).
      */
-    apply(content, rules, schema, logger) {
+    apply(content, rules, schema, logger, context) {
         const schemaKeys = Object.keys(schema.shape);
         const values = {};
         const confidenceMap = {};
-        for (const candidate of rules) {
+        const sourceIds = {};
+        for (let index = 0; index < rules.length; index += 1) {
+            const candidate = rules[index];
             const field = candidate.field;
             if (!schemaKeys.includes(field)) {
                 continue;
             }
-            const match = candidate.extract(content);
+            const match = candidate.extract(content, context);
             if (match === null) {
                 continue;
             }
@@ -110,9 +126,10 @@ export const rule = {
             }
             values[field] = parsed.data;
             confidenceMap[field] = match.confidence;
+            sourceIds[field] = candidate.id ?? `${candidate.field}#${index}`;
         }
         const missing = schemaKeys.filter((key) => !(key in values));
-        return { values, confidence: confidenceMap, missing };
+        return { values, confidence: confidenceMap, sourceIds, missing };
     },
 };
 //# sourceMappingURL=rules.js.map

package/dist/rules.js.map

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

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

@@ -27,6 +27,23 @@ export type ExtractorLlmConfig = {
      * Ignored when `mode !== 'cross-check'`.
      */
     crossCheckHints?: CrossCheckHints;
+    /**
+     * Hook called with the fully-built {@link LlmRequest} just before
+     * `provider.complete`. Return the request to send. Useful for PII
+     * redaction (replace emails / phones / IDs in `userContent`), locale
+     * tagging (prepend `Language: ...` to `systemPrompt`), or any caller-side
+     * pre-processing. The original `content` is forwarded so the hook can
+     * cross-reference it. May be asynchronous; errors propagate to `extract`.
+     */
+    transformRequest?: (request: LlmRequest, content: string) => LlmRequest | Promise<LlmRequest>;
+    /**
+     * Hook called with the parsed {@link LlmResult} just after
+     * `provider.complete`. Return the result the merge step should use. Useful
+     * for restoring PII-redacted values, applying caller-side post-processing,
+     * or stripping unsafe content. Receives the (possibly transformed) request
+     * for context. May be asynchronous; errors propagate to `extract`.
+     */
+    transformResponse?: (result: LlmResult, request: LlmRequest) => LlmResult | Promise<LlmResult>;
 };
 /**
  * Configuration accepted by {@link createExtractor}. A schema describes the
@@ -34,12 +51,15 @@ export type ExtractorLlmConfig = {
  * produce values for each field before any LLM fallback kicks in.
  *
  * @typeParam S - A Zod object schema describing the target data shape.
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   every rule's `extract` callback. Defaults to `unknown`, which keeps
+ *   context-unaware rules assignable with zero boilerplate.
  */
-export type ExtractorConfig<S extends z.ZodObject<z.ZodRawShape>> = {
+export type ExtractorConfig<S extends z.ZodObject<z.ZodRawShape>, TContext = unknown> = {
     /** Zod object schema the extractor targets. Drives field enumeration and re-validation. */
     schema: S;
     /** Deterministic rules evaluated against the raw content before any LLM fallback. */
-    rules: ExtractionRule[];
+    rules: ExtractionRule<TContext>[];
     /** Optional LLM fallback invoked for fields the rules could not produce. */
     llm?: ExtractorLlmConfig;
     /** Post-merge transformations, forwarded to every `merge.apply` call. */
@@ -48,6 +68,14 @@ export type ExtractorConfig<S extends z.ZodObject<z.ZodRawShape>> = {
     validators?: Validator<ExtractedData<z.infer<S>>>[];
     /** Overrides for the per-field merge policy (conflict strategy, confidences, compare). */
     policy?: Partial<FieldMergePolicy>;
+    /**
+     * Per-field policy overrides applied on top of `policy`. Precedence:
+     * library defaults < `policy` < `policyByField[field]`. Forwarded to every
+     * internal `merge.apply` call.
+     */
+    policyByField?: {
+        [K in keyof z.infer<S>]?: Partial<FieldMergePolicy>;
+    };
     /** Logger propagated through the merge pipeline for warnings and fallbacks. */
     logger?: Logger;
 };
@@ -56,21 +84,25 @@ export type ExtractorConfig<S extends z.ZodObject<z.ZodRawShape>> = {
  * this interface as the matching slice introduces them.
  *
  * @typeParam T - Shape of the target data object inferred from a Zod schema.
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   every rule's `extract` callback. Defaults to `unknown`.
  */
-export type Extractor<T> = {
+export type Extractor<T, TContext = unknown> = {
     /**
      * Run the full extraction pipeline against `content`: deterministic rules,
      * optionally followed by an LLM fallback for missing fields, then the merge
-     * + validation step.
+     * + validation step. An optional `context` is forwarded verbatim to every
+     * rule's `extract` callback.
      */
-    extract(content: string): Promise<ExtractionResult<T>>;
+    extract(content: string, context?: TContext): Promise<ExtractionResult<T>>;
     /**
      * Run the deterministic rules and merge them against a `null` LLM result.
      * Synchronous counterpart to {@link Extractor.extract} for batch workflows
      * where the LLM call is managed by the caller (queues, scheduled jobs,
-     * external batch APIs).
+     * external batch APIs). An optional `context` is forwarded verbatim to
+     * every rule's `extract` callback.
      */
-    extractSync(content: string): ExtractionResult<T>;
+    extractSync(content: string, context?: TContext): ExtractionResult<T>;
     /**
      * Build the LLM request for `partial`. The target field set depends on the
      * configured `llm.mode`: `'fill-gaps'` (default) covers only
@@ -87,10 +119,10 @@ export type Extractor<T> = {
      */
     parse(raw: unknown): LlmResult;
     /**
-     * Merge a previously-obtained `partial` with an LLM result and re-run the
-     * deterministic rules to produce the final {@link ExtractionResult}.
-     * Rules are pure, so re-running them is cheaper than carrying private
-     * state on the extractor.
+     * Merge a previously-obtained `partial` with an LLM result to produce the
+     * final {@link ExtractionResult}. Reuses the per-field values, confidence
+     * and provenance already carried by `partial`: the deterministic rules are
+     * not re-evaluated, so no `context` parameter is accepted here.
      */
     merge(partial: ExtractionResult<T>, llmResult: LlmResult, content: string): ExtractionResult<T>;
 };

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

package/dist/types/logger.types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Minimal logger interface consumed by llmbic internals. Any logger that
- * exposes a `warn` method (and optionally `info`) can be plugged in —
+ * exposes a `warn` method (and optionally `info`) can be plugged in -
  * pino, winston, `console`, or a test double.
  */
 export type Logger = {

package/dist/types/merge.types.d.ts

@@ -30,6 +30,14 @@ export type Normalizer<T> = (data: ExtractedData<T>, content: string) => Extract
 export type MergeApplyOptions<T> = {
     /** Overrides forwarded to every field-level fusion call. */
     policy?: Partial<FieldMergePolicy>;
+    /**
+     * Per-field policy overrides applied on top of `policy`. Precedence:
+     * library defaults < `policy` < `policyByField[field]`. Fields absent from
+     * the map fall back to `policy` alone.
+     */
+    policyByField?: {
+        [K in keyof T]?: Partial<FieldMergePolicy>;
+    };
     /** Transformations run in declared order after the per-field fusion. */
     normalizers?: Normalizer<T>[];
     /** Invariants run on the normalized data; their violations populate `validation`. */
@@ -40,13 +48,39 @@ export type MergeApplyOptions<T> = {
 /**
  * Strategy applied when the rule and the LLM disagree on a field value.
  *
- * - `'flag'` — keep the rule value, lower its confidence, and record a
+ * - `'flag'` - keep the rule value, lower its confidence, and record a
  *   {@link Conflict} so the caller can review the disagreement.
- * - `'prefer-rule'` — silently keep the rule value and its confidence.
- * - `'prefer-llm'` — silently keep the LLM value and the default LLM
+ * - `'prefer-rule'` - silently keep the rule value and its confidence.
+ * - `'prefer-llm'` - silently keep the LLM value and the default LLM
  *   confidence.
  */
 export type ConflictStrategy = 'flag' | 'prefer-rule' | 'prefer-llm';
+/**
+ * Origin of the value kept for a field after fusion. Each variant carries the
+ * `ruleId` of the deterministic rule involved when applicable, so consumers
+ * can attribute extracted values back to the exact rule that produced them.
+ *
+ * - `'rule'`: only the rule produced a value, or the rule won under
+ *   `'prefer-rule'`.
+ * - `'llm'`: only the LLM produced a value, or the LLM won under
+ *   `'prefer-llm'`.
+ * - `'agreement'`: rule and LLM produced equivalent values per the policy's
+ *   `compare` callback. `ruleId` points to the rule that matched.
+ * - `'flag'`: rule and LLM disagreed under the `'flag'` strategy. The rule
+ *   value is kept; `ruleId` identifies the rule.
+ */
+export type FieldSource = {
+    kind: 'rule';
+    ruleId: string;
+} | {
+    kind: 'llm';
+} | {
+    kind: 'agreement';
+    ruleId: string;
+} | {
+    kind: 'flag';
+    ruleId: string;
+};
 /**
  * A disagreement between a rule match and an LLM value for the same field.
  * Produced only when the resolution strategy is `'flag'`.
@@ -147,6 +181,14 @@ export type ExtractionResult<T> = {
     confidence: {
         [K in keyof T]: number | null;
     };
+    /**
+     * Origin of the value kept for each field, or `null` for missing fields.
+     * Use it to attribute extractions back to the rule that produced them, to
+     * detect agreement between rules and LLM, or to spot flagged conflicts.
+     */
+    sources: {
+        [K in keyof T]: FieldSource | null;
+    };
     /** Disagreements recorded by the `'flag'` strategy during per-field fusion. */
     conflicts: Conflict[];
     /** Fields for which no value could be produced. */

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

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

package/dist/types/provider.types.d.ts

@@ -8,7 +8,7 @@ export type LlmProvider = {
     /**
      * Send `request` to the underlying model and return the structured values
      * it produced. Observability concerns (token counters, latency, cost) are
-     * the caller's responsibility — they live outside the llmbic contract so
+     * the caller's responsibility - they live outside the llmbic contract so
      * the library stays free of vendor-specific metering.
      *
      * @param request - Prompt, user content, and JSON Schema built by {@link prompt.build}.

package/dist/types/rule.types.d.ts

@@ -13,12 +13,34 @@ export type RuleMatch<T> = {
 /**
  * A deterministic rule that tries to extract a single schema field from raw
  * content. `extract` returns `null` when the rule does not apply.
+ *
+ * Rules can optionally accept a `context` argument: an opaque, caller-defined
+ * value forwarded verbatim by `rule.apply` / `Extractor.extract`. Typical use
+ * is to expose per-call metadata (locale, tenant-specific configuration,
+ * feature flags) rules need to decide whether they apply. `TContext`
+ * defaults to `unknown` so context-unaware rules stay assignable to arrays
+ * typed with any context.
+ *
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   `extract`. Defaults to `unknown`.
  */
-export type ExtractionRule = {
+export type ExtractionRule<TContext = unknown> = {
+    /**
+     * Stable identifier surfaced in `ExtractionResult.sources` when this rule
+     * produces the kept value. Optional: when omitted, `rule.apply` assigns
+     * `${field}#${declarationIndex}` based on the rule's position in the
+     * `rules` array.
+     */
+    id?: string;
     /** Name of the schema field this rule targets. */
     field: string;
-    /** Inspects `content` and returns a match, or `null` if nothing was found. */
-    extract: (content: string) => RuleMatch<unknown> | null;
+    /**
+     * Inspects `content` - and optionally a caller-provided `context` -
+     * and returns a match, or `null` if nothing was found. `context` is
+     * forwarded verbatim by `rule.apply` / `Extractor.extract` and left
+     * `undefined` when the caller passes no context.
+     */
+    extract: (content: string, context?: TContext) => RuleMatch<unknown> | null;
 };
 /**
  * The output of the rules pass. Contains the values that deterministic rules
@@ -32,6 +54,15 @@ export type RulesResult<T> = {
     values: Partial<T>;
     /** Confidence score per extracted field, in `[0, 1]`. */
     confidence: Partial<Record<keyof T, number>>;
+    /**
+     * Identifier of the winning rule per extracted field. Always populated by
+     * {@link rule.apply}: either the rule's declared `id` or
+     * `${field}#${declarationIndex}` from the source `rules` array. Optional
+     * on the type for back-compat with callers who build {@link RulesResult}
+     * by hand; consumers (including {@link merge.apply}) tolerate its absence
+     * and surface an empty `ruleId` in {@link FieldSource} when missing.
+     */
+    sourceIds?: Partial<Record<keyof T, string>>;
     /** Schema fields for which no rule produced a valid value. */
     missing: (keyof T)[];
 };

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

@@ -1 +1 @@
-{"version":3,"file":"rule.types.d.ts","sourceRoot":"","sources":["../../src/types/rule.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC;IACT,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CACzD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,8DAA8D;IAC9D,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;CACtB,CAAC"}
+{"version":3,"file":"rule.types.d.ts","sourceRoot":"","sources":["../../src/types/rule.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC;IACT,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC/C;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,KAAK,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7E,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,8DAA8D;IAC9D,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmbic",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Hybrid data extraction — deterministic rules + LLM fallback, with per-field confidence scoring.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "typecheck": "tsc --noEmit",
     "example:ollama": "tsx examples/ollama.ts",
     "example:openai-batch": "tsx examples/openai-batch.ts",
+    "example:pii-redaction": "tsx examples/pii-redaction.ts",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "peerDependencies": {