smoltalk 0.0.5 → 0.0.7

package/README.md

@@ -1,26 +1,120 @@
 # Smoltalk
 
+Smoltalk is a package that exposes a common interface across different LLM providers. It exists because I think it's important to have an npm package that allows users to try out different kinds of LLMs, and prevents vendor lock-in. Using a different LLM should be as simple as switching out a model name.
+
 ## Install
 
 ```bash 
 pnpm install smoltalk
 ```
 
-## Usage
+## Quickstart
 
 ```typescript
 import { getClient } from "smoltalk";
 
 const client = getClient({
-  apiKey: process.env.GEMINI_API_KEY || "",
+  openAiApiKey: process.env.OPENAI_API_KEY || "",
+  googleApiKey: process.env.GEMINI_API_KEY || "",
   logLevel: "debug",
   model: "gemini-2.0-flash-lite",
 });
 
 async function main() {
-  const resp = await client.text("Hello, how are you?");
+  const resp = await client.prompt("Hello, how are you?");
   console.log(resp);
 }
 
 main();
-```
+```
+
+## Longer tutorial
+To use Smoltak, you first create a client:
+
+```ts
+import { getClient } from "smoltalk";
+
+const client = getClient({
+  openAiApiKey: process.env.OPENAI_API_KEY || "",
+  googleApiKey: process.env.GEMINI_API_KEY || "",
+  logLevel: "debug",
+  model: "gemini-2.0-flash-lite",
+});
+```
+
+Then you can call different methods on the client. The simplest is `prompt`:
+
+```ts
+const resp = await client.prompt("Hello, how are you?");
+```
+
+If you want tool calling, structured output, etc., `text` may be a cleaner option:
+
+```ts
+let messages: Message[] = [];
+  messages.push(
+    userMessage(
+      "Please use the add function to add the following numbers: 3 and 5"
+    )
+  );
+  const resp = await client.text({
+    messages,
+  });
+```
+
+Here is an example with tool calling:
+
+```ts
+function add({ a, b }: { a: number; b: number }): number {
+  return a + b;
+}
+
+const addTool = {
+  name: "add",
+  description: "Adds two numbers together and returns the result.",
+  schema: z.object({
+    a: z.number().describe("The first number to add"),
+    b: z.number().describe("The second number to add"),
+  }),
+};
+
+const resp = await client.text({
+  messages,
+  tools: [addTool]
+});
+
+```
+
+Here is an example with structured output:
+
+```ts
+const resp = await client.text({
+  messages,
+  responseFormat: z.object({
+    result: z.number(),
+  });
+});
+```
+
+A couple of design decisions to note:
+- You specify different API keys using different parameter names. This means you could set a couple of different API keys and then be able to change the model name without worrying about the keys, which makes things easier for code generation.
+- The schema for tools and structured outputs is defined using Zod.
+- Parameter names are camel case, as that is the naming convention in TypeScript. They are converted to snake case for you if required by the APIs.
+
+## Prior art
+- Langchain
+OpenRouter
+- Vercel AI
+
+These are all good options, but they are quite heavy, and I wanted a lighter option. That said, you may be better off with one of the above alternatives:
+- They are backed by a business and are more likely to be responsive.
+- They support way more functionality and providers. Smoltalk currently supports just a subset of functionality for OpenAI and Google.
+
+## Functionality
+Smoltalk pretty much lets you generate text using an OpenAI or Google model, with support for function calling and structured output, and that's it. I will add functionality and providers sporadically when I have time and need.
+
+## Contributing
+This repo could use some help! Any of the following contributions would be helpful:
+- Adding support for API parameters or endpoints
+- Adding support for different providers
+- Updating the list of models

package/dist/classes/ToolCall.d.ts

@@ -1,3 +1,4 @@
+import { FunctionCall } from "@google/genai";
 export type ToolCallOptions = {};
 export declare class ToolCall {
     private _id;
@@ -8,4 +9,8 @@ export declare class ToolCall {
     get id(): string;
     get name(): string;
     get arguments(): Record<string, any>;
+    toOpenAI(): any;
+    toGoogle(): {
+        functionCall: FunctionCall;
+    };
 }

package/dist/classes/ToolCall.js

@@ -30,4 +30,22 @@ export class ToolCall {
     get arguments() {
         return this._arguments;
     }
+    toOpenAI() {
+        return {
+            id: this._id,
+            type: "function",
+            function: {
+                name: this.name,
+                arguments: JSON.stringify(this.arguments),
+            },
+        };
+    }
+    toGoogle() {
+        return {
+            functionCall: {
+                name: this.name,
+                args: this.arguments,
+            },
+        };
+    }
 }

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

@@ -2,30 +2,28 @@ import { BaseMessage, MessageClass } from "./BaseMessage.js";
 import { TextPart } from "../../types.js";
 import { ChatCompletionMessageParam } from "openai/resources";
 import { Content } from "@google/genai";
+import { ToolCall } from "../ToolCall.js";
 export declare class AssistantMessage extends BaseMessage implements MessageClass {
     _role: "assistant";
     _content: string | Array<TextPart> | null;
     _name?: string;
     _audio?: any | null;
-    _function_call?: any | null;
     _refusal?: string | null;
-    _tool_calls?: Array<any>;
+    _toolCalls?: ToolCall[];
     _rawData?: any;
     constructor(content: string | Array<TextPart> | null, options?: {
         name?: string;
         audio?: any | null;
-        function_call?: any | null;
         refusal?: string | null;
-        tool_calls?: Array<any>;
+        toolCalls?: ToolCall[];
         rawData?: any;
     });
     get content(): string;
     get role(): "assistant";
     get name(): string | undefined;
     get audio(): any | null | undefined;
-    get function_call(): any | null | undefined;
     get refusal(): string | null | undefined;
-    get tool_calls(): Array<any> | undefined;
+    get toolCalls(): ToolCall[] | undefined;
     get rawData(): any;
     toOpenAIMessage(): ChatCompletionMessageParam;
     toGoogleMessage(): Content;

package/dist/classes/message/AssistantMessage.js

@@ -4,18 +4,16 @@ export class AssistantMessage extends BaseMessage {
     _content;
     _name;
     _audio;
-    _function_call;
     _refusal;
-    _tool_calls;
+    _toolCalls;
     _rawData;
     constructor(content, options = {}) {
         super();
         this._content = content;
         this._name = options.name;
         this._audio = options.audio;
-        this._function_call = options.function_call;
         this._refusal = options.refusal;
-        this._tool_calls = options.tool_calls;
+        this._toolCalls = options.toolCalls;
         this._rawData = options.rawData;
     }
     get content() {
@@ -35,22 +33,33 @@ export class AssistantMessage extends BaseMessage {
     get audio() {
         return this._audio;
     }
-    get function_call() {
-        return this._function_call;
-    }
     get refusal() {
         return this._refusal;
     }
-    get tool_calls() {
-        return this._tool_calls;
+    get toolCalls() {
+        return this._toolCalls;
     }
     get rawData() {
         return this._rawData;
     }
     toOpenAIMessage() {
-        return { role: this.role, content: this.content, name: this.name };
+        return {
+            role: this.role,
+            content: this.content,
+            name: this.name,
+            tool_calls: this.toolCalls?.map((tc) => tc.toOpenAI()),
+        };
     }
     toGoogleMessage() {
-        return { role: "model", parts: [{ text: this.content }] };
+        const parts = [];
+        if (this.content) {
+            parts.push({ text: this.content });
+        }
+        if (this.toolCalls) {
+            for (const tc of this.toolCalls) {
+                parts.push(tc.toGoogle());
+            }
+        }
+        return { role: "model", parts };
     }
 }

package/dist/classes/message/UserMessage.js

@@ -23,7 +23,11 @@ export class UserMessage extends BaseMessage {
         return this._rawData;
     }
     toOpenAIMessage() {
-        return { role: this.role, content: this.content, name: this.name };
+        return {
+            role: this.role,
+            content: this.content,
+            name: this.name,
+        };
     }
     toGoogleMessage() {
         return { role: this.role, parts: [{ text: this.content }] };

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

@@ -17,9 +17,8 @@ export declare function userMessage(content: string, options?: {
 export declare function assistantMessage(content: string | Array<TextPart> | null, options?: {
     name?: string;
     audio?: any | null;
-    function_call?: any | null;
     refusal?: string | null;
-    tool_calls?: Array<any>;
+    toolCalls?: Array<any>;
     rawData?: any;
 }): AssistantMessage;
 export declare function developerMessage(content: string | Array<TextPart>, options?: {

package/dist/clients/google.js

@@ -1,9 +1,9 @@
 import { GoogleGenAI } from "@google/genai";
+import { ToolCall } from "../classes/ToolCall.js";
 import { getLogger } from "../logger.js";
 import { success, } from "../types.js";
+import { zodToGoogleTool } from "../util/tool.js";
 import { BaseClient } from "./baseClient.js";
-import { ToolCall } from "../classes/ToolCall.js";
-import { convertOpenAIToolToGoogle } from "../util/common.js";
 export class SmolGoogle extends BaseClient {
     client;
     logger;
@@ -22,11 +22,19 @@ export class SmolGoogle extends BaseClient {
     }
     async text(config) {
         const messages = config.messages.map((msg) => msg.toGoogleMessage());
-        const tools = (config.tools || []).map((tool) => convertOpenAIToolToGoogle(tool));
+        const tools = (config.tools || []).map((tool) => {
+            return zodToGoogleTool(tool.name, tool.schema, {
+                description: tool.description,
+            });
+        });
         const genConfig = {};
         if (tools.length > 0) {
             genConfig.tools = [{ functionDeclarations: tools }];
         }
+        if (config.responseFormat) {
+            genConfig.responseMimeType = "application/json";
+            genConfig.responseJsonSchema = config.responseFormat.toJSONSchema();
+        }
         const request = {
             contents: messages,
             model: this.model,

package/dist/clients/openai.js

@@ -4,6 +4,7 @@ import { ToolCall } from "../classes/ToolCall.js";
 import { isFunctionToolCall } from "../util.js";
 import { getLogger } from "../logger.js";
 import { BaseClient } from "./baseClient.js";
+import { zodToOpenAITool } from "../util/tool.js";
 export class SmolOpenAi extends BaseClient {
     client;
     logger;
@@ -22,12 +23,26 @@ export class SmolOpenAi extends BaseClient {
     }
     async text(config) {
         const messages = config.messages.map((msg) => msg.toOpenAIMessage());
-        const completion = await this.client.chat.completions.create({
+        const request = {
             model: this.model,
             messages,
-            tools: config.tools,
-            response_format: config.responseFormat,
-        });
+            tools: config.tools?.map((tool) => {
+                return zodToOpenAITool(tool.name, tool.schema, {
+                    description: tool.description,
+                });
+            }),
+        };
+        if (config.responseFormat) {
+            request.response_format = {
+                type: "json_schema",
+                json_schema: {
+                    name: config.responseFormatName || "response",
+                    schema: config.responseFormat.toJSONSchema(),
+                },
+            };
+        }
+        this.logger.debug("Sending request to OpenAI:", JSON.stringify(request, null, 2));
+        const completion = await this.client.chat.completions.create(request);
         this.logger.debug("Response from OpenAI:", JSON.stringify(completion, null, 2));
         const message = completion.choices[0].message;
         const output = message.content;
@@ -43,9 +58,6 @@ export class SmolOpenAi extends BaseClient {
                 }
             }
         }
-        if (toolCalls.length > 0) {
-            this.logger.debug("Tool calls detected:", toolCalls);
-        }
         return success({ output, toolCalls });
     }
 }

package/dist/types.d.ts

@@ -1,19 +1,24 @@
 export * from "./types/result.js";
 import { LogLevel } from "egonlog";
-import { ModelName } from "./models.js";
+import { ZodType } from "zod";
 import { Message } from "./classes/message/index.js";
-import { Result } from "./types/result.js";
 import { ToolCall } from "./classes/ToolCall.js";
-import { OpenAIToolDefinition } from "./util/common.js";
+import { ModelName } from "./models.js";
+import { Result } from "./types/result.js";
 export type PromptConfig = {
     messages: Message[];
-    tools?: OpenAIToolDefinition[];
+    tools?: {
+        name: string;
+        description?: string;
+        schema: ZodType;
+    }[];
     instructions?: string;
     maxTokens?: number;
     temperature?: number;
     numSuggestions?: number;
     parallelToolCalls?: boolean;
-    responseFormat?: any;
+    responseFormat?: ZodType;
+    responseFormatName?: string;
     rawAttributes?: Record<string, any>;
 };
 export type SmolConfig = {

package/dist/util/{common.d.ts → tool.d.ts}

@@ -1,15 +1,23 @@
 import { FunctionDeclaration } from "@google/genai";
-/**
- * OpenAI tool definition format
- */
-export interface OpenAIToolDefinition {
+import { z } from "zod";
+type OpenAIToolParameters = {
+    type: "object";
+    properties: Record<string, any>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+type OpenAITool = {
     type: "function";
     function: {
         name: string;
-        description?: string;
-        parameters: Record<string, unknown>;
+        description: string;
+        parameters: OpenAIToolParameters;
     };
-}
+};
+export declare function zodToOpenAITool(name: string, schema: z.ZodType, options?: Partial<{
+    description?: string;
+    strict?: boolean;
+}>): OpenAITool;
 /**
  * Converts an OpenAI tool definition to a Google FunctionDeclaration format
  *
@@ -51,4 +59,9 @@ export interface OpenAIToolDefinition {
  * // }
  * ```
  */
