Overview
Flow ID: llm-model-upload
Category: Model Management
Estimated Duration: 5-30 minutes (depending on file size)
User Role: All Users
Complexity: Simple
Purpose: This flow allows users to add a new AI language model to the application. Models are required to enable chat functionality. The model file is uploaded from your computer to the application and becomes available for use in conversations.
Related Flows
- Select Active Chat Model - Choose this model for use in conversations
- Run Full Benchmark Suite - Test this model's performance
- View Model Information - View details about the uploaded model
- Delete a Model - Remove this model if no longer needed
- Upload Embedding Model - Similar process for different model type
Prerequisites
Before starting, users must have:
- Application installed and running
- A compatible AI model file saved on their computer (formats like .gguf or other supported formats)
- Sufficient disk space to store the model (models typically range from 2GB to 50GB+)
- Knowledge of where the model file is located on their computer
Step-by-Step Flow
Main Path (Happy Path)
Step 1: Navigate to Settings
- User Action: From any page in the application, click the "Settings" menu item in the navigation
- System Response: The Settings page loads and displays
- UI Elements Visible:
- Navigation menu with "Settings" highlighted
- Settings page content area
- Multiple tabs across the top of the settings area
- Visual Cues: Settings icon (gear symbol) appears in navigation, Settings tab is visually distinguished when active
Step 2: Access Chat AI Models Tab
- User Action: Click on the "Chat AI Models" tab at the top of the Settings page
- System Response: The Chat AI Models section displays, showing any existing models in a table or list format
- UI Elements Visible:
- "Chat AI Models" tab (now highlighted/active)
- List or table of existing models (if any have been uploaded)
- "Add Model" button (typically prominent, may be colored blue)
- Model information columns: Name, Type, Path, Actions
- Visual Cues: Active tab is visually distinct (underlined or highlighted), Add Model button stands out with color
Step 3: Initiate Model Upload
- User Action: Click the "Add Model" button
- System Response: A modal dialog (overlay window) appears on top of the current page
- UI Elements Visible:
- Modal window with title "Upload Model" or similar
- File upload area/button
- Text input field for Model Name
- Dropdown or selection field for Model Type
- "Cancel" and "Save" buttons at the bottom
- Close button (X) in the upper corner
- Visual Cues: Page behind the modal may be slightly dimmed, modal is centered and prominent
Step 4: Select Model File
- User Action: Click the "Choose File" or file upload button/area in the modal
- System Response: Operating system's file browser dialog opens
- UI Elements Visible:
- Native file browser window (appearance depends on operating system)
- File navigation interface
- File type filters (may show only compatible model formats)
- Visual Cues: Standard operating system file browser appearance
Step 5: Navigate to and Select File
- User Action: Browse through folders to locate the model file, then click on the desired file and click "Open" or equivalent
- System Response:
- File browser closes
- Modal dialog reappears
- Selected filename now appears in the file upload area
- Model Name field auto-populates based on the filename
- Model Type field may auto-populate to "Large Language Model"
- UI Elements Visible:
- Selected filename displayed (possibly with full path or just the filename)
- Model Name field filled with extracted name
- Model Type field showing "Large Language Model"
- Save button (may become enabled if it was disabled)
- Visual Cues: File selection area shows the selected file, fields are populated, visual indication that the form is complete
Step 6: Review and Adjust Model Information
- User Action: Review the auto-populated Model Name and Model Type; edit the Model Name if desired (Type typically stays as-is)
- System Response: Text updates in real-time as user types
- UI Elements Visible:
- Editable text field for Model Name (cursor appears when clicked)
- Model Type field (may be read-only or selectable)
- Character count or field validation indicators (if applicable)
- Visual Cues: Active text field is highlighted when clicked, cursor blinking indicates edit mode
Step 7: Confirm and Save
- User Action: Click the "Save" button at the bottom of the modal
- System Response:
- Modal content changes to show upload progress
- Progress bar appears and begins filling
- Percentage or status text may display (e.g., "Uploading... 15%")
- UI Elements Visible:
- Progress bar (animated, filling from left to right)
- Percentage text (updates as upload progresses)
- Status message (e.g., "Uploading model...")
- Cancel or Close button may become disabled during upload
- Visual Cues: Progress bar animation, percentage increasing, may show file size information
Step 8: Wait for Upload Completion
- User Action: Wait while the file uploads (no interaction required; user should not close the application)
- System Response:
- Progress bar continues advancing
- Percentage updates regularly
- May show upload speed or estimated time remaining
- UI Elements Visible:
- Continuously updating progress indicator
- Current status information
- Visual Cues: Animated progress bar provides visual feedback that the system is working
Step 9: Upload Completes Successfully
- User Action: No action required
- System Response:
- Progress reaches 100%
- Success message displays (e.g., "Model uploaded successfully!")
- Modal automatically closes after a brief moment (1-2 seconds) OR requires user to click "Done"
- User returns to the Settings page, Chat AI Models tab
- UI Elements Visible:
- Success message (may be green with checkmark icon)
- Settings page with updated model list
- Newly uploaded model now appears in the models table
- Visual Cues: Green color and checkmark indicate success, smooth transition back to main view
Step 10: Verify Model in List
- User Action: Look at the models list to confirm the new model appears
- System Response: Model list displays with the new model included
- UI Elements Visible:
- Table or list showing all models
- New model entry with Name, Type (Large Language Model), Path, and action buttons
- Model may have a status indicator showing it's ready to use
- Visual Cues: New model may be highlighted or positioned at the top of the list
Final Step: Model Ready for Use
- Success Indicator:
- Model appears in the models list
- Model can be selected as the active chat model
- No error messages are displayed
- System State Change:
- Model file is now stored locally in the application's data directory
- Model is registered in the application's database
- Model is available for selection in chat settings
- Next Possible Actions:
- Select this model as the active chat model
- Upload additional models
- Start a new chat using this model (if it's been set as active)
- Run benchmarks on this model to test performance
Alternative Paths & Strategies
Strategy A: Drag and Drop Upload
When to use: If the application supports drag-and-drop and the user finds it more convenient than clicking
Steps:
- Open the Settings page and navigate to Chat AI Models tab
- Click "Add Model" to open the upload modal
- Open file browser in a separate window to locate the model file
- Drag the model file from the file browser and drop it into the file upload area of the modal
- Model Name and Type auto-populate
- Click "Save" to begin upload
- Wait for completion (same as main path from Step 8)
Strategy B: Replace Existing Model
When to use: User wants to update an existing model with a new version
Steps:
- Navigate to Settings > Chat AI Models
- Locate the existing model in the list
- Click "Delete" or "Remove" button on the existing model
- Confirm deletion if prompted
- Follow main path steps 3-10 to upload the new version
Strategy C: Upload During Onboarding
When to use: First-time users during initial application setup
Steps:
- Application launches onboarding wizard
- Onboarding step prompts for model upload
- Embedded upload interface appears (similar to modal)
- Follow main path steps 4-9 within onboarding context
- Onboarding wizard advances to next step automatically
Error States & Recovery
Error 1: Incompatible File Format
Cause: User selected a file that is not a supported model format
User Experience:
- Error message appears after selecting file or during upload
- Message states: "Incompatible file format" or "This file type is not supported"
- Upload does not proceed
Recovery Steps:
- Read the error message carefully
- Click "OK" or close the error message
- Verify you have the correct model file (should be .gguf or other supported format)
- Click "Choose File" again and select the correct file
- If error persists, check model file documentation to confirm format compatibility
Error 2: Insufficient Disk Space
Cause: Not enough free space on the device to store the model
User Experience:
- Error message appears during upload, possibly when progress reaches a certain point
- Message states: "Insufficient disk space" or similar
- Upload stops and may roll back
Recovery Steps:
- Close the upload modal
- Free up disk space by deleting unnecessary files or moving them to external storage
- Return to Settings and restart the upload process
- Consider uploading a smaller model if disk space remains limited
Error 3: Upload Interrupted
Cause: Network disconnection, application crash, or user accidentally closed window
User Experience:
- Upload progress stops advancing
- Error message may appear: "Upload failed" or "Connection lost"
- Modal may close unexpectedly
Recovery Steps:
- Check if the model appears in the models list (partial uploads are typically removed automatically)
- Verify your computer is functioning normally (no crashes or freezes)
- Restart the upload process from Step 3 of the main path
- Ensure you don't close the application window during upload
Error 4: File Not Found
Cause: User moved or deleted the model file after selecting it but before upload completed
User Experience:
- Error message: "File not found" or "Cannot access file"
- Upload fails to start or stops immediately
Recovery Steps:
- Close the error message
- Locate the model file in your computer's file system
- Ensure the file has not been moved or deleted
- Restart the upload process and select the file from its current location
Error 5: Model Name Already Exists
Cause: A model with the same name already exists in the system
User Experience:
- Error message appears when trying to save: "Model name already exists" or similar
- Upload does not proceed
Recovery Steps:
- Read the error message
- Edit the Model Name field to use a different, unique name (e.g., add a version number or date)
- Click "Save" again
- Upload should proceed normally with the new name
Version History
| Date | Version | Author | Changes |
|---|---|---|---|
| 2025-10-04 | 1.1 | Iternal Technologies | Initial documentation with comprehensive detail |
Notes
Important Considerations:
- Model files can be very large (5-50GB+); ensure adequate disk space and stable connection
- Once uploaded, the model file is copied to the application's data directory; the original file can be safely deleted or moved
- The application must remain open and running during the entire upload process
- Multiple models can be uploaded, but only one can be active for chat at a time
- Model upload does not automatically select the model as active; this is a separate step
Common User Questions:
- "Where should I get model files?" - Models must be obtained from external sources; the application does not provide model downloads
- "How do I know if a model is compatible?" - Check the model documentation; AirgapAI typically supports GGUF and other quantized formats
- "Can I use the application while uploading?" - Yes, you can navigate to other pages, but don't close the application
- "What happens to the original file?" - It remains in its original location; the application creates its own copy
Trigger
What initiates this flow:
- User manually initiates
Specific trigger: User needs to add a new language model to use for AI conversations, either because:
- This is their first time using the application and no models are available
- They want to add an additional or alternative model to their collection
- They are replacing an existing model with an updated version
User Intent Analysis
Primary Intent
Upload and make available a new AI language model for conducting chat conversations.
Secondary Intents
- Build a library of different models with varying capabilities
- Test different models to find one that best suits their needs
- Ensure offline AI capability by having models locally available
- Prepare the system for benchmarking different models
Subintents
- Verify the model file is compatible before upload
- Ensure the model name is clearly identifiable for future selection
- Confirm the model type is correctly categorized