# google-gemini/genai-processors architecture

> Architecture diagram of the GitHub repository google-gemini/genai-processors, 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/google-gemini/genai-processors
- Repository: https://github.com/google-gemini/genai-processors

## Overview

##### Project type and purpose
- This is a Python library (genai-processors) for building modular, asynchronous, composable pipelines around generative-AI models.
- It provides abstractions like `Processor`, `ProcessorPart`, and streaming utilities to orchestrate AI calls (text, audio, video, etc.) and custom logic.

##### File structure
- Top-level:
- `genai_processors/` – core package
– `core/` – built-in Processor implementations (GenAIModel, LiveProcessor, audio/text I/O, etc.)
– `contrib/` – community-contributed processors
– utility modules: `cache.py`, `streams.py`, `switch.py`, `mime_types.py`, etc.
– `processor.py` – base `Processor` class
– tests/ – unit tests for all modules
- `examples/` – sample CLI and web apps demonstrating usage (live commentary, research agent, speech/text CLIs)
- `notebooks/` – interactive tutorials
- CI config, packaging (`pyproject.toml`), documentation (`README.md`, CONTRIBUTING.md)

##### README for additional insights
- Describes `Processor` abstraction: input/output are async streams of `ProcessorPart`s.
- Highlights built-in models (GenaiModel, LiveProcessor), stream utilities, and extensibility.
- Points to example flows like chaining (`+`), parallel (`//`), part creation, and Jinja templating.

##### Elements
- Data flow (ProcessorPart streams) between modules
- API calls from Processors to external services
- Composition relationships (`+`, `//`)

