# GenAI Processors Library 🚀

**Build Modular, Asynchronous, and Composable AI Pipelines for Generative AI.**

GenAI Processors is a lightweight Python library that implements efficient,
parallel content processing.


At the core of the GenAI Processors library lies the concept of `Processor`,
that encapsulates a unit of work with the following simple API taking a stream
of `ProcessorPart`s as input and returning a stream of `ProcessorPart`s (or
compatible types) as output.

By processing diverse input modalities in a bidirectional streaming fashion,
Processors are helpful for streamlining agent development, in particular for
building agents using the
[Gemini Live API](https://ai.google.dev/gemini-api/docs/live).

```python
async def call(
  content: AsyncIterable[ProcessorPart]
) -> AsyncIterable[ProcessorPartTypes]
```

The concept of `Processor` provides a common abstraction for Gemini model calls
and increasingly complex behaviors built around them, accommodating both
turn-based interactions and live streaming.

The GenAI Processors library offers an easy and intuitive way to create and
combine these processors and arranges for their async execution in the most
efficient way.

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
<!-- Add badges for PyPI version once available -->

## 🌟 Key Features

*   **Modular**: Breaks down complex tasks into reusable `Processor` and
    `PartProcessor` units, which are easily chained (`+`) or parallelized (`//`)
    to create sophisticated data flows and agentic behaviors.
*   **Integrated with GenAI API**: Includes ready-to-use processors like
    `GenaiModel` for turn-based API calls and `LiveProcessor` for real-time
    streaming interactions.
*   **Extensible**: Lets you create custom processors by inheriting from base
    classes or using simple function decorators.
*   **Rich Content Handling**:
    *   `ProcessorPart`: A wrapper around `genai.types.Part` enriched with
        metadata like MIME type, role, and custom attributes.
    *   Supports various content types (text, images, audio, custom JSON).
*   **Asynchronous & Concurrent**: Built on Python's familiar `asyncio`
    framework to orchestrate concurrent tasks (including network I/O and
    communication with compute-heavy subthreads).
*   **Stream Management**: Has utilities for splitting, concatenating, and
    merging asynchronous streams of `ProcessorPart`s.

## 📦 Installation

The GenAI Processors library requires Python 3.10+.

Install it with:

```bash
pip install genai-processors
```

## 🚀 Getting Started

Check the following colabs to get familiar with GenAI processors (we recommend
following them in order):

*   [content api colab](notebooks/content_api_intro.ipynb) - explains the basics
    of `ProcessorPart`, `ProcessorContent`, and how to create them.
*   [processor intro colab](notebooks/processor_intro.ipynb) - an introduction
    to the core concepts of GenAI Processors.
*   [create your own](notebooks/create_your_own_processor.ipynb) - a walkthrough
    of the typical steps to create a `Processor` or a `PartProcessor`.

## 📖 Examples

Explore the [examples/](examples/) directory for practical demonstrations:

*   [Research Agent colab](examples/research/genai_research_api.ipynb) -
    research agent built with Processors and comprising 3 sub-processors;
    chaining; creating `ProcessorPart`s; etc.
*   [Live Commentary example](examples/live/README.md) - description of the live
    commentary agent built with the Gemini Live API and composed of 2 agents,
    one for event detection and one for managing the conversation.

## 🧩 Built-in Processors

The [core/](core/) directory contains a set of basic processors that you can
leverage in your own applications. It includes the generic building blocks
needed for most real-time applications. This directory will evolve over time
including more core components to build more capabilities over time.

Community contributions expanding the set of built-in processors are under
[contrib/](contrib/) - see section below on how to add code to the GenAI
Processor library.

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for
guidelines on how to contribute to this project.

## 📜 License

This project is licensed under the Apache License, Version 2.0. See the
[LICENSE](LICENSE) file for details.
