feat: model profiles (#9387)

Author: hntrl

.changeset/grumpy-planes-hear.md

@@ -0,0 +1,13 @@
+---
+"@langchain/google-common": patch
+"@langchain/google-genai": patch
+"@langchain/anthropic": patch
+"@langchain/deepseek": patch
+"@langchain/openai": patch
+"@langchain/groq": patch
+"@langchain/xai": patch
+"@langchain/model-profiles": patch
+"@langchain/core": patch
+---
+
+Add `ModelProfile` and `.profile` properties to ChatModel

internal/model-profiles/README.md

@@ -0,0 +1,84 @@
+# Model Profiles Generator
+
+A CLI tool for automatically generating TypeScript model profile files from the [models.dev](https://models.dev) API. This tool fetches model capabilities and constraints, applies provider-level and model-specific overrides, and generates type-safe TypeScript files using the TypeScript AST API.
+
+## Overview
+
+The model-profiles generator simplifies the process of maintaining model capability profiles across LangChain provider packages.
+
+### Key Features
+
+- 🔄 **Automatic Data Fetching**: Fetches latest model data from the models.dev API
+- 🎯 **Provider-Level Overrides**: Apply overrides to all models for a provider
+- 🔧 **Model-Specific Overrides**: Fine-tune individual model profiles
+- 📝 **TypeScript AST Generation**: Uses TypeScript compiler API for type-safe code generation
+- 🎨 **Prettier Integration**: Automatically formats generated code using your project's Prettier config
+- 📦 **Monorepo Friendly**: Works seamlessly with pnpm workspaces and `--filter` commands
+- ✅ **Type Safety**: Generates code that matches the `ModelProfile` interface from `@langchain/core`
+
+## Architecture
+
+The model-profiles generator consists of:
+
+```text
+internal/model-profiles/
+├── src/
+│   ├── cli.ts              # Command-line interface
+│   ├── config.ts            # TOML config parsing and override logic
+│   ├── generator.ts         # TypeScript code generation and API integration
+│   ├── api-schema.ts        # TypeScript types for models.dev API
+│   └── tests/               # Test suite
+│       ├── config.test.ts
+│       └── generator.test.ts
+├── package.json             # Tool dependencies
+├── vitest.config.ts         # Test configuration
+└── README.md                # This documentation
+```
+
+## Usage
+
+### Basic Usage
+
+Create a TOML configuration file (e.g., `profiles.toml`) in a provider package:
+
+```toml
+provider = "openai"
+output = "src/chat_models/profiles.ts"
+```
+
+Then run the generator:
+
+```bash
+# From the model-profiles package
+pnpm --filter @langchain/model-profiles make --config profiles.toml
+
+# Or if running from within a provider package
+pnpm --filter @langchain/model-profiles make --config profiles.toml
+```
+
+### Configuration File Format
+
+The TOML configuration file supports the following structure:
+
+```toml
+# Required: Provider ID from models.dev
+provider = "openai"
+
+# Required: Output path for generated TypeScript file (relative to config file)
+output = "src/chat_models/profiles.ts"
+
+# Optional: Provider-level overrides (applied to all models)
+[overrides]
+maxInputTokens = 100000
+toolCalling = true
+structuredOutput = true
+imageUrlInputs = true
+
+# Optional: Model-specific overrides (override provider-level settings)
+[overrides."gpt-4"]
+maxOutputTokens = 8192
+
+[overrides."gpt-3.5-turbo"]
+maxInputTokens = 16385
+imageUrlInputs = false
+```

internal/model-profiles/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@langchain/model-profiles",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "make": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@langchain/core": "workspace:*",
+    "commander": "^11.1.0",
+    "prettier": "^2.8.3",
+    "typescript": "^5.9.3",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/iarna__toml": "^2.0.5",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.20.3",
+    "vitest": "^1.0.0"
+  }
+}

internal/model-profiles/src/api-schema.ts

