@agentskit/adapters 0.12.2 → 0.13.0

package/dist/catalog/index.d.cts

@@ -0,0 +1,205 @@
+import { JSONSchema7 } from 'json-schema';
+import { AdapterFactory } from '@agentskit/core';
+import { R as RetryOptions } from '../utils-ddwu4MN4.cjs';
+
+/**
+ * AgentsKit provider/model catalog — normalized metadata adapted from the
+ * `models.dev` data source into our own schema. This is the canonical shape;
+ * `models.dev` is an input, never a runtime dependency (see {@link CatalogSnapshot.source}).
+ */
+/** Input/output modalities a model accepts/produces. */
+interface CatalogModalities {
+    input: string[];
+    output: string[];
+}
+/**
+ * Per-token cost in USD per 1M tokens. Advisory metadata only — it is cached at
+ * snapshot time and drifts between regenerations, so never treat it as a hard
+ * contract for billing.
+ */
+interface CatalogModelCost {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** Context / output token ceilings. */
+interface CatalogModelLimit {
+    context?: number;
+    output?: number;
+}
+/** A single model entry within a provider. */
+interface CatalogModel {
+    id: string;
+    name: string;
+    family?: string;
+    limit?: CatalogModelLimit;
+    cost?: CatalogModelCost;
+    modalities?: CatalogModalities;
+    /** Capability flags — consult these instead of assuming "openai-compatible = works". */
+    toolCall: boolean;
+    structuredOutput: boolean;
+    reasoning: boolean;
+    attachment: boolean;
+    openWeights: boolean;
+    /** ISO-ish knowledge cutoff (e.g. "2024-05"). */
+    knowledge?: string;
+    releaseDate?: string;
+    lastUpdated?: string;
+    deprecated?: boolean;
+}
+/** A provider and its models. */
+interface CatalogProvider {
+    id: string;
+    name: string;
+    /** Environment variable names that hold this provider's API key. */
+    env: string[];
+    /** Default API base URL (when `models.dev` records one). */
+    baseUrl?: string;
+    doc?: string;
+    /**
+     * True when the provider exposes an OpenAI-compatible transport and can be
+     * dispatched via the native generic adapter rather than a bespoke factory.
+     */
+    openaiCompatible: boolean;
+    models: CatalogModel[];
+}
+/** Provenance + freshness metadata for a generated snapshot. */
+interface CatalogSource {
+    name: 'models.dev';
+    url: string;
+    /** Pinned upstream version/commit the snapshot was generated from. */
+    version: string;
+}
+/** The committed, schema-validated catalog artifact loaded at runtime. */
+interface CatalogSnapshot {
+    schemaVersion: 1;
+    /** ISO timestamp the snapshot was generated (set by the sync tool). */
+    generatedAt: string;
+    source: CatalogSource;
+    providers: CatalogProvider[];
+}
+
+/**
+ * Canonical JSON Schema for the provider/model catalog snapshot. Public export.
+ *
+ * JSON Schema is the single source of truth for contracts across AgentsKit
+ * (core stays zero-dep; Zod is opt-in convenience only, never canonical). The
+ * snapshot is validated against this schema at build time via the opt-in Ajv
+ * path (`@agentskit/validation`), not at runtime.
+ */
+declare const catalogSnapshotSchema: JSONSchema7;
+
+/**
+ * The committed catalog snapshot. Imported as data — the runtime never fetches
+ * `models.dev`. Heavy (thousands of models), so this module is only reachable
+ * via the `@agentskit/adapters/catalog` subpath, keeping the main bundle lean.
+ */
+declare const catalog: CatalogSnapshot;
+/** All providers in the snapshot. */
+declare function listProviders(): CatalogProvider[];
+/** Look up a provider by id (e.g. "openai", "deepseek"). */
+declare function getProvider(id: string): CatalogProvider | undefined;
+/** Look up a model within a provider. */
+declare function getModel(providerId: string, modelId: string): CatalogModel | undefined;
+/** Providers exposing an OpenAI-compatible transport (dispatchable natively). */
+declare function listOpenAICompatibleProviders(): CatalogProvider[];
+/** Snapshot freshness/provenance — surface this so consumers can reason about staleness. */
+declare function catalogSource(): CatalogSnapshot['source'] & {
+    generatedAt: string;
+};
+
+/**
+ * Local policy layer so consumers can constrain the catalog without forking it
+ * (enterprise-approved providers/models, disabled providers, etc.).
+ *
+ * Precedence (most → least restrictive):
+ *  1. `disabledProviders` always removes a provider, even if allow-listed.
+ *  2. `allowedProviders`, when set, keeps only listed providers.
+ *  3. `allowedModels[providerId]`, when set, keeps only listed models for that provider.
+ */
+interface CatalogOverrides {
+    /** When set, only these provider ids survive. */
+    allowedProviders?: string[];
+    /** Always removed, takes precedence over `allowedProviders`. */
+    disabledProviders?: string[];
+    /** Per-provider model allow-list. Absent provider key = no model restriction. */
+    allowedModels?: Record<string, string[]>;
+}
+/** Return a new snapshot with policy applied. The input snapshot is not mutated. */
+declare function applyOverrides(snapshot: CatalogSnapshot, overrides: CatalogOverrides): CatalogSnapshot;
+
+interface CatalogDispatchConfig {
+    provider: string;
+    model: string;
+    apiKey: string;
+    /** Override the catalog base URL (e.g. proxy / self-hosted gateway). */
+    baseUrl?: string;
+    retry?: RetryOptions;
+}
+declare class CatalogDispatchError extends Error {
+    readonly code: 'UNKNOWN_PROVIDER' | 'NOT_OPENAI_COMPATIBLE' | 'NO_BASE_URL';
+    constructor(message: string, code: 'UNKNOWN_PROVIDER' | 'NOT_OPENAI_COMPATIBLE' | 'NO_BASE_URL');
+}
+/**
+ * Build a native OpenAI-compatible adapter for a catalog provider/model. This is
+ * the generic dispatch path: any provider `models.dev` marks OpenAI-compatible
+ * lands here without bespoke per-provider code.
+ *
+ * First-class providers (anthropic/openai/gemini/ollama) keep their dedicated
+ * factories and are authoritative — do not route them through here.
+ */
+declare function dispatchFromCatalog(config: CatalogDispatchConfig): AdapterFactory;
+
+/**
+ * Catalog-backed providers that ship dedicated first-class factories here. These
+ * are authoritative and intentionally NOT dispatched via the generic catalog path.
+ *
+ * `ollama` is also first-class but is deliberately excluded: it is local-only and
+ * absent from `models.dev`, so it must not be flagged as "missing from catalog".
+ */
+declare const FIRST_CLASS_PROVIDERS: readonly ["anthropic", "openai", "google"];
+interface CatalogDriftReport {
+    /** Catalog providers that are neither first-class nor OpenAI-compatible — undispatchable. */
+    undispatchable: string[];
+    /** First-class provider ids with no matching catalog entry (rename/removal upstream). */
+    missingFromCatalog: string[];
+    /** True when every catalog provider can be dispatched and no first-class entry is missing. */
+    ok: boolean;
+}
+/**
+ * Drift check: every snapshot provider must map to a dispatchable adapter (first-class
+ * factory or native OpenAI-compatible) or be flagged. Run in CI so a regenerated
+ * snapshot that introduces an unroutable provider fails loudly instead of shipping silently.
+ */
+declare function detectCatalogDrift(providers?: CatalogProvider[]): CatalogDriftReport;
+
+interface ResolveCostOptions {
+    /**
+     * Opt in to a live fetch. Default `false` keeps the runtime offline and
+     * deterministic (the issue's "no runtime fetch" default). When `true`, a live
+     * lookup is attempted and the cached snapshot is the guaranteed fallback.
+     */
+    live?: boolean;
+    /** Abort the live fetch after this many ms (default 3000). */
+    timeoutMs?: number;
+    /** Injectable fetch for testing. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+interface ResolvedCost {
+    cost?: CatalogModelCost;
+    /** Where the returned cost came from. */
+    source: 'live' | 'cache';
+    /** True when served from cache and the snapshot is older than 30 days. */
+    stale: boolean;
+}
+/** Cached cost only — synchronous, never touches the network. */
+declare function getCachedCost(providerId: string, modelId: string): CatalogModelCost | undefined;
+/**
+ * Resolve a model's cost. Cache-only by default; with `{ live: true }` it tries
+ * the live source first and falls back to the cached snapshot on any failure
+ * (timeout, network, missing entry). Never throws on a network problem.
+ */
+declare function resolveCost(providerId: string, modelId: string, options?: ResolveCostOptions): Promise<ResolvedCost>;
+
+export { type CatalogDispatchConfig, CatalogDispatchError, type CatalogDriftReport, type CatalogModalities, type CatalogModel, type CatalogModelCost, type CatalogModelLimit, type CatalogOverrides, type CatalogProvider, type CatalogSnapshot, type CatalogSource, FIRST_CLASS_PROVIDERS, type ResolveCostOptions, type ResolvedCost, applyOverrides, catalog, catalogSnapshotSchema, catalogSource, detectCatalogDrift, dispatchFromCatalog, getCachedCost, getModel, getProvider, listOpenAICompatibleProviders, listProviders, resolveCost };

package/dist/catalog/index.d.ts

@@ -0,0 +1,205 @@
+import { JSONSchema7 } from 'json-schema';
+import { AdapterFactory } from '@agentskit/core';
+import { R as RetryOptions } from '../utils-ddwu4MN4.js';
+
+/**
+ * AgentsKit provider/model catalog — normalized metadata adapted from the
+ * `models.dev` data source into our own schema. This is the canonical shape;
+ * `models.dev` is an input, never a runtime dependency (see {@link CatalogSnapshot.source}).
+ */
+/** Input/output modalities a model accepts/produces. */
+interface CatalogModalities {
+    input: string[];
+    output: string[];
+}
+/**
+ * Per-token cost in USD per 1M tokens. Advisory metadata only — it is cached at
+ * snapshot time and drifts between regenerations, so never treat it as a hard
+ * contract for billing.
+ */
+interface CatalogModelCost {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** Context / output token ceilings. */
+interface CatalogModelLimit {
+    context?: number;
+    output?: number;
+}
+/** A single model entry within a provider. */
+interface CatalogModel {
+    id: string;
+    name: string;
+    family?: string;
+    limit?: CatalogModelLimit;
+    cost?: CatalogModelCost;
+    modalities?: CatalogModalities;
+    /** Capability flags — consult these instead of assuming "openai-compatible = works". */
+    toolCall: boolean;
+    structuredOutput: boolean;
+    reasoning: boolean;
+    attachment: boolean;
+    openWeights: boolean;
+    /** ISO-ish knowledge cutoff (e.g. "2024-05"). */
+    knowledge?: string;
+    releaseDate?: string;
+    lastUpdated?: string;
+    deprecated?: boolean;
+}
+/** A provider and its models. */
+interface CatalogProvider {
+    id: string;
+    name: string;
+    /** Environment variable names that hold this provider's API key. */
+    env: string[];
+    /** Default API base URL (when `models.dev` records one). */
+    baseUrl?: string;
+    doc?: string;
+    /**
+     * True when the provider exposes an OpenAI-compatible transport and can be
+     * dispatched via the native generic adapter rather than a bespoke factory.
+     */
+    openaiCompatible: boolean;
+    models: CatalogModel[];
+}
+/** Provenance + freshness metadata for a generated snapshot. */
+interface CatalogSource {
+    name: 'models.dev';
+    url: string;
+    /** Pinned upstream version/commit the snapshot was generated from. */
+    version: string;
+}
+/** The committed, schema-validated catalog artifact loaded at runtime. */
+interface CatalogSnapshot {
+    schemaVersion: 1;
+    /** ISO timestamp the snapshot was generated (set by the sync tool). */
+    generatedAt: string;
+    source: CatalogSource;
+    providers: CatalogProvider[];
+}
+
+/**
+ * Canonical JSON Schema for the provider/model catalog snapshot. Public export.
+ *
+ * JSON Schema is the single source of truth for contracts across AgentsKit
+ * (core stays zero-dep; Zod is opt-in convenience only, never canonical). The
+ * snapshot is validated against this schema at build time via the opt-in Ajv
+ * path (`@agentskit/validation`), not at runtime.
+ */
+declare const catalogSnapshotSchema: JSONSchema7;
+
+/**
+ * The committed catalog snapshot. Imported as data — the runtime never fetches
+ * `models.dev`. Heavy (thousands of models), so this module is only reachable
+ * via the `@agentskit/adapters/catalog` subpath, keeping the main bundle lean.
+ */
+declare const catalog: CatalogSnapshot;
+/** All providers in the snapshot. */
+declare function listProviders(): CatalogProvider[];
+/** Look up a provider by id (e.g. "openai", "deepseek"). */
+declare function getProvider(id: string): CatalogProvider | undefined;
+/** Look up a model within a provider. */
+declare function getModel(providerId: string, modelId: string): CatalogModel | undefined;
+/** Providers exposing an OpenAI-compatible transport (dispatchable natively). */
+declare function listOpenAICompatibleProviders(): CatalogProvider[];
+/** Snapshot freshness/provenance — surface this so consumers can reason about staleness. */
+declare function catalogSource(): CatalogSnapshot['source'] & {
+    generatedAt: string;
+};
+
+/**
+ * Local policy layer so consumers can constrain the catalog without forking it
+ * (enterprise-approved providers/models, disabled providers, etc.).
+ *
+ * Precedence (most → least restrictive):
+ *  1. `disabledProviders` always removes a provider, even if allow-listed.
+ *  2. `allowedProviders`, when set, keeps only listed providers.
+ *  3. `allowedModels[providerId]`, when set, keeps only listed models for that provider.
+ */
+interface CatalogOverrides {
+    /** When set, only these provider ids survive. */
+    allowedProviders?: string[];
+    /** Always removed, takes precedence over `allowedProviders`. */
+    disabledProviders?: string[];
+    /** Per-provider model allow-list. Absent provider key = no model restriction. */
+    allowedModels?: Record<string, string[]>;
+}
+/** Return a new snapshot with policy applied. The input snapshot is not mutated. */
+declare function applyOverrides(snapshot: CatalogSnapshot, overrides: CatalogOverrides): CatalogSnapshot;
+
+interface CatalogDispatchConfig {
+    provider: string;
+    model: string;
+    apiKey: string;
+    /** Override the catalog base URL (e.g. proxy / self-hosted gateway). */
+    baseUrl?: string;
+    retry?: RetryOptions;
+}
+declare class CatalogDispatchError extends Error {
+    readonly code: 'UNKNOWN_PROVIDER' | 'NOT_OPENAI_COMPATIBLE' | 'NO_BASE_URL';
+    constructor(message: string, code: 'UNKNOWN_PROVIDER' | 'NOT_OPENAI_COMPATIBLE' | 'NO_BASE_URL');
+}
+/**
+ * Build a native OpenAI-compatible adapter for a catalog provider/model. This is
+ * the generic dispatch path: any provider `models.dev` marks OpenAI-compatible
+ * lands here without bespoke per-provider code.
+ *
+ * First-class providers (anthropic/openai/gemini/ollama) keep their dedicated
+ * factories and are authoritative — do not route them through here.
+ */
+declare function dispatchFromCatalog(config: CatalogDispatchConfig): AdapterFactory;
+
+/**
+ * Catalog-backed providers that ship dedicated first-class factories here. These
+ * are authoritative and intentionally NOT dispatched via the generic catalog path.
+ *
+ * `ollama` is also first-class but is deliberately excluded: it is local-only and
+ * absent from `models.dev`, so it must not be flagged as "missing from catalog".
+ */
+declare const FIRST_CLASS_PROVIDERS: readonly ["anthropic", "openai", "google"];
+interface CatalogDriftReport {
+    /** Catalog providers that are neither first-class nor OpenAI-compatible — undispatchable. */
+    undispatchable: string[];
+    /** First-class provider ids with no matching catalog entry (rename/removal upstream). */
+    missingFromCatalog: string[];
+    /** True when every catalog provider can be dispatched and no first-class entry is missing. */
+    ok: boolean;
+}
+/**
+ * Drift check: every snapshot provider must map to a dispatchable adapter (first-class
+ * factory or native OpenAI-compatible) or be flagged. Run in CI so a regenerated
+ * snapshot that introduces an unroutable provider fails loudly instead of shipping silently.
+ */
+declare function detectCatalogDrift(providers?: CatalogProvider[]): CatalogDriftReport;
+
+interface ResolveCostOptions {
+    /**
+     * Opt in to a live fetch. Default `false` keeps the runtime offline and
+     * deterministic (the issue's "no runtime fetch" default). When `true`, a live
+     * lookup is attempted and the cached snapshot is the guaranteed fallback.
+     */
+    live?: boolean;
+    /** Abort the live fetch after this many ms (default 3000). */
+    timeoutMs?: number;
+    /** Injectable fetch for testing. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+interface ResolvedCost {
+    cost?: CatalogModelCost;
+    /** Where the returned cost came from. */
+    source: 'live' | 'cache';
+    /** True when served from cache and the snapshot is older than 30 days. */
+    stale: boolean;
+}
+/** Cached cost only — synchronous, never touches the network. */
+declare function getCachedCost(providerId: string, modelId: string): CatalogModelCost | undefined;
+/**
+ * Resolve a model's cost. Cache-only by default; with `{ live: true }` it tries
+ * the live source first and falls back to the cached snapshot on any failure
+ * (timeout, network, missing entry). Never throws on a network problem.
+ */
+declare function resolveCost(providerId: string, modelId: string, options?: ResolveCostOptions): Promise<ResolvedCost>;
+
+export { type CatalogDispatchConfig, CatalogDispatchError, type CatalogDriftReport, type CatalogModalities, type CatalogModel, type CatalogModelCost, type CatalogModelLimit, type CatalogOverrides, type CatalogProvider, type CatalogSnapshot, type CatalogSource, FIRST_CLASS_PROVIDERS, type ResolveCostOptions, type ResolvedCost, applyOverrides, catalog, catalogSnapshotSchema, catalogSource, detectCatalogDrift, dispatchFromCatalog, getCachedCost, getModel, getProvider, listOpenAICompatibleProviders, listProviders, resolveCost };