@axiom-lattice/protocols 4.5.0 → 4.6.0

package/src/ModelProviderProtocol.ts

@@ -0,0 +1,821 @@
+/**
+ * ModelProviderProtocol
+ *
+ * Tenant-scoped model provider catalog for the Axiom Lattice framework.
+ * A tenant owner/admin configures an upstream `baseURL` + `apiKey`, and the
+ * gateway pulls the available model list from that upstream and stores it as a
+ * snapshot.
+ */
+
+import type { LLMConfig } from "./ModelLatticeProtocol";
+
+/**
+ * Wire protocol used to talk to the upstream provider.
+ * Phase 1 implements only `openai-compatible`.
+ */
+export type ModelProviderWireProtocol = "openai-compatible";
+
+/**
+ * Which request style the upstream speaks.
+ *
+ * This is not the same question as `wireProtocol`: two upstreams can both be
+ * "OpenAI-compatible" yet expose different routes and request fields.
+ * Chat Completions posts `messages` to `/v1/chat/completions`; the Responses
+ * API posts `input` to `/v1/responses`. Sending one where the other is expected
+ * surfaces as unrecognised parameters, a missing route, or endless retries.
+ */
+export type ModelProviderApiStyle = "chat-completions" | "responses";
+
+/**
+ * Value handed to `LLMConfig.provider` when a discovered model is turned into a
+ * runtime client.
+ *
+ * Derived from `LLMConfig` rather than restated, so the two cannot drift.
+ */
+export type ModelProviderLlmProvider = LLMConfig["provider"];
+
+/**
+ * Build the tenant-scoped model key.
+ *
+ * The provider id scopes the upstream model id, so the same upstream id offered
+ * by two providers yields two independent, independently-credentialed models.
+ * The provider id is immutable, so renaming a provider never invalidates a key
+ * already stored in agent or eval configuration.
+ *
+ * @param providerId - Provider identifier
+ * @param modelId - Upstream model id
+ */
+export function toModelKey(providerId: string, modelId: string): string {
+  return `${providerId}/${modelId}`;
+}
+
+/**
+ * Split a model key back into its provider and upstream model id.
+ *
+ * Splits on the first separator only: upstream model ids routinely contain
+ * `/` themselves (`Qwen/Qwen2.5-7B-Instruct`).
+ *
+ * @param modelKey - Key produced by {@link toModelKey}
+ * @returns The two parts, or null when the key carries no separator
+ */
+export function parseModelKey(
+  modelKey: string
+): { providerId: string; modelId: string } | null {
+  const separator = modelKey.indexOf("/");
+  if (separator <= 0 || separator === modelKey.length - 1) {
+    return null;
+  }
+
+  return {
+    providerId: modelKey.slice(0, separator),
+    modelId: modelKey.slice(separator + 1),
+  };
+}
+
+/**
+ * Outcome of the most recent discovery attempt for a provider.
+ */
+export type ModelProviderStatus = "unknown" | "ok" | "error";
+
+/** The codes a probe can fail with — all of them upstream-side. */
+export type ModelProviderUpstreamErrorCode =
+  | "UPSTREAM_UNREACHABLE"
+  | "UPSTREAM_AUTH_FAILED"
+  | "UPSTREAM_REDIRECT_BLOCKED"
+  | "UPSTREAM_INVALID_RESPONSE"
+  | "UPSTREAM_RATE_LIMITED"
+  | "UPSTREAM_TIMEOUT";
+
+/**
+ * Stable error codes returned by the model provider endpoints.
+ *
+ * Declared here rather than in the gateway so clients can type the code they
+ * receive and switch over it exhaustively. A console that re-types the list as
+ * bare strings cannot be told when the server adds or renames one.
+ */
+export type ModelProviderErrorCode =
+  | "UNAUTHENTICATED"
+  | "TENANT_ACCESS_DENIED"
+  | "FORBIDDEN_ROLE"
+  | "INVALID_INPUT"
+  | "INVALID_BASE_URL"
+  | "UNSUPPORTED_PROTOCOL"
+  | "PROVIDER_NOT_FOUND"
+  | "PROVIDER_DISABLED"
+  | "PROVIDER_NAME_CONFLICT"
+  | "MODEL_KEY_CONFLICT"
+  | "UPSTREAM_UNREACHABLE"
+  | "UPSTREAM_AUTH_FAILED"
+  | "UPSTREAM_REDIRECT_BLOCKED"
+  | "UPSTREAM_INVALID_RESPONSE"
+  | "UPSTREAM_RATE_LIMITED"
+  | "UPSTREAM_TIMEOUT"
+  | "INTERNAL_ERROR";
+
+/**
+ * A tenant-scoped model provider configuration.
+ *
+ * `apiKey` holds the decrypted secret and is for **server-side use only**.
+ * It must never be serialized into an API response — route responses go through
+ * the service's public projection, which exposes `hasApiKey` / `apiKeyHint`.
+ */
+export interface ModelProviderEntry {
+  /**
+   * Unique identifier for the provider configuration
+   */
+  id: string;
+
+  /**
+   * Tenant identifier for multi-tenant isolation
+   */
+  tenantId: string;
+
+  /**
+   * Business name for the provider (unique within tenant)
+   */
+  name: string;
+
+  /**
+   * Optional friendly name for display
+   */
+  displayName?: string;
+
+  /**
+   * Wire protocol used for discovery
+   */
+  protocol: ModelProviderWireProtocol;
+
+  /**
+   * Request style the upstream speaks. Defaults to Chat Completions.
+   */
+  apiStyle: ModelProviderApiStyle;
+
+  /**
+   * LLMConfig provider value used when constructing a runtime client
+   */
+  llmProvider: ModelProviderLlmProvider;
+
+  /**
+   * Upstream base URL
+   */
+  baseURL: string;
+
+  /**
+   * Decrypted API key. Server-side only — never serialize into a response.
+   */
+  apiKey?: string;
+
+  /**
+   * Last 4 characters of the API key. Safe to expose.
+   */
+  apiKeyHint?: string;
+
+  /**
+   * Whether this provider participates in discovery and registration
+   */
+  enabled: boolean;
+
+  /**
+   * Outcome of the most recent discovery attempt
+   */
+  status: ModelProviderStatus;
+
+  /**
+   * Stable error code from the most recent failed discovery.
+   * Never the raw upstream response body.
+   */
+  lastError?: string;
+
+  /**
+   * Timestamp of the most recent successful discovery
+   */
+  lastDiscoveredAt?: Date;
+
+  /**
+   * User who created the configuration
+   */
+  createdBy?: string;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: Date;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: Date;
+}
+
+/**
+ * Request to create a new model provider configuration
+ */
+export interface CreateModelProviderRequest {
+  /**
+   * Business name for the provider (unique within tenant)
+   */
+  name: string;
+
+  /**
+   * Optional friendly name for display
+   */
+  displayName?: string;
+
+  /**
+   * Wire protocol used for discovery
+   */
+  protocol: ModelProviderWireProtocol;
+
+  /**
+   * Request style the upstream speaks. Defaults to Chat Completions.
+   */
+  apiStyle?: ModelProviderApiStyle;
+
+  /**
+   * Upstream base URL
+   */
+  baseURL: string;
+
+  /**
+   * Upstream API key. Required: a provider must always carry a credential.
+   *
+   * A keyless provider is not merely useless — it is unsafe. `initChatModel`
+   * falls back to `process.env[apiKeyEnvName ?? "OPENAI_API_KEY"]` when the
+   * config carries no key, so a keyless provider pointed at a tenant-chosen
+   * host would send the gateway's own deployment credential to it.
+   */
+  apiKey: string;
+
+  /**
+   * Whether this provider participates in discovery and registration
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Request to update an existing model provider configuration.
+ *
+ * An omitted or empty `apiKey` means "keep the existing key" — the store must
+ * not overwrite stored credentials in that case. To remove a stored key
+ * outright, set `clearApiKey`.
+ */
+export interface UpdateModelProviderRequest {
+  /**
+   * Business name for the provider
+   */
+  name?: string;
+
+  /**
+   * Optional friendly name for display
+   */
+  displayName?: string;
+
+  /**
+   * Wire protocol used for discovery
+   */
+  protocol?: ModelProviderWireProtocol;
+
+  /**
+   * Request style the upstream speaks
+   */
+  apiStyle?: ModelProviderApiStyle;
+
+  /**
+   * Upstream base URL
+   */
+  baseURL?: string;
+
+  /**
+   * Upstream API key. Omitted or empty keeps the existing key.
+   */
+  apiKey?: string;
+
+  /**
+   * Remove the stored API key.
+   *
+   * Needed because an empty `apiKey` means "keep": without this there is no way
+   * to revoke a leaked credential short of deleting the provider.
+   * Takes precedence over `apiKey`.
+   */
+  clearApiKey?: boolean;
+
+  /**
+   * Whether this provider participates in discovery and registration
+   */
+  enabled?: boolean;
+}
+
+/**
+ * A single model returned by an upstream discovery call
+ */
+export interface DiscoveredModel {
+  /**
+   * Upstream model id — this becomes the tenant-scoped `modelKey`
+   */
+  id: string;
+
+  /**
+   * Optional human-readable name from the upstream
+   */
+  displayName?: string;
+
+  /**
+   * Upstream `owned_by` field, when present
+   */
+  ownedBy?: string;
+
+  /**
+   * Upstream `created` field, when present
+   */
+  createdAt?: string;
+
+  /**
+   * Raw upstream payload for this model
+   */
+  raw?: unknown;
+}
+
+/**
+ * A model to store for a provider.
+ *
+ * Extends the discovered shape with an optional `enabled` override. Discovery
+ * leaves it out, which preserves whatever the tenant chose for a model that was
+ * already in the snapshot; an explicit selection states it.
+ */
+export interface ProviderModelInput extends DiscoveredModel {
+  enabled?: boolean;
+  /**
+   * The upstream no longer offers this model, but the row is kept.
+   *
+   * Distinct from `enabled: false`, which means the tenant switched it off.
+   */
+  stale?: boolean;
+}
+
+/**
+ * One model in an explicit provider model selection.
+ *
+ * Both states are stored: a deselected model is written with `enabled: false`
+ * rather than dropped. Only then can a later sync tell "the upstream no longer
+ * offers this" apart from "the tenant switched it off" — the two are otherwise
+ * indistinguishable in the data.
+ */
+export interface ModelSelection {
+  modelId: string;
+  enabled: boolean;
+  /** The upstream no longer offers this model; the row is kept, flagged. */
+  stale?: boolean;
+}
+
+/**
+ * A model recorded in a provider's snapshot
+ */
+export interface ModelProviderModelEntry {
+  /**
+   * Unique identifier for the snapshot row
+   */
+  id: string;
+
+  /**
+   * Tenant identifier for multi-tenant isolation
+   */
+  tenantId: string;
+
+  /**
+   * Identifier of the provider this model was discovered from
+   */
+  providerId: string;
+
+  /**
+   * Upstream model id — the tenant-scoped model key
+   */
+  modelId: string;
+
+  /**
+   * Optional human-readable name from the upstream
+   */
+  displayName?: string;
+
+  /**
+   * Upstream `owned_by` field, when present
+   */
+  ownedBy?: string;
+
+  /**
+   * Upstream `created` field, when present
+   */
+  upstreamCreatedAt?: Date;
+
+  /**
+   * Whether this model may be used
+   */
+  enabled: boolean;
+
+  /**
+   * The upstream no longer offers this model. The row is kept so configs that
+   * reference its key keep resolving, and so "dropped upstream" stays
+   * distinguishable from "switched off here".
+   */
+  stale?: boolean;
+
+  /**
+   * Timestamp of the discovery that produced this row
+   */
+  discoveredAt: Date;
+}
+
+/**
+ * Public projection of a provider configuration.
+ *
+ * This is the only shape that leaves the server: it never carries the API key
+ * itself, only whether one is configured and its last four characters.
+ */
+export interface ModelProviderPublicEntry {
+  /**
+   * Unique identifier for the provider configuration
+   */
+  id: string;
+
+  /**
+   * Tenant identifier
+   */
+  tenantId: string;
+
+  /**
+   * Business name for the provider
+   */
+  name: string;
+
+  /**
+   * Optional friendly name for display
+   */
+  displayName?: string;
+
+  /**
+   * Wire protocol used for discovery
+   */
+  protocol: ModelProviderWireProtocol;
+
+  /**
+   * Request style the upstream speaks
+   */
+  apiStyle: ModelProviderApiStyle;
+
+  /**
+   * LLMConfig provider value used when constructing a runtime client
+   */
+  llmProvider: ModelProviderLlmProvider;
+
+  /**
+   * Upstream base URL
+   */
+  baseURL: string;
+
+  /**
+   * Whether an API key is configured. Replaces the key itself in responses.
+   */
+  hasApiKey: boolean;
+
+  /**
+   * Last 4 characters of the API key, for display
+   */
+  apiKeyHint?: string;
+
+  /**
+   * Whether this provider participates in discovery and registration
+   */
+  enabled: boolean;
+
+  /**
+   * Outcome of the most recent discovery attempt
+   */
+  status: ModelProviderStatus;
+
+  /**
+   * Stable error code from the most recent failed discovery
+   */
+  lastError?: string;
+
+  /**
+   * Timestamp of the most recent successful discovery
+   */
+  lastDiscoveredAt?: string;
+
+  /**
+   * Number of models in this provider's snapshot
+   */
+  modelCount: number;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: string;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: string;
+}
+
+/**
+ * A model visible to a tenant, from either the discovery snapshot or the
+ * in-memory model registry.
+ */
+export interface TenantModelPublicEntry {
+  /**
+   * Tenant-scoped model key — the upstream model id
+   */
+  modelKey: string;
+
+  /**
+   * Optional human-readable name
+   */
+  displayName?: string;
+
+  /**
+   * Identifier of the provider offering this model
+   */
+  providerId: string;
+
+  /**
+   * Name of the provider offering this model
+   */
+  providerName: string;
+
+  /**
+   * Upstream `owned_by` field, when present
+   */
+  ownedBy?: string;
+
+  /**
+   * Where this entry came from
+   */
+  source: "snapshot" | "registered";
+
+  /**
+   * Whether the tenant has this model switched on.
+   * Entries sourced from the registry are always enabled.
+   */
+  enabled: boolean;
+
+  /**
+   * The upstream no longer offers this model (see `ModelProviderModelEntry.stale`)
+   */
+  stale: boolean;
+
+  /**
+   * Whether this model can actually be executed by an agent.
+   * Phase 1: true only for the `default` tenant.
+   */
+  executable: boolean;
+}
+
+/**
+ * The full model catalog visible to one tenant
+ */
+export interface TenantModelCatalog {
+  /**
+   * Provider configurations owned by the tenant
+   */
+  providers: ModelProviderPublicEntry[];
+
+  /**
+   * Models visible to the tenant
+   */
+  models: TenantModelPublicEntry[];
+}
+
+/**
+ * Result of running discovery against one provider
+ */
+export interface ModelDiscoveryResult {
+  /**
+   * Models returned by the upstream
+   */
+  discovered: DiscoveredModel[];
+
+  /**
+   * Model keys registered for execution, of the form `${providerId}/${modelId}`
+   */
+  registered: string[];
+
+  /**
+   * Provider status after this attempt
+   */
+  status: ModelProviderStatus;
+
+  /**
+   * Stable error code if the attempt failed
+   */
+  lastError?: string;
+}
+
+/**
+ * Ad-hoc probe of an upstream, used by the provider form to validate a base URL
+ * and API key before they are saved.
+ *
+ * Unlike `discover`, this accepts the URL from the request rather than loading
+ * it from the store — that is the whole point, since the values may not exist
+ * in the store yet. The URL is validated exactly as on create/update and is
+ * never persisted by a probe.
+ */
+export interface ModelProviderProbeRequest {
+  /**
+   * Upstream base URL to probe. Validated before any outbound request.
+   */
+  baseURL: string;
+
+  /**
+   * API key to authenticate with.
+   * Omitted on an existing provider means "use the stored key", which is
+   * resolved through `providerId` — the form never receives the stored key.
+   */
+  apiKey?: string;
+
+  /**
+   * Existing provider whose stored key should be used when `apiKey` is absent.
+   */
+  providerId?: string;
+
+  /**
+   * Wire protocol to speak. Defaults to `openai-compatible`.
+   */
+  protocol?: ModelProviderWireProtocol;
+}
+
+/**
+ * Outcome of a probe: what the upstream answered, and how long it took.
+ *
+ * A failed probe is still a successful request — the caller wants to render
+ * "unreachable: UPSTREAM_AUTH_FAILED" in the form, not handle an HTTP error.
+ * Only invalid input (bad URL, unknown protocol) is reported as an HTTP error.
+ */
+export interface ModelProviderProbeResult {
+  /**
+   * Whether the upstream answered with a model list
+   */
+  reachable: boolean;
+
+  /**
+   * Round-trip time in milliseconds, measured over the model list request
+   */
+  latencyMs: number;
+
+  /**
+   * Models the upstream returned. Empty when unreachable.
+   */
+  models: DiscoveredModel[];
+
+  /**
+   * Stable error code when `reachable` is false.
+   *
+   * Narrowed to the upstream subset: an invalid URL or an unsupported protocol
+   * is rejected before the request is attempted, so those surface as HTTP
+   * errors rather than as an unreachable probe.
+   */
+  error?: ModelProviderUpstreamErrorCode;
+}
+
+/**
+ * ModelProviderStore interface
+ * Provides tenant-scoped CRUD for provider configurations and their model snapshots
+ */
+export interface ModelProviderStore {
+  /**
+   * Get all provider configurations for a tenant
+   * @param tenantId - Tenant identifier
+   * @returns Array of provider configurations
+   */
+  listProviders(tenantId: string): Promise<ModelProviderEntry[]>;
+
+  /**
+   * Get a provider configuration by ID
+   * @param tenantId - Tenant identifier
+   * @param id - Provider identifier
+   * @returns Provider configuration if found, null otherwise
+   */
+  getProviderById(tenantId: string, id: string): Promise<ModelProviderEntry | null>;
+
+  /**
+   * Get a provider configuration by business name
+   * @param tenantId - Tenant identifier
+   * @param name - Provider business name
+   * @returns Provider configuration if found, null otherwise
+   */
+  getProviderByName(tenantId: string, name: string): Promise<ModelProviderEntry | null>;
+
+  /**
+   * Create a new provider configuration
+   * @param tenantId - Tenant identifier
+   * @param id - Provider identifier
+   * @param data - Provider creation data
+   * @returns Created provider configuration
+   */
+  createProvider(
+    tenantId: string,
+    id: string,
+    data: CreateModelProviderRequest
+  ): Promise<ModelProviderEntry>;
+
+  /**
+   * Update an existing provider configuration.
+   * An omitted or empty `apiKey` leaves the stored key untouched.
+   * @param tenantId - Tenant identifier
+   * @param id - Provider identifier
+   * @param updates - Partial provider data to update
+   * @returns Updated provider configuration if found, null otherwise
+   */
+  updateProvider(
+    tenantId: string,
+    id: string,
+    updates: Partial<UpdateModelProviderRequest>
+  ): Promise<ModelProviderEntry | null>;
+
+  /**
+   * Delete a provider configuration and its model snapshot
+   * @param tenantId - Tenant identifier
+   * @param id - Provider identifier
+   * @returns true if deleted, false otherwise
+   */
+  deleteProvider(tenantId: string, id: string): Promise<boolean>;
+
+  /**
+   * Record the outcome of a discovery attempt
+   * @param tenantId - Tenant identifier
+   * @param id - Provider identifier
+   * @param status - Discovery outcome
+   * @param lastError - Stable error code, if the attempt failed
+   * @param discoveredAt - Timestamp of a successful discovery
+   */
+  markProviderStatus(
+    tenantId: string,
+    id: string,
+    status: ModelProviderStatus,
+    lastError?: string,
+    discoveredAt?: Date
+  ): Promise<void>;
+
+  /**
+   * List snapshot models for a tenant
+   * @param tenantId - Tenant identifier
+   * @param providerId - Optional provider filter
+   * @returns Array of snapshot models
+   */
+  listModels(tenantId: string, providerId?: string): Promise<ModelProviderModelEntry[]>;
+
+  /**
+   * Get a single snapshot model.
+   * Keyed by provider as well as model id, since two providers in the same
+   * tenant may expose the same upstream model id.
+   * @param tenantId - Tenant identifier
+   * @param providerId - Provider identifier
+   * @param modelId - Upstream model id
+   * @returns Snapshot model if found, null otherwise
+   */
+  getModel(
+    tenantId: string,
+    providerId: string,
+    modelId: string
+  ): Promise<ModelProviderModelEntry | null>;
+
+  /**
+   * Replace a provider's model snapshot with the result of one discovery.
+   *
+   * Model ids are scoped per provider, so the same upstream id may appear
+   * under several providers in one tenant — each is an independent model
+   * addressed by `${providerId}/${modelId}`.
+   *
+   * @param tenantId - Tenant identifier
+   * @param providerId - Provider identifier
+   * @param models - Models returned by the most recent discovery
+   * @returns Model ids now present in this provider's snapshot
+   */
+  replaceProviderModels(
+    tenantId: string,
+    providerId: string,
+    models: ProviderModelInput[]
+  ): Promise<string[]>;
+
+  /**
+   * Enable or disable a single snapshot model
+   * @param tenantId - Tenant identifier
+   * @param providerId - Provider identifier
+   * @param modelId - Model id
+   * @param enabled - Desired state
+   * @returns Updated snapshot model if found, null otherwise
+   */
+  setModelEnabled(
+    tenantId: string,
+    providerId: string,
+    modelId: string,
+    enabled: boolean
+  ): Promise<ModelProviderModelEntry | null>;
+
+  /**
+   * Delete every snapshot model belonging to a provider
+   * @param tenantId - Tenant identifier
+   * @param providerId - Provider identifier
+   * @returns Number of rows deleted
+   */
+  deleteModelsByProvider(tenantId: string, providerId: string): Promise<number>;
+}