-export declare function convertOpenAIToolToGoogle(openAITool: OpenAIToolDefinition): FunctionDeclaration;
+export declare function openAIToGoogleTool(openAITool: OpenAITool): FunctionDeclaration;
+export declare function zodToGoogleTool(name: string, schema: z.ZodType, options?: Partial<{
+    description?: string;
+    strict?: boolean;
+}>): FunctionDeclaration;
+export {};

package/dist/util/{common.js → tool.js}

@@ -1,3 +1,38 @@
+export function zodToOpenAITool(name, schema, options = {}) {
+    // Convert Zod schema to JSON Schema
+    const jsonSchema = schema.toJSONSchema();
+    let description = "";
+    if (options?.description) {
+        description = options.description;
+    }
+    else if (typeof jsonSchema === "object" &&
+        "description" in jsonSchema &&
+        typeof jsonSchema.description === "string") {
+        description = jsonSchema.description;
+    }
+    // Build the parameters object
+    const parameters = {
+        type: "object",
+        properties: jsonSchema.properties || {},
+        required: jsonSchema.required || [],
+    };
+    const strict = options?.strict || false;
+    /* The additionalProperties field in an OpenAI schema,
+    which is based on JSON Schema, controls how the API handles
+    properties not explicitly listed in the properties section of an object.
+    By default, additionalProperties is set to true, which allows
+    the JSON object to contain any extra properties not defined in the schema.
+    */
+    parameters.additionalProperties = !strict;
+    return {
+        type: "function",
+        function: {
+            name,
+            description,
+            parameters,
+        },
+    };
+}
 /**
  * Removes properties that Google's API doesn't support from JSON schemas
  */
