@docshield/didactic 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -1,10 +1,70 @@
+//#region src/optimizer/types.d.ts
+
+/**
+ * Inline optimization config for didactic.eval().
+ */
+type OptimizeConfig = {
+  systemPrompt: string;
+  patchSystemPrompt?: string;
+  mergeSystemPrompt?: string;
+  targetSuccessRate: number;
+  maxIterations?: number;
+  maxCost?: number;
+  apiKey: string;
+  storeLogs?: boolean | string;
+  provider: LLMProviders;
+  thinking?: boolean;
+};
+/**
+ * Result for a single optimization iteration.
+ */
+interface IterationResult<TInput = unknown, TOutput = unknown> {
+  iteration: number;
+  systemPrompt: string;
+  passed: number;
+  total: number;
+  testCases: TestCaseResult<TInput, TOutput>[];
+  cost: number;
+}
+/**
+ * Final result from optimization.
+ */
+interface OptimizeResult<TInput = unknown, TOutput = unknown> {
+  success: boolean;
+  finalPrompt: string;
+  iterations: IterationResult<TInput, TOutput>[];
+  totalCost: number;
+  logFolder?: string;
+}
+//#endregion
 //#region src/types.d.ts
+/**
+ * Supported LLM providers.
+ * Used by both optimizer and LLM-based comparators.
+ */
+declare enum LLMProviders {
+  anthropic_claude_opus = "anthropic_claude_opus",
+  anthropic_claude_sonnet = "anthropic_claude_sonnet",
+  anthropic_claude_haiku = "anthropic_claude_haiku",
+  openai_gpt5 = "openai_gpt5",
+  openai_gpt5_mini = "openai_gpt5_mini",
+}
 /**
  * Result returned by a comparator function.
  */
 interface ComparatorResult {
   passed: boolean;
   similarity?: number;
+  rationale?: string;
+  cost?: number;
+}
+/**
+ * LLM configuration for use by LLM-based comparators.
+ * Can be specified at the top level of eval config to avoid repeating apiKey.
+ */
+interface LLMConfig {
+  apiKey: string;
+  provider?: LLMProviders;
 }
 /**
  * Context passed to comparators for cross-field access.
@@ -12,15 +72,29 @@ interface ComparatorResult {
 interface ComparatorContext {
   expectedParent: unknown;
   actualParent: unknown;
+  llmConfig?: LLMConfig;
 }
 /**
  * A comparator function that compares expected vs actual.
+ * Can be synchronous or asynchronous (for LLM-based comparators).
  */
-type Comparator<T = unknown> = (expected: T, actual: T, context?: ComparatorContext) => ComparatorResult;
+type Comparator<T = unknown> = (expected: T, actual: T, context?: ComparatorContext) => ComparatorResult | Promise<ComparatorResult>;
 /**
- * A map of field names to comparators.
+ * Marker interface for comparators with ordering metadata.
+ * Created by the unordered() wrapper function.
  */
-type ComparatorMap = Record<string, Comparator<any>>;
+interface ComparatorWithOrdering<T = unknown> {
+  (expected: T, actual: T, context?: ComparatorContext): ComparatorResult | Promise<ComparatorResult>;
+  _unordered: true;
+  _nestedComparators?: NestedComparatorConfig;
+}
+/**
+ * Recursive comparator configuration that matches data shape.
+ * Can be a comparator function, a comparator with ordering, or a nested object.
+ */
+type NestedComparatorConfig = {
+  [key: string]: Comparator<any> | ComparatorWithOrdering<any> | NestedComparatorConfig;
+};
 /**
  * The result returned by an executor.
  */
@@ -40,19 +114,6 @@ interface TestCase<TInput = unknown, TOutput = unknown> {
   input: TInput;
   expected: TOutput;
 }
-/**
- * Inline optimization config for didactic.eval().
- */
-type OptimizeConfig = {
-  systemPrompt: string;
-  targetSuccessRate: number;
-  maxIterations?: number;
-  maxCost?: number;
-  apiKey: string;
-  storeLogs?: boolean | string;
-  provider: LLMProviders;
-  thinking?: boolean;
-};
 /**
  * Base eval configuration shared by both modes.
  */
