@jaypie/llm 1.1.27 → 1.1.30-rc.0

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/esm/constants.d.ts

@@ -1,4 +1,25 @@
 export declare const PROVIDER: {
+    readonly GEMINI: {
+        readonly MODEL: {
+            readonly DEFAULT: "gemini-2.5-flash";
+            readonly SMALL: "gemini-2.5-flash";
+            readonly LARGE: "gemini-2.5-pro";
+            readonly TINY: "gemini-2.0-flash-lite";
+            readonly GEMINI_2_5_PRO: "gemini-2.5-pro";
+            readonly GEMINI_2_5_FLASH: "gemini-2.5-flash";
+            readonly GEMINI_2_0_FLASH: "gemini-2.0-flash";
+            readonly GEMINI_2_0_FLASH_LITE: "gemini-2.0-flash-lite";
+            readonly GEMINI_1_5_PRO: "gemini-1.5-pro";
+            readonly GEMINI_1_5_FLASH: "gemini-1.5-flash";
+            readonly GEMINI_1_5_FLASH_8B: "gemini-1.5-flash-8b";
+        };
+        readonly MODEL_MATCH_WORDS: readonly ["gemini", "google"];
+        readonly NAME: "gemini";
+        readonly ROLE: {
+            readonly MODEL: "model";
+            readonly USER: "user";
+        };
+    };
     readonly ANTHROPIC: {
         readonly MODEL: {
             readonly DEFAULT: "claude-opus-4-1";
@@ -67,7 +88,7 @@ export declare const PROVIDER: {
         readonly NAME: "openai";
     };
 };
-export type LlmProviderName = typeof PROVIDER.OPENAI.NAME | typeof PROVIDER.ANTHROPIC.NAME;
+export type LlmProviderName = typeof PROVIDER.ANTHROPIC.NAME | typeof PROVIDER.GEMINI.NAME | typeof PROVIDER.OPENAI.NAME;
 export declare const DEFAULT: {
     readonly PROVIDER: {
         readonly MODEL: {

package/dist/esm/index.d.ts

@@ -4,3 +4,4 @@ export type { LlmHistory, LlmInputContent, LlmInputContentFile, LlmInputContentI
 export { LlmMessageRole, LlmMessageType, } from "./types/LlmProvider.interface.js";
 export type { LlmTool } from "./types/LlmTool.interface.js";
 export { JaypieToolkit, toolkit, Toolkit, tools } from "./tools/index.js";
+export { GeminiProvider } from "./providers/gemini/index.js";