How mj11rock/poll-story-telegram-bot works
Project Type and Purpose
• This is a lightweight, scheduled automation script (Python CLI tool) that orchestrates two external services (OpenAI API and Telegram Bot API) to create an interactive, choice-driven story in a Telegram channel.
• It is not a web app or full-stack service; it is a “backend-only” integration utility invoked on a schedule (e.g., via cron).
File Structure Analysis
• Top-level files:
• telegram_poster.py – Core script containing logic to read/write state, call OpenAI, and post to Telegram.
• requirements.txt – Python dependencies (openai, python-telegram-bot, etc.).
• README.md – Detailed usage and architecture description.
• story_state.json (runtime) – Local JSON state file storing current story text and last poll ID.
• No additional modules or directories—single-file script.
Key Components
a. Scheduler
• cron or any job scheduler that triggers telegram_poster.py at fixed intervals.
b. State Store
• story_state.json on disk for persisting:
• current story text
• last poll ID
c. OpenAI API Integration
• Sends prompts (full story & winning choice) → Receives new story fragment + poll options.
• Configurable endpoint (OPENAI_BASE_URL) and model (OPENAI_MODEL).
d. Telegram Bot API Integration
• Publishes story text as a regular message.
• Creates a new poll with generated options.
e. Configuration
• Environment variables (OPENAI_API_KEY, OPENAI_BASE_URL)
• Hard-coded variables in telegram_poster.py (BOT_TOKEN, CHANNEL_ID, INITIAL_STORY_IDEA).
Interactions and Data Flow
1. Scheduler invokes telegram_poster.py.
2. Script loads story_state.json (or initializes with INITIAL_STORY_IDEA).
3. Determines last poll’s winning option.
4. Calls OpenAI API with full story + winning choice → Receives continuation + new options.
5. Calls Telegram Bot API:
a. Post continuation as text message.
b. Create new poll with 4 options.
6. Update story_state.json with new story text and new poll ID.
7. Exit; wait for next scheduled run.
Architectural Patterns and Principles
• Single responsibility: script coordinates state, AI, and messaging.
• Sequential flow with clear stages: Load state → AI generation → Messaging → Persist state.
• External integrations are decoupled via explicit API client calls.
• Stateless between runs except for the story_state.json checkpoint.