Стек intel-collector — что взял и почему

Для каждого пункта:

• Что это (одной строкой для не-инженера)
• Зачем взял
• Когда альтернатива была бы лучше
• Официальная документация

1. Python 3.12

Что это: Сам язык программирования. Версия 3.12 (с октября 2023). Актуальные тоже 3.13 / 3.14.

Зачем взял: Глубокая LLM/AI экосистема — все библиотеки (LangGraph, LiteLLM, SDK Anthropic/Google/OpenAI, pgvector wrappers) есть в Python нативно. 3.12 vs 3.11 — лучше typing (Generic TypedDict), быстрее, лучше error messages.

Альтернативы:

• TypeScript / Node.js — LangGraph есть и там, JS SDK от провайдеров есть. Имеет смысл если планируешь web-frontend на TS и хочешь единый язык
• Go / Rust — слабая LLM-экосистема, не стоит для AI-проектов

Docs: https://docs.python.org/3.12/

2. uv (package manager)

Что это: Инструмент для управления Python-пакетами и виртуальными окружениями. Альтернатива классической связке pip + venv или poetry.

Зачем взял: В 10-100 раз быстрее poetry. Один тул вместо нескольких (env, install, lock, publish). Развивается Astral — теми же кто делает ruff.

Альтернативы:

