@jaypie/llm 1.1.29 → 1.1.30

package/dist/cjs/operate/response/ResponseBuilder.d.ts

@@ -0,0 +1,89 @@
+import { JsonObject, JsonReturn } from "@jaypie/types";
+import { LlmHistory, LlmOperateResponse, LlmResponseStatus, LlmUsage, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+type LlmOutput = LlmOperateResponse["output"];
+export interface ResponseBuilderConfig {
+    model: string;
+    provider: string;
+}
+export interface LlmError {
+    detail?: string;
+    status: number | string;
+    title: string;
+}
+/**
+ * ResponseBuilder provides a fluent API for constructing LlmOperateResponse objects.
+ * It standardizes response construction across providers.
+ */
+export declare class ResponseBuilder {
+    private response;
+    constructor(config: ResponseBuilderConfig);
+    /**
+     * Set the response content
+     */
+    setContent(content: string | JsonObject | undefined): this;
+    /**
+     * Set the response status
+     */
+    setStatus(status: LlmResponseStatus): this;
+    /**
+     * Set an error on the response
+     */
+    setError(error: LlmError): this;
+    /**
+     * Set the history
+     */
+    setHistory(history: LlmHistory): this;
+    /**
+     * Append items to the history
+     */
+    appendToHistory(...items: LlmHistory): this;
+    /**
+     * Set the output
+     */
+    setOutput(output: LlmOutput): this;
+    /**
+     * Append items to the output
+     */
+    appendToOutput(...items: LlmOutput): this;
+    /**
+     * Add a raw provider response
+     */
+    addResponse(response: JsonReturn): this;
+    /**
+     * Add a usage entry for a single API call
+     */
+    addUsage(usage: LlmUsageItem): this;
+    /**
+     * Set the entire usage array
+     */
+    setUsage(usage: LlmUsage): this;
+    /**
+     * Get the current usage array for modifications
+     */
+    getUsage(): LlmUsage;
+    /**
+     * Get the current history for modifications
+     */
+    getHistory(): LlmHistory;
+    /**
+     * Get the current output for modifications
+     */
+    getOutput(): LlmOutput;
+    /**
+     * Mark response as completed
+     */
+    complete(): this;
+    /**
+     * Mark response as incomplete (e.g., max turns exceeded)
+     */
+    incomplete(): this;
+    /**
+     * Build and return the final response object
+     */
+    build(): LlmOperateResponse;
+}
+/**
+ * Factory function to create a new ResponseBuilder
+ */
+export declare function createResponseBuilder(config: ResponseBuilderConfig): ResponseBuilder;
+export {};

package/dist/cjs/operate/response/index.d.ts

@@ -0,0 +1,2 @@
+export { createResponseBuilder, ResponseBuilder } from "./ResponseBuilder.js";
+export type { LlmError, ResponseBuilderConfig } from "./ResponseBuilder.js";

package/dist/cjs/operate/retry/RetryExecutor.d.ts

@@ -0,0 +1,39 @@
+import { HookRunner, LlmHooks } from "../hooks/HookRunner.js";
+import { RetryPolicy } from "./RetryPolicy.js";
+export interface RetryContext {
+    input: unknown;
+    options?: unknown;
+    providerRequest: unknown;
+}
+export interface ErrorClassifier {
+    isRetryable(error: unknown): boolean;
+    isKnownError(error: unknown): boolean;
+}
+export interface RetryExecutorConfig {
+    errorClassifier: ErrorClassifier;
+    hookRunner?: HookRunner;
+    policy?: RetryPolicy;
+}
+export interface ExecuteOptions {
+    context: RetryContext;
+    hooks?: LlmHooks;
+}
+/**
+ * RetryExecutor handles the retry loop logic for LLM API calls.
+ * It provides exponential backoff, error classification, and hook execution.
+ */
+export declare class RetryExecutor {
+    private readonly policy;
+    private readonly hookRunner;
+    private readonly errorClassifier;
+    constructor(config: RetryExecutorConfig);
+    /**
+     * Execute an operation with retry logic
+     *
+     * @param operation - The async operation to execute
+     * @param options - Execution options including context and hooks
+     * @returns The result of the operation
+     * @throws BadGatewayError if all retries are exhausted or error is not retryable
+     */
+    execute<T>(operation: () => Promise<T>, options: ExecuteOptions): Promise<T>;
+}

package/dist/cjs/operate/retry/RetryPolicy.d.ts

@@ -0,0 +1,35 @@
+export declare const DEFAULT_INITIAL_DELAY_MS = 1000;
+export declare const DEFAULT_MAX_DELAY_MS = 32000;
+export declare const DEFAULT_BACKOFF_FACTOR = 2;
+export declare const DEFAULT_MAX_RETRIES = 6;
+export declare const MAX_RETRIES_ABSOLUTE_LIMIT = 72;
+export interface RetryPolicyConfig {
+    /** Initial delay in milliseconds before first retry. Default: 1000 */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds between retries. Default: 32000 */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff. Default: 2 */
+    backoffFactor?: number;
+    /** Maximum number of retries. Default: 6 */
+    maxRetries?: number;
+}
+/**
+ * RetryPolicy encapsulates retry configuration and delay calculation
+ * for the operate loop's retry logic.
+ */
+export declare class RetryPolicy {
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly backoffFactor: number;
+    readonly maxRetries: number;
+    constructor(config?: RetryPolicyConfig);
+    /**
+     * Calculate the delay for a given attempt number (0-indexed)
+     */
+    getDelayForAttempt(attempt: number): number;
+    /**
+     * Check if another retry should be attempted
+     */
+    shouldRetry(currentAttempt: number): boolean;
+}
+export declare const defaultRetryPolicy: RetryPolicy;

package/dist/cjs/operate/retry/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_BACKOFF_FACTOR, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MAX_RETRIES, defaultRetryPolicy, MAX_RETRIES_ABSOLUTE_LIMIT, RetryPolicy, } from "./RetryPolicy.js";
+export type { RetryPolicyConfig } from "./RetryPolicy.js";
+export { RetryExecutor } from "./RetryExecutor.js";
+export type { ErrorClassifier, ExecuteOptions, RetryContext, RetryExecutorConfig, } from "./RetryExecutor.js";

