feat(genai): add labels support (#1503)

<!--
# Thank you for contributing to LangChain-google!
-->

<!--
## Checklist for PR Creation

- [x] PR Title: "<type>[optional scope]: <description>"

- Where type is one of: feat, fix, docs, style, refactor, perf, test,
build, ci, chore, revert, release
- Scope is used to specifiy the package targeted. Options are: genai,
vertex, community, infra (repo-level)

- [x] PR Description and Relevant issues:

  - Description of the change
  - Relevant issues (if applicable)
  - Any dependencies required for this change

- [x] Add Tests and Docs:

  - If adding a new integration:
1. Include a test for the integration (preferably unit tests that do not
rely on network access)
2. Add an example notebook showing its use (place in the
`docs/docs/integrations` directory)

- [x] Lint and Test:
- Run `make format`, `make lint`, and `make test` from the root of the
package(s) you've modified
- See contribution guidelines for more:
https://github.com/langchain-ai/langchain-google/blob/main/README.md#contribute-code
-->

<!--
## Additional guidelines

- [x] PR title and description are appropriate
- [x] Necessary tests and documentation have been added
- [x] Lint and tests pass successfully
- [x] The following additional guidelines are adhered to:
  - Optional dependencies are imported within functions
- No unnecessary dependencies added to pyproject.toml files (except
those required for unit tests)
  - PR doesn't touch more than one package
  - Changes are backwards compatible
-->

## Description

<!-- e.g. "Implement user authentication feature" -->
Added the `labels` field to `ChatGoogleGenerativeAI`. This allows users
to attach custom metadata to API requests and track billing breakdowns.

This feature was already implemented in `ChatVertexAI`, and this change
makes it available in `ChatGoogleGenerativeAI` as well.


## Relevant issues

<!-- e.g. "Fixes #000" -->

fixes #1496

## Type

<!-- Select the type of Pull Request -->
<!-- Keep only the necessary ones -->

🆕 New Feature

## Changes(optional)

<!-- List of changes -->
- Added `labels: dict[str, str] | None` field to
`_BaseGoogleGenerativeAI`
- Implemented logic to pass `labels` to `GenerateContentConfig` in
`ChatGoogleGenerativeAI`
- Added unit tests to verify that labels is passed correctly

## Testing(optional)

<!-- Test procedure -->
```python
llm = ChatGoogleGenerativeAI(
    model="gemini-2.0-flash",
    labels={"env": "production", "team": "ml"},
)
```

<!-- Test result -->

Unit tests added:
- `labels` is correctly passed to `GenerateContentConfig`
- `labels` defaults to None when not specified

## Note(optional)

<!-- Information about the errors fixed by PR -->
<!-- Remaining issue or something -->
<!-- Other information about PR -->
`ChatVertexAI` includes labels validation [^1], but this was omitted in
`ChatGoogleGenerativeAI` to align with other fields that do not have
validation.

[^1]:
https://github.com/langchain-ai/langchain-google/blob/306f6ee3d8d03672d95f8907edefa61e41bf02d3/libs/vertexai/langchain_google_vertexai/chat_models.py#L1858-L1868

Google GenAI SDK already supports the `labels` field at here.

https://googleapis.github.io/python-genai/genai.html#genai.types.GenerateContentConfig.labels

---------

Co-authored-by: Mason Daugherty <mason@langchain.dev>
Co-authored-by: Mason Daugherty <github@mdrxy.com>

Author: Azuki-bar

libs/genai/langchain_google_genai/_common.py

@@ -506,6 +506,16 @@ class _BaseGoogleGenerativeAI(BaseModel):
         infrastructure.
     """
 
+    labels: dict[str, str] | None = Field(default=None)
+    """User-defined key-value metadata for organizing and filtering billing reports.
+
+    Attach labels to categorize API usage by team, environment, or feature.
+
+    Can be overridden per-request via invoke kwargs.
+
+    See: https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/add-labels-to-api-calls
+    """
+
     @model_validator(mode="after")
     def _resolve_project_from_credentials(self) -> Self:
         """Extract project from credentials if not explicitly set.

libs/genai/langchain_google_genai/chat_models.py

@@ -2797,6 +2797,10 @@ def _prepare_request(
 
         image_config = kwargs.pop("image_config", None)
 
+        labels = kwargs.pop("labels", None)
+        if labels is None:
+            labels = self.labels
+
         _consumed_kwargs = {
             "thinking_budget",
             "thinking_level",
@@ -2824,6 +2828,7 @@ def _prepare_request(
             timeout=timeout,
             max_retries=max_retries,
             image_config=image_config,
+            labels=labels,
             **remaining_kwargs,
         )
 
@@ -2971,6 +2976,7 @@ def _build_request_config(
         timeout: int | None = None,
         max_retries: int | None = None,
         image_config: dict[str, Any] | None = None,
+        labels: dict[str, str] | None = None,
         **kwargs: Any,
     ) -> GenerateContentConfig:
         """Build the final request configuration."""
@@ -3001,6 +3007,7 @@ def _build_request_config(
             system_instruction=system_instruction,
             http_options=http_options,
             image_config=image_config_obj,
+            labels=labels,
             **params.model_dump(exclude_unset=True),
             **kwargs,
         )

libs/genai/tests/unit_tests/test_chat_models.py

@@ -4921,3 +4921,51 @@ def test_openai_style_bind_with_response_format() -> None:
         strict=True,
     )
     assert bound4 is not None
+
+
+def test_labels_passed_to_generate_content_config() -> None:
+    """Test that `labels` is properly passed to `GenerateContentConfig`."""
+    llm = ChatGoogleGenerativeAI(
+        model=MODEL_NAME,
+        google_api_key=SecretStr(FAKE_API_KEY),
+        labels={"env": "production", "team": "ml"},
+    )
+    messages: list[BaseMessage] = [HumanMessage(content="Hello")]
+    request = llm._prepare_request(messages)
+    config = request["config"]
+
+    assert config.labels is not None
+    assert config.labels == {"env": "production", "team": "ml"}
+
+
+def test_labels_none_by_default() -> None:
+    """Test that `labels` is `None` by default."""
+    llm = ChatGoogleGenerativeAI(
+        model=MODEL_NAME,
+        google_api_key=SecretStr(FAKE_API_KEY),
+    )
+    assert llm.labels is None
+
+    messages: list[BaseMessage] = [HumanMessage(content="Hello")]
+    request = llm._prepare_request(messages)
+    config = request["config"]
+
+    assert config.labels is None
+
+
+def test_labels_override_in_invoke() -> None:
+    """Test that labels can be overridden at invocation time via kwargs."""
+    llm = ChatGoogleGenerativeAI(
+        model=MODEL_NAME,
+        google_api_key=SecretStr(FAKE_API_KEY),
+        labels={"env": "production", "team": "ml"},
+    )
+    messages: list[BaseMessage] = [HumanMessage(content="Hello")]
+
+    # Override labels via kwargs
+    request = llm._prepare_request(
+        messages, labels={"env": "staging", "request_id": "123"}
+    )
+    config = request["config"]
+
+    assert config.labels == {"env": "staging", "request_id": "123"}