• poetry (https://python-poetry.org/) — самый известный, более зрелый, медленнее. Defensible если уже знаешь
• pdm (https://pdm-project.org/) — middle ground
• pip + requirements.txt — простейший вариант, но без lockfile проблематично

Docs: https://docs.astral.sh/uv/

3. ruff (linter + formatter)

Что это: Инструмент который проверяет код на ошибки/стиль (lint) и форматирует его. Написан на Rust.

Зачем взял: В ~100 раз быстрее старого стека (black + isort + flake8 + pylint). Один тул вместо четырёх. В 2026 — индустриальный стандарт.

Альтернативы: Реально нет конкурента в 2026, ruff выиграл рынок.

Docs: https://docs.astral.sh/ruff/

4. mypy (type checker)

Что это: Проверяет типы в Python-коде до запуска. Если ты написал def f(x: int) и зовёшь f("string") — mypy это поймает.

Зачем взял: Индустриальный стандарт для CLI type checking. Хорошая документация.

Альтернативы:

• pyright (https://github.com/microsoft/pyright) — от Microsoft. Быстрее и строже mypy. Используется в VSCode Python extension под капотом. Defensible альтернатива — взял бы если приоритет скорость
• Без type checking вообще — для прототипа норм, для серьёзного кода — нет

Docs: https://mypy.readthedocs.io/

5. pytest (testing)

Что это: Фреймворк для написания unit / integration тестов.

Зачем взял: В 2026 нет реальных конкурентов. Богатая экосистема плагинов.

Альтернативы: unittest из stdlib (старый стандарт, более многословный, никто не любит).

Docs: https://docs.pytest.org/

6. pre-commit (git hooks)

Что это: Запускает lint / format / tests автоматически при git commit — до того как код уйдёт в git history.

Зачем взял: Solo dev: ловить проблемы сразу, а не на CI через 10 минут. Дисциплина с первого дня.

Альтернативы:

• Только CI (без pre-commit) — медленнее обратная связь
• Ничего — рискованно, грязный код накапливается

Docs: https://pre-commit.com/

7. LangGraph (orchestration)

Что это: Фреймворк для построения stateful workflows из LLM-узлов. Каждый узел = функция, между ними — рёбра. Состояние сохраняется между шагами, можно паузить и продолжать (checkpointing).

Зачем взял:

• Был назван в твоём артефакте Gemini как основа
• Stateful + checkpointing = ровно то что нужно для 15k продукта (паузы, human-in-the-loop)
• Postgres checkpointer официальный
• Используется в production многими командами в 2026

Альтернативы:

• CrewAI (https://www.crewai.com/) — более opinionated multi-agent. Хорош для "команда агентов с ролями", слабее для произвольных графов
• AutoGen (https://microsoft.github.io/autogen/) — от Microsoft. Мощный но сложный, упор на conversational multi-agent
• OpenAI Swarm (https://github.com/openai/swarm) — minimal, experimental
• Pydantic AI (https://ai.pydantic.dev/) — новее, типобезопасный, простой. Defensible альтернатива для intel-collector
• Plain async/await — для линейного pipeline (как наш) на самом деле было бы достаточно

Честный disclaimer: Для intel-collector конкретно — LangGraph слегка overkill. Взял потому что обкатываем паттерн для будущего 15k, где state и HITL критичны.

Docs: https://langchain-ai.github.io/langgraph/

8. LiteLLM (LLM abstraction)

Что это: Прокси/обёртка над всеми LLM-провайдерами (Anthropic, OpenAI, Google, Cohere, local Ollama/vLLM и десятки других). Единый API для всех.

Зачем взял:

• Switch между cloud (Gemini API) и on-prem (vLLM / Ollama) через .env, без правки кода — это требование архитектурного паттерна two-deployment-pattern
• Cost tracking, caching, retry — встроены
• Structured output через Pydantic — работает с Gemini

Альтернативы:

• Прямые SDK — google-generativeai, anthropic, openai. Чище для standalone use-case. Для intel-collector сам по себе хватило бы Google SDK. LiteLLM оправдан только связкой с будущим 15k
• LangChain ChatModel abstractions — есть в LangChain, но менее dedicated
• OpenAI-compatible HTTP API — почти все провайдеры эмулируют OpenAI endpoint, можно через httpx напрямую

Docs: https://docs.litellm.ai/

9. Pydantic v2

Что это: Библиотека для валидации данных через классы с автоматической проверкой типов и сериализацией в JSON. Когда LLM возвращает структуру — Pydantic проверяет что она правильная.

Зачем взял:

• Все нужные библиотеки (LangGraph, LangChain, LiteLLM, FastAPI) нативно ждут Pydantic
• V2 в 10x быстрее V1 (переписана на Rust под капотом)
• JSON Schema автогенерация для structured output
• Индустриальный стандарт для API/LLM работы в 2026

Альтернативы:

• dataclasses (stdlib) — без валидации, без serialization
• attrs — старее, валидация ручная
• msgspec (https://jcristharif.com/msgspec/) — в 2-3x быстрее Pydantic, но крошечная экосистема

Docs: https://docs.pydantic.dev/2/

10. pydantic-settings

Что это: Расширение Pydantic для типизированного чтения переменных окружения. Вместо os.environ["GEMINI_API_KEY"] пишешь settings.gemini_api_key с автоматической проверкой что переменная есть и нужного типа.

Зачем взял: Естественное продолжение Pydantic, читает .env файлы, валидация на старте процесса (если переменной нет — процесс не запустится, а не упадёт через 5 минут).

Альтернативы:

• python-dotenv + ручной парсинг — простейший
• environs — тоже типизированный, попроще

Docs: https://docs.pydantic.dev/latest/concepts/pydantic_settings/

11. SQLAlchemy 2.0

Что это: ORM (Object-Relational Mapper) для Python. Позволяет писать "класс Item" вместо "CREATE TABLE items" и работать с базой через Python-объекты.

Зачем взял:

• Industry standard, биггейшая экосистема
• V2.0 (с 2023) — современный typing-aware API (Mapped[str], select())
• Поддерживает sync + async
• Alembic (миграции) работает с ним из коробки
• pgvector интегрируется через pgvector.sqlalchemy

Альтернативы:

• SQLModel (https://sqlmodel.tiangolo.com/) — Pydantic + SQLAlchemy в одном. Defensible альтернатива — код был бы чище (не пришлось бы дублировать SQLAlchemy-модели и Pydantic-схемы). Менее зрелый, меньше advanced features. Имеет смысл переключиться если эстетика важнее
• Tortoise ORM — async-native, как Django ORM. Меньше ecosystem
• Raw SQL через psycopg — для очень простых случаев
• Django ORM — overkill, не используем Django

Docs: https://docs.sqlalchemy.org/en/20/

12. Alembic

Что это: Инструмент для миграций схемы БД — позволяет версионировать структуру таблиц. Когда добавил колонку — пишешь миграцию, она применяется на всех окружениях (dev / prod) в правильном порядке.

Зачем взял: Стандарт для SQLAlchemy. Альтернатив реально нет.

Docs: https://alembic.sqlalchemy.org/

13. psycopg (v3) с [binary]

Что это: Драйвер для подключения Python к PostgreSQL. [binary] означает прекомпилированную версию (быстрее ставится, не нужен компилятор).

Зачем взял: Самая современная версия (v3 с 2022). Лучше типизирован, async-aware, рекомендуется для SQLAlchemy 2.0.

Альтернативы:

• psycopg2 — старый, ещё работает, но deprecated в новых проектах
• asyncpg (https://magicstack.github.io/asyncpg/) — быстрее в pure async режиме, но интеграция с SQLAlchemy хуже

Docs: https://www.psycopg.org/psycopg3/docs/

14. pgvector

Что это: Расширение для PostgreSQL которое добавляет тип vector (массив чисел) и операции косинусного сходства. Позволяет хранить эмбеддинги (векторные представления текстов) в обычной таблице рядом с данными.

Зачем взял:

• Не нужен отдельный сервис (vector DB) — всё в одной Postgres
• Транзакционность с основными данными
• На нашем масштабе (тысячи items) — производительности хватает

Альтернативы:

• Qdrant (https://qdrant.tech/) — отдельный сервис, быстрее на больших объёмах (>1M векторов). Имеет смысл когда переедем на 100M+
• Weaviate, Pinecone (managed) — тоже отдельные сервисы
• ChromaDB — embedded, как SQLite для векторов
• FAISS (in-process Python) — нет persistence из коробки

Docs: https://github.com/pgvector/pgvector SQLAlchemy интеграция: https://github.com/pgvector/pgvector-python

15. feedparser (RSS)

Что это: Парсер RSS / Atom фидов в Python.

Зачем взял: Самый зрелый и проверенный временем (с 2003). Знает все edge-cases старых корявых RSS.

Альтернативы: Конкурентов реально нет. Все остальные — нишевые.

Docs: https://feedparser.readthedocs.io/

16. arxiv (Python lib)

Что это: Обёртка над публичным API Arxiv (научного препринт-сервера).

Зачем взял: Готовая работа с pagination, rate limits, parsing метаданных. Альтернатива — самому писать HTTP-клиент через httpx + feedparser.

Docs: https://github.com/lukasschwab/arxiv.py

17. httpx (HTTP client)

Что это: Современная замена requests. Поддерживает и синхронный, и асинхронный режим.

Зачем взял: Sync + async в одной библиотеке, поддержка HTTP/2, активно развивается.

Альтернативы:

• requests (https://requests.readthedocs.io/) — только sync, легендарная библиотека
• aiohttp (https://docs.aiohttp.org/) — только async, быстрее httpx в чистом async-сценарии

Docs: https://www.python-httpx.org/

18. python-telegram-bot v21

Что это: Обёртка над Telegram Bot API. Позволяет писать ботов в Python.

Зачем взял: Самая стабильная и долго живущая (с 2015), хорошие docs.

Альтернативы:

• aiogram (https://aiogram.dev/) — async-native, легче, более pythonic. Defensible альтернатива
• Прямой HTTP в Bot API через httpx — для одного сообщения в день overkill ставить целую библиотеку

Honest: Для нашего use-case (одно сообщение в день) — overkill. Если бы переписывал — взял бы 5 строк на httpx. Оставил ptb на случай если потом захочется inline-кнопки.

Docs: https://python-telegram-bot.org/

19. APScheduler

Что это: Внутрипроцессный планировщик задач. Держишь Python-процесс живым, он запускает функции по расписанию.

Зачем взял: In-process, async-native, гибче cron-а.

Альтернативы (актуально для нас):

• systemd timer + standalone script — честно был бы чище для нашего daily-cron use-case. Каждый запуск свежий, нет long-running процесса, проще debugging. Стоит переключиться если будет один-два jobs в день
• system cron — то же, но более примитивно (не tz-aware, нет misfire handling)
• Celery — heavy, нужен broker (Redis/RabbitMQ). Для нашего масштаба overkill

Docs: https://apscheduler.readthedocs.io/

20. structlog (логирование)

Что это: Структурированное логирование. Вместо print("user x did y") пишешь log.info("user_action", user_id=x, action=y) — выводится JSON, который легко парсить.

Зачем взял: Стандарт для production-grade Python в 2026.

Docs: https://www.structlog.org/

21. tenacity (retry)

Что это: Декораторы для автоматических повторных попыток функций при сбое (например, LLM API упал — повторить через 2 секунды).

Зачем взял: Будет нужно когда добавим robustness к LLM-вызовам (сейчас не используется в коде, но в pyproject стоит).

Docs: https://tenacity.readthedocs.io/

Архитектурные паттерны на которые опирался

Эти не библиотеки — это паттерны проектирования. Источники — общая инженерная судебная и твой Gemini-артефакт.

Two-deployment via .env

Один код, два режима (SaaS облако / On-Prem). Переключение через переменные окружения, не через ветки кода. Подробно: two-deployment-pattern.

Detеrministic on LLM

LLM — только для интерпретации/семантики. Бизнес-логика и подсчёты — обычный код. Подробно: ../concepts/deterministic-on-exceptions, ../algorithms/deterministic-on-llm.

LLM as judge

Использовать LLM не для генерации, а для оценки/ранжирования с structured output. Подробно: ../algorithms/llm-as-judge.

Fan-out / merge

Параллельные запросы с агрегацией. Подробно: ../algorithms/fan-out-merge.

Что почитать если хочешь понять глубже

LangGraph (главное что стоит освоить):

• Tutorial: https://langchain-ai.github.io/langgraph/tutorials/
• LangChain Academy (бесплатные курсы): https://academy.langchain.com/

Pydantic v2:

• Concepts overview: https://docs.pydantic.dev/2/concepts/

SQLAlchemy 2.0:

• Unified tutorial (новый паттерн): https://docs.sqlalchemy.org/en/20/tutorial/

Гайд по LLM agents в общем (good mental model):

• Anthropic's "Building effective agents": https://www.anthropic.com/research/building-effective-agents

Если хочешь чтобы я обновил по свежим веб-источникам

Я могу WebFetch / WebSearch и подтянуть что-то конкретное (например, "что нового в LangGraph за последние 3 месяца", "stack overflow обсуждение poetry vs uv 2026"). Скажи что именно — сделаю.