- package src/sigcal_bot, distribution and CLI sigcal-bot - environment variables SIGCAL_BOT_* - database file, container names, user agents, logs and QR device name - docs and changelog updated
5.7 KiB
AGENTS.md
Guidance for AI agents (and humans) changing this repository.
What this is
A single-purpose service: it polls an iCalendar feed (The Events Calendar /
MCR Commons) and posts events, with poster images, to one Signal group. Signal
has no bot API, so sending goes through signal-cli-rest-api in Docker.
Read README.md for the user-facing behaviour and setup.
Layout
src/sigcal_bot/
config.py TOML loading, defaults, duration/time parsers
feed.py conditional GET; validators committed only after parse
expand.py iCalendar -> Event; series-ID heuristics; recurrence expansion
format.py the group's post template (title/hashtags/time/venue/link)
images.py page scraping (venue, og:image) + poster download/resize/cache
store.py SQLite schema and all persistence
scheduler.py windows, reminder planning, dispatch/batching, Bot.tick
signal_client.py /v2/send HTTP client
watchdog.py throttled operator alerts
__main__.py CLI: run loop, --dump, --check, --once
tests/ pytest; fixtures are *.ics.txt (never *.ics)
Commands
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest # must pass, no network
sigcal-bot --config config.toml --dump # render the feed without sending
sigcal-bot --config config.toml --check # config + Signal account check
sigcal-bot --config config.toml --once # one tick
--dump uses a throwaway database and never sends; keep it that way.
Hard rules
- Never commit calendar data.
*.icsis gitignored; test fixtures must be named*.ics.txt.config.toml,signal-data/,data/,cache/are local-only. - UTC inside, local only at the edges. Store and compare UTC. Convert to
[calendar].timezoneonly for window maths and rendering. Never use naivedatetime.now()in code that persists a timestamp. tick()must never raise. Feed, scrape, image, and send problems are logged and reported to the watchdog; the loop has to survive all of them. The one catch-all in__main__is a backstop, not a design.- Images are optional; text is not. Any image or scraping failure must
degrade to a text-only post. Never let enrichment raise through
_compose. - Plan once, persist it. Reminder times and outbox rows are written when an event is first seen. Do not recompute schedules on every tick; that reorders posts when the feed changes or the process restarts.
- Delivery is at-least-once. Write
deliveriesand delete the outbox row only after a successful send. A crash may duplicate one post; that is accepted. Do not add silent "mark sent before send" shortcuts. - No network in tests. Inject
now, and use the fake sender/scraper/image service patterns intests/test_scheduler.py(httpx.MockTransportfor the feed).
Domain gotchas
- Series vs occurrence. TEC's UID is
{postID}-{startUnix}-{endUnix}@{host}, and the feed pre-expands recurrences. Announcements are deduped perseries_id; reminders perEvent.key. Changing this will spam the group with one post per occurrence. - Feed is capped (30 events by default) and contains no past events. Use
the coverage horizon (
max(start)of the snapshot) before marking eventsgone; otherwise a busy week "cancels" next month's events. - No
LOCATIONon many events. Venue/postcode come from the event page's JSON-LD (Event.location.name/address.postalCode), then the description. This is cached per URL inpages. - Poster URLs are full-size originals, sometimes WebP or a 20 MB phone photo. Always cap the download, downscale, flatten transparency onto white, and re-encode as JPEG.
- Posting windows (
08:00–10:00,18:00–21:00) are a preference, not a rule:clamp_send_atbreaks them when the next window would miss the event minusurgent_guard_minutes. - Reminder fallback. If
start − leadhas already passed when the event is discovered, the reminder moves to the morning of the event (or earlier, if the event starts before that morning time). - Batching. All outbox rows due in a tick become one message (text blocks
joined by blank lines, at most
max_images_per_postattachments).
Changing behaviour
- New post kind (e.g. digest): add a
kindtooutbox, plan rows in_sync/a new planner, make_dispatchtreat it like the others, add a template informat.py, and test planning + dispatch with a fake clock. - New config option: add a dataclass field in
config.pywith a sensible default, parse it inload_config, document it inconfig.example.tomland the README table. - Schema change: append to
SCHEMAinstore.py. There is no migration framework; deletingdata/sigcal-bot.sqlite3re-seeds silently.
Changelog
CHANGELOG.md is Keep-a-Changelog format. For anything a user of the bot would
notice — behaviour, configuration, CLI, operational requirements — add a bullet
under ## [Unreleased] in the right group (Added, Changed, Fixed,
Removed). Internal refactors and test-only changes do not need entries.
Never create version headings. No stable release exists yet; versions are cut
only when a release is actually deployed, by renaming Unreleased to
## [x.y.z] - YYYY-MM-DD.
Before you finish
pytestgreen,python -m pyflakes src testsclean.- New behaviour covered by a test (especially failure paths).
- User-visible changes have a
CHANGELOG.mdentry under## [Unreleased]. config.example.toml, README and AGENTS.md still accurate.git statusshows no.ics,config.toml,data/,cache/orsignal-data/files.