From 1a97920a22b7dc0217fc833104ff99efb12f03d8 Mon Sep 17 00:00:00 2001 From: toptobes Date: Mon, 18 Aug 2025 12:42:13 -0500 Subject: [PATCH] add model status support, type reranking providers --- src/administration/db-admin.ts | 14 +- .../types/db-admin/astra-create-keyspace.ts | 2 +- src/administration/types/db-admin/common.ts | 36 +++ .../db-admin/find-embedding-providers.ts | 119 ++++++-- .../db-admin/find-reranking-providers.ts | 280 +++++++++++++++++- .../types/db-admin/local-create-keyspace.ts | 4 +- 6 files changed, 417 insertions(+), 38 deletions(-) create mode 100644 src/administration/types/db-admin/common.ts diff --git a/src/administration/db-admin.ts b/src/administration/db-admin.ts index 61ae2e06..1f2ffdf6 100644 --- a/src/administration/db-admin.ts +++ b/src/administration/db-admin.ts @@ -13,12 +13,18 @@ // limitations under the License. // noinspection ExceptionCaughtLocallyJS -import type { FindEmbeddingProvidersResult } from '@/src/administration/types/db-admin/find-embedding-providers.js'; +import type { + FindEmbeddingProvidersOptions, + FindEmbeddingProvidersResult, +} from '@/src/administration/types/db-admin/find-embedding-providers.js'; import type { CommandOptions } from '@/src/lib/index.js'; import { HierarchicalLogger } from '@/src/lib/index.js'; import type { Db } from '@/src/db/index.js'; import type { AdminCommandEventMap } from '@/src/administration/events.js'; -import type { FindRerankingProvidersResult } from '@/src/administration/types/db-admin/find-reranking-providers.js'; +import type { + FindRerankingProvidersOptions, + FindRerankingProvidersResult, +} from '@/src/administration/types/db-admin/find-reranking-providers.js'; import type { DataAPIHttpClient } from '@/src/lib/api/clients/index.js'; /** @@ -171,7 +177,7 @@ export abstract class DbAdmin extends HierarchicalLogger { * * @returns The available embedding providers. */ - public async findEmbeddingProviders(options?: CommandOptions<{ timeout: 'databaseAdminTimeoutMs' }>): Promise { + public async findEmbeddingProviders(options?: FindEmbeddingProvidersOptions): Promise { const httpClient = this._getDataAPIHttpClient(); const resp = await httpClient.executeCommand({ findEmbeddingProviders: {} }, { @@ -199,7 +205,7 @@ export abstract class DbAdmin extends HierarchicalLogger { * * @returns The available reranking providers. */ - public async findRerankingProviders(options?: CommandOptions<{ timeout: 'databaseAdminTimeoutMs' }>): Promise { + public async findRerankingProviders(options?: FindRerankingProvidersOptions): Promise { const httpClient = this._getDataAPIHttpClient(); const resp = await httpClient.executeCommand({ findRerankingProviders: {} }, { diff --git a/src/administration/types/db-admin/astra-create-keyspace.ts b/src/administration/types/db-admin/astra-create-keyspace.ts index 4b01647a..3f45e81b 100644 --- a/src/administration/types/db-admin/astra-create-keyspace.ts +++ b/src/administration/types/db-admin/astra-create-keyspace.ts @@ -25,7 +25,7 @@ import type { CommandOptions } from '@/src/lib/index.js'; * yet created). * * @example - * ```typescript + * ```ts * // If using non-astra, this may be a common idiom: * const client = new DataAPIClient({ environment: 'dse' }); * const db = client.db('', { token: '' }); diff --git a/src/administration/types/db-admin/common.ts b/src/administration/types/db-admin/common.ts new file mode 100644 index 00000000..146a17a3 --- /dev/null +++ b/src/administration/types/db-admin/common.ts @@ -0,0 +1,36 @@ +// Copyright DataStax, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** + * The lifecycle status of a model indicating its current support level. + * + * - `'SUPPORTED'`: The model is actively supported and recommended for use + * - `'DEPRECATED'`: The model is still functional but deprecated and may be removed in the future + * - `'END_OF_LIFE'`: The model is no longer supported and should not be used + * + * @example + * ```ts + * // A model with active support + * status: 'SUPPORTED' + * + * // A model that's deprecated but still works + * status: 'DEPRECATED' + * + * // A model that's no longer available + * status: 'END_OF_LIFE' + * ``` + * + * @public + */ +export type ModelLifecycleStatus = 'SUPPORTED' | 'DEPRECATED' | 'END_OF_LIFE'; diff --git a/src/administration/types/db-admin/find-embedding-providers.ts b/src/administration/types/db-admin/find-embedding-providers.ts index 11cd82fd..d868aadc 100644 --- a/src/administration/types/db-admin/find-embedding-providers.ts +++ b/src/administration/types/db-admin/find-embedding-providers.ts @@ -12,6 +12,41 @@ // See the License for the specific language governing permissions and // limitations under the License. +import type { ModelLifecycleStatus } from '@/src/administration/types/db-admin/common.js'; +import type { CommandOptions, LitUnion } from '@/src/lib/index.js'; + +/** + * Options for finding embedding providers. + * + * @field filterModelStatus - Filter models by their lifecycle status. If not provided, defaults to 'SUPPORTED' only. Use empty string '' to include all statuses. + * + * @see DbAdmin.findEmbeddingProviders + * + * @public + */ +export interface FindEmbeddingProvidersOptions extends CommandOptions<{ timeout: 'databaseAdminTimeoutMs' }> { + /** + * Filter models by their lifecycle status. + * + * - If not provided: defaults to `'SUPPORTED'` only + * - If set to `''`: includes all statuses (`'SUPPORTED'`, `'DEPRECATED'`, `'END_OF_LIFE'`) + * - If set to specific status: includes only models with that status + * + * @example + * ```ts + * // Only supported models (default behavior) + * { filterModelStatus: 'SUPPORTED' } + * + * // All models regardless of status + * { filterModelStatus: '' } + * + * // Only deprecated models + * { filterModelStatus: 'DEPRECATED' } + * ``` + */ + filterModelStatus?: ModelLifecycleStatus | ''; +} + /** * The overarching result containing the `embeddingProviders` map. * @@ -26,7 +61,7 @@ export interface FindEmbeddingProvidersResult { * A map of embedding provider names (e.g. `openai`), to information about said provider (e.g. models/auth). * * @example - * ```typescript + * ```ts * { * openai: { * displayName: 'OpenAI', @@ -56,7 +91,7 @@ export interface EmbeddingProviderInfo { * The prettified name of the provider (as shown in the Astra portal). * * @example - * ```typescript + * ```ts * // openai.displayName: * 'OpenAI' * ``` @@ -69,7 +104,7 @@ export interface EmbeddingProviderInfo { * parameters (such as `huggingfaceDedicated` or `azureOpenAI`). * * @example - * ```typescript + * ```ts * // openai.url: * 'https://api.openai.com/v1/' * @@ -85,7 +120,7 @@ export interface EmbeddingProviderInfo { * * - `HEADER`: Authentication using direct API keys passed through headers on every Data API call. * See {@link EmbeddingHeadersProvider} for more info. - * ```typescript + * ```ts * const collections = await db.createCollection('my_coll', { * vector: { * service: { @@ -101,7 +136,7 @@ export interface EmbeddingProviderInfo { * ``` * * - `SHARED_SECRET`: Authentication tied to a collections at collections creation time using the Astra KMS. - * ```typescript + * ```ts * const collections = await db.collections('my_coll', { * // Not tied to the collections; can be different every time. * embeddingApiKey: 'sk-...', @@ -109,7 +144,7 @@ export interface EmbeddingProviderInfo { * ``` * * - `NONE`: For when a client doesn't need authentication to use (e.g. nvidia). - * ```typescript + * ```ts * const collections = await db.createCollection('my_coll', { * vector: { * service: { @@ -121,7 +156,7 @@ export interface EmbeddingProviderInfo { * ``` * * @example - * ```typescript + * ```ts * // openai.supportedAuthentication.HEADER: * { * enabled: true, @@ -132,14 +167,14 @@ export interface EmbeddingProviderInfo { * } * ``` */ - supportedAuthentication: Record, + supportedAuthentication: Record, EmbeddingProviderAuthInfo>, /** * Any additional, arbitrary parameters the provider may take in. May or may not be required. * * Passed into the `parameters` block in {@link VectorizeServiceOptions} (except for `vectorDimension`). * * @example - * ```typescript + * ```ts * // openai.parameters[1] * { * name: 'projectId', @@ -159,7 +194,7 @@ export interface EmbeddingProviderInfo { * may be truly arbitrary. * * @example - * ```typescript + * ```ts * // nvidia.models[0] * { * name: 'NV-Embed-QA', @@ -194,7 +229,7 @@ export interface EmbeddingProviderInfo { * See {@link EmbeddingHeadersProvider} for more info about the `HEADER` auth through the client. * * @example - * ```typescript + * ```ts * // openai.supportedAuthentication.HEADER: * { * enabled: true, @@ -231,7 +266,7 @@ export interface EmbeddingProviderAuthInfo { * Info on how exactly a method of auth may be used. * * @example - * ```typescript + * ```ts * // openai.supportedAuthentication.HEADER.tokens[0]: * { * accepted: 'x-embedding-api-key', @@ -268,7 +303,7 @@ export interface EmbeddingProviderTokenInfo { * set in the upper-level `dimension: number` field). * * @example - * ```typescript + * ```ts * // openai.parameters[1] * { * name: 'vectorDimension', @@ -300,7 +335,7 @@ export interface EmbeddingProviderModelParameterInfo { * `vector` block in {@link CollectionVectorOptions}/{@link TableVectorColumnDefinition}. * * @example - * ```typescript + * ```ts * // huggingface.parameters[0].name * endpointName * ``` @@ -312,7 +347,7 @@ export interface EmbeddingProviderModelParameterInfo { * Commonly `number` or `STRING`. * * @example - * ```typescript + * ```ts * // huggingface.parameters[0].type * STRING * ``` @@ -322,7 +357,7 @@ export interface EmbeddingProviderModelParameterInfo { * Whether the parameter is required to be passed in. * * @example - * ```typescript + * ```ts * // huggingface.parameters[0].required * true * ``` @@ -334,7 +369,7 @@ export interface EmbeddingProviderModelParameterInfo { * Will always be in string form (even if the `type` is `'number'`). * * @example - * ```typescript + * ```ts * // huggingface.parameters[0].defaultValue * '' * ``` @@ -346,7 +381,7 @@ export interface EmbeddingProviderModelParameterInfo { * Commonly either an empty record, or `{ numericRange: [, ] }`. * * @example - * ```typescript + * ```ts * // huggingface.parameters[0].validation * {} * ``` @@ -356,7 +391,7 @@ export interface EmbeddingProviderModelParameterInfo { * Any additional help text/information about the parameter. * * @example - * ```typescript + * ```ts * // huggingface.parameters[0].help * 'The name of your Hugging Face dedicated endpoint, the first part of the Endpoint URL.' * ``` @@ -371,7 +406,7 @@ export interface EmbeddingProviderModelParameterInfo { * set in the upper-level `dimension: number` field). * * @example - * ```typescript + * ```ts * // openai.parameters[1] * { * name: 'projectId', @@ -404,7 +439,7 @@ export interface EmbeddingProviderProviderParameterInfo extends EmbeddingProvide * Display name for the parameter. * * @example - * ```typescript + * ```ts * // openai.parameters[0].displayName * 'Organization ID' * ``` @@ -414,7 +449,7 @@ export interface EmbeddingProviderProviderParameterInfo extends EmbeddingProvide * Hint for parameter usage. * * @example - * ```typescript + * ```ts * // openai.parameters[0].hint * 'Add an (optional) organization ID' * ``` @@ -429,7 +464,7 @@ export interface EmbeddingProviderProviderParameterInfo extends EmbeddingProvide * may be truly arbitrary. * * @example - * ```typescript + * ```ts * // nvidia.models[0] * { * name: 'NV-Embed-QA', @@ -454,7 +489,7 @@ export interface EmbeddingProviderModelInfo { * may be truly arbitrary. * * @example - * ```typescript + * ```ts * // openai.models[0].name * 'text-embedding-3-small' * @@ -469,7 +504,7 @@ export interface EmbeddingProviderModelInfo { * If not present, a `vectorDimension` parameter will be present in the `model.parameters` block. * * @example - * ```typescript + * ```ts * // openai.models[3].vectorDimension (text-embedding-ada-002) * 1536 * @@ -484,7 +519,7 @@ export interface EmbeddingProviderModelInfo { * Passed into the `parameters` block in {@link VectorizeServiceOptions} (except for `vectorDimension`). * * @example - * ```typescript + * ```ts * // openai.models[0].parameters[0] (text-embedding-3-small) * { * name: 'vectorDimension', @@ -497,4 +532,36 @@ export interface EmbeddingProviderModelInfo { * ``` */ parameters: EmbeddingProviderModelParameterInfo[], + /** + * Information about the model's API support status. + * + * @example + * ```ts + * // openai.models[0].apiModelSupport + * { status: 'SUPPORTED' } + * ``` + */ + apiModelSupport: EmbeddingProviderModelApiSupportInfo, +} + +/** + * Information about the model's API support status and lifecycle. + * + * @field status - The current lifecycle status of the model + * + * @see EmbeddingProviderModelInfo + * + * @public + */ +export interface EmbeddingProviderModelApiSupportInfo { + /** + * The current lifecycle status of the model. + * + * @example + * ```ts + * // openai.models[0].apiModelSupport.status + * 'SUPPORTED' + * ``` + */ + status: ModelLifecycleStatus, } diff --git a/src/administration/types/db-admin/find-reranking-providers.ts b/src/administration/types/db-admin/find-reranking-providers.ts index bb77a523..783b07ac 100644 --- a/src/administration/types/db-admin/find-reranking-providers.ts +++ b/src/administration/types/db-admin/find-reranking-providers.ts @@ -12,10 +12,44 @@ // See the License for the specific language governing permissions and // limitations under the License. + +import type { ModelLifecycleStatus } from '@/src/administration/types/db-admin/common.js'; +import type { CommandOptions, LitUnion } from '@/src/lib/index.js'; + /** - * The overarching result containing the `rerankingProviders` map. + * Options for finding reranking providers. * - * **Temporarily dynamically typed. In a future release, the type will be strengthened.** + * @field filterModelStatus - Filter models by their lifecycle status. If not provided, defaults to `'SUPPORTED'` only. Use empty string `''` to include all statuses. + * + * @see DbAdmin.findRerankingProviders + * + * @public + */ +export interface FindRerankingProvidersOptions extends CommandOptions<{ timeout: 'databaseAdminTimeoutMs' }> { + /** + * Filter models by their lifecycle status. + * + * - If not provided: defaults to `'SUPPORTED'` only + * - If set to `''`: includes all statuses (`'SUPPORTED'`, `'DEPRECATED'`, `'END_OF_LIFE'`) + * - If set to specific status: includes only models with that status + * + * @example + * ```ts + * // Only supported models (default behavior) + * { filterModelStatus: 'SUPPORTED' } + * + * // All models regardless of status + * { filterModelStatus: '' } + * + * // Only deprecated models + * { filterModelStatus: 'DEPRECATED' } + * ``` + */ + filterModelStatus?: ModelLifecycleStatus | ''; +} + +/** + * The overarching result containing the `rerankingProviders` map. * * @field rerankingProviders - Map of reranking provider names to info about said provider. * @@ -28,7 +62,7 @@ export interface FindRerankingProvidersResult { * A map of reranking provider names (e.g. `nvidia`), to information about said provider (e.g. models/auth). * * @example - * ```typescript + * ```ts * { * nvidia: { * displayName: 'Nvidia', @@ -36,8 +70,244 @@ export interface FindRerankingProvidersResult { * } * } * ``` + */ + rerankingProviders: Record, +} + +/** + * Info about a specific reranking provider + * + * @field displayName - The prettified name of the provider (as shown in the portal) + * @field isDefault - Whether this provider is the default for reranking + * @field supportedAuthentication - Enabled methods of auth for the provider + * @field models - The specific models that the provider supports + * + * @see FindRerankingProvidersResult + * + * @public + */ +export interface RerankingProviderInfo { + /** + * The prettified name of the provider (as shown in the Astra portal). + * + * @example + * ```ts + * // nvidia.displayName: + * 'Nvidia' + * ``` + */ + displayName: string, + /** + * Whether this provider is the default for reranking. + * + * @example + * ```ts + * // nvidia.isDefault: + * true + * ``` + */ + isDefault: boolean, + /** + * Supported methods of authentication for the provider. + * + * Possible methods include `'HEADER'`, `'SHARED_SECRET'`, and `'NONE'`. + * + * - `'HEADER'`: Authentication using direct API keys passed through headers on every Data API call. + * - `'SHARED_SECRET'`: Authentication tied to a collections at collections creation time using the Astra KMS. + * - `'NONE'`: For when a client doesn't need authentication to use (e.g. nvidia). + * + * @example + * ```ts + * // nvidia.supportedAuthentication.NONE: + * { + * enabled: true, + * tokens: [], + * } + * ``` + */ + supportedAuthentication: Record, RerankingProviderAuthInfo>, + /** + * The specific models that the provider supports. * - * **Temporarily typed as `any`. In a future release, the type will be strengthened.** + * @example + * ```ts + * // nvidia.models[0] + * { + * name: 'nvidia/llama-3.2-nv-rerankqa-1b-v2', + * isDefault: true, + * url: 'https://...', + * properties: null, + * apiModelSupport: { + * status: 'SUPPORTED', + * }, + * } + * ``` + */ + models: RerankingProviderModelInfo[], + /** + * Additional parameters for the provider, if any. + */ + parameters?: Record, +} + +/** + * Information about a specific auth method, such as `'HEADER'`, `'SHARED_SECRET'`, or `'NONE'` for a specific provider. See + * {@link RerankingProviderInfo.supportedAuthentication} for more information. + * + * @example + * ```ts + * // nvidia.supportedAuthentication.NONE: + * { + * enabled: true, + * tokens: [], + * } + * ``` + * + * @field enabled - Whether this method of auth is supported for the provider. + * @field tokens - Additional info on how exactly this method of auth is supposed to be used. + * + * @see RerankingProviderInfo + * + * @public + */ +export interface RerankingProviderAuthInfo { + /** + * Whether this method of auth is supported for the provider. + */ + enabled: boolean, + /** + * Additional info on how exactly this method of auth is supposed to be used. + * + * Will be an empty array if `enabled` is `false`. + */ + tokens: RerankingProviderTokenInfo[], +} + +/** + * Info on how exactly a method of auth may be used. + * + * @field accepted - The accepted token + * @field forwarded - How the token is forwarded to the reranking provider + * + * @see RerankingProviderAuthInfo + * + * @public + */ +export interface RerankingProviderTokenInfo { + /** + * The accepted token. + * + * May most often be `providerKey` for `SHARED_SECRET`, or specific header names for `HEADER`. + */ + accepted: string, + /** + * How the token is forwarded to the reranking provider. + */ + forwarded: string, +} + +/** + * The specific models that the provider supports for reranking. + * + * @example + * ```ts + * // nvidia.models[0] + * { + * name: 'nvidia/llama-3.2-nv-rerankqa-1b-v2', + * isDefault: true, + * url: 'https://...', + * properties: null, + * apiModelSupport: { + * status: 'SUPPORTED', + * }, + * } + * ``` + * + * @field name - The name of the model to use + * @field isDefault - Whether this model is the default for the provider + * @field url - The URL endpoint for the reranking model + * @field properties - Additional properties for the model (may be null) + * @field apiModelSupport - Information about the model's API support status + * + * @see RerankingProviderInfo + * + * @public + */ +export interface RerankingProviderModelInfo { + /** + * The name of the model to use. + * + * @example + * ```ts + * // nvidia.models[0].name + * 'nvidia/llama-3.2-nv-rerankqa-1b-v2' + * ``` + */ + name: string, + /** + * Whether this model is the default for the provider. + * + * @example + * ```ts + * // nvidia.models[0].isDefault + * true + * ``` + */ + isDefault: boolean, + /** + * The URL endpoint for the reranking model. + * + * @example + * ```ts + * // nvidia.models[0].url + * 'https://...' + * ``` + */ + url: string, + /** + * Additional properties for the model (may be null). + * + * @example + * ```ts + * // nvidia.models[0].properties + * null + * ``` + */ + properties: Record | null, + /** + * Information about the model's API support status. + * + * @example + * ```ts + * // nvidia.models[0].apiModelSupport + * { status: 'SUPPORTED' } + * ``` + */ + apiModelSupport: RerankingProviderModelApiSupportInfo, + /** + * Additional parameters for the model, if any. + */ + parameters?: Record, +} + +/** + * Information about the model's API support status and lifecycle. + * + * @field status - The current lifecycle status of the model + * + * @see RerankingProviderModelInfo + * + * @public + */ +export interface RerankingProviderModelApiSupportInfo { + /** + * The current lifecycle status of the model. + * + * @example + * ```ts + * // nvidia.models[0].apiModelSupport.status + * 'SUPPORTED' + * ``` */ - rerankingProviders: Record, + status: ModelLifecycleStatus, } diff --git a/src/administration/types/db-admin/local-create-keyspace.ts b/src/administration/types/db-admin/local-create-keyspace.ts index 875ab14b..317834cc 100644 --- a/src/administration/types/db-admin/local-create-keyspace.ts +++ b/src/administration/types/db-admin/local-create-keyspace.ts @@ -26,7 +26,7 @@ import type { CommandOptions } from '@/src/lib/index.js'; * yet created). * * @example - * ```typescript + * ```ts * // If using non-astra, this may be a common idiom: * const client = new DataAPIClient({ environment: 'dse' }); * const db = client.db('', { token: '' }); @@ -59,7 +59,7 @@ export interface CreateDataAPIKeyspaceOptions extends CommandOptions<{ timeout: * If no replication options are provided, it will default to `'SimpleStrategy'` with a replication factor of `1`. * * @example - * ```typescript + * ```ts * await dbAdmin.createKeyspace('my_keyspace'); * * await dbAdmin.createKeyspace('my_keyspace', {