null-bot/AGENTS.md

AGENTS.md

Run

python main.py

Uses runpy to exec bot.py. No tests, no lint, no CI.

Architecture

• bot.py — Telegram bot (python-telegram-bot), single-worker asyncio.Queue, all crawl/parse serialized
• agent.py — pydantic-ai with local Ollama (granite4.1:8b), three agents (opportunity/event/workshop), output_type=str
• database.py — PocketBase client, collections events / opportunities / workshops
• scraper.py — crawl4ai AsyncWebCrawler URL → markdown
• prompts.py — system prompts for both agent types
• schemas.py — unused at runtime, per file comment: "File doesn't do anything, its just an outline"

Windows event-loop quirk

DO NOT remove the dual-event-loop pattern in bot.py:

1. PTB runs on WindowsSelectorEventLoopPolicy (line 357)
2. Scraper runs in a separate thread with WindowsProactorEventLoopPolicy (line 25) — required for Playwright subprocesses on Windows

The get_clean_content() wrapper in bot.py runs _run_scraper_in_thread via ThreadPoolExecutor. Scraper functions must not be called directly.

Agent output format

Agents use output_type=str (not structured output). JSON is parsed manually from agent.run() result:

• LLM returns JSON wrapped in json ... markdown backticks
• agent.py:56 strips the backtick wrappers before json.loads()
• The markdown wrapper is specified in prompts.py — don't change prompt format without updating the strip logic

Date formats

• Prompts instruct LLM: DD-MM-YYYY (or DD-MM-YYYY (HH:MM) for events)
• PocketBase expects: YYYY-MM-DD HH:MM:SS
• database.py field mapping: event date_time → PocketBase datetime, end_date → end_datetime; workshop same; opportunity deadline stays deadline

PocketBase collections

• events — fields: title, org, datetime, end_datetime, summary, location, url
• opportunities — fields: title, org, type, deadline, summary, location, url
• workshops — fields: title, org, datetime, end_datetime, summary, location, url
• Auth uses admin credentials from .env

Env vars

.env required: TG_TOKEN, OLLAMA_BASE_URL, ALLOWED_USERS, POCKETBASE_URL, POCKETBASE_ADMIN_EMAIL, POCKETBASE_ADMIN_PASSWORD

Auth

ALLOWED_USERS — comma-separated Telegram user IDs (no brackets). Checked on every command/message handler.

Save flow

When source is pasted text (not URL), the bot asks for a source URL before saving. context.user_data keys: last_extracted, last_source_value, last_source_kind, last_entry_type, awaiting_save_url, pending_save_url, pending_url_to_process.