Gemini Force 🚀

A Salesforce-native integration with Google's Gemini AI File Search capabilities

Gemini Force enables Salesforce users to upload documents, have them automatically indexed in Google's Gemini File Search, and then ask natural language questions about their content—all within the Salesforce UI.

✨ Features

• 📤 Single & Batch Upload - Upload one or many files at once with drag-and-drop support
• 🏷️ Flexible Tagging - Apply optional metadata tags to documents for organized retrieval
• 📚 Multi-Store Support - Configure multiple FileSearch Stores for different document categories
• 🔍 AI-Powered Search - Ask natural language questions about your documents
• 💬 Single-File Chat - Chat with individual documents in a conversational interface
• 📑 Multi-File Chat - Query across multiple documents in a single conversation
• 🔄 Real-time Status - Track document processing with live polling updates
• ⚙️ Admin Interface - Manage tag categories through a dedicated admin UI
• 🔐 Secure - API keys stored in Salesforce Custom Settings, never exposed to users

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              Salesforce                                  │
│                                                                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Upload    │  │   Tagging   │  │  Processing │  │    Chat     │    │
│  │  (Single)   │→ │  (Optional) │→ │   Status    │→ │  (Single)   │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
│                                                                          │
│  ┌─────────────────────────┐  ┌─────────────────────────────────────┐  │
│  │     Batch Uploader      │  │         Multi-File Chat             │  │
│  │  (Multiple Files)       │  │  (Query Across Documents)           │  │
│  └─────────────────────────┘  └─────────────────────────────────────┘  │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                    Shared LWC Libraries                           │  │
│  │  gforceUtils │ gforceStatusUtils │ gforceFileService             │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│         │                                                        │      │
│         ↓                                                        ↓      │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                        Apex Services                              │  │
│  │  FileService │ SyncService │ QueryService │ MultiFileQueryService│  │
│  │  StoreService │ HttpClient │ ResponseParser │ SettingsService    │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ↓ HTTPS
┌─────────────────────────────────────────────────────────────────────────┐
│                        Google Cloud Platform                             │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                  Gemini File Search API (v1beta)                  │  │
│  │  ┌─────────────────────┐    ┌─────────────────────────────────┐  │  │
│  │  │  FileSearchStore(s) │    │      generateContent API        │  │  │
│  │  │  (Multi-Store)      │    │   (RAG with File Search Tool)   │  │  │
│  │  └─────────────────────┘    └─────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

📋 Prerequisites

Salesforce

• Salesforce CLI (sf or sfdx)
• A Salesforce org (Developer Edition, Sandbox, or Scratch Org)
• DevHub enabled (for scratch orgs)

Google Cloud Platform

• A GCP project with billing enabled
• gcloud CLI installed and authenticated
• Gemini API enabled on your project

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/bhanudas/gemini-force.git
cd gemini-force

2. Set Up Google Cloud

# Copy the config template
cp gcp/config/setup-config.env.template gcp/config/setup-config.env

# Edit with your GCP project ID
# nano gcp/config/setup-config.env

# Run the setup script
chmod +x gcp/scripts/setup-gemini.sh
./gcp/scripts/setup-gemini.sh

The script will:

• Enable the Gemini API
• Create an API key
• Create a FileSearchStore for your documents
• Output the values you'll need for Salesforce configuration

3. Deploy to Salesforce

# Authenticate with your org
sf org login web --alias my-org

# Deploy the source
sf project deploy start --source-dir force-app/main/default --target-org my-org

# Run tests to verify deployment
sf apex run test --test-level RunLocalTests --target-org my-org --wait 10

4. Configure Integration Settings

After deployment, configure the Custom Settings in Salesforce:

1. Go to Setup → Custom Settings → gforce Integration Settings → Manage
2. Click New (for Org Default)
3. Enter your values:

Field	Description	Example
API Key	Your Gemini API key from GCP	AIzaSy...
FileSearch Store Name	Full store path from setup script	fileSearchStores/gforce-documents-xxxxx
LLM Model	Gemini model to use	gemini-2.5-flash
Max File Size MB	Maximum upload size	12
Max Retries	Retry count for failed uploads	3
Polling Interval Ms	Status check interval	3000
Timeout Seconds	API timeout	120

4b. Configure FileSearch Stores (Optional - Multi-Store)

For multi-store support, add records to the gforce FileSearch Store custom metadata:

1. Go to Setup → Custom Metadata Types → gforce FileSearch Store → Manage Records
2. A default store is included; add additional stores as needed:

