Rumor Mill

Rumor Mill is an AI gossip agent system built around Bree: a voice-first persona that calls people, collects "tea", remembers what matters, and routes stories back through the network.

The repo includes:

• A local CLI chat interface for Bree
• A FastAPI webhook server for Twilio SMS and voice callbacks
• An outbound calling pipeline backed by ElevenLabs ConvAI
• A scheduler for invites, nudges, queued call jobs, and retry handling
• PostgreSQL persistence via SQLAlchemy + Alembic
• A simulation harness for exercising the production pipeline without real phone calls

Architecture

The main flow is:

1. Build a call context from the database
2. Assemble Bree's persona, mode script, memories, and context into a prompt
3. Start or receive a call through Twilio + ElevenLabs
4. Collect a transcript
5. Extract structured tea items from the transcript
6. Persist calls, tea, deliveries, and memory
7. Send post-call SMS followups

Key modules:

• src/rumor_mill/call.py: outbound call orchestration and post-call processing
• src/rumor_mill/context.py: context-pack builder for graph, storylines, and spill items
• src/rumor_mill/prompt.py: prompt assembly from persona/scripts/memory
• src/rumor_mill/agent.py: CLI conversation engine with Anthropic tool use
• src/rumor_mill/scheduler.py: invites, nudges, queued jobs, scheduled calls, retries
• src/rumor_mill/voice_webhook.py: inbound Twilio voice handling
• src/rumor_mill/sms/webhook.py: inbound SMS classification and dispatch
• src/rumor_mill/db/models.py: SQLAlchemy models for users, calls, tea, deliveries, memories, and audit state
• src/rumor_mill/simulation/engine.py: multi-day simulation over the production pipeline

Reference docs:

• docs/architecture.json: structured product and system overview
• docs/memory-system.md: canonical gossip flow vs prompt-memory projection model
• docs/voice-call-pipeline.md: detailed plan -> execute -> finalize call path and prompt map

Requirements

• Python 3.11+
• PostgreSQL for the DB-backed runtime
• Twilio credentials for SMS/voice
• ElevenLabs credentials for calling
• Anthropic credentials for prompt-time chat and extraction flows

Setup

Create a virtual environment, install the package, and configure environment variables:

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Common env vars used by the app include:

• DATABASE_URL
• ANTHROPIC_API_KEY
• TWILIO_ACCOUNT_SID
• TWILIO_AUTH_TOKEN
• TWILIO_FROM_NUMBER
• ELEVENLABS_API_KEY
• ELEVENLABS_AGENT_ID
• ELEVENLABS_PHONE_NUMBER_ID
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_DEFAULT_REGION
• RUMOR_MILL_CONFIG

Run database migrations with Alembic after configuring DATABASE_URL:

alembic upgrade head

Entry Points

Installed console scripts:

• rumor-mill: text chat with Bree in the terminal
• tea-admin: inspect users, calls, tea, and queue call jobs
• tea-call: place a call for a specific user/number
• tea-scheduler: run one scheduler pass or the production loop
• tea-prompt: manage prompt assets
• tea-webhook: run the FastAPI webhook server

Examples:

rumor-mill
tea-webhook
tea-scheduler --loop
tea-admin users
tea-call +15551234567 --user Ben --mode collect

Tests

Run the full test suite with:

python3 -m pytest

Useful targeted runs:

python3 -m pytest tests/test_scheduler.py
python3 -m pytest tests/test_call.py
python3 -m pytest tests/test_simulation.py
python3 -m pytest tests/test_e2e.py

If your local Python environment auto-loads unrelated global pytest plugins, run with PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 to keep the test environment isolated.

Simulation

The simulation engine runs the real production pipeline with fake calls in place of live ElevenLabs conversations. This is the safest way to exercise routing, extraction, deliveries, and memory flow end to end.

Example:

python3 -m rumor_mill.simulation.engine --days 3

Supporting simulation assets live under src/rumor_mill/simulation/ and config/simulation/.

Prompts And Config

Prompt and persona assets live under config/, including:

• config/persona.md
• config/scripts/
• config/extraction_prompt.md
• config/briefing_prompt.md
• config/memory_instructions.md
• config/sms_copy.yaml

Prompt content can also be loaded from S3 through the prompt management tooling in the repo.

Deploy

The app is containerized with the root Dockerfile. Deployment helper scripts live under infra/.

Relevant files:

• Dockerfile
• infra/deploy.sh
• infra/push-image.sh
• infra/populate-secrets.sh

Repo Notes

• There was no root README before this file; the main in-repo system references now live in docs/architecture.json, docs/memory-system.md, and docs/voice-call-pipeline.md.
• Long-form docs under docs/ use the Markdown files as source of truth; sibling rendered HTML previews are local artifacts unless explicitly tracked (for example docs/architecture.html).
• The worktree may include planning docs under docs/superpowers/plans/ that are useful as implementation history but are not the runtime source of truth.