llm-exe 3.0.0-beta.1 → 3.0.0-beta.2

package/dist/index.d.mts

@@ -92,7 +92,7 @@ declare abstract class BaseParser<T = any, TInput = string> {
 declare abstract class BaseParserWithJson<S extends JSONSchema | undefined = undefined, T = S extends JSONSchema ? FromSchema<S> : Record<string, any>, TInput = string> extends BaseParser<T, TInput> {
     schema: S;
     validateSchema: boolean;
-    constructor(name: string, options: JsonParserOptions<S>);
+    constructor(name: string, options: ParserSchemaOptions<S>);
 }
 
 /**
@@ -111,25 +111,31 @@ declare class StringParser extends BaseParser<string> {
     parse(text: string, _attributes?: Record<string, any>): string;
 }
 
+type BooleanParserMatch = "exact" | "extract";
+interface BooleanParserOptions {
+    match?: BooleanParserMatch;
+}
 /**
  * v3 parser contract:
  * Category: strict
- * Mode: whole-output
+ * Mode: exact
  *
  * Accepts only documented boolean literals after trim/lowercase.
- * Returns true/false only when input is recognized.
- * Throws LlmExeError(parser.parse_failed) for empty, invalid-type, or
- * unrecognized input. Does not extract booleans from prose.
+ * Returns true/false only when input is recognized. Pass match: "extract" to
+ * extract one documented boolean literal from surrounding text.
+ * Throws LlmExeError(parser.parse_failed) for empty or unrecognized input.
+ * Invalid input types throw LlmExeError(parser.invalid_input).
  * Error context does not include input content unless LLM_EXE_DEBUG is enabled.
  *
  */
 declare class BooleanParser extends BaseParser<boolean> {
-    constructor();
+    private match;
+    constructor(options?: BooleanParserOptions);
     private getInputErrorContext;
     parse(text: string, _attributes?: Record<string, any>): boolean;
 }
 
-type NumberParserMatch = "extract" | "whole";
+type NumberParserMatch = "exact" | "extract";
 interface NumberParserOptions {
     match?: NumberParserMatch;
 }
@@ -138,7 +144,7 @@ interface NumberParserOptions {
  * Category: extractor
  * Mode: numeric token extraction
  *
- * Extracts one documented numeric token from text. Pass match: "whole" to
+ * Extracts one documented numeric token from text. Pass match: "exact" to
  * require the input to consist of exactly one numeric token (after trim) with
  * no surrounding prose.
  *
@@ -156,14 +162,16 @@ type JsonParserInput = string | Record<string, unknown> | unknown[];
 type JsonParserOutput<S extends JSONSchema | undefined> = S extends JSONSchema ? FromSchema<S> : Record<string, any>;
 declare class JsonParser<S extends JSONSchema | undefined = undefined> extends BaseParserWithJson<S, JsonParserOutput<S>, JsonParserInput> {
     private shouldValidateSchema;
+    private match;
     constructor(options?: JsonParserOptions<S>);
     /**
      * v3 parser contract:
      * Category: strict
-     * Mode: whole-output
+     * Mode: exact
      *
-     * Parses strict JSON object/array output only. Invalid JSON, empty input,
-     * JSON primitives, and non-plain runtime objects throw typed parser errors.
+     * Parses strict JSON object/array output by default. Pass match: "extract"
+     * to extract one JSON object or array from surrounding text. Invalid JSON,
+     * empty input, JSON primitives, and non-plain runtime objects throw typed parser errors.
      * Schema validation is on by default when a schema is provided unless
      * validateSchema: false is explicitly set.
      *
@@ -314,7 +322,7 @@ declare class MarkdownCodeBlocksParser extends BaseParser<{
     }[];
 }
 
-type StringExtractMatch = "word" | "whole" | "substring";
+type StringExtractMatch = "exact" | "word" | "substring";
 interface StringExtractParserOptions<E extends readonly string[] = readonly string[]> {
     enum: E;
     ignoreCase?: boolean;
@@ -331,14 +339,14 @@ declare class StringExtractParser<E extends readonly string[] = readonly string[
      * Mode: configured value extraction
      *
      * Returns the single configured enum value found in input. Matching is
-     * word-bounded by default; pass match: "whole" to require exact input or
+     * word-bounded by default; pass match: "exact" to require exact input or
      * match: "substring" for legacy contains() behavior. Case-insensitive by
      * default.
      *
      */
     parse(text: string, _attributes?: Record<string, any>): E[number];
     private findMatches;
-    private matchWhole;
+    private matchExact;
     private matchSubstring;
     private matchWord;
 }
@@ -350,16 +358,22 @@ declare class StringExtractParser<E extends readonly string[] = readonly string[
  * (e.g. "Source has 1 element(s) but target requires 2" when stringExtract
  * is called without options) instead of overload-resolution mystery.
  */
-type CreateParserArgs = [type: "string", options?: never] | [type: "boolean", options?: never] | [type: "listToArray", options?: never] | [type: "markdownCodeBlock", options?: never] | [type: "markdownCodeBlocks", options?: never] | [type: "replaceStringTemplate", options?: never] | [type: "number", options?: NumberParserOptions] | [type: "listToKeyValue", options?: ListToKeyValueParserOptions] | [type: "json", options?: JsonParserOptions<JSONSchema | undefined>] | [
+type CreateParserArgs = [type: "string", options?: never] | [type: "boolean", options?: BooleanParserOptions] | [type: "listToArray", options?: never] | [type: "markdownCodeBlock", options?: never] | [type: "markdownCodeBlocks", options?: never] | [type: "replaceStringTemplate", options?: never] | [type: "number", options?: NumberParserOptions] | [type: "listToKeyValue", options?: ListToKeyValueParserOptions] | [type: "json", options?: JsonParserOptions<JSONSchema | undefined>] | [
     type: "listToJson",
     options?: ListToJsonParserOptions<JSONSchema | undefined>
-] | [type: "stringExtract", options: StringExtractParserOptions<readonly string[]>];
+] | [
+    type: "stringExtract",
+    options: StringExtractParserOptions<readonly string[]>
+];
 /**
  * Maps a concrete argument tuple back to the parser instance type, preserving
  * schema inference for json/listToJson and enum literal narrowing for
  * stringExtract.
  */
-type CreateParserReturn<A extends readonly unknown[]> = A extends readonly ["string", ...unknown[]] ? StringParser : A extends readonly ["boolean", ...unknown[]] ? BooleanParser : A extends readonly ["number", ...unknown[]] ? NumberParser : A extends readonly ["listToArray", ...unknown[]] ? ListToArrayParser : A extends readonly ["listToKeyValue", ...unknown[]] ? ListToKeyValueParser : A extends readonly ["markdownCodeBlock", ...unknown[]] ? MarkdownCodeBlockParser : A extends readonly ["markdownCodeBlocks", ...unknown[]] ? MarkdownCodeBlocksParser : A extends readonly ["replaceStringTemplate", ...unknown[]] ? ReplaceStringTemplateParser : A extends readonly ["json"] | readonly ["json", undefined] ? JsonParser<undefined> : A extends readonly ["json", JsonParserOptions<infer S>] ? JsonParser<S> : A extends readonly ["listToJson"] | readonly ["listToJson", undefined] ? ListToJsonParser<undefined> : A extends readonly ["listToJson", ListToJsonParserOptions<infer S>] ? ListToJsonParser<S> : A extends readonly [
+type CreateParserReturn<A extends readonly unknown[]> = A extends readonly ["string", ...unknown[]] ? StringParser : A extends readonly ["boolean", ...unknown[]] ? BooleanParser : A extends readonly ["number", ...unknown[]] ? NumberParser : A extends readonly ["listToArray", ...unknown[]] ? ListToArrayParser : A extends readonly ["listToKeyValue", ...unknown[]] ? ListToKeyValueParser : A extends readonly ["markdownCodeBlock", ...unknown[]] ? MarkdownCodeBlockParser : A extends readonly ["markdownCodeBlocks", ...unknown[]] ? MarkdownCodeBlocksParser : A extends readonly ["replaceStringTemplate", ...unknown[]] ? ReplaceStringTemplateParser : A extends readonly ["json"] | readonly ["json", undefined] ? JsonParser<undefined> : A extends readonly ["json", JsonParserOptions<infer S>] ? JsonParser<S> : A extends readonly ["listToJson"] | readonly ["listToJson", undefined] ? ListToJsonParser<undefined> : A extends readonly [
+    "listToJson",
+    ListToJsonParserOptions<infer S>
+] ? ListToJsonParser<S> : A extends readonly [
     "stringExtract",
     StringExtractParserOptions<infer E extends readonly string[]>
 ] ? StringExtractParser<E> : never;
@@ -1057,11 +1071,15 @@ interface LlmExecutorWithFunctionsOptions<T extends GenericFunctionCall = "auto"
     jsonSchema?: Record<string, any>;
 }
 
-interface JsonParserOptions<S extends JSONSchema | undefined = undefined> {
+interface ParserSchemaOptions<S extends JSONSchema | undefined = undefined> {
     schema?: S;
     validateSchema?: boolean;
 }
-interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends JsonParserOptions<S> {
+type JsonParserMatch = "exact" | "extract";
+interface JsonParserOptions<S extends JSONSchema | undefined = undefined> extends ParserSchemaOptions<S> {
+    match?: JsonParserMatch;
+}
+interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends ParserSchemaOptions<S> {
     keyTransform?: "camelCase" | "preserve";
 }
 
@@ -2069,4 +2087,4 @@ declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, op
     };
 };
 
-export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, isLlmExeError, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };
+export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, type BooleanParserMatch, type BooleanParserOptions, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, type JsonParserMatch, type JsonParserOptions, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type NumberParserMatch, type NumberParserOptions, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, type StringExtractMatch, type StringExtractParserOptions, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, isLlmExeError, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };

package/dist/index.d.ts

@@ -92,7 +92,7 @@ declare abstract class BaseParser<T = any, TInput = string> {
 declare abstract class BaseParserWithJson<S extends JSONSchema | undefined = undefined, T = S extends JSONSchema ? FromSchema<S> : Record<string, any>, TInput = string> extends BaseParser<T, TInput> {
     schema: S;
     validateSchema: boolean;
-    constructor(name: string, options: JsonParserOptions<S>);
+    constructor(name: string, options: ParserSchemaOptions<S>);
 }
 
 /**
@@ -111,25 +111,31 @@ declare class StringParser extends BaseParser<string> {
     parse(text: string, _attributes?: Record<string, any>): string;
 }
 
+type BooleanParserMatch = "exact" | "extract";
+interface BooleanParserOptions {
+    match?: BooleanParserMatch;
+}
 /**
  * v3 parser contract:
  * Category: strict
- * Mode: whole-output
+ * Mode: exact
  *
  * Accepts only documented boolean literals after trim/lowercase.
- * Returns true/false only when input is recognized.
- * Throws LlmExeError(parser.parse_failed) for empty, invalid-type, or
- * unrecognized input. Does not extract booleans from prose.
+ * Returns true/false only when input is recognized. Pass match: "extract" to
+ * extract one documented boolean literal from surrounding text.
+ * Throws LlmExeError(parser.parse_failed) for empty or unrecognized input.
+ * Invalid input types throw LlmExeError(parser.invalid_input).
  * Error context does not include input content unless LLM_EXE_DEBUG is enabled.
  *
  */
 declare class BooleanParser extends BaseParser<boolean> {
-    constructor();
+    private match;
+    constructor(options?: BooleanParserOptions);
     private getInputErrorContext;
     parse(text: string, _attributes?: Record<string, any>): boolean;
 }
 
-type NumberParserMatch = "extract" | "whole";
+type NumberParserMatch = "exact" | "extract";
 interface NumberParserOptions {
     match?: NumberParserMatch;
 }
@@ -138,7 +144,7 @@ interface NumberParserOptions {
  * Category: extractor
  * Mode: numeric token extraction
  *
- * Extracts one documented numeric token from text. Pass match: "whole" to
+ * Extracts one documented numeric token from text. Pass match: "exact" to
  * require the input to consist of exactly one numeric token (after trim) with
  * no surrounding prose.
  *
@@ -156,14 +162,16 @@ type JsonParserInput = string | Record<string, unknown> | unknown[];
 type JsonParserOutput<S extends JSONSchema | undefined> = S extends JSONSchema ? FromSchema<S> : Record<string, any>;
 declare class JsonParser<S extends JSONSchema | undefined = undefined> extends BaseParserWithJson<S, JsonParserOutput<S>, JsonParserInput> {
     private shouldValidateSchema;
+    private match;
     constructor(options?: JsonParserOptions<S>);
     /**
      * v3 parser contract:
      * Category: strict
-     * Mode: whole-output
+     * Mode: exact
      *
-     * Parses strict JSON object/array output only. Invalid JSON, empty input,
-     * JSON primitives, and non-plain runtime objects throw typed parser errors.
+     * Parses strict JSON object/array output by default. Pass match: "extract"
+     * to extract one JSON object or array from surrounding text. Invalid JSON,
+     * empty input, JSON primitives, and non-plain runtime objects throw typed parser errors.
      * Schema validation is on by default when a schema is provided unless
      * validateSchema: false is explicitly set.
      *
@@ -314,7 +322,7 @@ declare class MarkdownCodeBlocksParser extends BaseParser<{
     }[];
 }
 
-type StringExtractMatch = "word" | "whole" | "substring";
+type StringExtractMatch = "exact" | "word" | "substring";
 interface StringExtractParserOptions<E extends readonly string[] = readonly string[]> {
     enum: E;
     ignoreCase?: boolean;
@@ -331,14 +339,14 @@ declare class StringExtractParser<E extends readonly string[] = readonly string[
      * Mode: configured value extraction
      *
      * Returns the single configured enum value found in input. Matching is
-     * word-bounded by default; pass match: "whole" to require exact input or
+     * word-bounded by default; pass match: "exact" to require exact input or
      * match: "substring" for legacy contains() behavior. Case-insensitive by
      * default.
      *
      */
     parse(text: string, _attributes?: Record<string, any>): E[number];
     private findMatches;
-    private matchWhole;
+    private matchExact;
     private matchSubstring;
     private matchWord;
 }
@@ -350,16 +358,22 @@ declare class StringExtractParser<E extends readonly string[] = readonly string[
  * (e.g. "Source has 1 element(s) but target requires 2" when stringExtract
  * is called without options) instead of overload-resolution mystery.
  */
-type CreateParserArgs = [type: "string", options?: never] | [type: "boolean", options?: never] | [type: "listToArray", options?: never] | [type: "markdownCodeBlock", options?: never] | [type: "markdownCodeBlocks", options?: never] | [type: "replaceStringTemplate", options?: never] | [type: "number", options?: NumberParserOptions] | [type: "listToKeyValue", options?: ListToKeyValueParserOptions] | [type: "json", options?: JsonParserOptions<JSONSchema | undefined>] | [
+type CreateParserArgs = [type: "string", options?: never] | [type: "boolean", options?: BooleanParserOptions] | [type: "listToArray", options?: never] | [type: "markdownCodeBlock", options?: never] | [type: "markdownCodeBlocks", options?: never] | [type: "replaceStringTemplate", options?: never] | [type: "number", options?: NumberParserOptions] | [type: "listToKeyValue", options?: ListToKeyValueParserOptions] | [type: "json", options?: JsonParserOptions<JSONSchema | undefined>] | [
     type: "listToJson",
     options?: ListToJsonParserOptions<JSONSchema | undefined>
-] | [type: "stringExtract", options: StringExtractParserOptions<readonly string[]>];
+] | [
+    type: "stringExtract",
+    options: StringExtractParserOptions<readonly string[]>
+];
 /**
  * Maps a concrete argument tuple back to the parser instance type, preserving
  * schema inference for json/listToJson and enum literal narrowing for
  * stringExtract.
  */
-type CreateParserReturn<A extends readonly unknown[]> = A extends readonly ["string", ...unknown[]] ? StringParser : A extends readonly ["boolean", ...unknown[]] ? BooleanParser : A extends readonly ["number", ...unknown[]] ? NumberParser : A extends readonly ["listToArray", ...unknown[]] ? ListToArrayParser : A extends readonly ["listToKeyValue", ...unknown[]] ? ListToKeyValueParser : A extends readonly ["markdownCodeBlock", ...unknown[]] ? MarkdownCodeBlockParser : A extends readonly ["markdownCodeBlocks", ...unknown[]] ? MarkdownCodeBlocksParser : A extends readonly ["replaceStringTemplate", ...unknown[]] ? ReplaceStringTemplateParser : A extends readonly ["json"] | readonly ["json", undefined] ? JsonParser<undefined> : A extends readonly ["json", JsonParserOptions<infer S>] ? JsonParser<S> : A extends readonly ["listToJson"] | readonly ["listToJson", undefined] ? ListToJsonParser<undefined> : A extends readonly ["listToJson", ListToJsonParserOptions<infer S>] ? ListToJsonParser<S> : A extends readonly [
+type CreateParserReturn<A extends readonly unknown[]> = A extends readonly ["string", ...unknown[]] ? StringParser : A extends readonly ["boolean", ...unknown[]] ? BooleanParser : A extends readonly ["number", ...unknown[]] ? NumberParser : A extends readonly ["listToArray", ...unknown[]] ? ListToArrayParser : A extends readonly ["listToKeyValue", ...unknown[]] ? ListToKeyValueParser : A extends readonly ["markdownCodeBlock", ...unknown[]] ? MarkdownCodeBlockParser : A extends readonly ["markdownCodeBlocks", ...unknown[]] ? MarkdownCodeBlocksParser : A extends readonly ["replaceStringTemplate", ...unknown[]] ? ReplaceStringTemplateParser : A extends readonly ["json"] | readonly ["json", undefined] ? JsonParser<undefined> : A extends readonly ["json", JsonParserOptions<infer S>] ? JsonParser<S> : A extends readonly ["listToJson"] | readonly ["listToJson", undefined] ? ListToJsonParser<undefined> : A extends readonly [
+    "listToJson",
+    ListToJsonParserOptions<infer S>
+] ? ListToJsonParser<S> : A extends readonly [
     "stringExtract",
     StringExtractParserOptions<infer E extends readonly string[]>
 ] ? StringExtractParser<E> : never;
@@ -1057,11 +1071,15 @@ interface LlmExecutorWithFunctionsOptions<T extends GenericFunctionCall = "auto"
     jsonSchema?: Record<string, any>;
 }
 
-interface JsonParserOptions<S extends JSONSchema | undefined = undefined> {
+interface ParserSchemaOptions<S extends JSONSchema | undefined = undefined> {
     schema?: S;
     validateSchema?: boolean;
 }
-interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends JsonParserOptions<S> {
+type JsonParserMatch = "exact" | "extract";
+interface JsonParserOptions<S extends JSONSchema | undefined = undefined> extends ParserSchemaOptions<S> {
+    match?: JsonParserMatch;
+}
+interface ListToJsonParserOptions<S extends JSONSchema | undefined = undefined> extends ParserSchemaOptions<S> {
     keyTransform?: "camelCase" | "preserve";
 }
 
@@ -2069,4 +2087,4 @@ declare function createEmbedding<T extends EmbeddingProviderKey>(provider: T, op
     };
 };
 
-export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, isLlmExeError, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };
+export { BaseExecutor, type BaseLlm, BaseParser, BasePrompt, BaseStateItem, type BooleanParserMatch, type BooleanParserOptions, ChatPrompt, CustomParser, DefaultState, DefaultStateItem, type EmbeddingProviderKey, type ErrorCategory, type ErrorCodes, type ErrorContextByCode, type ExecutionContext, type ExecutorContext, type ExecutorExecutionMetadata, type HookErrorRecord, type IChatMessages, type JsonParserMatch, type JsonParserOptions, LLM_EXE_ERROR_SYMBOL, LlmExeError, LlmExecutorOpenAiFunctions, LlmExecutorWithFunctions, LlmNativeFunctionParser, type LlmProvider, type LlmProviderKey, type NormalizedProviderError, type NumberParserMatch, type NumberParserOptions, type OpenAIModelName, OpenAiFunctionParser, type ProviderErrorContext, type StringExtractMatch, type StringExtractParserOptions, TextPrompt, type UseLlmKey, createCallableExecutor, createChatPrompt, createCoreExecutor, createCustomParser, createDialogue, createEmbedding, createLlmExecutor, createLlmFunctionExecutor, createOpenAiCompatibleConfiguration, createParser, createPrompt, createState, createStateItem, defineSchema, guards, isLlmExeError, registerHelpers, registerPartials, useExecutors, useLlm, useLlmConfiguration, index as utils };

package/dist/index.js

@@ -1266,9 +1266,12 @@ var BOOLEAN_VALUES = ["true", "false", "yes", "no", "y", "n", "1", "0"];
 var TRUTHY_VALUES = /* @__PURE__ */ new Set(["true", "yes", "y", "1"]);
 var FALSY_VALUES = /* @__PURE__ */ new Set(["false", "no", "n", "0"]);
 var MAX_ERROR_INPUT_EXCERPT_LENGTH = 500;
+var BOOLEAN_TOKEN_PATTERN = /(?<![\p{L}\p{N}])(?:true|false|yes|no|y|n|1|0)(?![\p{L}\p{N}])/giu;
 var BooleanParser = class extends BaseParser {
-  constructor() {
+  constructor(options) {
     super("boolean");
+    __publicField(this, "match");
+    this.match = options?.match ?? "exact";
   }
   getInputErrorContext(text) {
     const context = {
@@ -1316,6 +1319,36 @@ var BooleanParser = class extends BaseParser {
     if (FALSY_VALUES.has(clean)) {
       return false;
     }
+    if (this.match === "extract") {
+      const matches = Array.from(
+        text.toLowerCase().matchAll(BOOLEAN_TOKEN_PATTERN)
+      ).map((match) => match[0]);
+      const values = Array.from(
+        new Set(
+          matches.map((match) => {
+            if (TRUTHY_VALUES.has(match)) return true;
+            return false;
+          })
+        )
+      );
+      if (values.length === 1) {
+        return values[0];
+      }
+      if (values.length > 1) {
+        throw new LlmExeError(`Multiple boolean values found in input.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "BooleanParser.parse",
+            parser: "boolean",
+            reason: "ambiguous_boolean",
+            expected: "one boolean value",
+            match: this.match,
+            matchCount: values.length,
+            ...this.getInputErrorContext(text)
+          }
+        });
+      }
+    }
     throw new LlmExeError(`No boolean value found in input.`, {
       code: "parser.parse_failed",
       context: {
@@ -1323,6 +1356,7 @@ var BooleanParser = class extends BaseParser {
         parser: "boolean",
         reason: "unrecognized_boolean",
         expected: BOOLEAN_VALUES,
+        match: this.match,
         ...this.getInputErrorContext(text)
       }
     });
@@ -1347,7 +1381,7 @@ function toNumber(value) {
 
 // src/parser/parsers/NumberParser.ts
 var NUMERIC_TOKEN_PATTERN = /(^|[^\w.,])([+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?)(?![\w,])/g;
-var WHOLE_NUMERIC_PATTERN = /^[+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+var EXACT_NUMERIC_PATTERN = /^[+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 var NumberParser = class extends BaseParser {
   constructor(options) {
     super("number");
@@ -1382,16 +1416,16 @@ var NumberParser = class extends BaseParser {
         }
       });
     }
-    if (this.match === "whole") {
+    if (this.match === "exact") {
       const trimmed = text.trim();
-      if (!WHOLE_NUMERIC_PATTERN.test(trimmed)) {
-        throw new LlmExeError(`Input is not a whole numeric value.`, {
+      if (!EXACT_NUMERIC_PATTERN.test(trimmed)) {
+        throw new LlmExeError(`Input is not an exact numeric value.`, {
           code: "parser.parse_failed",
           context: {
             operation: "NumberParser.parse",
             parser: "number",
             reason: "no_numeric_value",
-            expected: "whole number",
+            expected: "exact number",
             match: this.match,
             inputLength: text.length
           }
@@ -1658,9 +1692,11 @@ function isPlainObject2(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-function normalizeWholeResponseJsonText(input) {
+function normalizeExactResponseJsonText(input) {
   const trimmed = input.trim();
-  const fenceMatch = trimmed.match(/^```([a-zA-Z]*)[^\S\r\n]*\r?\n([\s\S]*)```$/);
+  const fenceMatch = trimmed.match(
+    /^```([a-zA-Z]*)[^\S\r\n]*\r?\n([\s\S]*)```$/
+  );
   if (!fenceMatch) {
     return trimmed;
   }
@@ -1670,19 +1706,82 @@ function normalizeWholeResponseJsonText(input) {
   }
   return body.trim();
 }
+function findBalancedJsonEnd(input, start) {
+  const first = input[start];
+  const stack = first === "{" ? ["}"] : first === "[" ? ["]"] : [];
+  let inString = false;
+  let escaping = false;
+  for (let index = start + 1; index < input.length; index += 1) {
+    const char = input[index];
+    if (inString) {
+      if (escaping) {
+        escaping = false;
+      } else if (char === "\\") {
+        escaping = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      stack.push(char === "{" ? "}" : "]");
+      continue;
+    }
+    if (char !== "}" && char !== "]") {
+      continue;
+    }
+    if (stack[stack.length - 1] !== char) {
+      return void 0;
+    }
+    stack.pop();
+    if (stack.length === 0) {
+      return index;
+    }
+  }
+  return void 0;
+}
+function extractJsonCandidates(input) {
+  const candidates = [];
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (char !== "{" && char !== "[") {
+      continue;
+    }
+    const end = findBalancedJsonEnd(input, index);
+    if (end === void 0) {
+      continue;
+    }
+    const candidate = input.slice(index, end + 1);
+    try {
+      candidates.push({
+        parsed: JSON.parse(candidate)
+      });
+      index = end;
+    } catch {
+    }
+  }
+  return candidates;
+}
 var JsonParser = class extends BaseParserWithJson {
   constructor(options = {}) {
     super("json", options);
     __publicField(this, "shouldValidateSchema");
+    __publicField(this, "match");
+    this.match = options.match ?? "exact";
     this.shouldValidateSchema = !!options.schema && options.validateSchema !== false;
   }
   /**
    * v3 parser contract:
    * Category: strict
-   * Mode: whole-output
+   * Mode: exact
    *
-   * Parses strict JSON object/array output only. Invalid JSON, empty input,
-   * JSON primitives, and non-plain runtime objects throw typed parser errors.
+   * Parses strict JSON object/array output by default. Pass match: "extract"
+   * to extract one JSON object or array from surrounding text. Invalid JSON,
+   * empty input, JSON primitives, and non-plain runtime objects throw typed parser errors.
    * Schema validation is on by default when a schema is provided unless
    * validateSchema: false is explicitly set.
    *
@@ -1705,19 +1804,52 @@ var JsonParser = class extends BaseParserWithJson {
         });
       }
       try {
-        parsed = JSON.parse(normalizeWholeResponseJsonText(text));
+        parsed = JSON.parse(normalizeExactResponseJsonText(text));
       } catch (cause) {
-        throw new LlmExeError(`Invalid JSON input.`, {
-          code: "parser.parse_failed",
-          context: {
-            operation: "JsonParser.parse",
-            parser: "json",
-            reason: "invalid_json",
-            expected: "JSON object or array",
-            inputLength
-          },
-          cause
-        });
+        if (this.match === "extract") {
+          const candidates = extractJsonCandidates(text);
+          if (candidates.length === 1) {
+            parsed = candidates[0].parsed;
+          } else if (candidates.length > 1) {
+            throw new LlmExeError(`Multiple JSON values found in input.`, {
+              code: "parser.parse_failed",
+              context: {
+                operation: "JsonParser.parse",
+                parser: "json",
+                reason: "ambiguous_json_match",
+                expected: "one JSON object or array",
+                match: this.match,
+                inputLength,
+                matchCount: candidates.length
+              }
+            });
+          } else {
+            throw new LlmExeError(`No JSON value found in input.`, {
+              code: "parser.parse_failed",
+              context: {
+                operation: "JsonParser.parse",
+                parser: "json",
+                reason: "no_json_value",
+                expected: "JSON object or array",
+                match: this.match,
+                inputLength
+              },
+              cause
+            });
+          }
+        } else {
+          throw new LlmExeError(`Invalid JSON input.`, {
+            code: "parser.parse_failed",
+            context: {
+              operation: "JsonParser.parse",
+              parser: "json",
+              reason: "invalid_json",
+              expected: "JSON object or array",
+              inputLength
+            },
+            cause
+          });
+        }
       }
     } else if (Array.isArray(text) || isPlainObject2(text)) {
       parsed = text;
@@ -2988,7 +3120,7 @@ var StringExtractParser = class extends BaseParser {
    * Mode: configured value extraction
    *
    * Returns the single configured enum value found in input. Matching is
-   * word-bounded by default; pass match: "whole" to require exact input or
+   * word-bounded by default; pass match: "exact" to require exact input or
    * match: "substring" for legacy contains() behavior. Case-insensitive by
    * default.
    *
@@ -3070,8 +3202,8 @@ var StringExtractParser = class extends BaseParser {
   }
   findMatches(text) {
     switch (this.match) {
-      case "whole":
-        return this.matchWhole(text);
+      case "exact":
+        return this.matchExact(text);
       case "substring":
         return this.matchSubstring(text);
       case "word":
@@ -3079,7 +3211,7 @@ var StringExtractParser = class extends BaseParser {
         return this.matchWord(text);
     }
   }
-  matchWhole(text) {
+  matchExact(text) {
     const candidate = this.ignoreCase ? text.trim().toLowerCase() : text.trim();
     return this.enum.filter((option) => {
       if (option === "") return false;
@@ -3129,36 +3261,33 @@ function createParser(...args) {
     case "replaceStringTemplate":
       return new ReplaceStringTemplateParser();
     case "boolean":
-      return new BooleanParser();
+      return new BooleanParser(options);
     case "number":
       return new NumberParser(options);
     case "string":
       return new StringParser();
     default:
-      throw new LlmExeError(
-        `Invalid parser type: "${type}"`,
-        {
-          code: "parser.invalid_type",
-          context: {
-            operation: "createParser",
-            parser: type,
-            availableParsers: [
-              "json",
-              "string",
-              "boolean",
-              "number",
-              "stringExtract",
-              "listToArray",
-              "listToJson",
-              "listToKeyValue",
-              "replaceStringTemplate",
-              "markdownCodeBlock",
-              "markdownCodeBlocks"
-            ],
-            resolution: "Use a registered parser type, or define a custom parser."
-          }
+      throw new LlmExeError(`Invalid parser type: "${type}"`, {
+        code: "parser.invalid_type",
+        context: {
+          operation: "createParser",
+          parser: type,
+          availableParsers: [
+            "json",
+            "string",
+            "boolean",
+            "number",
+            "stringExtract",
+            "listToArray",
+            "listToJson",
+            "listToKeyValue",
+            "replaceStringTemplate",
+            "markdownCodeBlock",
+            "markdownCodeBlocks"
+          ],
+          resolution: "Use a registered parser type, or define a custom parser."
         }
-      );
+      });
   }
 }
 function createCustomParser(name, parserFn) {

package/dist/index.mjs

@@ -1200,9 +1200,12 @@ var BOOLEAN_VALUES = ["true", "false", "yes", "no", "y", "n", "1", "0"];
 var TRUTHY_VALUES = /* @__PURE__ */ new Set(["true", "yes", "y", "1"]);
 var FALSY_VALUES = /* @__PURE__ */ new Set(["false", "no", "n", "0"]);
 var MAX_ERROR_INPUT_EXCERPT_LENGTH = 500;
+var BOOLEAN_TOKEN_PATTERN = /(?<![\p{L}\p{N}])(?:true|false|yes|no|y|n|1|0)(?![\p{L}\p{N}])/giu;
 var BooleanParser = class extends BaseParser {
-  constructor() {
+  constructor(options) {
     super("boolean");
+    __publicField(this, "match");
+    this.match = options?.match ?? "exact";
   }
   getInputErrorContext(text) {
     const context = {
@@ -1250,6 +1253,36 @@ var BooleanParser = class extends BaseParser {
     if (FALSY_VALUES.has(clean)) {
       return false;
     }
+    if (this.match === "extract") {
+      const matches = Array.from(
+        text.toLowerCase().matchAll(BOOLEAN_TOKEN_PATTERN)
+      ).map((match) => match[0]);
+      const values = Array.from(
+        new Set(
+          matches.map((match) => {
+            if (TRUTHY_VALUES.has(match)) return true;
+            return false;
+          })
+        )
+      );
+      if (values.length === 1) {
+        return values[0];
+      }
+      if (values.length > 1) {
+        throw new LlmExeError(`Multiple boolean values found in input.`, {
+          code: "parser.parse_failed",
+          context: {
+            operation: "BooleanParser.parse",
+            parser: "boolean",
+            reason: "ambiguous_boolean",
+            expected: "one boolean value",
+            match: this.match,
+            matchCount: values.length,
+            ...this.getInputErrorContext(text)
+          }
+        });
+      }
+    }
     throw new LlmExeError(`No boolean value found in input.`, {
       code: "parser.parse_failed",
       context: {
@@ -1257,6 +1290,7 @@ var BooleanParser = class extends BaseParser {
         parser: "boolean",
         reason: "unrecognized_boolean",
         expected: BOOLEAN_VALUES,
+        match: this.match,
         ...this.getInputErrorContext(text)
       }
     });
@@ -1281,7 +1315,7 @@ function toNumber(value) {
 
 // src/parser/parsers/NumberParser.ts
 var NUMERIC_TOKEN_PATTERN = /(^|[^\w.,])([+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?)(?![\w,])/g;
-var WHOLE_NUMERIC_PATTERN = /^[+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+var EXACT_NUMERIC_PATTERN = /^[+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 var NumberParser = class extends BaseParser {
   constructor(options) {
     super("number");
@@ -1316,16 +1350,16 @@ var NumberParser = class extends BaseParser {
         }
       });
     }
-    if (this.match === "whole") {
+    if (this.match === "exact") {
       const trimmed = text.trim();
-      if (!WHOLE_NUMERIC_PATTERN.test(trimmed)) {
-        throw new LlmExeError(`Input is not a whole numeric value.`, {
+      if (!EXACT_NUMERIC_PATTERN.test(trimmed)) {
+        throw new LlmExeError(`Input is not an exact numeric value.`, {
           code: "parser.parse_failed",
           context: {
             operation: "NumberParser.parse",
             parser: "number",
             reason: "no_numeric_value",
-            expected: "whole number",
+            expected: "exact number",
             match: this.match,
             inputLength: text.length
           }
@@ -1592,9 +1626,11 @@ function isPlainObject2(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-function normalizeWholeResponseJsonText(input) {
+function normalizeExactResponseJsonText(input) {
   const trimmed = input.trim();
-  const fenceMatch = trimmed.match(/^```([a-zA-Z]*)[^\S\r\n]*\r?\n([\s\S]*)```$/);
+  const fenceMatch = trimmed.match(
+    /^```([a-zA-Z]*)[^\S\r\n]*\r?\n([\s\S]*)```$/
+  );
   if (!fenceMatch) {
     return trimmed;
   }
@@ -1604,19 +1640,82 @@ function normalizeWholeResponseJsonText(input) {
   }
   return body.trim();
 }
+function findBalancedJsonEnd(input, start) {
+  const first = input[start];
+  const stack = first === "{" ? ["}"] : first === "[" ? ["]"] : [];
+  let inString = false;
+  let escaping = false;
+  for (let index = start + 1; index < input.length; index += 1) {
+    const char = input[index];
+    if (inString) {
+      if (escaping) {
+        escaping = false;
+      } else if (char === "\\") {
+        escaping = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      stack.push(char === "{" ? "}" : "]");
+      continue;
+    }
+    if (char !== "}" && char !== "]") {
+      continue;
+    }
+    if (stack[stack.length - 1] !== char) {
+      return void 0;
+    }
+    stack.pop();
+    if (stack.length === 0) {
+      return index;
+    }
+  }
+  return void 0;
+}
+function extractJsonCandidates(input) {
+  const candidates = [];
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (char !== "{" && char !== "[") {
+      continue;
+    }
+    const end = findBalancedJsonEnd(input, index);
+    if (end === void 0) {
+      continue;
+    }
+    const candidate = input.slice(index, end + 1);
+    try {
+      candidates.push({
+        parsed: JSON.parse(candidate)
+      });
+      index = end;
+    } catch {
+    }
+  }
+  return candidates;
+}
 var JsonParser = class extends BaseParserWithJson {
   constructor(options = {}) {
     super("json", options);
     __publicField(this, "shouldValidateSchema");
+    __publicField(this, "match");
+    this.match = options.match ?? "exact";
     this.shouldValidateSchema = !!options.schema && options.validateSchema !== false;
   }
   /**
    * v3 parser contract:
    * Category: strict
-   * Mode: whole-output
+   * Mode: exact
    *
-   * Parses strict JSON object/array output only. Invalid JSON, empty input,
-   * JSON primitives, and non-plain runtime objects throw typed parser errors.
+   * Parses strict JSON object/array output by default. Pass match: "extract"
+   * to extract one JSON object or array from surrounding text. Invalid JSON,
+   * empty input, JSON primitives, and non-plain runtime objects throw typed parser errors.
    * Schema validation is on by default when a schema is provided unless
    * validateSchema: false is explicitly set.
    *
@@ -1639,19 +1738,52 @@ var JsonParser = class extends BaseParserWithJson {
         });
       }
       try {
-        parsed = JSON.parse(normalizeWholeResponseJsonText(text));
+        parsed = JSON.parse(normalizeExactResponseJsonText(text));
       } catch (cause) {
-        throw new LlmExeError(`Invalid JSON input.`, {
-          code: "parser.parse_failed",
-          context: {
-            operation: "JsonParser.parse",
-            parser: "json",
-            reason: "invalid_json",
-            expected: "JSON object or array",
-            inputLength
-          },
-          cause
-        });
+        if (this.match === "extract") {
+          const candidates = extractJsonCandidates(text);
+          if (candidates.length === 1) {
+            parsed = candidates[0].parsed;
+          } else if (candidates.length > 1) {
+            throw new LlmExeError(`Multiple JSON values found in input.`, {
+              code: "parser.parse_failed",
+              context: {
+                operation: "JsonParser.parse",
+                parser: "json",
+                reason: "ambiguous_json_match",
+                expected: "one JSON object or array",
+                match: this.match,
+                inputLength,
+                matchCount: candidates.length
+              }
+            });
+          } else {
+            throw new LlmExeError(`No JSON value found in input.`, {
+              code: "parser.parse_failed",
+              context: {
+                operation: "JsonParser.parse",
+                parser: "json",
+                reason: "no_json_value",
+                expected: "JSON object or array",
+                match: this.match,
+                inputLength
+              },
+              cause
+            });
+          }
+        } else {
+          throw new LlmExeError(`Invalid JSON input.`, {
+            code: "parser.parse_failed",
+            context: {
+              operation: "JsonParser.parse",
+              parser: "json",
+              reason: "invalid_json",
+              expected: "JSON object or array",
+              inputLength
+            },
+            cause
+          });
+        }
       }
     } else if (Array.isArray(text) || isPlainObject2(text)) {
       parsed = text;
@@ -2922,7 +3054,7 @@ var StringExtractParser = class extends BaseParser {
    * Mode: configured value extraction
    *
    * Returns the single configured enum value found in input. Matching is
-   * word-bounded by default; pass match: "whole" to require exact input or
+   * word-bounded by default; pass match: "exact" to require exact input or
    * match: "substring" for legacy contains() behavior. Case-insensitive by
    * default.
    *
@@ -3004,8 +3136,8 @@ var StringExtractParser = class extends BaseParser {
   }
   findMatches(text) {
     switch (this.match) {
-      case "whole":
-        return this.matchWhole(text);
+      case "exact":
+        return this.matchExact(text);
       case "substring":
         return this.matchSubstring(text);
       case "word":
@@ -3013,7 +3145,7 @@ var StringExtractParser = class extends BaseParser {
         return this.matchWord(text);
     }
   }
-  matchWhole(text) {
+  matchExact(text) {
     const candidate = this.ignoreCase ? text.trim().toLowerCase() : text.trim();
     return this.enum.filter((option) => {
       if (option === "") return false;
@@ -3063,36 +3195,33 @@ function createParser(...args) {
     case "replaceStringTemplate":
       return new ReplaceStringTemplateParser();
     case "boolean":
-      return new BooleanParser();
+      return new BooleanParser(options);
     case "number":
       return new NumberParser(options);
     case "string":
       return new StringParser();
     default:
-      throw new LlmExeError(
-        `Invalid parser type: "${type}"`,
-        {
-          code: "parser.invalid_type",
-          context: {
-            operation: "createParser",
-            parser: type,
-            availableParsers: [
-              "json",
-              "string",
-              "boolean",
-              "number",
-              "stringExtract",
-              "listToArray",
-              "listToJson",
-              "listToKeyValue",
-              "replaceStringTemplate",
-              "markdownCodeBlock",
-              "markdownCodeBlocks"
-            ],
-            resolution: "Use a registered parser type, or define a custom parser."
-          }
+      throw new LlmExeError(`Invalid parser type: "${type}"`, {
+        code: "parser.invalid_type",
+        context: {
+          operation: "createParser",
+          parser: type,
+          availableParsers: [
+            "json",
+            "string",
+            "boolean",
+            "number",
+            "stringExtract",
+            "listToArray",
+            "listToJson",
+            "listToKeyValue",
+            "replaceStringTemplate",
+            "markdownCodeBlock",
+            "markdownCodeBlocks"
+          ],
+          resolution: "Use a registered parser type, or define a custom parser."
         }
-      );
+      });
   }
 }
 function createCustomParser(name, parserFn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-exe",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.2",
   "description": "Simplify building LLM-powered apps with easy-to-use base components, supporting text and chat-based prompts with handlebars template engine, output parsers, and flexible function calling capabilities.",
   "keywords": [
     "ai",

package/readme.md

@@ -85,7 +85,7 @@ Welcome back!
 ```ts
 createParser("string");              // pass-through, returns string
 createParser("json", { schema });    // JSON with optional schema validation
-createParser("boolean");             // extracts boolean from response
+createParser("boolean");             // parses a boolean token
 createParser("number");              // extracts number from response
 createParser("stringExtract", { enum: ["yes", "no"] }); // match one of the enum values
 createParser("listToArray");         // newline-separated list → string[]