# 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*