@@ -0,0 +1,112 @@
+/**
+ * Schema definitions for model and provider types.
+ *
+ * Adapted from: https://github.com/sst/models.dev/blob/dev/packages/core/src/schema.ts
+ *
+ * Original source: SST models.dev
+ * License: Apache-2.0 (https://github.com/sst/models.dev/blob/dev/LICENSE)
+ *
+ * This file contains Zod schema definitions for validating model and provider
+ * configurations used in the langchain-model-profiles package.
+ */
+
+import { z } from "zod/v3";
+
+export const Model = z
+  .object({
+    id: z.string(),
+    name: z.string().min(1, "Model name cannot be empty"),
+    attachment: z.boolean(),
+    reasoning: z.boolean(),
+    tool_call: z.boolean(),
+    structured_output: z.boolean().optional(),
+    temperature: z.boolean().optional(),
+    knowledge: z
+      .string()
+      .regex(/^\d{4}-\d{2}(-\d{2})?$/, {
+        message: "Must be in YYYY-MM or YYYY-MM-DD format",
+      })
+      .optional(),
+    release_date: z.string().regex(/^\d{4}-\d{2}(-\d{2})?$/, {
+      message: "Must be in YYYY-MM or YYYY-MM-DD format",
+    }),
+    last_updated: z.string().regex(/^\d{4}-\d{2}(-\d{2})?$/, {
+      message: "Must be in YYYY-MM or YYYY-MM-DD format",
+    }),
+    modalities: z.object({
+      input: z.array(z.enum(["text", "audio", "image", "video", "pdf"])),
+      output: z.array(z.enum(["text", "audio", "image", "video", "pdf"])),
+    }),
+    open_weights: z.boolean(),
+    cost: z
+      .object({
+        input: z.number().min(0, "Input price cannot be negative"),
+        output: z.number().min(0, "Output price cannot be negative"),
+        reasoning: z
+          .number()
+          .min(0, "Input price cannot be negative")
+          .optional(),
+        cache_read: z
+          .number()
+          .min(0, "Cache read price cannot be negative")
+          .optional(),
+        cache_write: z
+          .number()
+          .min(0, "Cache write price cannot be negative")
+          .optional(),
+        input_audio: z
+          .number()
+          .min(0, "Audio input price cannot be negative")
+          .optional(),
+        output_audio: z
+          .number()
+          .min(0, "Audio output price cannot be negative")
+          .optional(),
+      })
+      .optional(),
+    limit: z.object({
+      context: z.number().min(0, "Context window must be positive"),
+      output: z.number().min(0, "Output tokens must be positive"),
+    }),
+    status: z.enum(["alpha", "beta", "deprecated"]).optional(),
+    provider: z
+      .object({
+        npm: z.string().optional(),
+        api: z.string().optional(),
+      })
+      .optional(),
+  })
+  .strict()
+  .refine(
+    (data) => {
+      return !(data.reasoning === false && data.cost?.reasoning !== undefined);
+    },
+    {
+      message: "Cannot set cost.reasoning when reasoning is false",
+      path: ["cost", "reasoning"],
+    }
+  );
+
+export type Model = z.infer<typeof Model>;
+
+export const Provider = z
+  .object({
+    id: z.string(),
+    env: z.array(z.string()).min(1, "Provider env cannot be empty"),
+    npm: z.string().min(1, "Provider npm module cannot be empty"),
+    api: z.string().optional(),
+    name: z.string().min(1, "Provider name cannot be empty"),
+    doc: z
+      .string()
+      .min(
+        1,
+        "Please provide a link to the provider documentation where models are listed"
+      ),
+    models: z.record(Model),
+  })
+  .strict();
+
+export type Provider = z.infer<typeof Provider>;
+
+export const ProviderMap = z.record(z.string(), Provider);
+export type ProviderMap = z.infer<typeof ProviderMap>;

internal/model-profiles/src/cli.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { parseConfig, separateOverrides } from "./config.js";
+import { generateModelProfiles } from "./generator.js";
+
+const program = new Command();
+
+program
+  .name("model-profiles")
+  .description("Make model profiles for a provider")
+  .requiredOption("--config <path>", "Path to the config TOML file")
+  .action(async (options: { config: string }) => {
+    try {
+      const config = parseConfig(options.config);
+      if (!config.provider) {
+        throw new Error(
+          'Provider name must be specified in the config file (provider = "...")'
+        );
+      }
+
+      const { providerOverrides, modelOverrides } = separateOverrides(
+        config.overrides
+      );
+
+      await generateModelProfiles(
+        config.provider,
+        providerOverrides,
+        modelOverrides,
+        config.output
+      );
+    } catch (error) {
+      console.error(
+        `Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);