@funkai/models 0.3.1 → 0.3.3

package/scripts/generate-models.ts

@@ -53,6 +53,8 @@ interface ApiProvider {
 /**
  * Convert a provider key to a TypeScript constant name.
  * e.g. "openai" → "OPENAI_MODELS", "meta-llama" → "META_LLAMA_MODELS"
+ *
+ * @private
  */
 function toConstName(provider: string): string {
   return `${provider.toUpperCase().replaceAll(/[^A-Z0-9]/g, "_")}_MODELS`;
@@ -61,6 +63,8 @@ function toConstName(provider: string): string {
 /**
  * Lowercase the first character of a string, preserving the rest as-is.
  * e.g. "OpenAI" → "openAI", "GoogleVertex" → "googleVertex", "XAI" → "xAI"
+ *
+ * @private
  */
 function lowerFirst(s: string): string {
   if (s.length === 0) {
@@ -75,6 +79,8 @@ function lowerFirst(s: string): string {
 
 /**
  * Return the correct indefinite article ("a" or "an") for a word.
+ *
+ * @private
  */
 function article(word: string): string {
   if (/^[aeiou]/i.test(word)) {
@@ -86,6 +92,8 @@ function article(word: string): string {
 /**
  * Convert per-million-token rate to per-token rate, rounding to
  * eliminate floating-point noise (e.g. `8.000000000000001e-7`).
+ *
+ * @private
  */
 function toPerToken(perMillion: number): number {
   return parseFloat((perMillion / 1_000_000).toPrecision(6));
@@ -94,6 +102,8 @@ function toPerToken(perMillion: number): number {
 /**
  * Format a number for codegen output, using scientific notation for
  * very small values.
+ *
+ * @private
  */
 function fmtNum(n: number): string {
   if (n === 0) {
@@ -105,22 +115,29 @@ function fmtNum(n: number): string {
   return String(n);
 }
 
+/** @private */
+function extractExampleId(model: ApiModel | undefined): string {
+  if (model !== undefined && model !== null) {
+    return model.id;
+  }
+  return "example-id";
+}
+
 /**
  * Build the pricing object literal string for a model.
+ *
+ * @private
  */
+function extractCostField(cost: ApiModel["cost"], field: "input" | "output"): number {
+  if (cost !== undefined && cost !== null) {
+    return cost[field] ?? 0;
+  }
+  return 0;
+}
+
 function buildPricing(cost: ApiModel["cost"]): string {
-  const costInput: number = (() => {
-    if (cost !== undefined && cost !== null && cost.input !== undefined && cost.input !== null) {
-      return cost.input;
-    }
-    return 0;
-  })();
-  const costOutput: number = (() => {
-    if (cost !== undefined && cost !== null && cost.output !== undefined && cost.output !== null) {
-      return cost.output;
-    }
-    return 0;
-  })();
+  const costInput = extractCostField(cost, "input");
+  const costOutput = extractCostField(cost, "output");
   const input = toPerToken(costInput);
   const output = toPerToken(costOutput);
   const parts: string[] = [`input: ${fmtNum(input)}`, `output: ${fmtNum(output)}`];
@@ -142,30 +159,22 @@ function buildPricing(cost: ApiModel["cost"]): string {
 
 /**
  * Build the modalities object literal string.
+ *
+ * @private
  */
+function extractModalityField(
+  modalities: ApiModel["modalities"],
+  field: "input" | "output",
+): string[] {
+  if (modalities !== undefined && modalities !== null) {
+    return modalities[field] ?? ["text"];
+  }
+  return ["text"];
+}
+
 function buildModalities(modalities: ApiModel["modalities"]): string {
-  const modalInput: string[] = (() => {
-    if (
-      modalities !== undefined &&
-      modalities !== null &&
-      modalities.input !== undefined &&
-      modalities.input !== null
-    ) {
-      return modalities.input;
-    }
-    return ["text"];
-  })();
-  const modalOutput: string[] = (() => {
-    if (
-      modalities !== undefined &&
-      modalities !== null &&
-      modalities.output !== undefined &&
-      modalities.output !== null
-    ) {
-      return modalities.output;
-    }
-    return ["text"];
-  })();
+  const modalInput = extractModalityField(modalities, "input");
+  const modalOutput = extractModalityField(modalities, "output");
   const input = JSON.stringify(modalInput);
   const output = JSON.stringify(modalOutput);
   return `{ input: ${input}, output: ${output} }`;
@@ -173,6 +182,8 @@ function buildModalities(modalities: ApiModel["modalities"]): string {
 
 /**
  * Build the capabilities object literal string.
+ *
+ * @private
  */
 function buildCapabilities(m: ApiModel): string {
   return [
@@ -185,28 +196,22 @@ function buildCapabilities(m: ApiModel): string {
 
 /**
  * Extract context window and max output from a model's limit field.
+ *
+ * @private
  */
 function getModelLimits(limit: ApiModel["limit"]): { contextWindow: number; maxOutput: number } {
   if (limit === undefined || limit === null) {
     return { contextWindow: 0, maxOutput: 0 };
   }
-  const contextWindow: number = (() => {
-    if (limit.context !== undefined && limit.context !== null) {
-      return limit.context;
-    }
-    return 0;
-  })();
-  const maxOutput: number = (() => {
-    if (limit.output !== undefined && limit.output !== null) {
-      return limit.output;
-    }
-    return 0;
-  })();
+  const contextWindow = limit.context ?? 0;
+  const maxOutput = limit.output ?? 0;
   return { contextWindow, maxOutput };
 }
 
 /**
  * Escape a string for use in a TypeScript single-quoted string literal.
+ *
+ * @private
  */
 function escapeStr(s: string): string {
   return s
@@ -216,6 +221,11 @@ function escapeStr(s: string): string {
     .replaceAll("\r", String.raw`\r`);
 }
 
+/**
+ * Check whether the staleness cache file indicates a recent fetch.
+ *
+ * @private
+ */
 function isFresh(reqPath: string): boolean {
   if (!existsSync(reqPath)) {
     return false;
@@ -286,37 +296,33 @@ export default lauf({
     rmSync(ENTRY_DIR, { recursive: true, force: true });
     mkdirSync(ENTRY_DIR, { recursive: true });
 
-    const providerFiles: { provider: string; constName: string; count: number }[] = [];
-
-    for (const providerKey of providerKeys) {
+    const providerFiles = providerKeys.flatMap((providerKey) => {
       const apiProviderEntry = apiData[providerKey];
       const providerEntry = providers[providerKey];
-      if (apiProviderEntry !== undefined && providerEntry !== undefined) {
-        if (apiProviderEntry.models === undefined || apiProviderEntry.models === null) {
-          throw new Error(
-            `models.dev API returned no models for configured provider: ${providerKey}`,
-          );
-        }
-        const apiModels = apiProviderEntry.models;
-        const constName = toConstName(providerKey);
-        const lines: string[] = [];
-
-        for (const [, m] of Object.entries(apiModels)) {
-          const id = escapeStr(m.id);
-          const name = escapeStr(m.name ?? m.id);
-          const family = escapeStr(m.family ?? "");
-          const pricing = buildPricing(m.cost);
-          const { contextWindow, maxOutput } = getModelLimits(m.limit);
-          const modalities = buildModalities(m.modalities);
-          const capabilities = buildCapabilities(m);
-
-          lines.push(
-            `  { id: '${id}', name: '${name}', provider: '${providerKey}', family: '${family}', pricing: ${pricing}, contextWindow: ${contextWindow}, maxOutput: ${maxOutput}, modalities: ${modalities}, capabilities: { ${capabilities} } },`,
-          );
-        }
-
-        // Write catalog provider file
-        const catalogContent = `${BANNER}
+      if (apiProviderEntry === undefined || providerEntry === undefined) {
+        return [];
+      }
+      if (apiProviderEntry.models === undefined || apiProviderEntry.models === null) {
+        throw new Error(
+          `models.dev API returned no models for configured provider: ${providerKey}`,
+        );
+      }
+      const apiModels = apiProviderEntry.models;
+      const constName = toConstName(providerKey);
+      const lines = Object.values(apiModels).map((m) => {
+        const id = escapeStr(m.id);
+        const name = escapeStr(m.name ?? m.id);
+        const family = escapeStr(m.family ?? "");
+        const pricing = buildPricing(m.cost);
+        const { contextWindow, maxOutput } = getModelLimits(m.limit);
+        const modalities = buildModalities(m.modalities);
+        const capabilities = buildCapabilities(m);
+
+        return `  { id: '${id}', name: '${name}', provider: '${providerKey}', family: '${family}', pricing: ${pricing}, contextWindow: ${contextWindow}, maxOutput: ${maxOutput}, modalities: ${modalities}, capabilities: { ${capabilities} } },`;
+      });
+
+      // Write catalog provider file
+      const catalogContent = `${BANNER}
 
 import type { ModelDefinition } from '../types.js'
 
@@ -325,24 +331,17 @@ ${lines.join("\n")}
 ] as const satisfies readonly ModelDefinition[]
 `;
 
-        const catalogPath = join(CATALOG_DIR, `${providerKey}.ts`);
-        writeFileSync(catalogPath, catalogContent, "utf8");
-
-        // Write per-provider entry point
-        const { prefix } = providerEntry;
-        const camel = lowerFirst(prefix);
-        const [firstModel] = Object.values(apiModels);
-        const exampleId = escapeStr(
-          (() => {
-            if (firstModel !== undefined) {
-              return firstModel.id;
-            }
-            return "example-id";
-          })(),
-        );
-        const providerName = escapeStr(providerEntry.name);
-        const art = article(providerEntry.name);
-        const entryContent = `${BANNER}
+      const catalogPath = join(CATALOG_DIR, `${providerKey}.ts`);
+      writeFileSync(catalogPath, catalogContent, "utf8");
+
+      // Write per-provider entry point
+      const { prefix } = providerEntry;
+      const camel = lowerFirst(prefix);
+      const [firstModel] = Object.values(apiModels);
+      const exampleId = escapeStr(extractExampleId(firstModel));
+      const providerName = escapeStr(providerEntry.name);
+      const art = article(providerEntry.name);
+      const entryContent = `${BANNER}
 
 import type { LiteralUnion } from 'type-fest'
 import type { ModelDefinition } from '../catalog/types.js'
@@ -374,6 +373,7 @@ export type ${prefix}ModelId = (typeof ${constName})[number]['id']
  */
 export const ${camel}Models = ${constName}
 
+/** @private */
 const MODEL_INDEX = new Map<string, ModelDefinition>(${constName}.map((m) => [m.id, m]))
 
 /**
@@ -397,13 +397,12 @@ export function ${camel}Model(id: LiteralUnion<${prefix}ModelId, string>): Model
 }
 `;
 
-        const entryPath = join(ENTRY_DIR, `${providerKey}.ts`);
-        writeFileSync(entryPath, entryContent, "utf8");
+      const entryPath = join(ENTRY_DIR, `${providerKey}.ts`);
+      writeFileSync(entryPath, entryContent, "utf8");
 
-        ctx.logger.success(`${providerKey} (${lines.length} models)`);
-        providerFiles.push({ provider: providerKey, constName, count: lines.length });
-      }
-    }
+      ctx.logger.success(`${providerKey} (${lines.length} models)`);
+      return [{ provider: providerKey, constName, count: lines.length }];
+    });
 
     // Catalog barrel
     const imports = providerFiles
@@ -414,6 +413,7 @@ export function ${camel}Model(id: LiteralUnion<${prefix}ModelId, string>): Model
 
     const catalogBarrel = `${BANNER}
 
+// oxlint-disable eslint-plugin-import/max-dependencies
 import type { ModelDefinition } from '../types.js'
 ${imports}
 
@@ -439,15 +439,17 @@ ${spreads}
         types: "./dist/index.d.mts",
         import: "./dist/index.mjs",
       },
+      ...Object.fromEntries(
+        providerFiles.map((p) => [
+          `./${p.provider}`,
+          {
+            types: `./dist/providers/${p.provider}.d.mts`,
+            import: `./dist/providers/${p.provider}.mjs`,
+          },
+        ]),
+      ),
     };
 
-    for (const p of providerFiles) {
-      exportsMap[`./${p.provider}`] = {
-        types: `./dist/providers/${p.provider}.d.mts`,
-        import: `./dist/providers/${p.provider}.mjs`,
-      };
-    }
-
     pkg.exports = exportsMap;
     writeFileSync(PACKAGE_JSON_PATH, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
     ctx.logger.success("package.json exports map updated");

package/src/catalog/index.ts

@@ -23,6 +23,7 @@ export type ModelId = LiteralUnion<KnownModelId, string>;
  */
 export const MODELS = GENERATED_MODELS satisfies readonly ModelDefinition[];
 
+/** @private */
 const MODEL_INDEX = new Map<string, ModelDefinition>(MODELS.map((m) => [m.id, m]));
 
 /**

package/src/cost/calculate.ts

@@ -8,6 +8,12 @@ import type { TokenUsage } from "@/provider/types.js";
  * Multiplies each token count by the corresponding per-token pricing rate.
  * Optional pricing fields (cache) default to `0` when absent.
  *
+ * **Reasoning token semantics**: `reasoningTokens` in {@link TokenUsage} are
+ * expected to be **exclusive** of `outputTokens` — they are billed separately.
+ * If your provider includes reasoning tokens _within_ the `outputTokens` count,
+ * you must deduct them before passing usage to this function to avoid
+ * double-counting output costs.
+ *
  * @param usage - Token counts from a model invocation.
  * @param pricing - Per-token pricing rates for the model.
  * @returns A {@link UsageCost} with per-field and total costs in USD.

package/src/cost/types.ts

@@ -3,6 +3,10 @@
  *
  * Each field is the dollar cost for that token category.
  * All fields are non-negative numbers. Fields that don't apply are `0`.
+ *
+ * **Note**: Values may exhibit floating-point imprecision inherent to
+ * JavaScript `number` (IEEE 754 double-precision) arithmetic. Do not rely
+ * on exact equality comparisons against expected cost values.
  */
 export interface UsageCost {
   /** Cost for input tokens. */

package/src/provider/registry.ts

@@ -59,6 +59,8 @@ export type ProviderRegistry = (modelId: ModelId) => LanguageModel;
  *
  * @param config - Provider mappings.
  * @returns A resolver function that maps model IDs to {@link LanguageModel} instances.
+ * @throws {Error} If the model ID is empty, missing the `provider/model` format,
+ *   or the underlying AI SDK registry fails to resolve the provider or model.
  *
  * @example
  * ```typescript
@@ -86,8 +88,40 @@ export function createProviderRegistry(config: ProviderRegistryConfig): Provider
     if (!modelId.trim()) {
       throw new Error("Cannot resolve model: model ID is empty");
     }
+    if (!modelId.includes("/")) {
+      throw new Error(
+        `Invalid model ID "${modelId}": expected "provider/model" format (e.g. "openai/gpt-4.1")`,
+      );
+    }
     // Cast needed: AI SDK overloads expect `provider/model` template literal,
     // But our ModelId is a branded string union. The runtime validates the format.
-    return inner.languageModel(modelId as `${string}/${string}`) as LanguageModel;
+    try {
+      // SAFETY: The first cast (`as \`${string}/${string}\``) is safe because we
+      // Validated above that `modelId` contains `/`. The second cast (`as
+      // LanguageModel`) narrows from the AI SDK's broader LanguageModel union to
+      // The v3 specification, which is the only version we support.
+      return inner.languageModel(modelId as `${string}/${string}`) as LanguageModel;
+    } catch (error) {
+      throw new Error(`Failed to resolve model "${modelId}": ${errorMessage(error)}`, {
+        cause: error,
+      });
+    }
   };
 }
+
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a human-readable message from an unknown error value.
+ *
+ * @param error - The caught error value.
+ * @returns The error message string.
+ *
+ * @private
+ */
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/provider/types.ts

@@ -17,6 +17,12 @@ export type LanguageModel = Extract<BaseLanguageModel, { specificationVersion: "
  * Base token counts shared by raw tracking records and final output.
  *
  * All fields are resolved `number` (0 when absent).
+ *
+ * **Reasoning token semantics**: `reasoningTokens` must be **exclusive** of
+ * `outputTokens`. Some providers include reasoning tokens inside the output
+ * token count — if so, callers must deduct reasoning tokens from
+ * `outputTokens` before constructing this type to avoid double-counting in
+ * cost calculations.
  */
 export interface TokenUsage {
   /** Number of input (prompt) tokens. */

package/tsconfig.json

@@ -5,21 +5,28 @@
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "lib": ["ES2024"],
+    "types": ["node"],
+
     "strict": true,
-    "esModuleInterop": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
+
     "declaration": true,
     "declarationMap": true,
     "sourceMap": true,
+
     "outDir": "./dist",
     "rootDir": ".",
     "paths": {
       "@/*": ["./src/*"]
-    },
-    "types": ["node"]
+    }
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist"]