@framers/agentos 0.1.121 → 0.1.123

package/dist/api/TextToolCallParser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file TextToolCallParser.ts
+ * Fallback parser for extracting tool invocations from plain-text LLM responses.
+ *
+ * When an LLM does not support native `tool_calls` (e.g. some Ollama models,
+ * open-source models), the model may still emit structured text that encodes
+ * tool invocations.  This parser recognises two common formats:
+ *
+ * **Format A — JSON in markdown code fences:**
+ * ```json
+ * {"tool": "web_search", "arguments": {"query": "AgentOS features"}}
+ * ```
+ *
+ * **Format B — ReAct-style structured text:**
+ * ```
+ * Thought: I need to search for information about AgentOS.
+ * Action: web_search
+ * Input: {"query": "AgentOS features"}
+ * ```
+ *
+ * The parser first attempts Format A extraction, then Format B.  Results from
+ * both passes are concatenated and returned as a unified array.
+ *
+ * @module api/TextToolCallParser
+ */
+/**
+ * A tool invocation extracted from unstructured LLM text output.
+ *
+ * Maps directly onto the `ToolCallRecord` shape used by {@link generateText},
+ * but uses `arguments` instead of `args` to match the canonical tool-call wire
+ * format before execution.
+ */
+export interface ParsedToolCall {
+    /** Name of the tool to invoke, as it appears in the tool registry. */
+    name: string;
+    /** Parsed argument object to pass to the tool's `execute` function. */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Parses tool invocations from an LLM's plain-text response.
+ *
+ * This is the primary entry point for the text-based tool-call fallback.
+ * It first attempts to extract JSON tool calls from markdown code fences
+ * (Format A), then falls back to ReAct-style `Action: / Input:` patterns
+ * (Format B).  Results from both passes are concatenated and de-duplicated
+ * by position (i.e. if the same tool call appears in both formats, both
+ * are included — the caller is responsible for deduplication if needed).
+ *
+ * @param text - Raw text from an LLM response.
+ * @returns An array of parsed tool calls, or an empty array if none were found.
+ *
+ * @example
+ * ```ts
+ * const calls = parseToolCallsFromText(responseText);
+ * for (const call of calls) {
+ *   console.log(`Tool: ${call.name}, Args:`, call.arguments);
+ * }
+ * ```
+ */
+export declare function parseToolCallsFromText(text: string): ParsedToolCall[];
+//# sourceMappingURL=TextToolCallParser.d.ts.map

package/dist/api/TextToolCallParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextToolCallParser.d.ts","sourceRoot":"","sources":["../../src/api/TextToolCallParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAgGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAOrE"}

package/dist/api/TextToolCallParser.js

@@ -0,0 +1,137 @@
+/**
+ * @file TextToolCallParser.ts
+ * Fallback parser for extracting tool invocations from plain-text LLM responses.
+ *
+ * When an LLM does not support native `tool_calls` (e.g. some Ollama models,
+ * open-source models), the model may still emit structured text that encodes
+ * tool invocations.  This parser recognises two common formats:
+ *
+ * **Format A — JSON in markdown code fences:**
+ * ```json
+ * {"tool": "web_search", "arguments": {"query": "AgentOS features"}}
+ * ```
+ *
+ * **Format B — ReAct-style structured text:**
+ * ```
+ * Thought: I need to search for information about AgentOS.
+ * Action: web_search
+ * Input: {"query": "AgentOS features"}
+ * ```
+ *
+ * The parser first attempts Format A extraction, then Format B.  Results from
+ * both passes are concatenated and returned as a unified array.
+ *
+ * @module api/TextToolCallParser
+ */
+/**
+ * Extracts tool calls embedded in a JSON markdown code fence.
+ *
+ * Matches ```json blocks whose body contains a top-level object with either
+ * `"tool"` or `"name"` plus `"arguments"` (or `"input"` / `"parameters"`).
+ * Also handles fenced arrays of such objects.
+ *
+ * @param text - Raw LLM response text.
+ * @returns Parsed tool calls found in fenced JSON blocks (may be empty).
+ */
+function parseJsonFences(text) {
+    const results = [];
+    // Match ```json ... ``` blocks (case-insensitive language tag)
+    const fencePattern = /```(?:json)?\s*\n?([\s\S]*?)```/gi;
+    let match;
+    while ((match = fencePattern.exec(text)) !== null) {
+        const body = match[1].trim();
+        if (!body)
+            continue;
+        try {
+            const parsed = JSON.parse(body);
+            const items = Array.isArray(parsed) ? parsed : [parsed];
+            for (const item of items) {
+                if (typeof item !== 'object' || item === null)
+                    continue;
+                const name = item.tool ?? item.name ?? item.function;
+                const args = item.arguments ?? item.input ?? item.parameters ?? item.params ?? {};
+                if (typeof name === 'string' && name.length > 0) {
+                    results.push({
+                        name,
+                        arguments: typeof args === 'object' && args !== null ? args : {},
+                    });
+                }
+            }
+        }
+        catch {
+            // Malformed JSON — skip this fence silently
+        }
+    }
+    return results;
+}
+/**
+ * Extracts tool calls from ReAct-style `Action: ... / Input: ...` blocks.
+ *
+ * The parser is line-oriented: it scans for `Action:` lines and then looks
+ * for a subsequent `Input:` line whose value is valid JSON.  An `Action:`
+ * without a following `Input:` is accepted with an empty argument object.
+ *
+ * @param text - Raw LLM response text.
+ * @returns Parsed tool calls found via the Action/Input pattern (may be empty).
+ */
+function parseReActStyle(text) {
+    const results = [];
+    // Match Action/Input pairs (multiline, case-insensitive keys)
+    const actionPattern = /^[ \t]*Action\s*:\s*(.+)$/gim;
+    let actionMatch;
+    while ((actionMatch = actionPattern.exec(text)) !== null) {
+        const name = actionMatch[1].trim();
+        if (!name)
+            continue;
+        // Look for a subsequent Input: line after this Action: line
+        const afterAction = text.slice(actionMatch.index + actionMatch[0].length);
+        const inputMatch = afterAction.match(/^[ \t]*Input\s*:\s*([\s\S]*?)(?=\n[ \t]*(?:Action|Thought|Observation)\s*:|$)/im);
+        let args = {};
+        if (inputMatch) {
+            const rawInput = inputMatch[1].trim();
+            if (rawInput) {
+                try {
+                    const parsed = JSON.parse(rawInput);
+                    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                        args = parsed;
+                    }
+                }
+                catch {
+                    // Non-JSON input — treat as a single string argument
+                    args = { input: rawInput };
+                }
+            }
+        }
+        results.push({ name, arguments: args });
+    }
+    return results;
+}
+/**
+ * Parses tool invocations from an LLM's plain-text response.
+ *
+ * This is the primary entry point for the text-based tool-call fallback.
+ * It first attempts to extract JSON tool calls from markdown code fences
+ * (Format A), then falls back to ReAct-style `Action: / Input:` patterns
+ * (Format B).  Results from both passes are concatenated and de-duplicated
+ * by position (i.e. if the same tool call appears in both formats, both
+ * are included — the caller is responsible for deduplication if needed).
+ *
+ * @param text - Raw text from an LLM response.
+ * @returns An array of parsed tool calls, or an empty array if none were found.
+ *
+ * @example
+ * ```ts
+ * const calls = parseToolCallsFromText(responseText);
+ * for (const call of calls) {
+ *   console.log(`Tool: ${call.name}, Args:`, call.arguments);
+ * }
+ * ```
+ */
+export function parseToolCallsFromText(text) {
+    if (!text || typeof text !== 'string')
+        return [];
+    const fromFences = parseJsonFences(text);
+    const fromReAct = parseReActStyle(text);
+    return [...fromFences, ...fromReAct];
+}
+//# sourceMappingURL=TextToolCallParser.js.map

