Feature Request: Add File Search Tool Support

**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:

```dart
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:

```dart
/// 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 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:

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

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

/// Lists FileSearchStores.
Future listFileSearchStores(ListFileSearchStoresRequest request);

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

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

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

### 4. Supporting types

```dart
/// 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:

| Existing | New (File Search) |
|----------|------------------|
| `Tool.googleSearch` | `Tool.fileSearch` |
| `Tool_GoogleSearch` | `FileSearch` |
| `RetrieverService` | `FileSearchStoreService` |
| `Corpus` | `FileSearchStore` |
| `queryCorpus()` | (handled via generateContent) |

## Python SDK Reference

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

```python
# 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:
```dart
enum GoogleServerSideTool {
codeExecution,
googleSearch,
fileSearch, // NEW
}
```

2. **`google_chat_options.dart`** - Add config:
```dart
class GoogleChatModelOptions {
final GoogleFileSearchConfig? fileSearchConfig;
}

class GoogleFileSearchConfig {
final List fileSearchStoreNames;
final String? metadataFilter;
}
```

3. **`google_message_mappers.dart`** - Update `toToolList()`:
```dart
List? 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`