surfaces/README.md

Lambda Lab 3.0 — Surfaces

Команда поверхностей. Telegram и Matrix боты для взаимодействия пользователя с AI-агентом Lambda.

Статус

Прототип в разработке. SDK платформы ещё не готов — работаем через MockPlatformClient.

Поверхность	Статус	Описание
Telegram	🔨 В разработке	Forum Topics: одна группа, чат = тема
Matrix	🔨 В разработке	Space + комнаты: чат = отдельная комната

---

Концепция

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

Поверхности — тонкие клиенты. Вся бизнес-логика на стороне платформы. Задача команды: сделать интерфейс удобным, надёжным и легко расширяемым.

---

Архитектура

surfaces-bot/
  core/                  — общее ядро, не зависит от транспорта
    protocol.py          — унифицированные структуры (IncomingMessage, OutgoingUI, ...)
    handler.py           — EventDispatcher: IncomingEvent → OutgoingEvent
    handlers/            — обработчики по типам событий
    store.py             — StateStore Protocol + InMemoryStore + SQLiteStore
    chat.py              — ChatManager: метаданные чатов C1/C2/C3
    auth.py              — AuthManager: аутентификация
    settings.py          — SettingsManager: коннекторы, скиллы, SOUL, безопасность

  adapter/
    telegram/            — aiogram 3.x адаптер
    matrix/              — matrix-nio адаптер

  platform/
    interface.py         — PlatformClient Protocol (контракт к SDK)
    mock.py              — MockPlatformClient (заглушка)

  docs/                  — документация
  .claude/agents/        — агенты для Claude Code

Ключевой принцип: добавить новую поверхность = написать один адаптер-конвертер. Ядро (core/) не трогается. Подробнее: docs/surface-protocol.md

---

Функционал прототипа

Telegram (подробнее)

• Чаты — Forum Topics: бот создаёт личную группу пользователя, каждый чат = отдельная тема
• Аутентификация — привязка Telegram аккаунта к аккаунту платформы
• Диалог — typing indicator, передача файлов, подтверждение опасных действий через inline-кнопки
• Настройки через /settings: коннекторы (Gmail, GitHub, Notion...), скиллы, личность агента (SOUL), безопасность, подписка

Matrix (подробнее)

• Чаты — Space + комнаты: бот создаёт личное пространство, каждый чат = комната
• Аутентификация — привязка Matrix аккаунта к аккаунту платформы
• Диалог — typing, файлы, подтверждение действий через реакции 👍/❌, треды для долгих задач
• Настройки — отдельная комната «Настройки» с командами !connectors, !skills, !soul, !safety, !status

---

Замена SDK

Вся работа с платформой идёт через PlatformClient Protocol:

class PlatformClient(Protocol):
    async def get_or_create_user(self, external_id: str, platform: str, ...) -> User: ...
    async def send_message(self, user_id: str, chat_id: str, text: str, ...) -> MessageResponse: ...
    async def get_settings(self, user_id: str) -> UserSettings: ...
    async def update_settings(self, user_id: str, action: Any) -> None: ...

Бот не управляет lifecycle контейнеров — это делает Master (платформа). Бот передаёт user_id + chat_id + сообщение; платформа сама решает нужно ли поднять контейнер.

Сейчас: MockPlatformClient в platform/mock.py. Когда SDK готов: добавляем SdkPlatformClient, меняем одну строку в DI. Адаптеры и ядро не трогаем.

---

Быстрый старт

# Зависимости
uv sync   # или: pip install -e ".[dev]"

# Тесты
pytest tests/ -v

# Запустить Telegram бота
cp .env.example .env  # заполнить TELEGRAM_BOT_TOKEN
python -m adapter.telegram.bot

# Запустить Matrix бота
cp .env.example .env  # заполнить MATRIX_* переменные
python -m adapter.matrix.bot

---

Документация

Файл	Содержание
docs/surface-protocol.md	Унификация поверхностей — все структуры, как добавить новую поверхность
docs/telegram-prototype.md	Функционал Telegram прототипа
docs/matrix-prototype.md	Функционал Matrix прототипа
docs/api-contract.md	Контракт к SDK платформы
docs/user-flow.md	FSM и user journey
docs/claude-code-guide.md	Гайд по работе с Claude Code

---

Команда

Поверхности и интеграции Lambda Lab 3.0, МАИ