llmbic 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.4.0] - 2026-04-18
+
+Non-breaking. Normalizers can now read the same caller-provided `context` the rules see, so post-merge cross-field fix-ups no longer have to be closed over at extractor-declaration time. Typical use: a normalizer that reconciles extracted fields against the `sourceUrl` or per-tenant configuration passed to `extract`.
+
+### Added
+
+- `Normalizer<T, TContext = unknown>` - second optional generic type parameter describing the shape of the per-call context forwarded to the normalizer's third argument. Defaults to `unknown`, so context-unaware normalizers and legacy code compile unchanged.
+- `Normalizer(data, content, context?)` - third optional argument, left `undefined` when the caller passes no context.
+- `MergeApplyOptions<T, TContext = unknown>` - second optional generic parameter shared with `Normalizer`, surfacing as `normalizers?: Normalizer<T, TContext>[]`.
+- `merge.apply<S, TContext>(schema, rulesResult, llmResult, content, options?, context?)` - sixth optional argument forwarded verbatim to every normalizer.
+- `ExtractorConfig<S, TContext>.normalizers` now types as `Normalizer<z.infer<S>, TContext>[]`, so the context flowing through rules reaches normalizers with the same compile-time shape.
+- `Extractor.merge(partial, llmResult, content, context?)` - fourth optional argument. Rules are still not re-evaluated, but normalizers run here too; accepting `context` keeps them consistent with `Extractor.extract` / `Extractor.extractSync`.
+
+## [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.
@@ -46,18 +75,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,12 +181,12 @@ 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) |
@@ -223,7 +223,7 @@ 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).
 
