llmbic 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.
@@ -46,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,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; 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:
@@ -339,7 +368,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 +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();
@@ -423,27 +452,27 @@ 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`. |
@@ -466,10 +495,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 +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;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,9 +81,9 @@ 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 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);
@@ -101,9 +103,9 @@ export function createExtractor(config) {
             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

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.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
             ? {
@@ -167,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
@@ -239,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

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":"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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

@@ -51,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. */
@@ -81,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
@@ -112,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":"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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

@@ -48,10 +48,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/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.3.0",
   "description": "Hybrid data extraction — deterministic rules + LLM fallback, with per-field confidence scoring.",
   "type": "module",
   "license": "MIT",