Final best practices:
- Lay out core abstractions centrally.
- Surround with built-in modules and contrib modules that implement those abstractions.
- Example apps at the perimeter, invoking the central pipeline.
- Async stream backbone connecting everything.
- Module with its key responsibility (e.g., “speech_to_text: audio → text parts”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Abstractions
    subgraph "Core Abstractions"
        direction TB
        ProcessorBase["Processor (base class)"]:::core
        ProcessorPart["ProcessorPart / Context"]:::core
        MapCombine["Map/Combine Processors"]:::core
    end

    %% Stream Utilities
    subgraph "Stream Utilities"
        direction TB
        Streams["streams (split, merge, content)"]:::streams
        Switch["switch (parallel/conditional routing)"]:::streams
    end

    %% Built-in Processors
    subgraph "Built-in Processors"
        direction TB
        GenAIModel["GenAI API model"]:::builtIn
        LiveModel["Live/streaming model"]:::builtIn
        OllamaModel["Ollama model"]:::builtIn
        AudioIO["audio_io"]:::builtIn
        SpeechToText["speech_to_text"]:::builtIn
        TextToSpeech["text_to_speech"]:::builtIn
        PDF["pdf processor"]:::builtIn
        Video["video processor"]:::builtIn
        EventDetection["event_detection"]:::builtIn
        Realtime["realtime wrapper"]:::builtIn
        RateLimitAudio["rate_limit_audio"]:::builtIn
        JinjaTemplate["jinja_template"]:::builtIn
        DriveConnector["drive connector"]:::builtIn
        GitHubConnector["github connector"]:::builtIn
        MIME["mime_types support"]:::builtIn
    end

    %% Contrib Processors
    subgraph "Contrib Processors"
        direction TB
        ContribRoot["Community extensions"]:::contrib
    end

    %% Utilities & Support
    subgraph "Utilities & Support"
        direction TB
        Cache["cache layer"]:::utils
        ContentAPI["content_api wrapper"]:::utils
        Debug["debug helpers"]:::utils
    end

    %% Examples & Tutorials
    subgraph "Examples & Tutorials"
        direction TB
        LiveApps["Live apps & CLIs"]:::examples
        CLISamples["Speech/Text/PDF CLIs"]:::examples
        Research["Research agent demos"]:::examples
        SimpleCLIs["Simple CLIs"]:::examples
        Notebooks["Notebooks"]:::examples
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GenAIApi["Gemini REST & Live APIs"]:::external
        OllamaApi["Ollama API"]:::external
        GoogleDrive["Google Drive"]:::external
        GitHubSvc["GitHub"]:::external
        PDFService["PDF service"]:::external
    end

    %% Relationships
    LiveApps -->|"invokes pipeline"| ProcessorBase
    CLISamples -->|"invokes pipeline"| ProcessorBase
    Research -->|"invokes pipeline"| ProcessorBase
    SimpleCLIs -->|"invokes pipeline"| ProcessorBase
    Notebooks -->|"invokes pipeline"| ProcessorBase

    ProcessorBase -->|"uses async streams"| Streams
    MapCombine -->|"uses routing"| Switch

    GenAIModel -->|"implements"| ProcessorBase
    LiveModel -->|"implements"| ProcessorBase
    OllamaModel -->|"implements"| ProcessorBase
    AudioIO -->|"implements"| ProcessorBase
    SpeechToText -->|"implements"| ProcessorBase
    TextToSpeech -->|"implements"| ProcessorBase
    PDF -->|"implements"| ProcessorBase
    Video -->|"implements"| ProcessorBase
    EventDetection -->|"implements"| ProcessorBase
    Realtime -->|"implements"| ProcessorBase
    RateLimitAudio -->|"implements"| ProcessorBase
    JinjaTemplate -->|"implements"| ProcessorBase
    DriveConnector -->|"implements"| ProcessorBase
    GitHubConnector -->|"implements"| ProcessorBase
    MIME -->|"implements"| ProcessorBase

    ContribRoot -->|"extends"| ProcessorBase

    Cache -->|"supports"| ProcessorBase
    ContentAPI -->|"supports"| ProcessorBase
    Debug -->|"supports"| ProcessorBase

    GenAIModel -->|"HTTP request/response"| GenAIApi
    LiveModel -->|"streaming API"| GenAIApi
    OllamaModel -->|"HTTP API"| OllamaApi
    DriveConnector -->|"REST calls"| GoogleDrive
    GitHubConnector -->|"REST calls"| GitHubSvc
    PDF -->|"external service"| PDFService

    ProcessorBase --- ProcessorPart

    %% Click Events
    click ProcessorBase "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/processor.py"
    click ProcessorPart "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/context.py"
    click MapCombine "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/map_processor.py"
    click Streams "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/streams.py"
    click Switch "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/switch.py"
    click GenAIModel "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/genai_model.py"
    click LiveModel "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/live_model.py"
    click OllamaModel "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/ollama_model.py"
    click AudioIO "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/audio_io.py"
    click SpeechToText "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/speech_to_text.py"
    click TextToSpeech "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/text_to_speech.py"
    click PDF "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/pdf.py"
    click Video "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/video.py"
    click EventDetection "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/event_detection.py"
    click Realtime "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/realtime.py"
    click RateLimitAudio "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/rate_limit_audio.py"
    click JinjaTemplate "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/jinja_template.py"
    click DriveConnector "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/drive.py"
    click GitHubConnector "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/core/github.py"
    click MIME "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/mime_types.py"
    click ContribRoot "https://github.com/google-gemini/genai-processors/tree/main/genai_processors/contrib/"
    click Cache "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/cache.py"
    click ContentAPI "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/content_api.py"
    click Debug "https://github.com/google-gemini/genai-processors/blob/main/genai_processors/debug.py"
    click LiveApps "https://github.com/google-gemini/genai-processors/tree/main/examples/live/"
    click CLISamples "https://github.com/google-gemini/genai-processors/tree/main/examples/"
    click Research "https://github.com/google-gemini/genai-processors/tree/main/examples/research/"
    click SimpleCLIs "https://github.com/google-gemini/genai-processors/blob/main/examples/live_simple_cli.py"
    click Notebooks "https://github.com/google-gemini/genai-processors/tree/main/notebooks/"

    %% Styles
    classDef core fill:#B3E5FC,stroke:#1E88E5,color:#0D47A1
    classDef streams fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef builtIn fill:#FFCCBC,stroke:#E64A19,color:#BF360C
    classDef contrib fill:#D1C4E9,stroke:#8E24AA,color:#4A148C
    classDef utils fill:#F0F4C3,stroke:#AFB42B,color:#827717
    classDef examples fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef external fill:#CFD8DC,stroke:#78909C,color:#263238
```