@@ -263,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 AND to every normalizer as their optional third argument; callbacks that ignore it still compile and work. `extractSync(content, context?)` behaves the same way for batch workflows. `Extractor.merge(partial, llmResult, content, context?)` does not re-evaluate rules (it reuses the partial's values) but normalizers still run, so it accepts the same optional `context`.
+
 ### Rich schemas
 
 The JSON Schema handed to the LLM supports the Zod constructs that show up in real-world extraction targets:
@@ -274,22 +303,35 @@ The JSON Schema handed to the LLM supports the Zod constructs that show up in re
 
 ### Normalizers
 
-Post-merge transformations. Run in sequence, receive the merged data + original content:
+Post-merge transformations. Run in sequence, receive the merged data + original content, and optionally the same per-call `context` the rules see (see [Per-call context](#per-call-context)):
 
 ```typescript
-const extractor = createExtractor({
+type Ctx = { sourceUrl: string };
+
+const extractor = createExtractor<typeof MySchema, Ctx>({
   schema: MySchema,
   rules: [...],
   normalizers: [
     (data, content) => {
-      // Fix a known data quality issue
+      // Rules/content-only normalizer: no context needed
       if (data.price && data.price < 100) data.price = null;
       return data;
     },
+    (data, _content, context) => {
+      // Context-aware: cross-field fix-up that depends on where the content came from
+      if (context && !data.city && /\/liege\//.test(context.sourceUrl)) {
+        data.city = 'Liège';
+      }
+      return data;
+    },
   ],
 });
+
+await extractor.extract(markdown, { sourceUrl: 'https://example.be/liege/123' });
 ```
 
+Context-unaware normalizers keep working unchanged - the third argument is optional and left `undefined` when the caller passes no context.
+
 ### Validators (invariants)
 
 Check the final output for logical consistency:
@@ -339,7 +381,7 @@ Common patterns:
 
 ## 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';
@@ -404,7 +446,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();
@@ -423,29 +465,29 @@ 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. |
+| `normalizers` | `Normalizer<T, TContext>[]` | no | Post-merge transformations, run in declared order. Each normalizer receives `(data, content, context?)`; `TContext` is shared with the rules array. |
 | `validators` | `Validator<ExtractedData<T>>[]` | no | Invariants populating `result.validation`. |
 | `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]`. |
@@ -466,10 +508,10 @@ Creates an extractor instance. Config:
 
 | Member | Signature | Description |
 |---|---|---|
-| `rule.create` | `(field, extract, options?) => ExtractionRule` | Declare a rule. `extract(content)` returns a `RuleMatch` or `null`. `options.id` sets the stable identifier surfaced in `result.sources`. |
+| `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>()`
 
@@ -484,11 +526,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, context?)` | sync | Merges rules + LLM, detects conflicts, normalizes, validates. Does not re-evaluate rules, but normalizers still run and receive `context` verbatim. |
 
 ## 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;AAmD7E;;;;;;;;;;;;;;;;;;;;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,CA4EvB"}
+{"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

@@ -55,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
@@ -79,10 +81,10 @@ export function createExtractor(config) {
         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 partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions);
+            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger, context);
+            const partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions, context);
             const shouldCallLlm = config.llm !== undefined &&
                 (buildOptions.mode === 'cross-check' || partial.missing.length > 0);
             if (!shouldCallLlm) {
@@ -98,13 +100,13 @@ export function createExtractor(config) {
             const llmResult = config.llm.transformResponse
                 ? await config.llm.transformResponse(parsedLlmResult, request)
                 : parsedLlmResult;
-            const final = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions);
+            const final = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions, context);
             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 partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions);
+            const rulesResult = rule.apply(content, config.rules, config.schema, config.logger, context);
+            const partial = merge.apply(config.schema, rulesResult, null, content, mergeOptions, context);
             return stampDuration(partial, startedAt);
         },
         prompt(content, partial) {
@@ -113,10 +115,10 @@ export function createExtractor(config) {
         parse(raw) {
             return prompt.parse(config.schema, allFields, raw);
         },
-        merge(partial, llmResult, content) {
+        merge(partial, llmResult, content, context) {
             const startedAt = performance.now();
             const rulesResult = rulesResultFromPartial(partial, allFields);
-            const result = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions);
+            const result = merge.apply(config.schema, rulesResult, llmResult, content, mergeOptions, context);
             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

@@ -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/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,19 +58,22 @@ 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
      * later slices; for now `durationMs` is `0`.
      *
      * @typeParam S - A Zod object schema.
+     * @typeParam TContext - Shape of the optional context forwarded to every
+     *   normalizer. Defaults to `unknown`.
      * @param schema - Zod object schema describing the target data shape.
      * @param rulesResult - Output of {@link rule.apply} for the same schema.
      * @param llmResult - Parsed LLM response, or `null` for rules-only mode.
      * @param content - Original text the rules and LLM were derived from; forwarded to normalizers so they can cross-reference the source.
      * @param options - Optional behavior overrides (policy, normalizers, validators, logger).
+     * @param context - Optional caller-defined value forwarded to every normalizer's third argument. Left `undefined` when omitted.
      */
-    apply<S extends z.ZodObject<z.ZodRawShape>>(schema: S, rulesResult: RulesResult<z.infer<S>>, llmResult: LlmResult | null, content: string, options?: MergeApplyOptions<z.infer<S>>): ExtractionResult<z.infer<S>>;
+    apply<S extends z.ZodObject<z.ZodRawShape>, TContext = unknown>(schema: S, rulesResult: RulesResult<z.infer<S>>, llmResult: LlmResult | null, content: string, options?: MergeApplyOptions<z.infer<S>, TContext>, context?: TContext): ExtractionResult<z.infer<S>>;
 };
 //# sourceMappingURL=merge.d.ts.map

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,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"}
+{"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;AA0KhC;;;;;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;;;;;;;;;;;;;;;;;;;;;;;OAuBG;UACG,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,QAAQ,oBAC1C,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,EAAE,QAAQ,CAAC,YACvC,QAAQ,GACjB,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAqChC,CAAC"}

package/dist/merge.js

@@ -12,7 +12,7 @@ function fuseAllFields(schemaKeys, rulesResult, llmResult, policy, policyByField
     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
             ? {
@@ -83,12 +83,14 @@ function deriveSource(fused, ruleMatch, llmValue, policy, ruleId) {
 /**
  * Apply every configured {@link Normalizer} to the merged data in declared
  * order. Normalizers may mutate their argument; the returned reference is
- * what the rest of the pipeline observes.
+ * what the rest of the pipeline observes. The caller-provided `context` is
+ * forwarded verbatim to every normalizer (left `undefined` when the caller
+ * passed none).
  */
-function runNormalizers(data, normalizers, content) {
+function runNormalizers(data, normalizers, content, context) {
     let current = data;
     for (const normalizer of normalizers ?? []) {
-        current = normalizer(current, content);
+        current = normalizer(current, content, context);
     }
     return current;
 }
@@ -167,7 +169,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
@@ -239,23 +241,26 @@ 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
      * later slices; for now `durationMs` is `0`.
      *
      * @typeParam S - A Zod object schema.
+     * @typeParam TContext - Shape of the optional context forwarded to every
+     *   normalizer. Defaults to `unknown`.
      * @param schema - Zod object schema describing the target data shape.
      * @param rulesResult - Output of {@link rule.apply} for the same schema.
      * @param llmResult - Parsed LLM response, or `null` for rules-only mode.
      * @param content - Original text the rules and LLM were derived from; forwarded to normalizers so they can cross-reference the source.
      * @param options - Optional behavior overrides (policy, normalizers, validators, logger).
+     * @param context - Optional caller-defined value forwarded to every normalizer's third argument. Left `undefined` when omitted.
      */
-    apply(schema, rulesResult, llmResult, content, options) {
+    apply(schema, rulesResult, llmResult, content, options, context) {
         const schemaKeys = Object.keys(schema.shape);
         const fusion = fuseAllFields(schemaKeys, rulesResult, llmResult, options?.policy, options?.policyByField, options?.logger);
-        const normalized = runNormalizers(fusion.data, options?.normalizers, content);
+        const normalized = runNormalizers(fusion.data, options?.normalizers, content, context);
         const violations = collectViolations(schema, normalized, fusion.missing, options?.validators);
         const valid = !violations.some((v) => v.severity === 'error');
         return {

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,18 +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, options?: {
+    create<TContext = unknown>(field: string, extract: (content: string, context?: TContext) => RuleMatch<unknown> | null, options?: {
         id?: string;
-    }): ExtractionRule;
+    }): 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
@@ -68,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;;;;;;;;;;;;OAYG;kBAEM,MAAM,WACJ,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,YAC7C;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,cAAc;IAIjB;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;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;CAwC3B,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,10 +7,15 @@ 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}`.
@@ -75,14 +80,22 @@ 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 = {};
@@ -93,7 +106,7 @@ export const rule = {
             if (!schemaKeys.includes(field)) {
                 continue;
             }
-            const match = candidate.extract(content);
+            const match = candidate.extract(content, context);
             if (match === null) {
                 continue;
             }

package/dist/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,KAAa,EACb,OAAuD,EACvD,OAAyB;QAEzB,OAAO,OAAO,EAAE,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC7F,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CACH,KAAa,EACb,OAAe,EACf,eAAuB,EACvB,SAA0C,EAC1C,OAAyB;QAEzB,MAAM,OAAO,GAAG,CAAC,OAAe,EAA6B,EAAE;YAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACpE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;QAChD,CAAC,CAAC;QACF,OAAO,OAAO,EAAE,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC7F,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAI,KAAQ,EAAE,KAAa;QACnC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CACH,OAAe,EACf,KAAuB,EACvB,MAAS,EACT,MAAe;QAGf,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAmB,CAAC;QAC/D,MAAM,MAAM,GAAkB,EAAE,CAAC;QACjC,MAAM,aAAa,GAAwC,EAAE,CAAC;QAC9D,MAAM,SAAS,GAAwC,EAAE,CAAC;QAE1D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACrD,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAmB,CAAC;YAC5C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,SAAS;YACX,CAAC;YACD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAiB,CAAC;YAClE,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,EAAE,IAAI,CAAC,+BAA+B,EAAE;oBAC5C,KAAK,EAAE,SAAS,CAAC,KAAK;oBACtB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;iBAC3B,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,MAAM,kBAAkB,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YAChD,IAAI,kBAAkB,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,IAAI,kBAAkB,EAAE,CAAC;gBAC/E,SAAS;YACX,CAAC;YACD,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,IAAwB,CAAC;YAChD,aAAa,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;YACxC,SAAS,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;QACnE,CAAC;QAED,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC;QAE7D,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IACnE,CAAC;CACF,CAAC"}
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

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

@@ -51,16 +51,24 @@ 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. */
-    normalizers?: Normalizer<z.infer<S>>[];
+    /**
+     * Post-merge transformations, forwarded to every `merge.apply` call.
+     * Normalizers share the extractor's `TContext`, so they can read the same
+     * per-call context as the rules (see
+     * {@link Extractor.extract} / {@link Extractor.extractSync} / {@link Extractor.merge}).
+     */
+    normalizers?: Normalizer<z.infer<S>, TContext>[];
     /** 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). */
@@ -81,21 +89,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
@@ -112,11 +124,12 @@ 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. Normalizers still run here, so an optional `context` is
+     * accepted and forwarded verbatim to every normalizer that declares one.
      */
-    merge(partial: ExtractionResult<T>, llmResult: LlmResult, content: string): ExtractionResult<T>;
+    merge(partial: ExtractionResult<T>, llmResult: LlmResult, content: string, context?: TContext): ExtractionResult<T>;
 };
 //# sourceMappingURL=extractor.types.d.ts.map

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":"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"}
+{"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

@@ -17,17 +17,29 @@ export type ExtractedData<T> = {
  * and return the updated data. They are allowed to mutate their input; the
  * merge pipeline shallow-copies once before invoking them.
  *
+ * Normalizers can optionally accept a `context` argument: an opaque,
+ * caller-defined value forwarded verbatim by `merge.apply` /
+ * `Extractor.extract` - the same per-call context the extractor's rules
+ * receive. Typical use is to gate cross-field fix-ups on tenant-specific
+ * configuration (e.g. a source URL, a feature flag). `TContext` defaults to
+ * `unknown` so context-unaware normalizers stay assignable to arrays typed
+ * with any context.
+ *
  * @typeParam T - Non-null target shape the extraction is aiming for.
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   the normalizer. Defaults to `unknown`.
  */
-export type Normalizer<T> = (data: ExtractedData<T>, content: string) => ExtractedData<T>;
+export type Normalizer<T, TContext = unknown> = (data: ExtractedData<T>, content: string, context?: TContext) => ExtractedData<T>;
 /**
  * Behavior overrides accepted by the top-level merge. Every field is
  * optional; defaults match rules-only mode with no normalization and no
  * validators.
  *
  * @typeParam T - Non-null target shape (`z.infer<Schema>`).
+ * @typeParam TContext - Shape of the optional per-call context forwarded to
+ *   every normalizer. Defaults to `unknown`.
  */
-export type MergeApplyOptions<T> = {
+export type MergeApplyOptions<T, TContext = unknown> = {
     /** Overrides forwarded to every field-level fusion call. */
     policy?: Partial<FieldMergePolicy>;
     /**
@@ -39,7 +51,7 @@ export type MergeApplyOptions<T> = {
         [K in keyof T]?: Partial<FieldMergePolicy>;
     };
     /** Transformations run in declared order after the per-field fusion. */
-    normalizers?: Normalizer<T>[];
+    normalizers?: Normalizer<T, TContext>[];
     /** Invariants run on the normalized data; their violations populate `validation`. */
     validators?: Validator<ExtractedData<T>>[];
     /** Logger propagated through the pipeline for warnings and fallbacks. */
@@ -48,10 +60,10 @@ 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';

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,8 +13,18 @@ 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
@@ -24,8 +34,13 @@ export type ExtractionRule = {
     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

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;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,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;;;;;;;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"}
+{"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.2.0",
+  "version": "1.4.0",
   "description": "Hybrid data extraction — deterministic rules + LLM fallback, with per-field confidence scoring.",
   "type": "module",
   "license": "MIT",