GenAI Processors: a stream-based Python library for Gemini pipelines

The fragmentation problem GenAI Processors targets

The README states the library exists to address "the fragmentation of LLM APIs" through three pillars: a unified content model, processors, and streaming. In practice that means one representation for inputs and outputs whether the content came from a text model, a live audio session or a tool call. ProcessorPart wraps genai.types.Part and adds metadata such as MIME type, role and custom attributes. ProcessorContent is the container around it.

The audience is narrow and specific: Python developers building Gemini applications who are tired of writing the same adapter code for each API surface. If your application only ever sends a string to a text model and prints the reply, the abstraction costs more than it returns. The library starts paying off when one pipeline mixes turn-based calls, real-time audio and tool use, because that is where the plumbing normally multiplies.

Processor, ProcessorStream and the dual-interface pattern

A Processor is a unit of work. Authors implement call, which takes a ProcessorStream and yields parts as they arrive. Callers use the other side of the same object: they can pass forgiving input such as a plain string or a list, and they get back a stream they can gather, read as text, or iterate chunk by chunk.

The README calls this the dual-interface pattern, and it is the design decision that shapes everything else. The producer side sees a stream and yields part types. The consumer side sees wide input types and a stream object with convenience methods. Composition happens through operators: processors chain with + and run in parallel with //. Stream management utilities handle splitting, concatenating and merging asynchronous streams of parts.

Concurrency is plain asyncio, which the README notes covers network I/O and communication with compute-heavy subthreads. There is no separate scheduler to learn. The trade-off is that you inherit asyncio's debugging experience: a processor that swallows an exception inside an async generator gives you a stalled stream rather than a stack trace at the call site.

Installing GenAI Processors and running a first processor

The README requires Python 3.10+, while pyproject.toml declares requires-python = ">=3.11". Treat 3.11 as the floor. Installation is one command from PyPI:

pip install genai-processors

The package name on PyPI is genai-processors while the import name is genai_processors. That mismatch trips people up in the first five minutes. Once installed, the smallest useful thing is to subclass Processor and echo its input, following the EchoProcessor example in the README:

from typing import AsyncIterable
from genai_processors import content_api
from genai_processors import processor

class EchoProcessor(processor.Processor):
  async def call(
      self, content: content_api.ProcessorStream
  ) -> AsyncIterable[content_api.ProcessorPartTypes]:
      async for part in content:
          yield part

Calling it exercises the consumer interface. The README passes a list mixing a string and a ProcessorPart, then shows the three ways to collect the result:

input_content = ["Hello ", content_api.ProcessorPart("World")]
result: content_api.ProcessorContent = await simple_text_processor(input_content).gather()
print(await simple_text_processor(input_content).text())
async for part in simple_text_processor(input_content):
  print(part.text, end="")

gather() collects everything into one ProcessorContent. text() returns the concatenated text, which is what the README recommends for text-only agents. Iterating the stream directly is the path for streaming use cases. After this, the README points at the documentation microsite and four Colab notebooks, in order: content_api_intro, processor_intro, create_your_own_processor and live_processor_intro.

What the dependency list commits you to

pyproject.toml lists the runtime dependencies, and they are not small. Alongside google-genai and absl-py you get opencv-python, numpy, Pillow, pypdfium2, pdfrw, webrtcvad, google-cloud-speech, google-cloud-texttospeech, sqlalchemy, mcp, jinja2, httpx and more. Optional dependencies for the contrib processors are deliberately split out, with pyproject.toml noting that the goal is to avoid dependency bloat in the main set.

That split helps, but the base install still carries computer vision, PDF and speech packages. If you are building a text-only agent, you are paying install size and image build time for libraries you will not import. This is a real cost in containerised deployments where layer size matters, and the README does not offer a slim extra to opt out of it.

Live streaming, GenaiModel and LiveProcessor