package/dist/cjs/operate/types.d.ts

@@ -0,0 +1,136 @@
+import { JsonObject } from "@jaypie/types";
+import { LlmHistory, LlmMessageType, LlmOperateOptions, LlmUsageItem } from "../types/LlmProvider.interface.js";
+import { Toolkit } from "../tools/Toolkit.class.js";
+/**
+ * Standardized tool call representation across providers
+ */
+export interface StandardToolCall {
+    /** Unique identifier for this tool call */
+    callId: string;
+    /** Name of the tool being called */
+    name: string;
+    /** JSON string of arguments */
+    arguments: string;
+    /** Original provider-specific tool call object */
+    raw: unknown;
+}
+/**
+ * Standardized tool result to send back to the provider
+ */
+export interface StandardToolResult {
+    /** The call ID this result corresponds to */
+    callId: string;
+    /** JSON string of the result */
+    output: string;
+    /** Whether the tool call was successful */
+    success: boolean;
+    /** Error message if the tool call failed */
+    error?: string;
+}
+/**
+ * Parsed response from a provider API call
+ */
+export interface ParsedResponse {
+    /** The text content of the response, if any */
+    content?: string | JsonObject;
+    /** Whether the response contains tool calls */
+    hasToolCalls: boolean;
+    /** The stop reason from the provider */
+    stopReason?: string;
+    /** Usage information for this response */
+    usage?: LlmUsageItem;
+    /** Raw provider response for storage */
+    raw: unknown;
+}
+/**
+ * Context passed to hooks and utilities during the operate loop
+ */
+export interface OperateContext {
+    /** The hooks configuration */
+    hooks: LlmOperateOptions["hooks"];
+    /** The operate options */
+    options: LlmOperateOptions;
+}
+/**
+ * Provider-agnostic request options
+ * Each adapter will convert this to provider-specific format
+ */
+export interface OperateRequest {
+    /** The model to use */
+    model: string;
+    /** The conversation history/messages */
+    messages: LlmHistory;
+    /** System instructions (if separate from messages) */
+    system?: string;
+    /** Additional instructions to append */
+    instructions?: string;
+    /** Tools available for the model */
+    tools?: ProviderToolDefinition[];
+    /** Structured output format */
+    format?: JsonObject;
+    /** Provider-specific options */
+    providerOptions?: JsonObject;
+    /** User identifier for tracking */
+    user?: string;
+}
+/**
+ * Tool definition in provider-agnostic format
+ */
+export interface ProviderToolDefinition {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** JSON Schema for parameters */
+    parameters: JsonObject;
+}
+/**
+ * Categories of errors for retry logic
+ */
+export declare enum ErrorCategory {
+    /** Error is transient and can be retried */
+    Retryable = "retryable",
+    /** Error is due to rate limiting */
+    RateLimit = "rate_limit",
+    /** Error cannot be recovered from */
+    Unrecoverable = "unrecoverable",
+    /** Error type is unknown */
+    Unknown = "unknown"
+}
+/**
+ * Classified error with metadata
+ */
+export interface ClassifiedError {
+    /** The original error */
+    error: unknown;
+    /** Category of the error */
+    category: ErrorCategory;
+    /** Whether a retry should be attempted */
+    shouldRetry: boolean;
+    /** Suggested delay before retry (if applicable) */
+    suggestedDelayMs?: number;
+}
+import type { ResponseBuilder } from "./response/ResponseBuilder.js";
+/**
+ * Internal state of the operate loop
+ */
+export interface OperateLoopState {
+    /** Current conversation input/messages */
+    currentInput: LlmHistory;
+    /** Current turn number (0-indexed, incremented at start of each turn) */
+    currentTurn: number;
+    /** Formatted output schema for structured output */
+    formattedFormat?: JsonObject;
+    /** Formatted tools for the provider */
+    formattedTools?: ProviderToolDefinition[];
+    /** Maximum allowed turns */
+    maxTurns: number;
+    /** Response builder instance */
+    responseBuilder: ResponseBuilder;
+    /** The toolkit for tool calls */
+    toolkit?: Toolkit;
+}
+/**
+ * Re-export message type for convenience in adapters
+ */
+export { LlmMessageType };

