@sembl/core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -836,6 +836,19 @@ interface CoerceOptions {
      * event.
      */
     onInvalidField?: InvalidFieldPolicy;
+    /**
+     * 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
@@ -988,6 +1001,8 @@ 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[];
     /** 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 +1026,8 @@ 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 input character budget for this call */
     maxInputChars?: number;
     /** Override the truncation policy for this call */
@@ -1028,6 +1045,7 @@ interface ResolvedConfig {
     traceSinks?: TraceSink[];
     maxRepairAttempts?: number;
     onInvalidField?: InvalidFieldPolicy;
+    instructions?: string | readonly string[];
     maxInputChars?: number;
     truncate?: TruncatePolicy;
     preprocess?: PreprocessSource;
@@ -1116,7 +1134,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
@@ -1162,4 +1191,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, 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, normalizeInstructions, partialCoerce, partialCoerceWithProvenance, provenanceInstructions, renderSources, resolveEnumSources, resolveIssues, runtimeSchemaToJsonSchema, sembl, splitProvenance, toOpenAIJsonSchema, toProvenanceSchema, toSources, validatePartial, validateStrict };

package/dist/index.d.ts

@@ -836,6 +836,19 @@ interface CoerceOptions {
      * event.
      */
     onInvalidField?: InvalidFieldPolicy;
+    /**
+     * 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
@@ -988,6 +1001,8 @@ 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[];
     /** 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 +1026,8 @@ 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 input character budget for this call */
     maxInputChars?: number;
     /** Override the truncation policy for this call */
@@ -1028,6 +1045,7 @@ interface ResolvedConfig {
     traceSinks?: TraceSink[];
     maxRepairAttempts?: number;
     onInvalidField?: InvalidFieldPolicy;
+    instructions?: string | readonly string[];
     maxInputChars?: number;
     truncate?: TruncatePolicy;
     preprocess?: PreprocessSource;
@@ -1116,7 +1134,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
@@ -1162,4 +1191,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, 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, normalizeInstructions, partialCoerce, partialCoerceWithProvenance, provenanceInstructions, renderSources, resolveEnumSources, resolveIssues, runtimeSchemaToJsonSchema, sembl, splitProvenance, toOpenAIJsonSchema, toProvenanceSchema, toSources, validatePartial, validateStrict };

package/dist/index.js

@@ -443,6 +443,14 @@ var SOURCE_INSTRUCTIONS = [
 ].join("\n");
 
 // src/coerce/prompt-builder.ts
+function normalizeInstructions(instructions) {
+  if (instructions === void 0) return [];
+  const list = typeof instructions === "string" ? [instructions] : instructions;
+  if (!Array.isArray(list) || list.some((entry) => typeof entry !== "string")) {
+    throw new RangeError("instructions must be a string or an array of strings");
+  }
+  return list.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
 function describeConstraints(constraints) {
   if (!constraints) {
     return [];
@@ -565,6 +573,14 @@ function buildPrompt(schema, bundle, options = {}) {
   lines.push("- Interpret the user's input semantically \u2014 infer meaning, don't just pattern match.");
   lines.push("- Respect every stated limit exactly; truncate or drop lower-priority content to stay within it.");
   lines.push("- Return only the structured JSON output matching the schema.");
+  const instructions = normalizeInstructions(options.instructions);
+  if (instructions.length > 0) {
+    lines.push("");
+    lines.push("Additional guidance for this extraction:");
+    for (const instruction of instructions) {
+      lines.push(`- ${instruction}`);
+    }
+  }
   return lines.join("\n");
 }
 
@@ -1239,6 +1255,7 @@ async function runCoercion(input, options, { mode, provenance }) {
       `maxRepairAttempts must be a non-negative integer, got ${String(options.maxRepairAttempts)}`
     );
   }
+  const instructions = normalizeInstructions(options.instructions);
   const onInvalidField = options.onInvalidField ?? "throw";
   if (!INVALID_FIELD_POLICIES.includes(onInvalidField)) {
     throw new RangeError(
@@ -1269,11 +1286,12 @@ async function runCoercion(input, options, { mode, provenance }) {
       rootSpan
     );
     const promptSpan = tracer.startSpan("buildPrompt", {}, rootSpan);
-    const basePrompt = buildPrompt(schema, bundle, { resolvedEnums });
+    const basePrompt = buildPrompt(schema, bundle, { resolvedEnums, instructions });
     const systemPrompt = provenance ? `${basePrompt}
 ${provenanceInstructions({ sourceLabels })}` : basePrompt;
     tracer.addEvent(promptSpan, "promptBuilt", {
-      promptLength: systemPrompt.length
+      promptLength: systemPrompt.length,
+      instructionCount: instructions.length
     });
     tracer.endSpan(promptSpan);
     const request = provenance ? toProvenanceSchema(schema, bundle, { sourceLabels }) : { schema, bundle };
@@ -1559,6 +1577,7 @@ function resolveConfig(callConfig) {
     traceSinks: callConfig?.traceSinks ?? global.traceSinks,
     maxRepairAttempts: callConfig?.maxRepairAttempts ?? global.maxRepairAttempts,
     onInvalidField: callConfig?.onInvalidField ?? global.onInvalidField,
+    instructions: callConfig?.instructions ?? global.instructions,
     maxInputChars: callConfig?.maxInputChars ?? global.maxInputChars,
     truncate: callConfig?.truncate ?? global.truncate,
     preprocess: callConfig?.preprocess ?? global.preprocess
@@ -1592,6 +1611,7 @@ var Coercible = class _Coercible {
       traceSinks: this._config.traceSinks,
       maxRepairAttempts: this._config.maxRepairAttempts,
       onInvalidField: this._config.onInvalidField,
+      instructions: this._config.instructions,
       maxInputChars: this._config.maxInputChars,
       truncate: this._config.truncate,
       preprocess: this._config.preprocess
@@ -1676,6 +1696,7 @@ export {
   field,
   isCoerceInput,
   isSource,
+  normalizeInstructions,
   partialCoerce,
   partialCoerceWithProvenance,
   provenanceInstructions,