# philschmid/gemini-2.5-ai-engineering-workshop architecture

> Architecture diagram of the GitHub repository philschmid/gemini-2.5-ai-engineering-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/philschmid/gemini-2.5-ai-engineering-workshop
- Repository: https://github.com/philschmid/gemini-2.5-ai-engineering-workshop

## Overview

##### Project type and purpose
- This repository is an educational “AI Engineering Workshop” built around Jupyter notebooks. It is not a web app or microservice mesh, but a set of client-side notebooks that demonstrate how to use the `google-genai` Python SDK and Google Gemini 2.5 APIs to build agentic, multimodal AI applications.

##### Main components
a. User Environment
- Jupyter Notebook (local or Colab) – where the workshop is executed
- Python runtime with the `google-genai` SDK installed
b. Local Assets
- assets/data folder containing sample audio.mp3, book.txt, rewe_invoice.pdf, standup.mp4
- Optional: solutions notebooks (only for instructor reference)
c. SDK Client
- `google-genai` Python package
- Handles authentication (API key) and all RPC calls
d. Google AI Studio / Gemini Cloud Services
- Gemini 2.5 text-generation/chat endpoint
- Multimodal processing endpoints (vision, audio, video, document)
- Function-calling & tool integration endpoints
- Model Context Protocol (MCP) servers (both stdio and HTTP modes)
e. External Tools & Services (optional)
- Native code execution tool
- Google Search grounding tool
- Any user-implemented function-calling HTTP service

##### Relationships and data flows
- The user opens a notebook → imports `google-genai` → configures API key → loads local asset (e.g., audio.mp3)
- The notebook (SDK client) serializes the request, sends it over HTTPS to the appropriate Gemini service (text, vision, audio, etc.)
- Cloud service processes input, returns JSON responses (text, structured data, images, audio, transcripts)
- Notebooks parse and render outputs (charts, tables, transcripts)
- In Part 3, notebook triggers function calls: SDK forwards structured payloads to user-provided HTTP endpoints or built-in tools, then merges results back into the chat
- In Part 4, notebook launches or connects to an MCP server (stdio or HTTP) and orchestrates an always-on agentic chat loop

##### Architectural patterns & principles
- Client–Server: notebooks (clients) ←→ Google Gemini Cloud (servers)
- Modular demos: each notebook focuses on a capability (text, chat, multimodal, function API, MCP)
- Pluggable tools/function-calling: SDK acts as broker between model and external code/APIs
- Separation of concerns:
- Notebook = orchestration & visualization
- SDK = transport & serialization
- Cloud = model execution & heavy compute

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Environment Layer
    subgraph "User Environment" 
        direction TB
        NB0["00-setup-and-authentication.ipynb"]:::local
        NB1["01-text-generation-and-chat.ipynb"]:::local
        NB2["02-multimodal-capabilities.ipynb"]:::local
        NB3["03-structured-outputs-function-calling-tools.ipynb"]:::local
        NB4["04-model-context-protocol-mcp.ipynb"]:::local
        subgraph "Instructor Solutions (optional)" 
            SOL0["00-setup-and-authentication.ipynb"]:::local
            SOL1["01-text-generation-and-chat.ipynb"]:::local
            SOL2["02-multimodal-capabilities.ipynb"]:::local
            SOL3["03-structured-outputs-function-calling-tools.ipynb"]:::local
            SOL4["04-model-context-protocol-mcp.ipynb"]:::local
        end
    end

    %% Local Assets Layer
    subgraph "Local Assets" 
        direction TB
        A1["audio.mp3"]:::local
        A2["book.txt"]:::local
        A3["rewe_invoice.pdf"]:::local
        A4["standup.mp4"]:::local
    end

    %% SDK Client Layer
    subgraph "SDK Client" 
        direction TB
        SDK["google-genai SDK"]:::sdk
    end

    %% Cloud Services Layer
    subgraph "Google AI Studio / Gemini Cloud Services"
        direction TB
        TEXT["Gemini Text Generation/Chat"]:::cloud
        MM["Gemini Multimodal Service"]:::cloud
        FUNC["Function-Calling & Tool Integration"]:::cloud
        MCP_STDIO["Model Context Protocol (stdio)"]:::cloud
        MCP_HTTP["Model Context Protocol (HTTP)"]:::cloud
    end

    %% External Tools & MCP Servers Layer
    subgraph "External Tools & MCP Servers"
        direction TB
        TOOL_NATIVE["Native Code Execution Tool"]:::external
        TOOL_SEARCH["Google Search Grounding Tool"]:::external
        USER_FUNC["User HTTP Service"]:::external
    end

    %% Data Flows
    NB0 -->|"import & configure API key"| SDK
    NB1 -->|"import & configure API key"| SDK
    NB2 -->|"import & configure API key"| SDK
    NB3 -->|"import & configure API key"| SDK
    NB4 -->|"import & configure API key"| SDK

    NB2 -->|"load asset"| A1
    NB2 -->|"load asset"| A2
    NB2 -->|"load asset"| A3
    NB2 -->|"load asset"| A4

    SDK -->|"API request"| TEXT
    SDK -->|"API request"| MM
    SDK -->|"function call payload"| FUNC
    SDK -->|"MCP handshake"| MCP_STDIO
    SDK -->|"MCP handshake"| MCP_HTTP

    TEXT -->|"API response"| SDK
    MM -->|"API response"| SDK
    FUNC -->|"API response"| SDK
    MCP_STDIO -->|"MCP message"| SDK
    MCP_HTTP -->|"MCP message"| SDK

    SDK -->|"return results"| NB1
    SDK -->|"return results"| NB2
    SDK -->|"return results"| NB3
    SDK -->|"return results"| NB4

    NB3 -->|"function call"| USER_FUNC
    USER_FUNC -->|"function result"| SDK
    USER_FUNC -->|"optional tool call"| TOOL_NATIVE
    USER_FUNC -->|"optional tool call"| TOOL_SEARCH

    %% Click Events
    click NB0 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/notebooks/00-setup-and-authentication.ipynb"
    click NB1 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/notebooks/01-text-generation-and-chat.ipynb"
    click NB2 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/notebooks/02-multimodal-capabilities.ipynb"
    click NB3 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/notebooks/03-structured-outputs-function-calling-tools.ipynb"
    click NB4 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/notebooks/04-model-context-protocol-mcp.ipynb"
    click SOL0 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/solutions/00-setup-and-authentication.ipynb"
    click SOL1 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/solutions/01-text-generation-and-chat.ipynb"
    click SOL2 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/solutions/02-multimodal-capabilities.ipynb"
    click SOL3 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/solutions/03-structured-outputs-function-calling-tools.ipynb"
    click SOL4 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/solutions/04-model-context-protocol-mcp.ipynb"
    click A1 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/assets/data/audio.mp3"
    click A2 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/assets/data/book.txt"
    click A3 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/assets/data/rewe_invoice.pdf"
    click A4 "https://github.com/philschmid/gemini-2.5-ai-engineering-workshop/blob/main/assets/data/standup.mp4"

    %% Styles
    classDef local fill:#D0E7FF,stroke:#0288D1,color:#000;
    classDef sdk fill:#D0FFD8,stroke:#388E3C,color:#000;
    classDef cloud fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef external fill:#E0E0E0,stroke:#757575,color:#000;
```