package/dist/cjs/providers/anthropic/AnthropicProvider.class.d.ts

@@ -3,6 +3,7 @@ import { LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateOptions, LlmO
 export declare class AnthropicProvider implements LlmProvider {
     private model;
     private _client?;
+    private _operateLoop?;
     private apiKey?;
     private log;
     private conversationHistory;
@@ -10,6 +11,7 @@ export declare class AnthropicProvider implements LlmProvider {
         apiKey?: string;
     });
     private getClient;
+    private getOperateLoop;
     send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
     operate(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
 }

package/dist/cjs/providers/gemini/GeminiProvider.class.d.ts

@@ -0,0 +1,17 @@
+import { JsonObject } from "@jaypie/types";
+import { LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateOptions, LlmOperateResponse, LlmProvider } from "../../types/LlmProvider.interface.js";
+export declare class GeminiProvider implements LlmProvider {
+    private model;
+    private _client?;
+    private _operateLoop?;
+    private apiKey?;
+    private log;
+    private conversationHistory;
+    constructor(model?: string, { apiKey }?: {
+        apiKey?: string;
+    });
+    private getClient;
+    private getOperateLoop;
+    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    operate(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
+}

package/dist/cjs/providers/gemini/index.d.ts

@@ -0,0 +1,3 @@
+export { GeminiProvider } from "./GeminiProvider.class.js";
+export * from "./types.js";
+export * from "./utils.js";

package/dist/cjs/providers/gemini/types.d.ts

@@ -0,0 +1,185 @@
+import { JsonObject } from "@jaypie/types";
+import { LlmMessageRole } from "../../types/LlmProvider.interface.js";
+export declare const ROLE_MAP: Record<LlmMessageRole, "user" | "model">;
+/**
+ * A part of content - can be text, function call, or function response
+ */
+export interface GeminiPart {
+    text?: string;
+    thought?: boolean;
+    thoughtSignature?: string;
+    functionCall?: GeminiFunctionCall;
+    functionResponse?: GeminiFunctionResponse;
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+    fileData?: {
+        mimeType?: string;
+        fileUri: string;
+    };
+}
+/**
+ * A function call made by the model
+ */
+export interface GeminiFunctionCall {
+    name?: string;
+    args?: Record<string, unknown>;
+    id?: string;
+}
+/**
+ * A response to a function call
+ */
+export interface GeminiFunctionResponse {
+    name: string;
+    response: Record<string, unknown>;
+}
+/**
+ * Content represents a message in the conversation
+ */
+export interface GeminiContent {
+    role: "user" | "model";
+    parts?: GeminiPart[];
+}
+/**
+ * Function declaration for tools
+ */
+export interface GeminiFunctionDeclaration {
+    name: string;
+    description: string;
+    parameters: JsonObject;
+}
+/**
+ * Tool definition containing function declarations
+ */
+export interface GeminiTool {
+    functionDeclarations?: GeminiFunctionDeclaration[];
+    googleSearch?: Record<string, unknown>;
+    codeExecution?: Record<string, unknown>;
+}
+/**
+ * Configuration for a generate content request
+ * This is a simplified internal type - we use the SDK's actual types at runtime
+ */
+export interface GeminiGenerateContentConfig {
+    systemInstruction?: string;
+    tools?: GeminiTool[];
+    toolConfig?: {
+        functionCallingConfig?: {
+            mode?: "AUTO" | "ANY" | "NONE";
+            allowedFunctionNames?: string[];
+        };
+    };
+    responseMimeType?: string;
+    responseJsonSchema?: JsonObject;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    maxOutputTokens?: number;
+    stopSequences?: string[];
+    candidateCount?: number;
+}
+/**
+ * Request structure for generateContent API
+ */
+export interface GeminiRequest {
+    model: string;
+    contents: GeminiContent[];
+    config?: GeminiGenerateContentConfig;
+}
+/**
+ * Usage metadata from the response
+ */
+export interface GeminiUsageMetadata {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    totalTokenCount?: number;
+    thoughtsTokenCount?: number;
+    cachedContentTokenCount?: number;
+}
+/**
+ * A response candidate from the model
+ */
+export interface GeminiCandidate {
+    content?: GeminiContent;
+    finishReason?: string;
+    index?: number;
+    safetyRatings?: Array<{
+        category: string;
+        probability: string;
+        blocked?: boolean;
+    }>;
+    citationMetadata?: {
+        citations?: Array<{
+            startIndex?: number;
+            endIndex?: number;
+            uri?: string;
+            title?: string;
+            license?: string;
+            publicationDate?: {
+                year?: number;
+                month?: number;
+                day?: number;
+            };
+        }>;
+    };
+    tokenCount?: number;
+    avgLogprobs?: number;
+}
+/**
+ * Prompt feedback from the API
+ */
+export interface GeminiPromptFeedback {
+    blockReason?: string;
+    safetyRatings?: Array<{
+        category: string;
+        probability: string;
+        blocked?: boolean;
+    }>;
+}
+/**
+ * Raw response from Gemini API
+ */
+export interface GeminiRawResponse {
+    candidates?: GeminiCandidate[];
+    promptFeedback?: GeminiPromptFeedback;
+    usageMetadata?: GeminiUsageMetadata;
+    modelVersion?: string;
+    responseId?: string;
+    createTime?: string;
+    text?: string;
+    functionCalls?: GeminiFunctionCall[];
+}
+/**
+ * Error information from Gemini API
+ */
+export interface GeminiErrorInfo {
+    status?: number;
+    code?: number;
+    message?: string;
+    details?: Array<{
+        "@type"?: string;
+        reason?: string;
+        domain?: string;
+        metadata?: Record<string, string>;
+    }>;
+}
+/**
+ * Finish reasons returned by Gemini
+ */
+export declare const FINISH_REASON: {
+    readonly FINISH_REASON_UNSPECIFIED: "FINISH_REASON_UNSPECIFIED";
+    readonly STOP: "STOP";
+    readonly MAX_TOKENS: "MAX_TOKENS";
+    readonly SAFETY: "SAFETY";
+    readonly RECITATION: "RECITATION";
+    readonly LANGUAGE: "LANGUAGE";
+    readonly OTHER: "OTHER";
+    readonly BLOCKLIST: "BLOCKLIST";
+    readonly PROHIBITED_CONTENT: "PROHIBITED_CONTENT";
+    readonly SPII: "SPII";
+    readonly MALFORMED_FUNCTION_CALL: "MALFORMED_FUNCTION_CALL";
+    readonly IMAGE_SAFETY: "IMAGE_SAFETY";
+    readonly UNEXPECTED_TOOL_CALL: "UNEXPECTED_TOOL_CALL";
+};
+export type GeminiFinishReason = (typeof FINISH_REASON)[keyof typeof FINISH_REASON];

package/dist/cjs/providers/gemini/utils.d.ts

@@ -0,0 +1,51 @@
+import { log as defaultLog } from "@jaypie/core";
+import { GoogleGenAI } from "@google/genai";
+import { LlmMessageOptions } from "../../types/LlmProvider.interface.js";
+export declare const getLogger: () => {
+    debug: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    error: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    fatal: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    info: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    trace: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    warn: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    var(key: string | Record<string, unknown>, value?: unknown): void;
+    with(tags: Record<string, unknown>): typeof defaultLog;
+    tag(key: string | string[] | Record<string, unknown> | null, value?: string): void;
+    untag(tags: string | string[] | Record<string, unknown> | null): void;
+    lib(options: {
+        level?: string;
+        lib?: string;
+        tags?: Record<string, unknown>;
+    }): typeof defaultLog;
+};
+export declare function initializeClient({ apiKey, }?: {
+    apiKey?: string;
+}): Promise<GoogleGenAI>;
+export interface ChatMessage {
+    role: "user" | "model";
+    content: string;
+}
+export declare function formatSystemMessage(systemPrompt: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): string;
+export declare function formatUserMessage(message: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function prepareMessages(message: string, { data, placeholders }?: LlmMessageOptions): {
+    messages: ChatMessage[];
+    systemInstruction?: string;
+};

package/dist/cjs/providers/openai/OpenAiProvider.class.d.ts

@@ -3,6 +3,7 @@ import { LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateOptions, LlmO
 export declare class OpenAiProvider implements LlmProvider {
     private model;
     private _client?;
+    private _operateLoop?;
     private apiKey?;
     private log;
     private conversationHistory;
@@ -10,6 +11,7 @@ export declare class OpenAiProvider implements LlmProvider {
         apiKey?: string;
     });
     private getClient;
+    private getOperateLoop;
     send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
     operate(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
 }

package/dist/cjs/providers/openrouter/OpenRouterProvider.class.d.ts

@@ -0,0 +1,17 @@
+import { JsonObject } from "@jaypie/types";
+import { LlmHistory, LlmInputMessage, LlmMessageOptions, LlmOperateOptions, LlmOperateResponse, LlmProvider } from "../../types/LlmProvider.interface.js";
+export declare class OpenRouterProvider implements LlmProvider {
+    private model;
+    private _client?;
+    private _operateLoop?;
+    private apiKey?;
+    private log;
+    private conversationHistory;
+    constructor(model?: string, { apiKey }?: {
+        apiKey?: string;
+    });
+    private getClient;
+    private getOperateLoop;
+    send(message: string, options?: LlmMessageOptions): Promise<string | JsonObject>;
+    operate(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
+}

package/dist/cjs/providers/openrouter/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenRouterProvider } from "./OpenRouterProvider.class.js";
+export * from "./utils.js";

package/dist/cjs/providers/openrouter/utils.d.ts

@@ -0,0 +1,49 @@
+import { log as defaultLog } from "@jaypie/core";
+import { OpenRouter } from "@openrouter/sdk";
+import { LlmMessageOptions } from "../../types/LlmProvider.interface.js";
+export declare const getLogger: () => {
+    debug: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    error: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    fatal: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    info: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    trace: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    warn: {
+        (...args: unknown[]): void;
+        var(key: string | Record<string, unknown>, value?: unknown): void;
+    };
+    var(key: string | Record<string, unknown>, value?: unknown): void;
+    with(tags: Record<string, unknown>): typeof defaultLog;
+    tag(key: string | string[] | Record<string, unknown> | null, value?: string): void;
+    untag(tags: string | string[] | Record<string, unknown> | null): void;
+    lib(options: {
+        level?: string;
+        lib?: string;
+        tags?: Record<string, unknown>;
+    }): typeof defaultLog;
+};
+export declare function initializeClient({ apiKey, }?: {
+    apiKey?: string;
+}): Promise<OpenRouter>;
+export declare function getDefaultModel(): string;
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export declare function formatSystemMessage(systemPrompt: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function formatUserMessage(message: string, { data, placeholders }?: Pick<LlmMessageOptions, "data" | "placeholders">): ChatMessage;
+export declare function prepareMessages(message: string, { system, data, placeholders }?: LlmMessageOptions): ChatMessage[];