@ljoukov/llm 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,252 @@
+import { Buffer } from 'node:buffer';
+import { GroundingMetadata, Part } from '@google/genai';
+import { z } from 'zod';
+import { ResponseTextConfig } from 'openai/resources/responses/responses';
+
+type LlmUsageTokens = {
+    readonly promptTokens?: number;
+    readonly cachedTokens?: number;
+    readonly responseTokens?: number;
+    readonly responseImageTokens?: number;
+    readonly thinkingTokens?: number;
+    readonly totalTokens?: number;
+    readonly toolUsePromptTokens?: number;
+};
+declare function estimateCallCostUsd({ modelId, tokens, responseImages, imageSize, }: {
+    modelId: string;
+    tokens: LlmUsageTokens | undefined;
+    responseImages: number;
+    imageSize?: string;
+}): number;
+
+type OpenAiReasoningEffort = "low" | "medium" | "high" | "xhigh";
+
+type LlmToolCallContext = {
+    readonly toolName: string;
+    readonly toolId: string;
+    readonly turn: number;
+    readonly toolIndex: number;
+};
+declare function getCurrentToolCallContext(): LlmToolCallContext | null;
+type JsonSchema = Record<string, unknown>;
+type LlmRole = "user" | "model" | "system" | "tool";
+type LlmInlineDataPart = {
+    type: "inlineData";
+    data: string;
+    mimeType?: string;
+};
+type LlmContentPart = {
+    type: "text";
+    text: string;
+    thought?: boolean;
+} | LlmInlineDataPart;
+type LlmContent = {
+    readonly role: LlmRole;
+    readonly parts: readonly LlmContentPart[];
+};
+type LlmImageSize = "1K" | "2K" | "4K";
+type LlmWebSearchMode = "cached" | "live";
+type LlmToolConfig = {
+    readonly type: "web-search";
+    readonly mode?: LlmWebSearchMode;
+} | {
+    readonly type: "code-execution";
+};
+type LlmTextDeltaEvent = {
+    readonly type: "delta";
+    readonly channel: "response";
+    readonly text: string;
+} | {
+    readonly type: "delta";
+    readonly channel: "thought";
+    readonly text: string;
+};
+type LlmUsageEvent = {
+    readonly type: "usage";
+    readonly usage: LlmUsageTokens;
+    readonly costUsd: number;
+    readonly modelVersion: string;
+};
+type LlmModelEvent = {
+    readonly type: "model";
+    readonly modelVersion: string;
+};
+type LlmBlockedEvent = {
+    readonly type: "blocked";
+};
+type LlmStreamEvent = LlmTextDeltaEvent | LlmUsageEvent | LlmModelEvent | LlmBlockedEvent;
+type LlmProvider = "openai" | "chatgpt" | "gemini";
+type LlmTextResult = {
+    readonly provider: LlmProvider;
+    readonly model: string;
+    readonly modelVersion: string;
+    readonly content?: LlmContent;
+    readonly text: string;
+    readonly thoughts: string;
+    readonly blocked: boolean;
+    readonly usage?: LlmUsageTokens;
+    readonly costUsd: number;
+    readonly grounding?: GroundingMetadata;
+};
+type LlmTextStream = {
+    readonly events: AsyncIterable<LlmStreamEvent>;
+    readonly result: Promise<LlmTextResult>;
+    readonly abort: () => void;
+};
+type LlmInput = {
+    readonly prompt: string;
+    readonly systemPrompt?: string;
+} | {
+    readonly contents: readonly LlmContent[];
+};
+type LlmBaseRequest = {
+    readonly model: string;
+    readonly tools?: readonly LlmToolConfig[];
+    readonly responseMimeType?: string;
+    readonly responseJsonSchema?: JsonSchema;
+    readonly responseModalities?: readonly string[];
+    readonly imageAspectRatio?: string;
+    readonly imageSize?: LlmImageSize;
+    readonly openAiReasoningEffort?: OpenAiReasoningEffort;
+    readonly openAiTextFormat?: ResponseTextConfig["format"];
+    readonly signal?: AbortSignal;
+};
+type LlmTextRequest = LlmInput & LlmBaseRequest;
+type LlmJsonRequest<T> = LlmInput & LlmBaseRequest & {
+    readonly schema: z.ZodType<T>;
+    readonly openAiSchemaName?: string;
+    readonly maxAttempts?: number;
+    readonly normalizeJson?: (value: unknown) => unknown;
+};
+declare class LlmJsonCallError extends Error {
+    readonly attempts: ReadonlyArray<{
+        readonly attempt: number;
+        readonly rawText: string;
+        readonly error: unknown;
+    }>;
+    constructor(message: string, attempts: ReadonlyArray<{
+        readonly attempt: number;
+        readonly rawText: string;
+        readonly error: unknown;
+    }>);
+}
+type LlmImageData = {
+    readonly mimeType?: string;
+    readonly data: Buffer;
+};
+type LlmGenerateImagesRequest = {
+    readonly model: string;
+    readonly stylePrompt: string;
+    readonly styleImages?: readonly LlmImageData[];
+    readonly imagePrompts: readonly string[];
+    readonly imageGradingPrompt: string;
+    readonly maxAttempts?: number;
+    readonly imageAspectRatio?: string;
+    readonly imageSize?: LlmImageSize;
+    readonly signal?: AbortSignal;
+};
+type LlmExecutableTool<Schema extends z.ZodType, Output> = {
+    readonly description?: string;
+    readonly inputSchema: Schema;
+    readonly execute: (input: z.output<Schema>) => Promise<Output> | Output;
+};
+type LlmToolSet = Record<string, LlmExecutableTool<z.ZodType, unknown>>;
+declare function tool<Schema extends z.ZodType, Output>(options: {
+    readonly description?: string;
+    readonly inputSchema: Schema;
+    readonly execute: (input: z.output<Schema>) => Promise<Output> | Output;
+}): LlmExecutableTool<Schema, Output>;
+type LlmToolCallResult = {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly error?: string;
+    readonly callId?: string;
+};
+type LlmToolLoopStep = {
+    readonly step: number;
+    readonly modelVersion: string;
+    readonly text?: string;
+    readonly thoughts?: string;
+    readonly toolCalls: readonly LlmToolCallResult[];
+    readonly usage?: LlmUsageTokens;
+    readonly costUsd: number;
+};
+type LlmToolLoopResult = {
+    readonly text: string;
+    readonly thoughts: string;
+    readonly steps: readonly LlmToolLoopStep[];
+    readonly totalCostUsd: number;
+};
+type LlmToolLoopRequest = LlmInput & {
+    readonly model: string;
+    readonly tools: LlmToolSet;
+    readonly modelTools?: readonly LlmToolConfig[];
+    readonly maxSteps?: number;
+    readonly openAiReasoningEffort?: OpenAiReasoningEffort;
+    readonly onEvent?: (event: LlmStreamEvent) => void;
+    readonly signal?: AbortSignal;
+};
+declare function toGeminiJsonSchema(schema: z.ZodType, options?: {
+    name?: string;
+}): JsonSchema;
+declare function sanitisePartForLogging(part: LlmContentPart): unknown;
+declare function convertGooglePartsToLlmParts(parts: readonly Part[]): LlmContentPart[];
+declare function parseJsonFromLlmText(rawText: string): unknown;
+declare function streamText(request: LlmTextRequest): LlmTextStream;
+declare function generateText(request: LlmTextRequest): Promise<LlmTextResult>;
+declare function generateJson<T>(request: LlmJsonRequest<T>): Promise<{
+    readonly value: T;
+    readonly rawText: string;
+    readonly result: LlmTextResult;
+}>;
+declare function runToolLoop(request: LlmToolLoopRequest): Promise<LlmToolLoopResult>;
+declare function generateImages(request: LlmGenerateImagesRequest): Promise<LlmImageData[]>;
+declare function generateImageInBatches(request: LlmGenerateImagesRequest & {
+    batchSize: number;
+    overlapSize: number;
+}): Promise<LlmImageData[]>;
+declare function stripCodexCitationMarkers(value: string): {
+    text: string;
+    stripped: boolean;
+};
+declare function appendMarkdownSourcesSection(value: string, sources: readonly string[]): string;
+
+/**
+ * Loads `.env.local` from `process.cwd()` once.
+ *
+ * - Does not override already-set `process.env` values.
+ * - Missing file is silently ignored.
+ */
+declare function loadLocalEnv(): void;
+declare function loadEnvFromFile(filePath: string, { override }?: {
+    override?: boolean;
+}): void;
+
+type ChatGptAuthProfile = {
+    readonly access: string;
+    readonly refresh: string;
+    readonly expires: number;
+    readonly accountId: string;
+    readonly idToken?: string;
+};
+declare function encodeChatGptAuthJson(profile: ChatGptAuthProfile): string;
+declare function encodeChatGptAuthJsonB64(profile: ChatGptAuthProfile): string;
+declare function exchangeChatGptOauthCode({ code, verifier, redirectUri, }: {
+    code: string;
+    verifier: string;
+    redirectUri?: string;
+}): Promise<ChatGptAuthProfile>;
+declare function refreshChatGptOauthToken(refreshToken: string): Promise<ChatGptAuthProfile>;
+declare function getChatGptAuthProfile(): Promise<ChatGptAuthProfile>;
+
+declare const GEMINI_MODEL_IDS: readonly ["gemini-3-pro-preview", "gemini-2.5-pro", "gemini-flash-latest", "gemini-flash-lite-latest"];
+type GeminiModelId = (typeof GEMINI_MODEL_IDS)[number];
+declare function isGeminiModelId(value: string): value is GeminiModelId;
+type GeminiConfiguration = {
+    readonly projectId?: string;
+    readonly location?: string;
+};
+declare function configureGemini(options?: GeminiConfiguration): void;
+
+export { type ChatGptAuthProfile, type GeminiModelId, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, LlmJsonCallError, type LlmJsonRequest, type LlmModelEvent, type LlmProvider, type LlmStreamEvent, type LlmTextDeltaEvent, type LlmTextRequest, type LlmTextResult, type LlmTextStream, type LlmToolCallContext, type LlmToolCallResult, type LlmToolConfig, type LlmToolLoopRequest, type LlmToolLoopResult, type LlmToolLoopStep, type LlmToolSet, type LlmUsageEvent, type LlmUsageTokens, type LlmWebSearchMode, appendMarkdownSourcesSection, configureGemini, convertGooglePartsToLlmParts, encodeChatGptAuthJson, encodeChatGptAuthJsonB64, estimateCallCostUsd, exchangeChatGptOauthCode, generateImageInBatches, generateImages, generateJson, generateText, getChatGptAuthProfile, getCurrentToolCallContext, isGeminiModelId, loadEnvFromFile, loadLocalEnv, parseJsonFromLlmText, refreshChatGptOauthToken, runToolLoop, sanitisePartForLogging, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import { Buffer } from 'node:buffer';
+import { GroundingMetadata, Part } from '@google/genai';
+import { z } from 'zod';
+import { ResponseTextConfig } from 'openai/resources/responses/responses';
+
+type LlmUsageTokens = {
+    readonly promptTokens?: number;
+    readonly cachedTokens?: number;
+    readonly responseTokens?: number;
+    readonly responseImageTokens?: number;
+    readonly thinkingTokens?: number;
+    readonly totalTokens?: number;
+    readonly toolUsePromptTokens?: number;
+};
+declare function estimateCallCostUsd({ modelId, tokens, responseImages, imageSize, }: {
+    modelId: string;
+    tokens: LlmUsageTokens | undefined;
+    responseImages: number;
+    imageSize?: string;
+}): number;
+
+type OpenAiReasoningEffort = "low" | "medium" | "high" | "xhigh";
+
+type LlmToolCallContext = {
+    readonly toolName: string;
+    readonly toolId: string;
+    readonly turn: number;
+    readonly toolIndex: number;
+};
+declare function getCurrentToolCallContext(): LlmToolCallContext | null;
+type JsonSchema = Record<string, unknown>;
+type LlmRole = "user" | "model" | "system" | "tool";
+type LlmInlineDataPart = {
+    type: "inlineData";
+    data: string;
+    mimeType?: string;
+};
+type LlmContentPart = {
+    type: "text";
+    text: string;
+    thought?: boolean;
+} | LlmInlineDataPart;
+type LlmContent = {
+    readonly role: LlmRole;
+    readonly parts: readonly LlmContentPart[];
+};
+type LlmImageSize = "1K" | "2K" | "4K";
+type LlmWebSearchMode = "cached" | "live";
+type LlmToolConfig = {
+    readonly type: "web-search";
+    readonly mode?: LlmWebSearchMode;
+} | {
+    readonly type: "code-execution";
+};
+type LlmTextDeltaEvent = {
+    readonly type: "delta";
+    readonly channel: "response";
+    readonly text: string;
+} | {
+    readonly type: "delta";
+    readonly channel: "thought";
+    readonly text: string;
+};
+type LlmUsageEvent = {
+    readonly type: "usage";
+    readonly usage: LlmUsageTokens;
+    readonly costUsd: number;
+    readonly modelVersion: string;
+};
+type LlmModelEvent = {
+    readonly type: "model";
+    readonly modelVersion: string;
+};
+type LlmBlockedEvent = {
+    readonly type: "blocked";
+};
+type LlmStreamEvent = LlmTextDeltaEvent | LlmUsageEvent | LlmModelEvent | LlmBlockedEvent;
+type LlmProvider = "openai" | "chatgpt" | "gemini";
+type LlmTextResult = {
+    readonly provider: LlmProvider;
+    readonly model: string;
+    readonly modelVersion: string;
+    readonly content?: LlmContent;
+    readonly text: string;
+    readonly thoughts: string;
+    readonly blocked: boolean;
+    readonly usage?: LlmUsageTokens;
+    readonly costUsd: number;
+    readonly grounding?: GroundingMetadata;
+};
+type LlmTextStream = {
+    readonly events: AsyncIterable<LlmStreamEvent>;
+    readonly result: Promise<LlmTextResult>;
+    readonly abort: () => void;
+};
+type LlmInput = {
+    readonly prompt: string;
+    readonly systemPrompt?: string;
+} | {
+    readonly contents: readonly LlmContent[];
+};
+type LlmBaseRequest = {
+    readonly model: string;
+    readonly tools?: readonly LlmToolConfig[];
+    readonly responseMimeType?: string;
+    readonly responseJsonSchema?: JsonSchema;
+    readonly responseModalities?: readonly string[];
+    readonly imageAspectRatio?: string;
+    readonly imageSize?: LlmImageSize;
+    readonly openAiReasoningEffort?: OpenAiReasoningEffort;
+    readonly openAiTextFormat?: ResponseTextConfig["format"];
+    readonly signal?: AbortSignal;
+};
+type LlmTextRequest = LlmInput & LlmBaseRequest;
+type LlmJsonRequest<T> = LlmInput & LlmBaseRequest & {
+    readonly schema: z.ZodType<T>;
+    readonly openAiSchemaName?: string;
+    readonly maxAttempts?: number;
+    readonly normalizeJson?: (value: unknown) => unknown;
+};
+declare class LlmJsonCallError extends Error {
+    readonly attempts: ReadonlyArray<{
+        readonly attempt: number;
+        readonly rawText: string;
+        readonly error: unknown;
+    }>;
+    constructor(message: string, attempts: ReadonlyArray<{
+        readonly attempt: number;
+        readonly rawText: string;
+        readonly error: unknown;
+    }>);
+}
+type LlmImageData = {
+    readonly mimeType?: string;
+    readonly data: Buffer;
+};
+type LlmGenerateImagesRequest = {
+    readonly model: string;
+    readonly stylePrompt: string;
+    readonly styleImages?: readonly LlmImageData[];
+    readonly imagePrompts: readonly string[];
+    readonly imageGradingPrompt: string;
+    readonly maxAttempts?: number;
+    readonly imageAspectRatio?: string;
+    readonly imageSize?: LlmImageSize;
+    readonly signal?: AbortSignal;
+};
+type LlmExecutableTool<Schema extends z.ZodType, Output> = {
+    readonly description?: string;
+    readonly inputSchema: Schema;
+    readonly execute: (input: z.output<Schema>) => Promise<Output> | Output;
+};
+type LlmToolSet = Record<string, LlmExecutableTool<z.ZodType, unknown>>;
+declare function tool<Schema extends z.ZodType, Output>(options: {
+    readonly description?: string;
+    readonly inputSchema: Schema;
+    readonly execute: (input: z.output<Schema>) => Promise<Output> | Output;
+}): LlmExecutableTool<Schema, Output>;
+type LlmToolCallResult = {
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly error?: string;
+    readonly callId?: string;
+};
+type LlmToolLoopStep = {
+    readonly step: number;
+    readonly modelVersion: string;
+    readonly text?: string;
+    readonly thoughts?: string;
+    readonly toolCalls: readonly LlmToolCallResult[];
+    readonly usage?: LlmUsageTokens;
+    readonly costUsd: number;
+};
+type LlmToolLoopResult = {
+    readonly text: string;
+    readonly thoughts: string;
+    readonly steps: readonly LlmToolLoopStep[];
+    readonly totalCostUsd: number;
+};
+type LlmToolLoopRequest = LlmInput & {
+    readonly model: string;
+    readonly tools: LlmToolSet;
+    readonly modelTools?: readonly LlmToolConfig[];
+    readonly maxSteps?: number;
+    readonly openAiReasoningEffort?: OpenAiReasoningEffort;
+    readonly onEvent?: (event: LlmStreamEvent) => void;
+    readonly signal?: AbortSignal;
+};
+declare function toGeminiJsonSchema(schema: z.ZodType, options?: {
+    name?: string;
+}): JsonSchema;
+declare function sanitisePartForLogging(part: LlmContentPart): unknown;
+declare function convertGooglePartsToLlmParts(parts: readonly Part[]): LlmContentPart[];
+declare function parseJsonFromLlmText(rawText: string): unknown;
+declare function streamText(request: LlmTextRequest): LlmTextStream;
+declare function generateText(request: LlmTextRequest): Promise<LlmTextResult>;
+declare function generateJson<T>(request: LlmJsonRequest<T>): Promise<{
+    readonly value: T;
+    readonly rawText: string;
+    readonly result: LlmTextResult;
+}>;
+declare function runToolLoop(request: LlmToolLoopRequest): Promise<LlmToolLoopResult>;
+declare function generateImages(request: LlmGenerateImagesRequest): Promise<LlmImageData[]>;
+declare function generateImageInBatches(request: LlmGenerateImagesRequest & {
+    batchSize: number;
+    overlapSize: number;
+}): Promise<LlmImageData[]>;
+declare function stripCodexCitationMarkers(value: string): {
+    text: string;
+    stripped: boolean;
+};
+declare function appendMarkdownSourcesSection(value: string, sources: readonly string[]): string;
+
+/**
+ * Loads `.env.local` from `process.cwd()` once.
+ *
+ * - Does not override already-set `process.env` values.
+ * - Missing file is silently ignored.
+ */
+declare function loadLocalEnv(): void;
+declare function loadEnvFromFile(filePath: string, { override }?: {
+    override?: boolean;
+}): void;
+
+type ChatGptAuthProfile = {
+    readonly access: string;
+    readonly refresh: string;
+    readonly expires: number;
+    readonly accountId: string;
+    readonly idToken?: string;
+};
+declare function encodeChatGptAuthJson(profile: ChatGptAuthProfile): string;
+declare function encodeChatGptAuthJsonB64(profile: ChatGptAuthProfile): string;
+declare function exchangeChatGptOauthCode({ code, verifier, redirectUri, }: {
+    code: string;
+    verifier: string;
+    redirectUri?: string;
+}): Promise<ChatGptAuthProfile>;
+declare function refreshChatGptOauthToken(refreshToken: string): Promise<ChatGptAuthProfile>;
+declare function getChatGptAuthProfile(): Promise<ChatGptAuthProfile>;
+
+declare const GEMINI_MODEL_IDS: readonly ["gemini-3-pro-preview", "gemini-2.5-pro", "gemini-flash-latest", "gemini-flash-lite-latest"];
+type GeminiModelId = (typeof GEMINI_MODEL_IDS)[number];
+declare function isGeminiModelId(value: string): value is GeminiModelId;
+type GeminiConfiguration = {
+    readonly projectId?: string;
+    readonly location?: string;
+};
+declare function configureGemini(options?: GeminiConfiguration): void;
+
+export { type ChatGptAuthProfile, type GeminiModelId, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, LlmJsonCallError, type LlmJsonRequest, type LlmModelEvent, type LlmProvider, type LlmStreamEvent, type LlmTextDeltaEvent, type LlmTextRequest, type LlmTextResult, type LlmTextStream, type LlmToolCallContext, type LlmToolCallResult, type LlmToolConfig, type LlmToolLoopRequest, type LlmToolLoopResult, type LlmToolLoopStep, type LlmToolSet, type LlmUsageEvent, type LlmUsageTokens, type LlmWebSearchMode, appendMarkdownSourcesSection, configureGemini, convertGooglePartsToLlmParts, encodeChatGptAuthJson, encodeChatGptAuthJsonB64, estimateCallCostUsd, exchangeChatGptOauthCode, generateImageInBatches, generateImages, generateJson, generateText, getChatGptAuthProfile, getCurrentToolCallContext, isGeminiModelId, loadEnvFromFile, loadLocalEnv, parseJsonFromLlmText, refreshChatGptOauthToken, runToolLoop, sanitisePartForLogging, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };