# 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           — логика: IncomingEvent → OutgoingEvent
    session.py           — управление сессиями и чатами
    auth.py              — аутентификация
    settings.py          — коннекторы, скиллы, 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`](docs/surface-protocol.md)

---

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

### Telegram ([подробнее](docs/telegram-prototype.md))

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

### Matrix ([подробнее](docs/matrix-prototype.md))

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

---

## Замена SDK

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

```python
class PlatformClient(Protocol):
    async def get_or_create_user(...) -> User: ...
    async def create_session(...) -> Session: ...
    async def send_message(...) -> AgentResponse: ...
    async def close_session(...) -> None: ...
    async def get_settings(...) -> UserSettings: ...
    async def update_settings(...) -> None: ...
```

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

---

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

```bash
# Зависимости
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/surface-protocol.md) | Унификация поверхностей — все структуры, как добавить новую поверхность |
| [`docs/telegram-prototype.md`](docs/telegram-prototype.md) | Функционал Telegram прототипа |
| [`docs/matrix-prototype.md`](docs/matrix-prototype.md) | Функционал Matrix прототипа |
| [`docs/api-contract.md`](docs/api-contract.md) | Контракт к SDK платформы |
| [`docs/user-flow.md`](docs/user-flow.md) | FSM и user journey |
| [`docs/claude-code-guide.md`](docs/claude-code-guide.md) | Гайд по работе с Claude Code |

---

## Команда

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