feat: migrate to new google-genai SDK with Gemini 3 support

[quantmind-br]

Summary

This PR completely migrates the Google Generative AI integration from the deprecated google-generativeai SDK to the new official google-genai SDK, covering both LLM generation and embeddings.

Key Changes

🔄 SDK Migration (Complete)

• Replaced google-generativeai with google-genai SDK across all files:
  • simple_chat.py - LLM generation
  • websocket_wiki.py - LLM generation
  • google_embedder_client.py - Embeddings
• Removed google-generativeai dependency entirely from pyproject.toml
• Updated API calls to use the new client-based architecture

🧠 Gemini 3 Thinking Support

• Added thinking_level configuration parameter for Gemini 3 models
• Supports LOW, MEDIUM, and HIGH thinking levels via ThinkingConfig
• Default model updated to gemini-3-flash-preview with thinking_level: high

📊 Embedding Model Update

• Upgraded from deprecated text-embedding-004 to gemini-embedding-001
• Configured output_dimensionality: 3072 for optimal embedding quality
• Migrated GoogleEmbedderClient to use new client.models.embed_content() API

Configuration Changes

generator.json

{
  "google": {
    "default_model": "gemini-3-flash-preview",
    "models": {
      "gemini-3-flash-preview": {
        "temperature": 1.0,
        "top_p": 0.8,
        "top_k": 20,
        "thinking_level": "high"
      }
    }
  }
}

embedder.json

{
  "google": {
    "model_kwargs": {
      "model": "gemini-embedding-001",
      "task_type": "SEMANTIC_SIMILARITY",
      "output_dimensionality": 3072
    }
  }
}

Why This Change?

1. Deprecation: The google-generativeai package is being deprecated in favor of google-genai
2. Consistency: Both generation and embeddings now use the same SDK
3. New Features: Access to Gemini 3's thinking capabilities
4. Better API Design: More consistent client-based architecture
5. Future-Proofing: Single SDK ensures compatibility with upcoming Google AI features

Files Changed

