Stallbot

Stallbot is a rule-based persona ("Margaret, 78, hard of hearing, chatty") that answers a phone spammer with stalling, tangents and misunderstandings, so the spammer wastes time instead of reaching a real person. It never gives out real information and never completes a number.

Pure Python standard library: no API keys, no network calls, no telephony.

Who it is for

Anyone who wants the engine behind an idea like this post:

"I would pay for an app that answers a 'Spam Risk' call with an AI that wastes the time of the spammer" https://bsky.app/profile/electproject.bsky.social/post/3mxad2w6ui22y

Today you type (or paste) what the caller says and read the reply.

Run

Requires Python 3.8+. From the repo root:

• Interactive terminal, you play the spammer: python3 -m stallbot.cli
• Seeded demo, rewrites docs/demo.txt: python3 -m stallbot.cli demo
• Play a file of caller lines (one per row): python3 -m stallbot.cli --script lines.txt --seed 1
• Local web page: python3 -m stallbot.server, then open http://127.0.0.1:8765 (binds to 127.0.0.1 only; JSON API at POST /api/reply)
• Tests: python3 -m unittest discover -s tests

Layout

• stallbot/engine.py: rules, replies, time estimate
• stallbot/cli.py: terminal chat and demo
• stallbot/server.py, stallbot/index.html: local web page and API
• docs/demo.txt: sample transcript from the seeded demo

Decisions

• This repo briefly held two overlapping implementations of the same idea. I kept the stallbot/ package (separate engine, CLI and web server, with a testable API and per-rule labels) and folded in the better parts of the other one: its demo script, its extra reply topics (legal threats, prizes, loans) and its test ideas.
• Dropped the optional local-LLM hook: it added a network path and made output non-deterministic. Rules keep the tool offline and reproducible.
• Rules are checked in priority order and the first match wins; sensitive requests (cards, gift cards, SSN, passwords) come first, so "payment immediately in gift cards" gets a stall about finding glasses, not a cheerful refund line.
• A reply is not repeated until all options of its topic have been used.
• The demo is seeded, so docs/demo.txt is reproducible.

Known limits

• Text only. There is no telephony: answering real calls would need a phone number, speech-to-text and text-to-speech, which are out of scope.
• Rule-based, not an LLM. A human spammer will notice the canned lines after a while.
• "Time wasted" is an estimate (spoken words at about 2.5 per second plus 4 s of pretend searching per turn), not a measurement.
• Web sessions live in memory with no cleanup; meant for local use.

License

MIT, see LICENSE.