@x12i/ai-tools

@x12i/ai-tools

TypeScript package for AI model catalogs, runtime cost calculation, and LLM utilities.

Pricing data is loaded from two JSON catalogs on open-assets.x12i.com, with bundled fallbacks shipped in the published package (src/data):

Catalog	URL	Used when
Direct vendor	models-catalog.json	provider is openai, anthropic, google, …
OpenRouter	openrouter-models-catalog.json	provider is openrouter, or as fallback

Remote catalogs are always treated as the latest source. The JSON version field (e.g. "0.1.0") is publisher metadata only — this library does not read or compare it.

v3.0 breaking changes

Aligned with @x12i/ai-profiles v3.3.0.

Accepted model strings

Only two forms are supported everywhere (model, modelUsed, usedModel, CLI --model, invoke config):

1. profile/choice — e.g. cheap/default, balanced/default, deep/google_deep
2. Concrete model id — e.g. deepseek-v3.2, deepseek/deepseek-v3.2, gpt-5.5, openai/gpt-5.5, gemini-2.5-flash-lite

Removed (v3)

Removed	Replacement
ai-profiles shortcuts (standard, cheapest, economy, …)	Full profile/choice keys (balanced/default, cheap/default, …)
Bare profile names (cheap, balanced)	cheap/default or { profile: "cheap", choice: "default" }
Project-local aliases (@x12i/ai-tools/aliases, ai-tools alias CLI, AliasRegistry)	Store profile/choice or concrete model ids in config
Legacy model shorthands (deepseekv32, claude-sonnet, …)	Catalog ids (deepseek-v3.2, deepseek/deepseek-v3.2)
listAIShortcuts	listAIProfiles / listAIProfileChoices
applyOpenRouterInvokePolicy	applyOpenRouterInvokeRouting
ModelProfileUnroutableError.profileAlias	profileKey

Migration examples

Before (v2.x)	After (v3)
standard, cheapest	balanced/default, cheap/default
cheap (bare)	cheap/default
ai-tools alias set best …	Store concrete id or profile/choice in config
deepseekv32	deepseek-v3.2 or deepseek/deepseek-v3.2
applyOpenRouterInvokePolicy(...)	applyOpenRouterInvokeRouting(...)

Dependency: @x12i/ai-profiles ^3.3.0 (minimum 3.3.0).

Invoke model resolution

Host-agnostic pipeline for AI engines that call LLMProviderRouter.invoke(). Pass { provider?, model }; get router-ready { provider, model, allowOpenRouterProxy?, providerProxy? } plus structured diagnostics.

import { resolveInvokeModel } from "@x12i/ai-tools";
// or: import { resolveInvokeModel } from "@x12i/ai-tools/invoke";

const { router, diagnostics, resolution } = await resolveInvokeModel(
  { provider: invokeConfig.provider, model: invokeConfig.model },
  {
    preferOpenRouter: true,
    openRouterApiKey: process.env.OPENROUTER_API_KEY,
    defaultProvider: "openai",
    modelsOnly: false, // set true to reject profile/choice inputs
  },
);

Object.assign(invokeConfig, router);
// diagnostics.profileKey / invokedModelId for logging when routedViaOpenRouter

Export	Role
resolveInvokeModel	Full pipeline (catalog → vendor map → OR routing)
buildInvokeModelResolverOptions	Build ModelResolverOptions with routeViaOpenRouter when preferred
mapResolutionToRouterConfig	Map ModelResolutionSuccess → { provider, model }
applyOpenRouterInvokeRouting	Set allowOpenRouterProxy / providerProxy on router config
normalizeInvokeModel	Idempotent gateway invoke wire shape (from ai-profiles v3.2)
resolveAndNormalizeInvokeModel	resolveAIProfile → normalizeInvokeModel
createAiToolsInvokeClient	Shared catalog + cost calculator + routing env
ModelProfileUnroutableError	Profile/choice input that failed to route

Responsibility split: ai-tools owns model strings, catalogs, OpenRouter vs direct transport, and cost. The AI engine owns sampling defaults, maxTokens, message templates, router registration, and activity tracking.

Set resolveModels: false for passthrough (no catalog lookup, no resolution errors).

AI profiles (@x12i/ai-profiles v3)

Profile resolution follows the same strict contract as @x12i/ai-profiles — inside and outside this repo (configs, graph nodes, AI engines, any service that calls resolveAIProfile).

Two kinds of model strings

