# PleiadesOrchestra

PleiadesOrchestra — чат-ассистентке бір үлкен хостингтегі модельдің орнына **шағын локалды модельдер** арқылы веб-сайтты басқаруға мүмкіндік беретін шағын сервистер жиынтығы. Не істеу керектігін GOAP планировщигі (goal-oriented action planning, мақсатқа бағытталған әрекеттерді жоспарлау) шешеді; модельдер тек тар міндеттерді орындайды: хабарламаны жіктеу, құралдың аргументтерін толтыру, қысқа жауап жазу.

Жүйе бір ғана сайт түріне арналмаған. Дүкен, қонақүйді брондау формасы, пицца конструкторы немесе билет анықтамасы — бәрі бірдей жұмыс істейді: сайт өзінің не істей алатынын сипаттайды, ал оркестратор сол сипаттама бойынша жоспар құрады.

## Қалай жұмыс істейді

1. Сайт [`<pleiades-chat>` виджетін](/kk/docs/widget/) енгізеді.
2. Сайт өз құралдарын браузерде WebMCP арқылы тіркейді (`document.modelContext.registerTool`). Құрал — атау, сипаттама және JSON-схема. [Құралдар](/kk/docs/tools/) бөлімін қараңыз.
3. Панель ашылғанда виджет құралдар каталогын оркестраторға жібереді (`POST /v1/widget/tools`). [Widget API](/kk/docs/api/widget/) бөлімін қараңыз.
4. Келуші хабарлама жазады. Оркестратор келушінің не қалайтынын анықтайды, құрал шақыруларының тізбегін жоспарлайды және барысын NDJSON ретінде ағынмен қайтарады.
5. Құралдар **келушінің браузерінде** орындалады. Жоспарға құрал қажет болғанда ағын `tool_call` жолымен аяқталады; виджет құралды бетте орындап, нәтижесін кері жібереді, сонда жұмыс жалғасады.

Оркестратор сайттың кодын да, дерекқорын да көрмейді: тек құрал атауларын, схемаларын және құралдардың жауаптарын көреді.

## Сервистер

| Сервис | Рөлі |
| --- | --- |
| `alpha-orchestrator` | HTTP-сервис. Арналарды, келушілерді, тредтер мен тарихты (SQLite) сақтайды, GOAP планировщигін іске қосады және жауаптарды ағынмен береді. Widget API мен server API осы жерде сипатталған. |
| `beta-text` | Шағын жауап моделі бар сервис. Сөйлесу жауабын жазады. |
| `gamma-decision` (Laya) | Типтелген шешімдер үшін қосалқы сервис. Таңдау және баға туралы сұрақтарға калибрленген ықтималдықтармен жауап береді; мәтін жазбайды. Ниетті жіктеу үшін және құралдың нұсқаларының арасынан таңдау үшін қолданылады. |
| `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` мәндерін панельдің жария мекенжайына қойыңыз.

## Беттер

- [Виджет](/kk/docs/widget/): `<pleiades-chat>` орнату және баптау.
- [Құралдар](/kk/docs/tools/): сайт құралдарды WebMCP арқылы қалай ашады.
- [Polyfill](/kk/docs/polyfill/): WebMCP-і жоқ браузерлерде, виджетсіз де.
- [Widget API](/kk/docs/api/widget/): виджет қолданатын REST және NDJSON API.
- [Server API](/kk/docs/api/server/): серверден серверге арналған эндпоинттер.
- [Ниеттер](/kk/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. -->