Two built-in processors cover the Gemini API surfaces. GenaiModel handles turn-based API calls. LiveProcessor handles real-time streaming interactions against the Gemini Live API. The examples directory shows what these look like assembled: realtime_simple_cli.py is an audio-in, audio-out live agent with Google Search as a tool, described in the README as a client-side implementation of a Live processor built with text-based Gemini API models. The live_commentator example composes two agents, one for event detection and one for managing the conversation.

The live_commentator example is the more instructive one because it shows the composition model doing actual work rather than demonstrating an API call. Two agents with different responsibilities, wired through the same Processor interface, is the pattern the library is selling. If your application is a single prompt and a single response, none of this applies to you.

One caveat the README does not resolve: it says the core/ directory "will evolve over time to include more core components". That is an explicit statement that the built-in set is not settled, which matters if you plan to depend on a specific processor's behaviour.

Where GenAI Processors is the wrong tool

The library is Gemini-specific. The built-in processors are GenaiModel and LiveProcessor, and the dependency list includes google-genai, google-cloud-speech and google-cloud-texttospeech. If your stack is Anthropic, OpenAI or a self-hosted model, the core abstractions might still be useful, but you would be writing every model processor yourself and carrying Google Cloud packages you do not call. The examples directory does include trip_request_cli_ollama.py, so an Ollama path exists in the examples, but the README does not present non-Gemini support as a supported direction.

Version churn is the second concern. v2.0.0 shipped in March 2026, following v1.1.1 and v1.1.0. A major version bump within roughly a year of the prior minor releases is normal for a young library, but it means code written against v1.x may need changes. The README does not document a migration guide, and it does not document rollback either. Pin your version and read the release notes before upgrading.

The third case is simpler: if you want a graph-based agent framework with a visual debugger and persistent state, this is not that. GenAI Processors is a composition layer over streams, not an orchestration platform.

How it compares to calling google-genai directly

The honest alternative is the google-genai SDK on its own. You get the same model access, the same Part types, and no additional abstraction between your code and the API. For a script that sends a prompt and reads a response, the SDK is less code and fewer dependencies.

The difference in approach shows up when content arrives from more than one place at once. With the raw SDK you write the fan-in yourself: collect partial responses, merge audio chunks with text, decide when a stream is complete. GenAI Processors gives you the + and // operators, ProcessorStream and the stream management utilities for splitting, concatenating and merging. The README's own framing is that streaming is "built-in by default, without added plumbing complexity".

So the choice is not about capability but about where the plumbing lives. Direct SDK use puts it in your application. GenAI Processors puts it in a library that is still on a fast release cadence, which is the trade you are making.

Licence, maintenance and the cost of upgrading

The project is Apache-2.0, declared in pyproject.toml as license = {file = "LICENSE"} and shown in the README badge. Apache-2.0 permits commercial use and modification and includes a patent grant. It also requires that you preserve copyright and licence notices and state significant changes. This is a summary of the licence text, not legal advice; check the LICENSE file and your own counsel for anything that matters.

The repository is not archived, and the last push was on 2026-09-09. The release history is v1.1.0, v1.1.1 and v2.0.0, with v2.0.0 dated 2026-03-10. There is a CONTRIBUTING.md at the top level and a contrib/ directory for community processors, so there is a defined path for outside contributions.

The upgrade cost is the part to budget for. A major version bump on a library whose core abstraction is an async streaming interface can change behaviour in ways that surface as silent stalls rather than exceptions. Pin the version in your lockfile, read the v2.0.0 release notes before moving, and keep your custom processors thin so a signature change in the base class is a small edit.

Editorial conclusion

Adopt GenAI Processors if you are already building on google-genai and want model calls, live audio and tool use expressed as composable asyncio processors instead of hand-rolled stream plumbing. Do not adopt it if you need a stable API surface, if you are not on Gemini, or if you cannot accept the dependency list in pyproject.toml, which pulls in opencv-python, numpy, webrtcvad, google-cloud-speech and google-cloud-texttospeech even for text-only work. Before committing, read llms.txt, run the four Colab notebooks in the order the README lists, and check whether the v2.0.0 release notes describe a migration path from v1.x.

Frequently asked questions

Official sources

1. google-gemini/genai-processors on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases