dvorobiev/bridge-status-bot

Purpose and Runtime

A Python 3.10+ Telegram bot that reports the live operational state of the Mityaevsky pontoon bridge in Kolomna. It derives bridge position, traffic-light color, and countdown timer from a camera stream using Google Gemini.

The executable entry point is bridge_bot.py, started with python3 bridge_bot.py.

Application Boundary

The repository is intentionally single-process and single-module: Telegram interaction, camera-frame acquisition, AI analysis, and response formatting are expected to be orchestrated in bridge_bot.py.

Core runtime dependencies are declared in requirements.txt; local secrets are supplied via .env based on .env.example.

Telegram Interaction Layer

The bot receives /start and /status commands in private chats and groups, and exposes an inline button for status refresh. This layer handles Telegram updates, command/button routing, and sends the formatted status response.

Primary path:

• bridge_bot.py

External service:

• Telegram Bot API, authenticated by TELEGRAM_TOKEN.

Camera Capture Stage

On a status request, the bot obtains a current image/frame from the bridge camera video stream. ffmpeg is an OS-level required dependency, indicating frame extraction likely occurs through a subprocess rather than a Python-native decoder.

Boundary: camera/video input is transformed into a still image suitable for AI inspection.

Primary path:

• bridge_bot.py

External/runtime dependency:

• ffmpeg installed on the host.

AI Vision Analysis Stage

The captured frame is submitted to Google Gemini, which is responsible for extracting three domain values: bridge state (joined/open versus separated), traffic-light color, and any visible countdown.

The API key is environment-provided, keeping model credentials outside source control.

Primary paths:

• bridge_bot.py

• .env.example

External service:

• Google Gemini API, authenticated by GEMINI_API_KEY.

Status Interpretation and Presentation

The bot converts model output into a concise human-facing result, including semantic bridge status, color/icon-based traffic signal status, optional countdown seconds, and observation time. The response format is designed for immediate operational use in Telegram rather than persistent storage or a web UI.

Primary path:

• bridge_bot.py

Control Flow and Failure Boundaries

The request path is synchronous in intent: Telegram command/callback → retrieve camera frame → Gemini analysis → normalize/format result → Telegram reply. Network and subprocess boundaries are the likely failure points: Telegram delivery, camera availability, ffmpeg execution, HTTP transport, and Gemini response quality/availability.

No database, queue, scheduler, or deployment infrastructure is represented in the repository tree; each status check is expected to be live/on-demand.