package/dist/api/TextToolCallParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextToolCallParser.js","sourceRoot":"","sources":["../../src/api/TextToolCallParser.ts"],"names":[],"mappings":"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"}

package/dist/api/agent.d.ts

@@ -27,6 +27,13 @@ export interface AgentOptions extends BaseAgentConfig {
      * When present, forwarded to `observability.usageLedger` internally.
      */
     usageLedger?: AgentOSUsageLedgerOptions;
+    /**
+     * Chain-of-thought reasoning instruction.
+     * - `false` — disable CoT injection.
+     * - `true` (default for agents) — inject the default CoT instruction when tools are present.
+     * - `string` — inject a custom CoT instruction when tools are present.
+     */
+    chainOfThought?: boolean | string;
 }
 /**
  * A named conversation session returned by `Agent.session()`.

package/dist/api/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEpG;;;;;;;GAOG;AACH,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD;;;OAGG;IACH,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,IAAI,OAAO,EAAE,CAAC;IACtB,wFAAwF;IACxF,KAAK,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACxC,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3F;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,gBAAgB,CAAC;IAC9E;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACnC,8EAA8E;IAC9E,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1D,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,iBAAiB,CAAC;IACpE;;;;OAIG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;CAC9D;AAgCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,KAAK,CA8J/C"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC/B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEpG;;;;;;;GAOG;AACH,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD;;;OAGG;IACH,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvC,+EAA+E;IAC/E,QAAQ,IAAI,OAAO,EAAE,CAAC;IACtB,wFAAwF;IACxF,KAAK,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACxC,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3F;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,gBAAgB,CAAC;IAC9E;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACnC,8EAA8E;IAC9E,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC1D,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,iBAAiB,CAAC;IACpE;;;;OAIG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;CAC9D;AAgCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,KAAK,CA+J/C"}

package/dist/api/agent.js

@@ -71,6 +71,7 @@ export function agent(opts) {
         system: buildSystemPrompt(opts),
         tools: opts.tools,
         maxSteps: opts.maxSteps ?? 5,
+        chainOfThought: opts.chainOfThought ?? true,
         apiKey: opts.apiKey,
         baseUrl: opts.baseUrl,
         usageLedger: effectiveLedger,

package/dist/api/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/api/agent.ts"],"names":[],"mappings":"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"}

package/dist/api/generateText.d.ts

@@ -39,6 +39,49 @@ export interface TokenUsage {
     /** Total cost reported by the provider across all steps, when available. */
     costUSD?: number;
 }
