# google-gemini/cookbook architecture

> Architecture diagram of the GitHub repository google-gemini/cookbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-gemini/cookbook
- Repository: https://github.com/google-gemini/cookbook

## Overview

#### Purpose and Entry Points
This is a documentation-and-executable-notebook cookbook for the Gemini API, not a deployable application. Users enter through `README.md`, then run tutorials in hosted notebook environments or locally. Primary paths are `quickstarts/` for single-feature API learning and `examples/` for composed use cases.

#### Core Learning Tracks
- **Authentication and baseline generation:** establishes API-key/OAuth access and basic multimodal prompting. Paths: `quickstarts/Authentication.ipynb`, `quickstarts/Authentication_with_OAuth.ipynb`, `quickstarts/Get_started.ipynb`.
- **Feature-specific API tutorials:** isolated notebook entry points cover streaming, structured output, safety, files, embeddings, caching, batch, and function calls. Paths: `quickstarts/Streaming.ipynb`, `quickstarts/JSON_mode.ipynb`, `quickstarts/File_Search.ipynb`.
- **Direct REST usage:** a parallel tutorial track demonstrates the Gemini REST surface rather than SDK clients. Paths: `quickstarts/rest/README.md`, `quickstarts/rest/Function_calling_REST.ipynb`, `quickstarts/rest/Streaming_REST.ipynb`.

#### Realtime and Asynchronous Flows
Realtime clients establish streaming/WebSocket sessions, send multimodal audio/video or tool-enabled requests, and consume incremental events. Paths: `quickstarts/Get_started_LiveAPI.py`, `quickstarts/websockets/Get_started_LiveAPI.py`, `quickstarts/Get_started_LiveTranslate.py`.  
Long-running operations use batch requests, media generation, or webhook notifications rather than a synchronous request/response loop. Paths: `quickstarts/Batch_mode.ipynb`, `quickstarts/Webhooks.ipynb`, `quickstarts/Get_started_Veo.ipynb`.

#### Model and Media Boundaries
Notebooks exercise Gemini text/multimodal inference plus specialized hosted model capabilities: image generation, video generation/editing, music, speech, transcription, and robotics/spatial reasoning. Paths: `quickstarts/Get_Started_Nano_Banana.ipynb`, `quickstarts/Get_started_Omni.ipynb`, `quickstarts/Get_started_LyriaRealTime.py`. The external service boundary is the Gemini API, accessed through REST or official language SDKs; credentials originate from Google AI Studio or OAuth.

#### Grounding, Retrieval, and Agent Composition
Examples combine model calls with tools and external knowledge/data systems. Grounding can use Google Search, Maps, URLs, and hosted File Search; retrieval examples integrate vector stores and orchestration frameworks. Paths: `quickstarts/Grounding.ipynb`, `examples/qdrant/Hybrid_Search_Legal.ipynb`, `examples/langchain/SQL_Agent_Gemini_LangChain.ipynb`. This is the main boundary between Gemini inference and third-party services such as Qdrant, Chroma, Pinecone, Weaviate, LangChain, LlamaIndex, and Google tools.

#### Practical Application Recipes
`examples/` assembles multi-stage flows—input ingestion, prompts/tool calls, model inference, and rendered or persisted outputs—rather than supplying reusable application packages. Representative integrations include browser control, video production, observability, Gradio UI, and Google Apps Script. Paths: `examples/Browser_as_a_tool.ipynb`, `examples/Animated_Story_Video_Generation_gemini.ipynb`, `examples/Cost_Estimation_And_Health_Monitoring.ipynb`.

#### Repository Quality Pipeline
Repository-maintenance code validates and normalizes notebooks. `tools/nb_tester/cli.py` drives notebook execution, comparison, rule checks, security scanning, AI/security auditing, and reporting; `tools/nblint_cli.py` and `tools/nbfmt_cli.py` provide linting and formatting. Paths: `tools/nb_tester/executor.py`, `tools/nb_tester/reporter.py`, `tools/nblint/linter.py`. GitHub Actions runs notebook-related automation and repository hygiene. Paths: `.github/workflows/notebooks.yaml`, `.github/workflows/new_examples_links_in_table_of_content.yml`.

