TradingAgents-Telegram: Instructions file for Claude Code

TradingAgents-Telegram — Architecture Reference

Telegram bot wrapping the TradingAgents library. Users curate a watchlist via Telegram, tap a ticker, and the bot runs TradingAgentsGraph.propagate(...) and posts a finviz chart + Telegraph link with the verdict. Per-step pipeline progress is streamed back into the message caption while the analysis runs.

Layout

src/tg_bot/ — package, organized as 4 subpackages + a small number of single-concept files at parent level. Each subpackage has a documented membership rule; the parent-level files are leaf primitives that don't fit into any single subpackage's concept.

src/tg_bot/
├── __init__.py
├── __main__.py                  # python -m tg_bot
├── app.py                       # PTB Application + BOT_COMMANDS + lifecycle hooks
├── config.py                    # env-driven Config (read once at process start)
├── auth.py                      # authorize TypeHandler (group=-1 gate)
├── validation.py                # yfinance ticker check + shared TICKER_RE
├── history.py                   # disk reader for past tradingagents logs
├── digest.py                    # /digest picker UI builder (no I/O, no globals)
├── market_calendar.py           # per-ticker exchange-session gate (exchange_calendars)
│
├── storage/                     # JSON persistence — terminal in the dep DAG
│   ├── _base.py                 # JsonStorage (atomic + fsync)
│   ├── watchlist.py             # WatchlistStorage singleton
│   └── user_config.py           # UserConfigStorage singleton (digest schedule + email mirror opt-in)
│
├── handlers/                    # PTB handlers — register dispatch surfaces
│   ├── commands.py              # slash commands (/add, /watch, /list, /email, etc.)
│   ├── callbacks.py             # prefix-dispatched callback handlers
│   ├── analysis_runner.py       # manual /watch + digest fan-out orchestration
│   └── pickers.py               # shared keyboard/response builders for commands+callbacks
│
├── pipeline/                    # LLM execution hot path
│   ├── analysis.py              # run_trading_analysis + GraphPool + .env overlay (build_config)
│   ├── cache.py                 # same-day result cache, keyed by AnalysisConfigKey
│   ├── config_key.py            # AnalysisConfigKey (frozen) — slug/caption/title
│   └── progress.py              # cancel-aware LangChain callback
│
└── rendering/                   # data → user-visible output
    ├── formatters.py            # HTML + MarkdownV2 captions (Invariant #4)
    ├── telegraph_client.py      # Telegraph publish (offloaded + resilient)
    ├── email_client.py          # digest email mirror via Resend (opt-in)
    └── chart.py                 # finviz URL builder