@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/ollama.md

@@ -0,0 +1,116 @@
+# Ollama
+
+Sends a prompt to a local Ollama instance and streams the generated response into the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/ollama-prompt` |
+
+---
+
+## What it does
+
+OllamaPrompt connects to a locally running [Ollama](https://ollama.ai)
+server, sends a configured prompt (optionally composed with data from the
+upstream pipeline), and streams or returns the model's response as the
+next pipeline value.
+
+---
+
+## Prerequisites
+
+An Ollama server must be running and accessible at the configured
+`endpoint` (default: `http://localhost:11434/api`). At least one model
+must be pulled (`ollama pull llama3` etc.).
+
+Because this service runs in the browser, the request comes from a web origin
+and Ollama rejects it unless that origin is allowed. Start the server with the
+origin permitted:
+
+```sh
+OLLAMA_ORIGINS='*' OLLAMA_HOST=localhost:11434 ollama serve
+```
+
+The symptom of forgetting is a request that fails with nothing useful in the
+response — the browser blocks it before Ollama ever answers.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `endpoint` | `string` | `"http://localhost:11434/api"` | Base URL of the Ollama API |
+| `model` | `string` | `""` | Model name to use (e.g. `"llama3"`, `"mistral"`) |
+| `prompt` | `string` | `""` | Prompt template sent to the model |
+| `temperature` | `number` | `0` | Sampling temperature (0 = deterministic) |
+| `seed` | `number` | `0` | Random seed for reproducibility |
+| `responseIsJson` | `boolean` | `false` | Parse the response as JSON before emitting |
+
+### Dynamic prompt composition
+
+The `prompt` field can reference upstream pipeline data using standard
+JavaScript template literal syntax or by composing a string in a
+preceding [Map](./map.md) service:
+
+```
+Classify the following text: {{params.text}}
+```
+
+The upstream pipeline value's fields are available as context when the
+prompt is processed.
+
+### `responseIsJson`
+
+When `true`, the model's response is parsed with `JSON.parse()` before
+being emitted. Use this when the model is prompted to return structured
+data. If parsing fails the raw string is emitted as a fallback.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — can be incorporated into the prompt template |
+| **Output** | Model response as a `string`, or as a parsed JSON object if `responseIsJson: true` |
+
+---
+
+## Available models (read-only)
+
+The service fetches the list of locally available models from
+`{endpoint}/tags` and exposes them as `availableModels` in its state.
+This list is shown in the UI's model selector.
+
+---
+
+## Example
+
+Summarise each article fetched from an RSS feed:
+
+```json
+[
+  {
+    "serviceId": "hookup.to/service/fetcher",
+    "state": { "url": "https://example.com/feed.json" }
+  },
+  {
+    "serviceId": "hookup.to/service/ollama-prompt",
+    "state": {
+      "model": "llama3",
+      "prompt": "Summarise this article in one sentence: ",
+      "temperature": 0.3,
+      "responseIsJson": false
+    }
+  },
+  {
+    "serviceId": "hookup.to/service/monitor",
+    "state": {}
+  }
+]
+```

package/bundle/docs/content/services/openai-prompt.md

