@agentproto/model-catalog 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy André and agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @agentproto/model-catalog
+
+A dependency-light (**zod-only**) unified model catalog for LLM, image, video,
+audio and voice models — with a cost dispatcher, curation, pricing, and a
+picker.
+
+This is the OSS core. Downstream consumers layer their own policy on top:
+`@agstudio/model-catalog` adds billing / access / BYOK; the `agentproto` CLI
+adds a provider-key store and the `agentproto models` picker.
+
+## Install
+
+```bash
+npm add @agentproto/model-catalog
+```
+
+## Subpaths
+
+| Import | What |
+| --- | --- |
+| `@agentproto/model-catalog` | everything re-exported |
+| `…/schema` | zod schemas + shared types (incl. `BillingUnit`, `CostMultipliers`) |
+| `…/llm` · `…/image` · `…/video` · `…/audio` · `…/voice` | per-modality catalogs |
+| `…/cost` · `…/pricing` | cost dispatcher + pricing helpers |
+| `…/curation` · `…/picker` | surfacing + selection helpers |
+| `…/byok` · `…/access` | policy hooks (debit decision, access evaluation) |
+
+```ts
+import { LLM_PRICING_CATALOG } from "@agentproto/model-catalog/llm"
+
+const p = LLM_PRICING_CATALOG["claude-opus-4-8"]
+//    → { inputPer1M, outputPer1M, provider, … }
+```
+
+## License
+
+MIT

package/dist/access/index.d.ts

@@ -0,0 +1,30 @@
+export { A as AccessDecision, a as AccessEffect, b as AccessEvalInput, c as AccessRule, d as AccessTarget, e as AppScope, f as evaluateAccess } from '../evaluate-DisH3H7u.js';
+import { R as ResolvedModel } from '../index-BICjPG8H.js';
+import '../base-BNHcMifc.js';
+import 'zod';
+import '../catalog-aQHd559b.js';
+import '../image/index.js';
+import '../video/index.js';
+import '../audio/index.js';
+import '../audio-BzVF_wke.js';
+import '../schema/voice.js';
+
+/**
+ * Catalog-flag defaults — the layer that runs before any workspace
+ * override. Mirrors the access-control plan:
+ *   - Default-allow: `lifecycle = stable && agentVisible = true`
+ *   - Default-block: `lifecycle = preview` or `lifecycle = deprecated`
+ *   - Default-block: any model with `agentVisible = false`
+ *
+ * Legacy catalog data (image/video) carries `agentVisible` but not
+ * `lifecycle` — until v2 normalization, lifecycle defaults to "stable"
+ * for every entry. LLM and audio entries default to allow (curated).
+ */
+
+interface CatalogDefaultDecision {
+    allowed: boolean;
+    reason: string;
+}
+declare function evaluateCatalogDefaults(model: ResolvedModel): CatalogDefaultDecision;
+
+export { type CatalogDefaultDecision, evaluateCatalogDefaults };

package/dist/access/index.mjs

@@ -0,0 +1,4 @@
+export { evaluateAccess, evaluateCatalogDefaults } from '../chunk-HRRG2RZO.mjs';
+import '../chunk-WTHHXXIK.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/access/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/audio/index.d.ts

