@sembl/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,742 @@
+/**
+ * Bounds a field's value beyond its type.
+ *
+ * Which keys apply depends on the value being checked, not on the declared
+ * field type: string bounds apply to strings, numeric bounds to numbers, and
+ * item bounds to arrays. On an array field the string/number bounds apply to
+ * each element, so `string[]` can carry both `maxItems` and `maxLength`.
+ */
+interface FieldConstraints {
+    /** Maximum string length, inclusive */
+    maxLength?: number;
+    /** Minimum string length, inclusive */
+    minLength?: number;
+    /** Minimum numeric value, inclusive */
+    minimum?: number;
+    /** Maximum numeric value, inclusive */
+    maximum?: number;
+    /** Minimum number of array entries, inclusive */
+    minItems?: number;
+    /** Maximum number of array entries, inclusive */
+    maxItems?: number;
+    /** Regular expression source a string value must match */
+    pattern?: string;
+}
+/**
+ * Describes the type of a schema field.
+ *
+ * `enum` values are fixed when the schema is compiled. `dynamicEnum` defers
+ * them to coercion time, naming a source the caller resolves — for value sets
+ * that live in a database or CMS rather than in the source tree.
+ */
+type FieldType = {
+    kind: "string";
+} | {
+    kind: "number";
+} | {
+    kind: "boolean";
+} | {
+    kind: "array";
+    items: FieldType;
+} | {
+    kind: "object";
+    nestedSchemaId: string;
+} | {
+    kind: "enum";
+    values: string[];
+} | {
+    kind: "dynamicEnum";
+    sourceId: string;
+};
+/**
+ * Describes a single field in a schema.
+ */
+interface FieldDescriptor {
+    /** Property name as it appears in the class */
+    name: string;
+    /** Semantic description from @Describe decorator */
+    description: string;
+    /** The resolved type of this field */
+    type: FieldType;
+    /** Whether this field is required (definite assignment) */
+    required: boolean;
+    /** Value bounds from the @Constrain decorator, if any */
+    constraints?: FieldConstraints;
+}
+/**
+ * A compiled runtime schema representing a decorated class.
+ */
+interface RuntimeSchema {
+    /** Unique identifier, typically the class name */
+    id: string;
+    /** Semantic description from @Schema decorator */
+    description: string;
+    /** All fields extracted from the class */
+    fields: FieldDescriptor[];
+}
+/**
+ * A bundle of all schemas extracted from a set of source files.
+ */
+interface SchemaBundle {
+    /** Map of schema ID to RuntimeSchema */
+    schemas: Record<string, RuntimeSchema>;
+}
+
+/**
+ * Supplies the legal values for a `dynamicEnum` source at coercion time.
+ *
+ * Sources are opaque to SEMBL: the id is whatever the schema author wrote in
+ * `@ValuesFrom("...")`, and the caller decides how to turn it into values (a
+ * CMS fetch, a database query, a static map). Called at most once per distinct
+ * source id per coercion; the caller owns any caching across coercions.
+ *
+ * ```ts
+ * const enumResolver: EnumResolver = async (sourceId) => {
+ *   const docs = await cms.taxonomy(sourceId);
+ *   return docs.map((d) => d.slug);
+ * };
+ * ```
+ */
+type EnumResolver = (sourceId: string) => readonly string[] | Promise<readonly string[]>;
+/**
+ * The legal values for every enum source that resolved successfully,
+ * keyed by source id.
+ *
+ * A source id absent from this map is *unresolved* — the field it backs falls
+ * back to a free-form string. Successful resolution always yields a non-empty
+ * array; an empty result is treated as a failure, not as "no legal values",
+ * because a field with zero legal values is unsatisfiable.
+ */
+type ResolvedEnums = Readonly<Record<string, readonly string[]>>;
+
+type JsonSchema = Record<string, unknown>;
+/**
+ * Which flavour of JSON Schema to emit.
+ *
+ * - `"openai-strict"` — the subset OpenAI structured outputs accepts.
+ * - `"standard"` — ordinary JSON Schema, for validators and other providers.
+ */
+type JsonSchemaDialect = "openai-strict" | "standard";
+/**
+ * Options for JSON Schema generation.
+ */
+interface JsonSchemaOptions {
+    /** Legal values for dynamic enum sources, from `resolveEnumSources` */
+    resolvedEnums?: ResolvedEnums;
+    /** Target dialect. Defaults to `"openai-strict"`. */
+    dialect?: JsonSchemaDialect;
+}
+/**
+ * Convert a RuntimeSchema to a JSON Schema object.
+ *
+ * Under `"openai-strict"`, every property is listed in `required` and an
+ * optional field becomes `anyOf: [T, null]`, as structured outputs demand.
+ * Under `"standard"`, only genuinely required fields are listed and optional
+ * ones are simply absent — which is what keeps an unmentioned field
+ * distinguishable from one the model explicitly nulled.
+ *
+ * Both dialects inline nested schemas (no `$ref`) and set
+ * `additionalProperties: false`. Dynamic enum fields become a string `enum`
+ * when their source resolved, and a plain string otherwise. FieldConstraints
+ * are emitted only in `"standard"` — see {@link CONSTRAINT_KEYWORDS}.
+ */
+declare function runtimeSchemaToJsonSchema(schema: RuntimeSchema, bundle?: SchemaBundle, options?: JsonSchemaOptions): JsonSchema;
+/**
+ * Wrap a RuntimeSchema as a top-level JSON Schema suitable for
+ * OpenAI's response_format.json_schema.schema parameter.
+ */
+declare function toOpenAIJsonSchema(schema: RuntimeSchema, bundle?: SchemaBundle, options?: Omit<JsonSchemaOptions, "dialect">): JsonSchema;
+
+/**
+ * An enum source that could not be turned into a usable set of legal values.
+ */
+interface EnumSourceFailure {
+    /** The source id that failed */
+    sourceId: string;
+    /** Why it failed: the resolver threw, or it produced no values */
+    reason: "threw" | "empty";
+    /** The thrown value, when `reason` is "threw" */
+    cause?: unknown;
+    /**
+     * Whether a required field depends on this source. A field counts as
+     * required only if every object on the path to it is also required — an
+     * unreachable field cannot make a coercion fail.
+     */
+    required: boolean;
+    /** Field paths that reference this source, for error messages */
+    paths: string[];
+}
+/**
+ * The outcome of resolving every enum source a schema reaches.
+ */
+interface EnumResolution {
+    /** Legal values for each source that resolved successfully */
+    enums: ResolvedEnums;
+    /** Sources that threw or produced nothing */
+    failures: EnumSourceFailure[];
+}
+/** How a single enum source is reached from the root schema. */
+interface EnumSourceUsage {
+    /** Whether the source is reachable through an unbroken chain of required fields */
+    required: boolean;
+    /** Field paths that reference this source */
+    paths: string[];
+}
+/**
+ * Collect the distinct dynamic enum source ids a schema reaches, directly or
+ * through its bundle, along with whether each is reachable through a chain of
+ * required fields.
+ */
+declare function collectEnumSources(schema: RuntimeSchema, bundle?: SchemaBundle): Map<string, EnumSourceUsage>;
+/**
+ * Resolve every dynamic enum source a schema reaches, calling `resolver` once
+ * per distinct source id and awaiting all of them concurrently.
+ *
+ * Resolution never throws on the caller's behalf. A source whose resolver
+ * throws, or which yields no values, is reported in `failures` and left out of
+ * `enums` — downstream that means the field widens to a free-form string.
+ * Widening a *required* field is a silent correctness hole, so callers are
+ * expected to treat a failure with `required: true` as fatal; `coerce` and
+ * `partialCoerce` do exactly that.
+ */
+declare function resolveEnumSources(schema: RuntimeSchema, resolver: EnumResolver, bundle?: SchemaBundle): Promise<EnumResolution>;
+
+/**
+ * Registry for looking up compiled RuntimeSchemas by ID.
+ */
+declare class SchemaRegistry {
+    private schemas;
+    /**
+     * Register a single schema.
+     */
+    register(schema: RuntimeSchema): void;
+    /**
+     * Register all schemas from a bundle.
+     */
+    registerBundle(bundle: SchemaBundle): void;
+    /**
+     * Look up a schema by ID.
+     */
+    get(id: string): RuntimeSchema | undefined;
+    /**
+     * Get a schema by ID, throwing if not found.
+     */
+    require(id: string): RuntimeSchema;
+    /**
+     * Get a SchemaBundle of all registered schemas.
+     */
+    toBundle(): SchemaBundle;
+    /**
+     * Get all registered schema IDs.
+     */
+    ids(): string[];
+}
+
+/**
+ * Class decorator marking a schema class with a semantic description.
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function Schema(description: string): ClassDecorator;
+/**
+ * Property decorator providing a field-level semantic description.
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function Describe(description: string): PropertyDecorator;
+/**
+ * Property decorator bounding a field's legal values — lengths, numeric
+ * ranges, array sizes, a pattern.
+ *
+ * Takes an object literal of compile-time constants; the compiler reads it
+ * from source, so computed expressions are not supported.
+ *
+ * ```ts
+ * @Describe("Display name for the listing.")
+ * @Constrain({ maxLength: 40 })
+ * name!: string;
+ * ```
+ *
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function Constrain(constraints: FieldConstraints): PropertyDecorator;
+/**
+ * Property decorator declaring that a field's legal values come from a named
+ * source resolved at coercion time rather than from the source tree — a CMS
+ * taxonomy, a database enum table.
+ *
+ * Applies to a string field or to the element type of a string array. The
+ * caller supplies an `EnumResolver` that maps `sourceId` to the legal values.
+ *
+ * ```ts
+ * @Describe("Amenities the property offers.")
+ * @ValuesFrom("amenities")
+ * amenities!: string[];
+ * ```
+ *
+ * No-op at runtime — parsed by the compiler from source AST.
+ */
+declare function ValuesFrom(sourceId: string): PropertyDecorator;
+
+/**
+ * Recursively makes all properties optional, including nested objects.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * Describes a single validation issue on a field.
+ */
+interface FieldValidationIssue {
+    /** Dot-separated path to the field, e.g. "address.city" */
+    path: string;
+    /** What went wrong */
+    message: string;
+    /** The value that was received, if any */
+    received?: unknown;
+}
+/**
+ * Error thrown when coercion validation fails.
+ */
+declare class CoerceError extends Error {
+    readonly issues: FieldValidationIssue[];
+    constructor(issues: FieldValidationIssue[]);
+}
+
+/**
+ * Error thrown when an enum source backing a required field could not be
+ * resolved.
+ *
+ * Falling back to a free-form string here would let the model invent values
+ * that pass coercion and fail downstream, so a required field with a dead
+ * taxonomy is a hard failure rather than a widening.
+ */
+declare class EnumResolutionError extends Error {
+    readonly failures: EnumSourceFailure[];
+    constructor(failures: EnumSourceFailure[]);
+}
+
+/**
+ * Configuration for a provider.
+ */
+interface ProviderConfig {
+    /** Model identifier, e.g. "gpt-4o" */
+    model: string;
+    /** Optional temperature override (0-2) */
+    temperature?: number;
+    /** Optional max tokens for the response */
+    maxTokens?: number;
+}
+/**
+ * Request sent to a provider for structured output.
+ */
+interface ProviderRequest {
+    /** System prompt with semantic context */
+    systemPrompt: string;
+    /** User input to coerce */
+    userInput: string;
+    /** JSON Schema for structured output */
+    jsonSchema: Record<string, unknown>;
+    /** The runtime schema being targeted */
+    schema: RuntimeSchema;
+    /**
+     * Bundle used to resolve nested schemas, when one was supplied.
+     *
+     * `jsonSchema` above is already built against this bundle in the
+     * OpenAI-strict dialect. Providers whose API wants a different dialect
+     * should re-derive from `schema` + `bundle` rather than reaching for
+     * `schema` alone — dropping the bundle silently emits nested objects with
+     * no properties.
+     */
+    bundle?: SchemaBundle;
+    /**
+     * Legal values for the schema's `dynamicEnum` sources, already resolved.
+     * A provider that re-derives its own JSON Schema must pass these along —
+     * dropping them silently widens those fields back to free-form strings.
+     */
+    resolvedEnums?: ResolvedEnums;
+}
+/**
+ * Token accounting for a single provider call.
+ *
+ * The cache fields are reported as the provider reports them, and providers
+ * disagree about whether cached tokens also appear in `promptTokens` — so read
+ * them as an effectiveness signal, not as terms to add up. Each provider's
+ * README states which convention it follows.
+ */
+interface ProviderUsage {
+    /** Input tokens, as the provider counts them. */
+    promptTokens: number;
+    /** Output tokens generated. */
+    completionTokens: number;
+    /** `promptTokens + completionTokens`. */
+    totalTokens: number;
+    /**
+     * Input tokens served from a prompt cache, when the provider reports it.
+     * Growing to cover the stable prefix across a batch is the signal that
+     * caching is working; a run of zeroes means it is not.
+     */
+    cacheReadTokens?: number;
+    /**
+     * Input tokens written to a prompt cache, when the provider reports it.
+     * Expect this on the first call of a batch and near zero afterwards; a
+     * write on every call means the cached prefix is being invalidated.
+     */
+    cacheWriteTokens?: number;
+}
+/**
+ * Response from a provider.
+ */
+interface ProviderResponse {
+    /** The parsed structured output */
+    data: Record<string, unknown>;
+    /** Raw response metadata for tracing */
+    usage?: ProviderUsage;
+}
+/**
+ * Interface that LLM providers must implement.
+ */
+interface Provider {
+    /**
+     * Send a structured output request to the LLM.
+     */
+    complete(request: ProviderRequest): Promise<ProviderResponse>;
+}
+
+/**
+ * A discrete event within a trace span.
+ */
+interface TraceEvent {
+    /** Event name */
+    name: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Arbitrary attributes */
+    attributes?: Record<string, unknown>;
+}
+/**
+ * A span representing a unit of work in the coercion pipeline.
+ */
+interface TraceSpan {
+    /** Unique span ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp (set when span completes) */
+    endTime?: number;
+    /** Events recorded during this span */
+    events: TraceEvent[];
+    /** Arbitrary attributes */
+    attributes?: Record<string, unknown>;
+    /** Parent span ID, if nested */
+    parentId?: string;
+}
+/**
+ * Sink that receives completed trace spans.
+ */
+interface TraceSink {
+    /** Called when a span is completed */
+    write(span: TraceSpan): void;
+}
+/**
+ * Context for tracing within a coercion call.
+ */
+interface TraceContext {
+    /** Start a new span */
+    startSpan(name: string, attributes?: Record<string, unknown>): TraceSpan;
+    /** End a span and dispatch to sinks */
+    endSpan(span: TraceSpan): void;
+    /** Add an event to the current span */
+    addEvent(span: TraceSpan, name: string, attributes?: Record<string, unknown>): void;
+}
+
+/**
+ * How well the input supported a value.
+ *
+ * A three-level scale rather than a number: models are poorly calibrated at
+ * producing a 0–1 score, and a review UI only ever needs to decide whether to
+ * flag a field for a human anyway.
+ */
+type FieldConfidence = "high" | "medium" | "low";
+/** Where a coerced field's value came from. */
+interface FieldProvenance {
+    /** How well the input supported this value. */
+    confidence: FieldConfidence;
+    /**
+     * The span of input the value was read from, quoted. Absent when the value
+     * was inferred rather than read — which is itself the signal worth showing.
+     */
+    evidence?: string;
+}
+/** A coercion result paired with per-field provenance. */
+interface ProvenanceResult<T> {
+    /** The coerced data, in the shape of the target schema. */
+    data: T;
+    /** Provenance for each top-level field the model returned, keyed by name. */
+    provenance: Record<string, FieldProvenance>;
+}
+/**
+ * Extra prompt guidance for a provenance run.
+ *
+ * The JSON Schema already forces the shape; what it cannot convey is how to
+ * judge confidence, which is the whole point of asking.
+ */
+declare const PROVENANCE_INSTRUCTIONS: string;
+/**
+ * Derive the schema to actually request when provenance is wanted: the same
+ * fields, each wrapped in `{ value, confidence, evidence }`.
+ *
+ * Only top-level fields are annotated. A nested object keeps its ordinary
+ * shape inside `value`, so provenance is reported for the object as a whole
+ * rather than per leaf — annotating every leaf multiplies both the schema and
+ * the output for detail a review UI rarely acts on.
+ *
+ * Returns a bundle carrying the wrapper, the per-field annotation schemas, and
+ * everything the original bundle held, so nested types still inline.
+ */
+declare function toProvenanceSchema(schema: RuntimeSchema, bundle?: SchemaBundle): {
+    schema: RuntimeSchema;
+    bundle: SchemaBundle;
+};
+/**
+ * Split a provenance-shaped response back into plain data and per-field
+ * provenance.
+ *
+ * A field the model returned unwrapped — or wrapped without a usable
+ * `confidence` — still yields its value; the provenance is simply not
+ * recorded. Losing an annotation is not a reason to lose the extraction, and
+ * the missing key is visible to the caller.
+ */
+declare function splitProvenance(response: Record<string, unknown>, schema: RuntimeSchema): {
+    data: Record<string, unknown>;
+    provenance: Record<string, FieldProvenance>;
+};
+
+/**
+ * Options for coerce and partialCoerce.
+ */
+interface CoerceOptions {
+    /** The LLM provider to use */
+    provider: Provider;
+    /** The target schema */
+    schema: RuntimeSchema;
+    /** Optional bundle for resolving nested schemas */
+    bundle?: SchemaBundle;
+    /** Optional resolver for @ValuesFrom enum sources */
+    enumResolver?: EnumResolver;
+    /** Optional trace sinks */
+    traceSinks?: TraceSink[];
+    /**
+     * How many times to send validation failures back to the model for
+     * correction before giving up. Defaults to 0 — no repair.
+     *
+     * A repair costs an extra call only when validation actually failed, so the
+     * happy path is unaffected. It is off by default because it also multiplies
+     * worst-case latency, which a caller should opt into knowingly. For
+     * extraction from messy input — scraped HTML, third-party payloads — 1 is
+     * usually the right setting.
+     */
+    maxRepairAttempts?: number;
+}
+/**
+ * Coerce user input into a fully validated instance of the target schema.
+ * Throws CoerceError if validation fails (required fields missing, type
+ * mismatches, constraint violations, values outside a resolved taxonomy).
+ * Throws EnumResolutionError if a required field's enum source cannot be resolved.
+ */
+declare function coerce<T>(input: string, options: CoerceOptions): Promise<T>;
+/**
+ * Coerce user input into a partial instance of the target schema.
+ * Only validates types of fields that are present; never throws for missing fields.
+ * Throws CoerceError only if present fields have type mismatches or violate
+ * their constraints, and EnumResolutionError if a required field's enum source
+ * cannot be resolved.
+ */
+declare function partialCoerce<T>(input: string, options: CoerceOptions): Promise<Partial<T>>;
+/**
+ * Like {@link coerce}, but each field also comes back with how well the input
+ * supported it and the text it was read from.
+ *
+ * Costs a larger schema and a longer response, so reach for it where a human
+ * reviews the result — a pre-filled form that should flag its guesses — rather
+ * than on a hot path.
+ */
+declare function coerceWithProvenance<T>(input: string, options: CoerceOptions): Promise<ProvenanceResult<T>>;
+/**
+ * Like {@link partialCoerce}, but each field also comes back with how well the
+ * input supported it and the text it was read from.
+ *
+ * This is the one a form pre-fill usually wants: fields the input never
+ * mentioned are simply absent, and the ones that are present say how much to
+ * trust them.
+ */
+declare function partialCoerceWithProvenance<T>(input: string, options: CoerceOptions): Promise<ProvenanceResult<Partial<T>>>;
+
+/**
+ * Build the input for a repair attempt: the original input, the output that
+ * was rejected, and what was wrong with it.
+ *
+ * The `Provider` interface is single-turn, so the correction has to travel as
+ * user text rather than as a real assistant turn. In practice that reads to
+ * the model the same way, and it keeps repair working on every provider
+ * without widening the provider contract. Exported so a caller who wants
+ * different wording can build their own and call the provider directly.
+ */
+declare function buildRepairInput(originalInput: string, rejected: Record<string, unknown>, issues: FieldValidationIssue[]): string;
+
+/**
+ * Configuration options shared by global and per-call config.
+ */
+interface SemblGlobalConfig {
+    /** The LLM provider to use */
+    provider?: Provider;
+    /** Optional bundle for resolving nested schemas */
+    bundle?: SchemaBundle;
+    /** Optional resolver for @ValuesFrom enum sources */
+    enumResolver?: EnumResolver;
+    /** Optional trace sinks */
+    traceSinks?: TraceSink[];
+    /** How many times to send validation failures back for correction. Default 0. */
+    maxRepairAttempts?: number;
+}
+/**
+ * Per-call configuration overrides passed to `sembl()`.
+ */
+interface SemblCallConfig {
+    /** Override the LLM provider for this call */
+    provider?: Provider;
+    /** Override the bundle for this call */
+    bundle?: SchemaBundle;
+    /** Override the enum source resolver for this call */
+    enumResolver?: EnumResolver;
+    /** Override trace sinks for this call */
+    traceSinks?: TraceSink[];
+    /** Override the repair attempt budget for this call */
+    maxRepairAttempts?: number;
+}
+/**
+ * Resolved configuration with a guaranteed provider.
+ */
+interface ResolvedConfig {
+    provider: Provider;
+    bundle?: SchemaBundle;
+    enumResolver?: EnumResolver;
+    traceSinks?: TraceSink[];
+    maxRepairAttempts?: number;
+}
+/**
+ * Global configuration singleton for SEMBL.
+ */
+declare class SemblConfig {
+    private static _config;
+    /** Set global defaults. */
+    static configure(config: SemblGlobalConfig): void;
+    /** Reset global config to empty (useful in tests). */
+    static reset(): void;
+    /** Read-only access to the current global config. */
+    static get current(): Readonly<SemblGlobalConfig>;
+}
+
+/**
+ * A chainable, thenable wrapper around coercion results.
+ *
+ * Each `.coerceTo()` / `.partialCoerceTo()` call eagerly triggers an LLM call,
+ * serializing the previous result as the input string for the next step.
+ *
+ * Implements `PromiseLike<T>` so it can be `await`ed directly.
+ *
+ * There is no provenance variant here: an intermediate link's annotations
+ * would be serialized into the next call's input and lost, and a terminal one
+ * would have to return a different shape than every other link. Use
+ * `coerceWithProvenance` / `partialCoerceWithProvenance` directly instead.
+ */
+declare class Coercible<T> implements PromiseLike<T> {
+    private readonly _promise;
+    private readonly _config;
+    constructor(_promise: Promise<T>, _config: ResolvedConfig);
+    /** The per-call options every link in the chain shares. */
+    private _optionsFor;
+    /**
+     * Chain a full coercion to a new schema.
+     * The current value is serialized and used as input for the next LLM call.
+     */
+    coerceTo<U>(schema: RuntimeSchema): Coercible<U>;
+    /**
+     * Chain a partial coercion to a new schema.
+     * The current value is serialized and used as input for the next LLM call.
+     */
+    partialCoerceTo<U>(schema: RuntimeSchema): Coercible<Partial<U>>;
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
+}
+/**
+ * Entry point for the fluent coercion API.
+ *
+ * Accepts a string or object as input. Objects are JSON-serialized.
+ * Returns a `Coercible<string>` that can be chained with `.coerceTo()` / `.partialCoerceTo()`.
+ *
+ * @example
+ * ```ts
+ * SemblConfig.configure({ provider, bundle });
+ * const result = await sembl("some user input")
+ *   .partialCoerceTo(ProfileSchema)
+ *   .coerceTo(IntentSchema);
+ * ```
+ */
+declare function sembl(input: string | Record<string, unknown>, config?: SemblCallConfig): Coercible<string>;
+
+/**
+ * Options for prompt generation.
+ */
+interface PromptOptions {
+    /** Legal values for dynamic enum sources, from `resolveEnumSources` */
+    resolvedEnums?: ResolvedEnums;
+}
+/**
+ * Build a system prompt that provides semantic context for the target schema.
+ * This assembles the semantic hierarchy so the LLM understands the meaning
+ * of each field in context.
+ */
+declare function buildPrompt(schema: RuntimeSchema, bundle?: SchemaBundle, options?: PromptOptions): string;
+
+/**
+ * Options shared by both validation modes.
+ */
+interface ValidationOptions {
+    /** Legal values for dynamic enum sources, from `resolveEnumSources` */
+    resolvedEnums?: ResolvedEnums;
+}
+/**
+ * Validate data against a RuntimeSchema in strict mode.
+ * All required fields must be present and correctly typed.
+ * Returns validation issues (empty array means valid).
+ */
+declare function validateStrict(data: Record<string, unknown>, schema: RuntimeSchema, bundle?: SchemaBundle, options?: ValidationOptions): FieldValidationIssue[];
+/**
+ * Validate data against a RuntimeSchema in partial mode.
+ * Only validates types of fields that ARE present; never fails for missing fields.
+ * Returns validation issues (empty array means valid).
+ */
+declare function validatePartial(data: Record<string, unknown>, schema: RuntimeSchema, bundle?: SchemaBundle, options?: ValidationOptions): FieldValidationIssue[];
+
+/**
+ * Tracer implementation that creates spans, records events, and dispatches to sinks.
+ */
+declare class Tracer implements TraceContext {
+    private sinks;
+    constructor(sinks?: TraceSink[]);
+    startSpan(name: string, attributes?: Record<string, unknown>, parent?: TraceSpan): TraceSpan;
+    endSpan(span: TraceSpan): void;
+    addEvent(span: TraceSpan, name: string, attributes?: Record<string, unknown>): void;
+}
+
+/**
+ * Default trace sink that writes spans to the console.
+ */
+declare class ConsoleSink implements TraceSink {
+    write(span: TraceSpan): void;
+}
+
+export { CoerceError, type CoerceOptions, Coercible, ConsoleSink, Constrain, type DeepPartial, Describe, type EnumResolution, EnumResolutionError, type EnumResolver, type EnumSourceFailure, type EnumSourceUsage, type FieldConfidence, type FieldConstraints, type FieldDescriptor, type FieldProvenance, type FieldType, type FieldValidationIssue, type JsonSchemaDialect, type JsonSchemaOptions, PROVENANCE_INSTRUCTIONS, type PromptOptions, type ProvenanceResult, type Provider, type ProviderConfig, type ProviderRequest, type ProviderResponse, type ResolvedEnums, type RuntimeSchema, Schema, type SchemaBundle, SchemaRegistry, type SemblCallConfig, SemblConfig, type SemblGlobalConfig, type TraceContext, type TraceEvent, type TraceSink, type TraceSpan, Tracer, type ValidationOptions, ValuesFrom, buildPrompt, buildRepairInput, coerce, coerceWithProvenance, collectEnumSources, partialCoerce, partialCoerceWithProvenance, resolveEnumSources, runtimeSchemaToJsonSchema, sembl, splitProvenance, toOpenAIJsonSchema, toProvenanceSchema, validatePartial, validateStrict };