File	Change Type
api/simple_chat.py	SDK migration + thinking support
api/websocket_wiki.py	SDK migration + thinking support
api/google_embedder_client.py	Complete rewrite for new SDK
api/config/generator.json	New model + thinking config
api/config/embedder.json	New embedding model
api/pyproject.toml	Removed google-generativeai
api/poetry.lock	Updated dependencies
api/api.py, api/main.py	Remove unused imports
.cursor/rules/*	IDE conventions for contributors

Test Plan

• Verify chat completions work with Google provider
• Verify WebSocket wiki generation works
• Test with different thinking_level values
• Verify embeddings are generated correctly with new model
• Test fallback behavior on API errors
• Verify no import errors for google-generativeai

---

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @quantmind-br, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly upgrades the project's integration with Google's Generative AI services by adopting the latest google-genai SDK. This migration not only future-proofs the application against deprecations but also unlocks advanced capabilities like Gemini 3's "thinking levels" and an improved embedding model, enhancing the quality and intelligence of AI-generated content and responses.

Highlights

• SDK Migration: Migrated from the deprecated google-generativeai SDK to the new google-genai SDK, updating API calls and client instantiation across the codebase.
• Gemini 3 Support: Introduced support for Gemini 3 models, including a new thinking_level configuration parameter (LOW, MEDIUM, HIGH) and setting gemini-3-flash-preview as the default model with high thinking.
• Embedding Model Upgrade: Updated the default Google embedding model from text-embedding-004 to gemini-embedding-001, configuring it with an output_dimensionality of 3072 for improved quality.
• Enhanced Null-Safety: Improved robustness in streaming responses by adding explicit null-safety checks for chunk.text when processing LLM output.
• New Documentation & Rules: Added AI-generated documentation files (.ai/docs/) covering API, data flow, request flow, and structure analysis, along with Cursor IDE rules and context files (CLAUDE.md, AGENTS.md).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request primarily focuses on updating the Google Generative AI integration, migrating from the deprecated google-generativeai SDK to the newer google-genai SDK for LLM generation. This involved updating api/pyproject.toml and api/poetry.lock to include the new SDK and update related dependencies, removing global configuration in api/main.py, and modifying api/simple_chat.py and api/websocket_wiki.py to use the new client instantiation pattern, including support for thinking_level in Gemini 3 models. The default Google model in api/config/generator.json was updated to gemini-3-flash-preview, and the Google embedder model in api/config/embedder.json was changed to gemini-embedding-001 with added output_dimensionality. Additionally, the pull request introduces extensive new documentation files under .ai/docs/ covering API analysis, data flow, dependency analysis, and request flow, along with new .cursor/rules/ files defining backend, frontend, and project overview conventions, and AGENTS.md and CLAUDE.md for AI agent configuration. Review comments suggest updating the example model in api_analysis.md to reflect the new gemini-3-flash-preview default and clarifying the documentation in api_analysis.md to distinguish between the new google-genai for generation and the continued use of google-generativeai for embeddings, and to fully migrate the embedder client to google-genai for consistency.

I am having trouble creating individual review comments. Click here to see my feedback.

api/pyproject.toml (15-16)

The PR description states that it migrates from the deprecated google-generativeai SDK to the new google-genai. However, google-generativeai is still listed as a dependency and has been updated. The google_embedder_client.py file still uses this deprecated package.

For consistency and future-proofing, it would be best to migrate the embedder client to the new google-genai SDK as well and remove the google-generativeai dependency entirely. This would complete the migration and align with the goal of moving away from the deprecated package.

.ai/docs/api_analysis.md (55)

The documentation mentions gemini-2.5-flash as an example model. Since this PR updates the default model to gemini-3-flash-preview, it would be good to update this example to reflect the new default.

          "models": [{"id": "gemini-3-flash-preview", "name": "gemini-3-flash-preview"}]

.ai/docs/dependency_analysis.md (35-49)

The documentation lists google-generativeai as the dependency for LLM SDKs and Gemini models. This PR migrates to the new google-genai SDK for generation. The documentation should be updated to reflect this change. While google-generativeai is still used for embeddings, google-genai should be listed as the primary SDK for generation.

[secret104278]

seems like we still have dependency from adalflow?

>>> from adalflow import GoogleGenAIClient, OllamaClient
MLflow not available. Install with: pip install mlflow
>>> GoogleGenAIClient()
Traceback (most recent call last):
  File "/opt/venv/lib/python3.11/site-packages/adalflow/utils/lazy_import.py", line 222, in safe_import
    return_modules.append(importlib.import_module(module_name))
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1204, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1176, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1140, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'google.generativeai'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/venv/lib/python3.11/site-packages/adalflow/utils/lazy_import.py", line 155, in load_class
    self.module = importlib.import_module(module_path)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1204, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1176, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1147, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 690, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 940, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/opt/venv/lib/python3.11/site-packages/adalflow/components/model_client/google_client.py", line 15, in <module>
    google = safe_import(
             ^^^^^^^^^^^^
  File "/opt/venv/lib/python3.11/site-packages/adalflow/utils/lazy_import.py", line 224, in safe_import
    raise ImportError(f"{install_message}")
ImportError: Please install google-generativeai with: pip install google-generativeai

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/opt/venv/lib/python3.11/site-packages/adalflow/utils/lazy_import.py", line 168, in __call__
    self.load_class()
  File "/opt/venv/lib/python3.11/site-packages/adalflow/utils/lazy_import.py", line 160, in load_class
    raise ImportError(f"{self.optional_package.error_message}")
ImportError: Please install google-generativeai with: pip install google-generativeai

[quantmind-br]

Thanks for catching this @secret104278!

Root cause: The adalflow framework's GoogleGenAIClient internally imports google.generativeai, which requires the deprecated google-generativeai package.

Solution: I've added google-generativeai back as a transitive dependency in pyproject.toml (commit 1baf317). This is marked as temporary until adalflow migrates to the new SDK.

Important clarification: Our custom code (simple_chat.py, websocket_wiki.py, google_embedder_client.py) uses the new google-genai SDK directly and does not depend on adalflow's GoogleGenAIClient. The dependency is only needed for other adalflow internals that may reference it.

The google-generativeai package will eventually be fully deprecated (Google's deadline is June 2026), so this is a temporary compatibility measure until the adalflow team updates their SDK integration.