@sembl/core 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,37 @@
+/**
+ * Named string formats a field can be constrained to.
+ *
+ * Each one is validated locally, described in the prompt, and — where JSON
+ * Schema has a matching keyword — emitted in the schema dialects that honour
+ * it. They exist for the fields every pipeline ends up normalising by hand:
+ * a country that came back as "United States", a state as "Calif.", a
+ * currency as "dollars".
+ *
+ * - `"url"` — an absolute http(s) URL.
+ * - `"email"` — one address, no display name.
+ * - `"date"` — a calendar date as `YYYY-MM-DD`.
+ * - `"datetime"` — an ISO 8601 timestamp, e.g. `2026-09-05T14:30:00Z`.
+ * - `"iso-country"` — an ISO 3166-1 alpha-2 code: `US`, `DE`, `PT`.
+ * - `"us-state"` — a two-letter USPS state code: `CA`, `NY`, `DC`, `PR`.
+ * - `"us-state-name"` — a state's full name: `California`, `New York`.
+ * - `"currency"` — an ISO 4217 code: `USD`, `EUR`, `GBP`.
+ */
+type FieldFormat = "url" | "email" | "date" | "datetime" | "iso-country" | "us-state" | "us-state-name" | "currency";
+declare const FIELD_FORMATS: readonly FieldFormat[];
+/**
+ * Check a string against a format. Returns a message describing what was
+ * expected when the value does not conform, undefined when it does.
+ */
+declare function validateFormat(value: string, format: FieldFormat): string | undefined;
+/** The phrase the prompt uses to state a format. */
+declare function describeFormat(format: FieldFormat): string;
+/**
+ * JSON Schema keywords for a format, in the standard dialect. The four with
+ * a JSON Schema `format` of their own use it; the code formats state their
+ * shape as a pattern, since a `format` a validator does not know is ignored.
+ */
+declare function formatToJsonSchema(format: FieldFormat): Record<string, unknown>;
+
 /**
  * Bounds a field's value beyond its type.
  *
@@ -7,6 +41,8 @@
  * each element, so `string[]` can carry both `maxItems` and `maxLength`.
  */
 interface FieldConstraints {
+    /** A named string format: `"url"`, `"date"`, `"iso-country"`, `"currency"`, … */
+    format?: FieldFormat;
     /** Maximum string length, inclusive */
     maxLength?: number;
     /** Minimum string length, inclusive */
@@ -571,6 +607,12 @@ interface Source {
     label?: string;
     /** The text itself. */
     text: string;
+    /**
+     * A cap on this source's own characters, applied before the coercion's
+     * total `maxInputChars`, so one huge page cannot starve the others. Cut
+     * with the coercion's `truncate` policy.
+     */
+    maxChars?: number;
 }
 /**
  * What a coercion accepts as input: a plain string, one labelled source, or
@@ -637,7 +679,9 @@ interface BudgetResult {
 /**
  * Fit a set of sources into a character budget.
  *
- * The budget covers the sources' text as a whole. When they exceed it, it is
+ * A source's own `maxChars` is applied first, on its own, so a page known to
+ * be huge can be capped without starving the sources beside it. Then the
+ * total budget, when there is one, covers the sources' text as a whole. When they exceed it, it is
  * shared out so that every source that fits within an equal share keeps all
  * of its text, and what those leave unused goes to the longer ones. A short
  * email next to a long scraped page is therefore never touched; the page
@@ -645,7 +689,7 @@ interface BudgetResult {
  * so the model knows the text is incomplete rather than reading a
  * mid-sentence stop as the end.
  */
-declare function budgetSources(sources: readonly Source[], maxChars: number, policy?: TruncatePolicy): BudgetResult;
+declare function budgetSources(sources: readonly Source[], maxChars: number | undefined, policy?: TruncatePolicy): BudgetResult;
 
 /**
  * What to do with a present field that fails validation.
@@ -750,6 +794,8 @@ interface ProvenanceResult<T> {
      * default `"throw"` policy, or when the response validated cleanly.
      */
     issues: ResolvedIssue[];
+    /** Token usage summed over every call the coercion made. */
+    usage: CoerceUsage;
 }
 /**
  * Extra prompt guidance for a provenance run.
@@ -765,6 +811,13 @@ interface ProvenanceOptions {
      * Each annotation then also asks which source the value was read from.
      */
     sourceLabels?: readonly string[];
