# PleiadesOrchestra

PleiadesOrchestra is a set of small services that let a chat assistant operate a website with **small local models** instead of one large hosted model. A GOAP planner (goal-oriented action planning) decides what to do; the models only do narrow jobs: classify a message, fill in a tool's arguments, write a short reply.

It is not built for one kind of site. A shop, a hotel booking form, a pizza builder or a ticket desk all work the same way: the site describes what it can do, and the orchestrator plans around that description.

## How it works

1. The site embeds the [`<pleiades-chat>` widget](/docs/widget/).
2. The site registers its own tools in the browser with WebMCP (`document.modelContext.registerTool`). A tool is a name, a description and a JSON schema. See [Tools](/docs/tools/).
3. When the panel opens, the widget sends the tool catalog to the orchestrator (`POST /v1/widget/tools`). See the [Widget API](/docs/api/widget/).
4. A visitor writes a message. The orchestrator works out what the visitor wants, plans a sequence of tool calls, and streams progress back as NDJSON.
5. Tools run **in the visitor's browser**. When the plan needs one, the stream ends with a `tool_call` line; the widget runs the tool on the page and posts the result back, and the run resumes.

The orchestrator never sees the site's code or database, only tool names, schemas, and what the tools answer.

## Services

| Service | Role |
| --- | --- |
| `alpha-orchestrator` | HTTP service. Holds channels, visitors, threads and history (SQLite), runs the GOAP planner and streams replies. The widget API and the server API are documented here. |
| `beta-text` | A small model service for replies. Writes the conversational answer. |
| `gamma-decision` (Laya) | Typed-decision sidecar. Answers choice and score questions with calibrated probabilities; never writes text. Used for intent classification and for choosing among a tool's options. |
| `delta-function-call` | A small model service that fills the JSON arguments of a tool call from the visitor's message and the tool's schema. |
| alpha-understand | Not a separate service: one call of a language model from `alpha-orchestrator` per message. It writes the message in English, splits it into tasks and marks how many of each product; the decision and function-call models read English only. |

Each model service can run on the same machine or elsewhere; `alpha-orchestrator` reaches it by base URL.

## Install

On a Linux or macOS server with `curl`, one command installs Docker if it is missing, generates the API keys and starts the stack (orchestrator and admin API) as one container, `ghcr.io/francyfox/pleiades`. The models are not part of it: they run on another machine, and you pass their addresses and keys as environment variables (`LLM_BASE_URL`, `LLM_API_KEY`, `FUNCTION_CALL_BASE_URL`, `FUNCTION_CALL_API_KEY`, `LAYA_API_BASE_URL`, `LAYA_API_KEY`) or edit `.env` afterwards:

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

`.env` and `data/` land in `~/pleiades-orchestra` (`PLEIADES_DIR` changes it); `PLEIADES_VERSION` picks a release tag. Rerunning the command pulls the new image and recreates the container; your `.env` and data are kept. The orchestrator listens on `127.0.0.1:3000`; public access goes through a reverse proxy or a tunnel. The admin panel opens at `http://127.0.0.1:3002`; create the first admin with `docker exec pleiades admin-api admin:create --email you@example.com` (the sign-in token is printed once). Behind a domain, set `BETTER_AUTH_URL` and `ADMIN_TRUSTED_ORIGINS` in `.env` to the panel's public URL.

## Pages

- [Widget](/docs/widget/): install and configure `<pleiades-chat>`.
- [Tools](/docs/tools/): how a site exposes tools with WebMCP.
- [Polyfill](/docs/polyfill/): WebMCP in browsers that lack it, also without the widget.
- [Widget API](/docs/api/widget/): the REST and NDJSON API the widget uses.
- [Server API](/docs/api/server/): server-to-server endpoints.
- [Intents](/docs/intents/): how a message is classified, and what is planned.

<!-- 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. -->