@@ -0,0 +1,74 @@
+# OpenAI Prompt
+
+Sends pipeline data to the OpenAI API and emits the model's response.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/openai-prompt` |
+
+---
+
+## What it does
+
+OpenAI Prompt connects to the OpenAI API and dispatches requests based on the selected model type:
+
+| Model type | Endpoint | Input | Output |
+|---|---|---|---|
+| `chat` | `/v1/chat/completions` | Text prompt + pipeline data | Assistant message string (or JSON) |
+| `image` | `/v1/images/generations` | Text prompt | Image URL |
+| `audio` (TTS) | `/v1/audio/speech` | Text string | Audio `Blob` |
+| `text` (Whisper) | `/v1/audio/transcriptions` | Audio `Blob` | Transcription string |
+
+The API key must be stored in the user vault under the key `openai-api-key` (read via `fromVault`).
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `model` | `string` | `"gpt-4o-mini"` | Model name |
+| `prompt` | `string` | `""` | System / user prompt prepended to the pipeline value |
+| `temperature` | `number` | `0` | Sampling temperature |
+| `seed` | `number` | `0` | Reproducibility seed |
+| `responseIsJson` | `boolean` | `false` | Parse the response as JSON before emitting |
+| `voice` | `string` | `"alloy"` | TTS voice (for `tts-1` model). One of `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer` |
+| `injectPrompt` | `boolean` | — | When `true`, appends the pipeline value to the configured prompt rather than replacing it |
+
+---
+
+## Available models
+
+| Model | Type |
+|---|---|
+| `gpt-4o-mini` | chat |
+| `dall-e-2` | image |
+| `dall-e-3` | image |
+| `tts-1` | audio |
+| `whisper-1` | text |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | String (chat/image/TTS) or audio `Blob` (Whisper) |
+| **Output** | String, JSON object, image URL, or audio `Blob` depending on model type |
+
+---
+
+## Example: summarise pipeline data
+
+```json
+{
+  "model": "gpt-4o-mini",
+  "prompt": "Summarise the following data in one sentence:",
+  "responseIsJson": false,
+  "temperature": 0.3
+}
+```

package/bundle/docs/content/services/output.md

@@ -0,0 +1,107 @@
+# Output
+
+Sends the current pipeline value to a remote endpoint via HTTP POST or WebSocket.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/output` |
+
+---
+
+## What it does
+
+Output is the egress point of a browser pipeline. On each pipeline
+trigger it serialises the current data to JSON and delivers it to a
+configured URL, either over a persistent WebSocket connection or as an
+HTTP POST request.
+
+Combined with the [Input](./input.md) service, Output is the standard
+way to bridge data between two runtimes — or from a browser pipeline to
+any external system.
+
+---
+
+## Modes
+
+| Mode | Description |
+|---|---|
+| `websocket` | Maintains a persistent WebSocket connection; sends each value as a JSON message |
+| `post` | Sends an HTTP POST request with the JSON body for each pipeline trigger |
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | `""` | Destination URL (`ws://`, `wss://`, `http://`, `https://`) |
+| `mode` | `"websocket" \| "post"` | `"websocket"` | Delivery mechanism |
+| `flow` | `"stop" \| "pass"` | `"stop"` | Whether to continue the pipeline after sending |
+| `headers` | `Record<string, string>` | `{}` | HTTP headers (for `post` mode) |
+| `bypass` | `boolean` | `true` | Skip sending; disconnect WebSocket if open. Output starts bypassed by default and must be explicitly activated. |
+
+### `flow`
+
+| Value | Behaviour |
+|---|---|
+| `"stop"` (default) | Pipeline terminates at Output; nothing downstream receives data |
+| `"pass"` | Data is sent AND the original input continues to the next service |
+
+Use `"pass"` when Output is a side-effect in the middle of a longer
+pipeline, e.g. logging to a server while also rendering to Canvas.
+
+### `headers`
+
+Static header values are strings. Dynamic headers (values evaluated at
+send time) use the same `=`-suffix syntax as the Map service:
+
+```json
+{
+  "Authorization=": "\"Bearer \" + params.token",
+  "Content-Type": "application/json"
+}
+```
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any JSON-serialisable value |
+| **Output (flow: stop)** | `null` — pipeline stops |
+| **Output (flow: pass)** | Original input, unchanged |
+
+---
+
+## Example: streaming to a remote runtime
+
+Send each timer tick to a remote hkp-rt WebSocket server:
+
+```json
+{
+  "url": "ws://my-server.example.com:9000/input",
+  "mode": "websocket",
+  "flow": "stop"
+}
+```
+
+## Example: HTTP POST with auth header
+
+Post data to a REST endpoint on each trigger:
+
+```json
+{
+  "url": "https://api.example.com/events",
+  "mode": "post",
+  "flow": "stop",
+  "headers": {
+    "Content-Type": "application/json",
+    "X-Api-Key": "my-secret-key"
+  }
+}
+```

package/bundle/docs/content/services/peer-socket.md