+    /**
+     * Only these top-level fields are wrapped; every other field comes back
+     * as a plain value with no provenance. Halves the output on schemas where
+     * a human reviews a handful of fields and code checks the rest. All
+     * fields when absent.
+     */
+    fields?: readonly string[];
 }
 /**
  * The provenance guidance for a run, extended with the source rule when the
@@ -836,6 +889,33 @@ interface CoerceOptions {
      * event.
      */
     onInvalidField?: InvalidFieldPolicy;
+    /**
+     * With `coerceWithProvenance` / `partialCoerceWithProvenance`: annotate only
+     * these top-level fields. The rest come back plain, which roughly halves
+     * the output when a human reviews a few fields and code checks the others.
+     * Ignored by the plain coercions.
+     */
+    provenanceFields?: readonly string[];
+    /**
+     * How many times to ask again when a non-empty input yields no fields at
+     * all. Default 0. A model occasionally answers `{}` for a page it could
+     * read; the retry tells it so and asks for every stated value. Counts
+     * separately from `maxRepairAttempts`.
+     */
+    retryOnEmpty?: number;
+    /**
+     * Extra guidance for this extraction that is not part of the schema: facts
+     * about the source ("prices on this site are in cents"), context the model
+     * cannot see ("the property is in Portugal, so assume EUR"), or judgement
+     * calls ("guest counts exclude infants"). Rendered as its own section at
+     * the end of the system prompt, so it stays on the instruction side of the
+     * data boundary that source blocks are excluded from — a hint placed inside
+     * a source would be ignored by design.
+     *
+     * Reaches every call of the run, repairs included, and is part of what a
+     * recording is keyed on.
+     */
+    instructions?: string | readonly string[];
     /**
      * Cap on the total characters of source text sent to the model, applied
      * after `preprocess`. Sources over the cap are cut per `truncate`, each
@@ -856,6 +936,27 @@ interface CoerceOptions {
 }
 /** A hook applied to each source before it is budgeted and rendered. */
 type PreprocessSource = (source: Source, index: number) => Source | string | Promise<Source | string>;
