# matrx_ai.providers.google — Module Overview


## IMPORTANT: Do not edit auto-generated sections.

> This document is partially auto-generated. Sections tagged `<!-- AUTO:id -->` are refreshed by the generator.
> Everything else is yours to edit freely and will never be overwritten.

<!-- AUTO:meta -->
## About This Document

This file is **partially auto-generated**. Sections wrapped in `<!-- AUTO:id -->` tags
are overwritten each time the generator runs. Everything else is yours to edit freely.

| Field | Value |
|-------|-------|
| Module | `matrx_ai/providers/google` |
| Last generated | 2026-04-07 11:38 |
| Output file | `matrx_ai/providers/google/MODULE_README.md` |
| Signature mode | `signatures` |

**To refresh auto-sections:**
```bash
python utils/code_context/generate_module_readme.py matrx_ai/providers/google --mode signatures
```

**To add permanent notes:** Write anywhere outside the `<!-- AUTO:... -->` blocks.
<!-- /AUTO:meta -->

<!-- HUMAN-EDITABLE: This section is yours. Agents & Humans can edit this section freely — it will not be overwritten. -->

## Architecture

The catalog chooses the wire contract; this package translates that contract
to the official `google-genai` SDK. `google_api.py` owns ordinary
`generateContent` turns, `google_video_api.py` owns generated-video polling,
and `specialized.py` owns the contracts that are not turns:

| Runtime | Catalog wire | SDK operation |
|---|---|---|
| `GoogleLiveSession` | `google_live` | persistent `aio.live.connect` bidi session |
| `GoogleMusicSession` | `google_music_realtime` | persistent `aio.live.music.connect` PCM stream |
| `GoogleEmbeddingRuntime` | `google_embeddings` | `aio.models.embed_content` |
| `GoogleBackgroundInteractionRuntime` | `google_interactions` | stored `interactions.create/get` |

The host owns authentication, WebSockets, durable polling, and vector-table
selection. These adapters own only provider protocol translation and reject a
catalog profile whose `wire_format` does not match.


<!-- AUTO:tree -->
## Directory Tree

> Auto-generated. 7 files across 1 directories.

```
matrx_ai/providers/google/
├── MODULE_README.md
├── __init__.py
├── google_api.py
├── google_client.py
├── google_video_api.py
├── sample_podcast_direct.py
├── translator.py
# excluded: 1 .md
```
<!-- /AUTO:tree -->

<!-- AUTO:signatures -->
## API Signatures

> Auto-generated via `output_mode="signatures"`. ~5-10% token cost vs full source.
> For full source, open the individual files directly.

```
---
Filepath: matrx_ai/providers/google/google_video_api.py  [python]

  class GoogleVideoGeneration:
      def __init__(self)
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
  def _start_operation()
  def _poll_until_done(op)
  def _download(gv = generated_video) -> bytes


---
Filepath: matrx_ai/providers/google/sample_podcast_direct.py  [python]

  TEMP_DIR = get_ext('TEMP_DIR')
  TEMP_PATH = TEMP_DIR / 'app_outputs' / 'ai'
  def save_binary_file(file_path: Path, data: bytes) -> None
  def generate(file_prefix)
  def convert_to_wav(audio_data: bytes, mime_type: str) -> bytes
  def parse_audio_mime_type(mime_type: str) -> dict[str, int | None]


---
Filepath: matrx_ai/providers/google/__init__.py  [python]



---
Filepath: matrx_ai/providers/google/google_api.py  [python]

  LOCAL_DEBUG = False
  class GoogleChat:
      def __init__(self, debug: bool = False)
      async def execute(self, unified_config: UnifiedConfig, profile: ResolvedCallProfile, debug: bool = False) -> UnifiedResponse
      async def _emit_media_from_response(self, response: UnifiedResponse, emitter: Emitter) -> None
      async def _handle_part(self, part: Part, emitter: Emitter, audio_format: str | None = None)
      async def _debug_part(self, part: Part)
  def _sanitize_for_debug(obj: object) -> object
  def _collect_tts_chunks() -> list[GenerateContentResponse]


---
Filepath: matrx_ai/providers/google/google_client.py  [python]

  def google_client() -> genai.Client
  def get_google_client() -> genai.Client


---
Filepath: matrx_ai/providers/google/translator.py  [python]

  class GoogleProviderConfig(TypedDict):
  class GoogleTranslator(BaseTranslator):
      def __init__(self, debug: bool = False)
      def to_google(self, config: UnifiedConfig, profile: ResolvedCallProfile) -> GoogleProviderConfig
      def to_google_video(self, config: UnifiedConfig) -> dict[str, Any]
      def _prepend_system_to_user_content(contents: list[dict], system_text: str) -> None
      def from_google(self, chunks: list[GenerateContentResponse], matrx_model_name: str, audio_format: str | None = None) -> UnifiedResponse
```
<!-- /AUTO:signatures -->

<!-- AUTO:callers -->
## Upstream Callers

> Auto-discovered by scanning all project files that import from this module.
> Set `ENTRY_POINTS` in `generate_readme.py` to pin specific functions.

| Caller | Calls |
|--------|-------|
| `matrx_ai/providers/data_sync/google_model_sync.py` | `get_google_client()` |
<!-- /AUTO:callers -->

<!-- AUTO:dependencies -->
## Dependencies

**External packages:** dotenv, google, google_client, matrx_connect, matrx_utils, rich
**Internal modules:** matrx_ai._ext, matrx_ai.config, matrx_ai.context, matrx_ai.media, matrx_ai.providers, matrx_ai.tools
<!-- /AUTO:dependencies -->

<!-- AUTO:config -->
## Generation Config

> Auto-managed. Contains the exact parameters used to generate this README.
> Used by parent modules to auto-refresh this file when it is stale.
> Do not edit manually — changes will be overwritten on the next run.

```json
{
  "subdirectory": "matrx_ai/providers/google",
  "mode": "signatures",
  "scope": null,
  "project_noise": null,
  "include_call_graph": false,
  "entry_points": null,
  "call_graph_exclude": [
    "tests"
  ],
  "signatures_exclude": [
    "tests",
    "db",
    "local_data",
    "docs"
  ]
}
```
<!-- /AUTO:config -->
