GorillaOps — Celebrity Squadron Builder

GorillaOps is a playful, satirical LLM + Retrieval classifier where you type a list of famous names and the app assigns each person to a "squadron" for the hypothetical question of 2025:

“1 Gorilla vs 100 men — who’s on the team and what role do they play?”

This project was designed to show thoughtful architecture (LLM routing + rule-based fallback + Wikipedia retrieval + YAML policy config), a modern Python GUI (Streamlit), reproducible tests, and an extensible design that can evolve into a more serious "entity-to-role" classifier for operations planning (e.g., incident response roles, conference staffing, volunteer coordination, etc.).

Content note

This app is satire and should be treated like a party game or creative writing prompt. It must not be used to harass, defame, or make factual claims about real people. By default, the GUI enables Safety Mode, softens negative labels, and allows opting out of sensitive categories.

What it does

• Lets you paste or type public-figure names (one per line).
• Retrieval-Augmented Classification: fetches Wikipedia summaries for each name to ground attributes before classification.
• Classifies each name into one of 10 themed “squadrons” using an LLM, with a deterministic rule-based + retrieval fallback if no API key is provided.
• Shows results in a table grouped by squadron; supports CSV/JSON export.
• Provides YAML-based policy for categories, descriptions, examples, and safety toggles.
• Abstracts the LLM behind an OpenAI-compatible REST client, so you can use OpenAI, OpenRouter, Together, Groq, or a local OpenAI-compatible server by changing env vars.

Quickstart

1. Python 3.10+

2. Install:

pip install -r requirements.txt

3. (Optional) Set API for an OpenAI-compatible endpoint:

# Standard OpenAI usage
export OPENAI_API_KEY=sk-...

# To point at any OpenAI-compatible server (optional)
# export OPENAI_BASE_URL=https://api.openai.com/v1
# export OPENAI_MODEL=gpt-4o-mini

4. Run the GUI:

streamlit run app/app.py

5. Paste names (one per line), toggle Fetch Wikipedia summaries, click Classify, and download results.

Safety & satire defaults

• Safety Mode ON by default: uses softer phrasing and avoids hard negative labels (“Traitors” can be toggled off).
• Rule-only mode available: no LLM, just transparent, deterministic rules (+ fuzzy string matching) using publicly known professions.
• If a name is unknown or ambiguous, output is "Unknown".

The 10 categories are configurable in data/squadron_rules.yaml

Retrieval‑Augmented Classification (Wikipedia)

Enable Fetch Wikipedia summaries in the sidebar to ground classification:

• The app calls the Wikipedia REST Summary API to get a short description per name (cached with requests-cache).
• Rule+Wiki: If the rule engine returns unknown, a transparent keyword extractor maps bios to categories (e.g., “sprinter” → Distractions, “astrophysicist” → Battle Strategists).
• LLM+Wiki The LLM prompt gets a per-name context block with the (truncated) summary to improve JSON role assignment.
• If offline or a page is a disambiguation, the app continues without the summary.

File tree

gorillaops-squadron-builder/
├── README.md
├── LICENSE
├── requirements.txt
├── .env.example
├── app/
│   ├── app.py
│   ├── llm_router.py
│   ├── classifier.py
│   ├── retrieval.py
│   ├── feature_extractor.py
│   └── ui_helpers.py
├── data/
│   └── squadron_rules.yaml
├── scripts/
│   ├── run.sh
│   └── dev.sh
└── tests/
    ├── test_classifier.py
    └── test_features.py

Configuration

• OPENAI_API_KEY — your key (optional; if missing, rule-engine + retrieval is used).
• OPENAI_BASE_URL — OpenAI-compatible base (default: https://api.openai.com/v1).
• OPENAI_MODEL — model name string (default: gpt-4o-mini).

Testing

pytest -q

---

Simple Green/White Desktop GUI (Tkinter)

Prefer a minimal desktop app? Launch the GUI:

python -m app.simple_gui

• Paste names (one per line), toggle Fetch Wikipedia summaries and/or Use LLM.
• Click Classify to populate the table.
• Use Export CSV/JSON buttons to save results.