Cloud Model Integration (Gemini)
Relevant source files
The following files were used as context for generating this wiki page:
The Cloud Model Integration (Gemini) module provides the platform with advanced reasoning capabilities and internet-connected knowledge by leveraging the Google Gemini API. While the project supports local execution via Phi-3, Gemini acts as the high-performance alternative for complex queries and general knowledge tasks. Sources: README.md, backend/modules/ml/gemini_model.py:1-6
This integration is part of a dual-model architecture where users can switch between a local model and the cloud-based Gemini model. The integration spans the entire stack, from the React frontend for selection, the Node.js orchestration service for context management, to the Python ML backend for API communication. Sources: README.md, ai-assistant-react/src/components/Chat/ChatInterface.jsx:131-149
System Architecture and Request Flow
The Gemini integration follows a three-tier architecture. A request initiated at the frontend passes through an authentication and orchestration layer before reaching the Python wrapper that communicates with Google's Generative AI servers. Sources: README.md, Ai-Assistant-v2/auth-service/server.js:213-288
Sequence of Operation
The following diagram illustrates how a user message is processed when the Gemini model is selected:
Backend Implementation (Python)
The core logic resides in the GeminiModel class within the Python backend. This class wraps the google-generativeai library to handle initialization, prompt construction, and content generation. Sources: backend/modules/ml/gemini_model.py:11-15
Configuration
The model uses specific parameters defined in the global configuration to ensure consistent behavior.
| Parameter | Value | Description |
|---|---|---|
model_name | gemini-flash-latest | The specific Google model version used. |
temperature | 0.7 | Controls randomness (balanced for Gemini). |
max_tokens | 500 | Maximum length of the generated response. |
top_p | 0.95 | Nucleus sampling probability. |
Sources: backend/ml_config/model_config.py:27-33
Prompt Construction Logic
The _build_prompt method formats the input into a structured string that Gemini can interpret. It prepends system instructions, appends the last 5 messages for context, and terminates with the user's current message. Sources: backend/modules/ml/gemini_model.py:85-117
# snippet from backend/modules/ml/gemini_model.py
prompt_parts = [f"System Instructions: {system_prompt}\n\n"]
# ... context inclusion ...
prompt_parts.append(f"User: {user_message}\n")
prompt_parts.append("Assistant:")
return "".join(prompt_parts)
Sources: backend/modules/ml/gemini_model.py:92-117
Orchestration and Context Management (Node.js)
The Node.js auth-service manages the persistent state and decides when to route requests to the Gemini integration. Sources: Ai-Assistant-v2/auth-service/routes/ai.js:14-20
Key Orchestration Steps:
- Model Selection: The service checks the
modelparameter in the request body (defaulting tophi3). Sources: Ai-Assistant-v2/auth-service/routes/ai.js:22 - Context Loading: Retrieves the last 10 messages from MongoDB to provide conversational history. Sources: Ai-Assistant-v2/auth-service/server.js:246-250
- Memory Injection: Performs vector-based search to find relevant long-term user memories and includes them in the payload to the Python service. Sources: Ai-Assistant-v2/auth-service/server.js:231-244
- Python Service Communication: Uses the
aiService.jswrapper to perform an HTTP POST to the Python/generateendpoint. Sources: Ai-Assistant-v2/auth-service/services/aiService.js:21-38
Frontend Integration (React)
The frontend provides the interface for switching between models and displays the Gemini-specific state. Sources: ai-assistant-react/src/components/Chat/ChatInterface.jsx:4-15
Model Switching Flow
The user can toggle the active model through the sidebar. This state is persisted in the backend settings and reflected in the local UI state currentModel. Sources: ai-assistant-react/src/components/Chat/ChatInterface.jsx:131-149
API Reference
Internal Generation Endpoint (Python Backend)
URL: /generate
Method: POST
| Field | Type | Description |
|---|---|---|
prompt | String | The current user input. |
model | String | Must be 'gemini' for cloud processing. |
context | Array | List of message objects {role, text}. |
memories | Array | List of memory objects {fact, importanceScore}. |
Sources: Ai-Assistant-v2/auth-service/server.js:255-260, backend/modules/ml/gemini_model.py:53-62
Error Handling and Fallbacks
The integration includes several layers of safety:
- Initialization Check: If the Gemini API key is missing or initialization fails,
self.is_loadedis set toFalse. Sources: backend/modules/ml/gemini_model.py:44-46 - Fallback Responses: If the API call fails or is not initialized, the system returns predefined fallback strings like "I apologize, but I'm having trouble processing your request right now." Sources: backend/modules/ml/gemini_model.py:68-71, backend/ml_config/model_config.py:55-58
- Service Retries: The Node.js service implements retry logic for calls to the Python service to handle transient network issues. Sources: Ai-Assistant-v2/auth-service/server.js:65-83
Summary
The Cloud Model Integration (Gemini) allows the AI Assistant to transcend local resource limitations. By using a specialized Python wrapper and a robust Node.js orchestration layer, the system provides high-quality, context-aware responses while maintaining the flexibility to switch back to local models for privacy or offline use. Sources: README.md, Ai-Assistant-v2/auth-service/routes/ai.js:142-167