@linxiraos/pi-catalog 1.0.0

package/dist/types/model-manager.d.ts

@@ -0,0 +1,77 @@
+import type { Api, Model, ModelSpec, Provider } from "./types.js";
+/**
+ * Controls when dynamic endpoint models should be fetched.
+ */
+export type ModelRefreshStrategy = "online" | "offline" | "online-if-uncached";
+/**
+ * Hook for loading and mapping stencil.so fallback data into canonical model objects.
+ */
+export interface ModelsDevFallback<TApi extends Api = Api, TPayload = unknown> {
+    /** Fetches raw fallback payload (for example from stencil.so). */
+    fetch(): Promise<TPayload>;
+    /** Maps payload into provider models. */
+    map(payload: TPayload, providerId: Provider): readonly ModelSpec<TApi>[];
+}
+/**
+ * Configuration for provider model resolution.
+ */
+export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload = unknown> {
+    /** Provider id used for static lookup and cache namespacing. */
+    providerId: Provider;
+    /** Optional static list override. When omitted, bundled models.json is used. */
+    staticModels?: readonly ModelSpec<TApi>[];
+    /** Optional override for the cache database path. Default: <agent-dir>/models.db. */
+    cacheDbPath?: string;
+    /** Optional provider id override for cache namespacing. Defaults to providerId. */
+    cacheProviderId?: string;
+    /** Maximum cache age in milliseconds before considered stale. Default: 2h (`DEFAULT_CACHE_TTL_MS`). */
+    cacheTtlMs?: number;
+    /** When true, a successful dynamic fetch is the complete provider catalog and prunes static-only models. */
+    dynamicModelsAuthoritative?: boolean;
+    /** Cached model ids whose presence forces refresh when the static or migration-policy fingerprint changes. */
+    dropCachedModelIdsOnStaticMismatch?: readonly string[];
+    /**
+     * Trusted, provider-wide request headers (compile-time constants, never
+     * credentials) that the cache may restore by value for any model whose live
+     * headers matched them at write time. Lets header-bearing dynamic models
+     * without a bundled static entry survive offline reads instead of being
+     * dropped as unrestorable (e.g. GitHub Copilot's User-Agent + API version).
+     */
+    restorableHeaderFallback?: Record<string, string>;
+    /** Optional dynamic endpoint fetcher. */
+    fetchDynamicModels?: () => Promise<readonly ModelSpec<TApi>[] | null>;
+    /** Optional stencil.so fallback hook. */
+    modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Resolution result.
+ *
+ * `stale` is false when the resolved catalog is authoritative for the selected provider:
+ * - a dynamic endpoint fetch succeeded in this call (an empty catalog is still
+ *   authoritative for the cycle, so downstream pruning of removed models runs),
+ * - a still-fresh authoritative cache was reused in `online-if-uncached` mode, or
+ * - the provider has no dynamic fetcher configured.
+ */
+export interface ModelResolutionResult<TApi extends Api = Api> {
+    models: Model<TApi>[];
+    stale: boolean;
+}
+/**
+ * Stateful facade over provider model resolution.
+ */
+export interface ModelManager<TApi extends Api = Api> {
+    refresh(strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;
+}
+/**
+ * Creates a reusable provider model manager.
+ */
+export declare function createModelManager<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>): ModelManager<TApi>;
+/**
+ * Resolves provider models with source precedence:
+ * static -> stencil.so -> cache -> dynamic.
+ *
+ * Later sources override earlier ones by model id.
+ */
+export declare function resolveProviderModels<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>, strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;

package/dist/types/model-thinking.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Thinking metadata: build-time derivation and runtime field-read helpers.
+ *
+ * Derivation (`resolveModelThinking`) runs exactly once per model — from
+ * `buildModel` for dynamic specs and from the catalog generator for bundled
+ * entries. Everything below the "runtime helpers" divider reads baked fields
+ * only: no id parsing, no host matching, no compat detection per request.
+ */
+import { Effort } from "./effort.js";
+import type { Api, CompatOf, Model, ModelSpec, ThinkingConfig } from "./types.js";
+/**
+ * Runtime helpers read baked metadata only, so they accept both pre-build
+ * specs and built models.
+ */
+type ApiModel<TApi extends Api = Api> = ModelSpec<TApi> | Model<TApi>;
+/**
+ * Resolve the canonical thinking metadata for a spec. Called exactly once per
+ * model by `buildModel`, after compat resolution.
+ *
+ * - Non-reasoning models never carry thinking.
+ * - Models that reason natively but reject the wire effort param
+ *   (`compat.supportsReasoningEffort: false` on openai-responses*) carry no
+ *   thinking either: `reasoning: true, thinking: undefined` IS the encoding
+ *   for "thinks, but exposes no control surface".
+ * - Explicit spec thinking (generator-baked or user-authored) owns the
+ *   capability surface (`mode`, `efforts`, `defaultLevel`); the wire facts
+ *   (`effortMap`, `supportsDisplay`) are backfilled from identity when not
+ *   explicitly set, so configs never need to know provider wire tier tables.
+ * - Sparse specs go through full inference.
+ */
+export declare function resolveModelThinking<TApi extends Api>(spec: ModelSpec<TApi>, compat: CompatOf<TApi>): ThinkingConfig | undefined;
+/** Derive thinking from identity + resolved compat, ignoring any baked value. Generator-side entry. */
+export declare function deriveThinking<TApi extends Api>(spec: ModelSpec<TApi>, compat: CompatOf<TApi>): ThinkingConfig;
+/**
+ * Returns the supported thinking efforts declared on the model metadata.
+ * Empty for non-reasoning models and for reasoning models without a
+ * controllable effort surface (`thinking: undefined`).
+ */
+export declare function getSupportedEfforts<TApi extends Api>(model: ApiModel<TApi>): readonly Effort[];
+/**
+ * Clamps a requested thinking level against explicit model metadata.
+ *
+ * Non-reasoning models always resolve to `undefined`.
+ */
+export declare function clampThinkingLevelForModel<TApi extends Api>(model: ApiModel<TApi> | undefined, requested: Effort | undefined): Effort | undefined;
+export declare function requireSupportedEffort<TApi extends Api>(model: ApiModel<TApi>, effort: Effort): Effort;
+/** Maps a normalized thinking effort to Google's `thinkingLevel` enum values. */
+export declare function mapEffortToGoogleThinkingLevel(effort: Effort): "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+/**
+ * Maps a normalized thinking effort to Anthropic adaptive effort values via
+ * the model's baked `thinking.effortMap` (identity for unmapped efforts).
+ */
+export declare function mapEffortToAnthropicAdaptiveEffort<TApi extends Api>(model: ApiModel<TApi>, effort: Effort): "low" | "medium" | "high" | "xhigh" | "max" | "adaptive";
+/**
+ * Resolves the upstream wire model id for a request at the given effort
+ * (`undefined` = thinking off). Collapsed effort-tier variants route through
+ * `thinking.effortRouting`; everything else falls back to
+ * `requestModelId ?? id`.
+ */
+export declare function resolveWireModelId<TApi extends Api>(model: ApiModel<TApi>, effort: Effort | undefined): string;
+/**
+ * Lowest supported effort in canonical order — the clamp target for
+ * thinking-off requests on `thinking.requiresEffort` models.
+ */
+export declare function minimumSupportedEffort<TApi extends Api>(model: ApiModel<TApi>): Effort | undefined;
+export {};

package/dist/types/models.d.ts

@@ -0,0 +1,12 @@
+import MODELS from "./models.json";
+import type { Api, KnownProvider, Model, Usage } from "./types.js";
+export type GeneratedProvider = keyof typeof MODELS;
+export declare function getBundledModel<TApi extends Api = Api>(provider: GeneratedProvider, modelId: string): Model<TApi>;
+export declare function getBundledProviders(): KnownProvider[];
+export declare function getBundledModels(provider: GeneratedProvider): Model<Api>[];
+export declare function calculateCost<TApi extends Api>(model: Model<TApi>, usage: Usage): Usage["cost"];
+/**
+ * Check if two models are equal by comparing both their id and provider.
+ * Returns false if either model is null or undefined.
+ */
+export declare function modelsAreEqual<TApi extends Api>(a: Model<TApi> | null | undefined, b: Model<TApi> | null | undefined): boolean;

package/dist/types/provider-models/bundled-references.d.ts

@@ -0,0 +1,13 @@
+import { getBundledModels } from "../models.js";
+import type { Api, Model, ModelSpec } from "../types.js";
+/**
+ * Project a built `Model` back to spec stage: `compat` becomes the verbatim
+ * sparse override record (`compatConfig`), never the resolved view. Discovery
+ * mappers spread these references into the specs they hand to the model
+ * manager, which rebuilds via `buildModel`.
+ */
+export declare function toModelSpec<TApi extends Api>(model: Model<TApi>): ModelSpec<TApi>;
+export declare function createBundledReferenceMap<TApi extends Api>(provider: Parameters<typeof getBundledModels>[0]): Map<string, ModelSpec<TApi>>;
+type ProviderReferenceSource<TApi extends Api> = Map<string, ModelSpec<TApi>> | (() => Map<string, ModelSpec<TApi>>);
+export declare function createReferenceResolver<TApi extends Api>(providerReferenceSource: ProviderReferenceSource<TApi>): (modelId: string) => ModelSpec<TApi> | undefined;
+export {};

package/dist/types/provider-models/cache-provider-id.d.ts

@@ -0,0 +1,9 @@
+export interface ModelCacheProviderIdOptions {
+    apiKey?: string;
+    baseUrl?: string;
+}
+export declare function getDefaultModelDiscoveryBaseUrl(providerId: string): string | undefined;
+/** Resolve an Ollama model-cache namespace scoped to the normalized discovery endpoint. */
+export declare function resolveOllamaModelCacheProviderId(providerId: string, baseUrl?: string): string;
+/** Resolve the cache namespace used by a provider's model-manager options without constructing those options. */
+export declare function resolveModelCacheProviderId(providerId: string, options?: ModelCacheProviderIdOptions): string;

package/dist/types/provider-models/descriptor-types.d.ts

@@ -0,0 +1,76 @@
+import type { ModelManagerOptions } from "../model-manager.js";
+import type { Api, FetchImpl } from "../types.js";
+/** Config passed to a provider's runtime model-manager factory. */
+export type ModelManagerConfig = {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: FetchImpl;
+    /** The supplied fetch already applies provider-specific authentication. */
+    authenticated?: boolean;
+};
+/** Catalog discovery configuration for providers that support endpoint-based model listing. */
+export interface CatalogDiscoveryConfig {
+    /** Human-readable name for log messages. */
+    label: string;
+    /**
+     * Environment variables to check for API keys during catalog generation.
+     * Defaults to the entry-level `envVars` when omitted.
+     */
+    envVars?: readonly string[];
+    /** OAuth provider for credential refresh during catalog generation. */
+    oauthProvider?: string;
+    /** When true, catalog discovery proceeds even without credentials. */
+    allowUnauthenticated?: boolean;
+}
+/** Unified provider descriptor used by both runtime discovery and catalog generation. */
+export interface ProviderDescriptor {
+    providerId: string;
+    createModelManagerOptions(config: ModelManagerConfig): ModelManagerOptions<Api>;
+    /** Preferred model ID when no explicit selection is made. */
+    defaultModel: string;
+    /** When true, the runtime creates a model manager even without a valid API key (e.g. ollama). */
+    allowUnauthenticated?: boolean;
+    /** When true, successful runtime discovery replaces bundled provider models instead of merging fallback-only IDs. */
+    dynamicModelsAuthoritative?: boolean;
+    /** Catalog discovery configuration. Only providers with this field participate in generate-models.ts. */
+    catalogDiscovery?: CatalogDiscoveryConfig;
+}
+/** A provider descriptor that has catalog discovery configured. */
+export type CatalogProviderDescriptor = ProviderDescriptor & {
+    catalogDiscovery: CatalogDiscoveryConfig;
+};
+/** Type guard for descriptors with catalog discovery. */
+export declare function isCatalogDescriptor(d: ProviderDescriptor): d is CatalogProviderDescriptor;
+/** Whether catalog discovery may run without provider credentials. */
+export declare function allowsUnauthenticatedCatalogDiscovery(descriptor: CatalogProviderDescriptor): boolean;
+/**
+ * One model provider's catalog-side description. The auth half of a provider
+ * (env keys, OAuth login/refresh flows) lives in `@linxiraos/pi-ai`'s registry;
+ * the catalog table below is the single source of truth for ids, default
+ * models, and discovery wiring.
+ *
+ * - Every entry is a member of `KnownProvider`.
+ * - `createModelManagerOptions` present (and not `specialModelManager`) ⇒
+ *   appears in `PROVIDER_DESCRIPTORS` for runtime model discovery.
+ * - \`catalogDiscovery\` present ⇒ participates in \`generate-models.ts\`.
+ */
+export interface ProviderCatalogEntry {
+    readonly id: string;
+    /** Preferred model ID when no explicit selection is made. */
+    readonly defaultModel: string;
+    /** Environment variables consulted (in order) for the provider's runtime API-key env fallback. */
+    readonly envVars?: readonly string[];
+    /** Runtime model-manager factory. Omitted for catalog-only providers. */
+    readonly createModelManagerOptions?: (config: ModelManagerConfig) => ModelManagerOptions<Api>;
+    /** When true, the runtime creates a model manager even without a valid API key. */
+    readonly allowUnauthenticated?: boolean;
+    /** When true, successful runtime discovery replaces bundled provider models. */
+    readonly dynamicModelsAuthoritative?: boolean;
+    /** Catalog discovery configuration for generate-models.ts. */
+    readonly catalogDiscovery?: CatalogDiscoveryConfig;
+    /**
+     * Built bespoke by the coding-agent runtime (OAuth-token-driven managers);
+     * excluded from `PROVIDER_DESCRIPTORS` even though models are discoverable.
+     */
+    readonly specialModelManager?: boolean;
+}