VisuaLeaf Config

The VisualLeaf Configuration dialog provides centralized settings management for customizing your MongoDB GUI experience. Configure AI-powered query assistance with multiple ChatGPT model options, set up email notifications via SendGrid integration, manage storage directories for comparison results, and apply theme preferences. All settings are validated in real-time and persisted across sessions for a seamless, personalized experience.

AI Configuration

Configure AI-powered query assistance with OpenAI ChatGPT models. VisualLeaf can help you write MongoDB queries, aggregation pipelines, and explain query results using natural language. You can configure multiple AI configurations with different models and API keys, then select which one to use as the active configuration.

AI Configuration Features

• Multiple AI Configs - Add and manage multiple ChatGPT API keys and models (e.g., one for development, one for production)
• Active Selection - Choose which AI configuration to use as the default across VisualLeaf
• Enable/Disable Toggle - Temporarily disable AI configs without deleting them
• Model Selection - Choose from 10+ ChatGPT models with different capabilities and pricing
• API Key Management - Securely store OpenAI API keys with masked input and show/hide toggle
• Sample Data Control - Configure whether to send sample data to AI for better accuracy or keep it private

AI Configuration Fields

Field	Description	Required
Active AI Configuration	Select which enabled AI configuration to use as the default. Dropdown shows AI type and last 5 characters of API key for identification (e.g., "ChatGPT4o (***xyz12)")	Yes (if any AI configs are enabled)
Enable Toggle	Toggle switch to enable or disable each AI configuration. Disabled configs are hidden from the Active AI Configuration dropdown	N/A
AI Type	OpenAI ChatGPT model to use. Options: ChatGPT4o, ChatGPT4oMini, ChatGPT41, ChatGPT41Mini, ChatGPT4Turbo, ChatGPT4, ChatGPT35Turbo, ChatGPTo1, ChatGPTo1Mini, ChatGPTo1Preview, ChatGPTo3Mini	Yes (if enabled)
API Key	Your OpenAI API key in format "sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx". Input is masked by default with eye icon to toggle visibility. Required field shows red border if enabled but empty	Yes (if enabled)
Send Sample Data	Toggle whether to send sample documents from your collections to AI for better query accuracy. When enabled, shows "Better Accuracy" badge and sends sample data. When disabled, shows "More Private" badge and only sends schema (field names and types)	No (defaults to off)

Available AI Models

Choose the ChatGPT model that best fits your needs:

Latest & Most Capable (Recommended)

• ChatGPT4o - Latest GPT-4 Optimized model with best performance and multimodal capabilities
• ChatGPT4oMini - Smaller, faster version of GPT-4o with lower cost and good performance
• ChatGPTo3Mini - Newest mini model with excellent speed and cost efficiency

Reasoning Models (Advanced)

• ChatGPTo1 - Advanced reasoning model for complex query logic and optimization
• ChatGPTo1Mini - Compact reasoning model with faster inference
• ChatGPTo1Preview - Preview version of O1 with latest experimental features

Previous Generation

• ChatGPT41 - GPT-4.1 with enhanced context understanding
• ChatGPT41Mini - Efficient version of GPT-4.1
• ChatGPT4Turbo - Fast GPT-4 variant optimized for speed
• ChatGPT4 - Original GPT-4 model (stable and reliable)
• ChatGPT35Turbo - GPT-3.5 Turbo (budget-friendly option)

Sample Data Privacy

The "Send sample data to AI" toggle controls what information is shared with OpenAI:

When Enabled (Better Accuracy)

• What's Sent: Collection schema (field names and types) PLUS sample documents from your collections
• Benefit: AI understands your actual data patterns, values, and relationships for more accurate query suggestions
• Use Case: Best for development environments or when working with non-sensitive data
• Visual Indicator: Green "Better Accuracy" badge with checkmark icon

When Disabled (More Private)

• What's Sent: Only collection schema (field names and BSON types like String, Number, Date)
• Limitation: AI cannot see actual data values, so queries may be less accurate or require more refinement
• Use Case: Production environments, sensitive data, or compliance requirements
• Visual Indicator: Blue "More Private" badge with shield icon, plus yellow warning about reduced accuracy

Managing Multiple AI Configurations

• Add AI Config - Click "+ Add AI Config" button to create additional configurations
• Remove Config - Click trash icon to delete a config (must have at least one remaining)
• Active Badge - Selected config shows purple "Active" badge
• Auto-selection - When disabling the active config, VisualLeaf automatically selects another enabled config
• Validation Warning - Yellow warning banner appears if no AI configs are enabled