Field	Description	Example
Label	Display name	Financial Documents
Store Name	Full Gemini resource path	fileSearchStores/finance-docs-xxxxx
Is Default	Set one store as default	true
Is Active	Enable/disable store	true

5. Assign Permission Sets

# For administrators
sf org assign permset --name gforce_Administrator --target-org my-org

# For standard users
sf org assign permset --name gforce_File_User --target-org my-org

6. Access the App

Navigate to the Gemini Force app in the App Launcher. Available tabs:

Tab	Description
Gemini Assistant	Single-file upload workflow with tagging and chat
Batch Upload	Upload and process multiple files at once
Multi-File Query	Query across multiple documents simultaneously
Gemini Files	List view of all uploaded files
Tag Admin	View configured tag categories
File Tags	Browse applied file tags
Chat Messages	View conversation history

📁 Project Structure

gemini-force/
├── force-app/main/default/
│   ├── applications/          # Lightning App definition
│   ├── classes/               # Apex classes
│   │   ├── gforce_FileService.cls          # File record management
│   │   ├── gforce_SyncService.cls          # Gemini sync operations
│   │   ├── gforce_QueryService.cls         # Single-file query handling
│   │   ├── gforce_MultiFileQueryService.cls # Multi-file query handling
│   │   ├── gforce_StoreService.cls         # FileSearch Store management
│   │   ├── gforce_HttpClient.cls           # API communications
│   │   ├── gforce_ResponseParser.cls       # API response parsing
│   │   ├── gforce_SettingsService.cls      # Configuration management
│   │   ├── gforce_FileSyncQueueable.cls    # Async file processing
│   │   ├── gforce_SyncFinalizer.cls        # Queueable finalizer
│   │   ├── gforce_SyncRetryHelper.cls      # Retry logic helper
│   │   ├── gforce_TestDataFactory.cls      # Test data utilities
│   │   └── *Test.cls                       # Test classes
│   ├── customMetadata/        # Tag definitions & FileSearch Store configs
│   ├── flexipages/            # Lightning App Pages
│   ├── layouts/               # Page Layouts
│   ├── lwc/                   # Lightning Web Components
│   │   ├── gforceFileDashboard/   # Main orchestration component
│   │   ├── gforceFileUploader/    # Single file upload UI
│   │   ├── gforceFileTagging/     # Optional metadata tagging UI
│   │   ├── gforceFileStatus/      # Processing status tracker
│   │   ├── gforceFileChat/        # Single-file chat interface
│   │   ├── gforceBatchUploader/   # Batch file upload UI
│   │   ├── gforceMultiFileChat/   # Multi-file query interface
│   │   ├── gforceTagAdmin/        # Tag administration UI
│   │   ├── gforceUtils/           # Shared logging & utilities
│   │   ├── gforceStatusUtils/     # Status styling helpers
│   │   └── gforceFileService/     # Centralized Apex wrappers
│   ├── objects/               # Custom Objects, Fields & Metadata Types
│   ├── permissionsets/        # Permission Sets
│   ├── remoteSiteSettings/    # Remote Site for Gemini API
│   └── tabs/                  # Custom Tabs (7 total)
├── gcp/
│   ├── config/                # GCP configuration templates
│   └── scripts/               # Setup automation scripts
├── config/                    # Salesforce DX config
└── docs/                      # Architecture documentation

🔧 Development

Creating a Scratch Org

# Create scratch org from DevHub
sf org create scratch --definition-file config/project-scratch-def.json --alias gforce-dev --duration-days 30

# Push source
sf project deploy start --source-dir force-app/main/default --target-org gforce-dev

# Assign permission set
sf org assign permset --name gforce_Administrator --target-org gforce-dev

# Open the org
sf org open --target-org gforce-dev

Running Tests

# Run all tests
sf apex run test --test-level RunLocalTests --target-org gforce-dev --wait 10

# Run specific test class
sf apex run test --class-names gforce_QueryServiceTest --target-org gforce-dev --wait 10

Linting

# Lint LWC components
npm run lint:lwc

# Auto-fix issues
npm run lint:lwc:fix

🔐 Security Notes

• API Keys: Stored in Salesforce Custom Settings (Hierarchy), protected by field-level security
• No hardcoded secrets: All sensitive values are configured post-deployment
• Remote Site Settings: Only the Gemini API endpoint is whitelisted
• Permission Sets: Granular access control for users and administrators

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Salesforce DX
• Powered by Google Gemini AI
• Inspired by the need for seamless document intelligence in Salesforce

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the Salesforce community