@@ -66,10 +101,14 @@ function removeUnsupportedProperties(obj) {
  * // }
  * ```
  */
-export function convertOpenAIToolToGoogle(openAITool) {
+export function openAIToGoogleTool(openAITool) {
     return {
         name: openAITool.function.name,
         description: openAITool.function.description,
         parametersJsonSchema: removeUnsupportedProperties(openAITool.function.parameters),
     };
 }
+export function zodToGoogleTool(name, schema, options = {}) {
+    const openAITool = zodToOpenAITool(name, schema, options);
+    return openAIToGoogleTool(openAITool);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smoltalk",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "A common interface for LLM APIs",
   "homepage": "https://github.com/egonSchiele/smoltalk",
   "scripts": {
@@ -8,7 +8,8 @@
     "test:tsc": "tsc -p tests/tsconfig.json",
     "coverage": "vitest --coverage",
     "build": "rm -rf dist && tsc",
-    "start": "cd dist && node index.js"
+    "start": "cd dist && node index.js",
+    "doc": "typedoc --disableSources --out docs lib && prettier docs/ --write"
   },
   "files": [
     "./dist"
@@ -31,12 +32,16 @@
   "license": "ISC",
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "prettier": "^3.7.4",
+    "termcolors": "github:egonSchiele/termcolors",
+    "typedoc": "^0.28.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.16",
+    "zod": "^4.3.5"
   },
   "dependencies": {
     "@google/genai": "^1.34.0",
     "egonlog": "^0.0.2",
     "openai": "^6.15.0"
   }
-}
+}