Package: google_cloud_ai_generativelanguage_v1beta
Current Version: 0.2.0
Repository: https://pub.dev/packages/google_cloud_ai_generativelanguage_v1beta

Summary

Google announced the File Search Tool for the Gemini API in November 2025 - a fully managed RAG (Retrieval-Augmented Generation) system. This feature is documented and available via the REST API but is not yet exposed in the Dart SDK.

Official Documentation

• File Search Documentation: https://ai.google.dev/gemini-api/docs/file-search
• Announcement Blog: https://blog.google/technology/developers/file-search-gemini-api/
• Tutorial (Medium): https://medium.com/google-cloud/rag-just-got-much-easier-with-file-search-tool-in-gemini-api-6494f5b1c6bc

What's Missing

1. fileSearch field in the Tool class

The current Tool class (around line 2647 in generativelanguage.dart) supports:

Tool({
  this.functionDeclarations = const [],
  this.googleSearchRetrieval,
  this.codeExecution,
  this.googleSearch,
  this.computerUse,
  this.urlContext,
}) : super(fullyQualifiedName);

Needed: Add fileSearch field similar to how googleSearch is implemented.

2. FileSearch class

Based on the Python/JavaScript SDK and REST API, this class should include:

/// Tool to support file search over uploaded documents.
final class FileSearch extends ProtoMessage {
  /// List of file search store names to search.
  /// Format: `fileSearchStores/{file_search_store_id}`
  final List<String> fileSearchStoreNames;

  /// Optional. Filter search results by metadata.
  /// Uses "key=value" syntax.
  final String? metadataFilter;

  FileSearch({
    this.fileSearchStoreNames = const [],
    this.metadataFilter,
  });
}

3. FileSearchStoreService for store management

Similar to how RetrieverService manages Corpus objects, a new service is needed:

/// Service for managing FileSearchStores.
final class FileSearchStoreService {
  /// Creates a new FileSearchStore.
  Future<FileSearchStore> createFileSearchStore(CreateFileSearchStoreRequest request);

  /// Gets a FileSearchStore.
  Future<FileSearchStore> getFileSearchStore(GetFileSearchStoreRequest request);

  /// Lists FileSearchStores.
  Future<ListFileSearchStoresResponse> listFileSearchStores(ListFileSearchStoresRequest request);

  /// Deletes a FileSearchStore.
  Future<void> deleteFileSearchStore(DeleteFileSearchStoreRequest request);

  /// Uploads a file directly to a FileSearchStore.
  Future<Operation> uploadToFileSearchStore(UploadToFileSearchStoreRequest request);

  /// Imports a file (already uploaded via Files API) into a FileSearchStore.
  Future<Operation> importFile(ImportFileRequest request);
}

4. Supporting types

/// A FileSearchStore is a container for document embeddings.
final class FileSearchStore extends ProtoMessage {
  final String name;
  final String? displayName;
  final DateTime? createTime;
  final DateTime? updateTime;
}

/// Configuration for chunking documents.
final class ChunkingConfig extends ProtoMessage {
  final WhiteSpaceConfig? whiteSpaceConfig;
}

final class WhiteSpaceConfig extends ProtoMessage {
  final int? maxTokensPerChunk;
  final int? chunkOverlapTokens;
}

REST API Reference

Generate Content with File Search

POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent

{
  "contents": [...],
  "tools": [{
    "fileSearch": {
      "fileSearchStoreNames": ["fileSearchStores/abc123"],
      "metadataFilter": "author=John"
    }
  }]
}

File Search Store Management

# Create store
POST https://generativelanguage.googleapis.com/v1beta/fileSearchStores
{ "displayName": "My Documents" }

# Upload file to store
POST https://generativelanguage.googleapis.com/v1beta/{store}/files:upload

# Import existing file
POST https://generativelanguage.googleapis.com/v1beta/{store}/files:import
{ "fileName": "files/abc123" }

# List stores
GET https://generativelanguage.googleapis.com/v1beta/fileSearchStores

# Delete store
DELETE https://generativelanguage.googleapis.com/v1beta/{store}

Comparison with Existing Patterns

The implementation should follow patterns already established in the package:

Python SDK Reference

For implementation reference, here's how the Python SDK exposes this:

# Create store
store = client.file_search_stores.create(
    config={'display_name': 'My Store'}
)

# Upload file
client.file_search_stores.upload_to_file_search_store(
    file='document.pdf',
    file_search_store_name=store.name
)

# Use in generation
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What does the document say?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(
            file_search=types.FileSearch(
                file_search_store_names=[store.name]
            )
        )]
    )
)

# Access citations
print(response.candidates[0].grounding_metadata)

Supported Models

Per documentation, File Search works with:

• gemini-2.5-flash
• gemini-2.5-flash-lite
• gemini-2.5-pro
• gemini-3-pro-preview

File Types Supported

150+ file types including:

• Documents: PDF, DOCX, XLSX, PPTX, ODT, RTF
• Code: Python, JavaScript, Java, C++, Go, Rust, SQL
• Text: Plain text, Markdown, CSV, TSV, XML, JSON
• And more...

Priority

This is a significant feature that enables managed RAG without external vector database dependencies. The Python and JavaScript SDKs already support it, so Dart users are currently blocked from using this capability.

Dartantic Implementation Notes (for when SDK support lands)

Once the SDK adds fileSearch support, Dartantic will need:

Files to Modify

1. google_server_side_tools.dart - Add enum value:

   enum GoogleServerSideTool {
     codeExecution,
     googleSearch,
     fileSearch,  // NEW
   }

2. google_chat_options.dart - Add config:

   class GoogleChatModelOptions {
     final GoogleFileSearchConfig? fileSearchConfig;
   }
   
   class GoogleFileSearchConfig {
     final List<String> fileSearchStoreNames;
     final String? metadataFilter;
   }

3. google_message_mappers.dart - Update toToolList():

   List<gl.Tool>? toToolList({
     required bool enableCodeExecution,
     required bool enableGoogleSearch,
     required bool enableFileSearch,  // NEW
     GoogleFileSearchConfig? fileSearchConfig,  // NEW
   })

4. google_chat_model.dart - Wire up the config

New Example

Create example/bin/server_side_tools_google/server_side_file_search.dart following the pattern from OpenAI's server_side_vector_search.dart