Демонстрация Stock Prices¶

Что делает проект¶

Stock Prices генерирует короткие MP4-видео с анимированными графиками цен и инвестиционного результата по тикерам. Пользователь может запустить генерацию из командной строки или написать короткий запрос Telegram-боту: проект загрузит исторические данные, подготовит датасет, отрендерит график и отправит готовое видео обратно.

Проект полезен для инвесторов, аналитиков, авторов финансового контента и команд, которым нужно быстро получить понятную визуализацию динамики актива без ручной подготовки графиков.

Короткий MP4-артефакт для демонстрации проекта без запуска Telegram-бота или live market download.

Пример финального кадра видео SBER и LKOH — Финальный кадр ролика: цветные линии, события на нижних дорожках и процентные подписи по тикерам.

Ключевые возможности¶

Генерация MP4-видео по одному или нескольким тикерам.
Поддержка MOEX и глобальных инструментов через разные источники данных.
Сценарии price и capital: можно показывать обычную цену закрытия или результат условной инвестиции с реинвестированием.
Настраиваемые даты, валюта подписи, длительность, FPS, легенда и градиентная линия.
Telegram-бот с компактным меню, быстрым пультом, очередью и готовым MP4 в ответ.
Случайные шортсы, ролик дня и недельный план на основе расширяемой тикерной вселенной: категории, даты доступной истории и пересечение периодов.
Metadata discovery MOEX для расширения random-вселенной без хранения ценовых рядов.
Единый Python API generate_video(VideoRequest), который используется и CLI, и Telegram-ботом.
Исторические данные обрабатываются в памяти для конкретного запроса; MP4 можно удалять сразу после отправки Telegram-ботом.

Для кого¶

Частный инвестор: быстро сравнить SBER и LKOH за 5 лет.
Автор финансового контента: получить ролик по AAPL, BTC или gold прямо из чата.
Аналитик: проверить разные классы активов в одном стиле.
Разработчик: встроить генерацию видео в другой Python-сервис через API.

Архитектура¶

CLI / Telegram
    |
    v
Parser -> VideoRequest / RenderSettings / TickerSpec
    |
    v
Pipeline generate_video()
    |
    +--> Downloader
    |       +--> MOEX ISS через apimoex
    |       +--> Yahoo Finance через yfinance
    |
    +--> Dataset builder
    |       +--> нормализация OHLCV
    |       +--> дивиденды и события
    |       +--> расчет CAPITAL_REINVEST
    |
    v
Matplotlib renderer -> imageio-ffmpeg -> MP4
    |
    v
Файл в animations/ или ответ Telegram-бота с последующей очисткой

Сильная сторона архитектуры в том, что вся генерация проходит через один pipeline. CLI, Python API и Telegram-бот не дублируют бизнес-логику, а только собирают параметры запроса.

Источники данных¶

MOEX ISS через apimoex: российские акции, индексы, облигации, валютный рынок и срочные инструменты.
Yahoo Finance через yfinance: иностранные акции, ETF, индексы, валютные пары, криптовалюты, металлы и товарные фьючерсы.
currencyconverter: конвертация глобальных инструментов в рублевую шкалу, когда это требуется.
Локальные события из проекта: дополнительный контекст для дивидендов, сплитов и корпоративных событий.

Поддерживаемые рынки и активы¶

Класс	Пример	Формат
Российские акции	`SBER`, `LKOH`, `GAZP`	`TICKER` или `TICKER\|stock\|shares`
Индексы MOEX	`IMOEX`	`IMOEX\|stock\|index`
Облигации MOEX	тикер облигации	`TICKER\|stock\|bonds`
Валютный рынок MOEX	`USD000UTSTOM`	`USD000UTSTOM\|currency\|selt`
Фьючерсы MOEX	`SiH4`	`SiH4\|futures\|forts`
Иностранные акции	`AAPL`, `MSFT`, `NVDA`	`AAPL\|global\|shares`
Глобальные индексы	`^GSPC`, `^IXIC`	`^GSPC\|global\|index`
Металлы	`gold`, `silver`, `GC=F`	Telegram alias или `GC=F\|global\|metals`
Товарные фьючерсы	`oil`, `BRENT`, `CL=F`	Telegram alias или `CL=F\|global\|commodities`
Валютные пары	`eurusd`, `EURUSD=X`	alias или `EURUSD=X\|global\|currency`
Криптовалюты	`btc`, `eth`, `BTC-USD`	alias или `BTC-USD\|global\|crypto`