+/**
+ * Configuration for the optional plan-then-execute planning phase.
+ *
+ * When `planning` is set to `true` on {@link GenerateTextOptions}, default
+ * settings are used.  Pass a `PlanningConfig` object for fine-grained control
+ * over the planning LLM call.
+ */
+export interface PlanningConfig {
+    /**
+     * Custom system prompt for the planning call.  When omitted a sensible
+     * default that asks the model to produce a numbered JSON plan is used.
+     */
+    systemPrompt?: string;
+    /**
+     * Sampling temperature for the planning call.
+     * Defaults to `0.2` (low creativity, high determinism for plans).
+     */
+    temperature?: number;
+    /**
+     * Hard token cap for the planning response.
+     * Defaults to `2048`.
+     */
+    maxTokens?: number;
+}
+/**
+ * A single step in a plan produced by the planning phase.
+ * Serialised to / from the JSON plan the LLM emits.
+ */
+export interface PlanStep {
+    /** Human-readable description of what this step accomplishes. */
+    description: string;
+    /** Name of the tool to invoke, or `null` when the step is pure reasoning. */
+    tool: string | null;
+    /** Short explanation of why this step is needed. */
+    reasoning: string;
+}
+/**
+ * The complete plan returned by {@link createPlan}.
+ */
+export interface Plan {
+    /** Ordered list of steps the agent should follow. */
+    steps: PlanStep[];
+}
 /**
  * Options for a {@link generateText} call.
  * Either `prompt` or `messages` (or both) must be provided.
@@ -92,6 +135,25 @@ export interface GenerateTextOptions {
     baseUrl?: string;
     /** Optional durable usage ledger configuration for helper-level accounting. */
     usageLedger?: AgentOSUsageLedgerOptions;
+    /**
+     * Chain-of-thought instruction prepended to the system prompt when tools
+     * are available.  Encourages the model to reason explicitly before choosing
+     * an action.
+     *
+     * - `false` (default) — no CoT injection.
+     * - `true` — inject the default CoT instruction.
+     * - `string` — inject a custom CoT instruction.
+     */
+    chainOfThought?: boolean | string;
+    /**
+     * Enable plan-then-execute mode.  When `true` (or a {@link PlanningConfig}),
+     * an upfront LLM call decomposes the task into numbered steps before the
+     * tool-calling loop begins.  The plan is injected into the system prompt
+     * so the model executes with full awareness of the strategy.
+     *
+     * Set to `false` or omit to skip planning entirely (the default).
+     */
+    planning?: boolean | PlanningConfig;
 }
 /**
  * The completed result returned by {@link generateText}.
@@ -130,7 +192,47 @@ export interface GenerateTextResult {
      * schema.  `undefined` when no output schema is configured.
      */
     parsed?: unknown;
+    /**
+     * The plan produced by the planning phase when `planning` is enabled.
+     * `undefined` when planning is disabled or was not requested.
+     */
+    plan?: Plan;
 }
+/**
+ * Default chain-of-thought instruction prepended to the system prompt when
+ * tools are available and `chainOfThought` is enabled.  Encourages the model
+ * to reason explicitly before selecting a tool or crafting a response.
+ */
+export declare const DEFAULT_COT_INSTRUCTION = "Before choosing an action, briefly reason about what you need to do and why. Consider:\n1. What information do you already have?\n2. What information do you need?\n3. Which tool is most appropriate and why?\nThen proceed with your tool call or response.";
+/**
+ * Resolves the chain-of-thought instruction from the `chainOfThought` option.
+ *
+ * @param cot - The `chainOfThought` option value.
+ * @returns The resolved CoT instruction string, or `undefined` if disabled.
+ *
+ * @internal
+ */
+export declare function resolveChainOfThought(cot: boolean | string | undefined): string | undefined;
+/**
+ * Makes a single LLM call to create an execution plan before the tool loop.
+ *
+ * The plan is a lightweight JSON object containing ordered steps.  It is
+ * injected into the system prompt for the subsequent tool loop so the model
+ * executes with full awareness of the strategy.
+ *
+ * @param provider - The resolved LLM provider instance.
+ * @param modelId - Model identifier to use for the planning call.
+ * @param userMessages - The user-supplied messages that describe the task.
+ * @param toolNames - Names of available tools (informational context for the planner).
+ * @param config - Optional planning configuration overrides.
+ * @param totalUsage - Mutable usage aggregator — the planning call's tokens are added here.
+ * @returns The parsed {@link Plan}, or `undefined` if parsing fails gracefully.
+ *
+ * @internal
+ */
+export declare function createPlan(provider: {
+    generateCompletion: (...args: any[]) => Promise<any>;
+}, modelId: string, userMessages: Array<Record<string, unknown>>, toolNames: string[], config: PlanningConfig | undefined, totalUsage: TokenUsage): Promise<Plan | undefined>;
 /**
  * Stateless text generation with optional multi-step tool calling.
  *
@@ -139,6 +241,9 @@ export interface GenerateTextResult {
  * assembled result.  Provider credentials are resolved from environment
  * variables unless overridden in `opts`.
  *
+ * When `planning` is enabled, an upfront LLM call produces a step-by-step plan
+ * that is then injected into the system prompt for the tool loop.
+ *
  * @param opts - Generation options including model, prompt/messages, and optional tools.
  * @returns A promise that resolves to the final text, token usage, tool call log, and finish reason.
  *

package/dist/api/generateText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateText.d.ts","sourceRoot":"","sources":["../../src/api/generateText.ts"],"names":[],"mappings":"AAWA,OAAO,EAAc,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAsB,KAAK,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,kCAAkC;IAClC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,CAAC;IACzB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+GAA+G;IAC/G,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,yBAAyB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,EAAE,UAAU,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;IACzD;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiNzF"}
+{"version":3,"file":"generateText.d.ts","sourceRoot":"","sources":["../../src/api/generateText.ts"],"names":[],"mappings":"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"}