Intro

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 .
  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 .
  3. When the panel opens, the widget sends the tool catalog to the orchestrator (POST /v1/widget/tools). See the Widget API .
  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

ServiceRole
alpha-orchestratorHTTP 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-textA 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-callA small model service that fills the JSON arguments of a tool call from the visitor's message and the tool's schema.
alpha-understandNot 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:

curl -fsSL https://raw.githubusercontent.com/francyfox/PleiadesOrchestra/master/scripts/install.sh | bash
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 : install and configure <pleiades-chat>.
  • Tools : how a site exposes tools with WebMCP.
  • Polyfill : WebMCP in browsers that lack it, also without the widget.
  • Widget API : the REST and NDJSON API the widget uses.
  • Server API : server-to-server endpoints.
  • Intents : how a message is classified, and what is planned.