# PleiadesOrchestra

PleiadesOrchestra — набор небольших сервисов, которые позволяют чат-ассистенту управлять сайтом с помощью **небольших локальных моделей** вместо одной крупной облачной. Что делать, решает GOAP-планировщик (goal-oriented action planning, целеориентированное планирование действий); модели выполняют только узкие задачи: классифицируют сообщение, заполняют аргументы инструмента, пишут короткий ответ.

Система не рассчитана на один тип сайта. Магазин, форма бронирования отеля, конструктор пиццы или касса билетов работают одинаково: сайт описывает, что он умеет, а оркестратор строит план вокруг этого описания.

## Как это работает

1. Сайт встраивает [виджет `<pleiades-chat>`](/ru/docs/widget/).
2. Сайт регистрирует собственные инструменты в браузере через WebMCP (`document.modelContext.registerTool`). Инструмент — это имя, описание и JSON-схема. См. [Инструменты](/ru/docs/tools/).
3. Когда панель открывается, виджет отправляет каталог инструментов оркестратору (`POST /v1/widget/tools`). См. [Widget API](/ru/docs/api/widget/).
4. Посетитель пишет сообщение. Оркестратор определяет, чего хочет посетитель, строит последовательность вызовов инструментов и передаёт прогресс потоком NDJSON.
5. Инструменты выполняются **в браузере посетителя**. Когда плану нужен инструмент, поток завершается строкой `tool_call`; виджет выполняет инструмент на странице и отправляет результат обратно, после чего запуск продолжается.

Оркестратор никогда не видит код или базу данных сайта — только имена инструментов, схемы и ответы инструментов.

## Сервисы

| Сервис | Роль |
| --- | --- |
| `alpha-orchestrator` | HTTP-сервис. Хранит каналы, посетителей, треды и историю (SQLite), запускает GOAP-планировщик и передаёт ответы потоком. Widget API и Server API описаны здесь. |
| `beta-text` | Сервис с небольшой моделью для ответов. Пишет разговорный ответ. |
| `gamma-decision` (Laya) | Sidecar для типизированных решений. Отвечает на вопросы выбора и оценки откалиброванными вероятностями; текст не пишет. Используется для классификации намерений и для выбора среди вариантов инструмента. |
| `delta-function-call` | Небольшой сервис с моделью, который заполняет JSON-аргументы вызова инструмента по сообщению посетителя и схеме инструмента. |
| alpha-understand | Не отдельный сервис: один вызов языковой модели из `alpha-orchestrator` на сообщение. Он пишет сообщение по-английски, делит его на задачи и отмечает количество каждого товара; модели решений и вызова функций читают только английский. |

Каждый сервис с моделью может работать на той же машине или на другой; `alpha-orchestrator` обращается к нему по базовому URL.

## Установка

На сервере с Linux или macOS одна команда ставит Docker (если его нет), генерирует API-ключи и запускает стек (оркестратор и admin API) одним контейнером `ghcr.io/francyfox/pleiades`. Модели в него не входят: они работают на другой машине, а их адреса и ключи передаются переменными окружения (`LLM_BASE_URL`, `LLM_API_KEY`, `FUNCTION_CALL_BASE_URL`, `FUNCTION_CALL_API_KEY`, `LAYA_API_BASE_URL`, `LAYA_API_KEY`) или правятся потом в `.env`:

```bash
curl -fsSL https://raw.githubusercontent.com/francyfox/PleiadesOrchestra/master/scripts/install.sh | bash
```

`.env` и `data/` лежат в `~/pleiades-orchestra` (`PLEIADES_DIR` меняет путь), `PLEIADES_VERSION` выбирает тег релиза. Повторный запуск скачивает новый образ и пересоздаёт контейнер, `.env` и данные сохраняются. Оркестратор слушает `127.0.0.1:3000`; публичный доступ — через обратный прокси или туннель. Админка открывается на `http://127.0.0.1:3002`; первого администратора создаёт `docker exec pleiades admin-api admin:create --email you@example.com` (токен входа печатается один раз). За доменом задайте в `.env` `BETTER_AUTH_URL` и `ADMIN_TRUSTED_ORIGINS` — публичный адрес панели.

## Страницы

- [Виджет](/ru/docs/widget/): установка и настройка `<pleiades-chat>`.
- [Инструменты](/ru/docs/tools/): как сайт предоставляет инструменты через WebMCP.
- [Полифил](/ru/docs/polyfill/): WebMCP в браузерах, где его нет, в том числе без виджета.
- [Widget API](/ru/docs/api/widget/): REST- и NDJSON-API, которое использует виджет.
- [Server API](/ru/docs/api/server/): эндпоинты для взаимодействия между серверами.
- [Намерения](/ru/docs/intents/): как классифицируется сообщение и что планируется.

<!-- TODO: link targets assume the SveltePress site serves content/<path>.md at /<path> and content/<dir>/index.md at /<dir>/; adjust if the router differs. -->
