@x12i/ai-tools 1.0.2

package/dist/types-DdGB3YaA.d.ts

@@ -0,0 +1,278 @@
+/** OpenRouter Models API — https://openrouter.ai/api/v1/models */
+type OpenRouterOutputModality = "text" | "image" | "audio" | "embeddings" | "video" | "speech" | "transcription" | "all";
+type OpenRouterModelsQuery = {
+    /** Comma-separated or "all" — default on our sync is "all". */
+    output_modalities?: string;
+    supported_parameters?: string;
+};
+type OpenRouterPricingApi = {
+    prompt: string;
+    completion: string;
+    request: string;
+    image: string;
+    web_search?: string;
+    internal_reasoning?: string;
+    input_cache_read?: string;
+    input_cache_write?: string;
+};
+type OpenRouterArchitectureApi = {
+    modality?: string;
+    input_modalities: string[];
+    output_modalities: string[];
+    tokenizer: string;
+    instruct_type: string | null;
+};
+type OpenRouterTopProviderApi = {
+    context_length: number;
+    max_completion_tokens: number | null;
+    is_moderated: boolean;
+};
+type OpenRouterDefaultParametersApi = {
+    temperature?: number | null;
+    top_p?: number | null;
+    top_k?: number | null;
+    frequency_penalty?: number | null;
+    presence_penalty?: number | null;
+    repetition_penalty?: number | null;
+};
+type OpenRouterModelApi = {
+    id: string;
+    canonical_slug: string;
+    hugging_face_id?: string | null;
+    name: string;
+    created: number;
+    description: string;
+    context_length: number;
+    architecture: OpenRouterArchitectureApi;
+    pricing: OpenRouterPricingApi;
+    top_provider: OpenRouterTopProviderApi;
+    per_request_limits: unknown | null;
+    supported_parameters: string[];
+    default_parameters: OpenRouterDefaultParametersApi | null;
+    supported_voices?: unknown | null;
+    knowledge_cutoff?: string | null;
+    expiration_date?: string | null;
+    links?: {
+        details?: string;
+    } | null;
+};
+type OpenRouterModelsResponse = {
+    data: OpenRouterModelApi[];
+};
+
+type AiModelPricing = {
+    promptUsdPerToken: number;
+    completionUsdPerToken: number;
+    imageUsdPerUnit: number;
+    requestUsdPerRequest: number;
+    cacheReadUsdPerToken?: number;
+    cacheWriteUsdPerToken?: number;
+    reasoningUsdPerToken?: number;
+    webSearchUsdPerRequest?: number;
+    openRouterMarkupUsdPerInputToken?: number;
+    openRouterMarkupUsdPerOutputToken?: number;
+    pricedAt: string;
+    source: "openrouter" | "direct" | "manual";
+};
+/**
+ * Canonical catalog record — mirrors OpenRouter Models API fields plus normalized pricing.
+ * Stored as-is in Catalox `data`; scalar fields duplicated in `indexed` for queries.
+ */
+type AiModelRecord = {
+    modelId: string;
+    name: string;
+    providerId: string;
+    canonicalSlug: string;
+    status: "active" | "deprecated" | "unknown";
+    description: string;
+    created: number;
+    expirationDate: string | null;
+    contextLength: number;
+    maxCompletionTokens: number | null;
+    isModerated: boolean;
+    modality: string;
+    inputModalities: string[];
+    outputModalities: string[];
+    tokenizer: string;
+    instructType: string | null;
+    supportedParameters: string[];
+    defaultParameters: OpenRouterDefaultParametersApi | null;
+    perRequestLimits: unknown | null;
+    pricing: AiModelPricing;
+    /** Raw OpenRouter pricing strings (USD per token/request/unit). */
+    openRouterPricing: OpenRouterPricingApi;
+    architecture: OpenRouterArchitectureApi;
+    topProvider: OpenRouterTopProviderApi;
+    /** Full OpenRouter API object — complete mirror for forward compatibility. */
+    openRouter: OpenRouterModelApi;
+    aliases: string[];
+    availableOnOpenRouter: boolean;
+    supportsStreaming: boolean;
+    supportsTools: boolean;
+    /** Exposes reasoning/thinking tokens (OpenRouter `reasoning` param and/or `internal_reasoning` pricing). */
+    supportsReasoning: boolean;
+    primaryOutputModality: string;
+    syncedAt: string;
+    syncSource: "openrouter" | "manual";
+};
+type ModelListFilters = {
+    providerId?: string;
+    status?: AiModelRecord["status"];
+    outputModality?: string;
+    inputModality?: string;
+    supportedParameter?: string;
+    supportsTools?: boolean;
+    supportsReasoning?: boolean;
+    search?: string;
+    limit?: number;
+    offset?: number;
+};
+type ModelListResult = {
+    models: AiModelRecord[];
+    total: number;
+    limit: number;
+    offset: number;
+};
+
+type AliasEntry = {
+    modelId: string;
+    provider: string;
+    description?: string;
+    tags?: string[];
+    addedAt: string;
+    updatedAt: string;
+};
+type AliasFileSchema = {
+    $schema?: string;
+    version: 1;
+    updatedAt: string;
+    aliases: Record<string, AliasEntry>;
+};
+type ResolvedModelRef = {
+    alias: string;
+    entry: AliasEntry;
+    modelRecord: AiModelRecord | null;
+    modelId: string;
+    provider: string;
+    name: string;
+};
+type AliasValidationReport = {
+    total: number;
+    ok: number;
+    unknown: number;
+    broken: number;
+    entries: Array<{
+        name: string;
+        status: "ok" | "unknown" | "broken";
+        modelId: string;
+        resolvedName?: string;
+        issue?: string;
+    }>;
+};
+
+type AliasRegistryOptions = {
+    aliasesPath?: string;
+};
+declare class AliasRegistry {
+    private readonly aliasesPath;
+    constructor(options?: AliasRegistryOptions);
+    get path(): string;
+    exists(): boolean;
+    init(): void;
+    load(): AliasFileSchema;
+    get(aliasName: string): AliasEntry | null;
+    list(filter?: {
+        tag?: string;
+    }): Array<{
+        name: string;
+    } & AliasEntry>;
+    set(aliasName: string, entry: Omit<AliasEntry, "addedAt" | "updatedAt">): AliasEntry;
+    remove(aliasName: string): boolean;
+    rename(from: string, to: string, options?: {
+        force?: boolean;
+    }): void;
+    private writeFile;
+}
+
+/**
+ * Env naming for vendor direct API keys: `{VENDOR}_API_KEY`
+ * where VENDOR is the provider id in UPPER_SNAKE (hyphens → underscores).
+ *
+ * Examples: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `META_LLAMA_API_KEY`, `X_AI_API_KEY`
+ */
+declare function providerIdToEnvKeyPrefix(providerId: string): string;
+declare function vendorApiKeyEnvName(providerId: string): string;
+type OpenRouterRoutingConfig = {
+    /** OPENROUTER_API_KEY is set and non-empty */
+    hasOpenRouterKey: boolean;
+    /** USE_OPENROUTER=true or USE_OPENROUTER=1 */
+    useOpenRouterExplicit: boolean;
+    /** Read `{PROVIDER}_API_KEY` for a catalog provider id */
+    getVendorApiKey(providerId: string): string | undefined;
+};
+/**
+ * Load routing hints from process env and optional `.env` (via @x12/env).
+ */
+declare function loadOpenRouterRoutingEnv(env?: Record<string, string | undefined>): OpenRouterRoutingConfig;
+/**
+ * Default route via OpenRouter when:
+ * 1. OPENROUTER_API_KEY is set AND USE_OPENROUTER=true|1, or
+ * 2. OPENROUTER_API_KEY is set AND the vendor's `{VENDOR}_API_KEY` is missing.
+ */
+declare function shouldDefaultRouteViaOpenRouter(providerId: string | undefined, config: OpenRouterRoutingConfig): boolean;
+
+type ModelResolutionInput = {
+    /** Provider hint (openrouter, openai, anthropic, …). May be omitted. */
+    provider?: string;
+    /** Model id, alias, shorthand, or partial name. Required. */
+    model: string;
+};
+type ResolutionStrategy = "alias-registry" | "alias-as-provider-correction" | "exact-match" | "catalog-alias-match" | "canonical-slug-match" | "provider-prefix-injection" | "cross-provider-correction" | "version-suffix-strip" | "date-suffix-strip" | "shorthand-expansion" | "partial-name-match" | "local-provider-passthrough";
+type ModelResolutionSuccess = {
+    found: true;
+    modelId: string;
+    record: AiModelRecord | null;
+    routedViaOpenRouter: boolean;
+    confidence: number;
+    resolvedVia: ResolutionStrategy[];
+    resolvedReason: string;
+    normalisedInput: string;
+};
+type ModelResolutionNotFound = {
+    found: false;
+    modelId: null;
+    record: null;
+    attemptedStrategies: ResolutionStrategy[];
+    bestRejectedCandidate?: {
+        modelId: string;
+        confidence: number;
+        reason: string;
+    };
+    reason: string;
+};
+type ModelResolutionResult = ModelResolutionSuccess | ModelResolutionNotFound;
+type ModelResolverOptions = {
+    confidenceThreshold?: number;
+    aliasRegistry?: AliasRegistry;
+    additionalShorthands?: Record<string, string>;
+    additionalProviderPatterns?: Array<{
+        pattern: RegExp;
+        provider: string;
+    }>;
+    additionalLocalProviders?: string[];
+    /** Env-based OpenRouter vs direct routing. Defaults to loadOpenRouterRoutingEnv(). */
+    routingEnv?: OpenRouterRoutingConfig;
+};
+type CatalogIndexes = {
+    aliasIndex: Map<string, string>;
+    slugIndex: Map<string, string>;
+    providerPrefixesBySize: string[];
+};
+/** @deprecated Use ModelResolutionSuccess via ModelNameResolver */
+type ResolvedModel = {
+    catalogModel: AiModelRecord;
+    matchedAlias: string;
+    routedViaOpenRouter: boolean;
+};
+
+export { type AiModelPricing as A, type CatalogIndexes as C, type ModelListFilters as M, type OpenRouterArchitectureApi as O, type ResolutionStrategy as R, type AiModelRecord as a, type AliasEntry as b, type AliasFileSchema as c, AliasRegistry as d, type AliasRegistryOptions as e, type AliasValidationReport as f, type ModelListResult as g, type ModelResolutionInput as h, type ModelResolutionNotFound as i, type ModelResolutionResult as j, type ModelResolutionSuccess as k, type ModelResolverOptions as l, type OpenRouterModelApi as m, type OpenRouterModelsQuery as n, type OpenRouterModelsResponse as o, type OpenRouterOutputModality as p, type OpenRouterPricingApi as q, type OpenRouterRoutingConfig as r, type OpenRouterTopProviderApi as s, type ResolvedModel as t, type ResolvedModelRef as u, loadOpenRouterRoutingEnv as v, providerIdToEnvKeyPrefix as w, shouldDefaultRouteViaOpenRouter as x, vendorApiKeyEnvName as y };

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@x12i/ai-tools",
+  "version": "1.0.2",
+  "description": "AI model catalog, cost calculation, and LLM utility belt backed by Catalox",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ai-tools": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./cost": {
+      "types": "./dist/cost/index.d.ts",
+      "import": "./dist/cost/index.js",
+      "require": "./dist/cost/index.cjs"
+    },
+    "./toolbox": {
+      "types": "./dist/toolbox/index.d.ts",
+      "import": "./dist/toolbox/index.js",
+      "require": "./dist/toolbox/index.cjs"
+    },
+    "./sync": {
+      "types": "./dist/sync/index.d.ts",
+      "import": "./dist/sync/index.js",
+      "require": "./dist/sync/index.cjs"
+    },
+    "./catalox": {
+      "types": "./dist/catalox/index.d.ts",
+      "import": "./dist/catalox/index.js",
+      "require": "./dist/catalox/index.cjs"
+    },
+    "./aliases": {
+      "types": "./dist/aliases/index.d.ts",
+      "import": "./dist/aliases/index.js",
+      "require": "./dist/aliases/index.cjs"
+    },
+    "./models": {
+      "types": "./dist/models/index.d.ts",
+      "import": "./dist/models/index.js",
+      "require": "./dist/models/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    "test:all": "npm test && npm run test:live",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "seed": "tsx scripts/seed.ts",
+    "seed:verbose": "tsx scripts/seed.ts --verbose",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "@x12i/catalox": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@x12i/helpers": {
+      "optional": true
+    },
+    "firebase-admin": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@x12i/env": "^4.0.1",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "nx-cache": "^1.0.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "@x12i/catalox": "^4.0.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^1.6.1"
+  },
+  "keywords": [
+    "ai",
+    "openrouter",
+    "catalox",
+    "llm",
+    "cost",
+    "models"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/x12i/ai-tools.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/aliases.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@x12i/ai-tools/schemas/aliases.json",
+  "title": "AI Tools Alias File",
+  "type": "object",
+  "required": ["version", "updatedAt", "aliases"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "aliases": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["modelId", "provider", "addedAt", "updatedAt"],
+        "properties": {
+          "modelId": { "type": "string", "minLength": 1 },
+          "provider": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "tags": { "type": "array", "items": { "type": "string" } },
+          "addedAt": { "type": "string", "format": "date-time" },
+          "updatedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}