/.gemini/styleguide.md

# GoogleCloudPlatform/generative-ai Style Guide

The current year is 2026.

IMPORTANT: Agent Platform (full name Gemini Enterprise Agent Platform) was previously named "Vertex AI" and many web resources use the legacy branding. Make sure that all new content uses the new name.

## Markdown Style (For `.md` files and `.ipynb` Markdown Cells)

- Use single backticks ( ` ` ) to format inline code elements, such as variable names, function names, enum names, and brief code snippets.
- Add documentation links to the appropriate Agent Platform pages when describing product features. e.g. https://docs.cloud.google.com/gemini-enterprise-agent-platform/
  - Do not reference documentation from the Gemini Developer API, e.g. https://ai.google.dev/ unless there is not a suitable page in the Agent Platform documentation.

The Author block in Notebooks and Markdown should be in a format like this:

For one author:

| Author |
| --- |
| [Firstname Lastname](https://github.com/username) |

For multiple authors

| Authors |
| --- |
| [Firstname Lastname](https://github.com/username) |
| [Firstname Lastname](https://github.com/username) |

## Code Requirements

- Don't include hard-coded Google Cloud project IDs, always use a placeholder like `[your-project-id]`

**Correct**

```py
PROJECT_ID = "[your-project-id]"
```

**Incorrect**

```py
PROJECT_ID = "actual-projectid-1234"
```

- Use the `global` endpoint for all requests, unless a regional endpoint is specifically required for a model or feature.

**Correct**

```py
LOCATION = "global"
```

**Incorrect**

```py
LOCATION = "us-central1"
```

- Don't restart the kernel or use `!pip`, use `%pip` when installing

**Correct**

```sh
%pip install
```

**Incorrect**

```sh
!pip install
```

```sh
!pip3 install
```

```py
app = IPython.Application.instance()
app.kernel.do_shutdown(True)
```

## Golden Rule: Use the Correct and Current SDK

Always use the **Google Gen AI SDK** (`google-genai`), which is the unified
standard library for all Gemini API requests (AI Studio/Gemini Developer API
and Vertex AI/Agent Platform) as of 2026. Do not use legacy libraries and SDKs.

-   **Library Name:** Google Gen AI SDK
-   **Python Package:** `google-genai`
-   **Legacy Library**: (`google-generativeai`) is deprecated.

**Installation:**

-   **Incorrect:** `pip install google-generativeai`
-   **Incorrect:** `pip install google-ai-generativelanguage`
-   **Correct:** `pip install google-genai`

**APIs and Usage:**

-   **Incorrect:** `import google.generativeai as genai`-> **Correct:** `from
    google import genai`
-   **Incorrect:** `from google.ai import generativelanguage_v1`  ->
    **Correct:** `from google import genai`
-   **Incorrect:** `from google.generativeai` -> **Correct:** `from google
    import genai`
-   **Incorrect:** `from google.generativeai import types` -> **Correct:** `from
    google.genai import types`
-   **Incorrect:** `import google.generativeai as genai` -> **Correct:** `from
    google import genai`
-   **Incorrect:** `genai.configure(api_key=...)` -> **Correct:** `client =
    genai.Client(api_key='...')`
-   **Incorrect:** `model = genai.GenerativeModel(...)`
-   **Incorrect:** `model.generate_content(...)` -> **Correct:**
    `client.models.generate_content(...)`
-   **Incorrect:** `response = model.generate_content(..., stream=True)` ->
    **Correct:** `client.models.generate_content_stream(...)`
-   **Incorrect:** `genai.GenerationConfig(...)` -> **Correct:**
    `types.GenerateContentConfig(...)`
-   **Incorrect:** `safety_settings={...}` -> **Correct:** Use `safety_settings`
    inside a `GenerateContentConfig` object.
-   **Incorrect:** `from google.api_core.exceptions import GoogleAPIError` ->
    **Correct:** `from google.genai.errors import APIError`
-   **Incorrect:** `types.ResponseModality.TEXT`

## Models

-   By default, use the following models when using `google-genai`:
    -   **General Text & Multimodal Tasks:** `gemini-3.5-flash`
    -   **Coding and Complex Reasoning Tasks:** `gemini-3.1-pro-preview`
    -   **Low Latency & High Volume Tasks:** `gemini-3.1-flash-lite`
    -   **Fast Image Generation and Editing:** `gemini-3.1-flash-image` (aka Nano Banana 2)
    -   **High-Quality Image Generation and Editing:** `gemini-3-pro-image` (aka Nano Banana Pro)
    -   **High-Fidelity Video Generation:**  or `veo-3.1-generate-001`
    -   **Advanced Video Editing Tasks:** `veo-3.1-generate-001`
    -   **Video Generation, Balance of speed and quality:**  `veo-3.1-fast-generate-001`
    -   **Fast Video Generation:** `veo-3.1-lite-generate-001`

-   It is also acceptable to use following models if explicitly requested by the
    user:
    -   **Gemini 2.5 Series**: `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-2.5-flash-lite`
    -   **Nano Banana:** `gemini-2.5-flash-image`

-   Do not use the following deprecated models (or their variants like
    `gemini-1.5-flash-latest`):
    -   **Gemini 3 Pro Preview**: `gemini-3-pro-preview` (Replaced by `gemini-3.1-pro-preview`)
    -   **Gemini 3 Flash Preview**: `gemini-3-flash-preview`
    -   **Gemini 3.1 Flash Image Preview**: `gemini-3.1-flash-image-preview`
    -   **Gemini 3 Pro Image Preview**: `gemini-3-pro-image-preview`
    -   **Gemini 2.0 Series**: `gemini-2.0-flash`, `gemini-2.0-flash-lite`
    -   **Gemini 1.5 Series**: `gemini-1.5-flash`, `gemini-1.5-pro`
    -   **Prohibited:** `gemini-pro`
    -   **Veo 3:** `veo-3.0-generate-001`, `veo-3.0-fast-generate-001`
    -   **Veo 2:** `veo-2.0-generate-001`
    -   **Imagen:** `imagegeneration@00*`, `imagetext@001` `imagen-3.0-*`, `imagen-4.0-*`