Skip to content

feat(gemini): refactor Gemini client for ADC/vertex auth and improvements when building with optional LLM provider dependencies#1201

Open
geojaz wants to merge 8 commits intogetzep:mainfrom
geojaz:feat/gemini
Open

feat(gemini): refactor Gemini client for ADC/vertex auth and improvements when building with optional LLM provider dependencies#1201
geojaz wants to merge 8 commits intogetzep:mainfrom
geojaz:feat/gemini

Conversation

@geojaz
Copy link
Copy Markdown
Contributor

@geojaz geojaz commented Feb 6, 2026

Summary

Refactors Gemini client to support both Google AI API (via API key) and Vertex AI (via Application Default Credentials) authentication modes. Also adds conditional
LLM provider dependency installation via Docker build arguments to reduce image size when using specific providers.

Type of Change

  • Bug fix
  • New feature
  • Performance improvement
  • Documentation/Tests

Objective

For new features and performance improvements:

Gemini ADC/Vertex AI Authentication:
Enables enterprise users to authenticate Gemini models using Application Default Credentials (ADC) instead of requiring API keys. This supports:

  • Service account authentication for production deployments
  • Vertex AI access with proper GCP project/location configuration
  • Seamless fallback: API key → GOOGLE_API_KEY env var → ADC
  • Consolidated client initialization logic across GeminiClient, GeminiEmbedder, and GeminiRerankerClient (~150 lines of duplicated code removed)

Docker Build Simplifications:
Adds build arguments to make it easier for users of "optional" LLM providers to build container images with the optional dependencies they need without including all.

Breaking Changes

  • This PR contains breaking changes

Note: No breaking changes.

  • Existing API key authentication continues to work unchanged

  • ADC support is opt-in (triggered when no API key is provided)

  • Docker defaults remain the same (OpenAI dependencies only)

    Checklist

    • Code follows project style guidelines (make lint passes)
    • Self-review completed
    • Documentation updated where necessary
    • No secrets or sensitive information committed

    Documentation updates:

    • Updated CLAUDE.md with Gemini authentication precedence and setup instructions
    • Added comprehensive Docker build examples to mcp_server/README.md
    • Documented GOOGLE_PROJECT_ID and GOOGLE_LOCATION environment variables
    • Added config-docker-falkordb-gemini.yaml template (no hardcoded credentials)

@danielchalef
Copy link
Copy Markdown
Member

danielchalef commented Feb 6, 2026 •
edited
Loading

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@geojaz
Copy link
Copy Markdown
Contributor Author

geojaz commented Feb 6, 2026

I have read the CLA Document and I hereby sign the CLA

danielchalef added a commit that referenced this pull request Feb 6, 2026
@danielchalef
@geojaz has signed the CLA in #1201
52a3421
@geojaz geojaz marked this pull request as draft February 6, 2026 17:30
@geojaz geojaz marked this pull request as ready for review February 6, 2026 19:02
@geojaz geojaz force-pushed the feat/gemini branch 2 times, most recently from 04a0ddb to 23d5f10 Compare February 6, 2026 19:17
@geojaz
Copy link
Copy Markdown
Contributor Author

geojaz commented Feb 7, 2026

Ok, i've validated gemini auth via vertex AI ADC and gemini API key 🚀
hopefully these changes make senses, i've been using it all day in my workflows

lehcode pushed a commit to lehcode/reactive-graphiti that referenced this pull request Feb 8, 2026
@danielchalef @lehcode
@geojaz has signed the CLA in getzep#1201
1507b84
maskshell pushed a commit to maskshell/graphiti that referenced this pull request Feb 9, 2026
@danielchalef @maskshell
@geojaz has signed the CLA in getzep#1201
2206c8d
maskshell pushed a commit to maskshell/graphiti that referenced this pull request Feb 9, 2026
@danielchalef @maskshell
@geojaz has signed the CLA in getzep#1201
b8f3927
maskshell pushed a commit to maskshell/graphiti that referenced this pull request Feb 10, 2026
@danielchalef @maskshell
@geojaz has signed the CLA in getzep#1201
0939ab1
geojaz and others added 8 commits February 15, 2026 11:29
@geojaz
feat(gemini): add Gemini 3 support with ADC authentication and refact…
73e2a5f 
…oring

Add support for Gemini 3 preview models, Application Default Credentials
(ADC) for Vertex AI authentication, and consolidate client initialization
logic across all Gemini components.

Features:
- Update default model to gemini-3-flash-preview
- Add gemini-3-pro-preview and gemini-3-flash-preview to model catalog
- Support ADC authentication via GOOGLE_CLOUD_PROJECT environment variable
- Create shared gemini_utils.py helper to DRY up ~150 lines of duplicated code
- Standardize on Google's GOOGLE_CLOUD_* environment variables

Changes:
- graphiti_core/llm_client/gemini_client.py: Gemini 3 models, use shared helper
- graphiti_core/llm_client/gemini_utils.py: New shared client initialization helper
- graphiti_core/embedder/gemini.py: Refactored to use shared helper
- graphiti_core/cross_encoder/gemini_reranker_client.py: Refactored to use shared helper
- All config files: Use GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION
- All docker-compose files: Pass through GOOGLE_CLOUD_* vars
- All tests: Updated to use GOOGLE_CLOUD_PROJECT in mocks