Main entry points: [`README.md`](https://github.com/google-gemini/cookbook/blob/main/README.md) (Cookbook guide), [`tools/nb_tester/cli.py`](https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/cli.py) (Notebook test CLI), [`examples/Browser_as_a_tool.ipynb`](https://github.com/google-gemini/cookbook/blob/main/examples/Browser_as_a_tool.ipynb) (Application recipes), [`quickstarts/Authentication.ipynb`](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb) (Auth and basics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning tracks"]
  node_auth["Auth and basics<br/>notebooks"]
  node_feature_tutorials["Feature tutorials<br/>notebooks<br/>[Streaming.ipynb]"]
  node_rest_track["REST tutorials<br/>notebooks<br/>[README.md]"]
  node_realtime["Realtime clients<br/>Python scripts"]
  node_async["Async operations<br/>notebooks<br/>[Batch_mode.ipynb]"]
  node_specialized_media["Specialized media models<br/>notebooks and scripts"]
  node_grounding["Grounding tutorials<br/>notebooks<br/>[Grounding.ipynb]"]
end

subgraph group_recipes["Composed recipes"]
  node_retrieval_agents["Retrieval and agents<br/>example notebooks"]
  node_application_recipes["Application recipes<br/>example notebooks"]
end

subgraph group_quality["Repository quality"]
  node_nb_tester_cli["Notebook test CLI<br/>Python CLI<br/>[cli.py]"]
  node_execution["Execution and comparison<br/>test runtime<br/>[executor.py]"]
  node_notebook_quality["Lint and format<br/>quality tools<br/>[nblint_cli.py]"]
  node_reporting["Reports and audits<br/>reporting<br/>[reporter.py]"]
  node_github_actions["GitHub Actions<br/>CI workflows<br/>[notebooks.yaml]"]
end

node_readme["Cookbook guide<br/>documentation<br/>[README.md]"]
node_gemini_api{{"Gemini API<br/>hosted API"}}
node_credentials{{"AI Studio / OAuth<br/>credential providers"}}
node_sdk["Official SDKs<br/>client libraries"]
node_third_party{{"Tools and data services<br/>external integrations"}}

node_readme -->|"starts with"| node_auth
node_readme -->|"links to"| node_feature_tutorials
node_readme -->|"links to"| node_rest_track
node_readme -->|"links to"| node_application_recipes
node_credentials -->|"authorizes"| node_auth
node_auth -->|"configures"| node_sdk
node_sdk -->|"calls"| node_gemini_api
node_rest_track -->|"calls directly"| node_gemini_api
node_feature_tutorials -->|"exercises"| node_gemini_api
node_realtime -->|"streams events with"| node_gemini_api
node_async -->|"submits long-running work"| node_gemini_api
node_specialized_media -->|"uses hosted capabilities"| node_gemini_api
node_grounding -->|"grounds inference"| node_gemini_api
node_grounding -->|"uses"| node_third_party
node_retrieval_agents -->|"integrates"| node_third_party
node_retrieval_agents -->|"composes with"| node_gemini_api
node_application_recipes -->|"orchestrates"| node_gemini_api
node_application_recipes -->|"integrates"| node_third_party
node_nb_tester_cli -->|"drives"| node_execution
node_nb_tester_cli -->|"runs checks"| node_notebook_quality
node_nb_tester_cli -->|"emits results"| node_reporting
node_github_actions -->|"automates"| node_nb_tester_cli
node_github_actions -->|"runs"| node_notebook_quality

click node_readme "https://github.com/google-gemini/cookbook/blob/main/README.md"
click node_auth "https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb"
click node_feature_tutorials "https://github.com/google-gemini/cookbook/blob/main/quickstarts/Streaming.ipynb"
click node_rest_track "https://github.com/google-gemini/cookbook/blob/main/quickstarts/rest/README.md"
click node_realtime "https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI.py"
click node_async "https://github.com/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb"
click node_specialized_media "https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_Started_Nano_Banana.ipynb"
click node_grounding "https://github.com/google-gemini/cookbook/blob/main/quickstarts/Grounding.ipynb"
click node_retrieval_agents "https://github.com/google-gemini/cookbook/blob/main/examples/qdrant/Hybrid_Search_Legal.ipynb"
click node_application_recipes "https://github.com/google-gemini/cookbook/blob/main/examples/Browser_as_a_tool.ipynb"
click node_nb_tester_cli "https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/cli.py"
click node_execution "https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/executor.py"
click node_notebook_quality "https://github.com/google-gemini/cookbook/blob/main/tools/nblint_cli.py"
click node_reporting "https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/reporter.py"
click node_github_actions "https://github.com/google-gemini/cookbook/blob/main/.github/workflows/notebooks.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_feature_tutorials,node_rest_track,node_realtime,node_async,node_specialized_media,node_grounding toneBlue
class node_retrieval_agents,node_application_recipes toneAmber
class node_nb_tester_cli,node_execution,node_notebook_quality,node_reporting,node_github_actions toneMint
class node_readme,node_gemini_api,node_credentials,node_sdk,node_third_party toneNeutral
```

## Components

### Learning tracks

Notebook and script entry points for API capabilities.

- [Auth and basics](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Authentication.ipynb): notebooks · API key/OAuth setup and baseline multimodal generation. · `quickstarts/Authentication.ipynb`
- [Feature tutorials](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Streaming.ipynb): notebooks · Streaming, JSON output, and hosted file search tutorials. · `quickstarts/Streaming.ipynb`
- [REST tutorials](https://github.com/google-gemini/cookbook/blob/main/quickstarts/rest/README.md): notebooks · Parallel Gemini REST learning track. · `quickstarts/rest/README.md`
- [Realtime clients](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI.py): Python scripts · Live streaming sessions for multimodal and tool-enabled requests. · `quickstarts/Get_started_LiveAPI.py`
- [Async operations](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb): notebooks · Batch, webhook, and long-running media workflows. · `quickstarts/Batch_mode.ipynb`
- [Specialized media models](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Get_Started_Nano_Banana.ipynb): notebooks and scripts · Image, video, music, speech, and spatial capabilities. · `quickstarts/Get_Started_Nano_Banana.ipynb`
- [Grounding tutorials](https://github.com/google-gemini/cookbook/blob/main/quickstarts/Grounding.ipynb): notebooks · Google tools, URLs, and hosted File Search grounding. · `quickstarts/Grounding.ipynb`

### Composed recipes

Multi-stage example integrations.

- [Retrieval and agents](https://github.com/google-gemini/cookbook/blob/main/examples/qdrant/Hybrid_Search_Legal.ipynb): example notebooks · Qdrant-backed retrieval and LangChain agent compositions. · `examples/qdrant/Hybrid_Search_Legal.ipynb`
- [Application recipes](https://github.com/google-gemini/cookbook/blob/main/examples/Browser_as_a_tool.ipynb): example notebooks · Browser, video, observability, UI, and Apps Script recipes. · `examples/Browser_as_a_tool.ipynb`

### Repository quality

Notebook validation and GitHub automation.

- [Notebook test CLI](https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/cli.py): Python CLI · Drives execution, comparisons, checks, audits, and reporting. · `tools/nb_tester/cli.py`
- [Execution and comparison](https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/executor.py): test runtime · Runs notebooks and evaluates outputs. · `tools/nb_tester/executor.py`
- [Lint and format](https://github.com/google-gemini/cookbook/blob/main/tools/nblint_cli.py): quality tools · Notebook rule checking and normalization. · `tools/nblint_cli.py`
- [Reports and audits](https://github.com/google-gemini/cookbook/blob/main/tools/nb_tester/reporter.py): reporting · Aggregates validation and audit results. · `tools/nb_tester/reporter.py`
- [GitHub Actions](https://github.com/google-gemini/cookbook/blob/main/.github/workflows/notebooks.yaml): CI workflows · Runs notebook automation and repository hygiene. · `.github/workflows/notebooks.yaml`

### Other components

- [Cookbook guide](https://github.com/google-gemini/cookbook/blob/main/README.md): documentation · Primary entry point to tutorials and examples. · `README.md`
- **Gemini API**: hosted API · External inference and specialized-model service boundary.
- **AI Studio / OAuth**: credential providers · Sources of API-key and OAuth access.
- **Official SDKs**: client libraries · Client boundary used by most cookbook flows.
- **Tools and data services**: external integrations · Google tools, vector stores, and orchestration frameworks.

## Connections

- Cookbook guide → Auth and basics: starts with
- Cookbook guide → Feature tutorials: links to
- Cookbook guide → REST tutorials: links to
- Cookbook guide → Application recipes: links to
- AI Studio / OAuth → Auth and basics: authorizes
- Auth and basics → Official SDKs: configures
- Official SDKs → Gemini API: calls
- REST tutorials → Gemini API: calls directly
- Feature tutorials → Gemini API: exercises
- Realtime clients → Gemini API: streams events with
- Async operations → Gemini API: submits long-running work
- Specialized media models → Gemini API: uses hosted capabilities
- Grounding tutorials → Gemini API: grounds inference
- Grounding tutorials → Tools and data services: uses
- Retrieval and agents → Tools and data services: integrates
- Retrieval and agents → Gemini API: composes with
- Application recipes → Gemini API: orchestrates
- Application recipes → Tools and data services: integrates
- Notebook test CLI → Execution and comparison: drives
- Notebook test CLI → Lint and format: runs checks
- Notebook test CLI → Reports and audits: emits results
- GitHub Actions → Notebook test CLI: automates
- GitHub Actions → Lint and format: runs
