# Dreamer (@leumas/dreamer)

The ecosystem's multi-stage ideation pipeline: a data-defined chain of LLM stages — the default is idea → expansion → feasibility → selection → scaffold → notes — where each stage can read earlier...


The ecosystem's **multi-stage ideation pipeline**: a data-defined chain of LLM stages — the default
is `idea → expansion → feasibility → selection → scaffold → notes` — where each stage can read
earlier stages' outputs and, critically, **run on any configured model** (ported from the legacy
`Dreamer` tool, which was hardwired to a single local Ollama model in five places).

## How agents call it

| Surface | How |
|---|---|
| Chatbot / Leviathan | attach the `dream` functioncall (stored doc, executor `action:dream`) |
| Automation rule | action `dream` (e.g. cron trigger → "ideate on X weekly") |
| MCP client | `functioncalls` server → `dream` tool |
| 3D-programming grid | an `action:dream` cell, chainable with other cells |
| HTTP | `POST /api/dreamer/run` (JSON) or `POST /api/dreamer/run/stream` (SSE) |
| Studio | Intelligence → Dreamer |
| Code | `runDreamer({ topic, depth, mode, definition, provider, model, stageModels, onEvent, signal, providerRegistry, connector })` from `@leumas/dreamer` |

Args: `topic` (required) · `depth` `standard`|`deep` (default standard) · `mode` `standard`|`wild`
(wild favors unconventional-but-plausible ideas) · `provider`/`model` (any @leumas/providers brain,
default `auto`) · `pipeline` (a custom definition; defaults to the 6-stage pipeline) · `stageModels`
(per-stage model overrides) · `inputValues` (values for a pipeline's declared `{{input.*}}` tokens).

## Any model — and mixable per stage (the whole point)

This is the headline capability. `provider`/`model` set the run default, but **`stageModels` overrides
the model per stage by key**, so a single run can brainstorm cheaply and decide expensively:

```jsonc
POST /api/dreamer/run
{
  "topic": "carbon-negative concrete",
  "depth": "deep",
  "provider": "auto",
  "stageModels": { "idea": "llama3.1", "selection": "claude-opus-4-8" }
}
```

Resolution per stage: `stageModels[key] → stage.provider/stage.model → the run's provider/model →
'auto'`. `'auto'` always resolves to whatever provider is available, so a call with no model set
still runs. Never call a raw provider — always go through the injected registry.

## The pipeline is DATA (add a stage with no code change)

A pipeline is portable JSON: `{ name, version, stages: [{ key, label, task, outputFormat,
priorOutputs }] }`. Studio can edit it, an action/HTTP caller can pass one in, and a tenant can store
their own. Validate any custom definition first — `GET /api/dreamer/pipeline` returns the default;
`POST /api/dreamer/pipeline/validate` returns `{ ok, errors }`. The one validator rejects duplicate
keys, self-references, unknown `priorOutputs`, and **forward references** (a stage consuming a later
stage's output).

## SSE vocabulary

`start · stage_start · stage_done · done · error` (+ `: ping` heartbeat every 15s; client disconnect
aborts the run; read POST-SSE with the shared `admin/_shared/sse.js` `streamPostSse` — EventSource is
GET-only). Every stage checkpoints to `/db/dreamer_runs`, so a dropped stream loses nothing and a
partial/failed run is still readable (the legacy tool left orphan folders with no status).

## Persistence

`dreamer_runs` dynamic collection (auto-written when a connector is injected): the doc is created
`running` up-front and updated after each stage with `steps`, `outputs`, `usage`, then finalized
`done`/`aborted`/`error`. No separate list route — query `/db/dreamer_runs`.

## Gating

`requireAuth` + `requireMembership('intelligence')` (admins bypass) + PassNode guard
`feature:dreamer.run` — author a `passnode_rules` doc with that resource id to meter/charge runs; no
rule = free pass. LLM calls cost real tokens, so meter before white-labeling.


---
Source: shared/services/knowledge/build-knowledge/dreamer.md
Canonical: https://docs.leumas.tech/p/how-to/dreamer