TOM (Total Orchestration Manager)

RU: локально ориентированный AI-оркестратор на Rust: роли (архитектор, кодер, аудитор и др.), FSM, планирование с декомпозицией, инструменты (ФС, git, shell, семантика, AST), память в PostgreSQL + векторы (pgvector, LanceDB), промпты под Ollama / gRPC к инференсу — попытка собрать автономный контур «задача → план → шаги → верификация» без привязки к одному облачному API.

EN: a Rust-first, local-first AI orchestration stack — multi-role planning, resilient markdown parsing (Tree-sitter), hybrid memory (Postgres + embeddings), and tool execution; optional tom-server / tom-client for inference over gRPC. Designed for repeatable agent runs with auditability and configurable models.

Ядро самодостаточно по логике оркестрации: состояние сессий и знания живут в БД и на диске, а конкретные модели и эндпоинты задаются конфигом (Settings, env, Keychain на macOS).

---

Оглавление

• Идея и принцип
• Как устроен контур
• Почему Rust и локальные модели
• Архитектура
• Требования и ограничения
• Быстрый старт
• Команды CLI
• Структура репозитория
• Документация
• Лицензия

---

Идея и принцип

Разработка с ИИ часто распадается на чат без памяти и без жёсткого цикла проверки. TOM задаётся целью свести это к машине состояний: оркестратор ведёт сессию, планировщик дробит работу, роли специализируют промпты, инструменты меняют реальность (файлы, репозиторий, команды), а консенсус и shadow-audit снижают риск «одной галлюцинации».

Ключевой принцип: критичные пути — на Rust; конфигурация и секреты не зашиваются в код (иерархия config.toml, env, macOS Keychain для ключей). Подробности целей и фаз — в docs/ROADMAP.md, архитектура — docs/design/ARCHITECTURE.md.

---

Как устроен контур

1. Старт сессии — команда start (интерактивно или с текстом задачи); конфигурация моделей и режимов (--local, --deep-reasoning, auto_proceed).
2. Планирование — мастер-план и итеративная декомпозиция, устойчивый разбор markdown (Tree-sitter).
3. Исполнение — инструменты и транзакционные действия с откатом при ошибках (в т.ч. FS / git).
4. Память и индексация — код-маппинг, эмбеддинги, граф знаний; фоновые процессы по мере реализации.
5. Верификация — политика «сначала проверка, потом доверие» (см. docs/AUTONOMOUS_SYSTEM.md).

flowchart LR
  subgraph entry [Вход]
    U[Задача / сессия]
  end
  subgraph core [tom-core]
    O[Orchestrator / FSM]
    P[Планировщик]
    T[Инструменты]
    O --> P --> T
  end
  subgraph data [Данные]
    PG[(PostgreSQL)]
    LD[(LanceDB)]
  end
  U --> O
  T --> PG
  T --> LD

Loading

---

Почему Rust и локальные модели

• Rust: предсказуемая производительность, один бинарь для ядра, строгая модель ошибок на границах с БД и сетью.
• Локальные модели (Ollama и др.): меньше утечек данных, воспроизводимые прогоны, контроль стоимости; флаг --local в CLI переключает сценарий на локальный инференс вместо удалённого хоста (см. код и конфиг).

Имена моделей и URL задаются в настройках, а не в README.

---

Архитектура

Крейт	Назначение
tom-core	CLI, оркестратор, планы, промпты, инструменты, БД, роли
tom-server	Сервис инференса (подключение локальных движков)
tom-client	gRPC-клиент к серверу инференса

flowchart TB
  subgraph ws [Workspace]
    C[tom-core CLI]
    S[tom-server]
    CL[tom-client]
  end
  C --> PG[(Postgres + pgvector)]
  C --> L[LanceDB]
  C <-- gRPC / HTTP --> S
  CL --> S

Loading

Миграции схемы: каталог migrations/.

---

Требования и ограничения

• PostgreSQL с расширением pgvector (удобно поднять через docker-compose.yml).
• Сборка tom-core тянет тяжёлые зависимости (SQLx, LanceDB, ML-стек при включённых фичах) — первый cargo build может занять заметное время.
• Секреты API на macOS ожидаются через Keychain (SecretManager); на других ОС путь может отличаться.
• Проект в активной разработке: не всё из ROADMAP реализовано на 100%.

---

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

Нужны Rust (stable) и Docker (для Postgres), либо свой инстанс Postgres с параметрами как в docker-compose.yml.

1. База данных

docker compose up -d

Проверьте строку подключения в конфиге (по умолчанию в коде задаётся postgres://tom:tom_pass@localhost:5432/tom_db — приведите её в соответствие с вашим docker-compose и Settings).

2. Сборка и запуск ядра

cargo build -p tom-core
cargo run -p tom-core -- status

Интерактивный старт задачи:

cargo run -p tom-core -- start

Переменные окружения и файлы конфигурации: см. загрузку в Settings::load (в т.ч. .tom/config.toml, dotenv).

---

Команды CLI

Команда	Назначение
start	Новая задача или продолжение; опции --task, --title, --auto-proceed, --deep-reasoning, --local
index	Индексация каталога через CodeMapper (--path, по умолчанию .)
status	Проверка окружения и связности
keys	Управление секретами в Keychain (set / delete / status)
migrate-vectors	Миграция эмбеддингов Postgres → LanceDB

Без подкоманды поведение см. в main.rs.

---

Структура репозитория

tom/
├── crates/
│   ├── tom-core/     # CLI, оркестрация, инструменты, БД
│   ├── tom-server/   # инференс-сервер
│   └── tom-client/   # gRPC-клиент
├── docs/             # ROADMAP, архитектура, гайды
├── migrations/       # SQLx
├── docker/           # образы и конфиги
├── scripts/          # вспомогательные скрипты
├── sandbox/          # изолированные эксперименты (см. .gitignore)
├── docker-compose.yml
├── run.sh            # сценарий запуска server/client (локальная среда)
└── Cargo.toml

---

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

Документ	Содержание
docs/ROADMAP.md	Дорожная карта и принципы
docs/design/ARCHITECTURE.md	Структура и движки
docs/AUTONOMOUS_SYSTEM.md	Автономность и verify

---

Лицензия

MIT — см. LICENSE.