@@ -0,0 +1,61 @@
+# Peer Socket
+
+Establishes a named peer-to-peer WebSocket connection for sending or receiving pipeline data between boards or runtimes.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/peer-socket` |
+
+---
+
+## What it does
+
+Peer Socket connects to the board's peer signalling infrastructure and registers under a `peerName`. It can send outgoing pipeline values to a named `targetPeer`, receive incoming data from other peers and inject it into its own pipeline, or both simultaneously.
+
+When a message arrives from the target peer, it is pushed downstream via `app.next()` — independently of any upstream pipeline trigger.
+
+Both names default to a random identity, drawn from two different prefixes (`Host-…` for `peerName`, `Guest-…` for `targetPeer`) so that a socket left unconfigured never ends up addressing itself.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `"Receive only"` \| `"Send only"` \| `"Receive and Send"` | `"Receive only"` | Whether the service sends, receives, or both |
+| `peerName` | `string` | Random `"Host-xxxx"` | Name this peer registers under |
+| `targetPeer` | `string` | Random `"Guest-xxxx"` | Name of the peer to send to (in Send or Receive and Send modes) |
+| `extractIncomingData` | `boolean` | `false` | When `true`, only the `data` field of the incoming message is injected into the pipeline |
+| `peerPort` | `number \| null` | `null` | Port override for the peer server |
+| `peerHost` | `string \| null` | `null` | Host override for the peer server |
+| `peerPath` | `string \| null` | `null` | Path override for the peer server WebSocket endpoint |
+
+### Receiving data
+
+When `mode` includes `"Receive"`, the service listens for `{ incoming: <data> }` configure calls from the peer infrastructure and injects the data downstream.
+
+### Sending data
+
+When `mode` includes `"Send"`, each value that arrives via `process()` is transmitted to `targetPeer` over the peer WebSocket connection.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — sent to `targetPeer` in Send mode |
+| **Output** | Data received from the peer, injected via `app.next()` |
+
+---
+
+## Typical use
+
+Connect two boards running in different browser tabs or devices:
+
+- Board A: `... → Peer Socket (Send only, peerName: "device-a", targetPeer: "device-b")`
+- Board B: `Peer Socket (Receive only, peerName: "device-b") → ...`

package/bundle/docs/content/services/qr-code.md

@@ -0,0 +1,48 @@
+# QR Code
+
+Displays a QR code for a URL, updating dynamically when new URLs arrive in the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/qr-code` |
+
+---
+
+## What it does
+
+QR Code renders a scannable QR code image for the configured or pipeline-provided URL. The URL is resolved through `resolveTemplateVars` so template variables (e.g. `{{userId}}`) are substituted before encoding.
+
+When the incoming value contains a `fromLink=` query parameter, QR Code appends the current template variable map as a base64-encoded `vars=` parameter so that the QR code carries the full context needed to reconstruct the state on the target device.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | `""` | Base URL to display as a QR code. Template variables are resolved. |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | String URL, or object with a `url` / `requestPath` key |
+| **Output** | The original input value (pass-through) |
+
+When the incoming URL differs from the current state, the displayed QR code updates automatically.
+
+---
+
+## Typical use: board-in-a-QR-code
+
+```
+Browser Sub-Service (source mode) → LZ Compress → QR Code
+```
+
+Sub-service emits the board JSON, LZ Compress reduces it to a URL-safe string, and QR Code renders a link that another device can scan to load the board.

package/bundle/docs/content/services/queue.md

@@ -0,0 +1,201 @@
+# Queue
+
+How one board says something to another.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Node.js (hkp-node) | `queue` |
+
+---
+
+## What it does
+
+A board owns its data, and a second board has no business reading the first
+one's tables — that is most of the reason the two are separate boards at all.
+What crosses between them is a **message**: a payload on a named topic, meaning
+nothing to the queue and everything to the two boards that agreed on the name.
+
+That makes a queue the joint between boards that run on **different clocks**. A
+booking board finishes reading an enquiry in seconds; the hotels it writes to
+answer in days. No pipeline spans days, so the two halves cannot be one flow —
+but they are still one workflow, and the message is what carries it across.
+
+Use a queue when the two sides are separated in *time*. Two things that happen
+in the same second belong in one pipeline, nested for readability — not in two
+boards with a queue faking a boundary that isn't there.
+
+### Which queue a `queue` sees
+
+Every other table in this runtime lives in a per-board file, which is what stops
+one board reading another's. **A queue is the deliberate exception**, and the
+only one: publishing and consuming are by definition not the same board, so the
+rows live in the database shared by every board of one owner.
+
+Isolation still holds where it matters. Between owners it is absolute — one
+person's messages are in another file entirely. And it holds around everything
+that is *not* a message: conversations, artifacts and a board's own SQL tables
+never leave the board they belong to.
+
+### Both sides sit on one runtime server
+
+The messages live with the runtime that took them in, so a board reaching them
+is a board on that same server. This is the locality rule
+[Conversations](./conversations.md) and [SQL](./sql.md) already have, not a new
+one: a board name means one database *per server it runs on*.
+
+Two units that talk therefore sit on one runtime server for now. Reaching a
+queue on another one is a job for the coordinator, which already holds a
+credential for every runtime of a board — a service inside a runtime holds none,
+and giving it one is the wrong shape.
+
+**Publish before you commit.** The one thing a board has to get right. A publish
+that fails passes nothing on and stops the pipeline, so the state change that
+says the message was sent must come *after* it. Ordered that way, a failed
+publish leaves the board where it was and the next tick sends it again — the
+board's own timer is the retry, which is why the framework needs no outbox.
+
+### Nobody dispatches
+
+There is no delivery loop and no router. A board **pulls**: put a `consume` in a
+pipeline that a [Timer](./timer.md) drives, exactly as a board polls anything
+else, and pair it with [Iterator](./iterator.md) to act on the messages one at a
+time.
+
+This is deliberate. A queue that pushed would be a wire between boards, and
+wires are what the ordered service list exists to avoid. What a queue adds is
+not routing but time.
+
+---
+
+## Modes
+
+| Mode | What it does | Emits |
+|---|---|---|
+| `publish` (default) | Puts one message on a topic | the message as stored |
+| `consume` | Claims the messages that may be worked on now | `{ messages: [...], count }` |
+| `ack` | Closes a claimed message: the work is done | `{ id, status, attempts }` |
+| `fail` | Hands a claimed message back, or buries it | `{ id, status, attempts }` |
+| `list` | Reads the log without claiming anything | `{ messages: [...], count }` |
+
+---
+
+## The guarantee: at-least-once, and the board says when
+
+`consume` claims a message for `visibilitySeconds` and hands it on. The pipeline
+does the work. An `ack`, placed where success is actually known, closes it.
+
+Anything that stops in between — a crash, a send that failed, a runtime
+restarted mid-flight — leaves the claim to expire, and the message is handed out
+again. That is the honest guarantee for work driven by mail: **the same enquiry
+twice is a nuisance; an enquiry lost is a customer.**
+
+A claim is therefore a deadline, not a lock. A runtime that dies holds nothing,
+and no one has to release anything on its behalf.
+
+A message handed out `maxAttempts` times without an acknowledgement stops being
+retried and is marked `dead`, where it stays readable — with the attempt count
+and the reason — rather than disappearing. `fail` on a message that has already
+used up its attempts buries it immediately, instead of handing it out once more
+only to bury it on the next pass.
+
+**Acked messages are kept.** A queue that deletes on ack can answer "what is
+pending" and nothing else, while the question actually asked when something has
+gone wrong is *what did the other board send me an hour ago, and what did I do
+with it*. `list` reads the whole log, claim state and attempt count included.
+
+---
+
+## Configuration
+
+| Field | Default | What it does |
+|---|---|---|
+| `mode` | `publish` | See the mode table |
+| `topic` | — | The name the two boards agreed on. Required by `publish` and `consume`; an optional filter for `list` |
+| `payloadFrom` | `""` | Dotted path to the part of the input to send. Empty sends the whole input |
+| `idFrom` | `id` | Where `ack` and `fail` find the message id in their input |
+| `limit` | `10` | How many messages one `consume` claims, or `list` returns |
+| `visibilitySeconds` | `300` | How long a claim holds before the message is handed out again |
+| `maxAttempts` | `5` | Hand-outs without an ack before the message is left alone |
+| `status` | `""` | Filter for `list`: `pending`, `claimed`, `done`, `dead` |
+
+| | |
+|---|---|
+| **Input** | whatever is being sent (`publish`), or a claimed message (`ack`, `fail`) |
+| **Output** | see the mode table above |
+| **Arrays** | a published array is **one** message, not many |
+| **Binary** | not accepted |
+
+A published array stays one message on purpose. What a board sends is what the
+other board reads, and a producer that meant several says so with an
+[Iterator](./iterator.md) — splitting here would make the count depend on the
+shape of a payload the queue is supposed to know nothing about.
+
+Anything that goes wrong is reported as `{ error }` and **passes nothing on**.
+
+---
+
+## Where it lives
+
+One file per owner, beside the per-board databases:
+
+```
+~/.hkp/node-<instance>/db/<sha256(owner)>/shared.db
+```
+
+`HKP_DB_DIR` moves the root; `HKP_DB_DIR=""` keeps everything in memory, which
+is what a throwaway run wants.
+
+---
+
+## Example
+
+The booking board, having understood an enquiry, sends it on:
+
+```json
+{
+  "uuid": "hand-over",
+  "serviceId": "queue",
+  "serviceName": "Queue",
+  "state": {
+    "mode": "publish",
+    "topic": "booking.ready",
+    "payloadFrom": "extraction"
+  }
+}
+```
+
+The hotels board picks it up on its own clock, acts on it, and closes it:
+
+```json
+[
+  { "uuid": "tick", "serviceId": "timer",
+    "state": { "periodic": true, "periodicValue": 30, "periodicUnit": "s", "running": true } },
+
+  { "uuid": "incoming", "serviceId": "queue",
+    "state": { "mode": "consume", "topic": "booking.ready", "limit": 5 } },
+
+  { "uuid": "per-request", "serviceId": "iterator",
+    "state": { "itemsFrom": "messages",
+               "pipeline": [ "…find hotels, draft the enquiry…",
+                 { "uuid": "done", "serviceId": "queue",
+                   "state": { "mode": "ack", "topic": "booking.ready" } } ] } }
+]
+```
+
+The `ack` sits **last**, after the work — that placement is the guarantee. Put
+it directly after the `consume` and a failure downstream loses the request
+silently.
+
+---
+
+## Testing a board on its own
+
+Because a topic is just a name, nothing has to exist on the other side. Publish
+a message by hand — an [Injector](./injector.md) into a `publish`, or the
+service's own panel — and the consuming board runs as if the producer were
+there. A board that consumes a topic nobody publishes to reads zero messages and
+reports no error, which is what makes it loadable and testable alone.

