Pollux

Multimodal orchestration for LLM APIs.

You describe what to analyze. Pollux handles source patterns, context caching, and multimodal complexity—so you don't.

Documentation · Quickstart · Cookbook

Quick Start

import asyncio
from pollux import Config, Source, run

result = asyncio.run(
    run(
        "What are the key findings?",
        source=Source.from_text(
            "Pollux supports fan-out, fan-in, and broadcast source patterns. "
            "It also supports context caching for repeated prompts."
        ),
        config=Config(provider="gemini", model="gemini-2.5-flash-lite"),
    )
)
print(result["answers"][0])
# "The key findings are: (1) three source patterns (fan-out, fan-in,
#  broadcast) and (2) context caching for token and cost savings."

run() returns a ResultEnvelope dict — answers is a list with one entry per prompt.

To use OpenAI instead: Config(provider="openai", model="gpt-5-nano").

For a full 2-minute walkthrough (install, key setup, success checks), see the Quickstart.

Why Pollux?

• Multimodal-first: PDFs, images, video, YouTube URLs, and arXiv papers—same API
• Source patterns: Fan-out (one source, many prompts), fan-in (many sources, one prompt), and broadcast (many-to-many)
• Context caching: Upload once, reuse across prompts—save tokens and money
• Structured output: Get typed responses via Options(response_schema=YourModel)
• Built for reliability: Async execution, automatic retries, concurrency control, and clear error messages with actionable hints

Installation

pip install pollux-ai

API Keys

Get a key from Google AI Studio or OpenAI Platform, then:

# Gemini (recommended starting point — supports context caching)
export GEMINI_API_KEY="your-key-here"

# OpenAI
export OPENAI_API_KEY="your-key-here"

Usage

Multi-Source Analysis

import asyncio

from pollux import Config, Source, run_many

async def main() -> None:
    config = Config(provider="gemini", model="gemini-2.5-flash-lite")
    sources = [
        Source.from_file("paper1.pdf"),
        Source.from_file("paper2.pdf"),
    ]
    prompts = ["Summarize the main argument.", "List key findings."]

    envelope = await run_many(prompts, sources=sources, config=config)
    for answer in envelope["answers"]:
        print(answer)

asyncio.run(main())

YouTube and arXiv Sources

from pollux import Source

lecture = Source.from_youtube("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
paper = Source.from_arxiv("2301.07041")

Pass these to run() or run_many() like any other source — Pollux handles the rest.

Structured Output

import asyncio

from pydantic import BaseModel

from pollux import Config, Options, Source, run

class Summary(BaseModel):
    title: str
    key_points: list[str]
    sentiment: str

result = asyncio.run(
    run(
        "Summarize this document.",
        source=Source.from_file("report.pdf"),
        config=Config(provider="gemini", model="gemini-2.5-flash-lite"),
        options=Options(response_schema=Summary),
    )
)
parsed = result["structured"]  # Summary instance
print(parsed.key_points)

Configuration

from pollux import Config

config = Config(
    provider="gemini",
    model="gemini-2.5-flash-lite",
    enable_caching=True,  # Gemini-only in v1.0
)

See the Configuration Guide for details.

Provider Differences

Pollux does not force strict feature parity across providers in v1.0. See the capability matrix: Provider Capabilities.

Documentation

• Quickstart — First result in 2 minutes
• Concepts — Mental model for source patterns and caching
• Sources and Patterns — Source constructors, run/run_many, ResultEnvelope
• Configuration — Providers, models, retries, caching
• Caching and Efficiency — TTL management, cache warming, cost savings
• Troubleshooting — Common issues and solutions
• API Reference — Entry points and types
• Cookbook — Scenario-driven, ready-to-run recipes

Contributing

See CONTRIBUTING and TESTING.md for guidelines.

Built during Google Summer of Code 2025 with Google DeepMind. Learn more

License

MIT