smoltalk 0.15.1 → 0.15.2

package/README.md

@@ -210,6 +210,7 @@ Two provider notes:
 | `stream` | `boolean` | If `true`, returns an `AsyncGenerator<StreamChunk>` instead of a `Promise`. |
 | `thinking` | `{ enabled, budgetTokens? }` | Enable extended thinking / thought signatures (Anthropic and Google). |
 | `reasoningEffort` | `"low" \| "medium" \| "high"` | Provider-agnostic reasoning effort level. |
+| `logprobs` | `{ top?: number }` | Return each generated token's log probability on `result.logprobs`, with `top` alternatives per token. OpenAI only; other providers ignore it. |
 | `maxMessages` | `number` | If the message list exceeds this count, returns a failure instead of calling the API. |
 | `abortSignal` | `AbortSignal` | Cancel an in-flight request. |
 | `toolLoopDetection` | `ToolLoopDetection` | Detect and break tool-call loops. See below. |

package/dist/classes/message/AssistantMessage.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { BaseMessage, MessageClass } from "./BaseMessage.js";
-import { CostEstimate, TextPart, ThinkingBlock, TokenUsage } from "../../types.js";
+import { CostEstimate, TextPart, ThinkingBlock, TokenLogprob, TokenUsage } from "../../types.js";
 import { ChatCompletionMessageParam } from "openai/resources";
 import { Content } from "@google/genai";
 import { ToolCall } from "../ToolCall.js";
@@ -25,6 +25,14 @@ export declare const AssistantMessageJSONSchema: z.ZodObject<{
         text: z.ZodString;
         signature: z.ZodString;
     }, z.core.$strip>>>;