package/bundle/docs/content/services/reduce.md

@@ -0,0 +1,51 @@
+# Reduce
+
+Folds a stream of pipeline values into a single accumulated result using a user-defined reducer expression.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/reduce` |
+
+---
+
+## What it does
+
+Reduce maintains an internal `reducedState` across successive pipeline ticks. On each `process()` call, the configured `reducer` expression is evaluated with `params` set to the current input and the accumulated state accessible as a second argument. The expression's return value becomes the new `reducedState` and is emitted downstream.
+
+This is conceptually equivalent to `Array.prototype.reduce` applied to a live stream over time.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `initialState` | `any` | `undefined` | Starting value for `reducedState`. Also resets the accumulator when updated. |
+| `reducer` | `string` | `""` | Expression evaluated per tick. Uses the same expression syntax as [Map](./map.md). |
+| `resetReducer` | `boolean` | `false` | When `true`, resets `reducedState` back to `initialState` on next configure call |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value — available as `params` in the reducer expression |
+| **Output** | The accumulated `reducedState` after applying the reducer |
+
+---
+
+## Example: running total
+
+```json
+{
+  "initialState": 0,
+  "reducer": "params.value + state"
+}
+```
+
+Each tick adds the incoming `value` to the running total. (Exact expression syntax depends on how `state` is bound in the expression scope — consult the Map service expression reference.)