SendGrid Email Configuration

Configure SendGrid integration for email notifications, alerts, and scheduled report delivery. SendGrid provides reliable transactional email delivery for VisualLeaf's communication features.

SendGrid Configuration Fields

Field	Description	Required
Enable SendGrid	Master toggle to enable or disable SendGrid email integration. When disabled, all SendGrid fields are hidden and email features are unavailable	N/A
SendGrid API Key	Your SendGrid API key in format "SG.xxxxxxxxxxxxxxxxxxxxxxxx". Get this from SendGrid dashboard under Settings > API Keys. Masked password field with eye toggle. Shows red border if enabled but empty	Yes (if SendGrid is enabled)
Sender First Name	First name that appears in the "From" field of sent emails (e.g., "John" in "John Doe")	No
Sender Last Name	Last name that appears in the "From" field of sent emails (e.g., "Doe" in "John Doe")	No
From Email Address	Email address that appears as the sender (e.g., "noreply@yourcompany.com"). Must be verified in SendGrid. Validated with email regex pattern. Shows red border if enabled but invalid	Yes (if SendGrid is enabled)

Setting Up SendGrid

1. Create SendGrid Account: Sign up at sendgrid.com for a free or paid account
2. Generate API Key: In SendGrid dashboard, go to Settings > API Keys > Create API Key. Select "Full Access" or at minimum "Mail Send" permissions
3. Verify Sender Email: In SendGrid, verify your sender email address under Settings > Sender Authentication. SendGrid requires this to prevent spam
4. Copy API Key: Copy the generated API key (starts with "SG.") - you won't be able to see it again
5. Configure VisualLeaf: Paste API key in VisualLeaf configuration, set sender name and verified email address
6. Save & Test: Save configuration and test email functionality to ensure delivery works

Email Use Cases in VisualLeaf

• Export Notifications: Receive email when large export jobs complete
• Scheduled Reports: Email database statistics and monitoring reports on a schedule
• Query Results: Email query or aggregation results to team members
• Alert Notifications: Send alerts when database metrics exceed thresholds
• Backup Confirmations: Confirmation emails for backup and restore operations

Troubleshooting SendGrid

• API Key Invalid: Verify the API key is correct and has "Mail Send" permissions. Check for extra spaces or missing characters
• Sender Not Verified: Email address must be verified in SendGrid Sender Authentication settings before sending
• Email Not Received: Check spam folder, verify recipient email is correct, and review SendGrid Activity feed for delivery status
• Rate Limits: Free SendGrid accounts have daily sending limits. Upgrade plan or reduce email frequency if hitting limits

Storage Settings

Configure local storage directories for VisualLeaf data and temporary files. These settings control where comparison results and other generated files are saved on your local filesystem.

Storage Configuration Fields

