Gata Newsroom

An automated multi-agent pipeline that transforms daily topics into a recurring satirical cartoon series starring Gata, a serious investigative calico cat who views all geopolitics through the lens of feline priorities.

Install

pipx install gata

If pipx is not installed: sudo apt install pipx && pipx ensurepath

Required API keys

Three LLM provider accounts are required before you can run Gata:

Auto-topic mode (pipeline.py without --topic) also requires a NewsAPI.org key in NEWSAPI_ORG_KEY. The gata command always requires a topic — Trend Scout is never used by it.

Export the keys in your shell, or place them in a .env file in the project root (it is gitignored and never committed):

# Option A — shell environment
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...
export XAI_API_KEY=...
export NEWSAPI_ORG_KEY=...   # only needed for auto-topic mode

# Option B — .env file (loaded automatically on startup)
ANTHROPIC_API_KEY=your_key_here
GEMINI_API_KEY=your_key_here
XAI_API_KEY=your_key_here
NEWSAPI_ORG_KEY=your_key_here

Quick start

gata "World Cup final: Argentina vs France"

This infers the most culturally relevant audience, negotiates a cultural angle, generates three independent cartoon concepts, picks the strongest one, and saves two PNGs to your working directory — one for the inferred audience and one for the UK public.

How it works

1. Trend Scout fetches today's top headlines for the community and ranks them by satirical potential; only used by pipeline.py when --topic is not supplied — the gata command always requires a topic and never invokes Trend Scout
2. Cultural Strategist — three Framers (Claude, Grok-build, Gemini) independently propose a cultural angle; Grok-4.3 (Resonator) aggregates and picks the sharpest one
3. Satirist — three Panelists (Claude, Grok-build, Gemini) independently generate a cartoon concept; Grok-4.3 (Aggregator) picks the strongest concept
4. Image Generator renders the approved concept into a PNG via a fallback chain of Gemini image models; overlays the Satirist-authored title as a dark banner at the top (suppressed with --no-title). When --linkedin-post is set and the layout is single-panel or horizontal, the saved file is corrected to exactly LinkedIn's 1200x644 Article-cover size — cropped/resized before the title banner, then re-fitted afterward so the banner never pushes it off-size; a vertical multi-panel cartoon is left untouched
5. Explainer (opt-in via --html) — three Writers (Claude, Grok-build, Gemini) independently draft an HTML explanation page; Grok-4.3 (Editor) picks the best one; runs twice — once in the target language, once in English
6. Bundle Writer saves the full output package: image, conversation logs, prompt card, telemetry, and summary

Agents

gata command

The simplest way to run the pipeline. Give it any topic and it generates two satirical cartoons: one for the most culturally relevant audience (inferred automatically) and one for the UK public.

# Generate cartoons for a news topic
gata "Interest rates stay high despite falling inflation"

# Any topic works — Gata will find the angle
gata "World Cup final: Argentina vs France"
gata "Tech layoffs hit Silicon Valley again"
gata "Portugal wins Eurovision"

# Skip the Cultural Strategist — feed the topic straight to the Satirist
gata "AI is replacing junior developers" --direct

# Also generate HTML explanation pages
gata "NATO summit in Brussels" --html

# Generate a researched (non-satirical) companion article alongside the cartoon
gata "Vibe coding in production" --linkedin-post
gata "Vibe coding in production" --linkedin-post --angle "where it should not be used" --angle "where it's fine as long as..."

Output folder: {cwd}/{topic_slug}/ — one PNG per audience, plus a bundle folder per image. Run gata --help to see all options.

pipeline.py — advanced usage

# Named community (exact match in communities.yaml; topic selected by Trend Scout)
python pipeline.py --community uk-politics

# Free-text community (no entry required in communities.yaml)
python pipeline.py --community "US community that dislikes Trump"
python pipeline.py --community "Communauté française qui critique Macron"

# Community + topic mode (topic supplied directly — no Trend Scout)
python pipeline.py --community uk-politics --topic "Number 10 is becoming available for rent, again."
python pipeline.py --community "Adeptos portugueses de futebol" --topic "O Ronaldo vai levar Portugal ao mundial"

# Random community and topic
python pipeline.py

# Manual mode (bypasses communities.yaml entirely)
python pipeline.py --topic "AI hype" --audience "developers" --language "English" --tone "dry wit"

# Multi-panel cartoon
python pipeline.py --community uk-politics --panels 3 --layout horizontal
python pipeline.py --community portuguese-adults --panels 2 --layout vertical

# HTML explanation pages + suppress title banner
python pipeline.py --community uk-politics --html --no-title

# Skip the Cultural Strategist (direct mode)
python pipeline.py --topic "AI hype" --audience "developers" --language "English" --direct

# Custom LLM provider chains via providers.yaml
python pipeline.py --community uk-politics --providers providers.yaml

# Researched (non-satirical) companion article, with operator-supplied angles
python pipeline.py --topic "Vibe coding in production" --audience "engineering leaders" --language English --tone neutral --direct --linkedin-post --angle "where it should not be used" --angle "where it's fine as long as..."

Multi-panel flags

Output bundle

Each run writes a bundle folder containing:

Communities

Communities are defined in communities.yaml. Each community specifies a target audience, output language, tone, seed topics, and optionally a default panel count.

To add a new community, add an entry to communities.yaml — no code changes required.

LLM provider configuration (providers.yaml)

providers.yaml controls which LLM models handle each agent role and in what fallback order. It is optional — if absent, Gata uses its built-in defaults (Claude Sonnet, Grok grok-build-0.1, and Gemini Flash as panelists; Grok grok-4.3 as aggregator).

Each panelist slot is an ordered fallback chain. If the primary model fails, the next model in the slot is tried — including across provider boundaries (cross-provider fallback). The aggregator entry works the same way.

panelists:
  - - provider: claude
      model: claude-sonnet-4-6
      timeout: 25.0        # optional: per-call limit in seconds
    - provider: gemini
      model: gemini-2.5-flash
      timeout: 15.0
  - - provider: grok
      model: grok-build-0.1
    - provider: gemini
      model: gemini-2.5-flash

aggregator:
  - provider: grok
    model: grok-4.3
  - provider: claude
    model: claude-sonnet-4-6

The optional timeout field (Spec 036) gives each provider its own per-call budget. If a provider stalls beyond that limit it is abandoned and the next provider in the chain starts with a fresh budget. Omit timeout (the default) to keep unbounded calls.

Load a custom file with --providers providers.yaml or place it in ./providers.yaml (auto-discovered).

Comedy configuration (humor.yaml)

humor.yaml controls comedy style and agent personality. All fields default to off.

Inconvenience levels: 0 = off; 1–33 = mild nudge; 34–66 = medium push; 67–100 = maximum.

Install from source (development)

python -m venv .venv && source .venv/bin/activate
pip install -e .

Architecture

See docs/architecture.md for agent diagrams and the communication protocol framework.

Status