CLI-примеры¶

Установка в режиме разработки:

pip install -e .

Российская акция:

stock-prices --tickers LKOH --start_date 2015-01-01 --end_date 2026-05-26 --currency RUB --duration 20 --fps 20

Сравнение двух российских акций:

stock-prices --tickers SBER LKOH --start_date 2020-01-01 --end_date 2026-05-26 --duration 24 --fps 20 --use_gradient

Иностранная акция:

stock-prices --tickers "AAPL|global|shares" --start_date 2018-01-01 --end_date 2026-05-26 --currency USD

Криптовалюта:

stock-prices --tickers "BTC-USD|global|crypto" --start_date 2020-01-01 --end_date 2026-05-26 --currency USD --value_col CLOSE

Металл:

stock-prices --tickers "GC=F|global|metals" --start_date 2018-01-01 --end_date 2026-05-26 --currency USD --use_gradient

Фьючерс MOEX:

stock-prices --tickers "SiH4|futures|forts" --start_date 2024-01-01 --end_date 2024-03-20 --value_col CLOSE

Работа через Telegram¶

Telegram-бот рассчитан на короткие запросы без знания CLI. /start, /menu, /shoot и снять открывают рабочий пульт, Random дает быстрый выбор 1/2/3 тикеров или категории, /shorts показывает готовые истории, а /queue или статус показывают состояние долгого рендера.

Минимальный набор для демонстрации:

/start
/shorts
/shorts SBER LKOH за год
/queue
SBER LKOH 2020 2024

Готовые preset-сценарии остаются ручными примерами, а случайный шортс, ролик дня и недельный план собираются без LLM из тикерной вселенной проекта. Подробные команды лежат в разделе Telegram-запросы.

Запуск Telegram-бота¶

Создайте локальный .env рядом с pyproject.toml:

TELEGRAM_BOT_TOKEN=<botfather-token>
STOCK_PRICES_DEFAULT_ENGINE=stock
STOCK_PRICES_DEFAULT_MARKET=shares
STOCK_PRICES_CURRENCY=RUB
STOCK_PRICES_DURATION=30
STOCK_PRICES_FPS=20

Запуск:

stock-prices bot

Ограничение доступа конкретным чатом:

stock-prices bot --allowed_chat_id 123456789

Одноразовая проверка доступных Telegram updates:

stock-prices bot --once

Используемые технологии¶

Python 3.10+: основной язык проекта.
Pandas и NumPy: обработка временных рядов, нормализация данных, расчет инвестиционного результата.
Matplotlib: отрисовка кадров и графиков.
imageio-ffmpeg: поставка ffmpeg-бинарника и сборка MP4 без отдельной системной установки ffmpeg.
yfinance: глобальные рынки, акции, индексы, валюты, криптовалюты и товарные фьючерсы.
apimoex и MOEX ISS: российский рынок, включая акции, индексы, валютные инструменты и futures.
requests: Telegram Bot API, сетевые запросы, retry/timeout для MOEX.
pytest и MkDocs: автоматические проверки поведения и документации.

Сценарий демонстрации на 3-5 минут¶

Показать цель проекта: "пишем тикер, получаем готовое видео с графиком".
Запустить CLI для SBER LKOH 2020-2024 и показать, что видео появляется в animations/.
Сгенерировать глобальный актив: AAPL|global|shares или BTC-USD|global|crypto.
Открыть Telegram-бота и отправить /shorts, затем /shorts SBER LKOH за год.
Показать ответ бота: job id, /queue или статус, готовый MP4 и текст для Пульса.
Объяснить архитектуру: один pipeline, разные входы, разные источники данных, единый renderer.
Завершить roadmap: куда проект можно развивать дальше.

Ограничения¶

Качество и глубина истории зависят от MOEX ISS и Yahoo Finance.
Некоторые тикеры могут отсутствовать, быть переименованы или иметь неполную историю.
Для Telegram-бота нужен доступ в интернет и валидный токен BotFather.
Длительные периоды, несколько тикеров и высокий FPS увеличивают время генерации.
Yahoo Finance не является официальным источником биржевых данных для production-grade торговых решений.

План развития¶

Улучшение визуальных тем и читаемости подписей.
Регулярное обновление config/moex_universe.json через scripts/collect_moex_universe.py, если нужно чаще подмешивать новые листинги MOEX.
Web UI для предпросмотра и настройки графика.
Больше тестовой матрицы по реальным активам и graceful fallback для нестабильных источников данных.