llmbic 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+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.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.
+- 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Smeets <contact@devpixel.be>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# Llmbic
+
+[![npm version](https://img.shields.io/npm/v/llmbic.svg)](https://www.npmjs.com/package/llmbic)
+[![CI](https://github.com/devpixel-be/llmbic/actions/workflows/ci.yml/badge.svg)](https://github.com/devpixel-be/llmbic/actions/workflows/ci.yml)
+[![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.
+
+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.
+
+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.
+
+## Install
+
+```bash
+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).
+
+## Quick start
+
+### Rules-only (no LLM, no network)
+
+```typescript
+import { z } from 'zod';
+import { createExtractor, rule, confidence } from 'llmbic';
+
+const InvoiceSchema = z.object({
+  total: z.number().nullable(),
+  currency: z.string().nullable(),
+  vendor: z.string().nullable(),
+  date: z.string().nullable(),
+});
+
+const extractor = createExtractor({
+  schema: InvoiceSchema,
+  rules: [
+    rule('total', (text) => {
+      const m = text.match(/Total[:\s]*(\d[\d.,\s]+)\s*€/i);
+      if (!m) return null;
+      return confidence(parseFloat(m[1].replace(/[\s.]/g, '').replace(',', '.')), 1.0);
+    }),
+    rule('currency', (text) => {
+      if (/€|EUR/i.test(text)) return confidence('EUR', 1.0);
+      if (/\$|USD/i.test(text)) return confidence('USD', 1.0);
+      return null;
+    }),
+  ],
+});
+
+const result = await extractor.extract(markdownContent);
+
+console.log(result.data);
+// { total: 1250.00, currency: 'EUR', vendor: null, date: null }
+
+console.log(result.confidence);
+// { total: 1.0, currency: 1.0, vendor: null, date: null }
+
+console.log(result.missing);
+// ['vendor', 'date']
+```
+
+### Rules + LLM
+
+```typescript
+import { createExtractor, rule, confidence } from 'llmbic';
+import type { LlmProvider } from 'llmbic';
+import OpenAI from 'openai';
+
+const client = new OpenAI();
+const provider: LlmProvider = {
+  async complete(request) {
+    const response = await client.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [
+        { role: 'system', content: request.systemPrompt },
+        { role: 'user', content: request.userContent },
+      ],
+      response_format: {
+        type: 'json_schema',
+        json_schema: { name: 'extraction', strict: true, schema: request.responseSchema },
+      },
+    });
+    return { values: JSON.parse(response.choices[0].message.content!) };
+  },
+};
+
+const extractor = createExtractor({
+  schema: InvoiceSchema,
+  rules: [
+    // ... same rules as above
+  ],
+  llm: {
+    provider,
+    systemPrompt: 'Extract invoice data from the following document.',
+  },
+});
+
+const result = await extractor.extract(markdownContent);
+
+console.log(result.data);
+// { total: 1250.00, currency: 'EUR', vendor: 'Acme Corp', date: '2026-04-14' }
+
+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
+```
+
+### Batch / async mode (for OpenAI Batch API, job queues, etc.)
+
+When you manage the LLM call yourself (batching, polling, custom transport), use the 4-step API:
+
+```typescript
+// Step 1 — Deterministic extraction (sync, instant)
+const partial = extractor.extractSync(markdown);
+
+// Step 2 — Build the LLM request (you send it however you want)
+const llmRequest = extractor.prompt(markdown, partial);
+// → { systemPrompt, userContent, responseSchema, knownValues }
+
+// ... submit to OpenAI Batch API, poll later, get the response ...
+
+// Step 3 — Parse the raw LLM response
+const llmResult = extractor.parse(rawJsonResponse);
+
+// Step 4 — Merge everything (fusion + conflict detection + validation)
+const result = extractor.merge(partial, llmResult, markdown);
+```
+
+## Features
+
+### Per-field confidence scoring
+
+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) |
+| LLM only | configurable default (0.7) |
+| Rule + LLM agree | 1.0 |
+| Rule + LLM disagree | 0.3 (flagged as conflict) |
+| No source | `null` |
+
+### Conflict detection
+
+When a rule and the LLM extract different values for the same field, Llmbic flags it:
+
+```typescript
+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'`.
+
+### Normalizers
+
+Post-merge transformations. Run in sequence, receive the merged data + original content:
+
+```typescript
+const extractor = createExtractor({
+  schema: MySchema,
+  rules: [...],
+  normalizers: [
+    (data, content) => {
+      // Fix a known data quality issue
+      if (data.price && data.price < 100) data.price = null;
+      return data;
+    },
+  ],
+});
+```
+
+### Validators (invariants)
+
+Check the final output for logical consistency:
+
+```typescript
+import { validators } from 'llmbic';
+
+const { field, crossField } = validators<MySchemaShape>();
+
+const extractor = createExtractor({
+  schema: MySchema,
+  rules: [...],
+  validators: [
+    field('price', 'price_positive', (v) => v === null || v > 0, 'Price must be positive'),
+    crossField('date_format', (d) => !d.date || /^\d{4}-\d{2}-\d{2}$/.test(d.date), 'Date must be YYYY-MM-DD'),
+  ],
+});
+
+result.validation;
+// { valid: true, violations: [] }
+// or { valid: false, violations: [{ field: 'price', rule: 'price_positive', message: '...', severity: 'error' }] }
+```
+
+## 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.
+
+```typescript
+import type { LlmProvider } from 'llmbic';
+
+const provider: LlmProvider = {
+  async complete(request) {
+    const response = await fetch('https://api.example.com/v1/complete', {
+      method: 'POST',
+      body: JSON.stringify({
+        system: request.systemPrompt,
+        user: request.userContent,
+        schema: request.responseSchema,
+      }),
+    });
+    const data = await response.json();
+    return { values: data.output };
+  },
+};
+```
+
+Ready-made snippets for common backends:
+
+**OpenAI** (Chat Completions + Structured Outputs):
+
+```typescript
+const client = new OpenAI();
+const provider: LlmProvider = {
+  async complete(request) {
+    const response = await client.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [
+        { role: 'system', content: request.systemPrompt },
+        { role: 'user', content: request.userContent },
+      ],
+      response_format: {
+        type: 'json_schema',
+        json_schema: { name: 'extraction', strict: true, schema: request.responseSchema },
+      },
+    });
+    return { values: JSON.parse(response.choices[0].message.content!) };
+  },
+};
+```
+
+**Anthropic** (Messages API + forced tool):
+
+```typescript
+const client = new Anthropic();
+const provider: LlmProvider = {
+  async complete(request) {
+    const response = await client.messages.create({
+      model: 'claude-haiku-4-5-20251001',
+      max_tokens: 4096,
+      system: request.systemPrompt,
+      messages: [{ role: 'user', content: request.userContent }],
+      tools: [{ name: 'extraction', input_schema: request.responseSchema }],
+      tool_choice: { type: 'tool', name: 'extraction' },
+    });
+    const toolUse = response.content.find((b) => b.type === 'tool_use');
+    return { values: toolUse!.input as Record<string, unknown> };
+  },
+};
+```
+
+**Ollama** (native `format` — JSON Schema, requires Ollama 0.5+):
+
+```typescript
+const client = new Ollama();
+const provider: LlmProvider = {
+  async complete(request) {
+    const response = await client.chat({
+      model: 'llama3.1',
+      messages: [
+        { role: 'system', content: request.systemPrompt },
+        { role: 'user', content: request.userContent },
+      ],
+      format: request.responseSchema,
+    });
+    return { values: JSON.parse(response.message.content) };
+  },
+};
+```
+
+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.
+
+## API reference
+
+### `createExtractor(config)`
+
+Creates an extractor instance. Config:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `schema` | `ZodObject` | yes | Output schema |
+| `rules` | `ExtractionRule[]` | yes | Deterministic extraction rules |
+| `llm` | `{ provider, systemPrompt, defaultConfidence? }` | no | LLM configuration. Omit for rules-only mode. |
+| `normalizers` | `Normalizer[]` | no | Post-merge transformations |
+| `validators` | `Validator[]` | no | Output invariants |
+| `conflictStrategy` | `'flag' \| 'prefer-rule' \| 'prefer-llm'` | no | Default: `'flag'` |
+| `logger` | `Logger` | no | Injectable logger (compatible with Pino, Winston, console) |
+
+### `rule(field, extractFn)`
+
+Factory to create an `ExtractionRule`.
+
+### `confidence(value, score)`
+
+Factory to create a `RuleMatch` with a confidence score.
+
+### `validators<T>()`
+
+Factory bound to the data shape `T`. Returns `{ field, crossField }`:
+
+- `field(name, rule, checkFn, message, severity?)` — single-field validator. `checkFn` receives the precise type of the field (`T[name]`).
+- `crossField(rule, checkFn, message, severity?)` — whole-object validator, produces a violation without a `field` property.
+
+Binding `T` once lets TypeScript infer each field's type from the field name, so predicates are fully typed without manual annotations.
+
+### Extractor methods
+
+| Method | Sync | Description |
+|--------|------|-------------|
+| `extract(content)` | async | Full pipeline: rules → LLM → merge → validate |
+| `extractSync(content)` | sync | Rules only. Returns partial result + missing fields. |
+| `prompt(content, partial)` | sync | Builds LLM prompt for missing fields only. |
+| `parse(raw)` | sync | Parses raw LLM JSON response. |
+| `merge(partial, llmResult, content)` | sync | Merges rules + LLM, detects conflicts, normalizes, validates. |
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/extractor.d.ts

@@ -0,0 +1,19 @@
+import type { z } from 'zod';
+import type { Extractor, ExtractorConfig } from './types/extractor.types.js';
+/**
+ * Bind a schema, deterministic rules and an optional LLM fallback into an
+ * {@link Extractor}. The returned object exposes the extraction pipeline as
+ * pre-configured methods; call sites stop having to thread `schema`,
+ * `rules` and provider wiring through every step.
+ *
+ * {@link Extractor.extract} runs {@link rule.apply}, then — when an LLM is
+ * configured and some fields are still missing — asks the provider for those
+ * fields only, parses the response with {@link prompt.parse} and fuses
+ * everything through {@link merge.apply}.
+ *
+ * @typeParam S - A Zod object schema describing the target data shape.
+ * @param config - Schema, deterministic rules, and optional LLM fallback.
+ * @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>>;
+//# sourceMappingURL=extractor.d.ts.map

package/dist/extractor.d.ts.map

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

package/dist/extractor.js

@@ -0,0 +1,96 @@
+import { rule } from './rules.js';
+import { merge } from './merge.js';
+import { prompt } from './prompt.js';
+/**
+ * Reconstruct a {@link RulesResult} from a `partial` that was previously
+ * produced by `extractSync` (i.e. a rules-only merge). Avoids re-running the
+ * rules during a deferred {@link Extractor.merge} call, since the partial
+ * already carries every rule value and its confidence.
+ */
+function rulesResultFromPartial(partial, allFields) {
+    const values = {};
+    const confidence = {};
+    for (const field of allFields) {
+        const value = partial.data[field];
+        if (value === null) {
+            continue;
+        }
+        values[field] = value;
+        const fieldConfidence = partial.confidence[field];
+        if (fieldConfidence !== null) {
+            confidence[field] = fieldConfidence;
+        }
+    }
+    return { values, confidence, missing: [...partial.missing] };
+}
+/**
+ * Stamp `result.meta.durationMs` with the wall-clock elapsed since `startedAt`.
+ * Used by every {@link Extractor} method that returns an {@link ExtractionResult},
+ * so consumers see real timings instead of the placeholder `0` left by
+ * {@link merge.apply}.
+ */
+function stampDuration(result, startedAt) {
+    return {
+        ...result,
+        meta: { ...result.meta, durationMs: performance.now() - startedAt },
+    };
+}
+/**
+ * Bind a schema, deterministic rules and an optional LLM fallback into an
+ * {@link Extractor}. The returned object exposes the extraction pipeline as
+ * pre-configured methods; call sites stop having to thread `schema`,
+ * `rules` and provider wiring through every step.
+ *
+ * {@link Extractor.extract} runs {@link rule.apply}, then — when an LLM is
+ * configured and some fields are still missing — asks the provider for those
+ * fields only, parses the response with {@link prompt.parse} and fuses
+ * everything through {@link merge.apply}.
+ *
+ * @typeParam S - A Zod object schema describing the target data shape.
+ * @param config - Schema, deterministic rules, and optional LLM fallback.
+ * @returns An {@link Extractor} bound to `config.schema`.
+ */
+export function createExtractor(config) {
+    const allFields = Object.keys(config.schema.shape);
+    if (allFields.length === 0) {
+        throw new Error('createExtractor: schema must declare at least one field');
+    }
+    return {
+        async extract(content) {
+            const startedAt = performance.now();
+            const rulesResult = rule.apply(content, config.rules, config.schema);
+            const partial = merge.apply(config.schema, rulesResult, null, content);
+            if (!config.llm || partial.missing.length === 0) {
+                return stampDuration(partial, startedAt);
+            }
+            const request = prompt.build(config.schema, partial, content, {
+                systemPrompt: config.llm.systemPrompt,
+            });
+            const completion = await config.llm.provider.complete(request);
+            const llmResult = prompt.parse(config.schema, partial.missing, completion.values);
+            const final = merge.apply(config.schema, rulesResult, llmResult, content);
+            return stampDuration(final, startedAt);
+        },
+        extractSync(content) {
+            const startedAt = performance.now();
+            const rulesResult = rule.apply(content, config.rules, config.schema);
+            const partial = merge.apply(config.schema, rulesResult, null, content);
+            return stampDuration(partial, startedAt);
+        },
+        prompt(content, partial) {
+            return prompt.build(config.schema, partial, content, {
+                systemPrompt: config.llm?.systemPrompt,
+            });
+        },
+        parse(raw) {
+            return prompt.parse(config.schema, allFields, raw);
+        },
+        merge(partial, llmResult, content) {
+            const startedAt = performance.now();
+            const rulesResult = rulesResultFromPartial(partial, allFields);
+            const result = merge.apply(config.schema, rulesResult, llmResult, content);
+            return stampDuration(result, startedAt);
+        },
+    };
+}
+//# sourceMappingURL=extractor.js.map

package/dist/extractor.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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
+ * to describe schemas, rules, providers, normalizers and validators.
+ *
+ * Llmbic does not ship vendor-specific provider adapters: the {@link LlmProvider}
+ * contract is a single-method interface, consumers implement it in ~10 lines
+ * using whichever SDK or HTTP client they prefer (see README).
+ */
+export { createExtractor } from './extractor.js';
+export { rule } from './rules.js';
+export { merge } from './merge.js';
+export { prompt } from './prompt.js';
+export { validator } from './validate.js';
+export type { ExtractionRule, RuleMatch, RulesResult, } from './types/rule.types.js';
+export type { Extractor, ExtractorConfig, ExtractorLlmConfig, } from './types/extractor.types.js';
+export type { LlmRequest } from './types/prompt.types.js';
+export type { LlmProvider } from './types/provider.types.js';
+export type { Logger } from './types/logger.types.js';
+export type { Severity, Violation, Validator, } from './types/validate.types.js';
+export type { Conflict, ConflictStrategy, ExtractedData, ExtractionMeta, ExtractionResult, FieldCompare, FieldMergePolicy, FieldMergeResult, LlmResult, MergeApplyOptions, Normalizer, ValidationResult, } from './types/merge.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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
+ * to describe schemas, rules, providers, normalizers and validators.
+ *
+ * Llmbic does not ship vendor-specific provider adapters: the {@link LlmProvider}
+ * contract is a single-method interface, consumers implement it in ~10 lines
+ * using whichever SDK or HTTP client they prefer (see README).
+ */
+export { createExtractor } from './extractor.js';
+export { rule } from './rules.js';
+export { merge } from './merge.js';
+export { prompt } from './prompt.js';
+export { validator } from './validate.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}

package/dist/merge.d.ts

@@ -0,0 +1,76 @@
+import type { z } from 'zod';
+import type { Logger } from './types/logger.types.js';
+import type { RuleMatch, RulesResult } from './types/rule.types.js';
+import type { ExtractionResult, FieldMergePolicy, FieldMergeResult, LlmResult, MergeApplyOptions } from './types/merge.types.js';
+/**
+ * Field-level and object-level merge primitives.
+ *
+ * For now, only {@link merge.field} is exposed; the top-level object merge
+ * will be added in a later slice.
+ */
+export declare const merge: {
+    /**
+     * Library defaults applied by {@link merge.field} when the caller omits
+     * one or more policy fields. Exposed so consumers can reference or spread
+     * them (e.g. `{ ...merge.defaultFieldPolicy, strategy: 'prefer-llm' }`).
+     *
+     * See {@link FieldMergePolicy} for the meaning of each field.
+     */
+    defaultFieldPolicy: {
+        /** See {@link FieldMergePolicy.strategy}. */
+        strategy: "flag";
+        /** See {@link FieldMergePolicy.defaultLlmConfidence}. */
+        defaultLlmConfidence: number;
+        /** See {@link FieldMergePolicy.flaggedConfidence}. */
+        flaggedConfidence: number;
+        /** See {@link FieldMergePolicy.agreementConfidence}. */
+        agreementConfidence: number;
+        /** See {@link FieldMergePolicy.compare}. Case-insensitive for strings, strict equality otherwise. */
+        compare: (a: unknown, b: unknown) => boolean;
+    };
+    /**
+     * Fuse a rule match and an LLM value for a single field, following the
+     * provided policy. Returns the kept value, its confidence, and a conflict
+     * record if the strategy flagged a disagreement.
+     *
+     * Any policy field omitted from `policy` falls back to
+     * {@link merge.defaultFieldPolicy}.
+     *
+     * Decision table (in order): rule-only, llm-only, both-null, agree,
+     * prefer-rule, prefer-llm, flag (default fallback).
+     *
+     * @typeParam T - Type of the rule value.
+     * @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
+     *   `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
+     *   (e.g. an unknown strategy slipped past the type system).
+     */
+    field<T>(field: string, ruleMatch: RuleMatch<T> | null, llmValue: unknown, policy?: Partial<FieldMergePolicy>, logger?: Logger): FieldMergeResult<T>;
+    /**
+     * Walk every field of `schema`, fuse the rules pass result with the LLM
+     * result via {@link merge.field}, and produce a typed
+     * {@link ExtractionResult}.
+     *
+     * 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)
+     * 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.
+     * @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).
+     */
+    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>>;
+};
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.d.ts.map

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