surfaces/.planning/codebase/STACK.md

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