@@ -61,23 +122,27 @@ interface BaseEvalConfig<TInput = unknown, TOutput = unknown> {
   executor: Executor<TInput, TOutput>;
   testCases: TestCase<TInput, TOutput>[];
   perTestThreshold?: number;
-  unorderedList?: boolean;
   optimize?: OptimizeConfig;
   rateLimitBatch?: number;
   rateLimitPause?: number;
+  llmConfig?: LLMConfig;
+  storeLogs?: boolean | string;
 }
 /**
- * Flexible comparators configuration.
- * Accepts either a single comparator function or a field mapping object.
- * Single comparator will apply the comparator to the object, primitive, list of objects, or list of primitives. If `unorderedList` is true, the comparator will be applied to the list of items in the array by similarity rather than index position.
+ * Top-level comparators configuration.
+ * Can be:
+ * - A single comparator function for root-level primitives/arrays (e.g., `exact`, `numeric`)
+ * - A ComparatorWithOrdering for unordered root-level arrays (e.g., `unordered(exact)`)
+ * - A nested object structure matching your data shape
  */
-type ComparatorsConfig = ComparatorMap | Comparator<any>;
+type ComparatorsConfig = NestedComparatorConfig | ComparatorWithOrdering<unknown> | Comparator<unknown>;
 /**
  * Main eval configuration.
- * Either `comparators` (field mapping or single function) OR `comparatorOverride` (whole-object) must be provided.
+ * - `comparators` (optional): field mapping or single comparator. Defaults to `exact` for entire shape.
+ * - `comparatorOverride`: whole-object comparison (bypasses field-level comparison).
  */
 type EvalConfig<TInput = unknown, TOutput = unknown> = (BaseEvalConfig<TInput, TOutput> & {
-  comparators: ComparatorsConfig;
+  comparators?: ComparatorsConfig;
   comparatorOverride?: undefined;
 }) | (BaseEvalConfig<TInput, TOutput> & {
   comparatorOverride: Comparator<TOutput>;
@@ -90,6 +155,8 @@ interface FieldResult {
   passed: boolean;
   expected: unknown;
   actual: unknown;
+  rationale?: string;
+  cost?: number;
 }
 /**
  * Result for a single test case.
@@ -100,6 +167,7 @@ interface TestCaseResult<TInput = unknown, TOutput = unknown> {
   actual?: TOutput;
   additionalContext?: unknown;
   cost?: number;
+  comparatorCost?: number;
   passed: boolean;
   fields: Record<string, FieldResult>;
   error?: string;
@@ -120,47 +188,11 @@ interface EvalResult<TInput = unknown, TOutput = unknown> {
   totalFields: number;
   accuracy: number;
   cost: number;
-}
-/**
- * Chat message for LLM calls.
- */
-interface Message {
-  role: 'system' | 'user' | 'assistant';
-  content: string;
-}
-/**
- * Supported LLM providers.
- */
-declare enum LLMProviders {
-  anthropic_claude_opus = "anthropic_claude_opus",
-  anthropic_claude_sonnet = "anthropic_claude_sonnet",
-  anthropic_claude_haiku = "anthropic_claude_haiku",
-  openai_gpt5 = "openai_gpt5",
-  openai_gpt5_mini = "openai_gpt5_mini",
-}
-/**
- * Result for a single optimization iteration.
- */
-interface IterationResult<TInput = unknown, TOutput = unknown> {
-  iteration: number;
-  systemPrompt: string;
-  passed: number;
-  total: number;
-  testCases: TestCaseResult<TInput, TOutput>[];
-  cost: number;
-}
-/**
- * Final result from optimization.
- */
-interface OptimizeResult<TInput = unknown, TOutput = unknown> {
-  success: boolean;
-  finalPrompt: string;
-  iterations: IterationResult<TInput, TOutput>[];
-  totalCost: number;
+  comparatorCost: number;
   logFolder?: string;
 }
 //#endregion
-//#region src/executors.d.ts
+//#region src/eval/executors.d.ts
 /**
  * Configuration for endpoint executor.
  */
@@ -243,7 +275,7 @@ declare function fn<TInput, TOutput extends object, TRaw = TOutput>(config: FnCo
  */
 declare function mock<TInput, TOutput extends object>(outputsOrFn: TOutput[] | ((input: TInput, systemPrompt?: string) => TOutput)): Executor<TInput, TOutput>;
 //#endregion
-//#region src/comparators.d.ts
+//#region src/eval/comparators/comparators.d.ts
 /** Checks if actual string contains a substring. */
 declare function contains(substring: string): Comparator<string>;
 /** Creates a comparator with custom logic. */
@@ -269,14 +301,51 @@ declare function within(config: {
   tolerance: number;
   mode?: 'percentage' | 'absolute';
 }): Comparator<number>;
+/** Configuration for LLM-based comparison. */
+interface LLMCompareConfig {
+  provider?: LLMProviders;
+  /** API key for LLM provider. If not provided, uses llmConfig.apiKey from eval config. */
+  apiKey?: string;
+  systemPrompt?: string;
+}
+/**
+ * Uses an LLM to compare expected vs actual values.
+ * Returns a comparison result with rationale and cost tracking.
+ * Default provider: anthropic_claude_haiku (fastest, cheapest).
+ */
+declare function llmCompare(config: LLMCompareConfig): Comparator;
+/**
+ * Marks a comparator or comparator config as unordered.
+ * When applied to an array field, items will be matched by similarity
+ * rather than index position (using Hungarian algorithm).
+ *
+ * @example
+ * // Unordered array of objects
+ * lineItems: unordered({
+ *   description: name,
+ *   price: within({ tolerance: 5 })
+ * })
+ *
+ * @example
+ * // Unordered array of primitives
+ * tags: unordered(exact)
+ *
+ * @example
+ * // When entire output is an array
+ * comparators: unordered({
+ *   carrier: exact,
+ *   premium: within({ tolerance: 0.05 })
+ * })
+ */
+declare function unordered<T>(comparator: Comparator<T> | NestedComparatorConfig): ComparatorWithOrdering<T>;
 //#endregion
-//#region src/eval.d.ts
+//#region src/eval/eval.d.ts
 /**
  * Run all test cases and return results.
  */
 declare function evaluate<TInput, TOutput>(config: EvalConfig<TInput, TOutput>): Promise<EvalResult<TInput, TOutput>>;
 //#endregion
-//#region src/optimizer.d.ts
+//#region src/optimizer/optimizer.d.ts
 declare function optimize<TInput, TOutput>(evalConfig: EvalConfig<TInput, TOutput>, config: OptimizeConfig): Promise<OptimizeResult<TInput, TOutput>>;
 //#endregion
 //#region src/index.d.ts
@@ -335,5 +404,5 @@ declare const didactic: {
   fn<TInput, TOutput extends object>(config: FnConfig<TInput, TOutput>): Executor<TInput, TOutput>;
 };
 //#endregion
-export { type Comparator, type ComparatorContext, type ComparatorMap, type ComparatorResult, type ComparatorsConfig, type EndpointConfig, type EvalConfig, type EvalResult, type Executor, type ExecutorResult, type FieldResult, type FnConfig, type IterationResult, LLMProviders, type Message, type OptimizeConfig, type OptimizeResult, type TestCase, type TestCaseResult, contains, custom, date, didactic as default, didactic as didact, didactic, endpoint, evaluate, exact, fn, mock, name, numeric, oneOf, optimize, presence, within };
+export { type Comparator, type ComparatorContext, type ComparatorResult, type EndpointConfig, type EvalConfig, type EvalResult, type Executor, type ExecutorResult, type FnConfig, type LLMCompareConfig, type LLMConfig, LLMProviders, type OptimizeConfig, type OptimizeResult, type TestCase, type TestCaseResult, contains, custom, date, didactic as default, didactic as didact, didactic, endpoint, evaluate, exact, fn, llmCompare, mock, name, numeric, oneOf, optimize, presence, unordered, within };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/executors.ts","../src/comparators.ts","../src/eval.ts","../src/optimizer.ts","../src/index.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/optimizer/types.ts","../src/types.ts","../src/eval/executors.ts","../src/eval/comparators/comparators.ts","../src/eval/eval.ts","../src/optimizer/optimizer.ts","../src/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/index.d.mts

@@ -1,10 +1,70 @@
+//#region src/optimizer/types.d.ts
+
+/**
+ * Inline optimization config for didactic.eval().
+ */
+type OptimizeConfig = {
+  systemPrompt: string;
+  patchSystemPrompt?: string;
+  mergeSystemPrompt?: string;
+  targetSuccessRate: number;
+  maxIterations?: number;
+  maxCost?: number;
+  apiKey: string;
+  storeLogs?: boolean | string;
+  provider: LLMProviders;
+  thinking?: boolean;
+};
+/**
+ * Result for a single optimization iteration.
+ */
+interface IterationResult<TInput = unknown, TOutput = unknown> {
+  iteration: number;
+  systemPrompt: string;
+  passed: number;
+  total: number;
+  testCases: TestCaseResult<TInput, TOutput>[];
+  cost: number;
+}
+/**
+ * Final result from optimization.
+ */
+interface OptimizeResult<TInput = unknown, TOutput = unknown> {
+  success: boolean;
+  finalPrompt: string;
+  iterations: IterationResult<TInput, TOutput>[];
+  totalCost: number;
+  logFolder?: string;
+}
+//#endregion
 //#region src/types.d.ts
+/**
+ * Supported LLM providers.
+ * Used by both optimizer and LLM-based comparators.
+ */
+declare enum LLMProviders {
+  anthropic_claude_opus = "anthropic_claude_opus",
+  anthropic_claude_sonnet = "anthropic_claude_sonnet",
+  anthropic_claude_haiku = "anthropic_claude_haiku",
+  openai_gpt5 = "openai_gpt5",
+  openai_gpt5_mini = "openai_gpt5_mini",
+}
 /**
  * Result returned by a comparator function.
  */
 interface ComparatorResult {
   passed: boolean;
   similarity?: number;
+  rationale?: string;
+  cost?: number;
+}
+/**
+ * LLM configuration for use by LLM-based comparators.
+ * Can be specified at the top level of eval config to avoid repeating apiKey.
+ */
+interface LLMConfig {
+  apiKey: string;
+  provider?: LLMProviders;
 }
 /**
  * Context passed to comparators for cross-field access.
@@ -12,15 +72,29 @@ interface ComparatorResult {
 interface ComparatorContext {
   expectedParent: unknown;
   actualParent: unknown;
+  llmConfig?: LLMConfig;
 }
 /**
  * A comparator function that compares expected vs actual.
+ * Can be synchronous or asynchronous (for LLM-based comparators).
  */
-type Comparator<T = unknown> = (expected: T, actual: T, context?: ComparatorContext) => ComparatorResult;
+type Comparator<T = unknown> = (expected: T, actual: T, context?: ComparatorContext) => ComparatorResult | Promise<ComparatorResult>;
 /**
- * A map of field names to comparators.
+ * Marker interface for comparators with ordering metadata.
+ * Created by the unordered() wrapper function.
  */
-type ComparatorMap = Record<string, Comparator<any>>;
+interface ComparatorWithOrdering<T = unknown> {
+  (expected: T, actual: T, context?: ComparatorContext): ComparatorResult | Promise<ComparatorResult>;
+  _unordered: true;
+  _nestedComparators?: NestedComparatorConfig;
+}
+/**
+ * Recursive comparator configuration that matches data shape.
+ * Can be a comparator function, a comparator with ordering, or a nested object.
+ */
+type NestedComparatorConfig = {
+  [key: string]: Comparator<any> | ComparatorWithOrdering<any> | NestedComparatorConfig;
+};
 /**
  * The result returned by an executor.
  */
@@ -40,19 +114,6 @@ interface TestCase<TInput = unknown, TOutput = unknown> {
   input: TInput;
   expected: TOutput;
 }
-/**
- * Inline optimization config for didactic.eval().
- */
-type OptimizeConfig = {
-  systemPrompt: string;
-  targetSuccessRate: number;
-  maxIterations?: number;
-  maxCost?: number;
-  apiKey: string;
-  storeLogs?: boolean | string;
-  provider: LLMProviders;
-  thinking?: boolean;
-};
 /**
  * Base eval configuration shared by both modes.
  */
@@ -61,23 +122,27 @@ interface BaseEvalConfig<TInput = unknown, TOutput = unknown> {
   executor: Executor<TInput, TOutput>;
   testCases: TestCase<TInput, TOutput>[];
   perTestThreshold?: number;
-  unorderedList?: boolean;
   optimize?: OptimizeConfig;
   rateLimitBatch?: number;
   rateLimitPause?: number;
+  llmConfig?: LLMConfig;
+  storeLogs?: boolean | string;
 }
 /**
- * Flexible comparators configuration.
- * Accepts either a single comparator function or a field mapping object.
- * Single comparator will apply the comparator to the object, primitive, list of objects, or list of primitives. If `unorderedList` is true, the comparator will be applied to the list of items in the array by similarity rather than index position.
+ * Top-level comparators configuration.
+ * Can be:
+ * - A single comparator function for root-level primitives/arrays (e.g., `exact`, `numeric`)
+ * - A ComparatorWithOrdering for unordered root-level arrays (e.g., `unordered(exact)`)
+ * - A nested object structure matching your data shape
  */
-type ComparatorsConfig = ComparatorMap | Comparator<any>;
+type ComparatorsConfig = NestedComparatorConfig | ComparatorWithOrdering<unknown> | Comparator<unknown>;
 /**
  * Main eval configuration.
- * Either `comparators` (field mapping or single function) OR `comparatorOverride` (whole-object) must be provided.
+ * - `comparators` (optional): field mapping or single comparator. Defaults to `exact` for entire shape.
+ * - `comparatorOverride`: whole-object comparison (bypasses field-level comparison).
  */
 type EvalConfig<TInput = unknown, TOutput = unknown> = (BaseEvalConfig<TInput, TOutput> & {
-  comparators: ComparatorsConfig;
+  comparators?: ComparatorsConfig;
   comparatorOverride?: undefined;
 }) | (BaseEvalConfig<TInput, TOutput> & {
   comparatorOverride: Comparator<TOutput>;
@@ -90,6 +155,8 @@ interface FieldResult {
   passed: boolean;
   expected: unknown;
   actual: unknown;
+  rationale?: string;
+  cost?: number;
 }
 /**
  * Result for a single test case.
@@ -100,6 +167,7 @@ interface TestCaseResult<TInput = unknown, TOutput = unknown> {
   actual?: TOutput;
   additionalContext?: unknown;
   cost?: number;
+  comparatorCost?: number;
   passed: boolean;
   fields: Record<string, FieldResult>;
   error?: string;
@@ -120,47 +188,11 @@ interface EvalResult<TInput = unknown, TOutput = unknown> {
   totalFields: number;
   accuracy: number;
   cost: number;
-}
-/**
- * Chat message for LLM calls.
- */
-interface Message {
-  role: 'system' | 'user' | 'assistant';
-  content: string;
-}
-/**
- * Supported LLM providers.
- */
-declare enum LLMProviders {
-  anthropic_claude_opus = "anthropic_claude_opus",
-  anthropic_claude_sonnet = "anthropic_claude_sonnet",
-  anthropic_claude_haiku = "anthropic_claude_haiku",
-  openai_gpt5 = "openai_gpt5",
-  openai_gpt5_mini = "openai_gpt5_mini",
-}
-/**
- * Result for a single optimization iteration.
- */
-interface IterationResult<TInput = unknown, TOutput = unknown> {
-  iteration: number;
-  systemPrompt: string;
-  passed: number;
-  total: number;
-  testCases: TestCaseResult<TInput, TOutput>[];
-  cost: number;
-}
-/**
- * Final result from optimization.
- */
-interface OptimizeResult<TInput = unknown, TOutput = unknown> {
-  success: boolean;
-  finalPrompt: string;
-  iterations: IterationResult<TInput, TOutput>[];
-  totalCost: number;
+  comparatorCost: number;
   logFolder?: string;
 }
 //#endregion
-//#region src/executors.d.ts
+//#region src/eval/executors.d.ts
 /**
  * Configuration for endpoint executor.
  */
@@ -243,7 +275,7 @@ declare function fn<TInput, TOutput extends object, TRaw = TOutput>(config: FnCo
  */
 declare function mock<TInput, TOutput extends object>(outputsOrFn: TOutput[] | ((input: TInput, systemPrompt?: string) => TOutput)): Executor<TInput, TOutput>;
 //#endregion
-//#region src/comparators.d.ts
+//#region src/eval/comparators/comparators.d.ts
 /** Checks if actual string contains a substring. */
 declare function contains(substring: string): Comparator<string>;
 /** Creates a comparator with custom logic. */
@@ -269,14 +301,51 @@ declare function within(config: {
   tolerance: number;
   mode?: 'percentage' | 'absolute';
 }): Comparator<number>;
+/** Configuration for LLM-based comparison. */
+interface LLMCompareConfig {
+  provider?: LLMProviders;
+  /** API key for LLM provider. If not provided, uses llmConfig.apiKey from eval config. */
+  apiKey?: string;
+  systemPrompt?: string;
+}
+/**
+ * Uses an LLM to compare expected vs actual values.
+ * Returns a comparison result with rationale and cost tracking.
+ * Default provider: anthropic_claude_haiku (fastest, cheapest).
+ */
+declare function llmCompare(config: LLMCompareConfig): Comparator;
+/**
+ * Marks a comparator or comparator config as unordered.
+ * When applied to an array field, items will be matched by similarity
+ * rather than index position (using Hungarian algorithm).
+ *
+ * @example
+ * // Unordered array of objects
+ * lineItems: unordered({
+ *   description: name,
+ *   price: within({ tolerance: 5 })
+ * })
+ *
+ * @example
+ * // Unordered array of primitives
+ * tags: unordered(exact)
+ *
+ * @example
+ * // When entire output is an array
+ * comparators: unordered({
+ *   carrier: exact,
+ *   premium: within({ tolerance: 0.05 })
+ * })
+ */
+declare function unordered<T>(comparator: Comparator<T> | NestedComparatorConfig): ComparatorWithOrdering<T>;
 //#endregion
-//#region src/eval.d.ts
+//#region src/eval/eval.d.ts
 /**
  * Run all test cases and return results.
  */
 declare function evaluate<TInput, TOutput>(config: EvalConfig<TInput, TOutput>): Promise<EvalResult<TInput, TOutput>>;
 //#endregion
-//#region src/optimizer.d.ts
+//#region src/optimizer/optimizer.d.ts
 declare function optimize<TInput, TOutput>(evalConfig: EvalConfig<TInput, TOutput>, config: OptimizeConfig): Promise<OptimizeResult<TInput, TOutput>>;
 //#endregion
 //#region src/index.d.ts
@@ -335,5 +404,5 @@ declare const didactic: {
   fn<TInput, TOutput extends object>(config: FnConfig<TInput, TOutput>): Executor<TInput, TOutput>;
 };
 //#endregion
-export { type Comparator, type ComparatorContext, type ComparatorMap, type ComparatorResult, type ComparatorsConfig, type EndpointConfig, type EvalConfig, type EvalResult, type Executor, type ExecutorResult, type FieldResult, type FnConfig, type IterationResult, LLMProviders, type Message, type OptimizeConfig, type OptimizeResult, type TestCase, type TestCaseResult, contains, custom, date, didactic as default, didactic as didact, didactic, endpoint, evaluate, exact, fn, mock, name, numeric, oneOf, optimize, presence, within };
+export { type Comparator, type ComparatorContext, type ComparatorResult, type EndpointConfig, type EvalConfig, type EvalResult, type Executor, type ExecutorResult, type FnConfig, type LLMCompareConfig, type LLMConfig, LLMProviders, type OptimizeConfig, type OptimizeResult, type TestCase, type TestCaseResult, contains, custom, date, didactic as default, didactic as didact, didactic, endpoint, evaluate, exact, fn, llmCompare, mock, name, numeric, oneOf, optimize, presence, unordered, within };
 //# sourceMappingURL=index.d.mts.map