@ljoukov/llm 0.1.2 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +214 -12
  2. package/dist/index.cjs +519 -41
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +53 -6
  5. package/dist/index.d.ts +53 -6
  6. package/dist/index.js +518 -41
  7. package/dist/index.js.map +1 -1
  8. package/package.json +1 -1
package/dist/index.d.cts CHANGED
@@ -29,7 +29,7 @@ type LlmToolCallContext = {
29
29
  };
30
30
  declare function getCurrentToolCallContext(): LlmToolCallContext | null;
31
31
  type JsonSchema = Record<string, unknown>;
32
- type LlmRole = "user" | "model" | "system" | "tool";
32
+ type LlmRole = "user" | "assistant" | "system" | "developer" | "tool";
33
33
  type LlmInlineDataPart = {
34
34
  type: "inlineData";
35
35
  data: string;
@@ -93,11 +93,45 @@ type LlmTextStream = {
93
93
  readonly result: Promise<LlmTextResult>;
94
94
  readonly abort: () => void;
95
95
  };
96
+ type DeepPartial<T> = T extends ReadonlyArray<infer Item> ? ReadonlyArray<DeepPartial<Item>> : T extends Array<infer Item> ? Array<DeepPartial<Item>> : T extends object ? {
97
+ [K in keyof T]?: DeepPartial<T[K]>;
98
+ } : T;
99
+ type LlmJsonPartialEvent<T> = {
100
+ readonly type: "json";
101
+ readonly stage: "partial";
102
+ readonly value: DeepPartial<T>;
103
+ };
104
+ type LlmJsonFinalEvent<T> = {
105
+ readonly type: "json";
106
+ readonly stage: "final";
107
+ readonly value: T;
108
+ };
109
+ type LlmJsonStreamEvent<T> = LlmStreamEvent | LlmJsonPartialEvent<T> | LlmJsonFinalEvent<T>;
110
+ type LlmJsonStream<T> = {
111
+ readonly events: AsyncIterable<LlmJsonStreamEvent<T>>;
112
+ readonly result: Promise<{
113
+ readonly value: T;
114
+ readonly rawText: string;
115
+ readonly result: LlmTextResult;
116
+ }>;
117
+ readonly abort: () => void;
118
+ };
119
+ type LlmInputMessage = {
120
+ readonly role: "user" | "assistant" | "system" | "developer";
121
+ readonly content: string | readonly LlmContentPart[];
122
+ };
96
123
  type LlmInput = {
97
- readonly prompt: string;
98
- readonly systemPrompt?: string;
99
- } | {
100
- readonly contents: readonly LlmContent[];
124
+ /**
125
+ * OpenAI-style input:
126
+ * - a plain string becomes one user message
127
+ * - message arrays allow multi-turn + role-specific content
128
+ */
129
+ readonly input: string | readonly LlmInputMessage[];
130
+ /**
131
+ * OpenAI-style top-level instructions.
132
+ * Applied as a system message before input.
133
+ */
134
+ readonly instructions?: string;
101
135
  };
102
136
  type LlmBaseRequest = {
103
137
  readonly model: string;
@@ -117,6 +151,18 @@ type LlmJsonRequest<T> = LlmInput & LlmBaseRequest & {
117
151
  readonly openAiSchemaName?: string;
118
152
  readonly maxAttempts?: number;
119
153
  readonly normalizeJson?: (value: unknown) => unknown;
154
+ /**
155
+ * Optional streaming callback. Useful to surface thought deltas while still
156
+ * returning a single validated JSON result.
157
+ */
158
+ readonly onEvent?: (event: LlmStreamEvent) => void;
159
+ };
160
+ type LlmJsonStreamRequest<T> = LlmJsonRequest<T> & {
161
+ /**
162
+ * - "partial" (default): emit best-effort partial JSON snapshots while streaming.
163
+ * - "final": stream thought deltas but only emit the final validated JSON value.
164
+ */
165
+ readonly streamMode?: "partial" | "final";
120
166
  };
121
167
  declare class LlmJsonCallError extends Error {
122
168
  readonly attempts: ReadonlyArray<{
@@ -195,6 +241,7 @@ declare function convertGooglePartsToLlmParts(parts: readonly Part[]): LlmConten
195
241
  declare function parseJsonFromLlmText(rawText: string): unknown;
196
242
  declare function streamText(request: LlmTextRequest): LlmTextStream;
197
243
  declare function generateText(request: LlmTextRequest): Promise<LlmTextResult>;
244
+ declare function streamJson<T>(request: LlmJsonStreamRequest<T>): LlmJsonStream<T>;
198
245
  declare function generateJson<T>(request: LlmJsonRequest<T>): Promise<{
199
246
  readonly value: T;
200
247
  readonly rawText: string;
@@ -249,4 +296,4 @@ type GeminiConfiguration = {
249
296
  };
250
297
  declare function configureGemini(options?: GeminiConfiguration): void;
251
298
 
252
- 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 };
299
+ export { type ChatGptAuthProfile, type GeminiModelId, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, type LlmInputMessage, LlmJsonCallError, type LlmJsonRequest, type LlmJsonStream, type LlmJsonStreamEvent, type LlmJsonStreamRequest, 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, streamJson, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };
package/dist/index.d.ts CHANGED
@@ -29,7 +29,7 @@ type LlmToolCallContext = {
29
29
  };
30
30
  declare function getCurrentToolCallContext(): LlmToolCallContext | null;
31
31
  type JsonSchema = Record<string, unknown>;
32
- type LlmRole = "user" | "model" | "system" | "tool";
32
+ type LlmRole = "user" | "assistant" | "system" | "developer" | "tool";
33
33
  type LlmInlineDataPart = {
34
34
  type: "inlineData";
35
35
  data: string;
@@ -93,11 +93,45 @@ type LlmTextStream = {
93
93
  readonly result: Promise<LlmTextResult>;
94
94
  readonly abort: () => void;
95
95
  };
96
+ type DeepPartial<T> = T extends ReadonlyArray<infer Item> ? ReadonlyArray<DeepPartial<Item>> : T extends Array<infer Item> ? Array<DeepPartial<Item>> : T extends object ? {
97
+ [K in keyof T]?: DeepPartial<T[K]>;
98
+ } : T;
99
+ type LlmJsonPartialEvent<T> = {
100
+ readonly type: "json";
101
+ readonly stage: "partial";
102
+ readonly value: DeepPartial<T>;
103
+ };
104
+ type LlmJsonFinalEvent<T> = {
105
+ readonly type: "json";
106
+ readonly stage: "final";
107
+ readonly value: T;
108
+ };
109
+ type LlmJsonStreamEvent<T> = LlmStreamEvent | LlmJsonPartialEvent<T> | LlmJsonFinalEvent<T>;
110
+ type LlmJsonStream<T> = {
111
+ readonly events: AsyncIterable<LlmJsonStreamEvent<T>>;
112
+ readonly result: Promise<{
113
+ readonly value: T;
114
+ readonly rawText: string;
115
+ readonly result: LlmTextResult;
116
+ }>;
117
+ readonly abort: () => void;
118
+ };
119
+ type LlmInputMessage = {
120
+ readonly role: "user" | "assistant" | "system" | "developer";
121
+ readonly content: string | readonly LlmContentPart[];
122
+ };
96
123
  type LlmInput = {
97
- readonly prompt: string;
98
- readonly systemPrompt?: string;
99
- } | {
100
- readonly contents: readonly LlmContent[];
124
+ /**
125
+ * OpenAI-style input:
126
+ * - a plain string becomes one user message
127
+ * - message arrays allow multi-turn + role-specific content
128
+ */
129
+ readonly input: string | readonly LlmInputMessage[];
130
+ /**
131
+ * OpenAI-style top-level instructions.
132
+ * Applied as a system message before input.
133
+ */
134
+ readonly instructions?: string;
101
135
  };
102
136
  type LlmBaseRequest = {
103
137
  readonly model: string;
@@ -117,6 +151,18 @@ type LlmJsonRequest<T> = LlmInput & LlmBaseRequest & {
117
151
  readonly openAiSchemaName?: string;
118
152
  readonly maxAttempts?: number;
119
153
  readonly normalizeJson?: (value: unknown) => unknown;
154
+ /**
155
+ * Optional streaming callback. Useful to surface thought deltas while still
156
+ * returning a single validated JSON result.
157
+ */
158
+ readonly onEvent?: (event: LlmStreamEvent) => void;
159
+ };
160
+ type LlmJsonStreamRequest<T> = LlmJsonRequest<T> & {
161
+ /**
162
+ * - "partial" (default): emit best-effort partial JSON snapshots while streaming.
163
+ * - "final": stream thought deltas but only emit the final validated JSON value.
164
+ */
165
+ readonly streamMode?: "partial" | "final";
120
166
  };
121
167
  declare class LlmJsonCallError extends Error {
122
168
  readonly attempts: ReadonlyArray<{
@@ -195,6 +241,7 @@ declare function convertGooglePartsToLlmParts(parts: readonly Part[]): LlmConten
195
241
  declare function parseJsonFromLlmText(rawText: string): unknown;
196
242
  declare function streamText(request: LlmTextRequest): LlmTextStream;
197
243
  declare function generateText(request: LlmTextRequest): Promise<LlmTextResult>;
244
+ declare function streamJson<T>(request: LlmJsonStreamRequest<T>): LlmJsonStream<T>;
198
245
  declare function generateJson<T>(request: LlmJsonRequest<T>): Promise<{
199
246
  readonly value: T;
200
247
  readonly rawText: string;
@@ -249,4 +296,4 @@ type GeminiConfiguration = {
249
296
  };
250
297
  declare function configureGemini(options?: GeminiConfiguration): void;
251
298
 
252
- 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 };
299
+ export { type ChatGptAuthProfile, type GeminiModelId, type JsonSchema, type LlmBaseRequest, type LlmBlockedEvent, type LlmContent, type LlmContentPart, type LlmExecutableTool, type LlmImageData, type LlmImageSize, type LlmInput, type LlmInputMessage, LlmJsonCallError, type LlmJsonRequest, type LlmJsonStream, type LlmJsonStreamEvent, type LlmJsonStreamRequest, 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, streamJson, streamText, stripCodexCitationMarkers, toGeminiJsonSchema, tool };