@obayd/agentic/src/utils.d.ts

A powerful agent framework for LLMs.

// src/lib/utils.d.ts

/**
 * Converts a streaming Fetch API Response (expected to be Server-Sent Events
 * from an API like OpenAI's chat completions with stream=true) into an
 * async generator yielding text chunks.
 *
 * Assumes the SSE format where data payloads are JSON objects containing
 * a path like `choices[0].delta.content`. Falls back to yielding the raw
 * data line if JSON parsing fails or the path is not found.
 * Handles the `[DONE]` signal.
 *
 * Note: Requires the environment to have Fetch API and related types (like `Response`) defined.
 *
 * @param response The `Response` object obtained from a `fetch` call, expected to have a readable stream body.
 * @returns An async generator yielding string chunks of the response content extracted from SSE data events.
 * @throws {Error} If the response status is not ok (response.ok is false). The error message will contain the status and response body text.
 * @throws {Error} If the response body is null.
 */
export declare function fetchResponseToStream(
  response: Response
): AsyncGenerator<string, void, unknown>;

/**
 * Generates a random string of a specified length.
 * Used for creating unique IDs (e.g., callId, function tags).
 * @param length The desired length of the random string.
 * @returns A random alphanumeric string.
 */
export declare function makeid(length: number): string;

/**
 * Parses an XML-like attribute string into a key-value object.
 * Handles double-quoted, single-quoted, and unquoted values.
 * Attempts to JSON.parse values, falling back to string, number, or boolean if parsing fails.
 * @param attrString The attribute string (e.g., 'key1="value1" key2=123 key3=\'{"json": true}\'').
 * @returns An object containing the parsed attributes. Returns empty object if input is null, undefined, or empty.
 */
export declare function parseAttributes(
  attrString: string | null | undefined
): Record<string, any>;

/**
 * Represents a standard content block structure, often used in message content arrays.
 */
export interface ContentPart {
  type: string; // e.g., 'text', 'image', etc.
  [key: string]: any; // Allow other properties like 'text', 'source', etc.
}

/**
 * Represents the standard structure for a normalized tool result.
 */
export interface NormalizedToolResult {
  /** An array representing the structured content of the result. */
  content: ContentPart[];
  /** An error message if the tool execution resulted in an error. */
  error?: any;
  /** Any additional properties returned by the tool are included here. */
  [key: string]: any;
}

/**
 * Normalizes various tool result formats into a standard structure.
 * Ensures the result has a `content` array (usually containing text objects)
 * and potentially an `error` field and other custom fields.
 *
 * @param result The raw result returned by the tool's action function.
 *        Can be null/undefined, a string, an array (of strings or content objects),
 *        or an object (potentially with 'content', 'error', or other fields).
 * @returns The normalized result object.
 */
export declare function normalizeToolResult(result: any): NormalizedToolResult;