Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Gemini Embedding 2 provider using the official google-genai SDK."""
from typing import Any, Dict, Optional
from google import genai
from google.genai import types
from google.genai.errors import APIError, ClientError
try:
from google.genai.types import HttpOptions, HttpRetryOptions
_HTTP_RETRY_AVAILABLE = True
except ImportError:
_HTTP_RETRY_AVAILABLE = False
from openviking.models.embedder.base import (
DenseEmbedderBase,
EmbedResult,
truncate_and_normalize,
)
from openviking.models.model_error import model_error_boundary
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
# Keep for backward-compat with existing unit tests that import it
_GEMINI_INPUT_TOKEN_LIMIT = 8192 # Gemini Embedding 2 hard limit
# Per-model token limits (Google API hard limits, from official docs)
_MODEL_TOKEN_LIMITS: Dict[str, int] = {
"gemini-embedding-2": 8192,
"gemini-embedding-2-preview": 8192,
"gemini-embedding-001": 2048,
}
_DEFAULT_TOKEN_LIMIT = 2048 # conservative fallback for unknown future models
# Stable Embedding 2 uses text instructions instead of task_type/title fields.
# https://ai.google.dev/gemini-api/docs/embeddings#task-types
_TASK_INSTRUCTIONS: Dict[str, str] = {
"RETRIEVAL_QUERY": "task: search result | query: {text}",
"RETRIEVAL_DOCUMENT": "title: {title} | text: {text}",
"SEMANTIC_SIMILARITY": "task: sentence similarity | query: {text}",
"CLASSIFICATION": "task: classification | query: {text}",
"CLUSTERING": "task: clustering | query: {text}",
"QUESTION_ANSWERING": "task: question answering | query: {text}",
"FACT_VERIFICATION": "task: fact checking | query: {text}",
"CODE_RETRIEVAL_QUERY": "task: code retrieval | query: {text}",
}
_VALID_TASK_TYPES: frozenset = frozenset(_TASK_INSTRUCTIONS)
_ERROR_HINTS: Dict[int, str] = {
400: "Invalid request — check model name and task_type value.",
401: "Invalid API key. Verify your GOOGLE_API_KEY or api_key in config.",
403: "Permission denied. API key may lack access to this model.",
404: "Model not found: '{model}'. Check spelling (e.g. 'gemini-embedding-2').",
429: "Resource exhausted. Wait and retry.",
500: "Gemini service error (Google-side). Retry after a delay.",
503: "Gemini service unavailable. Retry after a delay.",
}
def _raise_api_error(e: APIError, model: str) -> None:
hint = _ERROR_HINTS.get(e.code, "")
# Gemini returns HTTP 400 (not 401) when the API key is invalid
if e.code == 400 and "api key" in str(e).lower():
hint = "Invalid API key. Verify your GOOGLE_API_KEY or api_key in config."
msg = f"Gemini embedding failed (HTTP {e.code})"
if hint:
msg += f": {hint.format(model=model)}"
raise RuntimeError(msg) from e
class GeminiDenseEmbedder(DenseEmbedderBase):
"""Dense embedder backed by Google's Gemini Embedding models.
REST endpoint: /v1beta/models/{model}:embedContent (SDK handles Parts format internally).
Input token limit: per-model (8192 for gemini-embedding-2, 2048 for gemini-embedding-001).
Output dimension: 1–3072 (MRL; recommended 768, 1536, 3072; default 3072).
Task types: RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION,
CLUSTERING, CODE_RETRIEVAL_QUERY, QUESTION_ANSWERING, FACT_VERIFICATION.
Non-symmetric: use query_param/document_param in EmbeddingModelConfig.
"""
# Default output dimensions per model (used when user does not specify `dimension`).
# gemini-embedding-2: 3072 MRL model — supports 1–3072 via output_dimensionality
# gemini-embedding-2-preview: 3072 MRL model retained for explicit legacy configurations
# gemini-embedding-001: 3072 (native 768-dim vectors; 3072 shown as default for MRL compat)
# text-embedding-004: 768 fixed-dim legacy model, does not support MRL truncation
# Future gemini-embedding-*: default 3072 via _default_dimension() fallback
# Future text-embedding-*: default 768 via _default_dimension() prefix rule
supports_multimodal: bool = False # text-only; multimodal planned separately
KNOWN_DIMENSIONS: Dict[str, int] = {
"gemini-embedding-2": 3072,
"gemini-embedding-2-preview": 3072,
"gemini-embedding-001": 3072,
"text-embedding-004": 768,
}
@classmethod
def _default_dimension(cls, model: str) -> int:
"""Return default output dimension for a Gemini model.
Lookup order:
1. Exact match in KNOWN_DIMENSIONS
2. Prefix rule: text-embedding-* → 768 (legacy fixed-dim series)
3. Fallback: 3072 (gemini-embedding-* MRL models)
Examples:
gemini-embedding-2 → 3072 (exact match)
gemini-embedding-2-preview → 3072 (exact match)
text-embedding-004 → 768 (exact match)
text-embedding-005 → 768 (prefix rule — future model)
"""
if model in cls.KNOWN_DIMENSIONS:
return cls.KNOWN_DIMENSIONS[model]
if model.startswith("text-embedding-"):
return 768
return 3072
def __init__(
self,
model_name: str = "gemini-embedding-2",
api_key: Optional[str] = None,
dimension: Optional[int] = None,
task_type: Optional[str] = None,
query_param: Optional[str] = None,
document_param: Optional[str] = None,
config: Optional[Dict[str, Any]] = None,
):
super().__init__(model_name, config)
self.provider = "gemini"
if not api_key:
raise ValueError("Gemini provider requires api_key")
if task_type and task_type not in _VALID_TASK_TYPES:
raise ValueError(
f"Invalid task_type '{task_type}'. "
f"Valid values: {', '.join(sorted(_VALID_TASK_TYPES))}"
)
if dimension is not None and not (1 <= dimension <= 3072):
raise ValueError(f"dimension must be between 1 and 3072, got {dimension}")
self._client_kwargs: Dict[str, Any] = {"api_key": api_key}
if _HTTP_RETRY_AVAILABLE:
self._client_kwargs["http_options"] = HttpOptions(
retry_options=HttpRetryOptions(attempts=1)
)
self.client = genai.Client(**self._client_kwargs)
self.task_type = task_type
self.query_param = query_param
self.document_param = document_param
self._dimension = dimension or self._default_dimension(model_name)
self._token_limit = _MODEL_TOKEN_LIMITS.get(model_name, _DEFAULT_TOKEN_LIMIT)
def _prepare_request(
self,
text: str,
is_query: bool = False,
*,
task_type: Optional[str] = None,
title: Optional[str] = None,
) -> tuple[str, types.EmbedContentConfig]:
"""Build the model-specific text and request config."""
if task_type is None:
task_type = self.query_param if is_query else self.document_param
effective_task_type = task_type or self.task_type
task_type = effective_task_type.upper() if effective_task_type else None
config = types.EmbedContentConfig(output_dimensionality=self._dimension)
if self.model_name == "gemini-embedding-2":
if task_type and task_type not in _VALID_TASK_TYPES:
raise ValueError(
f"Invalid task_type '{effective_task_type}'. "
f"Valid values: {', '.join(sorted(_VALID_TASK_TYPES))}"
)
if task_type or title:
text = _TASK_INSTRUCTIONS[task_type or "RETRIEVAL_DOCUMENT"].format(
text=text, title=title or "none"
)
else:
config.task_type = task_type
config.title = title or None
return text, config
def __repr__(self) -> str:
return (
f"GeminiDenseEmbedder("
f"model={self.model_name!r}, "
f"dim={self._dimension}, "
f"task_type={self.task_type!r})"
)
@model_error_boundary
def embed(
self,
text: str,
is_query: bool = False,
*,
task_type: Optional[str] = None,
title: Optional[str] = None,
) -> EmbedResult:
if not text or not text.strip():
logger.warning("Empty text passed to embed(), returning zero vector")
return EmbedResult(dense_vector=[0.0] * self._dimension)
text, config = self._prepare_request(text, is_query, task_type=task_type, title=title)
# SDK accepts plain str; converts to REST Parts format internally.
def _call() -> EmbedResult:
result = self.client.models.embed_content(
model=self.model_name,
contents=text,
config=config,
)
vector = truncate_and_normalize(list(result.embeddings[0].values), self._dimension)
return EmbedResult(dense_vector=vector)
try:
result = self._run_once(
_call,
logger=logger,
operation_name="Gemini embedding",
)
# Estimate token usage
estimated_tokens = self._estimate_tokens(text)
self.update_token_usage(
model_name=self.model_name,
provider="gemini",
prompt_tokens=estimated_tokens,
completion_tokens=0,
)
return result
except (APIError, ClientError) as e:
_raise_api_error(e, self.model_name)
@model_error_boundary
async def embed_async(
self,
text: str,
is_query: bool = False,
*,
task_type: Optional[str] = None,
title: Optional[str] = None,
) -> EmbedResult:
if not text or not text.strip():
logger.warning("Empty text passed to embed_async(), returning zero vector")
return EmbedResult(dense_vector=[0.0] * self._dimension)
text, config = self._prepare_request(text, is_query, task_type=task_type, title=title)
async def _call() -> EmbedResult:
# Keep creation, use and cleanup on the calling event loop.
# Account embedders are shared by HTTP and background worker loops.
with genai.Client(**self._client_kwargs) as client:
async with client.aio as async_client:
result = await async_client.models.embed_content(
model=self.model_name,
contents=text,
config=config,
)
vector = truncate_and_normalize(list(result.embeddings[0].values), self._dimension)
return EmbedResult(dense_vector=vector)
try:
result = await self._run_once_async(
_call,
is_query=is_query,
logger=logger,
operation_name="Gemini async embedding",
)
estimated_tokens = self._estimate_tokens(text)
self.update_token_usage(
model_name=self.model_name,
provider="gemini",
prompt_tokens=estimated_tokens,
completion_tokens=0,
)
return result
except (APIError, ClientError) as e:
_raise_api_error(e, self.model_name)
def get_dimension(self) -> int:
return self._dimension
def close(self):
self.client.close()