Mikhail Putilovskij
c9072d51ea
7 documents covering stack, integrations, architecture, structure, conventions, testing, and concerns.
113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# Technology Stack
|
|
|
|
**Analysis Date:** 2026-04-01
|
|
|
|
## Languages
|
|
|
|
**Primary:**
|
|
- Python 3.11+ — all application code (enforced via `pyproject.toml` `requires-python = ">=3.11"`)
|
|
|
|
**Type Annotations:**
|
|
- Full `from __future__ import annotations` usage throughout
|
|
- `typing.Protocol` used for dependency inversion (`core/store.py`, `sdk/interface.py`)
|
|
|
|
## Runtime
|
|
|
|
**Environment:**
|
|
- CPython — runtime (development host currently runs 3.14.3)
|
|
- Minimum: Python 3.11 (uses `match`-compatible union syntax, `Self`, `X | Y` type hints)
|
|
|
|
**Package Manager:**
|
|
- `uv` 0.9.30 (Homebrew)
|
|
- Lockfile: `uv.lock` present and committed
|
|
- Install: `uv sync`
|
|
|
|
## Frameworks
|
|
|
|
**Telegram Bot:**
|
|
- `aiogram` 3.26.0 — async Telegram Bot API framework
|
|
- Used in `adapter/telegram/` (planned; directory not yet present in main branch)
|
|
- Brings in `aiohttp` 3.13.3 as its HTTP transport
|
|
|
|
**Matrix Bot:**
|
|
- `matrix-nio` 0.25.2 — async Matrix Client-Server API client
|
|
- Used in `adapter/matrix/bot.py`
|
|
- Key classes: `AsyncClient`, `AsyncClientConfig`, `RoomMessageText`, `ReactionEvent`, `InviteMemberEvent`, `RoomMemberEvent`, `MatrixRoom`
|
|
- Long-polling via `client.sync_forever(timeout=30000)`
|
|
|
|
**Data Validation:**
|
|
- `pydantic` 2.12.5 — data models in `sdk/interface.py`
|
|
- `User`, `Attachment`, `MessageResponse`, `MessageChunk`, `UserSettings`, `AgentEvent`, `PlatformError`
|
|
- Core protocol structs (`core/protocol.py`) use plain `dataclasses` instead
|
|
|
|
**Build/Dev:**
|
|
- `setuptools` ≥68 + `setuptools-scm` + `wheel` — build backend (`pyproject.toml`)
|
|
- `ruff` 0.15.8 — linting and import sorting (`line-length = 100`, `target-version = "py311"`, rules: E, F, I, UP, B)
|
|
- `mypy` 1.19.1 — static type checking
|
|
|
|
## Key Dependencies
|
|
|
|
**Critical:**
|
|
- `aiogram>=3.4,<4` (resolved: 3.26.0) — Telegram adapter; pin avoids breaking v4 API
|
|
- `matrix-nio>=0.21` (resolved: 0.25.2) — Matrix adapter; async-only client
|
|
- `pydantic>=2.5` (resolved: 2.12.5) — SDK interface models; v2 required (v1 incompatible)
|
|
|
|
**Infrastructure:**
|
|
- `structlog` 25.5.0 — structured logging throughout; used via `structlog.get_logger(__name__)`
|
|
- `python-dotenv` 1.2.2 — loads `.env` at bot startup (`load_dotenv(Path(...) / ".env")`)
|
|
- `httpx` 0.28.1 — available for HTTP calls (future SDK integration, not yet used in core logic)
|
|
|
|
**Async I/O:**
|
|
- `aiohttp` 3.13.3 — transitive via aiogram; provides HTTP session to Telegram Bot API
|
|
- `asyncio` — stdlib; used directly in `sdk/mock.py` (`asyncio.sleep` for latency simulation) and all bot entry points (`asyncio.run(main())`)
|
|
|
|
## Testing
|
|
|
|
**Runner:**
|
|
- `pytest` 9.0.2
|
|
- `pytest-asyncio` 1.3.0 — `asyncio_mode = "auto"` (set in `pyproject.toml`)
|
|
- `pytest-cov` 7.1.0 — coverage reporting
|
|
|
|
**Configuration:**
|
|
- `pyproject.toml` `[tool.pytest.ini_options]`: `testpaths = ["tests"]`, `pythonpath = ["."]`
|
|
- `conftest.py` at project root
|
|
|
|
## Internal Module Structure
|
|
|
|
**Core (no external deps except stdlib + pydantic via sdk):**
|
|
- `core/protocol.py` — `dataclasses`-based unified event types
|
|
- `core/store.py` — `StateStore` Protocol + `InMemoryStore` (dict) + `SQLiteStore` (stdlib `sqlite3`)
|
|
- `core/handler.py` — `EventDispatcher`
|
|
- `core/auth.py`, `core/chat.py`, `core/settings.py` — domain managers
|
|
|
|
**SDK Layer:**
|
|
- `sdk/interface.py` — `PlatformClient` Protocol (pydantic models)
|
|
- `sdk/mock.py` — `MockPlatformClient` in-process stub; simulates latency via `asyncio.sleep`
|
|
|
|
**Adapters:**
|
|
- `adapter/matrix/` — matrix-nio integration (active)
|
|
- `adapter/telegram/` — aiogram integration (referenced in deps, worktree branch exists)
|
|
|
|
## Configuration
|
|
|
|
**Environment:**
|
|
- Loaded from `.env` via `python-dotenv` at startup
|
|
- See `INTEGRATIONS.md` for full variable list
|
|
|
|
**Build:**
|
|
- `pyproject.toml` — single source of truth for deps, build, lint, test config
|
|
|
|
## Platform Requirements
|
|
|
|
**Development:**
|
|
- Python ≥3.11
|
|
- `uv` for dependency management
|
|
|
|
**Production:**
|
|
- Any environment with Python ≥3.11
|
|
- Matrix bot: requires writable filesystem path for `matrix_store/` (nio E2EE store) and SQLite DB
|
|
- Telegram bot: stateless beyond env vars (or optionally SQLite for persistence)
|
|
|
|
---
|
|
|
|
*Stack analysis: 2026-04-01*
|