Field	Description	Default Value
Compare Results Directory	Local filesystem path where collection comparison results are stored. Comparison HTML reports and diff files are saved here. Change this to organize comparison results in a custom location. Only affects future comparisons (existing results remain in their original location)	~/.visualeaf/compare (expands to user's home directory)

Directory Management Actions

• Browse Directory: Click "Browse" button to open native file picker and select a custom directory. Only directories (not files) can be selected
• Reset to Default: Click reset (undo) button to restore the default ~/.visualeaf/compare directory. Reset button only appears when using a custom path
• View Current Path: Current directory path is displayed in monospace font with "(default)" indicator if using the default location

Understanding Storage Paths

• Default Path (~/.visualeaf/compare): Tilde (~) expands to your home directory (e.g., /Users/username on Mac, C:serssername on Windows). VisualLeaf creates this directory automatically if it doesn't exist
• Custom Path: You can select any directory you have write access to. Useful for storing results on a different drive, network share, or organized project folder
• Future Comparisons Only: Changing the directory only affects new comparison operations. Previously saved results remain in their original location
• Automatic Creation: If the selected directory doesn't exist, VisualLeaf will create it when saving the first comparison result

Storage Best Practices

• Disk Space: Ensure the selected directory has sufficient disk space for comparison results, which can be large for collections with many differences
• Permissions: Verify you have write permissions to the selected directory. VisualLeaf will show an error if it cannot write to the path
• Backup Location: Consider using a directory that's included in your regular backup routine to preserve comparison history
• Organization: Use a dedicated directory for VisualLeaf results to keep them separate from other application data
• Network Drives: You can use network drives or cloud-synced folders, but local drives provide faster performance

Theme Settings

VisualLeaf supports theme customization to match your preferences and reduce eye strain during extended use. Theme settings will be available in a future update.

Planned Theme Features

• Dark Mode: Current default theme with dark backgrounds and high contrast for low-light environments
• Light Mode: Bright theme for well-lit environments and user preference
• Auto Switch: Automatically toggle between dark and light themes based on system preferences or time of day
• Custom Colors: Customize accent colors, syntax highlighting, and UI element colors
• Contrast Adjustment: Adjust contrast levels for accessibility requirements

Configuration Management

VisualLeaf provides validation, reset, and save functionality to ensure configuration integrity.

Validation Rules

The Save Configuration button is disabled until all validation requirements are met:

AI Configuration Validation

• At Least One Enabled: Must have at least one AI configuration enabled and properly configured
• API Key Required: Each enabled AI config must have a non-empty API key
• Active Selection Required: Must select an active AI configuration from the enabled configs
• Valid AI Type: Each config must have a valid AI model type selected

SendGrid Validation (if enabled)

• API Key Required: Must provide SendGrid API key if SendGrid is enabled
• Valid Email Format: From email address must be a valid email format (username@domain.com)
• Email Regex: Uses pattern /^[^\s@]+@[^\s@]+\.[^\s@]+$/ to validate email addresses

Visual Validation Feedback

• Red Borders: Invalid or required empty fields show red border on focus
• Warning Banners: Yellow warning banner appears if no AI configs are enabled
• Disabled Save Button: Save button is grayed out and shows disabled cursor when validation fails
• Focus Ring Colors: Valid fields use blue/purple focus ring, invalid fields use red focus ring

Configuration Actions

• Reset to Defaults: Click "Reset" button in header to restore all settings to factory defaults. This clears all AI configs, disables SendGrid, and resets storage paths. Use with caution!
• Save Configuration: Click "Save Configuration" button (only enabled when validation passes) to persist all changes. Shows success toast notification on save
• Cancel: Click "Cancel" button or close modal to discard changes and revert to last saved configuration

Persistence & Loading

• Auto-load: Configuration is automatically loaded when opening the dialog
• Persistent Storage: Settings are saved to VisualLeaf's configuration file and persist across app restarts
• Modal Data: Can be initialized with specific configuration data when opened from different contexts
• Real-time Validation: Validation runs continuously as you type to provide immediate feedback

Pro Tips

1. Multiple AI Models: Configure multiple AI configs with different models (e.g., ChatGPT4o for complex queries, ChatGPT4oMini for quick assistance) and switch between them based on your task.
2. Privacy vs Accuracy: For production data, disable "Send sample data to AI" to keep data private. For development, enable it for more accurate AI suggestions. You can have different configs for different environments.
3. API Key Organization: Use descriptive AI model names to identify configs easily. The last 5 characters of API key help distinguish multiple keys at a glance.
4. SendGrid Testing: After configuring SendGrid, test with a simple email to yourself before relying on it for production notifications. Check SendGrid Activity dashboard for delivery status.
5. Email Verification: Always verify your sender email address in SendGrid before configuring VisualLeaf. Unverified addresses cannot send emails and will cause errors.
6. Storage Organization: Use a custom compare results directory that's organized by project or environment (e.g., ~/projects/myapp/visualeaf-compares) for better file management.
7. Backup Config Before Reset: If you're experimenting with settings, note down your working configuration before clicking Reset. There's no undo for the reset operation.
8. Validation Feedback: Watch for red borders and disabled Save button to identify which fields need attention. Hover over fields to see validation messages if applicable.
9. Cost Management: If using OpenAI API, monitor your usage in OpenAI dashboard. Use mini models (ChatGPT4oMini, ChatGPTo3Mini) for cost-effective AI assistance without sacrificing too much quality.
10. Network Paths: While you can use network drives for storage, local drives offer better performance for comparison results. Consider network drives only for shared team access to results.

Related Features

• Collection Activity - Use AI assistance to write queries and filters for collection browsing with natural language prompts
• Aggregation Pipeline - AI can help construct complex aggregation pipelines by understanding your requirements in plain English
• MongoDB Shell - Get AI suggestions for MongoDB shell commands and query syntax
• Collection Compare - Compare collections and save results to the configured storage directory for later review
• Export Data - Configure SendGrid to receive email notifications when long-running export jobs complete
• Database Statistics - Schedule email delivery of statistics reports using SendGrid integration