Intent	What you pass	How ai-tools resolves it
Profile (capability tier)	profile/choice only	@x12i/ai-profiles → concrete provider + modelId
Concrete model (vendor SKU)	gemini-2.5-flash-lite, deepseek/deepseek-v3.2, …	Catalog / profile-choice index

flowchart TD
  input["model / modelUsed / usedModel string"]
  input --> composite{"profile/choice?"}
  composite -->|yes| profiles["@x12i/ai-profiles\nresolveAIProfile"]
  composite -->|no| concrete["catalog + registry index\n(concrete model SKU)"]
  profiles --> out["provider + modelId + pricing"]
  concrete --> out

Profile keys: profile/choice (required)

Canonical resolve key: {profile}/{choice} with a forward slash /.

"cheap/default"
"balanced/default"
"deep/google_deep"
"local/llama_cpp_gguf"

• Profile = capability contract (cheap, balanced, deep, json, …) — not a model name.
• Choice = implementation variant within that profile (default, google_floor, …).

Bare profile names are not accepted (cheap, balanced, deep alone). ai-tools does not infer default for you.

Valid	Invalid
cheap/default	cheap
deep/default	standard, cheapest (removed shortcuts)
balanced/default	balanced (without /choice)

resolveProfileForAsk — split fields allowed

For ask-node / FuncX config, pass either the combined key or explicit fields (still requires a choice):

import { resolveProfileForAsk, TEXT_CATALOG_LANE } from "@x12i/ai-tools";

await resolveProfileForAsk({
  profile: "cheap/default",
  catalogLane: TEXT_CATALOG_LANE,
});

await resolveProfileForAsk({
  profile: "cheap",
  choice: "default",
  catalogLane: TEXT_CATALOG_LANE,
});

catalogLane is required ("text" for most tiers; "image" for vision).

Concrete model names

When the string is a vendor or OpenRouter model id, resolution uses the catalog and the profile registry index:

import { CostCalculator, AiModelsCatalogClient } from "@x12i/ai-tools";

const calculator = new CostCalculator(catalog);

await calculator.calculate({
  tokens: { prompt: 1_000_000, completion: 0, total: 1_000_000 },
  provider: "google",
  modelUsed: "gemini-2.5-flash-lite",
});

await calculator.calculate({
  tokens: { prompt: 1_000_000, completion: 0, total: 1_000_000 },
  provider: "google",
  modelUsed: "cheap/default",
});

const catalog = new AiModelsCatalogClient();

await catalog.resolveModel({ model: "gemini-2.5-flash-lite", provider: "google" });
await catalog.resolveModel({ model: "cheap/default" });
// await catalog.resolveModel({ model: "cheap" }); // not found
// await catalog.resolveModel({ model: "standard" }); // not found (shortcut removed)

Errors and helpers

import {
  requireProfileResolveKey,
  profileResolveKey,
  ProfileResolveKeyRequiredError,
  formatProfileChoiceKey,
  isKnownProfileChoice,
  ensureConcreteModel,
} from "@x12i/ai-tools";

await requireProfileResolveKey("cheap", { choice: undefined }); // throws

await profileResolveKey("gemini-2.5-flash-lite"); // null — concrete SKU
await profileResolveKey("cheap/default"); // "cheap/default"

isKnownProfileChoice("cheap/default"); // true
isKnownProfileChoice("standard"); // false

What to put in configs

Stored value	Use when
cheap/default, deep/default	Task / graph tier (profile intent)
gemini-2.5-flash-lite, deepseek/deepseek-v3.2, openai/gpt-5.5	Explicit model SKU
cheap, standard, deepseekv32	Do not use — rejected in v3

Re-exports

import {
  resolveAIProfile,
  listAIProfiles,
  listAIProfileChoices,
  resolveAIProfileByTags,
  resolvePreferOpenRouter,
  readPreferOpenRouterFromEnv,
  ensureConcreteModel,
  resolveProfileForAsk,
  TEXT_CATALOG_LANE,
} from "@x12i/ai-tools";
// or
import { resolveProfileForAsk, requireProfileResolveKey } from "@x12i/ai-tools/profiles";

Install

npm install @x12i/ai-tools

Requires Node.js 20+.

Optional peers: @x12i/helpers, openai, better-sqlite3 (toolbox SQLite storage).

Quick start

import { AiModelsCatalogClient, CostCalculator } from "@x12i/ai-tools";

const catalog = new AiModelsCatalogClient();
const calculator = new CostCalculator(catalog);

const result = await calculator.calculate({
  tokens: { prompt: 1000, completion: 500, total: 1500 },
  provider: "openai",
  usedModel: "gpt-5.5-2026-04-23",
});

