specs/006-gemini-api-migration/data-model.md

Data Model: Gemini API Migration

Feature Branch: 006-gemini-api-migration Created: 2025-12-14

Overview

This migration does not introduce new database entities. It replaces the AI service layer implementation while maintaining existing data contracts.

Service Classes

GeminiService (replaces OpenAIService)

File: app/services/gemini_service.py

Attribute	Type	Description
client	genai.Client	Google GenAI client instance
model	str	Default model: "gemini-2.0-flash-exp"

Methods (signature-compatible with OpenAIService):

Method	Parameters	Return Type	Description
get_chat_response	prompt: str, history: List[dict] = None	str	Generate chat response using Gemini
translate_to_urdu	content: str	str	Translate English to Urdu
personalize_content	content: str, software_level: str, hardware_level: str, learning_goals: str	dict	Personalize content based on user profile

EmbeddingsService (modified)

File: app/services/embeddings_service.py

Attribute	Type	Description
client	genai.Client	Google GenAI client instance
model	str	"text-embedding-004"

Methods:

Method	Parameters	Return Type	Description
create_embedding	text: str	List[float]	Generate embedding vector for text

Configuration Changes

Settings Class (app/config.py)

Removed Fields:

• OPENAI_API_KEY: str
• OPENAI_MODEL_CHAT: str
• OPENAI_MODEL_EMBEDDING: str

Added Fields:

• GEMINI_API_KEY: str
• GEMINI_MODEL_CHAT: str = "gemini-2.0-flash-exp"
• GEMINI_MODEL_EMBEDDING: str = "text-embedding-004"

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	Yes	Google AI API key for Gemini services
OPENAI_API_KEY	Removed	No longer required

Data Flow (Unchanged)

Request → Route → Service (GeminiService) → Google Gemini API → Response
                       ↓
                    EmbeddingsService → Gemini text-embedding-004
                       ↓
                    Qdrant (unchanged)

Embedding Dimension Change

Service	Model	Dimensions
OpenAI (current)	text-embedding-3-small	1536
Gemini (new)	text-embedding-004	768

Impact: Existing Qdrant collections indexed with OpenAI embeddings are incompatible with Gemini embeddings. Re-indexing is out of scope per specification.

Message Format Mapping

Chat History Conversion

OpenAI Format (input from routes):

[
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
]

Gemini Format (internal conversion):

# System message → system_instruction config
# user → user
# assistant → model
[
    types.Content(role="user", parts=[types.Part(text="...")]),
    types.Content(role="model", parts=[types.Part(text="...")])
]

No Schema Changes

This migration does not modify:

• Database tables
• Pydantic request/response models
• API endpoint signatures
• Route patterns