@@ -0,0 +1,84 @@
+import { A as AudioCapabilities } from '../audio-BzVF_wke.js';
+import 'zod';
+
+/**
+ * Audio Model Catalog — TTS + STT provider models.
+ *
+ * Pairs with the voice catalog (`@agentproto/model-catalog/voice`) but a
+ * separate concern: voices describe *what the output sounds like*, models
+ * here describe *how the provider bills*. A single TTS model (e.g.
+ * ElevenLabs `multilingual-v2`) can render hundreds of voices at the
+ * same rate.
+ *
+ * Billing follows the per-kind dispatcher in `cost/index.ts`:
+ *   - TTS bills `per_1k_chars` (multiply characters/1000 × creditCost)
+ *   - STT bills `per_minute` (multiply ceil(seconds/60) × creditCost)
+ *
+ * Adding a model = 1 entry here + (if used by an integration) a
+ * provider call-site that passes the model id to the cost dispatcher
+ * so `calculateCost(modelId, { kind: "audio", characters / seconds })`
+ * returns real numbers instead of the placeholder.
+ *
+ * Prices are point-in-time (refresh monthly via the drift-check
+ * script). Sources noted per entry — production cost ≠ retail; we
+ * markup ~1.25-1.5× into `creditCost` (displayed credits, 1 cred ≈
+ * €0.01) consistent with the image/video catalogs.
+ */
+
+/**
+ * Audio MODALITY labels — what an audio model does. A model may do more
+ * than one (e.g. a combined engine, or a provider exposing both cascade
+ * TTS and conversational s2s), so these are boolean flags on
+ * `AudioCapabilities`, not a single discriminator. The model's catalog
+ * `kind` is always the family `"audio"`; modality lives here.
+ *   - `tts` — text → speech
+ *   - `stt` — speech → text
+ *   - `s2s` — speech ↔ speech (one model; distinct from a tts+llm+stt cascade)
+ */
+type AudioModality = "tts" | "stt" | "s2s";
+type AudioBillingUnit = "per_1k_chars" | "per_minute" | "per_second";
+type AudioProvider = "elevenlabs" | "minimax" | "openai" | "replicate" | "deepgram" | "assemblyai" | "google";
+interface AudioPricing {
+    /** How the provider charges (drives the cost dispatcher math). */
+    billingUnit: AudioBillingUnit;
+    /** Production cost in USD per `billingUnit`. */
+    baseCost: number;
+    /**
+     * @deprecated Credits derived at call time via
+     * `computeCenticredits({ baseCostUsd: baseCost, category: "audio" })`.
+     * Kept optional for back-compat with existing entries.
+     */
+    creditCost?: number;
+    /** Bypass markup formula and charge exactly this many credits per billingUnit. */
+    overrideCreditCost?: number;
+}
+
+interface AudioModelDefinition {
+    id: string;
+    name: string;
+    /** Provider-facing identifier (e.g. `eleven_multilingual_v2`, `nova-3`). */
+    providerId: string;
+    provider: AudioProvider;
+    capabilities: AudioCapabilities;
+    pricing: AudioPricing;
+    description: string;
+    agentVisible: boolean;
+}
+declare const AUDIO_MODEL_CATALOG: Record<string, AudioModelDefinition>;
+declare const AUDIO_MODEL_IDS: [string, ...string[]];
+declare const AGENT_AUDIO_MODEL_IDS: [string, ...string[]];
+declare const AGENT_TTS_MODEL_IDS: [string, ...string[]];
+declare const AGENT_STT_MODEL_IDS: [string, ...string[]];
+/** All catalog s2s entry ids (internal billing ids). */
+declare const S2S_MODEL_IDS: string[];
+/** Provider model strings the Gemini Live adapter accepts server-side,
+ *  derived from the catalog's google/s2s entries. */
+declare const GEMINI_LIVE_MODEL_IDS: string[];
+/** Default Gemini Live model — the low-latency flash tier (`google/gemini-live`). */
+declare const DEFAULT_GEMINI_LIVE_MODEL: string;
+/** True when `id` is one of the accepted Gemini Live provider model strings. */
+declare function isAcceptedGeminiLiveModel(id: string): boolean;
+/** Generate a markdown table of agent-visible TTS / STT models for prompt blocks */
+declare function generateAudioModelTable(modality?: AudioModality): string;
+
+export { AGENT_AUDIO_MODEL_IDS, AGENT_STT_MODEL_IDS, AGENT_TTS_MODEL_IDS, AUDIO_MODEL_CATALOG, AUDIO_MODEL_IDS, type AudioBillingUnit, type AudioModality, type AudioModelDefinition, type AudioProvider, DEFAULT_GEMINI_LIVE_MODEL, GEMINI_LIVE_MODEL_IDS, S2S_MODEL_IDS, generateAudioModelTable, isAcceptedGeminiLiveModel };

package/dist/audio/index.mjs

