@sembl/core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -119,30 +119,28 @@ interface SchemaBundle {
 }
 
 /**
- * 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);
- * };
- * ```
+ * What a resolver is told about the source it is asked for, beyond its id:
+ * which schema is being coerced and where in it the source is used. One
+ * resolver can then serve several taxonomies, log which field asked, or
+ * refuse a source that a required field depends on but it cannot vouch for.
  */
-type EnumResolver = (sourceId: string) => readonly string[] | Promise<readonly string[]>;
+interface EnumResolverContext {
+    sourceId: string;
+    /** The schema being coerced — the root, not a nested one. */
+    schema: RuntimeSchema;
+    /** Whether a chain of required fields reaches the source. */
+    required: boolean;
+    /** Dotted paths of every field drawing from the source, e.g. `address.country`. */
+    paths: 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.
+ * Resolves the legal values of a `@ValuesFrom` source at coercion time.
+ * Called once per distinct source id per coercion; caching is the caller's.
+ * The context argument is optional to accept — a resolver that only needs
+ * the id can ignore it.
  */
+type EnumResolver = (sourceId: string, context: EnumResolverContext) => readonly string[] | Promise<readonly string[]>;
+/** Resolved values keyed by source id. */
 type ResolvedEnums = Readonly<Record<string, readonly string[]>>;
 
 type JsonSchema = Record<string, unknown>;
@@ -469,14 +467,35 @@ interface ProviderConfig {
     /** Optional max tokens for the response */
     maxTokens?: number;
 }
+/**
+ * One earlier turn of a repair conversation. An assistant turn is the
+ * structured output the model produced; a user turn is what was said about
+ * it. Providers render them natively — as a tool call and its result, or as
+ * assistant and user messages — so the model sees its own rejected answer
+ * as its own rather than quoted back to it.
+ */
+type ProviderTurn = {
+    role: "assistant";
+    data: Record<string, unknown>;
+} | {
+    role: "user";
+    text: string;
+};
 /**
  * Request sent to a provider for structured output.
  */
 interface ProviderRequest {
     /** System prompt with semantic context */
     systemPrompt: string;
-    /** User input to coerce */
+    /** User input to coerce — the first user turn of the conversation. */
     userInput: string;
+    /**
+     * Turns after `userInput`, in order, for a repair or an empty-result
+     * retry: the rejected output as an assistant turn, then the correction as
+     * a user turn, and so on. Only sent to a provider whose `supportsHistory`
+     * is true; other providers get the correction folded into `userInput`.
+     */
+    history?: ProviderTurn[];
     /** JSON Schema for structured output */
     jsonSchema: Record<string, unknown>;
     /** The runtime schema being targeted */
@@ -543,6 +562,12 @@ interface Provider {
      * Send a structured output request to the LLM.
      */
     complete(request: ProviderRequest): Promise<ProviderResponse>;
+    /**
+     * Whether `complete` renders `request.history` as real turns. Leave unset
+     * (false) and repair corrections arrive as text inside `userInput`
+     * instead, which every provider can handle.
+     */
+    readonly supportsHistory?: boolean;
 }
 
 /**
@@ -1138,6 +1163,12 @@ declare function coerceMany<T>(inputs: CoerceManyInputs, options: CoerceManyOpti
  * different wording can build their own and call the provider directly.
  */
 declare function buildRepairInput(originalInput: string, rejected: Record<string, unknown>, issues: FieldValidationIssue[]): string;
+/**
+ * The correction alone — what was wrong and what to do — for a provider that
+ * carries the rejected output as a real assistant turn, so the model does not
+ * need it quoted back.
+ */
+declare function buildRepairCorrection(issues: FieldValidationIssue[]): string;
 
 /**
  * Configuration options shared by global and per-call config.
@@ -1356,4 +1387,4 @@ declare class ConsoleSink implements TraceSink {
     write(span: TraceSpan): void;
 }
 
-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 };
+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 EnumResolverContext, 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 ProviderTurn, 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, buildRepairCorrection, 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 };

package/dist/index.d.ts

@@ -119,30 +119,28 @@ interface SchemaBundle {
 }
 
 /**
- * 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);
- * };
- * ```
+ * What a resolver is told about the source it is asked for, beyond its id:
+ * which schema is being coerced and where in it the source is used. One
+ * resolver can then serve several taxonomies, log which field asked, or
+ * refuse a source that a required field depends on but it cannot vouch for.
  */
-type EnumResolver = (sourceId: string) => readonly string[] | Promise<readonly string[]>;
+interface EnumResolverContext {
+    sourceId: string;
+    /** The schema being coerced — the root, not a nested one. */
+    schema: RuntimeSchema;
+    /** Whether a chain of required fields reaches the source. */
+    required: boolean;
+    /** Dotted paths of every field drawing from the source, e.g. `address.country`. */
+    paths: 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.
+ * Resolves the legal values of a `@ValuesFrom` source at coercion time.
+ * Called once per distinct source id per coercion; caching is the caller's.
+ * The context argument is optional to accept — a resolver that only needs
+ * the id can ignore it.
  */
+type EnumResolver = (sourceId: string, context: EnumResolverContext) => readonly string[] | Promise<readonly string[]>;
+/** Resolved values keyed by source id. */
 type ResolvedEnums = Readonly<Record<string, readonly string[]>>;
 
 type JsonSchema = Record<string, unknown>;
@@ -469,14 +467,35 @@ interface ProviderConfig {
     /** Optional max tokens for the response */
     maxTokens?: number;
 }
+/**
+ * One earlier turn of a repair conversation. An assistant turn is the
+ * structured output the model produced; a user turn is what was said about
+ * it. Providers render them natively — as a tool call and its result, or as
+ * assistant and user messages — so the model sees its own rejected answer
+ * as its own rather than quoted back to it.
+ */
+type ProviderTurn = {
+    role: "assistant";
+    data: Record<string, unknown>;
+} | {
+    role: "user";
+    text: string;
+};
 /**
  * Request sent to a provider for structured output.
  */
 interface ProviderRequest {
     /** System prompt with semantic context */
     systemPrompt: string;
-    /** User input to coerce */
+    /** User input to coerce — the first user turn of the conversation. */
     userInput: string;
+    /**
+     * Turns after `userInput`, in order, for a repair or an empty-result
+     * retry: the rejected output as an assistant turn, then the correction as
+     * a user turn, and so on. Only sent to a provider whose `supportsHistory`
+     * is true; other providers get the correction folded into `userInput`.
+     */
+    history?: ProviderTurn[];
     /** JSON Schema for structured output */
     jsonSchema: Record<string, unknown>;
     /** The runtime schema being targeted */
@@ -543,6 +562,12 @@ interface Provider {
      * Send a structured output request to the LLM.
      */
     complete(request: ProviderRequest): Promise<ProviderResponse>;
+    /**
+     * Whether `complete` renders `request.history` as real turns. Leave unset
+     * (false) and repair corrections arrive as text inside `userInput`
+     * instead, which every provider can handle.
+     */
+    readonly supportsHistory?: boolean;
 }
 
 /**
@@ -1138,6 +1163,12 @@ declare function coerceMany<T>(inputs: CoerceManyInputs, options: CoerceManyOpti
  * different wording can build their own and call the provider directly.
  */
 declare function buildRepairInput(originalInput: string, rejected: Record<string, unknown>, issues: FieldValidationIssue[]): string;
+/**
+ * The correction alone — what was wrong and what to do — for a provider that
+ * carries the rejected output as a real assistant turn, so the model does not
+ * need it quoted back.
+ */
+declare function buildRepairCorrection(issues: FieldValidationIssue[]): string;
 
 /**
  * Configuration options shared by global and per-call config.
@@ -1356,4 +1387,4 @@ declare class ConsoleSink implements TraceSink {
     write(span: TraceSpan): void;
 }
 
-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 };
+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 EnumResolverContext, 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 ProviderTurn, 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, buildRepairCorrection, 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 };

package/dist/index.js

@@ -318,7 +318,7 @@ async function resolveEnumSources(schema, resolver, bundle) {
   await Promise.all(
     [...usages].map(async ([sourceId, usage]) => {
       try {
-        const values = await resolver(sourceId);
+        const values = await resolver(sourceId, { sourceId, schema, ...usage });
         if (!values || values.length === 0) {
           failures.push({ sourceId, reason: "empty", ...usage });
           return;
@@ -756,7 +756,7 @@ function renderReceived(received) {
   return text.length > MAX_RECEIVED_LENGTH ? `${text.slice(0, MAX_RECEIVED_LENGTH)}\u2026 (truncated)` : text;
 }
 function buildRepairInput(originalInput, rejected, issues) {
-  const lines = [
+  return [
     originalInput,
     "",
     "---",
@@ -765,9 +765,11 @@ function buildRepairInput(originalInput, rejected, issues) {
     "",
     JSON.stringify(rejected, null, 2),
     "",
-    "It was rejected because:",
-    ""
-  ];
+    buildRepairCorrection(issues)
+  ].join("\n");
+}
+function buildRepairCorrection(issues) {
+  const lines = ["The output was rejected because:", ""];
   for (const issue of issues) {
     lines.push(`- ${issue.path}: ${issue.message} (received: ${renderReceived(issue.received)})`);
   }
@@ -1561,11 +1563,21 @@ async function runCoercion(input, options, { mode, provenance, traceAttributes }
     let issues = [];
     let run = { data: {}, provenance: {}, issues: [], usage };
     let emptyRetries = 0;
+    const multiTurn = provider.supportsHistory === true;
+    const history = [];
+    const followUp = (rejected, text, folded) => {
+      if (multiTurn) {
+        history.push({ role: "assistant", data: rejected }, { role: "user", text });
+      } else {
+        userInput = folded;
+      }
+    };
     for (let attempt = 0; attempt <= maxRepairAttempts; attempt++) {
-      const llmSpan = tracer.startSpan("llmCall", { attempt }, rootSpan);
+      const llmSpan = tracer.startSpan("llmCall", { attempt, turns: history.length }, rootSpan);
       const response = await provider.complete({
         systemPrompt,
         userInput,
+        ...history.length > 0 ? { history: [...history] } : {},
         jsonSchema,
         schema: prepared.schema,
         bundle: prepared.bundle,
@@ -1578,11 +1590,11 @@ async function runCoercion(input, options, { mode, provenance, traceAttributes }
       if (hasInput && emptyRetries < retryOnEmpty && isEmptyResult(run.data)) {
         emptyRetries += 1;
         tracer.addEvent(rootSpan, "emptyRetry", { retry: emptyRetries });
-        userInput = `${renderedInput}
+        followUp(response.data, EMPTY_RETRY_NOTE, `${renderedInput}
 
 ---
 
-${EMPTY_RETRY_NOTE}`;
+${EMPTY_RETRY_NOTE}`);
         attempt -= 1;
         continue;
       }
@@ -1623,7 +1635,11 @@ ${EMPTY_RETRY_NOTE}`;
           issueCount: issues.length,
           paths: issues.map((issue) => issue.path)
         });
-        userInput = buildRepairInput(renderedInput, run.data, issues);
+        followUp(
+          response.data,
+          buildRepairCorrection(issues),
+          buildRepairInput(renderedInput, run.data, issues)
+        );
       }
     }
     throw new CoerceError(issues);
@@ -2042,6 +2058,7 @@ export {
   ValuesFrom,
   budgetSources,
   buildPrompt,
+  buildRepairCorrection,
   buildRepairInput,
   bundleOf,
   coerce,