findEmbeddingProviders support (#62)

* findEmbeddingProviders support (no tests + docs)

* fixes tiny bug in vectorize tests

* docs for findEmbeddingProviders

* tiny bit more documenation

* one more test for findEmbeddingProviders

Author: toptobes

src/data-api/db.ts

@@ -58,8 +58,7 @@ import { DataAPIDbAdmin } from '@/src/devops/data-api-db-admin';
  * Db spawning methods let you pass in the default namespace for the database, which is used for all subsequent db
  * operations in that object, but each method lets you override the namespace if necessary in its options.
  *
- * @example
- * ```typescript
+ * {@link DbAdmin.findEmbeddingProviders}typescript
  * const client = new DataAPIClient('AstraCS:...');
  *
  * // Connect to a database using a direct endpoint

src/data-api/embedding-providers/embedding-headers-provider.ts

@@ -31,9 +31,13 @@ import { EmbeddingAPIKeyHeaderProvider } from '@/src/data-api/embedding-provider
  * translated into an {@link EmbeddingAPIKeyHeaderProvider} under the hood.
  *
  * @example
- * ```
+ * ```typescript
+ * // Using explicit `EmbeddingHeadersProvider`
  * const provider = new AWSEmbeddingHeadersProvider('access-key-id', 'secret-access-key');
- * const collection = await db.collection('my_coll', { embeddingApiKey: provider });
+ * const coll1 = await db.collection('my_coll1', { embeddingApiKey: provider });
+ *
+ * // Implicitly converted to `EmbeddingAPIKeyHeaderProvider`
+ * const coll2 = await db.collection('my_coll2', { embeddingApiKey: 'sk-...' });
  * ```
  *
  * @see EmbeddingAPIKeyHeaderProvider

src/data-api/types/collections/collections-common.ts

@@ -36,7 +36,7 @@ export interface VectorOptions {
    * - Some models require a specific dimension that's already set by default
    *
    * You can find out more information about each model in the [DataStax docs](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html),
-   * or through the `findEmbeddingsProvider` command.
+   * or through {@link DbAdmin.findEmbeddingProviders}.
    */
   dimension?: number,
   /**
@@ -46,9 +46,11 @@ export interface VectorOptions {
    */
   metric?: 'cosine' | 'euclidean' | 'dot_product',
   /**
-   * NOTE: This feature is under current development.
+   * The options for defining the embedding service used for vectorize, to automatically transform your
+   * text into a vector ready for semantic vector searching.
    *
-   * @alpha
+   * You can find out more information about each provider/model in the [DataStax docs](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html),
+   * or through {@link DbAdmin.findEmbeddingProviders}.
    */
   service?: VectorizeServiceOptions,
 }
@@ -58,7 +60,7 @@ export interface VectorOptions {
  * text into a vector ready for semantic vector searching.
  *
  * You can find out more information about each provider/model in the [DataStax docs](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html),
- * or through the `findEmbeddingsProvider` command.
+ * or through {@link DbAdmin.findEmbeddingProviders}.
  *
  * @field provider - The name of the embedding provider which provides the model to use
  * @field model - The specific model to use for embedding, or undefined if it's an endpoint-defined model
@@ -72,16 +74,14 @@ export interface VectorizeServiceOptions {
    * The name of the embedding provider which provides the model to use.
    *
    * You can find out more information about each provider in the [DataStax docs](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html),
-   * or through the `findEmbeddingsProvider` command.
+   * or through  {@link DbAdmin.findEmbeddingProviders}.
    */
   provider: string,
   /**
    * The name of the embedding model to use.
    *
-   * In some situations, this may be `null`/`undefined` if the model may be arbitrary (such as with `huggingfaceDedicated`).
-   *
    * You can find out more information about each model in the [DataStax docs](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html),
-   * or through the `findEmbeddingsProvider` command.
+   * or through {@link DbAdmin.findEmbeddingProviders}.
    */
   modelName: string | nullish,
   /**
@@ -101,7 +101,7 @@ export interface VectorizeServiceOptions {
    * optional parameters (e.g. `openAi`), and some don't require any at all.
    *
    * You can find out more information about each provider/model in the [DataStax docs](https://docs.datastax.com/en/astra-db-serverless/databases/embedding-generation.html),
-   * or through the `findEmbeddingsProvider` command.
+   * or through {@link DbAdmin.findEmbeddingProviders}.
    */
   parameters?: Record<string, unknown>,
 }

src/devops/astra-db-admin.ts

@@ -21,6 +21,7 @@ import { WithTimeout } from '@/src/common/types';
 import { InternalRootClientOpts } from '@/src/client/types';
 import { isNullish, StaticTokenProvider, TokenProvider } from '@/src/common';
 import { validateAdminOpts } from '@/src/devops/utils';
+import { FindEmbeddingProvidersResult } from '@/src/devops/types/db-admin/find-embedding-providers';
 
 /**
  * An administrative class for managing Astra databases, including creating, listing, and deleting namespaces.
@@ -122,6 +123,27 @@ export class AstraDbAdmin extends DbAdmin {
     return this.#db;
   }
 
+  /**
+   * Returns detailed information about the availability and usage of the vectorize embedding providers available on the
+   * current database (may vary based on cloud provider & region).
+   *
+   * @example
+   * ```typescript
+   * const { embeddingProviders } = await dbAdmin.findEmbeddingProviders();
+   *
+   * // ['text-embedding-3-small', 'text-embedding-3-large', 'text-embedding-ada-002']
+   * console.log(embeddingProviders['openai'].models.map(m => m.name));
+   * ```
+   *
+   * @param options - The options for the timeout of the operation.
+   *
+   * @returns The available embedding providers.
+   */
+  public override async findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult> {
+    const resp = await this.#db.command({ findEmbeddingProviders: {} }, { namespace: null, maxTimeMS: options?.maxTimeMS });
+    return resp.status as FindEmbeddingProvidersResult;
+  }
+
   /**
    * Fetches the complete information about the database, such as the database name, IDs, region, status, actions, and
    * other metadata.

src/devops/data-api-db-admin.ts

@@ -20,6 +20,7 @@ import { DbAdmin } from '@/src/devops/db-admin';
 import { WithTimeout } from '@/src/common/types';
 import { validateAdminOpts } from '@/src/devops/utils';
 import { LocalCreateNamespaceOptions } from '@/src/devops/types/db-admin/local-create-namespace';
+import { FindEmbeddingProvidersResult } from '@/src/devops/types/db-admin/find-embedding-providers';
 
 /**
  * An administrative class for managing non-Astra databases, including creating, listing, and deleting namespaces.
@@ -92,6 +93,27 @@ export class DataAPIDbAdmin extends DbAdmin {
     return this.#db;
   }
 
+  /**
+   * Returns detailed information about the availability and usage of the vectorize embedding providers available on the
+   * current database (may vary based on cloud provider & region).
+   *
+   * @example
+   * ```typescript
+   * const { embeddingProviders } = await dbAdmin.findEmbeddingProviders();
+   *
+   * // ['text-embedding-3-small', 'text-embedding-3-large', 'text-embedding-ada-002']
+   * console.log(embeddingProviders['openai'].models.map(m => m.name));
+   * ```
+   *
+   * @param options - The options for the timeout of the operation.
+   *
+   * @returns The available embedding providers.
+   */
+  public override async findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult> {
+    const resp = await this.#httpClient.executeCommand({ findEmbeddingProviders: {} }, { namespace: null, maxTimeMS: options?.maxTimeMS });
+    return resp.status as FindEmbeddingProvidersResult;
+  }
+
   /**
    * Lists the namespaces in the database.
    *

src/devops/db-admin.ts

@@ -15,6 +15,8 @@
 
 import { AdminBlockingOptions, CreateNamespaceOptions } from '@/src/devops/types';
 import { Db } from '@/src/data-api';
+import { FindEmbeddingProvidersResult } from '@/src/devops/types/db-admin/find-embedding-providers';
+import { WithTimeout } from '@/src/common';
 
 /**
  * Represents some DatabaseAdmin class used for managing some specific database.
@@ -45,6 +47,24 @@ export abstract class DbAdmin {
    * @returns The underlying `Db` object.
    */
   abstract db(): Db;
+
+  /**
+   * Returns detailed information about the availability and usage of the vectorize embedding providers available on the
+   * current database (may vary based on cloud provider & region).
+   *
+   * @example
+   * ```typescript
+   * const { embeddingProviders } = await dbAdmin.findEmbeddingProviders();
+   *
+   * // ['text-embedding-3-small', 'text-embedding-3-large', 'text-embedding-ada-002']
+   * console.log(embeddingProviders['openai'].models.map(m => m.name));
+   * ```
+   *
+   * @param options - The options for the timeout of the operation.
+   *
+   * @returns The available embedding providers.
+   */
+  abstract findEmbeddingProviders(options?: WithTimeout): Promise<FindEmbeddingProvidersResult>;
   /**
    * Retrieves a list of all the namespaces in the database.
    *