+/**
+ * Token accounting for a whole coercion, summed over every provider call it
+ * made — the first attempt, repairs, and empty-result retries.
+ */
+interface CoerceUsage {
+    /** Provider calls made. */
+    calls: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** The result of a detailed coercion: the data plus what it cost to get it. */
+interface CoerceDetails<T> {
+    data: T;
+    /** Issues the `onInvalidField` policy absorbed. Empty under `"throw"`. */
+    issues: ResolvedIssue[];
+    /** Token usage summed over every call the coercion made. */
+    usage: CoerceUsage;
+}
 /**
  * Coerce user input into a fully validated instance of the target schema.
  * Throws CoerceError if validation fails (required fields missing, type
@@ -871,6 +972,44 @@ declare function coerce<T>(input: CoerceInput, options: CoerceOptions): Promise<
  * cannot be resolved.
  */
 declare function partialCoerce<T>(input: CoerceInput, options: CoerceOptions): Promise<Partial<T>>;
+/**
+ * Like {@link coerce}, but also returns the issues the `onInvalidField` policy
+ * absorbed and the token usage of every call made — without the cost of
+ * provenance. The one to use when a pipeline accounts for spend or shows
+ * dropped fields but never needs per-field confidence.
+ */
+declare function coerceDetailed<T>(input: CoerceInput, options: CoerceOptions): Promise<CoerceDetails<T>>;
+/** Like {@link partialCoerce}, with the issues and usage of {@link coerceDetailed}. */
+declare function partialCoerceDetailed<T>(input: CoerceInput, options: CoerceOptions): Promise<CoerceDetails<Partial<T>>>;
+/** What {@link primeCache} produced: a record that the prefix was sent once. */
+interface PrimedPrefix {
+    schemaId: string;
+    mode: "coerce" | "partialCoerce";
+    provenance: boolean;
+    /** Usage of the warm-up call. `cacheWriteTokens` shows the prefix landed. */
+    usage: CoerceUsage;
+    primedAt: string;
+}
+/** Options for {@link primeCache}: the coercion options the batch will use. */
+interface PrimeCacheOptions extends CoerceOptions {
+    mode?: "coerce" | "partialCoerce";
+    provenance?: boolean;
+}
+/**
+ * Send the stable prefix — system prompt and schema — once, ahead of a batch,
+ * so a provider that caches it writes the cache before the batch starts.
+ *
+ * Meant to overlap the caller's own preparation: start it while fetching
+ * pages, then pass the promise to `coerceMany` as `primed`. The batch then
+ * fans out at once instead of running its first item alone. The warm-up
+ * costs one call with a trivial input and a near-empty answer; the answer is
+ * not validated and never returned.
+ *
+ * Only the prefix matters, so the same options the batch will use must be
+ * passed — a different schema, mode, provenance setting or instructions is
+ * a different prefix and warms nothing.
+ */
+declare function primeCache(options: PrimeCacheOptions): Promise<PrimedPrefix>;
 /**
  * Like {@link coerce}, but each field also comes back with how well the input
  * supported it and the text it was read from.
@@ -890,25 +1029,44 @@ declare function coerceWithProvenance<T>(input: CoerceInput, options: CoerceOpti
  */
 declare function partialCoerceWithProvenance<T>(input: CoerceInput, options: CoerceOptions): Promise<ProvenanceResult<Partial<T>>>;
 
+/** What a batch accepts: an array, or anything that can be iterated, lazily or not. */
+type CoerceManyInputs = Iterable<CoerceInput> | AsyncIterable<CoerceInput>;
 /** Options for {@link coerceMany}. Everything in `CoerceOptions` applies to each item. */
-interface CoerceManyOptions extends CoerceOptions {
+interface CoerceManyOptions<T = unknown> extends CoerceOptions {
     /** How many items may be in flight at once. Default 4. */
     concurrency?: number;
     /** Which coercion to run per item. Default `"coerce"`. */
     mode?: "coerce" | "partialCoerce";
-    /** Ask for per-field provenance on every item. Default false. */
-    provenance?: boolean;
     /**
-     * Run the first item alone before fanning out, so a provider that caches
-     * the prompt prefix writes it once and every later item reads it. Costs
-     * one item's latency up front; saves a cache write per concurrent worker.
-     * Default true.
+     * Ask for provenance on every item: `true` for every field, or the names
+     * of the top-level fields to annotate. Default false.
+     */
+    provenance?: boolean | readonly string[];
+    /**
+     * How to warm a provider's prompt cache before fanning out, so the stable
+     * prefix is written once and every item reads it.
+     *
+     * - `true` (default): run the first item alone, then fan out. No extra
+     *   call, but the batch waits for one full item.
+     * - `"eager"`: send a warm-up call the moment the batch starts and fan out
+     *   as soon as it lands. One extra small call; no item waits on another.
+     *   The right choice when inputs stream in from an async iterable.
+     * - `false`: fan out immediately.
+     *
+     * Ignored when `primed` is given.
+     */
+    primeCache?: boolean | "eager";
+    /**
+     * A prefix already warmed with {@link primeCache}, or the promise of one.
+     * Start it while fetching inputs and hand it over here: the batch waits
+     * for it (not for an item) and then fans out. A warm-up that fails is
+     * traced and otherwise ignored — the batch runs, only colder.
      */
-    primeCache?: boolean;
+    primed?: PrimedPrefix | Promise<PrimedPrefix>;
     /** How the batch backs off when the provider pushes back. */
     retry?: RetryOptions;
     /** Called as each item settles, in completion order, for progress. */
-    onItem?: (result: CoerceManyResult<unknown>) => void;
+    onItem?: (result: CoerceManyResult<T>) => void;
     /** Stop starting new items; those not yet started fail with the reason. */
     signal?: AbortSignal;
 }
@@ -930,7 +1088,7 @@ interface RetryOptions {
     /** Longest pause, in milliseconds. Default 30000. */
     maxDelayMs?: number;
 }
-/** One item's outcome. `index` is its position in the input list. */
+/** One item's outcome. `index` is its position in the input sequence. */
 type CoerceManyResult<T> = {
     ok: true;
     index: number;
@@ -939,12 +1097,16 @@ type CoerceManyResult<T> = {
     provenance: Record<string, FieldProvenance>;
     /** Issues the `onInvalidField` policy absorbed for this item. */
     issues: ResolvedIssue[];
-    /** How many provider calls it took, repairs excluded. */
+    /** Token usage over every call this item made, repairs included. */
+    usage: CoerceUsage;
+    /** How many times the item was started, retries included. */
     attempts: number;
 } | {
     ok: false;
     index: number;
     error: unknown;
+    /** Usage of the calls made before giving up. */
+    usage: CoerceUsage;
     attempts: number;
 };
 /**
@@ -955,8 +1117,13 @@ type CoerceManyResult<T> = {
  * its own, so one bad listing cannot take down an import. Retryable provider
  * errors pause the whole batch and try the item again; anything else, a
  * `CoerceError` included, is that item's final answer.
+ *
+ * Inputs may be an array or any iterable, including an async one, so a
+ * batch can start while its inputs are still being fetched. Every span an
+ * item emits carries `itemIndex` (and `itemLabel` when the input is
+ * labelled), so a trace sink can attribute usage under concurrency.
  */
-declare function coerceMany<T>(inputs: readonly CoerceInput[], options: CoerceManyOptions): Promise<CoerceManyResult<T>[]>;
+declare function coerceMany<T>(inputs: CoerceManyInputs, options: CoerceManyOptions<T>): Promise<CoerceManyResult<T>[]>;
 
 /**
  * Build the input for a repair attempt: the original input (already rendered
@@ -988,6 +1155,10 @@ interface SemblGlobalConfig {
     maxRepairAttempts?: number;
     /** What to do with a present field that fails validation. Default "throw". */
     onInvalidField?: InvalidFieldPolicy;
+    /** Extra guidance rendered into every system prompt. */
+    instructions?: string | readonly string[];
+    /** Retries when a non-empty input yields no fields. Default 0. */
+    retryOnEmpty?: number;
     /** Cap on total source characters sent to the model. Unbounded by default. */
     maxInputChars?: number;
     /** Which part of an over-budget source to cut. Default "tail". */
@@ -1011,6 +1182,10 @@ interface SemblCallConfig {
     maxRepairAttempts?: number;
     /** Override the invalid-field policy for this call */
     onInvalidField?: InvalidFieldPolicy;
+    /** Guidance for this call. Replaces, rather than extends, the global list. */
+    instructions?: string | readonly string[];
+    /** Override the empty-result retry budget for this call */
+    retryOnEmpty?: number;
     /** Override the input character budget for this call */
     maxInputChars?: number;
     /** Override the truncation policy for this call */
@@ -1028,6 +1203,8 @@ interface ResolvedConfig {
     traceSinks?: TraceSink[];
     maxRepairAttempts?: number;
     onInvalidField?: InvalidFieldPolicy;
+    instructions?: string | readonly string[];
+    retryOnEmpty?: number;
     maxInputChars?: number;
     truncate?: TruncatePolicy;
     preprocess?: PreprocessSource;
@@ -1116,7 +1293,18 @@ declare function sembl(input: CoerceInput | Record<string, unknown>, config?: Se
 interface PromptOptions {
     /** Legal values for dynamic enum sources, from `resolveEnumSources` */
     resolvedEnums?: ResolvedEnums;
+    /**
+     * Caller-supplied guidance for this extraction, rendered as its own section
+     * of the system prompt. Blank entries are dropped.
+     */
+    instructions?: string | readonly string[];
 }
+/**
+ * Normalise the `instructions` option to a list of non-empty lines. Throws
+ * for anything that is not a string or a list of strings, since a hint that
+ * silently rendered as "[object Object]" would be worse than none.
+ */
+declare function normalizeInstructions(instructions: string | readonly string[] | undefined): string[];
 /**
  * Build a system prompt that provides semantic context for the target schema.
  * This assembles the semantic hierarchy so the LLM understands the meaning
@@ -1149,7 +1337,13 @@ declare function validatePartial(data: Record<string, unknown>, schema: RuntimeS
  */
 declare class Tracer implements TraceContext {
     private sinks;
-    constructor(sinks?: TraceSink[]);
+    private readonly baseAttributes;
+    /**
+     * `baseAttributes` are merged into every span this tracer opens — how a
+     * batch stamps `itemIndex` on the spans of each item, so a sink can tell
+     * whose `llmCall` it is looking at under concurrency.
+     */
+    constructor(sinks?: TraceSink[], baseAttributes?: Record<string, unknown>);
     startSpan(name: string, attributes?: Record<string, unknown>, parent?: TraceSpan): TraceSpan;
     endSpan(span: TraceSpan): void;
     addEvent(span: TraceSpan, name: string, attributes?: Record<string, unknown>): void;
@@ -1162,4 +1356,4 @@ declare class ConsoleSink implements TraceSink {
     write(span: TraceSpan): void;
 }
 
-export { type BudgetResult, CoerceError, type CoerceInput, type CoerceManyOptions, type CoerceManyResult, type CoerceOptions, Coercible, ConsoleSink, Constrain, type DeepPartial, type DefinedSchema, Describe, type EnumResolution, EnumResolutionError, type EnumResolver, type EnumSourceFailure, type EnumSourceUsage, type FieldBuilder, type FieldConfidence, type FieldConstraints, type FieldDescriptor, type FieldProvenance, type FieldType, type FieldValidationIssue, type Infer, type InferFields, type InvalidFieldPolicy, type IssueResolution, type JsonSchemaDialect, type JsonSchemaOptions, PROVENANCE_INSTRUCTIONS, type PreprocessSource, type PromptOptions, type ProvenanceOptions, type ProvenanceResult, type Provider, type ProviderConfig, type ProviderRequest, type ProviderResponse, type ProviderUsage, type ResolveIssuesOptions, type ResolveIssuesResult, type ResolvedEnums, type ResolvedIssue, type RetryOptions, type RuntimeSchema, SOURCE_INSTRUCTIONS, Schema, type SchemaBundle, SchemaRegistry, type SemblCallConfig, SemblConfig, type SemblGlobalConfig, type Source, type TraceContext, type TraceEvent, type TraceSink, type TraceSpan, Tracer, type TruncatePolicy, type TruncationRecord, type ValidationOptions, ValuesFrom, budgetSources, buildPrompt, buildRepairInput, bundleOf, coerce, coerceMany, coerceWithProvenance, collectEnumSources, defineSchema, field, isCoerceInput, isSource, partialCoerce, partialCoerceWithProvenance, provenanceInstructions, renderSources, resolveEnumSources, resolveIssues, runtimeSchemaToJsonSchema, sembl, splitProvenance, toOpenAIJsonSchema, toProvenanceSchema, toSources, validatePartial, validateStrict };
+export { type BudgetResult, type CoerceDetails, CoerceError, type CoerceInput, type CoerceManyOptions, type CoerceManyResult, type CoerceOptions, type CoerceUsage, Coercible, ConsoleSink, Constrain, type DeepPartial, type DefinedSchema, Describe, type EnumResolution, EnumResolutionError, type EnumResolver, type EnumSourceFailure, type EnumSourceUsage, FIELD_FORMATS, type FieldBuilder, type FieldConfidence, type FieldConstraints, type FieldDescriptor, type FieldFormat, type FieldProvenance, type FieldType, type FieldValidationIssue, type Infer, type InferFields, type InvalidFieldPolicy, type IssueResolution, type JsonSchemaDialect, type JsonSchemaOptions, PROVENANCE_INSTRUCTIONS, type PreprocessSource, type PrimeCacheOptions, type PrimedPrefix, type PromptOptions, type ProvenanceOptions, type ProvenanceResult, type Provider, type ProviderConfig, type ProviderRequest, type ProviderResponse, type ProviderUsage, type ResolveIssuesOptions, type ResolveIssuesResult, type ResolvedEnums, type ResolvedIssue, type RetryOptions, type RuntimeSchema, SOURCE_INSTRUCTIONS, Schema, type SchemaBundle, SchemaRegistry, type SemblCallConfig, SemblConfig, type SemblGlobalConfig, type Source, type TraceContext, type TraceEvent, type TraceSink, type TraceSpan, Tracer, type TruncatePolicy, type TruncationRecord, type ValidationOptions, ValuesFrom, budgetSources, buildPrompt, buildRepairInput, bundleOf, coerce, coerceDetailed, coerceMany, coerceWithProvenance, collectEnumSources, defineSchema, describeFormat, field, formatToJsonSchema, isCoerceInput, isSource, normalizeInstructions, partialCoerce, partialCoerceDetailed, partialCoerceWithProvenance, primeCache, provenanceInstructions, renderSources, resolveEnumSources, resolveIssues, runtimeSchemaToJsonSchema, sembl, splitProvenance, toOpenAIJsonSchema, toProvenanceSchema, toSources, validateFormat, validatePartial, validateStrict };