Authentication modes:
1. API Key (Google AI): Set GOOGLE_API_KEY
2. ADC (Vertex AI): Set GOOGLE_CLOUD_PROJECT + optional GOOGLE_CLOUD_LOCATION

All 63 Gemini tests passing.
@geojaz
feat(docker): add conditional LLM provider dependency installation
b8575b5 
Enable selective installation of LLM provider dependencies via Docker
build arguments to reduce image size and installation time.

Features:
- Add build arguments for optional provider dependencies (all default to false)
- Apply to all Dockerfiles: root, mcp_server/docker/Dockerfile, and Dockerfile.standalone
- Restructure mcp_server/pyproject.toml optional dependencies into individual groups
- Add comprehensive Docker build documentation with examples

Build Arguments:
- INSTALL_GOOGLE_GENAI - Install google-genai for Gemini models
- INSTALL_ANTHROPIC - Install anthropic for Claude models
- INSTALL_GROQ - Install groq for Groq models
- INSTALL_VOYAGEAI - Install voyageai for Voyage embeddings
- INSTALL_SENTENCE_TRANSFORMERS - Install sentence-transformers for local embeddings

Usage:
  # Build with specific providers
  docker build --build-arg INSTALL_GOOGLE_GENAI=true -f Dockerfile .
  docker build --build-arg INSTALL_GOOGLE_GENAI=true -f mcp_server/docker/Dockerfile .

Backward compatible: Default behavior unchanged (no optional providers installed).
@geojaz
chore: update dependencies and documentation
3068f62 
Update google-genai dependency to 1.62.0 to support Gemini 3 models and
update documentation with Gemini authentication guidance.

Changes:
- Bump google-genai from 1.8.0 to 1.62.0 in pyproject.toml
- Add Gemini authentication section to CLAUDE.md
- Update MCP server factories to allow optional API key for ADC
- Update uv.lock with new dependency versions
- Update CLA signature

All tests passing with updated dependencies.
@geojaz
fix: correct docker-compose env var syntax and add Vertex AI support
c1af06f 
- Fix environment variable default syntax (: to :-) for docker-compose compatibility
- Add vertexai: true for Neo4j Gemini config to use Application Default Credentials
- Update FalkorDB config for ADC (commented out pending API key removal)
- Fixes 'invalid interpolation format' error when running docker-compose
@geojaz
fix: correct docker-compose env var syntax and add Vertex AI support
3d5cf2a 
- Fix environment variable default syntax (: to :-) for docker-compose compatibility
- Add vertexai: true for Neo4j Gemini config to use Application Default Credentials
- Update FalkorDB config for ADC (commented out pending API key removal)
- Fixes 'invalid interpolation format' error when running docker-compose
@geojaz
feat(gemini): improve ADC authentication setup and environment handling
7a7b112 
- Update factories.py to set GOOGLE_CLOUD_PROJECT/LOCATION in environment
  when using ADC (no API key provided)
- Add google.auth import attempt to ensure credentials are loaded for ADC
- Add debug logging to gemini_utils.py to trace ADC initialization
- Update config-docker-falkordb-gemini.yaml to document both auth options
  (Google AI API key and Vertex AI ADC) with clear comments
- Create config-docker-neo4j-gemini.yaml for Neo4j backend with ADC support
- Create docker-compose-gemini-adc.yml as alternate composition with full ADC setup
- Fix docker-compose.yml environment variable passing to properly load .env
  configuration without trailing '-' defaults interfering with Vertex AI init
- Add start.sh helper script to properly handle docker-compose --env-file
- Update .env template to clearly document authentication options with
  both Google AI API key (free tier) and Vertex AI ADC (project-based)

The google-genai 1.62.0 library supports Vertex AI initialization via:
  genai.Client(vertexai=True, project=..., location=...)

This change ensures:
1. Environment variables are properly set from config before client init
2. ADC credentials are attempted to be loaded explicitly
3. Docker-compose properly passes env vars from .env file
4. Configuration is clear about both authentication methods
5. Debug logging added to trace initialization flow

Tested: genai.Client(vertexai=True, project, location) works correctly
when GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION are set in environment
@geojaz
fix: Remove explicit auth.default() call in Gemini client initialization
6b19e52 
The explicit call to auth.default() was causing test failures in CI because it attempts to load real credentials from the environment. The google-genai library handles ADC (Application Default Credentials) loading internally when genai.Client is initialized with vertexai=True, so the explicit credential loading is unnecessary.

This fix:
- Removes the google.auth import and HAS_GOOGLE_AUTH flag
- Allows genai.Client to handle credential loading internally
- Fixes all failing Gemini client, embedder, and reranker tests in CI
- All 219 unit tests now pass

The ADC authentication path still works correctly - when vertexai=True is passed without an API key, genai.Client will automatically use Application Default Credentials if available.
@geojaz
local config tweaks
4252f5e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@geojaz @danielchalef