@cbuff/llm 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charles Buffington
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @cbuff/llm
+
+Type-safe LLM wrapper built on [Vercel AI SDK](https://sdk.vercel.ai/) with provider/model registry and optional cost tracking.
+
+## Installation
+
+```bash
+bun add @cbuff/llm ai
+```
+
+Install the provider SDKs you need:
+
+```bash
+bun add @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
+```
+
+## Usage
+
+```typescript
+import { createLLM } from "@cbuff/llm";
+import { createOpenAI } from "@ai-sdk/openai";
+
+const llm = createLLM({
+  providers: {
+    openai: () => createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+    anthropic: async () => {
+      const { createAnthropic } = await import("@ai-sdk/anthropic");
+      return createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+    },
+  },
+  models: {
+    fast: { provider: "openai", id: "gpt-4o-mini" },
+    smart: { provider: "openai", id: "gpt-4o", costs: { input: 2.5, output: 10 } },
+    claude: { provider: "anthropic", id: "claude-sonnet-4-20250514", costs: { input: 3, output: 15 } },
+  },
+});
+
+// Full autocomplete on model names
+const { data, metadata } = await llm.generate({
+  model: "fast",
+  prompt: "Hello, world!",
+});
+
+console.log(data);
+console.log(metadata.totalCostUsd); // undefined if costs not configured
+```
+
+## Features
+
+- **Type-safe model selection** — Full autocomplete on model aliases, provider references validated at compile time
+- **Lazy provider loading** — Providers can be sync or async, loaded on first use and cached
+- **Optional cost tracking** — Define `costs: { input, output }` per model (USD per 1M tokens), skip if you don't need it
+- **Unified config** — Single `createLLM()` call with providers and models in one object
+
+## API
+
+### `createLLM(config)`
+
+Creates a typed LLM client.
+
+```typescript
+const llm = createLLM({
+  providers: {
+    [key: string]: () => Provider | Promise<Provider>
+  },
+  models: {
+    [alias: string]: {
+      provider: string;  // must match a key in providers
+      id: string;        // actual model ID sent to provider
+      costs?: { input: number; output: number };  // USD per 1M tokens
+    }
+  }
+});
+```
+
+### `llm.generate(params)`
+
+Generate text or structured output.
+
+```typescript
+const { data, metadata } = await llm.generate({
+  model: "fast",           // required, autocompletes to your model aliases
+  prompt: "Hello",         // required
+  system: "Be helpful",    // optional
+  temperature: 0.7,        // optional
+  maxOutputTokens: 1000,   // optional
+  output: schema,          // optional, for structured output
+  logKey: "my-request",    // optional, logs timing and cost
+});
+```
+
+**Returns:**
+
+```typescript
+{
+  data: string | T,  // text or structured output
+  metadata: {
+    responseTimeMs: number,
+    inputTokens: number,
+    outputTokens: number,
+    inputCostUsd?: number,   // undefined if costs not configured
+    outputCostUsd?: number,
+    totalCostUsd?: number,
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { type Output } from "ai";
+import type { GenerateParams, GenerateResponse, ModelEntry, ProviderFactory } from "./types.js";
+export type { GenerateMetadata, GenerateParams, GenerateResponse, LanguageModelProvider, ModelEntry, ProviderFactory } from "./types.js";
+/**
+ * Creates a type-safe LLM client with the given providers and models.
+ *
+ * @example
+ * ```typescript
+ * import { createLLM } from "@cbuff/llm";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ *
+ * const llm = createLLM({
+ *   providers: {
+ *     openai: () => createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   },
+ *   models: {
+ *     fast: { provider: "openai", id: "gpt-4o-mini" },
+ *     smart: { provider: "openai", id: "gpt-4o", costs: { input: 2.5, output: 10 } },
+ *   },
+ * });
+ *
+ * const { data } = await llm.generate({ model: "fast", prompt: "Hello" });
+ * ```
+ */
+export declare function createLLM<TProviders extends Record<string, ProviderFactory>, TModels extends Record<string, ModelEntry<keyof TProviders & string>>>(config: {
+    providers: TProviders;
+    models: TModels;
+}): {
+    generate: <TOutput extends Output.Output = Output.Output<string, string>>(params: GenerateParams<keyof TModels & string, TOutput>) => Promise<GenerateResponse<TOutput>>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,MAAM,EAAE,MAAM,IAAI,CAAC;AACnE,OAAO,KAAK,EAEV,cAAc,EACd,gBAAgB,EAEhB,UAAU,EACV,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,gBAAgB,EAAE,cAAc,EAChC,gBAAgB,EAAE,qBAAqB,EAAE,UAAU,EAAE,eAAe,EACrE,MAAM,YAAY,CAAC;AAgBpB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CACvB,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAClD,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,EACrE,MAAM,EAAE;IAAE,SAAS,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE;eAuD1B,OAAO,SAAS,MAAM,CAAC,MAAM,0CAC3C,cAAc,CAAC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,CAAC,KACtD,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;EAyCtC"}

package/dist/index.js

@@ -0,0 +1,112 @@
+import { generateText } from "ai";
+// ############################################################################
+// Cost Formatter
+// ############################################################################
+const costFormatter = new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 4,
+});
+// ############################################################################
+// createLLM Factory
+// ############################################################################
+/**
+ * Creates a type-safe LLM client with the given providers and models.
+ *
+ * @example
+ * ```typescript
+ * import { createLLM } from "@cbuff/llm";
+ * import { createOpenAI } from "@ai-sdk/openai";
+ *
+ * const llm = createLLM({
+ *   providers: {
+ *     openai: () => createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   },
+ *   models: {
+ *     fast: { provider: "openai", id: "gpt-4o-mini" },
+ *     smart: { provider: "openai", id: "gpt-4o", costs: { input: 2.5, output: 10 } },
+ *   },
+ * });
+ *
+ * const { data } = await llm.generate({ model: "fast", prompt: "Hello" });
+ * ```
+ */
+export function createLLM(config) {
+    // Provider cache: lazily resolved and stored
+    const providerCache = new Map();
+    /**
+     * Resolves a provider by key, using cache if available.
+     */
+    async function getProvider(providerKey) {
+        const cached = providerCache.get(providerKey);
+        if (cached)
+            return cached;
+        const factory = config.providers[providerKey];
+        const provider = await Promise.resolve(factory());
+        providerCache.set(providerKey, provider);
+        return provider;
+    }
+    /**
+     * Gets a language model instance for the given model alias.
+     */
+    async function getModel(modelKey) {
+        const modelConfig = config.models[modelKey];
+        const provider = await getProvider(modelConfig.provider);
+        return provider(modelConfig.id);
+    }
+    /**
+     * Calculates costs for the given model and token usage.
+     * Returns undefined values if costs are not configured.
+     */
+    function calculateCosts(modelKey, inputTokens, outputTokens) {
+        const modelConfig = config.models[modelKey];
+        if (!modelConfig.costs) {
+            return {
+                inputCostUsd: undefined,
+                outputCostUsd: undefined,
+                totalCostUsd: undefined,
+            };
+        }
+        const inputCostUsd = (inputTokens / 1_000_000) * modelConfig.costs.input;
+        const outputCostUsd = (outputTokens / 1_000_000) * modelConfig.costs.output;
+        const totalCostUsd = inputCostUsd + outputCostUsd;
+        return { inputCostUsd, outputCostUsd, totalCostUsd };
+    }
+    /**
+     * Generate text or structured output using the configured models.
+     */
+    async function generate(params) {
+        const model = await getModel(params.model);
+        const startTime = Date.now();
+        const result = await generateText({
+            model,
+            prompt: params.prompt,
+            system: params.system,
+            temperature: params.temperature,
+            maxOutputTokens: params.maxOutputTokens,
+            experimental_output: params.output,
+        });
+        const endTime = Date.now();
+        const responseTimeMs = endTime - startTime;
+        const inputTokens = result.usage?.inputTokens ?? 0;
+        const outputTokens = result.usage?.outputTokens ?? 0;
+        const costs = calculateCosts(params.model, inputTokens, outputTokens);
+        // Log if requested
+        if (params.logKey) {
+            const costStr = costs.totalCostUsd !== undefined
+                ? ` cost: ${costFormatter.format(costs.totalCostUsd)} (in: ${costFormatter.format(costs.inputCostUsd)}, out: ${costFormatter.format(costs.outputCostUsd)})`
+                : "";
+            console.log(`[LLM][${params.logKey}] ${(responseTimeMs / 1000).toFixed(2)}s using ${String(params.model)}${costStr}`);
+        }
+        return {
+            data: (params.output ? result.experimental_output : result.text),
+            metadata: {
+                responseTimeMs,
+                inputTokens,
+                outputTokens,
+                ...costs,
+            },
+        };
+    }
+    return { generate };
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+import type { generateText, LanguageModel, Output, InferGenerateOutput } from "ai";
+/**
+ * A provider instance that can create language models.
+ * This is the return type of provider factories like `createOpenAI()`.
+ */
+export type LanguageModelProvider = (modelId: string) => LanguageModel;
+/**
+ * A factory function that creates a provider instance.
+ * Can be sync or async (for lazy-loading provider SDKs).
+ */
+export type ProviderFactory = () => LanguageModelProvider | Promise<LanguageModelProvider>;
+/**
+ * Configuration for a single model.
+ * @template TProviders - Union of available provider keys
+ */
+export type ModelEntry<TProviders extends string> = {
+    /** The provider key to use for this model */
+    provider: TProviders;
+    /** The actual model ID to pass to the provider */
+    id: string;
+    /** Optional cost tracking (per 1M tokens in USD) */
+    costs?: {
+        input: number;
+        output: number;
+    };
+};
+/**
+ * Full configuration object for createLLM.
+ * @template TProviders - Record of provider factories
+ * @template TModels - Record of model configurations
+ */
+export type LLMConfig<TProviders extends Record<string, ProviderFactory>, TModels extends Record<string, ModelEntry<keyof TProviders & string>>> = {
+    providers: TProviders;
+    models: TModels;
+};
+type GenerateTextParams = Parameters<typeof generateText>[0];
+type DefaultOutput = Output.Output<string, string>;
+/**
+ * Parameters for the generate function.
+ * @template TModels - Union of available model keys
+ * @template TOutput - Output schema type
+ */
+export type GenerateParams<TModels extends string, TOutput extends Output.Output = DefaultOutput> = {
+    /** The model alias to use */
+    model: TModels;
+    /** The user prompt */
+    prompt: string;
+    /** Optional system prompt */
+    system?: string;
+    /** Optional output schema for structured generation */
+    output?: TOutput;
+    /** Optional key for logging */
+    logKey?: string;
+} & Pick<GenerateTextParams, "temperature" | "maxOutputTokens">;
+/**
+ * Response metadata from a generate call.
+ */
+export type GenerateMetadata = {
+    /** Response time in milliseconds */
+    responseTimeMs: number;
+    /** Number of input tokens used */
+    inputTokens: number;
+    /** Number of output tokens generated */
+    outputTokens: number;
+    /** Cost of input tokens in USD (undefined if costs not configured) */
+    inputCostUsd?: number;
+    /** Cost of output tokens in USD (undefined if costs not configured) */
+    outputCostUsd?: number;
+    /** Total cost in USD (undefined if costs not configured) */
+    totalCostUsd?: number;
+};
+/**
+ * Response from a generate call.
+ * @template TOutput - Output schema type
+ */
+export type GenerateResponse<TOutput extends Output.Output = DefaultOutput> = {
+    /** The generated data */
+    data: InferGenerateOutput<TOutput>;
+    /** Metadata about the generation */
+    metadata: GenerateMetadata;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,IAAI,CAAC;AAMnF;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,aAAa,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAM3F;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,UAAU,SAAS,MAAM,IAAI;IAClD,6CAA6C;IAC7C,QAAQ,EAAE,UAAU,CAAC;IACrB,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,KAAK,CAAC,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AAMF;;;;GAIG;AACH,MAAM,MAAM,SAAS,CACnB,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAClD,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,IACnE;IACF,SAAS,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAMF,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7D,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,cAAc,CACxB,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS,MAAM,CAAC,MAAM,GAAG,aAAa,IAC3C;IACF,6BAA6B;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,iBAAiB,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,GAAG,aAAa,IAAI;IAC5E,yBAAyB;IACzB,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACnC,oCAAoC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;CAC5B,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@cbuff/llm",
+  "version": "1.0.0",
+  "author": "Charles Buffington",
+  "description": "Type-safe LLM wrapper with provider/model registry and optional cost tracking",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/C41M50N/llm.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.39",
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@openrouter/ai-sdk-provider": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "ai-sdk",
+    "openai",
+    "anthropic",
+    "google",
+    "vercel-ai-sdk",
+    "typescript"
+  ],
+  "license": "MIT"
+}