Usage

CLI entrypoints

  • start_bot.py: launches the Telegram bot.

  • start_agent.py: starts the agent service.

  • start_api.py: runs the REST API on http://localhost:8000.

  • main.py: runs bot and agent together.

Environment

  • TELEGRAM_BOT_TOKEN: required for bot

  • DATABASE_PATH: SQLite database path (defaults to database.db)

  • PIPELINE_USE_AGENTS_ANALYZE: 1 to enable LLM analysis if keys are set

  • OPENAI_API_KEY / OPENROUTER_API_KEY: optional; enables LLM-based analysis

  • AGENT_DRY_RUN=1: do not persist results, only send summaries

Code structure

  • agent/: agent pipeline, browsing tools, and orchestration.

  • bot/: Telegram bot handlers, dispatcher, and utils.

  • shared/: shared utilities like database, logging, LLM wrappers, and events.

Telegram bot commands

Core commands (subset):

  • /start: intro and help

  • /task "Title" description: create a new autonomous search task

  • /status_task: list your tasks

  • /pause_task <id>, /resume_task <id>: control a task

  • /settings: view current settings

  • /set_relevance relevance <0-100>: set minimum relevance threshold

  • /set_notification [instant|daily|weekly] <0-100>: configure notifications

  • /set_group and /unset_group: switch notifications to a group chat

  • /history: show recent findings for your account

Quick links:

  • Manage your bot with @BotFather

  • aiogram message formatting: HTML mode

  • Group chat setup: add your bot to a group, then run /set_group

Configuration reference

  • DATABASE_PATH: SQLite file path; defaults to database.db

  • AGENT_POLL_SECONDS: seconds between agent iterations; default 30

  • AGENT_ID: identifier for the agent; default main_agent

  • PIPELINE_USE_AGENTS_ANALYZE: 1 to enable LLM analysis

Source selection

  • The agent automatically selects the most relevant source per query among: arXiv, Google Scholar, PubMed, GitHub. You do not need to configure a default source.

Task scheduling

  • The agent processes the most recently updated active task first on each iteration.

Typical workflow

  1. Start bot and agent

  2. Create a task with /task and your goal

  3. The agent generates queries, collects papers, ranks, analyzes, and decides

  4. You receive concise summaries in Telegram when useful items appear

Development

  • Run tests with uv run pytest.

  • Lint and type-check via ruff and pyright.

Local docs preview

uv run sphinx-build -b html docs docs/_build/html
start docs/_build/html/index.html