+    logprobs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        token: z.ZodString;
+        logprob: z.ZodNumber;
+        top: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            token: z.ZodString;
+            logprob: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
     rawData: z.ZodOptional<z.ZodAny>;
     usage: z.ZodOptional<z.ZodObject<{
         inputTokens: z.ZodNumber;
@@ -54,6 +62,7 @@ export declare class AssistantMessage extends BaseMessage implements MessageClas
     _refusal?: string | null;
     _toolCalls?: ToolCall[];
     _thinkingBlocks?: ThinkingBlock[];
+    _logprobs?: TokenLogprob[];
     _rawData?: any;
     _usage?: TokenUsage;
     _cost?: CostEstimate;
@@ -63,6 +72,7 @@ export declare class AssistantMessage extends BaseMessage implements MessageClas
         refusal?: string | null;
         toolCalls?: ToolCall[];
         thinkingBlocks?: ThinkingBlock[];
+        logprobs?: TokenLogprob[];
         rawData?: any;
         usage?: TokenUsage;
         cost?: CostEstimate;
@@ -76,6 +86,7 @@ export declare class AssistantMessage extends BaseMessage implements MessageClas
     get toolCalls(): ToolCall[] | undefined;
     get rawData(): any;
     get thinkingBlocks(): ThinkingBlock[] | undefined;
+    get logprobs(): TokenLogprob[] | undefined;
     get usage(): TokenUsage | undefined;
     get cost(): CostEstimate | undefined;
     toJSON(): AssistantMessageJSON;

package/dist/classes/message/AssistantMessage.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { BaseMessage } from "./BaseMessage.js";
-import { CostEstimateSchema, TextPartSchema, ThinkingBlockSchema, TokenUsageSchema, } from "../../types.js";
+import { CostEstimateSchema, TextPartSchema, ThinkingBlockSchema, TokenLogprobSchema, TokenUsageSchema, } from "../../types.js";
 import { ToolCall, ToolCallJSONSchema } from "../ToolCall.js";
 import { getLogger } from "../../util/logger.js";
 export const AssistantMessageJSONSchema = z.object({
@@ -11,6 +11,7 @@ export const AssistantMessageJSONSchema = z.object({
     refusal: z.string().nullable().optional(),
     toolCalls: z.array(ToolCallJSONSchema).optional(),
     thinkingBlocks: z.array(ThinkingBlockSchema).optional(),
+    logprobs: z.array(TokenLogprobSchema).optional(),
     rawData: z.any().optional(),
     usage: TokenUsageSchema.optional(),
     cost: CostEstimateSchema.optional(),
@@ -23,6 +24,7 @@ export class AssistantMessage extends BaseMessage {
     _refusal;
     _toolCalls;
     _thinkingBlocks;
+    _logprobs;
     _rawData;
     _usage;
     _cost;
@@ -34,6 +36,7 @@ export class AssistantMessage extends BaseMessage {
         this._refusal = options.refusal;
         this._toolCalls = options.toolCalls;
         this._thinkingBlocks = options.thinkingBlocks;
+        this._logprobs = options.logprobs;
         this._rawData = options.rawData;
         this._usage = options.usage;
         this._cost = options.cost;
@@ -65,6 +68,9 @@ export class AssistantMessage extends BaseMessage {
     get thinkingBlocks() {
         return this._thinkingBlocks;
     }
+    get logprobs() {
+        return this._logprobs;
+    }
     get usage() {
         return this._usage;
     }
@@ -80,6 +86,7 @@ export class AssistantMessage extends BaseMessage {
             refusal: this.refusal,
             toolCalls: this.toolCalls?.map((tc) => tc.toJSON()),
             thinkingBlocks: this._thinkingBlocks,
+            logprobs: this._logprobs,
             usage: this._usage,
             cost: this._cost,
             rawData: this._rawData,
@@ -100,6 +107,7 @@ export class AssistantMessage extends BaseMessage {
             refusal: result.data.refusal,
             toolCalls: result.data.toolCalls?.map((tc) => ToolCall.fromJSON(tc)),
             thinkingBlocks: result.data.thinkingBlocks,
+            logprobs: result.data.logprobs,
             rawData: result.data.rawData,
             usage: result.data.usage,
             cost: result.data.cost,

package/dist/classes/message/index.d.ts

@@ -8,7 +8,7 @@ import type { AssistantMessageJSON } from "./AssistantMessage.js";
 import type { DeveloperMessageJSON } from "./DeveloperMessage.js";
 import type { SystemMessageJSON } from "./SystemMessage.js";
 import type { ToolMessageJSON } from "./ToolMessage.js";
-import { CostEstimate, TextPart, TokenUsage, UserContentInput, ImagePart, FilePart, AudioPart } from "../../types.js";
+import { CostEstimate, TextPart, TokenLogprob, TokenUsage, UserContentInput, ImagePart, FilePart, AudioPart } from "../../types.js";
 import type { ImageRef, BlobRef } from "../../util/blobRef.js";
 export * from "./AssistantMessage.js";
 export * from "./BaseMessage.js";
@@ -38,6 +38,7 @@ export declare function assistantMessage(content: string | Array<TextPart> | nul
         text: string;
         signature: string;
     }>;
+    logprobs?: TokenLogprob[];
     rawData?: any;
     usage?: TokenUsage;
     cost?: CostEstimate;

package/dist/clients/logprobs.d.ts

@@ -0,0 +1,37 @@
+import type { TokenAlternative, TokenLogprob } from "../types.js";
+export type OpenAILogprob = {
+    token: string;
+    logprob: number;
+    top_logprobs?: TokenAlternative[];
+};
+/** OpenAI's per-token entries (chat `choices[].logprobs.content` and
+ *  Responses `output_text.logprobs`) as smoltalk's shape. Undefined when
+ *  there are none, so the result field stays absent. */
+export declare function fromOpenAILogprobs(entries: OpenAILogprob[] | null | undefined): TokenLogprob[] | undefined;
+/** How many alternatives per token a `logprobs` option asks for, or
+ *  undefined for none. `top: 0` and a missing `top` both mean none. */
+export declare function topAlternatives(option: {
+    top?: number;
+} | undefined): number | undefined;
+type OpenAIChatLogprobParams = {
+    logprobs?: true;
+    top_logprobs?: number;
+};
+/** The chat API's request parameters for a `logprobs` option: `logprobs: true`
+ *  whenever the option is set, `top_logprobs` only when alternatives were
+ *  asked for (the API rejects `top_logprobs` without `logprobs: true`). */
+export declare function openAIChatLogprobParams(option: {
+    top?: number;
+} | undefined): OpenAIChatLogprobParams;
+type ResponsesOutputPart = {
+    type: string;
+    logprobs?: OpenAILogprob[];
+};
+type ResponsesOutputItem = {
+    type: string;
+    content?: ResponsesOutputPart[];
+};
+/** The logprobs of every `output_text` part of a Responses API `output`,
+ *  in order, as smoltalk's shape. */
+export declare function responsesOutputLogprobs(output: ResponsesOutputItem[]): TokenLogprob[] | undefined;
+export {};

package/dist/clients/logprobs.js

@@ -0,0 +1,52 @@
+/** One entry in smoltalk's shape. `top` is present only when there are
+ *  alternatives, so an entry without them serializes without the key. */
+function tokenLogprob(token, logprob, top) {
+    if (top.length === 0) {
+        return { token, logprob };
+    }
+    return { token, logprob, top };
+}
+/** OpenAI's wire alternative also carries a `bytes` field, which smoltalk
+ *  drops; this copy keeps only the token and its logprob. */
+function openAIAlternative(entry) {
+    return { token: entry.token, logprob: entry.logprob };
+}
+/** OpenAI's per-token entries (chat `choices[].logprobs.content` and
+ *  Responses `output_text.logprobs`) as smoltalk's shape. Undefined when
+ *  there are none, so the result field stays absent. */
+export function fromOpenAILogprobs(entries) {
+    if (!entries || entries.length === 0) {
+        return undefined;
+    }
+    return entries.map((entry) => tokenLogprob(entry.token, entry.logprob, (entry.top_logprobs ?? []).map(openAIAlternative)));
+}
+/** How many alternatives per token a `logprobs` option asks for, or
+ *  undefined for none. `top: 0` and a missing `top` both mean none. */
+export function topAlternatives(option) {
+    if (option?.top === undefined || option.top <= 0) {
+        return undefined;
+    }
+    return option.top;
+}
+/** The chat API's request parameters for a `logprobs` option: `logprobs: true`
+ *  whenever the option is set, `top_logprobs` only when alternatives were
+ *  asked for (the API rejects `top_logprobs` without `logprobs: true`). */
+export function openAIChatLogprobParams(option) {
+    if (option === undefined) {
+        return {};
+    }
+    const top = topAlternatives(option);
+    if (top === undefined) {
+        return { logprobs: true };
+    }
+    return { logprobs: true, top_logprobs: top };
+}
+/** The logprobs of every `output_text` part of a Responses API `output`,
+ *  in order, as smoltalk's shape. */
+export function responsesOutputLogprobs(output) {
+    const textParts = output
+        .filter((item) => item.type === "message")
+        .flatMap((item) => item.content ?? [])
+        .filter((part) => part.type === "output_text");
+    return fromOpenAILogprobs(textParts.flatMap((part) => part.logprobs ?? []));
+}

package/dist/clients/openai.js

@@ -10,6 +10,7 @@ import { extractHttpErrorFields } from "../util/httpError.js";
 import { zodToOpenAITool } from "../util/tool.js";
 import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
 import { normalizeOpenAIStopReason } from "../util/stopReason.js";
+import { fromOpenAILogprobs, openAIChatLogprobParams, } from "./logprobs.js";
 import { Model } from "../model.js";
 export class SmolOpenAi extends BaseClient {
     client;
@@ -138,6 +139,7 @@ export class SmolOpenAi extends BaseClient {
             ...(config.reasoningEffort && {
                 reasoning_effort: config.reasoningEffort,
             }),
+            ...openAIChatLogprobParams(config.logprobs),
             ...this.maxTokensParam(config),
             ...sanitizeAttributes(config.rawAttributes),
             ...this.buildRequestExtras(config),
@@ -217,6 +219,7 @@ export class SmolOpenAi extends BaseClient {
         const { usage, cost } = this.calculateUsageAndCost(completion.usage, rawResponse);
         const hostedToolResults = this.parseHostedToolResults(completion, config);
         const rawStopReason = completion.choices[0]?.finish_reason ?? undefined;
+        const logprobs = fromOpenAILogprobs(completion.choices[0]?.logprobs?.content);
         const result = {
             output,
             toolCalls,
@@ -231,6 +234,9 @@ export class SmolOpenAi extends BaseClient {
         if (hostedToolResults.length > 0) {
             result.hostedToolResults = hostedToolResults;
         }
+        if (logprobs !== undefined) {
+            result.logprobs = logprobs;
+        }
         return success(result);
     }
     async *_textStream(config) {
@@ -254,10 +260,15 @@ export class SmolOpenAi extends BaseClient {
         let usage;
         let cost;
         let rawStopReason;
+        const logprobEntries = [];
         for await (const chunk of completion) {
             const chunkFinish = chunk.choices?.[0]?.finish_reason;
             if (chunkFinish)
                 rawStopReason = chunkFinish;
+            const chunkLogprobs = chunk.choices?.[0]?.logprobs?.content;
+            if (chunkLogprobs) {
+                logprobEntries.push(...chunkLogprobs);
+            }
             // Extract usage from the final chunk
             if (chunk.usage) {
                 // Header-based cost (LiteLLM) is unsupported while streaming.
@@ -309,6 +320,7 @@ export class SmolOpenAi extends BaseClient {
             toolCalls.push(toolCall);
             yield { type: "tool_call", toolCall };
         }
+        const logprobs = fromOpenAILogprobs(logprobEntries);
         const result = {
             output: content || null,
             toolCalls,
@@ -320,6 +332,9 @@ export class SmolOpenAi extends BaseClient {
         if (rawStopReason) {
             result.rawStopReason = rawStopReason;
         }
+        if (logprobs !== undefined) {
+            result.logprobs = logprobs;
+        }
         yield { type: "done", result };
     }
 }

package/dist/clients/openaiResponses.js

@@ -7,6 +7,7 @@ import { BaseClient } from "./baseClient.js";
 import { zodToOpenAIResponsesTool } from "../util/tool.js";
 import { responseFormatToJsonSchema } from "../util/jsonSchema.js";
 import { normalizeOpenAIResponsesStopReason } from "../util/stopReason.js";
+import { fromOpenAILogprobs, responsesOutputLogprobs, topAlternatives, } from "./logprobs.js";
 import { sanitizeAttributes } from "../util/util.js";
 import { WEB_SEARCH, webSearchResult, applyHostedToolCost } from "../util/hostedTools.js";
 import { Model } from "../model.js";
@@ -131,6 +132,13 @@ export class SmolOpenAiResponses extends BaseClient {
         if (config.reasoningEffort) {
             request.reasoning = { effort: config.reasoningEffort };
         }
+        if (config.logprobs !== undefined) {
+            request.include = ["message.output_text.logprobs"];
+            const top = topAlternatives(config.logprobs);
+            if (top !== undefined) {
+                request.top_logprobs = top;
+            }
+        }
         Object.assign(request, sanitizeAttributes(config.rawAttributes));
         return request;
     }
@@ -196,6 +204,7 @@ export class SmolOpenAiResponses extends BaseClient {
         const { results: hostedToolResults, cost: finalCost } = applyHostedToolCost(parsed, cost, this.getModel(), this.config.modelData);
         const incompleteReason = response.incomplete_details?.reason;
         const rawStopReason = incompleteReason ?? response.status ?? undefined;
+        const logprobs = responsesOutputLogprobs(response.output);
         const result = {
             output,
             toolCalls,
@@ -210,6 +219,9 @@ export class SmolOpenAiResponses extends BaseClient {
         if (hostedToolResults.length > 0) {
             result.hostedToolResults = hostedToolResults;
         }
+        if (logprobs !== undefined) {
+            result.logprobs = logprobs;
+        }
         return success(result);
     }
     async *_textStream(config) {
@@ -231,6 +243,7 @@ export class SmolOpenAiResponses extends BaseClient {
         let usage;
         let cost;
         let finalResponse;
+        const logprobEntries = [];
         for await (const event of stream) {
             if (event.type === "response.completed" ||
                 event.type === "response.incomplete") {
@@ -242,6 +255,10 @@ export class SmolOpenAiResponses extends BaseClient {
                     yield { type: "text", text: event.delta };
                     break;
                 }
+                case "response.output_text.done": {
+                    logprobEntries.push(...(event.logprobs ?? []));
+                    break;
+                }
                 case "response.function_call_arguments.delta": {
                     const existing = functionCalls.get(event.item_id);
                     if (existing) {
@@ -306,6 +323,7 @@ export class SmolOpenAiResponses extends BaseClient {
         }
         const incompleteReason = finalResponse?.incomplete_details?.reason;
         const rawStopReason = incompleteReason ?? finalResponse?.status ?? undefined;
+        const logprobs = fromOpenAILogprobs(logprobEntries);
         const result = {
             output: content || null,
             toolCalls,
@@ -317,6 +335,9 @@ export class SmolOpenAiResponses extends BaseClient {
         if (rawStopReason) {
             result.rawStopReason = rawStopReason;
         }
+        if (logprobs !== undefined) {
+            result.logprobs = logprobs;
+        }
         yield { type: "done", result };
     }
 }

package/dist/types.d.ts

@@ -108,6 +108,12 @@ export type SmolConfig = {
     };
     /** Provider-agnostic reasoning effort level. */
     reasoningEffort?: "low" | "medium" | "high";
+    /** Ask for the probability of each generated token. `top` is how many
+     *  alternatives to return per token, 0 or absent for none. Honoured by
+     *  OpenAI (both APIs); other providers ignore it. */
+    logprobs?: {
+        top?: number;
+    };
     responseFormatOptions?: Partial<{
         name: string;
         strict: boolean;
@@ -154,6 +160,9 @@ export type PromptResult = {
     output: string | null;
     toolCalls: ToolCall[];
     thinkingBlocks?: ThinkingBlock[];
+    /** Per-token log probabilities, when the call asked for them and the
+     *  provider returned them. Absent otherwise. */
+    logprobs?: TokenLogprob[];
     usage?: TokenUsage;
     cost?: CostEstimate;
     model?: ModelName;
@@ -167,7 +176,7 @@ export type PromptResult = {
      *  with probabilities here. */
     rawData?: unknown;
 };
-export declare function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, rawData, }: Partial<PromptResult>): PromptResult;
+export declare function promptResult({ output, toolCalls, thinkingBlocks, logprobs, usage, cost, model, hostedToolResults, stopReason, rawStopReason, rawData, }: Partial<PromptResult>): PromptResult;
 export type StreamChunk = {
     type: "text";
     text: string;
@@ -216,3 +225,24 @@ export declare const ThinkingBlockSchema: z.ZodObject<{
     text: z.ZodString;
     signature: z.ZodString;
 }, z.z.core.$strip>;
+/** A token the model could have produced at a position, and the log of
+ *  its probability. */
+export type TokenAlternative = {
+    token: string;
+    logprob: number;
+};
+/** One generated token and the log of its probability. `top` holds the
+ *  most likely alternatives at that position when the call asked for them. */
+export type TokenLogprob = {
+    token: string;
+    logprob: number;
+    top?: TokenAlternative[];
+};
+export declare const TokenLogprobSchema: z.ZodObject<{
+    token: z.ZodString;
+    logprob: z.ZodNumber;
+    top: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        token: z.ZodString;
+        logprob: z.ZodNumber;
+    }, z.z.core.$strip>>>;
+}, z.z.core.$strip>;

package/dist/types.js

@@ -4,11 +4,12 @@ import z from "zod";
 export * from "./types/costEstimate.js";
 export * from "./types/tokenUsage.js";
 export * from "./types/stopReason.js";
-export function promptResult({ output, toolCalls, thinkingBlocks, usage, cost, model, hostedToolResults, stopReason, rawStopReason, rawData, }) {
+export function promptResult({ output, toolCalls, thinkingBlocks, logprobs, usage, cost, model, hostedToolResults, stopReason, rawStopReason, rawData, }) {
     return {
         output: output || null,
         toolCalls: toolCalls || [],
         thinkingBlocks: thinkingBlocks,
+        logprobs,
         usage,
         cost,
         model,
@@ -22,3 +23,12 @@ export const ThinkingBlockSchema = z.object({
     text: z.string(),
     signature: z.string(),
 });
+const TokenAlternativeSchema = z.object({
+    token: z.string(),
+    logprob: z.number(),
+});
+export const TokenLogprobSchema = z.object({
+    token: z.string(),
+    logprob: z.number(),
+    top: z.array(TokenAlternativeSchema).optional(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "files": [