@x12i/ai-tools 1.0.4 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 2.0.0 — 2026-05-27
+
+### Breaking
+
+- Removed Catalox/Firestore catalog sync (`ensureAiModelsCatalog`, `runAiModelsCatalogSync`, `ai-tools sync`).
+- Pricing catalogs load from [open-assets.x12i.com](https://open-assets.x12i.com/) JSON with bundled `src/data` fallbacks.
+- Default catalog cache TTL is **24 hours** (was 1 hour in earlier CLI defaults).
+
+### Added
+
+- `AiModelsCatalogClient` with dual catalogs (direct vendor + OpenRouter pricing).
+- `loadCatalogSources`, `loadCatalogSourcesCached`, `refreshAiModelsCatalog`, `verifyAiModelsCatalog`.
+- `CostCalculator.calculateFromRecord()` for activity/gateway JSON.
+- Smart usage extraction (`extractUsageInput`) with model/token field priorities.
+- Versioned runtime model id resolution (`gpt-5.5-2026-04-23` → `openai/gpt-5.5`) with `VERSION_SUFFIX_PRICING` warning.
+- CLI: `catalog refresh`, `catalog verify`.
+
+### Notes
+
+- Catalog JSON `version` / `schema` fields are informational; the library does not validate or compare them.
+- Remote catalogs are always treated as the latest pricing source when the network is available.

package/README.md

@@ -1,315 +1,257 @@
 # @x12i/ai-tools
 
-TypeScript-first npm package for AI model catalog management, runtime cost calculation, project-local model aliases, and an integrated LLM utility belt — backed by [@x12i/catalox](https://www.npmjs.com/package/@x12i/catalox) and OpenRouter.
+TypeScript package for AI model catalogs, runtime cost calculation, project-local model aliases, and LLM utilities.
+
+Pricing data is loaded from two JSON catalogs on [open-assets.x12i.com](https://open-assets.x12i.com/), with bundled fallbacks shipped in the published package (`src/data`):
+
+| Catalog | URL | Used when |
+|---------|-----|-----------|
+| Direct vendor | [models-catalog.json](https://open-assets.x12i.com/models-catalog.json) | `provider` is `openai`, `anthropic`, `google`, … |
+| OpenRouter | [openrouter-models-catalog.json](https://open-assets.x12i.com/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.
+
+## v2.0 breaking changes
+
+- **Catalog source:** Pricing comes from open-assets JSON (+ bundled `src/data`), not Catalox/Firestore sync.
+- **CLI:** Use `ai-tools catalog refresh` and `ai-tools catalog verify` (removed `sync` / `ensure` commands).
+- **Cache:** In-memory catalog cache defaults to **24 hours** (`AI_TOOLS_CACHE_TTL_MS`, default `86400000`).
 
 ## Install
 
 ```bash
-npm install @x12i/ai-tools @x12i/catalox
+npm install @x12i/ai-tools
 ```
 
-Optional peers: `firebase-admin`, `@x12i/helpers`, `openai`, `better-sqlite3` (for toolbox SQLite storage).
+Requires **Node.js 20+**.
+
+Optional peers: `@x12i/helpers`, `openai`, `better-sqlite3` (toolbox SQLite storage).
 
 ## Quick start
 
 ```ts
-import { createCataloxFromEnv } from "@x12i/catalox/firebase";
-import {
-  ensureAiModelsCatalog,
-  AiModelsCatalogClient,
-  CostCalculator,
-} from "@x12i/ai-tools";
+import { AiModelsCatalogClient, CostCalculator } from "@x12i/ai-tools";
 
-const { catalox } = createCataloxFromEnv();
-await ensureAiModelsCatalog(catalox);
-
-const catalog = new AiModelsCatalogClient({ catalox });
+const catalog = new AiModelsCatalogClient();
 const calculator = new CostCalculator(catalog);
 
 const result = await calculator.calculate({
   tokens: { prompt: 1000, completion: 500, total: 1500 },
-  provider: "openrouter",
-  modelUsed: "openai/gpt-4o",
+  provider: "openai",
+  usedModel: "gpt-5.5-2026-04-23",
 });
 
 console.log(result.cost);
+console.log(result.resolvedModelId); // e.g. openai/gpt-5.5
+console.log(result.usedModel);       // gpt-5.5-2026-04-23
+console.log(result.usage);
 ```
 
-## Reasoning models
-
-After sync, each catalog record includes **`supportsReasoning`** — use it to branch prompts, token limits, or cost handling.
+From activity or gateway JSON:
 
 ```ts
-import { getModelInfo, isReasoningModel } from "@x12i/ai-tools";
-
-const model = await getModelInfo("openai/o3-mini");
-if (model?.supportsReasoning) {
-  // pass OpenRouter `reasoning: { effort: "medium" }`, bill reasoning tokens, etc.
-}
-
-// Same check without loading the full record field:
-isReasoningModel(model!);
-```
-
-Detection uses OpenRouter metadata:
-
-- `supported_parameters` includes `reasoning` (or `include_reasoning`)
-- pricing includes `internal_reasoning` (exposed as `pricing.reasoningUsdPerToken`)
-
-```bash
-npx ai-tools models list --reasoning
-npx ai-tools models count --reasoning
+const result = await calculator.calculateFromRecord(activityDocument);
 ```
 
-Re-run [Updating the model catalog](#updating-the-model-catalog) after upgrading `@x12i/ai-tools` so existing Firestore rows pick up new fields (e.g. `supportsReasoning`).
+### Catalog loading and cache
 
-## Updating the model catalog
+Catalogs are fetched on first use and cached in memory for **24 hours**. Later calls reuse the cache without network I/O. Override TTL with `AI_TOOLS_CACHE_TTL_MS`. If a fetch fails, bundled `src/data/*.json` is used automatically.
 
-The **ai-models** catalog in Catalox/Firestore is a mirror of the [OpenRouter Models API](https://openrouter.ai/docs/api-reference/models). OpenRouter’s public `/models` endpoint needs **no API key**; optional `OPENROUTER_API_KEY` only helps with rate limits.
-
-### Prerequisites
+```ts
+import {
+  AiModelsCatalogClient,
+  DEFAULT_CATALOG_CACHE_TTL_MS,
+  invalidateCatalogLoadCache,
+  resolveCatalogCacheTtlMs,
+} from "@x12i/ai-tools";
 
-Add to `.env` (see [Environment variables](#environment-variables)):
+const client = new AiModelsCatalogClient({
+  cacheTtlMs: resolveCatalogCacheTtlMs(), // or DEFAULT_CATALOG_CACHE_TTL_MS
+});
 
-| Variable | Required for sync |
-|----------|-------------------|
-| `GOOGLE_SERVICE_ACCOUNT_BASE64` | Yes |
-| `FIREBASE_PROJECT_ID` | Yes |
-| `FIRESTORE_DATABASE_ID` | No (defaults to `(default)`) |
-| `AI_TOOLS_APP_ID` | No (default: `ai-tools`) |
-| `AI_TOOLS_CATALOG_ID` | No (default: `ai-models`) |
+await client.getAllModels(); // first call may fetch
+await client.getAllModels(); // cached
 
-First time only, register the catalog descriptor and app binding:
+await client.refresh(); // force reload now
 
-```bash
-npx ai-tools catalog ensure
+invalidateCatalogLoadCache(); // process-wide cache clear
 ```
 
-### When to run an update
-
-| Situation | What to run |
-|-----------|-------------|
-| **First deploy** | `npx ai-tools catalog ensure` then `npx ai-tools sync` |
-| **Routine refresh** (new models/pricing on OpenRouter) | `npx ai-tools sync` |
-| **After upgrading `@x12i/ai-tools`** (new indexed fields) | `npx ai-tools sync` |
-| **Health check only** (no writes) | `npx ai-tools catalog verify` |
-| **Remove models OpenRouter dropped** | `npx ai-tools sync --prune-stale` |
-
-### Recommended commands
-
-**Full update (production default)** — fetch OpenRouter, upsert every model, then verify counts match:
+CLI:
 
 ```bash
-npx ai-tools sync
+npx ai-tools catalog refresh
+npx ai-tools catalog verify
+npx ai-tools catalog verify --json
 ```
 
-Same job via npm script:
+Offline (bundled data only):
 
 ```bash
-npm run seed
-npm run seed:verbose   # progress lines
+npx ai-tools catalog refresh --bundled-only
+npx ai-tools models list --bundled-only
 ```
 
-**CI / cron** — JSON on stdout, non-zero exit if sync or verify fails:
+| npm script | Command |
+|------------|---------|
+| `npm run catalog:refresh` | Fetch catalogs and warm cache |
+| `npm run catalog:verify` | Verify both catalogs load |
 
-```bash
-npx ai-tools sync --json
-# or
-npm run verify:seed
-```
+## Cost calculation
 
-**Verify only** (read-only; good between scheduled syncs):
+### Flat usage input
 
-```bash
-npx ai-tools catalog verify
-npx ai-tools catalog verify --json
-# or
-npm run verify:sync
+```ts
+await calculator.calculate({
+  tokens: { prompt: 1000, completion: 500, total: 1500 },
+  provider: "openrouter",
+  usedModel: "openai/gpt-4o",
+});
 ```
 
-**Dry run** (fetch OpenRouter, no Firestore writes):
+Runtime model priority: `usedModel` → `modelUsed` → `model`.
 
-```bash
-npx ai-tools sync --dry-run
-```
+Every result includes `cost`, `resolvedModelId`, `provider`, `usage`, and optional `usedModel`, `model`, `breakdown`, `warnings`.
 
-| npm script | Equivalent |
-|------------|------------|
-| `npm run seed` | `npx ai-tools sync` |
-| `npm run seed:verbose` | `npx ai-tools sync --verbose` |
-| `npm run verify:seed` | `npx ai-tools sync` (via seed script, sync + verify) |
-| `npm run verify:sync` | `npx ai-tools catalog verify` |
+### Activity / gateway records
 
-### What `sync` does
+Pass nested activity or MongoDB export JSON; model, provider, and tokens are extracted automatically:
 
-1. Ensures catalog + descriptor exist (`catalog ensure` logic).
-2. Fetches all models from OpenRouter (`output_modalities=all`).
-3. Upserts each row into Firestore/Catalox (`data` + `indexed` fields).
-4. Verifies Catalox count equals OpenRouter count (unless `--no-verify`).
+```ts
+const result = await calculator.calculateFromRecord(activityDocument);
+```
 
-On re-sync, existing rows are **updated** (`syncedAt`, pricing, metadata); `createdAt` is preserved and `version` increments.
+**Model field priority:** `usedModel` / `modelUsed` / `resolvedModel` → `model` on `outer.input` or `config` → `xynthesisModel` / `skillModel` in `rawConfig` (lowest).
 
-### Cron example
+**Token sources:** `usage` → `tokens` → `metadata.diagnostics` (flagged as `ESTIMATED_TOKEN_USAGE`).
 
-```bash
-# Daily at 04:00 — fail the job if sync or verify fails
-0 4 * * * cd /path/to/app && npx ai-tools sync --json >> /var/log/ai-tools-sync.log 2>&1
-```
+### Versioned runtime model ids
 
-### Programmatic update
+`gpt-5.5-2026-04-23` resolves to catalog id `openai/gpt-5.5` when only the base model is listed. The response keeps `usedModel` as the original string and sets `resolvedModelId` to the catalog id used for pricing. A `VERSION_SUFFIX_PRICING` warning is included when suffix stripping was used.
+
+## Model catalogs
 
 ```ts
-import { createCataloxFromEnv } from "@x12i/catalox/firebase";
-import { runAiModelsCatalogSync, verifyAiModelsCatalog } from "@x12i/ai-tools/catalog";
+import {
+  AiModelsCatalogClient,
+  loadCatalogSources,
+  loadCatalogSourcesCached,
+  refreshAiModelsCatalog,
+  verifyAiModelsCatalog,
+} from "@x12i/ai-tools";
 
-const { catalox, firestore } = createCataloxFromEnv();
+await refreshAiModelsCatalog(); // force network fetch + warm cache
 
-// Sync + verify (throws CatalogSyncJobError on failure)
-const job = await runAiModelsCatalogSync({ catalox, firestore, verifyAfter: true });
-console.log(job.sync.upserted, job.verify?.ok);
+const client = new AiModelsCatalogClient();
+const models = await client.getAllModels();
 
-// Verify only
-const report = await verifyAiModelsCatalog({ catalox });
-if (!report.ok) throw new Error(`catalog drift: missing=${report.missingInCatalox.length}`);
+const loaded = await loadCatalogSources({ bundledOnly: true });
+console.log(loaded.meta.directCount, loaded.meta.openRouterCount);
 ```
 
-## Smart model name resolution
+`OpenRouterSyncProvider` remains available to fetch live model metadata from the [OpenRouter Models API](https://openrouter.ai/docs/api-reference/models) (optional; catalogs used for pricing are the x12i JSON files above).
+
+## Smart model resolution
 
-Callers often pass messy `provider` + `model` pairs (typos, missing namespaces, version suffixes, aliases used as provider names, or no provider at all). **`ModelNameResolver`** normalises input and runs a deterministic strategy pipeline against the cached catalog (no network calls during resolution).
+`ModelNameResolver` normalises messy `provider` + `model` input against the cached catalog.
 
 ```ts
 import { AiModelsCatalogClient, ModelNameResolver } from "@x12i/ai-tools";
 
-const catalog = new AiModelsCatalogClient({ catalox });
+const catalog = new AiModelsCatalogClient();
 const models = await catalog.getAllModels();
-
 const resolver = new ModelNameResolver(models, { aliasRegistry });
+
 const result = await catalog.resolveModel({
   provider: "openrouter",
   model: "gpt4o",
 });
-
-if (result.found) {
-  console.log(result.modelId); // openai/gpt-4o
-  console.log(result.confidence, result.resolvedVia);
-  console.log(result.routedViaOpenRouter);
-}
 ```
 
-### What it handles
-
-| Input | Resolves to |
-|-------|-------------|
-| `openrouter` + `gpt-4o` | `openai/gpt-4o` (provider prefix inference) |
-| `openrouter` + `gpt4o` | `openai/gpt-4o` (shorthand expansion) |
-| `openrouter` + `gpt-4o-2024-08-06` | `openai/gpt-4o` (version suffix strip) |
-| `openrouter` + `openai/claude-3-5-sonnet` | `anthropic/claude-3-5-sonnet-…` (cross-provider correction) |
-| provider `best` (alias name) + any model | alias target (alias-as-provider correction) |
-| model only (`gpt-4o`) | catalog alias or prefix inference |
-| `ollama` + `llama3:8b` | passthrough (`record: null`, not an error) |
-
-Each success includes `confidence`, `resolvedVia[]`, and `resolvedReason`. Below-threshold matches return `found: false` with `bestRejectedCandidate` when applicable.
+| Input | Typical resolution |
+|-------|-------------------|
+| `openrouter` + `gpt-4o` | `openai/gpt-4o` |
+| `openrouter` + `gpt-4o-2024-08-06` | `openai/gpt-4o` (suffix strip) |
+| `gpt-4o` only | catalog alias or prefix inference |
+| `ollama` + `llama3:8b` | local passthrough |
 
-### OpenRouter vs direct provider (env defaults)
+### OpenRouter vs direct routing
 
-When the **provider is omitted** or ambiguous, routing defaults come from your `.env` (loaded via [@x12/env](https://www.npmjs.com/package/@x12i/env)):
+Routing defaults use `.env` via [@x12i/env](https://www.npmjs.com/package/@x12i/env):
 
-| Condition | Default routing |
-|-----------|-----------------|
-| `OPENROUTER_API_KEY` is set **and** `USE_OPENROUTER=true` or `USE_OPENROUTER=1` | OpenRouter |
-| `OPENROUTER_API_KEY` is set **and** `{VENDOR}_API_KEY` is missing for the resolved vendor | OpenRouter |
-| `{VENDOR}_API_KEY` is set (and `USE_OPENROUTER` not forcing OR) | Direct to that vendor |
-
-**Vendor API key naming:** `{VENDOR}_API_KEY` where `VENDOR` is the catalog `providerId` in `UPPER_SNAKE_CASE` (hyphens → underscores).
-
-Examples:
-
-- `openai` → `OPENAI_API_KEY`
-- `anthropic` → `ANTHROPIC_API_KEY`
-- `meta-llama` → `META_LLAMA_API_KEY`
-- `x-ai` → `X_AI_API_KEY`
+| Condition | Routes via OpenRouter |
+|-----------|----------------------|
+| `USE_OPENROUTER=true` and `OPENROUTER_API_KEY` set | Yes |
+| `OPENROUTER_API_KEY` set, vendor `{VENDOR}_API_KEY` missing | Yes |
+| Vendor key present, `USE_OPENROUTER` not forcing OR | Direct |
 
 ```ts
-import {
-  loadOpenRouterRoutingEnv,
-  shouldDefaultRouteViaOpenRouter,
-} from "@x12i/ai-tools";
-
-const routing = loadOpenRouterRoutingEnv();
-shouldDefaultRouteViaOpenRouter("openai", routing); // true if OR key set but OPENAI_API_KEY missing
+import { loadOpenRouterRoutingEnv, shouldDefaultRouteViaOpenRouter } from "@x12i/ai-tools";
 ```
 
-Explicit `provider: "openrouter"` always sets `routedViaOpenRouter: true`. Explicit direct providers (`openai`, `anthropic`, …) use direct routing unless env rules above apply.
-
-### CLI
+## Reasoning models
 
-```bash
-npx ai-tools models resolve --provider openrouter --model gpt4o
-npx ai-tools models resolve --model claude-sonnet --verbose
-npx ai-tools models resolve --model turbomax-9000 --json
-```
+Catalog records expose `supportsReasoning` when the model accepts reasoning parameters or has reasoning pricing.
 
-## Tests
+```ts
+import { getModelInfo, isReasoningModel } from "@x12i/ai-tools";
 
-```bash
-npm test              # unit tests (mocked)
-npm run test:live     # live Firestore/Catalox tests (uses .env)
-npm run test:all      # both
+const model = await getModelInfo("openai/o3-mini", { bundledOnly: true });
+if (model && isReasoningModel(model)) {
+  // bill reasoning tokens, pass OpenRouter reasoning params, etc.
+}
 ```
 
 ## CLI
 
-Catalog update commands are documented in [Updating the model catalog](#updating-the-model-catalog). Other commands:
-
 ```bash
+npx ai-tools catalog refresh
+npx ai-tools catalog verify --json
 npx ai-tools models list --provider openai
-npx ai-tools models list --reasoning
 npx ai-tools models resolve --model gpt4o --provider openrouter --verbose
-npx ai-tools cost --model openai/gpt-4o --prompt-tokens 2000 --completion-tokens 800
+npx ai-tools cost --model openai/gpt-5.5 --prompt-tokens 1000 --completion-tokens 500 --provider openai
 npx ai-tools alias init
 npx ai-tools alias set best anthropic/claude-opus-4 --provider openrouter
 npx ai-tools alias check
 ```
 
-### Environment variables
+## Environment variables
+
+Copy `.env.example` to `.env` in your app.
 
 | Variable | Purpose |
 |----------|---------|
-| `OPENROUTER_API_KEY` | OpenRouter API key; used for routing defaults and optional sync auth |
-| `USE_OPENROUTER` | Set to `true` or `1` to default API routing via OpenRouter when `OPENROUTER_API_KEY` is set |
-| `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, … | Direct vendor keys — pattern `{PROVIDER_ID}_API_KEY` (see smart resolver above) |
-| `GOOGLE_SERVICE_ACCOUNT_BASE64` | Firebase / Firestore credentials |
-| `FIREBASE_PROJECT_ID` | GCP project |
-| `FIRESTORE_DATABASE_ID` | Firestore database (default: `(default)`) |
-| `AI_TOOLS_APP_ID` | Catalox appId (default: `ai-tools`) |
-| `AI_TOOLS_CATALOG_ID` | Catalog id (default: `ai-models`) |
-| `AI_TOOLS_CACHE_TTL_MS` | nx-cache TTL override |
+| `OPENROUTER_API_KEY` | OpenRouter routing defaults |
+| `USE_OPENROUTER` | `true` / `1` to prefer OpenRouter when key is set |
+| `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) |
 | `AI_TOOLS_ALIASES_PATH` | Path to `aliases.json` |
 
-## Subpath exports
-
-- `@x12i/ai-tools` — main API (`ModelNameResolver`, `loadOpenRouterRoutingEnv`, catalog, cost, aliases)
-- `@x12i/ai-tools/cost`
-- `@x12i/ai-tools/toolbox`
-- `@x12i/ai-tools/sync` — sync + resolver types
-- `@x12i/ai-tools/catalox`
-- `@x12i/ai-tools/aliases`
-- `@x12i/ai-tools/models`
-- `@x12i/ai-tools/catalog` — `runAiModelsCatalogSync`, `verifyAiModelsCatalog`, bootstrap
-
-## Project aliases
-
-Commit `./ai-tools/aliases.json` in your application repo so dev/staging/prod share the same model vocabulary. Alias targets that use shorthand or versioned ids are resolved through the same smart resolver as runtime model strings.
+## Package exports
 
-## Publishing
+| Subpath | Contents |
+|---------|----------|
+| `@x12i/ai-tools` | Catalog client, cost calculator, resolver, aliases |
+| `@x12i/ai-tools/cost` | Cost types, `extractUsageInput`, `CostCalculator` |
+| `@x12i/ai-tools/catalog` | `loadCatalogSources`, `loadCatalogSourcesCached`, refresh/verify |
+| `@x12i/ai-tools/models` | Model listing and filters |
+| `@x12i/ai-tools/sync` | `ModelNameResolver`, OpenRouter fetch helper |
+| `@x12i/ai-tools/aliases` | Alias registry |
+| `@x12i/ai-tools/toolbox` | Tracker, router, guard |
 
-Scoped packages (`@x12i/...`) require public access on the free npm plan:
+## Tests
 
 ```bash
-npm publish
+npm test
+npm run build
+npm run test:live    # optional OpenRouter API live test
 ```
 
-`package.json` includes `"publishConfig": { "access": "public" }`. If publish still fails, run `npm publish --access public`.
+`prepublishOnly` runs build + tests before publish.
+
+## Project aliases
+
+Commit `./ai-tools/aliases.json` in your app repo. Alias targets are resolved with the same `ModelNameResolver` pipeline as runtime model strings.
 
 ## License
 

package/dist/AiModelsCatalogClient-B5FMI9gj.d.cts

@@ -0,0 +1,58 @@
+import { a as AiModelRecord, l as ModelResolverOptions, h as ModelResolutionInput, j as ModelResolutionResult } from './types-BrzJWsTU.cjs';
+
+type LoadCatalogOptions = {
+    directCatalogUrl?: string;
+    openRouterCatalogUrl?: string;
+    /** When true, skip HTTP and use bundled `src/data` only. */
+    bundledOnly?: boolean;
+    fetchTimeoutMs?: number;
+};
+type LoadedCatalogs = {
+    direct: Map<string, AiModelRecord>;
+    openrouter: Map<string, AiModelRecord>;
+    meta: {
+        directSource: "remote" | "bundled";
+        openRouterSource: "remote" | "bundled";
+        directUrl: string;
+        openRouterUrl: string;
+        directCount: number;
+        openRouterCount: number;
+    };
+};
+/** Load direct-provider and OpenRouter catalogs (remote with bundled fallback). */
+declare function loadCatalogSources(options?: LoadCatalogOptions): Promise<LoadedCatalogs>;
+/** Read bundled JSON from disk (CLI / tests without import assertions). */
+declare function readBundledCatalogFiles(): Promise<LoadedCatalogs>;
+
+type AiModelsCatalogClientOptions = LoadCatalogOptions & {
+    cacheTtlMs?: number;
+    /** Cache scope key (default: `default`). */
+    cacheKey?: string;
+    resolverOptions?: Omit<ModelResolverOptions, "aliasRegistry">;
+};
+declare class AiModelsCatalogClient {
+    private readonly cacheTtlMs;
+    private readonly cacheKey;
+    private readonly loadOptions;
+    private readonly resolverOptions?;
+    private directModels;
+    private openRouterModels;
+    private loadedAt;
+    private loadPromise;
+    constructor(options?: AiModelsCatalogClientOptions);
+    private isInstanceCacheValid;
+    private applyLoaded;
+    private ensureLoaded;
+    mergedModels(): Map<string, AiModelRecord>;
+    private catalogForProvider;
+    private resolver;
+    getAllModels(): Promise<Map<string, AiModelRecord>>;
+    getDirectModels(): Promise<Map<string, AiModelRecord>>;
+    getOpenRouterModels(): Promise<Map<string, AiModelRecord>>;
+    resolveModel(input: ModelResolutionInput, options?: ModelResolverOptions): Promise<ModelResolutionResult>;
+    getModel(modelId: string, provider?: string, options?: ModelResolverOptions): Promise<AiModelRecord | null>;
+    /** Clear caches and fetch catalogs again immediately. */
+    refresh(): Promise<void>;
+}
+
+export { AiModelsCatalogClient as A, type LoadCatalogOptions as L, type AiModelsCatalogClientOptions as a, type LoadedCatalogs as b, loadCatalogSources as l, readBundledCatalogFiles as r };

package/dist/AiModelsCatalogClient-CPPNI6Ry.d.ts

@@ -0,0 +1,58 @@
+import { a as AiModelRecord, l as ModelResolverOptions, h as ModelResolutionInput, j as ModelResolutionResult } from './types-BrzJWsTU.js';
+
+type LoadCatalogOptions = {
+    directCatalogUrl?: string;
+    openRouterCatalogUrl?: string;
+    /** When true, skip HTTP and use bundled `src/data` only. */
+    bundledOnly?: boolean;
+    fetchTimeoutMs?: number;
+};
+type LoadedCatalogs = {
+    direct: Map<string, AiModelRecord>;
+    openrouter: Map<string, AiModelRecord>;
+    meta: {
+        directSource: "remote" | "bundled";
+        openRouterSource: "remote" | "bundled";
+        directUrl: string;
+        openRouterUrl: string;
+        directCount: number;
+        openRouterCount: number;
+    };
+};
+/** Load direct-provider and OpenRouter catalogs (remote with bundled fallback). */
+declare function loadCatalogSources(options?: LoadCatalogOptions): Promise<LoadedCatalogs>;
+/** Read bundled JSON from disk (CLI / tests without import assertions). */
+declare function readBundledCatalogFiles(): Promise<LoadedCatalogs>;
+
+type AiModelsCatalogClientOptions = LoadCatalogOptions & {
+    cacheTtlMs?: number;
+    /** Cache scope key (default: `default`). */
+    cacheKey?: string;
+    resolverOptions?: Omit<ModelResolverOptions, "aliasRegistry">;
+};
+declare class AiModelsCatalogClient {
+    private readonly cacheTtlMs;
+    private readonly cacheKey;
+    private readonly loadOptions;
+    private readonly resolverOptions?;
+    private directModels;
+    private openRouterModels;
+    private loadedAt;
+    private loadPromise;
+    constructor(options?: AiModelsCatalogClientOptions);
+    private isInstanceCacheValid;
+    private applyLoaded;
+    private ensureLoaded;
+    mergedModels(): Map<string, AiModelRecord>;
+    private catalogForProvider;
+    private resolver;
+    getAllModels(): Promise<Map<string, AiModelRecord>>;
+    getDirectModels(): Promise<Map<string, AiModelRecord>>;
+    getOpenRouterModels(): Promise<Map<string, AiModelRecord>>;
+    resolveModel(input: ModelResolutionInput, options?: ModelResolverOptions): Promise<ModelResolutionResult>;
+    getModel(modelId: string, provider?: string, options?: ModelResolverOptions): Promise<AiModelRecord | null>;
+    /** Clear caches and fetch catalogs again immediately. */
+    refresh(): Promise<void>;
+}
+
+export { AiModelsCatalogClient as A, type LoadCatalogOptions as L, type AiModelsCatalogClientOptions as a, type LoadedCatalogs as b, loadCatalogSources as l, readBundledCatalogFiles as r };

package/dist/aliases/index.cjs

@@ -2,10 +2,11 @@
 
 
 
-var _chunkQWAX7VQOcjs = require('../chunk-QWAX7VQO.cjs');
-require('../chunk-7Q742NI3.cjs');
+var _chunkBAHBDADJcjs = require('../chunk-BAHBDADJ.cjs');
+require('../chunk-PADNCGZB.cjs');
+require('../chunk-GS7T56RP.cjs');
 
 
 
-exports.AliasRegistry = _chunkQWAX7VQOcjs.AliasRegistry; exports.AliasResolver = _chunkQWAX7VQOcjs.AliasResolver;
+exports.AliasRegistry = _chunkBAHBDADJcjs.AliasRegistry; exports.AliasResolver = _chunkBAHBDADJcjs.AliasResolver;
 //# sourceMappingURL=index.cjs.map

package/dist/aliases/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/ami/Documents/prometheus/x12i/ai-tools/dist/aliases/index.cjs"],"names":[],"mappings":"AAAA,0GAA8B;AAC9B;AACE;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACF,iHAAC","file":"/Users/ami/Documents/prometheus/x12i/ai-tools/dist/aliases/index.cjs"}
+{"version":3,"sources":["/Users/ami/Documents/prometheus/x12i/ai-tools/dist/aliases/index.cjs"],"names":[],"mappings":"AAAA,0GAA8B;AAC9B;AACE;AACA;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACF,iHAAC","file":"/Users/ami/Documents/prometheus/x12i/ai-tools/dist/aliases/index.cjs"}

package/dist/aliases/index.d.cts

@@ -1,8 +1,6 @@
-import { b as AliasRegistry, j as ResolvedModelRef, d as AliasValidationReport } from '../types-CX6QFNNy.cjs';
-export { A as AliasEntry, a as AliasFileSchema, c as AliasRegistryOptions } from '../types-CX6QFNNy.cjs';
-import { A as AiModelsCatalogClient } from '../AiModelsCatalogClient-CNeqFiFs.cjs';
-import '../types-BYXnCvKx.cjs';
-import '@x12i/catalox';
+import { d as AliasRegistry, u as ResolvedModelRef, f as AliasValidationReport } from '../types-BrzJWsTU.cjs';
+export { b as AliasEntry, c as AliasFileSchema, e as AliasRegistryOptions } from '../types-BrzJWsTU.cjs';
+import { A as AiModelsCatalogClient } from '../AiModelsCatalogClient-B5FMI9gj.cjs';
 
 type AliasResolverOptions = {
     registry: AliasRegistry;

package/dist/aliases/index.d.ts

@@ -1,8 +1,6 @@
-import { b as AliasRegistry, j as ResolvedModelRef, d as AliasValidationReport } from '../types-CuiPDcVs.js';
-export { A as AliasEntry, a as AliasFileSchema, c as AliasRegistryOptions } from '../types-CuiPDcVs.js';
-import { A as AiModelsCatalogClient } from '../AiModelsCatalogClient-nwFoEaqL.js';
-import '../types-BYXnCvKx.js';
-import '@x12i/catalox';
+import { d as AliasRegistry, u as ResolvedModelRef, f as AliasValidationReport } from '../types-BrzJWsTU.js';
+export { b as AliasEntry, c as AliasFileSchema, e as AliasRegistryOptions } from '../types-BrzJWsTU.js';
+import { A as AiModelsCatalogClient } from '../AiModelsCatalogClient-CPPNI6Ry.js';
 
 type AliasResolverOptions = {
     registry: AliasRegistry;