Python: Add Google AI package scaffolding

.gitignore

@@ -211,4 +211,8 @@ WARP.md
 **/frontend/dist/
 
 # Database files
-*.db
+*.db
+
+# Package development docs (internal use only)
+**/GAP_ANALYSIS.md
+**/PR*_CHECKLIST.md

python/packages/google/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/google/README.md

@@ -0,0 +1,179 @@
+# Get Started with Microsoft Agent Framework Google
+
+> **Note**: This package is currently under active development. The chat client implementations for Google AI and Vertex AI are coming soon. This initial release provides the foundational settings and configuration classes.
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-google --pre
+```
+
+## Google AI & Vertex AI Integration
+
+This package will provide integration with Google's generative AI platforms:
+
+- **Google AI (Gemini API)**: Direct access to Google's Gemini models with API key authentication
+- **Vertex AI**: Enterprise-grade access via Google Cloud Platform with advanced features like grounding and code execution
+
+### Current Status
+
+**Available Now:**
+- `GoogleAISettings`: Configuration class for Google AI (Gemini API) authentication and settings
+- `VertexAISettings`: Configuration class for Vertex AI authentication and settings
+
+**Coming Soon:**
+- `GoogleAIChatClient`: Chat client for Google AI with streaming, function calling, and multi-modal support
+- `VertexAIChatClient`: Enterprise chat client with grounding (Google Search) and code execution capabilities
+- Integration tests and usage samples
+
+### Configuration
+
+You can configure the settings classes now, which will be used by the chat clients in the next release:
+
+#### Google AI Settings
+
+```python
+from agent_framework_google import GoogleAISettings
+
+# Configure via environment variables
+# GOOGLE_AI_API_KEY=your_api_key
+# GOOGLE_AI_CHAT_MODEL_ID=gemini-1.5-pro
+
+settings = GoogleAISettings()
+
+# Or pass parameters directly
+settings = GoogleAISettings(
+    api_key="your_api_key",
+    chat_model_id="gemini-1.5-pro"
+)
+```
+
+#### Vertex AI Settings
+
+```python
+from agent_framework_google import VertexAISettings
+
+# Configure via environment variables
+# VERTEX_AI_PROJECT_ID=your-project-id
+# VERTEX_AI_LOCATION=us-central1
+# VERTEX_AI_CHAT_MODEL_ID=gemini-1.5-pro
+# GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+
+settings = VertexAISettings()
+
+# Or pass parameters directly
+settings = VertexAISettings(
+    project_id="your-project-id",
+    location="us-central1",
+    chat_model_id="gemini-1.5-pro"
+)
+```
+
+### Future Usage (Coming Soon)
+
+Once the chat clients are released, usage will look like this:
+
+#### Google AI (Gemini API)
+
+Use Google AI for straightforward access to Gemini models with API key authentication.
+
+```python
+from agent_framework.google import GoogleAIChatClient
+
+# Configure via environment variables
+# GOOGLE_AI_API_KEY=your_api_key
+# GOOGLE_AI_CHAT_MODEL_ID=gemini-1.5-pro
+
+client = GoogleAIChatClient()
+agent = client.create_agent(
+    name="Assistant",
+    instructions="You are a helpful assistant"
+)
+
+response = await agent.run("Hello!")
+print(response.text)
+```
+
+#### Vertex AI (Coming Soon)
+
+Use Vertex AI for enterprise features including grounding with Google Search and code execution.
+
+```python
+from agent_framework.google import VertexAIChatClient
+from agent_framework import HostedWebSearchTool
+
+# Configure via environment variables
+# VERTEX_AI_PROJECT_ID=your-project-id
+# VERTEX_AI_LOCATION=us-central1
+# VERTEX_AI_CHAT_MODEL_ID=gemini-1.5-pro
+# GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+
+client = VertexAIChatClient()
+agent = client.create_agent(
+    name="Assistant",
+    instructions="You are a helpful assistant",
+    tools=[HostedWebSearchTool()]  # Vertex AI exclusive
+)
+
+response = await agent.run("What's the latest news?")
+print(response.text)
+```
+
+## Configuration
+
+### Environment Variables
+
+**Google AI:**
+- `GOOGLE_AI_API_KEY`: Your Google AI API key ([Get one here](https://ai.google.dev/))
+- `GOOGLE_AI_CHAT_MODEL_ID`: Model to use (e.g., `gemini-1.5-pro`, `gemini-1.5-flash`)
+
+**Vertex AI:**
+- `VERTEX_AI_PROJECT_ID`: Your GCP project ID
+- `VERTEX_AI_LOCATION`: GCP region (e.g., `us-central1`)
+- `VERTEX_AI_CHAT_MODEL_ID`: Model to use (e.g., `gemini-1.5-pro`)
+- `GOOGLE_APPLICATION_CREDENTIALS`: Path to service account JSON file
+
+### Supported Models
+
+- `gemini-1.5-pro`: Most capable model
+- `gemini-1.5-flash`: Faster, cost-effective model
+- `gemini-2.0-flash-exp`: Experimental latest model
+
+## Features
+
+### Common Features (Both Google AI & Vertex AI)
+- ✅ Chat completion (streaming and non-streaming)
+- ✅ Function/tool calling
+- ✅ Multi-modal support (text, images, video, audio)
+- ✅ System instructions
+- ✅ Conversation history management
+
+### Vertex AI Exclusive Features (Coming Soon)
+- Grounding with Google Search
+- Grounding with Vertex AI Search
+- Code execution tool
+- Enterprise security and compliance
+- VPC-SC support
+
+## Development Roadmap
+
+This package is being developed incrementally:
+
+- ✅ **Phase 1 (Current)**: Package structure and settings classes
+- 🚧 **Phase 2 (Next)**: Google AI chat client with streaming and function calling
+- 🚧 **Phase 3**: Google AI integration tests and samples
+- 🚧 **Phase 4**: Vertex AI chat client with enterprise features
+- 🚧 **Phase 5**: Vertex AI integration tests and samples
+- 🚧 **Phase 6**: Advanced features (context caching, safety settings, etc.)
+
+## Examples
+
+Examples will be available once the chat clients are implemented. Check back soon or watch the [repository](https://github.com/microsoft/agent-framework) for updates.
+
+## Documentation
+
+For more information:
+- [Google AI Documentation](https://ai.google.dev/docs)
+- [Vertex AI Documentation](https://cloud.google.com/vertex-ai/docs)
+- [Agent Framework Documentation](https://aka.ms/agent-framework)
+- [Agent Framework Repository](https://github.com/microsoft/agent-framework)

python/packages/google/agent_framework_google/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+# NOTE: Client classes will be imported here in PR #2 and PR #4
+# from ._chat_client import GoogleAIChatClient, VertexAIChatClient
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    # "GoogleAIChatClient",  # Will be added in PR #2
+    # "VertexAIChatClient",  # Will be added in PR #4
+    "__version__",
+]

python/packages/google/agent_framework_google/_chat_client.py

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import ClassVar
+
+from agent_framework._pydantic import AFBaseSettings
+from pydantic import SecretStr
+
+
+class GoogleAISettings(AFBaseSettings):
+    """Google AI settings for Gemini API access.
+
+    The settings are first loaded from environment variables with the prefix 'GOOGLE_AI_'.
+    If the environment variables are not found, the settings can be loaded from a .env file
+    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the settings are missing.
+
+    Keyword Args:
+        api_key: The Google AI API key.
+        chat_model_id: The Google AI chat model ID (e.g., gemini-1.5-pro).
+        env_file_path: If provided, the .env settings are read from this file path location.
+        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework.google import GoogleAISettings
+
+            # Using environment variables
+            # Set GOOGLE_AI_API_KEY=your_api_key
+            # GOOGLE_AI_CHAT_MODEL_ID=gemini-1.5-pro
+
+            settings = GoogleAISettings()
+
+            # Or passing parameters directly
+            settings = GoogleAISettings(
+                api_key="your_api_key",
+                chat_model_id="gemini-1.5-pro"
+            )
+
+            # Or loading from a .env file
+            settings = GoogleAISettings(env_file_path="path/to/.env")
+    """
+
+    env_prefix: ClassVar[str] = "GOOGLE_AI_"
+
+    api_key: SecretStr | None = None
+    chat_model_id: str | None = None
+
+
+class VertexAISettings(AFBaseSettings):
+    """Vertex AI settings for Google Cloud access.
+
+    The settings are first loaded from environment variables with the prefix 'VERTEX_AI_'.
+    If the environment variables are not found, the settings can be loaded from a .env file
+    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the settings are missing.
+
+    Keyword Args:
+        project_id: The Google Cloud project ID.
+        location: The Google Cloud region (e.g., us-central1).
+        chat_model_id: The Vertex AI chat model ID (e.g., gemini-1.5-pro).
+        credentials_path: Optional path to service account JSON file.
+        env_file_path: If provided, the .env settings are read from this file path location.
+        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework.google import VertexAISettings
+
+            # Using environment variables
+            # Set VERTEX_AI_PROJECT_ID=your-project-id
+            # VERTEX_AI_LOCATION=us-central1
+            # VERTEX_AI_CHAT_MODEL_ID=gemini-1.5-pro
+            # GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+
+            settings = VertexAISettings()
+
+            # Or passing parameters directly
+            settings = VertexAISettings(
+                project_id="your-project-id",
+                location="us-central1",
+                chat_model_id="gemini-1.5-pro"
+            )
+
+            # Or loading from a .env file
+            settings = VertexAISettings(env_file_path="path/to/.env")
+    """
+
+    env_prefix: ClassVar[str] = "VERTEX_AI_"
+
+    project_id: str | None = None
+    location: str | None = None
+    chat_model_id: str | None = None
+    credentials_path: str | None = None
+
+
+# NOTE: Client implementations will be added in PR #2 and PR #4
+# For PR #1, we're only setting up the package structure and settings