@@ -0,0 +1,3 @@
+export { AGENT_AUDIO_MODEL_IDS, AGENT_STT_MODEL_IDS, AGENT_TTS_MODEL_IDS, AUDIO_MODEL_CATALOG, AUDIO_MODEL_IDS, DEFAULT_GEMINI_LIVE_MODEL, GEMINI_LIVE_MODEL_IDS, S2S_MODEL_IDS, generateAudioModelTable, isAcceptedGeminiLiveModel } from '../chunk-WRUWNKDB.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/audio/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/audio-BzVF_wke.d.ts

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+
+declare const AudioCapabilitiesSchema: z.ZodObject<{
+    tts: z.ZodOptional<z.ZodBoolean>;
+    stt: z.ZodOptional<z.ZodBoolean>;
+    s2s: z.ZodOptional<z.ZodBoolean>;
+    languages: z.ZodArray<z.ZodString>;
+    voiceCloning: z.ZodOptional<z.ZodBoolean>;
+    streaming: z.ZodOptional<z.ZodBoolean>;
+    timestamps: z.ZodOptional<z.ZodBoolean>;
+    diarization: z.ZodOptional<z.ZodBoolean>;
+    languageDetection: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type AudioCapabilities = z.infer<typeof AudioCapabilitiesSchema>;
+declare const AudioPricingSchema: z.ZodObject<{
+    billingUnit: z.ZodEnum<{
+        per_second: "per_second";
+        per_character: "per_character";
+    }>;
+    baseCost: z.ZodNumber;
+    baseCostUnit: z.ZodOptional<z.ZodString>;
+    creditCost: z.ZodOptional<z.ZodNumber>;
+    overrideCreditCost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type AudioPricing = z.infer<typeof AudioPricingSchema>;
+declare const AudioEntrySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"audio">;
+    capabilities: z.ZodObject<{
+        tts: z.ZodOptional<z.ZodBoolean>;
+        stt: z.ZodOptional<z.ZodBoolean>;
+        s2s: z.ZodOptional<z.ZodBoolean>;
+        languages: z.ZodArray<z.ZodString>;
+        voiceCloning: z.ZodOptional<z.ZodBoolean>;
+        streaming: z.ZodOptional<z.ZodBoolean>;
+        timestamps: z.ZodOptional<z.ZodBoolean>;
+        diarization: z.ZodOptional<z.ZodBoolean>;
+        languageDetection: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    pricing: z.ZodObject<{
+        billingUnit: z.ZodEnum<{
+            per_second: "per_second";
+            per_character: "per_character";
+        }>;
+        baseCost: z.ZodNumber;
+        baseCostUnit: z.ZodOptional<z.ZodString>;
+        creditCost: z.ZodOptional<z.ZodNumber>;
+        overrideCreditCost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    supportedLocales: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    provider: z.ZodEnum<{
+        anthropic: "anthropic";
+        assemblyai: "assemblyai";
+        deepgram: "deepgram";
+        elevenlabs: "elevenlabs";
+        "gemini-live": "gemini-live";
+        google: "google";
+        minimax: "minimax";
+        mistral: "mistral";
+        moonshot: "moonshot";
+        openai: "openai";
+        "openai-realtime": "openai-realtime";
+        openrouter: "openrouter";
+        replicate: "replicate";
+    }>;
+    providerId: z.ZodString;
+    agentVisible: z.ZodDefault<z.ZodBoolean>;
+    lifecycle: z.ZodDefault<z.ZodEnum<{
+        stable: "stable";
+        preview: "preview";
+        deprecated: "deprecated";
+    }>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    catalogPriceTier: z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        mid: "mid";
+        high: "high";
+        premium: "premium";
+    }>>;
+    nsfwPolicy: z.ZodDefault<z.ZodEnum<{
+        filtered: "filtered";
+        permissive: "permissive";
+        strict: "strict";
+    }>>;
+    regions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type AudioEntry = z.infer<typeof AudioEntrySchema>;
+
+export { type AudioCapabilities as A, AudioCapabilitiesSchema as a, type AudioEntry as b, AudioEntrySchema as c, type AudioPricing as d, AudioPricingSchema as e };

package/dist/base-BNHcMifc.d.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+
+/**
+ * Shared schema fragments for every model catalog entry.
+ *
+ * `baseEntryShape` is spread into per-kind schemas so each kind stays a
+ * plain `z.object` — required by `z.discriminatedUnion`.
+ *
+ * Mirrors the pattern in
+ * `packages/agencies/registry-client/src/types.ts` (`basePayloadShape`).
+ */
+declare const ModelKindSchema: z.ZodEnum<{
+    llm: "llm";
+    image: "image";
+    video: "video";
+    audio: "audio";
+}>;
+type ModelKind = z.infer<typeof ModelKindSchema>;
+declare const LifecycleSchema: z.ZodEnum<{
+    stable: "stable";
+    preview: "preview";
+    deprecated: "deprecated";
+}>;
+type Lifecycle = z.infer<typeof LifecycleSchema>;
+/**
+ * `catalogPriceTier` — the model's intrinsic cost bucket. Distinct from
+ * `subscriptionPlanTier` (the user's billing level) and `modelPreset`
+ * (an app's per-conversation UX picker). Always qualify when discussing
+ * tiers — bare `priceTier` / `tier` is ambiguous in this codebase.
+ */
+declare const CatalogPriceTierSchema: z.ZodEnum<{
+    low: "low";
+    mid: "mid";
+    high: "high";
+    premium: "premium";
+}>;
+type CatalogPriceTier = z.infer<typeof CatalogPriceTierSchema>;
+declare const NsfwPolicySchema: z.ZodEnum<{
+    filtered: "filtered";
+    permissive: "permissive";
+    strict: "strict";
+}>;
+type NsfwPolicy = z.infer<typeof NsfwPolicySchema>;
+/**
+ * Canonical model-provider registry — the single source of truth for the
+ * `provider` field on every catalog entry. Adding a model on a new
+ * provider means adding it here first, so a typo or an un-onboarded
+ * provider is a validation/build error rather than a silently-broken
+ * entry. `CatalogVoiceProviderSchema` is the voice-callable subset.
+ */
+declare const CatalogProviderSchema: z.ZodEnum<{
+    anthropic: "anthropic";
+    assemblyai: "assemblyai";
+    deepgram: "deepgram";
+    elevenlabs: "elevenlabs";
+    "gemini-live": "gemini-live";
+    google: "google";
+    minimax: "minimax";
+    mistral: "mistral";
+    moonshot: "moonshot";
+    openai: "openai";
+    "openai-realtime": "openai-realtime";
+    openrouter: "openrouter";
+    replicate: "replicate";
+}>;
+type CatalogProvider = z.infer<typeof CatalogProviderSchema>;
+declare const baseEntryShape: {
+    readonly id: z.ZodString;
+    readonly name: z.ZodString;
+    readonly description: z.ZodDefault<z.ZodString>;
+    readonly provider: z.ZodEnum<{
+        anthropic: "anthropic";
+        assemblyai: "assemblyai";
+        deepgram: "deepgram";
+        elevenlabs: "elevenlabs";
+        "gemini-live": "gemini-live";
+        google: "google";
+        minimax: "minimax";
+        mistral: "mistral";
+        moonshot: "moonshot";
+        openai: "openai";
+        "openai-realtime": "openai-realtime";
+        openrouter: "openrouter";
+        replicate: "replicate";
+    }>;
+    readonly providerId: z.ZodString;
+    readonly agentVisible: z.ZodDefault<z.ZodBoolean>;
+    readonly lifecycle: z.ZodDefault<z.ZodEnum<{
+        stable: "stable";
+        preview: "preview";
+        deprecated: "deprecated";
+    }>>;
+    readonly tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    readonly catalogPriceTier: z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        mid: "mid";
+        high: "high";
+        premium: "premium";
+    }>>;
+    readonly nsfwPolicy: z.ZodDefault<z.ZodEnum<{
+        filtered: "filtered";
+        permissive: "permissive";
+        strict: "strict";
+    }>>;
+    readonly regions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    readonly aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+};
+
+export { type CatalogProvider as C, type Lifecycle as L, type ModelKind as M, type NsfwPolicy as N, type CatalogPriceTier as a, CatalogPriceTierSchema as b, CatalogProviderSchema as c, LifecycleSchema as d, ModelKindSchema as e, NsfwPolicySchema as f, baseEntryShape as g };

package/dist/byok/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * BYOK (Bring Your Own Keys) policy.
+ *
+ * Single pure function — `shouldDebit` — that decides whether a model
+ * run should debit user credits or be recorded as a non-debiting shadow
+ * usage row. Truth table mirrors the open-coded behavior at
+ * the app orchestrator
+ * (commit `eeb1acdc`):
+ *
+ *   byokActive | hasConnector | result
+ *   -----------|--------------|----------------------------------
+ *   true       | true         | { debit: false, shadow: true }
+ *   true       | false        | { debit: true,  shadow: false }   ← BYOK flag set but no key — fall back to credits
+ *   false      | true         | { debit: true,  shadow: false }
+ *   false      | false        | { debit: true,  shadow: false }
+ *
+ * No DB calls, no I/O. Caller (orchestrator, MCP server) is responsible
+ * for resolving `byokActive` and `hasConnector` upstream.
+ */
+interface ShouldDebitInput {
+    modelId: string;
+    byokActive: boolean;
+    hasConnector: boolean;
+}
+interface ShouldDebitDecision {
+    debit: boolean;
+    shadow: boolean;
+    /** Stable string for logs/metrics; not user-facing copy. */
+    reason: "byok-active-with-connector" | "byok-flag-but-no-connector" | "non-byok";
+}
+declare function shouldDebit(input: ShouldDebitInput): ShouldDebitDecision;
+
+export { type ShouldDebitDecision, type ShouldDebitInput, shouldDebit };

package/dist/byok/index.mjs

@@ -0,0 +1,3 @@
+export { shouldDebit } from '../chunk-XFDXTFV3.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/byok/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}