Add town-hall community ability

[ileana-pr]

What does this Ability do?

Town Hall gives voice civic briefings from official government sources — upcoming meetings, active legislation, and agenda details for Virginia (LIS) plus Legistar cities (Richmond, Seattle, Oakland, Boston, Denver, Baltimore, Phoenix, Pittsburgh, San Jose). Built so contributors can add more jurisdictions via a CivicSource / LegistarCitySource subclass.

Suggested Trigger Words

• virginia state / virginia legislation
• richmond city / richmond legislation
• seattle city / seattle legislation
• oakland city / boston city / denver city / baltimore city / phoenix city / pittsburgh city / san jose city (and matching * legislation)
• town hall (asks which briefing)
• configure topics / remove topics / clear topics

Type

• New community Ability
• Improvement to existing Ability
• Bug fix
• Documentation update

External APIs

• No external APIs
• Uses external API(s):
  • Virginia Legislative Information System (LIS) — optional LIS_API_KEY; public ICS / BILLS.CSV fallbacks
  • Granicus Legistar Web API (webapi.legistar.com) — public, no key

Testing

• Tested in OpenHome Live Editor
• All exit paths tested (said "stop", "exit", etc.)
• Error scenarios tested (API down, bad input, etc.)
• Live Legistar /events and /matters smoke-checked per city; Detroit / Miami-Dade dropped (stale public feeds)

Checklist

• Files are in community/town-hall/
• main.py follows SDK pattern (extends MatchingCapability, has register_capability + call)
• README.md included with description, suggested triggers, and setup
• resume_normal_flow() called on every exit path
• No print() — using editor_logging_handler
• No hardcoded API keys — using placeholders / dashboard third-party keys
• No blocked imports (redis, user_config, importlib, raw open())
• No asyncio.sleep() or asyncio.create_task() — using session_tasks
• Error handling on all external calls
• Tested in OpenHome Live Editor (ability committed as account release; PR branched from latest dev)

Anything else?

• Architecture: CivicSource base + LegistarCitySource parent for Legistar cities; Virginia stays a separate LIS source.
• Contribution notes live under notes/ locally (gitignored) and are not part of this PR.
• Personal account .openhome.json fields stripped; community manifest has capability_id: null.

Made with Cursor

[github-actions]

🔀 Branch Merge Check

PR direction: add-town-hall → dev

✅ Passed — add-town-hall → dev is a valid merge direction

[github-actions]

✅ Community PR Path Check — Passed

All changed files are inside the community/ folder. Looks good!

[github-actions]

🔍 Lint Results

✅ __init__.py — Empty as expected

Files linted: community/town-hall/main.py community/town-hall/sources/baltimore_md.py community/town-hall/sources/base.py community/town-hall/sources/boston_ma.py community/town-hall/sources/denver_co.py community/town-hall/sources/legistar.py community/town-hall/sources/oakland_ca.py community/town-hall/sources/phoenix_az.py community/town-hall/sources/pittsburgh_pa.py community/town-hall/sources/registry.py community/town-hall/sources/richmond_va.py community/town-hall/sources/sanjose_ca.py community/town-hall/sources/seattle_wa.py community/town-hall/sources/virginia_state.py

✅ Flake8 — Passed

✅ All checks passed!

[github-actions]

✅ Ability Validation Passed

📋 Validating: community/town-hall
  ✅ All checks passed!

[uzair401]

Approving this, Really strong work, @ileana-pr. The sources/ architecture is clean and extensible, the whole multi-file package stays deploy-compliant (stdlib only, HTTP via session_tasks), and storage + parsing are solid. Merging into community, excited to see the feedback over the next 30 days.

One tiny non-blocking follow-up for later: _save_topic_preferences should delete-then-write (like your write_context_file already does) so re-configuring topics doesn't reset them. Thanks for a great contribution!