console.log(result.cost);
console.log(result.resolvedModelId);
console.log(result.usedModel);
console.log(result.usage);

From activity or invoke records:

const result = await calculator.calculateFromRecord(activityDocument);

Catalog loading and cache

Catalogs are fetched on first use and cached in memory for 24 hours. Override TTL with AI_TOOLS_CACHE_TTL_MS. If a fetch fails, bundled src/data/*.json is used automatically.

npx ai-tools catalog refresh
npx ai-tools catalog verify --json
npx ai-tools catalog refresh --bundled-only

npm script	Command
npm run catalog:refresh	Fetch catalogs and warm cache
npm run catalog:verify	Verify both catalogs load

Cost calculation

await calculator.calculate({
  tokens: { prompt: 1000, completion: 500, total: 1500 },
  provider: "openrouter",
  usedModel: "deepseek/deepseek-v3.2",
});

Runtime model priority: usedModel → modelUsed → model.

Profile vs model in usedModel: pass cheap/default for tier-based pricing; pass gemini-2.5-flash-lite (or vendor/slug) for a concrete SKU.

Smart model resolution

ModelNameResolver normalises provider + model input against the cached catalog. Catalog record aliases (metadata in JSON, e.g. deepseek-v3.2 → deepseek/deepseek-v3.2) are supported; shorthand tokens (deepseekv32, etc.) are not.

import { AiModelsCatalogClient, ModelNameResolver } from "@x12i/ai-tools";

const catalog = new AiModelsCatalogClient();
const models = await catalog.getAllModels();
const resolver = new ModelNameResolver(models);

const result = await catalog.resolveModel({
  provider: "openrouter",
  model: "deepseek-v3.2",
});

Input	Typical resolution
openrouter + deepseek-v3.2	deepseek/deepseek-v3.2
cheap/default	ai-profiles → e.g. google/gemini-2.5-flash-lite
standard, cheapest	not found (use balanced/default, cheap/default)
deepseekv32	not found (use deepseek-v3.2)
gemini-2.5-flash-lite	registry index / catalog
ollama + llama3:8b	local passthrough

OpenRouter vs direct routing

Condition	Routes via OpenRouter
PREFER_OPENROUTER true (default) and OPENROUTER_API_KEY set	Yes
OPENROUTER_API_KEY set, vendor {VENDOR}_API_KEY missing	Yes
Vendor key present, PREFER_OPENROUTER=false or 0	Direct

import {
  loadOpenRouterRoutingEnv,
  shouldDefaultRouteViaOpenRouter,
  resolvePreferOpenRouter,
} from "@x12i/ai-tools";

CLI

npx ai-tools catalog refresh
npx ai-tools catalog verify --json
npx ai-tools models list --provider openai
npx ai-tools models resolve --model deepseek-v3.2 --provider openrouter --verbose
npx ai-tools cost --model openai/gpt-5.5 --prompt-tokens 1000 --completion-tokens 500 --provider openai
npx ai-tools cost --model cheap/default --prompt-tokens 1000000 --completion-tokens 0 --provider google
npx ai-tools models resolve --model cheap/default --verbose

Environment variables

Copy .env.example to .env in your app.

Variable	Purpose
OPENROUTER_API_KEY	OpenRouter routing defaults; enables invoke proxy routing when set
PREFER_OPENROUTER	true / 1 / false / 0 — prefer OpenRouter when OR + vendor keys both set (default true when unset; parsed via @x12i/ai-profiles)
OPENAI_API_KEY, ANTHROPIC_API_KEY, …	Direct vendor keys ({PROVIDER_ID}_API_KEY)
AI_TOOLS_CACHE_TTL_MS	Catalog in-memory cache TTL (default: 86400000 = 24h)

Package exports

Subpath	Contents
@x12i/ai-tools	Catalog client, cost calculator, resolver, profiles, invoke
@x12i/ai-tools/cost	Cost types, extractUsageInput, CostCalculator
@x12i/ai-tools/catalog	loadCatalogSources, refresh/verify
@x12i/ai-tools/models	Model listing and filters
@x12i/ai-tools/sync	ModelNameResolver, OpenRouter fetch helper
@x12i/ai-tools/profiles	resolveProfileForAsk, ai-profiles v3 re-exports
@x12i/ai-tools/invoke	resolveInvokeModel, OpenRouter invoke routing helpers
@x12i/ai-tools/toolbox	Tracker, router, guard

Dependency: @x12i/ai-profiles ^3.3.0.

Tests

npm test
npm run build
npm run test:live    # optional OpenRouter API live test

License

MIT