tessl/npm-google--genai

Google Gen AI JavaScript SDK for building applications powered by Gemini with content generation, image/video generation, function calling, caching, and real-time live sessions

Overview

Eval results

Files

File Search Stores

Name: tessl/npm-google--genai
Author: tessl

File Search Stores provide document management and search capabilities for the Gemini API. A FileSearchStore acts as a container for documents that can be searched and retrieved during generation. The FileSearchStores class includes a nested Documents class for managing individual documents within a store.

Note: File Search Store functionality is only available in the Gemini Developer API, not in Vertex AI.

Capabilities

Create File Search Store

Creates a new FileSearchStore to hold documents for search operations.

/**
 * Creates a File Search Store
 * @param params - Parameters for creating the file search store
 * @returns Promise resolving to the created FileSearchStore
 */
function create(params: CreateFileSearchStoreParameters): Promise<FileSearchStore>;

interface CreateFileSearchStoreParameters {
  config?: CreateFileSearchStoreConfig;
}

interface CreateFileSearchStoreConfig {
  displayName?: string;
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

interface FileSearchStore {
  name?: string;
  displayName?: string;
  createTime?: string;
  updateTime?: string;
}

Usage Example:

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

const store = await client.fileSearchStores.create({
  config: {
    displayName: 'My Document Store'
  }
});

console.log('Created store:', store.name);

List File Search Stores

Lists all FileSearchStores owned by the user with pagination support.

/**
 * Lists file search stores
 * @param params - Optional parameters for pagination
 * @returns Promise resolving to a Pager of FileSearchStores
 */
function list(params?: ListFileSearchStoresParameters): Promise<Pager<FileSearchStore>>;

interface ListFileSearchStoresParameters {
  config?: ListFileSearchStoresConfig;
}

interface ListFileSearchStoresConfig {
  pageSize?: number;
  pageToken?: string;
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

Usage Example:

const stores = await client.fileSearchStores.list({
  config: { pageSize: 10 }
});

for await (const store of stores) {
  console.log('Store:', store.name, store.displayName);
}

Get File Search Store

Retrieves a specific FileSearchStore by name.

/**
 * Gets a File Search Store
 * @param params - Parameters specifying which store to retrieve
 * @returns Promise resolving to the FileSearchStore
 */
function get(params: GetFileSearchStoreParameters): Promise<FileSearchStore>;

interface GetFileSearchStoreParameters {
  name: string;
  config?: GetFileSearchStoreConfig;
}

interface GetFileSearchStoreConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

Usage Example:

const store = await client.fileSearchStores.get({
  name: 'fileSearchStores/abc123'
});

console.log('Store details:', store);

Delete File Search Store

Deletes a FileSearchStore and all its associated documents.

/**
 * Deletes a File Search Store
 * @param params - Parameters specifying which store to delete
 * @returns Promise resolving when deletion is complete
 */
function delete(params: DeleteFileSearchStoreParameters): Promise<void>;

interface DeleteFileSearchStoreParameters {
  name: string;
  config?: DeleteFileSearchStoreConfig;
}

interface DeleteFileSearchStoreConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

Usage Example:

await client.fileSearchStores.delete({
  name: 'fileSearchStores/abc123'
});

console.log('Store deleted successfully');

Upload File to File Search Store

Uploads a file asynchronously to a FileSearchStore, returning a long-running operation. Supported upload sources vary by platform:

Node.js: File path (string) or Blob object
Browser: Blob object (e.g., File)

/**
 * Uploads a file asynchronously to a FileSearchStore
 * @param params - Upload parameters including file and destination store
 * @returns Promise resolving to an UploadToFileSearchStoreOperation
 * @throws Error if called on a Vertex AI client
 * @throws Error if mimeType cannot be inferred
 */
function uploadToFileSearchStore(
  params: UploadToFileSearchStoreParameters
): Promise<UploadToFileSearchStoreOperation>;

interface UploadToFileSearchStoreParameters {
  fileSearchStoreName: string;
  file: string | Blob;
  config?: UploadToFileSearchStoreConfig;
}

interface UploadToFileSearchStoreConfig {
  mimeType?: string;
  displayName?: string;
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

interface UploadToFileSearchStoreOperation {
  name?: string;
  done?: boolean;
  response?: UploadToFileSearchStoreResponse;
  error?: Status;
  metadata?: Record<string, unknown>;
}

interface UploadToFileSearchStoreResponse {
  document?: Document;
}

Usage Example:

// Upload from file path (Node.js)
const operation = await client.fileSearchStores.uploadToFileSearchStore({
  fileSearchStoreName: 'fileSearchStores/abc123',
  file: '/path/to/document.pdf',
  config: {
    mimeType: 'application/pdf',
    displayName: 'Important Document'
  }
});

console.log('Upload operation:', operation.name);

// Check operation status
if (operation.done) {
  console.log('Document uploaded:', operation.response?.document?.name);
}

Import File to File Search Store

Imports a file from the File Service to a FileSearchStore as a long-running operation. This method allows you to add files that have already been uploaded via the Files API to a FileSearchStore for search capabilities.

/**
 * Imports a File from File Service to a FileSearchStore
 * @param params - Import parameters including source file and destination store
 * @returns Promise resolving to an ImportFileOperation
 * @throws Error if called on a Vertex AI client
 */
function importFile(params: ImportFileParameters): Promise<ImportFileOperation>;

interface ImportFileParameters {
  file_search_store_name: string;
  file_name: string;
  config?: ImportFileConfig;
}

interface ImportFileConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

interface ImportFileOperation {
  name?: string;
  done?: boolean;
  response?: ImportFileResponse;
  error?: Status;
  metadata?: Record<string, unknown>;
}

interface ImportFileResponse {
  document?: Document;
}

Usage Example:

// First, upload a file using the Files API
const uploadedFile = await client.files.upload({
  file: '/path/to/document.pdf'
});

// Then import it into a FileSearchStore
const operation = await client.fileSearchStores.importFile({
  file_search_store_name: 'fileSearchStores/abc123',
  file_name: uploadedFile.name
});

console.log('Import operation:', operation.name);

Document Management

The FileSearchStores class exposes a nested documents property that provides methods for managing individual documents within a store.

Documents Class

Access document management operations via client.fileSearchStores.documents.

interface FileSearchStores {
  readonly documents: Documents;
}

class Documents {
  list(params: ListDocumentsParameters): Promise<Pager<Document>>;
  get(params: GetDocumentParameters): Promise<Document>;
  delete(params: DeleteDocumentParameters): Promise<void>;
}

List Documents

Lists all documents in a FileSearchStore with pagination support.

/**
 * Lists documents in a FileSearchStore
 * @param params - Parameters including the parent store name
 * @returns Promise resolving to a Pager of Documents
 */
function list(params: ListDocumentsParameters): Promise<Pager<Document>>;

interface ListDocumentsParameters {
  parent: string;
  config?: ListDocumentsConfig;
}

interface ListDocumentsConfig {
  pageSize?: number;
  pageToken?: string;
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

interface Document {
  name?: string;
  displayName?: string;
  mimeType?: string;
  sizeBytes?: string;
  createTime?: string;
  updateTime?: string;
  state?: DocumentState;
  metadata?: Record<string, string>;
}

enum DocumentState {
  DOCUMENT_STATE_UNSPECIFIED = 'DOCUMENT_STATE_UNSPECIFIED',
  PROCESSING = 'PROCESSING',
  ACTIVE = 'ACTIVE',
  FAILED = 'FAILED'
}

Usage Example:

const documents = await client.fileSearchStores.documents.list({
  parent: 'fileSearchStores/abc123',
  config: { pageSize: 20 }
});

for await (const document of documents) {
  console.log('Document:', document.name, document.displayName, document.state);
}

Get Document

Retrieves a specific document by name.

/**
 * Gets a Document
 * @param params - Parameters specifying which document to retrieve
 * @returns Promise resolving to the Document
 */
function get(params: GetDocumentParameters): Promise<Document>;

interface GetDocumentParameters {
  name: string;
  config?: GetDocumentConfig;
}

interface GetDocumentConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

Usage Example:

const document = await client.fileSearchStores.documents.get({
  name: 'fileSearchStores/abc123/documents/doc456'
});

console.log('Document:', document.displayName, document.mimeType, document.sizeBytes);

Delete Document

Deletes a specific document from a FileSearchStore.

/**
 * Deletes a Document
 * @param params - Parameters specifying which document to delete
 * @returns Promise resolving when deletion is complete
 */
function delete(params: DeleteDocumentParameters): Promise<void>;

interface DeleteDocumentParameters {
  name: string;
  config?: DeleteDocumentConfig;
}

interface DeleteDocumentConfig {
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

Usage Example:

await client.fileSearchStores.documents.delete({
  name: 'fileSearchStores/abc123/documents/doc456'
});

console.log('Document deleted successfully');

Using File Search Stores with Generation

File Search Stores can be used with the FileSearch tool during content generation to provide search capabilities over your documents.

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Create a file search store and upload documents
const store = await client.fileSearchStores.create({
  config: { displayName: 'Product Documentation' }
});

await client.fileSearchStores.uploadToFileSearchStore({
  fileSearchStoreName: store.name,
  file: '/path/to/product-guide.pdf'
});

// Use the file search store in generation
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What are the key features mentioned in the product guide?',
  config: {
    tools: [{
      fileSearch: {
        fileSearchStore: store.name
      }
    }]
  }
});

console.log(response.text);

Type Definitions

interface Status {
  code?: number;
  message?: string;
  details?: Array<Record<string, unknown>>;
}

interface ListDocumentsResponse {
  documents?: Document[];
  nextPageToken?: string;
}

interface ListFileSearchStoresResponse {
  fileSearchStores?: FileSearchStore[];
  nextPageToken?: string;
}

Install with Tessl CLI