# RocketRide Documentation

> Build, run, and ship data + AI pipelines with the RocketRide toolchain.


---

# RocketRide Documentation

Route: /

---
slug: /
title: RocketRide Documentation
sidebar_label: Home
sidebar_position: 0
hide_table_of_contents: true
hide_title: true
pagination_next: null
pagination_prev: null
---

import { LuZap, LuCode, LuRocket, LuCloud, LuPlug, LuBlocks, LuBookOpen } from 'react-icons/lu';
import { SiPython, SiTypescript, SiDiscord, SiGithub } from 'react-icons/si';
import { VscVscode } from 'react-icons/vsc';

<div className="rr-hero">

# RocketRide <span className="rr-accent">Documentation</span>

RocketRide is an open-source runtime for AI pipelines. Pipelines are portable JSON: version-controlled, shareable, and executed by a multithreaded C++ core that runs the same way on your laptop, your servers, or RocketRide Cloud.

<div className="rr-hero-actions">
  <a className="rr-btn rr-btn--primary" href="/quickstart">Get Started</a>
  <a className="rr-btn rr-btn--secondary" href="/concepts/pipelines">Core Concepts</a>
</div>

</div>

<span className="rr-kicker">01 · Build</span>
## Build your first pipeline

New to RocketRide? Start here: run a working pipeline and pick up the core concepts along the way.

<CardGrid>
  <Card href="/quickstart/ide-walkthrough" title="Build in your IDE" icon={<LuZap />}>
    Install the VS Code extension, deploy a local runtime, and assemble a pipeline visually in minutes.
  </Card>
  <Card href="/quickstart/sdk-integration" title="Integrate with an SDK" icon={<LuCode />}>
    Drop pipelines into your TypeScript or Python application with a few lines of code.
  </Card>
</CardGrid>

<span className="rr-kicker">02 · Run</span>
## Choose how you run RocketRide

<CardGrid>
  <Card href="/operate/cloud" title="RocketRide Cloud" icon={<LuCloud />}>
    Start building right away on the managed platform. Same pipeline JSON, zero infrastructure to manage.
  </Card>
  <Card href="/operate/self-hosting" title="Self-host" icon={<LuRocket />}>
    Run the runtime on your own infrastructure — Docker, on-prem, or anywhere the engine builds.
  </Card>
</CardGrid>

<span className="rr-kicker">03 · Explore</span>
## Explore more

<CardGrid columns={3}>
  <Card href="/clients/typescript" title="TypeScript SDK" icon={<SiTypescript />}>
    Deploy, run, and observe pipelines from your TypeScript app.
  </Card>
  <Card href="/clients/python" title="Python SDK" icon={<SiPython />}>
    The same client surface, native to Python.
  </Card>
  <Card href="/nodes" title="Nodes" icon={<LuBlocks />}>
    The full catalog: LLMs, vector stores, parsers, tools, and more.
  </Card>
  <Card href="/connect/mcp/http" title="MCP" icon={<LuPlug />}>
    Expose any pipeline as an MCP tool for AI assistants.
  </Card>
  <Card href="/clients/vscode" title="VS Code Extension" icon={<VscVscode />}>
    Build, run, and debug pipelines visually in your editor.
  </Card>
  <Card href="/reference/pipeline-reference" title="Pipeline Reference" icon={<LuBookOpen />}>
    Every field of the portable pipeline JSON format.
  </Card>
</CardGrid>

<span className="rr-kicker">04 · Community</span>
## Community

<CardGrid>
  <Card href="https://discord.gg/PMXrtenMsY" title="Discord" icon={<SiDiscord />}>
    Share what you're building, swap ideas, and get help from the community.
  </Card>
  <Card href="https://github.com/rocketride-org" title="GitHub" icon={<SiGithub />}>
    RocketRide is open source. Report bugs, discuss in issues, and contribute code.
  </Card>
</CardGrid>


---

# Quickstart

Route: /quickstart

---
sidebar_position: 2
sidebar_label: Overview
title: Quickstart
hide_table_of_contents: true
---

import { LuLayoutDashboard, LuCode, LuTerminal } from 'react-icons/lu';

# Quickstart

Pick the path that matches how you want to build. Each one takes you from zero
to a running pipeline.

<div className="rr-card-grid">

<a className="rr-side-card" href="/quickstart/ide-walkthrough">
  <span className="rr-side-card__head"><LuLayoutDashboard className="rr-card-icon" /><span className="rr-side-card__title">Build in your IDE</span></span>
  <span className="rr-side-card__body">Install the extension, deploy a local runtime, and wire up your first pipeline on the visual canvas.</span>
</a>

<a className="rr-side-card" href="/quickstart/sdk-integration">
  <span className="rr-side-card__head"><LuCode className="rr-card-icon" /><span className="rr-side-card__title">Integrate with an SDK</span></span>
  <span className="rr-side-card__body">Run the <code>.pipe</code> file you built from your own Python or TypeScript application.</span>
</a>

<a className="rr-side-card" href="/quickstart/cli">
  <span className="rr-side-card__head"><LuTerminal className="rr-card-icon" /><span className="rr-side-card__title">Run from the CLI</span></span>
  <span className="rr-side-card__body">Start, feed, and monitor pipelines from a terminal — no code required.</span>
</a>

</div>

## New to RocketRide?

Start with **[Build in your IDE](/quickstart/ide-walkthrough)**, it installs the extension,
spins up a local runtime, and walks you through a `Chat → LLM` pipeline you can run in
minutes. Once you have a pipeline, the
**[SDK walkthrough](/quickstart/sdk-integration)** shows how to run it from your own
[Python](/clients/python) or [TypeScript](/clients/typescript) application. Not sure
where it should run long-term? See
[Choose How to Run RocketRide](/operate).

## More examples

For a curated, community-maintained list of RocketRide projects, templates, and integration
examples, see
[**awesome-rocketride**](https://github.com/rocketride-org/awesome-rocketride): real-world
pipelines (RAG over your docs, document extraction (OCR/NER), PII anonymization,
multi-provider LLM routing, and agent workflows), plus starter templates you can clone and
run.


---

# Run from the CLI

Route: /quickstart/cli

---
title: Run from the CLI
---

# Run from the CLI

The `rocketride` command-line tool runs pipelines from a terminal — the same
operations the SDKs expose, no code required. It ships with both
[clients](/clients): `pip install rocketride` or `npm install rocketride` puts
`rocketride` on your path.

The five steps below take you from a fresh install to a running pipeline. The
full command and flag reference is on the [CLI page](/connect/cli).

## 1. Point at an engine

Set your connection once with environment variables so you don't have to repeat
them on every command:

```bash
# Local engine (no API key needed)
export ROCKETRIDE_URI=ws://localhost:5565

# RocketRide Cloud — generate an API key from the online editor
export ROCKETRIDE_URI=wss://api.rocketride.ai
export ROCKETRIDE_APIKEY=your-api-key
```

See [Choose How to Run RocketRide](/operate) for engine setup.

## 2. Start a pipeline

Pass a `.pipe` file. The command starts the task, prints its token, and exits;
the pipeline keeps running on the engine:

```bash
rocketride start --pipeline ./my-pipeline.pipe
```

The CLI prints a **task token** when the run starts. Copy it, you'll use it
in the next steps.

```
Starting pipeline from ./my-pipeline.pipe...
Pipeline started.
Token: ey...
Stop it with: rocketride stop --token ey...
```

## 3. Upload files through a pipeline

Use `upload` to push one or more files through an extraction or processing
pipeline:

```bash
rocketride upload --pipeline ./extract.pipe ./document.pdf
```

Or feed files into a task that's already running by passing its token:

```bash
rocketride upload --token <task-token> ./report-q1.pdf ./report-q2.pdf
```

## 4. Check what is running

List the active tasks to confirm yours is still up and to find its token again:

```bash
rocketride list
```

The CLI does not stream events; live monitoring belongs to the platform's
monitor apps.

## 5. Stop a task

When you're done, or need to cancel early:

```bash
rocketride stop --token <task-token>
```

## Next steps

- [CLI reference](/connect/cli): every command, flag, and the file-store operations.
- [Integrate with an SDK](/quickstart/sdk-integration): the same operations, in code.
- [Examples](/examples/rag-pipeline): full pipelines to run.


---

# Build a pipeline in your IDE

Route: /quickstart/ide-walkthrough

---
title: Build a pipeline in your IDE
sidebar_label: Build in your IDE
---

import ThemedImage from '@theme/ThemedImage';
import { LuPlay } from 'react-icons/lu';

# Build a pipeline in your IDE

The visual canvas in the VS Code extension is the fastest way to author a `.pipe` file.
This walkthrough starts from zero and finishes with a running `Chat → LLM` pipeline you
can talk to.

## 1. Install the extension

Search for **RocketRide** in the VS Code Extension Marketplace and install it. The
extension also works in VS Code forks (Cursor, Windsurf, VSCodium) via the
[Open VSX Registry](https://open-vsx.org/extension/RocketRide/rocketride).

## 2. Deploy a server

Click the RocketRide
(<ThemedImage alt="RocketRide" className="rr-inline-icon" sources={{ light: '/img/rocketride-icon-colored.svg', dark: '/img/rocketride-icon-white.svg' }} />)
icon in your IDE sidebar, then choose how to run the runtime. **Local** is the
right choice here — it pulls the server straight into your IDE with no extra
setup. (The other options are covered in
[Choose How to Run RocketRide](/operate).)

## 3. Create a pipeline file

Create a file ending in `.pipe` (e.g. `my-first-pipeline.pipe`). The extension opens it in
the visual builder canvas. `.pipe` files are JSON under the hood, but you author them
visually.

## 4. Build a simple chat pipeline

Every pipeline starts with a **source node**:

1. Add a **Chat** source node: an interactive conversational interface.
2. Add an **LLM** node: pick a provider (OpenAI, Anthropic, Google, …) and set your API key.
3. Connect the Chat source's output lane to the LLM's input lane.

The result is a `Chat → LLM` pipeline; the LLM's response routes back to the chat interface
automatically.

## 5. Run it

Press the **<LuPlay className="rr-inline-icon" /> Run button** on the source node, or launch
from the **RocketRide sidebar**. Open the chat interface, send a message, and watch
the LLM respond in real time. Use the **Server Monitor** page to trace call trees, token usage,
and memory consumption.

Save the `.pipe` file, you'll run it from code in the next walkthrough.

## Next

- [Integrate a pipeline with an SDK](/quickstart/sdk-integration): run the `.pipe` file you
  just built from your own Python or TypeScript application.
- [VS Code extension](/clients/vscode): the full extension guide (canvas, runtime
  management, tracing).


---

# Integrate a pipeline with an SDK

Route: /quickstart/sdk-integration

---
title: Integrate a pipeline with an SDK
sidebar_label: Integrate with an SDK
---

# Integrate a pipeline with an SDK

Once you have a `.pipe` file, run it from your own application with the
[Python](/clients/python) or [TypeScript](/clients/typescript) SDK. Both connect to a
running engine, a local server (`ws://localhost:5565`) or RocketRide Cloud
(`https://api.rocketride.ai`), start the pipeline with `use()`, stream data with
`send()`, and stop it with `terminate()`.

If you do not have a `.pipe` file yet, build one first with the
[IDE walkthrough](/quickstart/ide-walkthrough).

## Python

```bash
pip install rocketride
```

```python
import asyncio
from rocketride import RocketRideClient

async def main():
    async with RocketRideClient(uri='ws://localhost:5565', auth='my-key') as client:
        result = await client.use(filepath='my-first-pipeline.pipe')
        token = result['token']
        out = await client.send(token, 'Hello, pipeline!', objinfo={'name': 'input.txt'}, mimetype='text/plain')
        print(out)
        await client.terminate(token)

asyncio.run(main())
```

See the [Python SDK reference](/clients/python) for chat, file uploads, streaming pipes,
events, and persist-mode reconnection.

## TypeScript

```bash
npm install rocketride
```

```typescript
import { RocketRideClient } from 'rocketride';

const client = new RocketRideClient({ uri: 'ws://localhost:5565', auth: process.env.ROCKETRIDE_APIKEY! });
await client.connect();
const { token } = await client.use({ filepath: './my-first-pipeline.pipe' });
const result = await client.send(token, 'Hello, pipeline!', { name: 'input.txt' }, 'text/plain');
console.log(result);
await client.terminate(token);
await client.disconnect();
```

See the [TypeScript SDK reference](/clients/typescript) for chat, file uploads, streaming
pipes, events, and persist-mode reconnection.

## Next

- [Pipeline JSON reference](/reference/pipeline-reference): every field of a `.pipe` file.
- [Troubleshooting](/support/troubleshooting): what to check when a run does not behave.


---

# Understanding RocketRide

Route: /concepts

---
title: Understanding RocketRide
sidebar_label: Understanding RocketRide
---

# Understanding RocketRide

RocketRide has a few moving parts. Once you know how they fit together, the rest
of the docs map cleanly onto them.

## The pipeline

A **pipeline** is a graph of nodes defined in a `.pipe` file (JSON). Data flows between nodes
along typed **data lanes**: a node declares which input lanes it consumes and which output
lanes it produces, and the engine routes data accordingly. See
[Pipelines](/concepts/pipelines) and the [Execution model](/concepts/execution-model).

## Nodes

**[Nodes](/nodes)** are the building blocks: LLM providers, vector stores, embedding models,
preprocessors, OCR/NER, web tools, agents, and sources like Chat. Each node ships a schema
(its config, inputs, and outputs) and runs inside the engine. Connectors are the nodes that
read from and write to external systems. See
[Nodes](/concepts/nodes) and
[Agents & tools](/concepts/agents-tools-skills).

## The runtime engine

Pipelines execute on a multithreaded **C++ engine** (the runtime). It loads the `.pipe`
definition, instantiates the nodes, and streams data through the graph. The same engine runs
locally, on-premises, and on RocketRide Cloud. See [Runtime & engine](/concepts/runtime-engine).

## Talking to the engine

You start and feed pipelines through one of two protocols:

- **[WebSocket](/connect/websocket)**: the native engine protocol (port 5565). The
  [TypeScript](/clients/typescript) and [Python](/clients/python) SDKs speak it for you:
  `use()` to start a pipeline, `send()`/`pipe()` to stream data, `chat()` for conversational
  flows, `terminate()` to stop.
- **[MCP](/connect/mcp/stdio)**: expose a pipeline as a tool for AI assistants like Claude and
  Cursor.

## How you build

- **Visually**: the VS Code [extension](/clients/vscode) opens `.pipe` files on a
  canvas; wire nodes by connecting lanes and press Run.
- **In code**: author or run the same pipeline from your application with the SDKs.
- **As an app**: wrap a pipeline in a UI that runs inside the RocketRide
  shell and deploy it to your team. See [Apps](/concepts/apps).

## Putting it together

A typical flow: author a `.pipe` visually → run it locally to iterate → integrate it into
your app via an SDK → deploy the engine on-prem or to [Cloud](/operate/cloud). The pipeline JSON never
changes across those steps.

See the [Quickstart](/quickstart) walkthroughs to do this end to end.


---

# Agents & Tools

Route: /concepts/agents-tools-skills

---
title: Agents & Tools
sidebar_position: 4
---

# Agents & tools

Most [nodes](/concepts/nodes) pass data along a lane and move on. An
**agent** is different: it reasons in a loop, deciding which model to call,
which tools to use, and when it is done. To do that it needs a few helpers wired
to it: an LLM, optionally tools, and (for some agent types) memory.

## Data lanes vs. control connections

Agents introduce a second kind of wiring alongside data lanes:

- **Data lanes** carry data _into_ and _out of_ the agent, a question arrives
  on an input lane, an answer leaves on an output lane.
- **Control (`invoke`) connections** attach the agent's _capabilities_: the
  LLM it thinks with, the tools it can call, the memory it reads and writes.

See the [Execution model](/concepts/execution-model) for how the two interact.

## Wiring: `control` lives on the helper

The connection between an agent and its helpers is declared on the **helper**,
not on the agent. Each LLM, tool, or memory node carries a `control` array whose
`from` points back at the agent that invokes it. The agent itself has no
`control` array, only its input lanes.

The agent has input lanes only, no `control` array. The LLM declares it is
controlled _by_ the agent, and the tool does likewise:

```json
[
  { "id": "agent_1", "provider": "agent_rocketride",
    "input": [{ "lane": "questions", "from": "chat_1" }] },
  { "id": "llm_1", "provider": "llm_openai",
    "control": [{ "classType": "llm", "from": "agent_1" }] },
  { "id": "tool_1", "provider": "tool_http_request",
    "control": [{ "classType": "tool", "from": "agent_1" }] }
]
```

A single LLM, tool, or memory node can serve several invokers: list each one as
its own entry in the helper's `control` array.

## Tools

A **tool** (class type `tool`) is a capability an agent can invoke at runtime:
an HTTP request, a web search, a shell command, a filesystem or git operation,
another pipeline, and many more. Tools have **no data lanes**: nothing streams
through them. They sit idle until an agent decides to call one, then return a
result to that agent. A tool joins a pipeline purely through its `control`
connection.

## Memory

Some agents keep state across turns through a **memory** node (`memory_internal`
or `memory_persistent`), wired the same way as any other helper.

| Agent              | LLM                  | Memory               | Tools    |
| ------------------ | -------------------- | -------------------- | -------- |
| `agent_rocketride` | Required (exactly 1) | Required (exactly 1) | Optional |
| `agent_crewai`     | Required (min 1)     | Not supported        | Optional |
| `agent_langchain`  | Required (min 1)     | Not supported        | Optional |

Only `agent_rocketride` has a memory port. Do not wire memory to `agent_crewai`
or `agent_langchain`.

## Multi-agent pipelines

An agent can invoke **another agent as a tool**. The sub-agent declares
`control: [{ "classType": "tool", "from": "<parent_agent_id>" }]` and takes no
input lanes of its own, it is driven by its parent. The sub-agent's own
helpers (its LLM and memory) point their `control` at the sub-agent, not at the
parent. This lets you compose specialists under a coordinator.

> The same `invoke`/`control` pattern applies beyond agents, any node whose
> catalog entry declares an `invoke` field (for example `summarization` or
> `extract_data`) is wired to its LLM the same way.

## Next steps

- [Nodes](/nodes): every agent, tool, LLM, and memory
  provider, with its `invoke` requirements.
- [Execution model](/concepts/execution-model): how control connections run
  alongside data lanes.
- [Pipeline JSON reference](/reference/pipeline-reference): the `control` and `invoke`
  fields in full.


---

# Apps

Route: /concepts/apps

---
title: Apps
---

# Apps

A **RocketRide app** is a user interface that runs inside the RocketRide
shell against your engine. The shell provides sign-in, the engine
connection, the workspace, and settings; the app brings the screens and the
pipelines behind them. Apps run in the browser or in a VS Code webview;
the pipelines they start always run on the server.

## Why apps

To a user, an app turns a pipeline's work into a tool a teammate opens,
not a script someone has to run themselves.

To RocketRide, the same engine, node catalog, and deploy path serve both
pipelines and the interfaces built on top of them, and the catalog of apps
is how that work is shared inside an organization.

## Apps and pipelines

A pipeline can belong to an app, or stand beside it. The difference decides who runs it and when.

**Bundled with the app.** The `.pipe` file lives in the app folder and ships with the app. The app starts it when it needs it, for example when the user runs a query, and every signed-in user gets their own instance, automatically. A bundled pipeline is never shared between users and cannot run on a schedule.

**Deployed on its own.** The pipeline is its own project, deployed
separately from the app. One instance serves everyone on the team it is
published to, and it can run on a schedule. The app refers to it by
identity and attaches to whatever is running; it does not start it.

A `.pipe` file outside the app folder is not deployed with the app. If the
app needs it, deploy it separately.

Secrets never ship in either case: pipeline configs carry
`${ROCKETRIDE_*}` placeholders that the server fills from the signed-in
user's stored keys.

## Next steps

- [App Builder](/guides/apps/app-builder): build, preview, and deploy an app.
- [Pipelines](/concepts/pipelines): what the app is running.
- [Shell API](/guides/apps): the hooks and descriptor, when you code by hand.


---

# Execution Model

Route: /concepts/execution-model

---
title: Execution Model
sidebar_position: 5
---

# Execution model

A [pipeline](/concepts/pipelines) describes _what_ to run; the execution model
is _how_ the [engine](/concepts/runtime-engine) runs it. Two mechanisms move
work through the graph: **data lanes** carry data between nodes, and **control
connections** let agents invoke their helpers.

## Data lanes

A **lane** is a typed channel between two nodes. A node declares the lanes it
consumes in its `input` array; the engine routes each output lane to the inputs
that ask for it.

```json
"input": [{ "lane": "questions", "from": "qdrant_1" }]
```

This reads: _take the `questions` lane produced by `qdrant_1` as my input._

### Lane types

Lanes are typed, and the type must match across a connection. This is the
complete lane table: lanes are a closed set fixed by the engine, and a node
only chooses which of them it accepts (see each node's entry in [Nodes](/nodes)):

| Lane        | Carries                          | Accepted by                                              |
| ----------- | -------------------------------- | -------------------------------------------------------- |
| `questions` | Queries flowing toward a model   | LLMs, vector stores (for retrieval), agents              |
| `answers`   | Model responses flowing back     | `response` target, nodes expecting generated text        |
| `documents` | Vector-ready chunks              | Vector store `documents` input                           |
| `text`      | Plain text content               | Preprocessors                                            |
| `tags`      | Structured metadata / parameters | Parsers                                                  |
| `image`     | Image content                    | Vision nodes                                             |
| `audio`     | Audio streams                    | Audio nodes                                              |
| `video`     | Video streams                    | Video nodes                                              |
| `table`     | Structured / tabular data        | Extractors, table-aware preprocessors                    |
| `json`      | JSON payloads                    | `response` target                                        |
| `words`     | Word-level tokens                | Engine-defined; no catalog node consumes it today        |
| `classifications` | Classification results     | Engine-defined; no catalog node consumes it today        |
| `classificationContext` | Context for a classification pass | Engine-defined; no catalog node consumes it today |

### Lane flow rules

- **Type compatibility**: the output lane of one node must match the input lane
  of the next. A `text` output feeds a `text` input; mismatched lanes are a
  pipeline error.
- **Transformation**: many nodes change the lane type. A preprocessor turns
  `text` into `documents` (vector-ready chunks); a text embedding node enriches
  `documents` with vectors for a store (media embedding nodes turn `image`/
  `video` into `documents`); an LLM turns `questions` into `answers`.
- **Fan-in**: a node can consume the same lane from several upstream nodes by
  listing multiple entries in `input`. A `response` node, for example, can merge
  `answers` from several agents.

```json
"input": [
  { "lane": "answers", "from": "agent_rocketride_1" },
  { "lane": "answers", "from": "agent_crewai_1" }
]
```

## Control connections

Data lanes are not the only wiring. Agents (and other nodes with an `invoke`
field) reach their LLM, tools, and memory through **control connections**
instead of lanes, see [Agents & tools](/concepts/agents-tools-skills). Control
connections form a side channel: the engine resolves them at startup so an
agent can call a tool mid-run without that tool ever sitting on a data lane.

## How a run flows

The engine streams; it does not run the graph stage by stage. Once a pipeline
starts:

1. Data enters at a **source** (a `webhook`, a `chat` stream, a file).
2. Each node processes data as it arrives and emits onto its output lanes.
   Independent branches run **concurrently** across threads.
3. Agents loop, calling their LLM and tools over one or more **waves** of
   reasoning, until they produce a result. For `agent_rocketride`, `max_waves`
   caps how many reasoning cycles it may take.
4. Results stream out through a **target** (typically a `response` node) back to
   the client as they are produced.

Because data streams rather than buffering, results can begin returning before
the whole input is consumed, which is what makes conversational `chat()` flows
feel live.

## How the engine parallelises

The engine is written in C++ and runs each pipeline run on its own thread pool.
Concurrent requests to the same pipeline do not queue behind each other —
the engine spawns an independent execution context for each incoming task. A
slow request (a large document going through OCR, embedding, and an LLM call)
does not block a fast one (a short question answered directly by the LLM).

### Streaming execution

Nodes process data **as it arrives**, not after the full upstream output is
available. When a preprocessor splits a 100-page document into 200 chunks, the
embedding node starts embedding chunk 1 while the preprocessor is still
producing chunk 2. The vector store starts upserting while the embedder is
computing later chunks. This keeps memory usage low and reduces end-to-end
latency, especially for large documents.

### Vector store batching

Vector stores (Qdrant, Pinecone, Milvus, Weaviate, etc.) accumulate chunks and
flush them in batches rather than upserting one at a time. A batch flushes when
it reaches either a chunk-count limit or a payload-size limit, whichever comes
first. The exact thresholds are backend-specific: for example, Qdrant flushes at
500 points or its payload limit, while Pinecone and Milvus use different
chunk-count defaults.

For small documents that produce few chunks, the flush happens at pipeline
completion. For large document sets, flushing starts mid-run and reduces peak
memory. Tuning batch size is covered in [Performance](/guides/performance).

Every run is also recorded to a durable run log as it executes — chapters,
traces, and console output you can replay after the run is gone. The
[Observability guide](/guides/observability) covers that side of execution.

## Next steps

- [Agents & tools](/concepts/agents-tools-skills): control connections in
  depth.
- [Nodes](/concepts/nodes): what sits on each lane.
- [WebSocket protocol](/connect/websocket): how clients feed and read a run.
- [Observability](/guides/observability): the run-log DVR, trace levels, and every monitoring surface.
- [Pipeline JSON reference](/reference/pipeline-reference): the `input`, `lane`, and
  `control` fields.


---

# Nodes

Route: /concepts/nodes

---
title: Nodes
sidebar_position: 3
---

# Nodes

A [pipeline](/concepts/pipelines) is a graph, and **nodes** are its vertices.
Every node is one component that does one job: call a model, embed text, query a
vector store, parse a document, run a tool. You assemble nodes into a pipeline;
the [engine](/concepts/runtime-engine) runs them.

## Anatomy of a node

Each node in a `.pipe` file is an object with a stable identity and a behaviour:

- **`id`**: a unique name for this node within the pipeline (e.g. `llm_1`).
- **`provider`**: what the node _is_ (e.g. `llm_openai`, `qdrant`, `webhook`).
  The provider determines the node's behaviour and which lanes it supports.
- **`config`**: provider-specific settings: API keys, model profiles,
  collection names, instructions. Swapping a provider or model is a config edit,
  not a code change.
- **`input`**: the data lanes this node consumes and the nodes they come from.

```json
{ "id": "llm_1", "provider": "llm_openai", "config": { "profile": "openai-5-2" }, "input": [{ "lane": "questions", "from": "qdrant_1" }] }
```

## Class types

Every provider belongs to a **class type** that describes the kind of work it
does. The class type also governs how the node is wired: data nodes connect
through lanes, while `agent`, `tool`, `llm`, and `memory` nodes participate in
control connections (see [Agents & tools](/concepts/agents-tools-skills)).

> source · data · text · image · audio · video · embedding · llm · store ·
> database · graph · tool · agent · memory · guard · rerank · search ·
> infrastructure · target · preprocessor

The list is not exhaustive — new class types are added as the catalog grows.

## Connectors

**Connectors** are the nodes at the edges of the graph, the ones that read from
or write to the world outside the pipeline:

- **Sources** bring data in: a `webhook` that receives a request, a `chat`
  source that streams a conversation, a file or database reader.
- **Targets** send results out: a `response` node that returns data to the
  caller, or a node that writes to a store or external system.

Everything between a source and a target (embedding, retrieval, LLM calls,
preprocessing) transforms data as it flows through.

## Swap providers, keep the pipeline

Because behaviour lives in `provider` + `config`, you can often change _which_
LLM or vector store a pipeline uses without touching its shape — as long as the
new provider has a compatible contract (same class type, supported lanes, and
control connections). Point an `llm` node at a different provider, or repoint a
`store` node at a different collection, and the surrounding graph is unchanged;
swapping to a provider with a different contract can change required config,
lanes, or control connections. Always [validate](/reference/pipeline-reference) the
pipeline after changing a provider.

## The catalog

Every available provider (100+ nodes across 15+ LLM providers, 9 vector
databases, OCR, NER, PII anonymization, transcription, and web tools) is
documented with its config, inputs, and outputs in
**[Nodes](/nodes)**.

## Next steps

- [Nodes](/nodes): every provider and its schema.
- [Agents & tools](/concepts/agents-tools-skills): the control-plane nodes.
- [Execution model](/concepts/execution-model): how lanes carry data between
  nodes.
- [Pipeline JSON reference](/reference/pipeline-reference): every field of a node.


---

# Pipelines

Route: /concepts/pipelines

---
title: Pipelines
sidebar_position: 1
---

# Pipelines

A **pipeline** is the unit of work in RocketRide: a directed graph of components
that move and transform data. Pipelines are authored as `.pipe` files (JSON) and
executed by the engine.

## Components and providers

Each node in the graph is a **component** with a unique `id` and a `provider`
that determines its behaviour (for example `webhook`, `response`, or an LLM
provider). Provider-specific settings live in the component's `config`.

See the [Nodes](/nodes) catalog for every available provider.

## Data lanes vs. invoke connections

Components are wired together two ways:

- **Data lanes**: a typed channel (e.g. `questions` → `answers`) carrying data
  from one component to the next. Declared as input connections.
- **Invoke (control) connections**: a component calls another by class type
  (e.g. an agent invoking an `llm`), rather than streaming data through a lane.

## The `.pipe` JSON shape

A `.pipe` file is JSON conforming to the pipeline schema. The full field-by-field
reference is generated from the schema source and published at
[Pipeline JSON reference](/reference/pipeline-reference).

## Minimal example

```json
{
  "components": [
    { "id": "in", "provider": "webhook", "config": { "mode": "Source" } },
    {
      "id": "out",
      "provider": "response",
      "config": { "lanes": [{ "laneId": "questions", "laneName": "questions" }] },
      "input": [{ "lane": "questions", "from": "in" }]
    }
  ]
}
```

## Next steps

- [Quickstart](/quickstart): run your first pipeline.
- [Pipeline JSON reference](/reference/pipeline-reference): every field.
- [Nodes](/nodes): the component catalog.


---

# Runtime & Engine

Route: /concepts/runtime-engine

---
title: Runtime & Engine
sidebar_position: 2
---

# Runtime & engine

Pipelines don't run themselves. The **engine** is the runtime that loads a
[`.pipe` definition](/concepts/pipelines), brings its nodes to life, and moves
data through the graph until the work is done.

## A multithreaded C++ core

The engine is a native, multithreaded **C++ runtime**, not a thin wrapper
around HTTP calls. It is built for throughput and reliability: nodes that have
no dependency on one another run concurrently, and data streams between them
rather than buffering the whole pipeline in memory. The same binary powers a
quick local iteration loop and a production workload.

## What the engine does

When a pipeline starts, the engine:

1. **Parses** the `.pipe` JSON and validates it against the pipeline schema.
2. **Instantiates** each component from its `provider`, applying the component's
   `config` (API keys, model profiles, collection names, and so on).
3. **Wires** the graph: connecting output [data lanes](/concepts/execution-model)
   to the input lanes that consume them, and resolving control (`invoke`)
   connections between agents and the LLMs, tools, and memory they drive.
4. **Streams** data through the graph, scheduling work across threads and
   emitting results as they are produced.
5. **Tears down** the run when the inputs are exhausted or the client calls
   `terminate()`.

For the full picture of how data and control flow at step 4, see the
[Execution model](/concepts/execution-model).

## One engine, anywhere

The pipeline JSON never changes across environments — only where the engine
lives does: locally behind the [VS Code extension](/clients/vscode) while you
build, self-hosted in your own network, or managed on RocketRide Cloud. See
[Choose How to Run RocketRide](/operate) for the comparison.

## Talking to the engine

You never call the engine's internals directly. Clients connect over one of two
protocols and the engine handles the rest:

- **[WebSocket](/connect/websocket)**: the native engine protocol. The
  [TypeScript](/clients/typescript) and [Python](/clients/python) SDKs speak it
  for you.
- **[MCP](/connect/mcp/stdio)**: exposes running pipelines as tools for AI
  assistants.

As pipelines run, the engine reports call trees, token usage, and memory so you
can observe what happened. See [Troubleshooting](/support/troubleshooting) for reading
that signal.

## Next steps

- [Execution model](/concepts/execution-model): how the engine schedules and
  streams a run.
- [Nodes](/concepts/nodes): the components the engine
  instantiates.
- [Self-hosting](/operate/self-hosting): run the engine in your own infrastructure.


---

# Client Libraries

Route: /clients

---
title: Client Libraries
---

# RocketRide Client Libraries

Official client libraries for the RocketRide Engine. The TypeScript and Python clients communicate with the server over DAP (Debug Adapter Protocol) on WebSocket and offer the same capabilities. The MCP client provides AI assistant integration via the Model Context Protocol. The chat widget embeds a brandable pipeline chat UI in any web page.

---

## Overview

- **Connect** with an API key; optional automatic reconnection (persist mode).
- **Pipelines**: start with `use()`, get a token, then send data via `send()`, `sendFiles()` / `send_files()`, or `pipe()`.
- **Chat** with AI via `chat()` and a `Question` object.
- **Lifecycle**: `onConnected` / `on_connected`, `onDisconnected` / `on_disconnected`, `onConnectError` / `on_connect_error`, `onEvent` / `on_event`.
- **Timeouts**: per-request timeout; optional max retry time for reconnects.

URIs: clients accept `http`/`https` or `ws`/`wss` and convert to WebSocket (`http` to `ws`, `https` to `wss`) when needed.

---

## Client SDK Documentation

| Client         | Package          | Document                                    |
| -------------- | ---------------- | ------------------------------------------- |
| **TypeScript** | `rocketride`     | [TypeScript SDK](/clients/typescript)       |
| **Python**     | `rocketride`     | [Python SDK](/clients/python)               |
| **VS Code**    | `rocketride` (extension) | [VS Code Extension](/clients/vscode) |
| **MCP**        | `rocketride-mcp` | [MCP server](/connect/mcp/stdio)                  |

Each document lists every constructor option, method, type, and usage example for that client.

Both SDK packages also install the [`rocketride` CLI](/connect/cli) — the same
operations from a terminal. The Python package additionally ships the
[OpenTelemetry bridge](/clients/python/otel-bridge) (`rocketride otel`), which
exports live pipeline traces and metrics over OTLP.

---

## Installation

### From PyPI / npm (public registry)

```bash
# TypeScript
npm install rocketride

# Python
pip install rocketride

# MCP
pip install rocketride-mcp
```

The chat widget is **not on a public registry yet**; build it from this repository and self-host the bundle:

```bash
./builder chat-widget:build   # -> packages/chat-widget/dist/rocketride-chat.js
```

See the [chat widget README](https://github.com/rocketride-org/rocketride-server/blob/develop/docs/public/chat-widget/README.md#getting-the-bundle) for the embed snippets and for what changes once `rocketride-chat-widget` is published.

### From the Engine (self-hosted download)

The engine serves the latest client packages via HTTP endpoints. Once the server is running, download them directly:

| Endpoint                        | Package                | Response                                |
| ------------------------------- | ---------------------- | --------------------------------------- |
| `GET /client/python/{filename}` | Python SDK wheel (curl: use `latest`) | `rocketride-{version}-py3-none-any.whl` |
| `GET /client/typescript`        | TypeScript SDK tarball | `rocketride-{version}.tgz`              |
| `GET /client/vscode`            | VSCode extension       | `rocketride-{version}.vsix`             |
| `GET /client/shell`             | Shell platform package | `shell.tgz`                             |
| `GET /client/docs`              | Agent docs bundle      | `docs.zip` (docs + stubs + manifest)    |

```bash
# Download and install Python client (use "latest" as filename for newest version)
curl -o rocketride-latest.whl http://localhost:5565/client/python/latest
pip install rocketride-latest.whl

# Download and install TypeScript client
curl -O http://localhost:5565/client/typescript
npm install rocketride-*.tgz

# Download and install VSCode extension
curl -O http://localhost:5565/client/vscode
code --install-extension rocketride-*.vsix
```

These endpoints are public (no authentication required) and automatically serve the latest version. Returns 404 with a JSON error if packages are not found.

All `/client/*` responses carry `Cache-Control: no-cache` so HTTP caches
revalidate instead of serving stale artifacts after a server upgrade.

The agent docs bundle is what `rocketride init` and the VS Code extension
install into a workspace's `.rocketride/docs/` — its `manifest.json` carries a
content hash consumers use as their change stamp, so an unchanged bundle is a
no-op to re-install.

The recommended workspace bootstrap, per language:

```bash
# TypeScript — the init shim, served by the server itself. No arguments
# needed: the shim reads the server from its own install URL, downloads
# that server's client into .rocketride/client/rocketride.tgz, installs
# it as a content-hashed file: dependency, and runs `rocketride init`.
pnpm install http://localhost:5565/client/typescript-init
pnpm exec typescript-init

# Python — install the server's wheel by its concrete filename (pip
# requires the .whl name in the URL), then init:
pip install http://localhost:5565/client/python/rocketride-1.3.0-py3-none-any.whl
rocketride init
```

Once the `rocketride` package is published to npmjs/PyPI, the public
bootstrap is simply `pnpm add rocketride` / `pip install rocketride`
followed by `rocketride init`; the forms above remain the self-hosted
path. Re-running `typescript-init` / `rocketride init` is the update
path — the client and workspace refresh against the connected server.

Two direct-URL forms to avoid, both verified broken:

- `pnpm add http://.../client/typescript` — pnpm caches URL tarballs by
  URL and NEVER refetches, so after a server upgrade it silently
  reinstalls the old cached build. The shim's `file:` dependency is
  hashed by content, so a rebuilt server package always installs. (The
  shim itself is safe to cache — it is tiny, stable, and carries no
  server-versioned content.)
- `pip install http://.../client/python/latest` — pip rejects URLs
  without a recognizable archive filename ("neither 'setup.py' nor
  'pyproject.toml' found"). The `/latest` route is for curl/scripting
  only; pip installs use the concrete wheel filename.

---

## License

MIT License -- see [LICENSE](https://github.com/rocketride-org/rocketride-server/blob/develop/LICENSE).


---

# Python SDK

Route: /clients/python

---
title: Python SDK
sidebar_position: 0
sidebar_label: Overview
---

import { LuSettings, LuPlug, LuPlay, LuRocket, LuSend, LuFolderOpen, LuMessageSquare, LuActivity, LuShieldAlert, LuBookOpen, LuFlaskConical, LuChartLine, LuRadar } from 'react-icons/lu';

# Python SDK

Build, run, and manage AI pipelines from Python. The `rocketride` package is
async-first — built on `asyncio` and `websockets` — and speaks the engine's native
[WebSocket protocol](/connect/websocket): you author a `.pipe`
([visually](/clients/vscode) or [by hand](/reference/pipeline-reference)) and run it
against the engine from your own application.

## Install

```bash
pip install rocketride
```

Python 3.10+. The [`rocketride` CLI](/connect/cli) is installed with the package.

## Quickstart

```python
import asyncio
from rocketride import RocketRideClient


async def main():
    async with RocketRideClient(uri='https://api.rocketride.ai', auth='my-key') as client:
        result = await client.use(filepath='pipeline.pipe')
        token = result['token']
        out = await client.send(token, 'Hello, pipeline!', objinfo={'name': 'input.txt'}, mimetype='text/plain')
        print(out)
        await client.terminate(token)


asyncio.run(main())
```

`send()` / `send_files()` target pipelines whose **source** is `webhook` or
`dropper`; if your pipeline source is `chat`, use
[`client.chat()`](/clients/python/chat). No pipeline yet? The
[IDE walkthrough](/quickstart/ide-walkthrough) builds one in minutes.

## Explore the SDK

<div className="rr-card-grid">

<a className="rr-side-card" href="/clients/python/configuration">
  <span className="rr-side-card__head"><LuSettings className="rr-card-icon" /><span className="rr-side-card__title">Configuration</span></span>
  <span className="rr-side-card__body">Constructor options, environment variables, timeouts, and reconnection.</span>
</a>

<a className="rr-side-card" href="/clients/python/connection">
  <span className="rr-side-card__head"><LuPlug className="rr-card-icon" /><span className="rr-side-card__title">Connection</span></span>
  <span className="rr-side-card__body">The attach/login layers, context manager, persist mode, and lifecycle callbacks.</span>
</a>

<a className="rr-side-card" href="/clients/python/pipelines">
  <span className="rr-side-card__head"><LuPlay className="rr-card-icon" /><span className="rr-side-card__title">Running Pipelines</span></span>
  <span className="rr-side-card__body">Start with <code>use()</code>, watch progress, validate, and terminate.</span>
</a>

<a className="rr-side-card" href="/clients/python/deploy">
  <span className="rr-side-card__head"><LuRocket className="rr-card-icon" /><span className="rr-side-card__title">Deployments</span></span>
  <span className="rr-side-card__body">Publish immutable versions, point team environments at them, and schedule runs.</span>
</a>

<a className="rr-side-card" href="/clients/python/data">
  <span className="rr-side-card__head"><LuSend className="rr-card-icon" /><span className="rr-side-card__title">Sending Data</span></span>
  <span className="rr-side-card__body">One-shot sends, concurrent file uploads with progress, and chunked streaming.</span>
</a>

<a className="rr-side-card" href="/clients/python/storage">
  <span className="rr-side-card__head"><LuFolderOpen className="rr-card-icon" /><span className="rr-side-card__title">File Storage</span></span>
  <span className="rr-side-card__body">Read, write, and manage your server-side store; signed URLs for direct access.</span>
</a>

<a className="rr-side-card" href="/clients/python/chat">
  <span className="rr-side-card__head"><LuMessageSquare className="rr-card-icon" /><span className="rr-side-card__title">Chat</span></span>
  <span className="rr-side-card__body">Build a <code>Question</code>, stream the response, parse it with <code>Answer</code>.</span>
</a>

<a className="rr-side-card" href="/clients/python/logs">
  <span className="rr-side-card__head"><LuActivity className="rr-card-icon" /><span className="rr-side-card__title">Run Logs</span></span>
  <span className="rr-side-card__body">The log continuum and the DVR session: live monitoring and replay with one API.</span>
</a>

<a className="rr-side-card" href="/clients/python/errors">
  <span className="rr-side-card__head"><LuShieldAlert className="rr-card-icon" /><span className="rr-side-card__title">Error Handling</span></span>
  <span className="rr-side-card__body">What the SDK raises, when, and how to catch it.</span>
</a>

<a className="rr-side-card" href="/clients/python/reference">
  <span className="rr-side-card__head"><LuBookOpen className="rr-card-icon" /><span className="rr-side-card__title">API Reference</span></span>
  <span className="rr-side-card__body">Every public class and method, in one place.</span>
</a>

<a className="rr-side-card" href="/clients/python/examples">
  <span className="rr-side-card__head"><LuFlaskConical className="rr-card-icon" /><span className="rr-side-card__title">Examples</span></span>
  <span className="rr-side-card__body">Seven complete programs, from hello-pipeline to custom DAP requests.</span>
</a>

<a className="rr-side-card" href="/clients/python/analytics">
  <span className="rr-side-card__head"><LuChartLine className="rr-card-icon" /><span className="rr-side-card__title">Analytics</span></span>
  <span className="rr-side-card__body">Report client-side analytics events through the SDK.</span>
</a>

<a className="rr-side-card" href="/clients/python/otel-bridge">
  <span className="rr-side-card__head"><LuRadar className="rr-card-icon" /><span className="rr-side-card__title">OpenTelemetry Bridge</span></span>
  <span className="rr-side-card__body">Export live pipeline traces and metrics over OTLP with <code>rocketride otel</code>.</span>
</a>

</div>

## Links

- [GitHub](https://github.com/rocketride-org/rocketride-server) · [PyPI](https://pypi.org/project/rocketride/) · [Discord](https://discord.gg/PMXrtenMsY)
- [Release notes](/support/release-notes) · [Get help](/support/get-help)


---

# Analytics

Route: /clients/python/analytics

---
title: Analytics
sidebar_position: 12
---

- [Overview](#overview)
- [Import](#import)
- [API](#api)
- [Event Names](#event-names)
- [What This Module Is Not](#what-this-module-is-not)

## **Overview**

`rocketride.analytics` is the one shared event-report function, bare bones by
design. Apps call ``report(event, props)`` with any string event name and a
free-form props dict. There is no central event list: **each app owns its own
taxonomy**. What the shared layer guarantees is that every reported event
carries an ``app`` property identifying the emitting app (``home-ui``,
``rocket-ui``, …), so downstream analytics can always segment by app. The
TypeScript mirror lives at ``rocketride/analytics`` in the TypeScript SDK.

## **Import**

```python
from rocketride.analytics import init_report, report
```

## **API**

```python
# Once, at app init: wire the emitting app id + transport. The sink is
# whatever callable your app uses to ship events (HTTP, queue, logger, ...).
init_report('rocket-ui', lambda event, props: my_sink.send(event, props))

# Anywhere after that:
report('pipeline:run', {'node_count': 4})
# → sink receives ('pipeline:run', {'app': 'rocket-ui', 'node_count': 4})
```

- ``init_report(app, sink)`` — stores the app id and transport. Call once per app.
- ``report(event, props=None)`` — forwards to the sink with ``app`` stamped into
  the props. Enforcement is string-ish only: a non-string or empty event name is
  a silent no-op, and nothing else is validated. Before ``init_report`` runs it
  is a safe no-op. It never raises — telemetry must never break the app.

## **Event Names**

By convention event names are ``object:action`` — lowercase, colon-separated
(``pipeline:run``, ``store:app_add``). The convention is documentation, not
enforcement: ``report()`` accepts any string so an app can evolve its taxonomy
without touching this module. Each app should keep its own documented event
list next to its call sites.

## **What This Module Is Not**

It is not a taxonomy and not a transport. There is no event-name ``Literal``
union, no typed property shapes, and no network I/O — the sink an app injects
does the sending. An earlier revision centralised a strict cross-app event
taxonomy here; that was removed in favour of per-app taxonomies and this loose
core.


---

# Chat

Route: /clients/python/chat

---
title: Chat
sidebar_position: 7
---

# Chat

Conversational pipelines: build a `Question`, send it with `client.chat()`, and
parse the response with `Answer`. Class tables in the
[API reference](/clients/python/reference#question).

Chat is the conversational lane: it works against `chat`, `webhook`, and
`dropper` pipeline sources. Under the hood the
client opens a pipe with MIME type `application/rocketride-question`, writes the
serialized `Question`,
closes the pipe, and returns the server result.

## Build a Question

```python
from rocketride.schema import Question

question = Question(expectJson=True)
question.addInstruction('Format', 'Return a JSON object with keys: summary, keywords.')
question.addExample('Summarize X', {'summary': '...', 'keywords': ['a', 'b']})
question.addQuestion('Summarize the main points and list keywords.')
```

`Question(type=QuestionType.QUESTION, filter=DocFilter(), expectJson=False, role='')` —
`QuestionType` is one of `QUESTION`, `SEMANTIC`, `KEYWORD`, `GET`, `PROMPT`. Steer
the model with `addInstruction`, `addExample`, `addContext`, `addHistory` (for
multi-turn), `addDocuments`, `addGoal`, and `addQuestion`.

## Send it

```python
response = await client.chat(token=token, question=question)
```

`chat(*, token, question, on_sse=None)` is keyword-only; the optional `on_sse`
callback streams server-sent events (token-by-token output) as they arrive. The
final answer is in the result body.

## Parse the response with Answer

`Answer` extracts structure from AI text, which often arrives wrapped in markdown or
code fences. The client does **not** attach an `Answer` to the result — you read the
body and feed it in:

```python
from rocketride.schema import Answer

answer_text = (response.get('answers') or [None])[0]
answer = Answer(expectJson=True)
answer.setAnswer(answer_text or '')
if answer.isJson():
    structured = answer.getJson()
else:
    structured = answer.getText()
```

Semantics worth knowing:

- `setAnswer(value)` stores the response, validating/parsing it as JSON when
  `expectJson` is `True`.
- `isJson()` returns the `expectJson` flag — it does **not** inspect the content.
- `getJson()` returns the parsed JSON; it returns `None` only when no answer has
  been set, and **raises `ValueError`** if the stored answer is not valid JSON.
- `getText()` returns the answer as plain text; `parsePython(value)` extracts Python
  code from a code block.
- `answer.tokens` carries the turn-total LLM token usage reported by the server.

A complete chat program is [example 6](/clients/python/examples#6-chat-question-with-instructions-and-examples-parse-json-answer).


---

# Configuration

Route: /clients/python/configuration

---
title: Configuration
sidebar_position: 1
---

# Configuration

Everything the `RocketRideClient` constructor accepts, the environment variables it
reads, and how its timeouts, reconnection, and debug hooks behave.

## Constructor

```python
from rocketride import RocketRideClient

client = RocketRideClient(
    uri='https://api.rocketride.ai',
    auth='my-key',
    persist=True,
)
```

| Argument | Type | Default | Description |
| --- | --- | --- | --- |
| `uri` | `str` | RocketRide Cloud (`https://api.rocketride.ai`) | Server URI. Falls back to `ROCKETRIDE_URI` from the environment, then to the Cloud endpoint. See [URI scheme](/clients/python/connection#uri-scheme). |
| `auth` | `str` | `None` | API key. Falls back to `ROCKETRIDE_APIKEY`. Omitting it leaves the client unauthenticated until [`connect(credential)`](/clients/python/connection) or `login()` supplies one. |
| `env` | `dict` | — | Override the environment map used for `${ROCKETRIDE_*}` substitution and credential lookup. If omitted, the client copies `os.environ` and then merges `.env` underneath it — **process environment wins** over `.env` values. |
| `module` | `str` | `CLIENT-0`, `CLIENT-1`, … | Client name for logging. |
| `request_timeout` | `float` | — | Default timeout in **ms** for DAP requests. Prevents a single call from hanging. |
| `max_retry_time` | `float` | — | Deprecated: accepted but **ignored** — reconnection never gives up. See [Reconnection](#reconnection). |
| `persist` | `bool` | `False` | Automatic reconnection. Set `True` for long-lived scripts or UIs. See [Reconnection](#reconnection). |
| `public` | `bool` | `False` | Reserved: declared but not currently consumed by the client. For unauthenticated public calls, [`attach()`](/clients/python/connection) without logging in. |
| `ws_path` | `str` | `'/task/service'` | WebSocket path override. Model-server clients pass `'/models'`. |
| `client_name` | `str` | `'Python SDK'` | Display name reported to the server. |
| `client_version` | `str` | package version | Display version reported to the server. |

There is no "missing uri/auth" error at construction time: an empty `uri` resolves to
RocketRide Cloud and an empty `auth` stays `None`. The only constructor-time
`ValueError` is a URI with no hostname.

## Callbacks

All lifecycle callbacks are **awaited** — pass `async` functions (a plain `lambda`
raises `TypeError` when the client awaits it).

| Argument | Called | Description |
| --- | --- | --- |
| `on_event` | per server event | Receives each event `dict`. Subscribe per-task with [`add_monitor`](/clients/python/pipelines#events). |
| `on_connected` | connection established | Receives connection info. |
| `on_disconnected` | connection lost **after** being connected | Args: `reason`, `has_error`. Do not call `disconnect()` here if you want auto-reconnect. |
| `on_connect_error` | each failed **reconnect** attempt (persist mode) | Args: `message: str`. An initial `connect()` failure raises to the caller instead. On auth failure the client stops retrying. |
| `on_protocol_message` | per raw DAP message | Plain callable; for protocol debugging. |
| `on_debug_message` | per debug line | Plain callable; for debug output. |
| `on_trace` | around high-level SDK requests | Plain callable (NOT awaited): `(type, message)`. Unlike the TypeScript `onTrace`, the message is not credential-redacted. |

```python
async def handle_event(event):
    print(event.get('event'), event.get('body'))


async def handle_connect_error(message):
    print('Connect error:', message)


client = RocketRideClient(
    uri='https://api.rocketride.ai',
    auth='my-key',
    persist=True,
    on_event=handle_event,
    on_connect_error=handle_connect_error,
)
```

## Reconnection

With `persist=True` the client reconnects with **linear backoff**: the delay grows by
0.25 s per consecutive failure, capped at 15 s, and reconnection **never gives up** —
`on_connect_error` fires on each failed attempt so you can surface "still
connecting…" in a UI. The one exception is an authentication failure: the client
stops retrying so the app can fix credentials and call `connect()` again.

`max_retry_time` is accepted for backward compatibility but **ignored**.

## Environment variables

| Variable | Description |
| --- | --- |
| `ROCKETRIDE_URI` | Server URI (e.g. `wss://api.rocketride.ai` or `ws://localhost:5565`) |
| `ROCKETRIDE_APIKEY` | API key for authentication |
| `ROCKETRIDE_TOKEN` | User token, accepted by the [CLI](/connect/cli) as an alternative credential |

The same map drives `${ROCKETRIDE_*}` substitution inside pipeline configs: the raw
pipeline is sent to the server, which resolves variables from its merged environment.

## Timeouts

`request_timeout` (constructor) sets the default for every DAP request;
[`request(..., timeout=...)`](/clients/python/reference#advanced-low-level-dap) overrides it
per call. [`connect(timeout=...)`](/clients/python/connection) bounds the connect +
auth handshake in non-persist mode. All timeouts are in milliseconds.


---

# Connection

Route: /clients/python/connection

---
title: Connection
sidebar_position: 2
---

# Connection

How the client attaches, authenticates, stays connected, and shuts down. The full
method tables live in the [API reference](/clients/python/reference#connection).

## The layered model

The connection has two layers you can drive together or separately:

- **Attach** opens the WebSocket without authenticating — enough for public
  operations like catalog browsing.
- **Login** performs the DAP auth handshake over an attached transport and returns a
  `ConnectResult` carrying your full identity (user, organizations, apps, teams).

`connect()` does both in one call; `disconnect()` logs out and detaches. The state
probes mirror the layers: `is_attached()` (socket open) and `is_authenticated()`
(auth handshake succeeded). `is_connected()` is a backward-compatible alias with
the same meaning as `is_attached()` — it does **not** imply authentication.

```python
result = await client.connect()  # attach + login
print(result['displayName'])

await client.logout()  # drop auth, keep the socket
await client.login('other-credential')  # re-auth on the same connection
await client.detach()  # tear down the socket
```

Calling `login()` with a different credential logs out first (best-effort); with the
same credential it is a no-op. `attach()` to a different URI detaches and
re-attaches.

## Context manager (recommended)

`async with` guarantees the connection closes even on exception — entering calls
`connect()`, exiting calls `disconnect()`:

```python
async with RocketRideClient(uri='wss://api.rocketride.ai', auth=os.environ['ROCKETRIDE_APIKEY']) as client:
    result = await client.use(filepath='pipeline.pipe')
    await client.send(result['token'], 'Hello, pipeline!')
```

> TypeScript's counterparts to the context manager are
> [`withConnection()` and `await using`](/clients/typescript/connection#scoped-disconnect).

## URI scheme

The scheme selects the transport. The client normalizes the `uri` to a WebSocket
address before connecting: `https://` and `wss://` both resolve to a secure `wss://`
connection, while `http://`, `ws://`, and a bare `host:port` resolve to plain
`ws://`. For RocketRide Cloud use `https://api.rocketride.ai` (or the equivalent
`wss://api.rocketride.ai`); for a local engine use `ws://localhost:5565`.

**Caution:** against a Cloud endpoint always use `https://` or `wss://` — an
`http://` or `ws://` URI (or a bare `host:port`) silently downgrades to an
unencrypted `ws://` connection.

## Staying connected

With `persist=True` the client survives drops: it reconnects with linear backoff
(+0.25 s per failure, 15 s cap) and never gives up, except on auth failure. Wire the
[lifecycle callbacks](/clients/python/configuration#callbacks) to observe it:

```python
async def on_connected(info):
    print('Connected:', info)


async def on_disconnected(reason, has_error):
    # Fires only after a successful connection drops.
    # Do NOT call disconnect() here if you want auto-reconnect.
    print('Disconnected:', reason, has_error)


async def on_connect_error(message):
    # Fires on each failed RECONNECT attempt; an initial connect() failure
    # raises to the caller instead.
    print('Connect error:', message)


client = RocketRideClient(
    uri='https://api.rocketride.ai',
    auth='my-key',
    persist=True,
    on_connected=on_connected,
    on_disconnected=on_disconnected,
    on_connect_error=on_connect_error,
)
await client.connect()
```

Use `on_disconnected` for "we were connected and then dropped"; use
`on_connect_error` for "failed to connect".

## Inspecting state

`get_connection_info()` returns `{'connected': bool, 'transport': str, 'uri': str}`
— useful for a "Connected to …" display. `get_apikey()` returns the key in use
(debugging only; avoid logging it). `set_env()` replaces the client's environment
map used for `${ROCKETRIDE_*}` substitution and credential lookup.


---

# Sending Data

Route: /clients/python/data

---
title: Sending Data
sidebar_position: 5
---

# Sending Data

Get data into a running pipeline: one-shot sends, file uploads with progress, and
chunked streaming. Method tables in the
[API reference](/clients/python/reference#data).

`send()` / `send_files()` / `pipe()` target pipelines whose **source** is `webhook`
or `dropper`. If your pipeline source is `chat`, use
[`client.chat()`](/clients/python/chat) instead.

## One-shot: `send()`

Use when you have the full payload in memory. It opens a pipe, writes once, closes,
and returns the pipeline result:

```python
result = await client.send(token, 'Hello, pipeline!', objinfo={'name': 'greeting.txt'}, mimetype='text/plain')
```

If `mimetype` is omitted the payload is sent as `application/octet-stream` — there
is no auto-detection. An optional `on_sse` callback receives server-sent events for
the transfer.

## Files: `send_files()`

Uploads a list of files concurrently (all at once via `asyncio.gather`) and returns
one `UPLOAD_RESULT` per file. Each entry is a path `str`, a `(path, objinfo)` tuple,
or a `(path, objinfo, mimetype)` tuple:

```python
files = ['doc1.md', 'doc2.md', ('doc3.json', {'tag': 'export'}, 'application/json')]
upload_results = await client.send_files(files, token)
for r in upload_results:
    if r['action'] == 'complete':
        print('OK', r['filepath'])
    else:
        print('Failed', r['filepath'], r.get('error'))
```

Two things to know:

- `send_files` **requires an API key** on the client (it raises `RuntimeError`
  without one).
- A missing file raises `ValueError` (`'File not found: …'`).

Watch progress by subscribing to `apaevt_status_upload` events
([Events](/clients/python/pipelines#events)) — bodies carry `filepath`,
`bytes_sent`, `file_size`.

## Streaming: `pipe()`

Use `pipe()` when data arrives incrementally or is too large to hold in memory. One
streaming upload is **open → write (one or more) → close**; `close()` returns the
processing result. The pipe reads files best in ~1 MB chunks and enforces `bytes`
payloads.

```python
pipe = await client.pipe(token, objinfo={'name': 'large.csv'}, mime_type='text/csv')
await pipe.open()
with open('large.csv', 'rb') as f:
    while True:
        chunk = f.read(64 * 1024)
        if not chunk:
            break
        await pipe.write(chunk)
result = await pipe.close()
```

`DataPipe` is also an async context manager — entering calls `open()`, exiting calls
`close()`:

```python
async with await client.pipe(token, mime_type='application/json') as pipe:
    await pipe.write(b'{"key": "value1"}')
    await pipe.write(b'{"key": "value2"}')
```

Properties: `is_opened` and `pipe_id` (server-assigned after `open()`). `pipe()` and
the pipe itself accept an `on_sse` callback for server-sent events, and
`DataPipe.tool()` invokes a pipeline tool function through the pipe — see the
[reference](/clients/python/reference#datapipe).

## Choosing

| You have | Use |
| --- | --- |
| A string or bytes in memory | `send()` |
| Files on disk, want per-file results + progress events | `send_files()` |
| Chunked/incremental data, or very large payloads | `pipe()` |
| A chat-source pipeline | [`chat()`](/clients/python/chat) |


---

# Deployments

Route: /clients/python/deploy

---
title: Deployments
sidebar_position: 4
---

# Deployments

Persist pipelines server-side and run them on a schedule. Accessed via
`client.deploy`; full method tables in the
[API reference](/clients/python/reference#deploy-clientdeploy).

## Teams as environments

`deploy.add` snapshots a pipeline as an **immutable, sha256-locked artifact
version** in the org registry; `deploy.deploy` points a **team** (the environment —
Staging, Production, …) at a version. Promotion and rollback are the same pointer
move. Deploy targets are always explicit — there is no default-team fallback. Every
registry add and pointer change lands in an immutable audit history
(`deploy.history`, rows carry `seq` as the stable append-order identity).

```python
result = await client.deploy.add(my_pipeline, comment='v2 prompt fix')
await client.deploy.deploy('proj-1', result['artifact']['version'], 'team-staging')
await client.deploy.set_schedule('proj-1', 'webhook_1', '*/15 * * * *', 'team-staging')

# Promote the same version to Production later — the identical gesture.
await client.deploy.deploy('proj-1', result['artifact']['version'], 'team-prod')

live = await client.deploy.list()
for dep in live['rows']:
    print(dep['teamId'], dep['projectId'], 'v', dep['version'], dep['state'])
```

`add(..., deploy_to=<team>)` collapses add + deploy into one step. Listings
(`deploy.list`, `deploy.versions`, `deploy.history`) return the standard
`{rows, total, page, pageSize}` envelope, server-paged.
`deploy.artifact(project_id, version)` fetches one immutable version's pipeline
JSON, sha256-verified server-side.

## Schedules

`deploy.set_schedule(project_id, source_id, schedule, team_id, ttl=None)` sets (or
clears with `None`/`'manual'`) one source's 5-field cron schedule.
`pause_schedule`/`resume_schedule` stop and restart a single source's firing without
touching its cron. `deploy.preview(schedule, count=None)` is **the** single cron
evaluator — validity plus next occurrences; never parse cron client-side.

Scheduled runs execute **as the team** (no stored user credential); their logs land
in the team's [run-log continuum](/clients/python/logs), readable by teammates via
`client.log` with `team_id`. `deploy.run(project_id, source_id, team_id)` triggers
one deployed source **now** — the same trusted, actor-free team dispatch the
scheduler uses — returning `{token, version}`, and `deploy.set_source_config` sets
per-source execution settings for deploy runs (trace level, debug output).

## States

| State | Meaning |
| --- | --- |
| `enabled` | Schedules fire per cron. |
| `disabled` | The kill switch (`deploy.disable`) — nothing runs until enabled again. |
| `errored` | A scheduled dispatch failed — on permissions, or on an unusable artifact (missing or sha256-tampered) — and the scheduler stopped retrying. |
| `removed` | Soft delete (`deploy.remove`): hidden from listings, history and artifacts survive; re-deploying revives it. |

## Permissions

Mutations require `task.control` on the TARGET team. Reads follow the visibility model: an org admin sees every team and every personal space; a user sees their own personal space and the teams they are a member of.

## App publish ladder

Typed wrappers over `rrext_deploy_app` — the publish ladder for RocketRide apps.
**Deploy** copies code to the server as the next immutable registry version
(`client.deploy.add`); a deployment carries the review lifecycle in its own `state`
(`private` → `submit` → `ready` | `rejected`). **Publish** binds a deployment to
an audience — `@me`, `@team/<name>`, or `@public` — as a pure pointer (`@user` is a legacy input alias for `@me`, never displayed);
repointing it covers first publish, update, promote, and rollback alike.

The review state lives on the **deployment**, not the binding: an app deploys
`private`, the developer `submit`s it, an admin approves (`ready`) or rejects
(`rejected`). A `@public` binding may only point at a `ready` deployment;
`@me`/`@team` accept any non-`failed` deployment.

App ids are partitioned by the caller org's **developer id**: every app is
`<developerId>.<name>` (globally unique), so an org can only deploy/publish
ids inside its own namespace (the platform holds `rocketride`). Deploying or
publishing an app requires the org to have claimed a developer id.

`deploy.add` and `deploy.add_app` live on `client.deploy`; every other verb
below is a method on the client itself (`client.list_deployments(...)`,
`client.publish_app(...)`), not on `client.deploy`.

| Method | Description |
| --- | --- |
| `deploy.add` | The ONE rail door (on the `client.deploy` namespace): deploy any kind of object as the next immutable registry version. `kind='pipe'` (default) takes a `pipeline` dict; `kind='app'` takes ONE `data` zip of the app's SOURCE (the server performs the build; client-produced binaries are never trusted), retained and unpacked at receipt, born deployment-state `private`. The app id must be inside your developer namespace. |
| `deploy.add_app` | Pack an app folder's source and deploy it as the next registry version — the one call behind the App Builder's Deploy button and CI scripts. Packs by the App Builder rules (workspace-rooted zip, `appManifest.include`, hierarchical gitignore + the hard node_modules/dist/.git baseline, symlink containment, 50MB zipped / 512MB uncompressed caps); `on_progress` narrates one line per step. Deploying activates nothing — bind an audience with `publish_app` afterwards. |
| `deploy.verify_app` | The no-side-effect precheck for `add_app` — purely local, no server call: manifest shape and id grammar, declared icon/README assets, `appManifest.include` entries, and a pack dry run against the size caps. Server-side concerns (the build, store review) are out of scope. |
| `list_deployments` | The version rail, newest first — the developer org sees its FULL rail (published or not), other callers only their visible versions. Each entry carries its deployment `state`, its `buildStatus` ('ok' = servable), and the `rungs` naming the audiences bound to it. |
| `submit_app` | Submit a deployed version for review — flips the deployment `private` → `submit`. |
| `withdraw_app` | Withdraw a pending review — the developer's own cancel: flips the deployment `submit` → `private`, the version leaves the admin queue and history records `withdrawn`. Only a version in `submit` withdraws. Developer-org + namespace gated, like submit. |
| `reply_app` | Append a developer message to the app's review thread — rides `deployment_history` as a `reply` row (side `'developer'`), the same stream `deploy.history()` reads. Developer-org + namespace gated, like submit. |
| `build_log` | One version's durable server build log — the full phase-by-phase output stored beside the version's artifacts (no error text rides the rail rows). Long logs serve their tail; empty `log` = none. Developer-org gated. |
| `publish_app` | Bind a deployment to '@me', '@team/<name>', or '@public' ('@user' = legacy input alias). The binding is a pure pointer born 'enabled'. '@public' requires the deployment be `ready`; '@me'/'@team' accept any non-`failed` deployment. Pinning ANOTHER org's public app to '@me'/'@team' is the version selector; publishing your own app requires the id to be in your namespace. |
| `where_app` | The reverse index: `{rung, handle, version, appVersion, state, deployedAt}` per audience — `state` is the bound deployment's review state. |

Serving needs no verb: a version's bundle loads from the stable
`/apps/<app_id>/v<N>/remoteEntry.js` URL constructed from its registry
version number, with entitlement enforced by the serve route on every
request (registry ints ONLY — semver is display).

Full signatures: [API reference](/clients/python/reference#app-publish-ladder).

See the [Shell API guide](/guides/apps) for the app model itself.


---

# Error Handling

Route: /clients/python/errors

---
title: Error Handling
sidebar_position: 9
---

# Error Handling

What the SDK raises, when, and how to catch it.

## What actually raises

| Situation | Raised |
| --- | --- |
| Bad API key / credentials during connect or login | `AuthenticationException` |
| Connection and transport failures | builtin `ConnectionError` (timeouts: `asyncio.TimeoutError`) |
| Data-pipe errors (open / write / close) | `PipeException` |
| `use()` argument problems (neither `filepath` nor `pipeline`; both; bad types) | `ValueError` |
| `use()` with a missing pipeline file | `FileNotFoundError` |
| Server rejects a pipeline start or a DAP request | `RuntimeError` |
| `get_service('')` / unknown service name | `ValueError` / `RuntimeError` |
| `send_files` without an API key, or a missing file | `RuntimeError` / `ValueError` |
| `Answer.getJson()` on non-JSON content | `ValueError` |

```python
from rocketride import RocketRideClient, AuthenticationException
from rocketride.core.exceptions import PipeException

try:
    async with RocketRideClient(uri=uri, auth=auth) as client:
        result = await client.use(filepath='pipeline.pipe')
        await client.send(result['token'], data)
except AuthenticationException:
    print('Bad credentials')
except (ValueError, FileNotFoundError) as e:
    print(f'Bad pipeline arguments: {e}')
except PipeException as e:
    print(f'Data transfer error: {e}')
except ConnectionError as e:
    print(f'Transport failure: {e}')
except RuntimeError as e:
    print(f'Server rejected the request: {e}')
```

`AuthenticationException` is raised on DAP auth failure. In
[persist mode](/clients/python/configuration#reconnection) the client catches it,
calls `on_connect_error`, and does **not** retry — fix credentials and call
`connect()` again.

## The hierarchy

```text
DAPException                    # Base DAP protocol error (has dap_result dict)
└── RocketRideException         # Base for all RocketRide errors
    ├── ConnectionException     # Reserved: transport failures raise builtin ConnectionError
    │   └── AuthenticationException  # Bad API key or credentials (actively raised)
    ├── PipeException           # Data pipe errors (also subclasses RuntimeError)
    ├── ExecutionException      # Reserved: defined but not currently raised
    └── ValidationException     # Reserved: defined but not currently raised
```

All exceptions in the hierarchy expose a `dap_result` dict with detailed server
error context, plus `code` and `hint`:

- `code` is the server's machine-readable classification, or `None`. Task
  failures carry one: `TASK_NOT_REGISTERED` (the token names no live task —
  never started, terminated, replaced, or the engine restarted),
  `TASK_AMBIGUOUS`, `TASK_COMPLETED`, `TASK_STOPPED`. **Classify on `code`, not
  on the message text**, which is written for people and may be reworded.
- `hint` is troubleshooting text the SDK attached for a developer, or `None`.
  It is kept out of `str(e)` so an application can show the message to an end
  user without the developer checklist.

```python
except PipeException as e:
    if e.code == 'TASK_NOT_REGISTERED':
        await restart_pipeline()      # the task is gone; start a new one
    else:
        print(e)                      # safe to show
        if e.hint:
            log.debug(e.hint)         # developer detail
```

`PipeException` also subclasses `RuntimeError`, so a broad
`except RuntimeError` catches pipe failures too.

`ConnectionException`, `ExecutionException`, and `ValidationException` exist in
`rocketride.core.exceptions` but the SDK does not currently raise them: transport
failures surface as the builtin `ConnectionError`, and pipeline start and
validation failures as the built-ins in the table above. Don't write handlers
that rely on them.


---

# Examples

Route: /clients/python/examples

---
title: Examples
sidebar_position: 11
---

# Examples

Complete, runnable programs covering the SDK surface end to end. For pipeline-level
examples, see the site-wide examples —
[RAG pipeline](/examples/rag-pipeline), [webhook pipeline](/examples/webhook-pipeline), and [document extraction](/examples/document-extraction).

## 1. Minimal: connect, run pipeline from file, send one string, disconnect

```python
import asyncio
from rocketride import RocketRideClient


async def main():
    client = RocketRideClient(uri='https://api.rocketride.ai', auth='my-key')
    await client.connect()
    result = await client.use(filepath='pipeline.pipe')
    token = result['token']
    out = await client.send(token, 'Hello, pipeline!', objinfo={'name': 'input.txt'}, mimetype='text/plain')
    print(out)
    await client.terminate(token)
    await client.disconnect()


asyncio.run(main())
```

## 2. One-off script with context manager (recommended)

```python
import asyncio
from rocketride import RocketRideClient


my_pipeline_config = {'components': []}  # your pipeline dict, e.g. json.load(open('pipeline.pipe'))


async def main():
    async with RocketRideClient(uri='wss://api.rocketride.ai', auth='my-key') as client:
        result = await client.use(pipeline=my_pipeline_config)
        token = result['token']
        await client.send(token, '{"data": 1}')
        status = await client.get_task_status(token)
        print(status)
        await client.terminate(token)


asyncio.run(main())
```

## 3. Long-lived app: persist mode, callbacks, and status handling

Lifecycle callbacks are awaited, so pass `async` functions:

```python
import asyncio
from rocketride import RocketRideClient


async def on_connected(info):
    print('Connected:', info)


async def on_disconnected(reason, has_error):
    # Do not call disconnect() here if you want auto-reconnect.
    print('Disconnected:', reason, has_error)


async def on_connect_error(msg):
    print('Connect error:', msg)


async def on_event(e):
    print(e.get('event'), e.get('body'))


async def main():
    client = RocketRideClient(
        uri='https://api.rocketride.ai',
        auth='my-key',
        persist=True,
        on_connected=on_connected,
        on_disconnected=on_disconnected,
        on_connect_error=on_connect_error,
        on_event=on_event,
    )
    await client.connect()
    # Later: use(), send_files(), etc. If the connection drops, the client
    # retries forever (linear backoff) — except on auth failure.


asyncio.run(main())
```

## 4. Upload multiple files and poll until pipeline completes

```python
import asyncio
from rocketride import RocketRideClient


async def main():
    client = RocketRideClient(uri='https://api.rocketride.ai', auth='my-key')
    await client.connect()
    result = await client.use(filepath='vectorize.pipe')
    token = result['token']
    await client.set_events(token, ['apaevt_status_upload', 'apaevt_status_processing'])

    files = ['doc1.md', 'doc2.md', ('doc3.json', {'tag': 'export'}, 'application/json')]
    upload_results = await client.send_files(files, token)
    for r in upload_results:
        if r['action'] == 'complete':
            print('OK', r['filepath'])
        else:
            print('Failed', r['filepath'], r.get('error'))

    while True:
        status = await client.get_task_status(token)
        print(f'Progress: {status.get("completedCount", 0)}/{status.get("totalCount", 0)}')
        if status.get('completed'):
            break
        await asyncio.sleep(2)
    await client.terminate(token)
    await client.disconnect()


asyncio.run(main())
```

## 5. Streaming large data with a pipe

```python
import asyncio
from rocketride import RocketRideClient


async def main():
    async with RocketRideClient(uri='https://api.rocketride.ai', auth='my-key') as client:
        result = await client.use(filepath='ingest.pipe')
        token = result['token']
        pipe = await client.pipe(token, objinfo={'name': 'large.csv'}, mime_type='text/csv')
        await pipe.open()
        with open('large.csv', 'rb') as f:
            while True:
                chunk = f.read(64 * 1024)
                if not chunk:
                    break
                await pipe.write(chunk)
        result = await pipe.close()
        print(result)
        await client.terminate(token)


asyncio.run(main())
```

## 6. Chat: question with instructions and examples, parse JSON answer

```python
import asyncio
from rocketride import RocketRideClient
from rocketride.schema import Question, Answer


async def main():
    async with RocketRideClient(uri='https://api.rocketride.ai', auth='my-key') as client:
        result = await client.use(filepath='chat_pipeline.pipe')
        token = result['token']
        question = Question(expectJson=True)
        question.addInstruction('Format', 'Return a JSON object with keys: summary, keywords.')
        question.addExample('Summarize X', {'summary': '...', 'keywords': ['a', 'b']})
        question.addQuestion('Summarize the main points and list keywords.')
        response = await client.chat(token=token, question=question)
        answer_text = (response.get('answers') or [None])[0]
        answer = Answer(expectJson=True)
        answer.setAnswer(answer_text or '')
        if answer.isJson():
            structured = answer.getJson()
        else:
            structured = answer.getText()
        print(structured)
        await client.terminate(token)


asyncio.run(main())
```

## 7. Discover services and send a custom DAP request

```python
import asyncio
from rocketride import RocketRideClient


async def main():
    client = RocketRideClient(uri='https://api.rocketride.ai', auth='my-key')
    await client.connect()
    services = await client.get_services()
    print('Available:', list(services['services'].keys()))
    ocr = await client.get_service('ocr')  # raises if the service is unknown
    print('OCR definition sections:', list(ocr.keys()))
    my_token = 'existing-task-token'  # token from an earlier client.use() call
    req = client.build_request('rrext_ping', token=my_token)
    res = await client.request(req, timeout=5000)
    if client.did_fail(res):
        raise RuntimeError(res.get('message', 'Ping failed'))
    await client.disconnect()


asyncio.run(main())
```


---

# Run Logs

Route: /clients/python/logs

---
title: Run Logs
sidebar_position: 8
---

# Run Logs — `client.log`

Every task writes a **run log**: one continuous JSONL event stream per task
identity (`project_id` + `source`, plus the scope: a `team_id` addresses that
team's DEPLOY continuum — [deploy runs](/clients/python/deploy) log into the
team's tree, readable by any teammate with monitor rights — while omitting it
addresses your own stream, where the optional `run_kind` picks between your dev
stream (the default) and your personal deploy stream: `'deploy'` without a
`team_id` is the only way to address that continuum). Individual runs are
**chapters** (tracks) inside the stream — there are no per-run log files. The log
survives disconnects and server restarts, powers replay of past runs through the
same panels that render live monitoring, and is retained on a ring (last ~1 GB)
plus a history age (7 days dev / 30 days deploy).

Streams are addressed by the plain identity tuple — never by task token (tokens
are credentials and appear nowhere in the log system).

## The DVR session — `open_event_stream()`

Opens a **DVR session** over one source continuum — the recommended way to consume
a run log. The session thinks in *positions* on the timeline; storage details
(segments, keyframes, deltas) are invisible and every event it delivers is fully
reconstructed.

The protocol is **seed-then-stream**: `seek(pos)` positions the session, the
`get_*()` calls seed your panels with state *as of* that position, and
`play(pos, speed, cb)` streams events strictly *after* what the seeds covered — no
gap, no duplicate. Speed `0` delivers as fast as possible, `1` is real time, `10`
is 10×. Playing from a past position auto-pins to live on catching the wall clock;
live is just the position pinned to now (`seek('live')`), not a separate mode.

```python
# Own dev stream; pass team_id='team-prod' for a team's deploy continuum.
session = client.log.open_event_stream('proj-1', 'chat_1')

# Canonical startup: position, seed the panels, then roll.
await session.seek('live')
status = await session.get_status()  # state as of the position
console_lines = await session.get_console(500)  # exactly what the console showed
traces = await session.get_traces(50)  # all in-flight + last 50 closed
await session.play(None, 0, lambda item: fold(item['event']))

# Replay a past run at 10x from its beginning.
chapters = await session.get_chapters()
await session.play(chapters[0]['beginTime'], 10, lambda item: fold(item['event']))

# Drill into one trace (a call tree; fetched sparsely from exactly
# the segments that contain it).
detail = await session.get_trace(traces['closed'][0]['beginSeq'])

session.pause()  # freeze the position
session.close_event_stream()  # dispose
```

`get_traces(n)` errors when `n > 50` — the session exposes all in-flight traces
plus a sliding window of the 50 most recently closed; any older trace is still
reachable by seeking to a position inside its lifetime. `get_trace(trace_id)`
resolves a trace by its begin event's continuum seq (pass the trace's own
`beginSeq` from its `get_traces` summary, not the chapter's) — the permanent identity (slot
ids recycle; `beginSeq` never does). Hosts that own a live subscription feed
arriving events to the session via `ingest_live(event)`; while pinned, arrival
paces delivery.

## `chapters()`

Returns the stream's timeline in one small read: each run's begin/end date-time,
starting sequence number and outcome, the activity spans for the timeline bar, the
retained window, and the retention horizon.

```python
timeline = await client.log.chapters('proj-1', 'chat_1')
for track in timeline['chapters']:
    print(track['beginTime'], track.get('endTime'), track.get('outcome'))
```

## `read()`

Ranged, paged event read over the continuum. Range forms: a sequence range
(`from_seq`/`to_seq`), a time range (`from_time`/`to_time`, omit `to_time` for "to
now"), or time-to-segment (`from_time` + `to_segment`). Responses are paged
(`max_events`/`max_bytes`, server-clamped): when `nextSeq` is present, pass it back
as `cursor` to continue. `types` filters event types server-side; a
`truncatedAtSeq` field means the request reached below the retention horizon.

```python
cursor = None
while True:
    page = await client.log.read('proj-1', 'chat_1', from_seq=0, cursor=cursor, types=['output'])
    for event in page['events']:
        print(event['body'].get('output', ''), end='')
    cursor = page.get('nextSeq')
    if cursor is None:
        break
```

Every event carries the continuum stamps in its **body** — the only place they
exist: `body['eventTime']` (epoch seconds, stamped once at engine ingress) and
`body['logSeq']` (catalog-seeded — a fresh stream starts at 1 and continues from
the recorded `lastSeq + 1` across runs and restarts; strictly monotonic) —
identical live and on replay. The DAP envelope's own `seq` is per-connection
protocol bookkeeping and says nothing about the continuum.

## `segment()`

Fetches one segment's raw JSONL bytes, chunked by byte offset — the bulk replay
path. The server hands over the immutable segment content as-is, in
**whole-line-aligned chunks** (every response ends on a newline, so each chunk
parses standalone). Repeat with the returned `nextOffset` until `final`. The
segment table comes from `chapters()`.

```python
offset = 0
while True:
    chunk = await client.log.segment('proj-1', 'chat_1', 0, offset=offset)
    for line in chunk['data'].splitlines():
        if line.strip():
            handle_event(json.loads(line))
    if chunk['final']:
        break
    offset = chunk['nextOffset']
```

Prefer `segment()` over paged `read()` when consuming whole runs (replay, export);
use `read()` for filtered or narrow ranged queries.

## `delete()`

Destructive. `before_time` drops segments wholly older than the cutoff (chapters
trimmed, horizon advanced); `all` removes the entire stream including its control
file.

```python
await client.log.delete('proj-1', 'chat_1', before_time=time.time() - 86400)
await client.log.delete('proj-1', 'chat_1', all=True)
```

## Wire surface and permissions

All methods use the single `rrext_log` DAP command, dispatched by a `subcommand`
argument (`chapters`, `read`, `segment`, `delete`). Reads require `task.monitor`;
`delete` requires `task.control`. The scope the request addresses picks whose
streams those rights are resolved against: without `team_id` you access your OWN
dev streams; with `team_id` the permission is checked against the TARGET team —
membership is the read/write right. `open_event_stream()` is client-side
composition: it issues `chapters` and `segment` calls under the hood and
registers a live `rrext_monitor` subscription while open — it adds no wire
surface of its own.


---

# OpenTelemetry Bridge

Route: /clients/python/otel-bridge

---
title: OpenTelemetry Bridge
sidebar_position: 13
---

# OpenTelemetry Bridge (`rocketride otel`)

The OpenTelemetry bridge exports **live pipeline traces and metrics** from a running
RocketRide engine to any OpenTelemetry collector over OTLP — Jaeger, Grafana Tempo, Datadog,
Langfuse, LangSmith, or anything else that ingests OTLP. It ships with the Python client
as the `rocketride otel` CLI command and requires **zero engine or server changes**: the
bridge is a pure consumer of the engine's documented
[WebSocket monitor protocol](/connect/websocket/observability), subscribing to the
`TASK`, `SUMMARY`, `FLOW`, and `SSE` event streams with the wildcard token scope (the
documented scope for an ingestion service) and translating them into OTel spans and
metrics on the fly. Point it at your engine and your collector, and every pipeline run
visible to your API key shows up as a trace.

```text
RocketRide engine ──(WebSocket monitor events)──▶ rocketride otel ──(OTLP)──▶ your backend
```

- [Install](#install)
- [Quickstart: Jaeger end-to-end](#quickstart-jaeger-end-to-end)
- [CLI reference](#cli-reference)
- [Backend recipes](#backend-recipes)
- [The span model](#the-span-model)
- [Attributes](#attributes)
- [Privacy: content is excluded by default](#privacy-content-is-excluded-by-default)
- [Metrics](#metrics)
- [Reconnection and shutdown](#reconnection-and-shutdown)
- [Troubleshooting](#troubleshooting)
- [Limitations](#limitations)

---

## Install

The bridge's OpenTelemetry dependencies are an optional extra — the base `rocketride`
package gains no new dependencies:

```bash
pip install 'rocketride[otel]'
```

Running `rocketride otel` without the extra exits with code 2 and prints the install
command above.

## Quickstart: Jaeger end-to-end

Run Jaeger all-in-one (UI + OTLP receivers, in-memory storage):

```bash
docker run --rm -d --name jaeger \
  -p 16686:16686 -p 4317:4317 -p 4318:4318 \
  jaegertracing/all-in-one:1.76.0
```

Start the bridge — the defaults already point at `http://localhost:4318` (OTLP over
HTTP/protobuf):

```bash
export ROCKETRIDE_URI=ws://localhost:5565   # or wss://api.rocketride.ai + ROCKETRIDE_APIKEY
rocketride otel
```

Now start a pipeline run **with a trace level** so it emits `FLOW` events (see
[the callout below](#flow-spans-need-a-trace-level) — this is the step everyone misses):

```python
import asyncio
from rocketride import RocketRideClient


async def main():
    # Uses ROCKETRIDE_URI / ROCKETRIDE_APIKEY from the environment
    async with RocketRideClient() as client:
        result = await client.use(filepath='pipeline.pipe', pipelineTraceLevel='summary')
        token = result['token']
        await client.send(token, 'hello traces', objinfo={'name': 'input.txt'}, mimetype='text/plain')
        await client.terminate(token)


asyncio.run(main())
```

Open [http://localhost:16686](http://localhost:16686), select the **rocketride-engine**
service, and click **Find Traces**. You'll see one trace per run: a task root span, a pipe
span per object, and component child spans underneath.

## CLI reference

```bash
rocketride otel [--endpoint URL] [--protocol http|grpc] [--service-name NAME]
                [--headers k=v,k=v] [--include-content] [--no-metrics]
                [--trace-level none|metadata|summary|full]
```

| Flag                | Default                                       | Description                                                                                                                            |
| ------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--endpoint <url>`  | `OTEL_EXPORTER_OTLP_ENDPOINT`, else the exporter default (`http://localhost:4318` for http, `localhost:4317` for grpc) | OTLP **base** URL. The signal paths `/v1/traces` / `/v1/metrics` are appended automatically unless already present, so pasting Langfuse's or LangSmith's ingest URL just works. Without the flag the endpoint environment variables are resolved by the OTel SDK exporters themselves (never pre-read by the bridge), so `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` keep their spec-defined precedence over the generic `OTEL_EXPORTER_OTLP_ENDPOINT` (which the SDK still treats as a base URL). |
| `--protocol <p>`    | `http`                                        | OTLP transport: `http` (http/protobuf) or `grpc`. The gRPC exporter is **not** part of the `otel` extra — see [Troubleshooting](#troubleshooting). |
| `--service-name <n>`| `OTEL_SERVICE_NAME` or `rocketride-engine`    | The `service.name` resource attribute your backend groups by.                                                                          |
| `--headers <pairs>` | `OTEL_EXPORTER_OTLP_HEADERS`                  | Comma-separated `key=value` pairs sent with every OTLP request. Values are split on the *first* `=` only, so base64 padding survives. **Prefer the env var for secrets** — command-line arguments are visible in shell history and `ps` output; keep `--headers` for non-secret headers. Without the flag, the OTel SDK resolves `OTEL_EXPORTER_OTLP_HEADERS` and the signal-specific `OTEL_EXPORTER_OTLP_TRACES_HEADERS` / `OTEL_EXPORTER_OTLP_METRICS_HEADERS` itself. |
| `--include-content` | off                                           | Include pipeline payload content in spans, truncated to 8 KB per attribute. **By default no payload text reaches any span.**            |
| `--no-metrics`      | off                                           | Export traces only; task status snapshots are not mapped to metrics.                                                                   |
| `--insecure`        | off (`ROCKETRIDE_OTEL_ALLOW_INSECURE`)        | Allow credential-bearing OTLP headers over cleartext transport to a **non-loopback** collector. Without it the bridge exits `2` rather than putting an `Authorization` / `x-api-key` value on the wire in the clear — see [Transport security](#transport-security). |
| `--trace-level <l>` | —                                             | **Informational only.** The bridge cannot change the trace level of runs it did not start; this flag just prints a reminder of how to start traced runs. |

Plus the standard connection arguments shared by all subcommands: `--uri`
(`ROCKETRIDE_URI`) and `--apikey` (`ROCKETRIDE_APIKEY`). No task token is needed — the
bridge subscribes to every task your API key owns.

**Configuration precedence:** explicit CLI flags > standard `OTEL_*` environment
variables > built-in defaults. Only `OTEL_SERVICE_NAME` is read by the bridge; the
endpoint and header variables are resolved by the OTel SDK exporters themselves
(never pre-read by the bridge), so the signal-specific
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `_METRICS_ENDPOINT` /
`OTEL_EXPORTER_OTLP_TRACES_HEADERS` / `_METRICS_HEADERS` keep their spec-defined
precedence over the generic variables whenever `--endpoint` / `--headers` is not
given. Pre-reading a generic variable and handing it to both exporters would turn
it into an explicit value that silently overrides the signal-specific ones.

### Transport security

OTLP exporters send whatever headers they are configured with to whatever endpoint
they are given; they impose no TLS requirement of their own. So before any exporter
is built, the bridge checks the *effective* endpoint of each signal (explicit
`--endpoint` > signal-specific env var > generic env var > SDK default) against the
*effective* headers (`--headers` plus all three `OTEL_EXPORTER_OTLP_*HEADERS`
variables — names only; values are never read, logged or echoed):

- A credential-looking header name (`Authorization`, `x-api-key`, `*-token`,
  `*-secret`, …) plus a **non-loopback** `http://` endpoint — or a gRPC endpoint with
  `OTEL_EXPORTER_OTLP_INSECURE` set — aborts startup with exit code `2`.
- Loopback endpoints (`localhost`, `127.0.0.1`, `::1`) are exempt: that is the local
  collector / Jaeger case from the quickstart.
- `--insecure` (or `ROCKETRIDE_OTEL_ALLOW_INSECURE=1`) overrides the check for a
  trusted network, and prints a warning to stderr.

Two related hardening measures need no configuration: the OTLP/HTTP exporters use a
session that **does not follow redirects** (`requests` strips `Authorization` only on
a cross-*host* redirect, so a 3xx would otherwise replay `x-api-key` to the redirect
target), and the startup line prints the endpoint **redacted** — userinfo and query
string removed — because a signed collector URL is itself a credential.

**Exit codes:** `0` graceful shutdown (Ctrl+C / SIGTERM), `1` unexpected runtime error,
`2` missing dependency (the `otel` extra, or the gRPC exporter with `--protocol grpc`),
a cleartext-credential refusal, or startup connection/subscribe failure.

### FLOW spans need a trace level

`apaevt_flow` events — and therefore per-component spans — fire **only for runs started
with a `pipelineTraceLevel`** (an argument of the `execute` request, i.e.
`client.use(..., pipelineTraceLevel='summary')`). The bridge can only observe; it cannot
turn tracing on for a run it did not start. Without a trace level you still get task
lifecycle spans and all metrics, just no component breakdown. `summary` is the practical
level: lane writes and final results without per-call noise.

## Backend recipes

### Jaeger / Grafana Tempo / any OTLP collector

Covered by the [quickstart](#quickstart-jaeger-end-to-end): OTLP/HTTP on port 4318
(or `--protocol grpc` against 4317 with the gRPC exporter installed). Grafana Tempo
listens on the same two ports once its `distributor.receivers.otlp` block is enabled, so
`--endpoint http://tempo:4318` is the only change; pair it with Grafana Mimir or
Prometheus for the metric stream. The same shape works for the OpenTelemetry Collector
and any other standard OTLP receiver.

### Langfuse

Langfuse ingests OTLP **traces over HTTP only** (no gRPC, no metrics) at
`/api/public/otel`, with HTTP Basic auth built from your project keys:

```bash
# Read the Langfuse project keys instead of typing them into the command:
# a literal key in a command line lands in shell history and in `ps` output,
# and `echo -n '<secret>' | base64` exposes it in the process list too.
printf 'Langfuse public key (pk-lf-...): ' >&2; read -r LANGFUSE_PUBLIC_KEY
printf 'Langfuse secret key (sk-lf-...): ' >&2; read -rs LANGFUSE_SECRET_KEY; echo >&2

# tr -d strips the line breaks GNU base64 inserts every 76 characters: real
# project keys exceed that, and a wrapped value is an invalid header.
export LANGFUSE_AUTH="$(printf '%s' "${LANGFUSE_PUBLIC_KEY}:${LANGFUSE_SECRET_KEY}" | base64 | tr -d '\r\n')"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${LANGFUSE_AUTH}"
unset LANGFUSE_SECRET_KEY

rocketride otel \
  --endpoint https://cloud.langfuse.com/api/public/otel \
  --no-metrics
```

(`printf` + `read -rs` is spelled the same in bash and zsh; bash users can shorten
the second line to `read -rsp 'Langfuse secret key: ' LANGFUSE_SECRET_KEY`.)

The auth header travels via `OTEL_EXPORTER_OTLP_HEADERS` rather than a `--headers`
argument so the secret never lands in your shell history or shows up in `ps` output.
Better still, source it from your secret manager — `export LANGFUSE_SECRET_KEY="$(op read ...)"`
or the equivalent — and export only the variable reference.

Use `https://us.cloud.langfuse.com/api/public/otel` for the US region, or
`https://<your-host>/api/public/otel` for self-hosted (Langfuse v3.22.0+). Pass
`--no-metrics`: Langfuse's OTLP ingest is traces-only. Spans from LLM components carry
`gen_ai.*` attributes, which Langfuse maps into its own data model.

### LangSmith

LangSmith ingests OTLP traces over HTTP at `/otel`, authenticated with an `x-api-key`
header (optional `Langsmith-Project` header to pick the project):

```bash
# Prompt for the key (or read it from a secret manager) rather than typing it
# into the command: the env var keeps it out of `ps`, but a literal value in
# the export line is still recorded in shell history.
printf 'LangSmith API key: ' >&2; read -rs LANGSMITH_API_KEY; echo >&2
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=${LANGSMITH_API_KEY},Langsmith-Project=your-project-name"

rocketride otel \
  --endpoint https://api.smith.langchain.com/otel \
  --no-metrics
```

Regional hosts: `eu.api.smith.langchain.com` (EU); self-hosted follows
`https://<your-domain>/api/v1/otel`.

### Datadog

Send OTLP to a Datadog Agent (or an OpenTelemetry Collector with the Datadog exporter)
that has OTLP ingestion enabled — the agent handles the Datadog API key, so the bridge
needs no auth headers:

```bash
rocketride otel --endpoint http://localhost:4318
```

Datadog natively maps `gen_ai.*` semantic-convention attributes (semconv v1.37+) in its
LLM Observability product, so LLM component spans light up without a Datadog SDK.

## The span model

One trace per pipeline run. The hierarchy the bridge builds:

```text
task <task name>                     task root span (INTERNAL), one per run
│                                      opened on apaevt_task begin (or the seeded
│                                      "running" snapshot when attaching mid-run)
│
└── <object name>                    pipe root span, one per (run, pipe id) segment
    │                                  opened on flow op=begin, closed on op=end;
    │                                  named after the object flowing through
    │
    ├── chat                         component span (llm_openai_1)
    │   │                              SpanKind CLIENT, gen_ai.operation.name=chat,
    │   │                              gen_ai.provider.name=openai
    │   └─ ● thinking                apaevt_sse events attach as span events to the
    │                                  innermost open span of their pipe
    │
    └── response_1                   plain component span (INTERNAL)
                                       opened on op=enter, closed on op=leave —
                                       paired by component identity, one span per
                                       lane write (including control lanes)
```

Runs are correlated primarily on the wire correlation id (`__id`,
`<token-prefix>.<source>`), falling back to `(project_id, source)`. A run first
observed through events lacking `__id` is promoted to its canonical id when that id
later arrives — never tracked twice. Details worth knowing:

- **enter/leave pairing is by component identity**, never stack position (the monitor
  protocol documents why). Expect one short component span per lane write — including
  the `open`/`closing`/`close` control lanes.
- **Component spans still open at run end or bridge shutdown** are closed with status
  `UNSET` and `rocketride.span.unclosed=true` — an honest "we never saw the leave", not
  an error.
- **Attaching mid-run:** events for pipes the bridge never saw begin get an implicit
  root span marked `rocketride.span.implicit=true`.
- **Errors:** a `trace.error` on a component `leave` event sets span status `ERROR`,
  records an `exception` span event, and sets `error.type` (`_OTHER` — the wire error
  is a free-form string). The error *text* is treated as payload: by default the
  status description is a generic `component error` and the exception event carries
  no message; with `--include-content` the wire error text is exported (8 KB cap).
- **Task restarts** close the current spans and open a fresh task span with
  `rocketride.task.restarted=true`.
- **GenAI conventions:** component ids map to GenAI semantic conventions where the id
  makes the role unambiguous — `llm_*` → `chat` (CLIENT), `embedding_*` → `embeddings`
  (CLIENT), `agent_*` → `invoke_agent` (INTERNAL), `tool_*` → `execute_tool` (INTERNAL,
  with `gen_ai.tool.name`). `gen_ai.provider.name` is set only for providers on the
  semconv well-known list (e.g. `llm_openai_*` → `openai`, `llm_anthropic_*` →
  `anthropic`); unknown providers omit the attribute rather than inventing a value.

## Attributes

| Attribute                        | On                    | Meaning                                                             |
| -------------------------------- | --------------------- | ------------------------------------------------------------------- |
| `rocketride.project_id`          | all spans and metrics | Pipeline project id                                                 |
| `rocketride.source`              | all spans and metrics | Pipeline source (e.g. `webhook_1`)                                  |
| `rocketride.run_id`              | all spans             | Wire correlation id of the run (`<token-prefix>.<source>`)          |
| `rocketride.task.name`           | task spans            | Task name from the lifecycle event                                  |
| `rocketride.task.restarted`      | task spans            | `true` when this span was opened by a task restart                  |
| `rocketride.pipe_id`             | pipe/component spans  | Pipe index within the pipeline                                      |
| `rocketride.object`              | pipe spans            | Name of the object flowing through this segment                     |
| `rocketride.component`           | component spans       | Component id (e.g. `llm_openai_1`)                                  |
| `rocketride.lane`                | component spans       | Lane being written (e.g. `text`, `open`, `close`)                   |
| `rocketride.flow.result`         | component spans       | Flow result string on leave (e.g. `continue`)                       |
| `rocketride.span.unclosed`       | any span              | `true`: closed at run end/shutdown without a matching leave         |
| `rocketride.span.implicit`       | pipe spans            | `true`: created for a pipe whose begin the bridge never saw         |
| `rocketride.flow.unmatched_leaves` | pipe spans          | Count of leave events that matched no open component span           |
| `rocketride.sse.type`            | span events           | SSE message type (e.g. `thinking`, `tool_call`)                     |
| `gen_ai.operation.name`          | LLM/agent/tool spans  | `chat`, `embeddings`, `invoke_agent`, or `execute_tool`             |
| `gen_ai.provider.name`           | LLM/embedding spans   | Well-known provider value derived from the component id             |
| `gen_ai.tool.name`               | tool spans            | Tool name derived from the component id                             |
| `error.type`                     | failed spans          | Always `_OTHER` (wire errors are free-form strings)                 |
| `rocketride.trace.data` / `rocketride.result` / `rocketride.sse.data` | content-gated | Payload content — **only with `--include-content`**, 8 KB cap |

`gen_ai.*` names follow the July 2026 snapshot of the
`open-telemetry/semantic-conventions-genai` registry (Development stability, no tagged
release); deprecated names such as `gen_ai.system` or `gen_ai.usage.prompt_tokens` are
never emitted.

## Privacy: content is excluded by default

By default **no pipeline payload content reaches any span** — not lane data
(`trace.data`), not run-segment results, not SSE message bodies, and not the
free-form error text of failed components (node errors routinely quote their input;
the error *signal* — `ERROR` status, `error.type`, the `exception` span event — still
exports, with the generic description `component error`). Only structural metadata
(names, ids, lanes, counts, timings) is exported, so the bridge is safe to point at a
shared collector out of the box.

Opting in with `--include-content` copies payload content into the
`rocketride.trace.data`, `rocketride.result`, and `rocketride.sse.data` attributes and
exports the verbatim wire error text in span statuses and `exception` events —
JSON-serialized and truncated to **8192 characters** per attribute. Treat the flag as
what it is: pipeline inputs and outputs flowing into your telemetry backend.

## Metrics

Unless `--no-metrics` is set, every `apaevt_status_update` snapshot (roughly every 500 ms
per running task) is mapped to OTel metrics, exported over the same OTLP endpoint. All
instruments carry `rocketride.project_id` / `rocketride.source` attributes.

| Instrument                       | Type            | Unit         | Meaning                                  |
| -------------------------------- | --------------- | ------------ | ---------------------------------------- |
| `rocketride.objects.total`       | up-down counter | `{object}`   | Objects seen by the pipeline run         |
| `rocketride.objects.completed`   | up-down counter | `{object}`   | Objects completed                        |
| `rocketride.objects.failed`      | up-down counter | `{object}`   | Objects failed                           |
| `rocketride.rate.count`          | gauge           | `{object}/s` | Instantaneous object processing rate     |
| `rocketride.rate.size`           | gauge           | `By/s`       | Instantaneous byte processing rate       |
| `rocketride.cpu.percent`         | gauge           | `%`          | Engine CPU utilization                   |
| `rocketride.cpu.percent.peak`    | gauge           | `%`          | Peak engine CPU utilization              |
| `rocketride.memory.cpu_mb`       | gauge           | `MBy`        | Engine CPU memory usage                  |
| `rocketride.memory.cpu_mb.peak`  | gauge           | `MBy`        | Peak engine CPU memory usage             |
| `rocketride.memory.gpu_mb`       | gauge           | `MBy`        | Engine GPU memory usage                  |
| `rocketride.memory.gpu_mb.peak`  | gauge           | `MBy`        | Peak engine GPU memory usage             |

Object counters are fed **per-run deltas** between snapshots, so re-sent snapshots don't
double-count; a task restart resets the engine's counts, which legitimately produces
negative deltas. The snapshot's `tokens.*` block is **compute credits (billing), not LLM
tokens**, and is deliberately not exported as `gen_ai.usage.*`.

## Reconnection and shutdown

- **Reconnects** use capped exponential backoff (1 s doubling up to 30 s). Monitor
  subscriptions are per-connection and not durable, but the SDK replays them on every
  reconnect, and the re-seeded "running"/status snapshots are handled idempotently —
  already-open spans are not duplicated. The seeded snapshot is also authoritative:
  tracked runs it no longer announces (their `end` was missed while disconnected) are
  closed with `rocketride.span.unclosed=true` and dropped.
- **Ctrl+C / SIGTERM** closes all open spans (marked `rocketride.span.unclosed=true`),
  flushes both exporters, and exits `0`.
- **Startup failure** (engine unreachable, subscribe rejected) prints a clean message to
  stderr and exits `2` so supervisors can tell "never started" from "was stopped".

### Embedding the bridge

`rocketride.otelbridge.run_bridge()` runs the same loop inside an application that owns
its own event loop (pass `install_signal_handlers=False` when the application owns
process signals). Two ownership rules matter there:

- **The bridge builds only the halves you did not supply.** Pass `mapper_factory` and
  it builds no `TracerProvider`; pass `metrics_factory` and it builds no
  `MeterProvider`. Each provider carries a background export thread, so a half that is
  built and never read is a leaked thread, not just wasted setup.
- **Whatever the bridge builds, the bridge shuts down.** A `shutdown_fn` you supply is
  *chained in front of* the providers' own shutdown, never substituted for it: yours
  runs first, theirs runs in a `finally` so it still happens if yours raises (your
  exception is logged to stderr and the bridge still exits `0`). Supplying
  `shutdown_fn` therefore never orphans a provider the bridge created.

## Troubleshooting

| Symptom                                                        | Cause / fix                                                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Exits immediately with code 2 and an install hint               | The `otel` extra is missing: `pip install 'rocketride[otel]'`.                                                                                   |
| Bridge runs, tasks appear, but **no component spans**           | The run was not started with a trace level. Start runs with `client.use(..., pipelineTraceLevel='summary')` — the bridge cannot enable it for you. |
| Exits with code 2, "connection" in the message                  | Engine unreachable at startup: check `--uri` / `ROCKETRIDE_URI` and `--apikey` / `ROCKETRIDE_APIKEY`.                                            |
| Bridge runs but nothing arrives in the backend                  | Exporter can't reach the collector (exports fail in the background; the bridge keeps running). Check host/port — OTLP/HTTP is **4318**, gRPC is **4317** — and that `--protocol` matches the receiver. |
| `--protocol grpc` fails with an install error                   | The gRPC exporter is not part of the extra: `pip install opentelemetry-exporter-otlp-proto-grpc`. Note Langfuse does not accept gRPC at all.     |
| Langfuse/LangSmith receive traces but metric exports error      | Their OTLP ingest is traces-only — run with `--no-metrics`.                                                                                      |
| Spans named `chat` carry no model name or token counts          | Expected — see [Limitations](#limitations).                                                                                                      |

## Limitations

Honest edges of a protocol-level bridge:

- **Span timestamps come from the engine; metric points do not.** Every forwarded
  event body carries `eventTime` (epoch seconds, stamped at ingress by the engine's
  run-log continuum), and spans and span events are stamped with it — so span
  durations are engine-measured and exclude WebSocket latency. Two edges remain: a
  span closed by a non-event path (bridge shutdown, snapshot reconciliation, or the
  tracked-run cap) and any event from an engine too old to stamp `eventTime` fall back
  to the bridge's own clock at that moment; and OpenTelemetry metric instruments take
  no explicit timestamp, so metric points are always recorded at arrival. A close is
  never stamped before its own span's start, so mixing the two sources cannot produce
  a negative duration.
- **LLM token usage and model names appear only when nodes surface them in events.**
  Flow events at `summary` level carry neither, so `gen_ai.request.model` and
  `gen_ai.usage.*` are honestly omitted rather than guessed, and LLM span names degrade
  to the bare operation (`chat`, not `chat gpt-4.1`). The status snapshot's `tokens.*`
  are compute credits, not LLM tokens, and are never mapped to `gen_ai.usage.*`.
- **`gen_ai.*` conventions are Development stability.** Attribute names follow the July
  2026 snapshot of `open-telemetry/semantic-conventions-genai`; they are centralized in
  one constants module and may be revised as the spec evolves.
- **Trace level is the run starter's choice.** `--trace-level` on the bridge is
  informational only; there is no protocol surface to change it for running tasks.
- **Restart accounting.** Object up-down counters are per-run deltas, so a task restart
  (counts reset) produces a negative step by design.
- **Spans export when they close.** The batch span processor exports a span only at
  `end()`, so a run whose `end` event is never observed holds its spans back until the
  bridge closes them — at the next reconnect's seeded snapshot (runs no longer
  announced are closed), when the tracked-run cap (1024) evicts the
  least-recently-eventful run, or at shutdown. Such spans are flagged
  `rocketride.span.unclosed=true`. There is deliberately no idle timeout: a quiet but
  alive task (e.g. a webhook service) keeps being announced and is never expired by a
  clock. Metric delta bookkeeping is likewise capped (4096 runs, least recently
  updated evicted first), so a bridge left running for weeks has bounded memory.

## See also

- [Monitor protocol reference](/connect/websocket/observability) — the event
  stream the bridge consumes
- [CLI reference](/connect/cli) — the `otel` flag table alongside the rest of the CLI
- [Python SDK](/clients/python) — the client the bridge ships with
- [Client libraries overview](/clients) — every official client


---

# Running Pipelines

Route: /clients/python/pipelines

---
title: Running Pipelines
sidebar_position: 3
---

# Running Pipelines

Start a pipeline, watch its progress, and stop it. Method tables live in the
[API reference](/clients/python/reference#pipeline-execution); this page covers the
workflow.

## Start with `use()`

`use()` starts a pipeline from a file or an in-memory config and returns a dict whose
`'token'` identifies the running task — every data and control call takes it.

```python
result = await client.use(filepath='pipeline.pipe')
token = result['token']
```

Beyond `filepath`/`pipeline`, `use()` accepts `source`, `threads`, `use_existing`,
`args`, `ttl`, `pipelineTraceLevel` (trace verbosity for the
[run log](/clients/python/logs)), `name` (a display name for the task), and `env`
(per-run variable overrides). Pass the pipeline config **as-is** — the client sends it
to the server, which resolves `${ROCKETRIDE_*}` variables from its merged
environment.

**Check `reused` before trusting the result.** `use_existing` returns the
instance that is already running under that token rather than starting the one
you submitted, and the result's `reused` flag is `True` when that happened. A
reused instance keeps the configuration it was created with — the pipeline in
this call is ignored, edits included — along with whatever state it has
accumulated. Benchmarks and A/B comparisons are where an unnoticed reuse costs
the most. Call `restart()` to apply new configuration to a live token.

**Why a token:** the server runs each pipeline as a separate task. The token targets
`send()`, `send_files()`, `pipe()`, `chat()`, `get_task_status()`, and `terminate()`
at the correct pipeline.

## Watch progress

Poll `get_task_status(token)` — it returns `completedCount`, `totalCount`,
`completed`, `state`, `exitCode`, and more:

```python
while True:
    status = await client.get_task_status(token)
    print(f'Progress: {status.get("completedCount", 0)}/{status.get("totalCount", 0)}')
    if status.get('completed'):
        break
    await asyncio.sleep(2)
```

### Events

For push-style progress instead of polling, add a monitor subscription; events
arrive at your [`on_event` callback](/clients/python/configuration#callbacks):

```python
await client.add_monitor({'token': token}, ['apaevt_status_upload', 'apaevt_status_processing'])
# ... later:
await client.remove_monitor({'token': token}, ['apaevt_status_upload', 'apaevt_status_processing'])
```

`add_monitor(key, types)` / `remove_monitor(key, types)` are reference-counted —
adding the same key merges types, removing unsubscribes a type only when its count
reaches zero. The key is `{'token': ...}` for a running task, or
`{'project_id': ..., 'source': ...}` (optionally with `'pipe_id'` and/or
`'team_id'` — a team ID addresses that team's deployed run). The older
`set_events(token, event_types, pipe_id=None)` still works but is deprecated in
favor of the monitor pair.

## Validate before you run

`validate(pipeline, source=None)` checks a pipeline config server-side without
starting it and returns errors and warnings — cheap insurance before `use()`.

## Stop with `terminate()`

`terminate(token)` stops the pipeline and frees server resources. Long-lived tasks
without a `ttl` run until terminated.

## Discover services

`get_services()` returns lightweight **summaries** of every service the server
supports (plus a deduplicated icon table and the server version). For a full
definition — config schema included — fetch one by name with `get_service(name)`.
Note `get_service` **raises** on failure (`ValueError` for an empty name,
`RuntimeError` for an unknown service); it never returns `None`.

```python
services = await client.get_services()
ocr = await client.get_service('ocr')  # raises if unknown
```

## Liveness

`ping()` performs a liveness check against the server and raises on failure.

> Deploying a pipeline so it persists server-side and runs on a schedule is a
> separate surface — see [Deployments](/clients/python/deploy).


---

# API Reference

Route: /clients/python/reference

---
title: API Reference
sidebar_position: 10
---

# API Reference

The core public surface of the Python SDK. Constructor options and
environment variables are on [Configuration](/clients/python/configuration);
exceptions on [Error Handling](/clients/python/errors).

## RocketRideClient

### Connection

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `attach` | `async def attach(self, uri: Optional[str] = None, *, timeout: Optional[float] = None) -> None` | - | Opens the WebSocket without authenticating. If `uri` is provided and differs from the current URI, detaches first; if already attached to the same URI, this is a no-op. |
| `detach` | `async def detach(self) -> None` | - | Closes the transport and leaves the client detached. |
| `is_attached` | `def is_attached(self) -> bool` | `bool` | Whether the WebSocket transport is open, regardless of authentication. |
| `login` | `async def login(self, credential: Optional[str] = None, *, uri: Optional[str] = None, timeout: Optional[float] = None) -> ConnectResult` | `ConnectResult` | Authenticates over an attached transport (attaching first if needed). A differing `uri` detaches and re-attaches; a differing `credential` logs out (best-effort) before logging in; logging in again with the same credential is a no-op. |
| `logout` | `async def logout(self) -> None` | - | Deauthenticates (sends `deauth`) and clears client auth state while keeping the attachment. |
| `is_authenticated` | `def is_authenticated(self) -> bool` | `bool` | Whether the auth handshake has succeeded on the current connection. |
| `connect` | `async def connect(self, credential: Optional[str] = None, *, timeout: Optional[float] = None) -> ConnectResult` | `ConnectResult` | Opens the WebSocket and performs DAP auth. Optional `credential` overrides the constructor `auth` for this connection attempt. Optional `timeout` (ms) bounds the connect + auth handshake (non-persist only). In **persist** mode, on failure the client calls `on_connect_error` and retries; on **auth** failure it does not retry. |
| `disconnect` | `async def disconnect(self) -> None` | - | Closes the connection and cancels reconnection. |
| `is_connected` | `def is_connected(self) -> bool` | `bool` | Backward-compatible alias for `is_attached()` — `True` when the WebSocket is open; does not imply authentication. |
| `get_connection_info` | `def get_connection_info(self) -> dict` | `dict` | Returns `{ 'connected': bool, 'transport': str, 'uri': str }`. |
| `get_apikey` | `def get_apikey(self) -> Optional[str]` | `str \| None` | The API key in use. For debugging only; avoid logging in production. |
| `set_env` | `def set_env(self, env: Dict[str, str]) -> None` | - | Replaces the client's environment map, used for `${ROCKETRIDE_*}` substitution and credential lookup. |

Context manager: `async with RocketRideClient(...) as client:` — entering calls
`connect()`, exiting calls `disconnect()`.

### Pipeline execution

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `use` | `async def use(self, *, token: str = None, filepath: str = None, pipeline: PipelineConfig = None, source: str = None, threads: int = None, use_existing: bool = None, args: List[str] = None, ttl: int = None, pipelineTraceLevel: str = None, name: str = None, env: Dict[str, str] = None) -> dict` | `dict` | Starts a pipeline. Requires `filepath` or `pipeline`. `pipelineTraceLevel` sets run-log trace verbosity, `name` a task display name, `env` per-run variable overrides. Returns a dict with at least `'token'`, plus `'reused': True` when `use_existing` handed back an already-running instance instead of starting this pipeline. |
| `terminate` | `async def terminate(self, token: str) -> None` | - | Stops the pipeline and frees server resources. |
| `get_task_status` | `async def get_task_status(self, token: str) -> dict` | `dict` | Current task status (`completedCount`, `totalCount`, `completed`, `state`, `exitCode`, …). |

### Data

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `pipe` | `async def pipe(self, token: str, objinfo: dict = None, mime_type: str = None, provider: str = None, on_sse=None) -> DataPipe` | `DataPipe` | Creates a **streaming** pipe: open, then one or more writes, then close. Default MIME: `'application/octet-stream'`. `on_sse` receives server-sent events. |
| `send` | `async def send(self, token: str, data: str \| bytes, objinfo: dict = None, mimetype: str = None, on_sse=None) -> PIPELINE_RESULT` | `PIPELINE_RESULT` | Sends data in **one shot** (open, write once, close). No MIME auto-detection — default is `'application/octet-stream'`. |
| `send_files` | `async def send_files(self, files: List[str \| Tuple[str, dict] \| Tuple[str, dict, str]], token: str) -> List[UPLOAD_RESULT]` | `List[UPLOAD_RESULT]` | Uploads files concurrently (unbounded `asyncio.gather`). **Requires an API key** (`RuntimeError` without one); a missing file raises `ValueError`. Progress via `on_event` as `apaevt_status_upload`. |

### Events

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `add_monitor` | `async def add_monitor(self, key: Dict[str, Any], types: List[str]) -> None` | - | Adds a reference-counted monitor subscription; events are delivered to `on_event`. Key: `{'token': ...}` or `{'project_id': ..., 'source': ...}` (+ optional `'pipe_id'`, `'team_id'`). |
| `remove_monitor` | `async def remove_monitor(self, key: Dict[str, Any], types: List[str]) -> None` | - | Removes a monitor subscription; a type unsubscribes from the server only when its reference count reaches zero. |
| `set_events` | `async def set_events(self, token: str, event_types: List[str], pipe_id: int = None) -> None` | - | **Deprecated** — use `add_monitor`/`remove_monitor`. Subscribes the task to the given event types. |

### Services, validation, and ping

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `get_services` | `async def get_services(self) -> dict` | `dict` | Lightweight **summaries** of every service, plus a deduplicated `icons` table and the server `version`. Full definitions come from `get_service`. |
| `get_service` | `async def get_service(self, service: str) -> dict` | `dict` | One service's full definition (config schema included). **Raises** `ValueError` (empty name) or `RuntimeError` (unknown service); never returns `None`. |
| `validate` | `async def validate(self, pipeline: PipelineConfig, *, source: str = None) -> dict` | `dict` | Validates a pipeline configuration without starting it; returns errors and warnings. |
| `ping` | `async def ping(self) -> None` | - | Liveness check; raises on failure. (A legacy `token` argument is accepted but not sent.) |

### Chat

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `chat` | `async def chat(self, *, token: str, question: Question, on_sse=None) -> PIPELINE_RESULT` | `PIPELINE_RESULT` | Sends the `Question` to the pipeline and returns the result. `on_sse` streams server-sent events (e.g. token-by-token output). See [Chat](/clients/python/chat). |

### Store (file access)

Paths are **relative** to the store root; absolute-like paths are rejected. See
[File Storage](/clients/python/storage) for the workflow.

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `fs_open` | `async def fs_open(self, path: str, mode: str = 'r') -> dict` | `dict` | Open a handle. Returns `{'handle': str}`; read mode also includes `'size'` (int). |
| `fs_read` | `async def fs_read(self, handle: str, offset: int = 0, length: int = 4_194_304) -> bytes` | `bytes` | Read up to `length` bytes (default 4 MB) from `offset`. Empty bytes = EOF. |
| `fs_write` | `async def fs_write(self, handle: str, data: bytes) -> int` | `int` | Write raw bytes to a write handle. Returns the number of bytes written. |
| `fs_close` | `async def fs_close(self, handle: str, mode: str = 'r') -> None` | - | Close a handle. `mode` must match the mode passed to `fs_open`. |
| `fs_read_string` | `async def fs_read_string(self, path: str, encoding: str = 'utf-8') -> str` | `str` | Read an entire file as a decoded string. |
| `fs_write_string` | `async def fs_write_string(self, path: str, text: str, encoding: str = 'utf-8') -> None` | - | Write a string to a file (overwrites). |
| `fs_read_json` | `async def fs_read_json(self, path: str) -> Any` | `Any` | Read and parse a JSON file. |
| `fs_write_json` | `async def fs_write_json(self, path: str, obj: Any) -> None` | - | Serialize an object to JSON and write it. |
| `fs_list_dir` | `async def fs_list_dir(self, path: str = '') -> dict` | `dict` | List immediate children: `{entries: [{name, type, size?, modified?}], count}`. |
| `fs_stat` | `async def fs_stat(self, path: str) -> dict` | `dict` | Metadata: `{exists, type, size, modified}` (`size`/`modified` for files only). |
| `fs_mkdir` | `async def fs_mkdir(self, path: str) -> None` | - | Create a directory. |
| `fs_rmdir` | `async def fs_rmdir(self, path: str, *, recursive: bool = False) -> None` | - | Remove a directory. `recursive=True` deletes contents. |
| `fs_rename` | `async def fs_rename(self, old_path: str, new_path: str) -> None` | - | Rename or move a file/directory (copy+delete on object stores; recursive for directories). |
| `fs_delete` | `async def fs_delete(self, path: str) -> None` | - | Delete a file. |
| `fs_get_url` | `async def fs_get_url(self, path: str, expires_in: int = 3600, download_name: str = None) -> str` | `str` | Time-limited HTTP(S) URL for direct browser access; inline by default, `download_name` forces `Content-Disposition: attachment`. |
| `fs_read_many` | `async def fs_read_many(self, paths: List[str]) -> List[Dict[str, Any]]` | `List[Dict]` | Batch-read many small files in one round trip (max 256 paths / 32 MiB total). Per-entry failures (`ok: False` + `error`), request order, `data` as `bytes`. |

### Database

Raw SQL through a pipeline database node (requires `allow_execute: true` on the
node). The TypeScript SDK additionally offers a Sequelize ORM binding over this
surface.

| Method | Signature | Description |
| --- | --- | --- |
| `database.query` | `async def query(*, token, sql, node_id='', session_id='', params=None) -> dict` | Execute raw SQL through the pipeline's `execute` tool function; returns `{rows, affected_rows}`. |
| `database.begin_transaction` | `async def begin_transaction(*, token, node_id='') -> dict` | Open a transaction (`begin` tool function); returns `{session_id}`. |
| `database.commit` | `async def commit(*, token, session_id, node_id='') -> dict` | Commit the open transaction. |
| `database.rollback` | `async def rollback(*, token, session_id, node_id='') -> dict` | Roll back the open transaction. |
| `database.dialect` | `async def dialect(*, token, node_id='') -> DatabaseDialect` | The target node's SQL dialect. |

### Deploy (`client.deploy`)

See [Deployments](/clients/python/deploy) for the model.

| Method | Signature | Returns |
| --- | --- | --- |
| `deploy.add` | `async def add(self, pipeline=None, *, kind='pipe', data=None, metadata=None, comment=None, deploy_to=None) -> PublishResult` | `PublishResult` |
| `deploy.add_app` | `async def add_app(self, app_root, *, workspace_root=None, comment=None, metadata=None, on_progress=None) -> PublishResult` | `PublishResult` |
| `deploy.verify_app` | `async def verify_app(self, app_root, *, workspace_root=None) -> AppVerifyReport` | `AppVerifyReport` |
| `deploy.deploy` | `async def deploy(self, project_id, version, team_id) -> Deployment` | `Deployment` |
| `deploy.list` | `async def list(self, *, team_id=None, page=None, page_size=None, search=None, filters=None, sort=None) -> DeployListResult` | `DeployListResult` |
| `deploy.get` | `async def get(self, project_id, team_id) -> Deployment` | `Deployment` |
| `deploy.versions` | `async def versions(self, project_id, *, page=None, ...) -> DeployVersionsResult` | `DeployVersionsResult` |
| `deploy.history` | `async def history(self, project_id, *, team_id=None, page=None, ...) -> DeployHistoryResult` | `DeployHistoryResult` |
| `deploy.disable` | `async def disable(self, project_id, team_id) -> Deployment` | `Deployment` |
| `deploy.enable` | `async def enable(self, project_id, team_id) -> Deployment` | `Deployment` |
| `deploy.remove` | `async def remove(self, project_id, team_id) -> Deployment` | `Deployment` |
| `deploy.set_schedule` | `async def set_schedule(self, project_id, source_id, schedule, team_id, *, ttl=None) -> Deployment` | `Deployment` |
| `deploy.pause_schedule` | `async def pause_schedule(self, project_id, source_id, team_id) -> Deployment` | `Deployment` |
| `deploy.resume_schedule` | `async def resume_schedule(self, project_id, source_id, team_id) -> Deployment` | `Deployment` |
| `deploy.set_source_config` | `async def set_source_config(self, project_id, source_id, team_id, ...) -> Deployment` | `Deployment` |
| `deploy.run` | `async def run(self, project_id, source_id, team_id) -> dict` | `{token, version}` |
| `deploy.artifact` | `async def artifact(self, project_id, version) -> PipelineConfig` | `PipelineConfig` |
| `deploy.preview` | `async def preview(self, schedule, count=None) -> SchedulePreview` | `SchedulePreview` |

### App publish ladder

See [Deployments](/clients/python/deploy#app-publish-ladder) for the model.
Only `deploy.add` and `deploy.add_app` live on `client.deploy`; the unprefixed
verbs below are methods on the client itself (`client.publish_app(...)`).

| Method | Signature | Description |
| ------ | --------- | ----------- |
| `deploy.add` | `async def add(self, pipeline=None, *, kind='pipe', data=None, metadata=None, comment=None, deploy_to=None) -> PublishResult` | The ONE rail door (on the `client.deploy` namespace): deploy any kind of object as the next immutable registry version. `kind='pipe'` (default) takes a `pipeline` dict; `kind='app'` takes ONE `data` zip of the app's SOURCE (the server performs the build; client-produced binaries are never trusted), retained and unpacked at receipt, born deployment-state `private`. The app id must be inside your developer namespace. |
| `deploy.add_app` | `async def add_app(self, app_root, *, workspace_root=None, comment=None, metadata=None, on_progress=None) -> PublishResult` | Pack an app folder's source and deploy it as the next registry version — the one call behind the App Builder's Deploy button and CI scripts. Packs by the App Builder rules (workspace-rooted zip, `appManifest.include`, hierarchical gitignore + the hard node_modules/dist/.git baseline, symlink containment, 50MB zipped / 512MB uncompressed caps); `on_progress` narrates one line per step. Deploying activates nothing — bind an audience with `publish_app` afterwards. |
| `deploy.verify_app` | `async def verify_app(self, app_root, *, workspace_root=None) -> AppVerifyReport` | The no-side-effect precheck for `add_app` — purely local, no server call: manifest shape and id grammar, declared icon/README assets, `appManifest.include` entries, and a pack dry run against the size caps. Server-side concerns (the build, store review) are out of scope. |
| `list_deployments` | `async def list_deployments(self, app_id) -> list[dict]` | The version rail, newest first — the developer org sees its FULL rail (published or not), other callers only their visible versions. Each entry carries its deployment `state`, its `buildStatus` ('ok' = servable), and the `rungs` naming the audiences bound to it. |
| `submit_app` | `async def submit_app(self, app_id, registry_version) -> dict` | Submit a deployed version for review — flips the deployment `private` → `submit`. |
| `withdraw_app` | `async def withdraw_app(self, app_id, registry_version) -> dict` | Withdraw a pending review — the developer's own cancel: flips the deployment `submit` → `private`, the version leaves the admin queue and history records `withdrawn`. Only a version in `submit` withdraws. Developer-org + namespace gated, like submit. |
| `reply_app` | `async def reply_app(self, app_id, message, registry_version=None) -> dict` | Append a developer message to the app's review thread — rides `deployment_history` as a `reply` row (side `'developer'`), the same stream `deploy.history()` reads. Developer-org + namespace gated, like submit. |
| `build_log` | `async def build_log(self, app_id, registry_version) -> dict` | One version's durable server build log — the full phase-by-phase output stored beside the version's artifacts (no error text rides the rail rows). Long logs serve their tail; empty `log` = none. Developer-org gated. |
| `publish_app` | `async def publish_app(self, app_id, registry_version, target) -> dict` | Bind a deployment to '@me', '@team/<name>', or '@public' ('@user' = legacy input alias). The binding is a pure pointer born 'enabled'. '@public' requires the deployment be `ready`; '@me'/'@team' accept any non-`failed` deployment. Pinning ANOTHER org's public app to '@me'/'@team' is the version selector; publishing your own app requires the id to be in your namespace. |
| `where_app` | `async def where_app(self, app_id) -> list[dict]` | The reverse index: `{rung, handle, version, appVersion, state, deployedAt}` per audience — `state` is the bound deployment's review state. |

Serving needs no verb: a version's bundle loads from the stable
`/apps/<app_id>/v<N>/remoteEntry.js` URL constructed from its registry
version number, with entitlement enforced by the serve route on every
request (registry ints ONLY — semver is display).

### App marketplace + developer verbs

Two raw DAP commands carry this surface (call via
`client.call("<command>", {"subcommand": ...})`):

- **`rrext_deploy_app`** — the developer-account + review verbs (claiming a
  developerId is a deploy PREREQUISITE, not a marketplace action): the
  `developer_*` family, `submit`, and `register_dev`.
- **`rrext_app`** — the pure marketplace: browse (`list`/`get`/`list_mine`),
  install (`desktop_add`/`desktop_remove`), admin review (`admin_*`), and
  pricing (`pricing_*`).

Grouped families (the `developer_*`/`submit`/`register_dev` rows are on
`rrext_deploy_app`; the rest on `rrext_app`):

| Subcommand family | Subcommands | Guard | Purpose |
| ----------------- | ----------- | ----- | ------- |
| developer_* | `developer_register` · `developer_stripe` · `developer_dashboard` · `developer_status` | org.admin (register) | Claim the org's developer id slug + Stripe Connect onboarding. |
| submit | `submit` | developer org + namespace | Submit a deployed version for review — flips the DEPLOYMENT `private` → `submit`. |
| register_dev | `register_dev` | self | Per-user live dev overlay (App Builder hot-reload); OSS-capable. |
| catalog | `list` · `get` · `list_mine` · `desktop_add` · `desktop_remove` | authenticated | Browse reachable apps, the developer's own rail view, and desktop membership. |
| admin_* | `admin_queue` · `admin_approve` · `admin_reject` · `admin_reply` · `admin_reseed` | sys.admin | Store review over the DEPLOYMENTS: the queue is deployments in `submit`; `admin_approve(appId, version)` → `ready`, `admin_reject(appId, version)` → `rejected`. |
| pricing_* | `pricing_list` · `pricing_create` · `pricing_delete` | developer org | Manage Stripe price tiers for a monetized app. |

**Review model.** The review state lives on the DEPLOYMENT. Going public is a
three-step flow: `submit` (deployment → `submit`, enters the admin queue) →
`admin_approve` (→ `ready`) → `publish_app @public` (point the public binding at
the `ready` version). A reject flips the deployment `rejected`; the developer
fixes and deploys a NEW version. `@me`/`@team` bindings need no approval.

### Run logs (`client.log`)

See [Run Logs](/clients/python/logs) for the continuum model and the DVR session.

## DataPipe

Returned by `await client.pipe(...)`. One streaming upload: **open → write (one or
more) → close**. Also an async context manager: entering calls `open()`, exiting
calls `close()`.

| Property | Type | Description |
| --- | --- | --- |
| `is_opened` | `bool` | Whether the pipe is open. |
| `pipe_id` | `int \| None` | Server-assigned pipe ID after `open()`. |

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `open` | `async def open(self) -> DataPipe` | `self` | Opens the pipe; required before `write()`. |
| `write` | `async def write(self, buffer: bytes) -> None` | - | Writes a chunk. Pipe must be open; payload must be `bytes`. |
| `close` | `async def close(self) -> PIPELINE_RESULT` | `PIPELINE_RESULT` | Closes the pipe and returns the processing result. |
| `tool` | `async def tool(self, *, tool: str, node_id: str = '', input: dict = None) -> Any` | `Any` | Invokes a pipeline tool function through the pipe. |

`open()` retries once automatically if it hits a transient "Connect call
failed" while the pipeline's data listener is still starting up (worst case
adds ~1.75s); a `PipeException` from `open()` means it kept failing past that
retry budget.

## Question

From `rocketride.schema`. Build a question for
`client.chat(token=..., question=question)`.

```python
Question(
    type: QuestionType = QuestionType.QUESTION,
    filter: DocFilter = None,
    expectJson: bool = False,
    role: str = '',
)
```

`QuestionType`: `QUESTION`, `SEMANTIC`, `KEYWORD`, `GET`, `PROMPT`.

| Method | Signature | Description |
| --- | --- | --- |
| `addInstruction` | `addInstruction(self, title: str, instruction: str)` | Adds an instruction (e.g. "Use bullet points"). |
| `addExample` | `addExample(self, given: str, result: dict \| list \| str)` | Adds an example input/output; `result` can be dict/list (JSON-serialized). |
| `addContext` | `addContext(self, context: str \| dict \| List[str] \| List[dict])` | Adds context. |
| `addHistory` | `addHistory(self, item: QuestionHistory)` | Adds a history item for multi-turn chat. |
| `addQuestion` | `addQuestion(self, question: str)` | Appends the question text. |
| `addDocuments` | `addDocuments(self, documents: Doc \| List[Doc])` | Adds documents for the AI to reference. |
| `addGoal` | `addGoal(self, goal: str)` | Adds a goal statement for the AI. |
| `getPrompt` | `getPrompt(self, has_previous_json_failed: bool = False) -> str` | Returns the full prompt (internal). |

## Answer

From `rocketride.schema`. Parses chat response content — see
[Chat](/clients/python/chat#parse-the-response-with-answer) for semantics.

| Member | Signature | Description |
| --- | --- | --- |
| `setAnswer` | `setAnswer(self, value: str \| dict \| list)` | Stores the response value, validating/parsing it as JSON when `expectJson` is `True`. |
| `getText` | `getText(self) -> str` | The answer as plain text. |
| `getJson` | `getJson(self) -> Optional[dict]` | The parsed JSON. Returns `None` only when no answer has been set; **raises `ValueError`** on invalid JSON. |
| `isJson` | `isJson(self) -> bool` | Returns the `expectJson` flag (does not inspect content). |
| `parsePython` | `parsePython(self, value: str) -> Any` | Extracts Python code from a code block in the response. |
| `tokens` | field | Turn-total LLM token usage reported by the server. The TypeScript `Answer` carries no usage field. <!-- language-specific --> |

## Types

- **PIPELINE_RESULT**: TypedDict with `name`, `path`, `objectId`, optional `result_types`, and dynamic fields.
- **UPLOAD_RESULT**: Per-file result with `action`, `filepath`, `error?`, `result?`, `upload_time?`, etc.
- **TASK_STATUS**: Task status with `completedCount`, `totalCount`, `completed`, `state`, `exitCode`, and many more fields.
- **ConnectResult**: Identity payload returned by `connect()`/`login()` — `userToken`, `userId`, `displayName`, organizations, apps, teams (all optional).
- **DAPMessage**: Dict with `type`, `seq`, and optional `command`, `arguments`, `body`, `success`, `message`, `event`, `token`, etc.
- **PipelineConfig**: Pipeline definition with `name`, `description`, `version`, `components`, `source`, `project_id`.
- **QuestionHistory**: `{ 'role': str, 'content': str }`.
- **QuestionExample**: `{ 'given': str, 'result': str }`.
- **QuestionType** / **QuestionText**: question kind enum and text wrapper from `rocketride.schema`.
- **Deploy types**: `DeployArtifact`, `Deployment`, `DeploymentSchedule`, `DeployActor`, `DeployHistoryEntry`, `PublishResult`, `DeployListResult`, `DeployVersionsResult`, `DeployHistoryResult`, `SchedulePreview` (from `rocketride.types`).

### Additional client surface

Further public methods, present in both SDKs, in brief:

| Area | Methods |
| --- | --- |
| Generic invoke | `call(command, ...)` — any DAP command; `tool(...)` — invoke a pipeline tool function <!-- language-specific --> |
| Task helpers | `get_task_token`, `get_task_pipeline`, `restart` |
| Identity | `get_account_info`; static `get_server_info`, `normalize_uri` |
| Monitors | `clear_all_monitors`, `identify` (plus `add_monitor`/`remove_monitor` above) |
| Template storage | `save_template`, `get_template`, `delete_template`, `get_all_templates` |
| Log storage | `save_log`, `get_log`, `delete_log`, `list_logs` |
| Dashboard | `get_dashboard`, `list_connections`, `list_tasks` |
| Profiling | `cprofile_start`, `cprofile_stop`, `cprofile_status`, `cprofile_report`, `cprofile_report_tree` |
| Namespaces | `client.account`, `client.billing` (account and billing APIs) |

## Advanced: low-level DAP

For commands not covered by the typed surface.

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `build_request` | `def build_request(self, command: str, *, token: str = None, arguments: dict = None, data: bytes \| str = None) -> dict` | `dict` | Builds a DAP request message. |
| `request` | `async def request(self, request: dict, timeout: float = None) -> dict` | `dict` | Sends the request and returns the response. `timeout` in ms overrides the default for this call. Use `did_fail(response)` before trusting `body`. |
| `dap_request` | `async def dap_request(self, command: str, arguments: dict = None, token: str = None, timeout: float = None) -> dict` | `dict` | Shorthand: builds and sends in one call. Python-only — in TypeScript, compose `buildRequest()` + `request()`. <!-- language-specific --> |
| `did_fail` | `def did_fail(self, request: dict) -> bool` | `bool` | `True` when the response indicates failure (`success === False`). |

```python
# Two-step (build then request)
req = client.build_request('rrext_monitor', token=token, arguments={'types': ['apaevt_status_upload']})
res = await client.request(req, timeout=5000)

# One-step with dap_request
res = await client.dap_request('rrext_services', {}, timeout=5000)

if client.did_fail(res):
    raise RuntimeError(res.get('message', 'Request failed'))
```


---

# File Storage

Route: /clients/python/storage

---
title: File Storage
sidebar_position: 6
---

# File Storage

Read, write, and manage files in your account's server-side store. All paths are
**relative** to the store root (e.g. `"docs/readme.md"`); `..` traversal is
rejected client-side, and `fs_rmdir`, `fs_rename`, `fs_get_url`, and
`fs_read_many` additionally reject absolute-like paths (leading `/` or `\`). Method tables in the
[API reference](/clients/python/reference#store-file-access).

## Strings and JSON (start here)

The convenience wrappers manage the handle lifecycle for you:

```python
await client.fs_write_string('notes/todo.txt', 'buy milk')
text = await client.fs_read_string('notes/todo.txt')

await client.fs_write_json('config/app.json', {'debug': True})
cfg = await client.fs_read_json('config/app.json')
```

## Browse and inspect

```python
listing = await client.fs_list_dir('reports')  # {entries: [{name, type, size?, modified?}], count}
for entry in listing['entries']:
    print(entry['name'], entry['type'])

meta = await client.fs_stat('reports/q3.pdf')  # {exists, type, size, modified}
await client.fs_mkdir('reports/2026')
await client.fs_rename('reports/q3.pdf', 'archive/q3.pdf')
await client.fs_delete('archive/q3.pdf')
await client.fs_rmdir('reports/2026', recursive=True)
```

`fs_rename` moves files or directories (copy+delete on object stores, recursive for
directories). `fs_rmdir` raises `ValueError` on empty or absolute-like paths.

## Binary I/O (handles)

For large or binary files, use the explicit handle lifecycle — `fs_open` →
`fs_read`/`fs_write` → `fs_close`, in up-to-4 MB chunks. `fs_close` must receive the
same mode as `fs_open`.

```python
info = await client.fs_open('uploads/video.mp4', 'w')
handle = info['handle']
try:
    with open('video.mp4', 'rb') as f:
        while chunk := f.read(4_194_304):
            await client.fs_write(handle, chunk)
finally:
    await client.fs_close(handle, 'w')
```

Read mode's `fs_open` result also includes `'size'`; an empty `bytes` from
`fs_read` means EOF.

## Batch reads

`fs_read_many(paths)` fetches many small files in **one** round trip (max 256 paths
/ 32 MiB total per call). Missing or unreadable files come back as per-entry results
(`ok: False` + `error`), never a call failure; results arrive in request order with
`data` as `bytes`.

## Direct URLs

`fs_get_url(path, expires_in=3600, download_name=None)` returns a time-limited
HTTP(S) URL for direct browser access. Cloud backends (S3/Azure) return a
presigned/SAS URL; the local filesystem backend returns a JWT-signed `/task/fetch`
URL. Served **inline** by default — right for streaming and `<img>`/`<video>`
sources:

```python
stream_url = await client.fs_get_url('uploads/video.mp4', expires_in=600)
```

Pass `download_name` to force a download with that filename via
`Content-Disposition: attachment` — the only reliable way to set the download
filename for cross-origin cloud URLs (where the browser `<a download>` hint is
ignored):

```python
download_url = await client.fs_get_url('uploads/video.mp4', download_name='my video.mp4')
```


---

# TypeScript SDK

Route: /clients/typescript

---
title: TypeScript SDK
sidebar_position: 0
sidebar_label: Overview
---

import { LuSettings, LuPlug, LuPlay, LuRocket, LuSend, LuFolderOpen, LuMessageSquare, LuActivity, LuShieldAlert, LuBookOpen, LuFlaskConical, LuChartLine, LuDatabase } from 'react-icons/lu';

# TypeScript SDK

Build, run, and manage AI pipelines from Node.js or the browser. The `rocketride`
package ships complete type definitions and speaks the engine's native
[WebSocket protocol](/connect/websocket): you author a `.pipe`
([visually](/clients/vscode) or [by hand](/reference/pipeline-reference)) and run it
against the engine from your own application.

## Install

```bash
npm install rocketride    # or: yarn add rocketride / pnpm add rocketride
```

The [`rocketride` CLI](/connect/cli) is installed with the package.

## Quickstart

```typescript
import { RocketRideClient } from 'rocketride';

const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'https://api.rocketride.ai',
});
await client.connect();
const { token } = await client.use({ filepath: './pipeline.pipe' });
const result = await client.send(token, 'Hello, pipeline!', { name: 'input.txt' }, 'text/plain');
console.log(result);
await client.terminate(token);
await client.disconnect();
```

`send()` / `sendFiles()` target pipelines whose **source** is `webhook` or
`dropper`; if your pipeline source is `chat`, use
[`client.chat()`](/clients/typescript/chat). No pipeline yet? The
[IDE walkthrough](/quickstart/ide-walkthrough) builds one in minutes.

## Explore the SDK

<div className="rr-card-grid">

<a className="rr-side-card" href="/clients/typescript/configuration">
  <span className="rr-side-card__head"><LuSettings className="rr-card-icon" /><span className="rr-side-card__title">Configuration</span></span>
  <span className="rr-side-card__body">Client config, environment variables, timeouts, and reconnection.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/connection">
  <span className="rr-side-card__head"><LuPlug className="rr-card-icon" /><span className="rr-side-card__title">Connection</span></span>
  <span className="rr-side-card__body">The attach/login layers, persist mode, concurrent-login semantics, and callbacks.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/pipelines">
  <span className="rr-side-card__head"><LuPlay className="rr-card-icon" /><span className="rr-side-card__title">Running Pipelines</span></span>
  <span className="rr-side-card__body">Start with <code>use()</code>, watch progress, validate, and terminate.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/deploy">
  <span className="rr-side-card__head"><LuRocket className="rr-card-icon" /><span className="rr-side-card__title">Deployments</span></span>
  <span className="rr-side-card__body">Publish immutable versions, point team environments at them, and schedule runs.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/data">
  <span className="rr-side-card__head"><LuSend className="rr-card-icon" /><span className="rr-side-card__title">Sending Data</span></span>
  <span className="rr-side-card__body">One-shot sends, concurrent file uploads with progress, and chunked streaming.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/storage">
  <span className="rr-side-card__head"><LuFolderOpen className="rr-card-icon" /><span className="rr-side-card__title">File Storage</span></span>
  <span className="rr-side-card__body">Read, write, and manage your server-side store; signed URLs for direct access.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/chat">
  <span className="rr-side-card__head"><LuMessageSquare className="rr-card-icon" /><span className="rr-side-card__title">Chat</span></span>
  <span className="rr-side-card__body">Build a <code>Question</code>, stream the response, parse it with <code>Answer</code>.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/logs">
  <span className="rr-side-card__head"><LuActivity className="rr-card-icon" /><span className="rr-side-card__title">Run Logs</span></span>
  <span className="rr-side-card__body">The log continuum and the DVR session: live monitoring and replay with one API.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/errors">
  <span className="rr-side-card__head"><LuShieldAlert className="rr-card-icon" /><span className="rr-side-card__title">Error Handling</span></span>
  <span className="rr-side-card__body">What the SDK throws, when, and how to catch it.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/reference">
  <span className="rr-side-card__head"><LuBookOpen className="rr-card-icon" /><span className="rr-side-card__title">API Reference</span></span>
  <span className="rr-side-card__body">Every public class and method, in one place.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/examples">
  <span className="rr-side-card__head"><LuFlaskConical className="rr-card-icon" /><span className="rr-side-card__title">Examples</span></span>
  <span className="rr-side-card__body">Seven complete programs, from hello-pipeline to custom DAP requests.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/database-sequelize">
  <span className="rr-side-card__head"><LuDatabase className="rr-card-icon" /><span className="rr-side-card__title">Sequelize over Pipelines</span></span>
  <span className="rr-side-card__body">A Sequelize ORM whose SQL rides a pipeline instead of a TCP socket.</span>
</a>

<a className="rr-side-card" href="/clients/typescript/analytics">
  <span className="rr-side-card__head"><LuChartLine className="rr-card-icon" /><span className="rr-side-card__title">Analytics</span></span>
  <span className="rr-side-card__body">Report client-side analytics events through the SDK.</span>
</a>

</div>

## Links

- [GitHub](https://github.com/rocketride-org/rocketride-server) · [npm](https://www.npmjs.com/package/rocketride) · [Discord](https://discord.gg/PMXrtenMsY)
- [Release notes](/support/release-notes) · [Get help](/support/get-help)


---

# Analytics

Route: /clients/typescript/analytics

---
title: Analytics
sidebar_position: 12
---

- [Overview](#overview)
- [Import](#import)
- [API](#api)
- [Event Names](#event-names)
- [What This Module Is Not](#what-this-module-is-not)

## **Overview**

`rocketride/analytics` is the one shared event-report function, bare bones by
design. Apps call `report(event, props)` with any string event name and a
free-form props bag. There is no central event list: **each app owns its own
taxonomy** (home-ui keeps its event names in the home-ui repo, the VS Code
extension keeps its own, and so on). What the shared layer guarantees is that
every reported event carries an `app` property identifying the emitting app
(`home-ui`, `rocket-ui`, …), so downstream analytics can always segment by app.
The Python mirror lives at `rocketride.analytics` in the Python SDK.

## **Import**

```typescript
import { initReport, report, type ReportSink } from 'rocketride/analytics';
```

## **API**

```typescript
// Once, at app init: wire the emitting app id + transport.
initReport('home-ui', (event, props) => posthog.capture(event, props));
// or, on the product side:
// Once, at app init: wire the emitting app id + transport. The sink is
// whatever function your app uses to ship events (HTTP, queue, logger, ...).
initReport('rocket-ui', (event, props) => mySink.send(event, props));

// Anywhere after that:
report('nav:click', { target: 'pricing' });
// → sink receives ('nav:click', { app: 'home-ui', target: 'pricing' })
```

- `initReport(app, sink)` — stores the app id and transport. Call once per app.
- `report(event, props?)` — forwards to the sink with `app` stamped into the
  props. Enforcement is string-ish only: a non-string or empty event name is a
  silent no-op, and nothing else is validated. Before `initReport` runs (and in
  builds where telemetry is unconfigured) it is a safe no-op. It never throws —
  telemetry must never break the app.

## **Event Names**

By convention event names are `object:action` — lowercase, colon-separated
(`chat:message_sent`, `store:app_add`). The convention is documentation, not
enforcement: `report()` accepts any string so an app can evolve its taxonomy
without touching this module. Each app should keep its own documented event
list next to its call sites.

## **What This Module Is Not**

It is not a taxonomy and not a transport. There is no event-name union, no
typed property shapes, no PostHog dependency, and no network I/O — the sink an
app injects does the sending. An earlier revision centralised a strict,
compile-time-checked cross-app event taxonomy here; that was removed in favour
of per-app taxonomies and this loose core.


---

# Chat

Route: /clients/typescript/chat

---
title: Chat
sidebar_position: 7
---

# Chat

Conversational pipelines: build a `Question`, send it with `client.chat()`, and
parse the response with `Answer`. Class tables in the
[API reference](/clients/typescript/reference#question).

Chat is the conversational lane: it works against `chat`, `webhook`, and
`dropper` pipeline sources. Under the hood the
client opens a pipe with MIME type `application/rocketride-question`, writes the
serialized `Question`, closes the pipe, and returns the server result.

## Build a Question

```typescript
import { Question } from 'rocketride';

const question = new Question({ expectJson: true });
question.addInstruction('Format', 'Return a JSON object with keys: summary, keywords.');
question.addExample('Summarize X', { summary: '...', keywords: ['a', 'b'] });
question.addQuestion('Summarize the main points and list keywords.');
```

`new Question({ type?, filter?, expectJson?, role? })` — `QuestionType` is one of
`QUESTION`, `SEMANTIC`, `KEYWORD`, `GET`, `PROMPT` (default `QUESTION`). Steer the
model with `addInstruction`, `addExample`, `addContext`, `addHistory` (for
multi-turn), `addDocuments`, `addGoal`, and `addQuestion`.

## Send it

```typescript
const response = await client.chat({ token, question });
```

`chat({ token, question, onSSE? })` — the optional `onSSE` callback streams
server-sent events (token-by-token output) as they arrive. The final answer is in
the result body.

## Parse the response with Answer

`Answer` extracts structure from AI text, which often arrives wrapped in markdown
or code fences. The client does **not** attach an `Answer` to the result — you read
the body and feed it in:

```typescript
import { Answer } from 'rocketride';

const answerText = response?.answers?.[0];
const answer = new Answer(true); // expectJson
answer.setAnswer(answerText ?? '');
const structured = answer.isJson() ? answer.getJson() : answer.getText();
```

Semantics worth knowing:

- `new Answer(expectJson = false)` — construct with `true` when you asked the model
  for JSON; `setAnswer()` then validates/parses the content as JSON.
- `isJson()` returns the `expectJson` flag the `Answer` was constructed with — it
  does **not** inspect the content.
- `getJson()` returns the parsed JSON and **throws** if the stored answer is not
  JSON-compatible; `getText()` returns plain text.
- `Answer.parsePython(value)` (static) extracts Python code from a code block.

A complete chat program is [example 6](/clients/typescript/examples#6-chat-question-with-instructions-and-examples-parse-json-answer).


---

# Configuration

Route: /clients/typescript/configuration

---
title: Configuration
sidebar_position: 1
---

# Configuration

Everything `RocketRideClientConfig` accepts, the environment variables the client
reads, and how its timeouts, reconnection, and debug hooks behave.

## Constructor

```typescript
import { RocketRideClient } from 'rocketride';

const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'https://api.rocketride.ai',
	persist: true,
});
```

`new RocketRideClient(config = {})` creates the instance; it does **not** open a
connection until you call `attach()`, `login()`, or
[`connect()`](/clients/typescript/connection).

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `auth` | `string` | — | Initial API key. Optional: omit and use `env.ROCKETRIDE_APIKEY`, or pass a credential directly to `login()`/`connect()`. |
| `uri` | `string` | RocketRide Cloud | Initial server URI (e.g. `https://api.rocketride.ai` or `ws://localhost:5565`). Optional: omit and use `env.ROCKETRIDE_URI` or the built-in Cloud default; `attach()`, `login()`, and `connect()` accept URI overrides. |
| `env` | `Record<string, string>` | `process.env` strings | Environment override used for `${ROCKETRIDE_*}` substitution and credential/URI defaults. In Node the SDK copies string values from `process.env`; it does **not** load `.env` files. |
| `persist` | `boolean` | `false` | Automatic reconnection with capped linear backoff. See [Reconnection](#reconnection). |
| `maxRetryTime` | `number` | — | Accepted for backward compatibility but **ignored**. Reconnection has no time limit; stop it explicitly with `detach()` or `disconnect()` (`logout()` keeps the anonymous attachment reconnecting). |
| `requestTimeout` | `number` | — | Default timeout in **ms** per request; overridable per `request()` call. |
| `module` | `string` | `CLIENT-0`, `CLIENT-1`, … | Client name for logging. |
| `wsPath` | `string` | `'/task/service'` | WebSocket path override. Model-server clients pass `'/models'`. |
| `clientName` / `clientVersion` | `string` | SDK name/version | Display identity reported to the server. |
| `public` | `boolean` | `false` | Reserved: declared but not currently consumed by the client. For unauthenticated public calls, [`attach()`](/clients/typescript/connection) without logging in. |

## Callbacks

| Property | Signature | Description |
| --- | --- | --- |
| `onConnected` | `(info?: string) => Promise<void>` | Called exactly once per accepted authenticated connection generation, after authentication and best-effort monitor restoration. |
| `onDisconnected` | `(reason?: string, hasError?: boolean) => Promise<void>` | Called at most once per generation, and only if that generation previously published `onConnected`. A failed or cancelled pre-authentication attempt does not call it. Do not call `disconnect()` here if you want persistent reconnection. |
| `onConnectError` | `(error: ConnectionException) => void \| Promise<void>` | Called for automatic reconnect failures; the next retry waits for this callback. Foreground `login()`/`connect()` failures reject their promises directly. Authentication failure stops automatic retries. |
| `onEvent` | `(event: DAPMessage) => Promise<void>` | Called for each server event (upload progress, task status, …). Event type is `event.event`, payload in `event.body`. Subscribe per-task with [`addMonitor`](/clients/typescript/pipelines#events). |
| `onTrace` | `(type: TraceType, message: DAPMessage) => void` | Called around high-level SDK requests with a credential-redacted message copy — for logging or telemetry. |
| `onProtocolMessage` | `(message: string) => void` | Credential-redacted DAP messages, for protocol debugging. |
| `onDebugMessage` | `(message: string) => void` | Debug output. |

```typescript
const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'wss://api.rocketride.ai',
	persist: true,
	requestTimeout: 30000,
	onConnected: async () => setStatus('connected'),
	onDisconnected: async () => setStatus('disconnected'),
	onConnectError: (error) => setStatus('error', error.message),
	onEvent: async (e) => handleServerEvent(e),
});
```

## Reconnection

With `persist: true`, an unexpected loss schedules a background reconnect using
**linear backoff**: 250 ms, 500 ms, 750 ms, and so on to a 15-second cap — and it
**never gives up**. A successful foreground login resets the delay. Foreground
`attach()`, `login()`, or `connect()`, URI changes, `logout()`, `detach()`, and
`disconnect()` invalidate stale timers, so stale callbacks cannot publish state.
Authentication failures are **not** retried automatically — fix credentials and call
`login()`/`connect()` again.

## Environment variables

| Variable | Description |
| --- | --- |
| `ROCKETRIDE_URI` | Server URI (e.g. `wss://api.rocketride.ai` or `ws://localhost:5565`) |
| `ROCKETRIDE_APIKEY` | API key, consulted by `login()` when no explicit credential is supplied |
| `ROCKETRIDE_TOKEN` | User token, accepted by the [CLI](/connect/cli) as an alternative credential |

The same map drives `${ROCKETRIDE_*}` substitution inside pipeline configs passed to
`use()` (`validate()` does not substitute). Replace it at runtime with `setEnv()`.

## Timeouts

`requestTimeout` (config) sets the default for every DAP request;
[`request(..., timeout)`](/clients/typescript/reference#advanced-low-level-dap)
overrides it per call. `attach()`, `login()`, and `connect()` accept a per-call
`{ timeout }` for the handshake. All timeouts are in milliseconds.


---

# Connection

Route: /clients/typescript/connection

---
title: Connection
sidebar_position: 2
---

# Connection

How the client attaches, authenticates, stays connected, and shuts down. The full
method tables live in the [API reference](/clients/typescript/reference#connection).

## The layered model

The connection has two layers you can drive together or separately:

- **Attach** opens the WebSocket without authenticating — public `rrext_public_*`
  requests are available on an anonymous attachment.
- **Login** authenticates over the attachment, restores monitor subscriptions, and
  returns a `ConnectResult` carrying your full identity (user, organizations, apps,
  teams).

`connect()` performs attach + login as one foreground operation; `disconnect()` does
a best-effort logout, cancels pending work, and detaches. The state probes mirror
the layers: `isAttached()` (socket open), `isAuthenticated()` (auth succeeded), and
`isConnected()` — a compatibility **alias for `isAttached()`**; it does not imply
authentication.

```typescript
const result = await client.connect();
console.log(result.displayName);

await client.logout(); // drop auth, keep an anonymous attachment
await client.login('other-credential'); // re-auth on the same connection
await client.detach(); // tear down the socket
```

For UIs that need anonymous public calls before sign-in: `attach()`, then
`login()`, and `logout()` to return to a fresh anonymous attachment. `login()` also
accepts an OAuth code exchange (`{ code, verifier, redirectUri }`) as the
credential.

## Concurrent logins

Concurrent foreground `login()`/`connect()` calls for the same endpoint and
credential **join** one operation: one attachment, one auth request, one result. A
different foreground login **supersedes** the earlier one, and foreground work
always supersedes background reconnects (never the reverse). Superseded waiters
reject with `LoginAttemptCancelledError('superseded')`; the error's `reason` is
exactly `'superseded'`, `'logout'`, or `'detached'`. An unsolicited transport loss
during login rejects with `ConnectionException` instead. See
[Error Handling](/clients/typescript/errors).

## Scoped disconnect

The client supports `await using` (`Symbol.asyncDispose`) for automatic disconnect
when leaving scope, and `RocketRideClient.withConnection()` for one-off scripts:

```typescript
const status = await RocketRideClient.withConnection({ auth: 'my-key', uri: 'wss://api.rocketride.ai' }, async (client) => {
	const { token } = await client.use({ pipeline: myPipelineConfig });
	await client.send(token, JSON.stringify({ data: 1 }));
	return await client.getTaskStatus(token);
});
```

> Python's counterpart to scoped disconnect is the
> [async context manager](/clients/python/connection#context-manager-recommended).

## URI scheme

The scheme selects the transport: `https://` and `wss://` resolve to a secure
`wss://` connection, while `http://`, `ws://`, and a bare `host:port` resolve to
plain `ws://`. For RocketRide Cloud use `https://api.rocketride.ai` (or
`wss://api.rocketride.ai`); for a local engine use `ws://localhost:5565`.

**Caution:** against a Cloud endpoint always use `https://` or `wss://` — an
`http://` or `ws://` URI (or a bare `host:port`) silently downgrades to an
unencrypted `ws://` connection.

## Staying connected

With `persist: true` the client survives drops — linear backoff (250 ms steps,
15 s cap), never gives up, auth failures excepted. Wire the
[lifecycle callbacks](/clients/typescript/configuration#callbacks) to observe it:

```typescript
const client = new RocketRideClient({
	auth: apiKey,
	uri: serverUri,
	persist: true,
	onConnected: async () => updateUI({ state: 'connected' }),
	onDisconnected: async (reason, hasError) => updateUI({ state: 'disconnected', reason, hasError }),
	onConnectError: (error) => updateUI({ state: 'error', message: error.message }),
});
await client.connect();
```

Use `onDisconnected` for "we were connected and then dropped"; use
`onConnectError` for "failed to connect". Only call `detach()` or `disconnect()`
when reconnection should stop.

## Inspecting state

`getConnectionInfo()` returns `{ connected, transport, uri }` — useful for a
"Connected to …" display. `getApiKey()` returns the key in use (debugging only;
avoid logging it). `setEnv()` replaces the environment map used for
`${ROCKETRIDE_*}` substitution and credential lookup.


---

# Sending Data

Route: /clients/typescript/data

---
title: Sending Data
sidebar_position: 5
---

# Sending Data

Get data into a running pipeline: one-shot sends, concurrent file uploads with
progress, and chunked streaming. Method tables in the
[API reference](/clients/typescript/reference#data).

`send()` / `sendFiles()` / `pipe()` target pipelines whose **source** is `webhook`
or `dropper`. If your pipeline source is `chat`, use
[`client.chat()`](/clients/typescript/chat) instead.

## One-shot: `send()`

Use when you have the full payload in memory. It opens a pipe, writes once, closes,
and resolves to the pipeline result:

```typescript
const result = await client.send(token, 'Hello, pipeline!', { name: 'greeting.txt' }, 'text/plain');
```

If the MIME type is omitted the payload is sent as `application/octet-stream` —
there is no auto-detection. An optional `onSSE` callback receives server-sent
events for the transfer.

## Files: `sendFiles()`

Uploads browser `File` objects through a worker pool capped at `maxConcurrent`
(default 5, validated positive integer). Results resolve in the same order as
`files`:

```typescript
const files = [new File([content1], 'a.md'), new File([content2], 'b.md')];
const uploadResults = await client.sendFiles(
	files.map((file) => ({ file })),
	token
);
console.log('Uploaded:', uploadResults.filter((r) => r.action === 'complete').length);
```

Each entry is `{ file, objinfo?, mimetype? }`. Watch progress by subscribing to
`apaevt_status_upload` events ([Events](/clients/typescript/pipelines#events))
— bodies carry `filepath`, `bytes_sent`, `file_size`.

## Streaming: `pipe()`

Use `pipe()` when data arrives incrementally or is too large to hold in memory. One
streaming upload is **open → write (one or more) → close**; `close()` resolves to
the processing result and is a no-op if already closed. Writes take `Uint8Array`
chunks.

```typescript
const pipe = await client.pipe(token, { name: 'large.csv' }, 'text/csv');
await pipe.open();
const rl = createInterface({ input: createReadStream('large.csv') });
for await (const line of rl) {
	await pipe.write(new TextEncoder().encode(line + '\n'));
}
const result = await pipe.close();
```

Getters: `isOpened` and `pipeId` (server-assigned after `open()`). `pipe()` and the
pipe itself accept an `onSSE` callback for server-sent events, and
`DataPipe.tool()` invokes a pipeline tool function through the pipe — see the
[reference](/clients/typescript/reference#datapipe).

## Choosing

| You have | Use |
| --- | --- |
| A string or `Uint8Array` in memory | `send()` |
| Browser `File` objects, want per-file results + progress events | `sendFiles()` |
| Chunked/incremental data, or very large payloads | `pipe()` |
| A chat-source pipeline | [`chat()`](/clients/typescript/chat) |


---

# Sequelize over Pipelines

Route: /clients/typescript/database-sequelize

---
title: Sequelize over Pipelines
sidebar_position: 13
---

# Sequelize over Pipelines

`client.database.sequelize(options)` builds a [Sequelize v6](https://sequelize.org/)
ORM instance whose Postgres dialect transports SQL over a RocketRide pipeline
instead of a TCP socket. No pg connection is opened — every `findAll`, `create`,
`update`, `destroy`, and raw query is forwarded through the pipeline's `execute`
tool function, and transactions ride the `begin`/`commit`/`rollback` tool
functions.

This lets browser and Node.js apps use familiar Sequelize model semantics
(`Model.findAll`, `Model.create`, `sequelize.transaction`) while the actual SQL
runs inside the pipeline on the server side.

> **Requirement:** the target database node must have `allow_execute: true` set in
> its pipeline configuration. The same flag also gates transactions
> (`begin`/`commit`/`rollback`) — no additional configuration is needed.

> **TypeScript-only.** The Python SDK has the same raw database surface
> (`client.database` with `query`/`begin_transaction`/`commit`/`rollback`) but no
> ORM binding.

## Method signature

```typescript
client.database.sequelize(options: {
  Sequelize: SequelizeConstructor;
  token: string;
  nodeId?: string;
  sequelizeOptions?: import('sequelize').Options;
}): Sequelize
```

> **Why `Sequelize` is passed in:** `sequelize` is a peer dependency, not a hard
> dependency, of the `rocketride` client. It transitively depends on Node built-ins
> (`util`, `debug`) that cannot be bundled for browser targets. Importing
> `Sequelize` yourself and passing the class in keeps `rocketride` safe to bundle
> in browser apps that never touch this method.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `Sequelize` | `SequelizeConstructor` | Yes | The `Sequelize` class, from `import { Sequelize } from 'sequelize'`. |
| `token` | `string` | Yes | Pipeline task token from [`use()`](/clients/typescript/pipelines). |
| `nodeId` | `string` | No | Target database node ID. When omitted, the first database node in the pipeline handles queries. |
| `sequelizeOptions` | `Options` | No | Extra Sequelize options merged over the defaults (e.g. `logging`, `define`). |

## Prerequisites

1. A running pipeline with a database node configured with `allow_execute: true`.
2. A pipeline token obtained from `client.use()`.
3. `sequelize` installed as a peer dependency (`npm install sequelize`).

## Define a model and query rows

```typescript
import { RocketRideClient } from 'rocketride';
import { Sequelize, DataTypes } from 'sequelize';

const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'wss://api.rocketride.ai',
});
await client.connect();

const { token } = await client.use({ filepath: './db-pipeline.pipe' });

// Build a Sequelize instance backed by the RocketRide pipeline
const sequelize = client.database.sequelize({ Sequelize, token, nodeId: 'my-postgres-node' });

// Define a model — no sync needed; table must exist in the target DB
const User = sequelize.define(
	'User',
	{
		id: { type: DataTypes.INTEGER, primaryKey: true },
		name: { type: DataTypes.STRING },
		email: { type: DataTypes.STRING },
		active: { type: DataTypes.BOOLEAN },
	},
	{ tableName: 'users', timestamps: false }
);

// Query rows
const users = await User.findAll({ where: { active: true }, limit: 10 });
console.log(users.map((u) => u.toJSON()));

await client.terminate(token);
await client.disconnect();
```

## Transactions

Transactions are forwarded through the pipeline's `begin`/`commit`/`rollback` tool
functions. Use `sequelize.transaction()` exactly as you would with a normal
Sequelize instance:

```typescript
const sequelize = client.database.sequelize({ Sequelize, token, nodeId: 'my-postgres-node' });

await sequelize.transaction(async (t) => {
	await sequelize.query('UPDATE accounts SET balance = balance - 100 WHERE id = :from', {
		replacements: { from: 1 },
		transaction: t,
	});
	await sequelize.query('UPDATE accounts SET balance = balance + 100 WHERE id = :to', {
		replacements: { to: 2 },
		transaction: t,
	});
	// If this callback throws, the transaction is automatically rolled back.
});
```

## Standalone factory (advanced)

If you are not using `RocketRideClient` directly (e.g. in a React hook that already
has a client from `useShellConnection()`), import the `createSequelize` factory:

```typescript
import { createSequelize } from 'rocketride';
import { Sequelize } from 'sequelize';

// client is the RocketRideClient instance from your shell context
const sequelize = createSequelize({
	Sequelize,
	db: client.database,
	token: myToken,
	nodeId: 'my-postgres-node',
});

const [rows] = await sequelize.query('SELECT * FROM products WHERE category = :cat', {
	replacements: { cat: 'electronics' },
});
console.log(rows);
```

`CreateSequelizeOptions` is also exported for TypeScript consumers that pass the
options object separately.

## Related

- `client.database.query()` — raw SQL without the ORM layer
  ([reference](/clients/typescript/reference#database)).
- `client.database.beginTransaction()` — manual transaction management.
- [`use()`](/clients/typescript/pipelines) — start the pipeline that carries the
  SQL.


---

# Deployments

Route: /clients/typescript/deploy

---
title: Deployments
sidebar_position: 4
---

# Deployments

Persist pipelines server-side and run them on a schedule. Accessed via
`client.deploy`; full method tables in the
[API reference](/clients/typescript/reference#deploy-clientdeploy).

## Teams as environments

`deploy.add` snapshots a pipeline as an **immutable, sha256-locked artifact
version** in the org registry; `deploy.deploy` points a **team** (the environment —
Staging, Production, …) at a version. Promotion and rollback are the same pointer
move. Deploy targets are always explicit — there is no default-team fallback. Every
registry add and pointer change lands in an immutable audit history (`deploy.history`,
rows carry `seq` as the stable append-order identity).

```typescript
const result = await client.deploy.add({ pipeline: myPipeline, comment: 'v2 prompt fix' });
await client.deploy.deploy('proj-1', result.artifact.version, 'team-staging');
await client.deploy.setSchedule('proj-1', 'webhook_1', '*/15 * * * *', 'team-staging');

// Promote the same version to Production later — the identical gesture.
await client.deploy.deploy('proj-1', result.artifact.version, 'team-prod');

const live = await client.deploy.list();
for (const dep of live.rows) {
	console.log(dep.teamId, dep.projectId, 'v', dep.version, dep.state);
}
```

`add({ pipeline, deployTo })` collapses add + deploy into one step.
Listings (`deploy.list`, `deploy.versions`, `deploy.history`) return the standard
`{ rows, total, page, pageSize }` envelope, server-paged.
`deploy.artifact(projectId, version)` fetches one immutable version's pipeline
JSON, sha256-verified server-side.

## Schedules

`deploy.setSchedule(projectId, sourceId, schedule, teamId, options?)` sets (or
clears with `null`/`'manual'`) one source's 5-field cron schedule.
`pauseSchedule`/`resumeSchedule` stop and restart a single source's firing without
touching its cron. `deploy.preview(schedule, count?)` is **the** single cron
evaluator — validity plus next occurrences; never parse cron client-side.

Scheduled runs execute **as the team** (no stored user credential); their logs
land in the team's [run-log continuum](/clients/typescript/logs), readable by
teammates via `client.log` with `teamId`. `deploy.run(projectId, sourceId, teamId)`
triggers one deployed source **now** — the same trusted, actor-free team dispatch
the scheduler uses — returning `{ token, version }`, and
`deploy.setSourceConfig` sets per-source execution settings for deploy runs
(`traceLevel`, `debugOut`).

## States

| State | Meaning |
| --- | --- |
| `enabled` | Schedules fire per cron. |
| `disabled` | The kill switch (`deploy.disable`) — nothing runs until enabled again. |
| `errored` | A scheduled dispatch failed — on permissions, or on an unusable artifact (missing or sha256-tampered) — and the scheduler stopped retrying. |
| `removed` | Soft delete (`deploy.remove`): hidden from listings, history and artifacts survive; re-deploying revives it. |

## Permissions

Mutations require `task.control` on the TARGET team. Reads follow the visibility model: an org admin sees every team and every personal space; a user sees their own personal space and the teams they are a member of.

## App publish ladder

Typed wrappers over `rrext_deploy_app` — the publish ladder for RocketRide apps.
**Deploy** copies code to the server as the next immutable registry version
(`deploy.add`); a deployment carries the review lifecycle in its own `state`
(`private` → `submit` → `ready` | `rejected`). **Publish** binds a deployment
to an audience — `@me`, `@team/<name>`, or `@public` — as a pure pointer (`@user` is a legacy input alias for `@me`, never displayed);
repointing it covers first publish, update, promote, and rollback alike.

The review state lives on the **deployment**, not the binding: an app deploys
`private` (internal-eligible), the developer `submit`s it for review, an admin
approves (`ready`) or rejects (`rejected`). A `@public` binding may only point
at a `ready` deployment; `@me`/`@team` bindings accept any internal-eligible
(not `failed`) deployment. So there is no separate "publish-and-wait" — public
listing is: submit → approve → repoint the public pointer.

App ids are partitioned by the caller org's **developer id**: every app is
`<developerId>.<name>` (globally unique), so an org can only deploy/publish
ids inside its own namespace — the platform holds `rocketride`. Deploying or
publishing an app requires the org to have claimed a developer id.

`deploy.add` and `deploy.addApp` live on `client.deploy`; every other verb
below is a method on the client itself (`client.listDeployments(...)`,
`client.publishApp(...)`), not on `client.deploy`.

| Method | Description |
| --- | --- |
| `deploy.add` | The ONE rail door: deploy any kind of object as the next immutable registry version. `kind:'pipe'` (default) takes a `pipeline` dict; `kind:'app'` takes ONE `data` zip of the app's SOURCE — the server performs the build (client-produced binaries are never trusted); the zip is retained and unpacked at receipt, born deployment-state `private`. The app id must be inside your developer namespace. |
| `deploy.addApp` | Pack an app folder's source and deploy it as the next registry version — the one call behind the App Builder's Deploy button and CI scripts. Packs by the App Builder rules (workspace-rooted zip, `appManifest.include`, hierarchical gitignore + the hard node_modules/dist/.git baseline, symlink containment, 50MB zipped / 512MB uncompressed caps); `onProgress` receives one line per step. Deploying activates nothing — bind an audience with `publishApp` afterwards. |
| `deploy.verifyApp` | The no-side-effect precheck for `addApp` — purely local, no server call: manifest shape and id grammar, declared icon/README assets, `appManifest.include` entries, and a pack dry run against the size caps. Server-side concerns (the build, store review) are out of scope. |
| `listDeployments` | The version rail, newest first — the developer org sees its FULL rail (published or not), other callers only their visible versions. Each entry carries its deployment `state`, its `buildStatus` ('ok' = servable), and the `rungs` naming the audiences bound to it. |
| `submitApp` | Submit a deployed version for store review — flips the deployment `private` → `submit` (it enters the admin queue). Developer-org + namespace gated. |
| `withdrawApp` | Withdraw a pending review — the developer's own cancel: flips the deployment `submit` → `private` (leaves the admin queue, back to draft; history records `withdrawn`). Only a version in `submit` withdraws. Developer-org + namespace gated. |
| `replyApp` | Append a developer message to the app's review thread — the developer half of the reviewer conversation. Rides `deployment_history` as a `reply` row (side `'developer'`), the same stream `deploy.history()` reads. Developer-org + namespace gated. |
| `buildLog` | One version's durable server build log — the full phase-by-phase output the build worker stores beside the version's artifacts (no error text rides the rail rows). Long logs serve their tail; `''` = no log. Developer-org gated. |
| `publishApp` | Bind a deployment to '@me', '@team/<name>', or '@public' ('@user' = legacy input alias). The binding is a pure pointer born 'enabled'. `@public` requires the deployment be `ready` (approved); `@me`/`@team` accept any non-`failed` deployment. Pinning ANOTHER org's public app to '@me'/'@team' is the version selector and is allowed; publishing your own app requires the id to be in your namespace. |
| `whereApp` | The reverse index: `{rung, handle, version, appVersion, state, deployedAt}` per audience — `state` is the bound DEPLOYMENT's review state. |

Serving needs no verb: a version's bundle loads from the stable
`/apps/<appId>/v<N>/remoteEntry.js` URL constructed from its registry
version number, with entitlement enforced by the serve route on every
request (registry ints ONLY — semver is display).

Full signatures: [API reference](/clients/typescript/reference#app-publish-ladder).

See the [Shell API guide](/guides/apps) for the app model itself.


---

# Error Handling

Route: /clients/typescript/errors

---
title: Error Handling
sidebar_position: 9
---

# Error Handling

What the SDK throws, when, and how to catch it.

## What actually throws

| Situation | Thrown |
| --- | --- |
| Bad API key / credentials during login or connect | `AuthenticationException` |
| Transport loss and connection failures (including during login) | `ConnectionException` |
| Data-pipe errors (open / write / close) | `PipeException` |
| A login superseded, logged out, or detached mid-flight | `LoginAttemptCancelledError` |
| Most argument and server-rejection errors (`use()`, `getService()`, DAP failures) | plain `Error` |
| `sendFiles` with a non-positive `maxConcurrent` | `RangeError` |
| `Answer.getJson()` on non-JSON content | throws |

```typescript
import { RocketRideClient, AuthenticationException, ConnectionException, LoginAttemptCancelledError } from 'rocketride';

try {
	await client.connect();
	const { token } = await client.use({ filepath: './pipeline.pipe' });
	await client.send(token, data);
} catch (e) {
	if (e instanceof AuthenticationException) {
		console.error('Bad credentials');
	} else if (e instanceof LoginAttemptCancelledError) {
		console.log('Login cancelled:', e.reason); // 'superseded' | 'logout' | 'detached'
	} else if (e instanceof ConnectionException) {
		console.error('Connection failed:', e.message);
	} else {
		console.error('Request failed:', e);
	}
}
```

`AuthenticationException` is thrown on DAP auth failure. In
[persist mode](/clients/typescript/configuration#reconnection) the client calls
`onConnectError` and does **not** retry authentication — fix credentials and call
`login()` or `connect()` again.

`LoginAttemptCancelledError` extends `Error` directly (intentionally not a
`RocketRideException`). Its `reason` is the `LoginAttemptCancellationReason` union
`'superseded' | 'logout' | 'detached'` — catch it when overlapping lifecycle
actions are expected. An unsolicited transport loss during login rejects with
`ConnectionException` instead. See
[Concurrent logins](/clients/typescript/connection#concurrent-logins).

## The hierarchy

The full hierarchy is exported from `rocketride`:

```text
DAPException                    # Base DAP protocol error
└── RocketRideException         # Base for all RocketRide errors
    ├── ConnectionException     # Connection/network issues
    │   └── AuthenticationException  # Bad API key or credentials
    ├── PipeException           # Data pipe errors
    ├── ExecutionException      # Reserved: defined but not currently thrown
    └── ValidationException     # Reserved: defined but not currently thrown

LoginAttemptCancelledError      # extends Error directly (by design)
```

Exceptions in the hierarchy expose a `dapResult` record with the server's error
context (mirroring Python's `dap_result`), plus two optional fields:

- `code` — the server's machine-readable classification, absent when the failure
  has none. Task failures carry one: `TASK_NOT_REGISTERED` (the token names no
  live task — never started, terminated, replaced, or the engine restarted),
  `TASK_AMBIGUOUS`, `TASK_COMPLETED`, `TASK_STOPPED`. **Classify on `code`, not
  on `message`**, which is written for people and may be reworded.
- `hint` — troubleshooting text the SDK attached for a developer, absent when
  there is none. Kept out of `message` so an application can show the message
  to an end user without the developer checklist.

```typescript
try {
	await pipe.open();
} catch (err) {
	if (err instanceof PipeException) {
		if (err.code === 'TASK_NOT_REGISTERED') await restartPipeline();
		else console.error(err.message, err.hint);
	}
}
```

In practice most failures outside the connection/pipe paths surface as plain
`Error` with a descriptive message — write handlers that catch the specific
classes above first and fall back to `Error`. `ExecutionException` and
`ValidationException` exist and are exported but the SDK does not currently throw
them; don't write handlers that rely on them.


---

# Examples

Route: /clients/typescript/examples

---
title: Examples
sidebar_position: 11
---

# Examples

Complete, runnable programs covering the SDK surface end to end. For pipeline-level
examples, see the site-wide examples —
[RAG pipeline](/examples/rag-pipeline), [webhook pipeline](/examples/webhook-pipeline), and [document extraction](/examples/document-extraction).

## 1. Minimal: connect, run pipeline from file, send one string, disconnect

```typescript
import { RocketRideClient } from 'rocketride';

const client = new RocketRideClient({
	auth: process.env.ROCKETRIDE_APIKEY!,
	uri: 'https://api.rocketride.ai',
});
await client.connect();
const { token } = await client.use({ filepath: './pipeline.pipe' });
const result = await client.send(token, 'Hello, pipeline!', { name: 'input.txt' }, 'text/plain');
console.log(result);
await client.terminate(token);
await client.disconnect();
```

## 2. One-off script with automatic disconnect (withConnection)

```typescript
import { RocketRideClient } from 'rocketride';

const myPipelineConfig = { components: [] }; // your pipeline object, e.g. JSON.parse of a .pipe file

const status = await RocketRideClient.withConnection({ auth: 'my-key', uri: 'wss://api.rocketride.ai' }, async (client) => {
	const { token } = await client.use({ pipeline: myPipelineConfig });
	await client.send(token, JSON.stringify({ data: 1 }));
	return await client.getTaskStatus(token);
});
console.log(status);
```

## 3. Long-lived app: persist mode, callbacks, and status handling

```typescript
import { RocketRideClient } from 'rocketride';

const apiKey = process.env.ROCKETRIDE_APIKEY!;
const serverUri = 'wss://api.rocketride.ai';

const client = new RocketRideClient({
	auth: apiKey,
	uri: serverUri,
	persist: true,
	onConnected: async () => updateUI({ state: 'connected' }),
	onDisconnected: async (reason, hasError) => updateUI({ state: 'disconnected', reason, hasError }),
	onConnectError: (error) => updateUI({ state: 'error', message: error.message }),
	onEvent: async (e) => {
		if (e.event === 'apaevt_status_upload') updateProgress(e.body);
	},
});
await client.connect();
// Later: use(), sendFiles(), etc. If the connection drops, the client retries
// forever (linear backoff) — except on auth failure. Do not call disconnect()
// in onDisconnected.
```

## 4. Upload multiple files and poll until pipeline completes

```typescript
import { RocketRideClient } from 'rocketride';

const auth = process.env.ROCKETRIDE_APIKEY!;
const uri = 'https://api.rocketride.ai';
const client = new RocketRideClient({ auth, uri, onEvent: async (e) => console.log(e.event, e.body) });
await client.connect();
const { token } = await client.use({ filepath: './vectorize.pipe' });
await client.setEvents(token, ['apaevt_status_upload', 'apaevt_status_processing']);

const files = [new File([content1], 'a.md'), new File([content2], 'b.md')];
const uploadResults = await client.sendFiles(
	files.map((file) => ({ file })),
	token
);
console.log('Uploaded:', uploadResults.filter((r) => r.action === 'complete').length);

while (true) {
	const status = await client.getTaskStatus(token);
	console.log(`Progress: ${status.completedCount}/${status.totalCount}`);
	if (status.completed) break;
	await new Promise((r) => setTimeout(r, 2000));
}
await client.terminate(token);
await client.disconnect();
```

## 5. Streaming large data with a pipe

```typescript
import { RocketRideClient } from 'rocketride';
import { createReadStream, readFileSync } from 'fs';
import { createInterface } from 'readline';

const auth = process.env.ROCKETRIDE_APIKEY!;
const uri = 'https://api.rocketride.ai';
const config = JSON.parse(readFileSync('./ingest.pipe', 'utf8'));

const client = new RocketRideClient({ auth, uri });
await client.connect();
const { token } = await client.use({ pipeline: config });

const pipe = await client.pipe(token, { name: 'large.csv' }, 'text/csv');
await pipe.open();
const rl = createInterface({ input: createReadStream('large.csv') });
for await (const line of rl) {
	await pipe.write(new TextEncoder().encode(line + '\n'));
}
const result = await pipe.close();
console.log(result);
await client.terminate(token);
await client.disconnect();
```

## 6. Chat: question with instructions and examples, parse JSON answer

```typescript
import { RocketRideClient, Question, Answer } from 'rocketride';
import { readFileSync } from 'fs';

const auth = process.env.ROCKETRIDE_APIKEY!;
const uri = 'https://api.rocketride.ai';
const chatPipelineConfig = JSON.parse(readFileSync('./chat_pipeline.pipe', 'utf8'));

const client = new RocketRideClient({ auth, uri });
await client.connect();
const { token } = await client.use({ pipeline: chatPipelineConfig });

const question = new Question({ expectJson: true });
question.addInstruction('Format', 'Return a JSON object with keys: summary, keywords.');
question.addExample('Summarize X', { summary: '...', keywords: ['a', 'b'] });
question.addQuestion('Summarize the main points and list keywords.');

const response = await client.chat({ token, question });
const answerText = response?.answers?.[0];
const answer = new Answer(true); // expectJson — so isJson()/getJson() engage
answer.setAnswer(answerText ?? '');
const structured = answer.isJson() ? answer.getJson() : answer.getText();
console.log(structured);

await client.terminate(token);
await client.disconnect();
```

## 7. Discover services and send a custom DAP request

```typescript
import { RocketRideClient } from 'rocketride';

const auth = 'my-key';
const uri = 'https://api.rocketride.ai';
const client = new RocketRideClient({ auth, uri });
await client.connect();

const services = await client.getServices();
console.log('Available:', Object.keys(services.services));
const ocr = await client.getService('ocr'); // throws if the service is unknown

const myToken = 'existing-task-token'; // token from an earlier client.use() call
const req = client.buildRequest('rrext_ping', { token: myToken });
const res = await client.request(req, 5000);
if (client.didFail(res)) throw new Error(res.message);
await client.disconnect();
```


---

# Run Logs

Route: /clients/typescript/logs

---
title: Run Logs
sidebar_position: 8
---

# Run Logs — `client.log`

Every task writes a **run log**: one continuous JSONL event stream per task
identity (`projectId` + `source`, plus the scope: a `teamId` addresses that
team's DEPLOY continuum — [deploy runs](/clients/typescript/deploy) log into the
team's tree, readable by any teammate with monitor rights — while omitting it
addresses your own stream, where the optional `runKind` picks between your dev
stream (the default) and your personal deploy stream: `'deploy'` without a
`teamId` is the only way to address that continuum). Individual runs are
**chapters** (tracks) inside the stream — there are no per-run log files. The log
survives disconnects and server restarts, powers replay of past runs through the
same panels that render live monitoring, and is retained on a ring (last ~1 GB)
plus a history age (7 days dev / 30 days deploy).

Streams are addressed by the plain identity tuple — never by task token (tokens
are credentials and appear nowhere in the log system).

## The DVR session — `openEventStream()`

Opens a **DVR session** over one source continuum — the recommended way to consume
a run log. The session thinks in *positions* on the timeline; storage details
(segments, keyframes, deltas) are invisible and every event it delivers is fully
reconstructed.

The protocol is **seed-then-stream**: `seek(pos)` positions the session, the
`get*()` calls seed your panels with state *as of* that position, and
`play(pos, speed, cb)` streams events strictly *after* what the seeds covered — no
gap, no duplicate. Speed `0` delivers as fast as possible, `1` is real time, `10`
is 10×. Playing from a past position auto-pins to live on catching the wall clock;
live is just the position pinned to now (`seek('live')`), not a separate mode.

```typescript
const stream = { projectId: 'proj-1', source: 'chat_1' };
const session = client.log.openEventStream(stream);

// Canonical startup: position, seed the panels, then roll.
await session.seek('live');
const status = await session.getStatus();           // state as of the position
const consoleLines = await session.getConsole(500); // exactly what the console showed
const traces = await session.getTraces(50);         // all in-flight + last 50 closed
await session.play(undefined, 0, ({ event }) => fold(event));

// Replay a past run at 10x from its beginning.
const [first] = await session.getChapters();
await session.play(first.beginTime, 10, ({ event }) => fold(event));

// Drill into one trace (a call tree; fetched sparsely from exactly
// the segments that contain it).
const detail = await session.getTrace(traces.closed[0].beginSeq);

session.pause();            // freeze the position
session.closeEventStream(); // dispose
```

`getTraces(n)` errors when `n > 50` — the session exposes all in-flight traces
plus a sliding window of the 50 most recently closed; any older trace is still
reachable by seeking to a position inside its lifetime. `getTrace(traceId)`
resolves a trace by its begin event's continuum seq (pass the trace's own
`beginSeq` from its `LogTraceSummary`, not the chapter's) — the permanent identity (slot
ids recycle; `beginSeq` never does). Hosts that own a live subscription feed
arriving events to the session via `ingestLive(event)`; while pinned, arrival
paces delivery.

## `chapters()`

Returns the stream's timeline in one small read: each run's begin/end date-time,
starting sequence number and outcome, the activity spans for the timeline bar, the
retained window, and the retention horizon.

```typescript
// Own dev stream; add teamId: 'team-prod' to read a team's deploy continuum.
const stream = { projectId: 'proj-1', source: 'chat_1' };
const timeline = await client.log.chapters(stream);
for (const track of timeline.chapters) {
	console.log(track.beginTime, track.endTime, track.outcome);
}
```

## `read()`

Ranged, paged event read over the continuum. Range forms: a sequence range
(`fromSeq`/`toSeq`), a time range (`fromTime`/`toTime`, omit `toTime` for "to
now"), or time-to-segment (`fromTime` + `toSegment`). Responses are paged
(`maxEvents`/`maxBytes`, server-clamped): when `nextSeq` is present, pass it back
as `cursor` to continue. `types` filters event types server-side; a
`truncatedAtSeq` field means the request reached below the retention horizon.

```typescript
let cursor: number | undefined;
do {
	const page = await client.log.read(stream, { fromSeq: 0, cursor, types: ['output'] });
	for (const event of page.events) {
		process.stdout.write(String(event.body?.output ?? ''));
	}
	cursor = page.nextSeq;
} while (cursor !== undefined);
```

Every event carries the continuum stamps in its **body** — the only place they
exist: `body.eventTime` (epoch seconds, stamped once at engine ingress) and
`body.logSeq` (catalog-seeded — a fresh stream starts at 1 and continues from the
recorded `lastSeq + 1` across runs and restarts; strictly monotonic) — identical
live and on replay. The DAP envelope's own `seq` is per-connection protocol
bookkeeping and says nothing about the continuum.

## `segment()`

Fetches one segment's raw JSONL bytes, chunked by byte offset — the bulk replay
path. The server hands over the immutable segment content as-is, in
**whole-line-aligned chunks** (every response ends on a newline, so each chunk
parses standalone). Repeat with the returned `nextOffset` until `final`. The
segment table comes from `chapters()`.

```typescript
let offset = 0;
for (;;) {
	const chunk = await client.log.segment(stream, 0, { offset });
	for (const line of chunk.data.split('\n')) {
		if (line.trim()) handleEvent(JSON.parse(line));
	}
	if (chunk.final) break;
	offset = chunk.nextOffset!;
}
```

Prefer `segment()` over paged `read()` when consuming whole runs (replay, export);
use `read()` for filtered or narrow ranged queries.

## `delete()`

Destructive. `beforeTime` drops segments wholly older than the cutoff (chapters
trimmed, horizon advanced); `all` removes the entire stream including its control
file.

```typescript
await client.log.delete(stream, { beforeTime: Date.now() / 1000 - 86400 });
await client.log.delete(stream, { all: true });
```

## Wire surface and permissions

All methods use the single `rrext_log` DAP command, dispatched by a `subcommand`
argument (`chapters`, `read`, `segment`, `delete`). Reads require `task.monitor`;
`delete` requires `task.control`. The scope the request addresses picks whose
streams those rights are resolved against: without `teamId` you access your OWN
dev streams; with `teamId` the permission is checked against the TARGET team —
membership is the read/write right. `openEventStream()` is client-side
composition: it issues `chapters` and `segment` calls under the hood and
registers a live monitor subscription while open (released by
`closeEventStream()`) — it adds no wire surface of its own.


---

# Running Pipelines

Route: /clients/typescript/pipelines

---
title: Running Pipelines
sidebar_position: 3
---

# Running Pipelines

Start a pipeline, watch its progress, and stop it. Method tables live in the
[API reference](/clients/typescript/reference#pipeline-execution); this page covers
the workflow.

## Start with `use()`

`use()` starts a pipeline from a file (Node only) or an in-memory config and
resolves to an object whose `token` identifies the running task — every data and
control call takes it.

```typescript
const { token } = await client.use({ filepath: './pipeline.pipe', ttl: 3600 });
```

Beyond `filepath`/`pipeline`, the options accept `source`, `threads`,
`useExisting`, `args`, `ttl`, `pipelineTraceLevel` (trace verbosity for the
[run log](/clients/typescript/logs)), `name` (a display name for the task), and
`env` (per-run variable overrides). Pass the pipeline config **as-is** — do not
wrap it in `{ pipeline: ... }`; the client sends it to the server, which resolves
`${ROCKETRIDE_*}` variables.

**Check `reused` before trusting the result.** `useExisting` returns the
instance that is already running under that token rather than starting the one
you submitted, and the result's `reused` flag is `true` when that happened. A
reused instance keeps the configuration it was created with — the pipeline in
this call is ignored, edits included — along with whatever state it has
accumulated. Benchmarks and A/B comparisons are where an unnoticed reuse costs
the most. Call `restart()` to apply new configuration to a live token.

**Why a token:** the server runs each pipeline as a separate task. The token
targets `send()`, `sendFiles()`, `pipe()`, `chat()`, `getTaskStatus()`, and
`terminate()` at the correct pipeline.

## Watch progress

Poll `getTaskStatus(token)` — it returns `completedCount`, `totalCount`,
`completed`, `state`, `exitCode`, and more. A per-call
`{ timeout }` option defaults to 15000 ms; pass `false` to disable the bound:

```typescript
while (true) {
	const status = await client.getTaskStatus(token);
	console.log(`Progress: ${status.completedCount}/${status.totalCount}`);
	if (status.completed) break;
	await new Promise((r) => setTimeout(r, 2000));
}
```

### Events

For push-style progress instead of polling, add a monitor subscription; events
arrive at your [`onEvent` callback](/clients/typescript/configuration#callbacks):

```typescript
await client.addMonitor({ token }, ['apaevt_status_upload', 'apaevt_status_processing']);
// ... later:
await client.removeMonitor({ token }, ['apaevt_status_upload', 'apaevt_status_processing']);
```

`addMonitor(key, types)` / `removeMonitor(key, types)` are reference-counted —
adding the same key merges types, removing unsubscribes a type only when its count
reaches zero. The `MonitorKey` is `{ token }` for a running task, or
`{ projectId, source, pipeId?, teamId? }` (a team ID addresses that team's deployed
run). The older `setEvents(token, eventTypes, pipeId?)` still works but is
deprecated in favor of the monitor pair.

## Validate before you run

`validate({ pipeline, source? })` checks a pipeline config server-side without
starting it and returns errors and warnings — cheap insurance before `use()`.

## Stop with `terminate()`

`terminate(token)` stops the pipeline and frees server resources. Long-lived tasks
without a `ttl` run until terminated.

## Discover services

`getServices()` returns lightweight **summaries** of every service the server
supports (plus a deduplicated icon table and the server version). For a full
definition — config schema included — fetch one by name with `getService(name)`,
which returns a `ServiceDefinition` and **throws** on failure (it never resolves to
`undefined`).

```typescript
const services = await client.getServices();
const ocr = await client.getService('ocr'); // throws if unknown
```

## Liveness

`ping(token?)` performs a liveness check and throws on failure; the optional token
scopes the ping to a task.

> Deploying a pipeline so it persists server-side and runs on a schedule is a
> separate surface — see [Deployments](/clients/typescript/deploy).


---

# API Reference

Route: /clients/typescript/reference

---
title: API Reference
sidebar_position: 10
---

# API Reference

The core public surface of the TypeScript SDK. Constructor options and
environment variables are on [Configuration](/clients/typescript/configuration);
exceptions on [Error Handling](/clients/typescript/errors).

## RocketRideClient

### Connection

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `attach` | `attach(uri?: string, options?: { timeout?: number }): Promise<void>` | `Promise<void>` | Opens an anonymous WebSocket attachment without authenticating. Public `rrext_public_*` requests are available. A URI override becomes the current endpoint. |
| `detach` | `detach(): Promise<void>` | `Promise<void>` | Cancels pending login and reconnect work, closes a CONNECTING or OPEN transport, and leaves the client detached. An in-flight login rejects with cancellation reason `detached`. |
| `isAttached` | `isAttached(): boolean` | `boolean` | Whether the WebSocket transport is open, regardless of authentication. |
| `login` | `login(credential?: string \| { code: string; verifier: string; redirectUri: string }, options?: { uri?: string; timeout?: number }): Promise<ConnectResult>` | `Promise<ConnectResult>` | Attaches if needed, authenticates, restores monitor subscriptions, and returns account data. The credential and URI may override construction-time values. |
| `logout` | `logout(): Promise<void>` | `Promise<void>` | Clears authentication while retaining an anonymous attachment. During an in-flight login it cancels all joined waiters with reason `logout` and establishes a fresh anonymous attachment. |
| `isAuthenticated` | `isAuthenticated(): boolean` | `boolean` | Whether authentication succeeded for the current attachment. |
| `connect` | `connect(credential?: string \| { code: string; verifier: string; redirectUri: string }, options?: { uri?: string; timeout?: number }): Promise<ConnectResult>` | `Promise<ConnectResult>` | Compatibility method that performs attach and login as one foreground operation. |
| `disconnect` | `disconnect(): Promise<void>` | `Promise<void>` | Best-effort logout/deauthentication, then cancels pending work and detaches. |
| `isConnected` | `isConnected(): boolean` | `boolean` | Compatibility **alias for `isAttached()`**; it does not imply authentication. |
| `setEnv` | `setEnv(env: Record<string, string>): void` | `void` | Replaces the client's environment map. `use()` uses it for `ROCKETRIDE_*` substitution; `login()` consults `ROCKETRIDE_APIKEY` when no explicit credential is supplied. |

Join/supersede semantics for concurrent logins are described on
[Connection](/clients/typescript/connection#concurrent-logins). The client also
supports `await using` (`Symbol.asyncDispose`).

### Pipeline execution

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `use` | `use(options?: { token?: string; filepath?: string; pipeline?: PipelineConfig; source?: string; threads?: number; useExisting?: boolean; args?: string[]; ttl?: number; pipelineTraceLevel?: 'none' \| 'metadata' \| 'summary' \| 'full'; name?: string; env?: Record<string, string> }): Promise<Record<string, any> & { token: string }>` | `Promise<{ token, ... }>` | Starts a pipeline. Pass either `pipeline` (object, used as-is — do not wrap it) or `filepath` (Node only). `pipelineTraceLevel` sets run-log trace verbosity, `name` a task display name, `env` per-run variable overrides. Returns at least `token`, plus `reused: true` when `useExisting` handed back an already-running instance instead of starting this pipeline. |
| `validate` | `validate(options: { pipeline: PipelineConfig \| Record<string, unknown>; source?: string }): Promise<ValidationResult>` | `Promise<ValidationResult>` | Validates a pipeline configuration without starting it; returns errors and warnings. |
| `terminate` | `terminate(token: string): Promise<void>` | - | Stops the pipeline for that token and frees server resources. |
| `getTaskStatus` | `getTaskStatus(token: string, options?: { timeout?: number \| false }): Promise<TASK_STATUS>` | `Promise<TASK_STATUS>` | Current task status (`completedCount`, `totalCount`, `completed`, `state`, `exitCode`, …). Per-call `timeout` defaults to 15000 ms; pass `false` to disable. |

### Data

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `pipe` | `pipe(token: string, objinfo?: Record<string, any>, mimeType?: string, provider?: string, onSSE?): Promise<DataPipe>` | `Promise<DataPipe>` | Creates a **streaming** data pipe: open, one or more writes, close. Default MIME: `application/octet-stream`. `onSSE` receives server-sent events. |
| `send` | `send(token: string, data: string \| Uint8Array, objinfo?: Record<string, any>, mimetype?: string, onSSE?): Promise<PIPELINE_RESULT \| undefined>` | `Promise<PIPELINE_RESULT \| undefined>` | Sends data in **one shot** (open, write once, close). No MIME auto-detection — default is `application/octet-stream`. |
| `sendFiles` | `sendFiles(files: Array<{ file: File; objinfo?: Record<string, any>; mimetype?: string }>, token: string, maxConcurrent?: number): Promise<UPLOAD_RESULT[]>` | `Promise<UPLOAD_RESULT[]>` | Uploads browser `File` objects through a worker pool capped at `maxConcurrent` (default **5**; must be a positive integer, else `RangeError`). Results resolve in the same order as `files`. Progress via `onEvent` as `apaevt_status_upload`. |

### Events

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `addMonitor` | `addMonitor(key: MonitorKey, types: string[]): Promise<void>` | - | Adds a reference-counted monitor subscription; events are delivered to `onEvent`. `MonitorKey` is `{ token }` or `{ projectId, source, pipeId?, teamId? }`. |
| `removeMonitor` | `removeMonitor(key: MonitorKey, types: string[]): Promise<void>` | - | Removes a monitor subscription; a type unsubscribes from the server only when its reference count reaches zero. |
| `setEvents` | `setEvents(token: string, eventTypes: string[], pipeId?: number): Promise<void>` | - | **Deprecated** — use `addMonitor`/`removeMonitor`. Subscribes the task (or optional pipe) to the given event types. |

### Services, validation, and ping

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `getServices` | `getServices(): Promise<ServicesResponse>` | `Promise<ServicesResponse>` | Lightweight **summaries** of every service, plus a deduplicated `icons` table and the server `version`. Full definitions come from `getService`. |
| `getService` | `getService(service: string): Promise<ServiceDefinition>` | `Promise<ServiceDefinition>` | One service's full definition (config schema included). **Throws** on failure — it never resolves to `undefined`. |
| `ping` | `ping(token?: string): Promise<void>` | - | Liveness check; throws on failure. Optional `token` for task-scoped ping. |

### Chat

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `chat` | `chat(options: { token: string; question: Question; onSSE? }): Promise<PIPELINE_RESULT>` | `Promise<PIPELINE_RESULT>` | Sends the `Question` to the pipeline and returns the result. `onSSE` streams server-sent events (e.g. token-by-token output). See [Chat](/clients/typescript/chat). |

### Convenience

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `getConnectionInfo` | `getConnectionInfo(): { connected: boolean; transport: string; uri: string }` | object | Current connection state and URI. |
| `getApiKey` | `getApiKey(): string \| undefined` | `string \| undefined` | The API key in use (debugging only; avoid logging in production). |

### Static

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `withConnection` | `RocketRideClient.withConnection<T>(config: RocketRideClientConfig, callback: (client: RocketRideClient) => Promise<T>): Promise<T>` | `Promise<T>` | Creates a client, calls `connect()`, runs `callback(client)`, then `disconnect()` in a `finally` block. In Python, use `async with RocketRideClient(...)` instead. <!-- language-specific --> |

### Store (file access)

Paths are **relative** to the store root; absolute-like paths are rejected. See
[File Storage](/clients/typescript/storage) for the workflow.

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `fsOpen` | `fsOpen(path: string, mode?: 'r' \| 'w'): Promise<{ handle: string; size?: number }>` | `Promise<{ handle; size? }>` | Open a handle (`mode` default `'r'`). Read mode also returns `size`. |
| `fsRead` | `fsRead(handle: string, offset?: number, length?: number): Promise<Uint8Array>` | `Promise<Uint8Array>` | Read up to `length` bytes (default 4 MB) from `offset`. Empty array = EOF. |
| `fsWrite` | `fsWrite(handle: string, data: Uint8Array): Promise<number>` | `Promise<number>` | Write raw bytes to a write handle. Resolves to the number of bytes written. |
| `fsClose` | `fsClose(handle: string, mode: 'r' \| 'w'): Promise<void>` | `Promise<void>` | Close a handle. `mode` must match the mode passed to `fsOpen`. |
| `fsReadString` | `fsReadString(path: string): Promise<string>` | `Promise<string>` | Read an entire file as a UTF-8 string. |
| `fsWriteString` | `fsWriteString(path: string, text: string): Promise<void>` | `Promise<void>` | Write a UTF-8 string to a file (overwrites). |
| `fsReadJson` | `fsReadJson<T = any>(path: string): Promise<T>` | `Promise<T>` | Read and parse a JSON file. |
| `fsWriteJson` | `fsWriteJson(path: string, obj: any): Promise<void>` | `Promise<void>` | Serialize an object to JSON and write it. |
| `fsListDir` | `fsListDir(path?: string): Promise<{ entries: Array<{ name; type: 'file' \| 'dir'; size?; modified? }>; count }>` | `Promise<{ entries; count }>` | List immediate children (default: store root). |
| `fsStat` | `fsStat(path: string): Promise<{ exists: boolean; type?: 'file' \| 'dir'; size?; modified? }>` | `Promise<{...}>` | File/dir metadata (`size`/`modified` for files only). |
| `fsMkdir` | `fsMkdir(path: string): Promise<void>` | `Promise<void>` | Create a directory. |
| `fsRmdir` | `fsRmdir(path: string, recursive?: boolean): Promise<void>` | `Promise<void>` | Remove a directory. `recursive` (default `false`) deletes contents. |
| `fsRename` | `fsRename(oldPath: string, newPath: string): Promise<void>` | `Promise<void>` | Rename or move a file/directory (copy+delete on object stores; recursive for directories). |
| `fsDelete` | `fsDelete(path: string): Promise<void>` | `Promise<void>` | Delete a file. |
| `fsGetUrl` | `fsGetUrl(path: string, expiresIn?: number, downloadName?: string): Promise<string>` | `Promise<string>` | Time-limited HTTP(S) URL for direct browser access; inline by default, `downloadName` forces `Content-Disposition: attachment`. `expiresIn` in seconds (default 3600). |
| `fsReadMany` | `fsReadMany(paths: string[]): Promise<Array<{ path, ok, data?, error? }>>` | `Promise<Array>` | Batch-read many small files in one round trip (max 256 paths / 32 MiB total). Per-entry failures (`ok: false` + `error`), request order, `data` as `Uint8Array`. |

### Database

Raw SQL through a pipeline database node (requires `allow_execute: true` on the
node).

| Method | Signature | Description |
| --- | --- | --- |
| `database.query` | `database.query({ token, sql, nodeId?, sessionId?, params? }): Promise<{ rows, affected_rows }>` | Execute raw SQL through the pipeline's `execute` tool function. |
| `database.beginTransaction` | `database.beginTransaction({ token, nodeId? }): Promise<{ session_id }>` | Open a transaction (`begin` tool function). |
| `database.commit` | `database.commit({ token, sessionId, nodeId? }): Promise<{ ok }>` | Commit the open transaction. |
| `database.rollback` | `database.rollback({ token, sessionId, nodeId? }): Promise<{ ok }>` | Roll back the open transaction. |
| `database.dialect` | `database.dialect({ token, nodeId? }): Promise<DatabaseDialect>` | The target node's SQL dialect. |
| `database.sequelize` | `database.sequelize({ Sequelize, token, nodeId?, sequelizeOptions? }): Sequelize` | Build a Sequelize v6 instance whose Postgres dialect transports SQL over the pipeline. See [Sequelize over Pipelines](/clients/typescript/database-sequelize). <!-- language-specific --> |

### Deploy (`client.deploy`)

See [Deployments](/clients/typescript/deploy) for the model.

| Method | Description |
| --- | --- |
| `deploy.add({kind?, pipeline?, data?, metadata?, comment?, deployTo?})` | The ONE rail door: deploy any kind of object as the next immutable registry version. `kind:'pipe'` (default) takes a `pipeline` dict; `kind:'app'` takes ONE `data` zip of the app's SOURCE — the server performs the build (client-produced binaries are never trusted); the zip is retained and unpacked at receipt, born deployment-state `private`. The app id must be inside your developer namespace. |
| `deploy.addApp(appRoot, { workspaceRoot?, comment?, metadata?, onProgress? }): Promise<PublishResult>` | Pack an app folder's source and deploy it as the next registry version — the one call behind the App Builder's Deploy button and CI scripts. Packs by the App Builder rules (workspace-rooted zip, `appManifest.include`, hierarchical gitignore + the hard node_modules/dist/.git baseline, symlink containment, 50MB zipped / 512MB uncompressed caps); `onProgress` receives one line per step. Deploying activates nothing — bind an audience with `publishApp` afterwards. |
| `deploy.verifyApp(appRoot, { workspaceRoot? }): Promise<AppVerifyReport>` | The no-side-effect precheck for `addApp` — purely local, no server call: manifest shape and id grammar, declared icon/README assets, `appManifest.include` entries, and a pack dry run against the size caps. Server-side concerns (the build, store review) are out of scope. |
| `deploy.deploy(projectId, version, teamId)` | Point a team at a version — promotion and rollback alike. |
| `deploy.list(params?)` | Deployments visible to you, standard `{ rows, total, page, pageSize }` envelope. |
| `deploy.get(projectId, teamId)` | One team's deployment, registry-joined. |
| `deploy.versions(projectId, params?)` | Registry versions (the version strip), newest first. |
| `deploy.history(projectId, params?)` | The immutable audit trail, newest first, server-paged. |
| `deploy.disable(projectId, teamId)` | The kill switch: nothing runs until enabled again. |
| `deploy.enable(projectId, teamId)` | Enable a disabled deployment. |
| `deploy.remove(projectId, teamId)` | Soft remove — history and artifacts survive forever. |
| `deploy.setSchedule(projectId, sourceId, schedule, teamId, options?)` | Set (or clear with `null`) one source's cron schedule; the paused flag is untouched. |
| `deploy.pauseSchedule(projectId, sourceId, teamId)` | Pause ONE schedule — cron/ttl kept, it just stops firing. |
| `deploy.resumeSchedule(projectId, sourceId, teamId)` | Resume a paused schedule. |
| `deploy.setSourceConfig(projectId, sourceId, teamId, options?)` | Per-source execution settings for deploy runs (`traceLevel`, `debugOut`). |
| `deploy.run(projectId, sourceId, teamId)` | Start one deployed source NOW (manual trigger); returns `{ token, version }`. |
| `deploy.artifact(projectId, version)` | One immutable version's pipeline JSON, sha256-verified server-side. |
| `deploy.preview(schedule, count?)` | THE single cron evaluator: validity + next occurrences. |

Returns mirror the Python table: `add` → `PublishResult`; `deploy`, `get`,
`disable`, `enable`, `remove`, `setSchedule`, `pauseSchedule`, `resumeSchedule`,
`setSourceConfig` → `Deployment`; `list`/`versions`/`history` →
`DeployListEnvelope<T>`; `run` → `{ token, version }`; `artifact` →
`PipelineConfig`; `preview` → `SchedulePreview`.

### App publish ladder

See [Deployments](/clients/typescript/deploy#app-publish-ladder) for the model.
Only `deploy.add` and `deploy.addApp` live on `client.deploy`; the unprefixed
verbs below are methods on the client itself (`client.publishApp(...)`).

| Method | Signature | Description |
| ------ | --------- | ----------- |
| `deploy.add` | `deploy.add({kind?, pipeline?, data?, metadata?, comment?, deployTo?}): Promise<PublishResult>` | The ONE rail door: deploy any kind of object as the next immutable registry version. `kind:'pipe'` (default) takes a `pipeline` dict; `kind:'app'` takes ONE `data` zip of the app's SOURCE — the server performs the build (client-produced binaries are never trusted); the zip is retained and unpacked at receipt, born deployment-state `private`. The app id must be inside your developer namespace. |
| `deploy.addApp` | `deploy.addApp(appRoot, { workspaceRoot?, comment?, metadata?, onProgress? }): Promise<PublishResult>` | Pack an app folder's source and deploy it as the next registry version — the one call behind the App Builder's Deploy button and CI scripts. Packs by the App Builder rules (workspace-rooted zip, `appManifest.include`, hierarchical gitignore + the hard node_modules/dist/.git baseline, symlink containment, 50MB zipped / 512MB uncompressed caps); `onProgress` receives one line per step. Deploying activates nothing — bind an audience with `publishApp` afterwards. |
| `deploy.verifyApp` | `deploy.verifyApp(appRoot, { workspaceRoot? }): Promise<AppVerifyReport>` | The no-side-effect precheck for `addApp` — purely local, no server call: manifest shape and id grammar, declared icon/README assets, `appManifest.include` entries, and a pack dry run against the size caps. Server-side concerns (the build, store review) are out of scope. |
| `listDeployments` | `listDeployments(appId): Promise<RailEntry[]>` | The version rail, newest first — the developer org sees its FULL rail (published or not), other callers only their visible versions. Each entry carries its deployment `state`, its `buildStatus` ('ok' = servable), and the `rungs` naming the audiences bound to it. |
| `submitApp` | `submitApp(appId, registryVersion): Promise<{artifact}>` | Submit a deployed version for store review — flips the deployment `private` → `submit` (it enters the admin queue). Developer-org + namespace gated. |
| `withdrawApp` | `withdrawApp(appId, registryVersion): Promise<{artifact}>` | Withdraw a pending review — the developer's own cancel: flips the deployment `submit` → `private` (leaves the admin queue, back to draft; history records `withdrawn`). Only a version in `submit` withdraws. Developer-org + namespace gated. |
| `replyApp` | `replyApp(appId, message, registryVersion?): Promise<{replied, appId}>` | Append a developer message to the app's review thread — the developer half of the reviewer conversation. Rides `deployment_history` as a `reply` row (side `'developer'`), the same stream `deploy.history()` reads. Developer-org + namespace gated. |
| `buildLog` | `buildLog(appId, registryVersion): Promise<{appId, version, log}>` | One version's durable server build log — the full phase-by-phase output the build worker stores beside the version's artifacts (no error text rides the rail rows). Long logs serve their tail; `''` = no log. Developer-org gated. |
| `publishApp` | `publishApp(appId, registryVersion, target): Promise<{publish}>` | Bind a deployment to '@me', '@team/<name>', or '@public' ('@user' = legacy input alias). The binding is a pure pointer born 'enabled'. `@public` requires the deployment be `ready` (approved); `@me`/`@team` accept any non-`failed` deployment. Pinning ANOTHER org's public app to '@me'/'@team' is the version selector and is allowed; publishing your own app requires the id to be in your namespace. |
| `whereApp` | `whereApp(appId): Promise<Pin[]>` | The reverse index: `{rung, handle, version, appVersion, state, deployedAt}` per audience — `state` is the bound DEPLOYMENT's review state. |

Serving needs no verb: a version's bundle loads from the stable
`/apps/<appId>/v<N>/remoteEntry.js` URL constructed from its registry
version number, with entitlement enforced by the serve route on every
request (registry ints ONLY — semver is display).

### App marketplace + developer verbs

Two raw DAP commands carry this surface (call via
`client.call('<command>', { subcommand, ... })`):

- **`rrext_deploy_app`** — the developer-account + review verbs (claiming a
  developerId is a deploy PREREQUISITE, not a marketplace action): the
  `developer_*` family, `submit`, and `register_dev`.
- **`rrext_app`** — the pure marketplace: browse (`list`/`get`/`list_mine`),
  install (`desktop_add`/`desktop_remove`), admin review (`admin_*`), and
  pricing (`pricing_*`).

Grouped families (the `developer_*`/`submit`/`register_dev` rows are on
`rrext_deploy_app`; the rest on `rrext_app`):

| Subcommand family | Subcommands | Guard | Purpose |
| ----------------- | ----------- | ----- | ------- |
| developer_* | `developer_register` · `developer_stripe` · `developer_dashboard` · `developer_status` | org.admin (register) | Claim the org's developer id slug + Stripe Connect onboarding. |
| submit | `submit` · `withdraw` · `reply` | developer org + namespace | Submit a deployed version for review (flips the DEPLOYMENT `private` → `submit`), cancel a pending review, or append a developer message to the review thread (sugar over `submitApp`/`withdrawApp`/`replyApp`). |
| register_dev | `register_dev` | self | Per-user live dev overlay (App Builder hot-reload); OSS-capable. |
| catalog | `list` · `get` · `list_mine` · `desktop_add` · `desktop_remove` | authenticated | Browse reachable apps, the developer's own rail view, and desktop membership. |
| admin_* | `admin_queue` · `admin_approve` · `admin_reject` · `admin_reply` · `admin_reseed` | sys.admin | Store review over the DEPLOYMENTS: the queue is deployments in `submit`; `admin_approve(appId, version)` flips it `ready`, `admin_reject(appId, version)` flips it `rejected`. |
| pricing_* | `pricing_list` · `pricing_create` · `pricing_delete` | developer org (owns the app_products row) | Manage Stripe price tiers for a monetized app. |

**Review model.** The review state lives on the DEPLOYMENT (`deployment_artifacts.state`).
`@me`/`@team` bindings need no approval — they serve any non-`failed`
deployment at once. Going public is a three-step flow: `submit` (deployment →
`submit`, enters the admin queue) → `admin_approve` (→ `ready`) → `publishApp
@public` (point the public binding at the now-`ready` version). A reject flips
the deployment `rejected`; the developer fixes and deploys a NEW version. The
store serves only public bindings whose deployment is `ready`.

### Run logs (`client.log`)

See [Run Logs](/clients/typescript/logs) for the continuum model and the DVR
session.

### Additional client surface

Further public methods, present in both SDKs, in brief:

| Area | Methods |
| --- | --- |
| Generic invoke | `call(command, ...)` — any DAP command; `tool(...)` — invoke a pipeline tool function <!-- language-specific --> |
| Task helpers | `getTaskToken`, `getTaskPipeline`, `restart` |
| Identity | `getAccountInfo`, `getOrgId`; static `getServerInfo`, `normalizeUri` |
| Monitors | `clearAllMonitors`, `identify` (plus `addMonitor`/`removeMonitor` above) |
| Template storage | `saveTemplate`, `getTemplate`, `deleteTemplate`, `getAllTemplates` |
| Log storage | `saveLog`, `getLog`, `deleteLog`, `listLogs` |
| Dashboard | `getDashboard`, `listConnections`, `listTasks` |
| Profiling | `cprofileStart`, `cprofileStop`, `cprofileStatus`, `cprofileReport`, `cprofileReportTree` |
| Namespaces | `client.account`, `client.billing` (account and billing APIs) |

## DataPipe

Returned by `client.pipe()`. One streaming upload: **open → write (one or more) →
close**. The server assigns a `pipeId` on open; `close()` finalizes the stream and
returns the pipeline result.

| Member | Type | Description |
| --- | --- | --- |
| `isOpened` | `boolean` (getter) | Whether the pipe has been opened and not yet closed. |
| `pipeId` | `number \| undefined` (getter) | Server-assigned pipe ID; set after `open()`. |

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `open` | `open(): Promise<DataPipe>` | `Promise<DataPipe>` | Opens the pipe on the server. Must be called before `write()`. |
| `write` | `write(buffer: Uint8Array): Promise<void>` | - | Writes a chunk. Pipe must be open. |
| `close` | `close(): Promise<PIPELINE_RESULT \| undefined>` | `Promise<PIPELINE_RESULT \| undefined>` | Closes the pipe and returns the processing result. No-op if already closed. |
| `tool` | `tool<T = any>(tool: string, nodeId = '', input: Record<string, unknown> = {}): Promise<T>` | `Promise<T>` | Invokes a pipeline tool function through the pipe. |

## Question

From `rocketride`. Build a question for `client.chat({ token, question })`.

```typescript
constructor(options?: {
  type?: QuestionType;
  filter?: DocFilter;
  expectJson?: boolean;
  role?: string;
})
```

`QuestionType`: `QUESTION`, `SEMANTIC`, `KEYWORD`, `GET`, `PROMPT`.

| Method | Signature | Description |
| --- | --- | --- |
| `addInstruction` | `addInstruction(title: string, instruction: string): void` | Adds an instruction for the AI (e.g. "Answer in bullet points"). |
| `addExample` | `addExample(given: string, result: string \| object \| any[]): void` | Adds an example input/output so the AI can match format. |
| `addContext` | `addContext(context: string \| object \| string[] \| object[]): void` | Adds context (e.g. "Q4 2024 data"). |
| `addHistory` | `addHistory(item: QuestionHistory): void` | Adds a history item (`{ role, content }`) for multi-turn chat. |
| `addQuestion` | `addQuestion(question: string): void` | Appends the main question text. |
| `addDocuments` | `addDocuments(documents: Doc \| Doc[]): void` | Adds documents for the AI to reference. |
| `addGoal` | `addGoal(goal: string): void` | Adds a goal statement for the AI. |
| `getPrompt` | `getPrompt(hasPreviousJsonFailed?: boolean): string` | Returns the full prompt (internal use). |

## Answer

Parses chat response content — see
[Chat](/clients/typescript/chat#parse-the-response-with-answer) for semantics.

```typescript
constructor(expectJson?: boolean)  // default false
```

| Method | Signature | Description |
| --- | --- | --- |
| `setAnswer` | `setAnswer(value: string \| object \| unknown[]): void` | Stores the response value, validating/parsing it as JSON when `expectJson` is `true`. |
| `getText` | `getText(): string` | The stored answer as plain text. |
| `getJson` | `getJson(): unknown` | The stored answer as parsed JSON; **throws** if it is not JSON-compatible. |
| `isJson` | `isJson(): boolean` | Returns the `expectJson` flag this `Answer` was constructed with (does not inspect content). |
| `Answer.parsePython` | `parsePython(value: string): string` | Static. Extracts Python code from a code block in the response. |

## Types

- **DAPMessage**: `{ type, seq, command?, arguments?, body?, success?, message?, request_seq?, event?, token?, data?, trace? }`.
- **TASK_STATUS**: Task status with `completedCount`, `totalCount`, `completed`, `state`, `exitCode`, and many more fields.
- **PIPELINE_RESULT**: `{ name, path, objectId, result_types?, [key: string]: any }`.
- **PipelineConfig**: Pipeline definition with `name`, `description`, `version`, `components`, `source`, `project_id`.
- **UPLOAD_RESULT**: Per-file result with e.g. `action` (`'complete'` \| `'error'`), `filepath`, `error?`, `result?`, `upload_time?`.
- **ConnectResult**: Identity payload returned by `connect()`/`login()` — user, organizations, apps, teams.
- **QuestionHistory**: `{ role: string, content: string }` · **QuestionExample**: `{ given: string, result: string }` · **QuestionType**/**QuestionText**.
- **Deploy types**: `DeployArtifact`, `Deployment`, `DeploymentSchedule`, `DeployActor`, `DeployHistoryEntry`, `PublishResult`, `DeployListEnvelope<T>` (the generic list/versions/history envelope), `DeployListParams`, `SchedulePreview` (from `rocketride`).
- **Sequelize types**: `CreateSequelizeOptions`, `SequelizeConstructor` (see [Sequelize over Pipelines](/clients/typescript/database-sequelize)). <!-- language-specific -->

## Advanced: low-level DAP

For commands not covered by the typed surface. TypeScript composes
`buildRequest()` + `request()` (the one-step `dap_request` shorthand is
Python-only).

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `buildRequest` | `buildRequest(command: string, options?: { token?: string; arguments?: Record<string, unknown>; data?: Uint8Array \| string }): DAPMessage` | `DAPMessage` | Builds a DAP request message with the next sequence number. |
| `request` | `request(request: DAPMessage, timeout?: number): Promise<DAPMessage>` | `Promise<DAPMessage>` | Sends the request and returns the response. `timeout` (ms) overrides the config default for this call. Check `didFail(response)` before using `response.body`. |
| `didFail` | `didFail(request: DAPMessage): boolean` | `boolean` | `true` when the passed response indicated failure (`success === false`). |

```typescript
const req = client.buildRequest('rrext_monitor', { token, arguments: { types: ['apaevt_status_upload'] } });
const res = await client.request(req, 5000);
if (client.didFail(res)) throw new Error(res.message);
```


---

# File Storage

Route: /clients/typescript/storage

---
title: File Storage
sidebar_position: 6
---

# File Storage

Read, write, and manage files in your account's server-side store. All paths are
**relative** to the store root (e.g. `'docs/readme.md'`); absolute-like paths
(starting with `/` or `\`) are rejected. Method tables in the
[API reference](/clients/typescript/reference#store-file-access).

## Strings and JSON (start here)

The convenience wrappers manage the handle lifecycle for you:

```typescript
await client.fsWriteString('notes/todo.txt', 'buy milk');
const text = await client.fsReadString('notes/todo.txt');

await client.fsWriteJson('config/app.json', { debug: true });
const cfg = await client.fsReadJson<{ debug: boolean }>('config/app.json');
```

## Browse and inspect

```typescript
const { entries } = await client.fsListDir('reports'); // { entries: [{name, type, size?, modified?}], count }
for (const e of entries) console.log(e.name, e.type);

const meta = await client.fsStat('reports/q3.pdf'); // { exists, type?, size?, modified? }
await client.fsMkdir('reports/2026');
await client.fsRename('reports/q3.pdf', 'archive/q3.pdf');
await client.fsDelete('archive/q3.pdf');
await client.fsRmdir('reports/2026', true);
```

`fsRename` moves files or directories (copy+delete on object stores, recursive for
directories).

## Binary I/O (handles)

For large or binary files, use the explicit handle lifecycle — `fsOpen` →
`fsRead`/`fsWrite` → `fsClose`, in up-to-4 MB chunks. `fsClose` must receive the
same mode as `fsOpen`.

```typescript
const { handle } = await client.fsOpen('uploads/video.mp4', 'w');
try {
	const chunkSize = 4 * 1024 * 1024;
	for (let offset = 0; offset < file.size; offset += chunkSize) {
		const chunk = new Uint8Array(await file.slice(offset, offset + chunkSize).arrayBuffer());
		await client.fsWrite(handle, chunk);
	}
} finally {
	await client.fsClose(handle, 'w');
}
```

Read mode's `fsOpen` result also includes `size`; an empty array from `fsRead`
means EOF.

## Batch reads

`fsReadMany(paths)` fetches many small files in **one** round trip (max 256 paths /
32 MiB total per call). Missing or unreadable files come back as per-entry results
(`ok: false` + `error`), never a call failure; results arrive in request order with
`data` as `Uint8Array`.

## Direct URLs

`fsGetUrl(path, expiresIn?, downloadName?)` returns a time-limited HTTP(S) URL for
direct browser access (`expiresIn` in seconds, default 3600). Cloud backends
(S3/Azure) return a presigned/SAS URL; the local filesystem backend returns a
JWT-signed `/task/fetch` URL. Served **inline** by default — right for
`<img>`/`<video>`/`<audio>` sources:

```typescript
const streamUrl = await client.fsGetUrl('uploads/video.mp4', 600);
```

Pass `downloadName` to force a download with that filename via
`Content-Disposition: attachment` — the only reliable way to set the download
filename for cross-origin cloud URLs (where the `<a download>` attribute is
ignored):

```typescript
const downloadUrl = await client.fsGetUrl('uploads/video.mp4', undefined, 'my video.mp4');
```


---

# Introduction

Route: /clients/vscode

---
title: Introduction
sidebar_label: Overview
sidebar_position: 1
---

<p align="center">
  <img src="https://raw.githubusercontent.com/rocketride-org/rocketride-server/develop/apps/vscode/assets/banner-vscode.png" alt="RocketRide for VS Code" width="900" />
</p>

<p align="center">
  Build, debug, and deploy AI pipelines - without leaving your IDE.
</p>

> **Works in every VS Code-based editor.** The same build supports VS Code and
> forks such as **Cursor**, **Windsurf**, and **VSCodium** — the visual canvas,
> runtime management, and pipeline tooling behave identically everywhere. The
> extension also auto-detects your coding agent — GitHub Copilot, Claude Code,
> Cursor, or Windsurf — and writes **RocketRide agent rules** into your
> workspace so the editor's AI understands how to build RocketRide pipelines.

<p align="center">
  <a href="https://marketplace.visualstudio.com/items?itemName=RocketRide.rocketride"><img src="https://img.shields.io/visual-studio-marketplace/v/RocketRide.rocketride?color=222223&label=Marketplace" alt="VS Code Marketplace" /></a>
  <a href="https://github.com/rocketride-org/rocketride-server"><img src="https://img.shields.io/github/stars/rocketride-org/rocketride-server?style=flat&color=238636&label=GitHub&logo=github&logoColor=white" alt="GitHub" /></a>
  <a href="https://discord.gg/PMXrtenMsY"><img src="https://img.shields.io/badge/Discord-Join-370b7a?logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="https://github.com/rocketride-org/rocketride-server/blob/develop/LICENSE"><img src="https://img.shields.io/badge/License-MIT-41b6e6" alt="MIT License" /></a>
</p>

## Quick Start

1. Install the **RocketRide** extension from the VS Code Marketplace
2. Click the **RocketRide** icon in the Activity Bar
3. Create a `.pipe` file - it opens automatically in the visual canvas builder
4. Wire up nodes by connecting input and output lanes, then hit **Play** to run

## What is RocketRide?

[RocketRide](https://rocketride.org) is an open-source, developer-native AI pipeline platform.
It lets you build, debug, and deploy production AI workflows without leaving your IDE -
using a visual drag-and-drop canvas or code-first with TypeScript and Python SDKs.

You build your `.pipe` - and you run it against the fastest AI runtime available.

- **100+ ready-to-use nodes** - 15+ LLM providers, 9 vector databases, OCR, NER, PII anonymization, and more
- **High-performance C++ engine** - production-grade speed and reliability
- **Deploy anywhere** - locally, on-premises, or self-hosted with Docker
- **MIT licensed** - fully open-source, OSI-compliant

## Features

- **Visual canvas builder** - Drag, drop, and wire up AI workflows directly in VS Code. Create `.pipe` files to get started.
- **Debugging & live traces** - Monitor running pipelines in real time with execution traces, token usage, and memory stats, see exactly what your agents are doing at every step.

- **App Builder** - Scaffold, live-preview, publish, and deploy [Shell Apps](/guides/apps) from a template, without leaving VS Code.
- **Connection manager** - Connect to a local engine (one click, no setup) or your own on-premises server.
- **SDKs for TypeScript, Python & MCP** - Embed pipelines in your apps or expose them as tools for AI assistants.

Need inspiration? Check out [awesome-rocketride](https://github.com/rocketride-org/awesome-rocketride#demos--examples), a collection of example projects built on RocketRide.

## Extension Settings

| Setting                              | Type       | Default                          | Description                                                                                                                               |
| ------------------------------------ | ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `rocketride.development.connectionMode` | `string` | `"local"`                        | Connection mode: `"local"` (your machine), `"docker"`, `"service"`, `"onprem"` (your own hosted server), or `"cloud"`                     |
| `rocketride.development.hostUrl`     | `string`   | `""`                             | Host URL for on-prem or direct connections. Host and port will be parsed from this URL.                                                   |
| `rocketride.deployment.connectionMode` | `string \| null` | `null`                   | Deployment connection mode (`null` = same as development)                                                                                 |
| `rocketride.deployment.hostUrl`      | `string`   | `""`                             | Host URL for the deployment connection                                                                                                    |
| `rocketride.defaultPipelinePath`     | `string`   | `"${workspaceFolder}/pipelines"` | Default directory path for creating new pipeline files                                                                                    |
| `rocketride.development.local.engineVersion` | `string` | `"latest"`                 | Engine version to download. `"latest"` for newest stable, `"prerelease"` for newest prerelease, or a specific tag like `"server-v3.1.1"`. |
| `rocketride.deployment.local.engineVersion` | `string` | `"latest"`                  | Engine version for the local deployment target                                                                                            |
| `rocketride.taskArguments`           | `string`   | `""`                             | Additional command-line arguments passed to each pipeline task                                                                            |
| `rocketride.pipelineDebugOutput`     | `boolean`  | `false`                          | Enable full debug output for pipeline tasks (`--trace=debugOut`)                                                                          |
| `rocketride.pipelineRestartBehavior` | `string`   | `"prompt"`                       | Behavior when a `.pipe` file changes while the pipeline is running: `"auto"`, `"manual"`, or `"prompt"`                                   |
| `rocketride.pipelineTTL`             | `integer`  | `900`                            | Default idle timeout (seconds) before a running pipeline is shut down; `0` = run forever                                                  |
| `rocketride.pipelineTraceLevel`      | `string`   | `"full"`                         | Tracing verbosity for pipeline execution: `"full"`, `"summary"`, `"metadata"`, or `"none"`                                                |
| `rocketride.welcomeDismissed`        | `boolean`  | `false`                          | Set to `true` to skip the welcome page on startup                                                                                         |
| `rocketride.integrations.autoAgentIntegration` | `boolean` | `true`                  | Auto-detect and install RocketRide documentation for coding agents (Copilot, Claude Code, Cursor, Windsurf) on startup                    |
| `rocketride.integrations.copilot`    | `boolean`  | `false`                          | Enable RocketRide integration with GitHub Copilot                                                                                         |
| `rocketride.integrations.claudeCode` | `boolean`  | `false`                          | Enable RocketRide integration with Claude Code                                                                                            |
| `rocketride.integrations.cursor`     | `boolean`  | `false`                          | Enable RocketRide integration with Cursor                                                                                                 |
| `rocketride.integrations.windsurf`   | `boolean`  | `false`                          | Enable RocketRide integration with Windsurf                                                                                               |
| `rocketride.integrations.claudeMd`   | `boolean`  | `false`                          | Install RocketRide instructions to `CLAUDE.md` at the repo root                                                                           |
| `rocketride.integrations.agentsMd`   | `boolean`  | `false`                          | Install RocketRide instructions to `AGENTS.md` at the repo root                                                                           |
| `rocketride.appdev.shellUrl`         | `string`   | `""`                             | App Builder: override the preview shell base URL (empty = the Development Mode engine)                                                    |
| `rocketride.appdev.autoWatch`        | `boolean`  | `true`                           | App Builder: start the app watch/rebuild session automatically when an App Builder screen opens                                           |

## Commands

| Command                                    | Description                      |
| ------------------------------------------ | -------------------------------- |
| `RocketRide: Settings`                     | Open extension settings          |
| `RocketRide: Server Monitor`               | View server and pipeline status  |
| `RocketRide Pipeline: Create New Pipeline` | Create a new `.pipe` file        |
| `RocketRide Pipeline: Run`                 | Run the selected pipeline        |
| `RocketRide Pipeline: Stop Pipeline`       | Stop a running pipeline          |
| `RocketRide: Open as Text`                 | Open a `.pipe` file as raw JSON  |
| `RocketRide: Welcome`                      | Open the welcome page            |

Connect, disconnect, and reconnect are buttons in the sidebar connection panel, not command-palette commands.

## Links

- [Documentation](https://docs.rocketride.org/)
- [Discord](https://discord.gg/PMXrtenMsY)
- [GitHub](https://github.com/rocketride-org/rocketride-server)
- [Contributing](https://github.com/rocketride-org/rocketride-server/blob/develop/CONTRIBUTING.md)
- [Security](https://github.com/rocketride-org/rocketride-server/blob/develop/SECURITY.md)

## License

MIT - see [LICENSE](https://github.com/rocketride-org/rocketride-server/blob/develop/LICENSE).


---

# App Builder

Route: /clients/vscode/app-builder

---
title: App Builder
sidebar_position: 4
---

# App Builder

The App Builder is the extension's workbench for building apps that run
inside the RocketRide shell. The loop (create, design, package, deploy)
and how pipelines fit into an app are documented in the
[App Builder guide](/guides/apps/app-builder). This page covers the
extension surface around it.

## Opening it

- **RocketRide: New App** in the command palette (or **New App** in the
  sidebar's app list) scaffolds an app into `apps/` and opens the builder.
- Switch the RocketRide sidebar to apps mode: **MY APPS** lists the
  `.rrapp`-bound apps found in your open workspace folders. Clicking a row
  opens its App Builder.
- Opening an app's `<name>.rrapp` file opens the builder for that app.

## Settings

| Setting | Default | Meaning |
| --- | --- | --- |
| `rocketride.appdev.autoWatch` | `true` | Start the watch session automatically when an App Builder opens |
| `rocketride.appdev.shellUrl` | `""` | Override the preview shell base URL (empty = the Development Mode engine). The origin must match the connected server, or the preview can't see your dev overlay |

## Debugging

Press F5 (**Debug App**) to open the previewed app in an external browser
with the debugger attached.

See the [App Builder guide](/guides/apps/app-builder) for everything else,
and the [Shell API](/guides/apps) for the hooks and descriptor the scaffold
gives you.


---

# Cloud Sign-In

Route: /clients/vscode/cloud-sign-in

---
title: Cloud Sign-In
sidebar_position: 5
---

# Cloud sign-in (Zitadel OIDC)

Signing in to RocketRide Cloud from the extension runs an OIDC authorization
code flow with PKCE against Zitadel. The extension opens the system browser and
receives the result through a deep link back into your editor.

## Which application the extension signs in as

Zitadel identifies the caller by a **client id**, and that id names a specific
application registration. The extension has its own registration, separate from
the one the website uses, because the two need different things:

| | extension | website |
|---|---|---|
| application type | native | web |
| redirect | `vscode://rocketride.rocketride/auth/callback` | `https://<host>` |

The redirect is the reason they cannot share. The extension's callback uses your
editor's URI scheme, and only the native registration lists those. A web
registration does not, so an authorization request that mixes the two is
rejected before any browser window opens:

```json
{"error":"invalid_request",
 "error_description":"The requested redirect_uri is missing in the client configuration."}
```

The scheme is your editor's, not literally `vscode` — `vscode-insiders`,
`cursor`, `windsurf`, `trae` and others each get their own, and all are
registered.

## Where the client id comes from

`RR_ZITADEL_VSCODE_CLIENT_ID` is inlined into the extension at build time by
`apps/vscode/esbuild.js`, which fails the build outright if it is missing. That
baked value is the default and needs no configuration.

## Overriding the tenant

`ioControl('signin', …)` accepts `zitadelUrl` and `clientId`. **They are a
pair.** Supply both to sign in against a different Zitadel tenant, or neither to
use the built-in values.

Supplying only `zitadelUrl` is rejected with an error rather than attempted. A
client id is a registration *inside* a tenant, so the built-in id means nothing
against a different one — the request would reach the new tenant carrying an id
it has never heard of, and fail with the same message as above. Rejecting it
early gives a reason instead of a puzzle.

The mirror case is **not** symmetric, and the asymmetry is deliberate. Supplying
only `clientId` is not rejected — it is **ignored**, and sign-in proceeds with
both built-in values. A client id names a registration inside a tenant, so an id
with no tenant to read it against has nothing to select; discarding it is what
makes the extension reach its own native registration instead of whatever the
caller happened to hold. That is precisely the bug this contract exists to
prevent, so the lone id is dropped on purpose rather than honoured.

It is dropped silently, though. If you pass a `clientId` and sign in as an
application you did not name, that is why.

```ts
// both — sign in against another tenant
ioControl(mode, 'signin', { zitadelUrl: 'https://auth.example.com',
                            clientId:   '123456789012345678' });

// neither — the normal case
ioControl(mode, 'signin');

// zitadelUrl alone — rejected, with an explanation
ioControl(mode, 'signin', { zitadelUrl: 'https://auth.example.com' });
```

## If sign-in fails

**Nothing happens when you click sign in.** The authorization request was
rejected before the browser opened. Check the client id in the URL if you can
see it — a mismatch between the application it names and the redirect the
extension sends is the usual cause.

**The browser opens and returns an error page.** Read the
`error_description`. `redirect_uri is missing in the client configuration`
means the registration you reached does not list your editor's scheme.

**Sign-in reports success but you are still signed out.** Report it. That
combination should not be reachable, and it hides its own cause.


---

# Deployment Webview Protocol

Route: /clients/vscode/deployment-webview

---
title: Deployment Webview Protocol
date: 2026-07-31
sidebar_position: 5
---

# Deployment webview protocol

The deploy surfaces (the file view's DEPLOY page and the team-deployment
record drawer) are rendered by shared UI components inside the Project
webview; the extension host owns the SDK connection and does ALL
SDK-to-view-model mapping before anything crosses `postMessage`. The
contract lives in `src/providers/types/deployTypes.ts` — this page mirrors
its exported surface. (One exception: `shell:connectionChange` is
deliberately not declared in `deployTypes.ts`; it comes from
`ShellHostToWebview`, composed into the per-view unions in `types.ts`.)

Conventions shared by both protocols:

- **View-model DTOs** (`DeployTeamRefDTO`, `DeployVersionCardDTO`,
  `TeamDeploymentRowDTO`, `TeamDeploymentScheduleDTO`,
  `DeployHistoryRowDTO`, `DeployScheduleRowDTO`, `DeploymentInfoDTO`,
  `SchedulePreviewResultDTO`) mirror
  `apps/shared/src/components/deploy-panel/types.ts` — the contract
  of record — field-for-field, so the webview hands them to the shared
  `DeployPanel` / `DeploymentView` components unchanged.
- **Two correlation styles**: MUTATION and RPC-style requests
  (`deploy:artifact`/`deploy:publish`/`deploy:deploy`, every
  `deployment:*` mutation, `deployment:preview`, `deployment:validate`)
  carry a `requestId`. Pure mutations' `…actionResult` reply echoes it with
  only an optional `error` string; the RPC-style reads' replies also carry
  their payload alongside the same echo — `deploy:artifactResult` carries
  `pipeline?`, `deployment:previewResult` carries `result` (+ optional
  `error`), and `deployment:validateResult` carries `result`. FETCH
  messages (`deploy:fetch`, `deployment:fetch`) carry NO `requestId`:
  their answer is a scoped push (`deploy:data`; `deployment:load` /
  `deployment:error` stamped with `teamId` + optional `sourceId`) that
  the host also re-sends after mutations, so it cannot be
  request-correlated by design.
- **Push-driven refresh**: nothing on these surfaces polls. The host relays
  `apaevt_deploy` invalidation events and live `apaevt_task` folds; the
  WEBVIEW then drives its own re-fetch.
- **Personal-deployment id mapping**: a personal deployment's RECORD id is the
  owner key `user~{uid}`; the wire id for API calls is `@me`. The HOST performs
  that mapping — API calls go out addressed `@me`, while every push
  (`deployment:load` / `deployment:error`) is stamped with the raw `user~{uid}`
  the webview opened with, so the record guard matches its own pushes.

## Deploy lifecycle (the file view's DEPLOY page)

`DeployLifecycleWebviewToHost` / `DeployLifecycleHostToWebview`:

| Direction | Message | Payload | Purpose |
| --- | --- | --- | --- |
| webview to host | `deploy:fetch` | `projectId` | Request the lifecycle snapshot for this project. |
| host to webview | `deploy:data` | `versions`, `deployments`, `teams` | The full snapshot: registry versions (newest first), this project's team deployments (the where-live rows), and the caller-visible teams with control rights. Pushed on fetch and after mutations. |
| webview to host | `deploy:artifact` | `requestId`, `projectId`, `version` | Fetch one immutable artifact's pipeline for the version cards' readonly-canvas record drawer. |
| host to webview | `deploy:artifactResult` | `requestId`, `pipeline?`, `error?` | The sha-verified pipeline JSON, or the failure reason. |
| webview to host | `deploy:publish` | `requestId`, `comment`, `deployTo?` | Publish the SAVED document as the next registry version (`deployTo` = one-step publish+deploy). |
| webview to host | `deploy:deploy` | `requestId`, `projectId`, `version`, `teamId` | Point a team at a version — promotion and rollback alike. |
| host to webview | `deploy:actionResult` | `requestId`, `error?` | Completion ack for publish/deploy requests. |

## Deployment record drawer (rides the Project webview channel)

The drawer lives INSIDE the Project webview, so every webview-to-host
message carries the TEAM identity (the project identity is the panel's
own). The scoped pushes (`deployment:load`, `deployment:error`) stamp it
back so a switched drawer ignores stale ones; the requestId-correlated
replies (`deployment:actionResult`, `deployment:previewResult`,
`deployment:validateResult`) and `shell:connectionChange` carry no
`teamId` — correlation or broadcast semantics make it unnecessary.

`DeploymentWebviewToHost` / `DeploymentHostToWebview`:

| Direction | Message | Payload | Purpose |
| --- | --- | --- | --- |
| webview to host | `deployment:fetch` | `teamId`, `sourceId?` | (Re-)fetch the deployment snapshot — on drawer open, on an `apaevt_deploy` invalidation, and after every mutation. `sourceId` absent = the TEAM record. |
| host to webview | `deployment:load` | `teamId` + `DeploymentLoadPayload` | The full host-mapped state of one team deployment: header info, the immutable artifact pipeline (readonly DESIGN), per-source schedule rows, versions, history, next-run previews, `runningSources`, and the caller's control rights. |
| host to webview | `deployment:error` | `teamId`, `sourceId?`, `error` | The record could not be loaded; the record guard (`teamId` + `sourceId`) drops errors from a stale fetch after switching records. |
| webview to host | `deployment:setDisabled` | `teamId`, `requestId`, `disabled` | The whole-deployment kill switch. |
| webview to host | `deployment:deployVersion` | `teamId`, `requestId`, `version` | Point this team at a version (Deploy version… / Rollback alike). |
| webview to host | `deployment:remove` | `teamId`, `requestId` | Soft-remove the deployment (history and artifacts survive). |
| webview to host | `deployment:runSource` | `teamId`, `requestId`, `sourceId` | Start one source NOW (the manual smoke-test dispatch). |
| webview to host | `deployment:stopSource` | `teamId`, `requestId`, `sourceId` | Stop one source's live run. |
| webview to host | `deployment:setSourceConfig` | `teamId`, `requestId`, `sourceId`, `traceLevel`, `debugOut` | Persist one source's execution settings. |
| webview to host | `deployment:setSchedulePaused` | `teamId`, `requestId`, `sourceId`, `paused` | Pause/resume one source's schedule — cron/ttl preserved. |
| webview to host | `deployment:setSchedule` | `teamId`, `requestId`, `sourceId`, `cron`, `ttl?` | Set (cron string) or clear (`null`) one source's schedule. |
| host to webview | `deployment:actionResult` | `requestId`, `error?` | Completion ack for any `deployment:*` mutation. |
| webview to host | `deployment:preview` | `teamId`, `requestId`, `cron`, `count` | Cron preview via the server's single evaluator — clients never parse cron. |
| host to webview | `deployment:previewResult` | `requestId`, `result`, `error?` | Validity + next occurrences. |
| webview to host | `deployment:validate` | `teamId`, `requestId`, `pipeline` | Pipeline validation passthrough for the readonly canvas. |
| host to webview | `deployment:validateResult` | `requestId`, `result` | Validation errors/warnings. |
| host to webview | `shell:connectionChange` | `isConnected` | Deploy-connection state for the drawer's connection indicator. |


---

# Google Account Sign-In

Route: /clients/vscode/google-oauth

---
title: Google Account Sign-In
sidebar_position: 4
---

# Google account sign-in (node OAuth)

Nodes that talk to Google services (for example the Gmail tool) offer a
"Login with Google" button in the node config panel. Google's consent screen
cannot render inside a VS Code webview, so the extension opens the system
browser and receives the resulting tokens through a deep link.

## Flow

1. The webview asks the host to open the hosted OAuth broker URL.
2. The extension opens the system browser at the broker
   (`https://oauth2.rocketride.ai/google?...`), passing the node's service
   config, a `baseURL` return address, and an explicit `scope` parameter for
   the node's selected access tier. Scopes are keyed by the node's provider
   (see `SERVICE_TIER_SCOPES` in `LoginWithGoogleButton.tsx`, mirroring the
   per-service `AccessSpec`s in `google_access.py`); an unknown provider or
   tier sends no `scope` parameter. The broker grants identity
   (`openid email profile`) plus exactly the requested scopes — least
   privilege — validated against an allowlist (unknown scopes are rejected
   with `400 invalid_scope`). Requests without a `scope` parameter fall back
   to the broker's legacy default consent (identity + Drive), which never
   includes Gmail.
3. The user completes Google's consent screen. The broker exchanges the code
   using its own verified Google application; no client secret ever reaches
   the extension or the pipeline config.
4. The broker redirects to the bounce page
   (`https://api.rocketride.ai/auth/vscode/google`), which forwards the result
   to the editor deep link `vscode://rocketride.rocketride/auth/google`.
5. The extension routes the tokens to the **live** editor for the document
   that started the login (resolved at delivery time — the original webview
   may have been recycled during the browser round-trip). If no live editor
   exists, the tokens are held and redelivered after the next editor load;
   undelivered tokens expire after 5 minutes. After the webview applies the
   tokens, the host saves the document, so the tokens reach the `.pipe` file
   without a manual save.

## Host and webview contract

Messages exchanged between the extension host and the pipeline editor webview:

| Direction | Message | Payload | Purpose |
| --- | --- | --- | --- |
| host to webview | `project:load` | `oauthReturnUrl: string` | The `baseURL` the webview passes to the broker. In VS Code this is the bounce page URL carrying the editor's URI scheme (`?scheme=vscode`, `vscode-insiders`, etc.). Sent on every load; a load also clears any webview-held pending tokens — but the host redelivers undelivered broker tokens right after the load, so a reload during the browser trip does not lose them. |
| webview to host | `project:openExternal` | `url: string` | Ask the host to open the broker URL in the system browser. The host registers a one-shot token waiter keyed by the URL's `node_id` before opening. If the browser fails to open, the waiter is unregistered and an error is shown. |
| host to webview | `project:oauthTokens` | `tokens: string, state: string` | Raw broker result, delivered to the current live webview for the originating document. `state` is JSON echoing the originating `node_id`; the config panel applies tokens only to the matching node, then clears them. The host saves the document after the first `project:contentChanged` that follows a delivery (one-shot), so no manual save is needed. |

The deep link handled by the extension is
`<uriScheme>://rocketride.rocketride/auth/google` with query parameters
`tokens`, `state`, and on failure `oauth_error` / `error` /
`error_description` (see `CloudAuthProvider.handleProviderOAuth`, the shared Google/Microsoft handler).

## Saved config shape

Tokens land at the node config **root**: `authType: "user"` and
`userToken: "<JSON token string>"`. Node configs are flat — the engine reads
`cfg.get('authType')` / `cfg.get('userToken')` at the top level, and the
generated form schema names dotted `services.json` field ids (for example
`google.userToken`) by their last component. The `parameters.*` locations some
widgets also read are legacy and are never written by this flow.

## Scopes and access tiers

The granted scopes are fixed at consent time. Raising a node's access tier
after connecting (for example `modify` → `send`) requires disconnecting and
reconnecting the Google account so the new tier's scopes are consented.
Lowering the tier does not: the engine's scope check treats
`https://mail.google.com/` as covering every Gmail scope and `gmail.modify`
as covering `gmail.readonly` (`missing_scopes` in `core/google_access.py`).
Tokens without a `scope` field are accepted (fail-open, for older tokens).

## Limitation

Tokens are applied by the node config panel. If the panel is closed when the
deep link returns, the tokens stay pending in the editor until the panel is
reopened for the node that started the login (or until the editor reloads and
the redelivery expires). There is also no disconnect affordance yet — the
login button disables once authenticated; clearing a token currently means
editing the `.pipe` by hand.

## Token refresh

The saved token carries an `oauth_server_url` pointing at the broker's
`/refresh` endpoint. At runtime the engine only honors that URL when it is
`https` and its host is a known broker host; self-hosted deployments can add
their own broker host with the `RR_OAUTH_BROKER_URL` environment variable.


---

# Installation

Route: /clients/vscode/installation

---
title: Installation
date: 2026-03-02
sidebar_position: 2
---

## Installing the Extension

1. Open VS Code.
2. Go to the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`).
3. Search for **RocketRide**.
4. Click **Install**.

## First-Run Setup

On first launch, the extension shows a **Welcome** page to guide you through setup:

1. **Choose a connection mode**: Cloud, on-premises, or local.
2. **Enter your server URL**: For on-premises or local mode (default: `http://localhost:5565`).
3. **Enter your API key**: Your RocketRide authentication token. This is stored securely in VS Code's secret storage.
4. **Click Connect**: The extension tests the connection and shows status in the status bar.

After initial setup, the extension auto-connects on startup.

## Configuration Settings

Open VS Code settings (`Ctrl+,` / `Cmd+,`) and search for `rocketride` to configure:

### Connection

| Setting | Default | Description |
|---------|---------|-------------|
| `rocketride.development.connectionMode` | `local` | Development connection mode: `cloud`, `docker`, `service`, `onprem`, or `local` |
| `rocketride.development.hostUrl` | - | Host URL for the development connection (onprem/docker/service modes) |
| `rocketride.development.useCustomServer` | `false` | Cloud mode: connect to `cloudUrl` instead of RocketRide Cloud |
| `rocketride.development.cloudUrl` | `https://api.rocketride.ai` | Cloud mode: the server targeted when `useCustomServer` is enabled |
| `rocketride.deployment.connectionMode` | `null` | Deployment connection mode (`null` = share the development connection) |
| `rocketride.deployment.hostUrl` | - | Host URL for the deployment connection (onprem/docker/service modes) |
| `rocketride.deployment.useCustomServer` | `false` | Cloud mode: deploy to `cloudUrl` instead of RocketRide Cloud |
| `rocketride.deployment.cloudUrl` | `https://api.rocketride.ai` | Cloud mode: the server targeted when `useCustomServer` is enabled |

In cloud mode nothing is baked into the extension: unchecked, the connection
targets the `cloudUrl` setting's default; checked, it targets the address you
enter (e.g. a staging server or `http://localhost:5565`). Sign-in exchanges
its OAuth code against the same effective server.

> Credentials are not a settings key. Enter your API key with the **Settings** page command `rocketride.page.settings.setupCredentials` (update or clear it via `rocketride.page.settings.updateApiKey` / `rocketride.page.settings.clearApiKey`). It is held in VS Code SecretStorage, not in `settings.json`.

### Pipeline

| Setting | Default | Description |
|---------|---------|-------------|
| `rocketride.defaultPipelinePath` | - | Default directory for new pipeline files |
| `rocketride.pipelineRestartBehavior` | - | Restart behavior: `auto`, `manual`, or `prompt` |
| `rocketride.taskArguments` | - | Additional command-line arguments passed to each pipeline task |
| `rocketride.pipelineDebugOutput` | `false` | Enable full debug output for pipeline tasks (`--trace=debugOut`) |

### Local Engine

| Setting | Default | Description |
|---------|---------|-------------|
| `rocketride.development.local.engineVersion` | `latest` | Engine version: `latest`, `prerelease`, or a specific tag |

### Integrations

| Setting | Default | Description |
|---------|---------|-------------|
| `rocketride.integrations.autoAgentIntegration` | `true` | Automatically detect and install RocketRide documentation for coding agents (Copilot, Claude Code, Cursor, Windsurf) on startup |
| `rocketride.integrations.copilot` | - | Enable GitHub Copilot integration for pipeline development |
| `rocketride.integrations.claudeCode` | - | Enable Claude Code integration |
| `rocketride.integrations.cursor` | - | Enable Cursor IDE integration |
| `rocketride.integrations.windsurf` | - | Enable Windsurf integration |
| `rocketride.integrations.claudeMd` | - | Install RocketRide instructions to CLAUDE.md at the repo root |
| `rocketride.integrations.agentsMd` | - | Install RocketRide instructions to AGENTS.md at the repo root |


---

# Microsoft Account Sign-In

Route: /clients/vscode/microsoft-oauth

---
title: Microsoft Account Sign-In
sidebar_position: 6
---

# Microsoft account sign-in (node OAuth)

Nodes that talk to Microsoft 365 services (Excel, Word, OneDrive, Outlook
Mail, Outlook Calendar) offer a "Login with Microsoft" button in the node
config panel. Microsoft's consent screen cannot render inside a VS Code
webview, so the extension opens the system browser and receives the
resulting tokens through a deep link.

:::note Broker rollout in progress
The hosted OAuth broker's Microsoft provider and its bounce page are being
built in the cloud repo; this user-OAuth path goes live once they ship. The
[app-only (client credentials)](#app-authentication-client-credentials) path
below works today and does not depend on the broker.
:::

## Flow

1. The webview asks the host to open the hosted OAuth broker URL.
2. The extension opens the system browser at the broker
   (`https://oauth2.rocketride.ai/microsoft?...`), passing the node's service
   config, a `baseURL` return address, and an explicit `scope` parameter for
   the node's selected access tier. Scopes are keyed by the node's provider
   (see `SERVICE_TIER_SCOPES` in `LoginWithMicrosoftButton.tsx`, mirroring
   the per-service `AccessSpec`s in `microsoft_access.py`); an unknown
   provider or tier sends no `scope` parameter. Five services are covered:
   `excel`, `word`, and `onedrive` (`readonly` | `write`), `outlook_mail`
   (`readonly` | `send` | `modify`), and `outlook_calendar`
   (`readonly` | `write`). The broker grants identity
   (`openid email profile`) plus exactly the requested Graph scopes — least
   privilege.
3. The user completes Microsoft Entra's consent screen. The broker exchanges
   the code using its own verified Entra application; no client secret ever
   reaches the extension or the pipeline config.
4. The broker redirects to the bounce page
   (`https://api.rocketride.ai/auth/vscode/microsoft`), which forwards the
   result to the editor deep link
   `vscode://rocketride.rocketride/auth/microsoft`.
5. The extension routes the tokens to the **live** editor for the document
   that started the login (resolved at delivery time — the original webview
   may have been recycled during the browser round-trip). If no live editor
   exists, the tokens are held and redelivered after the next editor load;
   undelivered tokens expire after 5 minutes. After the webview applies the
   tokens, the host saves the document, so the tokens reach the `.pipe` file
   without a manual save.

## Host and webview contract

Messages exchanged between the extension host and the pipeline editor webview:

| Direction | Message | Payload | Purpose |
| --- | --- | --- | --- |
| host to webview | `project:load` | `oauthReturnUrl: string` | The `baseURL` the webview passes to the broker. In VS Code this is the bounce page URL carrying the editor's URI scheme (`?scheme=vscode`, `vscode-insiders`, etc.). Sent on every load; a load also clears any webview-held pending tokens — but the host redelivers undelivered broker tokens right after the load, so a reload during the browser trip does not lose them. |
| webview to host | `project:openExternal` | `url: string` | Ask the host to open the broker URL in the system browser. The host registers a one-shot token waiter keyed by the URL's `node_id` before opening. If the browser fails to open, the waiter is unregistered and an error is shown. |
| host to webview | `project:oauthTokens` | `tokens: string, state: string` | Raw broker result, delivered to the current live webview for the originating document. `state` is JSON echoing the originating `node_id`; the config panel applies tokens only to the matching node, then clears them. The host saves the document after the first `project:contentChanged` that follows a delivery (one-shot), so no manual save is needed. |

The deep link handled by the extension is
`<uriScheme>://rocketride.rocketride/auth/microsoft` with query parameters
`tokens`, `state`, and on failure `oauth_error` / `error` /
`error_description` (see `CloudAuthProvider.handleProviderOAuth`, the shared Google/Microsoft handler).

## Saved config shape

Tokens land at the node config **root**: `authType: "user"` and
`userToken: "<JSON token string>"`. Node configs are flat — the engine reads
`cfg.get('authType')` / `cfg.get('userToken')` at the top level, and the
generated form schema names dotted `services.json` field ids (for example
`microsoft.userToken`) by their last component. The `parameters.*` locations
some widgets also read are legacy and are never written by this flow.

## Scopes and access tiers

The granted scopes are fixed at consent time. Raising a node's access tier
after connecting (for example Outlook Mail `modify` → a tier needing more
scopes) requires disconnecting and reconnecting the Microsoft account so the
new tier's scopes are consented. Lowering the tier does not: the engine's
scope check treats a family's `.ReadWrite` (or `.ReadWrite.All`) scope as
covering the matching `.Read` scope, and any `.All` scope as covering the
same scope without `.All` (`missing_scopes` in `core/microsoft_access.py`).
Tokens without a `scope` field are accepted (fail-open, for older tokens).

The five services and their tiers (see `SERVICE_TIER_SCOPES` in
`LoginWithMicrosoftButton.tsx` and the `AccessSpec`s in
`nodes/src/nodes/core/microsoft_access.py`):

| Service | Tiers | Scopes |
| --- | --- | --- |
| Excel | `readonly`, `write` (default) | `Files.ReadWrite` / `Files.ReadWrite` (Graph's workbook API accepts only delegated `Files.ReadWrite`, reads included; the `readonly` tier is a node-side write gate) |
| Word | `readonly`, `write` (default) | `Files.Read` / `Files.ReadWrite` |
| OneDrive | `readonly`, `write` (default) | `Files.Read` / `Files.ReadWrite` (sign-in also requests `User.ReadBasic.All` for invite recipient lookup; personal accounts cannot grant it, and the invite gate then refuses invites) |
| Outlook Mail | `readonly`, `send`, `modify` (default) | `Mail.Read` / `Mail.Read` + `Mail.Send` / `Mail.ReadWrite` + `Mail.Send` |
| Outlook Calendar | `readonly`, `write` (default) | `Calendars.Read` / `Calendars.ReadWrite` |

## Limitation

Tokens are applied by the node config panel. If the panel is closed when the
deep link returns, the tokens stay pending in the editor until the panel is
reopened for the node that started the login (or until the editor reloads
and the redelivery expires). There is also no disconnect affordance yet —
the login button disables once authenticated; clearing a token currently
means editing the `.pipe` by hand.

## Token refresh

The saved token carries an `oauth_server_url` pointing at the broker's
`/refresh` endpoint. At runtime the engine only honors that URL when it is
`https` and its host is a known broker host; self-hosted deployments can add
their own broker host with the `RR_OAUTH_BROKER_URL` environment variable.

## App authentication (client credentials)

The Word, OneDrive, Outlook Mail, and Outlook Calendar tool nodes also accept
`microsoft.authType: "service"` — an Entra app registration authenticating
with its own client credentials instead of a signed-in user. This path does
not depend on the OAuth broker and works today.

:::caution Excel is user OAuth only
Microsoft Graph's workbook (Excel) API does not support application
permissions — an app-only token is rejected regardless of what the app
registration has been granted. The Excel node therefore needs the
[user sign-in](#flow) path with the delegated `Files.ReadWrite` permission
(its own README documents this). Do not add Excel to the app-only walkthrough
below.
:::

### Entra app registration walkthrough

1. In the **Entra admin center** (`entra.microsoft.com`) go to
   **App registrations** → **New registration**. Register a
   **single-tenant** app (accounts in this organizational directory only).
2. Under **API permissions**, add **Microsoft Graph** →
   **Application permissions** (not delegated) matching each service the
   node will use **and the access tier configured on that node**
   (`<service>.access`). The engine checks the token's granted permissions
   against the tier's required scopes (`missing_scopes` in
   `core/microsoft_access.py`); an `.All` application permission satisfies
   the matching delegated scope name.

   | Service | Tier | Application permission |
   | --- | --- | --- |
   | Word | `readonly` | `Files.Read.All` |
   | Word | `write` (default) | `Files.ReadWrite.All` |
   | OneDrive | `readonly` | `Files.Read.All` |
   | OneDrive | `write` (default) | `Files.ReadWrite.All` |
   | OneDrive | any, when `onedrive.allowPublicSharing` is off and the agent uses `onedrive_invite` | `User.Read.All` (directory lookup of invite recipients; without it the invite fails closed) |
   | Outlook Mail | `readonly` | `Mail.Read` |
   | Outlook Mail | `send` | `Mail.Read` + `Mail.Send` |
   | Outlook Mail | `modify` (default) | `Mail.ReadWrite` + `Mail.Send` |
   | Outlook Calendar | `readonly` | `Calendars.Read` |
   | Outlook Calendar | `write` (default) | `Calendars.ReadWrite` |

   `Mail.Send` is a separate action permission — `Mail.ReadWrite` does not
   imply it, so the `send` and `modify` tiers list both.
3. Click **Grant admin consent for &lt;tenant&gt;** — application permissions
   are tenant-wide and require an admin to consent; the app cannot self-consent.
4. Under **Certificates & secrets**, create a **client secret** and copy its
   value immediately (it is not shown again).
5. Fill in the node config:

   | Field | Value |
   | --- | --- |
   | `microsoft.authType` | `"service"` |
   | `microsoft.tenantId` | the Entra tenant (directory) ID |
   | `microsoft.clientId` | the app registration's application (client) ID |
   | `microsoft.clientSecret` | the client secret value from step 4 |
   | `microsoft.userPrincipalName` | the acting user's UPN (email-shaped sign-in name) |

   Application permissions are not scoped to a mailbox or drive by
   themselves — every Graph call the node makes targets
   `/users/{userPrincipalName}` (mail, calendar) or that user's OneDrive, so
   `userPrincipalName` selects whose data the app-only credentials act on.

### App-only limitations

- **Excel:** not available under app-only auth (see the caution above).
- **OneDrive `onedrive_restore`:** Graph's item restore is OneDrive Personal
  only; the tool refuses up front under app-only auth, which is always a
  work/school tenant. Use the OneDrive web recycle bin instead.
- **Outlook Calendar `outlook_calendar_find_meeting_times`:** Graph's
  `findMeetingTimes` needs a signed-in user context and may not be
  supported under client credentials.

### Narrowing app-only access

`Files.ReadWrite.All`, `Mail.ReadWrite`, and `Calendars.ReadWrite` grant the
app access to every mailbox/calendar/drive in the tenant, not just the
configured `userPrincipalName` — RocketRide does not enforce a narrower
scope itself, only the acting-user convention above. To restrict the app's
reach at the Microsoft 365 side:

- **Mail and calendar:** Exchange Online's
  [`New-ApplicationAccessPolicy`](https://learn.microsoft.com/en-us/powershell/module/exchange/new-applicationaccesspolicy)
  restricts an application permission grant to a mail-enabled security group
  of specific mailboxes, so the app can only act on the users in that group
  even though the Graph permission is tenant-wide.
- **Files (OneDrive/SharePoint):** the sites-selected pattern
  (`Sites.Selected` plus a site-level permission grant) narrows file access
  to specific SharePoint sites rather than every drive in the tenant; the
  bundled OneDrive node currently declares `Files.ReadWrite.All` and does
  not use `Sites.Selected`, so adopting it is a deployment-side choice, not
  something the node configures.

Both mechanisms are configured directly against Microsoft 365 / Entra, not
through RocketRide.


---

# Usage Guide

Route: /clients/vscode/usage

---
title: Usage Guide
date: 2026-03-02
sidebar_position: 3
---

## Creating a Pipeline

1. Use **File > New File > RocketRide Pipeline**, or click **+** in the RocketRide sidebar, to create a new `.pipe` file.
2. The visual editor opens automatically for `.pipe` files.
3. Drag components from the component palette onto the canvas.
4. Configure each component's properties in the properties panel.
5. Connect component outputs to inputs by drawing connections between lanes.
6. Save the file, changes are auto-saved.

## Running a Pipeline

1. Click the inline **Run** button on the pipeline item in the RocketRide sidebar, or press **Play** on the source node in the canvas.
2. The **Status** page opens with real-time execution monitoring.
3. Watch data flow through components, view completion metrics, and check for errors.

## Debugging a Pipeline

1. In the **Run and Debug** view, start the **RocketRide: Launch Pipeline** debug configuration (a `rocketride`-type launch configuration).
2. The debugger opens with breakpoint support.
3. Set breakpoints on components to pause execution.
4. Step through the pipeline and inspect variable values at each breakpoint.

## Attaching to a Running Pipeline

If a pipeline is already running on the server:

1. In the **Run and Debug** view, start the **RocketRide: Attach to Pipeline** debug configuration.
2. The **Status** page opens and streams real-time data from the running pipeline.

## Deploying to Cloud

1. Open the pipeline's **DEPLOY** page from the RocketRide sidebar (the file view's DEPLOY page).
2. Configure deployment settings.
3. Click **Deploy** to push the pipeline to RocketRide.ai cloud.

## Cloud Connection — Custom Server

Cloud mode connects to the production RocketRide Cloud by default. **Settings → Development** (or **→ Deployment**) → connection mode **Cloud** offers a custom-server opt-in for staging or self-hosted cloud environments:

- **Use custom server** (per group: `rocketride.<group>.useCustomServer` plus `rocketride.<group>.cloudUrl`, where `<group>` is `development` or `deployment`): when checked, a URL field appears and sign-in plus all traffic target that server. When unchecked (or the URL is empty), the default cloud server shown under the checkbox is used — the default comes from the extension's setting declaration, nothing is baked into the webview bundles.
- **Save and reconnect:** the panel probes whichever server the form currently names (compatibility check), and **Sign In** deliberately uses the form's in-form value — the OAuth code is exchanged against the server you see, even before Save. Everything else (deploys, runs, checkout) rides the active connection, so after changing the server: save the settings, sign out, and sign in again to establish the session on the new server.
- **Session/server mismatch:** the extension records which server each sign-in was made against. If the form later targets a different server, the Cloud panel says so and withholds the Subscribe/checkout surface until you sign in on the selected server — billing always happens on the server the panel describes, never a previous one.
- **Invalid or unreachable URLs:** the compatibility probe fails and the panel reports that the configured server does not support RocketRide Cloud; sign-in stays available only for servers that pass the probe. An empty custom URL falls back to the default server.

## Pipeline Editor

The visual editor provides:

- **Component palette**: Browse and search available nodes (sources, LLMs, stores, etc.).
- **Canvas**: Drag-and-drop workspace for arranging components.
- **Properties panel**: Configure selected component settings (API keys, models, connection strings, etc.).
- **Lane connections**: Draw lines between component output and input lanes to define data flow.

## Pipeline Execution Defaults

Trace verbosity, the idle timeout (TTL), task arguments, and debug output for pipeline runs are configured once in **Settings → Pipeline** — they are workspace settings, not per-pipeline options:

- **Pipeline Trace Level** (`rocketride.pipelineTraceLevel`, default `full`): how much execution-trace data the engine emits — `full`, `summary`, `metadata`, or `none`. Higher levels populate the **Flow** and **Trace** tabs, but `full` inlines entire payloads (including images), which can noticeably slow runs that process large images.
- **Pipeline TTL** (`rocketride.pipelineTTL`, default `900` = 15 minutes): how long the engine keeps a pipeline alive without activity before stopping it. Fixed choices from 15 minutes to 8 hours, plus "Run forever or until you stop it" (`0` = no timeout).
- **Task Arguments** (`rocketride.taskArguments`, default empty): additional command-line arguments passed to each pipeline task process. The engine splits the string using shell parsing rules, so quoted paths are preserved.
- **Pipeline Debug Output** (`rocketride.pipelineDebugOutput`, default `false`): appends `--trace=debugOut` to the task arguments (unless they already contain a `--trace=` flag) for detailed task trace logging.

The extension host reads these from the workspace settings and passes them to the engine on each `run`/`restart` (the `status:pipelineAction` message carries only the action and source). The engine process itself starts with no extra flags — these settings apply per task, not to the server.

## `.env` Auto-Sync

After a successful engine connection, the extension syncs the workspace `.env` only for the **development** connection group using a self-hosted mode (local, Docker, service, or direct/on-prem connection). It writes the resolved `ROCKETRIDE_URI` (including a dynamic local port when applicable) and `ROCKETRIDE_APIKEY`, preserves existing comments and variables, and does not rewrite the file when its contents are already current. The RocketRide **Python SDK** reads the workspace `.env` automatically from its process working directory; the TypeScript SDK and CLIs read only process environment variables, so export the values first (for example, `set -a; source .env`).

Cloud connections are not synced because their OAuth token is not an SDK API key. Deployment connections, workspaces with no folder open, and unreadable `.env` files are also skipped; a sync failure never affects the connection itself. Keep `.env` gitignored.

The extension never automatically removes these keys: disconnecting, engine exit, or switching to cloud leaves the last-synced values in place. Remove them by hand if you no longer want them. Each development-group self-hosted connection syncs again, so a hand-edited `ROCKETRIDE_APIKEY` is overwritten on the next successful connection.

## Monitoring Execution

The **Status** page shows:

- **Component status**: Pending, running, completed, or failed indicators for each component.
- **Data flow**: Visual representation of data moving through the pipeline.
- **Metrics**: Completion rates and timing charts.
- **Errors**: Detailed error messages and logs for failed components.

## AI-Assisted Development

When enabled, the Copilot and Cursor integrations provide:

- Pipeline structure suggestions based on your use case.
- Component configuration recommendations.
- Error diagnosis and fix suggestions.
- Pipeline optimization tips.

Enable these in settings under `rocketride.integrations.copilot` and `rocketride.integrations.cursor`.


---

# Advanced Agents

Route: /guides/advanced-agents

---
title: Advanced Agents
sidebar_position: 9
---

# Advanced Agents

This page builds on the foundations in [Agents & Tools](/concepts/agents-tools-skills)
to cover multi-agent patterns, memory strategies, and safety techniques for
production agent pipelines.

## Multi-agent hierarchies

A manager agent can invoke a specialist agent as a tool. The specialist is just
another pipeline; it has its own source, its own nodes, and its own response
target. The manager calls it the same way it calls any other tool: by sending a
question and receiving an answer.

```text
manager-pipeline.pipe
  source_1 (webhook)
  agent_1 (agent_rocketride)   ← manager
    ↓ invokes via tool call
    specialist-pipeline.pipe
      source_1 (webhook)
      llm_1 (llm_openai)
      target_1 (response)
```

The [`agent_rocketride`](/nodes/agent_rocketride) node supports this pattern
natively — expose any running pipeline as an MCP tool (see
[MCP Server](/connect/mcp/stdio)) and the manager agent can call it.

This is useful when different specialists need different models, memory, or
tool sets. Keep each specialist pipeline small and single-purpose.

## Parallel tool calls

When an agent's reasoning step identifies multiple independent tool calls, the
engine fans them out concurrently. If the agent decides to search the vector
store AND look up a database row in the same step, both calls happen in
parallel and the results are merged before the next reasoning step.

This behaviour is automatic — no pipeline configuration is required. The
latency of a multi-tool step is bounded by the slowest tool, not the sum of all
tool latencies.

## Agent-as-tool via MCP

Any running RocketRide pipeline is automatically exposed as an MCP tool by the
[MCP server](/connect/mcp/stdio). This means a Claude Desktop or Cursor session can
invoke your pipeline as a tool, making your pipeline an agent capability in an
external system.

To use a pipeline as a tool in another RocketRide agent, expose it via MCP and
configure the consuming agent's `tool_mcp_client` node to point at the MCP
server.

## Memory strategies

Memory nodes give agents context across turns. The right choice depends on
what you need to survive and how:

| Strategy | Node | Persists across | Use when |
| --- | --- | --- | --- |
| **Session memory** | [`memory_internal`](/nodes/memory_internal) | Nothing (resets on restart) | Conversation context within one session only |
| **Persistent memory** | [`memory_persistent`](/nodes/memory_persistent) | Pipeline restarts (Redis backend only) | Context must survive restarts; the default in-memory backend does not persist |
| **Long-term semantic memory** | `tool_mem0` | Restarts; searchable | Agent should recall extracted facts and user preferences across many sessions. Requires a Mem0 account or self-hosted instance |

For most conversational agents, `memory_internal` is the right default. Add
`memory_persistent` when sessions must resume after a restart. Use `tool_mem0`
when the agent is expected to build a model of the user or domain over many
interactions.

When using persistent or long-term memory, scope it tightly. Storing everything
degrades retrieval quality. Use the memory node's summarisation or extraction
settings to store only meaningful context.

## Guardrails in agent pipelines

Place a [`guardrails`](/nodes/guardrails) node on the `answers` lane **between
the agent and the response target** to validate outputs before they reach the
caller:

```text
agent_1 → (answers lane) → guardrails_1 → target_1 (response)
```

The guardrails node can check for:

- Harmful or policy-violating content.
- Outputs that fail a format constraint (e.g. must be valid JSON).
- Answers that contain PII when they should not.

If a check fails, the guardrails node blocks the output. The pipeline run
stops cleanly rather than returning an invalid answer to the caller.

## Limiting agent scope

Agents are powerful, but an agent with too many tools becomes hard to reason
about and may make unexpected tool calls. Keep the tool set small and specific:

- Give each agent only the tools it needs for its task.
- Use a `prompt` node to explicitly tell the agent which tools to prefer.
- Use the `max_waves` config (where available) to cap reasoning loops —
  an unbounded loop is a latency and cost risk.

## Related

- [Concepts: Agents & Tools](/concepts/agents-tools-skills): control connections, wiring.
- [MCP Server](/connect/mcp/stdio): exposing pipelines as MCP tools.
- [Concepts: Error Handling](/guides/error-handling): handling agent failures.
- [Best Practices](/guides/best-practices): agents vs. direct LLM calls.


---

# Shell API

Route: /guides/apps

---
title: Shell API
---

# Shell API

A complete guide for developers building micro-frontend applications for the RocketRide Cloud platform.

---

## Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Getting Started](#getting-started)
3. [The App Manifest](#the-app-manifest)
4. [The App Descriptor](#the-app-descriptor)
5. [Shell Props: What Your App Receives](#shell-props-what-your-app-receives)
6. [Screen Zones](#screen-zones)
7. [Shell Hooks & APIs](#shell-hooks--apis)
8. [The Connection Manager (connectionManager)](#the-connection-manager-connectionmanager)
9. [The Documents System](#the-documents-system)
10. [The Virtual File System (IVirtualFileSystem)](#the-virtual-file-system-ivirtualfilesystem)
11. [DocExplorer: File Tree Component](#docexplorer-file-tree-component)
12. [DocTabs: Tab Bar Component](#doctabs-tab-bar-component)
13. [Cross-App Component Loading](#cross-app-component-loading)
14. [Theming](#theming)
15. [Build Configuration](#build-configuration)

---

## Architecture Overview

Shell-UI is a thin shell framework that hosts micro-frontend applications via [Module Federation](https://module-federation.io/). The shell owns:

- **Four screen zones**: Sidebar, Client Area, Debug Panel (ALT+D), Status Bar
- **Authentication**: OAuth2 PKCE via Zitadel
- **Subscription gating**: Checks server-side subscription state before loading paid apps
- **WebSocket connection**: RocketRide client singleton
- **Workspace persistence**: Per-app state in `.workspace/` JSON files
- **Theme management**: CSS custom properties (`--rr-*`)
- **Event bus**: Typed message bus for cross-component communication

Apps are independent packages that export an `AppDescriptor` via Module Federation. The shell loads them lazily when the user activates the app.

```text
┌──────────┬─────────────────────────┬────────────┐
│          │                         │            │
│ Sidebar  │      Client Area        │   Debug    │
│          │                         │  (ALT+D)   │
│          │                         │            │
├──────────┴─────────────────────────┴────────────┤
│ ● Connected    Ready                            │
└─────────────────────────────────────────────────┘
```

The shell mounts one component from your app:
- `app` → Client Area (required). Your app composes its own layout inside (columns, sidebar, status bar) with `<AppLayout>`.

---

## Getting Started

You build a shell app in your own repository: `npm install rocketride`, export
an `AppDescriptor` through Module Federation, and deploy the bundle to any
shell host.

> **Shortcut:** the VS Code extension's [App Builder](/clients/vscode/app-builder)
> scaffolds this whole shape from a template and adds a live preview, publish,
> and deploy loop — the steps below explain what it generates.

### 1. Create a new project

```bash
mkdir my-app && cd my-app
npm init -y
npm install rocketride react react-dom
npm install -D @rsbuild/core @rsbuild/plugin-react @module-federation/rsbuild-plugin typescript
```

### 2. Project structure

```text
my-app/
├── package.json
├── rsbuild.config.ts
├── tsconfig.json
└── src/
    ├── index.ts           # MF async boundary
    ├── AppDescriptor.ts   # What the shell loads
    └── MyApp.tsx           # Client area component
```

### 3. Define the manifest in `package.json`

```json
{
  "name": "my-app",
  "version": "1.0.0",
  "appManifest": {
    "id": "mycompany.myApp",
    "publisher": "My Company",
    "name": "My App",
    "description": "A short description for the app store",
    "categories": ["tools"]
  },
  "dependencies": {
    "rocketride": "^1.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}
```

### 4. Create the AppDescriptor (`src/AppDescriptor.ts`)

Import types from `rocketride/app-sdk`:

```typescript
import type { AppDescriptor } from 'rocketride/app-sdk';
import MyApp from './MyApp';

const MY_APP: AppDescriptor = {
  id: 'mycompany.myApp',
  name: 'My App',
  branding: { appName: 'My App' },
  app: MyApp,
};

export default MY_APP;
```

### 5. Create the App component (`src/MyApp.tsx`)

```typescript
import React from 'react';
import type { ShellAppProps } from 'rocketride/app-sdk';

const MyApp: React.FC<ShellAppProps> = ({ isConnected, identity }) => {
  return (
    <div style={{ padding: 40, fontFamily: 'var(--rr-font-family)' }}>
      <h1>Hello from My App!</h1>
      <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
      <p>User: {identity?.displayName ?? 'Not logged in'}</p>
    </div>
  );
};

export default MyApp;
```

### 6. Async boundary (`src/index.ts`)

```typescript
import('./AppDescriptor');
```

### 7. rsbuild.config.ts

```typescript
import fs from 'node:fs';
import path from 'node:path';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8'));
const moduleId = (pkg.appManifest?.id ?? 'unknown').replace(/[^a-zA-Z0-9_$]/g, '_');

export default defineConfig(() => ({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: moduleId,
      filename: 'remoteEntry.js',
      exposes: { './AppDescriptor': './src/AppDescriptor.ts' },
      dts: false,
      shared: {
        react:              { singleton: true, eager: true, requiredVersion: '^18.2.0' },
        'react-dom':        { singleton: true, eager: true, requiredVersion: '^18.2.0' },
        'rocketride/app-sdk': { singleton: true, requiredVersion: false },
      },
    }),
  ],
  source: { entry: { index: './src/index.ts' } },
  output: {
    distPath: { root: './dist' },
    assetPrefix: 'auto',
  },
}));
```

### 8. Build and deploy

```bash
npx rsbuild build
```

Deploy the contents of `./dist/` to your hosting provider. The shell loads your app's `remoteEntry.js` at runtime when it appears in the app manifest.

---

## The App Manifest

Declared in `package.json` under the `appManifest` key. This metadata is available at boot without loading the app bundle, used for the app store, authentication gating, and settings.

```typescript
interface AppManifest {
  /** Stable unique identifier (e.g. 'rocketride.myApp'). */
  id: string;
  /** Publisher name shown in the app store (e.g. 'My Company'). */
  publisher?: string;
  /** Display name shown in the app switcher. */
  name: string;
  /** Short description for the app store. */
  description?: string;
  /** Path to icon file (e.g. './src/icon.svg'). */
  icon?: string;
  /** Markdown readme for the app detail page. */
  readme?: string;
  /** Categories for filtering (e.g. ['tools', 'ai']). */
  categories?: string[];
  /** When false, the app runs without authentication. Default: true. */
  authenticated?: boolean;
  /** When false, the shell header (app name/icon in the sidebar) is hidden. Default: true. */
  showHeader?: boolean;
  /** When false, the status bar is hidden for this app. Default: true. */
  showStatusBar?: boolean;
  /** Settings contribution (VSCode `contributes.configuration` shape). Shown in the shell's Settings overlay. */
  contributes?: { configuration?: AppConfiguration };
  /** Internal: MF module identifier (derived from id). */
  moduleId?: string;
  /** App lifecycle status (e.g. 'auth', 'free', 'unsubscribed', 'subscribed', 'trialing', 'past_due', 'canceled'). */
  appStatus?: string;
  /** Whether the app is available on the desktop (non-cloud) platform. */
  onDesktop?: boolean;
}
```

### Settings

Apps can declare runtime settings (API keys, config values) that the shell manages. The declaration lives under `appManifest.contributes.configuration` — the exact `contributes.configuration` shape from the VSCode extension manifest specification, with setting keys dotted and prefixed with the app id:

```json
{
  "appManifest": {
    "contributes": {
      "configuration": {
        "title": "My App",
        "properties": {
          "mycompany.myApp.apiKey": {
            "type": "string",
            "description": "Your API key for the external service",
            "required": true
          }
        }
      }
    }
  }
}
```

Each property is a `SettingSchema` (`type`, `default`, `description`, `enum`, `required`, ...). Display labels derive from the setting key, VSCode-style — there is no label field (`apiKey` renders as "Api Key").

Settings are:
- Rendered in the shell's Settings overlay (grouped by app)
- Persisted to `.workspace/settings.json`
- Available to your app via `useShellApiConfig()`, access as `config['mycompany.myApp.apiKey']`

---

## The App Descriptor

The runtime descriptor your app exports. Loaded lazily when the user first activates your app.

```typescript
interface AppDescriptor {
  id: string;                              // Must match manifest id
  name: string;                            // Display name
  icon?: React.ReactNode;                  // Icon in app switcher
  branding: ShellBrandingConfig;           // Sidebar header branding

  /** The app's ONE mount point — rendered raw in the client area. */
  app: React.ComponentType<ShellAppProps>;

  /** Optional cross-app component catalog. Never mounted by the shell. */
  components?: {
    [key: string]: React.ComponentType<any>;
  };
}
```

- **`app`** is the single component the shell mounts in the client area; the app composes its own layout inside (columns, sidebar, status bar) with `<AppLayout>`
- **`components`** entries (e.g. `Canvas`, `Toolbar`, `DataGrid`) are never mounted by the shell but are loadable by other apps via `useAppComponent()`

### ShellBrandingConfig

```typescript
interface ShellBrandingConfig {
  appName: string;                 // Sidebar header text
  logo?: React.ReactNode;          // Expanded sidebar logo
  logoCollapsed?: React.ReactNode; // Collapsed sidebar logo
  iconDark?: React.ReactNode;      // Icon for dark palette (light-colored)
  iconLight?: React.ReactNode;     // Icon for light palette (dark-colored)
  icon?: React.ReactNode;          // Generic fallback icon
  welcomeLogo?: React.ReactNode;   // Welcome/loading screen logo
  welcomeTitle?: string;           // Welcome screen title
  welcomeSubtitle?: string;        // Welcome screen subtitle
}
```

**Icon resolution order**: the shell picks the best icon for the sidebar header:
1. `iconDark` / `iconLight` (matched to the active palette mode)
2. `icon` (generic branding icon)
3. Manifest `icon` URL (from `package.json`)
4. 2-letter monogram fallback

Pre-built theme-aware SVGs are available in `shared/assets/rocketride/`:
- `rocketride-dark.svg`: light body (`#E0DDF0`) for dark backgrounds
- `rocketride-light.svg`: dark body (`#1E1A34`) for light backgrounds
- `rocketride.svg`: `currentColor` body, CSS-controlled

---

## Shell Props: What Your App Receives

### ShellAppProps (your App component)

```typescript
interface ShellAppProps {
  /** Whether the RocketRide WebSocket is currently connected. */
  isConnected: boolean;
  /** Authenticated user identity, or null when not logged in. */
  identity: ConnectResult | null;
}
```

---

## Screen Zones

| Zone | Owner | Content |
|------|-------|---------|
| **Sidebar** | Your `app` component's layout (`AppLayout`) | App switcher header, your sidebar content, theme/account/settings footer |
| **Client Area** | Your `app` component | Whatever your app renders |
| **Debug Panel** | Shell (ALT+D toggle) | Live event log, postMessage traffic |
| **Status Bar** | Shell | Connection status, app name, ready state |
| **Overlays** | Shell | Account, Billing, Settings (triggered from sidebar footer) |

If your app's layout renders no sidebar, the client area gets the full window width.

---

## Shell Hooks & APIs

`rocketride/app-sdk` is a subpath export of the `rocketride` package: at build
time it gives your app types and IntelliSense, and at runtime Module
Federation's shared singleton mechanism replaces its stubs with the real
implementations from the shell host itself, published as the `shell`
package, which is why in-workspace code generated by the app scaffold
imports the same hooks directly from `'shell'`.

Import everything from `'rocketride/app-sdk'`:

```typescript
import { useShellConnection, useShellApiConfig, useWorkspace, connectionManager } from 'rocketride/app-sdk';
```

### Connection

| Hook/Function | Returns | Purpose |
|---------------|---------|---------|
| `useShellConnection()` | `{ client, isConnected, statusMessage }` | Access the RocketRide WebSocket client |
| `useShellApiConfig()` | `ShellApiConfig` | Read runtime config (API URLs, keys, user settings) |
| `getClient()` | `RocketRideClient \| null` | Non-React access to the client singleton |

### Auth

| Hook | Returns | Purpose |
|------|---------|---------|
| `useAuthUser()` | `ConnectResult \| null` | Current authenticated user identity |
| `useLogout()` | `() => void` | Trigger logout |
| `useSubscriptions()` | `{ desktopApps, isOnDesktop(appId), getStatus(appId) }` | User's desktop apps and subscription state |

### Workspace

| Hook | Returns | Purpose |
|------|---------|---------|
| `useWorkspace()` | `IWorkspaceContext` | Access workspace state and dispatch |

The workspace context provides:
- `seeded`: True once pre-auth default state has been populated (before connection)
- `loaded`: True once persisted workspace state has been read from disk (after connection)
- `prefs`: Current app preferences (theme, active view, etc.)
- `appState`: Opaque per-app state (used by Documents)
- `settings`: User-configured settings
- `activeAppId`: Current app ID
- `appManifest`: All registered apps
- `appLoading`: Whether the active app is currently loading
- `loadedApps`: Map of already-loaded app descriptors (for cross-app component loading)
- `loadApp(appId)`: Trigger lazy loading of an app's descriptor
- `updateAppState(updater)`: Update per-app state — pass a function receiving the previous state and returning the next
- `updateSetting(key, value)`: Update a single setting
- `updatePrefs(patch)`: Update workspace preferences
- `themeOptions`: Available theme choices
- `setTheme(themeId)`: Switch the active theme
- `dispatch(action)`: Update prefs or switch apps
- `emit(event, payload)` / `on(event, handler)`: Event bus (delegates to connectionManager)

### Workspace Lifecycle: `seeded` vs `loaded`

The workspace has a two-phase startup:

1. **Seeded** (`seeded = true`, `loaded = false`): The workspace has been populated with hardcoded defaults (default prefs, empty appState, empty settings). This happens immediately, before authentication or WebSocket connection. The Shell renders at this point so unauthenticated apps (e.g. home/landing page) can display.

2. **Loaded** (`seeded = true`, `loaded = true`): The WebSocket is connected and persisted state has been read from disk (`.workspace/global.json`, per-app workspace files, `settings.json`). Persisted prefs, appState, and settings overwrite the seeded defaults. Debounced persistence (auto-save) only activates after this point.

**What this means for your app:**

- The **Shell** renders as soon as `seeded` is true. It is then up to each app to decide whether it needs to wait for `loaded`.
- **Unauthenticated apps** (`authenticated: false`) can render immediately on seeded state, they receive `isConnected=false` and `identity=null` and should be designed to work with those values.
- **Authenticated apps** that depend on persisted settings (API keys, saved state) should gate on `loaded` before rendering data-dependent UI:

```typescript
const { loaded, settings } = useWorkspace();

if (!loaded) return <div>Loading workspace…</div>;

// Safe to read persisted settings here
const apiKey = settings.MY_API_KEY;
```

- **Persistence is safe**: debounced saves to disk only fire when `loaded` is true, so seeded defaults are never accidentally written over persisted data.

---

## The Connection Manager (connectionManager)

A typed, module-level event bus singleton. Works from React components, hooks, plain functions, anywhere.

### Basic usage

```typescript
import { connectionManager } from 'rocketride/app-sdk';

// Emit an event
connectionManager.emit('shell:loginRequest', { appId: 'rocketride.myApp' });

// Subscribe to an event (returns unsubscribe function)
const unsub = connectionManager.on('shell:connected', () => {
  console.log('Connected!');
});

// Later: unsubscribe
unsub();
```

### In a React component

```typescript
useEffect(() => {
  const unsub = connectionManager.on('shell:event', ({ event }) => {
    console.log('Server event:', event);
  });
  return unsub; // cleanup on unmount
}, []);
```

### Defined events

| Event | Payload | Direction | Description |
|-------|---------|-----------|-------------|
| `shell:connected` | `{}` | Shell → Apps | WebSocket connection established |
| `shell:disconnected` | `{ reason: string; hasError: boolean }` | Shell → Apps | WebSocket connection lost |
| `shell:login` | `{ user: ConnectResult }` | Shell → Apps | User authenticated |
| `shell:logout` | `{}` | Shell → Apps | User logged out |
| `shell:loginRequest` | `{ appId?: string }` | Apps → Shell | Request OAuth login (optionally targeting an app) |
| `shell:logoutRequest` | `{}` | Apps → Shell | Request logout |
| `shell:switchApp` | `{ appId: string }` | Apps → Shell | Switch the active app |
| `shell:subscribe` | `{ app: AppManifestEntry, plan?: CheckoutPlan }` | Apps → Shell | Open subscription checkout for an app; optional `plan` preselects a tier and skips the picker (straight to payment) |
| `shell:myApps` | `{}` | Apps → Shell | Navigate to My Apps |
| `shell:accountUpdate` | `ConnectResult` | Server → Shell | Server-pushed account/subscription change |
| `shell:sidebarCollapsing` | `{}` | Shell → Apps | Sidebar is collapsing (for layout adjustments) |
| `shell:themeChange` | `{ tokens: Record<string, string> }` | Shell → Apps | Theme CSS tokens changed |
| `shell:statusChange` | `{ message: string \| null }` | Shell → Apps | Transient status bar text changed |
| `shell:event` | `{ event: unknown }` | Server → Apps | Raw server event forwarded from WebSocket |
| `shell:appsUpdated` | `{ apps: ShellAppEntry[] }` | Shell-internal | App list updated |
| `shell:manifestRefresh` | `{ source: string }` | Shell-internal | App manifest re-fetched |
| `shell:openOverlay` | `{ id: 'account' \| 'settings' \| 'environment' }` | Shell-internal | Open a shell overlay |
| `shell:unsubscribe` | `{ appId: string }` | Shell-internal | Cancel an app subscription |
| `shell:viewActivated` | `{ viewId: string }` | Shell-internal | A shell view became active |

The events marked **Shell-internal** exist only in the shell package's internal event map — they are not part of the `ShellEventMap` exported from `rocketride/app-sdk`, so external apps cannot emit or subscribe to them type-safely.

### Extending the event map

Add custom events via TypeScript module augmentation:

```typescript
declare module 'rocketride/app-sdk' {
  interface ShellEventMap {
    'myapp:dataUpdated': { recordId: string; timestamp: number };
    'myapp:exportComplete': { fileUrl: string };
  }
}

// Now type-safe:
connectionManager.emit('myapp:dataUpdated', { recordId: '123', timestamp: Date.now() });
```

### Debug logging

All events are automatically captured in a circular buffer (500 entries) visible in the Debug Panel (ALT+D).

```typescript
import { getDebugLog, clearDebugLog, onAny } from 'rocketride/app-sdk';

// Get all captured events
const log = getDebugLog(); // DebugLogEntry[]

// Listen to ALL events (for custom logging)
const unsub = onAny((event, payload) => {
  console.log(`[${event}]`, payload);
});
```

---

## The Documents System

A VS Code-style document model for apps that manage files/documents. **Completely opt-in**, simple apps don't need it.

`Documents` is an **instantiable class**: your app creates it, owns it, passes it where needed. The shell never sees it.

### Core concepts

| Concept | Description |
|---------|-------------|
| **Document** | One per URI. Holds content in memory. Tracks dirty state and version. |
| **Editor** | A view onto a Document. Independent viewport state (scroll, cursor). Multiple editors can view the same document. |
| **EditorGroup** | A pane container. Holds an ordered list of editors. Supports horizontal/vertical splits. |

### Creating an instance

Create a `Documents` instance in your App component, passing an `IVirtualFileSystem`:

```typescript
// src/docs.ts — shared instance for your app
import { Documents } from 'rocketride/app-sdk';
import type { IVirtualFileSystem } from 'rocketride/app-sdk';

let _docs: Documents | null = null;

export function getDocs(): Documents {
  if (!_docs) throw new Error('Documents not initialised');
  return _docs;
}

export function createDocs(vfs: IVirtualFileSystem): Documents {
  _docs = new Documents(vfs);
  return _docs;
}

export function destroyDocs(): void {
  _docs?.destroy();
  _docs = null;
}
```

```typescript
// src/MyApp.tsx
import { createDocs, destroyDocs } from './docs';

const MyApp: React.FC<ShellAppProps> = () => {
  const { client } = useShellConnection();

  useEffect(() => {
    const vfs: IVirtualFileSystem = {
      list:   (dir) => client.fsListDir(dir),
      read:   (path) => client.fsReadJson(path),
      write:  (path, content) => client.fsWriteJson(path, content),
      rename: (old, new_) => client.fsRename(old, new_),
      delete: (path) => client.fsDelete(path),
      mkdir:  (path) => client.fsMkdir(path),
    };
    createDocs(vfs);
    return () => destroyDocs();
  }, [client]);

  return <MyAppInner />;
};
```

### Using the instance (call methods from anywhere)

```typescript
import { getDocs } from './docs';

// Open a file
await getDocs().openDocument('path/to/file.txt');

// Create a new document with initial content
const uri = getDocs().createDocument(undefined, { key: 'value' });

// Update content (any serializable value — stored as-is)
getDocs().updateContent(uri, { key: 'updated' });

// Save to disk
await getDocs().saveDocument(uri);
```

All operations are methods on the `Documents` instance:

| Method | Description |
|--------|-------------|
| `openDocument(uri, groupId?)` | Open a file (reads from VFS if not already open) |
| `createDocument(groupId?, content?)` | Create a new untitled document |
| `closeEditor(editorId)` | Close an editor (disposes doc if last clean ref) |
| `updateContent(uri, content)` | Update in-memory content (marks dirty) |
| `saveDocument(uri)` | Write to disk via VFS (marks clean) |
| `revertDocument(uri)` | Re-read from disk (replaces content) |
| `splitGroup(groupId, orientation)` | Split an editor group |
| `moveEditor(editorId, targetGroupId)` | Move editor between groups |
| `closeGroup(groupId)` | Close all editors in a group |
| `setActiveEditor(groupId, index)` | Activate an editor within a group |
| `setActiveGroup(groupId)` | Focus a group |
| `openStaticDocument(uri, label, content?, groupId?)`\* | Open a read-only static document with a display label |
| `splitGroupWithDocument(groupId, orientation)`\* | Split a group, moving the active document to the new pane |
| `updateSplitSizes(splitNodeId, sizes)`\* | Update the sizes of a split layout node |
| `updateEditorViewport(editorId, patch)` | Merge an editor's scroll position and cursor coordinates |
| `updateEditorViewState(editorId, viewState)`\* | Persist an editor's opaque view state (the app owns its shape) |
| `getState()` | Read state without subscribing |
| `getDocument(uri)` | Get a single document by URI |
| `destroy()` | Clean up the instance |

\* Available on the `shell` package's `Documents` implementation but not yet declared on the `rocketride/app-sdk` `Documents` typing — external TypeScript builds referencing them will fail to type-check.

### React subscription

```typescript
import { getDocs } from './docs';

const MyComponent: React.FC = () => {
  const state = getDocs().useStore(); // re-renders on any state change

  const activeGroup = state.groups[state.activeGroupId];
  const activeEditorId = activeGroup?.editorIds[activeGroup.activeEditorIndex];
  const activeEditor = activeEditorId ? state.editors[activeEditorId] : undefined;
  const activeDoc = activeEditor ? state.documents[activeEditor.documentUri] : undefined;

  return <div>{activeDoc?.uri ?? 'No document open'}</div>;
};
```

### Sharing across your app's tree

Components in different parts of your app's layout (e.g. your editor area and your sidebar) can share the same `Documents` instance via the module-level `getDocs()` function:

```text
MyApp (creates instance)     MySidebar (uses same instance)
     ↓                            ↓
  createDocs(vfs)              getDocs()
     ↓                            ↓
  getDocs().useStore()         getDocs().openDocument(path)
```

### Content type

`Document.content` is `unknown`, the exact object you store is the exact object you get back. No serialization happens inside the Documents class. The VFS handles serialization at the disk boundary.

- Pipeline editor: stores a `PipelineConfig` object
- Text editor: stores a `string`
- Image editor: stores a base64 string or metadata object

---

## The Virtual File System (IVirtualFileSystem)

The single abstraction for all file I/O. Created by the app, passed to both `new Documents(vfs)` and `DocExplorer`.

```typescript
interface IVirtualFileSystem {
  list(dir: string): Promise<{ name: string; type: 'file' | 'dir' }[]>;
  read(path: string): Promise<unknown>;
  write(path: string, content: unknown): Promise<void>;
  rename(oldPath: string, newPath: string): Promise<void>;
  delete(path: string): Promise<void>;
  mkdir(path: string): Promise<void>;
}
```

### Example: RocketRide client VFS

```typescript
const vfs: IVirtualFileSystem = {
  list: async (dir) => {
    const result = await client.fsListDir(`projects/${dir}`);
    return result.entries.map(e => ({ name: e.name, type: e.type }));
  },
  read:   (path) => client.fsReadJson(`projects/${path}`),
  write:  (path, content) => client.fsWriteJson(`projects/${path}`, content),
  rename: (old, new_) => client.fsRename(`projects/${old}`, `projects/${new_}`),
  delete: (path) => client.fsDelete(`projects/${path}`),
  mkdir:  (path) => client.fsMkdir(`projects/${path}`),
};
```

### Example: REST API VFS

```typescript
const vfs: IVirtualFileSystem = {
  list: async (dir) => {
    const res = await fetch(`/api/files?dir=${dir}`);
    return res.json();
  },
  read: async (path) => {
    const res = await fetch(`/api/files/${path}`);
    return res.json();
  },
  write: async (path, content) => {
    await fetch(`/api/files/${path}`, { method: 'PUT', body: JSON.stringify(content) });
  },
  rename: async (old, new_) => {
    await fetch(`/api/files/${old}/rename`, { method: 'POST', body: JSON.stringify({ to: new_ }) });
  },
  delete: async (path) => {
    await fetch(`/api/files/${path}`, { method: 'DELETE' });
  },
  mkdir: async (path) => {
    await fetch(`/api/files/${path}`, { method: 'POST', body: JSON.stringify({ type: 'dir' }) });
  },
};
```

---

## DocExplorer: File Tree Component

A generic file tree panel (like VS Code's EXPLORER). Renders a hierarchical file tree with:

- Directory expand/collapse
- Tree/flat view toggle
- File selection and active highlight
- Inline rename and create
- Context menus (rename/delete)
- Status dots (running/error/warning)
- Optional child items under files (with action buttons)
- Keyboard navigation

```typescript
import { DocExplorer } from 'shell';
import type { DocExplorerConfig, DocEntry } from 'shell';
import type { IVirtualFileSystem } from 'rocketride/app-sdk';

const config: DocExplorerConfig = {
  title: 'My Files',
  extensions: ['.txt', '.md'],
  displayName: (name) => name.replace(/\.(txt|md)$/, ''),
  emptyMessage: 'No files yet',
  createPlaceholder: 'file name',
};

<DocExplorer
  vfs={myVfs}
  config={config}
  entries={entries}
  statuses={statusMap}
  isConnected={isConnected}
  activeFilePath={activeUri}
  onOpenFile={(path) => getDocs().openDocument(path)}
  onFileManage={(action, path, newName) => { /* rename/delete/create */ }}
  onRefresh={() => refreshFileList()}
/>
```

### DocExplorerConfig

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `title` | `string` | (required) | Section header (e.g. "Pipelines", "Photos") |
| `extensions` | `string[] \| null` | `null` | File extensions to filter. Null = show all. |
| `displayName` | `(filename: string) => string` | Strips known extensions | Custom display name formatter |
| `createPlaceholder` | `string` | `'file name'` | Placeholder for inline create input |
| `emptyMessage` | `string` | `'No files'` | Empty state message |

---

## DocTabs: Tab Bar Component

A tab bar UI for a single editor group. Takes a `Documents` instance as a prop.

```typescript
import { DocTabs } from 'shell';
import { getDocs } from './docs';

<DocTabs
  docs={getDocs()}
  groupId={groupId}
  onDirtyClose={(editorId, uri) => {
    // Show "save changes?" dialog
  }}
/>
```

Features:
- Tab per editor in the group
- Dirty indicator (dot)
- Close button (on hover)
- Active tab highlight
- Calls `docs.setActiveEditor()` / `docs.closeEditor()` on the provided instance

---

## Cross-App Component Loading

Apps can expose components for other apps to use, and load components from other apps at runtime via Module Federation.

### Exposing components

Add them to your `components` object in the AppDescriptor. They're bundled automatically because they're imported, no extra `exposes` in rsbuild needed.

```typescript
const MY_APP: AppDescriptor = {
  id: 'rocketride.myApp',
  name: 'My App',
  branding: { appName: 'My App' },
  app: MyApp,
  components: {
    // Shell never mounts these, but other apps can access them
    SpecialChart: MySpecialChartComponent,
    DataGrid: MyDataGridComponent,
  },
};
```

Your `rsbuild.config.ts` still only needs one expose:

```typescript
exposes: {
  './AppDescriptor': './src/AppDescriptor.ts',
}
```

When the shell loads your AppDescriptor, all components referenced in `components` are included in the bundle automatically.

### Loading components from another app

Use `useAppComponent()`, it lazy-loads the target app's descriptor if needed and returns the component once available:

```typescript
import { useAppComponent } from 'rocketride/app-sdk';

const MyComponent: React.FC = () => {
  const Chart = useAppComponent('rocketride.otherApp', 'SpecialChart');

  if (!Chart) return <div>Loading...</div>;
  return <Chart data={myData} />;
};
```

The hook:
- Returns `null` while the target app's descriptor is loading
- Triggers a lazy load automatically if the app hasn't been visited yet
- Returns the component once available, no manual loading needed

---

## Theming

The shell manages themes via CSS custom properties. Your app should use `--rr-*` variables for all colors, fonts, and borders.

### Available CSS variables

| Variable | Purpose |
|----------|---------|
| `--rr-bg-default` | Main background |
| `--rr-bg-paper` | Card/panel background |
| `--rr-bg-surface-alt` | Hover/alternate background |
| `--rr-bg-input` | Input field background |
| `--rr-text-primary` | Primary text |
| `--rr-text-secondary` | Secondary/muted text |
| `--rr-text-disabled` | Disabled text |
| `--rr-brand` | Brand/accent color |
| `--rr-border` | Border color |
| `--rr-font-family` | Primary font |
| `--rr-font-family-mono` | Monospace font |
| `--rr-color-success` | Success green |
| `--rr-color-warning` | Warning orange |
| `--rr-color-error` | Error red |

### Responding to theme changes

```typescript
useEffect(() => {
  return connectionManager.on('shell:themeChange', ({ tokens }) => {
    // tokens is a Record<string, string> of all --rr-* values
    console.log('New theme:', tokens['--rr-brand']);
  });
}, []);
```

---

## Build Configuration

See the [Getting Started](#getting-started) section for the complete `rsbuild.config.ts` template.

Key points:
- The MF container `name` is derived automatically from `appManifest.id` in `package.json`
- Always expose `./AppDescriptor` as the single MF entry point
- `rocketride/app-sdk` must be a shared singleton so your app and the shell agree on one instance
- React and react-dom must be shared singletons to avoid duplicate instances

---

For the App Builder loop, see [App Builder](/guides/apps/app-builder).


---

# App Builder

Route: /guides/apps/app-builder

---
title: App Builder
---

# App Builder

The App Builder is the workspace in the RocketRide VS Code extension that
takes an app from an empty folder to a version your team can open. It owns
the work that sits between an app that runs on your machine and one your
team can use: scaffolding the project, previewing it against a real engine
while you edit, packaging it, and deploying versions you can publish, all
without leaving the editor. If you are not yet sure what an app is or
whether you need one, read [Apps](/concepts/apps) first. Switch the
RocketRide sidebar to apps mode and pick an app, or open its `<name>.rrapp`
file, and the builder opens on it.

Where a step has a command-line equivalent, it is shown after the step, so
the same loop runs from a terminal or CI.

## Before you start

- The extension, installed and signed in
  ([installation](/clients/vscode/installation)).
- Node and **pnpm**. Use pnpm, not npm: running `npm install` inside an app
  folder can corrupt the workspace layout. Dependencies install once at the
  workspace root.
- A developer id for your organization. Every app id is
  `<developerId>.<name>`. Your organization claims its developer id once,
  on the Deploy tab (lowercase letters and underscores, starting with a
  letter), and can then deploy
  only apps inside that namespace. Until the prefix of your app's id
  matches, the Deploy tab is read-only with a banner; the fix is to rename
  the id in `package.json`. Design and Package always work.

## The loop

The builder's tabs, in the order you meet them the first time. After
that, you come back to Design and Deploy most often.

### Create (Dashboard tab)

Start from the Dashboard tab, or run **RocketRide: New App** from the
command palette. The wizard asks for a name and a template (Blank or
Dashboard) and scaffolds the app under `apps/<slug>`. Always create apps
this way; a hand-made folder fails later with symptoms far from the cause.
The scaffold starts the id at `local.<slug>` until your organization has a
developer id; renaming the id later makes it a different app.

The `<name>.rrapp` file it creates is empty on purpose. Opening it opens
the App Builder; the app's identity lives in `package.json`.

What you will edit:

| File | What it is |
| --- | --- |
| `package.json` | the app manifest (`appManifest`): id, name, icon, README, included folders |
| `README.md` | your listing text |
| `icon.svg` | your listing icon |
| `src/App.tsx` | the screens |
| `src/AppDescriptor.ts` | how the app presents itself to the shell |

```bash
rocketride app create reports --template Dashboard
```

### Design

The Preview pane is the real shell, running against your connected engine,
with your app loaded inside it. Every save rebuilds and reloads. The
bundle you are previewing is a personal overlay that only you can see, and
it disappears when the panel closes or the connection drops, so
development work never reaches other users. **Components** is a live
gallery of everything importable from `shell`, and **Console** shows your
app's own console output as it runs.

:::note If the preview keeps showing a sign-in screen
With **Inherit Auth** off, an app that requires sign-in boots signed out on
purpose; turn it on to reuse your session. If it still bounces, the host
session is stale: sign out of VS Code and back in, then reload the preview.
:::

### Package

The Package tab edits the `appManifest` block in `package.json`. The file
is the truth, so editing it by hand is fine. Verification needs no server:

```bash
rocketride app verify ./apps/reports
```

### Your listing

Your listing is `README.md` and `icon.svg`, declared in `appManifest`
(`readme` and `icon`) and editable on the Package tab or by hand. Both
files must live inside the app folder. Versions are immutable, so replace
the scaffold README before your first deploy.

### Deploy

Two verbs, and they are not the same:

- **Deploy** uploads your app's source; the server builds it into the next
  immutable version. Deploying activates nothing.
- **Publish** points an audience at a version: `@me` for your own desktop,
  `@team/<name>` for a team. First release, update, and rollback are all
  the same move: repoint, never rebuild. There is no org-wide rung; an
  org-wide audience is a team your admin maintains.

A deploy packs the app folder plus any folders listed under
`appManifest.include`, and nothing else. Every `include` entry must exist.

```bash
rocketride app deploy ./apps/reports --comment "first version"
```

`rocketride app deploy` needs a deployment target (`ROCKETRIDE_DEPLOY_URI`
and `ROCKETRIDE_DEPLOY_APIKEY`) and refuses to run without one; `app
create` uses the development connection (`ROCKETRIDE_URI`) to vendor
platform packages, and `app verify` needs no connection. Publishing
happens on the Deploy tab.

## Adding a pipeline to your app

There are two ways, and they are different features. See
[Apps and pipelines](/concepts/apps#apps-and-pipelines) for the idea; this
is the how-to.

### Inside the app: runs per user, on demand

Put the `.pipe` file in the app folder and import it. The scaffold's build
treats `.pipe` as JSON. Start it from the shell connection:

```typescript
import summarizer from './summarizer.pipe';
import { useShellConnection } from 'shell';

const { client } = useShellConnection();
const { token } = await client.use({ pipeline: summarizer, useExisting: true });
```

Every signed-in user gets their own instance. Start it once per session and
keep the token; `useExisting: true` re-attaches after a reload instead of
failing because the pipeline is already running. The pipeline ships with the
app on deploy. Use this for work that happens when the user asks for it.

### Outside the app: shared, on a schedule

Build the pipeline as its own project and deploy it separately:

```bash
rocketride deploy add pipelines/nightly-report.pipe --comment "v1"
rocketride deploy publish <projectId> 1 --team <teamId>
```

The app does not start this pipeline. It imports the `.pipe` for its
identity only and asks the shell client for the running task's token
(`getTaskToken`) to attach to the instance the team is running:

```typescript
import nightly from '../../../pipelines/nightly-report.pipe'; // identity only
const projectId = String(nightly.project_id);
```

Outside its schedule window there is no running instance and no token.
That is the normal state, not an error; show the feature as offline and
check again later. Deploying the app does not carry this pipeline, so
deploy it on its own whenever it changes.

| | Inside the app | Outside the app |
| --- | --- | --- |
| Where the `.pipe` lives | in the app folder | its own project |
| Who runs it | one instance per signed-in user | one instance for the team |
| When it runs | when the app asks | on its schedule |
| How it deploys | with the app | separately, `rocketride deploy` |

## Next steps

- [Shell API](/guides/apps): hooks, the descriptor, and the manifest, when
  you code by hand.
- [CLI](/connect/cli): the full command reference.
- Building with a coding agent? The bundle the extension installs already
  contains the complete app reference; point your agent at
  `ROCKETRIDE_APPS.md`.


---

# Best Practices

Route: /guides/best-practices

---
title: Best Practices
sidebar_position: 10
---

# Best Practices

Practical guidance for building reliable, maintainable RocketRide pipelines.

## Credential management

**Store API keys in environment variables, never in `.pipe` files.**

A `.pipe` file is plain JSON. If you hard-code an API key, it will end up in
version control. Use `${ENV_VAR}` substitution in the config instead:

```json
{
  "provider": "llm_openai",
  "config": {
    "profile": "openai-4o",
    "openai-4o": { "apikey": "${ROCKETRIDE_OPENAI_KEY}" }
  }
}
```

`${...}` references are expanded server-side when the run is submitted: the SDK
sends `ROCKETRIDE_`-prefixed variables from the client environment, the server
merges them over its stored secrets, and only `ROCKETRIDE_`-prefixed references
are substituted. References to any other variable (such as `${OPENAI_API_KEY}`)
are replaced with `<REDACTED>`, not passed through.

Credentials are **per-node**: each node holds only its own key, and nodes do not
share credential state. A compromised node config does not expose keys belonging
to other nodes in the pipeline.

For production deployments, inject keys via a secrets manager (AWS Secrets
Manager, HashiCorp Vault, Doppler) rather than a `.env` file.

## Choosing a preprocessor

The preprocessor splits documents into chunks before embedding. The right choice
depends on your content and latency budget:

| Preprocessor | Best for | Notes |
| --- | --- | --- |
| [`preprocessor_langchain`](/nodes/preprocessor_langchain) | Most text content | Fast, deterministic chunking by character or token count. Good default. |
| [`preprocessor_llm`](/nodes/preprocessor_llm) | Semantic coherence matters | Uses an LLM to split at meaningful boundaries. Slower and costs tokens; best for long-form prose where chunk boundaries affect retrieval quality. |
| [`preprocessor_code`](/nodes/preprocessor_code) | Source code | Splits at function and class boundaries. Do not use for prose. |

Start with `preprocessor_langchain` and a chunk size of 512–1024 tokens.
Only switch to `preprocessor_llm` if retrieval quality is measurably poor.

Chunk size affects both retrieval precision and embedding cost. Smaller chunks
retrieve more precisely but increase the number of embeddings to store and query.

## Selecting a memory node

Memory nodes give an agent conversational context across turns. Choose based on
whether that context needs to survive pipeline restarts — the full strategy
table lives in [Advanced Agents](/guides/advanced-agents#memory-strategies).
If you don't need cross-session memory, `memory_internal` is the right
default — it has no external dependencies and no latency overhead.

## Agents vs. direct LLM calls

Use a **direct LLM node** (`llm_openai`, `llm_anthropic`, etc.) when:

- The task is a single-step transformation: summarise this text, classify this
  input, translate this sentence.
- The output schema is predictable.
- Latency is a concern — agents add at least one extra LLM round-trip.

Use an **agent node** (`agent_rocketride`, `agent_langchain`, etc.) when:

- The task requires deciding *which* tool to call based on the input.
- The task involves multiple steps that depend on intermediate results.
- You want the model to search, retrieve, compute, or call external APIs as part
  of answering a question.

A common mistake is wrapping a simple Q&A task in an agent "for flexibility."
Start with a direct LLM node; promote to an agent only when the task genuinely
requires tool use.

## Lane typing

Data in RocketRide flows through typed lanes. Wiring the wrong lane type is the
most common configuration error — the canonical lane table (what each lane
carries and which nodes accept it) lives on the
[Execution Model](/concepts/execution-model#lane-types) page.

**Common mistake:** wiring `text` to a node that expects `questions`. Text
arrives but the node waits for a question signal and never processes it. Check
the node's reference page (the **Lanes** table) when a node appears to receive
data but produces no output.

The VS Code extension highlights lane type mismatches in the canvas before you
run the pipeline.

## Related

- [Concepts: Execution Model](/concepts/execution-model): how lanes carry data.
- [Concepts: Agents & Tools](/concepts/agents-tools-skills): when agents are the right abstraction.
- [Concepts: Error Handling](/guides/error-handling): what happens when things go wrong.


---

# Error Handling

Route: /guides/error-handling

---
title: Error Handling
---

# Error Handling

Patterns for keeping pipelines useful when things fail. For the taxonomy of
*what* can fail — startup vs. runtime errors and how the engine reports them —
see [Troubleshooting](/support/troubleshooting); the event format lives in
[WebSocket Events](/connect/websocket/observability).

A runtime error stops the current pipeline run: the engine emits an error event
with the node ID and message, then halts. Nodes that already streamed output
are not rolled back, and concurrent runs on the same pipeline are unaffected.
The patterns below keep a single failure from becoming an outage.

## Agent retry loops

`agent_rocketride` has a configurable `max_waves` parameter that caps the
number of reasoning cycles (it is not a per-tool retry count). When a tool call
fails, the agent can retry with a modified call in a later wave. This handles
transient failures in external APIs without propagating an error to the
pipeline level.

## Fallback LLM profiles

If your primary model is unavailable, swap the `profile` to a fallback. Some
teams maintain two `.pipe` files, one using a premium model profile and one using
a cheaper or locally-hosted fallback, and switch between them by passing the
chosen file to the `rocketride` CLI's `--pipeline` flag (`rocketride start
--pipeline ./fallback.pipe`).

## Guardrails as a safety net

A [`guardrails`](/nodes/guardrails) node placed on the `answers` lane validates
LLM output before it reaches the response target. If the output fails
validation, the guardrail can block it or route it to an error handler rather
than returning it to the caller.

## Observability-driven debugging

Use the WebSocket event stream to watch a pipeline run in real time. Error
events pinpoint the failing node, which is usually enough to diagnose
configuration issues.

## Related

- [Troubleshooting](/support/troubleshooting): symptom → cause → fix, and the error taxonomy.
- [WebSocket Events](/connect/websocket/observability): full error event schema.
- [Best Practices](/guides/best-practices): credential and lane-type pitfalls.
- [Nodes: Guardrails](/nodes/guardrails): output validation.


---

# Observability

Route: /guides/observability

---
title: Observability
---

# Observability

Every RocketRide run is recorded. This guide is the map: the mental model
behind run logs, the two ways to watch a pipeline (live and replayed), and
which surface to reach for — each section links to the page that owns the
detail.

## The mental model: a DVR, not a log file

The engine writes every run into a durable, append-only stream — one
**continuum** per pipeline identity, where each run is a **chapter** inside
it. There are no per-run log files to collect. Watching a run live and
replaying it tomorrow are the same data at different positions: live is just
a position pinned to "now".

Two identities matter, and they do different jobs:

| Identity | What it is | What it's for |
| --- | --- | --- |
| **Task token** (`tk_...`) | The live control handle a run returns when started | Send data, poll status, terminate — dies with the run |
| **`projectId` + `source` (+ `teamId`)** | The pipeline's durable log identity | Monitoring subscriptions and everything recorded — outlives the run, works after it finished |

Omitting `teamId` addresses your own **dev stream**; passing it addresses
that team's **deploy continuum**. Team membership is the read right. Inside
the stream, `beginSeq` is a run's (and a trace's) permanent id.

## The two planes

**Live plane** — event subscriptions (`rrext_monitor` on the wire,
`add_monitor`/`addMonitor` in the SDKs). Push-based, per-connection, and
non-durable: if you weren't subscribed, you missed it. Covers lifecycle,
status updates (with metrics and billing), component-level flow events, and
console output. The full event schema lives on
[WebSocket Events](/connect/websocket/observability).

**Recorded plane** — the run-log continuum (`client.log` in the SDKs, the
`log_*` MCP tools). Pull-based and durable: chapters, ranged reads, per-object
traces, and a DVR session that can seek, replay at any speed, and pin to
live. The full API lives on the SDK [run-log pages](/clients/python/logs).

They are two views of the same events: a flow event you watch live is the
same record you replay from the log later.

## Trace levels

`pipelineTraceLevel` — set when a run starts — decides how much of the run
gets recorded (and emitted live as flow events):

| Level | Records | Cost |
| --- | --- | --- |
| `none` | Lifecycle, status, console only — **no traces** | None |
| `metadata` | Component enter/leave, object identities | Minimal |
| `summary` | Above, plus lane writes and final results | Modest — the debugging sweet spot |
| `full` | Everything, entire payloads inlined (including images) | Can slow runs and swell the log |

**The default depends on where you start the run** — each surface picks what
its users typically want, so don't assume:

| Surface | Default | Why |
| --- | --- | --- |
| Wire / SDK `use()` | `none` | Production callers opt in to tracing |
| MCP server tools | `summary` | Assistants need replayable content to debug |
| VS Code extension | `full` | Interactive debugging wants everything |

A run recorded with `none` still has chapters and console output — but its
traces are empty, which is the most common "why can't I replay this?" answer.

## Retention

Runs are kept **7 days (dev streams) / 30 days (deploy continuums)** on a
bounded (~1 GB) ring, evicted earlier under storage pressure. Reads below the
horizon fail explicitly (`TraceExpired` on MCP, truncation markers in the
SDKs) rather than returning partial silence.

## Which surface, when

| You are… | Reach for | Where |
| --- | --- | --- |
| Writing Python/TypeScript | `get_task_status` / `add_monitor` live; `client.log` chapters, reads, and DVR sessions | [Python](/clients/python/logs) · [TypeScript](/clients/typescript/logs) |
| In an AI assistant (MCP) | `monitor` and `list_running_pipelines` live; `log_chapters`/`log_read`/`log_traces`/`log_trace` for replay — traces render in the trace-viewer widget | [MCP tools](/connect/mcp/http/tools#replay-past-runs) |
| In VS Code | The Status page, Flow and Trace tabs, and the component debugger | [VS Code usage](/clients/vscode/usage) |
| Building your own ingester / dashboards | Raw `rrext_monitor` subscriptions over the WebSocket protocol | [WebSocket Events](/connect/websocket/observability) |

What RocketRide observability is **not**: there is no OpenTelemetry,
Prometheus, or webhook emitter — the wire protocol is the integration point
if you need one.

## Two workflows

**Watch a live run.** Start the pipeline (keep `projectId`/`source` from the
result), subscribe with `add_monitor({project_id, source})` or open the VS
Code Status page, and watch status/flow events arrive. Poll-style
alternatives: `get_task_status(token)` in the SDKs, `monitor` over MCP.

**Autopsy yesterday's failed run.** No token needed — the run is gone but the
log isn't. List the chapters for `projectId + source`, pick the failed run's
`beginSeq`, list its traces, and pull the failing object's full journey —
every component it entered and left, with lane data at each hop. In the SDKs
that's `chapters()`, then a DVR session's `get_traces()` → `get_trace()`; over
MCP it's
`log_chapters` → `log_traces` → `log_trace`.

## One naming trap

The SDK constructor option `on_trace`/`onTrace` has nothing to do with
pipeline traces — it's a client-side hook that logs the SDK's own
request/response frames for debugging your integration (and in Python it is
**not** credential-redacted). Pipeline tracing is controlled by
`pipelineTraceLevel` alone. See
[Configuration](/clients/python/configuration).


---

# Performance

Route: /guides/performance

---
title: Performance
---

# Performance

Practical levers for making pipelines faster and cheaper. For *why* these
levers exist — the engine's threading, streaming, and batching behaviour — see
the [Execution Model](/concepts/execution-model).

## Preprocessor chunk size

Chunk size directly affects embedding throughput and retrieval quality:

| Smaller chunks | Larger chunks |
| --- | --- |
| More precise retrieval | Fewer embedding API calls |
| More vectors to store and query | Lower storage cost |
| More embedding requests (cost) | Less precise retrieval for long queries |

A chunk size of 512–1024 tokens is a reasonable starting point for most text
content. Reduce chunk size if retrieval recall is poor on short queries; increase
if you're hitting embedding API rate limits.

## LLM context and cost

LLM nodes send the full accumulated context (system prompt, retrieved chunks,
conversation history) on every call. Costs scale with context size:

- **Retrieved chunks**: more chunks retrieved from the vector store = more
  tokens per LLM call. The retrieval limit is set by the question's docFilter
  `limit`, not a store node config field.
- **Memory nodes**: conversation history grows each turn. Use
  `memory_persistent` with `max_history` to cap history length
  (`memory_internal` has no window-limit config).
- **Model selection**: larger models (GPT-5, Claude Opus) cost more per token.
  Use them for reasoning-heavy tasks; use smaller models for classification and
  extraction where a cheaper model performs just as well.

## Vector store batch sizing

Vector stores flush chunks in batches (see
[Execution Model](/concepts/execution-model) for the mechanics). Batch size
affects throughput: larger batches reduce round-trip overhead but increase
memory usage per run. The defaults suit most workloads.

## Profiling a pipeline

The engine emits per-node timing in its WebSocket event stream. The CLI does
not stream it; subscribe from an SDK client or the platform's monitor apps.
The [WebSocket Events](/connect/websocket/observability) page documents the
event schema. To find bottlenecks, look for the node with the longest gap
between its `start` and `complete` events — that is usually the LLM call or the
embedding step.

## Related

- [Execution Model](/concepts/execution-model): threading, streaming, and batching.
- [Production](/operate/self-hosting/production): deployment topology for throughput.
- [WebSocket Events](/connect/websocket/observability): timing events.


---

# Document Extraction

Route: /examples/document-extraction

---
title: Document Extraction
sidebar_position: 3
---

# Document Extraction

Read files from the local file system, parse them into structured text, extract
specific fields, and return structured JSON. This pattern works well for invoice
processing, contract review, report summarisation, and any batch document
workflow.

## The pipeline

Save this as `extract.pipe`:

```json
{
  "components": [
    {
      "id": "source_1",
      "provider": "filesys",
      "config": {
        "include": [
          { "path": "/data/invoices" }
        ]
      }
    },
    {
      "id": "parser_1",
      "provider": "parse",
      "input": [
        { "lane": "tags", "from": "source_1" }
      ]
    },
    {
      "id": "extract_1",
      "provider": "extract_data",
      "config": {
        "profile": "default",
        "fields": [
          { "column": "invoice_number", "type": "text", "defval": "" },
          { "column": "total_amount",   "type": "text", "defval": "" },
          { "column": "due_date",       "type": "date", "defval": "" },
          { "column": "vendor_name",    "type": "text", "defval": "" }
        ]
      },
      "input": [
        { "lane": "text", "from": "parser_1" }
      ]
    },
    {
      "id": "llm_1",
      "provider": "llm_openai",
      "config": {
        "profile": "openai-4o-mini",
        "apikey": "${ROCKETRIDE_OPENAI_API_KEY}"
      },
      "control": [
        { "classType": "llm", "from": "extract_1" }
      ]
    },
    {
      "id": "target_1",
      "provider": "response",
      "input": [
        { "lane": "answers", "from": "extract_1" }
      ]
    }
  ]
}
```

## What each node does

| Node | Provider | Role |
| --- | --- | --- |
| `source_1` | `filesys` | Scans `/data/invoices` and emits each file as a tagged object on the `tags` lane. |
| `parser_1` | `parse` | Converts each file (PDF, Word, image, etc.) into clean text on the `text` lane. |
| `extract_1` | `extract_data` | Uses an LLM to pull the four named fields out of each document and emits the result as structured JSON on the `answers` lane. |
| `llm_1` | `llm_openai` | Answers `extract_1`'s extraction prompts over the `llm` invoke channel. |
| `target_1` | `response` | Returns the extracted JSON to the caller. |

## Start the pipeline

Put some PDF invoices in `/data/invoices`, then:

```bash
export OPENAI_API_KEY=sk-...

rocketride start --pipeline ./extract.pipe
```

The engine scans the directory, processes each file through the pipeline, and
streams the extracted JSON:

```json
{
  "invoice_number": "INV-2024-0042",
  "total_amount": "1,250.00 USD",
  "due_date": "2024-02-15",
  "vendor_name": "Acme Supplies Ltd."
}
```

## Upload files on demand

Swap the `filesys` source for a `webhook` source to process files as they
arrive rather than scanning a directory:

```json
{ "id": "source_1", "provider": "webhook" }
```

Then upload files via the CLI:

```bash
rocketride upload --pipeline ./extract.pipe ./invoice-001.pdf ./invoice-002.pdf
```

Or via the Drag & Drop UI by using the `dropper` provider:

```json
{ "id": "source_1", "provider": "dropper" }
```

The engine prints a browser URL where you can drop files and see results in
JSON, text, and table tabs.

## Next steps

- Add a [`db_postgres`](/nodes/db_postgres) node after `extract_1` to write the
  extracted fields directly to a database table.
- Add an [`anonymize`](/nodes/anonymize) node before `extract_1` to strip PII
  before it reaches the LLM.
- See the [`db_postgres` node reference](/nodes/db_postgres) for writing
  extracted data to a database.


---

# RAG Pipeline

Route: /examples/rag-pipeline

---
title: RAG Pipeline
sidebar_position: 1
---

# RAG Pipeline

Retrieval-augmented generation (RAG) is the most common pattern in RocketRide:
embed documents into a vector store, then answer questions by retrieving the
relevant chunks and feeding them to an LLM. This example walks through a
complete pipeline that accepts questions over HTTP, retrieves context from
Qdrant, and returns answers.

## What you need

- An OpenAI API key
- A running [Qdrant](https://qdrant.tech) instance (local Docker or Qdrant Cloud)
- The RocketRide engine running ([self-hosted](/operate/self-hosting) or [Cloud](/operate/cloud))

## The pipeline

Save this as `rag.pipe`:

```json
{
  "project_id": "rag-example",
  "components": [
    {
      "id": "source_1",
      "provider": "webhook"
    },
    {
      "id": "parser_1",
      "provider": "parse",
      "input": [
        { "lane": "tags", "from": "source_1" }
      ]
    },
    {
      "id": "prep_1",
      "provider": "preprocessor_langchain",
      "config": {
        "profile": "default",
        "default": {
          "mode": "strlen",
          "splitter": "RecursiveCharacterTextSplitter",
          "strlen": 512
        }
      },
      "input": [
        { "lane": "text", "from": "parser_1" }
      ]
    },
    {
      "id": "embed_1",
      "provider": "embedding_openai",
      "config": {
        "profile": "text-embedding-3-small",
        "apikey": "${ROCKETRIDE_OPENAI_API_KEY}"
      },
      "input": [
        { "lane": "documents", "from": "prep_1" },
        { "lane": "questions", "from": "source_1" }
      ]
    },
    {
      "id": "store_1",
      "provider": "qdrant",
      "config": {
        "profile": "local",
        "local": {
          "host": "localhost",
          "port": 6333,
          "collection": "rag-docs"
        }
      },
      "input": [
        { "lane": "documents", "from": "embed_1" },
        { "lane": "questions", "from": "embed_1" }
      ]
    },
    {
      "id": "llm_1",
      "provider": "llm_openai",
      "config": {
        "profile": "openai-4o",
        "apikey": "${ROCKETRIDE_OPENAI_API_KEY}"
      },
      "input": [
        { "lane": "questions", "from": "store_1" }
      ]
    },
    {
      "id": "target_1",
      "provider": "response",
      "input": [
        { "lane": "answers", "from": "llm_1" }
      ]
    }
  ]
}
```

## What each node does

| Node | Provider | Role |
| --- | --- | --- |
| `source_1` | `webhook` | Exposes an HTTP endpoint. Incoming documents arrive on the `tags` lane; incoming questions arrive on the `questions` lane. |
| `parser_1` | `parse` | Converts each uploaded file (PDF, Word, etc.) into clean text on the `text` lane. |
| `prep_1` | `preprocessor_langchain` | Splits the text into chunks and emits them on the `documents` lane. |
| `embed_1` | `embedding_openai` | Turns document chunks into vectors using `text-embedding-3-small` and emits `documents` (vectors + metadata). Also embeds incoming questions before retrieval. |
| `store_1` | `qdrant` | Upserts vectors from `embed_1` into the `rag-docs` collection. When an embedded question arrives, it retrieves the top matching chunks and re-emits them as `questions` with context injected. |
| `llm_1` | `llm_openai` | Receives the question + retrieved context and generates an answer using GPT-4o. |
| `target_1` | `response` | Returns the answer to the caller. |

## Start the pipeline

```bash
rocketride start --pipeline ./rag.pipe
```

The engine prints the webhook URL and public auth key:

```text
Webhook ready - system is ready to accept requests
  URL:  http://localhost:5567/webhook/rag-example/source_1
  Auth: abc123...
```

## Ingest documents

POST a document to the webhook URL. The pipeline embeds and stores it:

```bash
curl -X POST http://localhost:5567/webhook/rag-example/source_1 \
  -H "Authorization: Bearer abc123..." \
  -F "file=@./my-document.pdf"
```

## Ask a question

Send a plain-text question to the same endpoint:

```bash
curl -X POST http://localhost:5567/webhook/rag-example/source_1 \
  -H "Authorization: Bearer abc123..." \
  -H "Content-Type: text/plain" \
  -d "What does the document say about refund policy?"
```

The pipeline retrieves the relevant chunks from Qdrant, asks GPT-4o, and streams
back the answer.

## Next steps

- Swap `embedding_openai` for [`embedding_transformer`](/nodes/embedding_transformer) to run embeddings locally without an API key.
- Swap `qdrant` for [`pinecone`](/nodes/store_pinecone) or [`milvus`](/nodes/store_milvus) without changing the rest of the pipeline.
- Add a [`guardrails`](/nodes/guardrails) node between the LLM and response to validate outputs.
- See the [`store_qdrant` node reference](/nodes/store_qdrant) for configuration details.


---

# Webhook Pipeline

Route: /examples/webhook-pipeline

---
title: Webhook Pipeline
sidebar_position: 2
---

# Webhook Pipeline

The simplest useful pipeline: an HTTP endpoint that accepts a question, sends
it to an LLM, and returns the answer. This is the "hello world" of RocketRide —
a good starting point before adding vector stores, preprocessing, or agents.

## The pipeline

Save this as `chat.pipe`:

```json
{
  "project_id": "webhook-example",
  "components": [
    {
      "id": "source_1",
      "provider": "webhook"
    },
    {
      "id": "llm_1",
      "provider": "llm_openai",
      "config": {
        "profile": "openai-4o-mini",
        "apikey": "${ROCKETRIDE_OPENAI_API_KEY}"
      },
      "input": [
        { "lane": "questions", "from": "source_1" }
      ]
    },
    {
      "id": "target_1",
      "provider": "response",
      "input": [
        { "lane": "answers", "from": "llm_1" }
      ]
    }
  ]
}
```

Three nodes, one connection each. The `webhook` source receives the request, the
`llm_openai` node answers it, and the `response` target returns the result.

## Start the pipeline

```bash
export OPENAI_API_KEY=sk-...

rocketride start --pipeline ./chat.pipe
```

Output:

```text
Webhook ready - system is ready to accept requests
  URL:  http://localhost:5567/webhook/webhook-example/source_1
  Auth: <public-auth-key>
  Token: <private-token>
```

Keep the terminal open — the pipeline runs until you stop it.

## Send a question

```bash
curl -X POST "http://localhost:5567/webhook/webhook-example/source_1" \
  -H "Authorization: Bearer <public-auth-key>" \
  -H "Content-Type: text/plain" \
  -d "What is the capital of France?"
```

Response:

```json
{ "answer": "The capital of France is Paris." }
```

## Use the Chat UI variant

Swap `webhook` for `chat` to get a browser-based chat window instead of a raw
HTTP endpoint, no `curl` required:

```json
{ "id": "source_1", "provider": "chat" }
```

Restart the pipeline. The engine prints a chat URL:

```text
Chat ready - system is ready to accept questions
  URL: http://localhost:5567/chat/webhook-example/source_1?auth=<public-auth-key>
```

Open that URL in a browser and start typing. The `?auth=` query parameter is a
convenience for supplying the credential to the browser; the Chat UI stores it
in session storage for subsequent page loads. Webhook requests use the same key
in an `Authorization: Bearer <public-auth-key>` header.

Each displayed URL includes the project and source identifiers, so it remains
specific to this pipeline. The legacy `/webhook`, `/task/data`, `/chat`, and
`/dropper` URLs continue to work for existing integrations.

## Add a system prompt

Give the LLM a persona by adding a `prompt` node:

```json
{
  "id": "prompt_1",
  "provider": "prompt",
  "config": {
    "instructions": ["You are a helpful assistant that answers questions concisely."]
  },
  "input": [
    { "lane": "questions", "from": "source_1" }
  ]
}
```

Then wire `llm_1` to receive from `prompt_1` instead of `source_1`.

## Next steps

- Add a [`qdrant`](/nodes/store_qdrant) store between source and LLM to build the full [RAG pipeline](/examples/rag-pipeline).
- Replace `llm_openai` with [`llm_anthropic`](/nodes/llm_anthropic) or [`llm_ollama`](/nodes/llm_ollama) — the rest of the pipeline is unchanged.
- See the [`llm_anthropic` node reference](/nodes/llm_anthropic) for model profile options.


---

# Overview

Route: /nodes

---
title: Overview
slug: /nodes
sidebar_position: 0
---

Nodes are the building blocks of a RocketRide pipeline. A [pipeline](/concepts/pipelines)
is a directed graph, and each node is one component that does one job: call a model,
embed text, query a vector store, parse a document, or run a tool. You wire nodes
together and the [engine](/concepts/runtime-engine) runs them.

This page explains how a node is structured on disk and how the runtime loads and
executes it, then catalogs every node that ships with the toolchain, grouped by type.

## Anatomy of a node

Each built-in node is a directory under `nodes/src/nodes/<name>/`. A node is its
service manifest plus an implementation and its documentation:

```
nodes/src/nodes/llm_openai/
  services.json     # the manifest: identity, class type, capabilities, config schema
  IGlobal.py        # node-level lifecycle: config validation, dependency loading
  IInstance.py      # per-instance behaviour: what the node does each invocation
  *_client.py       # provider/client implementation detail
  requirements.txt  # Python dependencies, installed on demand
  <name>.svg        # canvas icon
  README.md         # co-located documentation (rendered as this node's page)
```

The **`services.json`** manifest is the contract the engine reads. Its key fields:

| Field | Purpose |
| --- | --- |
| `title` | Display name on the canvas and in this catalog. |
| `protocol` | The node's URL scheme, e.g. `llm_openai://`. |
| `classType` | The kind of work the node does (`llm`, `store`, `tool`, …). Governs how it wires into the graph. |
| `capabilities` | Flags that change engine behaviour, e.g. `invoke`. |
| `register` | How the engine registers the node: `filter` (transforms data in the graph) or `endpoint` (an edge connector). |
| `node` / `path` | The runtime (`python`) and module (`nodes.llm_openai`) the engine instantiates. |
| `prefix` | Prefix swapped when converting between URLs and module paths. |
| `description` | Prose shown in the editor. |
| `config` | The configuration schema: the fields a pipeline author fills in. |

A node's public contract is its `classType`, config schema, and the input/output
lanes it supports. The [pipeline JSON reference](/reference/pipeline-reference) documents how a
node is referenced from a `.pipe` file (`id`, `provider`, `config`, `input`).

## How the runtime runs a node

1. **Discovery & registration.** On startup the engine scans every `services*.json`
   and registers a factory keyed by `protocol`/`prefix`. The `register` value decides
   whether the node is a `filter` in the graph or an `endpoint` connector at its edge.
2. **Instantiation.** When a pipeline references a provider, the engine instantiates
   the implementation named by `node` and `path`. `IGlobal` runs once per node
   definition (it validates `config` and loads `requirements.txt` on demand);
   `IInstance` carries the per-invocation behaviour.
3. **Wiring.** The `classType` determines how the node connects. Data nodes exchange
   data through **lanes**; `agent`, `tool`, `llm`, and `memory` nodes participate in
   **control** connections (see [Agents & tools](/concepts/agents-tools-skills)).
4. **Execution.** The engine drives the graph from sources to targets, passing each
   node's output along its lanes. `capabilities` flags toggle engine features such as
   `invoke`. See the [execution model](/concepts/execution-model) for how data flows.

Because behaviour lives in `provider` + `config`, swapping which model or store a
pipeline uses is a config edit, not a code change.

## Node types

166 nodes across 21 types. Every node declares a
class type in its manifest; the catalog below is grouped by it.

### Sources

Bring data into a pipeline: webhooks, chat, file and database readers, and cloud connectors.

| Node | Description |
| --- | --- |
| [Chat](/nodes/webhook/chat) | A user interface component that provides a web-based chat experience. |
| [Drag & Drop](/nodes/webhook/dropper) | A user interface component that provides a web-based dropper experience. |
| [File Store Source](/nodes/tool_filesystem) | File Store source. |
| [Telegram Bot](/nodes/telegram) | A Telegram Bot source node that receives messages from users via the Telegram Bot API. |
| [Tools](/nodes/webhook/tools) | A source component that transfers no data: it exists to host tool nodes. |
| [Webhook](/nodes/webhook) | A user interface component that provides a web-based chat experience. |
| [Webhook](/nodes/webhook/webhook) | A source component that listens for incoming HTTP requests and accepts uploaded documents or data from external systems or processes. |

### LLMs

Call large language models for generation, chat, summarization, and reasoning across many providers.

| Node | Description |
| --- | --- |
| [Amazon Bedrock](/nodes/llm_bedrock) | A component that connects to Amazon Bedrock, providing access to a range of foundation models from leading AI providers through a unified AWS interface. |
| [Anthropic](/nodes/llm_anthropic) | A component that integrates with Anthropic's Claude models for natural language understanding and generation. |
| [Baidu Qianfan](/nodes/llm_baidu_qianfan) | A component that connects to Baidu Qianfan ERNIE large language models through Qianfan's OpenAI-compatible chat-completions API. |
| [Deepseek](/nodes/llm_deepseek) | A component that connects to DeepSeek’s large language models for advanced natural language processing. |
| [Gemini](/nodes/llm_gemini) | A component that connects to Gemini models for advanced natural language processing. |
| [GLM (Z.ai)](/nodes/llm_glm) | A component that connects to Zhipu AI's GLM large language models for advanced natural language processing. |
| [GMI Cloud](/nodes/llm_gmi_cloud) | A component that connects to GMI Cloud's large language models for advanced natural language processing. |
| [Kimi (Moonshot)](/nodes/llm_kimi) | A component that connects to Moonshot AI's Kimi large language models for advanced natural language processing. |
| [MiniMax](/nodes/llm_minimax) | A component that connects to MiniMax's large language models for advanced natural language processing. |
| [Mistral AI](/nodes/llm_mistral) | A component that connects to Mistral AI's advanced language models for natural language processing. |
| [Ollama](/nodes/llm_ollama) | A component that integrates with locally-hosted language models through Ollama. |
| [OpenAI](/nodes/llm_openai) | A component that connects to OpenAI's latest GPT models for advanced natural language processing. |
| [OpenAI-Compatible API](/nodes/llm_openai_api) | A component that connects to any OpenAI-compatible API endpoint for language model inference. |
| [Perplexity](/nodes/llm_perplexity) | A component that connects to Perplexity AI's Sonar models for advanced natural language processing with real-time web search capabilities. |
| [Qwen](/nodes/llm_qwen) | A component that connects to Alibaba Cloud's Qwen large language models via the DashScope API. |
| [xAI](/nodes/llm_xai) | A component that integrates with xAI's Grok language models for intelligent text generation and analysis. |

### Vision & Image

Analyze and transform images: vision models, OCR, thumbnails, cleanup, and accessibility descriptions.

| Node | Description |
| --- | --- |
| [Accessibility Describe](/nodes/accessibility_describe) | An accessibility-focused image analysis node that generates scene descriptions optimized for blind and visually impaired users. |
| [Background Removal](/nodes/background_removal) | Foreground / background separation using BiRefNet (MIT). |
| [Caption](/nodes/caption) | Generates a natural-language caption for an image using Florence-2 Base (MIT). |
| [Cleanup](/nodes/image_cleanup) | A component that processes an image, cleans it up for OCR tasks by converting to gray scale, removing noise, deskewing, and enhancing contrast. |
| [Depth Estimation](/nodes/depth_estimate) | Monocular depth estimation using Depth Anything V2 Small (Apache-2.0). |
| [Face Detection](/nodes/face_detection) | Per-frame face detection using MediaPipe BlazeFace (Apache-2.0). |
| [Gemini Vision](/nodes/llm_vision_gemini) | A component that connects to Google Gemini's vision-capable models for image analysis, OCR, visual understanding, and scene description. |
| [Image Orientation Fixer](/nodes/image_orient) | Turns scanned photographs the right way up. |
| [Mistral Vision](/nodes/llm_vision_mistral) | A component that connects to Mistral AI's vision-capable models for image analysis, OCR, and visual understanding tasks. |
| [Object Detection](/nodes/detect) | Per-frame object detection. |
| [OCR](/nodes/ocr) | A component that extracts machine-readable text from images and scanned documents using optical character recognition. |
| [Ollama Vision](/nodes/llm_vision_ollama) | A component that connects to locally-hosted open-source vision models through Ollama for image analysis, description, and visual understanding tasks. |
| [OpenAI Vision](/nodes/llm_vision_openai) | A component that connects to OpenAI's vision-capable models for image analysis, OCR, visual understanding, and scene description. |
| [Pose Estimation](/nodes/pose_estimation) | Top-down human pose estimation using RTMPose (Apache-2.0) via the rtmlib ONNX wrapper. |
| [Scan Cropper](/nodes/scan_cropper) | Splits a scan that holds several photos - a photo album page, or a handful of prints laid on the platen - into one image per photo. |
| [Segmentation](/nodes/detect_segment) | Pixel-level segmentation with HuggingFace-native engines: Mask2Former-instance (MIT, default) for closed-set instance masks; Mask2Former-semantic (MIT) for per-pixel class maps. |
| [Thumbnail](/nodes/thumbnail) | A processing component that creates thumbnails from input images. |

### Audio

Work with audio: transcription, text-to-speech, and playback.

| Node | Description |
| --- | --- |
| [Player](/nodes/audio_player) | The Audio Player component plays audio through the system’s default audio output device, including the audio track from video content. |
| [Text To Speech](/nodes/audio_tts) | Converts incoming text into speech using Kokoro-82M (local KPipeline or --modelserver KokoroLoader). |
| [Text To Speech (ElevenLabs)](/nodes/cloud_tts) | Converts incoming text into speech using the ElevenLabs text-to-speech API. |
| [Transcribe](/nodes/audio_transcribe) | The Audio transcribe component recieves audio or video and transcribes into text. |

### Video

Process video: frame extraction, embeddings, and video understanding.

| Node | Description |
| --- | --- |
| [Frame Grabber](/nodes/frame_grabber) | A component that extracts frames from video files and outputs them as image data. |
| [TwelveLabs](/nodes/twelvelabs) | Sends a video to TwelveLabs along with instructions and returns the generated text response. |
| [Video Composer](/nodes/video_composer) | Stitches a sequence of image frames into an MP4 video using FFmpeg. |

### Text

Operate on text: summarization, extraction, named-entity recognition, and anonymization.

| Node | Description |
| --- | --- |
| [Anomaly Detector](/nodes/anomaly_detector) | A pipeline monitoring component that detects anomalies in numeric output values using statistical methods. |
| [Anonymize](/nodes/anonymize) | A filter component that identifies and masks sensitive information in text data. |
| [Answers to Documents](/nodes/answer_documents) | An adapter component that turns model/agent answers into embeddable documents. |
| [Context Optimizer](/nodes/context_optimizer) | A transformation component that manages LLM context window budgets. |
| [Currency Convert (Explicit)](/nodes/currency_convert_explicit) | An opt-in currency converter for the audit-grade financial extraction suite. |
| [Data Extractor](/nodes/extract_data) | A component that processes unstructured or semi-structured text and extracts structured data in a tabular format. |
| [Dictionary](/nodes/dictionary) | A processing component that analyzes documents to extract a dictionary of key terms and phrases. |
| [Fact Extractor](/nodes/extract_facts) | The extraction brain. |
| [Named Entity Recognition](/nodes/ner) | A text processing component that identifies and extracts named entities from text using state-of-the-art transformer models. |
| [Normalize Facts](/nodes/normalize_facts) | A deterministic fact normalizer for the audit-grade financial extraction suite. |
| [Prompt](/nodes/prompt) | A transformation component that takes multiple inputs and merges them into a single question with a configurable prompt. |
| [Question](/nodes/question) | A transformation component that takes input text and encapsulates it as a Question object without modification. |
| [Schema Validate](/nodes/schema_validate) | A guard node for the audit-grade financial extraction suite. |
| [Summarization: LLM](/nodes/summarization) | A processing component that analyzes document content to extract concise summaries, key points, and named entities. |

### Embeddings

Turn text, images, or video into vectors for semantic search and retrieval.

| Node | Description |
| --- | --- |
| [Image](/nodes/embedding_image) | A processing component that generates vector embeddings from image content using advanced computer vision models. |
| [OpenAI (Embedding)](/nodes/embedding_openai) | A component that transforms text into numerical vector representations using advanced embedding models. |
| [Transformer](/nodes/embedding_transformer) | A component that transforms text into numerical vector representations using advanced embedding models. |
| [Video](/nodes/embedding_video) | A processing component that generates vector embeddings from video content by extracting frames at configurable intervals and encoding them using vision models such as CLIP. |

### Rerank

Reorder retrieved results by relevance to a query.

| Node | Description |
| --- | --- |
| [Cohere Rerank](/nodes/rerank_cohere) | A reranking component powered by Cohere's Rerank API that improves search quality by reordering retrieved documents based on their relevance to a given query. |
| [Hybrid Rerank](/nodes/search_hybrid) | A hybrid search component that re-ranks documents already retrieved by an upstream vector store, fusing their vector score with a BM25 keyword score for improved ordering. |

### Search

Query external search providers and the web.

| Node | Description |
| --- | --- |
| [Exa Search](/nodes/search_exa) | A direct Exa web search node. |

### Vector Stores

Store and query embeddings for retrieval: Qdrant, Pinecone, Milvus, Chroma, and more.

| Node | Description |
| --- | --- |
| [Astra DB](/nodes/store_astra) | A vector database component for Astra DB, enabling efficient storage and retrieval of vector embeddings. |
| [Chroma](/nodes/store_chroma) | A vector database component for Chroma, enabling efficient storage and retrieval of vector embeddings. |
| [Elasticsearch](/nodes/store_elasticsearch) | A vector database component for Elasticsearch, enabling efficient storage and retrieval of vector embeddings. |
| [Elasticsearch](/nodes/store_elasticsearch/elasticsearch) | A vector database component for Elasticsearch, enabling efficient storage and retrieval of vector embeddings. |
| [Milvus](/nodes/store_milvus) | A vector database component for Milvus, enabling efficient storage, indexing, and retrieval of vector embeddings. |
| [MongoDB Atlas](/nodes/store_atlas) | A vector database component for MongoDB Atlas, enabling efficient storage and retrieval of vector embeddings using MongoDB's native vector search capabilities. |
| [OpenSearch](/nodes/store_elasticsearch/opensearch) | An OpenSearch node that supports classic BM25 search and vector search for ingestion and retrieval workflows. |
| [Pinecone](/nodes/store_pinecone) | A component that connects to the Pinecone vector database for storing and retrieving high-dimensional embeddings. |
| [PostgreSQL (pgvector)](/nodes/store_postgres) | A component that enhances PostgreSQL with vector similarity search capabilities through the pgvector extension. |
| [Qdrant](/nodes/store_qdrant) | A vector database component for Qdrant, enabling efficient storage and retrieval of vector embeddings. |
| [RocketRide Vector](/nodes/rocketride_vector) | A RocketRide-managed vector store backed by PostgreSQL + pgvector. |
| [Weaviate](/nodes/store_weaviate) | A component that stores vector embeddings in a Weaviate instance for semantic search and retrieval. |

### Databases

Read from and write to relational and graph databases.

| Node | Description |
| --- | --- |
| [Aparavi AQL](/nodes/aparavi_aql) | Queries the Aparavi data governance platform using AQL (Aparavi Query Language). |
| [ClickHouse](/nodes/db_clickhouse) | A ClickHouse component that answers natural-language questions by translating them into SQL and executing them against the database, returning rows as a table, text, or structured answers. |
| [Firestore](/nodes/db_firestore) | A processing component that connects to Google Cloud Firestore (Native mode). |
| [Hotdata](/nodes/db_hotdata) | Creates one ephemeral Hotdata database for each pipeline run, or attaches to an existing one so agents in separate runs can share it. |
| [MySQL](/nodes/db_mysql) | A processing component that takes structured table data and inserts it into a MySQL database. |
| [PostgreSQL](/nodes/db_postgres) | A processing component that takes structured table data and inserts it into a PostgreSQL database. |
| [RocketRide SQL](/nodes/rocketride_sql) | A RocketRide-managed relational database. |

### Memory

Persist and recall conversational or working state across runs.

| Node | Description |
| --- | --- |
| [Memory (Internal)](/nodes/memory_internal) | Run-scoped keyed memory store exposed as agent tools. |
| [Persistent Memory](/nodes/memory_persistent) | A persistent cross-session memory node that retains data across pipeline invocations. |

### Agents

Autonomous nodes that plan and call tools to accomplish a goal.

| Node | Description |
| --- | --- |
| [CrewAI Agent](/nodes/agent_crewai) | Standalone single-agent CrewAI node. |
| [CrewAI Agent](/nodes/agent_crewai/crewai_agent) | Standalone single-agent CrewAI node. |
| [CrewAI Manager](/nodes/agent_crewai/crewai_manager) | Multi-agent manager using CrewAI hierarchical process. |
| [CrewAI Subagent](/nodes/agent_crewai/crewai_subagent) | Managed CrewAI sub-agent. |
| [Deep Agent](/nodes/agent_deepagent) | Single-agent execution using Deep Agents. |
| [Deep Agent](/nodes/agent_deepagent/deepagent_agent) | Single-agent execution using Deep Agents. |
| [DeepAgent Subagent](/nodes/agent_deepagent/deepagent_subagent) | Managed Deep Agent subagent. |
| [LangChain](/nodes/agent_langchain) | Single-agent execution using LangChain. |
| [LlamaIndex](/nodes/agent_llamaindex) | Single-agent execution using LlamaIndex's ReAct loop. |
| [RocketRide Wave](/nodes/agent_rocketride) | Wave-planning agent built natively on the RocketRide architecture. |

### Tools

Capabilities an agent or pipeline can invoke: HTTP, shell, code execution, and external APIs.

| Node | Description |
| --- | --- |
| [Apify](/nodes/tool_apify) | Exposes Apify Actors as agent tools. |
| [Bland AI](/nodes/tool_bland_ai) | Make and manage AI-powered phone calls via Bland AI. |
| [Calendar](/nodes/tool_google_workspace/calendar) | Exposes Google Calendar operations as agent tools. |
| [Chart (Chart.js)](/nodes/tool_chartjs) | Generates Chart.js v4 chart configurations from data using the pipeline LLM. |
| [Cognee](/nodes/tool_cognee) | Persistent semantic memory backed by a Cognee server, exposed as three agent tools. |
| [Crustdata](/nodes/tool_crustdata) | Exposes Crustdata's B2B company and people search as agent tools. |
| [Daytona](/nodes/tool_daytona) | Gives agents an isolated Daytona cloud sandbox for running code and shell commands. |
| [DeepL](/nodes/tool_deepl) | Exposes DeepL translation and AI rephrasing as agent tools. |
| [Docs](/nodes/tool_google_workspace/docs) | Exposes Google Docs operations as agent tools. |
| [Drive](/nodes/tool_google_workspace/drive) | Exposes Google Drive operations as agent tools. |
| [Exa Search](/nodes/tool_exa_search) | Exposes Exa semantic web search as an agent tool. |
| [Excel](/nodes/tool_microsoft_365) | Exposes Microsoft Excel operations as agent tools. |
| [Excel](/nodes/tool_microsoft_365/excel) | Exposes Microsoft Excel operations as agent tools. |
| [Firecrawl](/nodes/tool_firecrawl) | Exposes Firecrawl web-scraping operations as agent tools. |
| [Git](/nodes/tool_git) | Exposes local Git repository operations as agent tools. |
| [GitHub](/nodes/tool_github) | Exposes GitHub repository operations as agent tools. |
| [Gmail](/nodes/tool_google_workspace/gmail) | Exposes Gmail operations as agent tools. |
| [GoHighLevel](/nodes/tool_gohighlevel) | Exposes the GoHighLevel (LeadConnector) v2 REST API as agent tools. |
| [Google Calendar](/nodes/tool_google_workspace) | Exposes Google Calendar operations as agent tools. |
| [Google Cloud Storage](/nodes/tool_gcs) | A tool component that interacts with Google Cloud Storage buckets. |
| [HTTP Request](/nodes/tool_http_request) | Makes HTTP requests to public API endpoints, like curl for agents. |
| [LaserData Memory](/nodes/tool_laserdata_memory) | Durable, shared agent memory exposed as tools, backed by LaserData (Apache Iggy) via the Laser SDK. |
| [MCP Client](/nodes/tool_mcp_client) | Connects to the Butterbase MCP server and exposes its backend tools for agent tool-calling. |
| [Mem0](/nodes/tool_mem0) | Long-term, shared agent memory exposed as tools, backed by the hosted Mem0 Platform. |
| [Notion](/nodes/tool_notion) | Exposes a Notion workspace (search, pages, databases) as agent tools. |
| [Onedrive](/nodes/tool_microsoft_365/onedrive) | Exposes Microsoft OneDrive operations as agent tools. |
| [Oura](/nodes/tool_oura) | Exposes Oura Ring health data as read-only agent tools. |
| [Outlook Calendar](/nodes/tool_microsoft_365/outlook_calendar) | Exposes Microsoft Outlook Calendar operations as agent tools. |
| [Outlook Mail](/nodes/tool_microsoft_365/outlook_mail) | Exposes Microsoft Outlook Mail operations as agent tools. |
| [Pipedrive](/nodes/tool_pipedrive) | Exposes the Pipedrive CRM REST API v1 as agent tools. |
| [Pipeline Tool](/nodes/tool_pipe) | Exposes an inline pipeline as an agent tool. |
| [Python](/nodes/tool_python) | Executes Python code in a restricted in-process sandbox via exec(). |
| [Sheets](/nodes/tool_google_workspace/sheets) | Exposes Google Sheets operations as agent tools. |
| [Slack](/nodes/tool_slack) | Exposes Slack workspace operations as agent tools. |
| [Tavily](/nodes/tool_tavily) | Exposes Tavily real-time web search as an agent tool. |
| [v0 by Vercel](/nodes/tool_v0) | A component that connects to Vercel's v0 API to generate React + Tailwind CSS UI components from natural-language prompts. |
| [Vertex AI Vector Search](/nodes/tool_vertex_search) | A processing component that interacts with Google Vertex AI Vector Search. |
| [Word](/nodes/tool_microsoft_365/word) | Exposes Microsoft Word document operations as agent tools. |
| [xTrace Memory](/nodes/tool_xtrace_memory) | Long-term, shared agent memory exposed as tools, backed by xTrace Memory Manager. |

### Preprocessors

Prepare and chunk data before embedding or model calls.

| Node | Description |
| --- | --- |
| [Code](/nodes/preprocessor_code) | A specialized component designed to parse and tokenize source code. |
| [General Text](/nodes/preprocessor_langchain) | A preprocessing component that segments large bodies of text into intelligently sized chunks for downstream processing. |
| [LLM](/nodes/preprocessor_llm) | A processing component that analyzes document content to extract concise summaries, key points, and named entities and to divide a document for storage into a vector database. |
| [Text Chunker](/nodes/chunker) | A text chunking component that splits documents into smaller, semantically coherent chunks for downstream processing such as embedding, retrieval, and LLM-based generation. |

### Data

Extract, shape, and route structured data within the pipeline.

| Node | Description |
| --- | --- |
| [Extract](/nodes/landing_ai/extract) | Extracts structured fields from parsed Markdown using Landing.ai ADE and a JSON Schema you upload. |
| [Guild.ai](/nodes/tool_guild) | Run Guild.ai agents from a RocketRide pipeline or an agent. |
| [Landing.ai Extract](/nodes/landing_ai) | Extracts structured fields from parsed Markdown using Landing.ai ADE and a JSON Schema you upload. |
| [LlamaParse](/nodes/llamaparse) | A document parsing component that uses LlamaParse to extract text and structured data from various document formats including PDFs, images, Word documents, Excel spreadsheets, and other formats. |
| [n8n](/nodes/tool_n8n) | Trigger n8n workflows from a RocketRide pipeline or an agent. |
| [Parse](/nodes/landing_ai/parse) | Parses documents with Landing.ai Agentic Document Extraction (ADE), extracting clean Markdown text and structured tables from PDFs, images, and spreadsheets using the DPT-2 model. |
| [Reducto](/nodes/reducto) | A parsing component that uses Reducto to extract text and structured data from various document formats including PDFs, images, and other document types. |

### Guardrails

Validate and constrain inputs and outputs for safety and policy.

| Node | Description |
| --- | --- |
| [Authoritative Overlay](/nodes/authoritative_overlay) | Cross-checks extracted financial numbers against the US SEC EDGAR company-concept API for a configured CIK, scoped to a filing period (form / fy / fp / end). |
| [Guardrails](/nodes/guardrails) | A comprehensive input/output guardrails filter for AI safety. |

### Outputs

Send results out of the pipeline: responses, files, and external systems.

| Node | Description |
| --- | --- |
| [Local Text Output](/nodes/local_text_output) | A target component that writes data to the file system. |
| [Text Output](/nodes/text_output) | A target component that writes data to the file system. |

### Infrastructure

Plumbing that supports execution rather than transforming data.

| Node | Description |
| --- | --- |
| [Remote Processing](/nodes/remote) | A transport component that forwards data to a remote machine or processing node. |
| [Response](/nodes/response) | A component that returns processed answers back to the requesting client. |

### Graph Databases

Graph Databases nodes.

| Node | Description |
| --- | --- |
| [ArangoDB](/nodes/graph_arango) | A processing component that connects to an ArangoDB multi-model database. |
| [FalkorDB](/nodes/graph_falkordb) | A processing component that connects to a FalkorDB graph database. |
| [HydraDB](/nodes/graph_hydradb) | A database/tool node for HydraDB, a managed graph + memory store. |
| [Neo4J](/nodes/graph_neo4j) | A processing component that connects to a Neo4J graph database. |
| [RocketRide Graph](/nodes/rocketride_graph) | A RocketRide-managed graph database backed by PostgreSQL + Apache AGE. |

### Other

Nodes that do not fall into a single category above.

| Node | Description |
| --- | --- |
| [Core](/nodes/core) | A combined configuration that bundles a preprocessor, embedding model, vector store, and LLM into a single selectable unit. |
| [Fingerprinter](/nodes/core/hash) | A processing component that generates a unique fingerprint (hash) of a document's content. |
| [IBM Watson](/nodes/llm_ibm_watson) |  |
| [Parse/Process/Embed](/nodes/autopipe) | This component combines document parsing, text preprocessing, and embedding generation in a single node. |
| [Parser](/nodes/core/parser) | A document parsing component that extracts rich content from a wide variety of document types. |
| [Vectorizer](/nodes/vectorizer) | An internal filter that chunks incoming text, computes embeddings via the configured embedding component, and writes the resulting documents to the vector store. |


---

# Accessibility Describe

Route: /nodes/accessibility_describe

# accessibility_describe

A RocketRide image node that converts an image into a safety-oriented scene
description for blind and visually impaired users. Choose it when the next step
needs accessible text, including hazards, spatial references, visible text, and
navigation guidance.

## About Google Gemini

Google Gemini is the vision-model provider used by this node through the
`google-genai` Python package. The node sends image bytes and its analysis
prompt to the configured Gemini model in one content-generation request.

## What it does

The node buffers an incoming image stream until it finishes, then passes the
image and configured analysis prompt to Gemini and writes Gemini's response to
the `text` lane. Its built-in instructions emphasize hazards, spatial
orientation, readable text, concision, and environmental context; the default
analysis prompt requests environment, hazards, objects, text, people, and
navigation in fewer than 150 words.

It is a pipeline filter, not an agent tool. Use it for a complete
accessibility-focused narration instead of an image operation whose downstream
consumer needs another kind of result. An empty image stream produces no text.

---

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `text` | Analyze the completed image stream and emit the generated description. |

## Profiles

Default: **Gemini 2.5 Flash - Fast & Efficient (1M tokens)** (`gemini-2.5-flash`).

| Profile | Model | Context limit |
| --- | --- | --- |
| Gemini 2.5 Flash - Fast & Efficient (1M tokens) **(default)** | `gemini-2.5-flash` | `1048576` tokens |
| Gemini 2.5 Pro - High Quality (1M tokens) | `gemini-2.5-pro` | `1048576` tokens |
| Gemini 2.0 Flash - Balanced (1M tokens) | `gemini-2.0-flash` | `1048576` tokens |

## Configuration

Start with the default Flash profile, provide its API key, and keep the built-in
instructions and prompt if their safety-first structure fits the task. Adjust
the text fields when the user needs a different description policy, then use
the two formatting controls to make the output easier to act on. The model and
context-limit values are supplied by the selected profile.

### System Instructions

This text is the model's system instruction. By default it directs the model to
lead with hazards, use clock positions and relative distances, read visible text
exactly, favor actionable information, and identify the environment and
landmarks. Change it for a durable policy that should apply to every image—for
example, to add a site-specific safety rule—rather than to ask about one image.

An empty value falls back first to the generic `systemPrompt` runtime setting,
then to the built-in instruction. The selected hazard priority and spatial
format are appended to this instruction, so keep it compatible with those
controls instead of duplicating contradictory spatial or ordering rules.

### Analysis Prompt

The analysis prompt is the per-image request. Its default requests six
sections—environment, hazards, key objects, text, people, and navigation—and
asks Gemini to keep the description under 150 words. Change it when the output
has to match a particular consumer or structure; for example, ask for a brief
navigation-only description when a downstream voice interface must respond
quickly.

Leaving it empty falls back to the generic `prompt` runtime setting and then to
the built-in prompt. The implementation sends this text with the image, while
the system instructions remain a separate model setting.

### Hazard Priority

This control appends a safety-ordering instruction to the system prompt. The
default `high` tells the model to lead with hazards and to state that the area
appears safe when it finds none. Choose `medium` to include hazards in their
spatial context without requiring them first, or `low` for no extra hazard
emphasis. Keep `high` for navigation-oriented descriptions; lower it only when
another description order is more useful.

### Spatial Format

This control appends the requested spatial-language style to the system prompt.
`clock`, the default, asks for clock positions with 12 o'clock straight ahead;
`relative` asks for left, right, ahead, and behind; `both` asks for both forms.
Use `relative` for readers unfamiliar with clock positions, or `both` when
redundant orientation is valuable. It works alongside Hazard Priority because
hazards can use whichever spatial convention is selected.

---

## Authentication

Set the selected profile's Google AI API key in the node configuration. The
node will not start without a key, and it rejects a value beginning with `sk-`
as an OpenAI key rather than sending it to Gemini. Create the required key in
[Google AI Studio](https://aistudio.google.com/apikey).

## Notes

### Request and failure behavior

At the end of the image stream, the node base64-encodes the received bytes into
a data URL and sends the decoded bytes to Gemini with temperature `0.3` and a
maximum of `1024` output tokens. It makes one initial request plus up to three
retries for errors whose messages indicate a timeout, connection failure, HTTP
`500`, `502`, `503`, or `504`, or an internal server error; retry waits are 1,
2, and 4 seconds.

If all attempts fail, it raises an accessibility-vision error. Authentication,
rate-limit, invalid-input, unavailable-model, timeout, and safety-block
messages are translated to user-facing error text; other failures retain the
Google AI error message. A missing image or malformed image data URL raises a
value error before the model request.

## Upstream docs

- [Google Gemini API documentation](https://ai.google.dev/gemini-api/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `accessibility.prioritizeHazards` | `string` | **Hazard Priority**<br/>How aggressively to prioritize hazard detection | `"high"` |
| `accessibility.prompt` | `string` | **Analysis Prompt**<br/>Prompt template for generating accessibility descriptions from images | `"Describe this image for a blind person. Include: environment type, hazards with positions, key objects with clock positions, visible text, people, and navigation guidance. Keep under 150 words."` |
| `accessibility.spatialFormat` | `string` | **Spatial Format**<br/>How to describe spatial positions | `"clock"` |
| `accessibility.systemPrompt` | `string` | **System Instructions**<br/>Define the accessibility description behavior and priorities | `"You are an accessibility-focused scene analyzer designed to help blind and visually impaired users understand their surroundings through image descriptions."` |
| `accessibility_describe.profile` | `string` | **Vision Model**<br/>Select the Gemini vision model for accessibility descriptions | `"gemini-2.5-flash"` |
| `model` | `string` | **Model**<br/>Google Gemini vision model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |

## Dependencies

- `google-genai` `>=1.14.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/accessibility_describe)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# CrewAI Agent

Route: /nodes/agent_crewai

# agent_crewai

A RocketRide family of CrewAI nodes for a standalone agent, a manager that
delegates work to CrewAI subagents, and subagents used only by that manager.
Choose the Agent for one task, or the Manager and Subagent pair when work needs
named specialists.

## About CrewAI

CrewAI is a framework whose Agent, Task, and Crew objects organize language
model work and tool use. These nodes use those objects with RocketRide-provided
LLM and tool connections instead of configuring a model provider in CrewAI.

## What it does

The standalone CrewAI Agent receives a question, builds a one-agent sequential
crew, and sends its result to `answers`; it can also serve as a parent agent's
tool. The CrewAI Manager collects descriptors from connected CrewAI Subagents,
builds a hierarchical crew, and returns its synthesized result on the same
lane or as a tool result. A Subagent is not directly runnable: the Manager
builds its Agent and Task and uses the Subagent's own LLM and optional tool
connections while delegated work runs. Choose the Agent for an independent
task and the Manager plus Subagents for explicit division of work.

## Connections

### CrewAI Agent

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used by the standalone agent. |
| `tool` | no | Tools available to the agent through control-plane invocation. |

### CrewAI Manager

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used by the manager agent. |
| `tool` | no | Cross-cutting tools available to the manager itself through control-plane invocation. |
| `crewai` | yes | Connected CrewAI Subagent nodes to describe and delegate to. |

### CrewAI Subagent

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used when the Manager delegates to this subagent. |
| `tool` | no | Tools available to this subagent through control-plane invocation. |

The Manager stops with an error if no Subagent is connected or if none respond
to its `describe` fan-out. A Subagent's `tool` connection belongs to the
delegated specialist, not to the Manager.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `answers` | CrewAI Agent: run the standalone crew and emit its result. |
| `questions` | `answers` | CrewAI Manager: run the hierarchical crew and emit its result. |

CrewAI Subagent declares no lanes. Wire it to a Manager's `crewai` connection;
a direct question is rejected as an invalid use of the subagent.

## As a tool

The CrewAI Agent and CrewAI Manager each register
`<nodeId>.run_agent`, using their own pipeline node ID as the prefix. The
CrewAI Subagent is not a tool and exposes no `run_agent` function.

| Function | Description |
| --- | --- |
| `<nodeId>.run_agent` | CrewAI Agent: run the standalone agent for a delegated query and return its agent result. |
| `<nodeId>.run_agent` | CrewAI Manager: run the manager and its connected subagent crew for a delegated query and return its agent result. |

Both functions require an object with a non-empty `query: string` and accept
an optional `context: object`. Context is encoded as a
`RocketRide.agent.tool_context.v1` entry, and the result is
`{content, meta, stack}` rather than an `answers`-lane write. Non-object
input, a blank query, or non-object context raises `ValueError`. When an
agent description is configured, it is prepended to the registered tool
description that a parent agent sees.

## Configuration

Each variant has the `default` profile. Begin by wiring the LLM and, where
applicable, the Manager-to-Subagent and tool connections; use **Advanced Mode**
only after the basic role is clear. Empty advanced text fields fall back to the
drivers' built-in goal, backstory, and expected-output text where that driver
uses those fields.

### Agent description

CrewAI Agent and CrewAI Manager expose this field to parent agents through
their `run_agent` tool descriptions. Describe the actual job, inputs, and
expertise of the standalone agent or of the manager-and-crew as a whole, so a
parent can decide when to delegate. A specific value such as “Coordinates
research and fact-checking specialists” is useful; leave it empty when nothing
will call the node as a tool.

### Instructions

Instructions are appended as a bullet list to the CrewAI Agent's backstory.
For a Manager, they guide its delegation strategy through the manager
backstory; for a Subagent, they become part of the specialist's backstory.
Use short, durable constraints such as “cite the evidence supplied by tools,”
rather than duplicating the role and task text configured in Advanced Mode.

### Require tool call

This setting is off by default on the Agent and Manager. Enable it when a
response must be based on at least one real tool invocation, rather than an
answer produced without external work. For a Manager, tool invocations made by
delegated Subagents count toward the same guard. Leave it off when a valid
answer may require no tool call.

### Advanced Mode

Advanced Mode is off by default and reveals the CrewAI Agent and Task fields.
Turn it on only when the default Assistant/Specialist behavior and built-in
fallbacks are insufficient. It does not make a Subagent independently
runnable: that node remains a Manager-only component.

### Agent and task fields

For the standalone Agent, **Role**, **Goal**, **Backstory**, **Task**, and
**Expected Output** map to the CrewAI Agent and Task built for each question.
When Task is blank, the incoming question becomes the task; when it is set,
the question is appended as `User request:` context. Set Task when each run
has a stable assignment, and leave it blank for a general-purpose assistant.

For a Subagent, **Role** is the specialist name the Manager gives to CrewAI;
**Goal**, **Backstory**, **Task**, and **Expected Output** define the delegated
Agent and Task. A blank Subagent Task becomes `{user_request}`, while a
configured task can use CrewAI template variables such as `{user_request}`.
Use a unique, descriptive Role and a task that names the specialist's output;
the Manager uses the descriptor to assemble its crew.

For the Manager, **Manager Goal** and **Manager Backstory** configure its
delegator Agent. Set them when the Manager needs a particular delegation
policy or domain framing; otherwise it uses its built-in management goal and
backstory.

### Crew Planning

This Manager-only option is off by default. When enabled, CrewAI runs a planner
before the hierarchical crew and supplies the resulting plan to tasks; it also
adds an LLM call. Enable it only when the connected LLM reliably returns the
JSON CrewAI's planning conversion requires: a prose plan can make the whole run
fail with `Failed to get the Planning output`.

## Notes

### Manager execution

The Manager invokes `describe` on each explicitly connected Subagent, then
creates an Agent and Task for every descriptor. It gives the manager
`allow_delegation=True` and each specialist `allow_delegation=False`; the
specialist tasks have their direct tool lists cleared so the manager delegates
rather than using a specialist's tools itself. The Manager prefers the last
completed task's cleaned output to avoid returning its whole hierarchical
ReAct trace.

### Runtime and progress

All CrewAI kickoffs share one daemon-thread asyncio loop because the driver
treats CrewAI's process-wide internals as unsafe across multiple threads.
Concurrent kickoffs can still interleave at await points. A process-wide
listener forwards relevant CrewAI events to the initiating run as `thinking`
SSE messages; stream chunks and terminal formatter events are intentionally
not forwarded.

### Tool execution

The CrewAI LLM wrapper delegates through the node's `llm` connection and
reports no native function-calling support, so CrewAI uses its ReAct tool path.
Each connected tool is wrapped with an argument schema made from its declared
JSON input schema; exceptions from a wrapped tool are returned to CrewAI as an
object containing `error` and `type`.

## Upstream docs

- [CrewAI documentation](https://docs.crewai.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### CrewAI Agent (`services.agent.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `advanced_mode` | `boolean` | **Advanced Mode**<br/>Expose CrewAI Agent and Task configuration directly. | `false` |
| `agent_crewai.agent_config_header` | `null` | **Agent Config** | `null` |
| `agent_crewai.task_config_header` | `null` | **Task Config** | `null` |
| `agent_description` | `string` | **Agent description**<br/>What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` |
| `backstory` | `string` | **Backstory**<br/>Background context for this agent's persona. Maps to CrewAI Agent(backstory=...). |  |
| `expected_output` | `string` | **Expected Output**<br/>Description of the expected output format. Maps to CrewAI Task(expected_output=...). |  |
| `goal` | `string` | **Goal**<br/>What this agent is trying to achieve. Maps to CrewAI Agent(goal=...). |  |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the agent. |  |
| `require_tool_call` | `boolean` | **Require tool call**<br/>Require the agent to invoke at least one tool before answering. When on, a run that answers without calling any tool fails with a guard error. Use for determinism-critical pipelines where an ungrounded or narrated answer must never be delivered. Off by default. | `false` |
| `role` | `string` | **Role**<br/>Agent role name (e.g. 'Financial Analyst'). Maps to CrewAI Agent(role=...). |  |
| `task_description` | `string` | **Task**<br/>What this agent should do. If blank, the incoming question is used. Maps to CrewAI Task(description=...). |  |

### CrewAI Manager (`services.manager.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `advanced_mode` | `boolean` | **Advanced Mode**<br/>Expose CrewAI manager Agent configuration directly. | `false` |
| `agent_description` | `string` | **Agent description**<br/>What this manager + its sub-agent crew does. Used by parent agents that call this manager as a tool via `<nodeId>.run_agent` to decide when to invoke it. | `""` |
| `backstory` | `string` | **Manager Backstory**<br/>Background context for the manager's persona. Maps to CrewAI Agent(backstory=...). |  |
| `goal` | `string` | **Manager Goal**<br/>What the manager is trying to achieve. Maps to CrewAI Agent(goal=...). |  |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the manager's delegation strategy. |  |
| `planning` | `boolean` | **Crew Planning**<br/>Run CrewAI's planner before the crew executes, adding a step-by-step plan to each task. Off by default: the planner requires the LLM to return JSON matching CrewAI's plan schema, and a model that answers in prose instead fails the whole run with <b>Failed to get the Planning output</b>. It also costs one extra LLM call per kickoff. Enable only with a model that reliably emits well-formed JSON. | `false` |
| `require_tool_call` | `boolean` | **Require tool call**<br/>Require at least one tool call (including calls delegated to sub-agents) before answering. When on, a run that answers without any tool invocation fails with a guard error. Use for determinism-critical pipelines where an ungrounded or narrated answer must never be delivered. Off by default. | `false` |

### CrewAI Subagent (`services.subagent.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `advanced_mode` | `boolean` | **Advanced Mode**<br/>Expose CrewAI Agent and Task configuration directly. | `false` |
| `agent_crewai_subagent.agent_config_header` | `null` | **Agent Config** | `null` |
| `agent_crewai_subagent.task_config_header` | `null` | **Task Config** | `null` |
| `backstory` | `string` | **Backstory**<br/>Background context for this sub-agent's expertise. Helps the Manager and the sub-agent's own LLM reason about when it's the right choice. Maps to CrewAI Agent(backstory=...). |  |
| `expected_output` | `string` | **Expected Output**<br/>Description of the expected output format. Maps to CrewAI Task(expected_output=...). |  |
| `goal` | `string` | **Goal**<br/>What this sub-agent aims to achieve when delegated to. Maps to CrewAI Agent(goal=...). |  |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide this sub-agent when the Manager delegates to it. |  |
| `role` | `string` | **Role**<br/>Sub-agent role name (e.g. 'Financial Analyst'). The Manager uses this name when routing delegation. Maps to CrewAI Agent(role=...). |  |
| `task_description` | `string` | **Task**<br/>What this sub-agent does when delegated to by the Manager. The user's request is passed as additional context at run time. Maps to CrewAI Task(description=...). |  |

## Dependencies

- `crewai` `>=1.14.1,<2`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_crewai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# CrewAI Agent

Route: /nodes/agent_crewai/crewai_agent

---
title: CrewAI Agent
date: 2026-04-11
sidebar_position: 3
---

<head>
  <title>CrewAI Agent - RocketRide Documentation</title>
</head>

## What it does

Standalone single-agent [CrewAI](https://docs.crewai.com/) node. Receives a question, runs a one-agent `Crew`, and emits an answer. Can also be invoked as a tool by other agents via `<nodeId>.run_agent`.

**Lanes:** `questions` → `answers`

## Connections

| Channel | Required | Description                  |
| ------- | -------- | ---------------------------- |
| `llm`   | yes      | LLM the agent thinks with    |
| `tool`  | no       | Tools available to the agent |

## Configuration

By default only **Agent Description** and **Instructions** are shown. Toggle **Advanced Mode** to expose CrewAI-specific fields.

**Always visible:**

| Field             | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| Agent Description | What this agent does, used by parent agents to select and invoke it  |
| Instructions      | Extra guidance appended to the agent's backstory                     |

**Advanced Mode (Agent):**

| Field     | Default     | Maps to                |
| --------- | ----------- | ---------------------- |
| Role      | `Assistant` | `Agent(role=...)`      |
| Goal      | built-in    | `Agent(goal=...)`      |
| Backstory | built-in    | `Agent(backstory=...)` |

**Advanced Mode (Task):**

| Field           | Default             | Maps to                     |
| --------------- | ------------------- | --------------------------- |
| Task            | _(incoming prompt)_ | `Task(description=...)`     |
| Expected Output | built-in            | `Task(expected_output=...)` |

## Multi-agent workflows

For hierarchical multi-agent orchestration, use the `CrewAI Manager` node with one or more `CrewAI Subagent` nodes instead. A `CrewAI Agent` node cannot be used as a sub-agent under a Manager, that role is filled by `CrewAI Subagent`.


---

# CrewAI Manager

Route: /nodes/agent_crewai/crewai_manager

---
title: CrewAI Manager
date: 2026-03-02
sidebar_position: 4
---

<head>
  <title>CrewAI Manager - RocketRide Documentation</title>
</head>

## What it does

Hierarchical [CrewAI](https://docs.crewai.com/) manager node. Fans out to all connected `CrewAI Subagent` nodes, assembles a `Process.hierarchical` Crew, and synthesizes their outputs into a final answer. Can also be invoked as a tool by other agents via `<nodeId>.run_agent` for cross-framework nesting.

**Lanes:** `questions` → `answers`

## Connections

| Channel  | Required    | Description                                                                                                                       |
| -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `llm`    | yes         | LLM for the manager agent (and planning, when enabled)                                                                            |
| `tool`   | no          | Cross-cutting tools available to the manager itself, e.g. a dedup/lookup check it should run before finalizing a delegated result |
| `crewai` | yes (min 1) | Connected `CrewAI Subagent` nodes (min 1)                                                                                         |

The `crewai` channel accepts only `CrewAI Subagent` nodes. `CrewAI Agent` nodes cannot be used as sub-agents, their `classType` does not include `crewai`. The Manager itself also cannot be nested under another Manager (it lacks `classType: "crewai"`); cross-Manager composition is supported via `tool.run_agent` instead.

## Configuration

By default only **Instructions** is shown. Toggle **Advanced Mode** to expose the manager agent's CrewAI fields.

**Always visible:**

| Field        | Description                                             |
| ------------ | ------------------------------------------------------- |
| Instructions | Delegation guidance appended to the manager's backstory |

**Advanced Mode:**

| Field             | Default  | Maps to                |
| ----------------- | -------- | ---------------------- |
| Manager Goal      | built-in | `Agent(goal=...)`      |
| Manager Backstory | built-in | `Agent(backstory=...)` |

## How it works

1. Fans out `describe` to each connected `CrewAI Subagent` node individually
2. Each `CrewAI Subagent` responds with its role, goal, backstory, task description, expected output, and tools
3. The manager builds an `Agent + Task` per sub-agent, routing LLM and tool calls back through that sub-agent's own pipeline channels. Each delegate task then carries the manager's own `tool` channel in place of the tools it inherited — one assignment that keeps a sub-agent's tools off the manager and makes the manager's cross-cutting tools available on every task it executes. Delegation is unaffected: CrewAI merges the delegation tools on top. The manager agent itself holds no tools, because CrewAI rejects a hierarchical manager that carries any tools
4. Kicks off a hierarchical Crew, running CrewAI's planner with the manager's LLM only when **Crew Planning** is enabled (off by default)

The node raises an error at runtime if no sub-agents are connected or none respond to `describe`.


---

# CrewAI Subagent

Route: /nodes/agent_crewai/crewai_subagent

---
title: CrewAI Subagent
date: 2026-04-11
sidebar_position: 4
---

<head>
  <title>CrewAI Subagent - RocketRide Documentation</title>
</head>

## What it does

Managed [CrewAI](https://docs.crewai.com/) sub-agent. Wired into a `CrewAI Manager` via the `crewai` invoke channel. The Manager fans out `describe` to collect this sub-agent's role, goal, backstory, and task, then builds it into its own hierarchical `Crew`.

**Lanes:** none, this node is driven by a Manager, not by direct questions.

## Connections

| Channel | Required | Description                       |
| ------- | -------- | --------------------------------- |
| `llm`   | yes      | LLM this sub-agent thinks with    |
| `tool`  | no       | Tools available to this sub-agent |

The sub-agent's LLM and tool channels are independent of the Manager's. When the Manager delegates to this sub-agent, LLM and tool calls are routed back through this node's own channels.

## Configuration

By default only **Agent Description** and **Instructions** are shown. Toggle **Advanced Mode** to expose CrewAI-specific fields.

**Always visible:**

| Field             | Description                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------- |
| Agent Description | What this sub-agent specializes in, used by the Manager when deciding who to delegate to  |
| Instructions      | Extra guidance appended to this sub-agent's backstory                                     |

**Advanced Mode (Agent):**

| Field     | Default      | Maps to                |
| --------- | ------------ | ---------------------- |
| Role      | `Specialist` | `Agent(role=...)`      |
| Goal      | built-in     | `Agent(goal=...)`      |
| Backstory | built-in     | `Agent(backstory=...)` |

**Advanced Mode (Task):**

| Field           | Default             | Maps to                     |
| --------------- | ------------------- | --------------------------- |
| Task            | _(incoming prompt)_ | `Task(description=...)`     |
| Expected Output | built-in            | `Task(expected_output=...)` |

## Pipeline wiring

Must be wired into a `CrewAI Manager`'s `crewai` channel. **Can be connected to multiple Managers simultaneously**, each Manager independently includes this sub-agent in its own hierarchical `Crew`. This enables shared specialist sub-agents across multiple delegation hierarchies.

This node has **no `questions` lane** and cannot be invoked directly. It also cannot be called as a tool via `tool.run_agent`, Subagent's `classType` excludes `"tool"`. For a CrewAI agent that runs standalone or can be called as a tool by other agents, use the `CrewAI Agent` node instead.


---

# Deep Agent

Route: /nodes/agent_deepagent

# agent_deepagent

A planning-capable RocketRide agent built on the Deep Agents library, with optional managed sub-agents for hierarchical delegation.

## About Deep Agents

Deep Agents is an open-source agent framework built on LangChain and
LangGraph. It layers the machinery long-running tasks need — upfront
planning, state that persists across steps, and long-context management — on
top of the standard tools-plus-LLM agent loop.

## What it does

Runs an agent loop via `deepagents.create_deep_agent` (built on LangChain/LangGraph), which layers strategic planning, persistent state, and long-context management on top of the standard LangChain tool-calling loop. The package ships two node variants:

- **Deep Agent** (`agent_deepagent`): the orchestrator. Consumes `questions` and produces `answers`, runs standalone with its own tools, and registers as a tool (`classType: ["agent", "tool"]`) so a parent agent can delegate to it via `<nodeId>.run_agent`.
- **Deep Agent Subagent** (`agent_deepagent_subagent`): a managed worker (`classType: ["deepagent"]`). It has no `questions` lane and cannot be invoked directly or called as a tool; it must be wired into a Deep Agent via the `deepagent` invoke channel, which delegates to it based on its `description`.

Sub-agents are optional: with none connected, the Deep Agent behaves as a standard single-agent node. Inference is routed through the host LLM channel using a JSON envelope protocol, so any LLM that can follow JSON instructions works; native function-calling support is not required. Agent lifecycle progress (tool calls, LLM calls, agent steps) is streamed as SSE `thinking` events.

## Example pipelines

**Research assistant with an HTTP tool**

`chat → agent_deepagent → response_answers`

<div align="center">

![The Deep Agent node on the canvas with an LLM and an HTTP Request tool connected](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

`llm_anthropic` is wired to `llm` and `tool_http_request` to `tool`. Chat
questions reach the agent, which can call the HTTP tool before returning an
answer.

**Hierarchical team with specialists**

`webhook → agent_deepagent → response`, plus two Deep Agent Subagents on the
`deepagent` channel: a researcher (tools: `tool_exa_search`) and a coder
(tools: `tool_python`, `tool_github`), each with its own `llm`. The
orchestrator breaks the task apart and delegates each piece to the sub-agent
whose Description matches, and the plural `tool_calls` envelope lets it
delegate to several sub-agents in parallel in a single turn.

**Agent-callable research service**

A parent agent (e.g. `agent_rocketride`) with this Deep Agent connected as a
tool. With a filled-in Agent description, the parent invokes
`<nodeId>.run_agent` when it hits a question needing deep multi-step
research rather than attempting it in its own loop.

## Connections

### Deep Agent

| Channel     | Required    | Description                                                  |
|-------------|-------------|--------------------------------------------------------------|
| `llm`       | yes (min 1) | LLM used by the agent                                        |
| `tool`      | no          | Tools available to the agent (via control-plane invoke)      |
| `deepagent` | no          | Deep Agent Subagent nodes for hierarchical delegation        |

### Deep Agent Subagent

| Channel | Required    | Description                                    |
|---------|-------------|------------------------------------------------|
| `llm`   | yes (min 1) | LLM this sub-agent thinks with                 |
| `tool`  | no          | Tools available to this sub-agent              |

The sub-agent's LLM and tool channels are independent of the orchestrator's. When the orchestrator delegates, the sub-agent's LLM and tool calls are routed back through this node's own channels.

## Lanes

| Lane in     | Lane out  | Description                                     |
| ----------- | --------- | ----------------------------------------------- |
| `questions` | `answers` | Send the agent a task, receive its final answer |

Deep Agent only. The Subagent declares no lanes; it is driven by an
orchestrator, not by direct questions.

## As a tool

The Deep Agent (not the Subagent) exposes itself as an invokable tool, `<nodeId>.run_agent`, so parent agents can delegate to it in nested pipelines.

- **Input:** `{query: string, context?: object}`. `query` must be a non-empty string; `context`, when provided, is attached to the question as a `RocketRide.agent.tool_context.v1` JSON payload.
- **Output:** `{content, meta, stack}`.

When `agent_description` is non-empty it is included in the tool's description so parent agents can select this agent correctly.

## Configuration

Both variants are steered the same way: by default you add **Instructions**,
and turning on **Advanced Mode** swaps them for direct prompt fields. The
field-level details:

### Description (Subagent)

The most important field on a sub-agent. The orchestrating Deep Agent reads
**only this text** when deciding which sub-agent gets a task — it cannot see
the sub-agent's prompt, tools, or LLM. Keep it specific and action-oriented:
"Searches the web and summarizes findings with sources" gets routed work;
"helper agent" never gets picked. If a sub-agent sits idle while the
orchestrator does everything itself, fix this field first.

### Agent description (Deep Agent)

The same idea one level up: when the Deep Agent is used as a tool by a parent
agent, this text is folded into the `run_agent` tool description so the
caller can decide when to invoke it. Leave it blank if nothing calls this
agent as a tool.

### Instructions, System prompt & Advanced Mode

With Advanced Mode **off** (the default), you steer the agent by adding
Instructions — each non-empty line is appended, on its own line, to the
built-in system prompt that already handles planning and state. With Advanced
Mode **on**, the Instructions list is replaced by the raw prompt fields
(`system_prompt`, and `agent_description` on the orchestrator) for full
control; a blank `system_prompt` falls back to the built-in default. Stay in
default mode unless the built-in prompt is actively in your way — replacing
it discards the planning behavior that makes Deep Agents worth choosing.

### Require tool call

Smaller or weaker planning models occasionally **narrate** a multi-step tool
chain in prose instead of actually calling the tools, producing a
plausible-looking but ungrounded answer. When this toggle is on, any run that
produces an answer without invoking at least one tool fails with a
`RocketRide.agent.guard.v1` error instead of delivering the ungrounded text.
Off by default; enable it for determinism-critical pipelines. The guard
counts real tool invocations only — internal/local reads (for example the
wave agent's `memory.peek`) do not satisfy it.

## Notes

### Tool calling protocol

The host LLM is opaque to the driver, so tool calling uses a JSON envelope protocol: each LLM call is prefixed with a system preamble. **Tool calls are JSON; an answer to the person is not.**

- Single tool call: `{"type":"tool_call","name":"server.tool","args":{...}}`
- Parallel tool calls: `{"type":"tool_calls","calls":[{"name":"...","args":{...}}, ...]}`
- Final answer: `FINAL>>>` followed by the answer as plain text

**Why the answer left JSON.** Arguments are structured data, where JSON earns its keep. An answer is prose, and the JSON form asked the model to escape a whole markdown table into a string value — one missed inner quote and the envelope stopped parsing, so the person read the envelope instead of the answer. After `FINAL>>>` there is nothing left to escape, and the text is delivered exactly as written. The `{"type":"final","content":"..."}` shape is still accepted by the parser for any model that emits it; it is no longer what the preamble asks for.

"Exactly as written" is literal: only the separator between the marker and the answer is removed — one newline, or one space on the same line. Whitespace after that belongs to the answer, so `FINAL>>>` followed by an indented line still arrives as a markdown code block.

The sentinel is matched **at the start of a line** and is checked before any JSON is parsed. Before it, because an answer may legitimately open with `{`; anchored, because protocol text travels — a delegation carrying instructions, a note quoting the format, a transcript replayed into a prompt — and an unanchored match would read a tool call that merely mentions `FINAL>>>` as a final answer and drop the call. A sentinel with nothing after it is not an answer, and goes back through the retry loop.

The plural `tool_calls` form dispatches all entries concurrently (LangGraph's async ToolNode fans them out via `asyncio.gather`), which is what unlocks parallel sub-agent delegation in a single turn.

Up to 3 attempts are made when the LLM produces malformed JSON. Each retry names the character that broke the parse and quotes the text around it, and what it asks for next depends on what was attempted: a broken **answer** is pointed at `FINAL>>>`, where nothing can break again, while a broken **tool call** is asked for the same call repaired — telling the model to answer in prose instead would trade the work for a sentence about it. A tolerant parser extracts the first balanced JSON object, rescuing responses wrapped in markdown fences, followed by trailing prose, or stacked with a stray second object (a common failure mode: a duplicate call or hallucinated `final` appended after a `tool_call`). An unparseable envelope that unmistakably opens as a `final` is salvaged for its content rather than printed at the person; a malformed TOOL call never is, since rescuing one would turn work the crew intended to do into a sentence claiming it was done.

Host tool descriptors are converted to LangChain `BaseTool` instances with typed Pydantic input schemas built from each tool's JSON-Schema `inputSchema`; tool execution and LLM calls are bridged off the event loop via `asyncio.to_thread` so concurrent calls do not serialize.

### Hierarchical delegation

Connect one or more Deep Agent Subagent nodes to the `deepagent` invoke channel to turn the Deep Agent into an orchestrator. On each run:

1. The orchestrator fans out a `describe` invoke to every connected Subagent node.
2. Each sub-agent returns its name, description, system prompt, instructions, and a reference to its own engine channels.
3. The orchestrator builds a `deepagents.middleware.subagents.SubAgent` record per descriptor, wiring each sub-agent's LLM and tools to its own channels, and passes them to `create_deep_agent(subagents=...)`.
4. The orchestrator's LLM gains a `task(description, subagent_type)` tool it calls to delegate work. Each sub-agent runs in its own `AgentContext` that inherits the run metadata, so SSE events route back to the same logical run.

Give each sub-agent its own LLM, tools, and a clear `description`: the description is the only signal the orchestrator uses to choose a delegate. A Subagent can be connected to multiple orchestrators simultaneously; each orchestrator independently includes it in its own hierarchical run. A `describe` failure on one node is logged and skipped, not fatal to the run.

### Observability

The driver emits SSE `thinking` events throughout a run: host-tool discovery count, sub-agent collection count, agent start, per-tool start/completion/error (with tool name and input length), LLM call start/completion/error, and agent thinking/done transitions.

## Upstream docs

- [Deep Agents documentation](https://docs.langchain.com/oss/python/deepagents/overview)
- [LangChain documentation](https://python.langchain.com/docs/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Deep Agent (`services.agent.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `advanced_mode` | `boolean` | **Advanced Mode**<br/>When enabled, replace the Instructions list with direct Agent Description and System Prompt fields for full control. | `false` |
| `agent_description` | `string` | **Agent description**<br/>What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the agent. Each line is appended to the system prompt. |  |
| `require_tool_call` | `boolean` | **Require tool call**<br/>Require the agent to invoke at least one tool before answering. When on, a run that answers without calling any tool fails with a guard error. Use for determinism-critical pipelines where an ungrounded or narrated answer must never be delivered. Off by default. | `false` |
| `system_prompt` | `string` | **System prompt**<br/>Instructions that define this agent's role and behaviour. Leave blank to use the default. | `""` |

### Deep Agent Subagent (`services.subagent.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `advanced_mode` | `boolean` | **Advanced Mode**<br/>When enabled, replace the Instructions list with a direct System Prompt field for full control. | `false` |
| `description` | `string` | **Description**<br/>The orchestrator reads this description to decide when to delegate to this sub-agent. Keep it specific and action-oriented, this is the only signal the orchestrator uses to pick a sub-agent. | `""` |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide this sub-agent. Each line is appended to the system prompt. |  |
| `system_prompt` | `string` | **System prompt**<br/>Instructions that define this sub-agent's role and behaviour. Leave blank to use the default. | `""` |

## Dependencies

- `deepagents`
- `langchain`
- `langchain-core`
- `pydantic`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_deepagent)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Deep Agent

Route: /nodes/agent_deepagent/deepagent_agent

---
title: Deep Agent
date: 2026-04-13
sidebar_position: 1
---

<head>
  <title>Deep Agent - RocketRide Documentation</title>
</head>

## What it does

Agent node built on the [`deepagents`](https://github.com/langchain-ai/deepagents) library (LangChain/LangGraph). Adds strategic planning, persistent state, and long-context management on top of a standard LangChain agent loop.

Runs standalone with its own tools, or as an orchestrator that delegates to connected `Deep Agent Subagent` nodes on the `deepagent` invoke channel. Subagents are optional, behaviour matches the old single-agent node when none are wired.

**Lanes:** `questions` → `answers`

## Connections

| Channel     | Required | Description                                          |
| ----------- | -------- | ---------------------------------------------------- |
| `llm`       | yes      | LLM the agent thinks with                            |
| `tool`      | no       | Tools available to the agent                         |
| `deepagent` | no       | Connected `Deep Agent Subagent` nodes for delegation |

## Configuration

By default only **Instructions** is shown. Toggle **Advanced Mode** to expose the agent description and system prompt directly.

**Normal Mode:**

| Field        | Description                                         |
| ------------ | --------------------------------------------------- |
| Instructions | Lines appended to the agent's default system prompt |

**Advanced Mode:**

| Field             | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| Agent Description | What this agent does, used by parent agents to select and invoke it  |
| System Prompt     | The agent's full system prompt (overrides the built-in default)      |

## Tool calling

This node uses a **JSON envelope protocol** for tool calling: the host LLM is instructed to output either `{"type":"tool_call","name":"...","args":{...}}` or `{"type":"final","content":"..."}`. Works with any LLM that can follow JSON instructions, not just ones with native function-calling support. Up to 3 retries are attempted when the LLM produces malformed JSON, and a tolerant parser rescues responses with trailing content or a stray second object.

## Subagents

Connect one or more `Deep Agent Subagent` nodes to the `deepagent` invoke channel to turn this node into an orchestrator. Each subagent is a specialist: give it its own LLM, tools, and a clear description so the orchestrator knows when to delegate to it.

When subagents are wired up:

1. The orchestrator fans out a `describe` invoke to every connected `Deep Agent Subagent` node.
2. Each subagent returns its name, description, system prompt, and a reference to its own LLM and tools.
3. The orchestrator passes all subagents to `create_deep_agent(subagents=...)` and gains a `task(description, subagent_type)` tool it can call to delegate work.
4. Each subagent runs in its own `AgentContext` so SSE events route back to the correct run.

Subagents are optional, when none are wired the node behaves as a standard single-agent.

## Hierarchical delegation

On each run the orchestrator fans out a `describe` invoke, collects each subagent's descriptor, builds a `deepagents.SubAgent` record per subagent wired to its own LLM + tool channels, and passes them to `create_deep_agent(subagents=...)`. The orchestrator's LLM then calls the `task(description, subagent_type)` tool to delegate, each subagent runs inside its own `AgentContext` so SSE events route back to the same logical run.

## Using as a tool

This node exposes itself as an invokable tool (`<nodeId>.run_agent`) so parent agents can delegate to it in nested pipelines.


---

# DeepAgent Subagent

Route: /nodes/agent_deepagent/deepagent_subagent

---
title: DeepAgent Subagent
date: 2026-04-13
sidebar_position: 2
---

<head>
  <title>DeepAgent Subagent - RocketRide Documentation</title>
</head>

## What it does

Managed sub-agent driven by a `Deep Agent` orchestrator over the `deepagent` invoke channel. The orchestrator fans out `describe` to collect this sub-agent's description, system prompt, and instructions, then builds it into a `deepagents.SubAgent` record callable via the orchestrator LLM's `task` tool.

**Lanes:** none, this node is driven by an orchestrator, not by direct questions.

## Connections

| Channel | Required | Description                       |
| ------- | -------- | --------------------------------- |
| `llm`   | yes      | LLM this sub-agent thinks with    |
| `tool`  | no       | Tools available to this sub-agent |

The sub-agent's LLM and tool channels are independent of the orchestrator's. When the orchestrator delegates to this sub-agent, LLM and tool calls are routed back through this node's own channels.

## Configuration

**Always visible:**

| Field       | Description                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| Description | Short specialization summary. **This is the only signal the orchestrator reads to decide when to delegate.** |

Toggle **Advanced Mode** to replace _Instructions_ with a full _System Prompt_ field.

**Normal Mode:**

| Field        | Description                                              |
| ------------ | -------------------------------------------------------- |
| Instructions | Lines appended to this sub-agent's default system prompt |

**Advanced Mode:**

| Field         | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| System Prompt | The sub-agent's full system prompt (overrides the built-in default) |

## Pipeline wiring

Must be wired into a `Deep Agent` node's `deepagent` channel. **Can be connected to multiple orchestrators simultaneously**, each orchestrator independently includes this sub-agent in its own hierarchical run.

This node has **no `questions` lane** and cannot be invoked directly. It also cannot be called as a tool via `tool.run_agent`, Subagent's `classType` is `["deepagent"]` only. For a DeepAgent that runs standalone or can be called as a tool by other agents, use the `Deep Agent` node instead.


---

# LangChain

Route: /nodes/agent_langchain

# agent_langchain

A RocketRide agent node for answering questions with a LangChain agent loop and
the LLM and tools wired into the pipeline. Choose it when a single agent should
use LangChain's structured tool-call flow, rather than coordinate CrewAI
subagents.

## About LangChain

LangChain is a framework for building applications that combine language models
with tools and message-based workflows. This node uses its agent and chat-model
interfaces while keeping model and tool execution on RocketRide connections.

## What it does

The node accepts a question on `questions`, runs a LangChain agent using the
connected LLM and any connected tools, then writes the final text to `answers`.
It is also available to a parent agent as a tool. The LLM adapter asks the model
for a JSON envelope that represents either a tool call or a final answer, then
converts it into LangChain's structured message form. Choose this node for that
single-agent LangChain flow; use the CrewAI manager when work must be delegated
to configured specialist subagents.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used by the agent. |
| `tool` | no | Tools available to the agent through control-plane invocation. |

The `llm` connection is required. With no `tool` connection, the agent can
still produce a final answer, but has no pipeline tools to call.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `answers` | Run the agent for each incoming question and emit its final answer. |

During a run, the node sends `thinking` SSE updates for agent startup,
LLM activity, and tool-call activity.

## As a tool

The registered tool name is `<nodeId>.run_agent`, where `<nodeId>` is this
node's pipeline ID; it has no separately configured server-name prefix.

| Function | Description |
| --- | --- |
| `<nodeId>.run_agent` | Run this LangChain agent for a delegated query and return its agent result. |

The input must be an object with required non-empty `query: string` and optional
`context: object`. The node stores supplied context as a
`RocketRide.agent.tool_context.v1` context entry. The call returns
`{content, meta, stack}` to its caller instead of writing to `answers`.
Non-object input, a blank query, or a non-object context raises `ValueError`.
If the LLM does not produce a parsable envelope after three attempts, the
adapter supplies an explanatory final message rather than a tool call.

## Configuration

The only profile is `default`: connect an LLM first, then add tools only when
the agent needs to take actions or retrieve information. Most pipelines can
leave the profile selection alone and set the fields that shape delegation and
answering behavior.

### Agent description

This text is added to the registered `run_agent` tool description when it is
non-empty. Set it when another agent may choose this node, describing the
specialist job and the kinds of requests it should receive; leave it empty when
the node is only driven from its `questions` lane. A concrete description such
as “Summarizes retrieved policy documents” gives a parent a usable routing cue.

### Instructions

Use the instruction list for additional guidance supplied by this node's
configuration. Keep each entry narrowly scoped to the work the agent should do
or the constraints it must honor. Put enduring routing information in **Agent
description** instead, because that is the text exposed to parent agents.

### Require tool call

This option is off by default. Turn it on for a workflow where an answer must
follow at least one real tool invocation, for example a response that must be
grounded in a connected store. Leave it off when the agent can validly answer
without a tool; enabled runs that answer without a tool fail with the declared
guard error.

## Notes

### JSON tool-call protocol

RocketRide's LLM seam is text-based, while the LangChain agent expects
structured tool calls. On each model turn, the adapter requests exactly one
JSON object: `{"type":"tool_call","name":"server.tool","args":{...}}` or
`{"type":"final","content":"..."}`. It retries malformed output twice with
a correction prompt; after the third invalid response it returns an explanatory
AI message. Connected tools receive dynamically built argument schemas from
their declared input schemas, with a generic `input` field as the fallback.

## Upstream docs

- [LangChain documentation](https://docs.langchain.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `agent_description` | `string` | **Agent description**<br/>What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` |
| `agent_langchain.profile` | `string` | **Profile** | `"default"` |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the agent. |  |
| `require_tool_call` | `boolean` | **Require tool call**<br/>Require the agent to invoke at least one tool before answering. When on, a run that answers without calling any tool fails with a guard error. Use for determinism-critical pipelines where an ungrounded or narrated answer must never be delivered. Off by default. | `false` |

## Dependencies

- `langchain`
- `langchain-core`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_langchain)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# LlamaIndex

Route: /nodes/agent_llamaindex

# agent_llamaindex

A RocketRide agent node that answers questions with a LlamaIndex ReAct loop —
reasoning step by step and calling connected tools until it reaches an answer.

## About LlamaIndex

LlamaIndex is an open-source framework for building LLM applications over your
own data. It is best known for its retrieval and indexing toolkit and for
ReAct-style agents, which interleave reasoning with tool use so a model can
gather what it needs before answering.

## What it does

Takes a question on the `questions` lane, reasons about it step by step, calls
whatever tools are connected to it, and emits the final answer on the `answers`
lane. Because the reasoning loop is plain text (the model writes
`Thought / Action / Action Input`), it works with **any** LLM that can follow
the format — native function-calling support is not required, which makes it a
good fit for local or smaller models. It can also be invoked as a tool by a
parent agent, so it works as a specialist inside a larger agent hierarchy.

## Example pipelines

**Answer questions using an HTTP tool**

`chat → agent_llamaindex → response_answers`

<div align="center">

![The agent_llamaindex node on the canvas with an LLM and an HTTP Request tool connected](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

`llm_anthropic` is wired to the `llm` channel and `tool_http_request` to
`tool`. A question arrives on chat, the agent decides when to call the API,
reads the response, and returns a grounded answer.

**Research agent over your own documents**

`chat → agent_llamaindex → response_answers`

Swap the HTTP tool for `store_qdrant`: the agent searches the vector store on
demand rather than every question being forced through retrieval, then answers
from what it found.

**Specialist inside a larger agent**

An `agent_rocketride` node with this node connected on its `tool` channel. Fill
in **Agent description** so the parent knows when to delegate; it calls
`<nodeId>.run_agent` and gets the sub-agent's answer back.

## Connections

| Connection | Required | Description                                             |
| ---------- | -------- | ------------------------------------------------------- |
| `llm`      | yes      | LLM the agent reasons with                              |
| `tool`     | no       | Tools available to the agent during its reasoning loop  |

Without tools the node still works — it becomes a single-shot question
answerer. Tools are what make the ReAct loop worth using.

## Lanes

| Lane in     | Lane out  | Description                                      |
| ----------- | --------- | ------------------------------------------------ |
| `questions` | `answers` | Send a question, receive the agent's final answer |

## As a tool

When connected to a parent agent, the node exposes one function:

| Function             | Description                                        |
| -------------------- | -------------------------------------------------- |
| `<nodeId>.run_agent` | Run this agent on a query and return its answer    |

Input is `{query: string, context?: object}` — `query` must be a non-empty
string. The optional `context` object reaches the sub-agent as a context entry
of type `RocketRide.agent.tool_context.v1`. Output is `{content, meta, stack}`,
where `stack` is the list of reasoning steps taken. When invoked as a tool the
answer returns to the caller instead of going out on the `answers` lane.

The configured **Agent description** is prepended to this function's
description, so it is what a parent agent reads when choosing between
sub-agents.

## Configuration

The default profile needs nothing set — connect an LLM and the node runs. The
three fields shape *how* it behaves: what a parent agent is told about it, what
guidance its prompt carries, and whether ungrounded answers are allowed.

### Agent description

Only matters when this node is connected to a parent agent as a tool. The
parent reads **this text alone** when deciding whether to delegate — it cannot
see the instructions, the tools, or the LLM. Write it specific and
action-oriented: "Searches internal documentation and answers with citations"
gets picked; "helper agent" never does. Leave it blank if nothing calls this
agent as a tool.

### Instructions

Each line is appended to the built-in ReAct prompt, which already handles the
reasoning scaffolding. Use it for domain rules and tone ("prefer primary
sources", "answer in the user's language") — not for restating how to use
tools, which the loop already covers. Adding a great deal here works against
smaller models, whose instruction-following degrades as the prompt grows.

### Require tool call

Off by default. When on, a run that produces an answer without invoking at
least one tool fails with a `RocketRide.agent.guard.v1` error instead of
returning the text.

This guards against a real failure mode: weaker planning models sometimes
**narrate** a tool chain in prose — describing searches they never ran — and
produce a plausible but ungrounded answer. Turn it on for
determinism-critical pipelines where an ungrounded answer must never be
delivered. Note that it counts real tool invocations only; internal local reads
do not satisfy it. Leave it off for agents that can legitimately answer from
the model's own knowledge.

## Notes

### The reasoning loop

The node uses **llama-index-core** for the ReAct scaffolding
(`ReActChatFormatter`, `ReActOutputParser`) but drives the loop itself: each
turn it formats the ReAct prompt, calls the host LLM with `Observation:` as a
stop word, and parses the model's `Thought / Action / Action Input` or final
`Answer`. Tool execution goes through the host's control-plane `call_tool`, not
through LlamaIndex — connected tools are wrapped as metadata-only
`FunctionTool`s whose descriptions carry each tool's input JSON schema.

The loop runs up to **10 iterations**. If no final answer arrives within that
budget the node returns `"Agent stopped after reaching the maximum number of
reasoning steps."` Output that can't be parsed as a ReAct step is treated as a
direct answer (a leading `Thought:` is stripped so scaffolding doesn't leak to
the reader). A tool call that raises isn't fatal — the error is fed back to the
model as the observation (`{tool, error, type}`) so it can recover.

### Progress and traceability

Progress streams over the `thinking` SSE lane ("Starting LlamaIndex agent...",
"Calling &lt;tool&gt;..."), and every tool step (`action`, `action_input`,
`observation`) is recorded in the returned reasoning stack.

## Upstream docs

- [LlamaIndex agents](https://docs.llamaindex.ai/en/stable/understanding/agent/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `agent_description` | `string` | **Agent description**<br/>What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` |
| `agent_llamaindex.profile` | `string` | **Profile** | `"default"` |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the agent. |  |
| `require_tool_call` | `boolean` | **Require tool call**<br/>Require the agent to invoke at least one tool before answering. When on, a run that answers without calling any tool fails with a guard error. Use for determinism-critical pipelines where an ungrounded or narrated answer must never be delivered. Off by default. | `false` |

## Dependencies

- `llama-index-core`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_llamaindex)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# RocketRide Wave

Route: /nodes/agent_rocketride

# agent_rocketride

A RocketRide agent node that plans batches of tool calls as parallel waves and keeps their full results in keyed memory. Pick it when a task benefits from several independent tool calls per planning step and from reusing large intermediate results without repeatedly placing them in the LLM context.

## What it does

Receives questions on the `questions` lane, uses the required LLM, tool, and memory connections to plan a wave of calls, runs that wave, and eventually writes a final answer to `answers`. Each regular tool result is stored in memory while the next planning prompt receives only a structural summary; the agent can retrieve selected values later or substitute stored data into its final answer. Unlike an agent that takes a single tool action per turn, this node can execute one planned batch concurrently, with up to eight calls in a wave.

It can also act as a specialist for a parent agent through its registered `<nodeId>.run_agent` function. The service is marked experimental in its metadata.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used for planning and final-answer synthesis. |
| `tool` | no | Tools the agent may call through the control plane. |
| `memory` | yes | Keyed memory service used to store, retrieve, and clear tool results. |

The node needs both an LLM and a memory connection to run. A `tool` connection is optional, but without one the agent has no connected external tools to call.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `answers` | Run the agent for an incoming question and emit its final answer. |

## As a tool

The node registers one function under its node-id prefix: `<nodeId>.run_agent`.

| Function | Description |
| --- | --- |
| `<nodeId>.run_agent` | Run this Wave agent for a query and return its result to the calling agent. |

The input must be an object with a required, non-empty string `query`; it may also contain a `context` object. Invalid input raises a `ValueError`. When `context` is supplied, the node serializes it into the agent question as a `RocketRide.agent.tool_context.v1` context entry; serialization errors are ignored. The returned value is the agent result, whose advertised shape is `{content, meta, stack}`. The configured **Agent description**, when non-empty, is prepended to the registered function description that a parent agent sees.

## Configuration

The sole `default` profile supplies the baseline settings. Most uses need an LLM and memory connected first; then use the fields below to describe the specialist, guide its planning, bound the number of planning waves, and decide whether an answer must include a real tool invocation.

### Agent description

This text is included in the registered `run_agent` description only when the node is used as a tool. Set it to a concise account of the specialist's purpose and capabilities when a parent agent must choose whether to delegate to it. Leave it blank when the node is only driven through its `questions` lane or when no additional delegation cue is useful.

### Instructions

Instructions are inserted as separate planning-prompt instruction blocks on every wave. Use them for durable task rules or response guidance that should apply to all iterations; they accompany the system's built-in tool, memory, response-format, and behavioural instructions. Keep them focused because they are part of every LLM planning request.

### Max Waves

This integer is the maximum number of planning iterations before the node switches to a best-effort synthesis pass. The default is `10`, with allowed values from `1` to `50`. Lower it when predictable latency or tool usage matters more than continued exploration; raise it only for tasks that genuinely need several plan-and-execute rounds. A malformed empty plan also ends the loop early and uses synthesis rather than consuming additional waves.

### Require tool call

Off by default, this guard requires the run to invoke at least one real tool before returning an answer. Enable it for workflows where an answer based only on model reasoning is unacceptable. Internal reads such as `memory.peek` do not use the connected tool pipeline and therefore should not be treated as satisfying this guard; leave the guard off for questions the agent may answer without external tool use.

## Notes

### Wave execution and failure handling

The LLM returns either a final answer or a list of `{tool, args}` calls. Regular calls in that list run concurrently, capped at eight worker threads. A tool failure becomes an error result for the next planning step rather than aborting the whole run. If the wave limit is reached, or a response contains neither `done` nor any tool calls, the node makes a final LLM synthesis request from the accumulated result summaries.

The executor defines a 120-second per-call timeout constant, but its submitted futures are not awaited with that timeout in this implementation. Do not rely on that constant to terminate a slow tool call.

### Memory references

Results are stored under keys such as `wave-0.r0`, and only their structure is carried forward in the planning prompt. The internal `memory.peek` utility can read a key, apply a JMESPath path, or page through serialized data; JMESPath array previews are capped at 50 items and raw reads default to 8,000 characters. Final answers and later tool arguments may use `{{memory.ref:key}}`, optionally followed by a format and JMESPath path. Built-in formats are `markdown_table`, `html_table`, `csv`, `json`, and `text`; an unrecognized format asks the LLM to render the value instead.

## Upstream docs

- [RocketRide documentation](https://docs.rocketride.org)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `agent_description` | `string` | **Agent description**<br/>What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` |
| `agent_rocketride.profile` | `string` | **Profile** | `"default"` |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the agent's planning and responses. |  |
| `max_waves` | `integer` | **Max Waves**<br/>Maximum number of planning iterations before the synthesis fallback fires. | `10` |
| `require_tool_call` | `boolean` | **Require tool call**<br/>Require the agent to invoke at least one tool before answering. When on, a run that answers without calling any tool fails with a guard error. Use for determinism-critical pipelines where an ungrounded or narrated answer must never be delivered. Off by default. | `false` |

## Dependencies

- `jmespath`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_rocketride)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Anomaly Detector

Route: /nodes/anomaly_detector

# anomaly_detector

A RocketRide filter node that monitors numeric text or document metadata and
marks statistically unusual values. Pick it when a pipeline needs a rolling,
per-run check for outliers rather than a fixed rule for every value.

## What it does

The node accepts `text` and `documents` lanes and returns data on the matching
lane. Text is inspected for one numeric value; documents are copied and
enriched with anomaly metadata based on the configured metadata field. Use it
for changing measurements whose usual range must be learned from recent data,
instead of a rule-based validation node that compares each item against a
known limit.

The detector is created once per pipeline execution and shares one
thread-safe, fixed-size history across its instances. Each value is evaluated
against the existing history and only then added to it, so the history is
discarded when the run ends. This node is experimental.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `text` | Inspect a numeric value in text; anomalous values receive a suffix. |
| `documents` | `documents` | Inspect the configured metadata metric and add detection metadata. |

## Profiles

Default: **Z-Score - Standard deviation based detection** (`z_score`).

| Profile | Method | Default window | Warning / critical threshold |
| --- | --- | --- | --- |
| `z_score` **(default)** | Z-Score | 100 | 2.0 / 3.0 |
| `iqr` | Interquartile range | 100 | 1.5 / 3.0 |
| `rolling_avg` | Rolling Average - Moving average deviation detection | 50 | 2.0 / 3.0 |

## Configuration

Start with the profile whose kind of change you need to detect, then point
**Metric field** at the numeric document-metadata key to monitor. The defaults
are conservative starting points; every method needs a warm-up period before
it can identify an outlier.

### Detection method and sensitivity

Choose `z_score` when distance in standard deviations is meaningful, `iqr`
when you want quartile-based outlier bounds, or `rolling_avg` when percentage
change from recent values is more useful. `sensitivity` controls the IQR bounds
and normalizes the rolling-average score; lowering it makes both methods flag
smaller deviations. It has no effect on Z-Score, whose score is calculated
from the window standard deviation.

### Window size

**Window size** retains 10 to 10,000 recent values, with 100 by default. Use a
larger window for a stable long-term baseline and a smaller one when the normal
level changes quickly. Z-Score and Rolling Average need at least two existing
values; IQR needs four. Before that, a value is returned as `normal` with
`insufficient data`, so a very large window does not delay the minimum
warm-up but does make the baseline slower to adapt.

### Metric field

For documents, set **Metric field** to the metadata key containing the number;
the default is `value`. A missing or non-numeric key does not stop the
pipeline: the copied document is marked normal and receives an explanatory
`anomaly_details` value. Text input first attempts to parse all of the text,
then uses its first integer, decimal, or scientific-notation token; text with
no number passes through unchanged.

### Warning and critical thresholds

The detector labels a score at or above **Critical threshold** as `critical`,
then a score at or above **Warning threshold** as `warning`; lower scores are
`normal`. Raise these values to reduce alerts and lower them to surface more
borderline changes. With the default rolling-average settings, warning begins
at a 40% deviation and critical at 60%; changing sensitivity changes those
effective percentages as well.

## Notes

### Output details

For anomalous text, the node appends a suffix such as
`[ANOMALY: critical score=3.4119]`; normal text remains unchanged. Documents
receive `anomaly_score`, `anomaly_severity`, `anomaly_is_anomalous`, and
`anomaly_details` metadata. Non-finite numeric input is treated as normal and
is not added to the history.

### Method edge cases

Z-Score produces a normal result when the history has zero variance, IQR does
the same when the interquartile range is zero, and Rolling Average does so when
its local mean is zero. IQR marks any value outside its sensitivity-based
bounds as anomalous even if its resulting score remains below the configured
warning threshold; its severity still uses the warning and critical thresholds.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `anomaly_detector.criticalThreshold` | `number` | **Critical threshold**<br/>Threshold multiplier for critical-level anomalies | `3` |
| `anomaly_detector.method` | `string` | **Detection method**<br/>Statistical method used for anomaly detection | `"z_score"` |
| `anomaly_detector.metric` | `string` | **Metric field**<br/>The metadata field name containing the numeric value to monitor | `"value"` |
| `anomaly_detector.profile` | `string` | **Detection Method**<br/>Anomaly detection configuration | `"z_score"` |
| `anomaly_detector.sensitivity` | `number` | **Sensitivity**<br/>Detection sensitivity threshold (lower = more sensitive) | `2` |
| `anomaly_detector.warningThreshold` | `number` | **Warning threshold**<br/>Threshold multiplier for warning-level anomalies | `2` |
| `anomaly_detector.windowSize` | `integer` | **Window size**<br/>Number of recent values to consider for statistical calculations | `100` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/anomaly_detector)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Anonymize

Route: /nodes/anonymize

# anonymize

A RocketRide text filter that detects configured entity types and replaces their
spans before text continues downstream. Pick it to redact PII-like content
while preserving the rest of the document, rather than dropping the document
or relying on a fixed pattern matcher alone.

## About GLiNER

GLiNER is the named-entity recognizer used by this node through RocketRide's
GLiNER model adapter. The recognizer receives a list of labels, returns entity
spans, and is used here to replace those spans in pipeline text. This node can
also combine those detections with spans and labels supplied by an upstream
classification stage.

## What it does

The node accumulates text for an input object, detects entities when that
object closes, and writes the redacted text to the `text` lane. Without
classification input it detects the configured entity types; with
classification input it also uses its reported character spans and associated
rule labels. Choose it over an exact-match redaction step when the data needs
entity detection over configurable labels or integration with classifier
results.

In mask mode each detected span is replaced with the configured character for
the original span length. Token mode replaces it with a label such as
`[EMAIL]`; a classifier-only match becomes `[REDACTED]` unless an overlapping
GLiNER match supplies a more specific label.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `text` | Collect text for an object, redact detected spans at closing, and emit it. |

## Profiles

Default: **GLiNER Small - Lightweight general-purpose model** (`glinerSmall`).

| Profile | Model |
| --- | --- |
| `glinerMultiPII` | `urchade/gliner_multi_pii-v1` |
| `glinerPIILarge` | `knowledgator/gliner-pii-large-v1.0` |
| `glinerMergedLarge` | `xomad/gliner-model-merge-large-v1.0` |
| `glinerSmall` **(default)** | `urchade/gliner_small-v2.1` |
| `glinerMedium` | `urchade/gliner_medium-v2.1` |
| `glinerLarge` | `urchade/gliner_large-v2.1` |
| `glinerMulti` | `urchade/gliner_multi` |
| `gretelSmall` | `gretelai/gretel-gliner-bi-small-v1.0` |
| `gretelLarge` | `gretelai/gretel-gliner-bi-large-v1.0` |
| `glinerKo` | `taeminlee/gliner_ko` |
| `glinerIt` | `DeepMount00/GLiNER_PII_ITA` |
| `glinerAr` | `NAMAA-Space/gliner_arabic-v2.1` |
| `glinerCommunitySmall` | `gliner-community/gliner_small-v2.5` |
| `glinerCommunityMedium` | `gliner-community/gliner_medium-v2.5` |
| `glinerCommunityLarge` | `gliner-community/gliner_large-v2.5` |
| `glinerBiomedSmall` | `Ihor/gliner-biomed-small-v1.0` |
| `glinerBiomedLarge` | `Ihor/gliner-biomed-large-v1.0` |
| `custom` | _(your own GLiNER-compatible model)_ |

## Configuration

Choose a profile when one of the supplied model choices suits the text you
process, or choose `custom` and supply a model name. Most pipelines then only
need to tailor the entity labels and decide whether retaining entity labels in
the output is useful. The profile selected when adding the node is
`glinerSmall`; the configuration field itself defaults to `glinerMergedLarge`.

### Model

Profiles supply a model name, while the `custom` profile exposes **Model name**
for a name at least two characters long. Change models when the supplied
profile's intended language, domain, or resource trade-off is a closer match
for the data. The recognizer loads the configured model through the RocketRide
GLiNER adapter, which uses a model server when one is configured and otherwise
runs locally.

### Entity types to anonymize

**Entity types to anonymize** is a list of zero-shot labels. Its default has
15 common PII-style labels, including `person`, `email`, `phone number`, and
`credit card number`. Replace or extend this list for the kinds of entities
your pipeline must hide. Blank and non-string list items are ignored; a
non-list or an empty resulting list falls back to the default labels, so an
attempt to clear the list does not silently disable detection.

### Redaction style and character

Use `mask` (the default) when it is important to preserve the original text
length: each matched character is overwritten by **Character to use for
anonymization**, which defaults to `█`. Use `token` when downstream processing
needs to know what was removed; it substitutes label tokens instead and does
not use the masking character. Adjacent mask spans merge into one replacement;
token spans remain separate unless they actually overlap.

## Requirements

The node declares GPU capability and installs GLiNER plus an ONNX Runtime.
Outside macOS its requirements select `onnxruntime-gpu`; on macOS they select
the non-GPU `onnxruntime` package. Model loading is therefore a runtime cost to
plan for, especially before selecting a larger profile.

## Notes

### Long text and prediction failures

Text is processed in 1,024-character chunks with 128-character overlap, label
lists are sent in batches of 32, and up to four chunks run concurrently.
Duplicate entities from overlapping chunks are removed. A model error for one
label batch or chunk is logged and processing continues, so review redaction
results when complete coverage is required.

### Classifier input

When classification data arrives, the node uses three independent inputs.
`classificationPolicy` `idRef` values become GLiNER labels only when the local
Nucleuz `rulePack.dat` maps them; if the rule pack is unavailable, those labels
are omitted. `<Term>` values from `classificationRules` remain GLiNER labels
without the rule pack. Classifier-reported `textMatches` are redacted directly,
independent of both label sources. If neither source produces labels, GLiNER
adds no classification-derived detections, but the reported text matches are
still redacted.

## Upstream docs

- [GLiNER documentation](https://github.com/urchade/GLiNER)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `anonymize.model` | `string` | **Model name**<br/>Gliner model to use for anonymization |  |
| `anonymize.profile` | `string` | **Model**<br/>Anonymize model | `"glinerMergedLarge"` |
| `anonymizeChar` | `string` | **Character to use for anonymization**<br/>Character |  |
| `entityTypes` | `array` | **Entity types to anonymize**<br/>PII / entity types to detect and mask. Pre-filled with common types; remove any you don't want, or add your own (the model is zero-shot, so any label works). | `["person","name","email","phone number","address","social security number","credit card number","date of birth","organization","company","location","ip address","bank account","passport number","driver license"]` |
| `redactionStyle` | `string` | **Redaction style**<br/>How detected entities are replaced. 'mask' overwrites each entity with the anonymization character (████). 'token' replaces each entity with a labelled tag like [PERSON] or [EMAIL]. | `"mask"` |

## Dependencies

- `gliner`
- `onnxruntime-gpu` `==1.22.0; platform_system != 'Darwin'`
- `onnxruntime` `==1.22.0; platform_system == 'Darwin'`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/anonymize)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Answers to Documents

Route: /nodes/answer_documents

# answer_documents

A RocketRide adapter node that turns answers into embeddable documents while
preserving the answers lane. Pick it after a model or agent when its answers
need to be indexed for later retrieval rather than only sent to a response.

## What it does

The node reads `answers` and emits one or more documents on `documents`; the
original answer continues on `answers`. A JSON array produces one document for
each item, while a JSON object or non-empty plain-text answer produces one
document. Use it to bridge an answer-producing node to an embedding and store
pipeline, particularly when each item in a structured answer should be
retrievable independently.

Documents are made only when a downstream listener consumes `documents`. Empty
or whitespace text and JSON `null` produce no documents, while a malformed
JSON answer falls back to its non-empty text representation.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `answers` | `documents` | Emit one document for each answer item when a downstream listener needs documents. |
| `answers` | `answers` | Keep the original answer available to downstream answer consumers. |

## Configuration

This node has no configuration fields. Wire an answer-producing node into
`answers`, connect `documents` to an embedding or storage path when indexing is
needed, and retain the `answers` path when the same result must still be served
in the current run.

## Notes

### Document content and metadata

String items in a JSON array become `page_content` verbatim; object and other
non-string items are JSON-serialized with non-ASCII characters preserved. Each
emitted document has a `chunkId` that starts at zero for each input object, and
is marked as non-table, active text content. Its remaining provenance metadata
is populated from the pipeline context.

### Fan-out behavior

The node writes documents only if a `documents` listener exists. It does not
call a replacement writer for the `answers` lane, so the engine's normal answer
forwarding keeps the exact original answer for downstream consumers.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/answer_documents)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Aparavi AQL

Route: /nodes/aparavi_aql

# aparavi_aql

A RocketRide tool node that lets an agent retrieve Aparavi STORE metadata by
asking questions in plain English. Pick it when the data is governed by an
Aparavi server rather than stored in one of RocketRide's managed databases.

## About Aparavi

Aparavi is a data governance platform whose server exposes a query API over
metadata in its STORE table. This node uses Aparavi Query Language (AQL), an
SQL-like language, to retrieve those rows without requiring the calling agent
to construct the query itself.

## What it does

The node is a pure tool node: it has no pipeline lanes. Its required LLM turns
a natural-language request into a SELECT-only AQL query over the fixed STORE
schema, then the node sends that query to the configured Aparavi server. Pick
it over rocketride_sql when the authoritative data is Aparavi file metadata;
use the SQL node for the managed relational tenant database.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| llm | yes | Generates AQL from natural-language questions. |

## As a tool

The functions are registered under the bare names below; this node defines no
configurable server-name prefix. question arguments must be non-empty strings
in a JSON object.

| Function | Description |
| --- | --- |
| get_data | Generates safe AQL for required question, executes it, and returns STORE rows. |
| get_aql | Generates AQL for required question without executing it. |
| get_schema | Returns the fixed STORE table schema; use only after retrieval fails or is unexpected. |

get_data returns {rows, aql, count} when successful. If the client was not
initialized, a generated query is unsafe, generation never succeeds, or all
execution retries fail, it returns {error, aql, rows: []}. Invalid tool input
raises ValueError. The node tries generation and execution up to three times;
after an API error, the next LLM attempt receives the failed AQL and error.

get_aql returns {aql} and does not run the safety check or contact the API;
invalid input or an LLM failure raises. get_schema accepts an empty object and
returns {store: "STORE", columns: [...]}, where each column has a name, type,
and description.

## Configuration

The single built-in profile has no endpoint defaults. Supply the Aparavi server
connection, then describe the data in terms that help the required LLM select
the correct fixed STORE fields. Query retry count and result limit are fixed in
the implementation rather than configurable fields.

### Aparavi Server URL

Provide the base URL of the Aparavi server, including its scheme, for example
https://aparavi.example.com. The node removes a trailing slash before adding
its database-query path. Change this value when the target Aparavi deployment
changes; an empty or unreachable URL leaves the tool client uninitialized or
causes its HTTP calls to return errors after a 30-second timeout.

### Username and password

Username and Password are sent as HTTP Basic Auth on every Aparavi
database-query request. Set them to credentials accepted by the configured
server. Change both together when switching servers or users; a mismatched
endpoint and credentials becomes an API HTTP or connection error returned by
get_data after its retry loop.

### Data description

Data description is empty by default and is added as context to the LLM that
writes AQL. Describe the collection's purpose, vocabulary, and useful metadata
conventions when they are not evident from the fixed schema. This can improve
query selection without giving the model a new table: STORE remains the only
table in the generated-query prompt.

## Authentication

The node uses HTTP Basic Auth with the configured username and password for
the Aparavi database-query API. It sends POST requests to
/server/api/v3/database/query and does not use a separate token field.

## Limitations

This node runs on the RocketRide engine host and does not support remote
execution. The engine host must be able to reach the configured Aparavi server
using the supplied Basic Auth credentials. It only retrieves from the fixed
STORE schema: the safety check permits one SELECT statement, rejects embedded
multi-statement input, and blocks mutation and execution keywords before
sending AQL to the server. The API request uses a fixed 250-object limit and a
30-second timeout.

## Notes

### Query generation and result normalization

The LLM prompt supplies the fixed STORE schema, AQL syntax rules, and examples.
It asks for LIMIT 250 unless the question specifies another limit, while the
HTTP client itself requests at most 250 objects. Accidental Markdown fences in
the LLM output are removed. Timestamp values above 10,000,000,000 in the known
Aparavi date fields are treated as milliseconds and normalized to seconds in
returned rows.

## Upstream docs

- [Aparavi Data Suite documentation](https://aparavi.com/docs/data-suite/reports/create-a-new-report/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `aparavi.db_description` | `string` | **Data description**<br/>What is this data used for? Describe its content and purpose, this helps the LLM generate more accurate AQL queries. | `""` |
| `aparavi.password` | `string` | **Password**<br/>Aparavi login password |  |
| `aparavi.profile` | `string` |  | `"default"` |
| `aparavi.url` | `string` | **Aparavi Server URL**<br/>Base URL of the Aparavi server, e.g. https://aparavi.example.com | `""` |
| `aparavi.user` | `string` | **Username**<br/>Aparavi login username | `""` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/aparavi_aql)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Player

Route: /nodes/audio_player

# audio_player

A RocketRide audio sink that plays incoming audio or a video's audio track
through the system output device.

## What it does

The node passes incoming `audio` and `video` streams to a PCM player and has no
downstream lane. Choose it when a local pipeline needs to play a stream rather
than transform it, transcribe it, or generate speech. It serializes playback
across node instances with one shared lock.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `audio` | — | Pass the audio stream to the player. |
| `video` | — | Extract and play the video's audio track. |

## Configuration

This node exposes no configuration fields. It has one empty `default` profile;
playback behavior is fixed by the implementation.

## Limitations

The `nosaas` capability means this node is excluded from SaaS deployments. It
opens an output stream through `sounddevice`, so it is intended for a runtime
that can access an audio output device.

## Notes

### Fixed playback format and buffering

The player is configured for 44,100 Hz, two-channel, signed 16-bit PCM output
with a low-latency stream and 1,024-frame callback blocks. It accumulates input
into 16 KiB chunks and enqueues at most 32 chunks; a full queue blocks incoming
writes, providing natural backpressure that prevents unbounded memory growth.

At end of stream, whatever is left in the accumulator — a partial chunk, or the
whole stream when it is shorter than 16 KiB — is queued ahead of the
end-of-stream marker, so short streams and stream tails are never discarded.

On stop, the node polls until the queue and the internal playback buffer are
both fully drained before closing the stream, so buffered audio plays to
completion. The final callback always fills its output buffer as required by
`sounddevice`: a partial block is played in full and padded with silence, while
an exact-boundary end writes silence before stopping. The callback stops
immediately after committing that terminal block.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Dependencies

- `imageio_ffmpeg`
- `sounddevice` `>=0.5`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/audio_player)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Transcribe

Route: /nodes/audio_transcribe

# audio_transcribe

A RocketRide audio node that transcribes incoming audio or video streams into
text with the configured Whisper backend.

## About Whisper

Whisper is the transcription backend constructed by this node. The node uses
it to turn buffered PCM audio into timestamped text segments.

## What it does

The node accepts `audio` or `video`, extracts the audio track as 16 kHz mono
PCM, buffers it in chunks of `chunk_duration` seconds (default 60), and
transcribes each chunk with Whisper using built-in Silero voice-activity
detection. Consecutive segments are merged until one ends in terminal
punctuation (`.`, `?`, `!`), so the `text` lane carries whole sentences, each
stamped with the timestamp of its first segment. Pick it when a pipeline
needs spoken content as text, rather than local playback or speech synthesis.
Transcription runs through `ai.common.models.Whisper`: it routes to the model
server when the engine is started with `--modelserver`, otherwise it runs
locally via `faster-whisper`; no API key is required either way. When a
`documents` listener is attached, it also writes one document per merged
sentence; the declared lanes remain the `text` outputs below.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `audio` | `text` | Transcribe the audio stream into merged text sentences. |
| `video` | `text` | Transcribe audio decoded from the video stream into merged text sentences. |

## Profiles

Default: **Default (Base)** (`default`), an alias for the `base` model.

| Profile | Model | Context |
| --- | --- | --- |
| `default` **(default)** | `base` | Alias for the base model. |
| `tiny` | `tiny` | Fastest, least accurate. |
| `base` | `base` | Fast, low accuracy. |
| `small` | `small` | Medium speed and accuracy. |
| `medium` | `medium` | Slower, high accuracy. |
| `large-v3` | `large-v3` | Slowest, highest accuracy. |

Each profile owns a full copy of the configuration fields below, stored under
its own key, so editing `beam_size` on `medium` leaves `tiny`'s settings
untouched. A config with no `profile` key keeps working: it resolves against
`default`, whether its values sit at the top level or inside a
`"default": { … }` object.

## Configuration

Pick a profile with the **Model Profile** selector; only the model and
`language: en` differ between profiles, and everything else comes from the
field defaults, which reproduce the behavior this node had before the
decoding and VAD fields were exposed. Most users only need the profile and
`language`. Models are downloaded from HuggingFace on first use, and the GPU
is used automatically when available.

### Model

Declared once per profile and defaulted to that profile's own model;
setting it overrides the profile's choice. It is deliberately not a single
shared field: a shared field defaulted to `base` would be written into the
selected profile's object on the first save and win the merge — silently
downgrading `medium` to `base` with nothing logged.

### Language

ISO 639-1 code of the spoken language (default `en`). It must match the
audio; a mismatch produces garbled, half-translated text.

### Compute Type

CTranslate2 weight precision for the loaded model: `float16` (default),
`int8`, `int8_float16`, or `float32`. `float16` needs a GPU; CTranslate2
downgrades it to `int8` on CPU.

### Chunk Duration

Seconds of audio to buffer before sending a chunk to Whisper (default 60).
Longer chunks give Whisper more context per call; shorter chunks reduce
latency to the first transcript.

### Beam Size

Beam size for decoding (default 5). `1` is greedy and fastest; higher values
are slower and usually more accurate.

### VAD fields

`vad_filter` (default true) uses Whisper's built-in Silero VAD to drop
non-speech before transcribing. The other four map onto faster-whisper's
`VadOptions`: `vad_threshold` (default 0.5, Silero speech probability above
which audio counts as speech), `vad_min_silence_duration_ms` (default 500,
silence this long ends a speech chunk), `vad_speech_pad_ms` (default 400,
padding added to each side of a detected speech chunk), and
`vad_max_speech_duration_s` (default 0, split speech chunks longer than
this). They are merged over the node's defaults rather than replacing them,
so setting one leaves the others alone. `vad_threshold` and
`vad_speech_pad_ms` accept `0` as a real value; only
`vad_max_speech_duration_s` treats `0` specially, as "no limit".

## Notes

### Segmentation and documents

Transcription calls are serialized through a global lock so a single loaded
model is shared safely across instances. The transcriber combines
consecutive segments until one ends in `.`, `?`, or `!`, then writes that
text with the timestamp of its first segment. For document output, each
document carries `chunkId` (sequential per stream, reset on each new stream)
and `time_stamp` (seconds from stream start) in its metadata, plus
`metadata.source` (the source audio's media detail — `source_mime`,
`duration`, `sample_rate`, …) and `metadata.name` =
`<audio-stem>.segment<N>.txt` when the input carried a stream descriptor.

### Removed fields

`silence_threshold`, `min_seconds`, `max_seconds` and `vad_level` were
declared but read by nothing, and are gone as of #1809. They predate the
move to faster-whisper's built-in Silero VAD: `vad_level` (webrtcvad 0-3
aggressiveness) is replaced by `vad_threshold` (Silero 0-1 speech
probability), `silence_threshold` (seconds) by
`vad_min_silence_duration_ms`, and `min_seconds`/`max_seconds` by
`chunk_duration`, which is actually wired up. Configs that still carry the
old keys keep working: nothing validates node config keys, so the unknown
values are ignored. There is no automatic translation to the replacements,
since that would change transcripts for anyone who had set them.

### Profile history

Two fixed bugs explain the current design. Before #1809 the profiles set
`mode`, but the node reads `model` — so every profile silently loaded
`base`, whichever one you picked. Before #2067 the profile selector was
hidden and listed only `default`, so five of the six profiles were
unreachable from the UI.

## Upstream docs

- [Whisper repository](https://github.com/openai/whisper)
- [faster-whisper repository](https://github.com/SYSTRAN/faster-whisper)


<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `transcribe.base.model` | `string` | **Model**<br/>The Whisper model to use for transcription. Defaults to the model this profile selects | `"base"` |
| `transcribe.beam_size` | `number` | **Beam Size**<br/>Beam size for decoding. 1 is greedy (fastest); higher is slower and usually more accurate | `5` |
| `transcribe.chunk_duration` | `number` | **Chunk Duration (s)**<br/>Seconds of audio to buffer before sending a chunk to Whisper | `60` |
| `transcribe.compute_type` | `string` | **Compute Type**<br/>CTranslate2 weight precision. float16 needs a GPU and falls back to int8 on CPU; float32 is the most precise and the slowest | `"float16"` |
| `transcribe.default.model` | `string` | **Model**<br/>The Whisper model to use for transcription. Defaults to the model this profile selects | `"base"` |
| `transcribe.language` | `string` | **Language**<br/>ISO 639-1 code of the spoken language (e.g. en, ru, de). Must match the audio; a mismatch produces garbled half-translated text | `"en"` |
| `transcribe.large-v3.model` | `string` | **Model**<br/>The Whisper model to use for transcription. Defaults to the model this profile selects | `"large-v3"` |
| `transcribe.medium.model` | `string` | **Model**<br/>The Whisper model to use for transcription. Defaults to the model this profile selects | `"medium"` |
| `transcribe.profile` | `string` | **Model Profile**<br/>Whisper model preset. Each profile keeps its own copy of the settings below, so switching profiles does not disturb another profile's overrides | `"default"` |
| `transcribe.small.model` | `string` | **Model**<br/>The Whisper model to use for transcription. Defaults to the model this profile selects | `"small"` |
| `transcribe.tiny.model` | `string` | **Model**<br/>The Whisper model to use for transcription. Defaults to the model this profile selects | `"tiny"` |
| `transcribe.vad_filter` | `boolean` | **VAD Filter**<br/>Use Whisper's built-in Silero VAD to drop non-speech before transcribing | `true` |
| `transcribe.vad_max_speech_duration_s` | `number` | **VAD Maximum Speech (s)**<br/>Split speech chunks longer than this. 0 means no limit | `0` |
| `transcribe.vad_min_silence_duration_ms` | `number` | **VAD Minimum Silence (ms)**<br/>Silence this long ends a speech chunk | `500` |
| `transcribe.vad_speech_pad_ms` | `number` | **VAD Speech Padding (ms)**<br/>Padding added to each side of a detected speech chunk | `400` |
| `transcribe.vad_threshold` | `number` | **VAD Speech Threshold**<br/>Silero speech probability above which audio counts as speech (0-1) | `0.5` |

## Dependencies

- `faster-whisper`
- `ctranslate2`
- `av`
- `tokenizers`
- `huggingface-hub`
- `tqdm`
- `onnxruntime-gpu` `==1.22.0; platform_system != 'Darwin'`
- `onnxruntime` `==1.22.0; platform_system == 'Darwin'`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/audio_transcribe)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Text To Speech

Route: /nodes/audio_tts

# audio_tts

A RocketRide audio node that turns incoming text, documents, questions, or
answers into a WAV audio stream through Kokoro.

## About Kokoro

Kokoro is the text-to-speech backend used by this node. The node can construct
its pipeline locally or ask a configured model server to load the Kokoro
backend.

## What it does

The node synthesizes non-empty text and streams a `audio/wav` file on its
`audio` lane. Choose it when a pipeline needs to make text audible rather than
play already-produced media or turn speech into text. It extracts text from
the four supported input lanes, so it can speak data already moving through a
pipeline without an agent-tool interface.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `audio` | Synthesize the supplied text. |
| `documents` | `audio` | Join eligible document `page_content` values with newlines, then synthesize it. |
| `questions` | `audio` | Join question text with spaces, then synthesize it. |
| `answers` | `audio` | Synthesize the answer text. |

## Configuration

Choose the single `kokoro` profile and its voice. Most users only need to
choose a voice appropriate for their text; the profile selector does not offer
an alternative backend.

### Voice

The voice is required at startup; a blank value raises `Kokoro: choose a voice
from the list`. Its first character is passed to the local or remote Kokoro
pipeline as the language code, so select a voice with the appropriate prefix
for the language you need. The default `af_heart` starts with `a`; change it
when the desired voice or its language-code prefix differs.

## Notes

### Local and model-server execution

When a model-server address is configured, the node connects a `ModelClient`,
loads the `kokoro` loader there, and writes the returned base64 WAV data to a
temporary file. Without one, it installs the local requirements, ensures the
`en_core_web_sm` spaCy model is present when spaCy is importable, and creates a
local `KPipeline`. Both paths synthesize at speed 1; the local path writes
mono, 16-bit, 24 kHz WAV output.

### Input and cleanup behavior

Whitespace-only input produces no audio. Document input excludes documents of
type `Image`, `Audio`, and `Video`; the remaining page content is joined with
newlines. A temporary WAV file is removed after streaming and is also removed
if synthesis raises an exception.

## Upstream docs

- [Kokoro repository](https://github.com/hexgrad/kokoro)


<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `audio_tts.kokoro_voice` | `string` | **Voice**<br/>Kokoro voice. The language is derived automatically from the voice prefix (af_/am_ → American, bf_/bm_ → British, ef_/em_ → Spanish, etc.). | `"af_heart"` |
| `audio_tts.profile` | `string` | **TTS profile** | `"kokoro"` |

## Dependencies

- `numpy`
- `--only-binary` `docopt`
- `--only-binary` `num2words`
- `kokoro` `>=0.9.4`
- `soundfile` `>=0.13.1`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/audio_tts)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Authoritative Overlay

Route: /nodes/authoritative_overlay

# authoritative_overlay

The `authoritative_overlay` node is a pipeline filter that cross-checks extracted financial numbers against the live US SEC EDGAR company-concept API for a configured CIK. It forwards an answer only when it matches an official value for the requested filing period. Part of the **Audit-grade financial extraction node suite**.

## What it does

- **Input**: Pipeline `answers` (or `text` containing a JSON payload).
- **Process**: The node queries `https://data.sec.gov/api/xbrl/companyconcept/CIK{cik}/us-gaap/{concept}.json` and compares the extracted number against measurements that match the requested filing period.
- **Output**:
  - If the extracted number matches an official value **for that period**, the answer is forwarded downstream (once).
  - If there is a mismatch, missing period, failed lookup, or unrecognized regulator, the node **abstains** by dropping the answer and logging a warning.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `text` | `answers` | A JSON payload arriving as text is parsed, cross-checked against EDGAR, and forwarded on `answers` when it matches. |
| `answers` | `answers` | An upstream `answers` payload is cross-checked against EDGAR and re-forwarded on `answers` when it matches. |

## Configuration

See `services.json` for node configuration schemas.

The live `services.json` test block hits `data.sec.gov` and is excluded from the default `builder nodes:test` run (opt in with `ROCKETRIDE_INCLUDE_SKIP=authoritative_overlay`). Unit tests under `nodes/test/authoritative_overlay/` mock the API and do not require the network.

## Notes

### Supported regulators

Currently supported regulators:
- US SEC (EDGAR)

### Period-scoped matching

A match is **not** "this number appears somewhere in the company's filing history." The answer payload must include at least one of `form`, `fy`, `fp`, `end`, `unit`, or `frame`. All provided filters are applied together. Typical payload:

```json
{
  "concept": "AccountsPayableCurrent",
  "value": "$69,860,000,000",
  "form": "10-K",
  "fy": 2025
}
```

Without a period the node abstains. A value that is correct for a 2010 10-K will not verify a 2025 extraction.

> [!NOTE]
> **Strict Matching**: The node uses exact matching (`math.isclose` with `rel_tol=1e-9`). This ensures that only exact financial figures are passed through. Filings restated to the nearest thousand will not match a value extracted to the unit.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `authoritative_overlay.cik` | `string` | **Company CIK**<br/>The SEC Central Index Key for the company. | `"320193"` |
| `authoritative_overlay.profile` | `string` | **Profile**<br/>Overlay profile | `"basic"` |
| `authoritative_overlay.regulator_type` | `string` | **Regulator Source**<br/>Which regulator database to cross-check against | `"sec"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/authoritative_overlay)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Parse/Process/Embed

Route: /nodes/autopipe

# autopipe

An internal RocketRide meta-node ("Parse/Process/Embed") that assembles the document parse, preprocess, embed, and store filter stack at pipeline build time.

## What it does

This is an internal node: it is wired automatically by the pipeline engine, and most users will not add it manually.

Rather than processing data itself, autopipe inspects the task configuration during `beginGlobal` and inserts the appropriate filter nodes (parser, OCR, indexer, preprocessor, embedding, vector store) into the pipeline. Which filters get inserted depends on the engine's current operation mode (`CONFIG`, `SOURCE_INDEX`, `INDEX`, `INSTANCE`, or `TRANSFORM`) and on which sub-configurations are present.

The node registers as a `filter` with class type `other` and capability `internal`. It defines no lanes of its own; all data flows through the filters it inserts.

---

### Filter assembly

| Mode | Filters inserted |
| ---- | ---------------- |
| `INDEX` | vector store _(if `store` configured)_ → indexer |
| `INSTANCE` | parse → _(OCR if enabled)_ → _(indexer if enabled)_ → _(preprocessor)_ → _(embedding)_ → _(store)_ |
| `TRANSFORM` | parse → _(OCR if enabled)_ → _(preprocessor)_ → _(embedding)_ → _(store)_ |
| `CONFIG`, `SOURCE_INDEX` | nothing |

Filter instances are inserted with fixed ids: `parse_1`, `ocr_1`, `indexer_1`, `preprocessor_1`, `embedding_1`, `vector_1`.

The OCR and indexer toggles are not autopipe config fields. They are read from the `include` entries of the task configuration (`service` section for instance tasks, `source` section for transform tasks). A filter is enabled when any include entry sets the corresponding key (`ocr` or `index`) to true. The indexer is never inserted for transform tasks.

Where autopipe reads its own configuration also depends on the mode: for `INSTANCE` and `INDEX` tasks it comes from the `autopipe` key of the task configuration; for `TRANSFORM` tasks it comes from the `autopipe` key of the service config `parameters`.

---

## Configuration

Each field is a multi-provider sub-configuration (`provider` key plus a provider-named config block). The pipe shape exposes `remote`, `embedding`, and `store`; the transform shape exposes only `remote` and `embedding`.

| Field | Default | Description |
| ----- | ------- | ----------- |
| `remote` | `remote` provider, `local` profile | Remote processing target (see note below) |
| `preprocessor` | `preprocessor_langchain`, `default` profile | Text chunking before embedding |
| `embedding` | `embedding_transformer`, `miniLM` profile | Embedding model used to vectorize chunks |
| `store` | `qdrant`, `local` profile (collection `ROCKETRIDE`, `localhost:6333`) | Vector store the embeddings are written to |

Defaults come from the `default` preconfig profile in `services.json`. The preprocessor, embedding, and store filters are each only inserted when the corresponding key is present in the resolved autopipe configuration.

---

## Notes

### Remote processing

The implementation distinguishes local and remote filter placement, and the default profile carries a `remote` sub-configuration (host, port, apikey, `mode: local`). However, the remote-pipeline assembly path is currently commented out in `IGlobal.endGlobal` and the remote queue is never dispatched: all inserted filters run locally regardless of the `remote` setting.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/autopipe)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Background Removal

Route: /nodes/background_removal

# background_removal

A RocketRide image node that removes an image's background and produces an RGBA cutout plus alpha-coverage statistics. Choose it when a downstream image node needs the foreground isolated for re-compositing.

## About BiRefNet

BiRefNet is the image background-removal model family used by this node. The node can load the default BiRefNet model or its higher-resolution HR variant, using the configured model identifier and optional revision.

## What it does

The node accepts an image stream, runs background removal for each completed image, and can emit both a cutout image and JSON alpha statistics. The image output preserves the source RGB pixels and combines them with a straight, non-premultiplied alpha matte, so another node can composite it over a new background. Choose this node when you need that RGBA foreground asset rather than a caption, detections, or a depth map.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | An RGBA PNG cutout using the input image's RGB data and the predicted alpha matte. |
| `image` | `text` | JSON statistics: `mean_alpha` and `alpha_coverage_pct`. |

## Profiles

Default: **BiRefNet — default, 1K (MIT)** (`birefnet-default`).

| Profile | Model | Maximum input edge |
| --- | --- | --- |
| BiRefNet — default, 1K (MIT) **(default)** | `ZhengPeng7/BiRefNet` | `1024` px |
| BiRefNet HR — 2K, finer hair / edge detail (MIT) | `ZhengPeng7/BiRefNet_HR` | `2048` px |

## Configuration

Select the BiRefNet profile that gives the edge detail you need, then tune the maximum input edge only when latency or edge quality calls for it. The node falls back to its implementation default model if no model is configured.

### Model

The default profile uses the 1K BiRefNet variant; the HR profile uses the 2K variant for finer hair and edge detail. Start with the default profile and use HR when the foreground boundary needs more detail. A configured model identifier overrides the profile's model value, and the optional revision is passed to the model loader; use an override only when you intend to load a compatible BiRefNet model.

### Max input edge (px)

This caps the source image's long edge before inference. The default is `1024`; a lower value reduces inference work and memory use at the cost of a less detailed alpha matte, while a higher value can improve edges. The resulting alpha matte is restored to the original image dimensions before the RGBA cutout is created. The runtime clamps supplied values to `256` through `4096`, so values outside that range do not take effect as entered.

## Requirements

With a model server configured, inference runs there. Otherwise it runs locally on CPU, Apple Silicon (MPS), or CUDA, and a device lock serializes local inference so concurrent frames never run through the model at once.

## Notes

### Output and failures

For each successful image, `mean_alpha` is the alpha matte's average after scaling alpha bytes to `0.0`–`1.0`; `alpha_coverage_pct` is the percentage of pixels with alpha greater than `0.5`. The PNG encoder uses compression level 1. If image decoding or inference fails, the node logs a warning, drops that frame, and emits neither output for it.

## Upstream docs

- [BiRefNet model page](https://huggingface.co/ZhengPeng7/BiRefNet)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `background_removal.maxEdge` | `number` | **Max input edge (px)**<br/>Downscale source so long edge <= this value before inference; alpha is upsampled back to the original source size for compositing. Lower = faster + less VRAM; higher = sharper edges. | `1024` |
| `background_removal.model` | `string` | **Model**<br/>HuggingFace model identifier for background removal (overrides the profile default) |  |
| `background_removal.profile` | `string` | **Model**<br/>BiRefNet variant — default is 1K, HR is 2K for finer edges. | `"birefnet-default"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/background_removal)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Caption

Route: /nodes/caption

# caption

A RocketRide image node that turns each input image into a natural-language caption. Choose it when downstream text processing needs an image description rather than boxes, masks, or extracted text.

## About Florence-2

Florence-2 is the image captioning model used by this node. The node loads the configured model identifier and optional revision, and sends its configured caption task to the model for each image.

## What it does

The node buffers each incoming image stream, captions the completed image, and writes the resulting string on the `text` lane. It offers short, detailed, and more-detailed caption tasks through its configuration. Choose it for a general natural-language description of image content; reach for Object Detection when you need boxes and OCR when you need the text in the image.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `text` | Caption string for the completed input image. |

## Configuration

The single supplied profile selects the Florence-2 Base model, so most use cases only need a granularity choice. The implementation uses its default model and task if either value is empty.

### Granularity

Granularity selects one of three configured tasks: `caption` (the default, shown as Short), `detailed_caption`, or `more_detailed_caption`. Keep the default when a concise description is sufficient; use a more detailed task when the next node needs richer text to reason over. The task is passed directly to the captioning facade, so choose one of the values exposed in the configuration panel.

## Requirements

With a model server configured, captioning runs there. Otherwise it runs locally on CPU, Apple Silicon (MPS), or CUDA, and a device lock serializes local caption generation.

## Notes

### Empty captions on failure

The node runs captioning only when the `text` lane has a listener. If image decoding or caption inference raises an exception, it logs a warning and writes an empty string to that listener instead of propagating a result from the failed image.

## Upstream docs

- [Florence-2 Base model page](https://huggingface.co/microsoft/Florence-2-base)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `caption.profile` | `string` | **Model** | `"florence-base"` |
| `caption.task` | `string` | **Granularity**<br/>How detailed the caption should be. | `"caption"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/caption)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Text Chunker

Route: /nodes/chunker

# chunker

A RocketRide preprocessor node ("Text Chunker") that splits documents into smaller, overlapping chunks for downstream embedding, retrieval, and LLM generation. Pick it when you need sentence-boundary splitting with no extra dependencies, or token-accurate splitting sized with the real `tiktoken` BPE tokenizer.

## What it does

The node receives documents on its `documents` lane, splits each one's text with the configured strategy, and emits one document per chunk on the same lane. Every emitted chunk copies the source document and gets its own metadata — `chunkId`, `parentId` (the source `objectId`), `chunk_index`, `start_char`, `end_char`, and `total_chunks` — so downstream nodes can trace a chunk back to its origin or reassemble the original. The incoming documents themselves are never forwarded; only chunks continue down the pipeline, and documents whose text is empty or whitespace-only are consumed and produce nothing.

It deliberately covers only the two strategies the engine does not otherwise have: sentence-boundary grouping and real token counting. For recursive character splitting use the **General Text** (`preprocessor_langchain`) node, which already exposes LangChain's `RecursiveCharacterTextSplitter`; configuring `recursive` here fails at startup with a pointer to that node rather than falling back silently.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | `documents` | Split each incoming document and emit one document per chunk. |

## Profiles

Default: **Sentence Boundary - Splits at sentence endings for coherent chunks** (`sentence`).

| Profile | Strategy | Chunk size | Overlap | Best for |
| --- | --- | --- | --- | --- |
| `sentence` **(default)** | `sentence` | 1000 characters | 200 | Ordinary punctuated prose that should never be cut mid-sentence. |
| `token` | `token` | 512 tokens | 50 | Chunks that must fit a model's context or an embedding input limit. |

The `sentence` strategy splits on sentence-ending punctuation (`.`, `!`, `?`) followed by whitespace, using only the Python standard library — no third-party package and no language-model download. It treats a sentence as indivisible, so `chunk_size` is a grouping target rather than a hard cap: a single sentence longer than `chunk_size` is emitted whole.

The `token` strategy encodes the text with `tiktoken` and slices it by token count, so every chunk is capped at `chunk_size` tokens unconditionally. Its dependency is probed and its encoder imported only when this strategy is selected. Choose it for input with no sentence-ending punctuation — log lines, CSV rows, OCR dumps, minified text — where the sentence strategy finds no boundaries to group on and emits one oversized chunk.

## Configuration

Pick the profile first: it sets the strategy along with chunk size, overlap, and (for `token`) the encoding, and the defaults are sensible for each. The configuration panel then shows only the fields that apply to the chosen strategy, so there is nothing else most pipelines need to touch. All three values are validated at startup — a non-positive chunk size, a negative overlap, or an overlap that is not smaller than the chunk size stops the node rather than degrading quietly.

### Chunk size

The maximum size of a chunk, measured in **characters** for the `sentence` strategy and in **tokens** for the `token` strategy — the same field means different units depending on the profile. Larger values preserve more context per chunk but retrieve less precisely; smaller values sharpen retrieval and cost more chunks. The profile defaults (1000 characters, 512 tokens) suit general documents; when the chunks feed an embedding model or an LLM prompt, size them against that model's input limit using the `token` strategy so the count is exact rather than estimated.

### Chunk overlap

How much of each chunk is repeated at the start of the next one, in the same units as chunk size, so a sentence or idea straddling a boundary still appears whole in at least one chunk. It must be less than the chunk size. With the `token` strategy the window advances by `chunk_size - chunk_overlap` tokens; with the `sentence` strategy the trailing sentences of the finished chunk are carried forward as long as their combined span fits within the overlap, so the effective overlap lands on a sentence boundary and can be smaller than the configured value. Set it to `0` to disable overlap entirely; the profile defaults of 200 characters and 50 tokens are roughly a fifth and a tenth of their chunk sizes.

### Token encoding

The `tiktoken` encoding used to count and slice tokens. It applies only to the `token` strategy and is ignored by `sentence`. Match it to the model the chunks are destined for, since token boundaries differ between encodings: `cl100k_base` (the default) for GPT-4, GPT-3.5-turbo and `text-embedding-ada-002`, `o200k_base` for GPT-4o and newer models, `p50k_base` for Codex models, and `r50k_base` for GPT-3 models. The wrong encoding still produces chunks, but their token counts will not match what the consuming model measures.

## Notes

### Chunk metadata

`chunkId` is a running counter across everything emitted for one incoming object and resets to `0` when the next object opens; `chunk_index` restarts at `0` for each source document, and `total_chunks` is that document's chunk count. `start_char` and `end_char` are character offsets into the source text — exact for the `sentence` strategy, and derived from decoded token spans for the `token` strategy.

### Undecodable tokens

A token window can end mid-character, so the `token` strategy falls back to a per-token byte rebuild when a decode fails, substituting U+FFFD for bytes it cannot recover. A chunk is never dropped because of a malformed multi-byte sequence.

## Upstream docs

- [tiktoken](https://github.com/openai/tiktoken)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `chunker.chunk_overlap` | `integer` | **Chunk overlap**<br/>Number of characters or tokens to overlap between consecutive chunks; must be less than chunk size. | `200` |
| `chunker.chunk_size` | `integer` | **Chunk size**<br/>Maximum size of each chunk (characters for the sentence strategy, tokens for the token strategy) | `1000` |
| `chunker.encoding_name` | `string` | **Token encoding**<br/>Tiktoken encoding name (only used with token strategy) | `"cl100k_base"` |
| `chunker.profile` | `string` | **Chunking strategy**<br/>Select the text chunking strategy | `"sentence"` |

## Dependencies

- `tiktoken` `>=0.7.0,<1.0.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/chunker)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Text To Speech (ElevenLabs)

Route: /nodes/cloud_tts

# cloud_tts

A RocketRide audio node with OpenAI, ElevenLabs, and Rime registrations that converts text into MP3 audio. Pick it when pipeline text, documents, questions, or answers should be spoken through one of these cloud text-to-speech APIs.

## About OpenAI, ElevenLabs, and Rime

OpenAI, ElevenLabs, and Rime each publish a cloud text-to-speech API. This directory implements all three as separate registrations over one shared RocketRide engine, which selects the vendor from the node logical type and sends synthesis requests from the engine host over HTTPS.

## What it does

Accepts content on any of four lanes, turns the resulting text into speech through the selected cloud vendor, and writes the returned MP3 bytes to `audio`. Choose the OpenAI registration for the OpenAI text-to-speech API, the ElevenLabs registration for the ElevenLabs text-to-speech API, or the Rime registration for the Rime text-to-speech API; their lane wiring is identical, while their model, voice, and credential settings are separate. Unlike a local TTS node, this node makes an HTTPS request directly from the engine host and needs vendor credentials before it can start.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `audio` | Synthesize non-empty text input as MP3 audio. |
| `documents` | `audio` | Join eligible document page content, then synthesize it as MP3 audio. |
| `questions` | `audio` | Join the question text entries, then synthesize them as MP3 audio. |
| `answers` | `audio` | Read answer text, then synthesize it as MP3 audio. |

## Profiles

The directory registers three providers and each keeps its own default: the
OpenAI service defaults to **GPT-4o mini TTS - Fast, steerable, multilingual**
(`gpt-4o-mini-tts`), the ElevenLabs service to **Multilingual v2 - High
quality, 29 languages** (`eleven_multilingual_v2`), and the Rime service to
**Coda - Flagship, best quality** (`coda`). All three are marked below;
which one applies depends on the service you added to the pipeline.

| Profile | Vendor model | Default voice |
| --- | --- | --- |
| GPT-4o mini TTS - Fast, steerable, multilingual **(default)** | `gpt-4o-mini-tts` | `alloy` |
| TTS-1 - Low latency, standard quality | `tts-1` | `alloy` |
| TTS-1 HD - Higher quality, slower | `tts-1-hd` | `alloy` |
| Multilingual v2 - High quality, 29 languages **(default)** | `eleven_multilingual_v2` | `EXAVITQu4vr4xnSDxMaL` |
| Turbo v2.5 - Low latency, 32 languages | `eleven_turbo_v2_5` | `EXAVITQu4vr4xnSDxMaL` |
| Flash v2.5 - Lowest latency | `eleven_flash_v2_5` | `EXAVITQu4vr4xnSDxMaL` |
| Eleven v3 - Most expressive | `eleven_v3` | `EXAVITQu4vr4xnSDxMaL` |
| Coda - Flagship, best quality **(default)** | `coda` | `astra` |
| Arcana - Expressive, multilingual | `arcana` | `astra` |
| Mist v3 - Lowest latency | `mistv3` | `astra` |
| Mist v2 - Pronunciation control | `mistv2` | `astra` |


## Configuration

Select the registration first, then choose a model profile and a compatible voice for that vendor. The shared engine reads `model`, `voice`, and `apikey` from the selected configuration and falls back to its vendor-specific default model and voice only when those values are blank.

| Registration | Node | Endpoint | Key env |
| --- | --- | --- | --- |
| `services.tts_openai.json` | OpenAI TTS | `api.openai.com/v1/audio/speech` | `OPENAI_API_KEY` |
| `services.tts_elevenlabs.json` | ElevenLabs TTS | `api.elevenlabs.io/v1/text-to-speech/{voice}` | `ELEVENLABS_API_KEY` |
| `services.tts_rime.json` | Rime TTS | `users.rime.ai/v1/rime-tts` | `RIME_API_KEY` |

The per-vendor HTTPS call lives in `openai_tts.py`, `elevenlabs_tts.py`, and `rime_tts.py`; each returns MP3 bytes.

### OpenAI model and voice

The OpenAI registration offers the `gpt-4o-mini-tts`, `tts-1`, and `tts-1-hd` profiles, defaulting to `gpt-4o-mini-tts` with `alloy`. Choose a profile to change the `model` sent to OpenAI; choose a voice from the OpenAI voice list to change the `voice` in that request. The `marin` and `cedar` voice choices require a GPT-4o TTS model according to the field metadata, so do not pair them with a non-GPT-4o profile.

### ElevenLabs model and voice

The ElevenLabs registration offers the `eleven_multilingual_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2_5`, and `eleven_v3` profiles, defaulting to `eleven_multilingual_v2` with the `EXAVITQu4vr4xnSDxMaL` voice ID. Select a profile to change the `model_id` sent to ElevenLabs and a listed premade voice ID to change the voice placed in the request URL. Keep the model and voice within the ElevenLabs registration: the engine dispatches only from the registration's logical type and does not translate settings between vendors.

### Rime model and Speaker

The Rime registration offers the `coda`, `arcana`, `mistv3`, and `mistv2` profiles, defaulting to `coda` with the `astra` speaker. Rime speakers are model-specific, so each Rime profile carries its own `tts_rime.<model>.voice` enum and all of them merge under `voice` for the shared engine. Select a profile to change the `model` sent to Rime, then pick a speaker from that profile's own list; `astra` is valid across all four shipped models.

## Authentication

All three registrations require an API key at startup. Put it in the node configuration as `apikey`, or leave that value blank and set `OPENAI_API_KEY` for the OpenAI registration, `ELEVENLABS_API_KEY` for the ElevenLabs registration, or `RIME_API_KEY` for the Rime registration on the engine host. A missing key prevents startup; the requests use a bearer authorization header for OpenAI and Rime and the `xi-api-key` header for ElevenLabs.

## Notes

### Input handling and output

Whitespace-only input produces no audio request. Documents are converted by joining `page_content` from entries that have content and are not `Image`, `Audio`, or `Video`; questions are joined from their question text, and answers use `getText()` when available. Every successful vendor response is written as one `audio/mpeg` clip with a begin/write/end sequence; this node does not split an input into multiple synthesis calls.

### Per-request input caps

Each record is sent to the vendor in a single request, so the vendor's per-request input cap applies to the whole record: OpenAI roughly 4096 characters, ElevenLabs roughly 5000, and Rime 1,000 for `coda`, `mistv2`, and `mistv3` with no cap for `arcana`. Split long inputs upstream with a chunker node before this node; one record over the cap fails that record. The node checks the cap itself and fails the record with the character count, the limit, and what to do about it, because the vendor would otherwise return a bare `400` that never mentions length. Rime's cap is four to five times lower than the others, so a pipeline that worked on OpenAI can hit it simply by switching vendor.

### Request failures

Each vendor request has a 120-second HTTP timeout and raises for a non-success HTTP status. The lane handler logs a `Cloud TTS synthesis failed` warning and re-raises the exception, so a failed request does not emit a partial audio clip.

## Upstream docs

- [OpenAI text-to-speech documentation](https://platform.openai.com/docs/guides/text-to-speech)
- [ElevenLabs text-to-speech API documentation](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [Rime text-to-speech API documentation](https://docs.rime.ai/api-reference/endpoint/streaming-mp3)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Text To Speech (ElevenLabs) (`services.tts_elevenlabs.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `tts_elevenlabs.profile` | `string` | **Model**<br/>ElevenLabs model | `"eleven_multilingual_v2"` |
| `tts_elevenlabs.voice` | `string` | **Voice**<br/>Premade ElevenLabs voice (voice_id). | `"EXAVITQu4vr4xnSDxMaL"` |

### Text To Speech (OpenAI) (`services.tts_openai.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `tts_openai.profile` | `string` | **Model**<br/>OpenAI TTS model | `"gpt-4o-mini-tts"` |
| `tts_openai.voice` | `string` | **Voice**<br/>OpenAI TTS voice. The newer voices (marin, cedar) require a GPT-4o TTS model. | `"alloy"` |

### Text To Speech (Rime) (`services.tts_rime.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `tts_rime.arcana.voice` | `string` | **Speaker**<br/>Rime voice for the Arcana model. | `"astra"` |
| `tts_rime.coda.voice` | `string` | **Speaker**<br/>Rime voice for the Coda model. | `"astra"` |
| `tts_rime.mistv2.voice` | `string` | **Speaker**<br/>Rime voice for the Mist v2 model. | `"astra"` |
| `tts_rime.mistv3.voice` | `string` | **Speaker**<br/>Rime voice for the Mist v3 model. | `"astra"` |
| `tts_rime.profile` | `string` | **Model**<br/>Rime TTS model | `"coda"` |

## Dependencies

- `requests` `>=2.34.2`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/cloud_tts)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Context Optimizer

Route: /nodes/context_optimizer

# context_optimizer

A RocketRide text node that fits an LLM request into a model's context window by budgeting tokens across the system prompt, question, retrieved documents and conversation history. Put it in front of an LLM node when retrieval or a long conversation can push a prompt past the window and you want deterministic, local trimming instead of a provider-side rejection.

## What it does

The node counts the tokens of the prompt the engine will actually render with `tiktoken`, and only when that rendering exceeds the model's context window does it allocate a per-component budget and trim. The system prompt and the question are truncated on sentence boundaries, falling back to a token-level cut when a single sentence is still over budget; documents are ranked by their vector-DB `score` (descending, or by keyword overlap with the question when no scores are present) and selected greedily until the document budget is spent; conversation history keeps the first message and as many recent messages as fit, replacing the middle with a single summarized placeholder. A question carrying several `QuestionText` entries keeps every entry — the entries share the query allowance in proportion to their own size — so the per-entry embedding metadata that the embedding nodes write and the document stores read survives the node. Requests whose rendered prompt already fits pass through unchanged, and no extra model call is ever made. This node is marked **experimental**.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `questions` | Questions with optimized context fitting within model token limits |

## Profiles

Default: **Auto - Use default model limits** (`auto`). Both user-facing profiles ship the same budget split; they differ only in where the context window comes from.

| Profile | Budget split (system / query / documents / history) | When to pick it |
| --- | --- | --- |
| `auto` **(default)** | 10 / 15 / 50 / 25 | The usual choice: name the model and let the node resolve its window. |
| `manual` | 10 / 15 / 50 / 25 | A deployment whose real window neither the live catalog nor the fallback table knows; set **Max context tokens** yourself (ships at 128 000). |
| `ci_tiny` | 10 / 20 / 35 / 35 | Automated node tests only. It pins a 112-token window so every case is forced over budget; it is deliberately absent from the **Mode** dropdown. |

## Configuration

Pick a **Mode** and, in `auto`, name the model. The four budget percentages have workable defaults (10 / 15 / 50 / 25) and most pipelines never touch them — reach for them only when one component of your prompt is systematically starved.

### Mode

`auto` resolves the context window for the model named in **Model name**; `manual` ignores the model entirely and uses **Max context tokens**. `auto` is right whenever the model is one an `llm_*` node in this deployment publishes, which is the common case; `manual` is the escape hatch for a gateway, a fine-tune, or a self-hosted deployment whose window this build cannot know. How `auto` resolves the window — and what it does when it cannot — is described under [Where the context-window size comes from](#where-the-context-window-size-comes-from).

### Model name

The model identifier used for the window lookup in `auto` mode, e.g. `gpt-5.4`, `claude-sonnet-4-6`, `models/gemini-3.1-pro-preview`. Use the id an `llm_*` node publishes; a provider-scoped id (`openai/gpt-5`) also resolves under its bare name when that name is unambiguous, and the abbreviated family aliases `claude-sonnet`, `claude-opus`, `gemini-pro` and `gemini-flash` resolve from the built-in table. An id nothing recognizes does not fail the run — it is budgeted against the smallest window this build knows about, with a warning — so a typo here costs context rather than correctness. Set the id to match the LLM node the pipeline actually calls; budgeting for a larger window than the model has is what gets a request rejected downstream.

### Max context tokens

The explicit window, in tokens, used by `manual` mode; `0` falls back to the model default. Set it to the model's real total window, not the share you want the prompt to use — the percentages below divide this number. In `auto` mode the field is hidden and ignored.

### System prompt, query, document and history budget percentages

These four fields divide whatever window is left after the un-budgeted sections are counted (see [What is budgeted, and what is only counted](#what-is-budgeted-and-what-is-only-counted)). They are percentages of that remainder, and the node never lets them over-commit it: a set summing to more than 100 is scaled proportionally back to 100, and a set summing to less than 90 is honoured but logs a warning that the window is being under-used. The system prompt, query and document allowances are taken from their percentages in that order and history absorbs whatever is left, so history is the component that gives way first. Raise **Document budget %** for retrieval-heavy pipelines where history is short; raise **History budget %** for long chat sessions with few documents. A component given `0` is emptied whenever the request is over budget, which is a legitimate way to say "drop history before you touch my documents".

## Notes

### What is budgeted, and what is only counted

Exactly four fields of the incoming `Question` are budgeted and trimmed: `role` (the system prompt), `questions`, `documents` and `history`. Everything else `Question.getPrompt()` renders is **counted against the window but never trimmed**:

- `instructions`, including the JSON-format boilerplate `expectJson` injects (the `prompt` node appends here);
- `examples`;
- `context` (retrieval nodes fill this);
- `goals`;
- the section markup itself — the `### System Instructions:` / `### Documents:` / `### Current Task:` headers, the `Document N) Content:` and `role:` line prefixes, and the CRLF joins between them.

That second group is measured, not estimated: the incoming question is rendered through `getPrompt()` with the four budgeted fields emptied, the result is counted with the node's own tokenizer, and the total is subtracted from the context window *before* the per-component percentages are applied. A request is therefore judged against the prompt that will actually be sent — a question whose `role`, `questions`, `documents` and `history` fit but whose instructions and context push the rendering over the window is trimmed instead of being waved through. The figure errs high: it keeps the markup of every document, history message and question entry even though trimming may later drop some of them, and it adds a two-token margin for the line break `getPrompt()` appends after a non-empty `role`, which the blanked rendering cannot see.

If the un-budgeted fields alone fill the window, nothing is left to allocate: every budget becomes 0, all four budgeted fields are emptied, and the node warns once naming the cost. This node cannot shorten `instructions`, `examples`, `context` or `goals` — shorten them upstream, or raise **Max context tokens**.

### Where the context-window size comes from

`auto` mode resolves the window for the configured model in this order:

1. **The live model catalog** — the `modelTotalTokens` value on the matching `preconfig` profile of any LLM node, read through the engine's own service registry (`rocketlib.getServiceDefinitions()` to enumerate the registered types, then `getServiceDefinition()` for each raw definition; whichever definitions publish `modelTotalTokens` contribute — the chat `llm_*` nodes, the `image_vision_*` nodes, and the embedding/search nodes alike). Because the registry is the same path the engine used to load the nodes, the catalog is found whether this node runs from the source tree, from an installed node store, or from a `--node_path` materialisation with no sibling directories; it is re-read at every pipeline start, so a reloaded registry is never masked by a stale cache. Those values are kept current by the [`sync-models`](https://github.com/rocketride-org/rocketride-server/tree/develop/tools/sync_models) tool, so `gpt-5.4`, `claude-sonnet-4-6`, `models/gemini-3.1-pro-preview` and every other id the LLM nodes publish resolve without this node hard-coding them. Provider-scoped ids also resolve under their bare name (`openai/gpt-5` → `gpt-5`), but only when that name is unambiguous: an unscoped profile always wins, and a bare name that two gateways disagree about is dropped so it falls through to the table below rather than silently picking one. Where the same full id appears in two services files with different windows, the smaller is used.
2. **A built-in fallback table** (`ContextOptimizer.MODEL_LIMITS`), refreshed against that catalog on 2026-09-04. It covers deployments where no LLM node is registered with the engine, and it is where the abbreviated family aliases that no provider actually publishes — `claude-sonnet`, `claude-opus`, `gemini-pro`, `gemini-flash` — are defined.
3. **The conservative fallback** — the *smallest* context window published by any registered chat-LLM profile (`llm_*` nodes / `classType: ["llm"]`) or by the fallback table — 8 191 tokens on develop today, the smallest published chat windows (`gpt-4`, `codestral-latest`, `mistral-medium-2505`) — with a one-time warning naming the unresolved model id. Embedding input limits and vision models are catalogued for lookup but never lower this floor. An unknown id is usually a typo or a model this build predates; budgeting it low costs some unused context, whereas the previous optimistic 128 000 default made the provider reject the request outright for any smaller-window model. Set **Max context tokens** for the real window.

`manual` mode sets **Max context tokens** explicitly and bypasses all three.

The engine also exposes the *connected* LLM's own limit and tokenizer to upstream nodes through `IInvokeLLM.GetContextLength()` / `GetTokenCounter()` (as used by `summarization` and `preprocessor_llm`). That channel is only reachable after `beginFilter`, so this node does not consume it today; `manual` mode is the escape hatch when both the catalog and the fallback table are wrong for a given deployment.

### Offline use

Token counting uses `tiktoken`, which downloads its BPE vocabulary from `openaipublic.blob.core.windows.net` the first time a given encoding is requested (`o200k_base` for the GPT-5 / GPT-4o families, `cl100k_base` otherwise) and then caches it on disk. In an air-gapped or egress-restricted deployment, pre-seed that cache and point `TIKTOKEN_CACHE_DIR` at it before starting the engine. The node's own `services.json` test cases exercise the same path, so a CI runner without egress needs the same pre-seeded cache.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `context_optimizer.document_budget_pct` | `number` | **Document budget (%)**<br/>Percentage of context window for retrieved documents | `50` |
| `context_optimizer.history_budget_pct` | `number` | **History budget (%)**<br/>Percentage of context window for conversation history | `25` |
| `context_optimizer.max_context_tokens` | `number` | **Max context tokens**<br/>Override model token limit (0 = use model default) | `0` |
| `context_optimizer.model_name` | `string` | **Model name**<br/>Model identifier for context-window lookup. Use an id published by an llm_* node (e.g. gpt-5.4, claude-sonnet-4-6, models/gemini-3.1-pro-preview); a short family alias such as claude-sonnet also resolves. |  |
| `context_optimizer.profile` | `string` | **Mode**<br/>Context optimization mode | `"auto"` |
| `context_optimizer.query_budget_pct` | `number` | **Query budget (%)**<br/>Percentage of context window for the query/question | `15` |
| `context_optimizer.system_prompt_budget_pct` | `number` | **System prompt budget (%)**<br/>Percentage of context window for system prompt | `10` |

## Dependencies

- `tiktoken` `>=0.7.0,<1.0.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/context_optimizer)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Core

Route: /nodes/core

# core

The shared-services module of the RocketRide engine: it registers the built-in pipeline services (file system source, parser, fingerprinter, word indexer, ZIP target, null endpoint) and the common field libraries that other nodes merge into their own service definitions.

## What it does

`core` is not one node; it is the module that registers RocketRide's family of shared services. Each service is declared in a `services.*.json` file in this directory, and you configure them inside a pipeline rather than dropping one standalone node on the canvas.

The directory holds three kinds of content:

- **Concrete service definitions**: `services.filesys.json`, `services.parse.json`, `services.hash.json`, `services.indexer.json`, `services.zip.json`, and `services.null.json` each register one engine service (title, protocol, class type, capabilities, lanes, and config shape).
- **Shared field libraries**: the `services.common*.json` files define reusable field groups (cloud-provider credentials, include/exclude path forms, vector-store settings, LLM access, anonymization, remote processing) that are merged into other service definitions as required.
- **Shared code and assets**: `google_access.py` (the access/scope resolver used by Google tool nodes), `gcp_auth.py` (ADC and service-account credentials for GCP nodes), and the SVG icons displayed in the UI for connector and processing nodes (Amazon S3, Azure Blob, Google Drive, OneDrive, SharePoint, Outlook, Gmail, Confluence, Slack, SMB, and others).

The `hash/` and `parser/` subdirectories carry the per-service documentation pages for the Fingerprinter and Parser services.

---

### Protocol-bearing services

| Service | File | Protocol | Class type | Lanes |
|---------|------|----------|------------|-------|
| Local File System | `services.filesys.json` | `filesys://` | `source` | `_source` → `tags` |
| Parser | `services.parse.json` | `parse://` | `data` | `tags` → `text`, `table`, `image`, `video`, `audio` |
| Fingerprinter | `services.hash.json` | `hash://` | `data` | `tags` → `tags` |
| Word indexer | `services.indexer.json` | `indexer://` | (empty, internal, not selectable) | none |
| ZIP Creation | `services.zip.json` | `zip://` | `target` (internal) | none |
| Null | `services.null.json` | `null://` | (empty, internal) | `source` → `tags` |

### Local File System

A source service that reads data from the local file system, ingesting files and documents from directories for further processing. Capabilities: `filesystem`, `noremote`, `security`, `nosaas`. Supported actions: `export`, `delete`, `download`.

| Field | Type / Default | Description |
|-------|----------------|-------------|
| `include` | array (min 1 item) | Paths included for Scan, Index, Classify, and OCR. Windows: `C:\foldername` or `\\file.core.net\foldername`; Linux: `/file.core.net/foldername`. Each entry carries per-path toggles (`include.permissions`, `include.signing`). |
| `exclude` | array, optional | Paths excluded from processing (same path formats). |
| `excludeExternalDrives` | boolean, default `true` | Skip external drives. |
| `excludeEnableGlobal` | boolean, default `true` | Skip typical OS files and directories. |
| `excludeSymlinks` | boolean, default `true` | Skip symlinks. |
| `estimation` | section, optional | Cost estimations: `estimation.accessDelay`, `estimation.accessRate`, `estimation.storeCost`, `estimation.accessCost` (all numbers, default `0`). |

The service exposes two shape sections: **Source** (full form with estimation) and **Pipe** (the `Pipe.include` / `Pipe.exclude` variants, for example `/Users/usr/Documents/product-images/*`). A development variant of the definition exists as `services.filesys.json.dev`.

### Parser

Extracts structured content from a wide variety of document types. It automatically identifies embedded content and routes it to the appropriate output lane, making text, tables, images, audio, and video accessible for downstream processing. No configuration fields.

| Lane in | Lane out | Description |
|---------|----------|-------------|
| `tags` | `text` | Extracted plain text |
| `tags` | `table` | Extracted tables |
| `tags` | `image` | Extracted images |
| `tags` | `video` | Extracted video streams |
| `tags` | `audio` | Extracted audio streams |

### Fingerprinter

Generates a deterministic fingerprint (hash) of each document's content as it passes through the pipeline. The hash is computed from the raw or normalized text, so identical content always produces the same fingerprint regardless of metadata. Use it for deduplication, content tracking, and identity verification before indexing. Lane: `tags` → `tags`. Ships a single empty `default` preconfig profile and has no configuration fields.

### Word indexer

Enables full-text indexing inside the engine. Registered with capability `internal` and an empty `classType`, so it is not user-selectable on the canvas; it has no fields or shape of its own.

### ZIP Creation

An internal target service (protocol `zip://`) that streams processed objects into a ZIP archive. Supported actions: `export`, `delete`, `download`. Its target parameters are `storePath` (destination folder, see path formats in the Local File System section) and `url` (read-only, default `https://`).

### Null

An internal no-op endpoint registered as both a source shape and a target shape with empty parameter sections. Lane: `source` → `tags`.

---

## Lanes

| Lane in | Lane out | Description |
|---------|----------|-------------|
| `_source` | `tags` | Local File System emits source tags for downstream processing. |
| `tags` | `tags` | The Fingerprinter preserves the tags lane while adding its deterministic content fingerprint. |
| `source` | `tags` | The internal null endpoint forwards a source lane into tags without an external system. |

The parser also accepts `tags` and emits `text`, `table`, `image`, `video`, and `audio`; its protocol-specific documentation is in the `parser/` subdirectory.

## Configuration

This directory supplies several built-in services as well as shared field definitions used by other nodes. Configure the protocol-bearing service selected in a pipeline; the generated schema below is the field reference. The shared field files do not register a selectable service themselves.

### Shared field libraries

These files define common fields that are merged into a service definition as required. Field names below are exact.

### Basic fields and include/exclude forms (`services.common.json`)

- `storePath`: exact folder path; format varies by backend (Windows, Linux, AWS/S3 `bucketname/foldername`, Azure Blob `containername/foldername`, SharePoint `sitename/drivename/foldername`, OneDrive `account/foldername`).
- `url`: service URL, read-only, default `https://`.
- `include` / `exclude`: path arrays with per-path processing toggles: `include.classify` (default `false`), `include.ocr` (default `false`), `include.signing` (default `true`; enabling it unlocks `include.index` and `include.vectorize`), `include.index` (default `false`), `include.permissions` (default `false`), `include.vectorize` (default `false`).
- `estimation`: cost-estimation section (`estimation.accessCost`, `estimation.accessDelay`, `estimation.accessRate`, `estimation.storeCost`; all default `0`).
- `DTC.*` and `Pipe.*`: simplified include/exclude/feature variants of the same forms (OCR and permissions feature toggles) used by the DTC and Pipe shapes.
- Hidden plumbing fields: `sync` (default `true`), `actions`, `source.mode` (default `"Source"`), `target.mode` (default `"Target"`), `hideForm` (default `true`).

### AWS credentials (`services.common.aws.json`)

| Field | Type | Description |
|-------|------|-------------|
| `aws.accessKey` | string, secure, optional | Access key used to sign requests to Amazon S3. |
| `aws.secretKey` | string, secure, optional | Secret key used to access AWS services. |
| `aws.region` | enum | AWS region (us-east-1 through sa-east-1; default empty "Select Region"). |

### Google Cloud Platform credentials (`services.common.gcp.json`)

| Field | Type | Description |
|-------|------|-------------|
| `gcp.authType` | enum `adc` / `service_account`, default `adc` | Choose how to authenticate to Google Cloud Platform. |
| `gcp.serviceAccountKey` | data-url (`.json` upload) | Service Account JSON key file (used when authType is `service_account`). |
| `gcp.projectId` | string, optional | Specify the Google Cloud Project ID explicitly. Leave blank to infer from credentials. |

### Google Workspace credentials (`services.common.google.json`)

| Field | Type | Description |
|-------|------|-------------|
| `google.authType` | enum `service` / `user`, default `service` | Selects service-account vs user OAuth flow. |
| `google.customerId` | string | Google Workspace Customer ID (service auth). |
| `google.adminEmail` | string | Administrator e-mail with admin privileges (service auth). |
| `google.serviceKey` | data-url (`.json` upload) | Service-account JSON key file (service auth). |
| `google.oAuthButton` | string, optional | "Login with Google" OAuth widget (user auth). |
| `google.userToken` | string | Long-term access token used to mint Google API access tokens (user auth). |

### LLM access (`services.common.llm.json`)

| Field | Type / Default | Description |
|-------|----------------|-------------|
| `llm.local.serverbase` | string, default `http://localhost:11434/v1` | Base URL the model is hosted under. |
| `llm.cloud.apikey` | string, secure | API key or token. |
| `llm.cloud.project` | string | LLM project or organization name. |
| `llm.cloud.location` | string | LLM server location. |
| `llm.cloud.modelSource` | string, hidden, optional | Model source. |

### Remote processing (`services.common.remote.json`)

`remote.profile` selects the processing mode: `local` ("Process everything locally", the default) or `remote` ("Process CPU/GPU heavy tasks remotely"). Remote mode exposes `remote.host` (default `pipe.rocketride.ai`), `remote.port` (default `5565`), and `remote.apikey`.

### Vector stores and embeddings (`services.common.vector.json`)

| Field | Type / Default | Description |
|-------|----------------|-------------|
| `vector.host` / `vector.port` | string / number | Vector-store server address and port (with `vector.cloud.*` and `vector.local.*` variants, plus `vector.local.grpc_port`). |
| `vector.collection` | string, default `ROCKETRIDE` | Collection name. |
| `vector.score` | number 0-1, default `0.7` | Minimum retrieval score, from `0.0` "All results" to `1.0` "Almost identical". |
| `vector.top_k` | integer or string 1-1000, optional | Chroma only: overrides the caller's retrieval limit (25 on the data lane) in either direction for semantic and keyword search. Unset keeps the caller's limit. |
| `vector.apikey` | string, secure | API key. |
| `vectorizer.embedding` | combo `embedding` | Embedding provider selector. |
| `vectorizer.store` | combo `store` | Vector-store provider selector. |

### Anonymization (`services.common.anonymize.json`)

| Field | Type / Default | Description |
|-------|----------------|-------------|
| `anonymize` | boolean, default `false` (hidden) | Master toggle: mask classified/sensitive data in the text. |
| `anonymizeChar` | single character, default `█` | Mask character; `"SSN: 064 70 6733"` becomes `"SSN: ███████████"`. |
| `anonymizeAll` | boolean, default `false` | Collapse masked runs to a fixed length (`"SSN: ***"` instead of `"SSN: ***********"`). |

### Combined provider selectors (`services.all.json`)

Combines services into single selectable types for pipelines that pick one provider per slot:

| Field | Combo | Default |
|-------|-------|---------|
| `all.preprocessor` | `preprocessor` | `preprocessor_langchain` |
| `all.embedding` | `embedding` | `embedding_transformer` |
| `all.store` | `store` | `qdrant` |
| `all.llm` | `llm` | `openai` |

---

### Google access helper (`google_access.py`)

A single reader that turns a Google tool node's `access` enum and capability toggles into one resolved object: the OAuth scopes to request, plus the write/destructive gates the node's tool functions check at invoke time.

`resolve_google_access(config, spec)` resolves a node config against a per-API `AccessSpec` and returns a `GoogleAccess` with the granted tier, scopes, `can_write`, and gate flags. Tool functions then call `require_write(op)` and `require_flag(name, op)`, which raise `GoogleAccessError` when the operation is not enabled.

Behavior to know:

- A blank or omitted `access` value falls back to the spec's default tier; any other non-string value raises.
- `can_write` is derived from the granted scopes (a tier is writable if at least one scope does not end in `.readonly`), so it cannot drift from the actual grant.
- Gate flags are strict: only an explicit boolean `true` enables a gated operation. A present non-bool value (`"false"`, `1`, `"no"`) raises rather than coercing, and a missing flag defaults to off.

Bundled specs:

| Spec | Tiers (default in bold) | Gate flags |
|------|--------------------------|------------|
| `GMAIL` | `readonly` / **`modify`** / `send` | none (permanent delete needs the full `https://mail.google.com/` scope, which no tier grants; `gmail.modify` only trashes) |
| `DRIVE` | `readonly` / **`write`** | `allowPublicSharing`, `allowHardDelete` |
| `SHEETS` | `readonly` / **`write`** | none |
| `DOCS` | `readonly` / **`write`** | none |
| `CALENDAR` | `readonly` / **`write`** | `allowDelete` |
| `SLIDES` | `readonly` / **`write`** | none |
| `PEOPLE` | `readonly` / **`write`** (contacts write + directory read-only) | `allowDelete` |

---

### Running the tests

```bash
pytest nodes/test/core/test_google_access.py -v
```

## Limitations

The Local File System service reads local paths and is marked for filesystem access, security-sensitive use, non-remote execution, and non-SaaS deployment. Run pipelines that use it where the intended files are locally accessible; it is not available in hosted RocketRide deployments and cannot be moved to a remote execution host.

## Notes

The internal Word indexer, ZIP Creation, and null endpoint are protocol-bearing engine services but are not normal user-selectable nodes. The `core` directory also contains reusable JSON field fragments; those fragments are included in the generated schema but do not themselves register pipeline protocols.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### `services.all.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `all.embedding` |  | **Embedding** | `"embedding_transformer"` |
| `all.llm` |  | **LLM** | `"openai"` |
| `all.preprocessor` |  | **Preprocessor** | `"preprocessor_langchain"` |
| `all.store` |  | **Vector Store** | `"qdrant"` |

### `services.common.anonymize.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `anonymize` | `boolean` | **Anonymize Classified Information**<br/>Enable it if you want to mask any sensitive data in the text. If you leave it disabled, the text will be output as it is.<br/><br/>For example, if you enable it, then the text "SSN: 064 70 6733" will become "SSN: ***********". If you disable it, the text will remain "SSN: 064 70 6733". | `false` |
| `anonymizeAll` | `boolean` | **Anonymize All Data**<br/>Enable it if you want to collapse to the fixed length any sensitive data in the text.<br/><br/>For example, if you enable it, then the text "SSN: 064 70 6733" will become "SSN: ***". If you disable it, the text will remain "SSN: ***********". | `false` |
| `anonymizeChar` | `string` | **Anonymization Character**<br/>Specify a character that will mask any sensitive data in the text.<br/><br/>For example, if you specify the characher "*", then the text "SSN: 064 70 6733" will become "SSN: ***********". If you specify the character "?" the text will become "SSN: ???????????". | `"█"` |

### `services.common.aws.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `aws.accessKey` | `string` | **Access key**<br/>This is a key which gives access to your AWS resources. It is provided by the service provider. It is used to sign the requests you send to Amazon S3. |  |
| `aws.region` | `string` | **Region**<br/>This is defined and provided by the service provider. | `""` |
| `aws.secretKey` | `string` | **Secret key**<br/>This is a key used to access the AWS services. |  |

### `services.common.gcp.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `gcp.authType` | `string` | **Authentication Type**<br/>Choose how to authenticate to Google Cloud Platform. | `"adc"` |
| `gcp.projectId` | `string` | **Project ID**<br/>Optional: Specify the Google Cloud Project ID explicitly. Leave blank to infer from credentials. |  |
| `gcp.serviceAccountKey` | `string` | **Service Account Key JSON**<br/>Upload the JSON key file for your Google Cloud service account. |  |

### `services.common.google.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `google.adminEmail` | `string` | **Administrator E-mail**<br/>Enter the email address of a Google Workspace administrator.<br/><br/>This email should belong to a user with administrative privileges in your Google Workspace domain. |  |
| `google.authType` | `string` | **Authentication Type** | `"service"` |
| `google.customerId` | `string` | **Customer ID**<br/>Enter your Google Workspace Customer ID.<br/><br/>This unique identifier is assigned to your organization by Google. It is used to specify the particular Google Workspace domain you want to manage. |  |
| `google.oAuthButton` | `string` | **Login with Google** |  |
| `google.serviceKey` | `string` | **Service Account Key File**<br/>Upload the JSON key file for your Google Workspace service account.<br/><br/>This file contains the credentials necessary to authenticate API requests. |  |
| `google.userToken` | `string` | **Access Token**<br/>It is a long term token that allows you to get new access tokens to access the Google API. |  |

### `services.common.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `DTC.exclude` | `array` | **Provide the path to exclude** |  |
| `DTC.exclude.path` | `string` | **Exclude path** |  |
| `DTC.features` | `object` | **What features do you want?**<br/>Please be advised that selecting additional features will increase the time it takes to scan your data. |  |
| `DTC.include` | `array` | **Provide the path to your data** |  |
| `DTC.include.path` | `string` | **Include path** |  |
| `Pipe.exclude` | `array` | **Provide the path to exclude** |  |
| `Pipe.exclude.path` | `string` | **Exclude path** |  |
| `Pipe.features` | `object` | **What features do you want?**<br/>Please be advised that selecting additional features will increase the time it takes to scan your data. |  |
| `Pipe.include` | `array` | **Provide the path to your data** |  |
| `Pipe.include.path` | `string` | **Include path** |  |
| `actions` | `object` |  |  |
| `estimation` |  | **Cost estimations** |  |
| `estimation.accessCost` | `number` | **Access cost**<br/>The egress cost per MB to recall a file. | `0` |
| `estimation.accessDelay` | `number` | **Access delay**<br/>Elapsed time before access to a file starts. (For example: S3 could be 0 second delay, while Glacier could be hours. | `0` |
| `estimation.accessRate` | `number` | **Access rate**<br/>Time required to recall a file in MB per second. | `0` |
| `estimation.storeCost` | `number` | **Store cost**<br/>The cost per MB to store a file for a month. | `0` |
| `exclude` | `array` | **Exclude paths** |  |
| `exclude.path` | `string` | **Exclude path** |  |
| `hideForm` | `boolean` |  | `true` |
| `include` | `array` | **Include paths** |  |
| `include.classify` | `boolean` | **Enable Classification**<br/>Classification will assign each file to one or more classification policies. Once enabled, all supported files will be classified into one or more of the activated classification policies. | `false` |
| `include.index` | `boolean` | **Enable Indexing**<br/>Indexing will allow for full-text search of all processed files. Once enabled, all supported files will be scanned and indexed as they are processed.<br/>Once Index is enabled, other parameters like OCR and classify could be enabled too. | `false` |
| `include.ocr` | `boolean` | **Enable OCR**<br/>Optical Character Recognition (OCR) will convert typed or handwritten text found in images into text.Once enabled, all image files such as jpgs will have text extracted for use in classification and search. | `false` |
| `include.path` | `string` | **Include path** |  |
| `include.permissions` | `boolean` | **Enable Permissions**<br/>Permissions allow gathering of file ownerships and permissions from all connected and scanned sources. | `false` |
| `include.signing` | `boolean` | **Content Signature**<br/>Content Signature executes a hash algorithm on the content of every object to generate a "signature". Identical signatures indicate identical content and are an effective method to detect duplicate objects. | `true` |
| `include.vectorize` | `boolean` | **Enable AI Embeddings**<br/>AI embeddings make text content accessible to AI technologies like semantic relevancy and generative AP chants.<br/>Once AI embeddings are enabled, other parameters like OCR and classify could be enabled too. | `false` |
| `source.mode` | `string` |  | `"Source"` |
| `storePath` | `string` | **Store path**<br/>This path defines the exact specific folder in the filesystem.<br/><br/>Format for Windows : C:\foldername (for local filesystem) or \\file.core.net\foldername (for shared folders)<br/><br/>Format for Linux : /file.core.net/foldername<br/><br/>Format for AWS/S3 : bucketname/foldername<br/>Format for Azure blob : containername/foldername<br/>Format for SharePoint: sitename/drivename/foldername<br/>Format for onedrive: account/foldername |  |
| `sync` | `boolean` |  | `true` |
| `target.mode` | `string` |  | `"Target"` |
| `url` | `string` | **URL**<br/>URL to connect to the service. E.g: https://[dnsname].com | `"https://"` |

### `services.common.llm.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `llm.cloud.apikey` | `string` | **API key (Token)**<br/>Enter your API key or token |  |
| `llm.cloud.location` | `string` | **Location**<br/>LLM server location |  |
| `llm.cloud.modelSource` | `string` | **Model source** |  |
| `llm.cloud.project` | `string` | **Project (Organization)**<br/>LLM project or organization name |  |
| `llm.local.serverbase` | `string` | **LLM URL**<br/>Base url the model is hosted under. | `"http://localhost:11434/v1"` |

### `services.common.microsoft.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `microsoft.authType` | `string` | **Authentication Type** | `"service"` |
| `microsoft.clientId` | `string` | **Client ID**<br/>Application (client) ID of your Entra app registration. |  |
| `microsoft.clientSecret` | `string` | **Client Secret**<br/>Client secret of your Entra app registration. The app needs Microsoft Graph application permissions for this service, with admin consent granted. |  |
| `microsoft.oAuthButton` | `string` | **Login with Microsoft** |  |
| `microsoft.tenantId` | `string` | **Tenant ID**<br/>Enter your Microsoft Entra ID tenant (directory) ID.<br/><br/>Found in the Azure portal under Microsoft Entra ID > Overview. |  |
| `microsoft.userPrincipalName` | `string` | **Acting User (UPN)**<br/>User principal name (e-mail) the app acts as. App-only Graph calls target /users/{upn}; this is required for App authentication. |  |
| `microsoft.userToken` | `string` | **Access Token**<br/>It is a long term token that allows you to get new access tokens to access the Microsoft Graph API. |  |

### `services.common.remote.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `remote.apikey` | `string` | **API key**<br/>Enter your API key |  |
| `remote.host` | `string` | **Host** | `"pipe.rocketride.ai"` |
| `remote.local.mode` | `string` |  | const: `"local"` |
| `remote.port` | `number` | **Port** | `5565` |
| `remote.profile` | `string` | **Processing Mode** | `"local"` |
| `remote.provider` | `string` |  | const: `"remote"` |
| `remote.remote.mode` | `string` |  | const: `"remote"` |

### `services.common.vector.json`

| Field | Type | Description | Default |
|---|---|---|---|
| `vector.apikey` | `string` | **API key**<br/>Enter your API key |  |
| `vector.cloud.host` | `string` | **Host**<br/>Enter the server IP address e.g. Localhost |  |
| `vector.cloud.port` | `number` | **Port**<br/>Enter the port number |  |
| `vector.collection` | `string` | **Collection**<br/>Enter the name of the collection | `"ROCKETRIDE"` |
| `vector.host` | `string` | **Host**<br/>Enter the server IP address e.g. Localhost |  |
| `vector.local.grpc_port` | `number` | **gRPC Port**<br/>Enter the port number |  |
| `vector.local.host` | `string` | **Host**<br/>Enter the server IP address e.g. Localhost |  |
| `vector.local.port` | `number` | **Port**<br/>Enter the port number |  |
| `vector.port` | `number` | **Port**<br/>Enter the port number |  |
| `vector.score` | `number` | **Retrieval Score**<br/>Minumum retrieval score | `0.7` |
| `vector.top_k` | `integer,string` | **Top K**<br/>Chroma only: overrides the caller's retrieval limit in either direction (raising or lowering it) for semantic and keyword search; an integer or integer string from 1 to 1000, and when left unset the caller's own limit applies. |  |
| `vectorizer.embedding` |  | **Embedding** |  |
| `vectorizer.store` |  | **Vector Store** |  |

### Local File System (`services.filesys.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `Pipe.exclude` |  | Example Path: /Users/usr/Documents/product-images/* |  |
| `Pipe.filesys.source.parameters` |  |  |  |
| `Pipe.include` |  | Example Path: /Users/usr/Documents/product-images/* |  |
| `exclude` |  | This path defines the paths excluded for Scan, Index, Classify and OCR. By default, its empty.<br/><br/>Format for Windows : C:\foldername (for local filesystem) or \\file.core.net\foldername (for shared folders)<br/><br/>Format for Linux : /file.core.net/foldername |  |
| `excludeEnableGlobal` | `boolean` | **Exclude typical OS files and directories** | `true` |
| `excludeExternalDrives` | `boolean` | **Exclude external drives** | `true` |
| `excludeSymlinks` | `boolean` | **Exclude symlinks** | `true` |
| `filesys.source.parameters` |  | **Parameters** |  |
| `include` |  | This path defines the paths included for Scan, Index, Classify and OCR. By default, its empty.<br/><br/>Format for Windows : C:\foldername (for local filesystem) or \\file.core.net\foldername (for shared folders)<br/><br/>Format for Linux : /file.core.net/foldername |  |

### Fingerprinter (`services.hash.json`)

_No configuration fields._

### Word indexer (`services.indexer.json`)

_No configuration fields._

### Local File System (`services.null.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `null.source.parameters` |  | **Parameters** |  |

### Parser (`services.parse.json`)

_No configuration fields._

### ZIP Creation (`services.zip.json`)

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/core)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Fingerprinter

Route: /nodes/core/hash

---
title: Fingerprinter
date: 2026-04-11
sidebar_position: 1
---

<head>
  <title>Fingerprinter - RocketRide Documentation</title>
</head>

## What it does

Generates a deterministic fingerprint (hash) of each document's content as it passes through the pipeline. The hash is computed from the raw or normalized text, so identical content always produces the same fingerprint regardless of metadata. Use it for deduplication, content tracking, and identity verification before indexing.

**Lanes:** `data` → `data`

## Configuration

None.


---

# Parser

Route: /nodes/core/parser

---
title: Parser
date: 2026-04-11
sidebar_position: 1
---

<head>
  <title>Parser - RocketRide Documentation</title>
</head>

## What it does

Extracts structured content from a wide variety of document types. The Parser automatically identifies embedded content and routes it to the appropriate output lane, making text, tables, images, audio, and video accessible for downstream processing.

> **⚠️ Provenance limitation — not for audit-grade extraction.** Output is flattened to Markdown: page boundaries, bbox/polygon coordinates, and the table-HTML cell grid are dropped, so cell-level provenance and coordinate-based review cannot be reconstructed. Do not use this node where every value must trace back to its exact source cell (e.g. financial-table / regulatory extraction). For structure-preserving parsing that retains table HTML plus page and coordinate data, use the **`datalab_parse`** node instead.

**Lanes:**

| Lane in | Lane out | Description             |
| ------- | -------- | ----------------------- |
| `data`  | `text`   | Extracted plain text    |
| `data`  | `table`  | Extracted tables        |
| `data`  | `image`  | Extracted images        |
| `data`  | `audio`  | Extracted audio streams |
| `data`  | `video`  | Extracted video streams |

## Configuration

None.


---

# Currency Convert (Explicit)

Route: /nodes/currency_convert_explicit

# currency_convert_explicit

A RocketRide filter node that converts structured monetary facts at a rate and
date you explicitly supply. Pick it when a financial pipeline needs a
reproducible, auditable conversion step rather than a live exchange-rate lookup
or a node that only labels currencies.

## What it does

The node reads and re-emits the `answers` lane. For a fact whose configured
currency field matches the source currency, it preserves the original fact,
adds a `converted` amount and currency, and appends a provenance entry with the
rate, date, and source/target currencies. It never fetches rates or contacts a
network service, so the result depends only on the stated configuration.

Input may be one JSON fact object or a list of fact objects. Plain text, scalar
JSON, non-fact objects, invalid amounts, and facts in another currency pass
through unchanged, making this a safe opt-in step after structured extraction
or normalization.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `answers` | `answers` | Convert matching JSON fact records and forward every input record once. |

## Configuration

Set the source and target codes, state the conversion rate deliberately, then
align the amount and currency field names with the fact schema produced
upstream. The default profile supplies EUR-to-USD field names and a neutral
rate, but there is only one profile and these individual fields are what tailor
the conversion.

### Source and target currency

**Source currency** selects which facts are eligible; matching is
case-insensitive. **Target currency** is written exactly as configured into the
new `converted.currency` value. Keep both codes non-empty: if either is empty,
the node logs a warning and all answers pass through unchanged. Change the
field names below if an upstream extractor uses names other than `amount` and
`currency`.

### Conversion rate and rate date

**Conversion rate** is the multiplier in `target = source × rate`; it is not
retrieved or inferred. Supply the rate used by the relevant reporting policy
and record its applicable ISO-8601 date in **Rate date** so it is retained in
the provenance entry. A rate that cannot be interpreted as a finite number
causes a warning and leaves all answers unchanged rather than failing the run.

### Amount and currency fields

**Amount field** and **Currency field** name the keys to read from each fact.
The amount may be an integer, float, decimal-compatible string, or `Decimal`;
booleans and non-finite values are not monetary amounts and are left
unchanged. A missing field, non-string currency, or non-matching source
currency also leaves that fact untouched.

### Rounding decimals

**Rounding decimals** controls the fractional digits in `converted.amount` and
defaults to 2. Results use decimal arithmetic and round half-up, which avoids
binary floating-point conversion effects before the final JSON number is
written. Use 0 for whole-unit results or increase it, up to 10 in the
configuration schema, when the downstream fact contract needs more precision.

## Notes

### Output and provenance

The original amount and currency are never modified. The node creates a new
top-level `converted` object and adds a provenance object whose `op` is
`currency_convert_explicit`. An existing provenance list is copied and
appended to; a non-list existing value is preserved as the first item of a new
list. A later conversion therefore replaces the `converted` block but retains
earlier provenance entries.

### Answer forwarding

The node suppresses the engine's default immediate forward, collects converted
payloads for the input object, then writes each one at closing. This prevents
duplicates while preserving the distinction between a JSON answer and plain
text that merely looks like JSON. The node is experimental.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `currency_convert_explicit.amount_field` | `string` | **Amount field**<br/>The fact field holding the numeric amount to convert. | `"amount"` |
| `currency_convert_explicit.currency_field` | `string` | **Currency field**<br/>The fact field holding the currency code. | `"currency"` |
| `currency_convert_explicit.decimals` | `integer` | **Rounding decimals**<br/>Number of fractional digits for the converted amount (rounded half-up). | `2` |
| `currency_convert_explicit.profile` | `string` | **Conversion**<br/>Explicit currency conversion configuration | `"default"` |
| `currency_convert_explicit.rate` | `number` | **Conversion rate**<br/>The stated multiplier applied to the source amount (target = source × rate). Supply the rate deliberately; nothing is fetched. | `1` |
| `currency_convert_explicit.rate_date` | `string` | **Rate date**<br/>The date the rate applies to (ISO 8601, e.g. 2026-06-30). Recorded in the conversion provenance. | `""` |
| `currency_convert_explicit.source_currency` | `string` | **Source currency**<br/>Currency code to convert FROM (e.g. EUR). Only facts tagged with this currency are converted; case-insensitive. | `"EUR"` |
| `currency_convert_explicit.target_currency` | `string` | **Target currency**<br/>Currency code to convert TO (e.g. USD). | `"USD"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/currency_convert_explicit)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# ClickHouse

Route: /nodes/db_clickhouse

# db_clickhouse

A RocketRide database node for asking natural-language questions of ClickHouse
with an LLM, either on pipeline lanes or through agent tools. Choose it when
your data is in ClickHouse and you need its native-protocol connection.

## About ClickHouse

ClickHouse is the database product this node connects to. This implementation
uses the `clickhouse-sqlalchemy` dialect with the `clickhouse-driver` backend
over ClickHouse's native TCP protocol.

## What it does

On the `questions` lane, the node gives its reflected database schema and
optional database description to the connected LLM, asks it for a `SELECT`,
validates that query with `EXPLAIN`, and sends the result to the requested
`table`, `text`, or `answers` lane. It is also an agent tool node, so an agent
can retrieve data, inspect the startup-reflected schema, generate SQL, or—when
explicitly enabled—run raw SQL. Unlike a write-oriented relational database
node, its declared lanes contain no data-ingestion input.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used to craft SQL queries from questions |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `table` | Send query results as a Markdown table. |
| `questions` | `text` | Send the result as text. |
| `questions` | `answers` | Send the result as an answer. |

## As a tool

The registered tool names are bare method names; this node declares no
configurable server-name prefix.

| Function | Description |
| --- | --- |
| `get_data` | Generate a safe `SELECT` from a question and execute it. |
| `get_schema` | Return the schema reflected when the node started. |
| `get_sql` | Generate a safe `SELECT` without executing it. |
| `execute` | Run raw SQL, bypassing LLM translation and the safety check. |
| `begin` | Open a transaction and return its session ID. |
| `commit` | Commit and close a transaction session. |
| `rollback` | Roll back and close a transaction session. |
| `dialect` | Return `{ "dialect": "clickhouse" }`. |

`get_data` and `get_sql` require a non-empty `question`; `get_data` accepts an
optional `limit`, defaulting to 250 and clamped to 1–25,000. `get_schema`
accepts an optional `table`; an unknown table returns an `error` field, while
omitting it returns all reflected tables. `get_data` returns `{valid, rows,
sql, row_limit}` on success; a non-database question returns `{valid: false,
answer}`, and a query execution failure returns `{valid: false, error, sql,
rows: []}`.

`execute` requires non-empty `sql` and optionally accepts a transaction
`session_id` plus positional values for `$1`, `$2`, and so on. It returns
`{rows, affected_rows}`. `begin` takes no arguments and returns `{session_id}`;
`commit` and `rollback` require that ID and return `{ok: true}`. These four
write-capable operations fail when **Allow direct query execution** is off;
unknown or expired session IDs also fail. Invalid tool input raises an error.

## Configuration

Start with the default connection values, then set the database endpoint and
target table. Most question-answering setups need the host, credentials,
database, and a useful database description; the generated schema below is the
complete field reference.

### Database description

This text is added to every LLM SQL-generation request alongside the reflected
schema. Describe the data's purpose, meanings, and conventions when names
alone are ambiguous—for example, explain whether `amount` is a gross or net
value. Change it when queries choose the wrong interpretation; it does not
replace the actual table and column information collected at startup.

### ClickHouse host and TLS

With TLS off, a host without an explicit port uses ClickHouse's native default
of 9000. Turn TLS on for a TLS endpoint: the node adds `secure=true` to the
native DSN and supplies port 9440 if no port is present. Keep TLS off for a
plaintext local server. User, password, and database are URL-encoded when the
connection string is built, so reserved characters in those values are safe.

### Target database and table

The database selects the connection's database; the table identifies the
target table whose schema is also cached at startup. Set both to the exact
objects the LLM should use. The node reflects the full database for LLM context,
but it warns if this particular target table does not exist. Since the declared
lanes do not accept data for insertion, create and populate ClickHouse tables
outside this node.

### Max validation attempts

The default of five gives the LLM several chances to repair a query rejected by
`EXPLAIN`. Lower it when fast failure matters more than recovery; raise it for
complex schemas that need another correction cycle. The runtime clamps this
setting to 1–20. After the final rejected attempt it returns the last generated
result, so `EXPLAIN` retries improve generated SQL but do not guarantee that a
subsequent execution will succeed.

### Allow direct query execution

Leave this off by default. When on, the `execute`, `begin`, `commit`, and
`rollback` tools can bypass LLM translation and the generated-query safety
check, and raw statements use a transaction that commits on success. Enable it
only for trusted callers that need writes or dialect-specific SQL; use
`get_data` for ordinary read-only retrieval.

## Limitations

This node declares the `noremote` capability, so it cannot run in a remote
execution environment. It requires network reachability to the ClickHouse
server from the environment where the pipeline runs.

## Notes

### Generated-query safety

For LLM-generated SQL, the node only accepts `SELECT`, optionally preceded by
`EXPLAIN`. It strips comments, checks every semicolon-separated statement, and
rejects CTEs plus `SELECT ... INTO OUTFILE` or `INTO DUMPFILE`. It validates
each safe candidate with `EXPLAIN` and feeds database errors to the LLM for the
next attempt.

### ClickHouse schema details

The ClickHouse driver reports no foreign keys, so reflected schema output has
columns and best-effort primary keys but no foreign-key relationships.

## Upstream docs

- [ClickHouse documentation](https://clickhouse.com/docs/)


<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `clickhouse.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw SQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue SQL directly. | `false` |
| `clickhouse.database` | `string` | **Database name**<br/>Name of database | `"default"` |
| `clickhouse.db_description` | `string` | **Database description**<br/>What is this database used for? Describe its content and purpose, this helps the LLM generate more accurate queries. | `""` |
| `clickhouse.host` | `string` | **ClickHouse host**<br/>Host name or IP address of the ClickHouse server, optionally including a native-protocol port (e.g. localhost:9440). Defaults to port 9000 when none is given. | `"localhost"` |
| `clickhouse.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated SQL | `5` |
| `clickhouse.password` | `string` | **Password**<br/>Password to connect to the ClickHouse server |  |
| `clickhouse.profile` | `string` |  | `"default"` |
| `clickhouse.table` | `string` | **Table name**<br/>Name of table | `"table"` |
| `clickhouse.tls` | `boolean` | **Use TLS**<br/>Connect over TLS. Required for managed services such as ClickHouse Cloud (native TLS port 9440 is assumed when the host has no explicit port). Leave OFF for a plaintext local server on port 9000. ClickHouse-specific, MySQL/PostgreSQL nodes do not expose this. | `false` |
| `clickhouse.user` | `string` | **User**<br/>User to connect to the ClickHouse server | `"default"` |

## Dependencies

- `clickhouse-sqlalchemy` `==0.3.2`
- `clickhouse-driver` `==0.2.9`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/db_clickhouse)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Firestore

Route: /nodes/db_firestore

# db_firestore

A RocketRide database node that reads and writes documents in a Google Cloud Firestore (Native mode) database. Pick it when a pipeline's agent needs to fetch or persist individual JSON documents in Firestore.

## About Google Cloud Firestore

Firestore is Google Cloud's managed document database. It stores JSON-like
documents in named collections, addresses each document by an ID within its
collection, and is offered in a Native mode alongside a Datastore-compatible
mode. Applications on Google Cloud commonly use it for application state and
user-facing data.

## What it does

The node opens a Firestore client against one project and database when the pipeline starts and keeps it open for the run. It has no data lanes and no invoke connections: its whole surface is two document operations offered to a connected agent. Reach for it when the work is document-at-a-time reads and writes against Firestore; it does not expose collection queries, listing, or deletes.

Configuration names a default collection, so an agent can be pointed at one collection and then call the tools without repeating it.

## As a tool

The registered tool names are the bare method names below; an agent catalog namespaces them by the pipeline component id, not by the services.json `prefix`.

| Function | Description |
| --- | --- |
| `get_document` | Fetch a single document by ID and return its fields. |
| `set_document` | Create or merge a document from a JSON object. |

`get_document` requires `document_id` and accepts an optional `collection`. It returns the document's fields as an object. A document that does not exist, an unconnected client, or a Firestore failure comes back as an object with a single `error` key rather than as a raised exception.

`set_document` requires `data`, a JSON object to store, and accepts optional `collection` and `document_id`. With a `document_id` it writes with merge semantics, so listed fields are updated and unlisted fields on an existing document are left alone. With no `document_id` Firestore generates one and the returned message names it. Both success and failure are returned as a plain sentence, so an agent should read the returned text to confirm the write.

For both functions, omitting `collection` falls back to the collection configured on the node. Leaving both empty targets an empty collection name and the call fails.

## Configuration

Pick the credential mode, then name the collection the agent should work in; the database ID only matters for projects with more than one Firestore database. Nothing else needs to be set for a single-database project.

### Collection

The collection the tools use when a call does not pass its own `collection`. It has no default, and configuration validation warns when it is left blank — leaving it blank is only reasonable when every tool call will name its own collection. Set it to the one collection this node instance is responsible for, for example `orders`; an agent then calls `get_document` with just a `document_id`.

### Database ID

The Firestore database this node connects to, defaulting to `(default)`, which is the name Google Cloud gives the first database created in a project. Change it only when the project holds several named Firestore databases and this node should target one of the others. A blank value is treated as `(default)`.

## Authentication

The node uses RocketRide's shared Google Cloud credential resolution and requests the `https://www.googleapis.com/auth/datastore` scope.

**Authentication Type** selects between Application Default Credentials and Service Account JSON. Application Default Credentials is the default and suits an engine running on Google Cloud infrastructure with an attached service account, or a host where ADC has already been provisioned. Selecting Service Account JSON reveals **Service Account Key JSON**, an upload field for the key file; it is stored as a secret and is required in that mode.

**Project ID** is optional. Left blank, the project is taken from the uploaded key file or from the ambient default credentials; set it explicitly when the credentials could resolve to a different project than the one holding the data.

Grant the credential enough IAM to read and write the documents the agent will touch. Listing collections is not required — see the startup probe under Notes.

## Limitations

Declared `noremote`: this node runs on the local engine host only and is not
available for remote execution. It needs network access to Google Cloud APIs,
and, in Application Default Credentials mode, to whatever credential source the
host provides.

## Notes

### Startup probe

After connecting, the node tries to read one entry from the project's collection listing as a connectivity check. Listing collections needs broader IAM than document reads and writes, so a failure here is logged as a warning and startup continues — a narrowly scoped service account that can only touch documents is a supported setup. A warning from this probe is therefore not by itself proof that the tools will fail.

### Missing dependency

The node imports `google-cloud-firestore` at load time and raises an explicit `ImportError` when the package is unavailable, rather than failing later on the first tool call.

## Upstream docs

- [Firestore documentation](https://cloud.google.com/firestore/docs)
- [google-cloud-firestore Python client](https://cloud.google.com/python/docs/reference/firestore/latest)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `firestore.collection` | `string` | **Collection**<br/>The Firestore collection to query or insert into. |  |
| `firestore.database` | `string` | **Database ID**<br/>The Firestore database ID. Usually '(default)'. | `"(default)"` |
| `firestore.profile` | `string` |  | `"default"` |

## Dependencies

- `google-auth` `>=2.23.3`
- `google-cloud-firestore` `>=2.13.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/db_firestore)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Hotdata

Route: /nodes/db_hotdata

# db_hotdata

A database and tool node backed by [Hotdata](https://www.hotdata.dev/) — use a fresh ephemeral database per pipeline run or attach separate runs to one shared database.

## What it does

By default, the first time the node is used it provisions a Hotdata database with a TTL, and `endGlobal` deletes it. That makes it the right choice for scratch work — pull a dataset in, join and aggregate it, emit the answer, leave nothing behind. It can also attach to an existing database when data needs to be shared across pipeline runs.

As a pipeline node it takes natural-language questions on the `questions` lane and emits results on `table` / `text` / `answers`, and it loads structured rows arriving on the `answers` lane. As a tool node an agent drives it directly.

It needs a connected LLM (the `llm` control connection) to translate questions into SQL, in the same way `db_postgres` and `rocketride_sql` do.

## Example pipelines

`examples/db_hotdata.pipe` — Chat → Hotdata → Answers/Table, with Anthropic bound as the SQL-writing LLM.

An agent flow: `load_data` the rows, `build_index` on the text column, then `get_data` with a question, or `execute` a query using `bm25_search`.

## Connections

| Connection | Required | Description |
| ---------- | -------- | ----------- |
| `llm`      | yes      | LLM used to generate SQL from natural language |

## Lanes

| Lane in     | Lane out  | Description                                                                                                                                                 |
| ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `questions` | `table`   | Natural-language question, answered and emitted as a Markdown table                                                                                        |
| `questions` | `text`    | Natural-language question, answered and emitted as text                                                                                                     |
| `questions` | `answers` | Natural-language question, answered and emitted as an answer payload                                                                                        |
| `answers`   | —         | JSON rows, loaded into the configured table. A fenced or prose-wrapped object is unwrapped; `{"rows": [...]}` becomes N rows; text carrying no JSON raises  |

## As a tool

| Function      | Description                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `load_data`   | Load rows, or a previous query result by `result_id`, into a table. Creates the table if needed              |
| `get_data`    | Answer a plain-language question. The bound LLM writes the SQL; failures are retried with the error fed back |
| `get_sql`     | Generate the SQL for a question without running it                                                           |
| `execute`     | Run one raw read-only SQL statement. Gated by `allow_execute`                                                |
| `get_schema`  | Live tables and columns from `information_schema`                                                            |
| `build_index` | Build a `bm25`, `vector` or `sorted` index on a column                                                       |
| `dialect`     | The full SQL dialect briefing — read this before writing SQL by hand                                         |

## Configuration

Set an API key and workspace ID on the node, or export `HOTDATA_API_KEY` and `HOTDATA_WORKSPACE`. The default endpoint is `https://api.hotdata.dev`.

Wire an LLM to the node's `llm` control connection — without one, natural-language querying cannot work. See `examples/db_hotdata.pipe`.

## Limitations

- **The SQL surface is read-only.** `INSERT`, `UPDATE`, `DELETE` and all DDL are rejected by the server. `load_data` is the only way to get data in, and it uploads rather than issuing SQL.
- `allow_execute` is an application-level gate on raw SQL. It is **not** write protection — the SQL surface rejects writes regardless. It exists to keep untrusted callers from running expensive scans, which are billed per TB scanned.
- **`load_data` is a write path, and the SQL read-only guarantee does not cover it.** `replace`, `update` and `delete` modes overwrite or remove existing rows, so they are disabled unless `allow_destructive_load` is on. Without that gate an agent asked to "delete the bad rows" will route around the SQL guard by calling `load_data` with `mode=replace`. Default is append/upsert only.
- One statement per call; `SHOW TABLES` and `SHOW COLUMNS` error, so use `information_schema` or `DESCRIBE`.
- **Ephemeral data is destroyed when the run ends.** The configured TTL is only a fallback for a crashed engine. An attached database is left in place instead, and the `ttl` field does not apply to it — its expiry is whatever the creator set, so a database created with no TTL is never cleaned up automatically.
- With a Database API Token, both `GET /v1/databases/{id}` and `DELETE /v1/databases/{id}` return 403, so attached databases rely on their TTL for cleanup.
- **Writes to one table are serialized server-side.** A second concurrent writer is refused
  with `409 RESOURCE_LOCKED` ("retry shortly"). The node replays those — the request is
  rejected before doing any work, so a replay cannot double-load — but a shared table is a
  queue, not a parallel write path. Measured against the live API, 8 simultaneous appends to
  one table landed 1 without retries and 12 of 12 with them, the slowest taking 6 attempts
  over 12s. Publish latency grows with the number of concurrent publishers; give each agent
  its own table, or its own database, when that matters.
- Rate limits are dynamic and unpublished; the node honours `Retry-After` and retries shed requests, but a sustained overload surfaces as an error.
- Connections to external warehouses are configured on the Hotdata side, outside RocketRide's view.

## Notes

### Publishing into a shared database

Do not instruct an agent to call `load_data` on a shared database. Measured across two
model families, an agent that reasons correctly and reports the right answer still skips
that call most of the time — it is the third step of an instruction list, and models drop
it. Roughly one in four wrote the row.

Wire the agent's `answers` output into this node's `answers` lane instead. The row is
loaded because the graph says so, not because the model remembered. The agent keeps its
own private database as a thinking tool, and the shared table is written by the pipeline.

The agent's final answer has to be the row: an object, a list of objects, or a
single-key wrapper like `{"rows": [...]}`. Code fences and a sentence of preamble are
tolerated. Anything with no JSON in it raises rather than leaving an empty table.

### Sharing a database between runs

Create the database **outside any pipeline** — over the REST API, by whoever owns the demo — then pass its ID to every run through `database_id` (or `HOTDATA_DATABASE_ID`). Those runs attach to it instead of creating their own, so their agents can share tables and query results.

Do not let a pipeline run create the database and then hand its ID to later runs. A database this node created is owned by that run and is deleted at its teardown, so the ID goes stale the moment the creating run ends — and a consumer still attached to it loses the database underneath itself. Sharing only works reliably when the database outlives every run that uses it, which means nothing that deletes it can be one of them.

An attached database is never deleted by this node; managing its lifetime, including its TTL, is the caller's responsibility.

**Indexes on a shared database have to be built outside the node.** `build_index` needs the database's `default_connection_id`, and a Database API Token gets 403 from `GET /v1/databases/{id}`, so an attached run cannot read it back — the node raises a clear error rather than guessing. There is no pipeline run that can do it either: a database created outside a pipeline has no owning run, and a database a run created is deleted when that run ends. So whoever creates the shared database keeps the `default_connection_id` from the create response and builds indexes itself:

```http
POST /v1/connections/{default_connection_id}/tables/{schema}/{table}/indexes
{ "index_name": "...", "columns": ["..."], "index_type": "bm25" }
```

Build the index after the table exists and has rows. `bm25_search` and `vector_search` then work normally from every attached run — it is only index _creation_ that is closed to them.

**An attached run assumes the default schema is `main`.** The same 403 that hides the connection ID hides the database's real default schema, so the node cannot read it back. If the owning run created the database with a different default schema, pass `schema` explicitly on `load_data` — otherwise rows land in `main.<table>` and the owning run's queries against its own schema will not see them.

#### One table, one row shape

A shared table is written by more than one producer, and Hotdata requires every write to carry the table's full column set — a column left out of an append would be dropped, so the server refuses instead. `load_data` recovers automatically: it reads the table's live columns and fills the absent ones with null before retrying.

That recovery only works while the absent columns are textual. A numeric or temporal column that is null in **every** row of a batch is inferred as text, and the server will not re-type it. There is no payload that satisfies both rules, so give each kind of record its own table rather than sharing one table between records of different shapes.

### SQL dialect

Hotdata runs **Apache DataFusion 54 behind the PostgreSQL parser dialect**. Treat that as "Postgres syntax, DataFusion semantics and function library" — not as Postgres. Call the `dialect` tool for the full briefing; the essentials:

- Postgres syntax works: `::` casts, CTEs, window functions, `DISTINCT ON`, `ILIKE`, `INTERVAL`.
- Unquoted identifiers fold to lowercase — double-quote any name with uppercase or spaces.
- The function library is DataFusion's. **No JSON/JSONB operators** (`->`, `->>`, `jsonb_*`), no `pg_catalog`, no `to_number` or `age()`. Use `arrow_typeof`, `arrow_cast`, `date_bin`, `approx_percentile_cont` instead.
- Types are Arrow types (`Utf8`, `Int64`, `Timestamp`, `Decimal128`) — there is no native JSON, UUID or ENUM.
- Names are three-part `catalog.schema.table`; this database's own catalog is `default`.
- Search uses engine functions: `bm25_search(table, column, query)`, `vector_search(table, column, query)`, and `vector_distance(column, query)` for `ORDER BY`. Build the matching index first with `build_index`.

### Troubleshooting

| Symptom                                           | Cause                                                                                                   |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apikey is required` / `workspace_id is required` | Neither the config field nor the env var is set                                                         |
| `raw SQL execution is disabled`                   | Turn on `allow_execute`, or use `get_data` instead                                                      |
| `only one statement per call`                     | Hotdata rejects semicolon-separated batches                                                             |
| Unknown function errors                           | A Postgres-only function that DataFusion lacks — check `dialect`                                        |
| `still shedding load after ...s (HTTP 429)`       | Sustained back-pressure; retry later or reduce concurrency                                              |
| `still locked by another writer after ...s`       | Too many agents appending to one table for the job timeout; raise `job_timeout_secs` or split the table |
| Empty results from a fresh run                    | The database starts empty every run — `load_data` first                                                 |

## Upstream docs

- [Hotdata API reference](https://www.hotdata.dev/docs/api-reference) and [OpenAPI spec](https://www.hotdata.dev/openapi.yaml)
- [Core concepts](https://www.hotdata.dev/docs/core-concepts-overview)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `hotdata.allow_destructive_load` | `boolean` | **Allow destructive loads**<br/>Permit load_data to use replace, update or delete modes, which overwrite or remove existing rows. Off by default: load_data is append/upsert only, so an agent cannot destroy data another pipeline step loaded. | `false` |
| `hotdata.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit trusted callers to submit raw read-only SQL. | `false` |
| `hotdata.api_url` | `string` | **API URL**<br/>Hotdata API base URL. Leave empty for https://api.hotdata.dev. | `""` |
| `hotdata.apikey` | `string` | **API Key**<br/>Hotdata API key. | `""` |
| `hotdata.async_after_ms` | `integer` | **Run asynchronously after (milliseconds)**<br/>Wait this long before a query continues as an asynchronous job. | `5000` |
| `hotdata.database_id` | `string` | **Existing database ID**<br/>Leave empty to create a fresh ephemeral database per run (the default). Set an existing database ID so agents in separate pipeline runs share one database. An attached database is never deleted by this node, and indexes cannot be built on one. | `""` |
| `hotdata.db_description` | `string` | **Database description**<br/>Schema and domain hints for natural-language SQL generation. | `""` |
| `hotdata.job_timeout_secs` | `integer` | **Job timeout (seconds)**<br/>Maximum time to wait for an asynchronous query. | `300` |
| `hotdata.max_attempts` | `integer` | **Maximum attempts**<br/>Maximum SQL-generation attempts. | `3` |
| `hotdata.max_execute_rows` | `integer` | **Maximum execute rows**<br/>Maximum rows returned by raw SQL execution. | `25000` |
| `hotdata.table` | `string` | **Table**<br/>Table that rows arriving on the answers lane are loaded into. Created on first use. | `"pipeline_data"` |
| `hotdata.ttl` | `string` | **Database lifetime**<br/>Crash-safety expiry for a database this node creates. Ignored when an existing database ID is set, since that database's lifetime belongs to whoever created it. | `"24h"` |
| `hotdata.workspace_id` | `string` | **Workspace ID**<br/>Hotdata workspace ID. | `""` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/db_hotdata)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# MySQL

Route: /nodes/db_mysql

# db_mysql

A RocketRide database node for asking natural-language questions of MySQL and
inserting structured answers into a MySQL table. Choose it when your pipeline
needs both MySQL query tools and an `answers`-lane destination for rows.

## About MySQL

MySQL is the database product this node connects to. This implementation uses
SQLAlchemy with the PyMySQL driver to connect and reflect MySQL table schemas.

## What it does

On the `questions` lane, the node gives a connected LLM its startup-reflected
schema and optional database description, validates generated `SELECT` queries
with `EXPLAIN`, and emits results as a table, text, or answer. On the `answers`
lane, it inserts structured rows into the configured table, creating that table
from the first incoming data shape when necessary. It is also an agent tool
node, making it a better fit than a pipeline-only SQL destination when an agent
must decide what to retrieve or needs gated raw SQL.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used to craft SQL queries from questions |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `answers` | — | Insert structured answer data into the configured table. |
| `questions` | `table` | Send query results as a Markdown table. |
| `questions` | `text` | Send the result as text. |
| `questions` | `answers` | Send the result as an answer. |

## As a tool

The registered tool names are bare method names; this node declares no
configurable server-name prefix.

| Function | Description |
| --- | --- |
| `get_data` | Generate a safe `SELECT` from a question and execute it. |
| `get_schema` | Return the schema reflected when the node started. |
| `get_sql` | Generate a safe `SELECT` without executing it. |
| `execute` | Run raw SQL, bypassing LLM translation and the safety check. |
| `begin` | Open a transaction and return its session ID. |
| `commit` | Commit and close a transaction session. |
| `rollback` | Roll back and close a transaction session. |
| `dialect` | Return `{ "dialect": "mysql" }`. |

`get_data` and `get_sql` require a non-empty `question`; `get_data` accepts an
optional `limit`, defaulting to 250 and clamped to 1–25,000. `get_schema`
accepts an optional `table`; an unknown table returns an `error` field, while
omitting it returns all reflected tables. `get_data` returns `{valid, rows,
sql, row_limit}` on success; a non-database question returns `{valid: false,
answer}`, and a query execution failure returns `{valid: false, error, sql,
rows: []}`.

`execute` requires non-empty `sql` and optionally accepts a transaction
`session_id` plus positional values for `$1`, `$2`, and so on. It returns
`{rows, affected_rows}`. `begin` takes no arguments and returns `{session_id}`;
`commit` and `rollback` require that ID and return `{ok: true}`. These four
write-capable operations fail when **Allow direct query execution** is off;
unknown or expired session IDs also fail. Invalid tool input raises an error.

## Configuration

Start with the default connection values, then set the database endpoint and
target table. The generated schema below is the complete field reference;
describe the data well and leave direct execution disabled unless a trusted
caller truly needs it.

### Database description

This text is added to every LLM SQL-generation request alongside the reflected
schema. Describe the data's purpose, meanings, and conventions when names
alone are ambiguous—for example, explain whether `amount` is a gross or net
value. Change it when queries choose the wrong interpretation; it does not
replace the actual table and column information collected at startup.

### Connection and target table

Set the host, user, password, database, and table to the MySQL server and
target table. User, password, and database are URL-encoded before the PyMySQL
DSN is built, so reserved characters in those values are safe. The node
reflects the complete database for query context at startup, then separately
checks the target table: if it is absent, it warns and waits to create it from
the first incoming `answers` data.

### Max validation attempts

The default of five gives the LLM several chances to repair a query rejected by
`EXPLAIN`. Lower it when fast failure matters more than recovery; raise it for
complex schemas that need another correction cycle. The configuration field
allows 1–20, while the runtime accepts any positive configured number and
falls back to five for an invalid value. After the final rejected attempt it
returns the last generated result, so retries improve generated SQL but do not
guarantee that a subsequent execution will succeed.

### Allow direct query execution

Leave this off by default. When on, the `execute`, `begin`, `commit`, and
`rollback` tools can bypass LLM translation and the generated-query safety
check. A raw call without a session uses a transaction that commits on success;
use `begin` followed by `execute` with its session ID when several statements
must share a transaction. Enable it only for trusted callers that need writes
or dialect-specific SQL; use `get_data` for ordinary read-only retrieval.

## Limitations

This node declares the `noremote` capability, so it cannot run in a remote
execution environment. It requires network reachability to the MySQL server
from the environment where the pipeline runs.

## Notes

### Generated-query safety

For LLM-generated SQL, the node only accepts `SELECT`, optionally preceded by
`EXPLAIN`. It strips comments, checks every semicolon-separated statement, and
rejects CTEs plus `SELECT ... INTO OUTFILE` or `INTO DUMPFILE`. It validates
each safe candidate with `EXPLAIN` and feeds database errors to the LLM for the
next attempt. If the LLM decides a question is not a database query, its text
answer is emitted instead of executing SQL.

### Inserting answers

Incoming JSON rows are matched to the target schema case-insensitively; missing
schema columns become `NULL`, and unknown incoming keys are ignored. Lists and
dictionaries are serialized as JSON strings and booleans as `0` or `1`. For a
new table, the node adds an auto-increment `id` primary key and infers integer,
float, datetime, or text columns; short text becomes `VARCHAR(255)` and longer
text becomes `TEXT`.

### Connection checks and transactions

Saving configuration probes the server with `SELECT 1` using a five-second
connect timeout and reports the driver error when it cannot connect. The
runtime connection pool allows 30 concurrent connections. It retains at most
20 transaction sessions by default, rolls idle ones back after five minutes,
and rolls all open sessions back when the pipeline closes.

## Upstream docs

- [MySQL documentation](https://dev.mysql.com/doc/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `mysql.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw SQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue SQL directly. | `false` |
| `mysql.database` | `string` | **Database name**<br/>Name of database | `"database"` |
| `mysql.db_description` | `string` | **Database description**<br/>What is this database used for? Describe its content and purpose, this helps the LLM generate more accurate queries. | `""` |
| `mysql.host` | `string` | **MySQL host**<br/>Host name or IP address of the MySQL server | `"localhost"` |
| `mysql.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated SQL | `5` |
| `mysql.password` | `string` | **Password**<br/>Password to connect to the MySQL server |  |
| `mysql.profile` | `string` |  | `"default"` |
| `mysql.table` | `string` | **Table name**<br/>Name of table | `"table"` |
| `mysql.user` | `string` | **User**<br/>User to connect to the MySQL server | `"root"` |

## Dependencies

- `pymysql` `>=1.2.0`
- `cryptography`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/db_mysql)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# PostgreSQL

Route: /nodes/db_postgres

# db_postgres

A RocketRide database node that answers natural-language questions against a PostgreSQL database and inserts structured pipeline data into tables.

## What it does

Plays two roles in a pipeline. As a pipeline node, it receives natural-language questions on the `questions` lane, asks a connected LLM to translate them into SQL, executes the query, and emits the results; it also accepts structured data on the `answers` lane and inserts it into the configured table. As a tool node, agents call it directly through three functions: `get_data`, `get_schema`, and `get_sql`.

Uses SQLAlchemy with the psycopg2 driver (`psycopg2-binary`). The connection string is built as `postgresql+psycopg2://user:password@host/database`; user, password, and database are URL-encoded so reserved characters (`@`, `/`, `#`, `:`) are safe, and the host may carry an explicit port (e.g. `localhost:5433`).

Safety defaults: only `SELECT` statements are permitted for queries (whitelist check, see Notes), generated SQL is validated with `EXPLAIN` against the live database before execution, and raw SQL execution (`QuestionType.EXECUTE`) is disabled by default via `allow_execute`.

The same implementation also ships as a Supabase preset (`services.supabase.json`, protocol `db_supabase://`): Supabase is managed Postgres, so it is a branded configuration, not separate code.

## Example pipelines

**Chat with your database**

`chat → db_postgres → response_answers + response_table`

<div align="center">

![The PostgreSQL node on the canvas answering questions from chat, with an LLM connected](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

`llm_anthropic` is wired to `llm`. Natural-language questions arrive from
chat; PostgreSQL returns conversational answers and tabular results on the
two response lanes.

**Structured extraction into a table**

`webhook → ocr → extract_data → db_postgres`

Scanned documents are OCR'd, `extract_data` structures the fields, and the
rows arrive on this node's `answers` lane — the table is auto-created on
first insert.

**Agent with database access**

An agent (e.g. `agent_deepagent`) with this node connected as a tool. The
agent calls `get_schema` to learn the shape of the data, then `get_data` to
answer questions — with the SELECT-only whitelist keeping it read-safe.

## Connections

| Connection | Required | Description                                    |
| ---------- | -------- | ---------------------------------------------- |
| `llm`      | yes      | LLM used to generate SQL from natural language |

## Lanes

| Lane in     | Lane out | Description                                                    |
| ----------- | -------- | -------------------------------------------------------------- |
| `questions` | `table`  | Translate question to SQL, execute, return as a markdown table |
| `questions` | `text`   | Translate question to SQL, execute, return as text             |
| `questions` | `answers`| Translate question to SQL, execute, return as answers          |
| `answers`   | —        | Parse structured rows and insert into the table                |

If the LLM decides a question is not a database query, its text response is emitted instead of query results.

Two special question types are handled on the `questions` lane:

- **`QuestionType.DIALECT`**: emits `{"dialect": "postgres"}` on the `answers` lane so SDK callers can branch on the underlying engine.
- **`QuestionType.EXECUTE`**: runs the question text as raw SQL (read or write, no LLM, no safety check). Gated by `allow_execute`; when disabled the request is logged and dropped. `SELECT` results are capped at 25,000 rows; write statements report `affected_rows`.

## As a tool

When connected to an agent, the node exposes three functions. The registered tool names are the bare method names below; the services.json `prefix` is a URL/path prefix and never appears in a tool name. An agent catalog namespaces each tool by the pipeline component id (for example `<component-id>.get_data`).

| Tool         | Description                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `get_data`   | Natural language to SQL, executes it, returns rows plus the generated SQL (default 250 rows, max 25,000 via `limit`) |
| `get_schema` | Returns tables, columns, types, primary keys, and foreign keys, for the full database or one table                |
| `get_sql`    | Natural language to SQL only, no execution                                                                        |

`get_data` and `get_sql` return `valid: false` with an `error` (unsafe SQL) or an `answer` (the question was not a database query) when no executable query is produced.

### Transactions

Three additional tool functions support explicit database transactions. All three require `allow_execute=true` on the node (the same gate as `QuestionType.EXECUTE`); requests are silently dropped when the gate is off.

| Tool       | Input                     | Returns                    | Description                                                                                                   |
| ---------- | ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `begin`    | _(none)_                  | `{"session_id": "<id>"}`   | Opens a new transaction and reserves a dedicated connection for it. Returns a `session_id` that callers must thread through subsequent `execute`, `commit`, and `rollback` calls. |
| `commit`   | `{"session_id": "<id>"}` | `{"ok": true}`             | Commits all statements made on the given session, releases the held connection back to the pool, and removes the session entry. |
| `rollback` | `{"session_id": "<id>"}` | `{"ok": true}`             | Discards all statements made on the given session, releases the held connection, and removes the session entry. |

To run a statement inside an open transaction, pass the `session_id` returned by `begin` as the `session_id` field of an `execute` tool call. Statements without a `session_id` run on a fresh auto-commit connection and are not part of any transaction.

Sessions are server-scoped: the `session_id` is only valid on the node instance that issued it. Idle sessions are reaped automatically after a configurable timeout; the engine also closes all sessions when the pipeline is torn down.

The Python SDK exposes these as `client.database.begin_transaction()`, `client.database.commit()`, and `client.database.rollback()`. The TypeScript SDK exposes them as `client.database.beginTransaction()`, `client.database.commit()`, and `client.database.rollback()`.

To run a statement **inside** an open session from the SDK, pass the `session_id` (and any positional `$1..$n` `params`) to the database query method — Python `client.database.query(token=..., sql=..., session_id=..., params=[...])`, TypeScript `client.database.query({ token, sql, sessionId, params })`. Parameters are bound server-side. A `query(...)` call without a `session_id` runs on a fresh auto-commit connection and is not part of any transaction.

## Configuration

Connection settings (host, user, password, database, table) plus three fields
that shape query behavior, detailed below. The single `default` profile presets
`database` to `postgres`.

### Database description

Free-text description of what the database contains and what it is used for,
included in the prompt when the LLM generates SQL. This is the highest-leverage
field on the node: a specific description ("orders and customers for the EU
webshop; `orders.status` is an enum of pending/shipped/returned") measurably
improves query accuracy, while a blank one leaves the LLM guessing from column
names alone. Update it when the schema's meaning changes, not just its shape.

### Max validation attempts

How many times the node re-asks the LLM after `EXPLAIN` rejects the generated
SQL (default 5). Raise it for complex schemas where first attempts often fail;
lower it to fail fast in latency-sensitive pipelines. Each retry feeds the
database error back to the LLM, so attempts are not blind retries.

### Allow direct query execution

Gates raw SQL execution (`QuestionType.EXECUTE` and the transaction tools).
Off by default — leave it off unless a trusted application explicitly needs to
issue SQL directly, because enabled callers bypass both the LLM translation
and the SELECT-only safety check.

## Limitations

Declared `noremote`: this node runs on the local engine host only and is not
available for remote execution. It needs a direct network path to the
PostgreSQL server it queries.

## Notes

### SQL safety & validation

Generated SQL passes two gates before execution:

1. **Whitelist check**: only statements beginning with `SELECT` (optionally prefixed by `EXPLAIN`) are allowed; everything else is rejected. Comments are stripped first so comment-based bypasses are neutralised, every statement in a multi-statement input is checked, `SELECT ... INTO OUTFILE/DUMPFILE` is blocked, and `WITH` (CTE) is deliberately excluded because PostgreSQL accepts CTE-into-mutation (e.g. `WITH x AS (...) DELETE ...`).
2. **`EXPLAIN` validation**: the query is validated against the live database. If `EXPLAIN` rejects it, the rejected SQL and the database error are fed back to the LLM for a corrected query, up to `max_attempts` times (default 5).

Insert operations never go through SQL generation; they use the `answers` lane.

### Data insertion

Rows arriving on the `answers` lane are inserted into the configured `table`:

- The table is auto-created from the shape of the first batch if it does not exist (column types inferred from the data).
- Incoming keys are matched to columns case-insensitively (`UserName` maps to `username`); schema columns missing from the data are inserted as `NULL`.
- Lists and dicts are serialised as JSON strings; booleans are stored as `0`/`1`.
- Each batch is inserted in a single transaction: on failure it is rolled back and the error re-raised.

### Supabase preset

`services.supabase.json` registers the same node as Supabase (`db_supabase://`); its tools carry the same bare names. The connection is encrypted over TLS. Operational notes:

- **Use the Supavisor pooler** from the Supabase dashboard (Connect button): `aws-0-<region>.pooler.supabase.com:6543` (transaction) or `:5432` (session). It works over IPv4.
- The **direct connection** (`db.<project-ref>.supabase.co:5432`) is IPv6-only and will fail to resolve on networks without IPv6.
- For the pooler, the user must include your project ref: `postgres.<project-ref>`. Without the suffix the pooler returns `no tenant identifier`. For the direct connection it is just `postgres`.
- The database password comes from your Supabase project (Project Settings -> Database); the database name defaults to `postgres`.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### PostgreSQL (`services.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `postgresdb.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw SQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue SQL directly. | `false` |
| `postgresdb.database` | `string` | **Database name**<br/>Name of database | `"postgres"` |
| `postgresdb.db_description` | `string` | **Database description**<br/>What is this database used for? Describe its content and purpose, this helps the LLM generate more accurate queries. | `""` |
| `postgresdb.host` | `string` | **PostgreSQL host**<br/>Host name or IP address of the PostgreSQL server, optionally including a port (e.g. localhost:5433) | `"localhost"` |
| `postgresdb.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated SQL | `5` |
| `postgresdb.password` | `string` | **Password**<br/>Password to connect to the PostgreSQL server |  |
| `postgresdb.profile` | `string` |  | `"default"` |
| `postgresdb.table` | `string` | **Table name**<br/>Name of table | `"table"` |
| `postgresdb.user` | `string` | **User**<br/>User to connect to the PostgreSQL server | `"postgres"` |

### Supabase (`services.supabase.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `postgresdb.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw SQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue SQL directly. | `false` |
| `postgresdb.database` | `string` | **Database name**<br/>Name of database (Supabase default is 'postgres') | `"postgres"` |
| `postgresdb.db_description` | `string` | **Database description**<br/>What is this database used for? Describe its content and purpose, this helps the LLM generate more accurate queries. | `""` |
| `postgresdb.host` | `string` | **Supabase host**<br/>From the Supabase dashboard (Connect button), including the port. Recommended: the Supavisor pooler (works over IPv4) -> aws-0-<region>.pooler.supabase.com:6543 (transaction) or :5432 (session). The Direct connection (db.<project-ref>.supabase.co:5432) is IPv6-only and will fail to resolve on networks without IPv6. |  |
| `postgresdb.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated SQL | `5` |
| `postgresdb.password` | `string` | **Password**<br/>Database password from your Supabase project (Project Settings -> Database) |  |
| `postgresdb.profile` | `string` |  | `"default"` |
| `postgresdb.table` | `string` | **Table name**<br/>Name of table | `"table"` |
| `postgresdb.user` | `string` | **User**<br/>Database user. For the pooler (recommended) it MUST include your project ref: postgres.<project-ref>, without the .<project-ref> suffix the pooler returns 'no tenant identifier'. For the direct connection it is just: postgres | `"postgres"` |

## Dependencies

- `psycopg2-binary` `==2.9.12`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/db_postgres)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Depth Estimation

Route: /nodes/depth_estimate

# depth_estimate

A RocketRide image node that estimates a dense depth map from one image and emits both a colorized map and summary statistics. Choose it when you need per-pixel depth information instead of object bounding boxes or an image caption.

## About Depth Anything V2

Depth Anything V2 is the monocular depth-estimation model used by this node. The node loads the configured model identifier and optional revision, using the supplied V2 Small profile by default.

## What it does

The node buffers each input image, estimates depth, and restores the dense result to the input's original dimensions. It can send a JPEG colorized depth map on the `image` lane and the depth array's minimum, maximum, and mean as JSON on the `text` lane. Choose it for a frame-wide depth signal; pair it with Object Detection when you need boxes as well as rough distance context for detected objects.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | JPEG colorized depth map, where red is near and blue is far. |
| `image` | `text` | JSON depth statistics: `min`, `max`, and `mean`. |

## Configuration

The supplied V2 Small profile is the default model, leaving the maximum input edge as the main performance and detail control. The implementation uses its default model if no model is configured.

### Max input edge (px)

This setting limits the input image's long edge before depth inference; its default is `1024`. Lower it when local inference needs less work and memory, accepting less spatial detail in the predicted depth; raise it when sharper depth boundaries matter. The node upsamples the dense result to the original dimensions after inference. At runtime, malformed values use the default and all values are clamped to the range `256`–`4096`.

## Requirements

With a model server configured, inference runs there. Otherwise it runs locally on CPU, Apple Silicon (MPS), or CUDA, and a device lock serializes local model use. Output values are relative depth, not a calibrated physical distance.

## Notes

### Output and failures

The colorized map is encoded as JPEG after the depth result is restored to the original image size. The emitted statistics are calculated from that restored depth array. If image decoding or depth inference fails, the node logs a warning, drops the frame, and does not emit image or text output for it.

## Upstream docs

- [Depth Anything V2 Small model page](https://huggingface.co/depth-anything/Depth-Anything-V2-Small-hf)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `depth_estimate.maxEdge` | `number` | **Max input edge (px)**<br/>Downscale input so the long edge <= this value before inference; dense output is upsampled back to original. Lower = faster + less VRAM, higher = sharper depth. | `1024` |
| `depth_estimate.profile` | `string` | **Model** | `"v2-small"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/depth_estimate)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Object Detection

Route: /nodes/detect

# detect

A RocketRide image node that detects objects in each input frame and emits labeled bounding boxes plus an annotated image. Choose it when downstream work needs object locations; use Segmentation when it needs pixel masks instead.

## About RF-DETR and MM-Grounding-DINO

RF-DETR and MM-Grounding-DINO are the two detection backends exposed by this node. RF-DETR is the default common-object profile, while MM-Grounding-DINO is the prompt-driven open-vocabulary profile; the node supplies the selected backend, threshold, prompt, and optional revision to its detector.

## What it does

The node buffers each completed image stream, runs the selected detector, and can emit the detections as JSON and a JPEG annotated with boxes and labels. RF-DETR detects the configured profile's common-object class set; MM-Grounding-DINO lets the prompt define the desired objects or attributes. Choose it as a per-frame gate or whenever location, confidence, and centroid data matter, rather than choosing Caption for a prose description or Segmentation for masks.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | JPEG copy of the source image annotated with detection boxes and labels. |
| `image` | `text` | JSON array of detections with `label`, `score`, `box`, and `centroid`. |

## Profiles

Default: **RF-DETR — Common Objects (COCO, 80 classes, default)** (`rfdetr`).

| Profile | Backend | Use |
| --- | --- | --- |
| RF-DETR — Common Objects (COCO, 80 classes, default) **(default)** | `rfdetr` | Closed-set common-object detection. |
| MM-Grounding-DINO — Open-Vocabulary (any prompt) | `mmgdino` | Prompt-driven open-vocabulary detection. |

## Configuration

Start with the RF-DETR profile for the provided common-object detector. Switch to MM-Grounding-DINO when the sought object must be expressed in a prompt, then set a threshold to control which matched regions reach downstream nodes.

### Model

The RF-DETR profile is the default and supplies the `rfdetr` engine. The MM-Grounding-DINO profile supplies the `mmgdino` engine and makes the detection prompt visible in the configuration panel. If the runtime receives an unrecognized engine value, it logs a warning and uses its default backend instead; use one of the supplied profiles to avoid silently falling back.

### Detection prompt

This field is required for the prompt-driven MM-Grounding-DINO backend: startup fails when that backend has no non-empty prompt. It accepts period- or comma-separated terms, such as `person . car . dog`; the runtime splits either separator into the classes it passes to the detector. Use it to name objects or describe attributes such as `red car` or `person in a hat`. The field description explicitly warns that spatial relationships are not supported, so a prompt such as `the car on the left` can return all cars rather than only the left one.

### Confidence threshold

The threshold is a `0.0`–`1.0` minimum confidence for including a detection, with `0.3` as the default in both supplied profiles. Raise it when low-confidence boxes are creating noisy downstream work; lower it when missed candidates matter more than precision. If the runtime receives a non-numeric or out-of-range value, it logs a warning and uses its detector default threshold.

## Requirements

With a model server configured, detection runs there. Otherwise it runs locally on CPU, Apple Silicon (MPS), or CUDA, and a device lock serializes local inference.

## Notes

### Output and failures

The image output draws lime rectangles and labels containing each detection's label and score. If image decoding, detection, or output generation fails for a frame, the node logs a warning, drops that frame, and emits no image or text output for it.

## Upstream docs

- [RT-DETR fallback model page](https://huggingface.co/PekingU/rtdetr_r50vd)
- [Grounding DINO model page](https://huggingface.co/IDEA-Research/grounding-dino-tiny)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `detect.profile` | `string` | **Model** | `"rfdetr"` |
| `detect.prompt` | `string` | **Detection prompt**<br/>Example: "person . car . dog" (period or comma-separated list) or "red car" / "person in a hat" (described object). Returns all matching regions. Matches objects and attributes — not spatial relationships, so "the car on the left" returns all cars, not just the left one. |  |
| `detect.threshold` | `number` | **Confidence threshold**<br/>Minimum confidence score (0.0–1.0) to include a detection | `0.3` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/detect)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Segmentation

Route: /nodes/detect_segment

# detect_segment

A RocketRide image node that produces pixel-level instance or semantic segmentation, with a JSON result and an annotated image. Choose it when a bounding box alone is not enough and a downstream step needs the pixels belonging to each object or class region.

## About Hugging Face

This node's service definition identifies its Mask2Former engines as HuggingFace-native. Its configured profiles select pretrained Mask2Former models for object-instance and scene-region segmentation.

## What it does

The node consumes each image frame, runs the configured Mask2Former segmentation mode, and can emit both a JPEG overlay and a JSON mask payload. Instance mode returns separate masks, labels, scores, and boxes; semantic mode returns a per-pixel class map and class information. Use it instead of an object-detection node when the shape or extent of an object matters, rather than only its location.

## Lanes

| Lane in | Lane out | Description |
| ------- | -------- | ----------- |
| `image` | `image` | Annotated JPEG frame with translucent mask overlays; instance overlays also include boxes and labels. |
| `image` | `text` | JSON segmentation result: an instance list or a semantic-map object, according to the selected mode. |

## Profiles

Default: **Mask2Former — Object Instances (COCO, 80 classes, default)** (`mask2former-instance`).

| Profile | Mode | Default confidence threshold | Default max input edge |
| ------- | ---- | ---------------------------- | ---------------------- |
| Mask2Former — Object Instances (COCO, 80 classes, default) **(default)** | `instance` | `0.3` | `1024` px |
| Mask2Former — Scene Regions (ADE20K, 150 classes) | `semantic` | `0.0` | `1024` px |

## Configuration

Start with the profile that matches the kind of result a downstream node needs. The profile supplies a matching mode and engine; adjust the confidence and image-size controls only when the expected objects are missing, noisy, or too expensive to process.

### Mode and Engine

`instance` produces a separate mask for each detected object, while `semantic` produces a class map across the image. Keep the engine paired with its mode: the available instance and semantic engines are gated that way in the configuration. Pick instance mode for object-by-object handling, such as extracting individual people; pick semantic mode when classifying every pixel of a scene is more useful. An unrecognised mode falls back to the implementation default at startup.

### Confidence threshold

The threshold determines which masks are included, from `0.0` through `1.0`. The instance preset starts at `0.3`; raise it when low-confidence masks clutter the result, or lower it when a relevant object is being omitted. The semantic preset uses `0.0`, so its output retains all class assignments. Invalid threshold values are replaced with the implementation default rather than stopping the node.

### Max input edge (px)

Before inference, the node downscales an image whose long edge exceeds this value, then restores masks to the source dimensions for the overlay. The profiles use `1024` px. Lower it to reduce inference time and memory use on large frames; raise it when small boundaries need more detail, within the `256`–`4096` px range. Values outside that range are clamped at startup.

## Requirements

This node declares GPU capability and uses its configured transformer engine through a shared device lock when inference runs locally. Its profile metadata states that the engines can run through Transformers on CPU, MPS, or CUDA; use an accelerator when throughput or large images make CPU processing inadequate. The node also loads its declared dependencies before inference, including the mask decoder used to render returned masks.

## Notes

### Output and failures

The text and image outputs are produced only when those lanes have listeners. If image decoding or segmentation raises an error for a frame, the node logs a warning, drops that frame, and suppresses normal image forwarding rather than emitting a partial result.

## Upstream docs

- [Hugging Face Transformers documentation](https://huggingface.co/docs/transformers/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `detect_segment.engine` | `string` | **Engine**<br/>Backing engine. Gated by mode: instance -> mask2former-instance; semantic -> mask2former-semantic. | `"mask2former-instance"` |
| `detect_segment.maxEdge` | `number` | **Max input edge (px)**<br/>Downscale source so long edge <= this value before inference; masks are upsampled back to the source size. Lower = faster + less VRAM. | `1024` |
| `detect_segment.mode` | `string` | **Mode**<br/>Segmentation mode. instance: per-instance masks (default). semantic: per-pixel class map. Both use Mask2Former under the hood. | `"instance"` |
| `detect_segment.profile` | `string` | **Profile**<br/>Segmentation preset. Runs on CPU/MPS/CUDA via transformers. | `"mask2former-instance"` |
| `detect_segment.threshold` | `number` | **Confidence threshold**<br/>Minimum score (0.0-1.0) to include a mask | `0.3` |

## Dependencies

- `pycocotools`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/detect_segment)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Dictionary

Route: /nodes/dictionary

# dictionary

A RocketRide text-processing node that asks a connected LLM to turn text or table content into a glossary of company-specific terms. Choose it when downstream users or agents need concise definitions of internal vocabulary rather than a general structured-data extraction.

## What it does

The node accepts text or table content and sends each incoming chunk to its required LLM connection with a structured prompt (`expectJson: true`) and instructions to return a single JSON array of definitions. It writes one document for every returned definition; each document contains the JSON-serialized definition and is marked as non-table content. Use it instead of `extract_data` when the output should be a reusable vocabulary of terms and descriptions, not rows with a predefined schema.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used to extract and define terms. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `documents` | Emits one definition document for every item returned by the LLM. |

## Configuration

This node has no local configuration fields. Connect an LLM and supply text on its `text` lane; the same extraction path is also used when the runtime provides table content.

## Notes

### Definition output

The built-in prompt asks the LLM to include company-specific language, acronyms, and terms whose in-company meaning differs from common usage — including terms that are ambiguous. It always requests one JSON array: if the LLM response is valid JSON but is not an array, the node raises a descriptive `ValueError` before emitting any documents, and invalid JSON continues to surface the response parsing error. The example shape used by the prompt is `{\"term\": \"...\", \"description\": \"...\"}`, but the node serializes each returned object without imposing additional fields.

### Dependencies

The node has no Python package requirements of its own: it relies entirely on the separately installed AI module.

### Chunk metadata

The node resets its output `chunkId` for every input object, then increments it for each emitted definition. It writes `isTable: false` and `tableId: 0` even when the input arrived through the table-processing path, so downstream nodes receive glossary entries as ordinary documents.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/dictionary)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Image

Route: /nodes/embedding_image

# embedding_image

A RocketRide embedding node that turns image documents or image streams into vectors for a multimodal vector store; choose it when the source is an image rather than text or video.

## About Hugging Face

Hugging Face develops widely used open-source tooling and model repositories for machine learning. Its Transformers library provides common interfaces for loading and running pretrained models, including vision models.

## What it does

The node accepts image documents or a raw image stream and adds an `embedding` plus the producing `embedding_model`. Choose it over `embedding_transformer` for visual content and over `embedding_video` when frames have already been extracted. For the `documents` lane, every document must be an Image document; another type raises `ValueError`.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `documents` | `documents` | Decodes Image documents and enriches them with an embedding. |
| `image` | `documents` | Buffers a raw image stream and emits an embedded Image document. |

## Profiles

Default: **OpenAI - 16x16 - good performance, lower memory** (`openai-patch16`).

| Profile | Model | Context |
|---|---|---|
| `openai-patch16` *(default)* | `openai/clip-vit-base-patch16` | Default vision model. |
| `openai-patch32` | `openai/clip-vit-base-patch32` | Alternative CLIP profile. |
| `google16x224` | `google/vit-base-patch16-224` | ViT profile. |
| `custom` | User-provided | Enter a compatible Hugging Face model identifier. |

## Configuration

Choose a supplied profile for the corresponding bundled model; use Custom only when the exact model identifier is known to work with the implementation. The output vector shape comes from the chosen model, so select the same profile used when building the target vector index.

### Model

The default is `openai/clip-vit-base-patch16`. Model names containing `clip` use image features from the CLIP path; other names use the model output path. Change this only when the destination index and retrieval configuration can accommodate the new vector shape; a mismatch will make stored and query vectors incompatible.

## Requirements

The node declares GPU capability. Its embedding model is loaded through the model provider; the source does not define a CPU-only fallback, so provision a compatible model runtime when using this node.

## Notes

### Image stream output

On completion of an `image` stream, the node emits a base64-backed Image document and assigns a `chunkId`. Stream source details and the source stem are retained when supplied; documents on the `documents` lane retain their upstream provenance.

## Upstream docs

- [Hugging Face Transformers documentation](https://huggingface.co/docs/transformers)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `embedding.model` | `string` | **Model name**<br/>Hugging face model to use for embedding |  |
| `embedding.profile` | `string` | **Model**<br/>Embedding model | `"openai-patch16"` |

## Dependencies

- `transformers`
- `accelerate`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/embedding_image)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# OpenAI (Embedding)

Route: /nodes/embedding_openai

# embedding_openai

A RocketRide embedding node that turns document chunks and questions into OpenAI API vectors; choose it when both ingestion and retrieval should use the same hosted text embedding model.

## About OpenAI

OpenAI develops AI services and APIs. This node uses its embedding API through the `langchain-openai` integration to represent text as numeric vectors.

## What it does

The node adds an `embedding` and `embedding_model` to documents and questions. Choose it over `embedding_transformer` when the selected embedding model should be called through OpenAI rather than loaded as a local sentence transformer. Documents in one write are sent to `embed_documents` as a batch; questions use `embed_query`.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `documents` | `documents` | Embeds document chunks for storage. |
| `questions` | `questions` | Embeds questions for matching against stored vectors. |

## Profiles

Default: **Text Small - A highly efficient model** (`text-embedding-3-small`).

| Profile | Model | Context tokens |
|---|---|---|
| `text-embedding-3-small` *(default)* | `text-embedding-3-small` | 8,191 |
| `text-embedding-3-large` | `text-embedding-3-large` | 8,191 |
| `text-embedding-ada-002` | `text-embedding-ada-002` | 8,191 |
| `text-embedding-004` | `text-embedding-004` | 2,048 |
| `text-embedding-005` | `text-embedding-005` | 2,048 |
| `text-embedding-3-small-inference` | `text-embedding-3-small-inference` | 8,191 |
| `text-embedding-ada-002-v2` | `text-embedding-ada-002-v2` | 8,191 |
| `text-embedding-large-exp-03-07` | `text-embedding-large-exp-03-07` | 8,192 |
| `text-embedding-preview-0409` | `text-embedding-preview-0409` | 3,072 |

This node currently supports `text-embedding-3-small`, `text-embedding-3-large`,
and `text-embedding-ada-002`. The other declared profiles require LiteLLM
routing, which this node does not currently implement; selecting one sends its
model name to the OpenAI endpoint and fails during the startup probe.

## Configuration

Select the profile used for both document ingestion and question embedding. The wrapper reads the profile’s configured model and token limit, and probes the selected model with `dummy` at startup to discover the vector size; account for that small startup request.

### Model

The model value is passed to `OpenAIEmbeddings`. Keep the same profile for ingestion and querying the same vector index; changing it can change the vector representation and makes previously stored vectors unsuitable for new questions.

## Authentication

Set the secure `llm.cloud.apikey` field for the selected profile. RocketRide
resolves this field as `apikey` and passes it to `OpenAIEmbeddings`. If no
configured key is available, `langchain-openai` can fall back to the engine
process's `OPENAI_API_KEY` environment variable. The startup probe fails when
neither source provides a usable key.

## Upstream docs

- [OpenAI API documentation](https://platform.openai.com/docs)
- [langchain-openai documentation](https://python.langchain.com/docs/integrations/text_embedding/openai/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `openai_embed.model` | `string` | **Model name**<br/>OpenAI model to use for embedding |  |
| `openai_embed.profile` | `string` | **Model**<br/>OpenAI embedding model | `"text-embedding-3-small"` |

## Dependencies

- `openai`
- `langchain-openai`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/embedding_openai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Transformer

Route: /nodes/embedding_transformer

# embedding_transformer

A RocketRide embedding node that turns document chunks and questions into local sentence-transformer vectors; choose it when text must stay in the model runtime rather than use an external embedding API.

## About Hugging Face

Hugging Face develops open-source libraries and repositories for machine-learning models. Sentence Transformers is a model interface for creating sentence and passage embeddings used in semantic retrieval.

## What it does

The node embeds the `documents` and `questions` lanes, storing each result as a float list and recording the producing model. Choose it over `embedding_openai` when using a locally loaded sentence-transformer model and over the image or video embedders for text. Documents are buffered in groups of 64 and remaining documents flush when the input closes, while questions are encoded immediately.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `documents` | `documents` | Embeds document chunks. |
| `questions` | `questions` | Embeds questions for vector retrieval. |

## Profiles

Default: **miniLM - General use embeddings, good performance** (`miniLM`).

| Profile | Model | Context |
|---|---|---|
| `miniLM` *(default)* | `sentence-transformers/multi-qa-MiniLM-L6-cos-v1` | Default model. |
| `miniAll` | `sentence-transformers/all-MiniLM-L6-v2` | Alternative model. |
| `mpnet` | `sentence-transformers/multi-qa-mpnet-base-cos-v1` | Alternative model. |
| `custom` | User-provided | Enter a compatible Hugging Face model identifier. |

## Configuration

Start with `miniLM`; its vector size and maximum token count are read from the loaded model. Custom settings are relevant only when the model expects a different retrieval format or output shape.

### Model

Custom model names are passed to `SentenceTransformer`. Change the model only with a compatible downstream vector index, because the node writes the model’s vectors directly to documents and questions.

### Truncate dimensions

`truncate_dim` is passed to the model as `truncate_dim`; zero preserves its normal dimensionality. Set a positive value only when the selected model supports shorter embeddings and the vector store was created for that dimension; otherwise leave it at zero to avoid incompatible vectors.

### Document and query prefixes

The node prepends `document_prefix` to every document and `query_prefix` to every question before encoding. Leave both empty for models that do not require a role marker. For a model trained with separate passage and query prefixes, set the matching pair consistently during ingestion and retrieval; applying a prefix on only one side changes the representations being compared.

## Requirements

The node declares GPU capability. It loads a `SentenceTransformer` through the model provider; the source does not specify a CPU-only fallback, so provision the compatible model runtime.

## Upstream docs

- [Sentence Transformers documentation](https://www.sbert.net/)
- [Hugging Face documentation](https://huggingface.co/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `embedding.document_prefix` | `string` | **Document prefix**<br/>Prefix prepended to document text before encoding (e.g. 'search_document: ', 'passage: ') |  |
| `embedding.model` | `string` | **Model name**<br/>Hugging face model to use for embedding |  |
| `embedding.preprocessor` |  |  | `"preprocessor_langchain"` |
| `embedding.profile` | `string` | **Model**<br/>Embedding model | `"miniLM"` |
| `embedding.query_prefix` | `string` | **Query prefix**<br/>Prefix prepended to query text before encoding (e.g. 'search_query: ', 'query: ') |  |
| `embedding.truncate_dim` | `number` | **Truncate dimensions**<br/>Truncate embeddings to this dimensionality (0 = use model default) |  |

## Dependencies

- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/embedding_transformer)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Video

Route: /nodes/embedding_video

# embedding_video

A RocketRide embedding node that samples a video stream into embedded image documents; choose it when video needs frame-level retrieval rather than embedding a standalone image.

## About Hugging Face

Hugging Face provides open-source model tooling and model repositories. This node uses its vision-model interfaces to produce an embedding for each selected frame.

## What it does

The node buffers a video stream, extracts frames with OpenCV, and emits one Image document with an embedding per selected frame. Choose it over `embedding_image` when RocketRide must perform the frame extraction, and over text embedders for visual media. It is marked experimental and serializes shared model access with a lock.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `video` | `documents` | Emits embedded Image documents for sampled frames. |

## Profiles

Default: **OpenAI CLIP - 16x16 - good performance, lower memory** (`openai-patch16`).

| Profile | Model | Context |
|---|---|---|
| `openai-patch16` *(default)* | `openai/clip-vit-base-patch16` | Default frame model. |
| `openai-patch32` | `openai/clip-vit-base-patch32` | Alternative CLIP profile. |
| `google16x224` | `google/vit-base-patch16-224` | ViT profile. |
| `custom` | User-provided | Enter a compatible Hugging Face model identifier. |

## Configuration

Use the default model and sampling limits first. Frame count directly determines how many documents and model calls the node produces, so tune extraction for the retrieval granularity you actually need.

### Model

The default is `openai/clip-vit-base-patch16`; Custom accepts a model name. Choose a model compatible with the target vector index, because every emitted frame carries that model’s vector and model name.

### Frame extraction

Frames are sampled at `interval` seconds, starting at `start_time`. `duration` of zero continues to the end; otherwise the extraction window ends at `start_time + duration` and is clamped to the video length. Increase the interval or shorten the window for a coarse overview; decrease it for short visual events, accepting more documents and embedding work.

### Frame and file limits

`max_frames` defaults to 50 and zero removes that cap. `maxVideoSizeMB` defaults to 500; an oversized video is rejected with a warning and produces no output. Raise either limit only after sizing the worker memory and the downstream index for the added frames.

## Requirements

The node declares GPU capability and uses a vision model plus OpenCV. The source does not define a CPU-only fallback, so run it where the compatible model runtime is available.

## Notes

### Frame documents

Each output contains a base64 PNG Image, `embedding`, `embedding_model`, a frame number, and a timestamp. If the input provides stream details, source metadata and a `<video-stem>.frame<N>` name are retained. A missing reported frame rate falls back to 30 fps for timestamp calculation.

### Supported containers

MP4 (`video/mp4`), AVI (`video/x-msvideo`), QuickTime (`video/quicktime`), and WebM (`video/webm`). An unrecognized MIME type is still processed, treated as MP4.

## Upstream docs

- [Hugging Face Transformers documentation](https://huggingface.co/docs/transformers)
- [OpenCV documentation](https://docs.opencv.org/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `embedding.duration` | `number` | **Duration (in seconds) for frame extraction (0=end of video)** | `0` |
| `embedding.interval` | `number` | **Interval (in seconds) between frames**<br/>Time in seconds between extracted frames | `5` |
| `embedding.maxVideoSizeMB` | `number` | **Maximum video file size (MB)**<br/>Maximum allowed video file size in megabytes. Videos exceeding this limit will be rejected. | `500` |
| `embedding.max_frames` | `number` | **Maximum number of frames to extract (0=unlimited)**<br/>Limit the total number of frames extracted from the video. Set to 0 for unlimited. | `50` |
| `embedding.model` | `string` | **Model name**<br/>Hugging Face model to use for frame embedding |  |
| `embedding.profile` | `string` | **Model**<br/>Embedding model for video frames | `"openai-patch16"` |
| `embedding.start_time` | `number` | **Start time (in seconds) for frame extraction (0=beginning)** | `0` |

## Dependencies

- `transformers`
- `accelerate`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/embedding_video)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Data Extractor

Route: /nodes/extract_data

# extract_data

A RocketRide text-processing node that asks a connected LLM to extract configured columns from text, tables, or documents. Choose it when you need a consolidated table-shaped result from several chunks rather than a glossary or fact records with provenance.

## What it does

For each input chunk, the node gives the connected LLM the configured column names, types, and default values, then requests a JSON array of rows. It keeps the latest LLM response as the working table, supplies that table as context for later chunks, and asks the LLM to merge duplicates and fill empty fields. It consumes those intermediate answers and emits the final table only when the input object closes: as one JSON answer and/or one JSON document per row. Use `extract_facts` instead when extraction needs source provenance and an optional second validation pass.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used to extract configured field values. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `table` | `answers` | Emits the final extracted table as one JSON answer. |
| `table` | `documents` | Emits one JSON document for each row in the final table. |
| `text` | `answers` | Emits the final extracted table as one JSON answer. |
| `text` | `documents` | Emits one JSON document for each row in the final table. |
| `documents` | `answers` | Extracts from incoming documents and emits the final table as one JSON answer. |
| `documents` | `documents` | Extracts from incoming documents and emits one JSON document for each final row. |

## Configuration

Configure the fields the LLM should look for. The node has one hidden `default` profile, so most configuration consists of the field list rather than choosing among extraction modes.

### Fields

Provide between one and 32 fields. Each field has a column name, a type selected from the declared values, and an optional default value; the node passes all three to the LLM as extraction instructions. Use a column name that describes the value you want, even when that exact label is not expected in the source—the prompt explicitly allows the model to infer values from context. A blank column name or type does not stop the pipeline, but the node logs a warning and excludes that field from every extraction.

### Field types and defaults

The type communicates the expected shape to the LLM; use `text` for unstructured values, numeric and date/time types for values that should be recognized in those forms, and specialized types such as `email`, `url`, `phone`, or `json` when the value has that structure. The default value is also prompt context, not a post-processing guarantee: choose it only when it is a sensible fallback for a missing value. If the running table already has rows, the next prompt includes it and asks the LLM to merge duplicates and fill empty fields, so stable column names and compatible defaults make multi-chunk results more reliable.

## Notes

### Final output timing

The node calls `preventDefault` for each intermediate LLM answer, so downstream listeners do not receive a partial table after every chunk. It resets its accumulated table at the start of each input object. On close, it writes the full table only to output lanes that have listeners; document output contains JSON-serialized rows with non-table metadata.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `extract.column` | `string` | **Column**<br/>Name of column | `"column"` |
| `extract.defval` | `string` | **Default Value** | `""` |
| `extract.fields` | `array` |  |  |
| `extract.profile` | `string` |  | `"default"` |
| `extract.type` | `string` | **Type** | `"text"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/extract_data)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Fact Extractor

Route: /nodes/extract_facts

# extract_facts

A RocketRide text-processing node that extracts configured records from documents or tables, with optional LLM validation and source provenance. Choose it over `extract_data` when each emitted value needs a traceable source location or a second extraction check.

## What it does

The node buffers document and table context for an input object, then extracts one JSON record per logical record when that object closes. Its prompt includes the configured target fields and requires a `_provenance` object for every record. By default it sends the results through a second LLM prompt that rechecks the cited source, corrects or drops unsupported records, and attaches validation information. It emits the reconciled list as an answer and/or as one document per record. Use `extract_data` when a consolidated table is sufficient and there is no need to preserve per-record provenance or run a validator pass.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used for fact extraction and, when enabled, validation. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `table` | `answers` | Emits the reconciled fact list as one JSON answer. |
| `table` | `documents` | Emits one JSON document for each reconciled fact. |
| `documents` | `answers` | Extracts from incoming documents and emits the reconciled fact list as one JSON answer. |
| `documents` | `documents` | Extracts from incoming documents and emits one JSON document for each reconciled fact. |

## Configuration

Configure the target fields, then decide whether the second validation pass and provenance should be included. The node has one hidden `default` profile, so these choices apply directly to its extraction behavior.

### Fields

Provide between one and 32 target fields. Each field has a name, a type selected from the declared values, and an optional default value; the node places these in the LLM prompt. The extractor is instructed to infer a value from context when an exact field label is absent, so use names that express the facts you need rather than merely copying source headers. A field with a blank name or type is skipped at startup with a warning and is not available to the extractor or validator.

### Field types and defaults

The type tells the LLM how to interpret the target value. Use `text` for unconstrained values, numeric and date/time types for values that should be recognized in those forms, and specialized types such as `email`, `url`, `phone`, or `json` when their structure matters. The default value is prompt context, not a post-processing guarantee, so select one only when it is a sensible fallback for a missing fact. Keep types and defaults consistent with the source you expect to validate; the validator checks the extraction result against the same configured fields.

### Validate

Validation is on by default. With it enabled, the node runs a second prompt on the same LLM connection against the candidate records and source context. The validator can correct a value, repair its cited table location, lower its confidence, or remove a record that the source does not support. Turn it off when the extra prompt cost and latency are not worth the second check; in that mode the first-pass records are emitted without `_validation` annotations. If the validator returns no usable records, the node retains the first-pass candidates instead of discarding them.

### Include Provenance

This setting defaults to on. The extraction prompt asks for `page`, `table_id`, `row`, `col`, `source_text`, and `confidence` in `_provenance`; table records use the node's `[TABLE <id>]` fences and document inputs can carry `[Page N]` markers. Turn it off only when downstream consumers do not need source traceability, because the node removes `_provenance` from the final records after validation. It does not disable validation itself.

## Notes

### Buffered input and output

The node consumes incoming content with `preventDefault` and emits derived facts only on close, so downstream lanes never see its original input or partial LLM output. Table input is fenced with sequential table IDs. On the `documents` lane, documents marked `metadata.isTable` are sent to the table buffer; other content is buffered as free text, and a `page` metadata value is preserved in a page marker for the LLM. Document output serializes each fact as JSON; its `isTable` metadata is true when the fact's provenance has a table ID.

### Record shape

The built-in prompts request one object for each logical record, not a separate object for every target field. For table data, the extractor is told to treat the first row as a header and use a zero-based data-row index in provenance. The LLM supplies provenance on a best-effort basis, so it may return `null` for a source location that the provided context cannot establish.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `facts.column` | `string` | **Field**<br/>Name of the target fact field | `"field"` |
| `facts.defval` | `string` | **Default Value** | `""` |
| `facts.fields` | `array` |  |  |
| `facts.include_provenance` | `boolean` | **Include Provenance**<br/>Auto-attach provenance (page, table id, row, column, source text, confidence) to every emitted fact. | `true` |
| `facts.profile` | `string` |  | `"default"` |
| `facts.type` | `string` | **Type** | `"text"` |
| `facts.validate` | `boolean` | **Validate**<br/>Run a second validator prompt pass that double-checks extracted facts and reconciles on disagreement. | `true` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/extract_facts)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Face Detection

Route: /nodes/face_detection

# face_detection

A RocketRide image node that finds faces in each frame with MediaPipe BlazeFace and returns face boxes, scores, and optional alignment keypoints. Choose it as a lightweight face-presence or face-framing stage rather than a general-purpose object detector.

## About MediaPipe

MediaPipe Tasks is the local face-detection runtime used by this node. The implementation uses its FaceDetector interface with a cached BlazeFace model artifact.

## What it does

The node consumes an image stream, detects faces in each completed frame, and emits a JSON array plus an annotated JPEG. Each detection has the `face` label, a confidence score, a bounding box, and a centroid; the optional landmark setting adds six coarse keypoints. Use a general object-detection node for arbitrary object classes, and use this node when face-specific boxes and alignment points are what the pipeline needs.

## Lanes

| Lane in | Lane out | Description |
| ------- | -------- | ----------- |
| `image` | `image` | JPEG copy of the input frame annotated with cyan face boxes, labels, and any emitted landmark dots. |
| `image` | `text` | JSON array of face detections with `label`, `score`, `box`, `centroid`, and optional `landmarks`. |

## Configuration

The short-range BlazeFace profile is the available model choice. Tune the threshold to match the acceptable false-positive rate, then enable landmarks only for consumers that need their extra alignment information.

### Confidence threshold

The node passes this `0.0`–`1.0` value to MediaPipe as the minimum detection confidence; the default is `0.5`. Raise it when textured backgrounds or image artifacts are incorrectly reported as faces. Lower it when genuine faces are missed, accepting that more weak detections may be returned. The detector downsizes the long edge to 1333 px for inference and rescales its coordinates back to the source image, so the JSON remains in source-image coordinates.

### Emit 6 alignment keypoints

When enabled, each detection can include named points for the right eye, left eye, nose tip, mouth center, and both ear tragions. Keep it on for face-aware crops or alignment; turn it off when only boxes and centroids are needed, so downstream consumers do not have to handle landmark data. These are coarse alignment points, not a dense facial-landmark mesh.

## Notes

### Local runtime and model setup

The implementation runs MediaPipe Tasks on CPU/XNNPACK; it does not enable a GPU delegate. On first use it downloads the pinned short-range BlazeFace model to the engine model cache and verifies its SHA-256 checksum before retaining it. On Linux, MediaPipe may need the system libraries `libGLESv2.so.2` and `libEGL.so.1`; missing-library errors identify the needed soname and give a Debian/Ubuntu package hint.

### Output and failures

The node writes its text and image results only if the corresponding output lane has a listener. If a frame cannot be decoded or detection fails, it logs a warning, drops that frame, and suppresses default image forwarding rather than emitting a partial result.

## Upstream docs

- [MediaPipe Tasks documentation](https://ai.google.dev/edge/mediapipe/solutions/vision/face_detector)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `face_detection.emit_landmarks` | `boolean` | **Emit 6 alignment keypoints**<br/>Include coarse 6-point keypoints per face (eyes, nose, mouth, ear tragions) for face-aware framing and alignment. | `true` |
| `face_detection.profile` | `string` | **Model** | `"short"` |
| `face_detection.threshold` | `number` | **Confidence threshold**<br/>Minimum detection confidence (0.0-1.0). Default 0.5 - higher than object detect to suppress false faces on textured backgrounds. | `0.5` |

## Dependencies

- `mediapipe` `>=0.10.35`
- `Pillow`
- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/face_detection)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Frame Grabber

Route: /nodes/frame_grabber

# frame_grabber

A RocketRide video node that extracts selected still frames from an incoming
video stream and sends them downstream as PNG images, image documents, or a
frame-timestamp table. Choose it when later pipeline stages need individual
frames rather than the original video stream.

## About Pillow

Pillow is an image library that frame_grabber imports for optional watermark
rendering. It opens a selected frame, draws the watermark text, and encodes the
result as PNG.

## What it does

The node receives video on the `video` lane and selects frames in interval,
scene-transition, or keyframe mode. It can produce each selected frame as a
PNG image stream or as an image document; it can also collect frame numbers and
timestamps into a table when the video closes. Each output is generated only
when its corresponding downstream listener is present. Pick this node over a
single-image transform when a pipeline needs a controlled set of frames and
their timestamps from a video.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `video` | `image` | Emit each selected frame as an `image/png` stream. |
| `video` | `table` | Emit a Markdown table of selected frame numbers and timestamps when the video closes. |
| `video` | `documents` | Emit each selected frame as an image document with frame metadata. |

## Profiles

Default: **Extract video frames at intervals** (`interval`).

| Profile | Selection mode | Context |
| --- | --- | --- |
| `interval` **(default)** | Extract video frames at intervals | Shows the interval, start-time, duration, and watermark settings. |
| `transition` | Extract video frames at scene transitions | Shows the change percentage, minimum scene gap, time bounds, frame cap, and watermark settings. |
| `key` | Extract video frames at keyframes | Shows the time bounds, frame cap, and watermark settings. |

## Configuration

Start by selecting the frame-grabber mode. The default interval profile is the
right starting point for regular sampling; use the other profiles only when
their selection criteria match the video. The generated schema below lists the
available fields and defaults.

### Frame grabber mode

**Frame grabber mode** selects `interval`, `transition`, or `key` and changes
which settings the configuration panel exposes. Keep the default `interval`
when frames should be sampled at a regular cadence. Choose `transition` when
scene changes should control selection, or `key` when keyframes are the desired
selection points. The transition profile supplies `0.4` as its configured
percentage default.

### Interval between frames

**Interval (in seconds) between frames** is available in interval mode and
defaults to `5`. At global initialization, the node converts this interval to
frames per second as `1 / interval`; it must therefore be greater than zero,
or startup raises a `ValueError`. Lower it for more frequent sampling and raise
it when fewer frames are sufficient.

### Percentage change for frame and minimum gap

In transition mode, **Percentage change for frame** defaults to `0.4` and can
be set from `0.1` to `1.0` in the configuration panel. Use a lower percentage
when smaller changes should select frames; use a higher percentage to require
a larger change. **Minimum gap between scenes** defaults to `0` (disabled) and
can be set from `0.5` to `5` seconds to reduce burst detections in
high-motion segments. Pair a nonzero gap with a low percentage when a busy
video would otherwise produce closely spaced selections.

### Extraction window and frame cap

**Start time** and **Duration** are available in every profile. Their default
of `0` starts at the beginning and continues to the end of the video,
respectively; set them to limit work to a relevant segment. **Maximum number of
frames** is available in transition and keyframe modes and defaults to `0` for
no limit. Set a cap when downstream storage or review must be bounded.

### Watermark

**Watermark extracted frames** is off by default. When enabled, the node draws
the selected filename and timestamp parts before sending the frame to any
output. Choose a corner with **Watermark position**; keep the default
bottom-right placement unless it covers important content. The filename and
timestamp switches both default to `yes`; turn either off when that part of the
label is unwanted. If both are off, the frame is returned unchanged even when
watermarking is enabled.

The timestamp is formatted as `HH:MM:SS.ss`. When the incoming descriptor
identifies media extracted from a container, the filename label is rendered as
`file @ container`; otherwise it uses the available file or container name.
Watermark rendering is best effort: if Pillow raises an exception, the node
logs the error and emits the original frame.

## Notes

### Output metadata

On the documents lane, every frame is emitted as a `Doc` with type `Image`,
base64-encoded PNG content, the frame number as `chunkId`, and its timestamp as
`time_stamp`. The node attaches source-video provenance and gives frames a
derived PNG name when a source descriptor is available.

On the image lane, each frame is a separate `image/png` stream. Its begin
payload includes the frame's byte size and, when available, its dimensions,
derived name, and nested source provenance.

### Table output

The table lane accumulates a row for every selected frame and writes one
Markdown table only when the video closes and at least one row was collected.
Its columns are `Frame`, `Seconds`, and `Time Stamp`.

Each frame document is also given a human-readable `metadata.name` of the form
`<video-stem>.frame<N>.png`, where `<video-stem>` is the source video's file
name without extension and `N` counts the object's frames — the same number as
`chunkId`, so an object carrying several videos is numbered straight through
and no two frames share a name. Omitted when the source has no name.

## Upstream docs

- [Pillow documentation](https://pillow.readthedocs.io/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `grabber.duration` | `number` | **Duration  (in seconds) for frame extraction (0=end of video)** | `0` |
| `grabber.max_frames` | `number` | **Maximum number of frames to extract (0=unlimited)** | `0` |
| `grabber.min_scene_gap` | `number` | **Minimum gap between scenes (seconds)**<br/>Minimum time gap between extracted frames. Helps reduce burst detections in high-motion segments. Set to 0 to disable. | `0` |
| `grabber.percent` | `number` | **Percentage change for frame** | `0.4` |
| `grabber.profile` | `string` | **Frame grabber mode** | `"interval"` |
| `grabber.second.interval` | `number` | **Interval (in seconds) between frames** | `5` |
| `grabber.start_time` | `number` | **Start time (in seconds) for frame extraction (0=beginning)** | `0` |
| `grabber.watermark` | `string` | **Watermark extracted frames** | `"no"` |
| `grabber.watermark_filename` | `string` | **Include file name** | `"yes"` |
| `grabber.watermark_location` | `string` | **Watermark position** | `"bottom_right"` |
| `grabber.watermark_timestamp` | `string` | **Include timestamp** | `"yes"` |

## Dependencies

- `Pillow` `>=10.1.0 # ImageFont.load_default(size=)`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/frame_grabber)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# ArangoDB

Route: /nodes/graph_arango

# graph_arango

A RocketRide graph database node that translates questions into validated AQL for ArangoDB; choose it for an ArangoDB multi-model database rather than a Cypher graph service.

## About ArangoDB

ArangoDB is a database designed to work with document and graph data. It supports AQL for querying documents, edges, graphs, and search views through one database interface.

## What it does

The node reflects collections, named graphs, and ArangoSearch views, then uses its required LLM connection to build read-only AQL from a question. It can run in a pipeline or as an agent tool. Generated AQL is checked with `EXPLAIN`, which rejects plans containing data-modification nodes; choose it over `graph_falkordb` when the data is in ArangoDB and AQL is the target query language.

## Connections

| Connection | Required | Description |
|---|---|---|
| `llm` | yes | LLM used to craft AQL from a question. |

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `questions` | `table` | Emits a Markdown table result. |
| `questions` | `text` | Emits a text result. |
| `questions` | `answers` | Emits the answer result. |

## As a tool

The registered tool names are the bare method names `get_data`, `get_schema`, and `get_aql`; an agent catalog namespaces them by the pipeline component id, not by the services.json `prefix`.

| Function | Description |
|---|---|
| `get_data` | Requires a non-empty `question`; optional `limit` is clamped. Returns rows, executed AQL, and the applied row limit, or an `error` with empty rows. |
| `get_schema` | Accepts an optional `collection` filter and returns the database, collections, graphs, and views. An unknown collection returns `error`. |
| `get_aql` | Requires a non-empty `question`; returns a validated read-only AQL query and `valid: true`, or `error`/`answer` with `valid: false`. |

## Configuration

Configure the endpoint, database, credentials, and an accurate database description before using natural-language queries. The description and reflected schema are provided to the LLM, so improve it when generated AQL targets the wrong collections or relationships.

### Database description and validation attempts

`db_description` gives the LLM domain context. Start with a concise explanation of the collections and relationships, then add detail if retries produce invalid AQL. `max_attempts` defaults to five and controls re-generation after `EXPLAIN` rejects a query; raise it for a difficult schema only if the connected LLM needs more repair attempts.

### Result limits and direct execution

`max_execute_rows` caps raw `QuestionType.EXECUTE` results; a query above the cap fails rather than streaming unbounded rows. `allow_execute` is false by default. Enable it only for a trusted caller, because that path runs raw AQL without LLM translation or the normal read-only gate.

## Authentication

The default `userpass` method uses `user` and `password`; a blank user falls back to `root`. The `token` method passes the configured bearer/JWT token to the ArangoDB client. Startup verifies the configured database and performs a `RETURN 1` probe, so connection and permission failures surface before processing questions.

## Limitations

The node declares `noremote`, so it is intended for a deployment that can directly reach its ArangoDB endpoint. Normal natural-language and tool queries are read-only; direct execution is a separate trusted-caller option and must be explicitly enabled.

## Notes

### Pipeline question types

`QuestionType.DIALECT` emits `{"dialect": "arango"}` on `answers`. `QuestionType.EXECUTE` is rejected with a warning until `allow_execute` is enabled; when enabled, it may report `affected_rows` for writes that return no rows.

## Upstream docs

- [ArangoDB documentation](https://docs.arangodb.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `arangodb.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw AQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue AQL directly. | `false` |
| `arangodb.auth_method` | `string` | **Authentication** | `"userpass"` |
| `arangodb.database` | `string` | **Database name**<br/>Name of the ArangoDB database to query. '_system' is the built-in default — point this at your application database. | `"_system"` |
| `arangodb.db_description` | `string` | **Database description**<br/>What is this database used for? Describe its collections, graphs and domain — this helps the LLM generate more accurate AQL queries. | `""` |
| `arangodb.endpoint` | `string` | **Connection endpoint**<br/>HTTP(S) endpoint for the ArangoDB server. Use http://host:8529 for self-host/Docker, or https://<id>.arangodb.cloud:8529 for ArangoGraph cloud (TLS). | `"http://localhost:8529"` |
| `arangodb.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated AQL query | `5` |
| `arangodb.max_execute_rows` | `integer` | **Max result rows**<br/>Maximum number of rows returned by a query. Also caps the raw EXECUTE path; a query that exceeds it fails rather than streaming unbounded results. | `25000` |
| `arangodb.password` | `string` | **Password**<br/>Password to authenticate with the ArangoDB instance. |  |
| `arangodb.profile` | `string` |  | `"default"` |
| `arangodb.token` | `string` | **Bearer token**<br/>JWT bearer token for token-based authentication (e.g. ArangoGraph cloud). |  |
| `arangodb.user` | `string` | **User**<br/>Username to authenticate with ArangoDB. Defaults to 'root'. | `"root"` |

## Dependencies

- `python-arango`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/graph_arango)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# FalkorDB

Route: /nodes/graph_falkordb

# graph_falkordb

A RocketRide graph node that translates questions or agent calls into Cypher for FalkorDB; choose it when a FalkorDB graph is the data source rather than an ArangoDB database.

## About FalkorDB

FalkorDB is a graph database that uses Cypher queries and the Redis protocol. A server can host multiple named graphs, which this node can list and select.

## What it does

The node uses the required LLM connection to translate natural-language questions to Cypher, validates the result with `EXPLAIN`, and returns graph data through a pipeline or tools. It also provides a direct Cypher tool for callers that already have a query. Choose it over `graph_arango` for FalkorDB and Cypher; normal queries use the server’s read-only operation until writes are explicitly enabled.

## Connections

| Connection | Required | Description |
|---|---|---|
| `llm` | yes | LLM used to craft Cypher from a question. |

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `questions` | `table` | Emits a table result. |
| `questions` | `text` | Emits a text result. |
| `questions` | `answers` | Emits the answer result. |

## As a tool

The registered tool names are the bare method names below (an agent catalog namespaces them by the pipeline component id, not by the services.json `prefix`). It registers its FalkorDB-specific tools plus the inherited graph-tool surface.

| Function | Description |
|---|---|
| `get_data` | Requires a non-empty `question`; optional `limit` is clamped to the graph row cap. Returns sanitized rows, generated query, applied limit, and truncation state; generation/execution failure returns `error`, `valid: false`, and no rows. |
| `get_schema` | Takes no meaningful arguments and returns reflected `labels`, node properties, and relationships. |
| `get_query` | Requires a non-empty `question`, with optional `limit`; returns validated read-only Cypher and `valid: true`, or an `error`/off-topic `answer` with `valid: false`. |
| `execute` | Requires raw `query` and runs it without LLM translation; it raises an error unless `allow_execute` is enabled, and fails when the result exceeds the execute row cap. |
| `dialect` | Takes no meaningful arguments and returns `{dialect: "falkordb"}`. |
| `query` | Requires non-empty `cypher`; accepts optional object `params` and optional `graph`. Returns columns, serialized rows, count, and truncation state; Redis failures return `error` with empty rows. |
| `list_graphs` | Takes no arguments and returns graph names, or `error` with an empty graph list on a Redis failure. |

## Profiles

Default: **Manual configuration (host and port)** (`default`).

| Profile | Model | Context |
|---|---|---|
| `default` *(default)* | Manual configuration | Uses host and port fields. |
| `url` | FalkorDB URL | Uses the supplied connection string. |

## Configuration

Select Manual configuration for host and port fields, or the URL profile for a connection string. Both profiles include graph, LLM context, query safety, result caps, and timeout settings; begin with the defaults and adjust only for the actual graph and workload.

### Connection and credentials

The manual profile passes host, port, optional username/password, and TLS to the FalkorDB client. The URL profile requires a `falkor://`, `falkors://`, `redis://`, `rediss://`, or `unix://` URL. If a Password field is set with a URL, the node removes an embedded password and uses the field value, so the two cannot silently disagree.

### Graph description and retries

`graph` selects the named graph when a tool caller does not supply one. `db_description` is supplied to the LLM when it writes Cypher; add labels, relationships, and domain language when generation targets the wrong shape. `max_attempts` defaults to five and controls how often a rejected `EXPLAIN` result is repaired.

### Write access, row caps, and timeout

`allow_writes` defaults to false, using `GRAPH.RO_QUERY` so the server rejects write clauses. Enable it only for a trusted workload; direct `query` then uses `GRAPH.QUERY` and can return write statistics. `max_rows` truncates ordinary results and marks them truncated; `max_execute_rows` makes oversized direct-execute results fail. `query_timeout_ms` bounds a single server query.

## Authentication

Manual connections can omit credentials or provide the configured username and password. URL connections may carry credentials, but the separate Password field takes precedence when present. The node probes the connection at startup, so malformed connection settings or an unavailable server fail before a tool call.

## Notes

### Result representation

The direct query tool serializes graph nodes, relationships, paths, maps, lists, and temporal values into JSON-safe values. It returns no more than the configured row cap, allowing agents to recognize broad results through the `truncated` flag.

## Upstream docs

- [FalkorDB documentation](https://docs.falkordb.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `graph_falkordb.allow_execute` | `boolean` | **Allow Execute**<br/>Enable the execute tool, which runs raw Cypher with no LLM translation and no read-only gate. Leave OFF unless a trusted application explicitly needs to issue Cypher directly. | `false` |
| `graph_falkordb.allow_writes` | `boolean` | **Allow Writes**<br/>Permit CREATE/MERGE/SET/DELETE in the query tool. When off, queries run via GRAPH.RO_QUERY and the server itself rejects write clauses. | `false` |
| `graph_falkordb.db_description` | `string` | **Graph Description**<br/>What is this graph used for? Describe its content and domain, this helps the LLM generate more accurate Cypher queries. | `""` |
| `graph_falkordb.graph` | `string` | **Default Graph**<br/>A FalkorDB server hosts many graphs. This is the one queried when the caller does not name another. | `"agent"` |
| `graph_falkordb.host` | `string` | **Host**<br/>FalkorDB host, e.g. localhost or your-instance.falkordb.cloud. | `"localhost"` |
| `graph_falkordb.max_attempts` | `integer` | **Max Validation Attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated Cypher query. | `5` |
| `graph_falkordb.max_execute_rows` | `integer` | **Max Execute Rows**<br/>Upper cap on rows returned by the execute tool. The query fails if exceeded, so one statement cannot exhaust worker memory. | `25000` |
| `graph_falkordb.max_rows` | `integer` | **Max Rows**<br/>Upper cap on rows returned per query. Results beyond it are cut and flagged as truncated. | `250` |
| `graph_falkordb.password` | `string` | **Password**<br/>Password for the FalkorDB instance. Stored encrypted. When set it is the one used, replacing any password embedded in the FalkorDB URL. Leave empty for no auth, or to use the one the URL already carries. | `""` |
| `graph_falkordb.port` | `integer` | **Port**<br/>FalkorDB port (Redis protocol). FalkorDB Cloud assigns a per-instance port. | `6379` |
| `graph_falkordb.profile` | `string` | **Connection**<br/>How this node connects to FalkorDB | `"default"` |
| `graph_falkordb.query_timeout_ms` | `integer` | **Query Timeout (ms)**<br/>Server-side timeout for a single query. | `30000` |
| `graph_falkordb.tls` | `boolean` | **TLS**<br/>Connect with TLS. Required by FalkorDB Cloud TLS endpoints. | `false` |
| `graph_falkordb.url` | `string` | **FalkorDB URL**<br/>Connection string as shown in the FalkorDB Cloud console, e.g. falkor://falkordb@r-xxxx.instance-yyyy.cloud:53939. Use falkors:// for TLS. The URL may carry credentials, so it is stored encrypted; the password can also be left out of it and typed in the Password field below, which then replaces whatever the URL embeds. | `""` |
| `graph_falkordb.username` | `string` | **Username**<br/>Username, e.g. "default" for FalkorDB Cloud. Leave empty for no auth. | `""` |

## Dependencies

- `falkordb` `>=1.6,<2`
- `redis` `>=7.1,<8`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/graph_falkordb)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# HydraDB

Route: /nodes/graph_hydradb

# graph_hydradb

A RocketRide graph database and tool node for storing text as HydraDB memories
and recalling graph-enriched context. Pick it when an agent needs native memory
storage and retrieval rather than an embedding-backed data lane or Cypher queries.

## About HydraDB

HydraDB is a managed graph and memory store. This node uses its REST API to
ingest memories, retrieve context, inspect extracted relationships, and report
database readiness. HydraDB performs the knowledge-graph extraction and native
retrieval behind those operations.

## What it does

This is a tool-only node: it has no data lanes, so an agent calls it on demand.
`store_memory` sends text for memory ingestion, while `recall_memory` performs
HydraDB-native search over memories and knowledge. Choose it over graph query
nodes such as `graph_neo4j` when you want HydraDB's managed memory operations
instead of LLM-generated Cypher; it does not require an embedding input or an
LLM connection.

## As a tool

The functions are registered under the `hydradb` service prefix: for example,
`hydradb.store_memory`. There is no configurable tool-server-name field.

| Function | Description |
| --- | --- |
| `hydradb.store_memory` | Store text as a memory and return the ingest response. |
| `hydradb.recall_memory` | Search knowledge and memories by natural-language query and return ranked, graph-enriched results. |
| `hydradb.query_graph` | Inspect extracted entities and relationship triplets; it is not a free-form graph-query interface. |
| `hydradb.get_schema` | Return collection IDs and infrastructure-readiness information for the configured database. |

`store_memory` requires a non-empty `text` string and accepts an optional
object `metadata`; it returns `{status: "ok", result}` when the ingest request
returns. `recall_memory` requires a non-empty `query`; optional `max_results`
uses the node setting when omitted and is clamped from 1 through 100. It returns
`{results, result}`, where `result` is the raw query response.

`query_graph` accepts an optional non-empty `source_id` string, which limits the
relations inspection to that ingested source; it returns `{relations, result}`.
`get_schema` takes an empty object (or no argument) and returns `{database,
collections, infra, result}`. Invalid argument shapes or missing required text
raise validation errors, and transport or non-success API responses raise a
HydraDB request error rather than looking like empty retrieval results.

## Configuration

Set the API key and database first, then normally keep the default collection
and result limit. The generated schema below is the field reference; the
settings here determine the database and collection scope used by every tool
call.

### API Key and Database

The API key is required to use the service. Enter it in **API Key**, or leave
that field blank to use `HYDRA_DB_API_KEY`; the node trims either value and
clears its in-memory copy during teardown. **Database** is also required and is
sent with every request, so choose the database that contains the memories the
agent should be allowed to access. Saving a configuration with either value
missing issues a warning rather than attempting a network probe.

### Collection

**Collection** partitions memory operations inside the chosen database and
defaults to `default`; a blank value also resolves to `default`. Change it to
isolate separate users or workspaces that share a HydraDB database. The value
is applied consistently to ingestion, recall, and relation inspection, so a
memory stored in one collection is not retrieved by this node configured for
another.

### Max results

**Max results** is the default result count for `recall_memory`, with a default
of 10 and an effective range of 1–100. Raise it when an agent needs a broader
set of possible context, accepting a larger result payload; lower it when the
agent needs only the most relevant context. A per-call `max_results` overrides
this default but is subject to the same clamp.

## Authentication

Provide a HydraDB API key in **API Key**, or make `HYDRA_DB_API_KEY` available
to the worker running the node. The client sends it as a Bearer authorization
header and does not include request headers or bodies in its request-error
messages.

## Limitations

The `noremote` capability pins this node to the local worker because it holds a
client and credentials. It calls HydraDB's REST API rather than exposing a
pipeline data lane, and it cannot run arbitrary graph queries: `query_graph`
only returns the extracted relations, optionally for one source.

## Notes

### Ingestion and retrieval behavior

Memory ingestion uses the `/context/ingest` endpoint with `type=memory`,
`infer=true`, and `upsert=true`; HydraDB is therefore asked to extract
knowledge-graph information and to replace a memory with the same content.
Recall searches both knowledge and memories with the configured collection,
using HydraDB's `hybrid` query mode, `fast` mode, and graph context. The node
does not calculate embeddings or translate requests into a query language.

### Readiness and result shapes

`get_schema` combines the database collection list with the infrastructure
status response, so it is useful for confirming that the backing layers are
ready before relying on ingestion. `recall_memory` accepts a result list from
the first available `chunks`, `results`, or `data` field in the service
response; an unfamiliar response shape therefore produces an empty `results`
list while still returning the raw response under `result`.

## Upstream docs

- [HydraDB API reference](https://docs.hydradb.com/api-reference/v2/sdks.md)
- [HydraDB query API](https://docs.hydradb.com/api-reference/v2/endpoint/query.md)
- [HydraDB context ingest API](https://docs.hydradb.com/api-reference/v2/endpoint/ingest-context.md)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `hydradb.api_key` | `string` | **API Key**<br/>HydraDB API key. Falls back to the HYDRA_DB_API_KEY environment variable if left blank. |  |
| `hydradb.collection` | `string` | **Collection**<br/>Collection scope within the database (per-user/workspace partition for memories). | `"default"` |
| `hydradb.database` | `string` | **Database**<br/>HydraDB database - the space that stores your context. Create one in the HydraDB dashboard. |  |
| `hydradb.max_results` | `integer` | **Max results**<br/>Default maximum number of results returned by recall_memory. | `10` |
| `hydradb.profile` | `string` |  | `"default"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/graph_hydradb)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Neo4J

Route: /nodes/graph_neo4j

# graph_neo4j

A RocketRide graph and tool node that uses a connected LLM to answer
natural-language questions against a Neo4j graph database. Pick it for
knowledge-graph retrieval when Cypher generation and graph-schema awareness are
more useful than a native memory-store search.

## About Neo4j

Neo4j is a graph database accessed here through its Python driver and Bolt
connection protocol. Its data model represents nodes and the relationships
between them, which this node reflects for use in generated Cypher queries.

## What it does

On the `questions` lane, the node gives a connected LLM the reflected graph
schema and turns the question into a read-only Cypher query. It can emit query
results on `table`, `text`, and `answers`, and it exposes the same graph access
to agents as tools. Choose it over `graph_hydradb` when you need questions
translated to Cypher for an existing Neo4j graph; HydraDB instead offers native
memory operations and no data lanes.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used to generate Cypher from natural-language questions. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `table` | Emit executed query results as a Markdown table. |
| `questions` | `text` | Emit the result as text. |
| `questions` | `answers` | Emit executed results as a Markdown table, or an LLM reply when no graph query is produced. |

For regular questions, the LLM generates and validates Cypher before the node
runs it. A `DIALECT` question emits `{"dialect": "neo4j"}` on `answers`.
An `EXECUTE` question is handled separately and runs its text as raw Cypher
only when **Allow direct query execution** is enabled.

## As a tool

The functions are registered under the `neo4j` service prefix: for example,
`neo4j.get_data`. There is no configurable tool-server-name field.

| Function | Description |
| --- | --- |
| `neo4j.get_data` | Turn a natural-language request into a read-only Cypher query, run it, and return rows. |
| `neo4j.get_schema` | Return the reflected labels, properties, and relationship types. |
| `neo4j.get_query` | Return generated read-only Cypher without executing it. |
| `neo4j.execute` | Run raw Cypher only when direct execution is enabled. |
| `neo4j.dialect` | Return `{"dialect": "neo4j"}`. |
| `neo4j.get_cypher` | Deprecated compatibility alias for `get_query`; it also includes the statement under `cypher`. |

`get_data`, `get_query`, and `get_cypher` require a non-empty `question` and
accept an optional integer `limit`; absent or invalid limits resolve to 250 and
the maximum is 25,000. `get_data` returns `{valid, rows, query, row_limit,
truncated}` on success. Failed validation or execution returns `valid: false`
with `error`; a non-graph question returns `valid: false` with an `answer`
instead of rows.

`get_schema` accepts an optional `label`; an unknown label returns an `error`,
otherwise the response includes `{database, labels, nodes, relationships}`.
`execute` requires a non-empty raw `query` and returns `{rows, affected_rows}`;
it raises an error while direct execution is disabled. `dialect` accepts no
meaningful arguments. Generation failures return an error rather than an
executable query, and `get_cypher` preserves those outcomes while adding
`cypher` when a query is available.

## Configuration

Start with a working Bolt URI and authentication method, then describe the
graph so the LLM has useful domain context. The generated schema below lists
the fields; these settings control connection validation, generated-query
quality, and the intentionally restricted direct-execution path.

### Connection URI and database

**Connection URI** defaults to `neo4j://localhost:7687`; use the `neo4j://` or
`bolt://` forms for plaintext connections and the `neo4j+s://` or `bolt+s://`
forms for TLS. **Database name** defaults to `neo4j`. Change either to point at
the instance and database containing the graph the node should query. At
startup and when saving configuration, the driver verifies connectivity and
runs `RETURN 1` against that specific database, so a wrong database name or
missing access surfaces before the first question.

### Graph description

**Graph description** is appended to the LLM's query-generation context, along
with the reflected labels, property types, and relationships. Leave it empty
when the schema is self-explanatory; add a concise description of the graph's
domain when labels alone would be ambiguous. This helps the LLM choose the
correct interpretation, but it cannot replace a connection that exposes the
actual schema.

### Max validation attempts

**Max validation attempts** controls how many times a rejected generated query
is repaired after Neo4j rejects it under `EXPLAIN`. The setting defaults to 5;
the runtime clamps it to 1–10. Increase it only if valid requests routinely
need additional repair attempts, since each retry calls the LLM and delays the
answer. When all attempts fail, the node returns the database error rather than
running the last rejected query.

### Allow direct query execution

**Allow direct query execution** is off by default. Keep it off for normal
agent and lane traffic: generated reads pass the Cypher safety gate and use a
READ access-mode session. Turn it on only for a trusted caller that must issue
raw Cypher through `execute` or `QuestionType.EXECUTE`, because that path skips
both LLM translation and the read-only gate and can write to the database.
Raw execution is still limited to 25,000 returned rows; exceeding that limit
raises an error.

## Authentication

Choose **Username & Password** (the default) to send the configured user and
password to the driver; a blank user resolves to `neo4j`. Choose **Bearer
Token** to use the configured token through `neo4j.bearer_auth`. The save-time
probe reports authentication, connectivity, and Neo4j errors as warnings;
pipeline startup then fails fast if the configured server or database cannot
be verified.

## Limitations

The `noremote` capability pins this node to the local worker because it holds a
database client and credentials. The ordinary graph-query flow uses a
client-side best-effort blacklist for selected write and administrative clauses
and Neo4j READ access mode. Neither is a guaranteed read-only boundary: READ
access controls routing, and the blacklist cannot cover every mutating procedure.
Enabling direct execution grants trusted callers an explicit write-capable escape
hatch.

## Notes

### Schema reflection and query generation

At startup, the node reflects node labels and property types through
`db.schema.nodeTypeProperties()` and relationship information through
`db.schema.visualization()`. On servers where those procedures fail, it falls
back to `db.labels()` and `db.relationshipTypes()`. Reflection failure only
warns and leaves an empty schema cache, so the connection can continue but the
LLM has less structure to ground its Cypher generation.

The LLM is instructed to generate queries only from the reflected schema;
generated output is checked for unsafe clauses after comments are removed and
validated with `EXPLAIN`. The safety
gate rejects `CREATE`, `MERGE`, `DELETE`, `SET`, `DROP`, and other write or
admin clauses including mutating `apoc` procedures. The actual read query has a
30-second timeout and the implementation returns one row beyond the requested
limit to report `truncated` correctly.

### Result serialization

Returned graph values are made JSON-safe: nodes include `_labels`,
relationships include `_type`, paths become `{nodes, relationships}`, and
temporal values use their ISO representation. For raw execution, `affected_rows`
counts created or deleted nodes and relationships, changed properties, and
label changes reported by the Neo4j result summary.

## Upstream docs

- [Neo4j Python driver documentation](https://neo4j.com/docs/python-manual/)
- [Cypher manual](https://neo4j.com/docs/cypher-manual/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `graph_neo4j.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw Cypher without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue Cypher directly. | `false` |
| `graph_neo4j.auth_method` | `string` | **Authentication** | `"userpass"` |
| `graph_neo4j.database` | `string` | **Database name**<br/>Name of the Neo4J database to connect to. Use 'neo4j' for the default database. | `"neo4j"` |
| `graph_neo4j.db_description` | `string` | **Graph description**<br/>What is this graph used for? Describe its content and domain, this helps the LLM generate more accurate Cypher queries. | `""` |
| `graph_neo4j.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated Cypher query | `5` |
| `graph_neo4j.password` | `string` | **Password**<br/>Password to authenticate with the Neo4J instance. |  |
| `graph_neo4j.profile` | `string` |  | `"default"` |
| `graph_neo4j.token` | `string` | **Bearer token**<br/>Bearer token for token-based authentication (e.g. Neo4J Aura cloud). |  |
| `graph_neo4j.uri` | `string` | **Connection URI**<br/>Bolt URI for the Neo4J instance. Use neo4j:// or bolt:// for plaintext, neo4j+s:// or bolt+s:// for TLS (e.g. Neo4J Aura cloud) | `"neo4j://localhost:7687"` |
| `graph_neo4j.user` | `string` | **User**<br/>Username to authenticate with the Neo4J instance. | `"neo4j"` |

## Dependencies

- `neo4j`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/graph_neo4j)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Guardrails

Route: /nodes/guardrails

# guardrails

A RocketRide filter node that checks questions before they reach an LLM and answers before they reach users. Pick it when a pipeline needs configurable local rule checks at its boundary rather than another generation or retrieval step.

## What it does

Evaluates `questions` before forwarding them, `answers` before forwarding them, and collects `documents` as grounding context for answer checks. Input checks cover prompt-injection patterns, optional topic keywords, and optional size limits; output checks cover configured grounding, content-safety, PII, and format rules. Unlike an LLM moderation or retrieval node, it decides from the text and local configuration, then either forwards or suppresses the original pipeline item.

All checks are pure stdlib and regex: the node has no external dependencies, no model calls, and adds no network latency.

How it reacts is controlled by the `policy_mode` field: `block` drops the offending question or answer and never forwards it, `warn` logs the violation and forwards anyway, and `log` records the violation silently. The default profile runs in `warn` mode, so a freshly added node never blocks traffic until you opt in.

Text that is empty or whitespace-only is forwarded without checks.

---

## Lanes

| Lane in     | Lane out    | Description                                                           |
|-------------|-------------|-----------------------------------------------------------------------|
| `questions` | `questions` | Input checks run before the question is forwarded to the LLM         |
| `answers`   | `answers`   | Output checks run after the LLM responds                             |
| `documents` | `documents` | Forwarded unchanged; content is collected as ground-truth context for the hallucination check |

Question text is assembled from both the question objects and any attached context before evaluation. Collected document content resets per pipeline object.

## Profiles

Default: **Basic: Prompt injection + PII detection** (`basic`).

Start with `basic` to observe violations without interrupting a pipeline, or
`strict` when rejected content must not continue. Choose `custom` when the
checks need to be selected individually.

| Profile | Behaviour |
| --- | --- |
| `basic` **(default)** | Prompt injection + PII detection, `warn` mode. Only `policy_mode` is configurable in the UI. |
| `strict` | All checks enabled, `block` on violation, `max_input_length` 50000, `max_tokens_estimate` 4096. Exposes `policy_mode`, `max_tokens_estimate`, and `expected_format`. |
| `custom` | All checks enabled with no size limit, `warn` mode. Exposes every individual check, limit, topic, format, and policy control. |

## Configuration

The generated schema is the field reference. Use the checks below to select what to enforce, then choose the policy mode that determines whether an observed violation should stop the pipeline.

### Input checks

Run on the `questions` lane before the question is forwarded:

Enable prompt-injection checking for untrusted questions. Use an allowed-topic list to constrain a focused workflow, or a blocked-topic list for specific unacceptable terms; both are case-insensitive substring checks, not semantic classification. Set one or both size limits when unusually large questions should be stopped before later nodes consume them.

- **Prompt injection** (rule `prompt_injection`, critical severity): regex patterns covering instruction-override attempts ("ignore all previous instructions"), system-prompt extraction, role-play jailbreaks (DAN and similar), delimiter/token injection (`<|system|>`, `[INST]`, etc.), and encoding-evasion commands; plus weighted keyword scoring (keywords such as `jailbreak`, `bypass`, `ignore safety`) that triggers when the combined score reaches 0.7. Topic restriction only runs when `blocked_topics` or `allowed_topics` is non-empty.
- **Topic restriction** (rule `topic_restriction`): blocked-keyword matches are high severity; failing to match any allowed keyword is medium severity. Matching is case-insensitive substring.
- **Input length** (rule `input_length`, medium severity): only runs when a limit is set (`max_input_length > 0` or `max_tokens_estimate > 0`). Tokens are estimated as word count times 1.3, so treat `max_tokens_estimate` as a rough budget rather than an exact tokenizer count.

---

### Output checks

Run on the `answers` lane before the answer is forwarded:

Enable hallucination checking only when relevant documents arrive on the `documents` lane before the answer. It is a lexical grounding test, so use it to flag potentially unsupported output rather than as a factual verifier. Select an expected format only when a downstream consumer requires that shape; an unrecognized format value is skipped.

- **Hallucination** (rule `hallucination`, high severity): sentence-level grounding check. Each output sentence is evaluated for keyword overlap (3+ character non-stop words) against the combined source documents; sentences with less than 30% coverage are flagged. The check is skipped when no documents have been received on the `documents` lane.
- **Content safety** (rule `content_safety`, critical severity): regex patterns across three categories: self-harm, violence (weapon and explosive construction), and illegal activity (hacking, theft, counterfeiting).
- **PII leak** (rule `pii_leak`, high severity): pattern matches for `email`, `phone_us`, `ssn`, `credit_card`, and `ip_address`.
- **Format compliance** (rule `format_compliance`, medium severity): only runs when `expected_format` is set. `json` must parse cleanly; `markdown` requires at least one markdown element (heading, bold, code, list marker); `bullet_list` and `numbered_list` require at least half the non-empty lines to be list items.

---

### Policy modes

When any enabled check fails, `policy_mode` decides the outcome:

| Mode    | Effect                                                                             |
|---------|------------------------------------------------------------------------------------|
| `block` | Each violation is logged as a warning and the question or answer is dropped; nothing is forwarded downstream. |
| `warn`  | Each violation is logged as a warning; the item is forwarded anyway.               |
| `log`   | The item is forwarded with no warnings emitted.                                    |

Blocking happens silently from the pipeline's point of view: downstream nodes simply never receive the item. Check the engine logs (`Guardrails input blocked: ...` / `Guardrails output blocked: ...`) to see what was rejected and why.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `allowed_topics` | `array` | **Allowed topics**<br/>If set, input must contain at least one of these keywords |  |
| `blocked_topics` | `array` | **Blocked topics**<br/>Keywords for topics that should be rejected |  |
| `enable_content_safety` | `boolean` | **Enable content safety check**<br/>Detect harmful or unsafe content in output | `true` |
| `enable_hallucination_check` | `boolean` | **Enable hallucination check**<br/>Verify that output claims are grounded in source documents | `false` |
| `enable_pii_detection` | `boolean` | **Enable PII detection**<br/>Detect personal identifiable information (emails, phones, SSNs, credit cards) in output | `true` |
| `enable_prompt_injection` | `boolean` | **Enable prompt injection detection**<br/>Detect and flag prompt injection attempts in input | `true` |
| `expected_format` | `string` | **Expected output format**<br/>Validate that output matches this format (empty = no check) | `""` |
| `guardrails.profile` | `string` | **Profile**<br/>Guardrails profile | `"basic"` |
| `max_input_length` | `number` | **Max input length (chars)**<br/>Maximum character count for input text (0 = no limit) | `0` |
| `max_tokens_estimate` | `number` | **Max tokens (estimate)**<br/>Maximum estimated token count for input text (0 = no limit) | `0` |
| `policy_mode` | `string` | **Policy mode**<br/>How to handle violations: block (reject), warn (log + continue), log (silent) | `"warn"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/guardrails)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Cleanup

Route: /nodes/image_cleanup

# image_cleanup

A RocketRide image filter node that prepares incoming images for OCR by
normalizing their format, enhancing contrast, correcting skew, and closing small
gaps in characters. Use it before OCR when scans are noisy, low quality, or
tilted, rather than where downstream processing needs to retain the original
image bytes or color.

## About OpenCV

OpenCV supplies the image operations used by this node. Here it decodes the
normalized PNG, converts it to grayscale, applies blur, contrast enhancement,
rotation, and morphological closing, then encodes the result as PNG.

## What it does

Receives a streamed image on the `image` lane, buffers it until the stream ends,
then emits a cleaned replacement on the same lane. It is a pipeline-only filter:
there are no agent-callable functions or configuration fields. Pick it for an OCR
path that benefits from a grayscale, contrast-enhanced and deskewed image; place
another image node in the path when preserving color or the input representation
matters.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | Receives an image stream and emits its cleaned PNG replacement. |

## Configuration

This node has no configuration fields. Add it between the image source and the
OCR consumer; it applies the same cleanup sequence to every complete image
stream.

## Notes

### Processing and output

Inputs whose MIME type is not `image/png` are opened with Pillow, converted to
RGBA, and saved as PNG. The cleanup stages then decode the PNG with OpenCV,
convert it to grayscale, apply a 5×5 Gaussian blur and CLAHE contrast
enhancement (clip limit 2.0; 8×8 tile grid), deskew it, and apply morphological
closing with a 2×2 kernel. The output is therefore a grayscale `image/png`.

Deskewing inverts the grayscale image, finds its non-zero pixels, and uses their
minimum-area rectangle to choose a rotation angle. If no such pixels are found,
the angle remains zero. Rotation uses cubic interpolation and replicated image
borders, so edge pixels are extended rather than filled with a constant border.

### Streaming and failures

The node stores every `WRITE` chunk in memory and performs processing only on
`END`; it suppresses the original stream instead of forwarding it alongside the
replacement. It parses the source descriptor received at `BEGIN` and supplies it
when forwarding the cleaned image.

There is no local fallback to the original input. A non-PNG image that Pillow
cannot convert raises `ValueError`; the cleanup stages also raise when OpenCV
cannot decode or encode their PNG data. Use valid, complete image streams and
account for the full image being buffered before selecting this node for very
large inputs.

## Upstream docs

- [OpenCV documentation](https://docs.opencv.org/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Dependencies

- `pillow`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/image_cleanup)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Image Orientation Fixer

Route: /nodes/image_orient

# image_orient

A RocketRide filter node that turns scanned photographs the right way up.

## What it does

Scanning a photo album gives you pictures at every orientation — a print laid sideways on the
platen comes out sideways, and nothing downstream knows. This node looks at each photo four ways
(as it arrived, and turned 90°, 180°, 270°), finds faces in each, and keeps the orientation they
agree on.

It is deliberately cautious. **A photo turned the wrong way is worse than one left alone**, so
unless the evidence is clear the image passes through untouched and is listed on the text lane
instead. Expect it to fix most of a family album and name the rest for you to do by hand — not to
sweep everything.

Photos it does not rotate are **forwarded byte-for-byte**, never re-encoded, so leaving one alone
costs it nothing in quality.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | The photo, upright if the node was sure, unchanged if it was not |
| `image` | `text` | JSON decision record — what it chose, how sure it was, and why it declined |

## Configuration

| Setting | Default | What it does |
| --- | --- | --- |
| **How sure before rotating** | Balanced (1.1) | How clearly the winning orientation must beat the next best. Trades coverage, not correctness — see below |
| **Faces needed to decide** | 2 | How many faces must back the winner. Lower to 1 for portraits, where there is only ever one face |
| **Face clarity vs face size** | Balanced (1) | When one rotation shows a *bigger* face and another a *clearer* one, this decides which wins. See below |
| **Minimum face score** | 0.6 | How certain the detector must be that something *is* a face before it gets a vote. Raising it ignores doubtful faces but also discards real ones in dim or grainy scans; lowering it admits things that are not faces. Rarely worth changing — it was the least useful dial in testing, and moving it in either direction cost accuracy |
| **Detection size (px)** | 800 | How big a copy the face search runs on. Your image is never scaled; this only affects the search. Raise it if faces in group photos are missed. Cost grows with the square — 1600 is about 4× the work of 800 |
| **JPEG quality** | `auto` | Quality to re-save a rotated JPEG at. `auto` matches what the photo already had. Ignored for PNG; photos that are not rotated are never re-saved at all |

The first two are the ones worth touching. Both defaults were **measured** over 98 real album
photographs, not guessed:

| **How sure before rotating** | Fixed | Turned the wrong way |
| --- | --- | --- |
| Fix as many as possible (1.0) | 37 | 0 |
| **Balanced (1.1)** — default | **37** | **0** |
| Cautious (1.5) | 35 | 0 |
| Only when certain (2.0) | 29 | 0 |

None of those turn a photo the wrong way, because safety does not come from the threshold — it
comes from a rule inside the node: **two independent readings of the same faces must point the
same way before it acts.** One reading asks which orientation holds the most face; the other asks
which the detector was most certain about. Where they disagree the record says `mixed_signals` and
the photo is left alone. Without that rule, matching this coverage cost two photos turned wrongly.

So the setting trades coverage, not correctness. Lower it to fix a few more marginal cases; raise
it if you want the node to touch as little as possible.

### Face clarity vs face size

Each rotation is scored as `confidence ^ k x face area`, and this setting is `k`. It matters for
one specific failure: an upside-down face is still detected, just less confidently — and the box
drawn around it is sometimes *larger* than the box around the upright one. At `k = 1` the bigger
box wins and the photo is left the wrong way up.

| Setting | Faces needed | Corrected | Turned the wrong way |
| --- | --- | --- | --- |
| **Balanced (1)** — default | 2 | 37 | **0** |
| Favour the clearer face (4) | 2 | 38 | 1 |
| Strongly favour (8) | 1 | 39 | 3 |

Raising it rescues photos the default cannot reach, and costs errors elsewhere — the two move
together, so treat it as "how much am I willing to check by hand afterwards". It interacts with
**Faces needed to decide**: the highest setting only reaches those photos when that is also 1,
because they are single-face pictures.

### If something looks wrong

| Symptom | Try |
| --- | --- |
| A photo came out the wrong way round | Raise **How sure before rotating**. This should not happen; the file is worth keeping as an example |
| Too many photos left alone | Lower **How sure before rotating** toward 1.0, then **Faces needed to decide** to 1 |
| Portraits of one person are never rotated | Lower **Faces needed to decide** to 1 — there is only ever one face to find |
| Faces in group shots are missed | Raise **Detection size**; cost grows with the square, so 1600 is ~4× the work of 800 |
| Nothing is ever rotated, every record says `no_model` | The model could not be downloaded. Check network access from the engine host |

## Notes

### The decision record

```json
{"decoded": true, "rotation": 270, "confident": true,
 "scores": {"0": 0.011, "90": 0.004, "180": 0.0, "270": 0.194},
 "faces": 2, "ratio": 17.6, "reason": null}
```

`rotation` is **the correction applied, in degrees clockwise** — not the rotation the photo was
found in. A picture that arrived turned 90° clockwise is corrected with `"rotation": 270`.

`0` means the image was left as it was, and `confident` separates the two ways that happens:
`true` is "measured, and it was already upright", `false` is "not sure". `reason` names the doubt:

| `reason` | Means |
| --- | --- |
| `no_faces` | Nothing that scored as a face at any orientation |
| `few_faces` | Fewer faces backed the winner than **Faces needed to decide** |
| `thin_margin` | No orientation led the others by enough. Two orientations disagreeing looks like this too |
| `mixed_signals` | The two readings of the detections pointed different ways — the rotation holding the most face was not the one the detector was most certain about |
| `unencodable_format` | Analysed, but not JPEG or PNG, so the node declines to re-save it |
| `no_model` | The face model could not be loaded; nothing was analysed |

`decoded: false` is different again — the bytes were not a readable image. That needs a different
fix from "read it and left it alone", which is why they are not merged.

### Limitations

- **It needs faces.** Landscapes, documents and photographs of the backs of people's heads give it
  nothing to work with, and it will abstain on them. That is the honest boundary of the approach,
  not a tuning problem.
- **Upside-down photos are the hardest case.** A face detector fails on a sideways face, which is
  what makes 90°/270° detectable; it fails *less* reliably on an inverted one, so `180` corrections
  are less often confident than quarter turns.
- **Expect a residue it cannot reach.** On a 98-photo album it corrects 37 and leaves the rest,
  most of them genuinely upright but some not. A photo where one reading says upright and the other
  says inverted is exactly the case it refuses, and it will keep refusing it — the text lane names
  those so they can be done by hand rather than hunted for.
- **Only JPEG and PNG are re-saved.** Other formats are still analysed, and the record names
  `unencodable_format` as the reason — but it reports `rotation: 0`, not the correction it worked
  out, so it tells you the image was left alone and not which way it should go. The node will not
  re-encode these, because it has no way to recover their original compression settings and would
  be choosing one for you.
- **No EXIF is carried over.** A rotated image is re-encoded with OpenCV, which writes no EXIF and
  no colour profile. Photos that are not rotated keep their bytes exactly, so they keep everything.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `image_orient.confidenceWeight` | `number` | **Face clarity vs face size**<br/>When one rotation shows a bigger face but another shows a clearer one, this decides which wins. 'Balanced' is the safe default: measured over 98 album photographs it corrected 37 and got none wrong. Raising it rescues photos where an upside-down face is detected with a larger box than the upright one - but it acts on thinner evidence, and at the highest setting with 'Faces needed to decide' at 1 it corrected 39 and got 3 wrong. Raise it only if upside-down photos are being missed, and check the results. | `1` |
| `image_orient.detectSize` | `integer` | **Detection size (px)**<br/>How big a copy of the photo the face search runs on. Your image is never scaled - this only affects the search. Raise it if faces in group photos are being missed; the cost grows with the square, so 1600 is about four times the work of 800. | `800` |
| `image_orient.margin` | `number` | **How sure before rotating**<br/>How clearly the winning orientation must beat the next best one. Measured over 98 real album photographs, 'Balanced' corrected 37 and got none wrong. Move up if a photo ever comes out the wrong way round; move down only if you would rather fix more and check the results yourself. | `1.1` |
| `image_orient.minConfidence` | `number` | **Minimum face score**<br/>How certain the detector must be that something is a face before it gets a say. Raising it ignores doubtful faces; lowering it lets more in, including things that are not faces at all. | `0.6` |
| `image_orient.minFaces` | `integer` | **Faces needed to decide**<br/>How many faces must agree before the photo is turned. One face is thin evidence and was behind most of the mistakes in testing, so two is the default. Lower to 1 for portraits and single-subject photos, where there is only ever one face to find. | `2` |
| `image_orient.quality` | `string` | **JPEG quality**<br/>Type 'auto' to save at the same quality the photo already had, or a number from 1 to 100. Leave it on 'auto': the image has been through JPEG once already, so saving higher only makes the file bigger without recovering anything. Ignored for PNG, which is lossless. Photos that are not rotated are never re-saved at all. | `"auto"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/image_orient)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Landing.ai Extract

Route: /nodes/landing_ai

# landing_ai

A RocketRide document-processing package with separate Landing.ai Parse and Extract services: use Parse to turn an incoming document into Markdown and tables, then Extract when that Markdown must conform to a JSON Schema.

## About Landing.ai

Landing.ai provides Agentic Document Extraction (ADE), a document-processing
service for converting unstructured files into usable text and structured
data. In this package, ADE supplies a parsing operation and a schema-guided
extraction operation, which can be composed in a RocketRide pipeline.

## What it does

Landing.ai Parse receives document bytes on the `tags` lane and emits the ADE
Markdown response and any table chunks. Landing.ai Extract receives parsed
Markdown on `text`, calls ADE with an uploaded JSON Schema, and emits the
result as either an answer or one or more documents. Pick this package when
you need both operations from the same ADE service; choose Parse alone when
you only need readable document text and tables.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `tags` | `text` | Landing.ai Parse writes the document Markdown response. |
| `tags` | `table` | Landing.ai Parse writes each ADE chunk whose type is `table`. |
| `text` | `answers` | Landing.ai Extract writes its structured extraction as a JSON answer. |
| `text` | `documents` | Landing.ai Extract writes the extraction as JSON document content. |

## Configuration

Both services have one default profile. Configure the service that is placed
on the canvas: Parse needs a key and, normally, its default model and region;
Extract additionally needs an uploaded schema. The services look up a nested
`default` configuration when one is present.

### Landing.ai Parse

**Model** controls the value sent to ADE's `parse` call; its default is
`dpt-2-latest`, the only value offered by this node. Keep that default unless
the node's configuration is extended with another supported ADE model. The
**Region** defaults to `production`; select `eu` when the EU deployment is
required. Any other configured region is silently reset to `production` by
the parser, so use one of the two offered values.

### Landing.ai Extract

**Extraction Schema (JSON Schema file)** is required by the service metadata.
Upload a JSON-object data URL, not a plain value or array: the node decodes it,
rejects malformed JSON and uploads over 2 MiB, then serializes the object for
ADE. Use it to define the fields the response must contain; a bad upload is
reported during validation as a warning and fails when extraction runs.

**Strict** defaults to off. Leave it off when a partial extraction is useful;
enable it when a document that does not satisfy the schema must fail instead
of yielding a partial result. **Region** has the same `production`/`eu`
behavior as Parse and is likewise normalized to `production` for any other
value.

## Authentication

Set each service's **API Key** to a Landing.ai ADE key, or set
`ROCKETRIDE_LANDING_AI_KEY` when the field is blank. Save-time credential
checks make a small read-only `parse_jobs.list` call and report problems as
warnings; they do not block editing the pipeline.

## Notes

### Processing and failure behavior

Parse skips the ADE call entirely when neither its `text` nor `table` output
has a listener. With an API key missing or an empty document, it returns empty
text and no tables; an ADE request failure is logged and re-raised. Extract
joins all received text with blank lines. Empty input or a missing key produces
an empty extraction, while an invalid schema or ADE failure is logged and
re-raised. If the upstream response includes extraction warnings, the node
logs them but returns the response extraction.

### Extract document output

When `documents` is connected, Extract turns an object result into one JSON
document. If the extracted value is a list, it emits one JSON document per
item, numbering their chunk IDs from zero for each input object.

## Upstream docs

- [Landing.ai ADE Python documentation](https://docs.landing.ai/ade/ade-python)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Landing.ai Extract (`services.extract.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `landing_ai_extract.api_key` | `string` | **API Key**<br/>Your Landing.ai ADE API key. Falls back to the ROCKETRIDE_LANDING_AI_KEY environment variable when left blank. |  |
| `landing_ai_extract.region` | `string` | **Region**<br/>Which Landing.ai deployment to call. Use EU for the eu-west-1 data-residency endpoint. | `"production"` |
| `landing_ai_extract.schema_file` | `string` | **Extraction Schema (JSON Schema file)**<br/>Upload a .json file describing the fields to extract. Supports the ADE x-alternativeNames and format keywords. |  |
| `landing_ai_extract.strict` | `boolean` | **Strict**<br/>Fail the extraction when the document does not match the schema, instead of returning partial results. | `false` |

### Landing.ai Parse (`services.parse.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `landing_ai_parse.api_key` | `string` | **API Key**<br/>Your Landing.ai ADE API key. Falls back to the ROCKETRIDE_LANDING_AI_KEY environment variable when left blank. |  |
| `landing_ai_parse.model` | `string` | **Model**<br/>ADE parse model to use. | `"dpt-2-latest"` |
| `landing_ai_parse.region` | `string` | **Region**<br/>Which Landing.ai deployment to call. Use EU for the eu-west-1 data-residency endpoint. | `"production"` |

## Dependencies

- `landingai-ade`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/landing_ai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Extract

Route: /nodes/landing_ai/extract

# Landing.ai Extract

Extracts structured fields from parsed Markdown with Landing.ai ADE
(`client.extract`), using a JSON Schema you upload.

- **Protocol:** `landing_ai_extract://`
- **Lanes:** `text` (parsed Markdown) → `answers`, `documents`
- **Config:** API Key, Extraction Schema (`.json` upload), Strict, Region

ADE Extract consumes the **Markdown produced by Parse**, not the raw document,
so this node runs **downstream of Landing.ai Parse**:
`Parse (data → text) → Extract (text → answers)`.

The uploaded schema is a JSON Schema document; it supports ADE's `format` and
`x-alternativeNames` keywords. The Markdown received on the `text` lane is
accumulated and passed directly to the SDK — ADE Extract accepts the Markdown
content directly. The response's `extraction` (key-value data) is written to
`answers` and `documents`.


---

# Parse

Route: /nodes/landing_ai/parse

# Landing.ai Parse

Parses documents with Landing.ai ADE (`client.parse`), emitting Markdown text
and tables.

- **Protocol:** `landing_ai_parse://`
- **Lanes:** `data` → `text` (Markdown), `table`
- **Inputs:** PDF, images, spreadsheets (XLSX/CSV)
- **Config:** API Key, Model (`dpt-2-latest`), Region

The document arrives on the `Data` lane as a byte stream (handled by the
tag-stream state machine in `IInstance.py`) and is passed to the ADE SDK as a
`(filename, bytes)` tuple. The response's `markdown` goes to the `text` lane;
chunks of type `table` go to the `table` lane.

Pairs with **Landing.ai Extract** downstream for schema-based field extraction.


---

# LlamaParse

Route: /nodes/llamaparse

# llamaparse

A RocketRide data node that sends documents to LlamaParse and writes flattened Markdown text and extracted tables into the pipeline; use it for readable content, not audit-grade source provenance.

## About LlamaParse

LlamaParse is a document-parsing service used to turn files into text and
structured document content. This node uses its Python client to parse the
document bytes supplied by a RocketRide pipeline and to return the resulting
text and table data.

## What it does

The node processes incoming document data on `tags` and emits parsed Markdown
on `text` plus tables on `table`. It isolates each LlamaParse request in a
separate thread and event loop, which is useful where the surrounding runtime
already has event-loop state. Choose it when flattened Markdown is the desired
downstream format; use a structure-preserving parser when later review needs
page boundaries, coordinates, or the original table-cell grid.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `tags` | `text` | Parsed document text, flattened to Markdown. |
| `tags` | `table` | Table content detected in the parsed result. |

## Configuration

Start with an API key and the default simple configuration. Simple mode builds
the LlamaParse constructor arguments from the visible controls; advanced mode
instead parses the supplied JSON and merges its entries into those arguments.

### Advanced Configuration

Enable **Advanced Configuration** only when the simple controls cannot express
the parsing options you need. Its value must be valid JSON and must not set
`api_key`, which the node ignores when merging the advanced object. Save-time
validation only warns about unknown keys or invalid JSON, but startup aborts
when advanced mode has no configuration or when JSON cannot be parsed. A good
value is an object containing only the constructor options you intend to
override, such as `{"parse_mode": "parse_page_with_llm"}`.

### Parse Mode and LVM Model

The default **Parse Mode**, `parse_page_with_lvm`, passes that mode to the
client, optionally passes **LVM Model** as `vendor_multimodal_model_name`, and
sets a page-error tolerance of `0.05`. The `agentic` and `agentic_plus` choices
both select `parse_page_with_agent` and can use the same LVM model setting.

The displayed `cost_effective (LLM)` value does not match the code path that
checks for `cost_effective`; as written, choosing it supplies no parse-mode
argument. Keep the default or use an agentic choice when a specific mode must
be sent. The LVM model is not used by the cost-effective path.

### Additional Instructions and spreadsheet tables

**Additional Instructions** are passed only for the legacy
`parse_page_with_lvm` path, when non-blank; use them for parser guidance that
belongs with that mode. **Extract Sub Tables** defaults to off and, when on,
passes `spreadsheet_extract_sub_tables=True` to LlamaParse. Enable it only for
spreadsheets whose nested tables need separate parsing; it has no special
handling in the node beyond forwarding that setting.

## Authentication

Set **API Key** to the LlamaParse service key. Missing keys generate a
save-time warning and cause startup to raise before a parser is created.

## Requirements

The service metadata declares the `gpu` capability. The node itself creates a
LlamaParse client and sends document bytes to it; it does not download or run a
local model. A working network connection to the service and its Python
dependency are therefore required by this implementation.

## Notes

### Scale-header preservation

Financial statements declare their magnitude in a caption above the table ("(In millions)", "$ in thousands", "amounts in millions of USD"). If that caption is separated from its table by downstream chunking or an LLM step, every figure reads as raw units and is silently 1,000x, 1,000,000x, or 1,000,000,000x off. Nothing downstream catches it, because a wrong-by-1e6 number looks exactly like a right one.

To keep that loss visible, the parser post-processes the extracted Markdown:

- **Detects scale captions** the parser already emitted ("(in millions)", "in thousands, except per share amounts", "(₹ in crore)", ...) and normalizes each to a unit, a numeric factor, and an optional currency. Prose uses of the same words ("millions of users", "billions served", "hundreds of thousands of dollars") are not treated as captions.
- **Welds a marker to the table.** When a caption is in scope for a *numeric* table (same page/section, no page break between them), a normalized line is injected directly above the table, for example `> Scale: amounts in millions (x1,000,000)`. A later chunker or LLM cannot separate the scale from its figures. A caption is only welded onto a table that actually looks numeric, so a caption sitting over a prose or roster table is never mis-attached.
- **Flags a missing scale, when the context is financial.** When a numeric table has no caption in scope *and* the document shows a financial signal (a caption detected elsewhere, or a currency marking in the table itself), a warning line is injected above it: `> [scale?] Scale not detected for this table. Figures may be in thousands, millions, or billions. Verify against the source.` The warning errs toward caution: a visible warning is far cheaper than a silent 1e6 error. Plain numeric tables with no financial signal (inventory counts, server metrics, sports standings) are left untouched, so ordinary documents pay nothing for this feature. The markers are plain ASCII, so they survive a cp1252 console without an encoding error.

The welded markers travel in-band with the text and table lanes, so they are the durable downstream signal: whatever chunks or summarizes the output carries the scale (or the warning) with the figures.

For observability, the same results are also recorded in `parsing_metadata` (debug-logged by the instance; not currently re-emitted onto a lane):

- `detected_scales`: list of `{phrase, unit, factor, currency}` for each caption found.
- `scale_warnings`: per-table `{table_index, status, ...}` where `status` is `scale_detected`, `scale_missing`, `not_financial`, or `already_annotated` (the table already carried one of our markers and was left as-is).

Annotation is idempotent (re-running does not double-inject; the injected markers are not themselves read back as captions) and never blocks parsing: any failure falls back to the untouched text.

**Out of scope.** Recovering a caption that LlamaParse dropped from the source entirely is not handled here. That needs an independent source-text extraction and belongs to the audit-grade **`datalab_parse`** node. This node makes an *emitted-but-separable* scale un-loseable and flags its *absence*; it does not re-parse the source.

---


### Flattened output and failures

The node concatenates the returned document text and reads tables from either
`structured_data` or `items` metadata. It does not retain page boundaries,
bounding boxes, or a table HTML cell grid. Parsing errors, absent input, and
import errors return empty text and structured data rather than an exception.

For files over 50 MiB the isolated call raises the parser timeout settings to
at least 600 seconds. The worker waits up to 300 seconds for smaller files,
600 seconds above 100 MiB, and 900 seconds above 500 MiB; a timed-out worker
returns an empty result with error metadata while its daemon thread is left to
finish.

## Upstream docs

- [LlamaParse documentation](https://developers.llamaindex.ai/llamaparse/parse/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `llamaparse.advanced_config` | `string` | **Advanced Configuration (JSON)**<br/>Enter configuration options in JSON format. For more information, see: <a href='https://developers.llamaindex.ai/llamaparse/parse/v1/presets_and_modes/advance_parsing_modes/' target='_blank'>LlamaParse Documentation</a> | `"{\n  \"parse_mode\": \"parse_page_with_llm\",\n  \"spreadsheet_extract_sub_tables\": false,\n  \"system_prompt_append\": \"\",\n  \"lvm_model\": \"anthropic-sonnet-4.0\"\n}"` |
| `llamaparse.api_key` | `string` | **API Key**<br/>Your LlamaIndex API key for LlamaParse service |  |
| `llamaparse.lvm_model` | `string` | **LVM Model**<br/>The LVM model to use for parsing when LVM or agentic modes are selected. | `"anthropic-sonnet-4.0"` |
| `llamaparse.parse_mode` | `string` | **Parse Mode**<br/>The parse mode to use for chosing complexity of the parse | `"parse_page_with_lvm"` |
| `llamaparse.spreadsheet_extract_sub_tables` | `boolean` | **Extract Sub Tables**<br/>Extract sub-tables from spreadsheets for better table parsing. | `false` |
| `llamaparse.system_prompt_append` | `string` | **Additional Instructions**<br/>Additional instructions to append to the system prompt for LlamaParse. |  |
| `llamaparse.use_advanced_config` | `boolean` | **Advanced Configuration**<br/>Check to use advanced JSON configuration instead of simple options. | `false` |
| `llamaparse.use_system_prompt_append` | `boolean` | **Use Additional Instructions**<br/>Check to add custom instructions to the system prompt for LlamaParse. | `false` |

## Dependencies

- `llama-parse`
- `llama-index-core`
- `llama-cloud`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llamaparse)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Anthropic

Route: /nodes/llm_anthropic

# llm_anthropic

A RocketRide LLM node that connects Anthropic's Claude models to your pipeline.

## About Anthropic

Anthropic is an AI safety company and the maker of the Claude family of large
language models. Claude models are widely used for reasoning, long-context
analysis, conversational AI, and code generation.

## What it does

Connects Anthropic's Claude models to your pipeline. Used primarily as an `llm`
invoke connection by agents, vector stores, database nodes, and other nodes that
need an LLM (`classType: ["llm"]`, capability `invoke`). Can also be used directly
in a pipeline via lanes.

Built on **langchain-anthropic** (`ChatAnthropic`) with the **anthropic** SDK used
directly for save-time validation. The configured `modelOutputTokens` is passed to
the model as `max_tokens`. Token counts for budgeting are estimated at roughly
4 characters per token.

## Example pipelines

**Direct question answering**

`chat → llm_anthropic → response_answers`

<div align="center">

![The Anthropic node on the canvas between a chat source and an answers response](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

Questions arrive from chat and Claude's answers stream to the answers
response.

**LLM for an agent**

`webhook → agent_rocketride → response`, with this node connected to the
agent's `llm` channel. The agent uses Claude for its reasoning and tool
calling; swap profiles to trade cost against capability without touching the
pipeline.

**SQL generation for a database node**

`webhook → db_postgres → response`, with this node on the database node's
`llm` channel. Claude translates natural-language questions into SQL that the
database node validates and executes.

## Lanes

| Lane in     | Lane out  | Description                                           |
| ----------- | --------- | ----------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer  |

## Profiles

Default: **Claude Sonnet 4.6** (`claude-sonnet-4-6`).

| Profile | Model ID | Context tokens | Output tokens |
| ------- | -------- | -------------- | ------------- |
| Claude Sonnet 4.6 **(default)** | `claude-sonnet-4-6` | 1,000,000 | 128,000 |
| Anthropic: Claude Fable 5 | `claude-fable-5` | 1,000,000 | 128,000 |
| Anthropic: Claude Sonnet 5 | `claude-sonnet-5` | 1,000,000 | 128,000 |
| Anthropic: Claude Fable 5.1 | `claude-fable-5-1` | 1,000,000 | 128,000 |
| Claude Opus 5 | `claude-opus-5` | 1,000,000 | 128,000 |
| Anthropic: Claude Opus 4.8 | `claude-opus-4-8` | 1,000,000 | 128,000 |

<details>
<summary><strong>View 17 more models</strong></summary>

| Profile | Model ID | Context tokens | Output tokens |
| ------- | -------- | -------------- | ------------- |
| `custom` | _(user-specified)_ | 200,000 (editable) | — |
| Claude Opus 4.6 | `claude-opus-4-6` | 1,000,000 | 128,000 |
| Claude Haiku 4.5 | `claude-haiku-4-5` | 200,000 | 64,000 |
| Claude Sonnet 4.5 | `claude-sonnet-4-5` | 1,000,000 | 64,000 |
| Claude Opus 4.5 | `claude-opus-4-5` | 200,000 | 64,000 |
| Anthropic: Claude Opus 4.7 | `claude-opus-4-7` | 1,000,000 | 128,000 |
| Anthropic: Claude 3 Haiku | `claude-3-haiku` | 200,000 | 4,096 |
| Anthropic: Claude Fable Latest | `claude-fable-latest` | 1,000,000 | 128,000 |
| Anthropic Claude Haiku Latest | `claude-haiku-latest` | 200,000 | 64,000 |
| Anthropic: Claude Opus 4 | `claude-opus-4` | 200,000 | 32,000 |
| Anthropic: Claude Opus 4.1 | `claude-opus-4-1` | 200,000 | 32,000 |
| Claude Opus 5 (Fast) | `claude-opus-5-fast` | 1,000,000 | 128,000 |
| Anthropic: Claude Opus 4.7 (Fast) | `claude-opus-4-7-fast` | 1,000,000 | 128,000 |
| Anthropic: Claude Opus 4.8 (Fast) | `claude-opus-4-8-fast` | 1,000,000 | 128,000 |
| Anthropic: Claude Opus Latest | `claude-opus-latest` | 1,000,000 | 128,000 |
| Anthropic: Claude Sonnet 4 | `claude-sonnet-4` | 1,000,000 | 64,000 |
| Anthropic Claude Sonnet Latest | `claude-sonnet-latest` | 1,000,000 | 128,000 |

</details>

The `*-latest` profiles track Anthropic's current model aliases and update as
Anthropic promotes new versions; pin a specific profile when reproducibility
matters.

## Configuration

Pick a profile and provide an API key — that is the whole configuration for
most pipelines. The model ID and token limits for named profiles are fixed by
the profile; only the `custom` profile exposes `model` and `modelTotalTokens`
directly. `modelSource` records where a custom model definition comes from
(`manual` or `openrouter`).

### Extended thinking

The `extendedThinking` toggle (off by default) requests the model's reasoning
stream. Two switches must both be on for thinking to activate: the model's
`capabilities.reasoning` flag (stamped from OpenRouter model sync) and this
node's toggle. It affects the interactive streaming path only — the agent /
`expectJson` path never requests thinking. Provider-correct parameters are
chosen by model; see Notes for the exact per-model behavior.

## Authentication

Provide an Anthropic API key in the `apikey` field. The key is validated at
startup: it must be non-empty and start with `sk-ant` (covers both standard
`sk-ant-...` and newer `sk-ant-api03-...` formats). If the key fails this check,
the node raises `Invalid Anthropic API key format, please check your API key.`
The key is read at construction time and not stored by the node.

## Notes

### Extended thinking parameters by model

Routing prefixes such as `openrouter/anthropic/` are stripped before matching.

| Model                                  | Thinking parameters sent                                                                                                                                                                                                                      |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Legacy Claude 3 / 3.5 Haiku            | None. Those models have no extended thinking; sending parameters would return a 400. Haiku 4.5 is not excluded and follows the legacy row below.                                                                                               |
| Legacy models (Claude 3.x _except_ Claude 3 / 3.5 Haiku, plus 4.0, 4.1, 4.5 incl. Haiku 4.5 and its `claude-haiku-latest` alias, 4.6, Mythos Preview) | `thinking: {type: "enabled", budget_tokens: N}` plus the `interleaved-thinking-2025-05-14` beta header, where `N` is half the output-token limit (minimum 2,048, always below `max_tokens`). Skipped entirely if the output window is too small for a valid budget. |
| All other Claude models (`claude-opus-4-7`, `claude-opus-4-8`, and the Claude 5 family — `claude-sonnet-5`, `claude-opus-5`, `claude-fable-5`, `claude-mythos-5` — plus any future model) | `thinking: {type: "adaptive", display: "summarized"}` (adaptive thinking). Claude 4.7+ rejects the legacy `enabled` + `budget_tokens` shape with an HTTP 400, so the legacy models are an explicit allowlist and unknown or future models default to adaptive. |

The legacy list matches whole model ids, after `-YYYYMMDD` dated and `-fast`
deployment suffixes are stripped — never an open-ended prefix — so a future id
such as `claude-sonnet-4-50` is not mistaken for `claude-sonnet-4-5`.

When thinking is actually enabled, responses are streamed through the native
Anthropic Messages API handler (`ai.common.llm_native_stream`, provider
`anthropic`) so that thinking deltas (which LangChain drops) are preserved and
forwarded on the `thinking` SSE lane. Non-reasoning models stay on the default
LangChain streaming path.

### Save-time validation

When the node configuration is saved, a lightweight validation pass runs before
the first pipeline execution:

- Checks that `modelTotalTokens` (custom profile) is greater than 0.
- Sends a minimal one-token probe request (`max_tokens: 1`) to the configured
  model using the configured key.

Any failure (bad key, unknown model, rate limit, network error) is surfaced as a
concise single-line warning in the form `Error <status>: <type> - <message>`,
extracted from the API's structured error payload when available. Network or SDK
errors that carry no structured payload fall back to the raw exception message,
collapsed to a single line.

## Upstream docs

- [Anthropic API documentation](https://docs.anthropic.com/en/api)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `anthropic.profile` | `string` | **Model**<br/>LLM model | `"claude-sonnet-4-6"` |
| `extendedThinking` | `boolean` | **Extended thinking**<br/>Enable Anthropic extended thinking (reasoning) for this node. Off by default. Applies to reasoning-capable models on the interactive chat path. | `false` |
| `model` | `string` | **Model**<br/>Anthropic model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |

## Dependencies

- `langchain-anthropic`
- `anthropic`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_anthropic)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Baidu Qianfan

Route: /nodes/llm_baidu_qianfan

# llm_baidu_qianfan

A RocketRide LLM node that calls Baidu Qianfan ERNIE chat models through Qianfan's OpenAI-compatible chat-completions API.

## What it does

Connects a pipeline to Baidu Qianfan ERNIE large language models for chat-based text
generation, question answering, summarization, and Chinese-language enterprise AI
workflows. Questions arriving on the `questions` lane are answered by the configured
ERNIE model and emitted on the `answers` lane.

Uses **langchain-openai** (`ChatOpenAI`) over the **openai** Python SDK, pointed at
Qianfan's OpenAI-compatible endpoint. Temperature is fixed at `0` for deterministic
output, and generation is capped at the profile's output-token limit.

When you save the node configuration, the node validates it live: it sends a tiny test
completion (`"Hi"`, max 8 tokens) to the configured endpoint and surfaces a specific
warning for an invalid API key, an empty model name, a non-positive token limit, a rate
limit, an unreachable base URL, or any other API error.

At runtime, rate-limit and connection errors are treated as retryable; authentication
and other API errors fail immediately with a user-facing message.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **ERNIE 4.5 Turbo 128K** (`ernie-4-5-turbo-128k`).

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| `ernie-4-5-turbo-128k` **(default)** | `ernie-4.5-turbo-128k` | 128,000 | 4,096 |
| `ernie-4-5-turbo-32k` | `ernie-4.5-turbo-32k` | 32,768 | 4,096 |
| `ernie-5-0-thinking-preview` | `ernie-5.0-thinking-preview` | 128,000 | 8,192 |
| `custom` | _(user-specified)_ | 32,768 | 4,096 |

The named profiles pin the model name and token limits; only the API key, base URL, and
model source are editable. The **Custom** profile additionally exposes `model`,
`modelTotalTokens`, and `modelOutputTokens` so you can target any model available on
your Qianfan account.

## Configuration

Choose a named profile for a supported ERNIE model or `custom` for another model on
your account. Named profiles provide the model and token budgets; most pipelines only
need an API key and the correct regional endpoint.

### Base URL

Use `https://qianfan.baidubce.com/v2` for keys issued in China (the default) or
`https://api.baiduqianfan.ai/v1` for international keys. The endpoint and key must
belong to the same Qianfan environment.

## Authentication

Provide a Qianfan API key in `apikey`: it is required, and the node refuses to start
without one. The key must have access to the selected model.

An invalid or unauthorized key is reported as "Baidu Qianfan API key is invalid or
unauthorized" both at save-time validation and at runtime.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `baidu_qianfan.profile` | `string` | **Model**<br/>Baidu Qianfan model selection | `"ernie-4-5-turbo-128k"` |
| `baidu_qianfan.serverbase` | `string` | **Base URL**<br/>Qianfan OpenAI-compatible API endpoint. | `"https://qianfan.baidubce.com/v2"` |
| `model` | `string` | **Model**<br/>Baidu Qianfan model name |  |
| `modelOutputTokens` | `number` | **Output Tokens**<br/>Maximum generated tokens |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |

## Dependencies

- `openai`
- `langchain`
- `langchain-core`
- `langchain-openai`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_baidu_qianfan)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Amazon Bedrock

Route: /nodes/llm_bedrock

# llm_bedrock

A RocketRide LLM node that connects Amazon Bedrock-hosted foundation models to a pipeline.

## What it does

Provides an `llm` invoke connection backed by Amazon Bedrock. It is used primarily by
agents and other nodes that need an LLM, and can also be wired directly via lanes:
text arriving on the `questions` lane is answered on the `answers` lane.

Uses **langchain-aws (`ChatBedrock`)** on top of **boto3 / botocore**. The chat client is
created once per pipeline run with a fixed `temperature` of `0`; the output token cap is
taken from the model's configured output-token limit.

The node automatically prepends a cross-region inference prefix to the model ID based on
the configured AWS region: `eu.` for `eu*` regions, `apac.` for `ap*` regions, and `us.`
otherwise (for example, `meta.llama3-3-70b-instruct-v1:0` becomes
`us.meta.llama3-3-70b-instruct-v1:0` in `us-east-1`). Model IDs that are ARNs or already
carry a `us.` / `eu.` / `apac.` prefix are left untouched.

When you save the node configuration, it is validated with a minimal live API call
(`"Hi"`) against the selected model, so credential, model, and region problems surface
immediately instead of at pipeline runtime.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Llama 3.3 70B Instruct** (`meta_llama3_3-70b`).

| Profile | Model ID | Context tokens |
| ------- | -------- | -------------- |
| Llama 3.3 70B Instruct **(default)** | `meta.llama3-3-70b-instruct-v1:0` | 128,000 |
| Llama 4 Scout 17B Instruct | `meta.llama4-scout-17b-instruct-v1:0` | 3,500,000 |
| Llama 4 Maverick 17B Instruct | `meta.llama4-maverick-17b-instruct-v1:0` | 1,000,000 |
| Nova 2 Lite | `amazon.nova-2-lite-v1:0` | 1,000,000 |
| Claude Sonnet 4.5 | `anthropic.claude-sonnet-4-5-20250929-v1:0` | 200,000 |
| Claude Opus 4.5 | `anthropic.claude-opus-4-5-20251101-v1:0` | 200,000 |

<details>
<summary><strong>View 16 more models</strong></summary>

| Profile | Model ID | Context tokens |
| ------- | -------- | -------------- |
| Custom | _(user-specified)_ | 256,000 (editable) |
| Claude Haiku 4.5 | `anthropic.claude-haiku-4-5-20251001-v1:0` | 200,000 |
| Jamba 1.5 Large | `ai21.jamba-1-5-large-v1:0` | 256,000 |
| Jamba 1.5 Mini | `ai21.jamba-1-5-mini-v1:0` | 256,000 |
| Titan Text Express | `amazon.titan-text-express-v1` | 8,192 |
| Claude Sonnet 3.7 | `anthropic.claude-3-7-sonnet-20250219-v1:0` | 200,000 |
| Claude Haiku 3.5 | `anthropic.claude-3-5-haiku-20241022-v1:0` | 200,000 |
| Claude Opus 4 | `anthropic.claude-opus-4-20250514-v1:0` | 200,000 |
| Command R+ | `cohere.command-r-plus-v1:0` | 128,000 |
| Command R | `cohere.command-r-v1:0` | 128,000 |
| Llama 3.1 8B Instruct | `meta.llama3-1-8b-instruct-v1:0` | 128,000 |
| Llama 3.1 70B Instruct | `meta.llama3-1-70b-instruct-v1:0` | 128,000 |
| Llama 3.2 1B Instruct | `meta.llama3-2-1b-instruct-v1:0` | 128,000 |
| Llama 3.2 3B Instruct | `meta.llama3-2-3b-instruct-v1:0` | 128,000 |
| Llama 3.2 11B Vision Instruct | `meta.llama3-2-11b-instruct-v1:0` | 128,000 |
| Llama 3.2 90B Vision Instruct | `meta.llama3-2-90b-instruct-v1:0` | 128,000 |

</details>

All built-in profiles default to region `us-east-1`.

## Configuration

Choose a built-in profile and the AWS region where that model is available. The
profile supplies the model identifier and context limit; most pipelines do not need
to edit those values.

### Custom models

Select **Custom** to use a Bedrock model not listed above. Provide its full
provider-prefixed model ID (for example,
`anthropic.claude-3-7-sonnet-20250219-v1:0`) or an ARN for a custom or
provisioned model, plus the model's total token limit. Bare model names without a
provider prefix produce a save-time warning. See the
[Bedrock model IDs reference](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html)
for available identifiers.

## Authentication

Provide an AWS access key ID and secret access key with permission to invoke the chosen
Bedrock model in the configured region. Credentials are passed directly to the Bedrock
client and are not persisted by the node.

Save-time validation performs a minimal test invocation and reports provider errors
verbatim. One gotcha: Bedrock returns a `ValidationException` (HTTP 400) when the
**region** does not match your account or model availability, while incorrect keys
surface as different error types. If you see a `ValidationException` during validation,
verify the AWS region first.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `bedrock.profile` | `string` | **Model**<br/>LLM model | `"meta_llama3_3-70b"` |
| `model` | `string` | **Model**<br/>Bedrock LLM model name or ARN for custom or provisioned models |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |

## Dependencies

- `langchain-aws`
- `langchain-core`
- `langchain`
- `boto3`
- `botocore`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_bedrock)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Deepseek

Route: /nodes/llm_deepseek

# llm_deepseek

A RocketRide LLM node that connects DeepSeek models to a pipeline, via the DeepSeek cloud API, locally through Ollama, or through OpenRouter.

## What it does

Provides DeepSeek language models as an `llm` invoke connection for agents and other
nodes that need an LLM. It can also be used directly via lanes: send a question in,
receive a generated answer out.

Built on **LangChain's `ChatOpenAI`** client (DeepSeek exposes an OpenAI-compatible
API), so the same node works against the DeepSeek cloud endpoint, a local Ollama
server, or OpenRouter. Requests are made with **temperature 0**, and `max_tokens` is
capped at the selected profile's output-token limit.

At save time, the node validates cloud configurations (`deepseek-reasoner` and
`deepseek-chat` only) by sending a minimal 1-token probe to
`https://api.deepseek.com/v1`. Local/Ollama profiles are intentionally **not**
validated at save time: a misconfigured local server only surfaces at runtime.

## Lanes

| Lane in     | Lane out  | Description                                          |
|-------------|-----------|------------------------------------------------------|
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Cloud Reasoner** (`cloud-reasoner`).

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| Cloud Reasoner **(default)** | `deepseek-reasoner` | 128,000 | 4,096 |
| DeepSeek: DeepSeek V4 Pro | `deepseek-v4-pro` | 1,048,576 | 384,000 |
| DeepSeek: DeepSeek V4 Flash | `deepseek-v4-flash` | 1,048,576 | 384,000 |
| DeepSeek: DeepSeek V3.2 | `deepseek-v3.2` | 163,840 | 65,536 |
| DeepSeek: DeepSeek V3.2 Exp | `deepseek-v3.2-exp` | 163,840 | 65,536 |

<details>
<summary><strong>View 25 more models</strong></summary>

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| Cloud Chat | `deepseek-chat` | 163,840 | 16,384 |
| DeepSeek R1 1.5B (`deepseek-r1-1_5b`) | `deepseek-r1:1.5b` | 128,000 | 4,096 |
| DeepSeek R1 7B (`deepseek-r1-7b`) | `deepseek-r1:7b` | 128,000 | 4,096 |
| DeepSeek R1 8B (`deepseek-r1-8b`) | `deepseek-r1:8b` | 128,000 | 4,096 |
| DeepSeek R1 14B (`deepseek-r1-14b`) | `deepseek-r1:14b` | 128,000 | 4,096 |
| DeepSeek R1 32B (`deepseek-r1-32b`) | `deepseek-r1:32b` | 128,000 | 4,096 |
| DeepSeek R1 70B (`deepseek-r1-70b`) | `deepseek-r1:70b` | 128,000 | 4,096 |
| DeepSeek R1 671B (`deepseek-r1-671b`) | `deepseek-r1:671b` | 128,000 | 4,096 |
| DeepSeek V3 (`deepseek-v3`) | `deepseek-v3` | 128,000 | 4,096 |
| DeepSeek: DeepSeek V3 0324 | `deepseek-chat-v3-0324` | 163,840 | 147,456 |
| DeepSeek: DeepSeek V3.1 | `deepseek-chat-v3.1` | 163,840 | 144,900 |
| DeepSeek: R1 | `deepseek-r1` | 64,000 | 16,000 |
| DeepSeek: R1 0528 | `deepseek-r1-0528` | 163,840 | 32,768 |
| DeepSeek: R1 Distill Llama 70B | `deepseek-r1-distill-llama-70b` | 8,192 | 7,372 |
| DeepSeek: R1 Distill Qwen 32B | `deepseek-r1-distill-qwen-32b` | 32,768 | 32,768 |
| TNG: DeepSeek R1T2 Chimera | `deepseek-r1t2-chimera` | 163,840 | 163,840 |
| Nex AGI: DeepSeek V3.1 Nex N1 | `deepseek-v3.1-nex-n1` | 131,072 | 163,840 |
| DeepSeek: DeepSeek V3.1 Terminus | `deepseek-v3.1-terminus` | 163,840 | 32,768 |
| DeepSeek: DeepSeek V3.2 Speciale | `deepseek-v3.2-speciale` | 163,840 | 163,840 |
| `deepseek-v4-flash-0731` | `deepseek-v4-flash-0731` | 1,310,720 | 131,072 |
| `deepseek-v4-flash-0731-batch` | `deepseek-v4-flash-0731:batch` | 1,048,576 | 943,718 |
| `deepseek-v4-flash-latest` | `deepseek-v4-flash-latest` | 1,310,720 | 393,216 |
| `deepseek-v4-flash-vision-exp` | `deepseek-v4-flash-vision-exp` | 1,048,576 | 384,000 |
| `deepseek-v4-pro-0813` | `deepseek-v4-pro-0813` | 1,048,576 | 384,000 |
| `deepseek-v4-pro-0813-batch` | `deepseek-v4-pro-0813:batch` | 1,048,576 | 943,718 |

</details>

Cloud profiles use the DeepSeek API, local profiles use an Ollama-compatible
endpoint, and OpenRouter profiles use OpenRouter credentials.

## Configuration

Choose a profile for the provider and deployment you intend to use. Each profile
sets the model, model source, context and output limits, and—where applicable—the
endpoint; most users only need to provide the corresponding API key.

### Endpoint

Local profiles use the OpenAI-compatible `serverbase`, which defaults to
`http://localhost:11434/v1` for Ollama. The selected model must already be pulled
into Ollama. An empty endpoint raises `DeepSeek serverbase is required.` Cloud and
OpenRouter profiles supply their own endpoints.

## Authentication

DeepSeek cloud profiles require a key beginning with `sk-`; another format raises
`Invalid DeepSeek API key format` at startup. OpenRouter profiles require an
OpenRouter API key. Local profiles need no credential, so the node supplies the
placeholder `sk-local-dummy-key` required by the OpenAI client.

## Notes

### Save-time validation

When a pipeline is saved, `validateConfig` runs a 1-token probe (`"Hi"`) against the
DeepSeek cloud API using the official `openai` SDK, but only when the configured model
is `deepseek-reasoner` or `deepseek-chat`. Provider errors are surfaced as warnings
with the HTTP status, error type, and message preserved (e.g.
`Error 401: authentication_error - ...`); they do not block the save. All other
profiles (local and OpenRouter) are skipped at save time and will only fail at runtime
if misconfigured.

## Upstream docs

- [DeepSeek API documentation](https://platform.deepseek.com/docs)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `deepseek.profile` | `string` | **Model**<br/>Deepseek LLM model | `"cloud-reasoner"` |
| `model` | `string` | **Model**<br/>Deepseek model |  |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_deepseek)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Gemini

Route: /nodes/llm_gemini

# llm_gemini

A RocketRide LLM node that connects Google Gemini models to a pipeline.

## What it does

Connects Google Gemini models to your pipeline. Used primarily as an `llm` invoke
connection by agents and other nodes that need an LLM (`classType: llm`, capability
`invoke`). Can also be used directly via lanes: text arriving on the `questions` lane is
sent to the configured model and the generated text is emitted on the `answers` lane.

Uses the **google-genai** library (`genai.Client`) against the Gemini Developer API with
API-key authentication. Prompts are sent with `client.models.generate_content` and the
plain text response is returned. Token counts for budgeting are estimated locally at
roughly 0.75 tokens per word: an approximation, not the model's native tokenizer.

When you save the node configuration, it is validated with a minimal live probe (a
one-word prompt against the configured model). Provider errors (bad key, unknown model,
quota, etc.) surface as a warning that includes the provider's error code, status, and
full message. Image-output models that reject a text-only probe with an
`INVALID_ARGUMENT` "response modalities" error pass validation, since that is a probe
artifact rather than a configuration problem. The probe is skipped entirely when no API
key is present (secure fields are not decrypted at validate time).

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Gemini 3.1 Pro** (`gemini-3_1-pro-preview`).

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| Gemini 3.1 Pro **(default)** | `models/gemini-3.1-pro-preview` | 1,048,576 | 65,536 |
| Google: Gemini 3.6 Flash | `models/gemini-3.6-flash` | 1,048,576 | 65,536 |
| Google: Gemini 3.5 Flash | `models/gemini-3.5-flash` | 1,048,576 | 65,536 |
| Google: Gemini 3.5 Flash Lite | `models/gemini-3.5-flash-lite` | 1,048,576 | 65,536 |

<details>
<summary><strong>View 35 more models</strong></summary>

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| `custom` | _(user-specified)_ | editable | editable |
| Gemini 3.1 Flash Image Preview | `models/gemini-3.1-flash-image-preview` | 131,072 | 58,982 |
| Gemini 3.1 Flash Lite | `models/gemini-3.1-flash-lite-preview` | 1,048,576 | 65,536 |
| Gemini 3 Flash Preview | `models/gemini-3-flash-preview` | 1,048,576 | 65,536 |
| Gemini 3 Pro Image Preview | `models/gemini-3-pro-image-preview` | 65,536 | 32,768 |
| Gemini 2.5 Pro | `models/gemini-2.5-pro` | 1,048,576 | 65,536 |
| Gemini 2.5 Flash | `models/gemini-2.5-flash` | 1,048,576 | 65,535 |
| Gemini 2.5 Flash Lite | `models/gemini-2.5-flash-lite` | 1,048,576 | 65,535 |
| Gemini 2.5 Flash Image | `models/gemini-2.5-flash-image` | 32,768 | 8,192 |
| Gemini 3 Pro Preview | `models/gemini-3-pro-preview` | 1,048,576 | 65,536 |
| Gemini 3 Pro Image | `models/gemini-3-pro-image` | 131,072 | 32,768 |
| Gemini 2.0 Flash | `models/gemini-2.0-flash` | 1,048,576 | 65,535 |
| Gemini 2.0 Flash Lite | `models/gemini-2.0-flash-lite` | — | 65,536 |
| Google: Gemini 2.5 Flash Lite Preview 09-2025 | `models/gemini-2.5-flash-lite-preview-09-2025` | 1,048,576 | 65,535 |
| Google: Gemini 2.5 Pro Preview 06-05 | `models/gemini-2.5-pro-preview` | 1,048,576 | 65,536 |
| Google: Gemini 2.5 Pro Preview 05-06 | `models/gemini-2.5-pro-preview-05-06` | 1,048,576 | 65,535 |
| Google: Gemini 3.1 Pro Preview Custom Tools | `models/gemini-3.1-pro-preview-customtools` | 1,048,576 | 65,536 |
| Google Gemini Flash Latest | `models/gemini-flash-latest` | 1,048,576 | 65,536 |
| Google Gemini Pro Latest | `models/gemini-pro-latest` | 1,048,576 | 65,536 |
| Google: Nano Banana 2 (Gemini 3.1 Flash Image) | `models/gemini-3.1-flash-image` | 131,072 | 32,768 |
| Google: Gemini 3.1 Flash Lite | `models/gemini-3.1-flash-lite` | 1,048,576 | 65,536 |
| Google: Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image) | `models/gemini-3.1-flash-lite-image` | 65,536 | 58,982 |
| `models-gemini-2-5-flash-batch` | `models/gemini-2.5-flash:batch` | 1,048,576 | 65,535 |
| `models-gemini-2-5-flash-lite-batch` | `models/gemini-2.5-flash-lite:batch` | 1,048,576 | 65,535 |
| `models-gemini-2-5-pro-batch` | `models/gemini-2.5-pro:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-1-flash-lite-batch` | `models/gemini-3.1-flash-lite:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-1-pro-preview-batch` | `models/gemini-3.1-pro-preview:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-5-flash-batch` | `models/gemini-3.5-flash:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-5-flash-lite-batch` | `models/gemini-3.5-flash-lite:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-6-flash-batch` | `models/gemini-3.6-flash:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-7-flash` | `models/gemini-3.7-flash` | 1,048,576 | 65,536 |
| `models-gemini-3-7-flash-batch` | `models/gemini-3.7-flash:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-8-flash` | `models/gemini-3.8-flash` | 1,048,576 | 65,536 |
| `models-gemini-3-8-flash-batch` | `models/gemini-3.8-flash:batch` | 1,048,576 | 65,536 |
| `models-gemini-3-flash-preview-batch` | `models/gemini-3-flash-preview:batch` | 1,048,576 | 65,536 |

</details>

Profiles whose titles contain **Image** support image generation output.

## Configuration

Choose a model profile and supply an API key. Named profiles pin the model,
context window, and output limit, so most pipelines need no other settings.

### Custom model

Select `custom` to enter a Gemini model identifier such as
`models/gemini-2.5-pro`, its combined input and output token limit, and its output
token limit. The custom defaults are 1,114,112 total tokens and 65,536 output
tokens; set both to the actual limits of the model you select.

## Authentication

Provide a Google AI Developer API key in the `apikey` field of the chosen profile
(create one in Google AI Studio). The key is stored as a secure field. Key format
validation is delegated to the google-genai library; a missing key fails at pipeline
start with `Please enter your Gemini API key.`

Gotcha: the engine derives a profile sub-key from the segment after the first
underscore of the profile name (e.g. `gemini-2_5-pro` is stored under `5-pro`). The
node transparently falls back to that sub-key when reading the API key, so keys saved
under either layout work.

Vertex AI is not used by this node; it targets the Gemini Developer API only. (The
google-genai client also supports Vertex AI via `genai.Client(vertexai=True, ...)`; a
future refactor could unify the separate Vertex node with this one.)

## Notes

### Deprecated profiles

The following profiles remain selectable for existing pipelines but are deprecated:

- Gemini 3 Pro Preview; use `gemini-3_1-pro-preview`.
- Gemini 3 Pro Image; use `gemini-3-pro-image-preview`.
- Gemini 2.0 Flash; use `gemini-2_5-flash`.
- Gemini 2.0 Flash Lite; use `gemini-2_5-flash-lite`.

### Running the tests

The node ships a `test` block in `services.json` that runs against a local test server
with a mocked `google.genai`, so no real API key is required. Set `ROCKETRIDE_MOCK` to
`nodes/test/mocks`; the test sends "What is 2+2?" on `questions` (profile
`gemini-2_5-flash`) and expects `answers` to contain "Mock LLM response".

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `gemini.apikey` | `string` | **API Key**<br/>Google AI Developer API key |  |
| `gemini.model` | `string` | **Model**<br/>Gemini model |  |
| `gemini.modelTotalTokens` | `number` | **Total Tokens**<br/>Maximum number of input + output tokens |  |
| `gemini.outputTokens` | `number` | **Output Tokens**<br/>Maximum number of output tokens |  |
| `gemini.profile` | `string` | **Model**<br/>Gemini LLM model | `"gemini-3_1-pro-preview"` |

## Dependencies

- `google-genai`
- `google-api-core`
- `google-auth`
- `googleapis-common-protos`
- `proto-plus`
- `protobuf`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_gemini)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# GLM (Z.ai)

Route: /nodes/llm_glm

# llm_glm

A RocketRide LLM node that connects Zhipu AI's GLM family of open-weight hybrid-reasoning models to a pipeline through the OpenAI-compatible Z.ai cloud API or a self-hosted vLLM or SGLang deployment.

## About Zhipu AI GLM

GLM is Zhipu AI's family of open-weight models, served through the OpenAI-compatible Z.ai cloud API ([z.ai](https://z.ai)). The international cloud endpoint is `https://api.z.ai/api/paas/v4` and the mainland China endpoint is `https://open.bigmodel.cn/api/paas/v4`. GLM weights are openly published on Hugging Face under MIT-style licenses (`zai-org/GLM-5.2`, `zai-org/GLM-4.5-Air`, and so on), so the same models can be served locally.

## What it does

Provides chat completion using GLM models as an `llm`-class invoke filter. It can be wired directly via lanes or consumed by any agent or node that needs an LLM backend.

The GLM-4.5 through GLM-5 generations are hybrid-reasoning MoE models with thinking and non-thinking modes and strong agentic and coding performance. The vision variants (GLM-4V and GLM-4.5V), embedding, CogView (image), CogVideoX (video), rerank, and audio lines are out of scope for this chat node.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **GLM-5.2** (`glm-5-2`). The profile set matches the live Z.ai `/models` catalog (verified 2026-08).

| Profile | Model | Context | Output | Notes |
| ------- | ----- | ------- | ------ | ----- |
| GLM-5.2 **(default)** | `glm-5.2` | 1,000,000 | 32,768 | Frontier long-context reasoning and coding |
| GLM-5.1 | `glm-5.1` | 204,800 | 32,768 | Previous flagship |
| GLM-5 | `glm-5` | 204,800 | 32,768 | First GLM-5 generation |
| GLM-5 Turbo | `glm-5-turbo` | 204,800 | 32,768 | Fast cost-effective tier |
| GLM-4.7 | `glm-4.7` | 204,800 | 32,768 | Enhanced-reasoning 4.x flagship |
| GLM-4.6 | `glm-4.6` | 204,800 | 32,768 | Open-weight 4.x flagship |

<details>
<summary><strong>View 3 more models</strong></summary>

| Profile | Model | Context | Output | Notes |
| ------- | ----- | ------- | ------ | ----- |
| GLM-4.5 | `glm-4.5` | 131,072 | 32,768 | Open-weight |
| GLM-4.5 Air | `glm-4.5-air` | 131,072 | 32,768 | Open-weight, efficient cost/quality balance |
| `custom` | _(user-specified)_ | 131,072 | 8,192 | Any model on an OpenAI-compatible endpoint |

</details>

## Configuration

Choose a model profile. The profile supplies the model identifier and context window, so a cloud pipeline needs no additional model settings. Budget generous output tokens for reasoning-heavy prompts.

To use a self-hosted vLLM or SGLang deployment, select the **Custom Model** profile and point its server base URL at your OpenAI-compatible endpoint. The API key may be left empty there: the node passes a dummy token, and local servers accept any value.

## Authentication

Cloud profiles require a Z.ai or Zhipu AI API key in `apikey`. The key requirement is enforced by base-URL match: if `serverbase` contains `api.z.ai` or `bigmodel.cn` and no key is set, the node raises `GLM API key is required for cloud profiles.` at startup. Key format is not validated beyond presence.

## Notes

### Reasoning output

GLM-4.5+ models are reasoning models. The Z.ai cloud returns reasoning in a separate `reasoning_content` field, and for endpoints that inline `<think>...</think>` blocks in `content` the engine's shared LangChain adapter strips them and routes the reasoning to the thinking lane, so the node needs no stripping of its own.

### Model sync

Profiles are maintained by the `sync_models` tooling (`llm_glm` provider, `ROCKETRIDE_GLM_KEY`). The include filter keeps only the `glm-*` text chat models; vision (4V and 4.5V), embedding, rerank, audio, and reward variants are excluded, because they belong in dedicated nodes.

## Upstream docs

- [Z.ai API documentation](https://docs.z.ai/api-reference)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `glm.profile` | `string` | **Model**<br/>Zhipu AI GLM LLM model | `"glm-5-2"` |
| `glm.serverbase` | `string` | **Server base URL**<br/>OpenAI-compatible base URL for the GLM endpoint (e.g. https://api.z.ai/api/paas/v4 for the Z.ai cloud API, http://localhost:8000/v1 for a self-hosted vLLM / SGLang server). | `"https://api.z.ai/api/paas/v4"` |
| `model` | `string` | **Model**<br/>Zhipu AI GLM model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_glm)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# GMI Cloud

Route: /nodes/llm_gmi_cloud

# llm_gmi_cloud

A RocketRide LLM node that connects GMI Cloud-hosted models to a pipeline through
GMI Cloud's OpenAI-compatible API.

## About GMI Cloud

GMI Cloud is a cloud platform for deploying and serving AI models through managed
inference endpoints. Its catalog includes open-weight models and access to models
from multiple providers.

## What it does

Connects GMI Cloud-hosted models to a pipeline via an OpenAI-compatible API. Use it
as an `llm` invoke connection for agents and other nodes that need an LLM, or wire
it directly through the question and answer lanes.

Built on **langchain-openai's `ChatOpenAI`** client pointed at the GMI Cloud endpoint,
with `temperature` fixed at `0`. Rate-limit and connection errors are treated as
retryable; authentication and other API errors are mapped to friendly messages
(e.g. `Invalid API key.`).

Two safety behaviors are enforced on the endpoint URL: it must use **HTTPS**, and the
hostname must be `gmi-serving.com` or a subdomain of it (an SSRF guard on user-supplied
endpoints). This is checked both at save time and when the pipeline starts. An API key is
required at pipeline start; the shared endpoint `https://api.gmi-serving.com/v1` is used
when no endpoint URL is configured.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **DeepSeek V3** (`deepseek-v3`).

| Profile | Model | Context tokens |
| ------- | ----- | -------------- |
| DeepSeek V3 **(default)** | `deepseek-ai/DeepSeek-V3-0324` | 163,840 |
| Gemini 3.1 Pro | `google/gemini-3.1-pro-preview` | 128,000 |
| Gemini 3.1 Flash Lite | `google/gemini-3.1-flash-lite-preview` | 128,000 |
| GPT-5.2 | `openai/gpt-5.2` | 128,000 |

<details>
<summary><strong>View 18 more models</strong></summary>

| Profile | Model | Context tokens |
| ------- | ----- | -------------- |
| `custom` | _(user-specified)_ | editable |
| Llama 4 Scout | `meta-llama/Llama-4-Scout-17B-16E-Instruct` | 1,048,576 |
| Llama 4 Maverick | `meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 1,048,576 |
| Qwen3 235B | `Qwen/Qwen3-235B-A22B-FP8` | 131,072 |
| Qwen3 32B | `Qwen/Qwen3-32B-FP8` | 131,072 |
| Qwen3 30B | `Qwen/Qwen3-30B-A3B` | 131,072 |
| Qwen3 Coder 480B | `Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8` | 131,072 |
| DeepSeek V3.2 | `deepseek-ai/DeepSeek-V3.2` | 163,840 |
| DeepSeek R1 | `deepseek-ai/DeepSeek-R1` | 131,072 |
| DeepSeek R1 Distill 32B | `deepseek-ai/DeepSeek-R1-Distill-Qwen-32B` | 131,072 |
| DeepSeek R1 Distill 1.5B | `deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B` | 131,072 |
| DeepSeek Prover V2 | `deepseek-ai/DeepSeek-Prover-V2-671B` | 131,072 |
| GPT-5.1 | `openai/gpt-5.1` | 128,000 |
| GPT-5 | `openai/gpt-5` | 128,000 |
| GPT-4o | `openai/gpt-4o` | 128,000 |
| Claude Opus 4.5 | `anthropic/claude-opus-4.5` | 200,000 |
| Claude Sonnet 4.5 | `anthropic/claude-sonnet-4.5` | 200,000 |
| Gemini 3 Flash | `google/gemini-3-flash-preview` | 128,000 |

</details>

## Configuration

Choose a profile for a shared or deployed model. Named profiles set the model and
context limit; shared models also use the default endpoint, so most pipelines only
need an API key.

### Endpoint URL

Deploy-on-demand profiles require the endpoint supplied by the GMI Cloud console.
The URL must use HTTPS and its hostname must be `gmi-serving.com` or a subdomain;
other hosts are rejected. The shared endpoint defaults to
`https://api.gmi-serving.com/v1`.

### Custom models

Select `custom` to provide a GMI Cloud model identifier, its context limit, and an
endpoint URL directly. Open-weight identifiers use `org/model-name`, such as
`deepseek-ai/DeepSeek-R1`; proxied identifiers use `provider/model-name`, such as
`openai/gpt-4o`.

## Authentication

Provide a GMI Cloud API key in the **API Key** field. That is sufficient for
shared-tier models. For deploy-on-demand models, deploy the model in the
[GMI Cloud console](https://console.gmicloud.ai) and also provide the unique
endpoint URL.

## Notes

### Model tiers

Shared models are available immediately at the shared endpoint with an API key.
Llama, Qwen, and R1 Distill profiles are deploy-on-demand and require an endpoint
created in the GMI Cloud console. The custom profile accepts any GMI Cloud model ID,
token limit, and endpoint URL directly.

### Save-time validation

When the node configuration is saved, it is validated against the live API:

- Validation is skipped when the model or API key is not set yet, or (for
  deploy-on-demand profiles) when the endpoint URL has not been entered yet.
- The endpoint URL is checked for HTTPS and the `gmi-serving.com` domain.
- If the model name looks like a vision/multimodal model (contains `vl`, `vision`,
  `visual`, or `multimodal`), a warning is raised suggesting a vision node instead, and
  the API probe is skipped, since vision models may reject text-only requests.
- Otherwise a 1-token chat request probes the API to confirm both the API key and the
  model's existence. An HTTP 429 (rate limit) during the probe means the key was accepted
  and is treated as valid. Other API errors surface as warnings with the HTTP status,
  provider error type, and message.

## Upstream docs

- [GMI Cloud model catalogue](https://www.gmicloud.ai/models)
- [GMI Cloud console](https://console.gmicloud.ai)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `gmi_cloud.profile` | `string` | **Model**<br/>GMI Cloud LLM model | `"deepseek-v3"` |
| `gmi_cloud.serverbase` | `string` | **Endpoint URL**<br/>Your GMI Cloud deployment endpoint URL. Deploy the model at console.gmicloud.ai, then paste the provided endpoint URL here. |  |
| `model` | `string` | **Model**<br/>GMI Cloud model identifier. Use org/model-name for open-weight models (e.g. deepseek-ai/DeepSeek-R1, Qwen/Qwen3-32B-FP8) or provider/model-name for proxied models (e.g. openai/gpt-4o, anthropic/claude-sonnet-4.5, google/gemini-3-flash-preview). Full list: https://www.gmicloud.ai/models |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_gmi_cloud)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# IBM Watson

Route: /nodes/llm_ibm_watson

# llm_ibm_watson

A RocketRide LLM node that connects IBM watsonx foundation models to a pipeline via the IBM Cloud API.

## What it does

Connects IBM watsonx foundation models to your pipeline via the IBM Cloud API. Used primarily as an `llm` invoke connection by agents and other nodes that need an LLM. Can also be used directly via lanes.

Uses the **ibm-watsonx-ai** SDK (`ModelInference` with `TextChatParameters`). The service URL is derived from the configured location as `https://<location>.ml.cloud.ibm.com`. The location is validated against a fixed allowlist of known IBM Cloud regions before any connection is made. Temperature is fixed at `1`.

All four configuration fields are required. The node raises a configuration error at pipeline start if the API key, location, model ID, or project ID is missing, or if the location is not a known IBM Cloud region.

Token counts are estimated with a simple word-based approximation (roughly 0.75 tokens per word) rather than the model's native tokenizer.

---

## Configuration

### Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

### Fields

| Field        | Type   | Description                                                         |
| ------------ | ------ | ------------------------------------------------------------------- |
| `apikey`     | string | IBM Cloud API key (required)                                        |
| `location`   | enum   | IBM Cloud region (required, see below)                              |
| `model`      | string | watsonx model ID, specified directly; no preset profiles (required) |
| `project_id` | string | IBM watsonx project ID (required)                                   |

### Locations

The `location` value must be one of the following known IBM Cloud regions. Any other value is rejected at startup.

| Value      | Region        |
| ---------- | ------------- |
| `us-south` | Dallas        |
| `us-east`  | Washington DC |
| `eu-gb`    | London        |
| `eu-de`    | Frankfurt     |
| `eu-es`    | Madrid        |
| `jp-tok`   | Tokyo         |
| `jp-osa`   | Osaka         |
| `au-syd`   | Sydney        |
| `ca-tor`   | Toronto       |
| `br-sao`   | Sao Paulo     |

---

## Invoke functions

When used as an `llm` invoke connection, the node exposes the following functions to connected agents and other nodes:

| Function           | Description                                        |
| ------------------ | -------------------------------------------------- |
| `ask`              | Send a question and receive the generated answer   |
| `getContextLength` | Total context window size, in tokens               |
| `getOutputLength`  | Maximum output size, in tokens                     |
| `getTokenCounter`  | Token-counting function (word-based approximation) |

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_ibm_watson)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Kimi (Moonshot)

Route: /nodes/llm_kimi

# llm_kimi

A RocketRide LLM node that connects Moonshot AI's Kimi models to a pipeline through the OpenAI-compatible Moonshot API.

## What it does

Provides chat completion using Kimi and Moonshot models as an `llm`-class invoke filter. It can be wired directly via lanes or consumed by any agent or node that needs an LLM backend.

Built on **langchain-openai** (`ChatOpenAI`) pointed at the Moonshot endpoint; the **openai** SDK is used only for the save-time configuration probe. The request's `max_tokens` is set from the active profile's output token limit.

Temperature is set automatically per model family: Kimi K2 models run at temperature `1` (the API rejects any other value with "invalid temperature: only 1 is allowed for this model"), while the classic Moonshot v1 models run at temperature `0` for deterministic pipeline output.

When the node configuration is saved, cloud Moonshot endpoints (where `serverbase` contains `api.moonshot`) are validated with a minimal 1-token probe request. Failures are surfaced as warnings with the provider's HTTP status, error type, and message. Self-hosted or local OpenAI-compatible endpoints are not validated at save time.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Kimi K2.6** (`kimi-k2-6`).

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| Kimi K2.6 **(default)** | `kimi-k2.6` | 262,144 | 16,384 |
| MoonshotAI: Kimi K3 | `kimi-k3` | 1,048,576 | 943,718 |
| MoonshotAI: Kimi K2.7 Code | `kimi-k2.7-code` | 262,144 | 235,929 |

<details>
<summary><strong>View 9 more models</strong></summary>

| Profile | Model | Context tokens | Output tokens |
| ------- | ----- | -------------- | ------------- |
| Kimi K2.5 | `kimi-k2.5` | 262,144 | 16,384 |
| Moonshot v1 8K | `moonshot-v1-8k` | 8,192 | 4,096 |
| Moonshot v1 32K | `moonshot-v1-32k` | 32,768 | 4,096 |
| Moonshot v1 128K | `moonshot-v1-128k` | 131,072 | 4,096 |
| MoonshotAI: Kimi K2 0711 | `kimi-k2` | 131,072 | 100,352 |
| MoonshotAI: Kimi K2 0905 | `kimi-k2-0905` | 262,144 | 100,352 |
| MoonshotAI: Kimi K2 Thinking | `kimi-k2-thinking` | 262,144 | 100,352 |
| MoonshotAI Kimi Latest | `kimi-latest` | 1,048,576 | 943,718 |
| `kimi-k3-batch` | `kimi-k3:batch` | 1,048,576 | 943,718 |

</details>

## Configuration

Choose a model profile. The profile supplies the model identifier, context window,
and output limit, so the UI requires no additional model settings.

## Authentication

Cloud Moonshot endpoints require an API key starting with `sk-`. Any other format is rejected at startup with a key-format error. Keys are issued at the [Moonshot AI platform](https://platform.moonshot.ai/docs).

If no API key is configured (typical for self-hosted OpenAI-compatible endpoints), a placeholder key (`sk-local-dummy-key`) is sent instead because the OpenAI client requires a non-empty value.

## Notes

### Text-only models

Moonshot also publishes `moonshot-v1-{8k,32k,128k}-vision-preview` image-input
models. Those belong in a dedicated vision node in the `llm_vision_*` family and
are not available in this text-only node.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `kimi.profile` | `string` | **Model**<br/>Kimi (Moonshot) LLM model | `"kimi-k2-6"` |
| `model` | `string` | **Model**<br/>Kimi (Moonshot) model |  |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_kimi)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# MiniMax

Route: /nodes/llm_minimax

# llm_minimax

A RocketRide LLM node that connects MiniMax models to a pipeline via the MiniMax cloud API or a self-hosted OpenAI-compatible server.

## What it does

Provides MiniMax chat models as an `llm` invoke connection for agents and other nodes that need an LLM, and can also be used directly via lanes. It works against the MiniMax cloud API or a self-hosted OpenAI-compatible server (vLLM, SGLang, MLX, or Ollama).

The MiniMax API is OpenAI-compatible, so the node uses **langchain-openai** (`ChatOpenAI`) pointed at the configured base URL, with `temperature: 0` and the profile's output-token limit as `max_tokens`. Config validation at save time runs a minimal one-token probe through the **openai** SDK and surfaces provider errors as warnings.

MiniMax M2-series models return chain-of-thought wrapped in `<think>...</think>` inside the `content` field; the node strips that block so downstream pipeline nodes only see the final answer.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **MiniMax M2** (`minimax-m2`).

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `minimax-m2` **(default)** | `MiniMax-M2` | 204,800 | 65,536 |
| `minimax-m3` | `MiniMax-M3` | 1,000,000 | 131,072 |
| `minimax-m2-7` | `MiniMax-M2.7` | 204,800 | 65,536 |
| `minimax-m2-7-highspeed` | `MiniMax-M2.7-highspeed` | 204,800 | 65,536 |
| `minimax-m2-7-local` | `MiniMaxAI/MiniMax-M2.7` | 204,800 | 8,192 |

<details>
<summary><strong>View 13 more models</strong></summary>

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `custom` | _(user-specified)_ | 200,000 | 8,192 |
| `minimax-m2-1` | `MiniMax-M2.1` | 204,800 | 65,536 |
| `minimax-m2-1-highspeed` | `MiniMax-M2.1-highspeed` | 204,800 | 65,536 |
| `minimax-m2-5` | `MiniMax-M2.5` | 204,800 | 65,536 |
| `minimax-m2-5-highspeed` | `MiniMax-M2.5-highspeed` | 204,800 | 65,536 |
| `minimax-m2-local` | `MiniMaxAI/MiniMax-M2` | 204,800 | 8,192 |
| `minimax-m2-5-local` | `MiniMaxAI/MiniMax-M2.5` | 204,800 | 8,192 |
| `minimax-01` | `minimax-01` | 1,000,192 | 900,172 |
| `minimax-m1` | `minimax-m1` | 1,000,000 | 40,000 |
| `minimax-m2-her` | `minimax-m2-her` | 65,536 | 2,048 |
| `minimax-m2-7-free` | `minimax-m2.7:free` | 196,608 | 176,947 |
| `minimax-m3-batch` | `minimax-m3:batch` | 524,288 | 471,859 |
| `minimax-m3-free` | `minimax-m3:free` | 1,048,576 | 943,718 |

</details>

The `-highspeed` variants are MiniMax's faster tier of the same generation. MiniMax M3 is multimodal at the API level, though this node exposes only text.

## Configuration

Choose a profile to set the model and token limits. Cloud profiles target MiniMax's API; local profiles prefill the Hugging Face model path and a local OpenAI-compatible server, while `custom` exposes the model, context budget, and server URL for manual configuration.

### Server base URL

Use `https://api.minimax.io/v1` for the international cloud API or `https://api.minimaxi.com/v1` for China. Local profiles default to vLLM or SGLang at `http://localhost:8000/v1`; change the URL when using MLX, Ollama, or another OpenAI-compatible server.

## Authentication

Cloud profiles require a MiniMax API key in `apikey`. The key requirement is enforced by base-URL match: if `serverbase` contains `api.minimax` (covers both `api.minimax.io` international and `api.minimaxi.com` China) and no key is set, the node raises `MiniMax API key is required for cloud profiles.` at startup.

Local profiles (vLLM / SGLang / MLX / Ollama) have no `apikey` field; local OpenAI-compatible servers accept any token, so the node passes a dummy key (`sk-local-dummy-key`).

## Notes

### Local deployment

MiniMax's open-weight M2-family models are MIT-licensed 230B-parameter MoE models with about 10B parameters active per token. They require substantial memory:

- **Linux + GPU (at least 96 GB total VRAM):** Run vLLM or SGLang on port `8000` and use the profile's Hugging Face model path.
- **Apple Silicon Mac Studio (at least 128 GB unified memory):** Run MLX on port `8080`, set the server URL to `http://localhost:8080/v1`, and use a quantized build such as `mlx-community/MiniMax-M2.7-4bit`.
- **Ollama on lower-memory systems:** Set the server URL to `http://localhost:11434/v1` and use the tag you pulled. Verify that the tag exists before configuring it.

These models do not fit on a typical laptop without aggressive quantization. M2.7 is a reasoning model whose API separates `message.content` from `message.reasoning_content`, so allow a generous output budget even for short prompts.

## Upstream docs

- [MiniMax platform documentation](https://platform.minimaxi.com/document/)
- [MiniMax API reference (OpenAI-compatible)](https://www.minimax.io/platform/document/ChatCompletion)
- [MiniMax local deployment guide](https://platform.minimax.io/docs/guides/local-deploy)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `minimax.profile` | `string` | **Model**<br/>MiniMax LLM model | `"minimax-m2"` |
| `minimax.serverbase` | `string` | **Server base URL**<br/>OpenAI-compatible base URL for the MiniMax endpoint (e.g. https://api.minimax.io/v1 for international, https://api.minimaxi.com/v1 for China). | `"https://api.minimax.io/v1"` |
| `model` | `string` | **Model**<br/>MiniMax model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_minimax)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Mistral AI

Route: /nodes/llm_mistral

# llm_mistral

A RocketRide LLM node that connects Mistral AI's chat models to a pipeline.

## What it does

Connects Mistral AI models to your pipeline. Used primarily as an `llm` invoke connection
by agents and other nodes that need an LLM. Can also be used directly via lanes.

Uses the official **`mistralai`** Python SDK (both the 1.x and 2.x import layouts are
supported) and calls the `chat.complete` endpoint. Requests are sent with
`temperature: 0.0` for deterministic responses and no `max_tokens` cap, so the model
decides output length.

Prompts are validated against the model's context window before sending. Token counts are
estimated heuristically (about 1.25 tokens per word, adjusted for punctuation and long
words); no tokenizer round-trip is made. The context limit comes from the selected
profile's `modelTotalTokens`; if not configured, a built-in per-model default is used,
falling back to 32,768 tokens for unknown models.

Failed API calls are retried automatically with exponential backoff (see
[Retries and error handling](#retries-and-error-handling)), and raw provider errors are
rewritten into user-friendly messages.

When you save the node configuration, a minimal validation probe (a one-token `"Hi"`
completion) is sent to verify the API key and model before the pipeline ever runs.
Validation failures surface as warnings with the provider's error detail.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Mistral Large 3** (`mistral-large`).

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `mistral-large` **(default)** | `mistral-large-2512` | 262,144 | 209,715 |
| `mistral-medium-2604` | `mistral-medium-2604` | 16,384 | 4,096 |
| `mistral-small-2603` | `mistral-small-2603` | 262,144 | 209,715 |

<details>
<summary><strong>View 41 more models</strong></summary>

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `custom` | _(user-specified)_ | 32,768 | editable |
| `mistral-medium` | `mistral-medium-2508` | 131,072 | 4,096 |
| `mistral-small` | `mistral-small-2506` | 131,072 | 4,096 |
| `codestral` | `codestral-2508` | 256,000 | 204,800 |
| `magistral-medium` | `magistral-medium-2509` | 40,000 | 40,000 |
| `magistral-small` | `magistral-small-2509` | 40,960 | 4,096 |
| `devstral-medium` | `devstral-medium-2507` | 128,000 | 128,000 |
| `devstral-small` | `devstral-small-2507` | 128,000 | 128,000 |
| `ministral-14b` | `ministral-14b-2512` | 262,144 | 209,715 |
| `ministral-8b` | `ministral-8b-2512` | 262,144 | 209,715 |
| `ministral-3b` | `ministral-3b-2512` | 131,072 | 104,857 |
| `codestral-latest` | `codestral-latest` | 8,191 | 8,191 |
| `devstral-2512` | `devstral-2512` | 262,144 | 209,715 |
| `devstral-latest` | `devstral-latest` | 256,000 | 256,000 |
| `devstral-medium-latest` | `devstral-medium-latest` | 256,000 | 256,000 |
| `magistral-medium-latest` | `magistral-medium-latest` | 40,000 | 40,000 |
| `magistral-small-latest` | `magistral-small-latest` | 40,000 | 40,000 |
| `ministral-14b-latest` | `ministral-14b-latest` | 16,384 | 4,096 |
| `ministral-3b-latest` | `ministral-3b-latest` | 16,384 | 4,096 |
| `ministral-8b-latest` | `ministral-8b-latest` | 16,384 | 4,096 |
| `mistral-large-2411` | `mistral-large-2411` | 131,072 | 128,000 |
| `mistral-large-latest` | `mistral-large-latest` | 32,000 | 4,096 |
| `mistral-medium-2505` | `mistral-medium-2505` | 8,191 | 8,191 |
| `mistral-medium-3` | `mistral-medium-3` | 131,072 | 104,857 |
| `mistral-medium-3-5` | `mistral-medium-3-5` | 262,144 | 209,715 |
| `mistral-medium-c21211-r0-75` | `mistral-medium-c21211-r0-75` | 16,384 | 4,096 |
| `mistral-medium-latest` | `mistral-medium-latest` | 131,072 | 131,072 |
| `mistral-small-latest` | `mistral-small-latest` | 131,072 | 131,072 |
| `mistral-tiny-2407` | `mistral-tiny-2407` | 16,384 | 4,096 |
| `mistral-tiny-latest` | `mistral-tiny-latest` | 16,384 | 4,096 |
| `mistral-vibe-cli-fast` | `mistral-vibe-cli-fast` | 16,384 | 4,096 |
| `mistral-vibe-cli-latest` | `mistral-vibe-cli-latest` | 16,384 | 4,096 |
| `mistral-vibe-cli-with-tools` | `mistral-vibe-cli-with-tools` | 16,384 | 4,096 |
| `mistral-large-2407` | `mistral-large-2407` | 131,072 | 104,857 |
| `mistral-medium-3-1` | `mistral-medium-3.1` | 131,072 | 104,857 |
| `mistral-nemo` | `mistral-nemo` | 131,072 | 16,384 |
| `mistral-saba` | `mistral-saba` | 32,768 | 26,214 |
| `mistral-small-24b-instruct-2501` | `mistral-small-24b-instruct-2501` | 32,768 | 16,384 |
| `mistral-small-3-1-24b-instruct` | `mistral-small-3.1-24b-instruct` | 128,000 | 102,400 |
| `mistral-small-3-2-24b-instruct` | `mistral-small-3.2-24b-instruct` | 131,072 | 16,384 |
| `mistral-medium-3-5-batch` | `mistral-medium-3-5:batch` | 32,768 | 26,214 |

</details>

## Configuration

Choose a profile to pin the Mistral model and its declared context and output limits. Most users only need to select a profile and supply an API key; choose `custom` to enter another Mistral model ID and context limit, and use an explicit context limit only when you need to override the built-in per-model value.

## Authentication

Provide a Mistral AI API key in the `apikey` field (created in the
[Mistral AI console](https://console.mistral.ai/)). The key is read at startup and never
persisted by the node.

The node detects common key mix-ups at initialization and fails with a specific message:

- Keys starting with `sk-` are rejected as OpenAI keys.
- Keys starting with `AI` are rejected as Google AI / Gemini keys.

## Notes

### Retries and error handling

Transient failures (timeouts, network errors, rate limits, HTTP 5xx) are retried with
exponential backoff. Retry budget scales with the model tier:

| Model tier                      | Retries | Base delay |
| ------------------------------- | ------- | ---------- |
| `large` models                  | 3       | 2.0 s      |
| `medium` / `magistral` models   | 2       | 1.5 s      |
| All other (small / edge) models | 2       | 1.0 s      |

Non-retryable errors fail immediately. Whatever the cause, the raw API error is mapped to
a user-friendly message: authentication failures, rate limits, quota/billing issues,
invalid input, model unavailability, server errors, content-policy violations, timeouts,
and network problems each get a specific explanation instead of a stack trace.

## Upstream docs

- [Mistral AI documentation](https://docs.mistral.ai/)
- [Mistral AI console](https://console.mistral.ai/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `mistral.profile` | `string` | **Model**<br/>Mistral AI model selection | `"mistral-large"` |
| `model` | `string` | **Model**<br/>Mistral AI model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |

## Dependencies

- `mistralai`
- `mistral-common[sentencepiece]`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_mistral)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Ollama

Route: /nodes/llm_ollama

# llm_ollama

A RocketRide LLM node that routes pipeline traffic through a locally-hosted Ollama server.

## What it does

Provides text generation against an Ollama server running on your own hardware. The node acts as an `llm` connection for agents and other nodes, and can also be driven directly through its `questions` and `answers` lanes. Because inference stays on-premise and requires no external API key, it fits privacy-sensitive or air-gapped deployments. Internally, it uses **langchain-openai** (`ChatOpenAI`) against Ollama's OpenAI-compatible `/v1` endpoint.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Llama 3.3** (`llama3_3`).

| Profile | Model | Context |
| ------- | ----- | ------- |
| `llama3_3` **(default)** | `llama3.3:latest` | 128,000 |
| `llama4-latest` | `llama4:latest` | 10,000,000 |
| `qwen3-latest` | `qwen3:latest` | 128,000 |

<details>
<summary><strong>View 20 more models</strong></summary>

| Profile | Model | Context |
| ------- | ----- | ------- |
| `custom` | _(user-specified)_ | 16,385 |
| `llama3_1-8b` | `llama3.1:8b` | 128,000 |
| `llama3_1-70b` | `llama3.1:70b` | 128,000 |
| `llama3_1-405b` | `llama3.1:405b` | 128,000 |
| `phi4-14b` | `phi4` | 16,000 |
| `llama3_2-3b` | `llama3.2` | 128,000 |
| `llama3_2-1b` | `llama3.2:1b` | 128,000 |
| `mistral-7b` | `mistral` | 32,000 |
| `qwen2_5-7b` | `qwen2.5` | 128,000 |
| `qwen2_5-0_5b` | `qwen2.5:0.5b` | 128,000 |
| `qwen2_5-1_5b` | `qwen2.5:1.5b` | 128,000 |
| `qwen2_5-3b` | `qwen2.5:3b` | 128,000 |
| `qwen2_5-14b` | `qwen2.5:14b` | 128,000 |
| `qwen2_5-32b` | `qwen2.5:32b` | 128,000 |
| `qwen2_5-72b` | `qwen2.5:72b` | 128,000 |
| `deepseek-r1-1_5b` | `deepseek-r1:1.5b` | 128,000 |
| `deepseek-r1-7b` | `deepseek-r1:7b` | 128,000 |
| `deepseek-r1-14b` | `deepseek-r1:14b` | 128,000 |
| `deepseek-r1-32b` | `deepseek-r1:32b` | 128,000 |
| `deepseek-r1-671b` | `deepseek-r1:671b` | 128,000 |

</details>

## Configuration

Pick a profile to prefill the Ollama model, context limit, and server URL. Use `custom` to supply another Ollama tag, context token count, and endpoint; its initial context value is 16,385 tokens.

### Server base URL

Point the node at the Ollama server, normally `http://localhost:11434`. If the URL does not end in `/v1`, the node appends it automatically, so both `http://localhost:11434` and `http://localhost:11434/v1` work.

### Temperature and reasoning effort

Temperature defaults to `0`. When it is left unset for a reasoning model such as `gpt-oss`, the node uses `1.0`; set `reasoning_effort` to `low`, `medium`, or `high` when the selected model supports that control.

The OpenAI client requires a non-empty API key, so the node sends the placeholder `dummy-key`, which Ollama ignores.

## Upstream docs

- [Ollama documentation](https://docs.ollama.com/)
- [Ollama model library](https://ollama.com/library)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `model` | `string` | **Model**<br/>Ollama model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `ollama.profile` | `string` | **Model**<br/>LLM model | `"llama3_3"` |
| `reasoning_effort` | `string` | **Reasoning Effort**<br/>Optional reasoning budget for reasoning models: low, medium, or high. Leave unset to let reasoning models auto-use 'low'; a value set here always wins. Ignored by non-reasoning models. |  |
| `temperature` | `number` | **Temperature**<br/>Sampling temperature. Left unset by default so ollama.py can choose: 0 for standard models, and 1.0 for reasoning models (gpt-oss, deepseek-r1, qwen3, qwq, ...) so they emit a final answer instead of looping on empty output. Set an explicit value here to override the auto behavior. |  |

## Dependencies

- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_ollama)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# OpenAI

Route: /nodes/llm_openai

# llm_openai

A RocketRide LLM node that connects OpenAI GPT models to a pipeline.

## What it does

Provides an OpenAI-backed chat LLM for agents and other nodes that need a language model. It can also be wired directly through the `questions` and `answers` lanes. The node uses **langchain-openai** (`ChatOpenAI`) and the **openai** SDK, routing reasoning-capable models through the Responses API while other models use Chat Completions.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **GPT-5.2** (`openai-5-2`).

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `openai-5-2` **(default)** | `gpt-5.2` | 400,000 | 128,000 |
| `gpt-5-6-sol` | `gpt-5.6-sol` | 1,050,000 | 128,000 |
| `gpt-5-6-terra` | `gpt-5.6-terra` | 1,050,000 | 128,000 |
| `gpt-5-6-luna` | `gpt-5.6-luna` | 1,050,000 | 128,000 |
| `gpt-5-5` | `gpt-5.5` | 1,050,000 | 128,000 |

<details>
<summary><strong>View 80 more models</strong></summary>

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `custom` | _(user-specified)_ | 16,384 | editable |
| `openai-5-4` | `gpt-5.4` | 1,050,000 | 128,000 |
| `openai-5-4-pro` | `gpt-5.4-pro` | 1,050,000 | 128,000 |
| `openai-5-4-mini` | `gpt-5.4-mini` | 400,000 | 128,000 |
| `openai-5-4-nano` | `gpt-5.4-nano` | 400,000 | 128,000 |
| `openai-4o` | `gpt-4o` | 128,000 | 16,384 |
| `openai-4o-mini` | `gpt-4o-mini` | 128,000 | 16,384 |
| `openai-5` | `gpt-5` | 400,000 | 128,000 |
| `openai-5-1` | `gpt-5.1` | 400,000 | 128,000 |
| `openai-5-mini` | `gpt-5-mini` | 400,000 | 128,000 |
| `openai-5-nano` | `gpt-5-nano` | 400,000 | 128,000 |
| `gpt-3-5-turbo` | `gpt-3.5-turbo` | 16,385 | 4,096 |
| `gpt-3-5-turbo-16k` | `gpt-3.5-turbo-16k` | 16,385 | 4,096 |
| `gpt-4` | `gpt-4` | 8,191 | 4,096 |
| `gpt-4-1` | `gpt-4.1` | 1,047,576 | 32,768 |
| `gpt-4-1-mini` | `gpt-4.1-mini` | 1,047,576 | 32,768 |
| `gpt-4-1-nano` | `gpt-4.1-nano` | 1,047,576 | 32,768 |
| `gpt-4-turbo` | `gpt-4-turbo` | 128,000 | 4,096 |
| `gpt-5-1-chat-latest` | `gpt-5.1-chat-latest` | 128,000 | 16,384 |
| `gpt-5-2-chat-latest` | `gpt-5.2-chat-latest` | 128,000 | 16,384 |
| `gpt-5-3-chat-latest` | `gpt-5.3-chat-latest` | 128,000 | 16,384 |
| `gpt-5-chat-latest` | `gpt-5-chat-latest` | 128,000 | 16,384 |
| `o1` | `o1` | 200,000 | 100,000 |
| `o3` | `o3` | 200,000 | 100,000 |
| `o3-mini` | `o3-mini` | 200,000 | 100,000 |
| `o4-mini` | `o4-mini` | 200,000 | 100,000 |
| `gpt-4-turbo-preview` | `gpt-4-turbo-preview` | 128,000 | 4,096 |
| `gpt-5-1-chat` | `gpt-5.1-chat` | 128,000 | 16,384 |
| `gpt-5-3-chat` **(deprecated)** | `gpt-5.3-chat` | 128,000 | 16,384 |
| `gpt-5-6-luna-pro` | `gpt-5.6-luna-pro` | 1,050,000 | 128,000 |
| `gpt-5-6-sol-pro` | `gpt-5.6-sol-pro` | 1,050,000 | 128,000 |
| `gpt-5-6-terra-pro` | `gpt-5.6-terra-pro` | 1,050,000 | 128,000 |
| `gpt-5-chat` | `gpt-5-chat` | 128,000 | 16,384 |
| `gpt-chat-latest` | `gpt-chat-latest` | 400,000 | 128,000 |
| `gpt-latest` | `gpt-latest` | 1,050,000 | 128,000 |
| `gpt-mini-latest` | `gpt-mini-latest` | 400,000 | 128,000 |
| `gpt-oss-120b` | `gpt-oss-120b` | 131,072 | 117,964 |
| `gpt-oss-120b-free` **(deprecated)** | `gpt-oss-120b:free` | 131,072 | 131,072 |
| `gpt-oss-20b` | `gpt-oss-20b` | 131,072 | 117,964 |
| `gpt-oss-20b-free` | `gpt-oss-20b:free` | 131,072 | 32,768 |
| `gpt-oss-safeguard-20b` | `gpt-oss-safeguard-20b` | 131,072 | 65,536 |
| `o3-mini-high` | `o3-mini-high` | 200,000 | 100,000 |
| `o3-pro` | `o3-pro` | 200,000 | 100,000 |
| `o4-mini-high` | `o4-mini-high` | 200,000 | 100,000 |
| `gpt-3-5-turbo-batch` | `gpt-3.5-turbo:batch` | 16,385 | 4,096 |
| `gpt-4-1-batch` | `gpt-4.1:batch` | 1,047,576 | 32,768 |
| `gpt-4-1-mini-batch` | `gpt-4.1-mini:batch` | 1,047,576 | 32,768 |
| `gpt-4-1-nano-batch` | `gpt-4.1-nano:batch` | 1,047,576 | 32,768 |
| `gpt-4-turbo-batch` | `gpt-4-turbo:batch` | 128,000 | 4,096 |
| `gpt-4o-batch` | `gpt-4o:batch` | 128,000 | 16,384 |
| `gpt-4o-mini-batch` | `gpt-4o-mini:batch` | 128,000 | 16,384 |
| `gpt-5-1-batch` | `gpt-5.1:batch` | 400,000 | 128,000 |
| `gpt-5-2-batch` | `gpt-5.2:batch` | 400,000 | 128,000 |
| `gpt-5-2-chat` | `gpt-5.2-chat` | 128,000 | 32,000 |
| `gpt-5-2-pro-batch` | `gpt-5.2-pro:batch` | 400,000 | 128,000 |
| `gpt-5-4-batch` | `gpt-5.4:batch` | 1,050,000 | 128,000 |
| `gpt-5-4-mini-batch` | `gpt-5.4-mini:batch` | 400,000 | 128,000 |
| `gpt-5-4-nano-batch` | `gpt-5.4-nano:batch` | 400,000 | 128,000 |
| `gpt-5-4-pro-batch` | `gpt-5.4-pro:batch` | 1,050,000 | 128,000 |
| `gpt-5-5-batch` | `gpt-5.5:batch` | 1,050,000 | 128,000 |
| `gpt-5-5-pro-batch` | `gpt-5.5-pro:batch` | 1,050,000 | 128,000 |
| `gpt-5-6-luna-batch` | `gpt-5.6-luna:batch` | 1,050,000 | 128,000 |
| `gpt-5-6-luna-pro-batch` | `gpt-5.6-luna-pro:batch` | 1,050,000 | 128,000 |
| `gpt-5-6-sol-batch` | `gpt-5.6-sol:batch` | 1,050,000 | 128,000 |
| `gpt-5-6-sol-pro-batch` | `gpt-5.6-sol-pro:batch` | 1,050,000 | 128,000 |
| `gpt-5-6-terra-batch` | `gpt-5.6-terra:batch` | 1,050,000 | 128,000 |
| `gpt-5-6-terra-pro-batch` | `gpt-5.6-terra-pro:batch` | 1,050,000 | 128,000 |
| `gpt-5-batch` | `gpt-5:batch` | 400,000 | 128,000 |
| `gpt-5-mini-batch` | `gpt-5-mini:batch` | 400,000 | 128,000 |
| `gpt-5-nano-batch` | `gpt-5-nano:batch` | 400,000 | 128,000 |
| `gpt-5-pro-batch` | `gpt-5-pro:batch` | 400,000 | 128,000 |
| `gpt-6-astra` | `gpt-6-astra` | 1,050,000 | 128,000 |
| `gpt-6-astra-batch` | `gpt-6-astra:batch` | 1,050,000 | 128,000 |
| `gpt-6-astra-pro` | `gpt-6-astra-pro` | 1,050,000 | 128,000 |
| `gpt-6-astra-pro-batch` | `gpt-6-astra-pro:batch` | 1,050,000 | 128,000 |
| `gpt-oss-120b-batch` | `gpt-oss-120b:batch` | 131,072 | 117,964 |
| `gpt-oss-20b-batch` | `gpt-oss-20b:batch` | 131,072 | 117,964 |
| `o3-batch` | `o3:batch` | 200,000 | 100,000 |
| `o3-mini-batch` | `o3-mini:batch` | 200,000 | 100,000 |
| `o4-mini-batch` | `o4-mini:batch` | 200,000 | 100,000 |

</details>

## Configuration

Choose a profile to pin the OpenAI model and token limits; most users only need to select a profile and provide an API key. Preconfigured profiles keep model details fixed, while `custom` exposes the model name and context limit for models not listed here.

### Custom models

For `custom`, enter an OpenAI model ID and a positive context limit. The initial context value is 16,384 tokens; set it to the actual model limit so the pipeline can reject oversized prompts before sending them.

## Authentication

Set `apikey` to an OpenAI API key for every profile (including `custom`). The key is
verified with a live one-word test call during pipeline validation, so a bad key or model
name is reported before the pipeline runs rather than at first invoke.

## Notes

### Reasoning streaming

For models whose configuration carries `capabilities.reasoning`, the node builds a raw
`openai` client alongside the LangChain one and streams answers via the Responses API
with `reasoning: {summary: 'auto'}`. Reasoning-summary deltas are forwarded over the
`thinking` SSE lane while the answer streams normally. Non-reasoning models use plain
LangChain streaming with the profile's output limit. `temperature` is configurable on
every profile (range `0`-`2`, default `0`, which is generally more deterministic than
higher values, though OpenAI does not guarantee identical output for identical input);
reasoning models ignore it, because OpenAI's Responses API controls sampling separately.

### Validation and errors

Pipeline validation makes a small live call to verify the API key and model name. Models whose names begin with `gpt-5` are probed with `max_completion_tokens`; older models use `max_tokens`. Rate-limit and connection errors are retryable, while authentication and other API errors fail immediately with a provider-specific message.

### Testing

Automated node tests are declared in `services.json`:

- **Mock group**: runs the `openai-5-2`, `openai-5-4`, `openai-5-4-pro`, `openai-5-4-mini`,
  and `openai-5-4-nano` profiles against a mocked `langchain_openai`; no real API key needed.
  `ROCKETRIDE_MOCK` must point to `nodes/test/mocks`.
- **Real group**: skipped unless `ROCKETRIDE_OPENAI_KEY` is set; calls the live API with
  the `openai-4o-mini` profile.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `model` | `string` | **Model**<br/>OpenAI model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `openai.profile` | `string` | **Model**<br/>LLM model | `"openai-5-2"` |
| `temperature` | `number` | **Temperature**<br/>Sampling temperature for non-reasoning models: 0 is generally more deterministic, higher values increase variety. Ignored for reasoning models (o1, o3, GPT-5 reasoning variants, ...), which OpenAI's Responses API controls separately. | `0` |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_openai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# OpenAI-Compatible API

Route: /nodes/llm_openai_api

# llm_openai_api

A RocketRide LLM node that connects any OpenAI-compatible API endpoint to a pipeline.

## What it does

Connects any OpenAI-compatible API endpoint to your pipeline. Use this node for
providers that implement the OpenAI API spec (Featherless, Together, Groq, Ollama,
LM Studio, and others) but do not have a dedicated RocketRide node. Used primarily as an
`llm` invoke connection by agents and other nodes that need an LLM, but can also be used
directly via lanes.

Built on **langchain-openai** (`ChatOpenAI`) over the official **openai** SDK. The chat
client is created with `temperature: 0` for deterministic output, and `max_tokens` is set
from the shared LLM base's output-token budget (default 4096, minimum 1024). When
`base_url` is empty, the SDK falls back to the default OpenAI endpoint.

When the node configuration is saved, it validates the settings by sending a 1-token `"Hi"`
completion request to the configured endpoint (10-second timeout) and surfaces any provider
error (bad key, unknown model, unreachable URL) as a warning with the provider's status code
and message, truncated to 500 characters.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Generic endpoint default: **Custom OpenAI-compatible endpoint** (`custom`).
Nebius preset default: **Llama 3.3 70B Instruct** (`llama-3-3-70b`).

The directory documents the generic endpoint and the Nebius branded preset in one
combined profile table.

| Profile | Model | Context tokens | Source |
| ------- | ----- | -------------- | ------ |
| Generic `custom` **(default)** | _(user-specified)_ | 32,768 | Any OpenAI-compatible API |
| `llama-3-3-70b` **(default)** | `meta-llama/Llama-3.3-70B-Instruct` | 131,072 | Nebius Token Factory |
| `qwen3-235b` | `Qwen/Qwen3-235B-A22B` | 131,072 | Nebius Token Factory |
| `deepseek-v3` | `deepseek-ai/DeepSeek-V3` | 131,072 | Nebius Token Factory |

## Configuration

Choose `custom` for a generic provider and set its model ID, base URL, context limit,
and API key. Choose one of the named Nebius profiles when using Token Factory; those
profiles pin the model ID, endpoint, and context limit.

### Generic OpenAI-compatible endpoints

Set `base_url` to the provider's OpenAI-compatible API root and `model` to its exact
model identifier. When `base_url` is empty, the OpenAI SDK uses its default endpoint.
Use a positive `modelTotalTokens` value that matches the selected model.

### Nebius preset

`services.nebius.json` registers **Nebius** (`llm_nebius://`) as a branded preset of
this node. It uses the same Python implementation and pins the base URL to
`https://api.tokenfactory.nebius.com/v1/`. The three named Nebius profiles in the
combined table require no model or endpoint edits.

Nebius profiles default the API key to the `${ROCKETRIDE_NEBIUS_KEY}` environment
substitution, so no per-node key entry is needed when that variable is set. The Nebius
service also exposes its own `custom` option for another Token Factory model, retaining
the pinned endpoint, environment-backed key, and 131,072-token context limit. The
combined table represents the duplicate `custom` key once, using the generic service's
merged 32,768-token default.

## Authentication

For `custom`, provide the API key expected by the configured endpoint. Nebius named
profiles use `${ROCKETRIDE_NEBIUS_KEY}` by default; replace it only when the credential
must be supplied directly in the node configuration.

## Notes

### Error handling and retries

Provider errors are mapped to friendly messages and classified for retry:

| Provider exception    | Retried | Surfaced as                                     |
|-----------------------|---------|-------------------------------------------------|
| `AuthenticationError` | no      | `Invalid API key.`                              |
| `APIError`            | no      | `An error occurred with the API.`               |
| `RateLimitError`      | yes     | `Rate limit exceeded. Please try again later.`  |
| `APIConnectionError`  | yes     | `Failed to connect to the API.`                 |

Anything else falls through to the shared LLM base's default retry and mapping logic.

### Testing

`services.json` includes a `test` block that runs the `custom` profile against a local
test server with a mocked `langchain_openai`, so no real API key is required.
`ROCKETRIDE_MOCK` must point to `nodes/test/mocks`.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### OpenAI-Compatible API (`services.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `base_url` | `string` | **Base URL**<br/>API base URL (e.g. https://api.featherless.ai/v1) |  |
| `model` | `string` | **Model**<br/>Model name (e.g. zai-org/GLM-5, meta-llama/Llama-3-70b) |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `openai_api.profile` | `string` | **Model**<br/>Profile selection | `"custom"` |

### Nebius (`services.nebius.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `base_url` | `string` | **Base URL**<br/>OpenAI-compatible base URL. Defaults to Nebius Token Factory. |  |
| `model` | `string` | **Model**<br/>Nebius Token Factory model id (e.g. meta-llama/Llama-3.3-70B-Instruct). Full list: https://tokenfactory.nebius.com/models |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `openai_api.profile` | `string` | **Model**<br/>Nebius Token Factory model | `"llama-3-3-70b"` |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_openai_api)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Perplexity

Route: /nodes/llm_perplexity

# llm_perplexity

A RocketRide LLM node that connects Perplexity AI's Sonar models to a pipeline with built-in real-time web search.

## What it does

Routes questions through Perplexity AI's Sonar family of models, each of which grounds responses in current web content rather than training data alone. The node is registered with `classType: llm` and the `invoke` capability, so agents and other LLM-consuming nodes can use it as a drop-in model connection. It can also be driven directly via the `questions`/`answers` lane pair.

Uses `langchain-openai` (`ChatOpenAI`) against Perplexity's OpenAI-compatible endpoint at `https://api.perplexity.ai`. Temperature is fixed at `0`. The SDK's built-in retries are disabled; the node manages its own retry loop with per-model timeouts and exponential backoff (see "Timeouts and retries" below). Prompt length is checked against the model's token limit before each request, using a word-based estimate (approximately 0.75 words per token).

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Sonar** (`sonar`).

| Profile | Model | Context tokens | Output tokens | Model source |
| ------- | ----- | -------------- | ------------- | ------------ |
| `sonar` **(default)** | `sonar` | 127,072 | 114,364 | manual |
| `sonar-pro` | `sonar-pro` | 200,000 | 8,000 | manual |
| `sonar-reasoning-pro` | `sonar-reasoning-pro` | 128,000 | 115,200 | manual |
| `sonar-reasoning` | `sonar-reasoning` | 128,000 | 4,096 | manual |
| `sonar-deep-research` | `sonar-deep-research` | 128,000 | 115,200 | manual |
| `sonar-pro-search` | `sonar-pro-search` | 200,000 | 8,000 | OpenRouter |

All profiles except `sonar-pro-search` use manually configured model metadata. The `sonar-pro-search` profile pulls token limits from OpenRouter.

## Configuration

Choose a Sonar profile for the search and reasoning depth the pipeline needs. The
profile supplies the model ID, context window, and output budget; only the Perplexity
API key normally needs to be supplied.

## Authentication

Set `apikey` to a valid Perplexity AI API key in the selected profile's config panel. The key is validated at save time by sending a minimal 10-token probe request (`"Hi"`) to `https://api.perplexity.ai`. If the probe fails, a concise warning is surfaced rather than a raw error dump. For HTTP 401 responses that return an HTML page (a known Perplexity behavior), the node extracts the page title or `<h1>` text and formats it into a readable message.

To obtain an API key, visit [https://www.perplexity.ai/settings/api](https://www.perplexity.ai/settings/api).

## Notes

### Timeouts and retries

Request timeout and retry behavior scale with model complexity:

| Model(s)                    | Timeout | Max retries | Base delay |
|-----------------------------|---------|-------------|------------|
| `sonar-deep-research`       | 180 s   | 3           | 2.0 s      |
| `sonar-reasoning*` models   | 120 s   | 2           | 1.5 s      |
| All other models            | 60 s    | 2           | 1.0 s      |

Retries use exponential backoff (`base_delay x 2^attempt`) and only fire on transient failures: timeouts, connection/network errors, and HTTP 500/502/503/504 responses. Authentication errors, quota/billing errors, and input validation errors fail immediately without retrying.

After all retries are exhausted, raw API errors are translated into concise user-facing messages covering: bad API key, rate limiting, quota/billing issues, invalid input, model unavailability, content policy violations, timeouts, and network errors.

## Upstream docs

- [Perplexity AI documentation](https://docs.perplexity.ai/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `model` | `string` | **Model**<br/>Perplexity AI model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `perplexity.profile` | `string` | **Model**<br/>Perplexity AI model | `"sonar"` |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_perplexity)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Qwen

Route: /nodes/llm_qwen

# llm_qwen

A RocketRide LLM node that connects Alibaba Cloud Qwen models to a pipeline via the DashScope API.

## What it does

Provides Qwen chat completions to the pipeline. Used primarily as an `llm` invoke connection by agents and other nodes that need an LLM, and can also be used directly via lanes.

Uses **LangChain's `ChatOpenAI`** client pointed at DashScope's OpenAI-compatible endpoint. The endpoint is resolved at startup from the `base_url` field if set, otherwise from the `region` field. Temperature is fixed at `0`, and `max_tokens` is taken from the profile's `modelOutputTokens`.

When the node configuration is validated, the node performs a live 1-token test request against the API to verify the key, model, and region actually work. Failures surface as configuration warnings with the provider's error message.

## Lanes

| Lane in     | Lane out  | Description                                          |
|-------------|-----------|------------------------------------------------------|
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Qwen Flash (latest)** (`qwen-flash`).

The visible `(latest)` stable aliases always resolve to DashScope's current snapshot for their tier, so they do not go stale as new generations ship — prefer these unless you need to pin a specific release, which the first four collapsed profiles do.

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `qwen-flash` **(default)** | `qwen-flash` | 131,072 | 4,096 |
| `qwen-plus` | `qwen-plus` | 1,000,000 | 32,768 |
| `qwen-max` | `qwen-max` | 32,768 | 8,192 |
| `qwen-turbo` | `qwen-turbo` | 131,072 | 8,192 |

<details>
<summary><strong>View 45 more models</strong></summary>

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `qwen3-7-max` | `qwen3.7-max` | 1,000,000 | 131,072 |
| `qwen3-7-plus` | `qwen3.7-plus` | 1,000,000 | 131,072 |
| `qwen3-6-flash` | `qwen3.6-flash` | 1,000,000 | 65,536 |
| `qwen-plus-2025-07-28` | `qwen-plus-2025-07-28` | 1,000,000 | 32,768 |
| `qwen-2-5-72b-instruct` | `qwen-2.5-72b-instruct` | 32,768 | 16,384 |
| `qwen-2-5-7b-instruct` | `qwen-2.5-7b-instruct` | 32,768 | 29,491 |
| `qwen-2-5-coder-32b-instruct` | `qwen-2.5-coder-32b-instruct` | 32,768 | 29,491 |
| `qwen-plus-2025-07-28-thinking` | `qwen-plus-2025-07-28:thinking` | 1,000,000 | 32,768 |
| `qwen3-14b` | `qwen3-14b` | 131,072 | 16,384 |
| `qwen3-235b-a22b` | `qwen3-235b-a22b` | 131,072 | 8,192 |
| `qwen3-235b-a22b-2507` | `qwen3-235b-a22b-2507` | 262,144 | 16,384 |
| `qwen3-235b-a22b-thinking-2507` | `qwen3-235b-a22b-thinking-2507` | 131,072 | 117,964 |
| `qwen3-30b-a3b` | `qwen3-30b-a3b` | 131,072 | 16,384 |
| `qwen3-30b-a3b-instruct-2507` | `qwen3-30b-a3b-instruct-2507` | 262,144 | 32,000 |
| `qwen3-30b-a3b-thinking-2507` | `qwen3-30b-a3b-thinking-2507` | 81,920 | 32,768 |
| `qwen3-32b` | `qwen3-32b` | 131,072 | 16,384 |
| `qwen3-5-122b-a10b` | `qwen3.5-122b-a10b` | 262,144 | 81,920 |
| `qwen3-5-27b` | `qwen3.5-27b` | 262,144 | 65,536 |
| `qwen3-5-35b-a3b` | `qwen3.5-35b-a3b` | 262,144 | 16,384 |
| `qwen3-5-397b-a17b` | `qwen3.5-397b-a17b` | 262,144 | 65,536 |
| `qwen3-5-9b` | `qwen3.5-9b` | 262,144 | 235,929 |
| `qwen3-5-9b-batch` | `qwen3.5-9b:batch` | 262,144 | 235,929 |
| `qwen3-5-flash-02-23` | `qwen3.5-flash-02-23` | 1,000,000 | 65,536 |
| `qwen3-5-plus-02-15` | `qwen3.5-plus-02-15` | 1,000,000 | 65,536 |
| `qwen3-5-plus-20260420` | `qwen3.5-plus-20260420` | 1,000,000 | 65,536 |
| `qwen3-6-27b` | `qwen3.6-27b` | 262,144 | 65,536 |
| `qwen3-6-35b-a3b` | `qwen3.6-35b-a3b` | 262,144 | 235,929 |
| `qwen3-6-max-preview` | `qwen3.6-max-preview` | 262,144 | 65,536 |
| `qwen3-6-plus` | `qwen3.6-plus` | 1,000,000 | 65,536 |
| `qwen3-7-flash` | `qwen3.7-flash` | 1,000,000 | 65,536 |
| `qwen3-8-2-4t-a95b` | `qwen3.8-2.4t-a95b` | 1,048,576 | 262,144 |
| `qwen3-8-2-4t-a95b-batch` | `qwen3.8-2.4t-a95b:batch` | 1,010,000 | 909,000 |
| `qwen3-8-27b` | `qwen3.8-27b` | 1,000,000 | 131,072 |
| `qwen3-8-flash` | `qwen3.8-flash` | 1,000,000 | 131,072 |
| `qwen3-8-max-0902` | `qwen3.8-max-0902` | 1,000,000 | 131,072 |
| `qwen3-8b` | `qwen3-8b` | 131,072 | 8,192 |
| `qwen3-coder` | `qwen3-coder` | 262,144 | 65,536 |
| `qwen3-coder-30b-a3b-instruct` | `qwen3-coder-30b-a3b-instruct` | 262,144 | 235,929 |
| `qwen3-coder-flash` | `qwen3-coder-flash` | 1,000,000 | 65,536 |
| `qwen3-coder-next` | `qwen3-coder-next` | 262,144 | 235,929 |
| `qwen3-coder-plus` | `qwen3-coder-plus` | 1,000,000 | 65,536 |
| `qwen3-max` | `qwen3-max` | 262,144 | 65,536 |
| `qwen3-max-thinking` | `qwen3-max-thinking` | 262,144 | 65,536 |
| `qwen3-next-80b-a3b-instruct` | `qwen3-next-80b-a3b-instruct` | 262,144 | 235,929 |
| `qwen3-next-80b-a3b-thinking` | `qwen3-next-80b-a3b-thinking` | 262,144 | 235,929 |

</details>

The last four collapsed profiles are **deprecated**: they remain selectable so saved pipelines keep loading, but DashScope rejects their model IDs. They were introduced by OpenRouter fallback discovery in the model sync and carry OpenRouter/HuggingFace IDs rather than DashScope ones (e.g. DashScope uses `qwen2.5-72b-instruct`, not `qwen-2.5-72b-instruct`, and has no `:thinking` model variants — reasoning is controlled with the `enable_thinking` request parameter instead). Migrate to a live profile above.

## Configuration

Choose a profile to set the Qwen model and token limits, then select the DashScope region that issued your API key. Profiles keep the model and token values fixed while exposing the API key, region, and model-source settings.

## Authentication

Provide a DashScope API key in `apikey`. The key must start with `sk-`; anything else is rejected before any request is made. Make sure the key was issued for the region you select.

## Notes

### Regions

`region` selects the DashScope regional endpoint used for all API calls:

| Value  | Region          | Endpoint                                                  |
|--------|-----------------|-----------------------------------------------------------|
| `us`   | US (Virginia)   | `https://dashscope-us.aliyuncs.com/compatible-mode/v1`   |
| `intl` | Singapore       | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
| `cn`   | China (Beijing) | `https://dashscope.aliyuncs.com/compatible-mode/v1`       |

The default is `us`. An unrecognised value falls back to the US endpoint. DashScope API keys are region-specific, so a key issued for one endpoint will fail against another.

Setting `base_url` overrides this table entirely, which is how you reach a DashScope host Alibaba Cloud serves outside the three above — another Alibaba Cloud region, for instance. It is available on every live profile, including `custom`; the deprecated profiles above do not expose it. Leave it empty to use the regional endpoint.

### Error handling

Provider exceptions are mapped to friendly messages instead of raw stack traces:

- Authentication failures surface as "Invalid DashScope API key."
- Rate-limit errors surface as "Rate limit exceeded. Please try again later."
- Connection failures surface as "Failed to connect to the DashScope API."
- Other DashScope API errors surface as "An error occurred with the DashScope API."

Rate-limit and connection errors are classified as retryable by the shared chat base; authentication and generic API errors are not retried.

### Keeping the model list current

Profiles are maintained by the model sync tool, see [tools/sync_models](https://github.com/rocketride-org/rocketride-server/tree/develop/tools/sync_models):

```bash
python tools/sync_models/src/sync_models.py --provider llm_qwen --enable-discovery --apply
```

Discovery — adding profiles — requires `ROCKETRIDE_QWEN_KEY`. Without it the command above still runs, but only enriches profiles that already exist: OpenRouter and LiteLLM can supply token counts, and neither may add a profile unless you also pass `--allow-fallback-discovery`. Avoid that flag here — it lets OpenRouter contribute the HuggingFace-style IDs DashScope does not accept, which is what the deprecated profiles above are. The stable aliases are listed in `protected_profiles` so a non-authoritative source cannot deprecate them.

---

## Upstream docs

- [DashScope API reference](https://help.aliyun.com/zh/dashscope/)
- [Alibaba Cloud Model Studio models](https://www.alibabacloud.com/help/en/model-studio/models)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `model` | `string` | **Model**<br/>Qwen model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |
| `qwen.base_url` | `string` | **Base URL override**<br/>Optional. Overrides the endpoint selected by Region. Leave empty to use the regional endpoint. Set this to reach a DashScope host other than the three listed above, for example another Alibaba Cloud region. | `""` |
| `qwen.profile` | `string` | **Model**<br/>Qwen AI model selection | `"qwen-flash"` |
| `qwen.region` | `string` | **Region**<br/>DashScope regional endpoint. API keys are not interchangeable between regions. | `"us"` |

## Dependencies

- `openai`
- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_qwen)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Gemini Vision

Route: /nodes/llm_vision_gemini

# llm_vision_gemini

A RocketRide filter node that sends images to Google Gemini vision-capable models and emits the model's text analysis.

## What it does

Sends images to Google Gemini vision models and returns text analysis: image description, OCR, visual understanding, and scene description. Accepts either a single streamed image (via the `image` lane) or a stream of image documents such as frames from a frame grabber (via the `documents` lane). Metadata such as frame number and timestamp is preserved on the `documents` output.

Uses the **google-genai** SDK (`>=1.14.0`). Each inference call runs in its own client and worker thread with a **30-second hard timeout**, plus one automatic retry with exponential backoff for transient errors (timeouts, connection failures, 5xx responses). If no analysis prompt is configured, the node defaults to `Describe this image in detail.`

Most profiles support a 1 million token context window, making this node well-suited for high-volume frame analysis pipelines where many images are processed in sequence. The exception is Gemini 3.1 Flash Image Preview, which has a 131,072-token limit.

When both lanes are connected for the same frame, the node calls Gemini once and reuses the cached answer for the second lane, so you are not billed twice per image.

## Lanes

| Lane in     | Lane out    | Description                                                                      |
| ----------- | ----------- | -------------------------------------------------------------------------------- |
| `image`     | `text`      | Analyze a single streamed image, receive the model's text response               |
| `documents` | `documents` | Analyze image documents, return text analysis with original metadata preserved   |

## Profiles

Default: **Gemini 2.5 Flash - Fast Vision (1M tokens)** (`gemini-2_5-flash`).

| Profile | Model | Context tokens |
| ------- | ----- | -------------- |
| `gemini-2_5-flash` **(default)** | `models/gemini-2.5-flash` | 1,048,576 |
| `gemini-2_5-pro` | `models/gemini-2.5-pro` | 1,048,576 |
| `gemini-2_5-flash-lite` | `models/gemini-2.5-flash-lite` | 1,048,576 |
| `gemini-3_1-pro-preview` | `models/gemini-3.1-pro-preview` | 1,048,576 |
| `gemini-3_1-flash-image-preview` | `models/gemini-3.1-flash-image-preview` | 131,072 |

### Choosing a profile

- **Flash Lite**: fastest and cheapest; good for high-throughput frame pipelines where speed matters more than detail
- **Flash**: balanced speed and quality; the recommended default for most vision tasks
- **Pro**: highest quality analysis; use when accuracy is critical and latency is acceptable
- **3.1 Pro Preview / Flash Image Preview**: latest generation previews; expect higher capability but potential instability as models are still in preview

## Configuration

Choose a vision profile, then provide the API key and prompts for the analysis task.
The profile supplies the model identifier and context limit.

On the `documents` lane, each incoming `Image` document is replaced by a `Text`
document containing the model's answer, carrying the original metadata. The document
content is treated as base64-encoded PNG data. The original `Image` documents do not
flow downstream. Documents with a type other than `Image`, or with empty content, are
skipped with a warning. On the `image` lane, empty frames are also skipped with a
warning.

If inference fails for a document, the node logs a warning and continues with the next
one: a single bad frame does not stop the pipeline.

### System Instructions and Analysis Prompt

Use **System Instructions** to define the model's role; the node sends that value as
Gemini's `system_instruction` on every request. Use **Analysis Prompt** for the task to
perform on each image. When the analysis prompt is empty, the node uses
`Describe this image in detail.`

## Authentication

Get a key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey). Keys are free for development use and grant access to all Gemini models listed above.

The node validates the key format at startup: keys beginning with `sk-` are rejected immediately with a clear message indicating that the key appears to be an OpenAI key. When the configuration is saved, the node also runs a minimal API probe against the selected model and surfaces any provider error (invalid key, missing model, quota exceeded, etc.) as a warning. The probe is skipped while the key is still blank.

## Notes

### Error handling

API errors are mapped to user-friendly messages: authentication failures, rate limits, billing and quota issues, safety-filter blocks, model unavailability, timeouts, and 5xx service errors each produce a clear explanation instead of a raw stack trace.

Retry behavior: one retry for transient errors (timeout, connection, `500`/`502`/`503`/`504`, service unavailable) with exponential backoff starting at 1 second. Repeated timeouts are not retried beyond the second attempt, so a hung request costs at most two 30-second waits before the error is surfaced.

## Upstream docs

- [Gemini API documentation](https://ai.google.dev/gemini-api/docs)
- [Gemini model overview](https://ai.google.dev/gemini-api/docs/models)
- [Google AI Studio](https://aistudio.google.com/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `image_vision_gemini.apikey` | `string` | **API Key**<br/>Google AI API key. Get one at https://aistudio.google.com/apikey |  |
| `image_vision_gemini.profile` | `string` | **Vision Model**<br/>Select the Gemini vision model to use | `"gemini-2_5-flash"` |
| `model` | `string` | **Model**<br/>Gemini Vision model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |
| `vision.prompt` | `string` | **Analysis Prompt**<br/>Describe what you want to analyze or extract from the image |  |
| `vision.systemPrompt` | `string` | **System Instructions**<br/>Define the model's role and behavior for image analysis |  |

## Dependencies

- `google-genai` `>=1.14.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_vision_gemini)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Mistral Vision

Route: /nodes/llm_vision_mistral

# llm_vision_mistral

A RocketRide node that sends images to Mistral AI's vision-capable models and returns text analysis.

## What it does

Accepts either a single image (via the `image` lane) or a stream of image documents (via the `documents` lane, e.g. from a frame grabber), calls the configured Mistral vision model, and returns the model's response as text or as text documents.

Uses the official **mistralai** Python SDK with a custom `httpx` client (120 s timeout, redirects followed) to handle large image payloads. Token counting uses the **mistral-common** tokenizer, with per-model tokenizers loaded strictly; the v3 tokenizer is used as a fallback when no model-specific tokenizer is available.

All requests are sent with **temperature 0.0** for deterministic output. Transient failures (timeouts, connection errors, 5xx responses) are retried up to 3 times with exponential backoff. The base delay scales with model size: 2.0 s for `large` models, 1.5 s for `medium`, 1.0 s for all others. API errors are translated into user-friendly messages covering authentication failures, rate limits, quota exhaustion, content-policy violations, and image-processing errors.

## Lanes

| Lane in     | Lane out    | Description                                                                    |
| ----------- | ----------- | ------------------------------------------------------------------------------ |
| `image`     | `text`      | Analyze a single image, receive text                                           |
| `documents` | `documents` | Analyze image documents, return text analysis with original metadata preserved |

## Profiles

Default: **Mistral Large 3 - Premier Vision (256k tokens)** (`mistral-large-3`).

| Profile | Model | Context tokens |
| ------- | ----- | -------------- |
| `mistral-large-3` **(default)** | `mistral-large-2512` | 256,000 |
| `mistral-medium-3.1` | `mistral-medium-2508` | 128,000 |
| `mistral-small-3.2` | `mistral-small-2506` | 128,000 |
| `ministral-14b-3` | `ministral-14b-2512` | 256,000 |
| `ministral-8b-3` | `ministral-8b-2512` | 256,000 |
| `ministral-3b-3` | `ministral-3b-2512` | 256,000 |

## Configuration

Choose a profile for the quality, latency, and context window the task needs, then set
the API key and prompts. The profile supplies the model identifier and token limit.

On the `image` lane, incoming image bytes are buffered across chunks, base64-encoded
with the source MIME type, and sent to the model with the analysis prompt. The answer
is written downstream as text.

On the `documents` lane, only documents of type `Image` are processed. Other document
types and images with empty content are skipped with a warning. The document's
`page_content` is expected to be base64-encoded PNG. Each answer is emitted as a
`Text` document that preserves the original metadata (`chunkId`, `time_stamp`, and
other fields). A failed chunk is logged and skipped without stopping the batch.
Documents the node does not convert — the original `Image` documents, skipped
types, and failed chunks — do not flow downstream.

### System Instructions and Analysis Prompt

Use **System Instructions** to define the model's role and behavior. Use **Analysis
Prompt** to describe what to extract or explain from every image.

## Authentication

Provide a Mistral AI API key in the `apikey` field for the selected profile. The node validates the key format at startup: if you supply an OpenAI key (starting with `sk-`) or a Google AI/Gemini key (starting with `AI`), initialization fails immediately with a specific error message pointing to the wrong provider.

## Notes

### Image input

The node accepts images in the following formats:

- **HTTP(S) URL**: passed to the Mistral API as-is.
- **Data URI** (`data:image/...` or `data:application/...`): passed as-is.
- **Local file path**: read from disk, base64-encoded, and sent as a data URI. Files over **10 MB** are rejected. MIME type is inferred from the file extension (`.jpg`/`.jpeg` -> `image/jpeg`, `.png` -> `image/png`, `.gif` -> `image/gif`, `.webp` -> `image/webp`; any unrecognized extension defaults to `image/jpeg`).

## Upstream docs

- [Mistral vision documentation](https://docs.mistral.ai/capabilities/vision/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `image_vision_mistral.profile` | `string` | **Vision Model**<br/>Select the Mistral vision model to use | `"mistral-large-3"` |
| `model` | `string` | **Model**<br/>Mistral Vision model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |
| `vision.prompt` | `string` | **Analysis Prompt**<br/>Describe what you want to analyze or extract from the image |  |
| `vision.systemPrompt` | `string` | **System Instructions**<br/>Define the model's role and behavior for image analysis |  |

## Dependencies

- `mistralai`
- `mistral-common[sentencepiece]`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_vision_mistral)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Ollama Vision

Route: /nodes/llm_vision_ollama

# llm_vision_ollama

A RocketRide image node that sends images to locally-hosted Ollama vision models and returns text analysis.

## What it does

Connects to open-source multimodal models (Llama 3.2 Vision, LLaVA, Moondream, MiniCPM-V, Qwen 2.5 VL, or any custom model) served by a local Ollama instance. No API key is required: models run entirely on your own hardware, making the node suitable for privacy-sensitive workloads. It accepts either a single image or a stream of image documents (e.g. from a frame grabber); metadata such as frame number and timestamp is preserved on the `documents` output.

Uses **langchain-openai** (`ChatOpenAI`) against Ollama's OpenAI-compatible `/v1` endpoint. The configured server base URL is normalized to end with `/v1` automatically, and a placeholder API key (`"ollama"`) is sent because Ollama ignores it. Requests run with `temperature: 0`.

Each inference attempt is capped by a 30-second hard timeout; a timed-out or retryable failure is retried once with exponential backoff (a fresh HTTP client is created per attempt so a hung request cannot exhaust the connection pool). API errors are translated into actionable user-facing messages (see Troubleshooting).

## Lanes

| Lane in     | Lane out    | Description                                                                    |
| ----------- | ----------- | ------------------------------------------------------------------------------ |
| `image`     | `text`      | Analyze a single image, receive text                                           |
| `documents` | `documents` | Analyze image documents, return text analysis with original metadata preserved |

## Profiles

Default: **Llama 3.2 Vision 11B** (`llama3_2-vision-11b`).

| Profile | Model | Context tokens |
| ------- | ----- | -------------- |
| `custom` | _(user-specified)_ | 16,385 |
| `llama3_2-vision-11b` **(default)** | `llama3.2-vision:11b` | 128,000 |
| `llama3_2-vision-90b` | `llama3.2-vision:90b` | 128,000 |
| `llava-7b` | `llava:7b` | 32,768 |
| `llava-13b` | `llava:13b` | 4,096 |
| `llava-34b` | `llava:34b` | 4,096 |
| `moondream` | `moondream` | 2,048 |
| `minicpm-v` | `minicpm-v` | 8,192 |
| `qwen2_5vl-3b` | `qwen2.5vl:3b` | 128,000 |
| `qwen2_5vl-7b` | `qwen2.5vl:7b` | 128,000 |

## Configuration

Choose a bundled profile for a known Ollama model or `custom` for another multimodal
model. All profiles expose the server URL and prompts; `custom` also exposes the model
name and context limit. The default server is `http://localhost:11434/v1`.

### Image to text

Raw image bytes arrive in chunks over the AVI protocol, are accumulated, encoded as a
base64 data URL with the incoming MIME type, and sent to the model with the configured
analysis prompt. The model's answer is written to the `text` lane.

### Documents to documents

Each incoming `Doc` of type `Image` is analyzed individually. Its `page_content` is
expected to be base64-encoded PNG. The answer is emitted as a `Text` document that
preserves the original metadata (`chunkId`, `time_stamp`, and other fields). Non-image
documents and images with empty content are skipped with a warning; a per-document
failure is logged and skipped instead of failing the batch. The original image
documents do not flow downstream.

### System Instructions and Analysis Prompt

Use **System Instructions** to define the model's role and **Analysis Prompt** for the
image task. If the analysis prompt is empty, the node uses question text from the
request; if that is also empty, it uses `Describe this image.`

The selected model must already be pulled into Ollama (`ollama pull <model>`).

## Notes

### Troubleshooting

The node maps common API failures to clear messages:

| Symptom                               | Meaning / fix                                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| "Cannot connect to Ollama server"     | Ollama is not running, or `serverbase` points to the wrong host/port                              |
| "Model '...' is not loaded in Ollama" | Pull the model first: `ollama pull <model>`                                                       |
| "Too many requests to Ollama"         | Rate limited: wait a moment and retry                                                             |
| "Ollama returned a server error"      | Check the Ollama server logs                                                                      |
| "Vision request timed out"            | Inference exceeded the 30 s hard timeout; large models may need a warm-up run or a smaller model |
| "Image processing error"              | Use a supported image format: JPEG, PNG, GIF, WEBP                                                |

## Upstream docs

- [Ollama model library](https://ollama.com/library)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `image_vision_ollama.profile` | `string` | **Vision Model**<br/>Select the Ollama vision model to use | `"llama3_2-vision-11b"` |
| `model` | `string` | **Model**<br/>Ollama vision model name |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `vision.prompt` | `string` | **Analysis Prompt**<br/>Describe what you want to analyze or extract from the image |  |
| `vision.systemPrompt` | `string` | **System Instructions**<br/>Define the model's role and behavior for image analysis |  |

## Dependencies

- `langchain-openai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_vision_ollama)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# OpenAI Vision

Route: /nodes/llm_vision_openai

# llm_vision_openai

A RocketRide filter node that sends images to OpenAI's vision-capable models and returns the text analysis.

## What it does

Accepts single image frames or streams of image documents and calls OpenAI's Chat Completions API with each image encoded as a base64 data URL (with `detail: "auto"`), returning the model's text response. Supports the GPT-4.1 and GPT-4o model families for use cases including image analysis, OCR, visual understanding, and scene description.

Uses the official **`openai` Python SDK** (`>=2.38.0`). If no analysis prompt is configured, the node defaults to `"Describe this image in detail."`.

Each API call runs in a daemon thread with a **30-second hard timeout** and is retried **once** on retryable errors (rate limits, connection errors, timeouts, 5xx responses). Rate-limit retries honor the `retry-after` response header (default 60 s); other retries use exponential backoff starting at 1 s. A fresh HTTP client is created per attempt to avoid exhausting the connection pool from a prior timed-out attempt. API errors are translated to user-friendly messages covering authentication failure, rate limits, quota or billing issues, invalid input, model not found, timeout, and server unavailability.

When both lanes carry the same frame, the node makes only **one** API call per frame: the first lane to process the frame caches the answer, and the second lane reuses it. The cache is cleared at the start of each new frame.

## Lanes

| Lane in     | Lane out    | Description                                                                      |
| ----------- | ----------- | -------------------------------------------------------------------------------- |
| `image`     | `text`      | Analyze a single image frame and emit the model's text response                  |
| `documents` | `documents` | Analyze image documents and emit text analysis with original metadata preserved  |

## Profiles

Default: **GPT-4.1** (`openai-4-1`).

| Profile | Model | Context tokens |
| ------- | ----- | -------------- |
| `openai-4-1` **(default)** | `gpt-4.1` | 1,047,576 |
| `openai-4-1-mini` | `gpt-4.1-mini` | 1,047,576 |
| `openai-4-1-nano` | `gpt-4.1-nano` | 1,047,576 |
| `openai-4o` | `gpt-4o` | 128,000 |
| `openai-4o-mini` | `gpt-4o-mini` | 128,000 |

## Configuration

Choose a profile, then provide the API key and prompts for the analysis task. The
profile supplies the model identifier and context limit.

On the `documents` lane, each incoming `Image` document is replaced by a `Text`
document containing the model's answer, with the original frame, timestamp, and chunk
metadata carried over. Other document types and images with empty content are skipped
with a warning. Image document content is expected to be base64-encoded PNG, and the
original image documents do not flow downstream.

If inference fails for a document after retries, the node logs a warning and continues
with the next document. On the `image` lane, a failure logs a warning and emits nothing
for that frame. Empty image frames are also skipped with a warning.

### System Instructions and Analysis Prompt

Use **System Instructions** to define the model's role and **Analysis Prompt** to
describe the task for each image. When no analysis prompt is configured, the node uses
`Describe this image in detail.`

## Authentication

Provide an OpenAI API key in `image_vision_openai.apikey`. The key is validated at pipeline start: it must be present and must begin with `sk-`, otherwise the node raises a configuration error before any image is processed.

## Upstream docs

- [OpenAI Vision documentation](https://platform.openai.com/docs/guides/vision)
- [OpenAI API keys](https://platform.openai.com/api-keys)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `image_vision_openai.apikey` | `string` | **API Key**<br/>OpenAI API key. Get one at https://platform.openai.com/api-keys |  |
| `image_vision_openai.profile` | `string` | **Vision Model**<br/>Select the OpenAI vision model to use | `"openai-4-1"` |
| `model` | `string` | **Model**<br/>OpenAI Vision model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Maximum context length in tokens |  |
| `vision.prompt` | `string` | **Analysis Prompt**<br/>Describe what you want to analyze or extract from the image |  |
| `vision.systemPrompt` | `string` | **System Instructions**<br/>Define the model's role and behavior for image analysis |  |

## Dependencies

- `openai` `>=2.38.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_vision_openai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# xAI

Route: /nodes/llm_xai

# llm_xai

A RocketRide LLM node that connects xAI Grok models to a pipeline.

## What it does

Provides xAI's Grok models as an `llm` invoke connection for agents and other nodes that need a language model. The node can also be used directly via lanes: send text on the `questions` lane and receive a generated completion on the `answers` lane.

Uses **langchain-xai** (`ChatXAI`) under the hood. The chat client is always initialized with `temperature=0`, and `max_tokens` is set from the selected profile's output-token limit.

When the node config is saved, a minimal validation probe (a single-word prompt) is sent to the xAI API to verify the API key and model. Provider and HTTP errors are parsed into a readable `Error <code>: <message>` warning instead of failing silently.

## Lanes

| Lane in     | Lane out  | Description                                          |
| ----------- | --------- | ---------------------------------------------------- |
| `questions` | `answers` | Send a question directly, receive a generated answer |

## Profiles

Default: **Grok 3** (`grok-3`).

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `grok-3` **(default)** | `grok-3` | 131,072 | 131,072 |
| `grok-4-5` | `grok-4.5` | 500,000 | 450,000 |
| `grok-4-20` | `grok-4.20` | 2,000,000 | 1,800,000 |
| `grok-4-20-multi-agent` | `grok-4.20-multi-agent` | 2,000,000 | 1,800,000 |

<details>
<summary><strong>View 17 more models</strong></summary>

| Profile | Model | Context | Output |
| ------- | ----- | ------- | ------ |
| `custom` | _(user-specified)_ | 131,072 | editable |
| `grok-4-1-fast-reasoning` | `grok-4-1-fast-reasoning` | 2,000,000 | 4,096 |
| `grok-4-1-fast-non-reasoning` | `grok-4-1-fast-non-reasoning` | 2,000,000 | 4,096 |
| `grok-code-fast-1` | `grok-code-fast-1` | 256,000 | 10,000 |
| `grok-4-fast-reasoning` | `grok-4-fast-reasoning` | 2,000,000 | 4,096 |
| `grok-4-fast-non-reasoning` | `grok-4-fast-non-reasoning` | 2,000,000 | 4,096 |
| `grok-4` | `grok-4-0709` | 256,000 | 256,000 |
| `grok-3-mini` | `grok-3-mini` | 131,072 | 131,072 |
| `grok-3-beta` **(deprecated)** | `grok-3-beta` | 131,072 | 131,072 |
| `grok-3-mini-beta` **(deprecated)** | `grok-3-mini-beta` | 131,072 | 131,072 |
| `grok-4-1-fast` **(deprecated)** | `grok-4.1-fast` | 2,000,000 | 30,000 |
| `grok-4-fast` **(deprecated)** | `grok-4-fast` | 2,000,000 | 30,000 |
| `grok-4-3` | `grok-4.3` | 1,000,000 | 900,000 |
| `grok-build-0-1` | `grok-build-0.1` | 256,000 | 230,400 |
| `grok-latest` | `grok-latest` | 500,000 | 450,000 |
| `grok-4-3-batch` | `grok-4.3:batch` | 1,000,000 | 900,000 |
| `grok-4-6` | `grok-4.6` | 500,000 | 450,000 |

</details>

The `grok-3-beta`, `grok-3-mini-beta`, `grok-4-fast`, `grok-4-1-fast`,
`grok-4-20`, and `grok-4-20-multi-agent` profiles use OpenRouter-style model
IDs and expose the API key field for that source.

## Configuration

Choose a profile to set the model, context limit, and output limit. Built-in profiles keep those values fixed, while `custom` exposes the model ID and context limit for another xAI model.

### Custom models

For `custom`, enter an xAI model ID and a positive context limit. The initial context value is 131,072 tokens; the output limit is not preset.

## Authentication

For xAI-hosted profiles, provide an xAI API key in the `apikey` field. The key is validated at pipeline start: it must begin with the `xai-` prefix, otherwise the node raises `Invalid XAI API key format, please check your API key.` OpenRouter-sourced profiles use the key field exposed for that source instead.

The key is also checked at save time with a minimal probe request, so invalid keys, unknown models, or network problems surface as warnings in the UI before the pipeline runs.

---

## Upstream docs

- [xAI API documentation](https://docs.x.ai/docs/overview)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `model` | `string` | **Model**<br/>xAI model |  |
| `modelTotalTokens` | `number` | **Tokens**<br/>Total Tokens |  |
| `xai.profile` | `string` | **Model**<br/>LLM model | `"grok-3"` |

## Dependencies

- `langchain-xai`
- `langchain-core`
- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/llm_xai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Local Text Output

Route: /nodes/local_text_output

# local_text_output

A RocketRide target node that writes pipeline text to files on the machine running the pipeline; choose it when local filesystem output is required instead of an SMB export.

## What it does

The node accumulates text for each object and, when the object closes, writes it as a `.txt` file below the configured output directory. It consumes the `text` lane and produces no output lane. Choose `text_output` instead when the destination is an SMB network share rather than the pipeline host’s filesystem.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | — | Text content to write to the configured local output directory. |

## Configuration

Set the output directory, then decide whether a prefix should be removed from each source path before it becomes the destination-relative path. Most users can leave **exclude** at its default of `N/A`.

### Destination path

The node reads `storePath` as the output directory. It resolves this directory and each candidate target path before writing, then rejects a candidate that would resolve outside the output directory. Use an explicit directory the pipeline process is allowed to create and write to; an empty output path causes a warning and the object is skipped.

On Windows, configuration validation rejects `storePath` values containing `< > : " / | ? *`. The node also shortens over-long path components before the write and uses extended-length local paths on Windows.

### Exclude

The default `N/A` preserves the complete source path below the output directory. Set a prefix only when that leading source-path portion should not appear in the output hierarchy. If an object path does not begin with the configured prefix, the node logs a warning and skips that object rather than guessing a relative path.

When a prefix is accepted, the node removes it, replaces the source extension with `.txt`, and creates the necessary directory hierarchy. On Windows, the same invalid-character validation applies to a non-`N/A` exclude value.

## Limitations

This node is unavailable in SaaS deployments and writes directly to the pipeline host’s filesystem. Its filesystem and security capabilities mean the configured output location must be intentionally writable by that process; path traversal outside the resolved output directory is rejected.

## Notes

### Write behavior

Objects already marked failed upstream are not written. The node writes only non-empty accumulated text in UTF-8. Directory-creation and write failures are logged as warnings and leave the pipeline running; the per-object state is then reset.

## Upstream docs

- [Python `os` module](https://docs.python.org/3/library/os.html)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `local_text_output.exclude` | `string` | **exclude**<br/>Which paths to exclude from the output path, if not required put N/A. e.g Users/Downloads/ or N/A | `"N/A"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/local_text_output)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Memory (Internal)

Route: /nodes/memory_internal

# memory_internal

A RocketRide in-process memory node for temporary, keyed values within a
pipeline instance. Pick it for short-lived agent scratch space; use
`memory_persistent` when state must be retained across sessions.

## About RocketRide

RocketRide hosts this node as a Python pipeline component. The node itself
implements a small in-process store and has no separately configured service
or dependency.

## What it does

Creates a new keyed store for each node instance, then clears that store when
the instance is opened. It has no data lanes: its registered operations store,
retrieve, list, and clear values for code or an agent using the node. Choose it
over `memory_persistent` when the desired lifetime is only the current
instance and an external backend is unnecessary.

## Configuration

This node has no configuration fields, profiles, or lanes. Add it when its
run-scoped lifetime is appropriate; stored values are not copied or persisted
by the node, so do not use it for data that must survive a new instance.

## Notes

### Registered operations

The node registers four operations under the `memory` prefix:

| Function | Description |
| --- | --- |
| `memory.put` | Store a value under a key. |
| `memory.get` | Retrieve the value for a key. |
| `memory.list` | Return all stored keys in sorted order. |
| `memory.clear` | Remove one key or all keys. |

`memory.put` requires a non-empty string `key` and a `value`; it trims the key
before storing and returns `{ok: true, key}`. `memory.get` requires a non-empty
string `key`; a missing key returns `{ok: false, key, value: null}`. The
no-argument `memory.list` returns `{ok: true, keys}`. `memory.clear` accepts
an optional string `key`; omitting it, or supplying an empty or whitespace-only
key, clears every stored key and returns them in `cleared`.

Calls whose argument object is not a dictionary, or whose required key/value
is invalid or missing, raise a `ValueError` before reaching the store. Clearing
a specified key that does not exist is successful and returns an empty
`cleared` list.

### Lifetime

`beginInstance` creates the store and `open` clears it. In particular, opening
the node starts with an empty store even if the same instance was previously
used. The implementation uses a Python dictionary only; it does not provide
cross-instance or cross-process persistence.

## Upstream docs

- [RocketRide documentation](https://docs.rocketride.org)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/memory_internal)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Persistent Memory

Route: /nodes/memory_persistent

# memory_persistent

A RocketRide filter node that carries session memory across pipeline work by
`session_id`. Pick it when downstream nodes need prior session state; use
`memory_internal` for temporary, instance-scoped agent scratch space.

## About Redis

Redis is an optional backend this node uses for session values, metadata, and
operation history. Select it when memory must outlive the Python process; the
alternative backend keeps the same data in process for testing and development.

## What it does

On the `questions` lane, the node resumes or creates the session named in
question metadata and attaches its stored values as `memory_context` before
forwarding the question. On the `answers` lane, it writes the answer text to
`last_answer`, increments `answer_count`, and forwards the answer unchanged.
Choose it over `memory_internal` when this lane-based session context, a Redis
backend, or configurable expiry is needed.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `questions` | `questions` | Attach non-empty session context from memory, then forward the question. |
| `answers` | `answers` | Store the answer for its session, then forward it. |

## Profiles

Default: `memory`, the in-process store.

| Profile | Backend | Session lifetime |
| --- | --- | --- |
| `memory` *(default)* | In-memory | No expiry. |
| `redis` | Redis at `localhost:6379` | 24 hours. |
| `custom` | Redis at a supplied connection | 24 hours. |

Start with `memory` for a local test, then select `redis` when a process-local
store is not sufficient, or `custom` to point at a Redis instance other than
the default `localhost:6379`.

## Configuration

Choose a backend first. The in-memory default is appropriate for testing; a
Redis deployment needs its connection values and a retention policy. The
generated schema below is the complete field reference.

### Backend

`backend` accepts `memory` or `redis` and defaults to `memory`. The memory
backend is thread-safe and limits itself to 1,000 active sessions; it is useful
for testing and development but its contents live only in the engine process.
Switch to `redis` for a shared or process-surviving store. Any other backend
value stops initialization with a `ValueError`.

### Redis connection

`redis_host`, `redis_port`, and `redis_password` are used only with the Redis
backend. The Redis profile uses `localhost` and port `6379`; change the host
and port to reach a deployed server. A non-empty password is passed to the
Redis client, while an empty password becomes no password. Keep the memory
backend selected when no reachable Redis service is available.

### Session TTL (hours)

`session_ttl_hours` controls the TTL assigned when a new session is created.
The default `0` means no expiry; a value greater than zero expires all data,
keys, history, and metadata for that session together. Set a positive value
when stale context should be discarded automatically. With the in-memory
backend, expiry is removed lazily when the session is accessed or sessions are
listed; Redis aligns the backend keys with the session metadata TTL.

### History retention

Each stored value, counter increment, and clear operation records an operation
entry rather than the value itself. `max_history` defaults to `100`. When
`auto_summarize` is on (the default), the node checks after successful writes
and increments; if history exceeds that limit, it keeps the newest half and
replaces the older entries with one summary containing operation counts and
touched keys. Raise the limit to keep more recent operation detail; lower it
to bound history earlier. A clear is recorded but does not itself trigger the
summarization check.

## Authentication

For the Redis backend, provide `redis_password` only when the target Redis
server requires a password. The node passes that non-empty value directly to
the Redis client; the source does not configure any additional authentication
mechanism.

## Notes

### Session handling

A question or answer without a truthy metadata `session_id` passes through
without session storage, except that an answer can reuse the session ID seen on
the current question. Missing sessions are created on first use. Session IDs
must be 1–128 ASCII alphanumeric characters, hyphens, or underscores; keys
must be 1–256 characters from that set plus dots. Invalid session IDs are
logged and the affected question or answer is forwarded unchanged.

When a session has values, `questions` attaches every stored key and value as
`metadata['memory_context']`; an empty session adds no context. Answers use
`getText()` when available, otherwise their string representation, before
storing it as `last_answer`. Counter updates are lock-protected in memory and
use Redis `INCRBY` with the Redis backend.

### Backend behavior

Both backends return deep copies for stored values and history entries. Redis
serializes stored values as JSON under the `rr:memory` key prefix, while the
in-memory backend has no external dependency. The global store is initialized
once for a pipe and its backend is closed when the pipe ends.

## Upstream docs

- [Redis documentation](https://redis.io/docs/latest/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `auto_summarize` | `boolean` | **Auto-Summarize**<br/>Automatically summarize older history entries when limit is reached | `true` |
| `backend` | `string` | **Backend**<br/>Storage backend: redis (production) or memory (testing) | `"memory"` |
| `max_history` | `number` | **Max History Entries**<br/>Maximum history entries per session before auto-summarization | `100` |
| `redis_host` | `string` | **Redis Host**<br/>Redis server hostname | `"localhost"` |
| `redis_password` | `string` | **Redis Password**<br/>Redis server password (leave empty for no auth) |  |
| `redis_port` | `number` | **Redis Port**<br/>Redis server port | `6379` |
| `session_ttl_hours` | `number` | **Session TTL (hours)**<br/>How long sessions persist before auto-expiry (0 = no expiry) | `0` |

## Dependencies

- `redis`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/memory_persistent)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Named Entity Recognition

Route: /nodes/ner

# ner

A RocketRide text-processing node that identifies named entities with a configured Hugging Face model. Choose it when documents need entity metadata for downstream filtering or analysis, rather than LLM-generated structured records.

## About Hugging Face

Hugging Face provides tools and models for machine-learning workflows. This node uses its model identifiers with RocketRide's Transformers pipeline to perform named-entity recognition.

## What it does

The node runs named-entity recognition on incoming text and documents, filtering the model's results by the configured confidence threshold. Text continues unchanged on the `text` lane. Documents are copied and, by default, enriched with entity lists and a total count in their metadata. Use it instead of `dictionary` when you need model-recognized entity spans and categories, not LLM-authored definitions of internal terminology.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `text` | Runs recognition and passes the original text through unchanged. |
| `documents` | `documents` | Runs recognition on each document and writes an enriched copy downstream. |

## Profiles

Default: **BERT Large (English) - High accuracy for English text** (`bertLarge`).

| Profile | Model | Context |
| --- | --- | --- |
| `bertLarge` **(default)** | `dbmdz/bert-large-cased-finetuned-conll03-english` | English profile; `min_confidence` defaults to `0.9`. |
| `bertBase` | `dslim/bert-base-NER` | English profile; `min_confidence` defaults to `0.9`. |
| `distilbert` | `Davlan/distilbert-base-multilingual-cased-ner-hrl` | Multilingual profile; `min_confidence` defaults to `0.9`. |
| `xlmRoberta` | `Davlan/xlm-roberta-base-ner-hrl` | Multilingual profile; `min_confidence` defaults to `0.9`. |
| `deberta` | `dslim/distilbert-NER` | English profile; `min_confidence` defaults to `0.9`. |
| `biomedical` | `dmis-lab/biobert-base-cased-v1.1` | Biomedical profile; `min_confidence` defaults to `0.85`. |
| `custom` | _(your own token-classification model)_ | `min_confidence` defaults to `0.9`. |

## Configuration

Start with the profile that matches the language or domain of the input, then adjust confidence and output handling only when the default behavior does not fit the pipeline. Select `custom` when a compatible model identifier is required; the other profiles preconfigure their model value.

### Model

The profile selector defaults to `bertLarge`. Its preset supplies the model identifier, aggregation strategy, and confidence threshold. Use a named profile when it matches the input domain, or select `custom` to enter a model name yourself; the recognizer otherwise falls back to `dbmdz/bert-large-cased-finetuned-conll03-english` when no model value reaches it. A custom model must work with the NER pipeline and the selected aggregation strategy.

### Entity aggregation strategy

This controls how the underlying pipeline combines word pieces into entities. The default is `simple`; the available strategies are `none`, `simple`, `first`, `average`, and `max`. Change it when your model's subword output produces entity boundaries or scores that are not useful to downstream consumers. Because confidence filtering happens after recognition, a different aggregation strategy can also change which combined entities meet the threshold.

### Minimum confidence threshold

The threshold is a number from `0.0` to `1.0` and defaults to `0.9` for most presets (`0.85` for `biomedical`). Raise it when metadata should contain only more confident entities; lower it when the model is missing useful candidates and the pipeline can tolerate more noise. The recognizer discards results below this value before it formats the entity dictionaries or stores them in document metadata.

### Store entities in document metadata

This is on by default and affects the `documents` lane. When enabled, the node copies each document and stores deduplicated, sorted entity words under `entities_<type>` keys plus `entities_count`. Turn it off when the lane should preserve document metadata unchanged; recognition still runs, but the extracted entity list is not written to that document's metadata.

These values are written onto the document's `DocMetadata` as attributes, so in-process consumers read them as `doc.metadata.entities_per` rather than by subscript. They are extra fields on the model, so they still appear in the serialized metadata returned by `toDict()`.

A document that arrives without metadata is given a `DocMetadata` built from the object being processed, inheriting its `objectId`, `nodeId`, `parent`, `permissionId`, and `signature` rather than a placeholder identity.

## Requirements

This node declares GPU capability. It initializes its recognizer once at pipeline start and uses RocketRide's Transformers pipeline, which uses the model server when it is available and otherwise falls back to local execution. The model is not loaded while the node is opened in configuration mode.

## Notes

### Result handling

Each recognized item is formatted with `entity_group`, `word`, `score`, `start`, and `end`. Empty or whitespace-only text yields no entities. If recognition raises an exception, the node reports the error and returns an empty list, while text and documents continue through their normal lane handling.

### Text and document behavior

On the `text` lane, the node collects recognized entities in instance state but writes only the original text downstream. On the `documents` lane, it processes each document's `page_content` separately and uses `model_copy(deep=True)` before changing metadata, so neither the original document nor the metadata it carries is mutated.

## Upstream docs

- [Hugging Face Transformers documentation](https://huggingface.co/docs/transformers/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `ner.aggregation_strategy` | `string` | **Entity aggregation strategy**<br/>How to combine word pieces into entities | `"simple"` |
| `ner.min_confidence` | `number` | **Minimum confidence threshold**<br/>Minimum confidence score (0.0-1.0) for entity detection | `0.9` |
| `ner.model` | `string` | **Model name**<br/>HuggingFace model to use for NER |  |
| `ner.profile` | `string` | **Model**<br/>NER model configuration | `"bertLarge"` |
| `ner.store_in_metadata` | `boolean` | **Store entities in document metadata**<br/>Add extracted entities to document metadata fields | `true` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/ner)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Normalize Facts

Route: /nodes/normalize_facts

# normalize_facts

A RocketRide filter node that deterministically cleans up extracted financial
facts — the normalization step of the audit-grade financial extraction node
suite. No LLM, no network: given the same input it always produces the same
output.

## What it does

Reads structured facts on the `answers` lane and, for every fact, adds a
`normalized` block that:

- **maps the label to a standard metric name** (e.g. `Net sales` / `Turnover` →
  `revenue`) — matching is exact on the cleaned label, so a line item that merely
  *contains* a synonym (`Deferred revenue`, `Non-operating income`) is **not**
  mapped and keeps its own label as a passthrough metric;
- **parses the number and its sign** — parentheses `(1,234)`, trailing minus `1,234-`,
  unicode minus/dashes, and thousands separators are all handled;
- **detects and tags the currency** from symbols (`$ € £ ¥ ₹`) or ISO codes in the
  value or label — currency is **tagged, never converted** (conversion is the separate
  `currency_convert_explicit` node);
- **detects and tags the scale** (`in millions`, `£500m`, `1.2bn`) as a `scale_factor`
  — the scale is recorded but the value is **never multiplied**, so the as-stated
  number stays auditable and the scale can never be applied twice.

Across the batch the node also **de-duplicates** facts that are identical. The
identity key is the **cleaned raw label** plus metric, normalized value, currency,
scale and sign — so two different line items that happen to share a number
(`Revenue 1,234` and `Deferred revenue 1,234`) are always both kept. Facts that
share a label and metric but differ in value, currency or scale are conflicts, not
duplicates, and are all kept — a genuine fact is never dropped. Because dedupe works
on the whole batch, the facts are re-emitted together as a **single list answer** (a
lone bare fact object keeps its shape) — downstream consumers must accept a list
payload even when the facts arrived as separate answers.

The normalization is **non-destructive and audit-friendly**: the raw `label` and
`value` are left untouched, a `normalized` block is added, and a `provenance` entry
records how each field was derived. Records that are not fact objects — plain text,
bare numbers, and dicts carrying neither `label_field` nor `value_field` (page
markers, section headers) — pass through unchanged.

**Scope note:** percentage and ratio values (`12.5%`, `1.5x`) are out of scope for
this experimental version — `value_normalized` comes back `null` while the raw value
is preserved untouched. Handling them (tagging the unit the way scale is tagged) is
planned as a follow-up.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `answers` | `answers` | Normalizes each fact object and de-duplicates the batch; non-fact records pass through unchanged. |

## Configuration

Configuration is mostly optional: the default profile normalizes with plain-text
labels (`label`/`value`) and auto-detected currency and decimal format. The
fields below only need attention for a non-default field naming convention,
specialized label→metric mappings, or a non-US number format.

### Fields

| Field              | Type    | Default  | Description                                                                                       |
|--------------------|---------|----------|---------------------------------------------------------------------------------------------------|
| `label_field`      | string  | `label`  | The fact field holding the free-text metric label.                                                |
| `value_field`      | string  | `value`  | The fact field holding the raw numeric value to parse.                                             |
| `default_currency` | string  | `""`     | 3-letter ISO code to tag when none is detected (upper-cased; anything else is warned about and ignored). Empty leaves facts untagged. |
| `decimal_format`   | string  | `auto`   | `auto`/`us`: comma = thousands, dot = decimal. `eu`: dot = thousands, comma = decimal.            |
| `label_to_metric`  | object  | `{}`     | `{synonym: metric}` map merged over the built-in mapping (user entries win, case-insensitive).    |

The node never fails the run on misconfiguration: an invalid `label_to_metric`,
`decimal_format` or `default_currency` is warned about and ignored, and facts still
pass through normalized as far as possible.

## Notes

### Fact-record convention

A "fact" is a JSON object with a free-text label under `label_field` (default
`label`) and a raw value under `value_field` (default `value`). An answer payload may
be a single fact object or a list of fact objects; other shapes pass through
untouched.

Input:

```json
{ "label": "Revenue ($ in millions)", "value": "1,234.5" }
```

Output:

```json
{
  "label": "Revenue ($ in millions)",
  "value": "1,234.5",
  "normalized": {
    "metric": "revenue",
    "value_normalized": 1234.5,
    "currency": "USD",
    "scale_factor": 1000000,
    "scale_unit": "millions",
    "is_negative": false
  },
  "currency": "USD",
  "provenance": [
    {
      "op": "normalize_facts",
      "value_normalized": 1234.5,
      "currency": "USD",
      "currency_source": "label_symbol",
      "scale_factor": 1000000,
      "scale_unit": "millions",
      "scale_source": "label",
      "sign_source": "none",
      "metric_source": "mapped"
    }
  ]
}
```

`amount` and `currency` are mirrored to the top level (only when absent) so the
downstream `currency_convert_explicit` node works with its default field names.
The `amount` mirror is **withheld when `scale_factor != 1`** (as in the example
above): the converter multiplies `amount` as-is and does not read `scale_factor`,
so mirroring an as-stated in-millions figure would produce a converted number off
by the scale factor. Scaled facts must be explicitly de-scaled before conversion.
If the fact already carries a `provenance` list, the normalization entry is
appended so upstream provenance is preserved.

### Pipeline position

```text
datalab_parse → extract_facts → normalize_facts → currency_convert_explicit → schema_validate → …
```

This node is marked **experimental**.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `normalize_facts.decimal_format` | `string` | **Decimal format**<br/>Number format. 'auto'/'us': comma = thousands separator, dot = decimal point. 'eu': dot = thousands separator, comma = decimal point. | `"auto"` |
| `normalize_facts.default_currency` | `string` | **Default currency**<br/>3-letter ISO code to tag when none is detected in the label or value (anything else is ignored with a warning). Leave empty to keep facts untagged. | `""` |
| `normalize_facts.label_field` | `string` | **Label field**<br/>The fact field holding the free-text metric label (mapped to a standard metric name). | `"label"` |
| `normalize_facts.label_to_metric` | `object` | **Label→metric overrides**<br/>JSON map of {synonym: metric} merged over the built-in mapping (user entries win). Case-insensitive. | `{}` |
| `normalize_facts.profile` | `string` | **Normalization**<br/>Deterministic fact normalization configuration | `"default"` |
| `normalize_facts.value_field` | `string` | **Value field**<br/>The fact field holding the raw numeric value to parse. | `"value"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/normalize_facts)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# OCR

Route: /nodes/ocr

# ocr

A RocketRide filter node that extracts machine-readable text and tables from images using optical character recognition.

## What it does

Turns visual content (scanned documents, screenshots, photos) into structured text for downstream analysis. The node is GPU-capable and registered as a filter in the pipeline.

Four OCR engines are supported via the `ai.common.models` model-server wrappers: **EasyOCR** (multi-language, the default), **DocTR** (document-focused, language-agnostic), **Surya** (multi-language, 90+ languages), and **TrOCR** (transformer-based, Microsoft model). The wrappers auto-detect whether to call a remote model server or fall back to local inference. An unknown engine name falls back to EasyOCR silently.

Table extraction uses **img2table** for OpenCV-based table structure detection, with OCR inference routed through the same model-server adapter (`ModelServerOCR`). Detected tables are emitted on the `table` lane as Markdown. Both img2table v1 and v2 plug-in APIs are supported: v2 reorganised the API and replaced the two-step `content`/`to_ocr_dataframe` contract with a single `of()` method returning `OCRData`; the node detects the installed version at import time via `_IMG2TABLE_V2`.

Animated GIFs are handled frame by frame: each frame is OCR'd individually and the per-frame texts are joined with newlines before being written to the `text` lane. OCR reads are serialised with an internal threading lock so concurrent instances share one engine safely.

## Example pipelines

**Extract and redact document text**

`webhook → parse → ocr → ner → anonymize_text → response_text`

<div align="center">

![The OCR node on the canvas extracting text from parsed documents in a redaction pipeline](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

`parse` feeds document images to OCR and also sends text directly to NER.
Recognized and parsed text is tagged, anonymized, and returned as redacted
text.

**Invoice tables into a database**

`webhook → ocr → extract_data → db_postgres`

Invoice images come in and the `table` lane extracts their line items as
Markdown tables; `extract_data` structures the fields and PostgreSQL stores
the rows — paper documents to queryable data with no manual entry.

**Searchable archive of scanned records**

`webhook → ocr → embedding_transformer → store_qdrant`

OCR converts a scanned archive to text, the embedding node vectorizes it, and
the vector store makes it searchable by meaning rather than filename.

## Lanes

| Lane in     | Lane out | Description                       |
| ----------- | -------- | --------------------------------- |
| `documents` | `text`   | Extract text from image documents |
| `image`     | `text`   | Extract text from a raw image     |
| `image`     | `table`  | Extract tables from a raw image   |

On the `documents` lane, every incoming document must be of type `Image` (the node raises a `ValueError` otherwise). Each image document is OCR'd and re-emitted as a `Document`-type copy whose `page_content` is the extracted text. The original image documents are not forwarded: if a downstream node needs the images themselves, connect it to the source node directly.

## Profiles

Profiles are preconfigured combinations of engine, script family, and table engine. Selecting a profile sets all three at once. Default: **Latin (English)**
(`latin`).

| Profile key            | Title                         | Engine  | Script family         | Table engine |
| ---------------------- | ----------------------------- | ------- | --------------------- | ------------ |
| `latin` **(default)**  | Latin (English)               | EasyOCR | `latin`               | DocTR        |
| `latin-extended`       | Latin Extended (European)     | EasyOCR | `latin-extended`      | DocTR        |
| `cyrillic`             | Cyrillic (Russian, etc.)      | EasyOCR | `cyrillic`            | DocTR        |
| `arabic`               | Arabic/Persian/Urdu           | EasyOCR | `arabic`              | DocTR        |
| `devanagari`           | Devanagari (Hindi, etc.)      | EasyOCR | `devanagari`          | DocTR        |
| `chinese-simplified`   | Chinese (Simplified)          | EasyOCR | `chinese-simplified`  | DocTR        |
| `chinese-traditional`  | Chinese (Traditional)         | EasyOCR | `chinese-traditional` | DocTR        |
| `japanese`             | Japanese                      | EasyOCR | `japanese`            | DocTR        |
| `korean`               | Korean                        | EasyOCR | `korean`              | DocTR        |
| `doctr`                | DocTR (Language-agnostic)     | DocTR   | `latin` (unused)      | DocTR        |
| `surya`                | Surya (Multi-language)        | Surya   | `latin` (unused)      | Surya        |
| `trocr`                | TrOCR (Transformer)           | TrOCR   | `latin` (unused)      | DocTR        |

## Configuration

Pick a profile and you can usually ignore everything else — the remaining
fields exist to override what the profile chose. The main settings panel
exposes `ocr.profile`, `ocr.engine`, `ocr.script_family`, and
`ocr.table_engine`; the DocTR architecture fields are for table extraction
tuning.

### OCR Engine

Overrides the engine the profile selected. The trade-offs: **EasyOCR** covers
the most languages via script families and is the safe default. **DocTR** is
language-agnostic and strongest on structured documents (forms, dense
layouts). **Surya** handles 90+ languages without a script-family choice.
**TrOCR** is transformer-based and best on difficult, handwriting-like text.
An unknown engine name silently falls back to EasyOCR. The TrOCR engine
additionally reads an optional `trocr_model` config value selecting the
Hugging Face model variant (default: `microsoft/trocr-base-printed`).

### Script Family

Script families map to EasyOCR language code lists — this field picks which
set of language models EasyOCR loads. It applies **only when the engine is
EasyOCR**; DocTR, Surya, and TrOCR ignore it. A wrong script family is the
most common cause of garbage output on non-English documents: if Russian
scans come out as Latin gibberish, check this field first.

Every family except plain `latin` also loads English as a fallback:

| Family                | Languages loaded                                                                                                                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `latin`               | `en` only (English only, for reliability)                                                                                              |
| `latin-extended`      | `en` plus ~28 Latin-script languages: fr, de, es, it, pt, nl, pl, ro, cs, sk, hu, hr, sl, sq, lt, lv, da, no, sv, id, ms, tl, vi, tr, az, uz, sw, la, oc |
| `cyrillic`            | ru, uk, be, bg, rs_cyrillic, mn, en (Macedonian not supported by EasyOCR; Serbian maps to `rs_cyrillic`)                              |
| `arabic`              | ar, fa, ur, ug, en                                                                                                                     |
| `devanagari`          | hi, mr, ne, en                                                                                                                         |
| `bengali`             | bn, as, en                                                                                                                             |
| `chinese-simplified`  | ch_sim, en                                                                                                                             |
| `chinese-traditional` | ch_tra, en                                                                                                                             |
| `japanese`            | ja, en                                                                                                                                 |
| `korean`              | ko, en                                                                                                                                 |
| `thai`                | th, en                                                                                                                                 |
| `tamil`               | ta, en                                                                                                                                 |
| `telugu`              | te, en                                                                                                                                 |

The `bengali`, `thai`, `tamil`, and `telugu` families are selectable via `ocr.script_family` but have no preconfigured profile. The Japanese EasyOCR models may misread English text; the full test suite uses a relaxed assertion (`contains: "quick"` instead of `"quick brown fox"`) for that profile.

### Detection / Recognition Architecture (DocTR)

Model choices for DocTR's two-stage table pipeline: detection finds where text
is, recognition reads it. The defaults (`db_resnet50` + `crnn_vgg16_bn`) are
right for nearly everyone; alternatives trade accuracy against speed and
memory — see the [DocTR model docs](https://mindee.github.io/doctr/latest/using_doctr/using_models.html)
before changing them.

Detection architectures: `linknet_resnet18`, `linknet_resnet34`, `linknet_resnet50`, `db_resnet50`, `db_mobilenet_v3_large`, `fast_tiny`, `fast_small`, `fast_base`.

Recognition architectures: `crnn_vgg16_bn`, `crnn_mobilenet_v3_small`, `crnn_mobilenet_v3_large`, `sar_resnet31`, `master`, `vitstr_small`, `vitstr_base`, `parseq`.

### Table OCR Engine

Engine used for table text extraction (default DocTR, which is optimized for
document tables; EasyOCR and Surya are general-purpose alternatives). This is
independent of the main `engine` field — text and tables can use different
engines.

## Requirements

GPU-capable: engines run on CUDA when available and fall back to CPU (slower,
same results). Engine models are fetched through the `ai.common.models`
model-server wrappers, which auto-detect whether to call a remote model
server or run local inference; models download on first use.

## Notes

### OpenCV compatibility

All four engines share the `cv2` namespace but require different OpenCV builds. The node installs a single unified build, `opencv-contrib-python==4.13.0.92`, via `ai.common.opencv`, which also uninstalls competing variants (`opencv-python`, `opencv-python-headless`, `opencv-contrib-python-headless`) so only one `cv2` is active at runtime.

Upstream pins (as of the versions currently used):

| Engine  | PyPI package                               | Upstream OpenCV requirement            | Matches project's 4.13.0.92? |
| ------- | ------------------------------------------ | -------------------------------------- | ---------------------------- |
| EasyOCR | `easyocr` 1.7.2                            | `opencv-python-headless` (unpinned)    | Yes                          |
| DocTR   | `python-doctr` 1.0.1                       | `opencv-python <5.0.0, >=4.5.0`        | Yes                          |
| Surya   | `surya-ocr` 0.17.1                         | `opencv-python-headless==4.11.0.86`    | No (hard pin to 4.11.0.86)   |
| TrOCR   | `craft-text-detector` 0.4.3 (detector dep) | `opencv-python <4.5.4.62, >=3.4.8.29`  | No (caps below 4.5.4.62)     |

Surya and TrOCR's detector pin OpenCV to versions the project deliberately overrides. They work because `ai.common.opencv` runs `depends()` at import time and force-aligns all four OpenCV variants to 4.13.0.92 after the engines are installed. Always import `from ai.common.opencv import cv2` before importing an OCR engine, or the wrong `cv2` may be resolved.

For the same reason, `IGlobal.py` imports `ai.common.opencv` before img2table: img2table internally imports `cv2` at load time, so the correct OpenCV package must already be active.

### img2table version compatibility

img2table 2.0 (released 2026-05-10) reorganised the OCR plug-in API. The node supports both v1 and v2:

| Symbol / location                  | img2table v1      | img2table v2      |
| ---------------------------------- | ----------------- | ----------------- |
| `OCRInstance` base class           | `img2table.ocr.base` | `img2table.ocr._types` |
| Result type returned by `of()`     | `OCRDataframe` (`img2table.ocr.data`) | `OCRData` (`img2table.ocr._types`) |
| Plug-in contract                   | `content()` + `to_ocr_dataframe()` | single `of()` override |

The `_IMG2TABLE_V2` flag is set at import time and gates each code path. `external_contracts.py` declares version-tagged import requirements so the `check-externals` CI framework can validate the correct symbols on whichever version is installed.

## Upstream docs

- [EasyOCR](https://github.com/JaidedAI/EasyOCR)
- [DocTR documentation](https://mindee.github.io/doctr/)
- [Surya](https://github.com/VikParuchuri/surya)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `ocr.det_arch` | `string` | **Detection Architecture (DocTR)**<br/>Choose the architecture used for table text detection.<br/> Documentation: https://mindee.github.io/doctr/latest/using_doctr/using_models.html | `"db_resnet50"` |
| `ocr.engine` | `string` | **OCR Engine**<br/>Select the OCR engine for text extraction. EasyOCR supports many languages with script families. DocTR is language-agnostic and good for documents. Surya supports multi-language. TrOCR uses transformer models. | `"easyocr"` |
| `ocr.profile` | `string` | **OCR Profile**<br/>Select a preconfigured OCR profile optimized for different languages and use cases. | `"latin"` |
| `ocr.reco_arch` | `string` | **Recognition Architecture (DocTR)**<br/>Choose the architecture used for table text recognition.<br/> Documentation: https://mindee.github.io/doctr/latest/using_doctr/using_models.html | `"crnn_vgg16_bn"` |
| `ocr.script_family` | `string` | **Script Family**<br/>Select the script family for OCR. This determines which languages are loaded for text recognition. Only applies to EasyOCR engine. | `"latin"` |
| `ocr.table_engine` | `string` | **Table OCR Engine**<br/>Select the OCR engine used for table text extraction. DocTR is optimized for document tables. EasyOCR and Surya are general-purpose alternatives. | `"doctr"` |

## Dependencies

- `img2table`
- `pillow`
- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/ocr)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Pose Estimation

Route: /nodes/pose_estimation

# pose_estimation

A RocketRide image node that estimates human poses and produces a per-person set of COCO keypoints with an annotated skeleton. Choose it when a pipeline needs body position or joints, rather than only person detections or face locations.

## About RTMPose

RTMPose is the human-pose-estimation engine used here through the rtmlib ONNX wrapper. This node first detects people, then uses RTMPose to predict the keypoints for each retained person crop.

## What it does

For every input image frame, the node estimates people and emits a JSON array of person boxes with 17 COCO keypoints, as well as an annotated JPEG with skeleton lines and points. The configured threshold controls what is drawn, and the retained-person limit bounds crowded-frame processing. Use it instead of face detection when full human pose matters, and instead of object detection when downstream work needs joint locations.

## Lanes

| Lane in | Lane out | Description |
| ------- | -------- | ----------- |
| `image` | `image` | JPEG copy of the frame annotated with person boxes, skeleton edges, and qualifying keypoints. |
| `image` | `text` | JSON array of people, each with a `person` label, a box, and 17 named COCO keypoints containing coordinates and scores. |

## Profiles

Default: **RTMPose Medium** (`rtmpose-medium`).

| Profile | Default keypoint threshold | Default maximum persons |
| ------- | -------------------------- | ----------------------- |
| RTMPose Tiny | `0.3` | `20` |
| RTMPose Medium **(default)** | `0.3` | `20` |
| RTMPose Large | `0.3` | `20` |

## Configuration

Select a pose profile first, then use the threshold and person cap to balance useful annotation against work on each frame. The implementation normalizes invalid values at startup, so keeping the configuration within its declared range makes the chosen behavior explicit.

### Model

The Tiny, Medium, and Large profiles select their corresponding RTMPose modes; the default is Medium. Use a smaller profile where response time matters more than pose detail, and a larger profile where the available compute justifies it. An unknown profile falls back to the implementation's default mode.

### Keypoint score threshold

This `0.0`–`1.0` threshold controls skeleton rendering: keypoints below it are not drawn, and an edge is omitted if either endpoint is below it. The default `0.3` gives a moderately permissive overlay. Raise it to remove uncertain joints from the image output; lower it to show more tentative joints. The text output still receives the estimator's keypoint array, so consumers that make their own confidence decision should use the scores in JSON rather than relying on the drawing.

### Max persons per frame

The node keeps at most this many people after sorting by detection score. The default is `20`; reduce it for crowd scenes when latency or memory usage matters, and increase it when every person in a dense image is important. The runtime clamps the value to the `1`–`200` range.

## Requirements

This node declares GPU capability. It creates the pose-estimation facade with no fixed device: with a model server configured, inference is delegated there; otherwise it runs locally and serializes device access with a shared lock. Plan accelerator capacity for local high-throughput processing, especially when retaining many people per frame.

## Notes

### Output and failures

The text and image outputs are emitted only when their lanes have listeners. If an image cannot be decoded or inference fails, the node logs a warning, drops the frame, and prevents default forwarding instead of producing a partial pose result.

## Upstream docs

- [RTMPose documentation](https://mmpose.readthedocs.io/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `pose_estimation.max_persons` | `number` | **Max persons per frame**<br/>Cap on persons retained per frame (sorted by detection score). Limits memory + compute on crowd scenes. | `20` |
| `pose_estimation.profile` | `string` | **Model** | `"rtmpose-medium"` |
| `pose_estimation.threshold` | `number` | **Keypoint score threshold**<br/>Minimum per-keypoint confidence (0.0–1.0). Keypoints below this score are skipped when drawing the skeleton. | `0.3` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/pose_estimation)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Code

Route: /nodes/preprocessor_code

# preprocessor_code

A RocketRide preprocessor node that splits supported source code into
syntax-aware documents. Choose it over a general-text or LLM preprocessor when
you want code structures, rather than prose boundaries, to drive chunking.

## About Tree-sitter

Tree-sitter is the parsing library this node uses to build source-code syntax
trees. The node installs its language-specific grammar packages and creates a
parser for the selected language.

## What it does

Receives `text` and emits `documents` made from syntax-tree nodes. It supports
the C, C++, Python, JavaScript, and TypeScript profiles; in automatic mode it
detects one of those languages from the text itself. A matched class or
function can coexist with chunks for nested constructs, so output may overlap.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `documents` | Split source-code text into syntax-aware documents. |

## Profiles

Default: `auto`, which detects the language from the source text.

| Profile | Language |
| --- | --- |
| `auto` *(default)* | Detect from source text |
| `c` | C |
| `cpp` | C++ |
| `python` | Python |
| `javascript` | JavaScript |
| `typescript` | TypeScript |

## Configuration

Select the language profile that matches the input when its language is known;
otherwise leave the default automatic profile. The maximum string length is
present in the configuration, but the current implementation determines output
boundaries from syntax nodes.

### Code splitter profile

The automatic profile samples up to the first 5,000,000 characters and scores regex signals
for the five supported languages. It needs a score of at least 3 and a lead of
at least 2 over the runner-up; otherwise the input produces no documents and a
warning is emitted. Use an explicit profile for short snippets, unusual code,
or content that automatic detection cannot classify reliably.

For C and C++, automatic detection favors C for header-like ties and for
`extern "C"` without C++-only markers. Pick `cpp` explicitly when that
conservative choice is wrong for your input.

### Maximum string length

This value defaults to 512, but the splitter does not use it to divide a
syntax node. A large class or function is therefore emitted as one chunk even
when it exceeds that value. Change it only if a downstream component reads the
same configuration; it does not constrain this node's output today.

## Notes

### Output details

Both text and table callbacks are parsed. Table-derived documents are marked
as tables; each object starts its `chunkId` at 0. C and C++ header declarations
and whole `extern "C"` linkage blocks are included, while preprocessor lines
such as `#include` and `#define` are skipped.

The parser cache is a class attribute on `PreProcessor`, so a grammar loaded
once is reused by every instance in the process and outlives any single global
node instance. If the optional `tree_sitter_languages` package is available it
is used to load a grammar; otherwise the node loads the installed per-language
grammar module.

## Upstream docs

- [Tree-sitter documentation](https://tree-sitter.github.io/tree-sitter/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `code.splitter.auto.language` | `string` |  | const: `"auto"` |
| `code.splitter.c.language` | `string` |  | const: `"c"` |
| `code.splitter.cpp.language` | `string` |  | const: `"cpp"` |
| `code.splitter.javascript.language` | `string` |  | const: `"javascript"` |
| `code.splitter.profile` | `string` | **Code splitter profile** | `"auto"` |
| `code.splitter.python.language` | `string` |  | const: `"python"` |
| `code.splitter.strlen` | `number` | **Maximum string length** | `512` |
| `code.splitter.typescript.language` | `string` |  | const: `"typescript"` |

## Dependencies

- `tree-sitter`
- `tree-sitter-c`
- `tree-sitter-cpp`
- `tree-sitter-javascript`
- `tree-sitter-python`
- `tree-sitter-typescript`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/preprocessor_code)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# General Text

Route: /nodes/preprocessor_langchain

# preprocessor_langchain

A RocketRide preprocessor node that splits general text into documents for
embedding or LLM processing. Choose it over the code preprocessor for prose and
over the LLM preprocessor when deterministic, local splitter behavior is enough.

## About LangChain

LangChain provides the `langchain_text_splitters` classes used by this node.
The node selects one of those classes from its profile and supplies the chunk
size and length function it uses for splitting.

## What it does

Splits incoming `text` and `table` content on the `documents` lane. It offers
general, Markdown, LaTeX, sentence-oriented, and fixed-separator splitters,
whereas the code preprocessor extracts code syntax and the LLM preprocessor
asks a connected model to make chunking decisions. Text is accumulated until an
object closes; tables are split as they arrive.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `documents` | Split accumulated text when the object closes. |
| `table` | `documents` | Split each incoming table immediately. |

## Profiles

Default: `default`, the recursive character splitter.

| Profile | Splitter |
| --- | --- |
| `default` *(default)* | `RecursiveCharacterTextSplitter` |
| `recursive` | `RecursiveCharacterTextSplitter` |
| `character` | `CharacterTextSplitter` |
| `markdown` | `MarkdownTextSplitter` |
| `latex` | `LatexTextSplitter` |
| `nltk` | `NLTKTextSplitter` |
| `spacy` | `SpacyTextSplitter` |
| `custom` | `RecursiveCharacterTextSplitter` |

## Configuration

Start with the default profile and string-length mode for ordinary prose. Pick
a content-specific profile when its boundaries matter, then set the size in
characters or estimated tokens. The generated schema lists the profile-owned
fields; the choices below explain their operational effects.

### Text splitter

The profile fixes the splitter class; changing the class field to another
value fails configuration validation. Use `markdown` for Markdown, `latex` for
LaTeX, `character` for one fixed separator, `nltk` for the NLTK splitter, or
`spacy` for the spaCy splitter. The `custom` selector is present in the
configuration but is also fixed to `RecursiveCharacterTextSplitter`, so it
currently behaves like `default`.

### Split by and chunk size

String-length mode uses the configured string length, 512 by default. Token
mode estimates tokens as UTF-8 byte length divided by 3, rounded up; this is a
conservative estimate rather than a tokenizer's count. Choose token mode when
a downstream model or embedding service has a token budget, and lower the size
when chunks are rejected for being too long.

### Split separators

For the recursive profile, write a comma-separated sequence of quoted Python
string literals, such as `'\n\n', '\n', ' ', ''`. The node parses that
sequence with `ast.literal_eval`; every item must be a string or startup fails.
For the character profile, supply exactly one such literal. Change recursive
separators to prefer domain boundaries before falling back to shorter ones.

### Model

The spaCy profile uses the selected spaCy pipeline, defaulting to
`en_core_web_sm`. Choose one of the listed English, German, French, or Spanish
models for text in that language. If the pipeline is absent, the node downloads
it before creating the splitter; this may delay the first run.

## Notes

### Downloads and output

The NLTK profile installs its extra dependencies when selected and downloads
`punkt` when it cannot find it; it also attempts to download `punkt_tab` when
needed. All splitters use zero chunk overlap. Every emitted document receives a
sequential `chunkId` per object; table documents also receive a `tableId`.

### Token-budget safety net

When token mode also has a positive `max_model_tokens` configuration value,
the node subtracts `token_safety_margin` (32 by default), caps the requested
chunk size to the result, and force-splits any remaining oversized output. The
byte-per-token estimate defaults to 3.0 and can be changed through
`bytes_per_token`; lowering it estimates more tokens and is the safer choice.

## Upstream docs

- [LangChain text splitters](https://python.langchain.com/docs/how_to/recursive_text_splitter/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `langchain.splitter.character.separator` | `string` | **Split separator** | `"\"\\n\""` |
| `langchain.splitter.character.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to CharacterTextSplitter by the 'Character Text Splitter' profile and cannot be changed here. To use a different splitter, change the 'Text splitter' selector above to the matching profile. Editing this to another class fails validation with 'must be equal to constant'. | const: `"CharacterTextSplitter"` |
| `langchain.splitter.custom.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to RecursiveCharacterTextSplitter by the 'Custom' text-splitter profile and cannot be changed here; the custom profile currently behaves like default. To use a different splitter, change the 'Text splitter' selector above to the matching profile. Editing this to another class fails validation with 'must be equal to constant'. | const: `"RecursiveCharacterTextSplitter"` |
| `langchain.splitter.default.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to RecursiveCharacterTextSplitter by the 'Default' text-splitter profile and cannot be changed here. To use a different splitter, change the 'Text splitter' selector above to the matching profile (for example Markdown for MarkdownTextSplitter). Editing this to another class fails validation with 'must be equal to constant'. | const: `"RecursiveCharacterTextSplitter"` |
| `langchain.splitter.latex.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to LatexTextSplitter by the 'Latex Text Splitter' profile and cannot be changed here. To use a different splitter, change the 'Text splitter' selector above to the matching profile. Editing this to another class fails validation with 'must be equal to constant'. | const: `"LatexTextSplitter"` |
| `langchain.splitter.markdown.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to MarkdownTextSplitter by the 'Markdown Text Splitter' profile and cannot be changed here. To use MarkdownTextSplitter, select 'Markdown Text Splitter' in the 'Text splitter' selector above rather than editing this field. Editing this to another class fails validation with 'must be equal to constant'. | const: `"MarkdownTextSplitter"` |
| `langchain.splitter.mode` | `string` | **Split by** | `"strlen"` |
| `langchain.splitter.nltk.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to NLTKTextSplitter by the 'NLTK Text Splitter' profile and cannot be changed here. To use a different splitter, change the 'Text splitter' selector above to the matching profile. Editing this to another class fails validation with 'must be equal to constant'. | const: `"NLTKTextSplitter"` |
| `langchain.splitter.profile` | `string` | **Text splitter**<br/>Selects the splitter profile. Each profile locks one LangChain splitter class and shows only that splitter's options, so the splitter class is not chosen independently of the profile. Pick the profile that matches your content: Markdown for .md, Latex for LaTeX, Character/NLTK/Spacy as needed. Editing a profile's splitter field to a different class fails schema validation with a 'must be equal to constant' error; change this selector instead. | `"default"` |
| `langchain.splitter.recursive.separators` | `string` | **Split separators** | `"'\\n\\n', '\\n', ' ', ''"` |
| `langchain.splitter.recursive.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to RecursiveCharacterTextSplitter by the 'Recursive Character Text Splitter' profile and cannot be changed here. To use a different splitter, change the 'Text splitter' selector above to the matching profile. Editing this to another class fails validation with 'must be equal to constant'. | const: `"RecursiveCharacterTextSplitter"` |
| `langchain.splitter.spacy.model` | `string` | **Model** | `"en_core_web_sm"` |
| `langchain.splitter.spacy.splitter` | `string` | **Splitter class (set by profile)**<br/>Fixed to SpacyTextSplitter by the 'Spacy Text Splitter' profile and cannot be changed here. To use a different splitter, change the 'Text splitter' selector above to the matching profile. Editing this to another class fails validation with 'must be equal to constant'. | const: `"SpacyTextSplitter"` |
| `langchain.splitter.strlen` | `number` | **String length** | `512` |
| `langchain.splitter.tokens` | `number` | **Number of tokens** | `512` |

## Dependencies

- `langchain`
- `langchain-text-splitters`
- `langchain-core`
- `accelerate`
- `transformers`
- `tokenizers`
- `huggingface-hub`
- `pyyaml`
- `filelock`
- `regex`
- `tqdm`
- `safetensors`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/preprocessor_langchain)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# LLM

Route: /nodes/preprocessor_llm

# preprocessor_llm

A RocketRide preprocessor node that uses a connected LLM to split document text
into chunks for vector embedding storage. Choose it over rule-based text
splitters when the LLM's document-level chunking guidance is worth the model
call.

## About LangChain

LangChain is a library for language-model applications. This node's package
declares `langchain` and `langchain-core` dependencies while obtaining model
operations through RocketRide's LLM connection.

## What it does

Accumulates text for an object and, when it closes, asks the required LLM
connection for a JSON `chunks` array. The prompt requests coherent chunks that
preserve the input text plus a final summary chunk. Choose the general-text
preprocessor when deterministic local splitting is preferable, or the code
preprocessor for source-code syntax.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| `llm` | yes | LLM used to process document text. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `documents` | Accumulate and LLM-chunk text when the object closes. |
| `table` | `documents` | Split tables locally into document chunks. |

## Configuration

The default configuration uses 384 tokens as the prompt's target chunk size.
Connect an LLM before processing, because the node reads that connection's
context length, output length, and token counter on its first object.

### Number of tokens per document chunk

This setting is included in the LLM prompt as the target size, with a
three-quarters-as-many-words fallback. Set it to the chunk capacity appropriate
for the embedding model that will receive the documents. It also sets the
budget used to divide tables at line boundaries, so reduce it when table chunks
are too large for the downstream embedding model. It is not the limit used to
pre-split text for the LLM request: that limit comes from the connected LLM's
context and output capacities.

## Notes

### Text and table processing

Before calling the LLM, the node reserves its prompt size and 500 tokens for
JSON formatting, then uses the smaller of the remaining context budget and the
model's output capacity. It begins splitting oversized text at a 65,536-character
threshold, working through paragraphs, lines, sentences, and finally words. A
single oversized word can remain intact rather than being cut further.

Tables bypass the LLM. They are split only between lines; a line that is longer
than the configured token budget remains a chunk by itself. Empty output
content is discarded. Each emitted document gets a `chunkId`; LLM summary
chunks are marked as summaries, and chunks made from tables are marked as
tables with a shared `tableId` for their source table.

### LLM response shape

The node reads `chunks` from the LLM's JSON response. If that key is absent or
empty, text input produces no text documents; table chunks already collected
can still be emitted.

## Upstream docs

- [LangChain documentation](https://python.langchain.com/docs/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `preprocessor_llm.numberOfTokens` | `number` | **Number of tokens per document chunk. Needs to match your embedding model.** | `384` |
| `preprocessor_llm.profile` | `string` |  | `"default"` |

## Dependencies

- `langchain`
- `langchain-core`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/preprocessor_llm)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Prompt

Route: /nodes/prompt

# prompt

A RocketRide transformation node that merges multiple pipeline inputs into a single enriched question before it reaches an LLM or agent.

## What it does

Assembles a structured `Question` object from multiple pipeline inputs and emits it downstream. This is the primary mechanism for injecting retrieved documents, extracted text, and table content into a question before it reaches an LLM or agent node.

Each input lane maps to a different section of the rendered prompt. Inputs are collected as they arrive; the fully assembled question is not emitted until the node is closing, at which point all accumulated inputs are merged with the configured instructions and the enriched question is emitted on the `questions` lane.

If no `instructions` are configured, the default profile supplies a single instruction: `"Please provide a detailed and helpful response to the following question:"`. If an error occurs during the merge, the node logs the error and the enriched question is not emitted.

Use Prompt instead of Question when a downstream LLM needs a question together
with instructions or accumulated context. Use Question when text only needs to
be converted into a question without assembling a prompt.

## Lanes

| Lane in     | Lane out    | Description                                                                       |
| ----------- | ----------- | --------------------------------------------------------------------------------- |
| `documents` | (none)      | Added to the `### Documents:` section of the prompt                               |
| `text`      | (none)      | Added to the `### Context:` section of the prompt                                 |
| `table`     | (none)      | Added to the `### Context:` section of the prompt                                 |
| `questions` | `questions` | Collects question inputs; emits the fully assembled question when the node closes |

## Configuration

The default profile supplies one detailed-response instruction. Most pipelines
only need to change the setting when their downstream model needs a different
role, format, or response constraint.

### Instructions

Each instruction is added with the name `User Instruction`; when multiple instructions are configured they are numbered (`User Instruction 1`, `User Instruction 2`, and so on). A single string value is also accepted and treated as a one-element list.

Use a short, specific instruction when the retrieved context already states
the task. Add separate instructions when their order matters; they are added in
their configured order before the collected context and question.

## Requirements

The node is marked GPU-capable in its metadata, but its implementation only
assembles a `Question` object and does not load or call a model itself. Any
hardware requirement comes from the downstream LLM or agent that consumes the
result.

## Notes

### Rendered prompt structure

When the question is consumed by an LLM or agent, it is rendered in this order:

```
### System Instructions:
    1) **User Instruction**: [your configured instructions]

### Context:
    1) [text or table content from text/table lanes]

### Documents:
    Document 1) Content: [document content from documents lane]

### Current Task:
    [question text from questions lane]
```

---

### Typical use

The most common use is passing retrieved documents or extracted text alongside a question into an agent or LLM, giving it context it would not otherwise have.

**RAG into an LLM:**

```
           ┌──→ vector store ──→ documents ─┐
source ────┤                                ├──→ Prompt ──→ LLM
           └──────────────── questions ─────┘
```

**Passing context to an agent:**

```
text extractor ──→ text ──────────────────┐
vector store ───→ documents ──────────────┤
                                          ├──→ Prompt ──→ agent
source ─────────→ questions ──────────────┘
```

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `instructions` | `array` | **Instructions**<br/>Multiple instructions to add to questions before sending to LLM |  |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/prompt)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Question

Route: /nodes/question

# question

A RocketRide filter node that trims incoming text and wraps it as a `Question` object.

## What it does

Takes raw text from the `text` lane, strips surrounding whitespace, and encapsulates it as a `Question` object on the `questions` lane. The content is not generated, rewritten, or altered in any way; the node exists solely to translate unstructured text into the typed question entity that downstream nodes (vector stores, LLMs, agents, and the Prompt node) expect.

If the text is empty or whitespace-only after stripping, the node calls `preventDefault` and skips processing. The pipeline continues to the next node without emitting a question.

Choose Question when a pipeline has text that a downstream component expects as
a typed question. Choose Prompt instead when the question must also be combined
with instructions, documents, tables, or other context.

## Lanes

| Lane in | Lane out    | Description                                     |
|---------|-------------|-------------------------------------------------|
| `text`  | `questions` | Wrap text as a Question and pass it downstream  |

## Configuration

This node has no configurable fields. The single `default` profile is empty,
so wiring is the only setup: send non-empty text to `text` and consume the
result from `questions`.

## Requirements

This node needs no hardware of its own: it strips whitespace and wraps the text
as a `Question`, without loading or calling a model. Any GPU requirement belongs
to the node downstream that handles the question.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/question)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Reducto

Route: /nodes/reducto

# reducto

A RocketRide data node that uploads each incoming document to Reducto, then emits its reconstructed Markdown text and each detected table; use it when Reducto's parsing options match the documents you need to process.

## About Reducto

Reducto provides a document-parsing API for extracting content from files.
This node uses the Reducto Python client to upload document bytes, request a
parse, and convert the returned blocks into text and table outputs for a
RocketRide pipeline.

## What it does

Reducto buffers one document from the `tags` lane, uploads it, and calls the
Reducto parse API. It builds Markdown from the returned blocks and writes each
table both within that text and as a separate item on `table`. Pick it when you
want its simple OCR/figure options or can provide its advanced `enhance`
settings; choose a different parser when the required output is not the
block-based Markdown this node reconstructs.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `tags` | `text` | Markdown reconstructed from returned content blocks. |
| `tags` | `table` | Each returned `table` block, as separate Markdown content. |

## Configuration

The default profile uses Simple mode. Use it for the three built-in enhancement
choices; switch to Advanced Mode only when you need to send raw Reducto
`enhance` dictionaries. The simple and advanced settings are mutually
exclusive in the implementation.

### Advanced Mode

With **Advanced Mode** off, the node builds the `enhance` request from the
three simple toggles. With it on, it ignores those toggles and reads **Options**,
**Advanced Options**, and **Experimental Options** as Python dictionary
literals. Empty fields are omitted; present dictionaries merge in that order,
so a later field overrides an earlier key. Use Python syntax such as
`{'ocr_mode': 'agentic'}`, not JSON syntax such as `{"enabled": true}`:
validation uses `ast.literal_eval` and rejects a value that is not a dictionary.

### Simple-mode enhancement choices

**Contains Handwritten Text** adds `ocr_mode: 'agentic'`; enable it for
handwriting or small text and table-cell corrections. **Contains Non-English
Text** adds `ocr_system: 'multilingual'`; enable it for non-Germanic languages
or Unicode symbols. **AI Summarize Figures/Images** adds
`summarize_figures: true`; leave it off when the original figure content is
more useful than a generated summary. All three default to off.

In Simple mode the node always sends `summarize_tables: false`, regardless of
the figure-summary setting. In Advanced Mode, supply any desired behavior in
the dictionaries instead.

## Authentication

Set **API Key** to a Reducto API key. Configuration validation performs a
minimal in-memory upload of `ping.txt`; failure raises `Reducto API key
validation failed`, so saving configuration requires access to Reducto.

## Notes

### Output and failure behavior

The node performs a remote parse only when processing a buffered document.
It writes text or tables only when their respective output lane has a listener.
If the API key is missing, upload or parsing fails, or the response cannot be
read, the parser returns empty text and no tables; the instance logs the
condition and emits no replacement error document.

### Markdown reconstruction

Returned `title`, `section_header`, and `list_item` blocks become Markdown
headings and bullets. Table blocks are included in the full text and emitted
separately. A `figure` block is emitted as ordinary content unless figure
summarization was enabled, in which case it is prefixed with
`[DIAGRAM/IMAGE SUMMARY]:`.

## Upstream docs

- [Reducto documentation](https://docs.reducto.ai/overview)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `reducto.Contains_Handwritten_Text` | `boolean` | **Contains Handwritten Text**<br/>Enables Agentic OCR mode for better handwriting recognition and small text/table cell corrections. | `false` |
| `reducto.Contains_Non_English_Text` | `boolean` | **Contains Non-English Text**<br/>Enables Multilingual OCR system which can parse non-Germanic languages and unicode symbols. | `false` |
| `reducto.Summarize_Text` | `boolean` | **AI Summarize Figures/Images**<br/>Generate AI summaries for figures, diagrams, and images using vision-language models. | `false` |
| `reducto.advanced_documentation` | `null` | **Advanced Parse Mode - How to**<br/>In advanced mode, you can use the full set of options from the Reducto API. For each set of options you must use and only include a python dictionary, e.g., {'key': 'value', 'flag': True}. If no information is provided for a set of options, the default values will be used. For more information on what options are available, see the Reducto API documentation at https://docs.reducto.ai/parsing/default-configurations. This page also contains examples of how to format the options fields. (In Advanced mode your configuration from Simple mode will be ignored) | `null` |
| `reducto.advanced_options` | `string` | **Advanced Options**<br/>Advanced options for the Reducto API |  |
| `reducto.api_key` | `string` | **API Key**<br/>Your Reducto API key |  |
| `reducto.experimental_options` | `string` | **Experimental Options**<br/>Experimental options for the Reducto API |  |
| `reducto.options` | `string` | **Options**<br/>Options for the Reducto API |  |
| `reducto.parse_mode` | `boolean` | **Advanced Mode**<br/>Toggle to use the advanced parse mode, and have access to the full set of options from the Reducto API. | `false` |

## Dependencies

- `reductoai`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/reducto)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Remote Processing

Route: /nodes/remote

# remote

A RocketRide infrastructure node that forwards execution of a sub-pipeline to a separate RocketRide server.

## What it does

Forwards pipeline execution to a separate RocketRide server. The sub-pipeline
configuration is sent to the remote server over HTTP, data streams through a persistent
WebSocket connection, and results are returned to the local pipeline as they are
produced. Use this to run GPU-heavy or resource-intensive sub-pipelines on a dedicated
machine.

The node directory ships two services:

| Service | Protocol | Role |
|---------|----------|------|
| **Remote Processing** (`services.client.json`) | `remote://` | The node you place in a pipeline. Holds the sub-pipeline and the connection settings. |
| **Remote Server** (`services.server.json`) | `remote_server://` | Internal counterpart instantiated inside the remote pipeline. Marked `internal` -- never added by users directly. |

Built on **fastapi** (server-side WebSocket endpoint), **websockets** (synchronous
client connection), and **nest-asyncio** (running async coroutines from the synchronous
engine context).

Both services carry the `nosaas` capability -- the node is available on self-hosted
deployments only, not on RocketRide Cloud.

---

### How it works

`preparePipeline` (in `client/prepare_pipeline.py`) rewrites the user's simplified
pipeline before execution, based on the selected profile:

- **`local` profile** -- the remote node is removed and its sub-pipeline components are
  inlined into the local pipeline at the same position. Nothing leaves the machine.
- **`remote` profile** -- lanes that cross the local/remote boundary are rewired through
  the `remote` (client) and `remote_server` nodes, and a `remote_source_stub` source is
  inserted at the head of the remote pipeline:
  - local to remote: `local component -> remote -> remote_server -> remote component`
  - remote to local: `remote component -> remote_server -> remote -> local component`

Every component placed inside the sub-pipeline must support remote execution
(`PROTOCOL_CAPS.REMOTING`); preparation fails with
`The component '<provider>' does not support remote execution` otherwise. The remote
node itself must not have any `input` entries of its own in the simplified
configuration.

At runtime (remote profile) the client:

1. Sends `POST http://<host>:<port>/use?name=remote` to load the remote node on the server.
2. Creates the remote pipe with `POST http://<host>:<port>/remote?pipe=<taskId>`, posting the sub-pipeline JSON. The task ID of the running job identifies the pipe.
3. Opens `ws://<host>:<port>/remote/pipe?pipe=<taskId>` and keeps it open for the lifetime of the instance.
4. Deletes the remote pipe with `DELETE` on the same control URL when the pipeline ends.

All HTTP and WebSocket requests carry an `Authorization: Bearer <apikey>` header.

---

## Profiles

Default: `local`, which inlines the sub-pipeline without opening a network
connection.

| Profile | Description |
|---------|-------------|
| `local` **(default)** | Inlines the sub-pipeline locally; no network connection is created. |
| `remote` | Uses the preset `localhost:5565` and `xxx` API key as placeholders; replace them with the remote server details. |

## Configuration

### Pipeline and lane forwarding

`services.client.json` declares no static lanes (`"lanes": {}`); lane wiring is derived
from the sub-pipeline by `preparePipeline`. At runtime the client forwards these calls
over the WebSocket when the lane is listed in `input`:

| Lane | Payload | Sent when |
|------|---------|-----------|
| `tags` | bytes | `writeTag` -- only if `tags` is in `input` (default) |
| `text` | string | `writeText` -- only if `text` is in `input` |
| `words` | string list | `writeWords` -- only if `words` is in `input` |
| `documents` | document list | `writeDocuments` -- only if `documents` is in `input` |

Lifecycle calls `open`, `closing`, and `close` are always forwarded so the remote
pipeline tracks the local object lifecycle. Responses from the remote pipeline
(`writeText`, `writeDocuments`, etc.) are dispatched back into the local pipeline as
they arrive.

### Remote endpoint and sub-pipeline

Settings live under the node's `remote` configuration block; the sub-pipeline lives
under `pipeline`.

| Field      | Type / default | Description |
|------------|----------------|-------------|
| `profile`  | enum, default `local` | Execution mode: `local` or `remote` (see profiles below). |
| `host`     | string | Hostname or IP of the remote RocketRide server. Required in remote mode. |
| `port`     | number | Server port. Required in remote mode (remote profile preset uses `5565`). |
| `apikey`   | string | Bearer token for authenticating against the remote server. Required in remote mode. |
| `pipeline` | object | The sub-pipeline definition to execute remotely. Required. |
| `input`    | string list, default `["tags"]` | Lanes forwarded from the local pipeline to the remote one. |
| `output`   | string list, default `["documents"]` | Lanes expected back from the remote pipeline. |

Startup fails fast with an explicit exception if `host`, `port`, `apikey`, `pipeline`,
or the job's task ID is missing.

---

### Profile presets

| Profile | Description |
|---------|-------------|
| `local` _(default)_ | Runs the sub-pipeline on the same machine -- components are inlined, no network involved. |
| `remote` | Runs the sub-pipeline on a separate host. Preset values: `host: localhost`, `port: 5565`, `apikey: xxx` -- override all three before use. |

---

## Limitations

Remote Processing and its internal Remote Server counterpart are marked `nosaas`. They run only on self-hosted RocketRide deployments, because remote execution creates HTTP and WebSocket connections to another RocketRide server and transfers the configured sub-pipeline and its data across that boundary.

### Error handling and limits

- Every forwarded call is acknowledged: after processing, each side sends an `error`
  lane message containing an `APERR` result. A non-success code is re-raised on the
  caller's side, so remote failures surface in the local pipeline with the original
  error code (`Ec.RemoteException` wraps errors that originate locally while handling a
  remote response).
- List payloads are split into chunks whose estimated JSON size stays under ~0.98 MiB,
  keeping each WebSocket message below the default 1 MiB `max_size`. Large document
  batches therefore transfer as multiple messages transparently.
- The WebSocket is opened with no open/close timeout and stays connected for the whole
  instance lifetime; `websockets.client` logging is routed through the engine's
  `Remoting` log level.

---

## Notes

- Self-hosted deployments only -- not available on RocketRide Cloud (`nosaas` capability).
- The remote server must be running a RocketRide instance with the server component enabled.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Remote Processing (`services.client.json`)

_No configuration fields._

## Dependencies

- `fastapi`
- `nest-asyncio`
- `websockets`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/remote)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Cohere Rerank

Route: /nodes/rerank_cohere

# rerank_cohere

A RocketRide rerank node that reorders retrieved documents by relevance to the query using Cohere's Rerank API.

## About Cohere

Cohere provides the Rerank API used by this node to score a query against a list of document strings. The node sends the configured model, query, document list, and requested result count to that API, then uses the returned relevance scores to construct RocketRide documents.

## What it does

Takes questions that already carry retrieved documents and reorders those documents by how well they match the query. Cohere scores each document, results are sorted by relevance, cut to the top N, and anything below the minimum score threshold is dropped. Put it downstream of a retrieval or vector-store node so it can rerank the documents attached to each question.

Uses the **cohere** Python SDK (`ClientV2`). Supports the `rerank-english-v3.0` (default) and `rerank-v3.5` models, or any custom model name.

Key behavior to know:

- The incoming question is **deep-copied** before processing, so shared question objects in fan-out pipelines are never mutated.
- The query text is taken from the question's **first** question entry; a missing or whitespace-only query raises an error.
- Documents whose `page_content` is missing, non-string, or whitespace-only are **silently skipped** (Cohere rejects whitespace-only documents). If no usable document content remains, the node raises an error.
- Reranked documents preserve the original document `metadata`; the `score` field is replaced with Cohere's `relevance_score`.
- The `min_score` filter is applied **after** the top-N cut, so you can receive fewer than `top_n` results.
- Config validation only checks presence and format of required fields. It does **not** make a live API call, so a Cohere outage or rate limit at config time cannot surface a misleading error.

---

## Lanes

| Lane in     | Lane out    | Description                                   |
|-------------|-------------|-----------------------------------------------|
| `questions` | `documents` | Reranked documents ordered by relevance score |
| `questions` | `answers`   | An answer with the reranked documents         |

The `documents` lane is written only when at least one document survives the `min_score` filter. The `answers` lane is **always** written, so downstream nodes receive a result even when every document was filtered out: the answer text is the surviving documents' content joined by blank lines (empty string if none survived).

## Profiles

Default: **Rerank v3.0** (`rerank-english-v3.0`). The **Model** dropdown
selects a preconfigured profile:

| Profile               | Title       | Model                           |
|-----------------------|-------------|---------------------------------|
| `rerank-english-v3.0` **(default)** | Rerank v3.0 | `rerank-english-v3.0` |
| `rerank-v3.5`         | Rerank v3.5 | `rerank-v3.5`                   |
| `custom`              | Custom      | _(free-form model name)_        |

All preset profiles expose `top_n`, `min_score`, and the API key; `custom`
additionally takes a free-form model name.

## Configuration

Select a preset for the supplied model name, or use Custom to enter a model name. Most tuning is the trade-off between how many candidates Cohere considers worth returning and how selective the local score filter should be.

### Model

The named profiles provide their declared model values. Use Custom only when the API key is authorized for the name entered; the node rejects an empty or whitespace-only model before it can make a request.

### Top N and Min Score

`top_n` determines how many results are requested from Cohere before local filtering. It must be an integer of at least 1; whole-number numeric values are accepted, while booleans and fractional values are rejected. Keep the default of 5 for a small candidate set, increase it when later pipeline stages need more alternatives, and lower it to limit the resulting context.

`min_score` is then applied to those returned results and must be between 0.0 and 1.0. The default 0.0 preserves all returned results. Raise it to remove weak matches, but expect fewer than `top_n` documents because the threshold is applied after Cohere's top-N result set has been returned.

---

## Authentication

A Cohere API key is required. Set it in the node's **API Key** field. The node fails to initialize (with a warning) if the key is missing or blank.

The built-in pipeline test cases require the `ROCKETRIDE_RERANK_COHERE_KEY` environment variable to run against the live API.

---

## Notes

### API failures

Cohere API errors are mapped to a custom exception hierarchy whose class names let retry/circuit-breaker heuristics classify them correctly:

| Cohere error           | Raised as                   | Retryable |
|------------------------|-----------------------------|-----------|
| `UnauthorizedError`    | `RerankAuthenticationError` | No        |
| `BadRequestError`      | `RerankBadRequestError`     | No        |
| `TooManyRequestsError` | `RerankRateLimitError`      | Yes       |
| `InternalServerError`  | `RerankServerError`         | Yes       |
| Any other exception    | `RerankServerError`         | Yes       |

### Wiring with a vector store

Reranking sits between the vector store and the LLM. The store enriches the question with its matches and emits it on the `questions` lane; this node reranks those documents and emits the reordered set on `documents`; the prompt and LLM then build their context from the reranked `documents`:

```text
… → embedding → store ──questions──▶ rerank_cohere ──documents──▶ prompt → llm → response
```

To maximise quality, **retrieve generously and rerank down**: give the reranker more candidates than the store would return on its own, then keep a small `top_n` here (for example `5`) for the final context. The store's default candidate pool on the data lane is 25, so the widening must go above that. Only the Chroma store (`store_chroma`) exposes a **Top K** field for this; set it comfortably above the default, for example `50`. A value such as `20` is below the default and narrows retrieval instead of widening it. A complete, runnable pipeline is at [`examples/rag-rerank-pipeline.pipe`](../../../../examples/rag-rerank-pipeline.pipe).

## Upstream docs

- [Cohere Rerank API reference](https://docs.cohere.com/reference/rerank)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `min_score` | `number` | **Min Score**<br/>Minimum relevance score threshold (0.0-1.0) |  |
| `model` | `string` | **Model**<br/>Cohere rerank model name | `"rerank-english-v3.0"` |
| `rerank_cohere.profile` | `string` | **Model**<br/>Rerank model | `"rerank-english-v3.0"` |
| `top_n` | `number` | **Top N**<br/>Number of top results to return |  |

## Dependencies

- `cohere` `>=6.1.0,<7.0.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/rerank_cohere)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Response

Route: /nodes/response

# response

A RocketRide infrastructure node that captures pipeline output and returns it to the requesting client as a structured JSON response.

## What it does

Acts as the terminal node in pipelines triggered via HTTP: it collects everything arriving on its input lanes and writes it into the request's JSON response body, with each lane's data stored under a configurable result key. It handles the response phase of the HTTP request-response cycle, so the client receives all pipeline results in a single standardized JSON object.

When an object finishes processing, the node also copies the object's name, path (the containing directory, with the file name stripped), and metadata (all keys except Tika-derived ones, which are filtered out) into the response. It also records a `result_types` map that ties each result key back to its original lane type.

Data handling per lane:

- **text** - chunks are accumulated (joined with blank lines) and appended as one string per object.
- **table**, **documents**, **questions** - appended as-is; documents and questions are serialized to plain dicts.
- **json** - appended as-is (one entry per write).
- **answers** - appended as parsed JSON when the answer is JSON, otherwise as plain text.
- **image**, **audio**, **video** - the three multimedia lanes are handled identically: streamed chunks are buffered via AVI_ACTION signals (BEGIN / WRITE / END), then the complete stream is base64-encoded and appended as `{"mime_type": ..., "<lane>": ...}`, where `<lane>` is the payload key (`image` / `audio` / `video`). When the stream's BEGIN carries a stream descriptor, a sanitized projection of it is added as a `metadata` object (source provenance: mime, size, dimensions/duration, codec, and any nested `source` chain; the identity/security backlink is stripped). The `metadata` key is omitted when no descriptor arrived.

The node has no Python dependencies of its own (`requirements.txt` is empty); it relies on the separately installed AI module for document, question, and answer schemas and for image processing.

---

### Service variants

The same implementation is registered as ten services. The generic **HTTP Results** service (`response://`) accepts all nine lane types and lets you map each lane to its own result key. Nine single-lane variants accept exactly one lane each and expose a single `laneName` field:

| Service title    | Protocol                  | Lane        | Default result key |
|------------------|---------------------------|-------------|--------------------|
| HTTP Results     | `response://`             | all nine    | the lane type name |
| Return Answers   | `response_answers://`     | `answers`   | `answers`          |
| Return Audio     | `response_audio://`       | `audio`     | `audio`            |
| Return Documents | `response_documents://`   | `documents` | `documents`        |
| Return Image     | `response_image://`       | `image`     | `image`            |
| Return JSON      | `response_json://`        | `json`      | `json`             |
| Return Questions | `response_questions://`   | `questions` | `questions`        |
| Return Table     | `response_table://`       | `table`     | `table`            |
| Return Text      | `response_text://`        | `text`      | `text`             |
| Return Video     | `response_video://`       | `video`     | `video`            |

All variants are `classType: infrastructure` and register as a `filter`. The generic `response://` service additionally carries the `internal` capability.

---

## Lanes

All lanes are inputs; the node produces no output lanes.

| Lane in     | Lane out | Description |
|-------------|----------|-------------|
| `text`      | -        | Captured under the configured key |
| `table`     | -        | Captured under the configured key |
| `json`      | -        | Captured under the configured key |
| `documents` | -        | Captured under the configured key |
| `questions` | -        | Captured under the configured key |
| `answers`   | -        | Captured under the configured key |
| `audio`     | -        | Captured under the configured key (base64-encoded stream + descriptor `metadata`) |
| `video`     | -        | Captured under the configured key (base64-encoded stream + descriptor `metadata`) |
| `image`     | -        | Captured under the configured key (base64-encoded stream + descriptor `metadata`) |

## Configuration

Choose the generic HTTP Results service when one response needs several lane types, and use a single-lane variant when a pipeline has one terminal output. The generated schema contains the field definitions; the guidance below covers the effect of the result-key setting.

### Lane name and result key

For HTTP Results, each `lanes` entry maps a lane identifier to a result key of one to 32 characters. Use distinct keys when a client needs to distinguish returned types without consulting `result_types`; leave a lane unmapped to use its lane type as the key. In a single-lane service, the top-level `laneName` takes precedence over the `lanes` mapping, so set it only when every arriving result should use the same key.

---

## Notes

### Response format

The JSON object returned to the client has the following structure:

```json
{
  "name": "file.pdf",
  "path": "/some/directory",
  "metadata": { "...": "..." },
  "your_key": [ "...data..." ],
  "result_types": { "your_key": "answers" }
}
```

Each configured result key holds an array: one element per result produced for the object. `result_types` maps each configured key back to its original lane type, so clients can identify the kind of data each key contains even when custom key names are used. The `name`, `path`, and `metadata` fields are only present when the processed object carries those attributes; `metadata` excludes all Tika-derived keys.

For the multimedia lanes (`image`, `audio`, `video`) each array element is a media entry with the same shape — the base64 stream under the lane key plus the stream descriptor:

```json
{
  "mime_type": "image/png",
  "image": "<base64-encoded bytes>",
  "metadata": {
    "source_mime": "image/png",
    "size": 583006,
    "width": 1280,
    "height": 720,
    "name": "clip.frame0.png",
    "source": { "source_mime": "video/mp4", "duration": 74.05, "...": "...(nested origin chain)" }
  }
}
```

The `metadata` object is the **sanitized provenance projection** of the stream descriptor parsed from the media BEGIN — the media detail (mime, size, dimensions/duration, codec) plus the nested `source` chain, which chains back through each transform hop to the original media (nested to any depth). The identity/security backlink (`objectId`, `parent`, `permissionId`, `signature`, `nodeId`) is intentionally stripped and never reaches the client. `metadata` is omitted entirely when the stream arrives without a descriptor.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Return Answers (`services.answers.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"answers"` |

### Return Audio (`services.audio.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"audio"` |

### Return Documents (`services.documents.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"documents"` |

### Return Image (`services.image.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"image"` |

### HTTP Results (`services.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneId` | `string` | **Lane name** |  |
| `laneName` | `string` | **Result key** |  |
| `lanes` | `array` | **Lanes**<br/>Each lane maps pipeline data to a custom JSON key in the response. Select the data type (text, documents, answers, etc.) for Lane Name, and enter a custom JSON key name (1-32 characters) for Result Key. |  |

### Return JSON (`services.json.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"json"` |

### Return Questions (`services.questions.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"questions"` |

### Return Table (`services.table.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"table"` |

### Return Text (`services.text.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"text"` |

### Return Video (`services.video.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `laneName` | `string` | **Identifier key within result** | `"video"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/response)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# RocketRide Graph

Route: /nodes/rocketride_graph

# rocketride_graph

A RocketRide graph database node for natural-language Cypher queries against
the Apache AGE graph in the signed-in tenant's managed database. Pick it over
rocketride_sql when relationships and traversals are the data model.

## What it does

The node accepts questions, asks its required LLM to generate read-only Cypher,
translates it to Apache AGE SQL, and returns rows as a table, text, or answer.
It also exposes graph discovery and query functions to an agent. Use it for
graph labels, relationships, and multi-hop traversal; use rocketride_sql for
relational SQL or rocketride_vector for embedding-backed document retrieval.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| llm | yes | Produces Cypher from a natural-language question. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| questions | table | Returns an executed graph-query result as a Markdown table. |
| questions | text | Returns the graph-query result as text. |
| questions | answers | Returns the graph-query result on the answers lane. |

## As a tool

The inherited graph functions are registered under the bare names below; this
node defines no configurable server-name prefix. Inputs are JSON objects.

| Function | Description |
| --- | --- |
| get_data | Converts required natural-language question to a safe read-only Cypher query and returns rows; limit is optional. |
| get_schema | Returns the discovered labels, sampled node properties, and relationships. |
| get_query | Converts required natural-language question to read-only Cypher without executing it; limit is optional. |
| execute | Runs required raw Cypher query when direct execution is enabled. |
| dialect | Returns {"dialect": "age"}. |

get_data defaults to the shared read limit, then clamps the requested limit to
the configured Max read rows ceiling. A successful result contains
{valid, rows, query, row_limit, truncated}. Generation, validation, or
execution failure returns {valid: false, error, query, rows: []}; a non-graph
question may instead carry an LLM answer with valid: false.

get_query returns {query, valid: true} only after its safe-query checks.
execute bypasses the read-only gate but still passes Cypher through the AGE
translation and resource limits; it raises if direct execution is disabled or
the input is invalid, and otherwise returns {rows, affected_rows}.

## Configuration

The single built-in profile supplies the default graph name. RocketRide
provisions a per-tenant database for its managed database nodes, and this node
resolves it from the signed-in RocketRide identity instead of a host, user,
password, or database name you enter. Start with the defaults, then tune the
graph context and read limits around the size and shape of the graph your LLM
must query.

### Graph name and graph description

Graph name defaults to rocketride and must name an existing AGE graph; startup
fails instead of creating a missing graph. Graph description is empty by
default and becomes LLM context, so describe labels, relationship meaning, and
domain vocabulary when those are not obvious from reflected schema. Change the
graph name when the tenant database contains multiple AGE graphs; update the
description with it so generated Cypher targets the right model.

### Validation attempts and read rows

The node retries failed Cypher validation up to five times by default. Raise
Max validation attempts for a complex schema where the returned validation error
is likely to let the LLM repair its query, or lower it to fail faster. Max read
rows defaults to 1,000 and is an owner-controlled cap for both the questions
lane and get_data; increase it only when agents truly need larger result sets,
since results beyond the cap are intentionally truncated.

### Query timeout

Query timeout (ms) defaults to 30,000 and is applied inside each query's
transaction. Reduce it to protect an interactive pipeline from expensive
traversals; increase it only for known queries that legitimately need more
time. It works with the row cap: one limits execution time and the other limits
returned data.

### Allow direct query execution

This setting is off by default. Turning it on permits raw Cypher through the
execute tool and QuestionType.EXECUTE; those calls skip LLM translation and the
safe read-only gate. They still use the AGE translator and its resource
controls. Enable it only for trusted callers that require writes or raw Cypher.

## Limitations

This node runs on the RocketRide engine host and does not support remote
execution. The engine host must have access to the signed-in RocketRide
identity used to resolve the tenant DSN. The tenant database must already have
Apache AGE installed and contain the configured graph. Read paths are
intentionally read-only; raw execution remains disabled until explicitly
enabled.

## Notes

### Translation and schema discovery

Apache AGE cannot execute bare Cypher. Every query path is translated, and the
safe path runs in a server-side read-only transaction with a semantic firewall,
the base Cypher safety check, and a transaction-local statement timeout.
Schema reflection is best effort: it lists AGE labels, samples node properties,
and samples relationship endpoints; an individual reflection failure warns and
returns partial rather than blocking all schema output.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `rocketridegraph.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw Cypher without LLM translation or read-only safety checks. Resource limits still apply. Leave OFF unless a trusted application explicitly needs to issue Cypher directly. | `false` |
| `rocketridegraph.db_description` | `string` | **Graph description**<br/>What is this graph used for? Describe its content and purpose, this helps the LLM generate more accurate queries. | `""` |
| `rocketridegraph.graph` | `string` | **Graph name**<br/>Name of the AGE graph to query in your RocketRide cloud database | `"rocketride"` |
| `rocketridegraph.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if validation rejects the generated Cypher | `5` |
| `rocketridegraph.max_rows` | `integer` | **Max read rows**<br/>Row ceiling for read queries on the questions lane and get_data tool | `1000` |
| `rocketridegraph.profile` | `string` |  | `"default"` |
| `rocketridegraph.query_timeout_ms` | `integer` | **Query timeout (ms)**<br/>Per-query statement timeout applied inside each query's transaction | `30000` |

## Dependencies

- `psycopg2-binary` `==2.9.12`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/rocketride_graph)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# RocketRide SQL

Route: /nodes/rocketride_sql

# rocketride_sql

A RocketRide database node for asking natural-language questions of, and writing
structured pipeline data to, the relational database provisioned for the signed-in
RocketRide tenant. Pick it instead of a connection-configured PostgreSQL node when
the data belongs in that managed tenant database.

## What it does

On the questions lane, the node asks its connected LLM to produce a SQL query,
validates a safe query with EXPLAIN, and returns the result as a table, text, or
answer. On the answers lane, it inserts structured rows into the configured
table. Use it for relational queries and writes against the tenant database;
rocketride_vector is the sibling for document embeddings and rocketride_graph is
the sibling for Cypher graph queries.

## Connections

| Connection | Required | Description |
| --- | --- | --- |
| llm | yes | Produces SQL from a natural-language question. |

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| answers | — | Inserts structured pipeline rows into the configured table. |
| questions | table | Returns an executed query result as a Markdown table. |
| questions | text | Returns the query result as text. |
| questions | answers | Returns the query result on the answers lane. |

## As a tool

The inherited database functions are registered under the bare names below; this
node defines no configurable server-name prefix. Input must be a JSON object
unless a function explicitly permits an empty object.

| Function | Description |
| --- | --- |
| get_data | Converts a required natural-language question into safe SQL, executes it, and returns rows. |
| get_schema | Returns reflected tables, columns, primary keys, and foreign keys; table is optional. |
| get_sql | Converts a required question into SQL without executing it. |
| execute | Runs required raw SQL, with optional positional params and a transaction session_id. |
| begin | Opens a raw-SQL transaction and returns its session_id. |
| commit | Commits the required session_id. |
| rollback | Rolls back the required session_id. |
| dialect | Returns {"dialect": "postgres"}. |

get_data returns {valid, rows, sql, row_limit} for a successful query. A
generation or execution problem returns valid: false with error, SQL, or an LLM
answer as applicable. It defaults to 250 rows; a supplied limit is clamped to
the shared maximum. get_schema reports an unknown requested table as an error
value rather than throwing.

get_sql returns {sql, valid: true} only for safe generated SQL; unsafe SQL
returns {error, sql, valid: false}. execute, begin, commit, and rollback raise
for invalid input, an unknown or expired transaction, or when direct execution
is disabled. A successful raw execution returns {rows, affected_rows}; begin
returns {session_id} and transaction completion returns {ok: true}.

## Configuration

There is one built-in profile and no connection panel. RocketRide provisions a
per-tenant database for its managed database nodes, and this node resolves it
from the signed-in RocketRide identity instead of a host, user, password, or
database name you enter. Configure the table and the context supplied to the
LLM; leave direct execution disabled unless a trusted caller needs it.

### Table name and database description

Table name defaults to table and is the target used for structured answers-lane
inserts. Database description is empty by default and is included as context
when the node asks the LLM to write SQL. Change it when the database or table
has domain-specific meanings that a column name alone cannot convey; a concise
description helps the LLM choose relevant tables and predicates without
changing the actual schema.

### Max validation attempts

The node defaults to five LLM attempts when EXPLAIN rejects generated SQL.
Raise it when a complex, well-described schema produces repairable SQL errors;
lower it when fast failure matters more than another LLM round trip. It affects
only the natural-language path, not raw execute calls.

### Allow direct query execution

This setting is off by default. When enabled, QuestionType.EXECUTE on the
questions lane and the execute, begin, commit, and rollback tools can run raw
SQL without LLM translation or SQL safety checks. Enable it only for a trusted
application that needs write statements or explicit transactions; otherwise
keep it off so those entry points fail rather than executing input.

## Limitations

This node is marked noremote and depends on a signed-in RocketRide identity to
resolve the per-tenant DSN. It cannot start where that cloud identity is not
available; DSN resolution is deliberately not replaced by host or credential
fields. LLM-generated queries are limited to the safe SQL path, while raw SQL
is unavailable until direct execution is explicitly enabled.

## Notes

### Query paths

The node inherits PostgreSQL schema reflection and its structured query surface.
For QuestionType.DIALECT, the questions lane emits the PostgreSQL dialect on
answers. For QuestionType.EXECUTE, a disabled direct-execution setting logs and
drops the request; successful raw SELECT results are bounded by the shared
execution-row maximum, while writes report affected_rows.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `rocketridesql.allow_execute` | `boolean` | **Allow direct query execution**<br/>Permit QuestionType.EXECUTE callers to run raw SQL without LLM translation or safety checks. Leave OFF unless a trusted application explicitly needs to issue SQL directly. | `false` |
| `rocketridesql.db_description` | `string` | **Database description**<br/>What is this database used for? Describe its content and purpose, this helps the LLM generate more accurate queries. | `""` |
| `rocketridesql.max_attempts` | `integer` | **Max validation attempts**<br/>Maximum number of times to re-ask the LLM if EXPLAIN rejects the generated SQL | `5` |
| `rocketridesql.profile` | `string` |  | `"default"` |
| `rocketridesql.table` | `string` | **Table name**<br/>Name of the table to read from or write to in your RocketRide cloud database | `"table"` |

## Dependencies

- `psycopg2-binary` `==2.9.12`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/rocketride_sql)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# RocketRide Vector

Route: /nodes/rocketride_vector

# rocketride_vector

A RocketRide vector store node that stores embedded document chunks and retrieves
them by keyword or semantic similarity from the managed tenant database. Pick it
over the SQL and graph nodes for retrieval-augmented document search.

## What it does

The node writes documents from the documents lane into a pgvector-backed table,
replacing existing chunks for the same object IDs. Questions can produce
matching documents, answers, or enriched questions through the three configured
question outputs. Use it when retrieval should flow through a pipeline; unlike
the tool-capable sibling stores, this node registers no agent tools or raw-SQL
execution surface.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| documents | — | Stores document chunks in the configured vector table. |
| questions | documents | Returns matching documents. |
| questions | answers | Returns matching documents as answers. |
| questions | questions | Enriches a question with matching documents. |

## Configuration

The single cloud profile provides a table, cosine similarity, a score threshold,
and HNSW index defaults. RocketRide provisions a per-tenant database for its
managed database nodes, and this node resolves it from the signed-in RocketRide
identity instead of a host, user, password, or database name you enter. Bind an
embedding module for semantic search; the embedding dimension is taken from the
first stored document rather than from a configuration field.

### Table

Table defaults to rocketride and is the PostgreSQL table that holds the chunks
and embeddings. Choose a distinct table when separate corpora need separate
retrieval indexes or retention behavior. The node accepts only an unquoted
PostgreSQL identifier: it must start with a letter or underscore, use only
letters, digits, and underscores, and be at most 63 characters. Invalid names
are rejected during configuration validation and at startup.

### Score threshold and similarity metric

Score threshold defaults to 0.5; it is the minimum returned similarity score.
Raise it when loose matches are polluting downstream context, and lower it when
relevant documents are being excluded. Scores are calculated from the
configured metric: cosine uses 1 - distance, L2 uses 1 / (1 + distance), and
inner product negates the returned distance. Regardless of this setting, the
store drops results below its fixed 0.20 minimum similarity floor.

Similarity Metric defaults to cosine; l2 and inner_product are also accepted.
Select the metric that matches the embeddings and expected notion of closeness
before the table is first written, because it chooses the HNSW operator class
used for the index. An unsupported value prevents startup.

### HNSW m and ef_construction

The table's HNSW index is created on first write. HNSW m defaults to 16 and
controls the graph degree; HNSW ef_construction defaults to 64 and controls the
candidate list used while building it. Higher values can improve search quality
at the cost of a more expensive, larger index. Values are clamped to pgvector's
supported ranges (m 2–100 and ef_construction 4–1,000), and ef_construction is
raised to at least twice m. These values do not rebuild an index that already
exists.

## Notes

### Storage and retrieval behavior

The node creates the table on the first write and creates a metric-compatible
HNSW index then. pgvector cannot create that index for embeddings wider than
2,000 dimensions, so the node warns and searches without the index in that
case. Keyword search uses a content LIKE match; semantic search needs an
embedding bound to the question and raises if none is available. Missing tables
produce empty search results rather than an error.

Deleted objects are excluded by default, while document rendering reassembles
stored chunks by chunkId. The store removes all existing chunks for incoming
object IDs before inserting the replacement chunks, preventing duplicate data
for a re-ingested object.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `rrvector.collection` | `string` | **Table**<br/>Name of the table to store vectors in your RocketRide cloud database. | `"rocketride"` |
| `rrvector.hnsw_ef_construction` | `integer` | **HNSW ef_construction**<br/>HNSW build-time candidate list size used when the index is first created. | `64` |
| `rrvector.hnsw_m` | `integer` | **HNSW m**<br/>HNSW graph degree (max connections per layer) used when the index is first created. | `16` |
| `rrvector.profile` | `string` | **RocketRide cloud database**<br/>Connect to... | `"cloud"` |
| `rrvector.provider` | `string` |  | const: `"rocketride_vector"` |
| `rrvector.score` | `number` | **Score threshold**<br/>Minimum similarity score for a document to be returned by search. | `0.5` |
| `rrvector.similarity` | `string` | **Similarity Metric**<br/>The similarity metric to use for vector search. Also selects the HNSW index operator class. | `"cosine"` |

## Dependencies

- `psycopg2-binary`
- `pgvector`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/rocketride_vector)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Scan Cropper

Route: /nodes/scan_cropper

# scan_cropper

A RocketRide filter node that splits a scan holding several photos into one image per photo.

## What it does

Feed it a scanned photo-album page, or a handful of prints laid on the platen together, and it
emits each photograph as its own image downstream — straightened, cropped to its own edges, and
named in the order you would read the page.

It works out what the background is from the scan itself, so there is no white / dark / album
mode to pick. A pixel counts as background only when all three of these hold: it is *plain*
(no local texture), it is painted in one of the scan's *dominant* colours, and it belongs to a
region that *reaches the edge of the scan*. Each condition covers a gap the others leave —
texture alone keeps the scanner lid, colour alone eats dark clothing that happens to match a
dark page, and reachability alone eats a photo that touches the edge of the platen.

Photos mounted edge to edge never come apart by eroding them, so a region is additionally cut
along any straight border that spans it, recursively. Whether such a cut is believed is
arbitrated by standard print ratios — as a veto, never as a requirement, so a panorama or a
trimmed print is still accepted as the non-standard shape it is.

Detection runs on a downscaled copy and the rectangles are scaled back up, which is what makes
a 143 MP flatbed scan tractable at all. The crops themselves are always taken at full
resolution.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `image` | One JPEG per photo found, in page reading order |
| `image` | `text` | JSON detection record — what was found, where, and what it was called |

A scan that yields no photos is **forwarded unchanged** rather than dropped, so nothing
silently disappears from a pipeline.

## Profiles

Default: **Album page - photos mounted together** (`album`).

| Profile | Sets | Because |
| --- | --- | --- |
| `album` **(default)** | `maxDepth 4`, `texture 4.0`, `minRelative 0.40` | Mounted photos often touch, so separating them is worth the cost |
| `loose` | `maxDepth 0`, `minRelative 0.20` | Separately laid prints never touch — the search for joins is pure waste — and their sizes vary more |
| `textured` | `texture 9.0` | Stops page grain being read as photo content |
| `detail` | `detectSize 4500`, `maxDepth 6` | Tighter edges, more separation attempts |

## Configuration

Start and usually finish with **Scan type** — see `## Profiles` above for what each one sets
and why. There is deliberately no white / dark / album background setting: the node infers the
background from the scan, so the presets describe what you *scanned* instead, and change the
things that genuinely differ between those cases.

A scan type shows only **Straighten photos** and **JPEG quality**; everything else it decides
for you. To go further, each one carries its own **Show advanced settings** switch, which opens
the ten tunables filled in with *that* scan type's numbers — open it under *Textured page* and
`texture` reads 9.0, open it under *Album page* and it reads 4.0. So you start from the preset
nearest your scans and adjust one thing, rather than setting ten values from scratch.

There is deliberately no separate "Advanced" scan type. A scan type is what decides the values,
so an Advanced entry would have nothing to show you but a fixed set of numbers unrelated to the
preset you had selected a moment earlier.

Writing the config by hand rather than through the form, the settings go **inside an object
named after the Scan type**, not beside it:

```json
{ "profile": "textured", "textured": { "quality": "auto", "deskew": true } }
```

`Config.getNodeConfig` reads the user's settings from `connConfig[profile]` and ignores every
top-level key, so a setting written beside `profile` is silently dropped.

### Every setting

Most are only visible behind **Show advanced settings**, and only worth touching if the symptom
table below points at one.

| Setting | Default | What it does |
| --- | --- | --- |
| **Scan type** | Album page | Picks the numbers below to suit what you scanned |
| **Straighten photos** | Yes | Rotates each photo upright as it is cut. Off keeps the original pixels, tilt and all |
| **JPEG quality** | `auto` | `auto` matches the quality your scanner saved at. A number 1-100 overrides it |
| **File size vs quality (dB)** | 0.5 | Only used when quality is `auto`. How much final quality to trade for smaller files. On a 33-page album: 657 MB at 0.2, 463 MB at 0.5, 330 MB at 1.0 |
| **Detection size (px)** | 3000 | Long edge the search runs on. Crops are always cut at full resolution, so this trades speed against how precisely edges are found. Quadratic cost |
| **Page smoothness** | 4.0 | How smooth an area must be to count as empty page. Raise for grainy or fabric pages; lower if a photo with large flat areas is cut short |
| **Smallest photo to keep** | 0.005 | Ignore anything below this share of the scan — half a percent of the page |
| **Largest photo to keep** | 0.95 | Ignore anything above this share. Kept under 1.0 so a failed detection returns nothing rather than the whole page as one "photo" |
| **Longest allowed shape** | 5.0 | How stretched a rectangle may be before it is rejected as not a photo, long side over short. 5.0 comfortably allows panoramas |
| **Discard small leftovers** | 0.4 | Drop finds much smaller than the biggest photo, assuming they are torn pieces. Set 0 to keep everything |
| **Separate touching photos** | 4 | How many times one shape may be cut apart. 0 disables the search entirely and is the biggest speed win when photos never touch |
| **Tilt allowance when separating** | 1.5 | How crooked a join between two photos may be and still be found. Not a speed setting |
| **Print shape tolerance (%)** | 8.0 | How far the two halves of a proposed cut may sit from a standard print shape. Only arbitrates cuts; never rejects a photo on its own |

### If something looks wrong

| Symptom | Try |
| --- | --- |
| The page itself comes out as photos | Raise **Page smoothness** (`texture`), or use the *Textured page* preset |
| A photo with a big plain area (sky, studio backdrop) is cut short or missed | Lower **Page smoothness** |
| Several touching photos come out as one image | Raise **Separate touching photos** (`maxDepth`); raise **Print shape tolerance** |
| One photo is cut in half | Lower **Print shape tolerance** (`ratioTolerance`) |
| Small photos are missed | Lower **Smallest photo to keep**, or lower **Discard small leftovers** to 0 |
| Dust and specks come out as crops | Raise **Smallest photo to keep** |
| Crop edges sit slightly inside or outside the photo | Raise **Detection size** |

### Speed

Two fields are real levers and one only looks like one:

- **`maxDepth: 0`** switches off the search for joins between touching photos. It is the
  dominant cost and the right setting whenever photos never touch — that is what the
  *Loose prints* preset does.
- **`detectSize`** is quadratic — 3000 → 2000 is roughly a 2.25× saving on every pass.
- **`skew`** is *not* a performance setting. Lowering it narrows the angular search without
  buying back any time, because the number of angles tried never drops below five.

## Notes

### Output names

Crops are named `<scan>.crop<N>.jpg`, numbered in reading order: top row left to right, then
the next row down. The numbering is dense — a photo that was detected but could not be cropped
leaves no gap in the filenames, because a gap reads as lost data. Use the `cropped` flag in the
text record to find those instead.

The counter runs per *object*, not per stream, so a source that hands the node several images
in one object (a multi-page document, or an upstream fan-out) still gets unique names.

### The detection record

The `text` lane carries one JSON document per scan:

```json
{
  "decoded": true,
  "count": 3,
  "regions": [
    {
      "cx": 337.0, "cy": 428.0, "w": 398.0, "h": 520.0, "angle": 0.0,
      "area_pct": 10.78, "ratio_error": 2.0, "cropped": true, "name": "1.crop0.jpg"
    }
  ]
}
```

`decoded` is what separates *"this is not an image I can read"* from *"I read it and found
nothing"* — both otherwise report zero regions, and telling them apart is the difference
between an auditable run over a folder of scans and a pile of silent zeros. `ratio_error` is
how far the photo sits from the nearest standard print size, in percent; it is reported for
diagnosis and never used to reject a photo.

### Limitations

- **Memory.** Decoding a 143 MP scan costs roughly 430 MB, plus about 105 MB per crop while it
  is being encoded. Like every other buffering node here, this one has no input size cap.
- **Metadata is not carried over.** Crops are re-encoded with OpenCV, which writes no EXIF and
  no ICC profile — any capture metadata, colour profile or orientation tag on the source scan
  is dropped. The crops are new images, not edited originals.
- **Edge accuracy** is bounded by `detectSize`: at the default, one pixel of detection error is
  about five pixels on a 14000 px-tall scan.

### Provenance

The detection algorithm, the seam search and the JPEG quality matching were developed by the
author in personal forks of two open-source scan croppers, and are contributed here by their
author under this repository's MIT licence:

- [`autocrop`](https://github.com/z80z80z80/autocrop) — the texture-based detector, the seam
  search, `snap_to_border`, the exact-corner crop, and the quality tables (commits `faf2942`,
  `e64b754`, `0717a1f`).
- [`ScanCropper`](https://github.com/murniox/ScanCropper) — standard print-ratio arbitration,
  the duplicate-region test, and the deskew angle floor (commit `120c81b`).

Nothing authored by those projects' other contributors was carried over.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `scan_cropper.album.tune` | `boolean` | **Show advanced settings**<br/>Reveals every value this scan type uses, filled in with its own numbers, so you can start from it and adjust one thing rather than setting all ten from scratch. | `false` |
| `scan_cropper.deskew` | `boolean` | **Straighten photos**<br/>Rotates each photo upright as it is cut, so a slightly crooked scan comes out square. Turn this off only if you would rather keep the original pixels untouched - the photo then keeps its tilt and has page-coloured wedges in the corners. | `true` |
| `scan_cropper.detail.detectSize` | `integer` | **Detection size (px)**<br/>How big a copy of the scan the search for photos runs on. Your crops are always cut from the full-resolution original, so this only trades speed against how precisely photo edges are located. It is the main speed control and the cost is quadratic: 3000 to 2000 is about 2.25x faster. Raise it if crop edges land slightly inside or outside the photo. | `4500` |
| `scan_cropper.detail.maxDepth` | `integer` | **Separate touching photos**<br/>Photos mounted edge to edge look like one shape and have to be cut apart; this is how many times a shape may be cut. Set to 0 when your photos never touch - it switches off the most expensive part of the search and is by far the biggest speed win. Raise it if a row of several touching photos comes out as one image. | `6` |
| `scan_cropper.detail.tune` | `boolean` | **Show advanced settings**<br/>Reveals every value this scan type uses, filled in with its own numbers, so you can start from it and adjust one thing rather than setting all ten from scratch. | `false` |
| `scan_cropper.detectSize` | `integer` | **Detection size (px)**<br/>How big a copy of the scan the search for photos runs on. Your crops are always cut from the full-resolution original, so this only trades speed against how precisely photo edges are located. It is the main speed control and the cost is quadratic: 3000 to 2000 is about 2.25x faster. Raise it if crop edges land slightly inside or outside the photo. | `3000` |
| `scan_cropper.loose.maxDepth` | `integer` | **Separate touching photos**<br/>Photos mounted edge to edge look like one shape and have to be cut apart; this is how many times a shape may be cut. Set to 0 when your photos never touch - it switches off the most expensive part of the search and is by far the biggest speed win. Raise it if a row of several touching photos comes out as one image. | `0` |
| `scan_cropper.loose.minRelative` | `number` | **Discard small leftovers**<br/>Throws away finds much smaller than the biggest photo on the page, on the assumption they are torn-off pieces of one photo rather than photos in their own right. 0.4 means 'drop anything under 40% of the largest'. Lower it, or set 0 to keep everything, when one page genuinely holds photos of very different sizes. | `0.2` |
| `scan_cropper.loose.tune` | `boolean` | **Show advanced settings**<br/>Reveals every value this scan type uses, filled in with its own numbers, so you can start from it and adjust one thing rather than setting all ten from scratch. | `false` |
| `scan_cropper.maxArea` | `number` | **Largest photo to keep**<br/>Ignore anything larger than this share of the whole scan. Kept below 1.0 so that failing to find the photos returns nothing rather than handing you the entire page as one giant 'photo'. You rarely need to change this. | `0.95` |
| `scan_cropper.maxAspect` | `number` | **Longest allowed shape**<br/>How stretched a rectangle may be before it is rejected as not a photo, measured as long side divided by short side. 5.0 comfortably allows panoramas. Lower it if strips of page edge or scanner lid are being picked up as photos. | `5` |
| `scan_cropper.maxDepth` | `integer` | **Separate touching photos**<br/>Photos mounted edge to edge look like one shape and have to be cut apart; this is how many times a shape may be cut. Set to 0 when your photos never touch - it switches off the most expensive part of the search and is by far the biggest speed win. Raise it if a row of several touching photos comes out as one image. | `4` |
| `scan_cropper.minArea` | `number` | **Smallest photo to keep**<br/>Ignore anything smaller than this share of the whole scan. 0.005 means half a percent of the page. Lower it if small photos or stamps are being missed; raise it if specks and dust are coming out as tiny crops. | `0.005` |
| `scan_cropper.minRelative` | `number` | **Discard small leftovers**<br/>Throws away finds much smaller than the biggest photo on the page, on the assumption they are torn-off pieces of one photo rather than photos in their own right. 0.4 means 'drop anything under 40% of the largest'. Lower it, or set 0 to keep everything, when one page genuinely holds photos of very different sizes. | `0.4` |
| `scan_cropper.profile` | `string` | **Scan type**<br/>Pick what you actually scanned and nothing else needs setting. There is no white/dark/album background choice because the node works the background out from the scan itself - what these change is whether photos touch each other, how similar their sizes are, and how grainy the page is. Every scan type carries a 'Show advanced settings' switch that opens up its own values for tweaking. | `"album"` |
| `scan_cropper.quality` | `string` | **JPEG quality**<br/>Type 'auto' to match the quality your scanner saved at, or a number from 1 to 100. Leave it on 'auto': saving above the original cannot recover detail the scanner already threw away, it only makes files bigger - a quality-75 scan re-saved at 100 is roughly four times the size and looks the same. | `"auto"` |
| `scan_cropper.qualityTolerance` | `number` | **File size vs quality (dB)**<br/>Only used when JPEG quality is 'auto'. How much final quality to give up in exchange for smaller files. 0.2 keeps files large and near-perfect, 1.0 makes them roughly half the size with a difference you would struggle to see. Measured on a 33-page album: 657 MB at 0.2, 463 MB at 0.5, 330 MB at 1.0. | `0.5` |
| `scan_cropper.ratioTolerance` | `number` | **Print shape tolerance (%)**<br/>Used only when deciding whether a shape is two touching photos or one whole photo: how far the pieces may sit from a standard print shape (6x4, 5x7, square and so on). It never rejects a photo on its own, so an unusual shape is still kept. Raise it if photos that should be split are staying joined; lower it if one photo is being cut in half. | `8` |
| `scan_cropper.skew` | `number` | **Tilt allowance when separating (degrees)**<br/>How crooked the join between two touching photos may be and still be found. NOT a speed setting - lowering it narrows the search without saving any time, because the number of angles tried does not drop below five. Raise it only if touching photos on a visibly crooked scan are not being separated. | `1.5` |
| `scan_cropper.texture` | `number` | **Page smoothness**<br/>How smooth an area has to be before it counts as empty page rather than part of a photo. RAISE this if the page itself is being detected as photos (grainy, patterned or fabric-covered pages). LOWER it if a photo with large flat areas - a plain sky, a studio backdrop - is being cut short or missed. | `4` |
| `scan_cropper.textured.texture` | `number` | **Page smoothness**<br/>How smooth an area has to be before it counts as empty page rather than part of a photo. RAISE this if the page itself is being detected as photos (grainy, patterned or fabric-covered pages). LOWER it if a photo with large flat areas - a plain sky, a studio backdrop - is being cut short or missed. | `9` |
| `scan_cropper.textured.tune` | `boolean` | **Show advanced settings**<br/>Reveals every value this scan type uses, filled in with its own numbers, so you can start from it and adjust one thing rather than setting all ten from scratch. | `false` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/scan_cropper)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Schema Validate

Route: /nodes/schema_validate

# schema_validate

A RocketRide guard node that flags inconsistencies in structured financial facts —
most notably a **cost row stored as revenue** — and makes sure **provenance is never
dropped**. It is the validation step of the audit-grade financial extraction node suite.

## What it does

Reads structured facts on the `answers` lane and, for every fact, runs a set of
deterministic audit checks. The node is a **guard**: it *flags*, it never fixes,
drops, or reorders records, and it never calls an LLM or the network.

For every fact it inspects, the node:

- adds a `validation` block (`valid`, `severity`, `flags`);
- appends a `provenance` entry recording that the fact was checked and which flags
  fired — so the audit chain is always present on the fact it leaves behind.

Records that are not fact objects (plain text, bare numbers), and non-dict elements
inside a list payload, are **passed through unchanged** — the node never drops a
record.

### Fact-record convention

A "fact" is a JSON object. The relevant fields are configurable:

- `amount_field` (default `amount`) — the numeric amount;
- `currency_field` (default `currency`) — the currency code;
- `metric_field` (default `metric`) — the line-item label (e.g. `"Cost of goods sold"`);
- `category_field` (default `category`) — the declared classification (e.g. `"revenue"`).

An answer payload may be a single fact object or a list of fact objects; other shapes
pass through untouched.

### Checks

| Flag code | Severity | Fires when |
|---|---|---|
| `missing_amount` | warning | `amount_field` is absent or `null`. |
| `non_numeric_amount` | warning | `amount_field` is present but not a finite number (bools and comma/currency-formatted strings are rejected). |
| `missing_currency` | warning | `currency_field` is absent, `null`, or blank. |
| `category_metric_mismatch` | **error** | The metric label implies one category but the fact declares another — the headline "cost row stored as revenue" guard. |
| `ambiguous_metric` | warning | The metric label matches keywords from two or more categories, so the declared category can't be corroborated (suppresses the mismatch check). |
| `sign_category_mismatch` | configurable (`sign`, default warning) | The amount's sign contradicts its class (an expense/liability with a positive amount, or revenue/asset with a negative amount). Zero never fires. Applies only to the four built-in signed classes (revenue/expense/asset/liability); a custom category has no sign convention and is not sign-checked. |
| `unknown_category` | warning | `category_field` is present but is not a recognized classification. |
| `missing_provenance` | configurable (`require_provenance`, default error) | The **incoming** fact has no usable `provenance` list — the value is absent, `null`, an **empty list** `[]`, or not a list at all. |
| `malformed_provenance` | warning | `provenance` is present but is not a list (the original value is preserved, never discarded). |

`valid` is `true` when no `error`-severity flag fired (warnings do not invalidate).
`severity` is the highest severity across the flags (`error` > `warning` > `ok`).

The metric classifier is **keyword-based**: it case-insensitively substring-matches the metric label
against `category_metric_map`. It is intentionally conservative — a label that matches keywords from
two or more categories resolves to `ambiguous` (and suppresses the mismatch check) rather than
guessing, and a label matching none is simply not classified. Because it is heuristic, tune
`category_metric_map` to your corpus: e.g. a label containing `"tax"` (expense) and `"income"`
(revenue) is treated as ambiguous, and `"deferred tax asset"` matches the `"tax"` keyword. Declared
categories are recognized from the built-in aliases **plus** the keys of `category_metric_map`, so a
custom category (e.g. `equity`) added to the map is accepted rather than flagged `unknown_category`.

### Example

Input — a cost row wrongly declared as revenue, positive amount, no provenance:

```json
{ "metric": "Cost of goods sold", "category": "revenue", "amount": 500, "currency": "USD" }
```

Output (defaults `sign="warning"`, `require_provenance="error"`):

```json
{
  "metric": "Cost of goods sold",
  "category": "revenue",
  "amount": 500,
  "currency": "USD",
  "validation": {
    "op": "schema_validate",
    "valid": false,
    "severity": "error",
    "flags": [
      { "code": "category_metric_mismatch", "severity": "error", "field": "category",
        "message": "metric 'Cost of goods sold' implies category 'expense' but fact declares 'revenue'" },
      { "code": "missing_provenance", "severity": "error", "field": "provenance",
        "message": "fact has no usable provenance list; upstream extraction chain is not recorded" }
    ]
  },
  "provenance": [
    { "op": "schema_validate", "valid": false,
      "flag_codes": ["category_metric_mismatch", "missing_provenance"] }
  ]
}
```

The sign check does **not** fire here: it resolves the class from the *declared*
category when that is a signed class, and a declared `revenue` with a positive
amount is self-consistent — the mismatch flag already captures the inconsistency.
`sign_category_mismatch` fires when the sign contradicts the resolved class, e.g.
a fact declared `expense` (or with an expense metric and no declared category)
carrying a positive amount.

A clean fact receives `validation: { "op": "schema_validate", "valid": true, "severity": "ok", "flags": [] }`
and a provenance entry with `"flag_codes": []` — proof it was checked.

### Provenance handling

The node always appends its own `{ "op": "schema_validate", ... }` entry, never
rewriting existing entries and preserving order:

- if `provenance` is a non-empty list → the entry is appended to a copy of it;
- if `provenance` is absent/`null` → a new `[entry]` list is created (and
  `missing_provenance` fires);
- if `provenance` is an **empty list** `[]` → the entry is appended (result
  `[entry]`), and `missing_provenance` fires — an empty chain is treated as no
  usable provenance;
- if `provenance` is present but not a list → the original value is preserved in
  place as `[original, entry]` (and `malformed_provenance` fires).

`missing_provenance` is evaluated against the **incoming** fact, before this node
appends its own entry, so the guard can actually fire.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `answers` | `answers` | Annotates fact dictionaries and re-emits every record. Non-fact payloads retain their content; JSON-lane scalar values are re-emitted as text (`expectJson=False`). |

## Configuration

The default profile expects conventional financial field names and applies all
checks. Change the field names only when upstream facts use a different schema;
otherwise the defaults keep the validator and its provenance records consistent.

### Fact field names

`amount_field`, `currency_field`, `metric_field`, and `category_field` select
the keys read from each fact. The defaults are `amount`, `currency`, `metric`,
and `category`. Change all relevant names to match an upstream extraction
schema; changing only one can turn valid facts into missing-field warnings.
Blank or whitespace-only configured names fall back to their defaults.

### Category → metric keywords

`category_metric_map` maps a canonical category to a list of metric-label
substrings. Its default map recognizes revenue, expense, asset, and liability.
Extend it for corpus-specific labels, or use an empty object to skip the
metric/category mismatch check. A keyword that appears in more than one
category makes the metric ambiguous and suppresses that mismatch check, so use
distinct, deliberate keywords. A malformed map logs a warning and retains the
built-in default.

### Sign and provenance severity

`sign` and `require_provenance` accept `off`, `warning`, or `error`; their
defaults are `warning` and `error`. Set either to `off` when that check is not
meaningful for an input source, use `warning` for review queues, and use
`error` when the check must make the record invalid. Missing or `null` values
retain their defaults without a warning; any other invalid non-null value logs
a warning and falls back to the default. A pre-existing `validation` field is
replaced when the fact is re-validated.

## Notes

### Pipeline position

```text
datalab_parse → extract_facts → normalize_facts → currency_convert_explicit → schema_validate → authoritative_overlay → reconcile
```

Several of these sibling nodes (`datalab_parse`, `extract_facts`, `authoritative_overlay`,
`reconcile`, `currency_convert_explicit`) are part of the in-progress audit-grade financial
extraction suite (epic #1432) and are not all on `develop` yet; `schema_validate` stands alone and
runs on any upstream that emits fact objects on the `answers` lane.

This node is marked **experimental**.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `schema_validate.amount_field` | `string` | **Amount field**<br/>The fact field holding the numeric amount (presence and sign checks). | `"amount"` |
| `schema_validate.category_field` | `string` | **Category field**<br/>The fact field holding the declared classification (e.g. revenue, expense) — checked against the metric. | `"category"` |
| `schema_validate.category_metric_map` | `object` | **Category → metric keywords**<br/>Map of canonical category to metric keyword substrings that imply it. Drives the cost-as-revenue check. Leave empty to skip the metric/category mismatch check. |  |
| `schema_validate.currency_field` | `string` | **Currency field**<br/>The fact field holding the currency code (presence check only). | `"currency"` |
| `schema_validate.metric_field` | `string` | **Metric field**<br/>The fact field naming the line item (e.g. 'Cost of goods sold') — the classifier input for the mismatch check. | `"metric"` |
| `schema_validate.profile` | `string` | **Validation**<br/>Schema validation configuration | `"default"` |
| `schema_validate.require_provenance` | `string` | **Require provenance**<br/>Severity for a fact that arrives with no usable provenance list (absent, empty, or not a list). Set to 'off' to disable the flag; a provenance entry is still appended. | `"error"` |
| `schema_validate.sign` | `string` | **Sign check severity**<br/>Severity for a sign-convention violation (e.g. an expense with a positive amount). Set to 'off' to disable the check. | `"warning"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/schema_validate)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Exa Search

Route: /nodes/search_exa

# search_exa

A RocketRide search node that submits a user question to the Exa web search API and returns the raw results as pipeline output.

## About Exa

Exa provides the search API called by this node. The node posts a query and the configured search options to Exa, then returns the response body as formatted JSON after applying its local URL-safety checks.

## What it does

Takes a question from the `questions` lane, sends it as a single query to the Exa REST endpoint (`https://api.exa.ai/search`), and writes the pretty-printed Exa JSON response to the `answers` and `text` lanes.

Uses the **requests** library directly against the Exa REST API; no Exa SDK is required. Each HTTP request has a 30-second timeout. The node expects exactly one question per invocation: an empty question or a multi-question payload raises an error immediately.

Result URLs are sanitized before leaving the node, guarding downstream nodes against SSRF via attacker-influenced search content; see **URL safety** under Notes for what is checked and dropped.

---

## Lanes

| Lane in     | Lane out  | Description                                                    |
|-------------|-----------|----------------------------------------------------------------|
| `questions` | `answers` | Search results as answers (pretty-printed Exa JSON)            |
| `questions` | `text`    | Search results as plain text                                   |

## Configuration

The single default profile starts with automatic search, five results, and highlights enabled. Supply credentials, then tune the search options only when the result style or response size needs to change.

### Search Type

Choose `auto` for the default request behavior. Select `keyword` or `neural` when the query should explicitly use that Exa search type. The selected value is passed as the API request's `type`; it does not change how RocketRide interprets the returned payload.

### Results and highlights

`numResults` controls how many results the request asks for and accepts values from 1 through 20. Keep the default 5 for a compact response; increase it when later stages need a broader result set, bearing in mind that the entire raw response is sent to both output lanes.

When highlights are enabled, the node sends a `contents.highlights` request with the configured maximum character count. The default is 600 characters; the allowed range is 100 through 4,000. Turn highlights off when result metadata is sufficient, or reduce their size when downstream context is more valuable than excerpts.

---

## Authentication

The API key is resolved in the following order:

1. `apikey` in the node config
2. `apikey` in the connection config
3. The `ROCKETRIDE_EXA_KEY` environment variable

If none of these sources provides a non-empty value, the pipeline fails at startup with `search_exa: apikey is required`. The editor also surfaces a validation warning while you are configuring the node.

---

## Notes

### Request failures

Exa HTTP errors are mapped to descriptive failures:

- **401**: `Exa authentication failed` -- bad or missing API key
- **429**: `Exa rate limit exceeded`
- Other 4xx/5xx: `Exa request failed (<status>)` with the upstream message body
- Network timeout: `search_exa: Exa request timed out`
- Connection failure: `search_exa: Unable to reach Exa`

### URL safety

Before serializing results, the node validates every `url`, `image`, and `favicon` field. Each must use `http` or `https` and resolve to a public IP address. A result whose primary `url` resolves to a private, loopback, link-local, reserved, multicast, or unspecified address is dropped entirely; invalid `image` and `favicon` fields are removed while their result is retained. This sanitization is skipped when `ROCKETRIDE_MOCK` is set. That bypass is intended only for controlled tests and must never be enabled in production.

## Upstream docs

- [Exa documentation](https://docs.exa.ai/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `search_exa.apikey` | `string` | **API Key**<br/>Exa API key | `""` |
| `search_exa.highlightChars` | `integer` | **Highlight Chars** | `600` |
| `search_exa.includeHighlights` | `boolean` | **Include Highlights** | `true` |
| `search_exa.numResults` | `integer` | **Results** | `5` |
| `search_exa.profile` | `string` | **Profile** | `"default"` |
| `search_exa.type` | `string` | **Search Type** | `"auto"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/search_exa)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Hybrid Rerank

Route: /nodes/search_hybrid

# search_hybrid

A RocketRide filter node that re-orders the documents already attached to a question, fusing each document's upstream vector score with a BM25 keyword score. Pick it when a retrieval step returns roughly the right candidates but ranks them badly.

## What it does

The node reads a question that already carries retrieved documents, scores those same documents with BM25 against the question text, and merges the BM25 ranking with the incoming vector ranking using Reciprocal Rank Fusion (RRF). It emits the re-ordered documents, and can also emit them as a composed answer. Place it downstream of a vector-store search or another node that attaches documents to questions.

It is a re-ranker, not a retriever: no embedding or index lookup happens here, and the incoming document `score` is reused as the vector signal. A keyword-relevant document the upstream search did not return can therefore never be surfaced — for that, put a store that does dense and sparse retrieval in one query upstream instead. The node is marked experimental.

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `questions` | `documents` | Documents re-ordered by the fused vector + BM25 ranking. |
| `questions` | `answers` | The top-ranked documents composed into a single answer, each entry showing its rank, its score and the first 500 characters of its content. |

The query is the text of the question's **first** question entry. A question with no query text, or with no documents attached, is skipped: nothing is emitted on either lane. Each lane is written only when it has a downstream listener and at least one document survived re-ranking, so a question can produce no output object at all — put a pass-through-guaranteeing node after this one if a downstream stage requires a result for every question.

## Profiles

Default: **Balanced - Equal weight to vector and keyword search** (`balanced`).

| Profile | Alpha | Top K | RRF k |
|---|---|---|---|
| `balanced` **(default)** | 0.5 | 10 | 60 |
| `semantic` | 0.8 | 10 | 60 |
| `keyword` | 0.2 | 10 | 60 |

The three profiles differ only in `alpha`; they all return ten results and use an RRF constant of 60.

## Configuration

Pick the profile whose balance matches the corpus — `balanced` when both signals are worth the same, `semantic` when the questions are paraphrases of the content, `keyword` when they carry names, codes or other exact strings. The profile fills in all three fields, so most pipelines change nothing else. Values are validated when the node loads: an out-of-range alpha is clamped to `[0.0, 1.0]` with a warning, while `top_k` below 1 or a negative `rrf_k` raise an error rather than starting with a configuration that cannot produce sensible results.

### Search mode

Selects one of the profiles above and, with it, the alpha / top-k / RRF-constant triple shown in the configuration panel. Change the individual values below only when no profile fits.

### Alpha (vector weight)

Weights the vector ranking; BM25 gets `1 - alpha`. `0.5` treats both signals equally. Raise it when the incoming vector scores are trustworthy and the questions are semantic; lower it when exact term overlap decides relevance.

The endpoints are the limits of the weighting, not a switch to a single-signal mode. A leg weighted `0.0` contributes nothing to its documents' fused scores, so they sort below everything the weighted leg ranked — but they are still returned. `alpha = 1.0` emits the vector ranking followed by the unscored documents in BM25 order, which is exactly what `alpha = 0.99` emits. Alpha changes the order of the results, never which documents come back.

### Top K results

Caps how many documents are emitted, applied after fusion. The default of `10` suits a retrieval step that already narrowed the candidate set; raise it when a downstream reader can use more context, lower it when the consumer is a prompt with a tight budget. BM25 always scores the full incoming set — `top_k` only truncates the final ranking.

### RRF constant (k)

The `k` in the RRF term `weight / (k + rank + 1)`. It flattens the curve: at the default `60`, the difference between rank 1 and rank 2 is small, so a document needs to place well in *both* rankings to reach the top. Lower it (single digits) to let a strong first-place finish in one ranking dominate; raise it to spread influence further down both lists. It is not a score threshold and never removes a document.

## Notes

### How the ranking is built

Two ranked lists are formed from the same incoming documents: the vector list, sorted by the document scores that arrived, and the BM25 list, scored against the query. Text is tokenized by lowercasing and splitting on non-alphanumeric characters, so BM25 matches whole words, not substrings or stems. RRF then sums `weight / (rrf_k + rank + 1)` per list, weighting vector by `alpha` and BM25 by `1 - alpha`, and sorts by that total. Because RRF is rank-based, the magnitudes of the incoming vector scores do not matter — only the order they impose.

### Documents that arrive without a score

`Doc.score` is unset unless an upstream node fills it in, and a missing score is treated as absence of evidence rather than a score of zero. Such documents are left out of the vector list entirely but still ranked by BM25, and still returned. When no document carries a score there is no vector signal to fuse and the node ranks by BM25 alone; when only some do, the rest are ranked on their BM25 evidence. Either case logs a warning naming the missing signal, once per instance rather than once per question.

The only document the node does not return is one with no evidence in either leg — no score *and* no text BM25 can rank, such as empty content or content that tokenizes to nothing. That holds at every alpha.

### The emitted score is a ranking key, not a similarity

Each returned document's `score` is overwritten with the value that ordered it: the RRF score whenever both legs produced a ranking. That is a small rank-derived number (roughly `1 / (rrf_k + rank)`, about 0.016 at `rrf_k = 60`), and a document contributed only by a zero-weighted leg scores exactly `0.0`, meaning "contributed nothing", not "matched badly". Only when one leg produces no ranking at all does the node fall back to returning the other leg's list with its own raw BM25 or vector score. Do not compare these values against a calibrated similarity threshold downstream.

### Fan-out safety

The incoming question and the documents mapped back into the result are deep-copied, so a question fanned out to several branches is not mutated by this node.

## Upstream docs

- [rank_bm25](https://github.com/dorianbrown/rank_bm25) — the BM25 implementation this node uses.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `search_hybrid.alpha` | `number` | **Alpha (vector weight)**<br/>Weight for vector scores (0.0 = BM25 only, 1.0 = vector only, 0.5 = balanced) | `0.5` |
| `search_hybrid.profile` | `string` | **Search mode**<br/>Select the balance between vector and keyword search | `"balanced"` |
| `search_hybrid.rrf_k` | `number` | **RRF constant (k)**<br/>Reciprocal Rank Fusion constant. Higher values reduce impact of top rankings | `60` |
| `search_hybrid.top_k` | `number` | **Top K results**<br/>Maximum number of results to return after hybrid ranking | `10` |

## Dependencies

- `rank_bm25` `>=0.2.2,<1.0.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/search_hybrid)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Astra DB

Route: /nodes/store_astra

# store_astra

A RocketRide vector store for Astra DB that stores embedded document chunks and retrieves matching content in a pipeline or through an agent tool.

## About Astra DB

Astra DB is a database service with a Data API for application access. This node uses that API to create and query a collection whose vector and lexical search features are enabled. It is a storage and retrieval backend: it does not create embeddings or host a local database.

## What it does

The node writes embedded documents from the `documents` lane to an Astra collection and searches that collection for incoming questions. Semantic questions use the question embedding as the collection's vector sort; keyword questions use Astra's lexical sort. It can also bind `search`, `upsert`, and `delete` to an agent.

Choose it when the data must live behind an Astra Data API endpoint and you want Astra to provide both vector and lexical retrieval. Pick a sibling store instead when your existing collection lives in that sibling's database; this node creates and manages an Astra collection rather than adapting another store's protocol.

The collection is created only on the first write. Its vector dimension comes from those first incoming embeddings, its configured similarity is applied at creation, and lexical search is enabled with Astra's `standard` analyzer. A question or read against a collection that has not been created simply returns no documents.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store pre-embedded document chunks. |
| `questions` | `documents` | Emit matching documents. |
| `questions` | `answers` | Emit matching documents as answers. |
| `questions` | `questions` | Enrich the question with matching documents. |

## As a tool

The configured tool server name is the namespace for the functions below; it defaults to `astra`.

| Function | Description |
| --- | --- |
| `search` | Search the collection for matching documents. |
| `upsert` | Add or update documents in the collection. |
| `delete` | Remove documents by object ID. |

`search` and an `upsert` without a supplied embedding use the node's bound embedding provider. These calls are on the agent tool channel, not the document lanes. Give each Astra node a distinct tool server name when an agent can reach more than one of them.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Profiles

Default: **Astra DB cloud server** (`cloud`).

| Profile | Endpoint | Collection |
| --- | --- | --- |
| Local test server | `http://localhost:8080` | `ROCKETRIDE` |
| Astra DB cloud server **(default)** | Set an API endpoint | `ROCKETRIDE` |

## Configuration

Choose the profile, then provide the endpoint, token, collection, similarity, and retrieval score for the Astra database. The profile supplies the initial connection values; most deployments only need to replace the cloud endpoint and token. Feed an embedding node before this store: an arriving document without an embedding raises an error instead of being stored.

### Endpoint, token, and collection

Set **API Endpoint** to the Astra Data API endpoint and **Application Token** to the token used by `DataAPIClient`. The local profile deliberately starts with a local endpoint and test token, so replace both values when it is not your test server. A bad endpoint or token surfaces when the client uses the API; this node does not make a save-time connection probe.

Set a collection name before ingesting. It must start with a letter or number, and the remaining characters may only be letters, numbers, or underscores; startup rejects any other name. This matters before the first write because that write creates the collection—correct the name rather than expecting a later query to create it.

### Similarity and embedding dimension

The first successful ingest fixes the collection's vector dimension from the incoming embedding, and uses the selected similarity metric. `cosine` is the default; `euclidean` and `dot_product` are the only alternatives accepted by the implementation. Leave the default for ordinary normalized embedding vectors; change it only when the embedding model and the collection's intended metric agree. Reusing a collection with a different embedding length or an incompatible metric is a reason to create a separate collection rather than mix vectors.

### Retrieval score

The generated configuration supplies the requested retrieval score, while the store also has a hard floor: semantic hits below `0.20` are discarded before they reach any output lane. Raise the configured score when loosely related context is polluting answers; lower it when relevant content is absent, while remembering that values below the hard floor cannot restore those results. Keyword search does not carry this vector-similarity filter.

### Profile choice and first write

The cloud profile is the default and begins with empty endpoint and token values, which is the right starting point for an Astra deployment. The local profile is specifically a test-server preset: it uses `http://localhost:8080`, `test-token`, and the `ROCKETRIDE` collection. Select it only when that is the server you intend to reach; it is not a discovery mode for a cloud database.

The first write has two responsibilities: it creates the collection and supplies the vector dimension used for it. Send a small, representative embedded document after configuration rather than letting the first production batch establish an accidental dimension. Reads, deletes, and renders before that first creation are safe but return no stored content.

### Collection lifecycle controls

This store treats `chunkId` 0 as the beginning of a full object. If an ingest batch contains that chunk, the store schedules the object's existing chunks for deletion before inserting the new batch. Use a stable `objectId` across re-ingests to get replacement behavior; changing it creates another independently stored object.

Soft deletion is a separate lifecycle action. It leaves the chunks in Astra and changes `meta.isDeleted`, while a hard removal deletes the matching records. Choose soft deletion when a caller may need to inspect or restore the object; choose hard deletion when its data must no longer be stored.

### Tool Server Name

This is the namespace for agent functions, so the default exposes `astra.search`, `astra.upsert`, and `astra.delete`. Change it when multiple Astra nodes are connected to the same agent to prevent name collisions.

## Authentication

Set **API Endpoint** to the Astra Data API endpoint and **Application Token** to the token passed to the Data API client. The local profile also has endpoint and token values, so replace them when connecting to a different local server. The node passes the configured token directly to the Data API client; it does not offer a second authentication mode.

## Notes

### Search behavior and filters

Keyword search uses Astra's native lexical sort and supports the requested offset and limit. Semantic search uses the question embedding, includes a similarity score, and uses the requested result limit. Both paths apply the standard document filters for node, parent, permissions, object, table, and chunk selection. By default they also require `meta.isDeleted` to be false, so marked-deleted content stays hidden unless a caller explicitly requests it.

The two search modes are selected by the incoming question rather than by a second connection setting. Use a semantic question when the vocabulary may differ from the stored text, and use keyword search when exact words, paging, or the lexical index are more important. A semantic query with no collection returns an empty set; a document with no embedding is rejected at ingestion rather than being converted to keyword-only content.

### Ingestion, replacement, and deletion

The node stores each chunk with a generated `_id`, the content, metadata, and its vector. It collects up to 500 chunks before inserting. If a chunk with `chunkId` 0 arrives, all existing chunks with the same `objectId` are deleted first, so a complete re-ingest replaces that object instead of duplicating it. Near-zero vectors are omitted from the insert batch; the special zero-vector schema control document is adjusted to a tiny non-zero vector.

`markDeleted` and `markActive` update the `meta.isDeleted` flag for all chunks of the supplied object IDs, while `remove` permanently deletes those chunks. Rendering an object fetches its non-deleted chunks, sorts them by `chunkId` in the node, and joins their content because Astra does not guarantee the returned order.

That ordering detail matters when rendering a document whose chunks were written in parallel: do not rely on Astra's natural return order to reproduce the source text. The node makes the ordering decision itself, then calls the render callback with the combined text.

### Tool embedding dependency

Agent `search` needs an embedding for semantic retrieval, and agent `upsert` needs one to write a vector. Supplying an embedding in the tool call avoids that dependency; otherwise bind an embedding provider to the node. Do not assume the pipeline's document lane will supply it to a tool invocation—the two paths are separate.

## Upstream docs

- [Astra DB documentation](https://docs.datastax.com/en/astra-db/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `astra_db.api_endpoint` | `string` | **API Endpoint**<br/>Enter the server API endpoint e.g. <instance-name>.<region>.apps.astra.datastax.com |  |
| `astra_db.application_token` | `string` | **Application Token**<br/>Enter the server API application token |  |
| `astra_db.provider` | `string` |  | const: `"astra_db"` |
| `astra_db.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'astra' exposes tools as astra.search / astra.upsert / astra.delete. Change this when running multiple Astra DB nodes in the same pipeline so their tool names do not collide. | `"astra"` |

## Dependencies

- `astrapy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_astra)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# MongoDB Atlas

Route: /nodes/store_atlas

# store_atlas

A RocketRide vector store for MongoDB Atlas that stores embedded document chunks and retrieves matching content in a pipeline or through an agent tool.

## About MongoDB Atlas

MongoDB Atlas is a managed database service. This node stores documents in an Atlas collection, uses MongoDB text search for keyword queries, and creates an Atlas vector search index for embedding queries. It is the Atlas-specific option in the vector-store family, not a general connector for arbitrary MongoDB deployments.

## What it does

The node ingests embedded chunks into a MongoDB Atlas collection and searches them for incoming questions. Semantic questions use an Atlas `$vectorSearch` aggregation; keyword questions use MongoDB full-text search. It also exposes `search`, `upsert`, and `delete` when bound to an agent.

Choose it when your RocketRide store belongs in an Atlas collection and you want both retrieval paths from one node. Use a different store node for a collection hosted by a different database engine; this implementation creates Atlas-specific metadata, text, and vector indexes on first ingest.

An embedding node must run before the document lane. Ingesting a chunk without an embedding fails, while semantic questions likewise require an embedding. The first write creates the collection when needed and sizes the vector search index from that embedding's dimension.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store pre-embedded document chunks. |
| `questions` | `documents` | Emit matching documents. |
| `questions` | `answers` | Emit matching documents as answers. |
| `questions` | `questions` | Enrich the question with matching documents. |

## As a tool

The configured tool server name is the namespace for the functions below; it defaults to `atlas`.

| Function | Description |
| --- | --- |
| `search` | Search the collection for matching documents. |
| `upsert` | Add or update documents in the collection. |
| `delete` | Remove documents by object ID. |

`search` and an `upsert` without a supplied embedding use the node's bound embedding provider. Tool invocations do not flow through the pipeline's embedding lane, so bind that provider when agents should create or search vectors automatically. Choose a distinct tool server name for each Atlas node an agent can access.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Configuration

Provide the Atlas connection URI, database, collection, similarity, and retrieval score. The node creates the collection and its indexes when it first receives documents. Keep those index choices stable for an existing collection; this implementation checks for an index name but does not rebuild a differently shaped vector index for you.

### Connection URI, database, and collection

The host must be a non-empty MongoDB SRV URI in the form `mongodb+srv://user:password@cluster.example.mongodb.net/?...`, and a non-empty API key value is required when the configuration is saved. The runtime client is constructed from the URI, including its credentials. Use this node only with an Atlas endpoint that supports the indexes it creates; a connection string for some other MongoDB deployment is not an equivalent replacement.

Database names cannot contain `/`, `\\`, spaces, quotes, `$`, `*`, `<`, `>`, `:`, `|`, or `?`, and are at most 64 characters. Collection names cannot start with `system.`, cannot contain `$`, and are at most 120 characters. Correct invalid names before saving: the validation is intended to catch a doomed deployment rather than let the first ingest fail later.

### Vector indexes and similarity

On first ingestion the node creates ordinary metadata indexes, a text index on `content`, and a vector search index named `vector_index`. That vector index takes its dimension from the incoming embeddings. Similarity defaults to `cosine`; `euclidean` and `dotproduct` are the other accepted values. Keep the selected metric and embedding dimension aligned with the vectors you will query; changing either after collection creation calls for a new compatible index or collection.

The implementation logs and continues if Atlas rejects vector-index creation, with a message that it may need to be created in Atlas. If semantic retrieval then fails while keyword retrieval works, inspect the Atlas vector index rather than changing the question text. The node also builds metadata indexes and a text index, so first ingest is doing setup work as well as writing data.

### Retrieval score and result windows

Semantic search requests ten candidates for every requested result and returns the requested limit (25 when none is supplied). It does not support a non-zero offset. Use keyword search when you need offset/limit paging; it uses text score, supports both, and defaults its limit to 25.

The configured score should be tuned for relevance, but it is not the only safeguard: returned semantic scores are normalized and anything below `0.20` is dropped. Raise the score when unrelated chunks reach a prompt; lower it when useful context is missing, but do not expect a setting below the hard floor to return weaker hits. Cosine results are normalized differently from the other supported metrics, another reason not to change the metric casually on an established collection.

### First ingest and index readiness

The first ingest both stores documents and attempts the Atlas setup: ordinary metadata indexes, a `content` text index, and the vector search index. For an established collection, make sure the configured vector-index name and metric describe the index you already operate. The node checks whether that named search index exists; it does not assume that a different existing index is usable.

Atlas may reject creation of the vector index while leaving the collection available. The implementation logs that condition and continues, which can make keyword search appear healthy while semantic search is unavailable. Treat that split result as an index-readiness issue, and create or repair the Atlas vector index before tuning retrieval settings.

### Object replacement and batch sizing

An incoming `chunkId` 0 identifies the start of an object replacement. The node deletes stored chunks for each such `objectId` before inserting the batch, then stores every new chunk with generated `_id`, embedding, text, and metadata. Send complete replacement batches together; sending only a new top-level chunk removes the older object chunks by design.

The implementation flushes an insert batch at 500 documents or when its accumulated object size exceeds the payload limit. That makes large imports incremental without changing retrieval semantics. When diagnosing a partial import, check the source batch and the first chunk's metadata rather than assuming every call is one atomic object write.

### Tool Server Name

This is the namespace for the three agent functions: `atlas.search`, `atlas.upsert`, and `atlas.delete` by default. Change it to avoid collisions between multiple Atlas tool nodes.

## Authentication

Supply the MongoDB SRV URI, including its credentials, as the host value. The save-time check also requires a non-empty API key value; the runtime client is constructed from the configured URI. The node has no separate local or unauthenticated profile.

## Notes

### Filters, lifecycle, and rendering

Both search modes apply filters for node, parent, permissions, object, table, and chunk information. Default filters also require `meta.isDeleted` to be false, so soft-deleted chunks remain stored but do not appear in ordinary searches. `markDeleted` and `markActive` toggle that flag, while `remove` permanently deletes the selected objects.

When a batch includes `chunkId` 0 for an object, the node removes all older chunks for that object before inserting the new batch. This is replacement behavior for a full re-ingest, not an append-only import. Inserts flush at 500 documents or when their accumulated Python object size passes the configured payload limit. Rendering an object rebuilds its text by chunk ID in windows, so it can handle large multi-chunk documents.

Rendering does not query an application-level full-text document. Instead, it fetches matching chunks by object and chunk range, places them into their chunk-ID positions, and joins the available content. Gaps therefore remain gaps rather than shifting later chunks into earlier positions.

### Search-mode selection

Semantic search is appropriate when matching meaning across different wording, but it requires a compatible question embedding and cannot page with a non-zero offset. Keyword search uses the collection's text index and is the better choice for literal terms or page-by-page inspection. Both modes honor the document filters, so a missing result can be caused by metadata selection or soft deletion as well as ranking.

### Agent tool behavior

The agent `search` function performs semantic retrieval and the agent `upsert` function can use a supplied vector or a bound embedding provider. `delete` permanently removes by object ID. Keep the tool server name unique when several Atlas stores are attached to one agent; otherwise the same function names would collide.

## Upstream docs

- [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `atlas.provider` | `string` |  | const: `"atlas"` |
| `atlas.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'atlas' exposes tools as atlas.search / atlas.upsert / atlas.delete. Change this when running multiple Atlas nodes in the same pipeline so their tool names do not collide. | `"atlas"` |
| `vector.cloud.host` |  | Enter the server IP address e.g. <your-instance-name>.<region>.atlas.io |  |
| `vector.database` |  |  | `"rocketride_db"` |

## Dependencies

- `pymongo`
- `dnspython`
- `pydantic`
- `urllib3`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_atlas)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Chroma

Route: /nodes/store_chroma

# store_chroma

A RocketRide vector store for Chroma that stores embedded document chunks and retrieves matching content in a pipeline or through an agent tool.

## About Chroma

Chroma is a vector database used here through its HTTP client. This node keeps document text, metadata, and vectors in a Chroma collection and queries that server over the network. It does not run an embedded Chroma database inside RocketRide.

## What it does

The node stores pre-embedded chunks in a Chroma collection and retrieves them by vector similarity or keyword containment for incoming questions. It can also be connected as an agent tool. Choose it when a reachable Chroma server is the store for your pipeline and you need both pipeline lanes and agent access; choose a sibling store when the database you operate is not Chroma.

The node uses the lightweight `chromadb-client` HTTP client and creates the collection on its first write. It requires an embedding on every incoming document, so wire an embedding node ahead of its document lane. It can use a self-managed server or a token-authenticated cloud server, but both are remote HTTP connections.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store pre-embedded document chunks. |
| `questions` | `documents` | Emit matching documents. |
| `questions` | `answers` | Emit matching documents as answers. |
| `questions` | `questions` | Enrich the question with matching documents. |

## As a tool

The configured tool server name is the namespace for the functions below; it defaults to `chroma`.

| Function | Description |
| --- | --- |
| `search` | Search the collection for matching documents. |
| `upsert` | Add or update documents in the collection. |
| `delete` | Remove documents by object ID. |

`search` and an `upsert` without a supplied embedding use the node's bound embedding provider. These calls are separate from the data lanes, so a pipeline embedding upstream does not by itself provide vectors to a tool call. Use different server names when an agent has access to multiple Chroma nodes.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Profiles

Default: **Your own ChromaDB server** (`local`).

| Profile | Connection | Authentication |
| --- | --- | --- |
| Your own ChromaDB server **(default)** | Host and port | None configured by the node |
| ChromaDB Cloud Server | Host and port | Token authentication with the API key |

## Configuration

Start with the local or cloud profile, then provide the host, port, collection, similarity, retrieval score, and—when using cloud—the API key. Most fields can remain at their profile values after the server address is set. The collection's similarity is established when it is first created, so choose it before writing the first documents.

### Connection profile and port

The local profile creates a plain HTTP client; the cloud profile connects over TLS and sends the API key in the `x-chroma-token` header, which suits ChromaDB Cloud or any TLS-protected remote server. ChromaDB Cloud additionally requires `tenant` and `database`; its host is `api.trychroma.com`. Use the cloud profile only when you have the token that Chroma expects; the local profile deliberately supplies no credentials. The implementation removes an `http://` or `https://` prefix and trailing slash from the configured host before connecting, so enter the host once rather than trying to encode a path in it.

Ports may be literal integers, numeric strings, or interpolated environment values. A whole-number value in the TCP range is used; a boolean, fractional value, unresolved placeholder, non-numeric value, or out-of-range value silently falls back to `8000`. This is useful for an environment placeholder, but it can also send a cloud connection to the wrong port: if a connection unexpectedly targets `8000`, check the resolved value first.

### Collection and similarity

The collection is created on first write with the selected similarity in its `hnsw:space` metadata. `cosine` is the default; `l2` and `ip` are the only other accepted values. Keep that setting aligned with your embedding model, and do not expect changing it later to rewrite an existing collection's index. Use a separate collection if the new model needs a different vector shape or distance metric.

Semantic retrieval needs a question embedding and does not support a non-zero offset. Use keyword search when you need paged text matching: it uses Chroma's document-contains filter and supports offset and limit. Semantic scores are converted from Chroma distances and hits below `0.20` are always discarded. Raise the requested score when marginal chunks are harming a prompt; lower it for recall, knowing the hard floor still applies.

### Retrieval score and document filters

The retrieval score controls which semantic hits are emitted after distance conversion. It affects semantic questions only, not keyword containment. Default filters exclude records with `isDeleted` metadata set to true, while records without that key are treated as active. The same filter conversion supports node, parent, object, table, chunk range, and permission constraints, so prefer filters over copying data into many collections merely to narrow a query.

### Top K

**Top K** (`top_k`) sets how many candidate chunks Chroma fetches for a semantic or keyword question before score filtering. It overrides the caller's request limit in both directions rather than only widening it: on the data lane that limit is 25, so `50` doubles the candidate pool while `20` shrinks it. Leave it unset to use the caller's limit as-is. The `chroma.search` tool sets its own `top_k` (default 10, maximum 100), and whole-object fetches are unaffected.

Valid values are `1` to `1000`, written as an integer (`50`) or an integer string (`"50"`). The string form exists because environment interpolation always resolves to a string, so a `${ROCKETRIDE_TOP_K}` placeholder validates; a placeholder still unresolved at run time falls back to the caller's limit rather than failing the node, the same way `port` falls back to its default. Any other non-integer value, or an integer outside that range, is rejected when the node starts instead of being silently clamped, so a mistyped value surfaces immediately rather than quietly changing how many documents you retrieve.

To widen the pool for a reranker or for hard, specific questions, pick a value comfortably above the caller's limit, for example `50`, and place a `rerank_cohere` node after this one to reorder the candidates and keep a small, high-relevance set. A complete example is at [`examples/rag-rerank-pipeline.pipe`](../../../../examples/rag-rerank-pipeline.pipe).

### Profile choice and collection creation

Use **Your own ChromaDB server** when you control a reachable server and do not need token authentication. Use **ChromaDB Cloud Server** when that server expects the configured API key. The profile determines how the HTTP client is constructed, so switching profiles is not just a different display label for the same connection.

The first document write calls Chroma's get-or-create collection operation and attaches the chosen `hnsw:space` metadata. Make the similarity decision before the first write. If you need to move an existing collection to a different distance metric, create and migrate to a new collection instead of expecting this node to alter the existing index.

### Document lane and tool embeddings

Every document-lane chunk needs an embedding; the store raises an error when it is absent. A semantic question needs an embedding too, while keyword containment works from the question text. This is intentionally different from an agent `upsert`, which can ask the node's bound embedding provider to create a missing vector.

Use the bound provider for an agent that must add or search information without manually supplying embeddings. If an agent tool fails for a vector-related reason while document-lane storage succeeds, inspect that binding and the tool payload before changing Chroma configuration.

### Tool Server Name

This value namespaces the agent functions: `chroma.search`, `chroma.upsert`, and `chroma.delete` by default. Change it for distinct Chroma stores exposed to the same agent.

## Authentication

The cloud profile passes **API Key** to Chroma's token-authentication client. The local profile constructs the HTTP client without those authentication settings. A failed connection reports the host and port and points to connectivity, credentials, or an incompatible server as possible causes.

## Notes

### Server compatibility

When the server reports a version, this node requires Chroma 0.6 or later. An unparseable or unavailable version does not block connection, but an identified older server is rejected with an upgrade message. This protects against an older server failing later with a confusing client compatibility error.

### Ingestion, replacement, and rendering

Every ingested chunk needs an embedding. Inserts are batched and flush at 500 chunks or when the accumulated payload exceeds the configured limit. A chunk with `chunkId` 0 causes older chunks with the same `objectId` to be deleted before the new chunks are upserted, so a re-ingest replaces an object rather than adding a second copy. Chroma record IDs are generated UUIDs; use `objectId` and `chunkId` as the stable application identifiers.

Soft deletion marks the metadata and hides a document from default search; hard deletion removes it. Rendering reconstructs an object in chunk-ID order and reads it in configured windows, tolerating gaps in the sequence. That makes the render path appropriate for a large stored document, not a guarantee that all chunks are contiguous.

The node gives each Chroma record a fresh UUID, even when an object is being re-ingested. The stable identifiers for lifecycle operations are therefore the metadata `objectId` and `chunkId`, not an internal Chroma record ID. Keep those metadata values consistent across imports to make replacement, filters, and rendering predictable.

### Search result interpretation

Chroma reports distances, which the node converts to the score carried by a returned document. The conversion differs for cosine versus `l2` or `ip`, so a numeric threshold has meaning only alongside the selected similarity. Compare retrieval-score behavior within one collection and metric; do not treat the same threshold as equivalent after changing metrics.

When semantic results are unexpectedly empty, verify the query embedding, the collection metric, the `isDeleted` filter, and the `0.20` hard floor in that order. When keyword results are unexpectedly empty, verify the search text and document containment rather than the vector score.

### Agent tool dependency

Agent semantic search and automatic tool upserts require the node's bound embedding provider unless the tool request supplies an embedding itself. If a tool returns an embedding-related error while the pipeline path works, check the tool binding rather than the Chroma host configuration.

## Upstream docs

- [Chroma documentation](https://docs.trychroma.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `chroma.database` | `string` | **Database**<br/>Chroma Cloud database name (required for Chroma Cloud, optional for self-hosted multi-tenant servers) | `""` |
| `chroma.profile` | `string` | **Type of chroma host**<br/>Connect to... | `"local"` |
| `chroma.provider` | `string` |  | const: `"chroma"` |
| `chroma.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'chroma' exposes tools as chroma.search / chroma.upsert / chroma.delete. Change this when running multiple Chroma nodes in the same pipeline so their tool names do not collide. | `"chroma"` |
| `chroma.ssl` | `boolean` | **Use TLS**<br/>Connect over HTTPS. Required for Chroma Cloud, which serves HTTPS only. Turn it off for a self-hosted server reached over plain HTTP. | `true` |
| `chroma.tenant` | `string` | **Tenant**<br/>Chroma Cloud tenant id (required for Chroma Cloud, optional for self-hosted multi-tenant servers) | `""` |
| `vector.cloud.host` |  | Enter the server IP address e.g. <your-instance-url> |  |
| `vector.cloud.port` | `number,string` | Port number. Enter a plain integer such as 443, or an env-var placeholder like ${ROCKETRIDE_CHROMA_PORT}. Placeholders resolve to a string at run time, so this field accepts both a number and a string; the node coerces the value to an integer before connecting, so either form works. | `"443"` |
| `vector.local.host` |  |  | `"localhost"` |
| `vector.local.port` | `number,string` | Port number. Enter a plain integer such as 8000, or an env-var placeholder like ${ROCKETRIDE_CHROMA_PORT}. Placeholders resolve to a string at run time, so this field accepts both a number and a string; the node coerces the value to an integer before connecting, so either form works. | `"8000"` |

## Dependencies

- `chromadb-client`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_chroma)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Elasticsearch

Route: /nodes/store_elasticsearch

# store_elasticsearch

A RocketRide store node that indexes text or embedded document chunks in Elasticsearch or OpenSearch and retrieves them through pipeline lanes.

## About Elasticsearch and OpenSearch

Elasticsearch and OpenSearch are search backends that index text and can search embedding vectors. This directory provides a RocketRide service for each backend, choosing one from configuration at runtime. Both services can use either text-index or vector-store mode, but their deployment and index-management behavior is not interchangeable.

## What it does

This directory provides two services: Elasticsearch and OpenSearch. Both ingest raw text for BM25-style index search or embedded documents for vector retrieval, then emit matching text, documents, or answers for incoming questions. Elasticsearch also supports a `questions` → `questions` lane for retrieved-context enrichment; OpenSearch does not declare that lane.

Pick this node when Elasticsearch or OpenSearch is already the searchable index for your pipeline, especially when the same lane layout must support either keyword or embedding retrieval. Choose a dedicated vector-store sibling when its database is where your vectors belong and you do not need the dual-mode search behavior.

In **index mode**, use the `text` lane for raw text and queries run BM25-style matching. In **vector-store mode**, use the `documents` lane after an embedding node. Changing mode changes how the inputs are handled; it is not merely a different ranking option on one index.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | — | Ingest raw text for index mode. |
| `documents` | — | Ingest embedded documents for vector-store mode. |
| `questions` | `text` | Emit matching text. |
| `questions` | `documents` | Emit matching documents. |
| `questions` | `answers` | Emit matching content as answers. |
| `questions` | `questions` | Enrich the question with matching documents for the Elasticsearch service. |

## Profiles

The directory registers two backends and each keeps its own default: the
Elasticsearch service defaults to **Self-managed Elasticsearch**
(`self-managed`), the OpenSearch service to **Local OpenSearch** (`local`).
Both are marked below; which one applies depends on the service you added
to the pipeline.

| Profile | Backend | Mode |
| --- | --- | --- |
| Self-managed Elasticsearch **(default)** | Elasticsearch | Vector store |
| Elastic Cloud Hosted | Elasticsearch | Vector store |
| Elastic Cloud Serverless | Elasticsearch | Vector store |
| Local OpenSearch **(default)** | OpenSearch | Index |

## Configuration

Select the service and deployment profile before choosing the index or collection and search mode. Elasticsearch and OpenSearch have separate connection fields and separate index implementations, even though both expose the same core input lanes. Set the mode and index deliberately before first ingest; otherwise data can be written to an index with mappings intended for the other mode.

### Elasticsearch

The Elasticsearch profiles are self-managed, cloud-hosted, and cloud-serverless. Self-managed starts with `localhost:9200`; cloud-hosted uses port `9243`, and cloud-serverless uses port `443`. Pick the cloud profile for an Elastic Cloud endpoint so the client uses the correct connection values; keep self-managed for a local or independently hosted cluster.

The index name defaults to `rocketride` and must be 1–255 lowercase letters, digits, `.`, `_`, or `-`. Slashes and spaces are invalid. Configuration validation warns about a bad name or a zero port and then makes a short cluster-health request, so a warning about connectivity is a cue to correct the endpoint or credentials before attempting ingestion.

### Elasticsearch Store Mode and retrieval

Elasticsearch starts in vector-store mode. Turn **Store Mode** off to ingest and search raw text instead. In index mode, documents arriving on the `documents` lane are ignored; use `text`. In vector-store mode, documents must contain embeddings, and semantic questions need an embedding as well. If a pipeline appears to accept input but returns no results, first verify that its lane matches the selected mode.

The Elasticsearch vector store uses a dense-vector mapping, and its similarity defaults to cosine. Use another supported similarity only when the stored embedding model calls for it; an existing vector index should not be treated as metric-agnostic. The standard retrieval-score setting is the cutoff for semantic results: raise it when unrelated chunks contaminate context and lower it when recall is too sparse.

### Retrieval Score

The retrieval-score control is meaningful only for vector-store retrieval. Start with the default when bringing up a new embedding corpus, then raise it if the documents injected into an answer are merely adjacent in topic rather than useful context. Lower it when a precise question has no supporting chunks, but check the embedding model and index dimension first—threshold changes cannot make incompatible vectors comparable.

Tune the score after testing queries that represent the vocabulary and specificity of the actual pipeline. Text-index matches use the BM25-style path instead, so changing this field will not repair unexpectedly broad or narrow keyword results. Use the match operator and phrase controls for that job.

### Elasticsearch text search behavior

Enable **Customize Indexing Search Behavior** only when the default broad matching needs refinement. `or` is the default and is useful for recall; `and` requires all terms when queries are returning too much; `exact` performs phrase matching. **Slop** applies only to `exact` and defaults to `0`; increase it when the same phrase is expected with intervening words.

Enable contextual snippets when downstream consumers need just the matching passage instead of the full stored text. The default snippet size is 250 characters; increase it for more surrounding context and reduce it to keep answer payloads focused. These choices alter searching only, so they can be adjusted between runs without re-ingesting the text index.

The node scans every matching text hit in batches of 500 with a one-minute scroll context. That favors a pipeline which intentionally processes the complete matching set rather than a small top-k result page. Constrain the query or select a more specific index when a broad keyword search would make that full result set too large for downstream processing.

### OpenSearch

OpenSearch uses the configured host, collection, and optional basic-auth credentials. Its local profile starts in index mode, unlike Elasticsearch's vector-store default. The collection defaults to `rocketride` and allows lowercase letters, numbers, and underscores. Choose a new collection before switching a production workload between modes, rather than relying on a common name to be safe for both mappings.

When basic authentication is enabled, a host without a scheme gets `http://`, then an `http://` URL is upgraded to `https://`. The client also disables certificate verification in that branch. This accommodates self-managed clusters with self-signed certificates, but it means the host and authentication toggle jointly determine the connection—not just the text entered in **Host**.

### OpenSearch Store Mode, embedding dimension, and score

Turn **Store Mode** on to create and use an OpenSearch vector index. **Embedding Dimension** is required in that mode and defaults to `768`; it must match every vector you send. A missing, non-numeric, or wrong-sized question embedding is skipped rather than searched, and a document without an embedding is skipped rather than indexed. If a vector query produces nothing without an error, compare the model dimension to this setting first.

**Retrieval Score** defaults to `0.5` and filters lower-scoring OpenSearch vector hits. Raise it for a more precise context window, or lower it when useful matches are missing. The same optional index-search controls—match operator, slop, and contextual snippets—apply only when index mode is active; do not expect them to tune k-NN ranking.

OpenSearch verifies the existing vector mapping before using it. If the index is not a `knn_vector` index or its dimension differs, the implementation deletes and recreates the index. Treat an embedding-dimension change as destructive for that index: use a new collection name when preserving existing data matters.

### OpenSearch text search behavior

With **Store Mode** off, raw `text` input creates a text mapping when the collection does not already exist, and questions use the shared BM25-style search path. Configure match operator, phrase slop, and snippets for the query shape rather than the ingest shape: none of these fields changes how the text is indexed. This makes them safe controls to experiment with between pipeline runs.

The OpenSearch text path emits every matching hit it scans, as answers, text, and documents when the corresponding listeners exist. If a large result set is surprising, narrow the query or use a more restrictive match operator; the node is not limiting text hits to the ten k-NN neighbors used by the vector path.

## Authentication

Elasticsearch cloud profiles use the configured API key. OpenSearch optionally uses the configured username and password when **Use basic auth** is enabled; the connection normalizes the host to HTTPS in that case. Self-managed Elasticsearch supplies no credentials to its client configuration. When OpenSearch authentication is disabled, the implementation does not pass the entered username or password to the client.

## Notes

### Index-mode output behavior

In index mode, the node writes text from the `text` lane and searches it with BM25-style queries. Text search scans all matching results in batches of 500 using a one-minute scroll window, instead of returning only an initial page. Each result can be emitted as an answer, text, and document; with highlighting enabled, the highlighted fragments are emitted in place of the full content.

The `questions` → `questions` lane belongs only to the Elasticsearch service. Do not wire downstream behavior that depends on that enrichment lane when the configured service is OpenSearch, even though both services can emit text, documents, and answers.

In both backends, a highlighted text result replaces the otherwise emitted full content with each returned fragment. This is useful for prompt-sized evidence windows, but it also means a downstream consumer needing the whole source should leave snippets off or retrieve the source through a different flow.

### Vector ingestion and lifecycle

For OpenSearch vector ingest, an application document ID is built from `objectId` and `chunkId`, so writing the same pair updates that record. The vector mapping uses a k-NN field with an HNSW/FAISS cosine setup. Elasticsearch uses its document-store implementation, which batches writes at 500 actions or its payload limit, supports soft deletion through `meta.isDeleted`, and permanently removes matching object IDs with a delete-by-query operation.

The OpenSearch vector path does not silently coerce a bad question vector into a compatible query. It skips missing, non-numeric, or wrong-dimensional vectors, then applies the score threshold to the ten returned k-NN hits. That behavior protects the index from invalid input but can look like an empty retrieval result; confirm the embedding before reducing the score.

Elasticsearch can reconstruct a stored object by fetching chunk ranges in chunk-ID order. That render path is Elasticsearch-only; the OpenSearch service does not implement the equivalent object rendering path in this node.

### Mode-switching checklist

Before switching a pipeline, confirm the selected backend, mode, index name, and—when using OpenSearch vectors—embedding dimension. Then send data on the correct input lane: `text` for index mode or embedded `documents` for vector mode. This avoids the two silent skips in the implementation: document-lane input in index mode and invalid OpenSearch vector input in vector mode.

For a destructive migration, use a new OpenSearch collection name and ingest the new vectors before retiring the old one. Reusing a collection while changing its dimension gives the node a reason to delete and recreate its vector index, which removes the existing indexed data.

## Upstream docs

- [Elasticsearch documentation](https://www.elastic.co/guide/index.html)
- [OpenSearch documentation](https://docs.opensearch.org/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Elasticsearch (`services.elasticsearch.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `elasticsearch.index` | `string` | **Index Name / Collection Name**<br/>Enter the name of the Elasticsearch index | `"rocketride"` |
| `elasticsearch.index_label` | `object` | **Index Mode** |  |
| `elasticsearch.matchOperator` | `string` | **Match Operator**<br/>Controls how multiple query terms are matched: 'or' (default) matches documents containing ANY of the query terms, 'and' matches documents containing ALL of the query terms, 'exact' requires the exact phrase to appear in order (phrase matching). | `"or"` |
| `elasticsearch.profile` | `string` | **Deployment Type**<br/>Connect to... | `"self-managed"` |
| `elasticsearch.provider` | `string` |  | const: `"elasticsearch"` |
| `elasticsearch.search` | `boolean` | **Customize Indexing Search Behavior**<br/>Customize the search behavior of the index. This option does not affect the ingestion and creation of the index. You can switch between behaviors when searching between pipeline runs. | `false` |
| `elasticsearch.search.exact.slop` | `number` | **Slop**<br/>The number of words to allow between terms when exact phrase search is enabled. | `0` |
| `elasticsearch.search.highlight` | `boolean` | **Return contextual snippets**<br/>Use the unified highlighter to return snippets around matches. | `false` |
| `elasticsearch.search.highlight.fragment_size` | `number` | **Snippet size (characters)**<br/>Maximum characters in the returned highlight snippet (context window) per hit. | `250` |
| `elasticsearch.store_enabled` | `boolean` | **Store**<br/>Enable document storage | `true` |
| `elasticsearch.store_mode` | `boolean` | **Store Mode**<br/>Toggle between index (text search) and vector store (semantic search). | `true` |
| `elasticsearch.type` | `string` | **Type**<br/>Elasticsearch operation type | `"vector_database"` |
| `elasticsearch.vstore_label` | `object` | **Vector Store Mode** |  |
| `vector.cloud.host` |  | Enter the Elastic Cloud host URL e.g. <your-deployment-id>.es.<region>.cloud.es.io |  |
| `vector.cloud.port` |  |  | `9243` |
| `vector.index` | `string` | **Index Name / Collection Name**<br/>Enter the name of the Elasticsearch index (must be lowercase) | `"rocketride"` |
| `vector.local.host` |  |  | `"localhost"` |
| `vector.local.port` |  |  | `9200` |

### OpenSearch (`services.opensearch.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `opensearch.auth.enabled` | `boolean` | **Use basic auth**<br/>Enable basic authentication when connecting. | `true` |
| `opensearch.auth.password` | `string` | **Password** | `""` |
| `opensearch.auth.username` | `string` | **Username** | `"admin"` |
| `opensearch.collection` | `string` | **Collection**<br/>The name of the collection to use for the OpenSearch index. Only lowercase letters, numbers, and underscores are allowed. | `"rocketride"` |
| `opensearch.dim` | `integer` | **Embedding Dimension**<br/>Required in vector store mode; dimension of embedding vectors. | `768` |
| `opensearch.host` | `string` | **Host**<br/>Localhost URL for OpenSearch. | `"http://localhost:9200"` |
| `opensearch.index_label` | `object` | **Index Mode** |  |
| `opensearch.matchOperator` | `string` | **Match Operator**<br/>Controls how multiple query terms are matched: 'or' (default) matches documents containing ANY of the query terms, 'and' matches documents containing ALL of the query terms, 'exact' requires the exact phrase to appear in order (phrase matching). | `"or"` |
| `opensearch.mode` | `boolean` | **Store Mode**<br/>Toggle between index and vector store. | `false` |
| `opensearch.provider` | `string` |  | const: `"opensearch"` |
| `opensearch.score` | `number` | **Retrieval Score**<br/>Minimum retrieval score for vector stores | `0.5` |
| `opensearch.search` | `boolean` | **Customize Indexing Search Behavior**<br/>Customize the search behavior of the index. This option does not affect the ingestion and creation of the index. You can switch between behaviors when searching between pipeline runs. | `false` |
| `opensearch.search.exact.slop` | `number` | **Slop**<br/>The number of words to allow between terms when exact phrase search is enabled. | `0` |
| `opensearch.search.highlight` | `boolean` | **Return contextual snippets**<br/>Use the unified highlighter to return snippets around matches. | `false` |
| `opensearch.search.highlight.fragment_size` | `number` | **Snippet size (characters)**<br/>Maximum characters in the returned highlight snippet (context window) per hit. | `250` |
| `opensearch.vstore_label` | `object` | **Vector Store Mode** |  |

## Dependencies

- `elasticsearch` `>=8.0.0,<9.0.0`
- `opensearch-py` `==3.2.0`
- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_elasticsearch)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Elasticsearch

Route: /nodes/store_elasticsearch/elasticsearch

---
title: Elasticsearch
date: 2026-04-08
sidebar_position: 1
---

<head>
  <title>Elasticsearch - RocketRide Documentation</title>
</head>

## What it does

Elasticsearch node with two modes: **Index** (BM25 full-text search) and **Vector Store** (semantic/kNN search). Switch between modes with the Store Mode toggle, no pipeline rewiring needed.

**Lanes:**

| Lane in     | Lane out    | Description                                                  |
| ----------- | ----------- | ------------------------------------------------------------ |
| `text`      | -           | Ingest raw text (index mode only)                            |
| `documents` | -           | Ingest pre-embedded documents (vector store mode only)       |
| `questions` | `text`      | Search and return matching text                              |
| `questions` | `documents` | Search and return matching documents                         |
| `questions` | `answers`   | Search and return matching documents as answers              |
| `questions` | `questions` | Enrich question with matching documents for downstream nodes |

Documents must be run through an embedding node before reaching this node (vector store mode only).

## Profiles

| Profile                  | Default port | Description                                   |
| ------------------------ | ------------ | --------------------------------------------- |
| Self-managed _(default)_ | `9200`       | Your own Elasticsearch instance               |
| Elastic Cloud Hosted     | `9243`       | Hosted deployment: requires host and API key |
| Elastic Cloud Serverless | `443`        | Serverless: requires host and API key        |

## Configuration

| Field      | Required   | Description                                             |
| ---------- | ---------- | ------------------------------------------------------- |
| Host       | yes        | Elasticsearch server address                            |
| Port       | yes        | Elasticsearch server port                               |
| API Key    | cloud only | Authentication token                                    |
| Index Name | yes        | Elasticsearch index (lowercase, max 255 chars)          |
| Store Mode | yes        | `Index` (BM25 text search) or `Vector Store` (semantic) |

## Index mode: search options

| Field                      | Default | Description                                                |
| -------------------------- | ------- | ---------------------------------------------------------- |
| Match Operator             | `or`    | `or`: any term, `and`: all terms, `exact`: phrase match |
| Slop                       | `0`     | Words allowed between terms in exact phrase match          |
| Return contextual snippets | off     | Highlight matching passages in results                     |
| Snippet size               | `250`   | Max characters per highlight snippet                       |

## Upstream docs

- [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
- [Elastic Cloud](https://www.elastic.co/cloud)


---

# OpenSearch

Route: /nodes/store_elasticsearch/opensearch

---
title: OpenSearch
date: 2026-04-08
sidebar_position: 1
---

<head>
  <title>OpenSearch - RocketRide Documentation</title>
</head>

## What it does

OpenSearch node with two modes: **Index** (BM25 full-text search) and **Vector Store** (kNN semantic search). Switch between modes with the Store Mode toggle, no pipeline rewiring needed.

**Lanes:**

| Lane in     | Lane out    | Description                                            |
| ----------- | ----------- | ------------------------------------------------------ |
| `text`      | -           | Ingest raw text (index mode only)                      |
| `documents` | -           | Ingest pre-embedded documents (vector store mode only) |
| `questions` | `text`      | Search and return matching text                        |
| `questions` | `documents` | Search and return matching documents                   |
| `questions` | `answers`   | Search and return matching documents as answers        |

Documents must be run through an embedding node before reaching this node (vector store mode only).

## Configuration

| Field               | Required    | Description                                                       |
| ------------------- | ----------- | ----------------------------------------------------------------- |
| Host                | yes         | OpenSearch server URL (e.g. `http://localhost:9200`)              |
| Collection          | yes         | Index name (lowercase, max 255 chars)                             |
| Use basic auth      | no          | Enable username/password authentication                           |
| Username            | auth only   | Basic auth username (default `admin`)                             |
| Password            | auth only   | Basic auth password                                               |
| Store Mode          | yes         | `Index` (BM25 text search) or `Vector Store` (kNN)                |
| Embedding Dimension | vector only | Must match the dimension of your embedding model                  |
| Retrieval Score     | vector only | Minimum similarity score to include a result (0–1, default `0.5`) |

## Index mode: search options

| Field                      | Default | Description                                                |
| -------------------------- | ------- | ---------------------------------------------------------- |
| Match Operator             | `or`    | `or`: any term, `and`: all terms, `exact`: phrase match |
| Slop                       | `0`     | Words allowed between terms in exact phrase match          |
| Return contextual snippets | off     | Highlight matching passages in results                     |
| Snippet size               | `250`   | Max characters per highlight snippet                       |

## Upstream docs

- [OpenSearch documentation](https://opensearch.org/docs/latest/)


---

# Milvus

Route: /nodes/store_milvus

# store_milvus

A RocketRide vector-store node that stores embedded document chunks in Milvus and retrieves them by semantic or keyword search. Use it when a pipeline or agent needs a Milvus-backed document store.

## About Milvus

Milvus is a vector database for storing embeddings and finding similar vectors.
It is designed for vector-search workloads and supports structured fields alongside
vector data. Use it when your team has chosen Milvus as the place to operate its
retrieval data, whether the service is self-managed or hosted.

## What it does

The node accepts embedded documents on its `documents` lane and can retrieve matching documents for incoming questions. It also exposes the same store to an agent as tools. The collection is created when documents are first added, and incoming chunks without embeddings are rejected. Pick it over the other vector-store nodes when Milvus is the database already available to the workload, or when its collection and index model is the model your operators need to manage.

At creation, the driver makes an `id` scalar index and an `IVF_FLAT` vector index with `nlist` 1024. It stores the document content and metadata with the vector, so metadata filters and keyword retrieval can operate over the same collection.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store embedded document chunks. |
| `questions` | `documents` | Return matching documents. |
| `questions` | `answers` | Return matching documents as answers. |
| `questions` | `questions` | Enrich questions with matching documents. |

## As a tool

The configured tool-server name defaults to `milvus`.

| Function | Description |
| --- | --- |
| `search` | Searches the store for a non-empty `query`; accepts optional `top_k` and metadata `filter`, and returns matching content, metadata, and scores. |
| `upsert` | Adds or updates a non-empty `documents` array. Each document requires content and an object ID; it can provide an embedding and embedding model or use the bound embedding provider. |
| `delete` | Deletes documents for a non-empty `object_ids` array and returns the deleted count. |

`search` requires a bound embedding provider for semantic similarity search. The three functions return a failure object when their required input or an embedding cannot be obtained.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Profiles

Default: **Milvus cloud server** (`cloud`).

| Profile | Default host | Default port |
| --- | --- | --- |
| Milvus cloud server **(default)** | Empty | `443` |
| Your own Milvus server | `localhost` | `19530` |

## Configuration

Choose the cloud or local profile first, then configure the host, port, and collection. The profile controls how the runtime forms the connection: cloud mode uses HTTPS and the token, while local mode uses HTTP with the configured host and port. Most installations only need to name the destination collection and replace the cloud endpoint or the local defaults.

### Host, port, and API key

The driver trims whitespace, removes a leading `http://` or `https://`, and removes
trailing slashes from the host you enter. For cloud mode it always constructs an
HTTPS URI and supplies the trimmed API key as the Milvus token; for local mode it
constructs an HTTP URI from host and port without a token. Use the cloud profile
only for an endpoint that accepts that HTTPS/token connection. A connection error
at startup usually means that the selected profile does not match the endpoint,
or that the host was entered with an incompatible port.

### Collection

The collection is the destination for stored chunks. The save-time probe accepts names from 1 to 255 characters that begin with a letter or underscore and then use only letters, digits, or underscores. A collection is created when the first documents are added, using their vector size. Change it to isolate a corpus or embedding space; changing it points this node at a different store, rather than partitioning data within the old one. A save warning about the name means the collection will not start successfully until it follows the identifier rule.

### Similarity and retrieval score

The runtime accepts `L2`, `IP`, `COSINE`, `JACCARD`, `HAMMING`, or `BM25` as the similarity setting, defaulting to `COSINE`; another value stops initialization. It builds the vector index using this metric, so select the metric that matches the embeddings already in the collection before writing its first data. Changing it later does not rebuild an existing index.

The retrieval score defaults to `0.5` and filters converted result scores. For cosine results the driver converts the returned distance to `(distance + 1) / 2`; for other metrics it applies a sigmoid conversion. Raise the score when retrieved context is noisy or unrelated; lower it when the expected source material is absent. The tradeoff is recall versus the amount of weak context passed downstream, and a threshold can only be meaningful with the same metric used to create the collection.

### Write batch size and timeout

The driver uses a 60-second connection timeout and writes chunks in batches of
50 by default. These settings are read from the node configuration even though
most deployments can leave them alone. Increase a batch size only when a larger
write has been demonstrated to be reliable for the endpoint; reduce it when
bulk writes fail partway through or the service cannot absorb the requested
load. Increase the timeout for a slow but healthy remote service, rather than
using it to mask a host, port, or authentication mismatch.

### Tool Server Name

The tool-server name defaults to `milvus` and prefixes the three agent functions. Change it when multiple Milvus stores are connected to the same agent so their functions do not share a namespace.

## Authentication

For a cloud profile, provide the API key; the runtime passes it as the Milvus token. The local profile connects with the configured host and port without a token.

## Notes

### Search and document lifecycle

Semantic search requires an embedding and does not accept a non-zero offset. Keyword search uses the same metadata filters as retrieval. Re-ingesting an object deletes its existing chunks before the replacement chunks are inserted. The store can mark chunks deleted or active, and its default filters exclude marked-deleted chunks.

Milvus inserts chunks in batches of 50. A semantic search against an existing
collection also checks the embedding model before querying, so a model or vector
dimension mismatch is surfaced instead of silently mixing incompatible vectors.

The store maps metadata such as node, parent, object, permission, table, and
deletion state into Milvus filter expressions. Searches exclude soft-deleted
chunks unless a caller explicitly requests deleted content. This is useful when
one collection holds multiple sources: use the normal metadata filters to scope
retrieval instead of creating a collection per source unless you need hard data
separation.

### Rendering

Rendering retrieves an object's chunks in `chunkId` order and sends joined text to the callback in `renderChunkSize` groups. The node's document count is a count of stored vectors (chunks).

## Upstream docs

- [Milvus documentation](https://milvus.io/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `milvus.profile` | `string` | **Type of Milvus host**<br/>Connect to... | `"cloud"` |
| `milvus.provider` | `string` |  | const: `"milvus"` |
| `milvus.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'milvus' exposes tools as milvus.search / milvus.upsert / milvus.delete. Change this when running multiple Milvus nodes in the same pipeline so their tool names do not collide. | `"milvus"` |
| `vector.cloud.host` |  | Enter the server IP address e.g. <your-instance-name>.<region>.zillizcloud.com |  |
| `vector.cloud.port` |  |  | `443` |
| `vector.local.host` |  |  | `"localhost"` |
| `vector.local.port` |  |  | `19530` |

## Dependencies

- `environs`
- `marshmallow`
- `grpcio`
- `milvus-lite` `; platform_system != "Windows"`
- `pandas`
- `protobuf`
- `ujson`
- `pymilvus`
- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_milvus)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Pinecone

Route: /nodes/store_pinecone

# store_pinecone

A RocketRide vector-store node that stores embedded document chunks in a Pinecone index and retrieves them by semantic or keyword search. Use it when a pipeline or agent needs a Pinecone-backed document store.

## About Pinecone

Pinecone is a managed vector database for applications that search embedding
data. It organizes vectors into indexes and supports vector queries with
metadata filters. Use it when Pinecone is the service your application uses for
retrieval and you want RocketRide to store and query the same index.

## What it does

The node accepts embedded documents on its `documents` lane and can retrieve matching documents for incoming questions. It also exposes the store to an agent as tools. It creates a Pinecone index when documents are first added, and rejects incoming chunks without embeddings. Pick it over a self-managed store when the retrieval corpus belongs in a Pinecone index and its selected deployment mode is already part of the intended Pinecone setup.

The driver treats its Collection setting as the Pinecone index name. When it has to create that index, the supplied embeddings determine its dimension and the selected similarity setting determines its metric.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store embedded document chunks. |
| `questions` | `documents` | Return matching documents. |
| `questions` | `answers` | Return matching documents as answers. |
| `questions` | `questions` | Enrich questions with matching documents. |

## As a tool

The configured tool-server name defaults to `pinecone`.

| Function | Description |
| --- | --- |
| `search` | Searches the store for a non-empty `query`; accepts optional `top_k` and metadata `filter`, and returns matching content, metadata, and scores. |
| `upsert` | Adds or updates a non-empty `documents` array. Each document requires content and an object ID; it can provide an embedding and embedding model or use the bound embedding provider. |
| `delete` | Deletes documents for a non-empty `object_ids` array and returns the deleted count. |

`search` requires a bound embedding provider for semantic similarity search. The three functions return a failure object when their required input or an embedding cannot be obtained.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Profiles

Default: **Pinecone Serverless Dense Index** (`serverless-dense`).

| Profile | Deployment mode | Context |
| --- | --- | --- |
| Pinecone Pod-Based Index | `pod-based` | Creates a pod-based index. |
| Pinecone Serverless Dense Index **(default)** | `serverless-dense` | Creates a serverless index. |

## Configuration

Choose the profile that matches the target index, then provide the API key and collection name. New indexes use the selected profile; an existing index is checked against it during the save-time probe. The profile selection matters at creation time, while the key and collection select which existing Pinecone resource this node connects to.

### Index profile

`Pinecone Serverless Dense Index` is the default profile and creates an index
with the driver's serverless specification; `Pinecone Pod-Based Index` uses its
pod-based specification. Select the one that matches an index you already have,
or the kind of index you intend the node to create. The save-time probe compares
an existing index's specification with the selected profile and warns if they do
not agree; change the profile rather than assuming the node can change the
existing index's deployment type.

### Collection

The collection is the Pinecone index name and defaults to `rocketride`. Validation requires lowercase letters, numbers, and hyphens only; it rejects leading or trailing hyphens, consecutive hyphens, and names over 45 characters. Choose a name that identifies the one index this node will use. Change it to direct the node to a different Pinecone index, not to split a corpus inside one index. A validation warning flags a name that cannot be used by the configured service.

### Similarity and retrieval score

The runtime accepts `cosine`, `euclidean`, or `dotproduct` as the similarity setting, defaulting to `cosine`; another value stops initialization. This value becomes the metric when the driver creates an index, so make it agree with the embedding data and leave an existing index's metric alone. Choosing the wrong metric changes ranking and can make good matches appear weak.

Although the configuration value `score` is read with a default of `0.5`, the semantic-search filtering code reads the separately named `threshhold_search` attribute, whose initial value is `0.0`; therefore the configured score is not applied by this implementation. Do not rely on this setting to suppress weak Pinecone results. If relevance needs stricter filtering, apply a downstream constraint or use a store whose retrieval threshold is enforced until this implementation changes.

### API key

The API key is trimmed before the Pinecone client is created. It is needed both
to open the store and for the save-time probe that lists indexes. Rotate or
replace it when authentication fails rather than changing the collection name;
the probe can also reveal a key that reaches Pinecone but cannot inspect the
chosen index. Keep one key per intended service boundary when the node should
not see every index available to a broader application credential.

### Tool Server Name

The tool-server name defaults to `pinecone` and prefixes the three agent functions. Change it when multiple Pinecone stores are connected to the same agent so their functions do not share a namespace.

## Authentication

Set the API key for the selected Pinecone profile. The runtime creates its client with that key, and the save-time probe uses it to list indexes and check an existing index's deployment mode.

## Notes

### Search and document lifecycle

Semantic search requires an embedding and does not accept a non-zero offset. Keyword search adds a content filter to the metadata filters. Re-ingesting an object deletes its existing chunks before replacement chunks are upserted. The store can mark chunks deleted or active, and its default filters exclude marked-deleted chunks.

The node retrieves semantic results with the requested limit (or 25 when no
limit is supplied). It runs the collection-existence and embedding-model checks
before searching, which makes a missing index or incompatible model fail before
results are returned.

Index creation is intentionally opinionated: the serverless branch supplies an
AWS `us-east-1` specification, while the pod branch supplies one `p1.x1` pod in
`us-east1-gcp`. Those are creation-time defaults in this node, not settings
that alter an existing index. Choose an already compatible index when those
defaults are not appropriate for the intended deployment.

### Rendering and paths

Rendering retrieves an object's chunks in `chunkId` order and sends joined text to the callback in `renderChunkSize` groups. For path listing, the driver requests enough records for the requested offset and limit, then slices the results locally.

Metadata filters include document identity, parent path, permissions, table
information, and deletion state. The driver defaults `isDeleted` to false in
its Pinecone filter, so a soft-deleted source does not appear in normal
retrieval. That makes reactivating or explicitly including deleted material a
separate caller choice rather than an accidental result of broad searching.

## Upstream docs

- [Pinecone documentation](https://docs.pinecone.io/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `pinecone.collection` | `string` | **Collection**<br/>Enter the name of the collection. Accepted are: Lower case, alphanumeric characters, hyphens | `"rocketride"` |
| `pinecone.profile` | `string` | **Type of Pinecone Connection**<br/>Connect to... | `"pod-based"` |
| `pinecone.provider` | `string` |  | const: `"pinecone"` |
| `pinecone.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'pinecone' exposes tools as pinecone.search / pinecone.upsert / pinecone.delete. Change this when running multiple Pinecone nodes in the same pipeline so their tool names do not collide. | `"pinecone"` |

## Dependencies

- `pinecone`
- `pinecone-plugin-assistant`
- `pinecone-plugin-interface`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_pinecone)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# PostgreSQL (pgvector)

Route: /nodes/store_postgres

# store_postgres

A RocketRide vector-store node that stores embedded document chunks in PostgreSQL with pgvector and retrieves them by semantic or keyword search. Use it when a pipeline or agent needs vector retrieval in a PostgreSQL database.

## About PostgreSQL

PostgreSQL is a relational database that stores structured data and supports SQL
queries. The pgvector extension adds a vector data type and vector-distance
operators to PostgreSQL. This combination is useful when vector retrieval should
live beside the relational data and operational practices a team already uses.

## What it does

The node accepts embedded documents on its `documents` lane and can retrieve matching documents for incoming questions. It also exposes the store to an agent as tools. The target table is created when documents are first added, and semantic retrieval requires question embeddings. Pick it over a dedicated vector database when the corpus should remain in a PostgreSQL database and the operator can provide pgvector there.

The created table contains content, document metadata, the embedding, its model name, and its vector size. That makes one table the store for both vector retrieval and keyword lookup, while the configured database retains PostgreSQL's normal connection and access controls.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store embedded document chunks. |
| `questions` | `documents` | Return matching documents. |
| `questions` | `answers` | Return matching documents as answers. |
| `questions` | `questions` | Enrich questions with matching documents. |

## As a tool

The configured tool-server name defaults to `postgres`.

| Function | Description |
| --- | --- |
| `search` | Searches the store for a non-empty `query`; accepts optional `top_k` and metadata `filter`, and returns matching content, metadata, and scores. |
| `upsert` | Adds or updates a non-empty `documents` array. Each document requires content and an object ID; it can provide an embedding and embedding model or use the bound embedding provider. |
| `delete` | Deletes documents for a non-empty `object_ids` array and returns the deleted count. |

`search` requires a bound embedding provider for semantic similarity search. The three functions return a failure object when their required input or an embedding cannot be obtained.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Configuration

Enter the PostgreSQL connection details and choose the table that will hold the chunks. The local profile supplies the initial values, including a retrieval score of `0.5` and `cosine` similarity. Start by confirming that these credentials reach a database where the `vector` type is available; the save-time probe opens a short-lived connection, runs `SELECT 1`, and tests that type before this node is used in a pipeline.

### Connection and database

Host, port, user, password, and database are passed directly to the PostgreSQL
client. Use a dedicated database or role when you want the retrieval corpus to
have separate ownership from other application tables. Connection or permission
errors during the save-time probe point to these fields; an error about the
`vector` type means pgvector is not available in the selected database.

### Table

The Table field names the table used for vectors; its default is `rocketride`. It must be a valid unquoted PostgreSQL identifier: at most 63 characters, starting with a letter or underscore, and thereafter containing only letters, digits, or underscores. The driver also accepts the legacy `collection` key, but the panel uses Table.

Change the table when a corpus needs its own physical store. The runtime uses the
name in its SQL statements and does not quote it, which is why punctuation,
spaces, and a leading digit are rejected instead of being escaped. A valid new
name produces a new table at first ingest; it does not migrate rows from the
old table.

### Similarity Metric

Choose `cosine`, `l2`, or `inner_product`; the runtime maps them to PostgreSQL's vector-distance operators and rejects any other value. Use the setting that matches how the vectors are meant to be compared, because it determines ranking for semantic searches. `cosine` maps to `<=>`, `l2` to `<->`, and `inner_product` to `<#>`.

The retrieval score defaults to `0.5`, and the driver always removes results
whose converted score is below its hard `0.20` floor. Raise the configured
threshold to give downstream prompts fewer, more selective documents; lower it
when relevant documents are missing. The conversion differs by metric—cosine
uses `1 - distance`, L2 uses `1 / (1 + distance)`, and inner product negates
the returned distance—so do not carry a score threshold across a metric change
without retesting the retrieval quality.

### Retrieval and embedding compatibility

The first write creates the table with a vector column sized for its incoming
embedding. Later semantic searches check the requested embedding model against
the existing collection before executing. Keep documents produced by compatible
embedding configurations in the same table; a model or vector-size mismatch is
a sign to create or select a separate table, rather than to treat the failure
as an ordinary relevance-tuning issue.

### Tool Server Name

The tool-server name defaults to `postgres` and prefixes the three agent functions. Change it when multiple PostgreSQL stores are connected to the same agent so their functions do not share a namespace.

## Authentication

Provide the configured PostgreSQL host, port, user, password, and database. The save-time probe opens a PostgreSQL connection with those values and verifies that the database supports the `vector` type.

## Notes

### Search and document lifecycle

Semantic search requires an embedding. Keyword search performs a `LIKE` match on content with the metadata filters. Re-ingesting an object deletes its existing rows before replacement chunks are inserted. The store can mark chunks deleted or active, and its default filters exclude marked-deleted chunks.

Semantic search orders by the chosen pgvector distance operator and checks that
the stored embedding model is compatible before searching. Unlike the other
paths, it cannot take a non-zero result offset. This matters for callers that
try to paginate semantic results: use a limit or a separate retrieval strategy
instead of expecting SQL-style offset pagination.

The metadata filters are translated to SQL predicates for node, parent,
permissions, object IDs, chunk IDs, table data, and deletion state. Normal
searches exclude marked-deleted rows. Use those filters to narrow one shared
table to an eligible corpus; changing the table name is for an independently
managed store, not the routine way to restrict a query.

### Rendering

Rendering retrieves an object's chunks in `chunkId` order and sends joined text to the callback in `renderChunkSize` groups. The node's document count is a count of rows in the table.

The runtime removes an object's existing rows and commits that deletion before
it inserts the replacement chunks. Retain a source of truth that can be
ingested again: if a replacement write fails, the previous rows have already
been removed rather than preserved as a fallback copy.

## Upstream docs

- [PostgreSQL documentation](https://www.postgresql.org/docs/)
- [pgvector documentation](https://github.com/pgvector/pgvector)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `postgres.profile` | `string` | **Type of PostgreSQL host**<br/>Connect to... | `"local"` |
| `postgres.provider` | `string` |  | const: `"postgres"` |
| `postgres.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'postgres' exposes tools as postgres.search / postgres.upsert / postgres.delete. Change this when running multiple Postgres nodes in the same pipeline so their tool names do not collide. | `"postgres"` |
| `vector.collection` | `string` | **Table**<br/>Name of the table to store vectors. | `"rocketride"` |
| `vector.local.database` | `string` | **Database**<br/>Name of the database | `"postgres"` |
| `vector.local.host` |  | **Host**<br/>Host name or IP address of the PostgreSQL server | `"your-postgres-host.example.com"` |
| `vector.local.password` | `string` | **Password**<br/>Password to connect to the PostgreSQL server |  |
| `vector.local.port` |  | **Port**<br/>Port number of the PostgreSQL server | `5432` |
| `vector.local.user` | `string` | **User**<br/>User to connect to the PostgreSQL server | `"postgres"` |
| `vector.similarity` | `string` | **Similarity Metric**<br/>The similarity metric to use for vector search | `"cosine"` |

## Dependencies

- `psycopg2-binary`
- `pgvector`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_postgres)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Qdrant

Route: /nodes/store_qdrant

# store_qdrant

A RocketRide vector store node backed by Qdrant, for storing embedded documents and retrieving them by semantic or keyword search.

## About Qdrant

Qdrant is an open-source vector database built for similarity search at scale.
It stores high-dimensional embeddings and returns the closest matches to a
query vector, with filtering and payload support, and runs self-hosted or as a
managed service (Qdrant Cloud).

## What it does

Stores pre-embedded document chunks in a Qdrant collection and retrieves them by semantic (vector) similarity or full-text keyword search. Works with both self-hosted Qdrant and Qdrant Cloud. The node is also a tool node (`classType: ["store", "tool"]` with the `invoke` capability), so agents in the same pipeline can call its `search`, `upsert`, and `delete` tools directly.

Uses the official **`qdrant_client`** Python SDK over REST (`prefer_grpc=False`, 60-second timeout). If the configured host has no scheme, `http://` is prepended automatically.

Documents must be run through an embedding node before reaching this node: the store does not compute embeddings on the data lane and raises an error if a chunk arrives without one.

The collection is created automatically on first write, including payload indexes on `meta.nodeId`, `meta.objectId`, `meta.parent`, `meta.permissionId`, `meta.isDeleted`, `meta.isTable`, and a full-text index on `content` (word tokenizer, lowercase, token length 2-15). Writing chunk 0 of an object first deletes all existing points with the same `objectId`, so re-ingesting a document replaces it rather than duplicating it. Upserts are batched: a flush happens every 500 points or when the accumulated payload exceeds the payload limit (32 MiB by default).

## Example pipelines

**End-to-end RAG pipeline**

`webhook → parse → preprocessor_langchain → embedding_transformer → qdrant`

`chat → embedding_transformer → qdrant → prompt → llm_openai → response_answers`

<div align="center">

![The Qdrant node on the canvas storing embedded documents and serving retrieval for a RAG pipeline](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

Documents are parsed, chunked, embedded, and stored in Qdrant. Chat questions
use the same embedding and Qdrant retrieval path before the prompt and LLM
produce an answer.

**Question answering over stored documents**

`webhook → embedding_transformer → store_qdrant → llm_anthropic → response`

The question is embedded, this node enriches it with the most relevant stored
documents (`questions` → `questions` lane), and the LLM answers from that
retrieved context.

**Agent with searchable memory**

An agent with this node connected as a tool: it calls `search` for context
when it decides it needs it, and `upsert`s new facts as it works — a knowledge
base the agent reads and writes on demand instead of retrieval running on
every question.

## Lanes

| Lane in     | Lane out    | Description                                                      |
| ----------- | ----------- | ---------------------------------------------------------------- |
| `documents` | —           | Ingest pre-embedded documents into the collection                |
| `questions` | `documents` | Return matching documents                                        |
| `questions` | `answers`   | Return matching documents as an answer                           |
| `questions` | `questions` | Enrich the question with matching documents for downstream nodes |

## As a tool

Tools are exposed under the configured `serverName` namespace (default `qdrant`).

### `search`

Semantic similarity search over the collection.

| Argument | Type    | Description                                                               |
| -------- | ------- | ------------------------------------------------------------------------- |
| `query`  | string  | Required. The search query text.                                          |
| `top_k`  | integer | Maximum results to return (default 10, capped at 100).                    |
| `filter` | object  | Optional metadata filter; supports `objectId`, `nodeId`, and `parent` keys. |

Requires an embedding provider bound to the node (the embedding sub-block in the configuration). If semantic search fails, the tool falls back to keyword search. Returns `{"results": [{content, score, metadata}], "total": n}` on success or `{"success": false, "error": "..."}` on failure.

### `upsert`

Add or update documents in the collection.

Each item in the `documents` array requires `content` and `object_id` (used for deduplication) and may include `metadata` (keys `nodeId`/`parent`/`chunkId` are stored; defaults `"vectordb_tool"`, `"/"`, `0`), plus optional pre-computed `embedding` and `embedding_model` to skip automatic embedding. Without a pre-computed vector the node's bound embedding provider is used; if none is configured the call fails. Returns `{"success": true, "count": n, "skipped": n}`.

### `delete`

Delete documents by ID.

Takes a required `object_ids` string array and removes all points whose `meta.objectId` matches. Returns `{"success": true, "deleted_count": n}`.

## Profiles

Default: **Qdrant cloud server** (`cloud`).

| Profile                         | Default host                   | Default port |
| ------------------------------- | ------------------------------ | ------------ |
| Qdrant cloud server **(default)** | _(your Qdrant Cloud endpoint)_ | `6333`       |
| Your own Qdrant server          | `localhost`                    | `6333`       |

## Configuration

Choose the host type (cloud or self-hosted), point the node at your Qdrant
endpoint, and name the collection. Most deployments only ever touch the host,
API key, and collection fields.

### Tool Server Name

Prefix for the tool names agents see: `qdrant` exposes `qdrant.search`,
`qdrant.upsert`, `qdrant.delete`. Change it when running multiple Qdrant nodes
in the same pipeline — give each a distinct name so their tool names do not
collide and the agent can tell the stores apart.

## Authentication

Self-hosted Qdrant typically needs no credentials: leave `apikey` empty. For Qdrant Cloud, set `host` to your instance endpoint (`<instance>.<region>.qdrant.io`) and provide the cluster API key in `apikey`. The key is passed as the `api_key` argument of the Qdrant client.

## Notes

### Scoring and relevance

Raw Qdrant scores are rescaled to `[0, 1]` before filtering. For `Cosine` similarity the rescaling is `(score + 1) / 2`; for other metrics a sigmoid is applied. Results below a hard floor of `0.20` are always dropped as noise, and the configured retrieval `score` threshold is applied on top of that in the rescaled space (applied by the base store, not passed to Qdrant as `score_threshold`).

The similarity metric defaults to `Cosine`; `Euclid`, `Dot`, and `Manhattan` are also accepted. Any other value raises a configuration error at startup. Semantic search uses exact search (`SearchParams(exact=True)`) and does not support a non-zero result offset; keyword search and plain filtered gets use Qdrant scroll and do support offsets.

Deletion of source files is handled as a soft delete: chunks are marked `meta.isDeleted: true` and excluded from all searches by default. They are only returned when the filter explicitly asks for deleted documents. A document that reappears is marked active again.

### Save-time validation

When the configuration is saved, the node validates it with a fast read-only probe (`get_collections`, 10-second timeout):

- The collection name must match `^[A-Za-z0-9._-]{1,255}$`: no `/` or spaces.
- Port `0` is rejected explicitly.
- Scheme is inferred when the host has none: `http` for `localhost` or `127.*`, `https` for `*.qdrant.io` hosts or port `443`.
- Qdrant Cloud with a wrong port does not return an HTTP status: the probe simply times out after 10 seconds and surfaces a timeout warning.

### Language support and rehydration

- Qdrant's full-text tokenizer does not support all languages out of the box. Chinese, Japanese, and Korean are not enabled in the default Qdrant build and require building Qdrant from source with the `--features multiling-chinese,multiling-japanese,multiling-korean` flags. This only affects keyword search over the `content` payload; semantic search uses the embeddings you provide and is unaffected.
- Rendering a full document rehydrates all of its chunks in `chunkId` order, fetching them in batches of up to 32 MiB and joining them, so out-of-order storage is handled transparently.

## Upstream docs

- [Qdrant documentation](https://qdrant.tech/documentation/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `qdrant.profile` | `string` | **Type of Qdrant host**<br/>Connect to... | `"cloud"` |
| `qdrant.provider` | `string` |  | const: `"qdrant"` |
| `qdrant.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'qdrant' exposes tools as qdrant.search / qdrant.upsert / qdrant.delete. Change this when running multiple Qdrant nodes in the same pipeline so their tool names do not collide. | `"qdrant"` |
| `vector.cloud.host` |  | Enter the server IP address e.g. <your-instance-name>.<region>.qdrant.io |  |
| `vector.cloud.port` |  |  | `6333` |
| `vector.local.host` |  |  | `"localhost"` |
| `vector.local.port` |  |  | `6333` |

## Dependencies

- `grpcio`
- `grpcio-tools`
- `portalocker`
- `pydantic`
- `urllib3`
- `httpx`
- `qdrant_client` `==1.17.1`
- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_qdrant)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Weaviate

Route: /nodes/store_weaviate

# store_weaviate

A RocketRide vector-store node that stores embedded document chunks in Weaviate and retrieves them by semantic or keyword search. Use it when a pipeline or agent needs a Weaviate-backed document store.

## About Weaviate

Weaviate is a vector database for storing data with embeddings and structured
properties. It supports vector search and filtered retrieval over collections.
Use it when a team has selected Weaviate for its retrieval data and wants a
RocketRide pipeline or agent to use the same collection.

## What it does

The node accepts embedded documents on its `documents` lane and can retrieve matching documents for incoming questions. It also exposes the store to an agent as tools. A collection is created when documents are first added, and incoming chunks without embeddings are rejected. Pick it over the sibling vector stores when Weaviate is the database the workload already operates, including when the node should use Weaviate's local REST and gRPC connection or its cloud connection.

The driver creates the collection without a vectorizer and gives it an HNSW vector index. It stores document content and metadata as collection properties, allowing semantic or keyword retrieval with the same metadata filters.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | — | Store embedded document chunks. |
| `questions` | `documents` | Return matching documents. |
| `questions` | `answers` | Return matching documents as answers. |
| `questions` | `questions` | Enrich questions with matching documents. |

## As a tool

The configured tool-server name defaults to `weaviate`.

| Function | Description |
| --- | --- |
| `search` | Searches the store for a non-empty `query`; accepts optional `top_k` and metadata `filter`, and returns matching content, metadata, and scores. |
| `upsert` | Adds or updates a non-empty `documents` array. Each document requires content and an object ID; it can provide an embedding and embedding model or use the bound embedding provider. |
| `delete` | Deletes documents for a non-empty `object_ids` array and returns the deleted count. |

`search` requires a bound embedding provider for semantic similarity search. The three functions return a failure object when their required input or an embedding cannot be obtained.

`search` accepts an optional `filter` object honoring only `objectId`, `nodeId` and `parent`; any other key is rejected. `upsert` accepts an optional `metadata` object storing `nodeId`, `parent` and `chunkId`, defaulting to `"vectordb_tool"`, `"/"` and `0` respectively.

## Profiles

Default: **Your own Weaviate server** (`local`).

| Profile | Default host | Default port |
| --- | --- | --- |
| Your own Weaviate server **(default)** | `localhost` | `8080` |
| Weaviate cloud server | Empty | `443` |

## Configuration

Choose the cloud or local profile, then configure the host and collection. The cloud profile connects to the configured cluster URL; the local profile also uses the configured gRPC port, which defaults to `50051`. The profile changes the connection method, so decide which service you are connecting to before adjusting search settings.

### Host, ports, and API key

The runtime trims whitespace, strips a leading `http://` or `https://`, and
removes trailing slashes from the entered host. Cloud mode calls the cloud
connection with the API key. Local mode passes the configured REST and gRPC
ports, and uses the API key only when one is supplied. Use the local profile for
a service that exposes both local endpoints; a startup or validation failure can
mean the selected profile does not match the service, or that the local gRPC
port is unavailable.

### Collection

The collection is the destination for stored chunks and is created with no vectorizer and an HNSW vector index when first needed. The save-time probe requires a name that begins with an uppercase letter and then contains only letters, digits, or underscores. Change it to isolate a corpus or embedding space; it directs the node to a different collection rather than creating a logical partition. A name that begins lowercase or contains punctuation stops configuration before the pipeline starts.

### Similarity and retrieval score

The runtime accepts `cosine`, `dot`, `l2-squared`, `hamming`, or `manhattan` as the similarity setting, defaulting to `cosine`; another value stops initialization. It passes the selected value to the HNSW index when it creates a collection, so make the choice match the embedding space before the first ingest. Changing the setting does not recreate an existing collection's index.

The retrieval score defaults to `0.5`, while the conversion code also drops results below a hard `0.20` before returning them. Raise the configured threshold if weak documents crowd the context; lower it when expected material is omitted, remembering that nothing below `0.20` can be returned. Cosine scores are converted as `(distance + 1) / 2`; the other supported metrics use a sigmoid conversion, so threshold values are not directly comparable after a metric change.

### Connection timeouts

The client uses separate initialization, query, and insert timeouts of 30, 60,
and 120 seconds. They are fixed by this node's implementation, so a slow
connection cannot be tuned from this panel. If only large writes time out while
queries work, reduce the ingest workload or investigate the service path; if
all operations time out, start with the selected profile, host, ports, and API
key instead of treating it as a retrieval-score problem.

### Tool Server Name

The tool-server name defaults to `weaviate` and prefixes the three agent functions. Change it when multiple Weaviate stores are connected to the same agent so their functions do not share a namespace.

## Authentication

For a cloud profile, provide the API key; the runtime uses it for the cloud connection. For a local profile, the key is optional: an empty key connects without credentials, while a supplied key is used for local authentication.

## Notes

### Search and document lifecycle

Semantic search requires an embedding and does not accept a non-zero offset. Keyword search matches content with the metadata filters. Re-ingesting an object deletes its existing chunks before replacement chunks are added. The store can mark chunks deleted or active, and its default filters exclude marked-deleted chunks.

Before semantic search, the driver checks that the collection is compatible with
the query's embedding model. The collection's batch import reports an error if
any objects failed to import, instead of silently treating a partial write as a
successful ingest.

Filters cover node, parent, permissions, object IDs, chunks, table fields, and
the deletion flag. Normal queries add `isDeleted = false`, so marked-deleted
content is hidden unless a caller requests it. This lets a shared collection be
scoped at query time without using collection names as routine access filters.

### Rendering

Rendering retrieves an object's chunks in `chunkId` order and sends joined text to the callback in `renderChunkSize` groups. The node's document count is a count of stored vectors (chunks).

When an object is re-ingested, the driver deletes its existing objects before
adding replacements through Weaviate's dynamic batch API. A batch with failed
objects raises an error after the batch ends. Keep the original source
available for a retry, since the replacement behavior is not an all-or-nothing
transaction across the prior objects and the new batch.

## Upstream docs

- [Weaviate documentation](https://docs.weaviate.io/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `vector.cloud.host` |  | Enter the server IP address e.g. <your-instance-name>.weaviate.cloud |  |
| `vector.cloud.port` |  |  | `443` |
| `vector.local.grpc_port` |  |  | `50051` |
| `vector.local.host` |  |  | `"localhost"` |
| `vector.local.port` |  |  | `8080` |
| `weaviate.profile` | `string` | **Type of Weaviate host**<br/>Connect to... | `"local"` |
| `weaviate.provider` | `string` |  | const: `"weaviate"` |
| `weaviate.serverName` | `string` | **Tool Server Name**<br/>Namespace for agent-facing tool names, e.g. 'weaviate' exposes tools as weaviate.search / weaviate.upsert / weaviate.delete. Change this when running multiple Weaviate nodes in the same pipeline so their tool names do not collide. | `"weaviate"` |

## Dependencies

- `authlib`
- `grpcio`
- `grpcio-health-checking`
- `grpcio-tools`
- `httpx`
- `pydantic`
- `requests`
- `validators`
- `weaviate-client` `>=4.20.0`
- `numpy`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/store_weaviate)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Summarization: LLM

Route: /nodes/summarization

# summarization

A RocketRide filter node that uses an LLM to distill incoming text into a summary, key points, and named entities.

## What it does

Accumulates all text (and table content) of each object flowing through the pipeline, then on close splits the full document into chunks and asks the connected LLM to extract three things from each chunk: a concise summary, a list of key points, and the most significant named entities (people, organizations, products, events, dates, locations). The LLM is instructed to respond as JSON.

Chunking uses LangChain's `RecursiveCharacterTextSplitter`, sized to the connected LLM's context length and measured with the LLM's own token counter. The token budget of the instruction prompt itself is accounted for, so each chunk plus the prompt always fits the model's context window.

Only the first `numberOfSummaries` chunks (default 2) are summarized; the rest of the document is ignored. Each of the three extraction sections can be disabled individually by setting its config field to `0`. Choose this node when one LLM pass should produce all three outputs; use a simpler text transformation when no LLM-generated summary is needed.

Output is emitted only on lanes that actually have a downstream listener: plain formatted text on the `text` lane, and/or one structured document per section on the `documents` lane.

## Connections

| Connection | Required | Description |
|---|---|---|
| `llm` | yes | LLM used for extraction and for its context length and token counter. |

## Lanes

| Lane in | Lane out | Description |
|---------|----------|-------------|
| `text` | `text` | Summarized output as plain text: a summary block, a `Key Points:` bullet list, and an `Entities:` bullet list. Sections that are disabled or empty are omitted. |
| `text` | `documents` | Summarized output as structured documents: each summary, key-point list, and entity list becomes its own `Doc` with an incrementing `chunkId` in its metadata. |

The declared input lane is `text`; the node accumulates that text for the
current object before it invokes the LLM at close.

## Configuration

The default configuration summarizes two chunks, targets 1,500 words per
summary, 250 words per key point, and extracts 25 entities. Tune the limits to
the length and density of the source material; the splitter uses the connected
LLM's token counter and context length, not a fixed character limit.

### Number of chunks to summarize

`numberOfSummaries` limits how many chunks are sent to the LLM after splitting.
Keep the default when the opening chunks are representative. Raise it to cover
longer documents, accepting more LLM calls; set it to `0` when no chunks should
be processed.

### Summary, key-point, and entity limits

`numberOfSummaryWords`, `numberOfKeyPointWords`, and `numberOfEntities` control
the instructions passed to the LLM. Set a value to `0` to omit that section.
Use smaller limits for compact indexing output and larger limits when downstream
readers need more detail. These limits do not change how many source chunks are
selected; that is controlled by `numberOfSummaries`.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `summarization.numberOfEntities` | `number` | **Number of entities to extract from the document. Set to 0 to disable entity extraction.** |  |
| `summarization.numberOfKeyPointWords` | `number` | **Number of words in each key point. Set to 0 to disable key points.** |  |
| `summarization.numberOfSummaries` | `number` | **Number of chunks to summarize after the document is split** |  |
| `summarization.numberOfSummaryWords` | `number` | **Number of words in each summary. Set to 0 to disable summaries.** |  |
| `summarization.profile` | `string` |  | `"default"` |

## Dependencies

- `langchain`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/summarization)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Telegram Bot

Route: /nodes/telegram

# telegram

A RocketRide source node that connects a Telegram bot to a pipeline; choose it when a bot’s messages and media should initiate pipeline work and receive a reply.

## About Telegram

Telegram is a messaging service with a Bot API. This node uses that API to receive updates, download attached files, and send text replies to the originating chat.

## What it does

Telegram receives text or supported attachments, sends each item to the matching pipeline lane, and returns the first pipeline answer to the sender. Choose it instead of a generic webhook when the input and response should follow Telegram’s bot update and reply flow. It supports polling for outgoing connections to the Bot API and webhook delivery for a publicly reachable callback.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `_source` | `text` | Text messages are written as text. |
| `_source` | `image` | Photos are downloaded and written as JPEG image data. |
| `_source` | `audio` | Audio files and voice messages are written as audio data. |
| `_source` | `video` | Videos are written as video data. |
| `_source` | `tags` | Documents are written as tagged data for a downstream parser. |

## Configuration

Set a bot token, then choose the delivery mode that your deployment can support. Polling is the default and needs no public callback. Webhook mode additionally needs a reachable callback URL.

### Connection Mode

`polling` is the default. It clears any previously registered webhook, repeatedly calls Telegram’s update endpoint with a 30-second server timeout and up to 100 updates, and retries after errors; use it where the pipeline process can make outbound requests but cannot expose a public route.

Choose `webhook` only when Telegram can POST to a public HTTPS URL that reaches this pipeline. The node registers that URL and derives its local POST route from its path (or `/telegram/webhook` when the URL has no path). In webhook mode, incoming requests without the generated secret header are rejected with HTTP 403; malformed request bodies return HTTP 500.

### Webhook URL

This value is used only in webhook mode. Provide the complete public URL, including the path your reverse proxy or tunnel forwards to the pipeline’s shared web-server port. Leaving it empty makes webhook registration fail; use polling when a public route is unavailable.

## Authentication

Set **Bot Token** to the token for the bot that should receive updates. The node uses it in its Bot API requests and displays only its final six characters in the monitor information. A missing token aborts startup after publishing a missing-token status.

## Notes

### Message handling and replies

Both new and edited messages are considered. Unsupported updates are ignored. Files reported larger than 20 MiB are skipped before download, and download or pipeline failures return no reply while recording failed bytes in the monitor.

Only the first answer in the pipeline response is sent back. Replies longer than 4,096 characters are truncated with an ellipsis; errors from Telegram’s send operation are logged and do not crash the update handler.

### Webhook reachability

Webhook delivery uses the pipeline’s shared web server and requires the process entry point to provide it. The implementation notes that a multi-tenant cloud engine cannot expose an individual pipeline subprocess port to Telegram, so use polling there; the local POST route can still be used by a self-hosted deployment that forwards it publicly.

## Upstream docs

- [Telegram Bot API](https://core.telegram.org/bots/api)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `Pipe.source.parameters` |  | **Bot Configuration** |  |
| `telegram.botToken` | `string` | **Bot Token**<br/>Telegram bot token from @BotFather (e.g. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11) |  |
| `telegram.mode` | `string` | **Connection Mode**<br/>Polling works anywhere without a public URL. Webhook requires a public HTTPS endpoint. | `"polling"` |
| `telegram.webhookUrl` | `string` | **Webhook URL**<br/>Public HTTPS URL Telegram will POST updates to (e.g. https://your-server.com/telegram/webhook). Required for webhook mode. |  |

## Dependencies

- `aiohttp` `>=3.14.1`
- `requests`
- `fastapi`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/telegram)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Text Output

Route: /nodes/text_output

# text_output

A RocketRide target node that writes a pipeline object’s text to an SMB share; choose it when the destination is network storage rather than the engine’s local filesystem.

## About SMB

SMB is the network file-sharing protocol used by this node to reach its target. The implementation connects to the configured server and share through Python SMB client libraries.

## What it does

The node consumes text, writes non-empty output as UTF-8 `.txt` files on the configured SMB share, and produces no downstream lane. It retains the source-derived directory structure and skips unchanged objects, making it appropriate for incremental exports to a reachable share. Choose `local_text_output` instead when the desired destination is the pipeline host’s local filesystem rather than a network server.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | — | Text content to write to the SMB share. |

## Configuration

Configure the SMB server and destination path first. Authentication is optional for a guest-accessible share; anonymization settings only matter when sensitive content should be masked before export.

### SMB destination

The node validates the server name as a hostname or IP address and requires a store path between 3 and 256 characters. The first store-path segment identifies the share; it may be followed by folders. The path cannot be rooted, contain empty or dot folders, or contain `<>:"|?*`.

At action startup, the node configures SMB credentials only when both username and password are supplied, verifies the share, and checks the full destination path. Use a `DOMAIN\\user` username when credentials are needed; supplying only one credential fails validation. Choose a share that the running task can reach, because configuration validation deliberately does not make the SMB connection.

### Anonymization

With anonymization off (the default), the node writes the incoming text unchanged. Turn it on when the pipeline’s classification output must be masked before the file is written: the node requests classification and applies the `anonymize_text` filter. The masking character defaults to `█`; it must be exactly one character when anonymization is enabled.

Enable **anonymize all** when every classified match should become a fixed three-character mask instead of a character-for-character replacement. Changing the classification policies, masking character, or this setting changes the stored settings key and causes all objects to be transformed again, including objects that would otherwise be unchanged.

## Authentication

Credentials are optional. For a protected SMB share, set both username and password; the username must contain a domain-like prefix and the password may be at most 127 characters. For a guest-accessible share, leave both blank. Credentials are registered against the configured server only, so two endpoints pointing at different servers never overwrite each other's credentials.

Configuration validation probes the target, and treats the two failure kinds differently. A rejected or expired credential, a share the account may not enter, or a share name that does not exist fails validation, because each is a configuration mistake to fix. A target that is merely unreachable — no route, refused connection, timeout, dropped transport — is reported as a warning and does not reject the configuration: validation also runs on the Platform host, which often has no network path to the customer's share, and a transient failure such as the share being locked by another process is treated the same way. The store path itself is exempt, since it is created on first write; only the share it lives under has to be reachable and permitted.

## Limitations

This node is excluded from SaaS and remote deployments. It opens a direct SMB connection from the running task to the configured server, so the task environment must have network access to that share and the required SMB dependencies; use a deployment located where that share is reachable.

## Notes

### Incremental writes

For each object, the node derives a target path, hash-truncates over-long path components, and records a transformation key containing object flags, the source change key, and the target file’s modification time and size. An object is skipped when that key still matches and anonymization settings have not changed. Empty text is skipped, while write or SMB errors are stored as the object’s completion error.

## Upstream docs

- [smbprotocol project](https://github.com/jborean93/smbprotocol)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `anonymize` |  |  |  |
| `text_output.password` | `string` | **Password**<br/>Password for the SMB user name above. |  |
| `text_output.server` | `string` | **Server Name**<br/>Host name or IP address of the SMB server hosting the share, e.g. files.example.com or 10.0.0.12. |  |
| `text_output.username` | `string` | **User Name**<br/>User name used to authenticate against the SMB share. Leave the user name and password empty to connect with the engine's own credentials. |  |

## Dependencies

- `cffi`
- `cryptography`
- `pycparser`
- `pyspnego`
- `smbprotocol`
- `sspilib`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/text_output)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Thumbnail

Route: /nodes/thumbnail

# thumbnail

A RocketRide image filter that turns an existing image or Image document into a
compact 128×128 PNG thumbnail. Choose it when downstream preview, storage, or
vision work needs a fixed-size image rather than the source resolution.

## About Pillow

Pillow is a Python imaging library. This node uses the shared Pillow-based image
helper to decode input images, resize them, crop a thumbnail, and encode PNG
output.

## What it does

The node accepts raw images on the `image` lane and Image documents on the
`documents` lane, then produces thumbnail versions for the lanes declared by the
pipeline. It is a pure transform with no configuration or agent-tool surface.
Use it after an image is already available and you need a compact, consistently
sized derivative; it does not select frames or acquire images from another
source.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `image` | `documents` | Emit the thumbnail as an Image document. |
| `image` | `image` | Emit the thumbnail as a raw PNG image stream. |
| `documents` | `documents` | Replace each supported Image document with its thumbnail. |

## Configuration

This node has no configuration fields. Its output size is fixed by the
implementation, so connect the input and only attach the output lane or lanes
your pipeline needs.

## Notes

### Thumbnail output

The shared image helper works on a copy, progressively reduces very large
images, preserves aspect ratio during its resize step, then center-crops the
result to exactly 128×128 pixels. Both raw-image and document paths encode the
result as PNG; the raw-image output therefore announces `image/png` even if the
input used a different MIME type.

### Raw image streams

The `image` lane buffers the input from `BEGIN` through `WRITE` and processes
it at `END`. If `documents` is connected, it emits one base64-encoded `Image`
document with new thumbnail metadata and preserved source provenance. If
`image` is connected, it emits an enriched PNG stream with the thumbnail width
and height. When both lanes have listeners, it emits both forms.

### Image documents

Only documents whose `type` is `Image` and whose `page_content` is non-empty
are processed. Unsupported documents, empty content, and document-level decode
or processing errors produce a warning and are skipped, while the node
continues processing the remaining documents in the batch. The emitted document
keeps a copy of the original metadata and adds an image-source layer for the
new thumbnail.

## Upstream docs

- [Pillow documentation](https://pillow.readthedocs.io/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/thumbnail)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Apify

Route: /nodes/tool_apify

# tool_apify

A RocketRide tool node for an agent that needs to run an Apify Actor or retrieve a dataset's items, with per-run item, time, and cost bounds.

## About Apify

Apify is the external service this node accesses through its Python client. Its Actor runs can produce a default dataset, and this node can also read a dataset that already exists.

## What it does

Use this node when an agent needs Actor-produced structured items or an existing Apify dataset. It exposes agent tools only—there are no pipeline lanes—and waits for an Actor run before reading its default dataset. Pick it over a general web or code-execution tool when the work is already packaged as an Apify Actor or dataset.

## As a tool

The registered prefix is `apify`, so the agent sees `apify.run_actor` and `apify.get_dataset_items`.

| Function | Description |
|---|---|
| `apify.run_actor` | Runs an Actor to completion, then reads items from its default dataset. |
| `apify.get_dataset_items` | Reads items from an existing dataset. |

### `apify.run_actor`

`actor_id` is required and may be an Actor ID or name. `run_input` is an optional object passed directly to that Actor, so its shape depends on the chosen Actor. `limit` is optional and is clamped to the configured item cap. The result contains `success`, `dataset_id`, `count`, and `items`; a run without a default dataset succeeds with an empty dataset ID and item list. Invalid input raises an error, and client errors from the Actor or dataset request are surfaced as tool failures.

### `apify.get_dataset_items`

`dataset_id` is required; `limit` is optional and uses the same configured cap. The result contains `success`, `count`, and `items`. A missing dataset ID raises an error, and client request failures are surfaced rather than represented as an empty result.

## Configuration

Set the API token first. The remaining settings are guardrails for agent-selected Actors; start with their defaults and increase them only when a known Actor needs more capacity.

### Max Items

This is the upper bound for items returned by either tool and defaults to 100. A per-call `limit` can reduce the result set but can never exceed this value; invalid or omitted call limits use the cap. Raise it when the agent needs a larger complete result set, and keep it small when sending results into a limited agent context. Invalid or non-positive configuration falls back to 100.

### Run Timeout (seconds)

This setting bounds both the Actor's run timeout and how long the client waits for it, defaulting to 120 seconds. Increase it for an Actor that legitimately takes longer to finish; leave it conservative for agent-chosen work so a stuck run cannot hold the pipeline indefinitely. Invalid or non-positive configuration falls back to 120.

### Max Cost (USD)

This value is passed as the per-run total-charge limit for pay-per-event Actors and defaults to 1. Increase it only after establishing the expected cost of the specific Actor; the limit applies to `run_actor`, not dataset reads. A value that cannot be parsed as a decimal falls back to 1.

## Authentication

Provide an Apify API token in **API Token**. The node creates its client at pipeline startup and fails to start when the configured token is empty.

## Upstream docs

- [Apify documentation](https://docs.apify.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_apify.apikey` | `string` | **API Token**<br/>Apify API token | `""` |
| `tool_apify.max_cost_usd` | `number` | **Max Cost (USD)**<br/>Spend limit per run for pay-per-event Actors. | `1` |
| `tool_apify.max_items` | `integer` | **Max Items**<br/>Upper cap on items returned per call (agent requests are clamped to this). | `100` |
| `tool_apify.run_timeout_secs` | `integer` | **Run Timeout (seconds)**<br/>Max seconds an Actor run may take before it is stopped. | `120` |

## Dependencies

- `apify-client` `>=3,<4`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_apify)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Bland AI

Route: /nodes/tool_bland_ai

# tool_bland_ai

A RocketRide tool node that lets an AI agent initiate an outbound Bland AI call, inspect a call, and request analysis of a completed call.

## About Bland AI

Bland AI is the third-party phone-call service this node invokes over its HTTP API. The node uses it for outbound AI calls, call retrieval, and post-call analysis.

## What it does

Use this node when an agent must make and follow up on an AI-powered outbound phone call. It exposes tools only, with no pipeline lanes, and keeps the configured call defaults in one provider driver. Choose it over a generic HTTP tool when the agent needs the node's input checks, call defaults, or optional completion polling.

## As a tool

The server name defaults to `bland`, registering the following functions as `bland.make_call`, `bland.get_call`, and `bland.analyze_call`.

| Function | Description |
|---|---|
| `bland.make_call` | Initiates an outbound AI phone call. |
| `bland.get_call` | Retrieves the details of a call, with optional waiting for completion. |
| `bland.analyze_call` | Requests post-call analysis for a call. |

### `bland.make_call`

`phone_number` and `task` are required. The number is expected in E.164 form, while `task` gives the voice agent its instructions. Optional `first_sentence`, `voice`, and positive-integer `max_duration` override or supplement configured call defaults; optional `webhook` must begin with `https://`. The function returns the provider response, including the call ID used by later tools. Invalid input and API request failures raise errors.

### `bland.get_call`

`call_id` is required. Set optional `wait_for_completion` to true to poll every 10 seconds for up to 300 seconds; otherwise the current call details are returned immediately. The provider response supplies call status and details. A missing call ID, a polling timeout, or an API request failure raises an error.

### `bland.analyze_call`

`call_id` is required. Optional `goal` describes the analysis purpose, and optional `questions` is an array of `[question, expected_type]` pairs. Without `questions`, the client sends its built-in questions about caller mood, key information, and action items. The function returns the provider response; invalid input and request failures raise errors.

## Configuration

Supply the API key, then set defaults that should apply to every `make_call` invocation. Per-call voice and duration can override their defaults; recording and language remain node-level settings.

### Server name

This hidden field controls the tool namespace and defaults to `bland`. Change it only when multiple Bland AI nodes share an agent and their names must differ.

### Default Voice and Language

The node passes **Default Voice** to a call unless that call supplies `voice`; the default is `June`. **Language** defaults to `en` and is sent on every call. Change either only when the voice or language should be consistent for this node's calls; the call schema does not expose a per-call language override.

### Max Call Duration

This is the default positive duration in minutes for `make_call` and defaults to 5. A call's `max_duration` overrides it when supplied. Increase it for interactions that need more time, but keep it bounded for short tasks; non-positive, boolean, or non-integer configuration prevents node startup.

### Record Calls

This boolean defaults to enabled and is sent on every `make_call` request. Set it according to whether calls made through this node should request recording; unlike duration, an individual tool call cannot override it.

## Authentication

Provide a Bland AI API key in **API Key**. The node does not initialize without a non-empty key.

## Upstream docs

- [Bland AI documentation](https://docs.bland.ai)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `bland_ai.apikey` | `string` | **API Key**<br/>Bland AI API key (org_xxx). Get one at https://www.bland.ai | `""` |
| `bland_ai.language` | `string` | **Language** | `"en"` |
| `bland_ai.maxDuration` | `integer` | **Max Call Duration (minutes)**<br/>Maximum call length in minutes (positive integer) | `5` |
| `bland_ai.record` | `boolean` | **Record Calls** | `true` |
| `bland_ai.serverName` | `string` | **Server name**<br/>Namespace prefix for the tools: <serverName>.make_call, <serverName>.get_call, <serverName>.analyze_call | `"bland"` |
| `bland_ai.voice` | `string` | **Default Voice**<br/>Default AI voice for calls | `"June"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_bland_ai)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Chart (Chart.js)

Route: /nodes/tool_chartjs

# tool_chartjs

A RocketRide tool node that asks the pipeline LLM to turn structured data into a ready-to-render Chart.js configuration for an agent response.

## About Chart.js

Chart.js is the chart configuration format produced by this node. The node requests a static JSON configuration and returns it in a `chartjs` fenced block for the RocketRide chat UI to render.

## What it does

Use this node when an agent needs a chart, graph, or visualization from supplied data rather than a hand-authored configuration. It is an agent tool with a required LLM connection, not a data-flow lane processor. The node validates the LLM's JSON response and wraps it in the rendering fence, so choose it over a generic LLM call when the response must be a Chart.js chart.

## Connections

| Connection | Required | Description |
|---|---|---|
| `llm` | yes | LLM used to generate Chart.js configurations from data. |

The node uses the first controller registered under the `llm` role. If no LLM is connected, `generate_chart` fails before it can generate a configuration.

## As a tool

The server name defaults to `chartjs`, registering `chartjs.generate_chart`.

| Function | Description |
|---|---|
| `chartjs.generate_chart` | Generates a static Chart.js JSON configuration from structured data and returns it as a `chartjs` fenced block. |

### `chartjs.generate_chart`

`data` is required and must be a non-empty object or array. Optional `chart_type` is one of `bar`, `line`, `pie`, `doughnut`, `radar`, `polarArea`, `scatter`, or `bubble`; `title` and `description` must be strings when supplied. The tool returns a string that must be placed verbatim in the answer—do not wrap it in another code fence. Invalid input, a missing LLM, an empty model response, or model output that is not JSON raises an error.

## Configuration

The only setting is the hidden server name. Most pipelines should retain the default.

### Server name

The server name determines the advertised namespace and defaults to `chartjs`. Change it only when multiple Chart.js nodes are attached to the same agent and their function names must be distinct; use the corresponding prefix when calling the tool.

## Notes

### Input shaping

List input is truncated to its first 200 entries before prompting the LLM. The serialized data is also limited to 20,000 characters; oversized serialized input is shortened before it reaches the model. Use summary-sized data when completeness matters, or pre-aggregate a larger export before calling the tool.

### Generated configuration

The internal prompt requires `type`, `data` with `labels` and `datasets`, and `options`, with responsiveness and aspect-ratio preservation enabled. It also prohibits JavaScript callbacks, so the output is static JSON rather than executable chart code.

## Upstream docs

- [Chart.js documentation](https://www.chartjs.org/docs/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_chartjs.serverName` | `string` | **Server name**<br/>Namespace prefix for the tool: <serverName>.generate_chart | `"chartjs"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_chartjs)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Cognee

Route: /nodes/tool_cognee

# tool_cognee

A RocketRide tool node that gives agents persistent semantic memory through a Cognee server, with explicit storage, retrieval, and processing-status tools.

## About Cognee

Cognee is the external semantic-memory service this node accesses through its REST API. Its memory workflow stores plain text, builds a semantic knowledge graph, and recalls results with references.

## What it does

Use this node when agents need durable semantic memory that outlives a single tool call or agent run. It exposes agent tools only—there are no pipeline lanes—and keeps the configured dataset as the default memory scope. Pick it over run-scoped agent memory when another agent or a later call must deliberately store and retrieve semantic memory; it does not inspect source-code ASTs, import graphs, or call graphs.

## As a tool

The registered prefix is `cognee`, so the agent sees `cognee.remember`, `cognee.recall`, and `cognee.memory_status`.

| Function | Description |
|---|---|
| `cognee.remember` | Stores plain text in a dataset and starts semantic-memory processing. |
| `cognee.recall` | Retrieves memory results for a natural-language query, always requesting references. |
| `cognee.memory_status` | Reports whether the configured dataset's processing is pending, running, completed, or failed. |

### `cognee.remember`

`text` is required and must be non-empty plain text. Optional `dataset` must be the configured dataset unless dataset override is enabled; optional boolean `run_in_background` returns after queuing processing when true. The server response must contain a non-empty `status` and may include dataset and pipeline-run identifiers. Invalid input raises an error; failed requests raise redacted Cognee errors, and this non-idempotent request is not retried.

### `cognee.recall`

`query` is required and non-empty. Optional `dataset` follows the same scope rule; optional `search_type` must be one of the configured supported strategies, and optional `top_k` must be an integer. The result is `results` plus `count`; references are always requested from the server. Invalid input or server failures raise errors rather than returning an empty recall result.

### `cognee.memory_status`

`dataset` is optional and defaults to the configured dataset, subject to the same override rule. Before requesting status, the node lists datasets and resolves the name by exact match. It returns the dataset name and ID plus one of `pending`, `running`, `completed`, or `failed`. An unresolved dataset or an invalid server response raises an error.

## Configuration

Set the server URL and dataset first. The remaining settings control which data an agent may select, how recall is requested, and how much time each request can consume.

### Server URL and API Key

**Server URL** defaults to `http://localhost:8000`; trailing slashes are removed before requests. An absent or empty field uses that default, while a whitespace-only configured URL prevents startup. **API Key** is optional for a self-hosted server that accepts unauthenticated requests; when the field is blank, the node falls back to `COGNEE_API_KEY` and sends it as the `X-Api-Key` header. Set the URL to the reachable server from the engine environment and add a key when that server requires access control.

### Dataset and Allow dataset override

**Dataset** defaults to `main` and is the scope used whenever a call omits `dataset`. Keep **Allow dataset override** disabled to stop agents from selecting a different dataset; it is enabled only by the boolean value `true`. Enable it only when the agent is intentionally allowed to work across separate memory scopes.

### Default recall strategy and Recall results (top_k)

The default strategy is `GRAPH_COMPLETION_DECOMPOSITION`. Configuration is normalized to uppercase and falls back to that default if it is unsupported; a tool-call override must be a supported strategy or the call fails. **Recall results (top_k)** defaults to 15 and is clamped from 1 through 100 in configuration; a call override must be an integer and is then clamped to the same range. Raise it when broader recall is needed, while keeping it lower when an agent needs a focused result set.

### Request timeout (s)

This is the timeout for every Cognee request and defaults to 120 seconds. Configuration is clamped from 5 through 600 seconds; increase it only for a server whose processing or retrieval normally takes longer, because every tool call waits up to this bound.

## Authentication

For an access-controlled Cognee server, provide **API Key** or set `COGNEE_API_KEY`. The node does not send an `X-Api-Key` header when neither source supplies a key, which supports self-hosted servers configured for unauthenticated access.

## Notes

### Request behavior

`remember` and `recall` use one POST attempt. Dataset listing and status checks use the shared retrying GET helper. For background storage, call `memory_status` and wait for `completed` before relying on a recall result.

### Shared memory across agents

A RocketRide component may carry multiple tool/control entries, so one `tool_cognee` node can serve several agents at once. Prefer that to duplicating the node per agent: one component keeps the server, credentials, dataset, and retrieval settings from drifting apart. Shared recall requires every participant to use the same Cognee server, an authenticated identity with permission to the shared memory, and the same dataset — keep **Allow dataset override** disabled so no agent can select a different dataset. Memory never moves implicitly: an agent must call `cognee.remember` to store, and another must call `cognee.recall` to retrieve; each agent still needs its own run-scoped working memory.

Simultaneous writes may overlap. The node provides no transaction, serialization, or ordering guarantee across tool calls, and recall is eventually consistent with processing. Prefer a sequential handoff: let the storing agent finish, wait for `cognee.memory_status` to report `completed`, and only then have the receiving agent recall. See the copyable [`cognee-shared-memory-agents.pipe`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/cognee-shared-memory-agents.pipe) example.

## Upstream docs

- [Cognee documentation](https://docs.cognee.ai)
- [Cognee API reference](https://docs.cognee.ai/api-reference/introduction)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `cognee.allow_dataset_override` | `boolean` | **Allow dataset override**<br/>Allow agents to select a dataset per call. Leave off when several agents should share one operator-controlled memory scope. | `false` |
| `cognee.api_key` | `string` | **API Key**<br/>Cognee API key sent as the <code>X-Api-Key</code> header. Falls back to <code>COGNEE_API_KEY</code>. Self-hosted servers with access control disabled can leave this blank. | `""` |
| `cognee.base_url` | `string` | **Server URL**<br/>Base URL of the Cognee server. Self-hosted Cognee defaults to <b>http://localhost:8000</b>. For Cognee Cloud, use the instance URL from <a href='https://platform.cognee.ai' target='_blank'>platform.cognee.ai</a>. | `"http://localhost:8000"` |
| `cognee.dataset` | `string` | **Dataset**<br/>Default Cognee dataset used by all agent tools. Tool calls stay in this operator-controlled scope unless per-call overrides are enabled. | `"main"` |
| `cognee.request_timeout` | `integer` | **Request timeout (s)**<br/>Maximum seconds to wait for one Cognee request. | `120` |
| `cognee.search_type` | `string` | **Default recall strategy**<br/>How recall retrieves memory. Graph completion decomposition is the semantic default; the agent can override it per call. | `"GRAPH_COMPLETION_DECOMPOSITION"` |
| `cognee.top_k` | `integer` | **Recall results (top_k)**<br/>Maximum number of results recall retrieves per query. | `15` |

## Dependencies

- `requests` `>=2.34.2`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_cognee)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Crustdata

Route: /nodes/tool_crustdata

# tool_crustdata

A RocketRide tool node that gives an agent filter-based search over Crustdata's B2B company and people index. Pick it when an agent needs to discover accounts or contacts matching criteria, rather than to look up one company or person it already knows.

## About Crustdata

Crustdata is a B2B data provider that maintains an indexed database of companies and people — firmographics, funding, headcount and hiring signals on the company side; work history, education and contact details on the people side. It sells access through a REST API aimed at sales, recruiting and market-research teams rather than through an application of its own.

## What it does

The node has no data lanes and exposes two search functions to an agent: one over Crustdata's company index, one over its people index. Each takes a flat list of `{field, type, value}` conditions, wraps them into the `{op, conditions}` group form Crustdata's API expects, and returns the records the service sends back. Results are cursor-paginated, so an agent can walk a large result set across several calls. Prefer this node over a generic HTTP tool when an agent needs Crustdata's filter grammar, limits and pagination already handled; reach for a web-search or scraping node instead when the target is open-web content rather than an indexed B2B record.

The node is marked `experimental`. Its request and response shapes are read from Crustdata's published API reference, but no live account has exercised it end to end — see `## Notes`.

## As a tool

The server-name prefix is `crustdata`, producing these registered functions.

| Function | Description |
|---|---|
| `crustdata.company_search` | Search Crustdata for companies matching one or more filters (industry, region, headcount, funding, current company, and more). Returns structured company records: firmographics, funding history, headcount, and hiring signals. Use it to find prospects or research accounts by criteria, not to look up one already-known company by name. |
| `crustdata.person_search` | Search Crustdata for people matching one or more filters (current company, current title, region, and more). Returns structured profiles: name, title, work history, education, and verified contact info where available. Use it to find or enrich people by criteria. |

Both functions take the same arguments. `filters` is required and must be a non-empty array of `{field, type, value}` conditions. `field` is a dotted path such as `basic_info.primary_domain` (company) or `experience.employment_details.current.title` (person). `type` is one of `=`, `!=`, `<`, `=<`, `>`, `=>`, `in`, `not_in`, `is_null`, `is_not_null`, `(.)` (fuzzy/contains), `[.]` (exact list membership), `geo_distance`, or `geo_exclude` — note `=<` and `=>` rather than `<=` and `>=`, and that the two geo operators take a `{location, distance, unit}` object as their `value`.

The optional arguments are `match` (`and` or `or`, defaulting to `and`), `sorts` (an array of `{field, order}` objects, `order` being `asc` or `desc`), `limit` (1–1000, defaulting to the node's configured Default Result Limit), and `cursor` (a `next_cursor` from an earlier call; omit it for the first page).

Every call returns an object carrying `success`, `filters` (the conditions echoed back), `count`, and `results` — the Crustdata records passed through as received, with no per-record remapping. `next_cursor` and `total_count` are added when Crustdata's response includes them. Missing or empty `filters`, a failed request, and a non-JSON response body all come back as `success: false` with an `error` string; the agent sees a failure as data rather than as a raised exception.

## Configuration

Two fields: the API key and a default result limit. Supply the key (or its environment fallback) and leave the limit alone unless agents routinely need larger pages.

### API Key

Required. The node reads it from this field, falling back to the `CRUSTDATA_API_KEY` environment variable; if neither supplies a value the node fails to start. See `## Authentication`.

### Default Result Limit

The `limit` applied to any search where the agent does not pass one of its own. It defaults to 10 and accepts 1–1000; a value outside that range is clamped into it, and a non-numeric value falls back to 10. An agent's per-call `limit` overrides it and is clamped the same way, falling back to this configured value when it cannot be read as a number.

Keep it small when responses feed straight into an agent's context — raw Crustdata records are wide, and a large page burns tokens quickly. Raise it when an agent sweeps broad filters and would otherwise have to paginate repeatedly; beyond the limit, an agent can page through the rest with `cursor` instead.

## Authentication

The node needs a Crustdata API key, issued from <https://crustdata.com>. Put it in the **API Key** field, where it is encrypted at rest and masked in the UI, or set `CRUSTDATA_API_KEY` on the engine host; the configured field wins when both are present. The key is sent as an `Authorization: Bearer <key>` header, alongside the `x-api-version: 2025-11-01` header that every request to this API carries.

## Notes

### Experimental status

The endpoints, condition schema and cursor pagination implemented here come from Crustdata's own versioned API reference rather than from a live integration. What is not verified: the complete searchable-field list for each entity, and whether a given key's plan includes the real-time variants Crustdata also advertises alongside its indexed search. Tracked as [issue #2129](https://github.com/rocketride-org/rocketride-server/issues/2129).

### Pagination

Pass a response's `next_cursor` back as the next call's `cursor`. Keep `filters` and `sorts` identical across pages — changing either invalidates the cursor — which is why an explicit `sorts` is worth passing whenever an agent intends to paginate.

### Why `match` has only two values

`match` accepts `and` or `or`, and anything else is treated as `and`. Person search's third operator, `all_of`, is not a general combinator: it constrains its conditions to a single nested-array path such as employment or education, so it does not fit a flat "combine these conditions" parameter and is not exposed.

### Request handling

Calls go out through `requests`; no Crustdata SDK is used. Each request times out after 30 seconds and is retried with exponential backoff (up to four attempts) on timeouts, connection errors, HTTP 429 and 5xx responses. Other 4xx responses fail immediately without a retry.

## Upstream docs

- [Crustdata company search reference](https://docs.crustdata.com/company-docs/search/reference)
- [Crustdata person search reference](https://docs.crustdata.com/person-docs/search/reference)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_crustdata.apikey` | `string` | **API Key**<br/>Crustdata API key (from https://crustdata.com) | `""` |
| `tool_crustdata.defaultLimit` | `integer` | **Default Result Limit**<br/>Default maximum number of results per search (1-1000) | `10` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_crustdata)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Daytona

Route: /nodes/tool_daytona

# tool_daytona

A RocketRide tool node that gives an agent a shared, ephemeral Daytona sandbox for remote code, shell commands, and text-file operations.

## About Daytona

Daytona is the external sandbox service this node accesses through its Python SDK. This node creates an ephemeral sandbox and uses it for code execution, shell commands, and file transfer during a pipeline run.

## What it does

Use this node when an agent must execute generated code or commands outside the engine host and retain files or installed packages across related tool calls. It exposes tools only, with no pipeline lanes, and creates its sandbox only when a tool first needs it. Pick it over a local execution tool when remote sandbox isolation and an automatically cleaned-up session are required.

## As a tool

The registered prefix is `daytona`, so the agent sees four functions.

| Function | Description |
|---|---|
| `daytona.run_code` | Runs source code in the configured sandbox language. |
| `daytona.run_command` | Runs a shell command, optionally in a sandbox working directory. |
| `daytona.upload_file` | Creates or overwrites a UTF-8 text file in the sandbox. |
| `daytona.download_file` | Reads a text file from the sandbox. |

### `daytona.run_code`

`code` is required and must be a non-empty string. The function returns `exit_code`, captured `output`, and `truncated`. A Daytona SDK failure instead returns `error`, `exit_code: -1`, empty output, and `truncated: false`.

### `daytona.run_command`

`command` is required and non-empty; optional `cwd` must be a string and is passed as the sandbox working directory when non-blank. The result and failure shape match `run_code`. Use it to install dependencies, build, or invoke shell programs in the same sandbox session.

### `daytona.upload_file`

`path` and string `content` are required. The function encodes content as UTF-8, creates or overwrites the file, and returns `success` with `path`. A Daytona failure returns `success: false`, the requested path, and `error`.

### `daytona.download_file`

`path` is required and non-empty. Successful output has `content` and `truncated`; missing files and SDK failures return empty content, `truncated: false`, and `error`. Unlike the other stateful calls, this function does not create a replacement sandbox after an expiration because an empty replacement cannot recover the file.

## Configuration

Provide the API key, then keep the defaults unless a particular sandbox workload needs a different image, language, lifetime, or output budget.

### API URL, Target Region, and Snapshot

Leave **API URL** blank to let the SDK use its default endpoint; set it only for a different Daytona endpoint. Leave **Target Region** blank to use the organization's default target, or select a target for a specific region. **Snapshot** is also optional and is passed when creating the sandbox; use it when a known snapshot supplies the runtime state your workload requires.

### Language

This sets the sandbox language used by `run_code` and defaults to `python`. The supported configured values are `python`, `javascript`, and `typescript`. `run_command` remains the tool for shell commands regardless of this setting.

### Auto-stop (minutes)

The shared sandbox is created as ephemeral, and this interval defaults to 5 minutes. After inactivity, server-side auto-stop deletes it; use a longer value only when calls need a longer idle gap without losing their files and installed packages. The node clamps configuration from 1 through 120 minutes, never allowing zero to disable this cost-safety cleanup.

### Execution Timeout (seconds) and Max Output (characters)

Both `run_code` and `run_command` use **Execution Timeout**, which defaults to 120 seconds and is clamped from 1 through 1,200. **Max Output** defaults to 50,000 characters and is clamped from 1,000 through 1,000,000; longer command output and downloaded file content are returned only up to that cap with `truncated: true`. Increase either only when the agent needs it, because timeout limits wait time and output limits protect its context window.

## Authentication

Provide a Daytona API key in **API Key**. The node fails pipeline startup when the key is empty.

## Notes

### Session lifecycle

All calls in a pipeline share one lazily created sandbox. A lock prevents simultaneous tool calls from creating multiple sandboxes. `run_code`, `run_command`, and `upload_file` retry once on a fresh sandbox when the prior handle has expired; any state from the old sandbox is gone and must be restored. Pipeline shutdown attempts to delete the sandbox, while ephemeral auto-stop remains the cleanup fallback if deletion fails.

## Upstream docs

- [Daytona documentation](https://www.daytona.io/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_daytona.api_url` | `string` | **API URL**<br/>Daytona API endpoint. Leave empty for the default cloud (https://app.daytona.io/api); set for self-hosted Daytona. | `""` |
| `tool_daytona.apikey` | `string` | **API Key**<br/>Daytona API key (app.daytona.io → Keys). | `""` |
| `tool_daytona.auto_stop_minutes` | `integer` | **Auto-stop (minutes)**<br/>Sandbox stops (and, being ephemeral, deletes itself) after this many minutes of inactivity: the cost safety net if cleanup is missed. | `5` |
| `tool_daytona.exec_timeout_secs` | `integer` | **Execution Timeout (seconds)**<br/>Max seconds a single run_code/run_command call may take. | `120` |
| `tool_daytona.language` | `string` | **Language**<br/>Language runtime for run_code in the sandbox. | `"python"` |
| `tool_daytona.max_output_chars` | `integer` | **Max Output (characters)**<br/>Output longer than this is truncated before being returned to the agent. | `50000` |
| `tool_daytona.snapshot` | `string` | **Snapshot**<br/>Daytona snapshot to create the sandbox from. Leave empty for the default snapshot. | `""` |
| `tool_daytona.target` | `string` | **Target Region**<br/>Sandbox region, e.g. "us" or "eu". Leave empty for the organization default. | `""` |

## Dependencies

- `daytona` `==0.140.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_daytona)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# DeepL

Route: /nodes/tool_deepl

# tool_deepl

A RocketRide tool node that gives an agent DeepL translation and text-rephrasing functions, with node defaults for common translation requests.

## About DeepL

DeepL is the external translation and rephrasing API this node calls over HTTPS. This node uses its translation endpoint and its Write rephrasing endpoint to process one text value or a batch.

## What it does

Use this node when an agent must translate text or rewrite it in a requested style or tone. It exposes tools only—there are no pipeline lanes—and returns a structured result plus the first result as a convenient `text` field. Pick it over a general LLM transformation when an API translation target, detected source language, or DeepL Write result is required.

## As a tool

The registered prefix is `deepl`, so the agent sees `deepl.deepl_translate` and `deepl.deepl_write`.

| Function | Description |
|---|---|
| `deepl.deepl_translate` | Translates text into a target language. |
| `deepl.deepl_write` | Rephrases text with an optional writing style or tone. |

### `deepl.deepl_translate`

`text` is required and accepts one non-empty string or a list of at most 50 non-empty strings. `target_lang` uses the call value when present and otherwise falls back to **Default Target Language**; `source_lang` is optional and is sent only when non-blank. Optional `formality`, `model_type`, boolean `preserve_formatting`, and non-blank `context` are added to the request when valid. The result is `success`, `translations`, first-result `text`, and `error`; invalid input or request failures return `success: false` with an empty result list and an error message.

### `deepl.deepl_write`

`text` has the same one-string-or-up-to-50-strings rule. Optional `target_lang` is restricted to `de`, `en-GB`, `en-US`, `es`, `fr`, `it`, `ja`, `ko`, `pt-BR`, `pt-PT`, or `zh`. Supply either optional `writing_style` or `tone`, never both; supplying both returns a failure without making an HTTP request. The result is `success`, `improvements`, first-result `text`, and `error`; invalid input or request failures use the same failure shape.

## Configuration

Set the API key, then configure the values that should be used when a translation call omits them. A valid tool-call argument takes precedence over a configured default.

### Default Target Language

This is the fallback target for `deepl_translate` and defaults to `EN-US`. Leave it as the common target for the node's callers, or set it to another target so agents do not need to repeat it. If neither the call nor configuration provides a non-blank target, translation returns an error.

### Formality

This is the fallback formality for translation and defaults to `default`. The supported values are `default`, `more`, `less`, `prefer_more`, and `prefer_less`; a valid call value overrides it. Change it when the translated output needs a consistent level of formality, while noting that unsupported target-language combinations are returned by DeepL as errors rather than silently ignored. A cleared or invalid default is omitted from the request when no valid call value is supplied.

### Model Type

This optional translation fallback defaults to empty, which omits it and lets the service choose. Valid values are `latency_optimized`, `quality_optimized`, and `prefer_quality_optimized`; a valid call value takes precedence. Set it only when this node needs a consistent quality or latency preference, and keep it blank when no preference should be sent.

## Authentication

Provide **API Key** or set `ROCKETRIDE_DEEPL_KEY`; a non-blank configuration key takes precedence over the environment variable. The node fails startup if neither is set. Keys ending in `:fx` use the free API host; other keys use the standard API host. The key is sent in the authorization header and is not included in returned request errors.

## Notes

### Request and error handling

Invalid text batches are rejected before an HTTP request. The node sends requests through the shared retrying POST helper and returns a structured failure for request errors or unexpected response bodies. It provides specific safe messages for quota exhaustion, authentication failure, and rate limiting.

## Upstream docs

- [DeepL API documentation](https://developers.deepl.com/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_deepl.apikey` | `string` | **API Key**<br/>DeepL API key (from https://www.deepl.com/pro-api). A key ending in :fx is a Free-tier key and is routed to api-free.deepl.com automatically. | `""` |
| `tool_deepl.formality` | `string` | **Formality**<br/>Default formality for translation. Only honored by a subset of target languages; DeepL returns an error for unsupported ones, which the node surfaces. | `"default"` |
| `tool_deepl.modelType` | `string` | **Model Type**<br/>Translation model to request. Empty lets DeepL choose its default. quality_optimized favors quality, latency_optimized favors speed, prefer_quality_optimized uses quality where available and otherwise falls back. | `""` |
| `tool_deepl.targetLang` | `string` | **Default Target Language**<br/>Default target language for translation when the agent does not supply one. Regional variants are allowed (e.g. EN-US, EN-GB, PT-BR, PT-PT, ZH-HANS, ZH-HANT). | `"EN-US"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_deepl)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Exa Search

Route: /nodes/tool_exa_search

# tool_exa_search

A RocketRide tool node that gives an AI agent live semantic web search through Exa when it needs fresher or broader results than its built-in knowledge.

## About Exa

Exa is a search product built for finding and retrieving web content. It is known for
semantic search, which matches a query by meaning as well as by keywords.

## What it does

This node exposes Exa search only as an agent tool; it has no pipeline lanes. Choose it
when an agent needs focused web research with domain or publication-date filters, rather
than page extraction from a URL it already knows. Each search returns compact result
metadata and can include retrieved text.

## As a tool

The tool server prefix is `exa` by default. It registers exactly one function:

| Function | Description |
| --- | --- |
| `exa.exa_search` | Searches Exa for web pages matching a natural-language or keyword query. |

`query` is required and must be non-empty. Optional `num_results` is clamped to 1–50;
`type` accepts `auto`, `neural`, or `keyword`; `use_autoprompt` and `include_text`
override the node defaults. Calls may also pass domain include/exclude lists and ISO 8601
start/end publication dates.

On success the function returns `success`, the query, the number returned, and result
objects containing title, URL, score, publication date, author, and text when available.
A blank query or an HTTP failure returns `success: false`, an empty result list, and an
error message instead of raising an exception.

## Configuration

Configure the API key first, then use the remaining values as sensible defaults for tool
calls. An agent can override the result count, search type, autoprompt choice, and text
inclusion on an individual search.

### Number of Results

The default is 10 and the accepted range is 1–50. Raise it when a broad comparison needs
more candidates; lower it when the agent only needs the most likely sources and should
avoid spending context on a long result list.

### Search Type

`auto` is the default. Use `neural` for concept-oriented questions and `keyword` when
exact terms matter. An unsupported per-call value falls back to `auto`, so use one of the
three accepted values when a particular retrieval style is required.

### Autoprompt and text content

Autoprompt and full text both default to enabled. Keep autoprompt on when the query can
benefit from Exa's query optimization; turn it off when the agent must preserve an exact
phrase. Keep text on when the agent needs material to read, but turn it off for lightweight
URL discovery because returned text can substantially enlarge the result payload.

## Authentication

Set **API Key**, or provide `EXA_API_KEY` on the engine host when the field is empty. A
key is required at startup and is sent in the `x-api-key` header for each search.

## Notes

### Retries

Requests use a 30-second timeout. Rate limits, server errors, and timeouts retry up to
three times with 2-, 4-, and 8-second waits before the failure is returned to the agent.

## Upstream docs

- [Exa documentation](https://docs.exa.ai)

<!-- Legacy pre-schema prose retained below only while the generated documentation is preserved. -->

> Experimental: this node is marked `experimental` and may change.

### What it does

When an agent calls the `exa_search` tool, the node runs a real-time search against the
Exa `/search` REST API and hands back structured results: title, URL, text content,
relevance score, published date, and author.

Implemented with the **requests** library, no Exa SDK is used. Requests time out after
30 seconds and are retried up to 3 times with exponential backoff (2 s base delay) on
rate limits (HTTP 429), server errors (5xx), and timeouts. Failures are returned to the
agent as a structured `{"success": false, "error": ...}` result rather than raised.

The node has no pipeline lanes (`lanes` is `{}`). Only agent runtimes reach it, through
the `invoke` capability.

---

### Configuration


| Field | Type | Description |
|---|---|---|
| `apikey` | string | Default empty. Exa API key (from https://exa.ai) |
| `numResults` | integer | Default 10. Maximum number of search results to return (1-50) |
| `useAutoprompt` | boolean | Default true. Let Exa optimize the query for better results |
| `searchType` | string | Default "auto". Type of search to perform |
| `includeText` | boolean | Default true. Include full text content in results |


The config values act as defaults, the agent can override `num_results`, `type`,
`use_autoprompt`, and `include_text` per call.

---

### Available tools

### `exa_search`

Search the web using Exa semantic search. `query` is the only required parameter.


| Tool | Description |
|---|---|---|
| `exa_search` | Search the web using Exa semantic search. Provide a natural language query to find relevant web pages. Returns structured results with title, URL, text content, relevance score, and published date. |


Returns an object with `success`, `query`, `num_results`, `results` (array of
`{title, url, score, published_date, author, text?}`, `text` only when content was
requested and returned), and `error` on failure.

---

### Authentication

Drop your Exa API key into the **API Key** config field (grab one at https://exa.ai).
The field is encrypted at rest and masked in the UI. Alternatively, set the
`EXA_API_KEY` environment variable on the engine host, the config field takes
precedence when both are set. The key is sent to the Exa API in the `x-api-key`
request header.

---

-->

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_exa_search.apikey` | `string` | **API Key**<br/>Exa API key (from https://exa.ai) | `""` |
| `tool_exa_search.includeText` | `boolean` | **Include Text Content**<br/>Include full text content in results | `true` |
| `tool_exa_search.numResults` | `integer` | **Number of Results**<br/>Maximum number of search results to return (1-50) | `10` |
| `tool_exa_search.searchType` | `string` | **Search Type**<br/>Type of search to perform | `"auto"` |
| `tool_exa_search.useAutoprompt` | `boolean` | **Use Autoprompt**<br/>Let Exa optimize the query for better results | `true` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_exa_search)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# File Store Source

Route: /nodes/tool_filesystem

# tool_filesystem

One node directory providing three RocketRide services — an agent file tool, a pipeline sink, and a pipeline source — all backed by the account-scoped RocketRide file store.

## What it does

All three services operate on RocketRide file storage — the account-scoped store used
by the platform and its client SDK `fs_*` methods. All paths are plain and relative to
the task's **storage anchor**, which the task file provides: the owning user's file
tree (`users/<client_id>/files/`) for development runs, or a task-specific subtree of
the deployment team's storage (`teams/<teamId>/files/tasks/<projectId>/`) for deployed
runs. Files written here are visible in the file browser and vice versa, and node
behavior is identical in both modes. Identity and the anchor are resolved
automatically from the running task (`rocketlib.getTask()`), never from the
environment; no account configuration is needed on any of the three services.

Three services share this node's code:

| Service | Protocol | Role |
|---|---|---|
| **File System** | `tool_filesystem://` | agent tool — read/write/delete/list/mkdir/stat |
| **File Store** | `filestore://` | pipeline sink — persist lane data to the store |
| **File Store Source** | `filestore_source://` | pipeline source — stream stored files into a pipeline |

Choose **File System** when an agent must read or produce files that should remain
available in the account file store. Choose **File Store** when a pipeline needs to
persist lane data there, and **File Store Source** when stored files should feed a
pipeline — it is a finite source: the task completes once the configured path has been
fully scanned, not a long-running server.

## Lanes

File Store (`filestore://`), the pipeline sink:

| Lane in | Lane out | Description |
| --- | --- | --- |
| `documents` | `json` | Persist each document's `page_content` (parsed text, always `.txt`); emit one reference per document. |
| `text` | `json` | Persist as Markdown (`.md`); emit a reference. |
| `table` | `json` | Persist the table as Markdown (`.md`); emit a reference. |
| `image` | `json` | Stream chunks to the store, commit on end; emit a reference. |
| `audio` | `json` | Stream chunks to the store, commit on end; emit a reference. |
| `video` | `json` | Stream chunks to the store, commit on end; emit a reference. |

File Store Source (`filestore_source://`), the pipeline source:

| Lane in | Lane out | Description |
| --- | --- | --- |
| `_source` | `tags` | Read each scanned file in full and send it as a raw object for a downstream parser. |

## As a tool

The File System service exposes the account file store to an agent as a set of
callable tools, namespaced by the node id (an agent sees `tool_filesystem_1.read_file`).
If no task identity is available or the account store fails to initialise, a warning is
logged and **all** tool methods are hidden from the agent.

Every operation is gated by a per-operation allow toggle. Read, write, list, mkdir, and
stat are **on by default**; **delete is off by default**. Tools whose toggle is disabled
are hidden from the agent at discovery time (`tool.query`), not just blocked at
invocation, and the allow-flag is re-checked at invocation as defence-in-depth.

| Tool | Description |
|---|---|
| `read_file` | Read a file and return its contents as a decoded string. Required: `path`. Optional: `encoding` (default `utf-8`), `maxBytes` (default 256 KB, max 4 MB). Returns `{path, content, size}`; files larger than `maxBytes` are rejected. |
| `list_directory` | List the immediate children of a directory. Optional: `path` (defaults to the account root). Returns `{entries: [{name, type, size?, modified?}], count}`. |
| `stat_file` | Get metadata for a file or directory. Required: `path`. Returns `{exists, type?, size?, modified?}`. |
| `write_file` | Create or overwrite a file with text content. Required: `path`, `content`. Optional: `encoding` (default `utf-8`). Returns `{path, bytesWritten}`. |
| `create_directory` | Create a directory; intermediate segments are created as needed. Required: `path`. Returns `{path, created: true}`. |
| `delete_file` | Delete a file. Only available when `allowDelete` is enabled. Required: `path`. Returns `{path, deleted: true}`. |

## Configuration

### File System (`tool_filesystem://`)

Leave the allow toggles at their defaults unless the pipeline calls for less: disable
write access for read-only analysis agents, and enable `allowDelete` only when the
agent is trusted to delete account files.

**Path Whitelist** (`pathWhitelist`): if non-empty, the relative path of **every**
operation must match at least one pattern. Patterns use `re.search` semantics — a
partial match anywhere in the path is enough, so a pattern like `secret` also matches
`notsecret/file.txt`. Anchor with `^` and `$` for a full-path match (e.g. `^docs/.*$`).
Invalid regexes are skipped with a logged warning. An empty `path` on `list_directory`
means the account root and bypasses the whitelist check (an empty string can't match a
non-trivial regex).

**Read size cap**: `read_file` accepts `maxBytes` (default **256 KB**, hard ceiling
**4 MB**). Files larger than the cap are **rejected with an error**, not truncated —
use a smaller `maxBytes` for sampling, or split the file. The cap exists because the
underlying store defaults to 100 MB per read, which could blow the agent's context
window or OOM the engine subprocess long before the LLM ever sees the result.

### File Store (`filestore://`)

**Where it writes**: **Target directory** (`targetDir`, default `output/`) + the
object's original name stem, with the lane's extension rule applied — e.g.
`output/report.txt` (nameless inputs fall back to the object id). When one object
emits several documents they also carry an index (`report_0.txt`, `report_1.txt`, …).
Each lane owns its extension rule, keyed to what the lane actually carries:
`text`/`table` carry markdown, so they always store `.md`; `documents` carries parsed
text (`page_content`), so it always stores `.txt` — a parsed `report.pdf` stores as
`report.txt`, keeping the extension truthful about the bytes; media derive it from the
stream's mime type, then the source extension, then `.bin`.

**When the file already exists** (`onConflict`, default `unique`): with `unique` the
sink appends `_1`, `_2`, …, giving up with an error after 100 attempts rather than
probing indefinitely. With `skip` it leaves the existing file alone, logs a warning,
and emits no reference for it. With `overwrite` it replaces the file — and skips the
existence probe entirely, which also saves a store round-trip per stream.
**`overwrite` can lose data**: filenames derive from the source object's *basename*,
so two inputs at `a/1.jpg` and `b/1.jpg` both resolve to the same target in a flat
`targetDir` and the second silently replaces the first — `unique` stays the default
for exactly that reason. A streamed write that is cut off part-way never leaves a
partial file behind: under `unique` and `skip` the sink deletes what it wrote; under
`overwrite` the stream goes to a `.part-<objectId>` sibling and only replaces the
target once complete, so an interrupted run leaves the existing file exactly as it
was. `skip` compares against an existing **file** — a directory sharing the name does
not by itself cause a skip.

**What it emits**: on the `json` lane, one `{path, url?}` object per persisted file —
`path` is the store-relative path; `url` is a time-limited signed download URL, only
present when **Emit download URL** (`emitUrl`) is on. Plain JSON, no Doc/chunkId
metadata. The signed URL is minted server-side via the store's `get_url` (no agent
`task.store` permission needed); **URL expiry (seconds)** (`urlExpiresIn`, default
3600, max 3600) sets its TTL.

**Guards**: the sink honours the account's `allowWrite` setting and the same path
whitelist as the File System tool's `write_file`. Every candidate path is
whitelist-checked *before* it is probed, so a path the whitelist would reject never
reveals whether files exist in the store. Media chunks stream straight to the store,
so memory stays bounded regardless of file size; the file is created only once the
first non-empty chunk arrives — an empty stream writes nothing.

### File Store Source (`filestore_source://`)

**Path** (`path`, required): file or folder to process, relative to the account file
store root. If it resolves to a file, only that file is streamed; a folder streams
every file directly inside it, and with **Recursive** (`recursive`, default off)
subfolders are descended too (breadth-first). A `path` that doesn't exist in the store
fails the task.

The scan reports each file to the engine (name + size), which queues it and calls back
into the node to render it: the file is read in full and sent downstream as a raw
object for a parser node to interpret (the parser sniffs the file type from the
extension in the entry name). Because delivery rides the engine's scan/render
contract, per-object completed/failed accounting and the task exit code are handled by
the engine — a successful run ends with exit code 0. A file that cannot be read
(including one over the store's default 100 MB per-read cap) is **marked failed with a
warning**; the scan continues with the remaining files, and the failure is reflected
in the task's failed-object count.

## Notes

### Storage location

Files land under the configured storage backend (defaults to `~/.rocketlib/store/`).
For the default filesystem backend the absolute path is the task's storage anchor
plus the relative path:

```text
<store>/users/<client_id>/files/<path>                    # development runs
<store>/teams/<teamId>/files/tasks/<projectId>/<path>     # deployed runs
```

The anchor comes from the task file the engine wrote at spawn; the node picks up
the current task automatically, no configuration needed.

### Running the tests

```bash
pytest nodes/test/tool_filesystem/ -v
```

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### File Store Source (`services.source.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `Pipe.source.parameters` |  |  |  |
| `filesystem.path` | `string` | **Path**<br/>File or folder to process, relative to the account file store root. A folder processes every file directly inside it. | `""` |
| `filesystem.recursive` | `boolean` | **Recursive**<br/>When the path is a folder, also process all files in its subfolders. | `false` |

### File Store (`services.store.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `filesystem.emitUrl` | `boolean` | **Emit download URL**<br/>Also include a time-limited signed download URL in the emitted JSON reference. | `false` |
| `filesystem.onConflict` | `string` | **When the file already exists**<br/>What the sink does when the target path is already taken. 'Replace' is destructive in a way that is easy to miss: names come from the source object's BASENAME, so two inputs from different folders that share a filename resolve to the same target and the second silently replaces the first. Leave it on 'Write under a new name' unless you are deliberately re-running into the same directory. | `"unique"` |
| `filesystem.pathWhitelist` | `array` | **Path Whitelist**<br/>Regex patterns applied to the relative path of every write using re.search semantics: a partial match anywhere in the path is enough, so a pattern like 'secret' will also match 'notsecret/file.txt'. Anchor with ^ and $ if you need a full-path match (e.g. '^docs/.*$'). If non-empty, a path must match at least one pattern. If empty, all paths under the task's storage anchor are allowed. |  |
| `filesystem.targetDir` | `string` | **Target directory**<br/>Base directory (relative to the account file store root) that lane-written files are placed under. | `"output/"` |
| `filesystem.urlExpiresIn` | `integer` | **URL expiry (seconds)**<br/>TTL for the signed URL when 'Emit download URL' is on. Max 3600. | `3600` |
| `filesystem.whitelistPattern` | `string` | **Path Pattern (regex)** | `""` |

### File System (`services.tool.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `filesystem.allowDelete` | `boolean` | **Delete files**<br/>Destructive: enable only when the agent is trusted to delete account files. | `false` |
| `filesystem.allowList` | `boolean` | **List directories** | `true` |
| `filesystem.allowMkdir` | `boolean` | **Create directories** | `true` |
| `filesystem.allowRead` | `boolean` | **Read files** | `true` |
| `filesystem.allowStat` | `boolean` | **Stat (metadata)** | `true` |
| `filesystem.allowWrite` | `boolean` | **Write files** | `true` |
| `filesystem.pathWhitelist` | `array` | **Path Whitelist**<br/>Regex patterns applied to the relative path of every operation using re.search semantics: a partial match anywhere in the path is enough, so a pattern like 'secret' will also match 'notsecret/file.txt'. Anchor with ^ and $ if you need a full-path match (e.g. '^docs/.*$'). If non-empty, a path must match at least one pattern. If empty, all paths under the task's storage anchor (the owning user's file tree for development runs, the task's team subtree for deployed runs) are allowed. |  |
| `filesystem.whitelistPattern` | `string` | **Path Pattern (regex)** | `""` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_filesystem)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Firecrawl

Route: /nodes/tool_firecrawl

# tool_firecrawl

A RocketRide tool node that lets an AI agent scrape a known web page or discover URLs on a site through Firecrawl.

## About Firecrawl

Firecrawl is a web-data service for retrieving and structuring website content. It is
used to turn web pages into agent-ready content and to discover a site's linked pages.

## What it does

This node exposes Firecrawl only as an agent tool and has no pipeline lanes. Pick it when
an agent already has a URL to read, or needs a site's link map; use a search tool instead
when it first needs to discover relevant sites. The node provides one single-page scrape
operation and one URL-map operation.

## As a tool

The tool server prefix is `firecrawl` by default. It registers these functions:

| Function | Description |
| --- | --- |
| `firecrawl.scrape_url` | Scrapes one URL and returns its content and metadata. |
| `firecrawl.map_url` | Maps a site from a root URL and returns discovered links. |

Both functions require a truthy `url`. `scrape_url` accepts `format` of `markdown`
(default) or `html`; after scraping, the node selects that attribute from the response,
then falls back to Markdown and finally an empty string. Its successful result is
`{success, content, metadata}`; non-string content is JSON-encoded. `map_url` returns
`{success, links}`, retaining string links and URL fields from returned link objects.

Invalid input and Firecrawl errors raise tool errors rather than returning an error
object. This lets the agent distinguish an empty successful map from a failed request.

## Configuration

The node has one operational setting: the API key. There are no per-call service defaults
to tune; choose the scrape format in the individual `scrape_url` call.

### API Key

Provide a non-empty key before starting the pipeline. Startup fails if it is absent, and
the configured key is the only credential source used by this node.

## Authentication

Set **API Key** to a Firecrawl API key. The key is passed when the node creates its
`FirecrawlApp` client.

## Notes

### Retry behavior

The wrapper retries a matching rate-limit error indefinitely, waiting five seconds each
time. Recognized 5xx errors retry at most five times with the same delay; other errors
propagate immediately.

## Upstream docs

- [Firecrawl documentation](https://docs.firecrawl.dev)

<!-- Legacy pre-schema prose retained below only while the generated documentation is preserved. -->

### What it does

Gives an agent the ability to scrape web pages and map website structures using the
Firecrawl API. Useful for agents that need to read live web content or discover URLs
across a site.

Uses the **firecrawl-py** SDK (`FirecrawlApp`). The client is created once when the
pipeline starts; a non-empty `apikey` is required or startup fails.

All Firecrawl calls are wrapped with automatic retry handling: rate-limit responses
(HTTP 429) are retried indefinitely with a 5-second sleep between attempts, and server
errors (HTTP 5xx) are retried up to 5 times with the same delay before the error is
raised.

---

### Configuration


| Field | Type | Description |
|---|---|---|
| `apikey` | string | Default empty. Firecrawl API key |


The node ships a single `default` profile. It has no lanes; it registers as a tool
provider and is invoked by an agent node, not wired into data lanes.

---

### Available tools

Tools are registered under the `firecrawl` prefix.

### scrape_url

Scrape a single web page and return its content.


| Tool | Description |
|---|---|---|
| `scrape_url` | Scrape a single web page and return its content. |
| `map_url` | Map a website's structure and return all discovered URLs. |


Returns `{ success, content, metadata }`. If the requested format is unavailable in the
Firecrawl response, the node falls back to `markdown` content; non-string content is
JSON-encoded.

### map_url

Map a website's structure and return all discovered URLs.

| Parameter | Required | Description       |
|-----------|----------|-------------------|
| `url`     | yes      | Root URL to map   |

Returns `{ success, links }` where `links` is an array of discovered URL strings.

---

### Authentication

Set `apikey` to a Firecrawl API key (created at [firecrawl.dev](https://www.firecrawl.dev)).
The key is passed directly to `FirecrawlApp`, no other credentials are needed.

---

### Upstream docs

- [Firecrawl documentation](https://docs.firecrawl.dev)

---

-->

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_firecrawl.apikey` | `string` | **API Key**<br/>Firecrawl API key | `""` |

## Dependencies

- `firecrawl-py`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_firecrawl)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Google Cloud Storage

Route: /nodes/tool_gcs

# tool_gcs

A RocketRide tool node that gives an agent read access to a Google Cloud
Storage bucket. Pick it when an agent needs to discover object names in a
bucket and pull one down to the engine host for further processing.

## About Google Cloud Storage

Google Cloud Storage is Google Cloud's object storage service. Data is kept as
objects inside buckets, addressed by a key that usually reads like a directory
path, and access is governed by Google Cloud IAM. It is commonly used for data
lakes, backups, media, and as the staging area between systems in a cloud
pipeline.

## What it does

The node has no data lanes and no control-plane connections; it exists purely
as an agent tool. It exposes two read-only operations against one configured
bucket: listing object names and downloading a single object to a temporary
file on the engine host. Pick it over a generic HTTP client when the agent
should stay scoped to one bucket — and optionally one prefix within it — with
credentials and a download size cap held by the node rather than by the agent.
It reads objects only; it cannot upload, delete, or otherwise modify a bucket.

## As a tool

The server-name prefix is `gcs`, producing these registered functions.

| Function | Description |
|---|---|
| `gcs.list_files` | List object names in the configured bucket. |
| `gcs.download_file` | Download one object to a temporary file on the engine host and return its local path. |

`list_files` takes no required arguments. Optional `prefix` narrows the listing
and is appended to the node's configured **Path Prefix**; optional
`max_results` caps the number of names returned and defaults to 10. It returns
a list of object names. On failure it returns a single-element list whose entry
is an error string rather than raising.

`download_file` requires `file_name`, the object's name or path inside the
bucket, which is likewise resolved beneath the configured **Path Prefix**. On
success it returns `success`, `local_path` (the temporary file on the engine
host), and `size` in bytes. Every failure — client not connected, bucket not
configured, object over the size cap, or any GCS error — comes back as a
dictionary with a single `error` key, so an agent should check for `error`
before reading `local_path`.

Only the most recent download is retained: starting a new download deletes the
previous temporary file, and anything left is removed when the node shuts down.
An agent that needs a downloaded file must consume it before requesting the
next one.

## Configuration

Set the bucket the node is allowed to touch and how it authenticates; the rest
has working defaults. **Bucket Name** is what makes the tool functions usable —
without it both functions return a "Bucket name not configured" error. The node
verifies its credentials and fetches the bucket at startup, so a bad key, a
missing bucket, or insufficient permission fails the pipeline immediately
rather than at the agent's first call.

### Bucket Name

The name of the single Google Cloud Storage bucket this node reads. It is not
an argument the agent can supply, so one node instance means one bucket;
connect a second `tool_gcs` node to expose a second bucket to the same agent.

### Path Prefix

An optional path inside the bucket that scopes every operation. When set, the
node normalizes it to end with `/` before use, so `reports` matches objects
under `reports/` and not a sibling key such as `reports-archive/2024.csv`.
Object names the agent passes are resolved beneath it: with a prefix of
`reports`, `download_file` called with `q1.csv` reads `reports/q1.csv`, and a
`prefix` argument to `list_files` is appended rather than replacing it. Leave
it blank to expose the whole bucket. Note that this scopes what the tool
functions address, not what the credentials are permitted to read — use IAM for
an enforced boundary.

### Max Download Bytes

The ceiling, in bytes, on a single `download_file` call; the default is
52,428,800 (50 MiB). The node checks the object's reported size before
downloading and re-checks the file's actual size afterwards, in case the object
changed in between, so an oversized object cannot land on disk. Both checks
return an `error` naming the object's size and the configured limit. Raise it
when the agent legitimately needs larger objects and the engine host has the
disk for them; lower it to keep an agent from consuming host disk on a bucket
of large files.

## Authentication

The node uses the shared RocketRide Google Cloud credentials fields and
requests the read-only Cloud Storage scope
(`https://www.googleapis.com/auth/devstorage.read_only`). Two authentication
types are available:

- **Application Default Credentials** (the default) — no key is configured and
  credentials are discovered from the environment. Use this when the engine
  runs on Google Cloud with an attached service account, or where `gcloud`
  application-default credentials are already present.
- **Service Account JSON** — upload the service account's JSON key file. The
  key is a secret; the field is stored as an uploaded file.

**Project ID** is optional in both modes. Left blank, it is taken from the
service account key or from the ambient credentials. The identity needs
permission to read the configured bucket and to list its objects; the startup
bucket check will fail otherwise.

## Limitations

The node declares the `noremote` capability, so it runs on the local engine
host and is not available for remote execution. That host needs network access
to Google Cloud Storage and enough disk for the largest download **Max Download
Bytes** allows. Downloaded objects are written to the engine host's temporary
directory and are only reachable by whatever runs there — the tool returns a
local path, not a URL. Access is read-only: there is no write, upload, or
delete path in this node.

## Upstream docs

- [Google Cloud Storage documentation](https://cloud.google.com/storage/docs)
- [`google-cloud-storage` Python client](https://cloud.google.com/python/docs/reference/storage/latest)
- [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `gcs.bucketName` | `string` | **Bucket Name**<br/>The Google Cloud Storage bucket name. |  |
| `gcs.maxDownloadBytes` | `integer` | **Max Download Bytes**<br/>Reject downloads larger than this many bytes (default 50 MiB). Protects server disk from oversized objects. | `52428800` |
| `gcs.prefix` | `string` | **Path Prefix**<br/>Optional path prefix inside the bucket. |  |
| `gcs.profile` | `string` |  | `"default"` |

## Dependencies

- `google-auth` `>=2.23.3`
- `google-cloud-storage` `>=2.13.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_gcs)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Git

Route: /nodes/tool_git

# tool_git

A RocketRide tool node that exposes local Git repository operations to an AI agent.

+## About Git

Git is a distributed version-control system for tracking changes in source files. Its
repositories preserve commit history and support local work as well as remote collaboration.

## What it does

This node gives an agent repository inspection and modification operations without requiring a
host `git` executable. Pick it when work must stay within one repository's history and working
tree; use a GitHub-style service node when the task is primarily hosting-platform operations.
It has no pipeline lanes.

## As a tool

The tool server prefix is `git` by default. It registers the following functions:

| Function | Description |
| --- | --- |
| `git.clone` | Clones a remote repository to a path. |
| `git.init` | Initializes a repository at a path. |
| `git.status` | Returns working-tree and branch state. |
| `git.log` | Returns filtered commit history. |
| `git.show` | Returns one commit's metadata, patch, and statistics. |
| `git.diff` | Produces a working-tree, staged, or ref-to-ref diff. |
| `git.blame` | Returns per-line commit and author information. |
| `git.file_at` | Returns a file's content at a ref. |
| `git.write_file` | Creates or overwrites a working-tree text file. |
| `git.stage` | Stages a non-empty list of paths. |
| `git.commit` | Commits the staged index. |
| `git.stash` | Pushes, pops, lists, or drops stash entries. |
| `git.branch_list` | Lists local and optional remote branches. |
| `git.branch_create` | Creates a branch, optionally from a ref. |
| `git.checkout` | Checks out an existing local branch. |
| `git.branch_delete` | Deletes a branch. |
| `git.merge` | Merges a branch into the current branch. |
| `git.fetch` | Fetches a remote without merging. |
| `git.pull` | Fetches then fast-forwards the current branch. |
| `git.push` | Pushes the current or requested branch. |
| `git.grep` | Searches tracked content with a regular expression. |
| `git.ls_files` | Lists tracked files, with optional prefix and untracked files. |

All calls require an initialized repository and reject unknown arguments. `clone` requires
`url` and `path` (optional `branch`); `init` requires `path` (optional
`initial_branch`). `show` requires `ref`; `blame` requires `path`; `file_at`
requires both `path` and `ref`; `write_file` requires `path` and `content`; and
`commit` requires `message`. `stash` requires `op` of `push`, `pop`, `list`,
or `drop`; branch creation, checkout, deletion, and merge require their named branch
argument. `grep` requires `pattern` and bounds `max_results` to 1–10,000.

Validation, Git, and libgit2 failures return an `{error: message}` result. With
read-only mode on, every write operation is blocked; `stash` remains callable only for
`op: list`.

## Configuration

Set the repository location and safety policy before connecting this node to an agent.
Credentials are only needed when the selected remote requires them.

### Repository Path

A local path is opened in place, so agent writes persist there. A URL is cloned to a
temporary directory at pipeline start and removed on exit. Leave it blank when the agent
should call `clone` or `init` itself; configure authentication first if that runtime clone
needs a private remote.

### Authentication Type

Choose `none` for public repositories, `token` for HTTPS username-and-token credentials,
or `ssh` for an SSH key. An unrecognized value falls back to `none` with a warning;
missing credentials for the selected authenticated mode also warn, so correct them before an
agent starts remote work.

### SSH Private Key

Use a PEM-encoded private key only when **Authentication Type** is `ssh`; provide
**SSH Key Passphrase** if it is encrypted. The key is written to a temporary `0400` file for
remote operations and then removed. Use token authentication instead when the provider issues
a scoped HTTPS token and an SSH key is unnecessary.

### Safe Mode and Read-Only Mode

Read-only mode defaults to on and blocks clone, initialization, writes, staging, commits,
mutating stash operations, branch changes, merge, fetch, pull, and push. Turn it off only
when the agent should modify the repository. Safe mode also defaults to on; it blocks force
push and force branch deletion, but does not block ordinary writes. Keep both defaults for
analysis-only agents.

## Authentication

For HTTPS, set **Authentication Type** to `token`, then provide **Username** and
**Token / Password**. For SSH, select `ssh` and provide the PEM private key plus an optional
passphrase. Secret fields are stored as secure configuration fields.

## Notes

### Write boundaries

`write_file` and `stage` reject traversal and `.git` paths, but a local configured
repository is otherwise writable once read-only mode is disabled. Use a temporary clone or a
sandboxed working copy when an agent should not alter the original checkout.

### Merge safety

`merge` first checks whether the requested branch is already incorporated into the current
branch; that read-only check succeeds even when the repository contains local changes. If the
merge would change the repository, the index and working tree must be clean — no staged,
unstaged, or untracked changes — so commit, stash, or remove them before retrying. When a
merge starts from a clean repository and encounters conflicts, the node aborts it and restores
the index and working tree to the original `HEAD`; because the clean-worktree check runs
before the merge begins, conflict cleanup cannot discard pre-existing local work.

## Upstream docs

- [Git documentation](https://git-scm.com/doc)

<!-- Legacy pre-schema prose retained below only while the generated documentation is preserved. -->

### What it does

Gives an agent safe, full-featured access to a git repository. The agent can open an
existing local repository, clone a remote one, or initialize a fresh one, then work with
the complete toolset: status and logs, diffs, staging and commits, branches, remotes, and
history search.

Uses **pygit2 / libgit2**: the libgit2 native library is bundled inside the pygit2 wheel,
so no host `git` binary is required on the machine running the engine.

Write operations are guarded by two toggles, **both on by default**: **read-only mode**
blocks all writes, and **safe mode** blocks force-push and force branch deletion. A
freshly added node can only inspect a repository until you turn read-only mode off.

---

### Configuration


| Field | Type | Description |
|---|---|---|
| `repoPath` | string | Default empty. Local path to an existing repository, or a remote URL (https://, git@, ssh://). A remote URL is cloned into a temporary directory at pipeline start and cleaned up on exit. Leave blank to let the agent call clone or init at runtime. |
| `authType` | string | Default "none". How to authenticate with remote repositories. |
| `username` | string | Default empty. Git username for token-based HTTPS authentication. |
| `token` | string | Default empty. Personal access token or password for HTTPS authentication. Leave empty when using SSH. |
| `sshKey` | string | Default empty. PEM-encoded SSH private key content (starts with -----BEGIN ...). Used when Auth Type is SSH. |
| `sshPassphrase` | string | Default empty. Passphrase for the SSH private key, if encrypted. Leave empty for unencrypted keys. |
| `safeMode` | boolean | Default true. Block destructive operations: force-push and force branch deletion. Normal branch deletion is allowed only when the branch is fully merged into HEAD; deleting an unmerged branch requires force=true (which is blocked in safe mode). Recommended for agent use. |
| `readOnlyMode` | boolean | Default true. Block ALL write operations (clone, init, write_file, stage, commit, stash push/pop/drop, branch create/delete, checkout, merge, fetch, pull, push). Read-only tools (status, log, show, diff, blame, file_at, branch_list, grep, ls_files, stash list) remain available. Strictly stronger than Safe Mode. Recommended when the agent only needs to inspect a repository. |


### repoPath: local path vs remote URL

`repoPath` is interpreted differently depending on its value:

| Value | Behaviour |
|-------|-----------|
| **Remote URL** (`https://`, `http://`, `git://`, `git@`, `ssh://`) | The repository is cloned into a temporary directory when the pipeline starts. The temp directory is deleted automatically when the pipeline ends. Use this for read-only analysis or ephemeral write workflows. |
| **Local path** | The existing directory is opened in place. No copy is made. Changes made by the agent persist on disk. |
| **Empty** | No repository is opened at startup. The agent must call `clone` or `init` as its first action. |

> **Note:** when using a remote URL with write operations (`push`), ensure `authType` and credentials are configured, since the cloned temp repo retains the remote `origin` from the URL.

---

### Available tools

### Repository


| Tool | Description |
|---|---|---|
| `clone` | Clone a remote git repository to a local path. Returns clone summary including the checked-out branch and HEAD SHA. |
| `init` | Initialise a new empty git repository at the given path. Creates the directory if it does not exist. |
| `status` | Return the working-tree status: current branch, staged files, unstaged modifications, and untracked files. |
| `log` | Return commit history. Supports filtering by branch, file path, author name, and date range. |
| `show` | Show full details of a single commit: metadata, diff patch, and file-change statistics. |
| `diff` | Produce a unified diff. Can diff working tree vs HEAD, two refs, or the staged index vs HEAD. |
| `blame` | Return per-line blame for a file: which commit and author last modified each line. |
| `file_at` | Return the raw content of a file at a specific commit or ref. |
| `write_file` | Write text content to a file in the working tree (creates or overwrites). Call stage then commit after writing to save the change. |
| `stage` | Stage files for the next commit (equivalent to git add). Deleted files are removed from the index. |
| `commit` | Create a commit from the current staged index. |
| `stash` | Manage the git stash. Operations: push, pop, list, drop. |
| `branch_list` | List local branches, and optionally remote-tracking branches. |
| `branch_create` | Create a new branch, optionally from a specific ref. |
| `checkout` | Check out an existing local branch. |
| `branch_delete` | Delete a branch. Normal deletion is always allowed. Force deletion (force=true) is blocked when safeMode=true. |
| `merge` | Merge a branch into the current branch. A merge that would change the repository requires a clean working tree. Fast-forwards if possible, otherwise creates a merge commit. Raises on conflicts. |
| `fetch` | Fetch updates from a remote without merging. |
| `pull` | Fetch from a remote and fast-forward merge the current branch. |
| `push` | Push the current (or specified) branch to a remote. Force-push is blocked unless safeMode=false. |
| `grep` | Search tracked file contents for a regex pattern. Returns file, line number, and matching line for each hit. Capped at max_results hits to keep responses bounded. |
| `ls_files` | List all tracked files in the repository, optionally filtered by path prefix. |


### Status & info

| Tool        | Description                                              |
|-------------|----------------------------------------------------------|
| `status` | Working-tree status: staged, unstaged, untracked files  |
| `log`    | Commit history with optional filters                    |
| `show`   | Full details + diff for a single commit                 |

### Diff & inspection

| Tool              | Description                                                        |
|-------------------|--------------------------------------------------------------------|
| `diff`        | Unified diff (working tree, two refs, or staged)                   |
| `blame`       | Per-line blame for a file                                          |
| `file_at`     | File content at a specific commit or ref                           |

### Working tree & commits

| Tool          | Description                         |
|---------------|-------------------------------------|
| `write_file` | Write text content to a file in the working tree (creates or overwrites) |
| `stage`   | Stage files (git add)               |
| `commit`  | Create a commit from staged index   |
| `stash`   | Push / pop / list / drop stash      |

### Branches

| Tool                | Description                          |
|---------------------|--------------------------------------|
| `branch_list`   | List local (and/or remote) branches  |
| `branch_create` | Create a branch from any ref         |
| `checkout`      | Check out an existing branch         |
| `branch_delete` | Delete a branch                      |
| `merge`         | Merge a branch into the current one  |

### Remote

| Tool        | Description                                 |
|-------------|---------------------------------------------|
| `fetch` | Fetch from a remote                         |
| `pull`  | Fetch + fast-forward merge                  |
| `push`  | Push to a remote (force-push blocked in safe mode) |

### Search

| Tool           | Description                                        |
|----------------|----------------------------------------------------|
| `grep`     | Regex search across tracked file contents          |
| `ls_files` | List tracked (and optionally untracked) files      |

---

### Safe mode

When `safeMode` is `true` (the default), the following operations raise an error instead of executing:

- **force push**: `push` with `force: true`
- **force branch deletion**: `branch_delete` with `force: true`

Normal branch deletion (`force: false`) is not gated by safe mode, but it only succeeds
when the branch is fully merged into `HEAD`; deleting an unmerged branch requires
`force: true`, which safe mode blocks. In practice, an unmerged branch cannot be deleted
while safe mode is on.

Set `safeMode: false` in the node config to allow force operations.

### Security note: write scope

Safe mode does **not** restrict file writes. Anything outside the `.git/` directory is fair game for `write_file`, including `.gitignore`, CI configs, build scripts, source files, and lockfiles. Path traversal (`../`) and writes inside `.git/` are blocked, but otherwise the agent has full read/write access to the working tree.

When pointing the node at a real repository (rather than a remote URL that auto-clones into a temp directory), treat the agent as a human contributor with commit rights to that tree. If you need stricter scoping, run the agent against a temp clone or a sandboxed working copy.

---

### Read-only mode

When `readOnlyMode` is `true` (the default), every mutating tool is blocked at dispatch and returns a JSON error. This is strictly stronger than `safeMode` and is the recommended setting when the agent only needs to inspect a repository.

Blocked tools: `clone`, `init`, `write_file`, `stage`, `commit`, `stash` (op `push` / `pop` / `drop`), `branch_create`, `checkout`, `branch_delete`, `merge`, `fetch`, `pull`, `push`.

Always allowed: `status`, `log`, `show`, `diff`, `blame`, `file_at`, `branch_list`, `grep`, `ls_files`, and `stash` with `op: "list"`.

Set `readOnlyMode: false` in the node config to allow write operations (subject to `safeMode`).

---

### Merge safety

`merge` first checks whether the requested branch is already incorporated into the current
branch. That read-only check succeeds even when the repository contains local changes. If the
merge would change the repository, the index and working tree must be clean: no staged,
unstaged, or untracked changes. Commit, stash, or remove those changes before retrying.

When a merge starts from a clean repository and encounters conflicts, the node aborts it and
restores the index and working tree to the original `HEAD`. Because the clean-worktree check
runs before the merge begins, conflict cleanup cannot discard pre-existing local work.

---

### Authentication

### Token (HTTPS)

Set `authType: token`, then provide `username` (e.g. `"git"` for GitHub/GitLab) and `token`
(personal access token or app password).

### SSH

Set `authType: ssh`, then paste the PEM-encoded private key content into `sshKey`.
If the key has a passphrase, set `sshPassphrase` as well.

The key content is written to a temporary file with `chmod 0400` during remote operations
and deleted immediately after.

---

### Running the tests

```bash
# Unit tests only (no git binary or real repo needed)
pytest nodes/test/tool_git/test_tools.py -v

# Integration tests against a real local repository
export GIT_TEST_REPO_PATH=/path/to/any/local/git/repo
pytest nodes/test/tool_git/test_tools.py -v
```

---

-->

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `git.authType` | `string` | **Authentication Type**<br/>How to authenticate with remote repositories. | `"none"` |
| `git.readOnlyMode` | `boolean` | **Read-Only Mode**<br/>Block ALL write operations (clone, init, write_file, stage, commit, stash push/pop/drop, branch create/delete, checkout, merge, fetch, pull, push). Read-only tools (status, log, show, diff, blame, file_at, branch_list, grep, ls_files, stash list) remain available. Strictly stronger than Safe Mode. Recommended when the agent only needs to inspect a repository. | `true` |
| `git.repoPath` | `string` | **Repository Path**<br/>Local path to an existing repository, or a remote URL (https://, git@, ssh://). A remote URL is cloned into a temporary directory at pipeline start and cleaned up on exit. Leave blank to let the agent call clone or init at runtime. | `""` |
| `git.safeMode` | `boolean` | **Safe Mode**<br/>Block destructive operations: force-push and force branch deletion. Normal branch deletion is allowed only when the branch is fully merged into HEAD; deleting an unmerged branch requires force=true (which is blocked in safe mode). Recommended for agent use. | `true` |
| `git.sshKey` | `string` | **SSH Private Key**<br/>PEM-encoded SSH private key content (starts with -----BEGIN ...). Used when Auth Type is SSH. | `""` |
| `git.sshPassphrase` | `string` | **SSH Key Passphrase**<br/>Passphrase for the SSH private key, if encrypted. Leave empty for unencrypted keys. | `""` |
| `git.token` | `string` | **Token / Password**<br/>Personal access token or password for HTTPS authentication. Leave empty when using SSH. | `""` |
| `git.username` | `string` | **Username**<br/>Git username for token-based HTTPS authentication. | `""` |

## Dependencies

- `pygit2` `>=1.19.2`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_git)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# GitHub

Route: /nodes/tool_github

# tool_github

A RocketRide tool node that exposes GitHub repository operations to an AI agent.

## About GitHub

GitHub is the world's largest code-hosting platform, built on git. Teams use it
for source control, code review, issue tracking, releases, and CI/CD automation
via GitHub Actions.

## What it does

Gives an agent full access to the GitHub REST API: files, issues, pull requests,
reviews, releases, workflows, organizations, users, search, and commit history. Useful
for agents that manage codebases, triage issues, automate releases, or operate CI/CD
pipelines.

Uses the **requests** library to call the GitHub REST API v3 (`https://api.github.com`,
API version `2022-11-28`) with Bearer-token auth and a 30-second request timeout. API
responses are stripped of noisy fields (`node_id`, `_links`, gravatar data, etc.) so the
agent gets compact, useful output.

A personal access token is **required**: the pipeline fails to start without one. Write
operations are **allowed by default**; enable **read-only mode** to block every mutating
tool when the agent should only inspect.

## Example pipelines

**GitHub assistant**

`chat → agent_rocketride → response_answers`

<div align="center">

![The GitHub node on the canvas connected to an agent as a tool](example.png)

[![Download example.pipe](https://img.shields.io/badge/example.pipe-Download-41b6e6?style=for-the-badge)](example.pipe)

</div>

`llm_anthropic` is wired to `llm` and `tool_github` to `tool`. Chat questions
reach the agent, which can inspect or update the configured repository before
returning an answer.

**Read-only codebase analyst**

An agent with this node as a tool and read-only mode **on**: it can search
code, read files, and summarize pull requests, with every mutating call
blocked at dispatch — safe to point at production repositories.

**Release automation**

`webhook → agent_deepagent → response`, with this node plus `tool_python` as
tools. The agent drafts release notes from `commit_list`, creates the release
with `release_create`, and dispatches the publish workflow with
`workflow_dispatch`.

## As a tool

List tools accept `per_page` (1–100, default 30) and `page` (default 1) for pagination.

Most tools accept an optional `repo` parameter (`owner/repo`). If omitted, the configured
`defaultRepo` is used; if neither is set, the call fails with an error asking for a repo.

### Files

| Tool | Description |
|---|---|
| `file_get` | Get the decoded content and metadata of a single file |
| `file_list` | List files and directories at a path |
| `file_create` | Create a new file |
| `file_edit` | Update an existing file. Requires the current file SHA (get it from `file_get` first) |
| `file_delete` | Delete a file. Requires the current file SHA (get it from `file_get` first) |

`file_get` raises an error when the path is a directory (use `file_list`), and
`file_list` raises when the path is a file (use `file_get`). Reads accept an optional
`ref` (branch, tag, or commit SHA); writes accept an optional `branch` and commit
`message`.

### Issues

| Tool            | Description                                              |
|-----------------|----------------------------------------------------------|
| `issue_get`     | Get a single issue by number                             |
| `issue_list`    | List issues (filter by state, labels, assignee)          |
| `issue_create`  | Create a new issue (title, body, labels, assignees)      |
| `issue_comment` | Post a comment on an issue                               |
| `issue_edit`    | Edit an issue (title, body, state, labels, assignees)    |
| `issue_lock`    | Lock an issue to prevent further comments                |

GitHub's issues endpoint includes pull requests; `issue_list` filters them out, and
`issue_get` raises an error for PR numbers (use `pr_get`).

### Pull requests

| Tool        | Description                                                  |
|-------------|--------------------------------------------------------------|
| `pr_get`    | Get a single pull request by number                          |
| `pr_list`   | List pull requests (filter by state, base branch)            |
| `pr_create` | Create a pull request (title, head, base, body, draft flag)  |

### Reviews

| Tool            | Description                                                       |
|-----------------|-------------------------------------------------------------------|
| `review_create` | Submit a PR review: `APPROVE`, `REQUEST_CHANGES`, or `COMMENT`  |
| `review_list`   | List all reviews on a pull request                                |
| `review_get`    | Get a single review                                               |
| `review_update` | Update the body of a pending review                               |

### Repository

| Tool       | Description                                                            |
|------------|------------------------------------------------------------------------|
| `repo_get` | Repository metadata (stars, forks, language, default branch, etc.)     |

### Releases

| Tool             | Description                                              |
|------------------|----------------------------------------------------------|
| `release_list`   | List releases                                            |
| `release_get`    | Get a single release by ID                               |
| `release_create` | Create a release (tag, title, notes, draft/prerelease)   |
| `release_update` | Update an existing release                               |
| `release_delete` | Delete a release                                         |

### Workflows

| Tool                 | Description                                            |
|----------------------|--------------------------------------------------------|
| `workflow_list`      | List workflows in a repository                         |
| `workflow_get`       | Get a single workflow by ID or filename (e.g. `ci.yml`) |
| `workflow_dispatch`  | Trigger a `workflow_dispatch` event on a branch or tag, with optional inputs |
| `workflow_enable`    | Enable a previously disabled workflow                  |
| `workflow_disable`   | Disable a workflow so it will not run                  |
| `workflow_get_usage` | Billable minutes and run counts for a workflow         |

### Organization & users

| Tool             | Description                                                            |
|------------------|------------------------------------------------------------------------|
| `org_list_repos` | List repos in an organization (filter by type)                         |
| `user_get_repos` | List repos for a user, omit `username` for the authenticated user     |
| `user_invite`    | Invite a user to an organization by email (role: `admin` · `direct_member` · `billing_manager`) |

### Search & commits

| Tool            | Description                                                          |
|-----------------|----------------------------------------------------------------------|
| `search_code`   | Search code, supports GitHub code search syntax (e.g. `mcp_client transport extension:py`) |
| `search_issues` | Search issues and PRs, supports GitHub issue search syntax, optional `state` filter |
| `commit_list`   | List commits, optionally filtered to a file path or starting ref     |
| `commit_get`    | Get a single commit with diff stats and per-file patches             |

## Configuration

Three fields: the token (see Authentication), a default repository, and a
read-only switch. The two behavioral ones are detailed below.

### Default Repository

Fallback repo in `owner/repo` format used when a tool call omits its `repo`
parameter. Note that `search_code` and `search_issues` also fall back to it:
when a default repo is configured, searches are scoped to that repository
unless the call passes its own `repo`. To search across all accessible
repositories, leave this field blank.

### Read-only mode

When `readOnly` is `true`, every mutating tool is blocked at dispatch and returns an
error. This is the recommended setting when the agent only needs to inspect repositories.

Blocked tools: `file_create`, `file_edit`, `file_delete`, `issue_create`,
`issue_comment`, `issue_edit`, `issue_lock`, `pr_create`, `review_create`,
`review_update`, `release_create`, `release_update`, `release_delete`,
`workflow_dispatch`, `workflow_enable`, `workflow_disable`, `user_invite`.

Always allowed: `file_get`, `file_list`, `issue_get`, `issue_list`, `pr_get`, `pr_list`,
`review_list`, `review_get`, `repo_get`, `release_list`, `release_get`, `workflow_list`,
`workflow_get`, `workflow_get_usage`, `org_list_repos`, `user_get_repos`, `search_code`,
`search_issues`, `commit_list`, `commit_get`.

Note the default is `false`, a freshly added node can write. Turn read-only mode on
explicitly for inspect-only agents.

## Authentication

Set `token` to a GitHub Personal Access Token. Classic tokens need the `repo`, `issues`,
`pull_requests`, and `workflows` scopes; a fine-grained token scoped to only the
repositories the agent needs is the safer choice. The token is sent as a
`Authorization: Bearer` header on every request; there is no unauthenticated mode.

API errors are surfaced to the agent as readable messages including the HTTP status and
GitHub's error details.

## Notes

### Running the tests

```bash
# Integration tests against a real repository (skipped unless both vars are set)
export GITHUB_TOKEN=<your token>
export GITHUB_TEST_REPO=owner/repo
pytest nodes/test/tool_github/test_tools.py -v
```

## Upstream docs

- [GitHub REST API documentation](https://docs.github.com/en/rest)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `github.defaultRepo` | `string` | **Default Repository**<br/>Default repo in owner/repo format (e.g. acme/myapp). Tool calls that omit the repo parameter will use this value. | `""` |
| `github.readOnly` | `boolean` | **Read-only mode**<br/>When enabled, all write operations (file create/edit/delete, issue create, PR create, etc.) are blocked. Safe for agents that should only read. | `false` |
| `github.token` | `string` | **Personal Access Token**<br/>GitHub PAT with repo, issues, pull_requests, and workflows scopes. Use a fine-grained token scoped to only the repos you need. | `""` |

## Dependencies

- `requests` `>=2.34.2`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_github)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# GoHighLevel

Route: /nodes/tool_gohighlevel

# tool_gohighlevel

A RocketRide tool node that exposes the GoHighLevel (LeadConnector) v2 REST API to an AI agent.

## What it does

Gives an agent one GoHighLevel sub-account: contacts, contact notes and tasks,
opportunities, pipelines, conversations, messages, calendars, appointments and
appointment notes, custom fields, custom values, tags, businesses, locations and users.
101 tools in all, plus a generic `request` tool for any v2 endpoint that has no dedicated
tool here. Useful for lead nurture, appointment booking, CRM reporting, and pipelines
that read from or write to a sub-account.

Uses the **requests** library against `https://services.leadconnectorhq.com` with a
30-second timeout, and **tenacity** to retry GoHighLevel's burst rate limit. There is no
response envelope to unwrap: each endpoint names its own key, and the key does not always
match the resource (`GET /contacts/{id}/appointments` returns `events`), so every tool
names the key it reads. Records come back trimmed to the fields the node documents, and
custom fields are projected into one object keyed by field id.

Authentication is a sub-account **Private Integration Token**, and both the token and the
**location id** are required: the pipeline fails to start without them. Write operations
are **allowed by default**; enable **read-only mode** to hide every mutating tool from the
agent.

---

## As a tool

Tools are published as `gohighlevel.<tool>`. The **Writes** column marks the tools that
read-only mode hides.

### `appointment_notes` (4 tools, opt in)

| Tool | Writes | Description |
|---|---|---|
| `appointment_notes_create` | yes | Write a note on an appointment. |
| `appointment_notes_delete` | yes | Delete a note from an appointment. |
| `appointment_notes_list` |  | List the notes written on one appointment. |
| `appointment_notes_update` | yes | Replace the text of a note on an appointment. |

### `appointments` (9 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `appointment_create` | yes | Book an appointment for a contact on a calendar. |
| `appointment_delete` | yes | Delete a calendar event by id. |
| `appointment_free_slots_list` |  | Find the times a calendar can be booked, before calling appointment_create. |
| `appointment_get` |  | Get one appointment by id. |
| `appointment_list` |  | List the appointments and other events on a calendar, a user or a calendar group inside a time window. |
| `appointment_update` | yes | Update an appointment: reschedule it, reassign it, or change its status. |
| `blocked_slot_create` | yes | Block a period on a calendar or on a user so it cannot be booked. |
| `blocked_slot_list` |  | List the blocked time on a calendar, a user or a calendar group inside a time window: the periods that are deliberately unavailable rather than booked. |
| `blocked_slot_update` | yes | Move or retitle a blocked slot. |

### `businesses` (5 tools, opt in)

| Tool | Writes | Description |
|---|---|---|
| `business_create` | yes | Create a business on the configured sub-account. |
| `business_delete` | yes | Delete a business by id. |
| `business_get` |  | Get one business by id. |
| `business_list` |  | List the businesses on the configured sub-account. |
| `business_update` | yes | Update a business. |

### `calendar_groups` (6 tools, opt in)

| Tool | Writes | Description |
|---|---|---|
| `calendar_group_create` | yes | Create a calendar group in the configured sub-account. |
| `calendar_group_delete` | yes | Delete a calendar group. |
| `calendar_group_list` |  | List the calendar groups in the configured sub-account. |
| `calendar_group_slug_check` |  | Check whether a calendar group slug is free in the configured sub-account, before creating or renaming a group. |
| `calendar_group_status_set` | yes | Enable or disable a calendar group without deleting it. |
| `calendar_group_update` | yes | Replace the name, description and slug of a calendar group. |

### `calendars` (5 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `calendar_create` | yes | Create a calendar in the configured sub-account. |
| `calendar_delete` | yes | Delete a calendar by id. |
| `calendar_get` |  | Get one calendar by id, with its whole configuration: team members, slot sizing, booking window, open hours and custom availabilities. |
| `calendar_list` |  | List the calendars in the configured sub-account. |
| `calendar_update` | yes | Update a calendar. |

### `contact_notes` (5 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `contact_notes_create` | yes | Write a note on a contact. |
| `contact_notes_delete` | yes | Delete a note. |
| `contact_notes_get` |  | Get one note by id. |
| `contact_notes_list` |  | List the notes on a contact. |
| `contact_notes_update` | yes | Update a note. |

### `contact_tasks` (6 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `contact_tasks_create` | yes | Create a task on a contact: a follow-up call, a document to send, anything a person has to do next. |
| `contact_tasks_delete` | yes | Delete a task. |
| `contact_tasks_get` |  | Get one task by id. |
| `contact_tasks_list` |  | List the tasks on a contact, open and completed alike. |
| `contact_tasks_set_completed` | yes | Mark a task done, or reopen one, without touching its title, due date or assignee. |
| `contact_tasks_update` | yes | Update a task. |

### `contacts` (16 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `contact_appointments_list` |  | List the calendar appointments booked for a contact. |
| `contact_create` | yes | Create a contact in the configured sub-account. |
| `contact_delete` | yes | Delete a contact by id. |
| `contact_duplicate_check` |  | Check whether a phone number or email already belongs to a contact, before creating one. |
| `contact_followers_add` | yes | Add users as followers of a contact. |
| `contact_followers_remove` | yes | Remove followers from a contact, by user id. |
| `contact_get` |  | Get one contact by id. |
| `contact_list` |  | List contacts in the configured sub-account. |
| `contact_list_by_business` |  | List the contacts assigned to a business. |
| `contact_search` |  | Find contacts in the configured sub-account by email, phone, name, tag or any other field. |
| `contact_tags_add` | yes | Add tags to a contact. |
| `contact_tags_remove` | yes | Remove tags from a contact. |
| `contact_update` | yes | Update a contact. |
| `contact_upsert` | yes | Create a contact, or update the existing one when its email or phone already belongs to a contact. |
| `contact_workflow_add` | yes | Enrol a contact in a workflow. |
| `contact_workflow_remove` | yes | Remove a contact from a workflow. |

### `conversations` (5 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `conversation_create` | yes | Open a conversation with a contact in the configured sub-account. |
| `conversation_delete` | yes | Delete a conversation and every message in it. |
| `conversation_get` |  | Get one conversation by id, including how many of its messages are unread and who it is assigned to. |
| `conversation_search` |  | Find conversations in the configured sub-account, by contact, owner, channel, read state or free text. |
| `conversation_update` | yes | Update a conversation read state, star or feedback. |

### `custom_fields` (5 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `custom_field_create` | yes | Create a custom field definition on the configured sub-account. |
| `custom_field_delete` | yes | Delete a custom field definition from the configured sub-account. |
| `custom_field_get` |  | Get one custom field definition. |
| `custom_field_list` |  | List the custom field definitions on the configured sub-account. |
| `custom_field_update` | yes | Update a custom field definition. |

### `custom_values` (5 tools, opt in)

| Tool | Writes | Description |
|---|---|---|
| `custom_value_create` | yes | Create a custom value on the configured sub-account. |
| `custom_value_delete` | yes | Delete a custom value from the configured sub-account. |
| `custom_value_get` |  | Get one custom value by id. |
| `custom_value_list` |  | List the custom values on the configured sub-account. |
| `custom_value_update` | yes | Replace a custom value. |

### `location_tags` (5 tools, opt in)

| Tool | Writes | Description |
|---|---|---|
| `location_tags_create` | yes | Define a new tag on the configured sub-account and return it with its id. |
| `location_tags_delete` | yes | Delete a tag definition from the sub-account. |
| `location_tags_get` |  | Get one tag definition by id. |
| `location_tags_list` |  | List every tag defined on the configured sub-account, with the id of each. |
| `location_tags_update` | yes | Rename a tag definition. |

### `locations` (2 tools, opt in)

| Tool | Writes | Description |
|---|---|---|
| `location_get` |  | Get the configured sub-account, which GoHighLevel also calls a location. |
| `location_tasks_search` |  | Search tasks across the whole sub-account, optionally narrowed by contact, assignee, business, completion state or free text. |

### `message_sending` (3 tools, opt in)

Opt-in on purpose, and not part of the default set: these are the only tools whose write
path has never been exercised against the live API (a trial sub-account has no phone or
email provider to send through), and a send from an unattended pipeline cannot be
recalled. Enable the group only on a sub-account where the send path has been proven.

| Tool | Writes | Description |
|---|---|---|
| `message_email_schedule_cancel` | yes | Cancel a scheduled email that has not gone out yet. |
| `message_schedule_cancel` | yes | Cancel a message that was scheduled but has not gone out yet. |
| `message_send` | yes | Send a message to a contact on any channel: SMS, email, WhatsApp, Instagram, Facebook, RCS, TikTok, live chat or a custom provider. |

### `messages` (5 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `message_email_get` |  | Get one email message by id, with its subject, sender, to, cc and bcc lists, thread id and attachment URLs. |
| `message_export` |  | Export messages across the whole configured sub-account, rather than one conversation at a time. |
| `message_get` |  | Get one message by id, including its body, direction, delivery status and attachment URLs. |
| `message_list` |  | Read the messages in one conversation. |
| `message_transcription_get` |  | Get the speech-to-text transcription of a recorded call or voicemail. |

### `opportunities` (10 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `opportunity_create` | yes | Create an opportunity in the configured sub-account, against a pipeline and a contact. |
| `opportunity_delete` | yes | Delete an opportunity by id. |
| `opportunity_followers_add` | yes | Add users as followers of an opportunity, so they are notified as it moves. |
| `opportunity_followers_remove` | yes | Remove followers from an opportunity, by user id, or clear them all with isRemoveAllFollowers. |
| `opportunity_get` |  | Get one opportunity by id. |
| `opportunity_search` |  | Find opportunities in the configured sub-account, filtered by pipeline, stage, contact, status, assignee or free text. |
| `opportunity_search_advanced` |  | Search opportunities in the configured sub-account by free text, and optionally pull their notes, tasks, calendar events and unread conversation counts back in the same call. |
| `opportunity_status_update` | yes | Move an opportunity to won, lost, abandoned or back to open. |
| `opportunity_update` | yes | Update an opportunity. |
| `opportunity_upsert` | yes | Update an opportunity when you pass its id, or create one when you do not. |

### `pipelines` (2 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `lost_reason_list` |  | List the reasons this sub-account records for a lost deal. |
| `pipeline_list` |  | List the opportunity pipelines on the configured sub-account, each with its stages. |

### `users` (3 tools, default)

| Tool | Writes | Description |
|---|---|---|
| `user_get` |  | Get one user by id, including the permissions map and the scopes string that the two list tools leave out. |
| `user_list_by_location` |  | List every user of the configured sub-account in one response. |
| `user_search` |  | Find users of the configured sub-account by name, email, phone or role. |

### `request` (1 tool, gated by `allowRawRequest`)

| Tool | Writes | Description |
|---|---|---|
| `request` | GET only in read-only mode | Call any GoHighLevel v2 endpoint at https://services.leadconnectorhq.com directly, by method and path. |

`request` is the escape hatch for endpoints with no dedicated tool. It sends what you give
it and returns the raw response body, where the typed tools validate their input, put the
sub-account id wherever the endpoint wants it, and return a compact result. The
`Authorization` and `Version` headers are added for you, and rate-limit retries and
read-only enforcement apply the same way. Writes under `/conversations/messages`
additionally require the `message_sending` tool group, the same opt-in the typed send
tools sit behind. Two things it does not do for you: the
sub-account id is not injected (most endpoints want `locationId`, but
`GET /opportunities/search` spells it `location_id`), and a trailing slash and the exact
casing of the path are both load-bearing, since GoHighLevel answers a mis-cased path with
401 rather than 404.

---

## Configuration

### Tool groups

Full coverage here is 101 tools across 18 groups. That is more than an LLM can choose
between reliably, so the node publishes only the groups named in **Tool groups**. Leaving
the field empty publishes the default set: **71 tools** across `appointments`,
`calendars`, `contact_notes`, `contact_tasks`, `contacts`, `conversations`,
`custom_fields`, `messages`, `opportunities`, `pipelines` and `users`, which is everything
an agent needs to run lead nurture and appointment booking end to end. `users` is in the
default set despite being administrative: it is three read-only tools, and it is the only
way to resolve the user ids that `assignedTo`, `followers` and `assignedUserId` need.
`message_sending` is deliberately not: reading messages is default, but originating one
from an unattended pipeline cannot be recalled, so sending is an explicit opt-in.

Available groups:

`appointment_notes`, `appointments`, `businesses`, `calendar_groups`, `calendars`,
`contact_notes`, `contact_tasks`, `contacts`, `conversations`, `custom_fields`,
`custom_values`, `location_tags`, `locations`, `message_sending`, `messages`,
`opportunities`, `pipelines`, `users`.

A tool in a group that is not published is invisible to the agent and refused if invoked
anyway. Group names are matched case-insensitively. A name this node does not implement is
reported as a warning in the editor; at runtime it is dropped from the selection with a
warning in the job log, and a `toolGroups` value that names *only* unknown groups stops
the pipeline at startup. Falling back to the defaults there would publish more tools than
the misspelled config asked for.

### Pagination

Every list tool returns the same envelope: `{items, count, total, next, has_more}`. Ask
for another page only while `has_more` is true, and pass `next` back as the parameter the
tool's description names. `next` is null when there is no next page. `total` is null on
most endpoints, and null there means unknown rather than zero.

**18 list tools always report `total: null`, by design rather than by defect.** Their
endpoints send no record count at all, so there is nothing to report and the node does not
synthesise one. Measured by running the live suite against a real sub-account, not inferred
from the specs:

`appointment_list`, `appointment_notes_list`, `blocked_slot_list`, `business_list`,
`calendar_group_list`, `calendar_list`, `contact_appointments_list`,
`contact_list_by_business`, `contact_notes_list`, `contact_tasks_list`,
`custom_field_list`, `custom_value_list`, `location_tags_list`, `location_tasks_search`,
`lost_reason_list`, `message_list`, `pipeline_list`, `user_list_by_location`.

Do not treat a null `total` from any of them as an empty result or as a bug: page with
`has_more` instead. The tools that do report a count are `contact_list`, `contact_search`,
`conversation_search`, `message_export`, `opportunity_search`,
`opportunity_search_advanced` and `user_search`. Two additional tools,
`contact_list_by_business` and `lost_reason_list`, read a count field their endpoints
document, but no observed live response ever carried it, which is why they stay in the
null list above.

GoHighLevel does not have one pagination style. The contacts list pages on a
`startAfter` plus `startAfterId` pair, the searches page on an opaque `searchAfter` value,
and several endpoints page on a `skip` offset. GoHighLevel also carries its cursors on the
records rather than on the response root, so the last page has one too. The node compares
the page size it received against the size it asked for instead of trusting cursor
presence, which is what keeps `has_more` from claiming a page that does not exist.

Maximum page size is per endpoint, not global: `appointment_notes_list` caps at 20,
`message_export` at 500, and the rest at 100, which is the node's own ceiling on the
endpoints where GoHighLevel publishes no maximum. Sending a larger value is a hard 400
rather than a silent clamp, so the node clamps before the request goes out.

### Custom fields

Read and write use opposite shapes, and GoHighLevel rejects the wrong one. Reads return
custom fields as one object keyed by field id (`{"<field id>": <value>}`). Creates and
updates take an array (`[{"id": "<field id>", "field_value": <value>}]`). A record from a
get tool cannot be passed back to an update unchanged. Use `custom_field_list` (group
`custom_fields`) to discover field ids.

Several write tools, including the contact, opportunity and custom field creates and
updates, accept an `extra` object. It is merged into the request body after the typed
parameters, so it reaches any API field this node does not model explicitly:

```json
{ "firstName": "Ada", "extra": { "someUndocumentedField": "value" } }
```

`tags` cannot be smuggled through `extra` on an update or an upsert. GoHighLevel replaces
the whole tag array rather than adding to it, so sending it there would delete the tags you
did not list; use `contact_tags_add` and `contact_tags_remove` instead. `contact_create`
takes `tags` as a normal parameter, since a contact being created has none to lose.

### Tags have a sub-account-level side effect

`contact_tags_add` is not only a per-contact write. Adding a tag name that does not exist
yet **defines that tag on the whole sub-account**, where it shows up in `location_tags_list`
and in the GoHighLevel UI from then on. `contact_tags_remove` takes the tag off the contact
and leaves the definition behind. Only `location_tags_delete` (group `location_tags`, opt
in) removes a definition.

This matters for anything that loops. An agent that tags a few thousand contacts with
generated names, then removes the tags again, leaves a few thousand tag definitions on the
sub-account, and nothing in the contacts group can clean them up. Reuse the names
`location_tags_list` already reports, or publish `location_tags` alongside `contacts` so
whatever creates definitions can also remove them. Confirmed live against a real sub-account,
not read out of the spec: the specs describe neither half of this.

---

## Authentication

The node accepts exactly one credential: a **sub-account Private Integration Token**.
Create it under Settings -> Private Integrations, pick the scopes, and copy the token when
it is shown. There is no way to read it again afterwards.

Three consequences are worth knowing before you deploy this node.

**One credential reaches exactly one sub-account.** A location token authenticates that
location and nothing else. There is no fan-out: minting per-location tokens from an agency
credential runs through `POST /oauth/locationToken`, which is OAuth-only and refuses a
Private Integration Token. N sub-accounts need N node instances, each with its own token
and its own `locationId`. Agency-scoped endpoints answer `403 Forbidden resource` to a
sub-account token, and no configuration change grants access.

**Rotation is a silent cliff.** Rotating with "expire later" keeps the old token working
for exactly 7 days and then stops it, with nothing in the API signalling the deadline
beforehand. Rotating with "expire now" breaks it immediately. A 401 raised by this node
carries that explanation rather than a bare "unauthorized", because a rotation about a week
earlier is the most likely cause.

**Editing scopes does not mint a new token.** The existing token keeps working, so nothing
looks broken, but calls that need a scope you removed start failing while the credential
still authenticates. GoHighLevel answers those with `401 The token is not authorized for
this scope`, which the node passes through with a note that scopes are edited on the
Private Integration itself.

### A 401 is not always a credential problem

Four error shapes are worth naming, because all four look like auth failures and none of
them is one.

- A missing or mismatched `locationId` returns `403 The token does not have access to this
  location`, which blames the token for a missing parameter.
- A mis-cased path returns 401 rather than 404.
- A missing required parameter can return 401 too. `GET /users/search` called bare answers
  `401 E01 - Unauthorized request`, and the same call answers 422 naming the parameter once
  a `locationId` is supplied. The status depends on what else you sent, not on the token.
- The gateway in front of the API answers 401 for its own failures. One was captured live
  carrying the body text `Command timed out`, which is a timeout rather than anything to do
  with the credential.

The node rewrites all four into messages that name the real cause, and its 401 fall-through
claims a credential problem only when the body actually complains about one or carries no
message at all. A timeout is reported as a timeout and is worth retrying; nothing there
should send anyone to rotate a working token.

### Errors carry more than a message

Some GoHighLevel errors name the record that caused them, and the id is the way out of the
error. `conversation_create` for a contact that already has a conversation answers HTTP 400
with `{"message": "Conversation already exists", "canonicalCode":
"CONVERSATIONS_CONVERSATION_ALREADY_EXISTS", "conversationId": "..."}`, and that is the
common case rather than an edge one: creating a contact through the API creates its
conversation too. The node carries every id the body names, plus `canonicalCode` and
`traceId`, into the raised message and onto the exception, so the agent can use the existing
conversation instead of stopping at "already exists".

### Why there is no OAuth option

GoHighLevel's OAuth access tokens last about 24 hours, and its refresh tokens are
single-use: the moment you spend one, the old refresh token is dead and a new one comes
back in the response. A node's only credential store is static config, which it cannot
write to, so the new refresh token would be thrown away. The pipeline would work for
roughly a day, refresh once successfully, work for another day, then present an
invalidated refresh token and die. That failure is delayed, silent, and unrecoverable
without a browser consent flow, and pasting the original refresh token back in does not
fix it. Supporting OAuth needs a durable secret store the node can write to on every
refresh, with a lock so concurrent runs cannot race. Until that exists, the Private
Integration Token is the only credential in this API that static config is the correct
store for.

The legacy v1 API key is not accepted either. v1 reached end of support on 31 December
2025, new keys can no longer be generated, and a v1 key will never authenticate against
`services.leadconnectorhq.com`.

---

## Notes

### Rate limits

Measured against a sub-account Private Integration Token, not assumed from the docs: **25
requests per 10 seconds** and **10,000 per day**. The 100 per 10 seconds published for
marketplace apps does not apply here. Every response carries `x-ratelimit-max`,
`x-ratelimit-remaining`, `x-ratelimit-interval-milliseconds`, `x-ratelimit-limit-daily`,
`x-ratelimit-daily-remaining` and `x-ratelimit-daily-reset`.

GoHighLevel sends no `Retry-After`, not even on the 429 itself, so the client computes its
own wait: one burst window (`x-ratelimit-interval-milliseconds`, 10000 on every observed
response), up to three attempts. If the wait would exceed the 30-second request timeout
the call fails immediately with the wait time in the message rather than blocking the
pipeline. `x-ratelimit-daily-reset` is deliberately never used as a sleep: it is a
duration in milliseconds, about 24 hours, and treating it as a timestamp would produce a
sleep of roughly 55 years. Exhausting the daily budget is a circuit break rather than
something to retry, so the node reports it and stops.

### Read-only mode

With **Read-only mode** enabled, every tool that creates, updates or deletes is dropped
from the published set: the agent does not see it in `tool.query`, and invoking it anyway
is refused. The `request` tool stays published, because it is still a working read tool,
but accepts only GET.

Hiding rather than refusing is a deliberate departure from `tool_pipedrive`, which
publishes its write tools in read-only mode and blocks them at invoke time. An agent
cannot tell in advance that a published tool is blocked, so it spends a turn finding out,
and roughly 40 tools it can only ever fail on are 40 tools' worth of wasted context.

### Running the tests

```bash
# Stubbed suite: no credentials, no network
python -m pytest nodes/test/tool_gohighlevel/test_gohighlevel.py -v

# Live suite, reads only
export GHL_PIT=<sub-account Private Integration Token>
export GHL_LOCATION_ID=<the sub-account the token is scoped to>
python -m pytest nodes/test/tool_gohighlevel/test_tools.py -v

# Live suite including the create and delete lifecycles
export GHL_ALLOW_WRITES=1
python -m pytest nodes/test/tool_gohighlevel/test_tools.py -v
```

The live suite calls the real API. Point it at a trial or sandbox sub-account: the write
tests create real records, and they remove them in a `finally` block. Do not run it under
pytest-xdist, since parallel workers share one rate-limit budget but pace themselves
independently.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `gohighlevel.allowRawRequest` | `boolean` | **Allow raw API requests**<br/>Publishes the generic <b>request</b> tool, which can call any GoHighLevel v2 endpoint by method and path. It uses the same authentication, version header, rate-limit handling and read-only enforcement as the typed tools. Message-send paths under /conversations/messages additionally require the message_sending tool group. Disable to restrict the agent to the typed tools only. | `true` |
| `gohighlevel.locationId` | `string` | **Location ID**<br/>The sub-account (location) this node operates on, from Settings -> Business Profile. The token is opaque, so the location cannot be derived from it. Without this value GoHighLevel answers <code>403</code> with a message that blames the token rather than the missing parameter. | `""` |
| `gohighlevel.privateIntegrationToken` | `string` | **Private Integration Token**<br/>Sub-account Private Integration Token (Settings -> Private Integrations), sent as <code>Authorization: Bearer</code>. It starts with <code>pit-</code>. Agency tokens, OAuth access tokens and v1 API keys are not supported: one token reaches exactly one sub-account, so N sub-accounts need N node instances. | `""` |
| `gohighlevel.readOnly` | `boolean` | **Read-only mode**<br/>When enabled, every create, update and delete tool is hidden from the agent rather than merely refused, and the generic request tool only accepts GET. Safe for agents that should only inspect the account. | `false` |
| `gohighlevel.toolGroups` | `array` | **Tool groups**<br/>Which groups of GoHighLevel tools this node publishes to the agent. This node implements 101 tools across 18 groups, far more than an LLM can choose between reliably, so only the listed groups are exposed. <b>Leave this empty for the recommended set</b>: the 71 tools marked default below, which is everything an agent needs to run lead nurture and appointment booking end to end. Use <b>all</b> to publish all 101. Naming groups replaces the default set rather than adding to it, and a value that names only unknown groups stops the pipeline at startup rather than widening back to the defaults. <b>message_sending</b> (send a message, cancel a scheduled send) is a deliberate opt-in: sends from an unattended pipeline cannot be recalled. | `[]` |

## Dependencies

- `requests` `>=2.34.2`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_gohighlevel)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Google Calendar

Route: /nodes/tool_google_workspace

# tool_google_workspace

A RocketRide tool family that exposes Google Calendar, Docs, Drive, Gmail, and Sheets to an agent. Pick the service-specific tool matching the Google Workspace resource the agent must operate, rather than using a general HTTP tool.

## About Google Workspace

Google Workspace is a collection of cloud productivity services including mail, calendars, documents, file storage, and spreadsheets. Organizations use its services for collaboration and administrative work.

## What it does

This parent groups five no-lane tool services: Calendar, Docs, Drive, Gmail, and Sheets. Each service authenticates through the shared Google lifecycle, builds only its own Google API client, and registers functions under its own server-name prefix. Select a service according to the resource the agent needs; the individual variant READMEs document their service-specific calls in depth.

## As a tool

Each service registers exactly the functions below. A function name is prefixed by its service name; `check_connection` checks that service's configured access and connection. Individual operation arguments and return shapes are exposed in each function's registered schema.

| Function | Description |
|---|---|
| `calendar.check_connection` | Google Calendar operation registered by this service. |
| `calendar.event_list` | Google Calendar operation registered by this service. |
| `calendar.event_get` | Google Calendar operation registered by this service. |
| `calendar.event_instances` | Google Calendar operation registered by this service. |
| `calendar.freebusy_query` | Google Calendar operation registered by this service. |
| `calendar.calendar_list` | Google Calendar operation registered by this service. |
| `calendar.calendar_get` | Google Calendar operation registered by this service. |
| `calendar.acl_list` | Google Calendar operation registered by this service. |
| `calendar.event_create` | Google Calendar operation registered by this service. |
| `calendar.event_update` | Google Calendar operation registered by this service. |
| `calendar.event_move` | Google Calendar operation registered by this service. |
| `calendar.event_quick_add` | Google Calendar operation registered by this service. |
| `calendar.calendar_create` | Google Calendar operation registered by this service. |
| `calendar.calendar_update` | Google Calendar operation registered by this service. |
| `calendar.acl_insert` | Google Calendar operation registered by this service. |
| `calendar.acl_delete` | Google Calendar operation registered by this service. |
| `calendar.event_delete` | Google Calendar operation registered by this service. |
| `calendar.calendar_delete` | Google Calendar operation registered by this service. |
| `docs.check_connection` | Google Docs operation registered by this service. |
| `docs.document_get` | Google Docs operation registered by this service. |
| `docs.document_create` | Google Docs operation registered by this service. |
| `docs.batch_update` | Google Docs operation registered by this service. |
| `docs.text_append` | Google Docs operation registered by this service. |
| `docs.text_replace` | Google Docs operation registered by this service. |
| `docs.image_insert` | Google Docs operation registered by this service. |
| `docs.table_insert` | Google Docs operation registered by this service. |
| `drive.check_connection` | Google Drive operation registered by this service. |
| `drive.file_list` | Google Drive operation registered by this service. |
| `drive.file_search` | Google Drive operation registered by this service. |
| `drive.file_get` | Google Drive operation registered by this service. |
| `drive.file_download` | Google Drive operation registered by this service. |
| `drive.file_export` | Google Drive operation registered by this service. |
| `drive.drives_list` | Google Drive operation registered by this service. |
| `drive.changes_list` | Google Drive operation registered by this service. |
| `drive.file_create` | Google Drive operation registered by this service. |
| `drive.file_update` | Google Drive operation registered by this service. |
| `drive.file_copy` | Google Drive operation registered by this service. |
| `drive.file_move` | Google Drive operation registered by this service. |
| `drive.file_trash` | Google Drive operation registered by this service. |
| `drive.file_untrash` | Google Drive operation registered by this service. |
| `drive.folder_create` | Google Drive operation registered by this service. |
| `drive.permission_list` | Google Drive operation registered by this service. |
| `drive.permission_update` | Google Drive operation registered by this service. |
| `drive.permission_delete` | Google Drive operation registered by this service. |
| `drive.permission_create` | Google Drive operation registered by this service. |
| `drive.file_delete` | Google Drive operation registered by this service. |
| `gmail.check_connection` | Gmail operation registered by this service. |
| `gmail.message_list` | Gmail operation registered by this service. |
| `gmail.message_search` | Gmail operation registered by this service. |
| `gmail.message_get` | Gmail operation registered by this service. |
| `gmail.message_modify` | Gmail operation registered by this service. |
| `gmail.message_batch_modify` | Gmail operation registered by this service. |
| `gmail.label_apply` | Gmail operation registered by this service. |
| `gmail.label_remove` | Gmail operation registered by this service. |
| `gmail.thread_get` | Gmail operation registered by this service. |
| `gmail.thread_list` | Gmail operation registered by this service. |
| `gmail.label_list` | Gmail operation registered by this service. |
| `gmail.label_create` | Gmail operation registered by this service. |
| `gmail.label_update` | Gmail operation registered by this service. |
| `gmail.label_delete` | Gmail operation registered by this service. |
| `gmail.draft_list` | Gmail operation registered by this service. |
| `gmail.draft_get` | Gmail operation registered by this service. |
| `gmail.draft_create` | Gmail operation registered by this service. |
| `gmail.draft_update` | Gmail operation registered by this service. |
| `gmail.draft_send` | Gmail operation registered by this service. |
| `gmail.draft_delete` | Gmail operation registered by this service. |
| `gmail.message_send` | Gmail operation registered by this service. |
| `gmail.message_trash` | Gmail operation registered by this service. |
| `gmail.message_untrash` | Gmail operation registered by this service. |
| `gmail.attachment_get` | Gmail operation registered by this service. |
| `gmail.history_list` | Gmail operation registered by this service. |
| `gmail.message_delete` | Gmail operation registered by this service. |
| `gmail.messages_batchDelete` | Gmail operation registered by this service. |
| `gmail.thread_modify` | Gmail operation registered by this service. |
| `gmail.thread_trash` | Gmail operation registered by this service. |
| `gmail.thread_untrash` | Gmail operation registered by this service. |
| `gmail.thread_delete` | Gmail operation registered by this service. |
| `gmail.message_archive` | Gmail operation registered by this service. |
| `gmail.message_mark_read` | Gmail operation registered by this service. |
| `gmail.message_mark_unread` | Gmail operation registered by this service. |
| `gmail.message_star` | Gmail operation registered by this service. |
| `gmail.message_unstar` | Gmail operation registered by this service. |
| `gmail.message_get_body` | Gmail operation registered by this service. |
| `gmail.filter_list` | Gmail operation registered by this service. |
| `gmail.filter_create` | Gmail operation registered by this service. |
| `gmail.filter_delete` | Gmail operation registered by this service. |
| `gmail.watch_start` | Gmail operation registered by this service. |
| `gmail.watch_stop` | Gmail operation registered by this service. |
| `gmail.send_as_list` | Gmail operation registered by this service. |
| `gmail.send_as_get` | Gmail operation registered by this service. |
| `gmail.send_as_create` | Gmail operation registered by this service. |
| `gmail.send_as_update` | Gmail operation registered by this service. |
| `gmail.send_as_delete` | Gmail operation registered by this service. |
| `gmail.imap_get` | Gmail operation registered by this service. |
| `gmail.imap_update` | Gmail operation registered by this service. |
| `gmail.pop_get` | Gmail operation registered by this service. |
| `gmail.pop_update` | Gmail operation registered by this service. |
| `gmail.vacation_get` | Gmail operation registered by this service. |
| `gmail.vacation_update` | Gmail operation registered by this service. |
| `gmail.forwarding_address_list` | Gmail operation registered by this service. |
| `gmail.forwarding_address_create` | Gmail operation registered by this service. |
| `gmail.forwarding_address_delete` | Gmail operation registered by this service. |
| `gmail.delegate_list` | Gmail operation registered by this service. |
| `gmail.delegate_create` | Gmail operation registered by this service. |
| `gmail.delegate_delete` | Gmail operation registered by this service. |
| `gmail.smime_list` | Gmail operation registered by this service. |
| `gmail.smime_set_default` | Gmail operation registered by this service. |
| `gmail.smime_delete` | Gmail operation registered by this service. |
| `sheets.check_connection` | Google Sheets operation registered by this service. |
| `sheets.values_get` | Google Sheets operation registered by this service. |
| `sheets.values_batch_get` | Google Sheets operation registered by this service. |
| `sheets.spreadsheet_get` | Google Sheets operation registered by this service. |
| `sheets.values_update` | Google Sheets operation registered by this service. |
| `sheets.values_batch_update` | Google Sheets operation registered by this service. |
| `sheets.values_append` | Google Sheets operation registered by this service. |
| `sheets.values_clear` | Google Sheets operation registered by this service. |
| `sheets.spreadsheet_create` | Google Sheets operation registered by this service. |
| `sheets.sheet_add` | Google Sheets operation registered by this service. |
| `sheets.sheet_delete` | Google Sheets operation registered by this service. |
| `sheets.sheet_duplicate` | Google Sheets operation registered by this service. |
| `sheets.sheet_copy_to` | Google Sheets operation registered by this service. |
| `sheets.batch_update` | Google Sheets operation registered by this service. |

Write, delete, and sharing calls can be refused by the configured access tier or explicit safety flags. Connection and Google API failures surface through the tool call; call the relevant `check_connection` function when a scope or permission error needs diagnosis.

## Configuration

Choose the authentication mode and the narrowest access tier for each service. The five services are independently configured, so setting a high tier for one does not broaden another service.

### Google authentication

Each service has `authType` with `service` as the default and supports a service-account key, optional administrator email, or a user OAuth token. Use service authentication when the service account has the intended resource access; use user OAuth when the calls must act as the signed-in user. Missing service credentials or a user token whose scopes do not cover the selected tier produce configuration warnings.

### Google Calendar

Calendar defaults to the `write` access tier; `readonly` allows only event, calendar, ACL, and free/busy reads. Deleting events or calendars remains refused until `allowDelete` is enabled. Public or domain-wide ACL inserts require `allowPublicSharing`; keep both safety flags off unless the agent has an explicit destructive or sharing responsibility.

### Google Docs

Docs defaults to `write`, which permits document creation, text and structural updates. Use `readonly` for an agent that should only read document text and metadata. In particular, reserve `batch_update` for agents that intentionally issue structured Docs update requests.

### Google Drive

Drive defaults to `write`; `readonly` supports listing, metadata, downloading, and export without modifications. Public or external sharing is blocked until `allowPublicSharing` is on. Permanent `file_delete` bypasses Trash and is separately blocked until `allowHardDelete` is on; prefer trashing for recoverable removal.

### Gmail

Gmail defaults to `modify`, permitting reads and organization but not sending. Select `readonly` for an inspection agent, `send` when it must send mail, `settings` or `settings_sharing` only for the corresponding administrative operations, and `full` only when permanent deletion is intended. Even at the full tier, hard deletion is blocked until `allowHardDelete` is enabled.

### Google Sheets

Sheets defaults to `write`, covering spreadsheet creation, values operations, sheet structure changes, and batch updates. Select `readonly` when the agent should only retrieve values and metadata.

## Authentication

Google user mode relies on the stored user OAuth token; service mode uses the configured service account material, optionally with an administrator identity for delegated access. Select access tiers through the service configuration rather than hand-entering scopes. The connection-check tool verifies whether granted OAuth scopes cover the selected tier.

## Notes

### Separate server names

Calendar, Docs, Drive, Gmail, and Sheets use the `calendar`, `docs`, `drive`, `gmail`, and `sheets` prefixes respectively. They are distinct tool servers even though they share authentication lifecycle code.

## Upstream docs

- [Google Workspace developer documentation](https://developers.google.com/workspace)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Google Calendar (`services.calendar.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `calendar.access` | `string` | **Access level**<br/>Calendar scopes to request. readonly: read events, calendars, ACLs, and free/busy only. write: full read/write (create, update, move, quick-add events; manage calendars and ACLs). Deletion additionally requires the allowDelete flag; public/domain-wide ACL sharing requires allowPublicSharing. | `"write"` |
| `calendar.allowDelete` | `boolean` | **Allow event / calendar deletion**<br/>When off (the default), event_delete and calendar_delete are refused even at the write tier. Enable only if the agent should be able to permanently delete events and calendars — this is irreversible. | `false` |
| `calendar.allowPublicSharing` | `boolean` | **Allow public / domain-wide calendar sharing**<br/>Off by default. When off, acl_insert refuses rules that expose the calendar beyond individual grantees (scopeType 'default' = anyone on the internet, and 'domain' = everyone in a domain). Turn on to allow public or domain-wide sharing. Grants to individual users/groups are not gated. | `false` |

### Google Docs (`services.docs.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `docs.access` | `string` | **Access level**<br/>Docs scopes to request. readonly: read document text and metadata only. write: full read/write (create documents, append and replace text, insert images and tables, and run arbitrary batchUpdate requests). | `"write"` |

### Google Drive (`services.drive.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `drive.access` | `string` | **Access level**<br/>Drive scopes to request. readonly: list, read metadata, download, and export only. write: full read/write (create, update, copy, move, trash, folders, and sharing). | `"write"` |
| `drive.allowHardDelete` | `boolean` | **Allow permanent delete**<br/>Off by default. When off, file_delete (which permanently deletes a file, bypassing Trash and irreversibly) is refused. Turn on to allow permanent deletion; file_trash is the recoverable alternative. | `false` |
| `drive.allowPublicSharing` | `boolean` | **Allow public / external sharing**<br/>Off by default. When off, permission_create refuses anyone-with-link grants and grants to a domain or user outside the account's own domain. Turn on to allow sharing files publicly or with external parties. | `false` |

### Gmail (`services.gmail.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `gmail.access` | `string` | **Access level**<br/>Gmail scopes to request. readonly: read only. modify: read + label/organize. send: modify + send mail. settings: modify + filters/IMAP/POP/vacation/forwarding. settings_sharing: settings + sendAs/delegation/S⁠MIME. full: complete mailbox access, required for permanent delete. | `"modify"` |
| `gmail.allowHardDelete` | `boolean` | **Allow permanent delete**<br/>Enable permanent message/thread deletion (requires full access tier). Disabled by default to protect against accidental data loss. | `false` |

### Google Sheets (`services.sheets.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `sheets.access` | `string` | **Access level**<br/>Sheets scopes to request. readonly: read values and metadata only. write: full read/write (create, update, append, clear, and structure changes such as add/delete/duplicate sheet). | `"write"` |

## Dependencies

- `google-api-python-client`
- `google-auth`
- `google-auth-oauthlib`
- `google-auth-httplib2`
- `idna` `>=3.15`
- `protobuf` `>=5.29.6`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_google_workspace)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Calendar

Route: /nodes/tool_google_workspace/calendar

# Google Calendar tool node (`tool_calendar`)

Exposes the Google Calendar API v3 as agent tools: list, get, create, update,
move, quick-add, and delete events (including expanding recurring series into
instances); query free/busy; manage calendars; and read/insert/delete
access-control (ACL) rules.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is a
`@tool_function` an agent calls on demand. Operational targets (`calendarId`,
`eventId`, `ruleId`) are always tool-call parameters, never node config;
`calendarId` defaults to `primary`. Outputs are cleaned shapes (event
`id`/`status`/`start`/`end`/`attendees`, calendar metadata, ACL rules, free/busy
ranges), not raw API JSON.

## Configuration

| Field | Notes |
|-------|-------|
| `google.authType` | `service` (service account) or `user` (OAuth). |
| `google.serviceKey` / `google.adminEmail` | Service account JSON key; `adminEmail` enables domain-wide delegation (impersonate that user). |
| `google.oAuthButton` / `google.userToken` | User OAuth: sign in to populate the access token. |
| `calendar.access` | `readonly` or `write` (default). Resolved by the shared `CALENDAR` spec in `core/google_access.py`; scopes are never hand-entered. |
| `calendar.allowDelete` | Boolean, default **false**. When off, `event_delete` and `calendar_delete` are refused even at the write tier. Enable only to permit permanent, irreversible deletion. |
| `calendar.allowPublicSharing` | Boolean, default **false**. When off, `acl_insert` refuses rules that expose the calendar beyond individual grantees (scopeType `default` = anyone on the internet, `domain` = everyone in a domain). Grants to individual users/groups are not gated. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `calendar.readonly` | read events, calendars, ACLs, free/busy |
| `write` | `calendar` | full read/write (default) |

Deletion (`event_delete`, `calendar_delete`) requires the `write` tier **and**
`calendar.allowDelete` = true. The flag is off by default and, like gmail's
`allowHardDelete`, is absent from the default profile (absent means false).
Removing a sharing rule (`acl_delete`) is a write-tier operation and is **not**
gated by `allowDelete`.

## Tools

- **Read events:** `event_list` (with incremental sync — see below),
  `event_get`, `event_instances` (expand a recurring series), `freebusy_query`.
- **Read calendars/ACL:** `calendar_list`, `calendar_get`, `acl_list`.
- **Write events:** `event_create`, `event_update` (partial / patch semantics),
  `event_move`, `event_quick_add` (natural-language).
- **Write calendars/ACL:** `calendar_create`, `calendar_update` (patch),
  `acl_insert` (share; scopeType `default`/`domain` additionally requires
  `allowPublicSharing`), `acl_delete` (unshare).
- **Delete (write + `allowDelete`):** `event_delete`, `calendar_delete`.
- **Diagnostics:** `check_connection` probes the Calendar API with a live call;
  for user OAuth it also verifies that granted scopes cover the configured
  access tier (service-account auth has no per-user scope grant to check).

### Incremental sync (`syncToken`)

`event_list` and `calendar_list` return a `nextSyncToken` on the last page of a
fully-consumed listing. Store it, then pass it back as `syncToken` on the next
call to receive **only** the events/calendars that changed since — the efficient
way to keep a local view in sync. Do not combine `syncToken` with `timeMin` /
`timeMax` / `q`. Paginate with `nextPageToken` until it is absent; the
`nextSyncToken` appears on that final page.

### Attendee invitations (`sendUpdates`)

Event writes (`event_create`, `event_update`, `event_move`, `event_quick_add`,
`event_delete`) take a `sendUpdates` parameter — `all` (default), `externalOnly`,
or `none`. The node **always sends it explicitly**: Google's implicit default is
`none`, which would silently skip notifying attendees. Sending invitations is
normal write-tier behavior and is **not** gated separately — an agent with write
access can invite attendees, so scope the node accordingly.

`event_update` accepts an empty `description` or `location` to clear that field.
For `acl_insert`, `scopeType` must be `user`, `group`, `domain`, or `default`; `default` and `domain` rules require `calendar.allowPublicSharing` = true;
the first three require `scopeValue`.

## Setup

Authenticate with either a Google **service account** (`google.serviceKey` JSON,
optionally `google.adminEmail` for domain-wide delegation) or **user OAuth**
(click sign-in to populate `google.userToken`). The Google Calendar API must be
enabled on the Google Cloud project backing the credential.

## Limits

- `maxResults` on listings is clamped to `1..250` (default 50); page with
  `nextPageToken`.
- Free/busy queries return busy ranges per calendar plus any per-calendar errors
  (e.g. a calendar the credential cannot see).
- Rate limits are per Google project; the node retries `429`, rate-limit/quota
  `403`, and `5xx` responses with exponential backoff.

## Examples

An agent finds a free slot, then books it and invites a guest:

```text
freebusy_query  { "timeMin": "2026-07-11T09:00:00Z", "timeMax": "2026-07-11T17:00:00Z",
                  "calendarIds": ["primary"] }
event_create    { "summary": "Design sync", "start": {"dateTime": "2026-07-11T14:00:00Z"},
                  "end": {"dateTime": "2026-07-11T15:00:00Z"},
                  "attendees": [{"email": "sam@example.com"}] }
```

## Upstream docs

- Google Calendar API v3: https://developers.google.com/calendar/api/v3/reference
- Events: https://developers.google.com/calendar/api/v3/reference/events
- Sync (syncToken): https://developers.google.com/calendar/api/guides/sync
- FreeBusy: https://developers.google.com/calendar/api/v3/reference/freebusy/query

## Troubleshooting

- **Scope / 403 errors:** call `check_connection`; if scopes are missing,
  disconnect and reconnect the Google account at the required access tier.
- **`access` is read-only:** write operations raise `GoogleAccessError`; raise
  `calendar.access` to `write`.
- **Delete refused at write tier:** `event_delete` / `calendar_delete` also need
  `calendar.allowDelete` = true; it is off by default.
- **Attendees not notified:** pass `sendUpdates: "all"` (the node's default) —
  `none` suppresses invitations.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Docs

Route: /nodes/tool_google_workspace/docs

# Google Docs tool node (`tool_docs`)

Exposes the Google Docs API v1 as agent tools: read a document's text; create
documents; append and replace text; insert inline images and tables; and run
arbitrary `batchUpdate` requests (styling, named ranges, positioned inserts,
deletes).

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is a
`@tool_function` an agent calls on demand. Operational targets (`documentId`)
are always tool-call parameters, never node config. Outputs are cleaned shapes
(`documentId`, `title`, `revisionId`, `body_text`, `replies_count`,
`occurrencesChanged`), not raw API JSON.

## Configuration

| Field | Notes |
|-------|-------|
| `google.authType` | `service` (service account) or `user` (OAuth). |
| `google.serviceKey` / `google.adminEmail` | Service account JSON key; `adminEmail` enables domain-wide delegation (impersonate that user). |
| `google.oAuthButton` / `google.userToken` | User OAuth: sign in to populate the access token. |
| `docs.access` | `readonly` or `write` (default). Resolved by the shared `DOCS` spec in `core/google_access.py`; scopes are never hand-entered. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `documents.readonly` | read document text + metadata only |
| `write` | `documents` | full read/write (default) |

There are no destructive gate flags. Permanent document deletion is a Drive
operation and lives in `tool_drive`.

## Tools

- **Read:** `document_get` — returns `{documentId, title, revisionId,
  body_text}`, where `body_text` is the concatenated plain text of the
  paragraph text runs. Long documents are capped at 50,000 characters and
  flagged with `truncated: true`. Works at the `readonly` tier.
- **Write:** `document_create` (create a document, optionally seeding initial
  body text via a follow-up `insertText`), `batch_update` (the catch-all: pass
  the full Docs `batchUpdate` request list).
- **Convenience wrappers (write)** over `batch_update`, so an agent needn't do
  index math:
  - `text_append` — append text at the end of the body
    (`insertText` at `endOfSegmentLocation`).
  - `text_replace` — replace all occurrences of a string (`replaceAllText`);
    `matchCase` defaults to `false`. Returns `occurrencesChanged`.
  - `image_insert` — insert an inline image at the end of the body
    (`insertInlineImage`); the `uri` **must** be a public `https://` URL.
    Optional `width`/`height` in points (PT).
  - `table_insert` — insert an empty `rows`×`columns` table at the end of the
    body (`insertTable`); `rows` is clamped to 1..1000 and `columns` to 1..25.
- **Diagnostics:** `check_connection` probes the Docs API with a live call; for
  user OAuth it also verifies that granted scopes cover the configured access
  tier (service-account auth has no per-user scope grant to check).

The entire Docs v1 surface is `documents().get` / `create` / `batchUpdate`; the
wrappers are conveniences over `batch_update`.

## Setup

Authenticate with either a Google **service account** (`google.serviceKey` JSON,
optionally `google.adminEmail` for domain-wide delegation) or **user OAuth**
(click sign-in to populate `google.userToken`). The Google Docs API must be
enabled on the Google Cloud project backing the credential.

## Limits

- **Export is not a Docs operation.** Exporting a document to PDF or `.docx` is a
  Drive export, not a Docs API call — use `tool_drive`'s `file_export`
  (issue #1056), not this node.
- `document_get`'s `body_text` is capped at 50,000 characters (`truncated: true`
  when the document is longer) and covers paragraph text runs only — table
  cells, headers/footers, and footnotes are not concatenated. For full
  structure use `batch_update` reads or the raw document.
- `batch_update` request bodies follow Google's Docs `batchUpdate` limits.
- Rate limits are per Google project; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

An agent creates a document, appends text, then inserts a table:

```
document_create { "title": "Weekly Report", "text": "Summary\n" }
text_append     { "documentId": "1AbC...", "text": "\nMetrics below:\n" }
table_insert    { "documentId": "1AbC...", "rows": 3, "columns": 2 }
```

Replace a placeholder throughout a template:

```
text_replace    { "documentId": "1AbC...", "containsText": "{{name}}",
                  "text": "Ada Lovelace", "matchCase": true }
```

## Upstream docs

- Google Docs API v1: https://developers.google.com/docs/api/reference/rest
- `documents.batchUpdate`: https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
- Request types (insertText, replaceAllText, insertInlineImage, insertTable): https://developers.google.com/docs/api/reference/rest/v1/documents/request

## Troubleshooting

- **Scope / 403 errors:** call `check_connection`; if scopes are missing,
  disconnect and reconnect the Google account at the required access tier.
- **`access` is read-only:** write operations raise `GoogleAccessError`; raise
  `docs.access` to `write`.
- **`image_insert` rejects the URL:** the `uri` must be a public `https://` URL
  Google can fetch (not `http://`, a data URL, or a private/authenticated link).

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Drive

Route: /nodes/tool_google_workspace/drive

# Google Drive tool node (`tool_drive`)

Exposes the Google Drive API v3 as agent tools: list and search files, read
metadata, download binary files and export native Docs/Sheets/Slides,
create/update/copy/move files and folders, manage sharing (permissions),
trash/untrash, track changes, and permanently delete. Works across My Drive and
shared drives.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is a
`@tool_function` an agent calls on demand. Operational targets (`fileId`,
`folderId`, `permissionId`) are always tool-call parameters, never node config.
Outputs are cleaned shapes (`id`, `name`, `mimeType`, `parents`, `webViewLink`,
`modifiedTime`, `size`, `trashed`, `driveId`), not raw API JSON. Every file
operation sets `supportsAllDrives` so shared-drive items work transparently.

## Configuration

| Field | Notes |
|-------|-------|
| `google.authType` | `service` (service account) or `user` (OAuth). |
| `google.serviceKey` / `google.adminEmail` | Service account JSON key; `adminEmail` enables domain-wide delegation (impersonate that user) and sets the account's own domain for the sharing gate. |
| `google.oAuthButton` / `google.userToken` | User OAuth: sign in to populate the access token. |
| `drive.access` | `readonly` or `write` (default). Resolved by the shared `DRIVE` spec in `core/google_access.py`; scopes are never hand-entered. |
| `drive.allowPublicSharing` | Off by default. Gate for anyone-with-link and external-domain grants (see Sharing gate). |
| `drive.allowHardDelete` | Off by default. Gate for `file_delete` (permanent delete, bypasses Trash, irreversible). |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `drive.readonly` | list/search, read metadata and permissions, download, export |
| `write` | `drive` | full read/write (default) |

## Tools

- **Read:** `file_list` (optional query `q`), `file_search` (query required),
  `file_get` (metadata), `file_download` (non-native binary → base64),
  `file_export` (native Docs/Sheets/Slides → base64 in a chosen format),
  `drives_list` (shared drives), `changes_list` (change tracking),
  `permission_list` (sharing entries).
- **Write:** `file_create`, `file_update`, `file_copy`, `file_move`,
  `file_trash`, `file_untrash`, `folder_create`, `permission_update`,
  `permission_delete`, `permission_create`.
- **Gated:** `file_delete` (permanent delete).
- **Diagnostics:** `check_connection` probes the Drive API with a live call;
  for user OAuth it also verifies that granted scopes cover the configured
  access tier (service-account auth has no per-user scope grant to check).

### Download vs. export (native files)

Google-native files (Docs, Sheets, Slides — `mimeType`
`application/vnd.google-apps.*`) have **no binary blob**. `file_download`
**refuses** them with a pointer to `file_export`. Use `file_export` with a
target `mimeType` (e.g. `application/pdf`,
`application/vnd.openxmlformats-officedocument.wordprocessingml.document` for
`.docx`, `text/csv` for Sheets) to render native files into a real format. Both
return `{fileId, mimeType, size, data_base64}`. `file_download` caps at 10 MiB
(checked via metadata first); `file_export` is capped at ~10 MiB by Google.
`file_export`'s PDF/`.docx` output is what feeds the `tool_docs` / #1058 export
workflow.

### Sharing gate (`permission_create` + `allowPublicSharing`)

Granting access is gated so an agent cannot silently make files public or share
them externally. The account's **own domain** is resolved from `adminEmail`
(service auth) or from the user token's `hd`/`email` claim (user auth); when it
can't be determined it is **unknown**.

| Grant `type` | Requires `allowPublicSharing`? |
|--------------|--------------------------------|
| `anyone` (public link) | Always. |
| `domain` == account's own domain | No. |
| `domain` != own domain (or unknown) | Yes. |
| `user` / `group`, same domain as account | No. |
| `user` / `group`, different domain (account domain known) | Yes. |
| `user` / `group`, account domain **unknown** | No — treated as internal. |

Both the public-link and external-party cases are gated by the single
`allowPublicSharing` flag. When it is off, a gated grant raises
`GoogleAccessError` naming the flag. `user`/`group` grants always send a
notification email by default (`sendNotificationEmail`, default `true`).

Moving or copying a file into an already-public folder inherits that folder's
ACL, which is a sharing path this gate cannot see.

### Hard-delete gate (`file_delete` + `allowHardDelete`)

`file_delete` **permanently** removes a file, bypassing Trash — **irreversible**.
It requires the `write` tier **and** the `allowHardDelete` flag. `file_trash`
(recoverable) is the safe alternative and needs only `write`.

### Shared drives

Every file operation passes `supportsAllDrives=True` (and reads pass
`includeItemsFromAllDrives=True`), so files on shared drives are visible and
mutable. `file_list`/`file_search` accept `driveId` + `corpora` to scope a
search to one shared drive; `drives_list` enumerates accessible shared drives;
`changes_list` accepts a `driveId` to track a specific shared drive.

## Setup

Authenticate with either a Google **service account** (`google.serviceKey` JSON,
optionally `google.adminEmail` for domain-wide delegation) or **user OAuth**
(click sign-in to populate `google.userToken`). The Drive API must be enabled on
the Google Cloud project backing the credential.

## Limits

- `file_download` caps at 10 MiB (checked from metadata before fetching);
  `file_export` at Google's ~10 MiB export limit.
- List calls page with `pageToken`; `pageSize` clamps to 1–100 (default 25).
- Rate limits are per Google project; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

```text
file_search   { "q": "name contains 'invoice' and trashed = false" }
file_get      { "fileId": "1AbC..." }
file_export   { "fileId": "1Doc...", "mimeType": "application/pdf" }
file_trash    { "fileId": "1AbC..." }
```

## Upstream docs

- Google Drive API v3: https://developers.google.com/drive/api/reference/rest/v3
- Search query syntax: https://developers.google.com/drive/api/guides/search-files
- Exporting native files: https://developers.google.com/drive/api/guides/manage-downloads

## Troubleshooting

- **Scope / 403 errors:** call `check_connection`; if scopes are missing,
  disconnect and reconnect the Google account at the required access tier.
- **`access` is read-only:** write operations raise `GoogleAccessError`; raise
  `drive.access` to `write`.
- **Sharing refused:** the grant is public/external and `allowPublicSharing` is
  off — enable it, or grant to an internal user/domain.
- **Delete refused:** `file_delete` needs `allowHardDelete`; use `file_trash`
  for a recoverable delete.
- **`file_download` refused:** the file is Google-native — use `file_export`.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Gmail

Route: /nodes/tool_google_workspace/gmail

# Gmail tool node (`tool_gmail`)

Exposes the Gmail v1 API as agent tools: read/search/organize mail, manage
labels and drafts, send (including in-thread replies), and—when explicitly
enabled—permanently delete.

## Configuration

| Field | Notes |
|-------|-------|
| `google.authType` | `service` (service account) or `user` (OAuth). |
| `google.serviceKey` / `google.adminEmail` | Service account JSON key; adminEmail enables domain-wide delegation (impersonate that user). |
| `google.oAuthButton` / `google.userToken` | User OAuth: sign in to populate the access token. |
| `gmail.access` | `readonly` → `modify` → `send` → `full`. Resolved by the shared `GMAIL` spec in `core/google_access.py`; scopes are never hand-entered. |
| `gmail.allowHardDelete` | Off by default. Gate for permanent delete; only effective with `access: full`. |

## Access tiers → scopes

| Tier | Scope(s) | Capability |
|------|----------|------------|
| `readonly` | `gmail.readonly` | read/search only |
| `modify` | `gmail.modify` | read + label/organize (default) |
| `send` | `gmail.modify`, `gmail.send` | + send mail |
| `full` | `https://mail.google.com/` | + permanent delete (with `allowHardDelete`) |

## Tools

- **Read/sync:** `message_list`, `message_get`, `message_search`, `thread_get`,
  `thread_list`, `label_list`, `draft_list`, `draft_get`, `attachment_get`,
  `history_list`.
- **Organize (write):** `message_modify`, `message_batch_modify`, `label_apply`,
  `label_remove`, `label_create`, `label_update`, `label_delete`. Change read
  state by adding/removing the `UNREAD` label via `message_modify` /
  `message_batch_modify`.
- **Write:** `message_send` (reply in-thread via `threadId`), `message_trash`,
  `message_untrash`, `draft_create`, `draft_update`, `draft_send`,
  `draft_delete`. Sending requires the `send` or `full` tier.
- **Permanent delete (gated):** `message_delete`, `messages_batchDelete` —
  require `allowHardDelete` **and** the `full` tier; batch ops take an explicit
  id list (never a query), capped at 1000 per call.
- **Diagnostics:** `check_connection` probes the Gmail API with a live call;
  for user OAuth it also verifies that granted scopes cover the configured
  access tier (service-account auth has no per-user scope grant to check).

Operational targets (`messageId`, `threadId`, `labelId`, `query`) are always
tool-call parameters, never node config. Outputs are cleaned shapes (ids,
labelIds, snippet, headers, threadId, historyId), not raw API JSON.


---

# Sheets

Route: /nodes/tool_google_workspace/sheets

# Google Sheets tool node (`tool_sheets`)

Exposes the Google Sheets API v4 as agent tools: read, write, append, and clear
cell values; create spreadsheets; add, delete, duplicate, and copy sheets; and
run arbitrary `batchUpdate` requests (formatting, charts, conditional
formatting, sheet deletion).

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is a
`@tool_function` an agent calls on demand. Operational targets
(`spreadsheetId`, `sheetId`, ranges) are always tool-call parameters, never node
config. Outputs are cleaned shapes (`updatedRange`, `updatedRows`,
`updatedCells`, `values`, sheet properties), not raw API JSON.

## Configuration

| Field | Notes |
|-------|-------|
| `google.authType` | `service` (service account) or `user` (OAuth). |
| `google.serviceKey` / `google.adminEmail` | Service account JSON key; `adminEmail` enables domain-wide delegation (impersonate that user). |
| `google.oAuthButton` / `google.userToken` | User OAuth: sign in to populate the access token. |
| `sheets.access` | `readonly` or `write` (default). Resolved by the shared `SHEETS` spec in `core/google_access.py`; scopes are never hand-entered. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `spreadsheets.readonly` | read values + metadata only |
| `write` | `spreadsheets` | full read/write (default) |

There are no destructive gate flags. Note that sheet deletion and value clears
are NOT trash-recoverable — the Sheets API has no trash; recovery is only
possible through the spreadsheet's version history. Permanent spreadsheet
deletion is a Drive operation and lives in `tool_drive`.

## Tools

- **Read:** `spreadsheet_get` (metadata + sheet properties), `values_get`
  (one A1 range), `values_batch_get` (multiple ranges).
- **Write values:** `values_update`, `values_batch_update`, `values_append`,
  `values_clear`. Writes use `valueInputOption` (default `USER_ENTERED`, so
  `=SUM(...)` becomes a formula and `1,000` a number; pass `RAW` to store
  literally).
- **Structure (write):** `spreadsheet_create`, `sheet_add`, `sheet_delete`,
  `sheet_duplicate`, `sheet_copy_to` (copy a tab into another spreadsheet).
- **Catch-all (write):** `batch_update` accepts the full Sheets `batchUpdate`
  request list — formatting, charts, conditional formatting, protected ranges,
  and sheet deletion all go through it. `sheet_add` / `sheet_delete` /
  `sheet_duplicate` are convenience wrappers over the same endpoint;
  `sheet_copy_to` is the separate `spreadsheets.sheets.copyTo` endpoint.
- **Diagnostics:** `check_connection` probes the Sheets API with a live call;
  for user OAuth it also verifies that granted scopes cover the configured
  access tier (service-account auth has no per-user scope grant to check).

## Setup

Authenticate with either a Google **service account** (`google.serviceKey` JSON,
optionally `google.adminEmail` for domain-wide delegation) or **user OAuth**
(click sign-in to populate `google.userToken`). The Sheets API must be enabled
on the Google Cloud project backing the credential.

## Limits

- `batch_update` request bodies follow Google's Sheets `batchUpdate` limits.
- Value ranges use A1 notation; very large reads should be paged by range.
- Rate limits are per Google project; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

An agent reads a range, then appends a row:

```
values_get      { "spreadsheetId": "1AbC...", "range": "Sheet1!A1:C10" }
values_append   { "spreadsheetId": "1AbC...", "range": "Sheet1!A1",
                  "values": [["2026-07-10", "Widget", 42]] }
```

## Upstream docs

- Google Sheets API v4: https://developers.google.com/sheets/api/reference/rest
- `spreadsheets.values`: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values
- `spreadsheets.batchUpdate`: https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/batchUpdate

## Troubleshooting

- **Scope / 403 errors:** call `check_connection`; if scopes are missing,
  disconnect and reconnect the Google account at the required access tier.
- **`access` is read-only:** write operations raise `GoogleAccessError`; raise
  `sheets.access` to `write`.
- **Empty `values`:** the range may be outside the populated grid, or
  `valueRenderOption` may be filtering formulas — try `UNFORMATTED_VALUE`.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Guild.ai

Route: /nodes/tool_guild

# tool_guild

A RocketRide node that runs Guild.ai agents as a pipeline step or as a tool another AI agent can invoke.

+## About Guild.ai

Guild.ai is a platform for building and operating governed AI agents. Its agents run in
Guild workspaces, where a trigger API key authorizes an external system to start sessions.

## What it does

Use this node to hand prepared RocketRide data to a configured Guild agent, either as a
pipeline step or as a tool another agent can call. It is a bridge to a remote agent runtime,
not a parser, vector store, or search node. The pipeline face always waits for the Guild
session; the tool face can return a session identifier immediately.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `text` | `text` | Sends text to the configured agent and emits its answer as text. |
| `text` | `answers` | Sends text to the configured agent and emits its answer as an answer. |
| `text` | `table` | Sends text to the configured agent and emits session data as a table row. |
| `questions` | `answers` | Sends the question text and emits the answer. |
| `questions` | `text` | Sends the question text and emits the answer as text. |
| `questions` | `table` | Sends the question text and emits session data as a table row. |
| `documents` | `documents` | Sends document text and emits the answer as a document. |
| `documents` | `text` | Sends document text and emits the answer as text. |
| `documents` | `table` | Sends document text and emits session data as a table row. |

Inputs are joined with newlines. Empty input starts no session, and an empty configured
agent is an error. The pipeline step always waits, regardless of Result mode.

## As a tool

The tool server prefix is `guild` by default. It registers these functions:

| Function | Description |
| --- | --- |
| `guild.run_agent` | Starts a Guild agent session, optionally waiting for its answer. |
| `guild.get_session` | Returns a session's current status. |
| `guild.get_session_events` | Returns recent session events and extracted output. |

`run_agent` requires `input`; optional `agent` overrides the configured default and
optional `wait` otherwise follows Result mode. It returns `{success, session_id, status,
output}`; with `wait: false`, status is `running` and output is null. `get_session`
requires `session_id` and returns `{success, session_id, status}`.
`get_session_events` requires `session_id`, accepts `limit` from 1–1000 (default 100),
and returns `{success, events, output}`, using the tail when needed so the final output is
not dropped.

Bad input and missing configuration raise `ValueError`; API, transport, and session failures
raise `RuntimeError`. A waited-session timeout does not cancel the remote session and includes
its ID in the resulting error. Starting a session is not retried, avoiding duplicate runs.

## Configuration

Configure the connection, workspace identity, and default agent before enabling either face.
The connection fields can use their matching `ROCKETRIDE_GUILD_*` environment variables
when the node field is blank; run options are read only from node configuration.

### Agent and Result mode

The configured agent is required by pipeline execution and is the default for `run_agent`.
Result mode defaults to `wait`; use `start` only when a tool caller should receive a session
ID for later inspection. The pipeline ignores `start` and waits because downstream lanes need
the result.

### Session timeout and session budget

Timeout defaults to 300 seconds and is constrained to 5–3600 seconds. Raise it for an agent
that legitimately needs a longer run; do not mistake a local timeout for cancellation of the
Guild session. Max sessions defaults to 10 and is a shared per-run reservation, so lower it to
limit an agent that could repeatedly invoke the tool.

### TLS verification

Leave TLS verification enabled. Disable it only for a self-hosted Guild deployment using a
self-signed certificate, since it otherwise verifies the server certificate for each request.

## Authentication

Guild uses HTTP Basic authentication with a trigger API key: **API Key ID** is the username
and **API Key Secret** is the password. Configure both halves, along with the workspace owner
and workspace; the secret is a secure field.

## Notes

### Session output and identifiers

Agent and session identifiers are restricted to plain path-segment values before requests are
formed. GET calls may retry transient errors up to twice, whereas session-start POST calls never
retry. If the session contains no final-answer event, its successful output is an empty string.

## Upstream docs

- [Guild triggers documentation](https://docs.guild.ai/platform/triggers)

<!-- Legacy pre-schema prose retained below only while the generated documentation is preserved. -->

> Not to be confused with `guildai.org`, an unrelated ML experiment-tracking tool.

### What it does

Guild.ai is a control plane for AI agents: agents are authored, versioned, and governed in a
Guild workspace, and the Guild runtime injects credentials so an agent never sees a raw API key.
Guild has no data-processing model of its own - no parsing, chunking, embedding, or vector
search.

That is the division of labour this node exists for. A RocketRide pipeline does the data work
(ingest, parse, chunk, embed, retrieve), then hands a well-formed payload to a governed Guild
agent to perform the action.

The node has two faces, both backed by the same three REST calls:

- **As a pipeline step**, lane input is sent to the agent configured on the node and its answer
  flows downstream. The step always runs exactly once - deterministic, no prompt tuning.
- **As a tool**, an agent decides when to invoke `run_agent` to delegate work, plus `get_session`
  / `get_session_events` to follow up on a session it started earlier.

Guild runs agents **asynchronously**: every call starts a session and this node polls it to
completion (there is no synchronous mode on Guild's side to expose).

### As a pipeline node

Lane input is flattened into the input for the **configured** agent, a session is started and
polled to completion, and the agent's answer is emitted downstream.

| Lane in     | Lane out                       | Description                                             |
| ----------- | ------------------------------ | ------------------------------------------------------- |
| `text`      | `text`, `answers`, `table`     | Sends the text to the configured agent; emits its answer |
| `questions` | `answers`, `text`, `table`     | Sends the question text; emits the answer                |
| `documents` | `documents`, `text`, `table`   | Sends the document text; emits the answer                |

The answer is written to whichever output lanes are connected; a `table` listener additionally
receives `{session_id, status, output}` for downstream DB/ETL nodes. An **Agent** must be
configured - the pipeline step raises if it is empty. Empty input starts no session.

Example: [`examples/guild-agent.pipe`](../../../../examples/guild-agent.pipe) (chat -> Guild.ai ->
response).

### As a tool

Exposes three functions to an agent. Tools are namespaced by the node's **id** in the pipeline,
not by the node's `prefix`: a node with id `tool_guild_1` exposes `tool_guild_1.run_agent`. Use
the fully namespaced form when instructing an agent to call them.

| Tool | Description |
|---|---|
| `run_agent` | Run a Guild agent on some input and return its answer. |
| `get_session` | Check whether a session is running, completed, or failed. |
| `get_session_events` | Read a session's transcript, including its final answer. |

### `run_agent`

| Parameter | Required | Description |
|---|---|---|
| `input` | yes | Text sent to the Guild agent as its input. |
| `agent` | no | Agent to run. Defaults to the agent configured on the node. |
| `wait` | no | Wait for the answer (default), or start the session and return only its id. |

Returns `{ success, session_id, status, output }`.

Each call starts a **billed** Guild session and is not idempotent - a successful call should
never be retried.

### `get_session`

| Parameter | Required | Description |
|---|---|---|
| `session_id` | yes | Id of the session to inspect. |

Returns `{ success, session_id, status }`, where `status` is `running`, `completed`, or `failed`.

### `get_session_events`

| Parameter | Required | Description |
|---|---|---|
| `session_id` | yes | Id of the session to read. |
| `limit` | no | Max events to return (default 100, capped at 1000). |

Returns `{ success, events, output }`. Events are oldest-first (the answer is last), so when the
transcript is longer than `limit` the **most recent** `limit` events are returned — the answer is
never dropped. The node follows the endpoint's pagination to reach the tail.

Errors are raised, never returned as error dicts: `ValueError` for bad input or missing
configuration, `RuntimeError` for API and transport failures. The engine converts a raised
exception into the structured error an agent sees, so an agent can still read the message and
correct itself.

Example: [`examples/guild-delegate-agent.pipe`](../../../../examples/guild-delegate-agent.pipe)
(a RocketRide agent with Guild.ai bound as a tool).

### Configuration

| Field | Type | Description |
|---|---|---|
| Guild Base URL | `string` | Default `https://app.guild.ai`. Override only for an enterprise or self-hosted deployment. |
| API Key ID | `string` | The id half of a Guild trigger API key - the HTTP Basic username. Stored as a secure field. |
| API Key Secret | `string` | The secret half - the Basic password. Shown once when the key is created. Stored as a secure field. |
| Workspace owner | `string` | The owner segment of the workspace URL (`app.guild.ai/<owner>/<workspace>`). |
| Workspace | `string` | The workspace segment of that URL. |
| Agent | `string` | Agent to run as the pipeline step, and the default for `run_agent`. Required for the pipeline step. |
| Result mode | `enum` | Default `wait`. `start` returns a session id without waiting - useful for fire-and-forget tool calls. The pipeline step always waits. |
| Session timeout (seconds) | `integer` | Default 300, range 5-3600. How long to poll before raising. |
| Max sessions per run | `integer` | Default 10, range 1-1000. Cap on billed Guild sessions per pipeline run. |
| Verify TLS certificate | `boolean` | Default on. Disable only for a self-hosted Guild with a self-signed certificate. |

The connection fields fall back to an environment variable when left empty: `ROCKETRIDE_GUILD_URL`
(Base URL), `ROCKETRIDE_GUILD_KEY_ID`, `ROCKETRIDE_GUILD_KEY_SECRET`, `ROCKETRIDE_GUILD_OWNER`,
`ROCKETRIDE_GUILD_WORKSPACE`, and `ROCKETRIDE_GUILD_AGENT`. The run options (result mode, session
timeout, max sessions, verify TLS) are read from the node config only.

Out-of-range or non-numeric timeouts fall back to their defaults rather than failing the run.

### Notes

- **Pipeline step vs tool.** The pipeline step runs the agent exactly once - deterministic, no
  prompt tuning. The tool lets an agent decide *whether* and *how often* to call; an agent that
  is not told to call once may start several sessions in one turn, each billed. When you bind
  this node as a tool, instruct the agent to call `run_agent` once and return its answer.
- **First session can be slow.** Guild sessions run on Guild's runtime; a cold start (notably on
  the free tier) can take tens of seconds before warming up. Set the session timeout with room to
  spare.
- **Result mode `start`** is only meaningful for the tool face (fire-and-forget). The pipeline
  step always waits, because a bare session id is of no use to downstream nodes.

### Safety limits

- **Max sessions per run** caps how many sessions one pipeline run may start. Guild bills per
  automation and the free tier allows only 100 per month, so this bounds a runaway agent loop.
  Reserved before the request is sent, so the cap gates the billable call itself.
- **Session timeout** bounds polling. A timeout here does **not** cancel the session on Guild -
  the session id is included in the error so the run stays traceable.
- **POSTs are never retried.** Replaying a session start would bill a second automation. Only
  idempotent GETs retry, at most twice, honouring `Retry-After`.
- **Agent-supplied identifiers** (`agent`, `session_id`) are validated as plain identifiers, so a
  tool call cannot smuggle a path or redirect the request off the configured host.
- **Error messages never echo response bodies**, which can contain the prompt that was sent.

### Authentication

Guild authenticates machine access with a **trigger API key** over HTTP Basic: the key id is the
username, the key secret the password. Create one on the trigger's page in the Guild app; the
secret is shown only once.

Both halves are required - setting only one raises a config warning. A `401` from Guild most
often means the key is scoped to a different trigger than the agent being run, since Guild
scopes trigger API keys per trigger.

See the [Guild triggers documentation](https://docs.guild.ai/platform/triggers) for how keys and
API triggers are set up.

### Limits

- Read and run only. The node cannot deploy, roll back, or fork agents, and cannot manage
  credentials or policies - those are governance surfaces that belong to Guild's own UI.
- No agent discovery: Guild publishes no REST endpoint for listing agents, so the agent name must
  be configured or passed by the caller.
- No streaming. Guild streams partial output over WebSocket; this node polls instead.
- Text only - binary lanes are not forwarded.

-->

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_guild.agent` | `string` | **Agent**<br/>Agent to run as the pipeline step, and the default for the run_agent tool. Required for the pipeline step; an agent may override it per call. | `""` |
| `tool_guild.apiKeyId` | `string` | **API Key ID**<br/>The id half of a Guild trigger API key. Guild authenticates with HTTP Basic — the key id is the username. Create a key on the trigger's page in the Guild app. | `""` |
| `tool_guild.apiKeySecret` | `string` | **API Key Secret**<br/>The secret half of the Guild trigger API key (the Basic auth password). Shown once when the key is created. | `""` |
| `tool_guild.baseUrl` | `string` | **Guild Base URL**<br/>Base URL of the Guild API. Leave as the default for Guild Cloud; override only for an enterprise or self-hosted deployment. | `"https://app.guild.ai"` |
| `tool_guild.maxSessions` | `integer` | **Max sessions per run**<br/>Cap on Guild sessions this node may start in one pipeline run. Guild bills per automation (the free tier allows 100/month), so this bounds a runaway agent loop. | `10` |
| `tool_guild.owner` | `string` | **Workspace owner**<br/>The owner name that the workspace lives under, as it appears in the Guild app URL (app.guild.ai/<owner>/<workspace>). | `""` |
| `tool_guild.resultMode` | `string` | **Result mode**<br/>Guild runs agents asynchronously; 'wait' polls the session until it finishes. 'start' returns the session id without waiting — useful for fire-and-forget tool calls, but the pipeline step always waits (a session id is of no use downstream). | `"wait"` |
| `tool_guild.timeout` | `integer` | **Session timeout (seconds)**<br/>Max seconds to wait for a session to finish before raising. Guild's own turn timeout is 3600s; a timeout here does NOT cancel the session on Guild's side — the session id is reported so the run stays traceable. | `300` |
| `tool_guild.verifyTls` | `boolean` | **Verify TLS certificate**<br/>Leave ON. Disable only for a self-hosted Guild served with a self-signed certificate. | `true` |
| `tool_guild.workspace` | `string` | **Workspace**<br/>The Guild workspace holding the agent to run, as it appears in the app URL. | `""` |

## Dependencies

- `requests` `>=2.34.2`
- `idna` `>=3.10`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_guild)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# HTTP Request

Route: /nodes/tool_http_request

# tool_http_request

A RocketRide tool node that lets an AI agent make guarded HTTP requests to public API endpoints.

## About HTTP

HTTP is the request-and-response protocol used by web APIs. An HTTP request names a URL,
method, headers, credentials, and optional body, while a response carries status, headers,
and content.

## What it does

This node provides one controlled HTTP client for an agent and has no pipeline lanes. Pick
it when the agent must call a public API endpoint directly; use a product-specific tool when
that service already has a dedicated node and richer operations. Method switches, URL
patterns, the network boundary, and rate limits are enforced before every request.

## As a tool

The hidden server-name setting defaults to `http`, so the registered function is
`http.http_request` by default.

| Function | Description |
| --- | --- |
| `http.http_request` | Makes one guarded HTTP request and returns its completed response. |

`url` and `method` are required. The method must be one of GET, POST, PUT, PATCH,
DELETE, HEAD, or OPTIONS and must be enabled in configuration. Optional inputs include
headers, query parameters, path parameters, timeout, advanced authentication and body
objects, plus `body_json`, `bearer_token`, and `basic_auth` shortcuts. A completed
response—including a non-2xx HTTP response—returns `status_code`, `status_text`,
`headers`, `body`, `json`, `elapsed_ms`, and `content_type`.

Invalid input, disabled methods, whitelist rejection, rate-limit rejection, and transport
errors raise tool errors. A parsed JSON field is null when the response type is not JSON-like
or cannot be parsed; the raw text remains in `body`.

## Configuration

Use the default method set for a broad but controlled API agent, then limit endpoints and
throughput for the services it is allowed to reach. The server name changes the function
namespace and should be stable once an agent prompt refers to it.

### Allowed methods

GET, POST, PUT, PATCH, and DELETE are enabled by default; HEAD and OPTIONS are disabled.
Enable only methods that the intended API flow needs, especially before giving an agent
access to a URL where mutation is possible.

### URL Whitelist

An empty whitelist allows every public URL; non-public network destinations remain blocked
either way. Non-empty patterns are matched against the request URL, so anchor them when the
endpoint scope must be exact, for example `^https://api.example.com/`. Path-parameter
replacements are percent-encoded to remain a single URL path segment.

### Network boundary

Private, loopback, link-local, and multicast destination addresses are blocked. Redirects
are returned to the agent as 3xx responses and are not followed automatically. There is no
private-network override: localhost and internal endpoints are intentionally unsupported.

### Rate limits

The defaults are 10 requests per second, 100 per minute, and five concurrent requests.
The token buckets and concurrency limit reject immediately rather than queue, so an agent
must retry later after a limit error. Set all three values explicitly to zero to disable
limiting; otherwise each configured value is clamped to at least one.

## Authentication

This node has no stored service credential: provide credentials per request. The simple
shortcuts set bearer or Basic authentication when the equivalent advanced object is absent.
Advanced authentication supports `none`, `basic`, `bearer`, and an API key placed in a
header or query parameter.

## Notes

### Request bodies and timeout

`body_json` serializes objects and arrays as JSON; a string is used verbatim. The advanced
body supports raw content, multipart form data, and URL-encoded form data. Timeout defaults
to 30 seconds, caps positive values at 300 seconds, and treats zero or negative values as
the default.

## Upstream docs

- [HTTP documentation at MDN](https://developer.mozilla.org/docs/Web/HTTP)

<!-- Legacy pre-schema prose retained below only while the generated documentation is preserved. -->

### What it does

Exposes a single agent-callable tool, `http_request`, registered as
`<serverName>.http_request` (default: `http.http_request`). The agent provides the full
request (method, URL, headers, query/path parameters, auth, and body) and receives a
structured response containing status, headers, body text, parsed JSON, and timing.

Uses the **requests** library to execute calls. The node has no lanes; it is attached to
an agent purely as a tool.

Four security guardrails are enforced before every request:

- **Allowed methods**: per-method toggles. `GET`, `POST`, `PUT`, `PATCH`, `DELETE` are
  enabled by default; `HEAD` and `OPTIONS` are disabled by default.
- **URL whitelist**: regex patterns the request URL must match. **Empty by default,
  which allows all public URLs** (config validation emits a warning when the whitelist is
  empty).
- **Network boundary**: private, loopback, link-local, and multicast destination addresses
  are blocked. Redirects are returned to the agent as 3xx responses and are not followed
  automatically. There is no private-network override: localhost and internal endpoints are
  intentionally unsupported.
- **Rate limiting**: token-bucket limits per second and per minute, plus a concurrency
  cap. On by default (10/s, 100/min, 5 concurrent).

---

### Configuration


| Field | Type | Description |
|---|---|---|
| `serverName` | string | Default "http". Namespace prefix for the tool: <serverName>.http_request |
| `allowGET` | boolean | Default true.  |
| `allowPOST` | boolean | Default true.  |
| `allowPUT` | boolean | Default true.  |
| `allowPATCH` | boolean | Default true.  |
| `allowDELETE` | boolean | Default true.  |
| `allowHEAD` | boolean | Default false.  |
| `allowOPTIONS` | boolean | Default false.  |
| `whitelistPattern` | string | Default empty.  |
| `urlWhitelist` | array | Regex patterns for allowed public URLs. A request URL must match at least one pattern. If empty, all public URLs are allowed; non-public network destinations remain blocked. |
| `rateLimitPerSecond` | number | Default 10. Maximum number of HTTP requests allowed per second. Uses a token-bucket algorithm for smooth enforcement. |
| `rateLimitPerMinute` | number | Default 100. Maximum number of HTTP requests allowed per minute. Provides a broader throttle beyond the per-second limit. |
| `maxConcurrentRequests` | number | Default 5. Maximum number of HTTP requests that can be in-flight simultaneously. |


The node ships one profile, **Default**, which sets `serverName` to `http`.

An invalid non-empty whitelist regex now fails configuration validation rather than being
skipped, so a typo can no longer silently widen the restriction. Blank or whitespace-only
placeholder rows are ignored; a whitelist made only of them allows all public destinations.

---

### Available tools


| Tool | Description |
|---|---|---|
| `http_request` | Make an HTTP request. Required: "url" and "method". For JSON bodies, pass "body_json" as a JSON object (e.g. {"name": "foo"}), it is serialized automatically. For bearer auth, pass "bearer_token" as a string. For basic auth, pass "basic_auth": {"username": "...", "password": "..."}. Optional: "headers", "query_params", "path_params", "timeout" (seconds, default 30, max 300). |


### Required parameters

| Parameter | Description                                                   |
|-----------|---------------------------------------------------------------|
| `url`     | Full URL, e.g. `https://api.example.com/users/1`              |
| `method`  | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS` |

### Convenience shortcuts

These cover the common cases without the verbose `auth` / `body` objects. Each shortcut
is only applied when the corresponding advanced field is not also set.

| Parameter      | Description                                                                 |
|----------------|-----------------------------------------------------------------------------|
| `body_json`    | JSON object or array, passed directly, serialized automatically and sent as raw `application/json` |
| `bearer_token` | Token string, sent as an `Authorization: Bearer ...` header                |
| `basic_auth`   | `{username, password}` for HTTP basic auth                                  |

### Optional parameters

| Parameter      | Description                                                              |
|----------------|---------------------------------------------------------------------------|
| `query_params` | Key-value pairs appended to the URL as the query string                  |
| `headers`      | Custom request headers                                                   |
| `path_params`  | Replacements for `:name` placeholders in the URL (e.g. `{"id": "123"}` replaces `:id`) |
| `timeout`      | Request timeout in seconds. Default `30`, capped at `300`.               |
| `auth`         | Advanced auth config (see Authentication below). Prefer the shortcuts.   |
| `body`         | Advanced body config (see Request bodies below). Prefer `body_json`.     |

### Response

```json
{
  "status_code": 200,
  "status_text": "OK",
  "headers": { ... },
  "body": "...",
  "json": { ... },
  "elapsed_ms": 142,
  "content_type": "application/json"
}
```

`json` is populated automatically when the response `Content-Type` contains `json` (or
`javascript`) and the body parses; otherwise it is `null` and the raw text is in `body`.
`elapsed_ms` is wall-clock request time in milliseconds.

---

### Authentication

The `auth` object supports `type`: `none`, `basic`, `bearer`, or `api_key`.

| Type      | Fields                                            | Effect                                                       |
|-----------|---------------------------------------------------|--------------------------------------------------------------|
| `basic`   | `basic: {username, password}`                     | HTTP basic auth                                              |
| `bearer`  | `bearer: {token}`                                 | `Authorization: Bearer <token>` header                       |
| `api_key` | `api_key: {key, value, add_to}`                   | Adds `key: value` as a header (`add_to: "header"`, the default) or query parameter (`add_to: "query_param"`) |

For the common cases, the `bearer_token` and `basic_auth` shortcuts are simpler and
expand to the same thing.

---

### Request bodies

The `body` object supports `type`: `none`, `raw`, `form_data`, or `x_www_form_urlencoded`.

| Type                     | Fields                          | Effect                                                                |
|--------------------------|---------------------------------|------------------------------------------------------------------------|
| `raw`                    | `raw: {content, content_type}`  | Sends `content` as-is. `content_type` must be one of `application/json` (default), `application/xml`, `text/html`, `text/javascript`, `text/plain`; it becomes the `Content-Type` header unless one is already set. |
| `form_data`              | `form_data: {key: value, ...}`  | Sent as a `multipart/form-data` envelope                              |
| `x_www_form_urlencoded`  | `urlencoded: {key: value, ...}` | Sent as URL-encoded form fields                                       |

For JSON payloads, prefer the `body_json` shortcut, pass the object directly and it is
serialized and wrapped as raw `application/json` automatically.

---

### Rate limiting

Three independent limits are enforced per node (shared across all calls):

- **Per-second**: token bucket, capacity and refill rate equal to `rateLimitPerSecond`.
- **Per-minute**: token bucket, capacity `rateLimitPerMinute`, refilling continuously.
- **Concurrency**: semaphore capped at `maxConcurrentRequests` in-flight requests.

The limiter does **not** queue or block: when a limit is hit the tool call fails
immediately with an error telling the agent to retry after a short delay (or to wait
for an in-flight request, for the concurrency limit). The concurrency check runs first
so a rejected request never consumes rate tokens.

To disable rate limiting entirely, set **all three** values to `0`. Otherwise each
non-zero value is clamped to a minimum of `1`.

---

-->

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `http_request.allowDELETE` | `boolean` | **DELETE** | `true` |
| `http_request.allowGET` | `boolean` | **GET** | `true` |
| `http_request.allowHEAD` | `boolean` | **HEAD** | `false` |
| `http_request.allowOPTIONS` | `boolean` | **OPTIONS** | `false` |
| `http_request.allowPATCH` | `boolean` | **PATCH** | `true` |
| `http_request.allowPOST` | `boolean` | **POST** | `true` |
| `http_request.allowPUT` | `boolean` | **PUT** | `true` |
| `http_request.maxConcurrentRequests` | `number` | **Max concurrent requests**<br/>Maximum number of HTTP requests that can be in-flight simultaneously. | `5` |
| `http_request.rateLimitPerMinute` | `number` | **Max requests per minute**<br/>Maximum number of HTTP requests allowed per minute. Provides a broader throttle beyond the per-second limit. | `100` |
| `http_request.rateLimitPerSecond` | `number` | **Max requests per second**<br/>Maximum number of HTTP requests allowed per second. Uses a token-bucket algorithm for smooth enforcement. | `10` |
| `http_request.serverName` | `string` | **Server name**<br/>Namespace prefix for the tool: <serverName>.http_request | `"http"` |
| `http_request.urlWhitelist` | `array` | **URL Whitelist**<br/>Python regex patterns applied with match() to the final canonical URL after path substitution, regular query parameters, and query-based API-key auth. A request-time source recognizer accepts only exact literal/escaped hosts with supported numeric-port forms, or a deliberate [^/] whole-authority form, followed by an explicit authority boundary. Unsupported or ambiguous authority syntax fails closed even when the regex matches. [] or only blank placeholder rows allows all public destinations; non-public destinations remain blocked. Blank rows mixed with valid patterns are ignored; invalid non-empty regexes, non-string values, and malformed entries fail closed. |  |
| `http_request.whitelistPattern` | `string` | **URL Pattern (regex)**<br/>Applied with Python regex match() to the final canonical URL after path substitution, regular query parameters, and query-based API-key auth. After matching, a fail-closed source grammar requires a literal HTTP(S) scheme; an exact literal/escaped DNS, IPv4, or bracketed-IPv6 host with an optional exact or [0-9]-based port policy, or a whole-authority [^/] policy; and an explicit path, query, or end boundary. Unsupported or ambiguous authority regex syntax is denied at request time. Example: ^https://api\.example\.com(?::[0-9]+)?(?:/\|$). Scheme-only prefixes are denied; use an empty whitelist to allow all public destinations. Blank placeholder rows are ignored. | `""` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_http_request)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# LaserData Memory

Route: /nodes/tool_laserdata_memory

# tool_laserdata_memory

Adds durable, shared memory to agents through four tools: `laserdata.remember`,
`laserdata.recall`, `laserdata.improve`, and `laserdata.forget`.

This is a `tool` node (`classType: ["tool"]`, invoke capability, no data lanes). Multiple agents
can connect to the same LaserData Memory node and share its namespace-scoped durable memory.

## About LaserData

LaserData provides data infrastructure and an SDK for working with durable
streams, memory, context, and state on Apache Iggy. This node uses its Laser
SDK memory primitive as a shared, durable store for agents.

## What it does

[LaserData](https://laserdata.com) is real-time data infrastructure on Apache Iggy: durable event
streams with memory/context/state SDKs on top. This node wraps the Laser SDK's `memory` primitive.
Every `remember` appends to a durable memory topic (an auditable event stream), `recall` folds the
topic back into the current items, `improve` records a ranking feedback signal, and `forget`
appends a tombstone. Memory survives pipeline restarts and is shared by every agent pointing at
the same deployment and namespace.

Memory is grouped by **namespace** (e.g. `customer:42`). By default the agent may pass a
namespace per call, falling back to the one configured on the node; turn
`allow_namespace_override` off to lock all calls to the configured namespace. A `conversation` id
can additionally scope items to one session.

## As a tool

- **`laserdata.remember`** stores a statement verbatim and returns its `memory_id` (a
  time-ordered ULID).
- **`laserdata.recall`** returns up to `limit` items, most recent first. The topic-backed memory
  ignores the semantic `query` (a vector backend would rank by it); each row carries `id`,
  `text`, and — when present — `score`, `conversation`, and `kind`.
- **`laserdata.improve`** records feedback on an item: positive `weight` promotes it in future
  recalls, negative demotes it.
- **`laserdata.forget`** deletes one item by id (the durable audit stream keeps its history).

Bad input raises `ValueError`; backend and timeout failures raise `RuntimeError`. There is no
destructive clear/reset tool.

## Profiles

Default: **Your own Apache Iggy server** (`local`).

| Profile | Deployment | Context |
|---|---|---|
| `local` **(default)** | Your own Apache Iggy server | Uses the local connection-string field |
| `cloud` | LaserData Cloud | Uses the cloud connection-string field |

### SDK contract provenance

Pinned to **`laser-sdk==0.1.1`** (PyPI, in `requirements.txt`); the contract below was verified
against `0.0.1rc21` and has not been re-checked on 0.1.1. rc20+ speaks only Apache Iggy's VSR
cluster protocol (the upcoming clustering wire format), so the server must be a
VSR-enabled build: LaserData Cloud deployments **created on/after 2026-07-31** serve it (older
deployments must be recreated — confirmed with the LaserData team), as does
[laserdata/laser-stack](https://github.com/laserdata/laser-stack) locally. The full
remember → recall → improve → forget round-trip was verified live against a LaserData Cloud
free-tier deployment on rc21/VSR (2026-07-31), including TLS auto-attach with the SDK's embedded
root CA. The SDK surface itself was verified by
introspection on 2026-07-29: `Laser.connect(connection_string)`, `laser.memory(namespace)`, and
async `Memory.remember/recall/improve/forget`. The SDK is a native (PyO3) async client whose
futures must be created on a running event loop, so the node keeps one persistent bridge loop in
a daemon thread (`IGlobal`) and submits each synchronously-dispatched tool call to it. The
connection opens lazily on the first tool call and closes on pipe teardown.

## Configuration

The **LaserData deployment** dropdown selects a connection mode (a preconfig profile, same
pattern as the Qdrant node) and switches the visible fields and defaults:

**Your own Apache Iggy server** (`local`, the default):

- `connection_string`: `user:password@host:port`, e.g. `iggy:iggy@localhost:8090` (Iggy's
  default dev credentials). Secure field; falls back to the `LASER_CONNECTION_STRING`
  environment variable. A containerized engine needs an address reachable from the container
  (e.g. `host.docker.internal`). No token exists in this mode.
- The server must be a **VSR-enabled** Iggy build (rc20+ wheels speak only the VSR clustering
  protocol): use [laserdata/laser-stack](https://github.com/laserdata/laser-stack)
  (`./scripts/up`, which also prints a ready `LASER_CONNECTION_STRING`). Stock pre-VSR
  `iggyrs/iggy` images cannot talk to this SDK.
- `folded` defaults to `true` — recall folds the memory topic in-process, which a plain Iggy
  server (no managed backend) requires.

**LaserData Cloud** (`cloud`):

- `connection_string`: `user:password@<deployment-domain>:8090` — the user/password from the
  deployment's **Credentials** tab, the domain and TCP port from its **Overview** tab (secure;
  same env fallback). TLS is automatic for `*.laserdata.cloud` hosts (the SDK ships LaserData's
  root CA — no certificate file, no extra flags). There is no separate API token — all auth
  travels in the connection string. The deployment must serve VSR: created on/after 2026-07-31;
  recreate older ones (all verified against a live Cloud deployment).
- `folded` defaults to `true` — the folded (in-process) recall path is the one verified live
  against Cloud; turn it off only on a deployment serving a managed KV view.

Shared by both modes:

- `namespace`: default memory scope for all connected agents; required here or per call.
- `stream` (advanced): the Iggy stream the memory topics live in, pinned as the connection's
  default stream at connect. Defaults to `rocketride-memory`; nodes sharing one memory must match.
- `allow_namespace_override` (advanced): permit per-call namespaces. Defaults to `true`.
- `folded` (advanced): overridable per the mode notes above.
- `recall_limit` (advanced): default recall result limit, 1–200. Defaults to 10.
- `op_timeout` (advanced): per-operation timeout (including first connect), 5–600 seconds.
  Defaults to 30.

## Notes

### Deferred scope

`context(id)` assembly, `kv` get/set/delete, and `fork(id)` copy-on-write
state are not exposed. The node is deliberately a request-driven memory/state
provider rather than an event-stream source.

## Upstream docs

- LaserData: https://laserdata.com
- LaserData docs: https://docs.laserdata.com
- Laser SDK repo: https://github.com/laserdata/laser-sdk

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `laserdata.allow_namespace_override` | `boolean` | **Allow namespace override**<br/>When on (default), the agent may pass a different namespace per call. Turn off to lock every call to the configured namespace. | `true` |
| `laserdata.cloud.connection_string` | `string` | **Connection string**<br/>LaserData Cloud endpoint in the form <code>user:password@host:port</code> — the user and password from your deployment's <b>Credentials</b> tab, the domain and TCP port from its <b>Overview</b> tab. TLS is automatic for <code>*.laserdata.cloud</code> hosts (the SDK ships the LaserData root CA). The deployment must serve VSR — created on/after 2026-07-31; recreate older ones. Falls back to the LASER_CONNECTION_STRING environment variable when blank. | `""` |
| `laserdata.folded` | `boolean` | **Folded recall**<br/>When on (default), 'recall' folds the durable memory topic in-process — works against plain Apache Iggy and LaserData Cloud alike (verified live). Turn off only to read a managed KV view on a deployment that serves one. | `true` |
| `laserdata.local.connection_string` | `string` | **Connection string**<br/>Apache Iggy connection string in the form <code>user:password@host:port</code>, e.g. <code>iggy:iggy@localhost:8090</code>. The server must be a VSR-enabled Iggy build — use <a href='https://github.com/laserdata/laser-stack' target='_blank'>laser-stack</a> (its <code>./scripts/up</code> prints a ready connection string); stock pre-VSR Iggy images cannot talk to this SDK. A containerized engine needs an address reachable from the container, e.g. <code>host.docker.internal</code>. Falls back to the LASER_CONNECTION_STRING environment variable when blank. | `""` |
| `laserdata.namespace` | `string` | **Namespace**<br/>Memory scope every call reads and writes, e.g. <code>customer:42</code>. Can be passed by the agent per call; a namespace is required on the call or here. | `""` |
| `laserdata.op_timeout` | `integer` | **Operation timeout (s)**<br/>Max seconds any single memory operation (including the first connect) may take before it fails. | `30` |
| `laserdata.profile` | `string` | **LaserData deployment**<br/>Connect to... | `"local"` |
| `laserdata.recall_limit` | `integer` | **Recall limit**<br/>Maximum number of memory items to retrieve per recall. | `10` |
| `laserdata.show_advanced` | `boolean` | **Advanced settings**<br/>Show advanced options. The defaults work for most cases, leave off for a simple setup. | `false` |
| `laserdata.stream` | `string` | **Stream**<br/>The Iggy stream the memory topics live in, pinned as the connection's default stream. All nodes sharing one memory must use the same stream. | `"rocketride-memory"` |

## Dependencies

- `laser-sdk` `==0.1.1`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_laserdata_memory)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# MCP Client

Route: /nodes/tool_mcp_client

# tool_mcp_client

A RocketRide tool node that connects to an external [Model Context Protocol](https://modelcontextprotocol.io/) server and exposes its tools to AI agents.

## About Model Context Protocol

Model Context Protocol is a protocol for connecting AI applications to tools
and data sources. MCP servers publish their available tools and accept calls
using the protocol; this node makes those published tools available in a
RocketRide agent.

## What it does

Connects to an MCP server over one of three transports (STDIO (local subprocess), Streamable HTTP, or legacy HTTP+SSE), performs the MCP `initialize` handshake, discovers the server's tools via `tools/list` when the pipeline starts, and exposes them to agent nodes. Agents then discover and invoke these tools during their reasoning loop; each call is forwarded to the server as `tools/call` and the raw MCP result is returned.

This node has no pipeline lanes: it is a control-plane tool node, connected to agents via the `tools` invoke channel.

## As a tool

The node registers exactly the tools returned by the connected server. Each
tool is named `<serverName>.<toolName>`; `serverName` defaults to `mcp` (or to
the node catalog name when present). The argument schema and returned value are
the discovered server contract. Malformed input, an unknown namespace, a
disconnected client, or a server failure raises an error rather than looking
like an empty result.

Tools are namespaced as `serverName.toolName` (e.g. `mcp.search_docs`), where `serverName` is set in configuration. Tools are discovered at pipeline startup and cached, and the cache is re-read from the server whenever an agent discovers its tools or asks for a tool the cache does not know (at most once per second), so a server that adds or renames tools while the pipeline runs is picked up without a restart. A changed catalog is reported as a pipeline warning naming the added and removed tools. A tool that is still unknown after that refresh is refused with an explicit `ToolUnavailableError` and is never sent to the server, so an agent sees a clear failure rather than a plausible-looking answer.

The implementation is pure Python standard library (`subprocess`, `urllib`, JSON-RPC 2.0), no MCP SDK dependency and no extra packages to install. Each request has a 20-second timeout.

---

## Profiles

The directory registers two services and each keeps its own default: MCP Client
defaults to **RocketRide MCP server (stdio)** (`RocketRide`), and the Butterbase
MCP Client preset to **Butterbase MCP server** (`butterbase`). Both are marked
below; which one applies depends on the service you added to the pipeline.

| Profile | Transport | Notes |
|---|---|---|
| RocketRide MCP server (stdio) **(default)** | `stdio` | Launches `python -m rocketride_mcp` |
| Generic MCP server (Streamable HTTP) | `streamable-http` | Enter endpoint URL |
| Generic MCP server (legacy HTTP+SSE) | `sse` | Enter SSE endpoint URL |
| Butterbase MCP server **(default)** | `streamable-http` | Branded Butterbase preset |

## Configuration

Choose the transport first, then provide only the connection values it uses.
The default profile starts the RocketRide MCP server over STDIO; use an HTTP
profile when the server runs elsewhere.

### Server name

The server name controls the agent-visible `<serverName>.<toolName>` prefix.
Leave the default `mcp` when one MCP server is attached, and choose a distinct
name when an agent has tools from multiple MCP Client nodes so their names do
not collide.

### STDIO transport

Launches a local subprocess as the MCP server and speaks JSON-RPC over its stdin/stdout. The subprocess inherits the engine's environment (with `PYTHONUNBUFFERED=1` set).

Older configs that used separate `command` + `args` fields are still accepted for backwards compatibility.

### Streamable HTTP transport

Connects to a modern Streamable HTTP MCP endpoint (spec 2025-03-26 transport). Handles both plain-JSON and SSE-streamed responses, tracks the `Mcp-Session-Id` returned by the server, and sends a best-effort `DELETE` to terminate the session when the pipeline stops.

### Legacy HTTP+SSE transport

Connects to an older two-channel MCP server: a long-lived SSE `GET` stream for responses (read on a background thread) plus an `endpoint` event that supplies the session-specific POST URL for requests.

Configuration is validated at save time: `commandLine` is required for `stdio`, `endpoint` for `streamable-http`, and `sse_endpoint` for `sse`.

---

## Authentication

For the HTTP transports (`streamable-http` and `sse`), set `bearer` to send an `Authorization: Bearer <token>` header on every request. The token is stored encrypted and masked in the UI. Arbitrary additional headers (e.g. API-key headers) can be supplied via `headers`; a `bearer` value overrides any `Authorization` key in `headers`.

The STDIO transport has no authentication fields: the subprocess runs locally with the engine's environment.

---

## Notes

### Butterbase preset

`services.butterbase.json` in this directory defines **Butterbase MCP Client**, a branded preset that reuses this node's implementation (not a separate node). It pins the transport to `streamable-http` with endpoint `https://api.butterbase.ai/mcp`, namespaces tools as `butterbase.<tool>` (e.g. `butterbase.init_app`), and surfaces the bearer field as a Butterbase API key (`bb_sk_...`, created in the Butterbase dashboard). Prerequisite: enable Developer Mode on your Butterbase app so the agent can create and modify resources.

---

### Runtime behavior

- Protocol versions advertised during `initialize`: `2024-11-05` for STDIO, `2025-11-25` for Streamable HTTP and SSE.
- Tool calls must use the fully namespaced `server.tool` form; a call addressed to a different `serverName` than this node's is rejected.
- The MCP server process/connection is started in `beginGlobal` and shut down in `endGlobal`; a failed handshake or tool discovery fails pipeline startup with a warning.

---

### Zero-argument tools

Some MCP tools take no arguments (their input schema is empty). Strict reasoning-model agents can silently drop such a tool from their catalog when it is advertised with an empty JSON Schema. To keep these tools usable everywhere, the client normalizes an empty input schema to carry a single optional placeholder argument (`rr_no_args`) before presenting the tool to an agent. RocketRide records which cached tools received that synthesized placeholder and strips it only for those tools before the call, so the MCP server never receives it. A tool that genuinely declares an argument named `rr_no_args` continues to receive that argument unchanged.

---

## Upstream docs

- [Model Context Protocol specification](https://modelcontextprotocol.io/)
- [Butterbase documentation](https://docs.butterbase.ai)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Butterbase MCP Client (`services.butterbase.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `mcp_client.bearer` | `string` | **API Key**<br/>Butterbase API key (bb_sk_...). Create one in the <b>Butterbase dashboard</b>: <a href='https://dashboard.butterbase.ai' target='_blank'>dashboard.butterbase.ai</a> → API Keys. Sent as an Authorization Bearer token. | `""` |
| `mcp_client.endpoint` | `string` | **Endpoint**<br/>Butterbase MCP Streamable HTTP endpoint. Defaults to the production server. | `"https://api.butterbase.ai/mcp"` |
| `mcp_client.serverName` | `string` | **Server name**<br/>Namespace prefix for the discovered tools: <serverName>.<toolName> (example: butterbase.init_app). | `"butterbase"` |

### MCP Client (`services.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `mcp_client.bearer` | `string` | **Bearer token**<br/>Optional Authorization bearer token | `""` |
| `mcp_client.commandLine` | `string` | **Command line**<br/>Command line to launch MCP server (stdio transport). Example: python -m rocketride_mcp | `"python -m rocketride_mcp"` |
| `mcp_client.endpoint` | `string` | **Endpoint**<br/>MCP Streamable HTTP endpoint URL. Example: http(s)://host:port/mcp | `""` |
| `mcp_client.headers` | `object` | **Headers**<br/>Extra HTTP headers for streamable-http/sse transports | `{}` |
| `mcp_client.serverName` | `string` | **Server name**<br/>Namespace prefix for tools: <serverName>.<toolName> (example: local.echo) | `"mcp"` |
| `mcp_client.sse_endpoint` | `string` | **SSE endpoint (legacy)**<br/>Legacy MCP SSE URL (old transport). Example: http://127.0.0.1:8000/sse | `""` |
| `mcp_client.transport` | `string` | **Transport**<br/>How to connect to the MCP server | `"streamable-http"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_mcp_client)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Mem0

Route: /nodes/tool_mem0

# tool_mem0

Long-term, shared agent memory exposed as **tools** (`mem0.remember` / `mem0.recall`),
backed by the hosted [Mem0 Platform](https://docs.mem0.ai) REST API.

This is a `tool` node (`classType: ["tool"]`, no data lanes), not the agent's run-scoped
`memory` subsystem, it complements it. Wire it to an agent via `control` (class `tool`).

## About Mem0

Mem0 is a memory platform for AI applications. It stores conversation-derived
facts and supports semantic retrieval, which makes it suitable when several
agents or pipeline runs need a shared memory outside a single run.

## What it does

This node gives an agent persistent, externally hosted memory through two
tools and has no data lanes. Pick it over an in-run memory component when a
fact must be available to later agents or pipeline executions that use the
same configured scope.

## As a tool

- **`mem0.remember`** → `POST /v1/memories/`: ingest conversation turns; Mem0 extracts and
  stores salient facts server-side.
- **`mem0.recall`** → `POST /v1/memories/search/`: semantic search over the pool; returns
  ranked memories.

## Configuration

`api_key` is required (or set `MEM0_API_KEY`); a scope is required to store and recall. The full
field set is in the [Schema](#schema) section below and in `services.json`.

**Scope with `user_id`.** On the hosted platform a memory added with an `agent_id` / `app_id` is
stored under the `user_id` but doesn't reliably carry that id, while `recall` AND-narrows by every
id set, so configuring `agent_id` can make recalls come back empty even though the write
succeeded (verified against the live API). Use `user_id` (and `run_id` for sessions); leave
`agent_id` / `app_id` empty unless verified for your account.

### Ingestion and recall behavior

Leave **Infer memories** on to let Mem0 derive salient facts from supplied
turns; turn it off only when raw messages are the desired stored form. Keep
**Synchronous store** on when a following recall must see the just-added fact;
turning it off returns before background extraction completes. Increase the
store timeout only when extraction regularly outlives its 30-second default,
and adjust the recall limit when the agent needs a broader or narrower result
set.

## Notes

### Direct REST integration

This node calls the Mem0 REST API directly with `requests` rather than the `mem0ai` SDK: the
SDK hard-pins `openai<1.110`, which is unsatisfiable alongside the engine's OpenAI nodes
(`openai>=2.38`). The REST surface is identical: the entity ids
(`user_id` / `agent_id` / `run_id` / `app_id`) go top-level in the JSON body for both `add` and
`search`, built from one internal scope helper. Deps (`requests`, `tenacity`) are already in the
engine: no new third-party packages, no version conflict.

Mem0's `add` is asynchronous (queues extraction, returns an `event_id`). By default `remember`
polls `GET /v1/event/{event_id}/` until the job is terminal (or `ingest_timeout` elapses) so a
following `recall` sees the memory, like xTrace's synchronous ingest. Turn `wait` off for
fire-and-forget. `search` returns ranked rows (handled whether the API returns a bare list or a
`{"results": […]}` object).

### Credentials

Get an API key (`m0-…`) from [app.mem0.ai](https://app.mem0.ai) → API Keys. Never commit keys:
use node config (encrypted) or the env var.

## Upstream docs

- [Mem0 documentation](https://docs.mem0.ai)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `mem0.agent_id` | `string` | **Agent id**<br/>Optional agent scope. Caution: on the hosted Mem0 platform an agent_id is not reliably stored on the memory but still narrows recall, so setting it can make recalls come back empty. Prefer scoping by user id; leave this empty unless you have verified it works. | `""` |
| `mem0.api_key` | `string` | **API Key**<br/>Mem0 Platform API key (m0-...). Get it from the <b>Mem0 dashboard</b>: <a href='https://app.mem0.ai' target='_blank'>app.mem0.ai</a> → API Keys. | `""` |
| `mem0.app_id` | `string` | **App id**<br/>Optional app scope. Same caveat as Agent id: it narrows recall but is not reliably stored on the hosted platform, so setting it can hide memories. Prefer scoping by user id. | `""` |
| `mem0.base_url` | `string` | **Base URL**<br/>Mem0 REST API base URL. Defaults to the hosted endpoint; override for self-hosted / enterprise deployments. | `"https://api.mem0.ai"` |
| `mem0.infer` | `boolean` | **Infer memories**<br/>When on (default), Mem0 runs LLM extraction to derive salient facts from the turns. When off, the raw messages are stored verbatim. | `true` |
| `mem0.ingest_timeout` | `integer` | **Store timeout (s)**<br/>Max seconds 'remember' waits/polls for background extraction to finish before returning a 'queued' result. | `30` |
| `mem0.run_id` | `string` | **Run id**<br/>Optional session/run scope stamped on stored memories and used to narrow recall. Can be passed by the agent per call. | `""` |
| `mem0.search_limit` | `integer` | **Recall limit**<br/>Maximum number of memory rows to retrieve per recall. | `10` |
| `mem0.show_advanced` | `boolean` | **Advanced settings**<br/>Show advanced options. The defaults work for most cases, leave off for a simple setup. | `false` |
| `mem0.user_id` | `string` | **User id**<br/>Who this memory belongs to (used to store and recall). Can be passed by the agent per call. At least one scope (user id, or an advanced agent/run/app id) is required. | `""` |
| `mem0.wait` | `boolean` | **Synchronous store**<br/>When on (default), 'remember' polls Mem0 until background extraction finishes, so a following 'recall' can see the new memory. When off, 'remember' returns immediately and extraction runs in the background. | `true` |

## Dependencies

- `requests`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_mem0)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Excel

Route: /nodes/tool_microsoft_365

# tool_microsoft_365

A RocketRide tool family that exposes Excel, OneDrive, Outlook Calendar, Outlook Mail, and Word to an agent. Use the service whose resource the agent needs, rather than a general HTTP tool.

## About Microsoft 365

Microsoft 365 is Microsoft's cloud productivity suite, bundling Word, Excel, Outlook, and OneDrive with Exchange and SharePoint under one subscription. Organizations use it for document authoring, spreadsheets, email, calendaring, and file storage, accessed from desktop, web, and mobile clients. The Microsoft Graph API exposes these services under one authentication and permissions model.

## What it does

This parent groups five no-lane tool services: Excel, OneDrive, Outlook Calendar, Outlook Mail, and Word. Each service authenticates through the shared Microsoft Graph credential and request machinery in `graph_client.py`, builds only its own Graph client, and registers `<service>_*` functions as agent tools. Operational targets (file path/id, message id, event id) are always tool-call parameters, never node config, and outputs are cleaned shapes rather than raw Graph JSON. Select a service according to the Microsoft 365 resource the agent needs.

## As a tool

Each service registers exactly the functions below, every name prefixed with the service name; `<service>_check_connection` checks that service's configured access and connection. Individual operation arguments and return shapes are exposed in each function's registered schema.

### Excel

| Function | Description |
|---|---|
| `excel_list_worksheets` | List a workbook's worksheets (tabs). |
| `excel_read_range` | Read values/formulas in one A1 range. |
| `excel_read_used_range` | Read a worksheet's populated area. |
| `excel_update_range` | Overwrite values in an A1 range. |
| `excel_clear_range` | Clear an A1 range's contents. |
| `excel_add_worksheet` | Add a new worksheet (tab). |
| `excel_list_tables` | List a workbook's tables. |
| `excel_read_table` | Read every row of a table. |
| `excel_add_table` | Create a table over an A1 range. |
| `excel_add_table_rows` | Append rows to a table. |
| `excel_add_chart` | Add a chart plotting a source range. |
| `excel_calculate` | Full recalculation of the workbook. |
| `excel_create_workbook` | Create a new blank `.xlsx` workbook. |
| `excel_check_connection` | Diagnostics — connection and scope coverage. |

### OneDrive

| Function | Description |
|---|---|
| `onedrive_list_items` | List a folder's items (root by default). |
| `onedrive_search` | Search files and folders by name/content. |
| `onedrive_get_metadata` | Read one item's metadata. |
| `onedrive_download` | Download content (inline base64 ≤ 1 MiB, else a `downloadUrl`). |
| `onedrive_upload` | Upload/overwrite a file (chunked above 4 MB). |
| `onedrive_create_folder` | Create a folder inside a parent folder. |
| `onedrive_copy` | Copy a file or folder (async). |
| `onedrive_move` | Move an item to another folder. |
| `onedrive_rename` | Rename an item in place. |
| `onedrive_trash` | Move an item to the recycle bin. |
| `onedrive_restore` | Restore a trashed item. OneDrive Personal only (Graph limitation): refused under `service` auth; work/school accounts get Graph's error. |
| `onedrive_permanently_delete` | Permanently delete an item (gated). |
| `onedrive_create_sharing_link` | Create a view/edit sharing link (anonymous scope gated). |
| `onedrive_list_permissions` | List sharing permissions on an item. |
| `onedrive_invite` | Invite people by email (non-individual recipients gated via directory lookup). |
| `onedrive_delete_permission` | Revoke a sharing permission. |
| `onedrive_check_connection` | Diagnostics — connection and scope coverage. |

### Outlook Calendar

| Function | Description |
|---|---|
| `outlook_calendar_list_events` | List events in a window (recurring series expanded). |
| `outlook_calendar_get_event` | Get a single event by id. |
| `outlook_calendar_create_event` | Create an event, optionally inviting attendees (write tier). |
| `outlook_calendar_update_event` | Update an event — only provided fields change (write tier). |
| `outlook_calendar_delete_event` | Delete an event (write tier). |
| `outlook_calendar_respond` | Respond to a meeting invitation (write tier). |
| `outlook_calendar_find_meeting_times` | Suggest meeting times for a set of attendees. |
| `outlook_calendar_get_schedule` | Get free/busy schedule information for mailboxes. |
| `outlook_calendar_list_calendars` | List the mailbox's calendars. |
| `outlook_calendar_create_calendar` | Create a new calendar (write tier). |
| `outlook_calendar_delta_sync` | Incrementally sync a calendar view via a caller-provided delta link. |
| `outlook_calendar_check_connection` | Diagnostics — connection and scope coverage. |

### Outlook Mail

| Function | Description |
|---|---|
| `outlook_mail_list_messages` | List a folder's messages (inbox by default), search or OData filter. |
| `outlook_mail_get_message` | Get one message with its full body (HTML converted to readable text). |
| `outlook_mail_send_message` | Send an email immediately (send/modify tier). |
| `outlook_mail_create_draft` | Create a draft message (modify tier). |
| `outlook_mail_reply` | Reply to the sender only (send/modify tier). |
| `outlook_mail_reply_all` | Reply to all recipients (send/modify tier). |
| `outlook_mail_forward` | Forward to new recipients (send/modify tier). |
| `outlook_mail_move_message` | Move a message to another folder (modify tier). |
| `outlook_mail_set_read` | Mark a message read/unread (modify tier). |
| `outlook_mail_set_categories` | Replace a message's category labels (modify tier). |
| `outlook_mail_delete_message` | Soft delete — move to Deleted Items (modify tier). |
| `outlook_mail_permanently_delete` | Permanently delete (modify tier + `allowHardDelete` gate). |
| `outlook_mail_list_folders` | List the mailbox's mail folders. |
| `outlook_mail_create_folder` | Create a mail folder (modify tier). |
| `outlook_mail_list_attachments` | List attachment metadata on a message. |
| `outlook_mail_get_attachment` | Download an attachment's content (base64). |
| `outlook_mail_add_attachment` | Attach a file to a draft message (modify tier). |
| `outlook_mail_check_connection` | Diagnostics — connection and scope coverage. |

### Word

| Function | Description |
|---|---|
| `word_read_text` | Read a document's paragraph and table-cell text, newline-joined. |
| `word_create_document` | Create a new `.docx` from a list of paragraph texts. |
| `word_append_text` | Append paragraphs to the end of a document. |
| `word_replace_text` | Find/replace text across paragraphs and table cells; returns the replacement count. |
| `word_export_pdf` | Convert to PDF and upload it beside the source. |
| `word_check_connection` | Diagnostics — connection and scope coverage. |

Write, delete, and sharing calls can be refused by the configured access tier or explicit safety flags. Connection and Graph API failures surface through the tool call; call the relevant `check_connection` function when a scope or permission error needs diagnosis.

## Configuration

Choose the authentication mode and the narrowest access tier for each service. The five services are independently configured, so setting a high tier for one does not broaden another service.

### Microsoft authentication

Every service exposes `microsoft.authType`, defaulting to `service`: an Entra app using the client-credentials flow (`microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret`), acting as `microsoft.userPrincipalName` (app-only calls target `/users/{upn}`). The `user` mode is OAuth via the RocketRide broker: the `microsoft.oAuthButton` sign-in populates `microsoft.userToken`, which the broker refreshes automatically. Application (`service`) permissions always require admin consent.

### Excel

Excel defaults to the `write` access tier; `readonly` refuses the mutating tools node-side. Both tiers request the same delegated `Files.ReadWrite` scope — Graph's workbook API accepts no narrower scope and documents application-only tokens as not supported, so user OAuth is the documented auth path even though `service` auth is configurable. There are no destructive gate flags.

### OneDrive

OneDrive defaults to `write`; `readonly` supports listing, search, metadata, and download without modification. Public or non-individual-recipient sharing is refused until `onedrive.allowPublicSharing` is on — with it off, `onedrive_invite` resolves every recipient against the directory and fails closed on any recipient (or lookup error) that isn't an individual user. Permanent delete bypasses the recycle bin and stays refused until `onedrive.allowHardDelete` is on; prefer `onedrive_trash` for recoverable removal.

### Outlook Calendar

Outlook Calendar defaults to `write`; `readonly` allows only event/calendar reads, meeting-time suggestions, free/busy schedules, and delta-sync. There are no destructive gate flags — unlike Outlook Mail's hard-delete flag, event deletion needs only the `write` tier.

### Outlook Mail

Outlook Mail defaults to `modify`, the tier needed for drafts, moves, organizing, and attachments; `send` adds only sending and replying (`Mail.Send`) without `Mail.ReadWrite`, and `readonly` allows reads only. Permanent deletion stays refused until `outlook_mail.allowHardDelete` is on; with it off, `outlook_mail_delete_message` still moves messages to Deleted Items.

### Word

Word defaults to `write`; `readonly` allows only `word_read_text`. There are no destructive gate flags — every write is a read-modify-write round trip guarded by Graph's own `If-Match` precondition rather than a node-side gate.

## Authentication

Every service authenticates through the shared Microsoft Graph credential and request machinery in `graph_client.py` — the one copy every service's `client.py` binds via `functools.partial`. Credential construction validates its token endpoint against Microsoft's own Entra ID (Azure AD) host (`login.microsoftonline.com`) only, and validates the broker refresh URL against `https` plus a trusted broker host (`oauth2.rocketride.ai` / `oauth.rocketride.ai`, or `RR_OAUTH_BROKER_URL` for a self-hosted broker) — so a tampered stored token can never redirect credentials elsewhere. The broker-backed refresh fails loud on HTTP rejection, connection errors, malformed bodies, and 200 responses without an access token, and clears a stale expiry so a fresh token is never re-refreshed per call. Scope diagnostics (`token_scope_report`) back each service's `validateConfig`, its `check_connection` tool, and `build_auth`, so the three checks cannot drift. Requests retry `429`/`5xx` with exponential backoff; permission `401`/`403` and other errors fail fast with an agent-readable message.

Register the app in the Entra admin center (`entra.microsoft.com` → App registrations) and grant the Graph permission each service's Configuration section names, with admin consent required for application (`service`) permissions.

## Notes

### Excel

- Every call is sessionless — no persisted workbook session (`workbook-session-id`) is opened or closed. Graph fully supports this; the tradeoff is one extra recalculation round trip per call versus a session, deferred until usage shows the need for sessions.
- `excel_create_workbook` writes a minimal blank workbook (one empty "Sheet1"); it does not clone an existing file or template.
- Range/table operations use A1 notation and Graph's workbook function addressing; very large reads should be paged by range.
- Troubleshooting: scope/403 errors — call `excel_check_connection`; if scopes are missing, reconnect the Microsoft account (user auth) or grant/consent the Entra app permission (service auth). `access` is read-only — write tools raise `MicrosoftAccessError`; raise `excel.access` to `write`. Empty `values` — the range may be outside the used range, or the file path/sheet name may not match exactly; call `excel_list_worksheets` to confirm names.

### OneDrive

- `onedrive_copy` runs asynchronously on Graph's side; the tool returns once the copy is accepted, not once it completes.
- `onedrive_upload` chunks large files at 5 MiB per PUT to the resumable upload session, per Graph's recommended chunk size.
- `onedrive_restore` is OneDrive Personal only — Microsoft Graph does not support restore for work or school accounts. The tool refuses up front under Entra app (service) auth; a work/school user OAuth account surfaces Graph's own error. Use the OneDrive web recycle bin instead.
- Troubleshooting: scope/403 errors — call `onedrive_check_connection`. Sharing/invite refused — anonymous links, and invites to any recipient that doesn't resolve to an individual directory user (including a lookup permission error), need `onedrive.allowPublicSharing` enabled; permanent delete needs `onedrive.allowHardDelete` enabled. Item not found — confirm whether the caller meant a path or an item id; a value without `/` is always treated as an item id, never a bare root-level filename.

### Outlook Calendar

- `outlook_calendar_create_event` / `outlook_calendar_update_event` accept `start`/`end` as either a plain `'YYYY-MM-DDTHH:MM:SS'` string (wrapped as UTC) or an already-shaped `{dateTime, timeZone}` object.
- `attendees` invites are sent by Graph itself as part of creating/updating the event — the `write` tier gates the Graph call, not a separate "send" step.
- `outlook_calendar_find_meeting_times` needs a delegated (signed-in user) context on Microsoft's side and may not be supported under app-only (client-credentials) authentication.
- `outlook_calendar_delta_sync` takes `start`/`end` on the first call; pass the returned `delta_link` back in on subsequent calls to fetch only what changed.
- Troubleshooting: scope/403 errors — call `outlook_calendar_check_connection`. `access` is `readonly` — every write tool raises `MicrosoftAccessError`; raise `outlook_calendar.access` to `write`. `outlook_calendar_find_meeting_times` fails under app-only auth — this endpoint needs a delegated (signed-in user) context; switch to user OAuth or use `outlook_calendar_get_schedule` instead.

### Outlook Mail

- `outlook_mail_list_messages`'s `query` is treated as a full-text `$search` term unless it looks like an OData filter expression (contains `eq`, `ne`, `gt`, `lt`, `ge`, `le`, `startswith(`, or `contains(`), in which case it is passed through as `$filter`.
- `outlook_mail_add_attachment` only works against a draft message — create one with `outlook_mail_create_draft` first.
- Troubleshooting: scope/403 errors — call `outlook_mail_check_connection`. `access` is `readonly` — every write/send tool raises `MicrosoftAccessError`; raise `outlook_mail.access` to `send` or `modify`. `access` is `send` but drafts/moves/attachments are refused — the `send` tier lacks `Mail.ReadWrite`; raise `outlook_mail.access` to `modify`. Permanent delete refused — needs `outlook_mail.allowHardDelete` enabled; `outlook_mail_delete_message` (soft delete to Deleted Items) is always available at the `modify` tier.

### Word

- Concurrency: round-trip edits (`word_append_text`, `word_replace_text`) use `If-Match`; a stale eTag (someone else edited the file since it was downloaded) surfaces as a `GraphError` naming the conflict. The tool does not retry automatically — re-read with `word_read_text` and retry the edit. `word_create_document` sends no `If-Match` — nothing to conflict with yet.
- `word_replace_text` scans each paragraph's original, never-mutated text exactly once, so a `replace` value containing `find` cannot double-count. Paragraphs with zero matches are left completely untouched; paragraphs with at least one match get their new text written into the first run with every other run blanked, so the first run's formatting wins for the whole merged text.
- `word_export_pdf` relies on Graph's server-side format conversion (`?format=pdf`); very large or exotic documents may take longer to convert or fail conversion upstream.
- Troubleshooting: scope/403 errors — call `word_check_connection`. `access` is read-only — raise `word.access` to `write`. Conflict / 409 / 412 errors — the file changed since it was downloaded; call `word_read_text` to get the current content and retry the edit. `word_replace_text` returns 0 — confirm the exact text; `find` is a literal (case-sensitive) substring match, not a regex.

### Rate limits

All five services are subject to per Entra app / tenant rate limits; the node retries `429`/`5xx` responses with exponential backoff.

## Upstream docs

- Microsoft Graph Excel API: https://learn.microsoft.com/en-us/graph/api/resources/excel
- Workbook range: https://learn.microsoft.com/en-us/graph/api/range-get
- Workbook tables: https://learn.microsoft.com/en-us/graph/api/resources/table
- Microsoft Graph OneDrive API: https://learn.microsoft.com/en-us/graph/api/resources/onedrive
- DriveItem: https://learn.microsoft.com/en-us/graph/api/resources/driveitem
- Upload large files: https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession
- Sharing: https://learn.microsoft.com/en-us/graph/api/driveitem-createlink
- Microsoft Graph calendar API: https://learn.microsoft.com/en-us/graph/api/resources/calendar
- Event: https://learn.microsoft.com/en-us/graph/api/resources/event
- Find meeting times: https://learn.microsoft.com/en-us/graph/api/user-findmeetingtimes
- Get schedule: https://learn.microsoft.com/en-us/graph/api/calendar-getschedule
- Delta query: https://learn.microsoft.com/en-us/graph/delta-query-events
- Microsoft Graph mail API: https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview
- Message: https://learn.microsoft.com/en-us/graph/api/resources/message
- Send mail: https://learn.microsoft.com/en-us/graph/api/user-sendmail
- Search messages: https://learn.microsoft.com/en-us/graph/search-query-parameter
- Microsoft Graph drive content API: https://learn.microsoft.com/en-us/graph/api/driveitem-get-content
- DriveItem format conversion: https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format
- python-docx: https://python-docx.readthedocs.io/

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Excel (`services.excel.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `excel.access` | `string` | **Access level**<br/>Graph scopes to request. readonly: read worksheets, ranges, and tables only. write: full read/write (update ranges, add worksheets/tables/charts, create workbooks). | `"write"` |

### OneDrive (`services.onedrive.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `onedrive.access` | `string` | **Access level**<br/>Graph scopes to request. readonly: list, search, read metadata, and download only. write: full read/write (upload, create folders, copy/move/rename, trash/restore, and sharing). | `"write"` |
| `onedrive.allowHardDelete` | `boolean` | **Allow permanent delete**<br/>Off by default. When off, only trash/restore are available; permanent delete is refused. | `false` |
| `onedrive.allowPublicSharing` | `boolean` | **Allow public / org-wide sharing**<br/>Off by default. When off, create_sharing_link refuses 'anonymous' links and invite only accepts recipients that resolve to individual directory users (distribution lists and unresolvable addresses are refused). Turn on to allow public links and unrestricted invites. | `false` |

### Outlook Calendar (`services.outlook_calendar.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `outlook_calendar.access` | `string` | **Access level**<br/>Graph scopes to request. readonly: list and read events/calendars, find meeting times, get schedules, and delta-sync only. write: full read/write (default) — create/update/delete events, respond to invitations, and create calendars. | `"write"` |

### Outlook Mail (`services.outlook_mail.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `outlook_mail.access` | `string` | **Access level**<br/>Graph scopes to request. readonly: list, search, and read messages/folders/attachments only. send: readonly plus sending mail, replies, and forwards. modify: full read/write (default) — drafts, moves, organizing, attachments, and permanent delete (when allowHardDelete is on), plus send. | `"modify"` |
| `outlook_mail.allowHardDelete` | `boolean` | **Allow permanent delete**<br/>Off by default. When off, delete moves messages to Deleted Items; permanent delete is refused. Turn on to allow permanent delete. | `false` |

### Word (`services.word.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `word.access` | `string` | **Access level**<br/>Graph scopes to request. readonly: read document text only. write: full read/write (create, append, replace text, export PDF). | `"write"` |

## Dependencies

- `python-docx`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_microsoft_365)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Excel

Route: /nodes/tool_microsoft_365/excel

# Excel tool node (`tool_excel`)

Exposes the Microsoft Graph workbook API as agent tools: list worksheets and
tables; read, write, and clear ranges; add worksheets, tables, table rows,
and charts; recalculate; and create new workbooks. Operates on `.xlsx` files
in the acting user's OneDrive.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is
a `@tool_function` an agent calls on demand. Operational targets (file
path/id, sheet, range, table) are always tool-call parameters, never node
config. Outputs are cleaned shapes (`address`, `values`, `rowCount`, sheet/
table properties), not raw Graph JSON.

Every call is sessionless — no persisted workbook session (`workbook-session-id`)
is opened or closed. Graph fully supports this; the tradeoff is one extra
recalculation round trip per call versus a session, deferred until usage shows
the need for sessions.

## Configuration

| Field | Notes |
|-------|-------|
| `microsoft.authType` | `service` (Entra app, client credentials) or `user` (OAuth). |
| `microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret` | Entra app credentials for `service` auth. |
| `microsoft.userPrincipalName` | Acting user's UPN for `service` auth (app-only calls target `/users/{upn}`). |
| `microsoft.oAuthButton` / `microsoft.userToken` | User OAuth: sign in to populate the access token. |
| `excel.access` | `readonly` or `write` (default). Resolved by the shared `EXCEL` spec in `core/microsoft_access.py`; scopes are never hand-entered. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `Files.ReadWrite` | read worksheets, ranges, and tables only (writes refused node-side) |
| `write` | `Files.ReadWrite` | full read/write (default) |

Both tiers request `Files.ReadWrite`: Graph's workbook API documents delegated
`Files.ReadWrite` as the least-privileged scope for every endpoint, reads
included (`Files.Read` is not accepted), and lists application permissions as
not supported.

There are no destructive gate flags.

## Tools

- **Read:** `excel_list_worksheets`, `excel_read_range` (one A1 range),
  `excel_read_used_range` (the populated area), `excel_list_tables`,
  `excel_read_table`.
- **Write ranges:** `excel_update_range` (overwrites), `excel_clear_range`
  (contents only, formatting preserved).
- **Structure (write):** `excel_add_worksheet`, `excel_add_table`,
  `excel_add_table_rows`, `excel_add_chart`.
- **Workbook (write):** `excel_calculate` (full recalculation),
  `excel_create_workbook` (new blank `.xlsx` at a OneDrive path).
- **Diagnostics:** `excel_check_connection` verifies that granted OAuth
  scopes cover the configured access tier.

## Setup

Authenticate with either an **Entra app** (`microsoft.tenantId` /
`microsoft.clientId` / `microsoft.clientSecret` / `microsoft.userPrincipalName`,
client-credentials flow) or **user OAuth** (click sign-in to populate
`microsoft.userToken`). See `microsoft-oauth.md` for the Entra app / consent
setup shared by every Microsoft 365 tool service. The app must be granted the
delegated Graph `Files.ReadWrite` permission with admin consent — Graph's
workbook API accepts only delegated `Files.ReadWrite` (not `Files.Read`) and
documents application-only tokens as not supported, so user OAuth is the
documented path.

## Limits

- Range/table operations use A1 notation and Graph's workbook function
  addressing (`range(address='...')`); very large reads should be paged by
  range.
- `excel_create_workbook` writes a minimal blank workbook (one empty
  "Sheet1"); it does not clone an existing file or template.
- Rate limits are per Entra app / tenant; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

An agent reads a worksheet's used range, then appends rows to a table:

```
excel_read_used_range  { "file": "Reports/q3.xlsx", "sheet": "Sheet1" }
excel_add_table_rows   { "file": "Reports/q3.xlsx", "table": "Table1",
                          "rows": [["2026-07-10", "Widget", 42]] }
```

## Upstream docs

- Microsoft Graph Excel API: https://learn.microsoft.com/en-us/graph/api/resources/excel
- Workbook range: https://learn.microsoft.com/en-us/graph/api/range-get
- Workbook tables: https://learn.microsoft.com/en-us/graph/api/resources/table

## Troubleshooting

- **Scope / 403 errors:** call `excel_check_connection`; if scopes are
  missing, disconnect and reconnect the Microsoft account (user auth) or
  grant/consent the Entra app permission (service auth) at the required tier.
- **`access` is read-only:** write tools raise `MicrosoftAccessError`; raise
  `excel.access` to `write`.
- **Empty `values`:** the range may be outside the used range, or the file
  path/sheet name may not match exactly — call `excel_list_worksheets` to
  confirm names.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Onedrive

Route: /nodes/tool_microsoft_365/onedrive

# OneDrive tool node (`tool_onedrive`)

Exposes the Microsoft Graph drive API as agent tools: list and search files
and folders, read metadata, download and upload content, create folders,
copy/move/rename items, trash/restore, and manage sharing (links and
permission grants). Operates on the acting user's OneDrive.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is
a `@tool_function` an agent calls on demand. Operational targets (item path
or id, folder, permission id) are always tool-call parameters, never node
config. Outputs are cleaned shapes (`id`, `name`, `size`, `webUrl`,
`folder`/`file`, `lastModifiedDateTime`, `parentReference.path`), not raw
Graph JSON.

Items are addressed by either a drive-relative path (`'Reports/q3.pdf'`) or a
drive item id — whichever the caller has on hand. The rule (shared
`looks_like_item_id()` in `client.py`): the literal `root`, or a value that is
**15+ characters drawn only from `[A-Za-z0-9!]`** (Graph item ids look like
`01BYE5RZ6QN3ZWBTUFOFD3GSPGOHDJD36K`), is treated as an item id; anything else
— including a bare root-level filename such as `report.pdf` — is treated as a
path under the drive root.

## Configuration

| Field | Notes |
|-------|-------|
| `microsoft.authType` | `service` (Entra app, client credentials) or `user` (OAuth). |
| `microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret` | Entra app credentials for `service` auth. |
| `microsoft.userPrincipalName` | Acting user's UPN for `service` auth (app-only calls target `/users/{upn}`). |
| `microsoft.oAuthButton` / `microsoft.userToken` | User OAuth: sign in to populate the access token. |
| `onedrive.access` | `readonly` or `write` (default). Resolved by the shared `ONEDRIVE` spec in `core/microsoft_access.py`; scopes are never hand-entered. |
| `onedrive.allowPublicSharing` | Off by default. Gates anonymous sharing links and invites to non-individual recipients. |
| `onedrive.allowHardDelete` | Off by default. Gates `onedrive_permanently_delete`; trash/restore are always available. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `Files.Read` | list, search, read metadata, and download only |
| `write` | `Files.ReadWrite` (+ requests `User.ReadBasic.All` at sign-in) | full read/write (default); the optional directory scope backs the invite gate and is unavailable to personal accounts |

### Gate flags

- **`allowPublicSharing`**: off by default. When off, `onedrive_create_sharing_link`
  refuses `scope="anonymous"` links, and `onedrive_invite` looks up every
  recipient in the directory (`GET /users/{email}`) and refuses the whole
  invite if any recipient fails to resolve to an individual directory user —
  distribution lists and unresolvable addresses included. Fails closed: a
  lookup permission error is treated the same as a non-user address.
- **`allowHardDelete`**: off by default. When off, `onedrive_permanently_delete`
  is refused; `onedrive_trash` is always available as the recoverable
  alternative (see the `onedrive_restore` limit below).

## Tools

- **Read:** `onedrive_list_items` (a folder's children), `onedrive_search`,
  `onedrive_get_metadata`, `onedrive_download` (inline base64 ≤ 1 MiB, else a
  `downloadUrl`).
- **Write:** `onedrive_upload` (simple PUT ≤ 4 MB, else a chunked resumable
  session), `onedrive_create_folder`, `onedrive_copy`, `onedrive_move`,
  `onedrive_rename`.
- **Trash / restore / delete (write):** `onedrive_trash`, `onedrive_restore`,
  `onedrive_permanently_delete` (gated by `allowHardDelete`).
- **Sharing (write):** `onedrive_create_sharing_link` (gated by
  `allowPublicSharing` for anonymous links), `onedrive_list_permissions`
  (read-only), `onedrive_invite` (gated by `allowPublicSharing`; recipients
  must resolve to individual directory users otherwise), `onedrive_delete_permission`.
- **Diagnostics:** `onedrive_check_connection` verifies that granted OAuth
  scopes cover the configured access tier.

## Setup

Authenticate with either an **Entra app** (`microsoft.tenantId` /
`microsoft.clientId` / `microsoft.clientSecret` / `microsoft.userPrincipalName`,
client-credentials flow) or **user OAuth** (click sign-in to populate
`microsoft.userToken`). See `microsoft-oauth.md` for the Entra app / consent
setup shared by every Microsoft 365 tool service. The Graph permissions differ
by auth mode:

| Auth mode | Tier | Graph permission | Invite directory lookup (`allowPublicSharing` off) |
|-----------|------|------------------|-----------------------------------------------------|
| User OAuth (delegated) | `readonly` | `Files.Read` | `User.ReadBasic.All` (requested at sign-in; unavailable to personal accounts) |
| User OAuth (delegated) | `write` | `Files.ReadWrite` | `User.ReadBasic.All` |
| Entra app (application, admin consent) | `readonly` | `Files.Read.All` | `User.Read.All` |
| Entra app (application, admin consent) | `write` | `Files.ReadWrite.All` | `User.Read.All` |

Application permissions always require admin consent. The directory-lookup
permission is only needed when `onedrive.allowPublicSharing` is off and the
agent calls `onedrive_invite`; without it the invite fails closed with a hint
naming the missing scope.

## Limits

- `onedrive_copy` runs asynchronously on Graph's side; the tool returns once
  the copy is accepted, not once it completes.
- `onedrive_upload` chunks large files at 5 MiB per PUT to the resumable
  upload session, per Graph's recommended chunk size.
- Rate limits are per Entra app / tenant; the node retries `429`/`5xx` with
  exponential backoff (chunked-upload PUTs included — they are idempotent by
  `Content-Range`).
- `onedrive_restore` is **OneDrive Personal only** — Microsoft Graph does not
  support `POST /drive/items/{id}/restore` for work or school accounts. The
  tool refuses up front under Entra app (service) auth; a work/school user
  OAuth account surfaces Graph's own error. Use the OneDrive web recycle bin
  instead.

## Examples

An agent uploads a report, then shares it with a named colleague:

```text
onedrive_upload  { "path": "Reports/q3.pdf", "content_base64": "..." }
onedrive_invite  { "item": "Reports/q3.pdf", "emails": ["alex@contoso.com"],
                    "role": "read" }
```

## Upstream docs

- Microsoft Graph OneDrive API: https://learn.microsoft.com/en-us/graph/api/resources/onedrive
- DriveItem: https://learn.microsoft.com/en-us/graph/api/resources/driveitem
- Upload large files: https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession
- Sharing: https://learn.microsoft.com/en-us/graph/api/driveitem-createlink

## Troubleshooting

- **Scope / 403 errors:** call `onedrive_check_connection`; if scopes are
  missing, disconnect and reconnect the Microsoft account (user auth) or
  grant/consent the Entra app permission (service auth) at the required tier.
- **`access` is read-only:** write tools raise `MicrosoftAccessError`; raise
  `onedrive.access` to `write`.
- **Sharing/invite refused:** anonymous links, and invites to any recipient
  that doesn't resolve to an individual directory user (including a lookup
  permission error), need `onedrive.allowPublicSharing` enabled; permanent
  delete needs `onedrive.allowHardDelete` enabled.
- **Item not found:** confirm whether the caller meant a path or an item id —
  a value without `/` is always treated as an item id, never a bare
  root-level filename.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Outlook Calendar

Route: /nodes/tool_microsoft_365/outlook_calendar

# Outlook Calendar tool node (`tool_outlook_calendar`)

Exposes the Microsoft Graph calendar API as agent tools: list/read events
(including calendarView expansion of recurring series), create/update/delete
events, respond to invitations, find meeting times, get free/busy schedules,
list/create calendars, and delta-sync a calendar view. Operates on the
acting user's calendar.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is
a `@tool_function` an agent calls on demand. Operational targets (event id,
calendar id) are always tool-call parameters, never node config. Outputs are
cleaned shapes (`id`, `subject`, `start`, `end`, `location`, `organizer`,
`attendees`, `isAllDay`, `isCancelled`, `seriesMasterId`, `recurrence`,
`onlineMeeting`, `webLink`, `bodyPreview` for events; `id`, `name`,
`isDefaultCalendar`, `canEdit`, `owner` for calendars), not raw Graph JSON.

## Configuration

| Field | Notes |
|-------|-------|
| `microsoft.authType` | `service` (Entra app, client credentials) or `user` (OAuth). |
| `microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret` | Entra app credentials for `service` auth. |
| `microsoft.userPrincipalName` | Acting user's UPN for `service` auth (app-only calls target `/users/{upn}`). |
| `microsoft.oAuthButton` / `microsoft.userToken` | User OAuth: sign in to populate the access token. |
| `outlook_calendar.access` | `readonly` or `write` (default). Resolved by the shared `OUTLOOK_CALENDAR` spec in `core/microsoft_access.py`; scopes are never hand-entered. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `Calendars.Read` | list/read events and calendars, find meeting times, get schedules, and delta-sync only |
| `write` | `Calendars.ReadWrite` | full read/write (default) — create/update/delete events, respond to invitations, and create calendars, plus everything `readonly` grants |

No gate flags — unlike Outlook Mail's hard-delete flag, event deletion here
needs only the `write` tier.

## Tools

- **Read:** `outlook_calendar_list_events` (calendarView, recurring series
  expanded), `outlook_calendar_get_event`, `outlook_calendar_find_meeting_times`,
  `outlook_calendar_get_schedule`, `outlook_calendar_list_calendars`,
  `outlook_calendar_delta_sync`.
- **Write:** `outlook_calendar_create_event`, `outlook_calendar_update_event`
  (PATCH — only provided fields change), `outlook_calendar_delete_event`,
  `outlook_calendar_respond` (accept/decline/tentativelyAccept),
  `outlook_calendar_create_calendar`.
- **Diagnostics:** `outlook_calendar_check_connection` verifies that granted
  OAuth scopes cover the configured access tier.

## Setup

Authenticate with either an **Entra app** (`microsoft.tenantId` /
`microsoft.clientId` / `microsoft.clientSecret` / `microsoft.userPrincipalName`,
client-credentials flow) or **user OAuth** (click sign-in to populate
`microsoft.userToken`). See `microsoft-oauth.md` for the Entra app / consent
setup shared by every Microsoft 365 tool service. The app must be granted the
Graph `Calendars.Read` and/or `Calendars.ReadWrite` permission (application or
delegated, matching the auth mode and the configured tier) with admin consent.

## Limits

- `outlook_calendar_create_event` / `outlook_calendar_update_event` accept
  `start`/`end` as either a plain `'YYYY-MM-DDTHH:MM:SS'` string (wrapped as
  UTC) or an already-shaped `{dateTime, timeZone}` object.
- `attendees` invites are sent by Graph itself as part of creating/updating
  the event — the `write` tier gates the Graph call, not a separate "send"
  step.
- `outlook_calendar_find_meeting_times` (`findMeetingTimes`) needs a
  delegated (signed-in user) context on Microsoft's side and may not be
  supported under app-only (client-credentials) authentication.
- `outlook_calendar_delta_sync` takes `start`/`end` on the first call; pass
  the returned `delta_link` back in on subsequent calls to fetch only what
  changed.
- Rate limits are per Entra app / tenant; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

An agent creates a meeting and later syncs changes:

```text
outlook_calendar_create_event { "subject": "Sync", "start": "2026-08-11T14:00:00",
                                 "end": "2026-08-11T14:30:00",
                                 "attendees": ["alex@contoso.com"] }
outlook_calendar_delta_sync   { "start": "2026-08-01T00:00:00", "end": "2026-08-08T00:00:00" }
outlook_calendar_delta_sync   { "delta_link": "<deltaLink from the previous call>" }
```

## Upstream docs

- Microsoft Graph calendar API: https://learn.microsoft.com/en-us/graph/api/resources/calendar
- Event: https://learn.microsoft.com/en-us/graph/api/resources/event
- Find meeting times: https://learn.microsoft.com/en-us/graph/api/user-findmeetingtimes
- Get schedule: https://learn.microsoft.com/en-us/graph/api/calendar-getschedule
- Delta query: https://learn.microsoft.com/en-us/graph/delta-query-events

## Troubleshooting

- **Scope / 403 errors:** call `outlook_calendar_check_connection`; if scopes
  are missing, disconnect and reconnect the Microsoft account (user auth) or
  grant/consent the Entra app permission (service auth) at the required tier.
- **`access` is `readonly`:** every write tool raises `MicrosoftAccessError`;
  raise `outlook_calendar.access` to `write`.
- **`outlook_calendar_find_meeting_times` fails under app-only auth:** this
  endpoint needs a delegated (signed-in user) context; switch to user OAuth
  or use `outlook_calendar_get_schedule` instead.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Outlook Mail

Route: /nodes/tool_microsoft_365/outlook_mail

# Outlook Mail tool node (`tool_outlook_mail`)

Exposes the Microsoft Graph mail API as agent tools: list, search, and read
messages, send mail and replies/forwards, manage drafts, move/organize
messages and folders, manage attachments, and mark read state. Operates on
the acting user's mailbox.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is
a `@tool_function` an agent calls on demand. Operational targets (message id,
folder id, attachment id) are always tool-call parameters, never node
config. Outputs are cleaned shapes (`id`, `subject`, `from`, `toRecipients`,
`receivedDateTime`, `bodyPreview`, `isRead`, `hasAttachments`,
`parentFolderId`, plus a readable `body` on `outlook_mail_get_message`), not
raw Graph JSON.

## Configuration

| Field | Notes |
|-------|-------|
| `microsoft.authType` | `service` (Entra app, client credentials) or `user` (OAuth). |
| `microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret` | Entra app credentials for `service` auth. |
| `microsoft.userPrincipalName` | Acting user's UPN for `service` auth (app-only calls target `/users/{upn}`). |
| `microsoft.oAuthButton` / `microsoft.userToken` | User OAuth: sign in to populate the access token. |
| `outlook_mail.access` | `readonly`, `send`, or `modify` (default). Resolved by the shared `OUTLOOK_MAIL` spec in `core/microsoft_access.py`; scopes are never hand-entered. |
| `outlook_mail.allowHardDelete` | Off by default. When off, delete moves messages to Deleted Items; permanent delete is refused. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `Mail.Read` | list, search, and read messages/folders/attachments only |
| `send` | `Mail.Read`, `Mail.Send` | readonly plus sending mail, replies, and forwards |
| `modify` | `Mail.ReadWrite`, `Mail.Send` | full read/write (default) — drafts, moves, organizing, attachments, and permanent delete (when `allowHardDelete` is on), plus send |

The `send` tier is nominally "writable" (only `readonly` is treated as
read-only) but does **not** carry `Mail.ReadWrite`: sending is gated on the
`Mail.Send` scope, and every drafting/organizing/attachment tool is
separately gated on `Mail.ReadWrite`, so a `send`-tier node can send and
reply but cannot create drafts, move messages, or touch folders/attachments.

### Gate flags

- **`allowHardDelete`**: off by default. When off, `outlook_mail_delete_message`
  moves a message to Deleted Items (recoverable) and
  `outlook_mail_permanently_delete` is refused. Turn on to allow permanent,
  irreversible delete.

## Tools

- **Read:** `outlook_mail_list_messages` (a folder's messages, search or
  OData filter), `outlook_mail_get_message` (full body, HTML converted to
  readable text), `outlook_mail_list_folders`, `outlook_mail_list_attachments`,
  `outlook_mail_get_attachment`.
- **Send (send/modify tier):** `outlook_mail_send_message`, `outlook_mail_reply`,
  `outlook_mail_reply_all`, `outlook_mail_forward`.
- **Modify (modify tier):** `outlook_mail_create_draft`, `outlook_mail_move_message`,
  `outlook_mail_set_read`, `outlook_mail_set_categories`,
  `outlook_mail_delete_message` (soft delete), `outlook_mail_create_folder`,
  `outlook_mail_add_attachment` (drafts only).
- **Delete (modify tier + gate):** `outlook_mail_permanently_delete` (gated by
  `allowHardDelete`).
- **Diagnostics:** `outlook_mail_check_connection` verifies that granted
  OAuth scopes cover the configured access tier.

## Setup

Authenticate with either an **Entra app** (`microsoft.tenantId` /
`microsoft.clientId` / `microsoft.clientSecret` / `microsoft.userPrincipalName`,
client-credentials flow) or **user OAuth** (click sign-in to populate
`microsoft.userToken`). See `microsoft-oauth.md` for the Entra app / consent
setup shared by every Microsoft 365 tool service. The app must be granted the
Graph `Mail.Read`, `Mail.Send`, and/or `Mail.ReadWrite` permission
(application or delegated, matching the auth mode and the configured tier)
with admin consent.

## Limits

- `outlook_mail_list_messages`' `query` is treated as a full-text `$search`
  term unless it looks like an OData filter expression (contains `eq`, `ne`,
  `gt`, `lt`, `ge`, `le`, `startswith(`, or `contains(`), in which case it is
  passed through as `$filter`.
- `outlook_mail_add_attachment` only works against a draft message — create
  one with `outlook_mail_create_draft` first.
- Rate limits are per Entra app / tenant; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

An agent drafts a reply and attaches a file:

```text
outlook_mail_create_draft  { "to": ["alex@contoso.com"], "subject": "Re: Q3",
                              "body": "See attached." }
outlook_mail_add_attachment { "message_id": "<draft id>", "name": "q3.pdf",
                               "content_base64": "..." }
```

## Upstream docs

- Microsoft Graph mail API: https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview
- Message: https://learn.microsoft.com/en-us/graph/api/resources/message
- Send mail: https://learn.microsoft.com/en-us/graph/api/user-sendmail
- Search messages: https://learn.microsoft.com/en-us/graph/search-query-parameter

## Troubleshooting

- **Scope / 403 errors:** call `outlook_mail_check_connection`; if scopes are
  missing, disconnect and reconnect the Microsoft account (user auth) or
  grant/consent the Entra app permission (service auth) at the required tier.
- **`access` is `readonly`:** every write/send tool raises
  `MicrosoftAccessError`; raise `outlook_mail.access` to `send` or `modify`.
- **`access` is `send` but drafts/moves/attachments are refused:** the `send`
  tier lacks `Mail.ReadWrite`; raise `outlook_mail.access` to `modify`.
- **Permanent delete refused:** needs `outlook_mail.allowHardDelete` enabled;
  `outlook_mail_delete_message` (soft delete to Deleted Items) is always
  available at the `modify` tier.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Word

Route: /nodes/tool_microsoft_365/word

# Word tool node (`tool_word`)

Exposes a docx round-trip over the Microsoft Graph drive content API as agent
tools: read text, create a document from paragraphs, append text, find/replace
text, and export to PDF. Operates on `.docx` files in the acting user's
OneDrive, editing them in-process with `python-docx`.

## What it does

An agent-invocable tool node — no data flows through lanes. Each operation is
a `@tool_function` an agent calls on demand. Operational targets (file
path/id, new-document destination path) are always tool-call parameters,
never node config. Outputs are cleaned shapes (`id`, `name`, `webUrl`, text),
not raw Graph JSON and never the raw docx/PDF bytes.

There is no persisted Word Online editing session. Every write downloads the
current `.docx` (`GET` metadata for the eTag, then `GET .../content`), edits
it in-process, and re-uploads the whole file (`PUT .../content`) with an
`If-Match` header carrying that eTag — Graph rejects the write with
`409`/`412` if the file changed in between, which surfaces as a `GraphError`
naming the conflict rather than silently last-writer-wins overwriting someone
else's edit. On a conflict, re-read with `word_read_text` and retry.

## Configuration

| Field | Notes |
|-------|-------|
| `microsoft.authType` | `service` (Entra app, client credentials) or `user` (OAuth). |
| `microsoft.tenantId` / `microsoft.clientId` / `microsoft.clientSecret` | Entra app credentials for `service` auth. |
| `microsoft.userPrincipalName` | Acting user's UPN for `service` auth (app-only calls target `/users/{upn}`). |
| `microsoft.oAuthButton` / `microsoft.userToken` | User OAuth: sign in to populate the access token. |
| `word.access` | `readonly` or `write` (default). Resolved by the shared `WORD` spec in `core/microsoft_access.py`; scopes are never hand-entered. |

### Access tiers → scopes

| Tier | Scope | Capability |
|------|-------|------------|
| `readonly` | `Files.Read` | read document text only |
| `write` | `Files.ReadWrite` | full read/write (default) |

There are no destructive gate flags.

## Tools

- **Read:** `word_read_text` — every body paragraph plus every table cell's
  text, newline-joined.
- **Write:** `word_create_document` (new `.docx` from a paragraph list, no
  `If-Match` — nothing to conflict with yet), `word_append_text` (append
  paragraphs, `If-Match`-guarded), `word_replace_text` (find/replace across
  paragraphs and table cells, `If-Match`-guarded, returns a replacement
  count), `word_export_pdf` (server-side PDF conversion, uploaded beside the
  source; returns file metadata, never the PDF bytes).
- **Diagnostics:** `word_check_connection` verifies that granted OAuth scopes
  cover the configured access tier.

### `word_replace_text` approach

Replacement runs in a single pass per paragraph (body and table cells
alike), scanning each paragraph's *original* text exactly once:

- `original = paragraph.text` (the concatenation of all its runs) is
  scanned for `find` and the count and replacement are both computed from
  that one, never-mutated string. Scanning already-replaced text instead
  (a run-then-paragraph two-pass approach) is how a `replace` value that
  itself contains `find` would double-count and corrupt the result — e.g.
  `find='foo'`, `replace='foobar'` on `'foo is here'` would match once,
  rewrite it to `'foobar is here'`, then find `'foo'` again inside the
  freshly written `'foobar'` on a second pass, ending with a wrong count
  of 2 and corrupted text `'foobarbar is here'`. A single pass over the
  original text avoids this entirely.
- Paragraphs with **zero** matches are left completely untouched — no run
  is touched, no formatting is disturbed.
- Paragraphs with **at least one** match get their new text written into
  the first run, with every other run in that paragraph blanked. The
  first run's formatting wins for the whole merged text — a multi-run
  paragraph that matches loses its intra-paragraph formatting boundaries
  (bold/italic spans, etc.) on replacement. This is a known trade-off of a
  plain read-modify-write text replace, not a substitute for a real Word
  editing session.

## Setup

Authenticate with either an **Entra app** (`microsoft.tenantId` /
`microsoft.clientId` / `microsoft.clientSecret` / `microsoft.userPrincipalName`,
client-credentials flow) or **user OAuth** (click sign-in to populate
`microsoft.userToken`). See `microsoft-oauth.md` for the Entra app / consent
setup shared by every Microsoft 365 tool service. The Graph permission the
app needs depends on the auth mode:

| Auth mode | Tier | Graph permission |
| --- | --- | --- |
| User OAuth (delegated) | `readonly` | `Files.Read` |
| User OAuth (delegated) | `write` | `Files.ReadWrite` |
| Entra app (application, admin consent) | `readonly` | `Files.Read.All` |
| Entra app (application, admin consent) | `write` | `Files.ReadWrite.All` |

Application permissions always require admin consent. Unlike the Excel
workbook API, Word's drive-item download/upload/convert calls work app-only,
so both auth modes are fully supported.

## Limits

- Concurrency: round-trip edits (`word_append_text`, `word_replace_text`) use
  `If-Match`; a stale eTag (someone else edited the file since it was
  downloaded) surfaces as a `GraphError` naming the conflict. The tool does
  not retry automatically — re-read with `word_read_text` and retry the edit.
- `word_export_pdf` relies on Graph's server-side format conversion
  (`?format=pdf`); very large or exotic documents may take longer to convert
  or fail conversion upstream.
- `word_replace_text` writes a matched paragraph's new text into its first
  run and blanks the rest, collapsing per-run formatting in that paragraph to
  the first run's style — acceptable for plain text edits, not a substitute
  for a real Word editing session. Unmatched paragraphs are untouched.
- Rate limits are per Entra app / tenant; the node retries `429`/`5xx` with
  exponential backoff.

## Examples

An agent creates a report, then finds and replaces a placeholder:

```
word_create_document  { "path": "Docs/report.docx",
                         "paragraphs": ["Q3 Report", "Status: DRAFT"] }
word_replace_text      { "file": "Docs/report.docx", "find": "DRAFT",
                          "replace": "FINAL" }
```

## Upstream docs

- Microsoft Graph drive content API: https://learn.microsoft.com/en-us/graph/api/driveitem-get-content
- DriveItem format conversion: https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format
- python-docx: https://python-docx.readthedocs.io/

## Troubleshooting

- **Scope / 403 errors:** call `word_check_connection`; if scopes are
  missing, disconnect and reconnect the Microsoft account (user auth) or
  grant/consent the Entra app permission (service auth) at the required tier.
- **`access` is read-only:** write tools raise `MicrosoftAccessError`; raise
  `word.access` to `write`.
- **Conflict / 409 / 412 errors:** the file changed since it was downloaded
  (someone else edited it, or a prior call's upload already advanced the
  eTag). Call `word_read_text` to get the current content and retry the edit.
- **`word_replace_text` returns 0:** confirm the exact text — `find` is a
  literal (case-sensitive) substring match, not a regex.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# n8n

Route: /nodes/tool_n8n

# tool_n8n

A RocketRide node that invokes an n8n webhook from pipeline lanes or gives an
agent controlled access to an n8n instance. Pick it when an existing n8n
workflow is the right automation boundary rather than rebuilding that flow on
the RocketRide canvas.

## About n8n

n8n is a workflow-automation product that connects services and custom logic
through executable workflows. It can expose a workflow through webhooks and a
public API; this node uses those interfaces from RocketRide.

## What it does

Connects a RocketRide pipeline to [n8n](https://n8n.io) workflow automation. It's a **dual node**:

- **Pipeline step** — lane input is POSTed to a workflow's webhook and the workflow's response flows out to the next node.
- **Agent tool** — an agent can trigger workflows and inspect workflows/executions at runtime.

n8n is self-hosted, so you configure your instance's **Base URL** and (for listing/polling) a **public API key**.

## Lanes

**Lanes:**

| Lane in     | Lane out            | Description                                                        |
| ----------- | ------------------- | ------------------------------------------------------------------ |
| `text` | `text` | Sends text to the configured workflow and emits its result |
| `text` | `answers` | Sends text to the configured workflow and emits its result |
| `text` | `table` | Sends text to the configured workflow and emits its result |
| `questions` | `answers` | Sends question text to the workflow and emits its result |
| `questions` | `text` | Sends question text to the workflow and emits its result |
| `questions` | `table` | Sends question text to the workflow and emits its result |
| `documents` | `documents` | Sends documents to the configured workflow and emits its result |
| `documents` | `text` | Sends documents to the configured workflow and emits its result |
| `documents` | `table` | Sends documents to the configured workflow and emits its result |
| `image` | `image` | Sends binary input as multipart and emits returned image data |
| `image` | `text` | Sends binary input as multipart and emits a text result |
| `image` | `answers` | Sends binary input as multipart and emits an answer result |
| `image` | `table` | Sends binary input as multipart and emits a structured result |
| `audio` | `audio` | Sends binary input as multipart and emits returned audio data |
| `audio` | `text` | Sends binary input as multipart and emits a text result |
| `audio` | `answers` | Sends binary input as multipart and emits an answer result |
| `audio` | `table` | Sends binary input as multipart and emits a structured result |
| `video` | `video` | Sends binary input as multipart and emits returned video data |
| `video` | `text` | Sends binary input as multipart and emits a text result |
| `video` | `answers` | Sends binary input as multipart and emits an answer result |
| `video` | `table` | Sends binary input as multipart and emits a structured result |

Structured (`payloadMode: structured`) and binary requests preserve document boundaries/metadata and file bytes; a `table` listener receives structured (dict/list) results.

The accumulated input is sent to the configured **Workflow (webhook path)** as JSON `{"data": "<input>"}`. The webhook response is emitted to whichever output lanes are connected.

## As a tool

Exposes these functions to an agent (namespaced under `n8n`):

| Function                | Description                                                              |
| ----------------------- | ------------------------------------------------------------------------ |
| `n8n.trigger_workflow`  | Trigger a workflow by its webhook path; returns the response             |
| `n8n.list_workflows`    | List workflows (id, name, active, webhook paths) — needs API key         |
| `n8n.get_workflow`      | Get one workflow by id — needs API key                                   |
| `n8n.list_executions`   | List recent executions (status, timestamps) — needs API key              |
| `n8n.get_execution`     | Get one execution by id, with data — needs API key                       |
| `n8n.activate_workflow` | Activate a workflow (blocked in read-only mode) — needs API key          |
| `n8n.deactivate_workflow` | Deactivate a workflow (blocked in read-only mode) — needs API key      |

The agent never chooses the host — every request targets the configured Base URL — and `workflow` arguments are sanitized to a plain webhook path.

Tool calls return a `success` flag and an `error` message on validation or API
failure. `trigger_workflow` uses its optional `workflow` argument or the
configured workflow, and `get_workflow`, `get_execution`,
`activate_workflow`, and `deactivate_workflow` each require an `id`.

## Configuration

Configure the Base URL and the webhook path first. The default synchronous,
simple-payload setup suits a workflow that returns one response; most other
fields can remain at their defaults.

### Payload shape and result mode

Use **structured** payloads when the workflow needs separate document content
and metadata; the default **simple** mode flattens input into one `data`
string for compatibility. **Sync** waits for the webhook response and should
be paired with a response-producing workflow. Choose **async** for a long run:
it polls the public API and therefore requires the API key. Raise the matching
timeout only when the workflow genuinely needs longer than the 30-second sync
or 120-second async defaults.

### Authentication and write access

Webhook authentication is independent of the public API key. Match it to the
target Webhook node, supplying the relevant header, basic credentials, or
bearer/JWT token only for its selected mode. Keep TLS verification enabled
unless a self-signed local HTTPS instance requires otherwise. Read-only mode
is on by default; disable it only when the agent is explicitly allowed to
activate or deactivate workflows.

## Notes

### Setup

- **Triggering is webhook-only.** The target workflow needs a **Webhook** trigger node. Manual/cron/event-triggered workflows can't be triggered over HTTP directly — wrap them with a webhook **dispatcher** (Execute Sub-Workflow); see the [n8n integration guide](https://docs.rocketride.org/connect/n8n).
- **Activate the workflow.** A production webhook (`/webhook/...`) only exists once the workflow is **activated/published** in n8n — otherwise the call 404s and the node tells you to activate it. While editing, set `test_mode` to use the editor's one-shot `/webhook-test/...` route.
- **Return a result.** For `sync` mode, the workflow must end in a **"Respond to Webhook"** node (or set the Webhook node to respond when the last node finishes); otherwise n8n only returns a "workflow started" ack and the node warns you.
- **Docker reachability.** If RocketRide runs in a container, `localhost` points at the container, not your machine. Use `http://host.docker.internal:5678` (Docker Desktop, or add `extra_hosts: ["host.docker.internal:host-gateway"]` on Linux), or run n8n on the same Docker network and use `http://n8n:5678`. The node detects this and suggests the fix.

### Round-trips (n8n → RocketRide)

The reverse direction needs no special node: any RocketRide pipeline with a `webhook`/`chat`/`dropper` source is HTTP-callable from n8n's **HTTP Request** node, enabling RR→n8n→RR round-trips. See the [n8n integration guide](https://docs.rocketride.org/connect/n8n) and the templates [`examples/n8n-roundtrip.pipe`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n-roundtrip.pipe) + [`examples/n8n-call-rocketride.workflow.json`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n-call-rocketride.workflow.json).

### Environment variables

Either set fields in the node config or use env vars:

```bash
ROCKETRIDE_N8N_URL=http://localhost:5678
ROCKETRIDE_N8N_KEY=...   # n8n public API key
```

## Upstream docs

- [n8n documentation](https://docs.n8n.io)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_n8n.apiKey` | `string` | **API Key (X-N8N-API-KEY)**<br/>n8n public API key. Needed only to list/inspect workflows and poll executions — not for triggering webhooks. | `""` |
| `tool_n8n.asyncTimeout` | `integer` | **Execution timeout (seconds)**<br/>Max seconds to wait for an async execution to finish before raising an error. | `120` |
| `tool_n8n.baseUrl` | `string` | **n8n Base URL**<br/>Base URL of your n8n instance, e.g. http://localhost:5678 or https://n8n.example.com. If RocketRide runs in Docker, use http://host.docker.internal:5678 (or the n8n container name) — 'localhost' would point at the container. | `"http://localhost:5678"` |
| `tool_n8n.mode` | `string` | **Result mode**<br/>Sync requires the workflow to end in a 'Respond to Webhook' node. Async polls the execution via the public API (API key required). | `"sync"` |
| `tool_n8n.payloadMode` | `string` | **Payload shape (pipeline step)**<br/>How lane input is sent to the workflow. 'structured' preserves document boundaries + metadata; 'simple' (default) flattens to a single string for back-compat. | `"simple"` |
| `tool_n8n.readOnly` | `boolean` | **Read-only mode**<br/>When ON, write operations (activate/deactivate workflow) are blocked. | `true` |
| `tool_n8n.syncTimeout` | `integer` | **Response timeout (seconds)**<br/>Max seconds to wait for the webhook response in sync mode (raise for slow workflows). | `30` |
| `tool_n8n.verifyTls` | `boolean` | **Verify TLS certificate**<br/>Leave ON. Disable only for a self-signed local n8n served over HTTPS. | `true` |
| `tool_n8n.webhookAuth` | `string` | **Webhook auth**<br/>Authentication on the workflow's Webhook node. Separate from the API key above. | `"none"` |
| `tool_n8n.webhookHeaderName` | `string` | **Header name**<br/>Header name (when Webhook auth = Header auth). | `""` |
| `tool_n8n.webhookHeaderValue` | `string` | **Header value**<br/>Header value (when Webhook auth = Header auth). | `""` |
| `tool_n8n.webhookPassword` | `string` | **Password**<br/>Password (when Webhook auth = Basic auth). | `""` |
| `tool_n8n.webhookToken` | `string` | **Token**<br/>Token sent as 'Authorization: Bearer <token>' (when Webhook auth = Bearer token or JWT). | `""` |
| `tool_n8n.webhookUser` | `string` | **Username**<br/>Username (when Webhook auth = Basic auth). | `""` |
| `tool_n8n.workflow` | `string` | **Workflow (webhook path)**<br/>The webhook path the target workflow listens on (set on its Webhook node). Used by the pipeline step and as the default for the trigger tool. | `""` |

## Dependencies

- `requests` `>=2.34.2`
- `idna` `>=3.10`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_n8n)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Notion

Route: /nodes/tool_notion

# tool_notion

A RocketRide tool node that gives an agent read and write access to a Notion workspace: search it, read pages and database rows, and create, update, or append to pages. Pick it when an agent's knowledge or its output lives in Notion rather than in files or a database.

## About Notion

Notion is a workspace product that combines documents, wikis, and lightweight databases in one place. Its pages are built from nested blocks, and its databases hold rows that are themselves pages with typed properties. Teams use it for notes, specs, and project tracking.

## What it does

The node has no data lanes; it exists only as an agent tool server, exposing eight Notion operations. An agent typically searches for a page or database id first, then reads properties or body text, and optionally writes back — creating a sub-page or database row, updating property values, or appending paragraphs. Pick it over a generic HTTP tool when you want Notion's block tree flattened into readable text and its database/data-source split handled for you.

Notion's current API splits what older documentation calls a "database" into a **database** (the container: title, parent, and a list of data sources) and a **data source** (the thing whose rows you query). This node targets that shape. Tools that take a `database_id` resolve it to a data source automatically when the database has exactly one, and need an explicit `data_source_id` only when there is more than one.

## As a tool

The server-name prefix is `notion`, producing these registered functions.

| Function | Description |
|---|---|
| `notion_search` | Search the workspace by title text across pages and databases the integration has been shared with. Use it to find an id before reading or writing. |
| `notion_get_database` | Return a database's title and its data sources (id and name). |
| `notion_query_database` | Query a database's rows with an optional Notion filter and sorts. |
| `notion_get_page` | Return a page's properties, `url`, and `in_trash` flag — not its body. |
| `notion_get_page_content` | Return a page's body as flattened plain text. |
| `notion_create_page` | Create a sub-page under a page, or a new row under a data source, with optional initial body text. |
| `notion_update_page` | Update a page's property values and/or move it to or from trash. |
| `notion_append_content` | Append text to the end of a page's or block's body, one paragraph per line. |

Every function returns `success`, plus its own fields on success (`results`/`has_more`/`next_cursor` for the two listing calls, `text` for page content, `page_id` and `url` for creation, `appended` for the append) and `error` on failure. Notion API failures are returned in that envelope rather than raised.

`notion_search` accepts `query`, an optional `filter_type` of `page` or `data_source`, and `page_size`. `notion_query_database` requires `database_id` and accepts `data_source_id`, `filter`, `sorts`, `page_size`, and `start_cursor`; page sizes are clamped to 1–100. `notion_get_page_content` requires `page_id` and accepts `max_depth` (default 4). `notion_create_page` requires `parent_id` and a `parent_type` of `page` or `data_source`, and accepts `title`, `properties`, and `content`. `notion_update_page` requires `page_id` and at least one of `properties` or `in_trash`. `notion_append_content` requires `block_id` and non-empty `text`.

Property values in `filter`, and in the `properties` of the two write calls, use Notion's own typed property-value shape (for example `{"Status": {"select": {"name": "Done"}}}`) and are passed through unchanged.

## Configuration

The node has a single field: the integration secret it authenticates with. There is nothing else to tune — everything an agent varies is a tool argument, not configuration.

### API Key

The Notion internal integration secret. It is stored encrypted and masked in the UI. Leave it empty only if you set `NOTION_API_KEY` on the engine host instead; the config field wins when both are present, and startup fails when neither yields a value.

## Authentication

Create an internal integration at <https://www.notion.so/my-integrations> and paste its secret into **API Key**, or set `NOTION_API_KEY` on the engine host. The key is sent as an `Authorization: Bearer` header.

Access is granted per page, not per scope: an integration sees only the pages and databases explicitly shared with it from a page's connection menu, and sharing a page also shares everything nested beneath it. A search that returns nothing usually means nothing has been shared yet.

## Notes

### Experimental

The node is marked `experimental`. Its request and response shapes are read from Notion's own API reference, but no live workspace has exercised it end to end, so the surface may change.

### Reading page content

A page's body is a block tree, not text. `notion_get_page_content` walks that tree and emits one line per block, indenting nested content (a toggle's children, a nested bullet) up to `max_depth` levels. Blocks with no text of their own — dividers, images, tables — contribute nothing rather than being guessed at. Raise `max_depth` for deeply nested pages; the default of 4 covers ordinary documents.

### Titles on new database rows

A database's title property is not always called "Name". When `notion_create_page` is given a `title` for a `data_source` parent and the caller's `properties` does not already name a title field, the node looks the real key up from the data source's schema. Supply the title inside `properties` yourself if you want to bypass that lookup.

### Retries and duplicate writes

Reads time out after 30 seconds and retry up to three times with exponential backoff on connection errors, rate limits (honoring `Retry-After` when it is longer than the computed delay), and 5xx responses. The three write functions are never retried, because Notion offers no idempotency key and a retried mutation could duplicate a page or its content — an agent that sees a connection error on a write should check the target before trying again.

### Request limits

`notion_append_content` sends at most 100 blocks per request, batching longer input. A line over 2000 characters is rejected outright rather than truncated, matching Notion's rich-text limit; shorten the line and retry.

## Upstream docs

- [Notion API reference](https://developers.notion.com/reference/intro)
- [Notion request limits](https://developers.notion.com/reference/request-limits)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_notion.apikey` | `string` | **API Key**<br/>Notion internal integration secret (from https://www.notion.so/my-integrations) | `""` |

## Dependencies

- `requests` `>=2.34.2`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_notion)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Oura

Route: /nodes/tool_oura

# tool_oura

A RocketRide agent tool node that exposes the [Oura API v2](https://cloud.ouraring.com/v2/docs) as read-only tools. Bind it to any agent (`agent_rocketride`, `agent_langchain`, `agent_crewai`, `agent_deepagent`) and the agent can query the token owner's Oura Ring data on demand.

## About Oura

Oura makes a wearable ring and companion service for personal health and
activity data. Its API gives applications access to the token owner's records,
including sleep, readiness, activity, and other health measurements.

## What it does

Wraps every current Oura v2 `usercollection` endpoint behind 21 tool functions (the deprecated `tag` endpoint is skipped in favor of its successor, `enhanced_tag`). All operations are **read-only** — the Oura v2 API offers no write endpoints for personal data, so an agent bound to this node can never modify anything.

Responses are compacted before they reach the agent: heavy time-series fields (`class_5_min`, `sleep_phase_5_min`, `hrv`, `heart_rate`, `met`, `movement_30_sec`, `motion_count`) are stripped unless the tool call passes `include_detail: true`. This keeps multi-day queries within sane token budgets while leaving full-resolution data one flag away.

Pagination is followed transparently (up to 10 pages per call). If a range is truncated, the response carries a `next_token` the agent can pass back to continue — Oura returns documents date-ascending, so the missing pages hold the most recent data. `daily_summary` cannot paginate; it instead flags a page-cap hit with a `truncated` key so the agent knows to narrow the range.

## As a tool

Tools use the `oura` prefix by default. They return API data or raise a
descriptive error; they do not modify the token owner's data.

| Tool | Oura collection | Description |
|---|---|---|
| `personal_info` | `personal_info` | Age, weight, height, biological sex, email |
| `ring_configuration` | `ring_configuration` | Ring color, design, firmware, hardware, size |
| `ring_battery_level` | `ring_battery_level` | Battery level samples over time (datetime-windowed) |
| `daily_summary` | (merged) | One record per day combining sleep, readiness, activity, and stress |
| `sleep_daily` | `daily_sleep` | Daily sleep scores and contributors |
| `readiness_daily` | `daily_readiness` | Daily readiness scores and contributors |
| `activity_daily` | `daily_activity` | Steps, calories, MET minutes, sedentary time |
| `stress_daily` | `daily_stress` | High-stress / high-recovery seconds, day summary |
| `resilience_daily` | `daily_resilience` | Resilience level and contributors |
| `spo2_daily` | `daily_spo2` | Blood oxygen averages, breathing disturbance index |
| `cardiovascular_age_daily` | `daily_cardiovascular_age` | Vascular age estimates |
| `sleep_periods` | `sleep` | Detailed sleep periods: stages, HR, HRV, respiratory rate |
| `heartrate` | `heartrate` | Raw heart rate samples (datetime-windowed) |
| `workouts` | `workout` | Logged workouts |
| `sessions` | `session` | Meditation / breathing / relaxation sessions |
| `tags` | `enhanced_tag` | User-logged events (caffeine, alcohol, sickness, custom) |
| `rest_mode_periods` | `rest_mode_period` | Rest mode windows |
| `sleep_time` | `sleep_time` | Recommended bedtime windows |
| `vo2_max` | `vO2_max` | VO2 max estimates |
| `collection_get` / `document_get` | (any) | Generic escape hatches: any date-filtered collection by name, any document by ID. `heartrate`, `ring_battery_level`, and `ring_configuration` are excluded where their filters don't apply — use the dedicated tools |

Date-range tools accept `start_date` / `end_date` (ISO `YYYY-MM-DD`); when omitted, `end_date` defaults to tomorrow (UTC) — Oura `day` fields use the wearer's local timezone, so UTC-today would drop the current local day for anyone ahead of UTC — and `start_date` to a per-tool sensible window (7 days for daily scores, 30 for workouts/sessions/tags, 90 for rest mode). `heartrate` and `ring_battery_level` filter on ISO datetimes (24-hour and 72-hour default windows respectively).

---

## Configuration

Set the access token and leave the rest of the behavior to the agent's tool
calls. This is a tool-only node with no data lanes, so bind it to an agent
rather than wiring it into a data-flow branch.

### Access Token

Supply an Oura API bearer token in the secure field. Use the environment
fallback only when deployment configuration cannot hold the token; a missing
token prevents the node from starting, while an expired or insufficiently
scoped token produces a descriptive tool error.

---

## Authentication

The token is resolved in the following order:

1. `token` in the node config
2. `token` in the connection config
3. The `ROCKETRIDE_OURA_TOKEN` environment variable

The node sends the token as a standard `Authorization: Bearer` header, so any valid Oura API v2 bearer token works. Oura deprecated personal access tokens in December 2025 (previously issued ones still work); new tokens come from the OAuth2 flow of a registered API application:

1. Register an application at [cloud.ouraring.com](https://cloud.ouraring.com) (personal single-user apps need no Oura approval — the 10-user limit only applies beyond that). A `localhost` redirect URI is fine.
2. For quick personal use, run the implicit flow: open `https://cloud.ouraring.com/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=token` in a browser, approve, and copy the `access_token` from the redirect URL fragment. Implicit-flow tokens expire after ~30 days. **Omit the `scope` parameter** so the consent screen offers every scope enabled for your app — Oura's documented scope list (`email personal daily heartrate workout tag session spo2Daily`) is incomplete, and several of this node's tools need undocumented scopes (`ring_configuration`, `stress`, `heart_health`). A token minted with only the documented scopes gets `Oura scope not granted (401)` on ring configuration, battery level, stress, resilience, cardiovascular age, and VO2 max.
3. For renewable tokens, use the authorization-code flow (`response_type=code`, then exchange at `https://api.ouraring.com/oauth/token` with the client secret) and rotate via the returned single-use `refresh_token`.

If your pipeline only needs a subset of the data, you can still pass an explicit `scope` parameter to restrict the token. If no source provides a token, the pipeline fails at startup with `tool_oura: token is required`; the editor also surfaces a validation warning while configuring the node.

---

## Notes

### Error handling

Oura HTTP errors are mapped to descriptive failures the agent can act on:

- **401**: `Oura authentication failed` — bad or expired token; when Oura's response mentions a scope, it is surfaced as `Oura scope not granted` instead (Oura reports missing OAuth scopes as 401, not 403), so re-authorize the app with that scope rather than replacing the token. `daily_summary` degrades gracefully: collections the token lacks scopes for are skipped and listed in `skipped_collections` instead of failing the whole call
- **403**: `Oura access denied` — token lacks the required scope
- **404**: `Oura resource not found` — wrong or stale document ID, or an ID from a different collection
- **422**: `Oura rejected the request parameters` — malformed dates or filters
- **426**: `Oura subscription required` — the data needs an active Oura membership
- **429**: `Oura rate limit exceeded` — Oura allows 5000 requests per 5-minute window
- Network timeout / connection failures raise with an explicit message

## Upstream docs

- [Oura API documentation](https://cloud.ouraring.com/v2/docs)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `oura.token` | `string` | **Access Token**<br/>Oura API bearer token: an OAuth2 access token from a registered app at cloud.ouraring.com (personal access tokens were deprecated in Dec 2025; previously issued ones still work). Grants read-only access to the token owner's data. Falls back to the ROCKETRIDE_OURA_TOKEN environment variable when empty. | `""` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_oura)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Pipeline Tool

Route: /nodes/tool_pipe

# tool_pipe

A RocketRide tool node that turns a whole inline pipeline into a single agent tool.

## About RocketRide

RocketRide is a pipeline system for connecting sources, processors, models,
and responses. This node packages a connected portion of that same pipeline
as a callable tool for an agent.

## What it does

Exposes one tool, `run_pipe`, to an AI agent. When the agent calls it, the input text
fans out to every connected output lane, the inline sub-pipeline runs synchronously, and
the value from the configured response lane is returned to the agent.

`tool_pipe` is the one `tool_*` node with real output lanes (`text`, `questions`,
`documents`, `table`, `answers`) on its `_source` channel. Wire them to other nodes on
the same canvas to shape the tool's behavior, and cap each connected branch with a
response node so results can flow back. As always, the agent binds through the `invoke`
capability.

The sub-pipeline run is fully isolated. After the input is routed, the sub-pipeline is
flushed (`closing`) and closed in **dependency order** — a join is flushed only after all
of its upstream branches, so a diamond sub-pipeline (two branches feeding one join)
returns the merged output of both branches, not just the first. The flush completes before
the response value is read. Those response entries are snapshotted and then removed so
they don't leak into the parent pipeline. The node has no external Python dependencies
(`requirements.txt` is empty).

---

## Lanes

| Lane in | Lane out | Description |
|---|---|---|
| `_source` | `text` | Sends the agent input as text to connected nodes |
| `_source` | `questions` | Sends the input as a Question to connected nodes |
| `_source` | `documents` | Sends the input as a Doc to connected nodes |
| `_source` | `table` | Sends the raw input to connected nodes |
| `_source` | `answers` | Sends the input as an Answer to connected nodes |

## As a tool

| Function | Description |
|---|---|
| `tool_pipe.run_pipe` | Runs the connected inline pipeline with required non-empty `data` and returns `result` |

`tool_pipe` is the default server-name prefix. The response is a string from
the configured return lane; missing input raises an error, while a pipeline
that produces no selected response returns an empty result.

### Sub-pipeline ownership

Because `tool_pipe` opens, flushes, and closes its sub-pipeline on every invocation, each
node it reaches must have no other lifecycle owner. Three wirings break that and are
**rejected when the pipeline opens**:

- **Shared with the main flow or a second start.** If a sub-pipeline node is also
  reachable from the source — the main flow feeds into it, or the sub-pipeline flows back
  into a main-flow node — the main flow owns it and flushes it at end-of-object, not
  during the invocation, so the tool reads an incomplete result. Keep each branch
  self-contained and end it in its own response node.
- **Shared between two `tool_pipe`s.** A node reached by two invoke nodes has ambiguous
  ownership. Give each its own sub-pipeline.
- **A data input on the invoke node itself.** `tool_pipe` has no input lane — it is driven
  only through the tool control seam.

Invoking the *same* `tool_pipe` from two agents is fine: that is one sub-pipeline with one
owner, run once per invocation. Nesting is fine too — a sub-pipeline may contain an agent
that invokes another `tool_pipe`, and each level flushes its own sub-pipeline in order.
See `examples/incorrect/` for a runnable example of each rejection.

---

## Configuration

The single default profile uses an empty description and returns the `text`
response lane. Configure the description before attaching this node to an
agent, then make the return type match a response lane that the sub-pipeline
actually produces.

### Tool Description

Describe the connected sub-pipeline in the language an agent can use to decide
when to call it. An empty default makes the tool harder for the agent to select;
for example, use “Summarize a supplied support ticket” for a summarization
branch.

### Return Type

Use `text` for a normal textual response. Choose `answers`, `documents`, or
`table` only when the connected response node writes that lane: a mismatch
returns an empty result, which can look like a successful but unhelpful call.

---

## Notes

### Lane payloads

The input string the agent passes is written to **every** connected output lane, lanes
without a listener are skipped:

| Lane        | Payload sent downstream                              |
|-------------|------------------------------------------------------|
| `text`      | The raw input string                                 |
| `questions` | A `Question` object containing the input as a question |
| `documents` | A single `Doc` with the input as `page_content`      |
| `table`     | The raw input string                                 |
| `answers`   | An `Answer` object with the input as the answer      |

---

### Agent tool details

#### Pipeline


| Tool | Description |
|---|---|---|
| `run_pipe` | Run the connected pipeline with the given input and return its result. |


`run_pipe` takes one required parameter, `data` (string): the input to send to the
pipeline. An empty or missing `data` raises an error. The tool returns an object with a
single `result` string.

---

### Return value extraction

After the sub-pipeline completes, the node reads the response value named by
`return_type`:

- **`text`**: returned as a plain string.
- **`answers`**: the response is a list; the **first** answer is returned as a string.
- **`documents`** / **`table`**: list or dict values are JSON-serialised to a string for
  the agent.
- A missing value returns an empty string.

> **Gotcha:** if the sub-pipeline returns no data at all, the tool returns an empty
> `result`. Make sure each connected branch ends with a response node, and that the
> branch feeding the lane named by `return_type` actually produces a response.

## Upstream docs

- [RocketRide documentation](https://docs.rocketride.org)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_pipe.return_type` | `string` | **Return Type**<br/>Which response lane value to return to the agent | `"text"` |
| `tool_pipe.tool_description` | `string` | **Tool Description**<br/>Natural-language description the agent uses to decide when to call this tool | `""` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_pipe)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Pipedrive

Route: /nodes/tool_pipedrive

# tool_pipedrive

A RocketRide tool node that exposes a selected portion of the Pipedrive CRM to an agent. Pick it for typed CRM work such as deals, contacts, and activities; keep its tool groups narrow so an agent can choose reliably.

## About Pipedrive

Pipedrive is a customer relationship management product centered on sales pipelines, deals, contacts, and activities. Teams use it to organize sales work and report on pipeline progress.

## What it does

The node has no data lanes and publishes Pipedrive REST API functions as agent tools. It can expose the everyday CRM surface by default or additional specialized groups, with a generic API request function as an explicit option. It is preferable to a generic HTTP tool when the agent needs typed Pipedrive operations, response cleanup, pagination conventions, and read-only enforcement.

## As a tool

Tools are published as `pipedrive.<tool>`.

#### `activities` — 13 tools

| Tool | Description |
|---|---|
| `activity_create` | Create an activity (call, meeting, task, ...) and optionally link it to a deal, person or organization. |
| `activity_delete` | Delete an activity. |
| `activity_delete_bulk` | Delete multiple activities in one call. |
| `activity_field_list` | List the activity fields, including custom fields and their 40-character keys. |
| `activity_get` | Get a single activity by id. |
| `activity_list` | List activities, optionally filtered by owner, type, completion state or due-date range. |
| `activity_mark_done` | Mark an activity as done (or reopen it with done="0"). |
| `activity_type_create` | Create a custom activity type. |
| `activity_type_delete` | Delete an activity type. |
| `activity_type_delete_bulk` | Delete multiple activity types in one call. |
| `activity_type_list` | List the activity types configured in this Pipedrive account, with the key to pass as activity "type". |
| `activity_type_update` | Update an activity type. |
| `activity_update` | Update an activity. Pass done=1 to mark it complete. |

#### `call_logs` — 5 tools

| Tool | Description |
|---|---|
| `call_log_create` | Log a phone call. |
| `call_log_delete` | Delete a call log. |
| `call_log_get` | Get a single call log. |
| `call_log_list` | List the call logs of the authenticated user. |
| `call_log_recording_add` | Attach an audio recording to a call log. |

#### `deals` — 27 tools

| Tool | Description |
|---|---|
| `deal_activities_list` | List activities associated with a deal. |
| `deal_create` | Create a deal. |
| `deal_delete` | Delete a deal. Pipedrive keeps it recoverable for 30 days. |
| `deal_delete_bulk` | Delete multiple deals in one call. |
| `deal_duplicate` | Duplicate a deal. |
| `deal_files_list` | List files attached to a deal. |
| `deal_follower_add` | Add a follower to a deal. |
| `deal_follower_delete` | Remove a follower from a deal. |
| `deal_followers_list` | List followers of a deal. |
| `deal_get` | Get a single deal by id, including its custom fields. |
| `deal_list` | List deals, optionally filtered by owner, stage, status or a saved filter. |
| `deal_mail_messages_list` | List email messages associated with a deal. |
| `deal_merge` | Merge one deal into another. The source deal is removed. |
| `deal_participant_add` | Add a person as a participant of a deal. |
| `deal_participant_delete` | Remove a participant from a deal. |
| `deal_participants_list` | List participants (persons) of a deal. |
| `deal_permitted_users_list` | List users who have permission to see or edit a deal. |
| `deal_persons_list` | List persons linked to a deal, either directly or through its organization. |
| `deal_product_add` | Attach a product to a deal. |
| `deal_product_delete` | Detach a product from a deal. |
| `deal_product_update` | Update a product already attached to a deal. |
| `deal_products_list` | List products attached to a deal, with their quantities and prices. |
| `deal_search` | Search deals by title, notes or custom field values. |
| `deal_summary` | Get a summary of deals: total count and value, grouped by currency. |
| `deal_timeline` | Get deals grouped into time periods, with per-period totals. Useful for pipeline trend questions. |
| `deal_update` | Update a deal. Only the fields you pass are changed. |
| `deal_updates_list` | Get the update history (flow) of a deal: field changes, notes, activities and emails. |

#### `fields` — 6 tools

| Tool | Description |
|---|---|
| `field_create` | Create a custom field on deals, persons, organizations or products. |
| `field_delete` | Delete a custom field. The data stored in it is lost. |
| `field_delete_bulk` | Delete multiple custom fields in one call. |
| `field_get` | Get a single field definition, including its options for enum and set fields. |
| `field_list` | List the fields of deals, persons, organizations or products, including custom fields and the 40-character keys used to read and write them. |
| `field_update` | Update a custom field. Field type cannot be changed after creation. |

#### `files` — 8 tools

| Tool | Description |
|---|---|
| `file_create` | Upload a file and attach it to a deal, person, organization, product, activity or lead. |
| `file_create_remote` | Create a new empty remote document (Google Drive) and attach it to a record. |
| `file_delete` | Delete a file. |
| `file_download` | Download a file. Returns base64 content by default, or decoded text with as_text="1". |
| `file_get` | Get the metadata of a single file. |
| `file_link_remote` | Link an existing remote file (Google Drive) to a record. |
| `file_list` | List files stored in Pipedrive. |
| `file_update` | Rename a file or change its description. |

#### `filters` — 7 tools

| Tool | Description |
|---|---|
| `filter_create` | Create a saved filter. |
| `filter_delete` | Delete a saved filter. |
| `filter_delete_bulk` | Delete multiple saved filters in one call. |
| `filter_get` | Get a single filter, including its condition tree. |
| `filter_helpers_get` | Get the field ids, operators and value formats that filter conditions accept. Call this before building a filter. |
| `filter_list` | List saved filters. Pass a returned filter id as filter_id to the list tools to reuse a filter the user already built in the UI. |
| `filter_update` | Update a saved filter. |

#### `goals` — 5 tools

| Tool | Description |
|---|---|
| `goal_create` | Create a goal. |
| `goal_delete` | Delete a goal. |
| `goal_find` | Find goals by title, assignee, type or period. |
| `goal_results_get` | Get the progress of a goal over a period: how much of the target has been reached. |
| `goal_update` | Update a goal. |

#### `leads` — 12 tools

| Tool | Description |
|---|---|
| `lead_create` | Create a lead. Link it to a person or an organization (at least one is required). |
| `lead_delete` | Delete a lead. |
| `lead_get` | Get a single lead by its uuid. |
| `lead_label_create` | Create a lead label. |
| `lead_label_delete` | Delete a lead label. |
| `lead_label_list` | List the lead labels configured in this account, with the uuids to pass as label_ids. |
| `lead_label_update` | Update a lead label. |
| `lead_list` | List leads from the Leads Inbox. |
| `lead_permitted_users_list` | List users who have permission to see or edit a lead. |
| `lead_search` | Search leads by title, notes or custom field values. |
| `lead_source_list` | List the lead sources available in this account. |
| `lead_update` | Update a lead. Only the fields you pass are changed. |

#### `mailbox` — 6 tools

| Tool | Description |
|---|---|
| `mail_message_get` | Get a single mail message, optionally with its body. |
| `mail_thread_delete` | Delete a mail thread. |
| `mail_thread_get` | Get a single mail thread. |
| `mail_thread_list` | List mail threads in a mailbox folder. |
| `mail_thread_messages_list` | List the messages in a mail thread. |
| `mail_thread_update` | Link a mail thread to a deal or lead, or change its shared, read and archived flags. |

#### `misc` — 8 tools

| Tool | Description |
|---|---|
| `billing_addons_list` | List the billing add-ons the company has subscribed to. |
| `channel_conversation_delete` | Delete a conversation from a messaging channel. |
| `channel_create` | Register a messaging channel so an external inbox can appear in Pipedrive. |
| `channel_delete` | Delete a messaging channel. |
| `channel_message_receive` | Deliver an inbound message from an external messaging provider into a Pipedrive channel. |
| `currency_list` | List the currencies supported by the account, with their ids and decimal precision. |
| `meeting_link_create` | Link a Pipedrive user to a video-calling provider so meeting links can be generated. |
| `meeting_link_delete` | Remove the link between a Pipedrive user and a video-calling provider. |

#### `notes` — 11 tools

| Tool | Description |
|---|---|
| `note_comment_create` | Add a comment to a note. |
| `note_comment_delete` | Delete a comment from a note. |
| `note_comment_get` | Get a single comment on a note. |
| `note_comment_list` | List comments on a note. |
| `note_comment_update` | Update a comment on a note. |
| `note_create` | Create a note. Attach it by passing at least one of deal_id, person_id, org_id, lead_id or project_id. |
| `note_delete` | Delete a note. |
| `note_field_list` | List the note fields available in this account. |
| `note_get` | Get a single note by id. |
| `note_list` | List notes, optionally filtered by the record they are attached to or by date. |
| `note_update` | Update a note. |

#### `org_relationships` — 5 tools

| Tool | Description |
|---|---|
| `org_relationship_create` | Create a relationship between two organizations. |
| `org_relationship_delete` | Delete an organization relationship. |
| `org_relationship_get` | Get a single organization relationship. |
| `org_relationship_list` | List parent/child relationships of an organization. |
| `org_relationship_update` | Update an organization relationship. |

#### `organizations` — 18 tools

| Tool | Description |
|---|---|
| `organization_activities_list` | List activities associated with an organization. |
| `organization_create` | Create an organization. |
| `organization_deals_list` | List deals associated with an organization. |
| `organization_delete` | Delete an organization. |
| `organization_delete_bulk` | Delete multiple organizations in one call. |
| `organization_files_list` | List files attached to an organization. |
| `organization_follower_add` | Add a follower to an organization. |
| `organization_follower_delete` | Remove a follower from an organization. |
| `organization_followers_list` | List followers of an organization. |
| `organization_get` | Get a single organization by id, including its custom fields. |
| `organization_list` | List organizations (companies), optionally filtered by owner, saved filter or first letter. |
| `organization_mail_messages_list` | List email messages associated with an organization. |
| `organization_merge` | Merge one organization into another. The source organization is removed. |
| `organization_permitted_users_list` | List users who have permission to see or edit an organization. |
| `organization_persons_list` | List persons that belong to an organization. |
| `organization_search` | Search organizations by name, address, notes or custom field values. |
| `organization_update` | Update an organization. Only the fields you pass are changed. |
| `organization_updates_list` | Get the update history (flow) of an organization. |

#### `permission_sets` — 3 tools

| Tool | Description |
|---|---|
| `permission_set_assignments_list` | List the users assigned to a permission set. |
| `permission_set_get` | Get a single permission set. |
| `permission_set_list` | List the permission sets available in the account. |

#### `persons` — 18 tools

| Tool | Description |
|---|---|
| `person_activities_list` | List activities associated with a person. |
| `person_create` | Create a person (contact). |
| `person_deals_list` | List deals associated with a person. |
| `person_delete` | Delete a person. |
| `person_delete_bulk` | Delete multiple persons in one call. |
| `person_files_list` | List files attached to a person. |
| `person_follower_add` | Add a follower to a person. |
| `person_follower_delete` | Remove a follower from a person. |
| `person_followers_list` | List followers of a person. |
| `person_get` | Get a single person by id, including emails, phones and custom fields. |
| `person_list` | List persons (contacts), optionally filtered by owner, saved filter or first letter. |
| `person_mail_messages_list` | List email messages associated with a person. |
| `person_merge` | Merge one person into another. The source person is removed. |
| `person_permitted_users_list` | List users who have permission to see or edit a person. |
| `person_products_list` | List products associated with a person through their deals. |
| `person_search` | Search persons by name, email, phone, notes or custom field values. |
| `person_update` | Update a person. Only the fields you pass are changed; passing email or phone replaces the whole list. |
| `person_updates_list` | Get the update history (flow) of a person. |

#### `pipelines` — 8 tools

| Tool | Description |
|---|---|
| `pipeline_conversion_stats` | Get stage-to-stage conversion rates and win/lost rates for a pipeline over a date range. |
| `pipeline_create` | Create a pipeline. |
| `pipeline_deals_list` | List deals in a pipeline. |
| `pipeline_delete` | Delete a pipeline. |
| `pipeline_get` | Get a single pipeline, including per-stage deal totals. |
| `pipeline_list` | List all pipelines. Start here to find the pipeline_id and stage layout of the account. |
| `pipeline_movement_stats` | Get how deals moved into, through and out of each stage of a pipeline over a date range. |
| `pipeline_update` | Update a pipeline. |

#### `products` — 16 tools

| Tool | Description |
|---|---|
| `product_create` | Create a product in the catalogue. |
| `product_deals_list` | List deals a product is attached to. |
| `product_delete` | Delete a product from the catalogue. |
| `product_files_list` | List files attached to a product. |
| `product_follower_add` | Add a follower to a product. |
| `product_follower_delete` | Remove a follower from a product. |
| `product_followers_list` | List followers of a product. |
| `product_get` | Get a single product by id, including its prices. |
| `product_list` | List products from the catalogue. |
| `product_permitted_users_list` | List users who have permission to see or edit a product. |
| `product_search` | Search products by name, code or custom field values. |
| `product_update` | Update a product. |
| `product_variation_create` | Create a product variation. |
| `product_variation_delete` | Delete a product variation. |
| `product_variation_list` | List the variations of a product. |
| `product_variation_update` | Update a product variation. |

#### `projects` — 22 tools

| Tool | Description |
|---|---|
| `project_activities_list` | List the activities of a project. |
| `project_archive` | Archive a project. |
| `project_board_get` | Get a single project board. |
| `project_board_list` | List project boards. Board ids are needed to create a project. |
| `project_create` | Create a project. |
| `project_delete` | Delete a project. |
| `project_get` | Get a single project. |
| `project_groups_list` | List the groups of a project. |
| `project_list` | List projects. |
| `project_phase_get` | Get a single project phase. |
| `project_phase_list` | List the phases of a project board. Phase ids are needed to create a project. |
| `project_plan_activity_update` | Move an activity to another phase or group within a project plan. |
| `project_plan_get` | Get the plan of a project: its tasks and activities with their scheduled dates. |
| `project_plan_task_update` | Move a task to another phase or group within a project plan. |
| `project_task_create` | Create a project task. |
| `project_task_delete` | Delete a project task. |
| `project_task_get` | Get a single project task. |
| `project_task_list` | List project tasks. |
| `project_task_update` | Update a project task. Pass done=1 to complete it. |
| `project_template_get` | Get a single project template. |
| `project_template_list` | List project templates. |
| `project_update` | Update a project. |

#### `request` — 1 tools

| Tool | Description |
|---|---|
| `request` | Call any Pipedrive REST API v1 endpoint directly. Use this only for endpoints that have no dedicated tool here — the typed tools validate their inputs and return compact results, this one returns the raw API payload. Authentication, rate-limit retries and read-only enforcement still apply. See https://developers.pipedrive.com/docs/api/v1 for the endpoint reference. |

#### `roles` — 13 tools

| Tool | Description |
|---|---|
| `role_assignment_add` | Assign a user to a role. |
| `role_assignment_delete` | Remove a user from a role. |
| `role_assignments_list` | List the users assigned to a role. |
| `role_create` | Create a role. |
| `role_delete` | Delete a role. |
| `role_get` | Get a single role. |
| `role_list` | List the roles configured in the account. |
| `role_pipelines_list` | List which pipelines a role can see. |
| `role_pipelines_set` | Set which pipelines a role can see. |
| `role_setting_set` | Change one visibility setting of a role. |
| `role_settings_get` | Get the visibility settings of a role. |
| `role_sub_roles_list` | List the sub-roles of a role. |
| `role_update` | Update a role. |

#### `search` — 4 tools

| Tool | Description |
|---|---|
| `item_search` | Search across every Pipedrive item type at once — deals, persons, organizations, products, leads, files and projects. Use this when you do not know which record type holds the answer. |
| `item_search_by_field` | Search a single field for a value — for example find every deal whose custom "Contract number" field starts with a string. Returns distinct field values by default. |
| `lookup` | Quick global lookup that returns just the id, type and name of each match. Cheaper than item_search when you only need to resolve a name to an id. |
| `recents_list` | List every record created or changed since a timestamp. Use this to sync a CRM snapshot incrementally instead of re-listing everything. |

#### `stages` — 7 tools

| Tool | Description |
|---|---|
| `stage_create` | Create a stage in a pipeline. |
| `stage_deals_list` | List deals sitting in a stage. |
| `stage_delete` | Delete a stage. |
| `stage_delete_bulk` | Delete multiple stages in one call. |
| `stage_get` | Get a single stage. |
| `stage_list` | List stages, optionally restricted to a single pipeline. |
| `stage_update` | Update a stage. |

#### `subscriptions` — 9 tools

| Tool | Description |
|---|---|
| `subscription_delete` | Delete a subscription and detach it from its deal. |
| `subscription_find_by_deal` | Find the subscription attached to a deal. |
| `subscription_get` | Get a single revenue subscription. |
| `subscription_installment_create` | Create an installment subscription on a deal. |
| `subscription_installment_update` | Replace the payment schedule of an installment subscription. |
| `subscription_payments_list` | List the payments of a subscription. |
| `subscription_recurring_cancel` | Cancel a recurring subscription. |
| `subscription_recurring_create` | Create a recurring revenue subscription on a deal. |
| `subscription_recurring_update` | Update a recurring subscription from a given date onward. |

#### `teams` — 8 tools

| Tool | Description |
|---|---|
| `team_create` | Create a team. |
| `team_get` | Get a single team. |
| `team_list` | List all teams. |
| `team_list_for_user` | List the teams a user belongs to. |
| `team_update` | Update a team. |
| `team_user_add` | Add users to a team. |
| `team_user_delete` | Remove users from a team. |
| `team_users_list` | List the user ids that belong to a team. |

#### `users` — 12 tools

| Tool | Description |
|---|---|
| `user_connections_list` | List the third-party accounts (Google, Microsoft, ...) connected to the authenticated user. |
| `user_create` | Invite a new user to the Pipedrive account. |
| `user_find` | Find users by name or email. |
| `user_followers_list` | List the followers of a user. |
| `user_get` | Get a single user by id. |
| `user_list` | List all users in the Pipedrive account. Use this to resolve a user name to the user_id needed by owner filters. |
| `user_me` | Get the user the API token belongs to, including the company id, domain and default currency. |
| `user_permissions_get` | List the effective permissions of a user (what they can see, add, edit and delete). |
| `user_role_assignments_list` | List the role assignments of a user. |
| `user_role_settings_get` | Get the role settings that apply to a user. |
| `user_settings_get` | Get the authenticated user settings: timezone, currency, date format and feature flags. |
| `user_update` | Activate or deactivate a user. |

#### `webhooks` — 3 tools

| Tool | Description |
|---|---|
| `webhook_create` | Create a webhook subscription. |
| `webhook_delete` | Delete a webhook subscription. |
| `webhook_list` | List the webhooks registered by this API token. |

---



Only the selected Tool groups are registered. All functions return the Pipedrive result after the client unwraps its response envelope; API, authentication, or blocked write failures are returned as errors to the agent.

## Configuration

Begin with the default group selection: deals, persons, organizations, activities, pipelines, stages, notes, and search. It publishes the normal CRM surface without asking an LLM to reason across the whole API.

### Tool groups

The node has 255 typed functions across its groups. Select only the groups an agent needs; a function in an unselected group is not registered and cannot be invoked. Add specialized groups as the agent's responsibility grows, or select `all` only for a deliberate full-surface integration. The node warns when the selected groups publish more than 120 tools, but still runs; this warning is a signal to narrow the set when the agent begins choosing the wrong function.

### Read-only mode

Read-only is off by default. Turn it on for an inspection, reporting, or retrieval agent: create, update, delete, add, merge, set, and bulk-delete functions are blocked before a request is made, and the generic request function accepts only `GET` and `HEAD`. Leave it off only when the agent has an approved write responsibility.

### Allow raw API requests

The raw request switch is on by default and publishes `pipedrive.request`. Disable it when typed functions are the complete intended contract; leave it enabled when a controlled agent needs a Pipedrive v1 endpoint that is not modeled by a typed function. Raw requests use the same authentication, rate-limit handling, and read-only checks.

### Company Domain

Leave the domain blank to use the shared Pipedrive v1 API host. Set it to the company subdomain when the account requires requests at its own Pipedrive host; enter only the subdomain, not a full URL.

### Pagination and custom fields

List functions generally use `start` (offset) and `limit`; return values include a next offset when another page exists. Project functions use cursor pagination. Pipedrive custom-field keys are discovered with the field functions and can be supplied through an `extra` object on typed create and update calls; that object is merged after typed parameters, so use it only for deliberate API fields.

## Authentication

Set `apiToken` to a Pipedrive API token or OAuth access token. The client sends JWT-style, long, or values formatted as `Bearer <token>` using the Authorization header; it sends other values as the `api_token` query parameter. A missing token prevents startup.

## Notes

### Times are UTC, in both directions

Every field carrying a time of day, an activity's `due_date` and `due_time`, a
record's `add_time`, is UTC on the wire. Pipedrive displays those values in each
viewer's own timezone, and validates none of them, so a local wall-clock time sent
here is not rejected. It is stored, and from then on it reads as a real time.

A meeting asked for at 12:30 in California and written as `12:30` comes back to the
person who asked for it as 05:30.

Convert before writing and convert back before reporting. The hour moves the **date**
as well: 20:00 Pacific on a Wednesday is 03:00 UTC on the Thursday, so a converted
time beside an unconverted date is a booking on the wrong day. Take both from the
same rendering. The `tool_datetime` node returns `utc_date` and `utc_time` next to
`date` and `time` for exactly this.

Two things this does **not** apply to. A `duration` is a length, not an instant:
`02:00` is two hours in every timezone there is, and converting it corrupts it. A
pure date with no time, `expected_close_date` or a goal's period, names no instant,
so no zone can be wrong about it.

The `start_date` / `end_date` filters on `activity_list` and `note_list` compare
against those same UTC values, so a range that means one whole local day may need
widening by a day at each end.

### Rate limits

The client retries rate-limited responses up to three times, honoring `Retry-After` before the Pipedrive reset header. If the required wait would exceed the request timeout, the call fails with the wait time instead of blocking the pipeline.

## Upstream docs

- [Pipedrive API documentation](https://developers.pipedrive.com/docs/api/v1)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `pipedrive.allowRawRequest` | `boolean` | **Allow raw API requests**<br/>Publishes the generic <b>request</b> tool, which can call any Pipedrive v1 endpoint by method and path. It uses the same authentication, rate-limit handling and read-only enforcement as the typed tools. Disable to restrict the agent to the typed tools only. | `true` |
| `pipedrive.apiToken` | `string` | **API Token**<br/>Pipedrive API token (Settings -> Personal preferences -> API), or an OAuth access token. Tokens starting with a JWT-style prefix are sent as a Bearer header; everything else is sent as the api_token query parameter. | `""` |
| `pipedrive.companyDomain` | `string` | **Company Domain**<br/>Your Pipedrive company domain, i.e. the "acme" in https://acme.pipedrive.com. When set, requests go to https://{domain}.pipedrive.com/api/v1; otherwise https://api.pipedrive.com/api/v1 is used. | `""` |
| `pipedrive.readOnly` | `boolean` | **Read-only mode**<br/>When enabled, every create, update and delete tool is blocked, and the generic request tool only accepts GET. Safe for agents that should only inspect the CRM. | `false` |
| `pipedrive.toolGroups` | `array` | **Tool groups**<br/>Which groups of Pipedrive tools this node publishes to the agent. The full API is 255 tools, which is more than an LLM can choose between reliably, so only the selected groups are exposed. Pick one or more from the list; tool counts are shown per group, and selections totalling more than 120 log a warning but still run. Selecting <b>All groups</b> publishes everything and skips that warning. | `["deals","persons","organizations","activities","pipelines","stages","notes","search"]` |

## Dependencies

- `requests` `>=2.34.2`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_pipedrive)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Python

Route: /nodes/tool_python

# tool_python

A RocketRide tool node that lets an agent run small Python calculations or transformations when a built-in tool is not enough. Pick it for bounded code execution, not for integrations that need filesystem, network, or subprocess access.

## About RestrictedPython

RestrictedPython is a Python library for defining and enforcing a restricted execution environment. This node uses it to compile agent-supplied source with restricted guards and safe builtins.

## What it does

The node exposes one sandboxed execution tool and has no data lanes. It is suited to calculations, data reshaping, text processing, and other code that can run with the allowlisted imports; choose a purpose-built integration when the task needs an external system. The registered tool validates its input before passing it to the sandbox and returns the sandbox result rather than raising for an ordinary script error.

## As a tool

The server-name prefix defaults to `python`, so the registered function is `python.execute`.

| Function | Description |
|---|---|
| `python.execute` | Run Python source in the restricted sandbox. |

`code` is required and must be a non-empty string. Use `print()` for visible output and assign a JSON-compatible value to `result` to return it structurally. The response has `stdout`, `stderr`, `exit_code` (0 success, 1 exception, -1 timeout), `timed_out`, and `result`; blocked imports or invalid code are reported through that result.

## Configuration

Start with the default timeout and no additional modules. The server name is normally only changed to avoid a tool-name collision.

### Execution timeout (seconds)

The value is clamped to 1–1200 seconds; absent or invalid input uses the sandbox default. Raise it only for a computation that genuinely needs longer, because an agent call remains occupied until the sandbox returns or times out.

### Additional Allowed Modules

Each configured module name is added to the sandbox's import allowlist. Keep this list empty for the narrowest environment; add a module only when the agent needs it and you accept the capabilities that module exposes. The tool description tells the agent the effective allowed-import list, and every other import raises `ImportError`.

## Notes

### Sandbox boundary

The node uses RestrictedPython's restricted compiler and safe builtins. A tool call requires a JSON object; a missing, blank, or non-string `code` value raises a validation error before execution.

## Upstream docs

- [RestrictedPython documentation](https://restrictedpython.readthedocs.io/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_python.allowedModules` | `array` | **Additional Allowed Modules**<br/>Modules the agent is allowed to import, in addition to the built-in defaults (math, json, re, collections, datetime, etc.). |  |
| `tool_python.moduleName` | `string` | **Module name** | `""` |
| `tool_python.serverName` | `string` | **Server name**<br/>Namespace prefix for the tool: <serverName>.execute | `"python"` |
| `tool_python.timeout` | `integer` | **Execution timeout (seconds)**<br/>Maximum seconds a script may run before it is killed. Useful for long-running operations like network scans. Default is 20s, max is 1200s. | `20` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_python)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Slack

Route: /nodes/tool_slack

# tool_slack

A RocketRide tool node that lets an agent post to and inspect a Slack workspace. Pick it when an agent needs recent channel context or must notify a team; use a webhook-only setup for a deliberately post-only integration.

## About Slack

Slack is a work communication platform organized around channels and message threads. Teams use it for discussions, notifications, and integrations that report work into shared spaces.

## What it does

The node has no data lanes and exposes four Slack operations to an agent. Bot-token mode can test the connection, post messages, list public channels, and read channel history; incoming-webhook mode exposes posting only. This is a narrower, task-oriented surface than a generic HTTP client, with channel-name handling and Slack-specific failures.

## As a tool

The server-name prefix is `slack`, producing these registered functions.

| Function | Description |
|---|---|
| `slack.check_connection` | Verify the connection and return workspace and bot identity details. |
| `slack.message_post` | Post required `text` to a channel or thread. In webhook mode the webhook's channel is used. |
| `slack.channels_list` | List public channels. |
| `slack.channel_history` | Return recent messages for a required channel. |

`message_post` requires `text`; `channel` is required in bot-token mode and can be an ID or a name. `thread_ts` replies in a thread. `channels_list` accepts `limit`; `channel_history` accepts required `channel`, plus `limit`, `oldest`, and `latest`. Errors are raised as Slack-specific failures: invalid credentials, missing OAuth scope, rate limiting, bad requests, and server failures. In webhook mode the three inspection functions reject the call because they require a bot token.

`channel_history` returns `ts`, `user` and `text` per message, `thread_ts` for threaded
messages, `subtype` whenever Slack classifies the entry, and `bot_id` whenever a bot
posted it. Treat `subtype` as a classifier rather than a noise flag: `file_share`,
`thread_broadcast` and `me_message` are ordinary user messages, while `channel_join`,
`channel_leave`, `channel_topic`, `tombstone`, `pinned_item` and `reminder_add` are
system entries. That system list is open-ended, so drop entries by naming the subtypes
you do not want rather than by presence. To skip your own posts, compare `bot_id`
against the one `check_connection` reports — not the `bot_message` subtype, since an app
posting under its own bot identity produces a `bot_id` and no subtype at all.

## Configuration

Configure exactly one credential mode. A configured value wins over the corresponding environment fallback; configuring both token and webhook URL, or neither, prevents startup.

### Bot User OAuth Token

Use this mode when the agent needs channel discovery or history. The bot token supports posting with `chat:write`, listing public channels with `channels:read`, and history with `channels:history`; invite the bot to every channel it must read. Choose it rather than a webhook whenever the agent needs more than post-only behavior.

### Incoming Webhook URL

Use a webhook for a fixed-channel, post-only agent. `message_post` ignores its `channel` and `thread_ts` arguments in this mode, because Slack delivers to the webhook's configured channel. Do not pair it with a bot token.

## Authentication

Set either a bot OAuth token or an incoming-webhook URL. Both are secrets. Slack authentication and authorization errors reach the agent as typed failures; a missing scope error identifies the required scope.

## Notes

### Channel lookup

Channel arguments may be IDs such as `C0123ABCDEF` or names such as `#general`. If a name cannot be resolved, call `slack.channels_list` and retry with the returned ID.

## Upstream docs

- [Slack API documentation](https://api.slack.com/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `slack.token` | `string` | **Bot User OAuth Token**<br/>Slack bot token (starts with xoxb-) from your app's OAuth & Permissions page. Needs chat:write to post, channels:read to list channels, and channels:history to read history. Leave empty when using a webhook URL. | `""` |
| `slack.webhookUrl` | `string` | **Incoming Webhook URL**<br/>Slack incoming-webhook URL for zero-scope setups. Enables ONLY message_post, and messages always go to the channel the webhook was created for. Configure either this or a bot token, not both. | `""` |

## Dependencies

- `slack_sdk` `>=3.27.0,<4.0.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_slack)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Tavily

Route: /nodes/tool_tavily

# tool_tavily

A RocketRide tool node that gives an agent live web-search results from Tavily. Pick it when an agent needs current web pages in a compact search result, rather than a general HTTP request or a static knowledge source.

## About Tavily

Tavily provides search and research APIs intended for AI applications. Its search response combines result URLs, titles, snippets, and relevance information for programmatic use.

## What it does

The node has no data lanes and registers one real-time search function. It sends the configured defaults and any supported per-call overrides to the Tavily search endpoint, then returns structured result records. Use it for retrieval during an agent run; it is experimental, so callers should handle service errors rather than assuming a search always succeeds.

## As a tool

The prefix defaults to `tavily`, so the registered function is `tavily.tavily`.

| Function | Description |
|---|---|
| `tavily.tavily` | Search the web with a required natural-language `query`. |

Optional arguments are `max_results` (1–20), `search_depth` (`basic` or `advanced`), `topic` (`general`, `news`, or `finance`), `time_range` (`day`, `week`, `month`, or `year`), and `include_domains` / `exclude_domains`. A successful response includes `success`, the query, `num_results`, and `results`; a failed request returns `success: false` with an `error` string.

## Configuration

Set the API key, then use the defaults as a sensible baseline. Call-level arguments override the configured result count, depth, and topic when a specific question needs a different search.

### Max Results

The configured count must be 1–20 and defaults to 5. Increase it when the agent must compare multiple sources; keep it small for focused questions so the agent receives less irrelevant context.

### Search Depth and Topic

`advanced` is the default depth, while `basic` is available for a simpler search. The topic default is `general`; choose `news` or `finance` when that category better matches the request. These settings remain defaults only—per-call values take precedence.

## Authentication

Set `apikey` to a Tavily API key. An empty key prevents the node from performing a search.

## Upstream docs

- [Tavily API documentation](https://docs.tavily.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_tavily.apikey` | `string` | **API Key**<br/>Tavily API key (from https://tavily.com) | `""` |
| `tool_tavily.maxResults` | `integer` | **Max Results**<br/>Maximum number of search results to return (1-20) | `5` |
| `tool_tavily.searchDepth` | `string` | **Search Depth**<br/>Tavily search depth | `"advanced"` |
| `tool_tavily.topic` | `string` | **Topic**<br/>Search topic category | `"general"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_tavily)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# v0 by Vercel

Route: /nodes/tool_v0

# tool_v0

A RocketRide tool node that lets an agent generate and iterate on React UI components through Vercel's v0 API. Pick it for a UI-generation conversation with server-side chat continuity, rather than for editing an existing local codebase.

## About v0

v0 is Vercel's generative interface for creating web UI from natural-language instructions. It produces component files and a preview as part of a stateful generation conversation.

## What it does

The node has no data lanes and exposes a creation call plus a follow-up refinement call. A creation returns a chat ID, generated files, primary component code, and a preview URL; a refinement uses that same chat ID so prior context need not be submitted again. It is experimental, and transport, malformed-response, or API errors propagate as tool errors.

## As a tool

The prefix defaults to `v0`.

| Function | Description |
|---|---|
| `v0.generate_ui` | Generate UI from required natural-language `prompt`. |
| `v0.refine_ui` | Send required `prompt` and required `chat_id` to refine an earlier generation. |

Both functions return `success`, `chat_id`, primary `code`, all `files`, and `demo_url`. Keep the returned chat ID for later refinements. Missing or blank required arguments raise validation errors; an API error, non-JSON response, unexpected payload, or response with no files raises an error instead of returning a success payload.

## Configuration

The only configuration is the API key. The server name comes from the service prefix and does not need routine adjustment.

## Authentication

Set `apikey` to the Vercel v0 API key used in the Authorization Bearer header. Keep it secret; without it the node cannot call the API.

## Upstream docs

- [v0 documentation](https://v0.dev/docs)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_v0.apikey` | `string` | **API Key**<br/>Vercel v0 API key | `""` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_v0)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Vertex AI Vector Search

Route: /nodes/tool_vertex_search

# tool_vertex_search

A RocketRide tool node that looks up nearest neighbors in a Google Cloud Vertex AI Vector Search index. Pick it when an agent already has an embedding vector and needs the matching IDs out of an index that is deployed and managed in Vertex AI.

## About Vertex AI Vector Search

Vertex AI is Google Cloud's managed platform for machine-learning models and
the services around them. Vector Search, formerly called Matching Engine, is
its approximate-nearest-neighbor service: an index of embedding vectors is
built, then deployed onto an index endpoint that answers similarity queries at
low latency. Applications on Google Cloud use it as the retrieval layer behind
semantic search and recommendations.

## What it does

The node connects to one deployed Vertex AI Vector Search index when the pipeline starts and holds that endpoint open for the run. It has no data lanes and no invoke connections: its entire surface is a single nearest-neighbor lookup offered to a connected agent. Reach for it when the index already lives in Vertex AI and the pipeline only needs to query it.

It is a query-only tool, not a vector-store adapter. There is no way to add, upsert, or delete vectors through this node, and it does not embed text — the caller supplies the query vector, and indexing stays in Vertex AI.

## As a tool

The server-name prefix is `vertex`, producing this registered function.

| Function | Description |
| --- | --- |
| `search` | Return the nearest neighbors of a supplied embedding vector. |

`search` requires `query_vector`, an array of numbers holding the query embedding. `top_k` sets how many neighbors to request and falls back to `10` when it is omitted, zero, or not a number. `score_threshold` is optional and defaults to `0.0`.

A successful call returns a list of `{id, distance}` objects, one per neighbor, in the order Vertex AI returned them. Failures are not raised: a disconnected index endpoint or an error from the Vertex AI call comes back as a one-item list holding a single `error` key, so an agent should check for that key before treating the result as neighbors.

`score_threshold` is applied by the node after Vertex AI answers, and only when the value is greater than zero — a zero or negative threshold filters nothing. Neighbors whose `distance` is below the threshold are dropped, which assumes similarity semantics where a higher number is a better match, such as an index built with `DOT_PRODUCT_DISTANCE`. It is wrong for a distance metric such as `SQUARED_L2_DISTANCE`, where a lower number is the better match and thresholding this way discards the closest results. Because the filter runs locally on the `top_k` neighbors Vertex AI already returned, a threshold can return fewer than `top_k` results and never more.

## Configuration

Point the node at one deployed index: the region it lives in, the index endpoint, and the deployed index on that endpoint. Those three, plus the credential settings under Authentication, are the whole configuration — there is a single profile and nothing else to choose.

### Index Endpoint ID and Deployed Index ID

These two identify the exact index the tool queries, and both are required — startup fails with an explicit error when either is blank, and configuration validation warns about each one separately while you are still editing. The index endpoint is the deployed serving resource; the deployed index ID names one of the indexes deployed onto it, since an endpoint can carry several. Take both from the Vertex AI console rather than guessing: the deployed index ID is not the index's own resource ID.

### Location

The Google Cloud region holding the index endpoint, defaulting to `us-central1`. It must match the region the endpoint was created in — a valid endpoint ID looked up in the wrong region simply will not be found. Change it whenever the index lives elsewhere, for example `europe-west4`.

## Authentication

The node uses RocketRide's shared Google Cloud credential resolution and requests the `https://www.googleapis.com/auth/cloud-platform` scope.

**Authentication Type** selects between Application Default Credentials and Service Account JSON. Application Default Credentials is the default and suits an engine running on Google Cloud infrastructure with an attached service account, or any host where ADC has already been provisioned. Selecting Service Account JSON reveals **Service Account Key JSON**, an upload field for the key file; it is stored as a secret and is required in that mode.

**Project ID** is optional. Left blank, the project is taken from the uploaded key file or from the ambient default credentials; set it explicitly when the credentials could resolve to a different project than the one holding the index.

Grant the credential enough IAM to read the index endpoint and query the deployed index.

## Limitations

Declared `noremote`: this node runs on the local engine host only and is not available for remote execution. It needs network access to the Vertex AI API and, in Application Default Credentials mode, to whatever credential source the host provides.

## Notes

### Startup checks

Connecting builds the index endpoint handle with the resolved project, region, and credentials passed in directly; the node deliberately avoids `aiplatform.init()`, which would mutate process-global SDK state and affect other nodes in the same runtime. It then lists the endpoint's deployed indexes and fails startup when the configured deployed index ID is not among them, so a wrong ID surfaces at pipeline start instead of as empty search results later. In configuration-only open mode the node skips connecting entirely.

### Missing dependency

`google-cloud-aiplatform` is imported optionally, and its absence is reported as an explicit `ImportError` when the node starts rather than as a confusing failure on the first tool call.

## Upstream docs

- [Vertex AI Vector Search documentation](https://cloud.google.com/vertex-ai/docs/vector-search/overview)
- [google-cloud-aiplatform Python client](https://cloud.google.com/python/docs/reference/aiplatform/latest)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `vertex.deployedIndexId` | `string` | **Deployed Index ID**<br/>The ID of the deployed index. |  |
| `vertex.indexEndpointId` | `string` | **Index Endpoint ID**<br/>The ID of the Vector Search Index Endpoint. |  |
| `vertex.location` | `string` | **Location**<br/>The Google Cloud region, e.g. us-central1. | `"us-central1"` |
| `vertex.profile` | `string` |  | `"default"` |

## Dependencies

- `google-auth` `>=2.23.3`
- `google-cloud-aiplatform` `>=1.40.0`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_vertex_search)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# xTrace Memory

Route: /nodes/tool_xtrace_memory

# tool_xtrace_memory

A RocketRide tool node that gives an agent persistent, shared xTrace memory. Pick it when agents need cross-session context for a user or group, rather than the run-scoped memory used internally by an agent.

## About xTrace Memory

xTrace Memory is a service for storing conversation-derived memory and retrieving relevant context later. It is designed to let separate agents share an organization- or group-scoped memory pool.

## What it does

The node has no data lanes and exposes explicit store and recall operations. `remember` ingests conversation turns and returns the ingest-job state; `recall` searches the configured scope and can return a ready-to-inject context block. Unlike a run-scoped scratchpad, this store is not cleared when a session opens, so agents pointing at the same scope can use the same memories.

## As a tool

The prefix defaults to `xtrace`.

| Function | Description |
|---|---|
| `xtrace.remember` | Ingest conversation turns into shared persistent memory. |
| `xtrace.recall` | Search memory for context relevant to a required query. |

`remember` accepts either `messages` (preferred: objects with `role` and `content`) or one `content` value, plus optional `user_id` and `conv_id`. It returns `success`, `status`, `job_id`, `memories_created`, and `error`; missing content or user scope returns a failed result. `recall` accepts `query`, optional `user_id`, `group_ids`, `mode`, and `limit`, and returns `context`, ranked `results`, `count`, and `error`. A recall with no user, group, agent, or app scope returns an error instead of searching the entire organization.

## Configuration

Set the API key and organization ID first. The remaining defaults work for a basic per-user memory; use the advanced controls only when you need intentional sharing, a narrower scope, or different ingest and recall behavior.

### User id and Group ids (shared memory)

A configured user ID supplies the default owner for both tools. Group IDs are a comma-separated shared scope; use them only when memories should be visible across users or agents. A call can override these values, so keep the configured scope narrow when the same node serves different requests.

### Ingest behavior

Synchronous ingest is on by default, so `remember` waits for extraction to reach a terminal state or the configured 30-second timeout. Turn it off only when the caller can tolerate a pending job. Artifact extraction is off by default; enable it only when that extra extraction is necessary.

### Recall behavior

`compose` is the default recall mode and returns an injected-context block as well as ranked rows. Use `retrieve` when the caller needs only the ranked records. The recall limit defaults to 10 and is clamped from 1 to 100; increase it only when the agent can make use of the additional context.

### Agent and App scope

Optional agent and app IDs are attached at ingest and both narrow recall. Use them to partition one organization memory pool; both values participate in the recall scope.

## Authentication

Set `api_key` and `org_id`. Requests carry them in the `x-api-key` and `X-Org-Id` headers. Failed HTTP requests are returned to the tool as failed result objects; idempotent retrieval retries rate limits, server errors, and timeouts, while ingestion avoids ambiguous retries that could duplicate memory.

## Upstream docs

- [xTrace Memory documentation](https://docs.mem.xtrace.ai)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `xtrace_memory.agent_id` | `string` | **Agent id**<br/>Optional agent scope stamped on ingested memories and AND-narrowed on recall. | `""` |
| `xtrace_memory.api_key` | `string` | **API Key**<br/>xTrace API key (xtk_...). Get it from the <b>Developer Portal</b>: <a href='https://app.xtrace.ai' target='_blank'>app.xtrace.ai</a> → Settings → API Keys (not in mem.xtrace.ai). | `""` |
| `xtrace_memory.app_id` | `string` | **App id**<br/>Optional app scope stamped on ingested memories and AND-narrowed on recall. | `""` |
| `xtrace_memory.base_url` | `string` | **Base URL**<br/>xTrace Memory API base URL. Production by default; use https://api.staging.xtrace.ai for staging. | `"https://api.production.xtrace.ai"` |
| `xtrace_memory.extract_artifacts` | `boolean` | **Extract artifacts**<br/>Opt into artifact extraction (the most expensive stage). Facts and episodes are always extracted. Leave off unless you need it. | `false` |
| `xtrace_memory.group_ids` | `string` | **Group ids (shared memory)**<br/>Optional. Comma-separated group ids (grp_...) to share memory across users/agents. Leave empty for private memory. | `""` |
| `xtrace_memory.ingest_timeout` | `integer` | **Ingest timeout (s)**<br/>Max seconds to wait/poll for an ingest job to reach a terminal state. | `30` |
| `xtrace_memory.org_id` | `string` | **Org id**<br/>xTrace organization id (org_...). Same place as the API key: <a href='https://app.xtrace.ai' target='_blank'>app.xtrace.ai</a> → Settings → API Keys. | `""` |
| `xtrace_memory.search_limit` | `integer` | **Recall limit**<br/>Maximum number of memory rows to retrieve per recall. | `10` |
| `xtrace_memory.search_mode` | `string` | **Recall mode**<br/>'compose' returns a ready-to-inject markdown context block (LLM-selected); 'retrieve' returns ranked rows only. | `"compose"` |
| `xtrace_memory.show_advanced` | `boolean` | **Advanced settings**<br/>Show advanced options. The defaults work for most cases, leave off for a simple setup. | `false` |
| `xtrace_memory.user_id` | `string` | **User id**<br/>Who this memory belongs to (used to store and recall). Can be passed by the agent per call. | `""` |
| `xtrace_memory.wait` | `boolean` | **Synchronous ingest**<br/>When on, ingest waits (up to ~30s) for extraction to finish so the agent gets a terminal result. When off, ingest returns immediately and runs in the background. | `true` |

## Dependencies

- `requests`
- `tenacity`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_xtrace_memory)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# TwelveLabs

Route: /nodes/twelvelabs

# twelvelabs

A RocketRide video node that sends an incoming video to TwelveLabs and emits
the service's generated text response.

## About TwelveLabs

TwelveLabs is the video-analysis service that this node contacts. RocketRide
uses it to index a submitted video temporarily and request text generated from
that indexed video.

## What it does

The node receives `video` data, collects the stream, submits the resulting
temporary file for analysis, and writes the returned text to `text` when that
lane has a listener. Pick it when a pipeline needs a hosted analysis response
for a complete video, rather than local playback, transcription, or speech
generation. There is no agent-tool interface.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `video` | `text` | Submit the completed video stream and emit its generated text response. |

## Configuration

Set the API key and add instructions only when the default description prompt
is not enough. The node has one `default` profile, so profile selection itself
does not change its behavior.

### Instructions

The instruction strings are joined with newlines and sent as the analysis
prompt. Leave the list empty to use `Describe this video.`. Add instructions
when the response needs to answer a particular question or follow a particular
format; use separate entries for distinct constraints so they remain readable
in the configuration panel.

## Authentication

Set `apikey` to the API key accepted by the TwelveLabs client. The key and
instructions are loaded once when the pipeline starts and shared by the node's
instances.

## Notes

### Submission lifecycle and failures

Every stream is buffered in memory, written to a temporary file when it ends,
and analyzed through a new index named `rocketride-<random>`. The node polls
the indexing task every five seconds, fails if that task reports `failed`, and
raises `TwelveLabs task timed out` after 15 minutes. It attempts to delete both
the temporary index and the local temporary file even when processing fails;
an empty service response is emitted as `No data from TwelveLabs`.

### Input file suffix

The local temporary-file suffix follows the input MIME type for MP4, QuickTime,
AVI, WebM, Matroska, and MPEG video. Any other MIME type is written with an
`.mp4` suffix. This only determines the temporary filename; choose a MIME type
that accurately describes the input so the upload is not mislabeled.

## Upstream docs

- [TwelveLabs documentation](https://docs.twelvelabs.io)


<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `twelvelabs.apikey` | `string` | **API Key**<br/>TwelveLabs API key. |  |
| `twelvelabs.instructions` | `array` | **Instructions**<br/>Instructions to guide TwelveLabs when analyzing the video. |  |
| `twelvelabs.profile` | `string` |  | `"default"` |

## Dependencies

- `twelvelabs`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/twelvelabs)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Vectorizer

Route: /nodes/vectorizer

# vectorizer

An internal RocketRide ingestion filter that chunks flagged text and tables, creates embeddings through configured components, and persists the resulting documents to a configured store.

## What it does

The vectorizer runs only for objects marked with `FLAGS.VECTORIZE`. It passes
each non-empty text or table value through a configured preprocessor, embeds
the resulting chunks, and either writes them directly to the store or sends
them downstream for an endpoint store driver. Choose it for the internal
ingestion path that needs RocketRide's preprocessor, embedding, and store
components together; it is not a canvas-configured document parser or an agent
tool.

## Configuration

This node declares no fields or profiles of its own. Outside configuration-open
mode, it looks for optional multi-provider `preprocessor`, `embedding`, and
`store` sections in the connection configuration and initializes each present
component. Vectorization requires the processing path to supply the components
it uses: text is split with the preprocessor, chunks are encoded with the
embedding component, and they are persisted or rendered through the store.

## Notes

### Chunk metadata and modes

Chunk and table counters reset for every object. Each chunk carries its chunk
ID, whether it came from a table, its table ID, a false deletion flag, and the
object permission ID (or `-1` if absent). In instance mode, chunks are added
directly to the store and the object is marked vectorized on close. In transform
mode, chunks are written downstream as documents instead.

### Rendering

For an object whose `vectorBatchId` is non-zero, the node asks the store to
render the saved content into the text writer and prevents the default render
path. Objects that have not been marked vectorized are left to the default
renderer.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/vectorizer)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Video Composer

Route: /nodes/video_composer

# video_composer

A RocketRide video node that collects image frames and encodes them as an MP4 clip with FFmpeg. Place it after an image-producing filter when those frames should become a playable video rather than continue through an image lane.

## About FFmpeg

FFmpeg is the encoder this node invokes to turn an image pipe into an MP4 stream. The implementation sends input and receives output through pipes, so it does not create temporary video files.

## What it does

The node receives image frames, buffers them until the current object closes, then encodes the sequence as `video/mp4` and sends it down the video lane. It also sends the completed data to the UI in base64-encoded SSE chunks. Use it after image filters or frame-generation steps; use a video-analysis node instead when the goal is to inspect an existing video rather than compose one.

## Lanes

| Lane in | Lane out | Description |
| ------- | -------- | ----------- |
| `image` | `video` | MP4 video encoded from the accumulated input frames. |

## Profiles

Default: **Standard quality (H.264, CRF 23)** (`standard`).

| Profile | Codec | Quality (CRF) | Frame rate |
| ------- | ----- | ------------- | ---------- |
| Standard quality (H.264, CRF 23) **(default)** | `libx264` | `23` | `1.0` fps |
| High quality (H.264, CRF 18) | `libx264` | `18` | `1.0` fps |

## Configuration

Choose the standard profile for the smaller default output or the high-quality profile when image detail matters more than file size. Then set playback rate and quality for the way the generated clip will be viewed; the configured codec is passed to FFmpeg as the video codec.

### Output frame rate (fps)

This value determines both the FFmpeg input framerate and the playback speed of the MP4. The profiles default to `1.0` fps. Set it to match the timing of the upstream frames: raise it for a faster playback sequence, or lower it when each frame should remain on screen longer. Encoding returns no video if the runtime value is not greater than zero and no more than `240` fps.

### Quality (CRF)

CRF is the H.264 constant-rate-factor setting, from `0` through `51`; lower values preserve more detail and produce larger files. The standard profile uses `23`, while the high-quality profile uses `18`. Lower it when artifacts in generated or processed frames are unacceptable, and raise it when output size matters more than visual fidelity. Out-of-range values cause encoding to return no video.

## Notes

### Frames, formats, and memory

Frames are buffered in memory until the input object closes, so peak memory grows roughly with frame count times frame size; the implementation notes that typical resolutions below 500 frames are its intended scale. Send one supported image MIME type per sequence: PNG, JPEG, WebP, BMP, and TIFF are mapped to FFmpeg input codecs, while an unknown type is treated as PNG. The encoder chooses that codec from the most recently received frame's MIME type.

### Encoding failures

An empty frame sequence produces no video. FFmpeg failures, a missing or non-executable FFmpeg binary, unsupported codecs, and an encode timeout all result in no lane output rather than a partial MP4. Successful output is written in 48 KiB AVI and SSE chunks, followed by a `video_complete` SSE event.

## Upstream docs

- [FFmpeg documentation](https://ffmpeg.org/documentation.html)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `composer.crf` | `number` | **Quality (CRF)**<br/>Constant Rate Factor for H.264. Lower = better quality, larger file. Range 0-51. | `23` |
| `composer.fps` | `number` | **Output frame rate (fps)**<br/>Playback speed of the output video. Should match the upstream frame rate. | `1` |
| `composer.profile` | `string` | **Output quality**<br/>Video encoding quality preset | `"standard"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/video_composer)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Webhook

Route: /nodes/webhook

# webhook

A RocketRide source-node directory offering raw HTTP intake, browser chat and upload interfaces, and a tool-only endpoint; choose the service that matches how a client should enter the pipeline.

## What it does

The directory provides four endpoint services that share a long-running, engine-provided web server: Webhook, Chat, Dropper, and Tools. Choose **Webhook** for programmatic HTTP intake, **Chat** for browser-submitted questions, **Dropper** for browser file uploads, or **Tools** when an application needs to call connected tools without adding an agent or data lane. Each service is a source, so it starts work rather than consuming a preceding pipeline lane.

## Connections

### Tools (`tools://`)

| Connection | Required | Description |
| --- | --- | --- |
| `tool` | no | Tool nodes hosted by this endpoint through the control-plane invoke channel. |

The Tools service has no data outputs. It keeps the endpoint alive so a client can reach the connected tools directly.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `_source` | `questions` | **Chat** emits each browser-submitted message as a question. |
| `_source` | `tags` | **Dropper** emits uploaded files as tagged data. |
| `_source` | — | **Tools** is an invoke host and emits no data lane. |
| `_source` | `tags` | **Webhook** can emit tagged input. |
| `_source` | `text` | **Webhook** can emit text input. |
| `_source` | `json` | **Webhook** can emit JSON input. |
| `_source` | `audio` | **Webhook** can emit audio input. |
| `_source` | `video` | **Webhook** can emit video input. |
| `_source` | `image` | **Webhook** can emit image input. |
| `_source` | `questions` | **Webhook** can emit question input. |

## Configuration

These services expose no node-specific settings beyond the standard source properties. Select the service whose interaction model fits the caller, then wire its declared output lane to the downstream node that handles that data type.

### Endpoint service

Use **Webhook** when another system can send an HTTP request, **Chat** when people should enter questions in a web UI, and **Dropper** when people should upload files in a web UI. Use **Tools** only to host invoke-connected tool nodes for direct client calls: it intentionally has neither a user-facing URL nor a data lane.

## Authentication

On startup, Webhook, Chat, and Dropper publish an interface URL plus a public authorization key and private token in the monitor information. The Chat and Dropper button URLs include the public authorization key as the `auth` query parameter; Tools does not publish a user-facing URL. Treat the private token as a secret and restrict access to monitor information that contains it.

## Notes

### Shared server lifecycle

The endpoint registers its target with the shared web server initialized by `ai.node` and waits until shutdown. It does not create a server itself. If that shared server is unavailable, startup raises an explanatory error; run these services through the RocketRide pipeline process that provides it. The published interface is reachable only where deployment networking, firewalls, and reverse proxies permit access.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

### Chat (`services.chat.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `Pipe.source.parameters` |  |  |  |

### Dropper (`services.dropper.json`)

| Field | Type | Description | Default |
|---|---|---|---|
| `Pipe.source.parameters` |  |  |  |

### Tools (`services.tools.json`)

_No configuration fields._

### Webhook (`services.webhook.json`)

_No configuration fields._

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/webhook)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->


---

# Chat

Route: /nodes/webhook/chat

---
title: Chat
date: 2026-04-09
sidebar_position: 1
---

<head>
  <title>Chat - RocketRide Documentation</title>
</head>

## What it does

Source node that serves a web-based chat interface. Users open the chat URL in a browser, type questions, and each submission flows through the pipeline as a `questions` lane. Results are returned in the chat window.

After the pipeline starts, the Project Log displays the chat URL and public authorization key.

**Lanes:**

| Lane in | Lane out    | Description                                               |
| ------- | ----------- | --------------------------------------------------------- |
| -       | `questions` | Each message submitted via the chat UI becomes a question |

## Configuration

None. The chat URL and authorization key are generated automatically when the pipeline starts.


---

# Drag & Drop

Route: /nodes/webhook/dropper

---
title: Drag & Drop
date: 2026-04-09
sidebar_position: 1
---

<head>
  <title>Drag & Drop - RocketRide Documentation</title>
</head>

## What it does

Source node that serves a web-based drag-and-drop file upload interface. Users open the URL in a browser and drop files onto the page; each upload is sent through the pipeline for processing. Results are displayed in the browser across JSON, text, table, and image tabs.

After the pipeline starts, the Project Log displays the dropper URL and public authorization key.

**Lanes:**

| Lane in | Lane out | Description                |
| ------- | -------- | -------------------------- |
| -       | `data`   | Each uploaded file as data |

## Configuration

None. The dropper URL and authorization key are generated automatically when the pipeline starts.


---

# Tools

Route: /nodes/webhook/tools

---
title: Tools
date: 2026-07-26
sidebar_position: 1
---

<head>
  <title>Tools - RocketRide Documentation</title>
</head>

## What it does

Source node that transfers no data: it exists to host tool nodes. Connect tools
to it through the tool invoke channel — exactly as tools connect to an agent —
and call them directly from a client with `client.tool()`. No agent, no LLM, no
data lanes.

Use it when a pipeline's whole purpose is exposing capabilities to an
application: file storage operations, vector store management, or third-party
integrations driven by your own code rather than by an LLM.

```json
{
	"source": "tools_1",
	"components": [
		{ "id": "tools_1", "provider": "tools", "config": {}, "input": [] },
		{
			"id": "toolfs_1",
			"provider": "tool_filesystem",
			"config": {},
			"input": [],
			"control": [{ "classType": "tool", "from": "tools_1" }]
		}
	]
}
```

```python
result = await client.use(pipeline=pipeline)
listing = await client.tool(
    token=result['token'],
    tool='list_directory',
    node_id='toolfs_1',
    input={'path': ''},
)
```

**Lanes:**

| Lane in | Lane out | Description                             |
| ------- | -------- | --------------------------------------- |
| -       | -        | No data lanes — pure tool-invoke host    |

## Configuration

None. The node holds the pipeline open until the task is terminated; connected
tool nodes handle `client.tool()` calls via the control plane.


---

# Webhook

Route: /nodes/webhook/webhook

---
title: Webhook
date: 2026-04-09
sidebar_position: 1
---

<head>
  <title>Webhook - RocketRide Documentation</title>
</head>

## What it does

Source node that exposes an HTTP POST endpoint. External tools, scripts, or services send files or data to the URL, triggering the pipeline to process the uploaded content.

After the pipeline starts, the Project Log displays the webhook URL and public authorization key.

**Lanes:**

| Lane in | Lane out                                  | Description                         |
| ------- | ----------------------------------------- | ----------------------------------- |
| -       | `data`, `text`, `audio`, `video`, `image` | Data received from the HTTP request |

## Configuration

None. The endpoint URL and authorization key are generated automatically when the pipeline starts.


---

# CLI Reference

Route: /connect/cli

---
title: CLI Reference
---

import { SiPython, SiTypescript } from 'react-icons/si';

# CLI Reference

The `rocketride` command-line tool starts pipelines, streams files through them,
and manages the engine's file store — the same operations the
[SDKs](/clients/typescript) expose, from a terminal. It ships with both the
[TypeScript](/clients/typescript) and [Python](/clients/python) clients, so
installing either package puts `rocketride` on your path.

> Driving the engine from an AI assistant instead of a terminal? The
> [MCP server](/connect/mcp/stdio) exposes the same pipeline operations as tools for
> Claude, Cursor, and other MCP clients.

> **Python vs TypeScript CLI:** Both packages ship a `rocketride` command with
> the same commands and flag names, with one exception: `otel` — the
> [OpenTelemetry bridge](/clients/python/otel-bridge) — ships with the Python
> package only. Output is plain, line-oriented text; continuous live monitoring
> is deliberately not part of the CLI (the platform's monitor apps own that
> job) — `otel` forwards the engine's monitor stream to your own observability
> backend rather than rendering it in a terminal.

## Install

Install either SDK to get `rocketride` on your path:

<div className="rr-card-grid">

<a className="rr-side-card" href="/clients/python">
  <span className="rr-side-card__head"><SiPython className="rr-card-icon" /><span className="rr-side-card__title">Python SDK</span></span>
  <span className="rr-side-card__body"><code>pip install rocketride</code> — installs the CLI alongside the Python client.</span>
</a>

<a className="rr-side-card" href="/clients/typescript">
  <span className="rr-side-card__head"><SiTypescript className="rr-card-icon" /><span className="rr-side-card__title">TypeScript SDK</span></span>
  <span className="rr-side-card__body"><code>npm install rocketride</code> — installs the CLI alongside the Node.js client.</span>
</a>

</div>

New to the CLI? [Run from the CLI](/quickstart/cli) walks from a fresh install
to a running pipeline in five steps; this page is the command reference.

## Connecting

Every command accepts connection options, which also read from the environment
so you can set them once:

| Option           | Env var                | Default               | Description                                                            |
| ---------------- | ---------------------- | --------------------- | ---------------------------------------------------------------------- |
| `--uri <uri>`    | `ROCKETRIDE_URI`       | Python: `https://api.rocketride.ai`; TypeScript: `http://localhost:5565` (normalized to `ws://` at connect time) | Engine endpoint (see [Cloud](/operate/cloud) / [Self-hosting](/operate/self-hosting)). |
| `--apikey <key>` | `ROCKETRIDE_APIKEY`    | -                     | API token for authentication.                                          |
| `--pipeline <path>` | `ROCKETRIDE_PIPELINE` | -                  | Default pipeline path for `start`/`upload`.                            |
| `--token <token>` | `ROCKETRIDE_TOKEN`    | -                     | Default task token for token-bearing commands.                         |

Against a [Cloud](/operate/cloud) endpoint use an `https://`/`wss://` URI so the
connection is encrypted.

## Commands

| Command  | What it does                                                               |
| -------- | -------------------------------------------------------------------------- |
| `start`  | Start a new pipeline from a `.pipe` file and print its task token.         |
| `upload` | Send files through a pipeline (by `--pipeline` or an existing task token). |
| `stop`   | Stop a running task.                                                       |
| `validate` | Validate `.pipe` files against the engine without executing them.        |
| `list`   | List all active tasks.                                                     |
| `otel`   | Export live pipeline traces and metrics to an OpenTelemetry collector. Python CLI only. |
| `store`  | File-store operations: `dir`, `type`, `write`, `rm`, `mkdir`, `stat`.     |

### start

Use `start` to run a pipeline. The command loads the pipeline, starts the
engine task, prints the task token, and exits; the task keeps running on the
engine.

```bash
rocketride start --pipeline ./rag.pipe

# Start with extra worker threads (useful for CPU-bound nodes)
rocketride start --pipeline ./rag.pipe --threads 8
```

Key flags:

| Flag | Description |
| --- | --- |
| `--pipeline <path>` | Path to the `.pipe` JSON file. |
| `--threads <n>` | Number of worker threads. Default 4. |
| `--token <token>` | Supply a custom task token for the new run (the server generates one if not provided). A pipeline file is still required; to find tasks that are already running, use `list`. |

### upload

Use `upload` when you need to push one or more files through a pipeline. The
command starts a new pipeline task (or reuses one via `--token`), uploads each
file, and streams results back.

```bash
rocketride upload --pipeline ./extract.pipe ./invoice.pdf

# Upload multiple files concurrently
rocketride upload --pipeline ./extract.pipe ./docs/*.pdf --max-concurrent 4

# Feed files into an already-running task
rocketride upload --token <task-token> ./report-q1.pdf ./report-q2.pdf
```

Key flags:

| Flag | Description |
| --- | --- |
| `--pipeline <path>` | Path to the `.pipe` file. Required unless `--token` is given. |
| `--token <token>` | Send files to an existing task instead of starting a new one. |
| `--max-concurrent <n>` | Maximum number of files to upload in parallel. Default 5. TypeScript CLI only. |

### stop

Use `stop` to terminate a running task. This sends a stop signal to the engine,
which cleanly shuts down the pipeline run.

```bash
rocketride stop --token <task-token>
```

The token is printed by `start` at the beginning of the run, and `list` shows
the token of every active task. Save it if you need to stop a long-running
pipeline later.

### validate

Use `validate` to check one or more `.pipe` files against the engine without
executing them — before deploying a pipeline, or as a CI gate on every pull
request. Glob patterns are expanded by the CLI itself, so wildcards behave the
same on Windows shells. Files must contain a JSON object — either the pipeline
config itself or the `{ "pipeline": { ... } }` wrapper that `.pipe` files use;
a file that cannot be read or parsed is reported as invalid.

The engine checks structure and component references only — duplicate ids,
unknown `input`/`control` lanes, dangling `from` references, a `source` that
names no component. Provider availability and lane compatibility are runtime
concerns and are not reported here.

```bash
# Validate a single pipeline
rocketride validate ./rag.pipe

# Validate every pipeline in a directory
rocketride validate ./pipelines/*.pipe

# Machine-readable report for CI
rocketride validate ./pipelines/*.pipe --json
```

Key flags:

| Flag | Description |
| --- | --- |
| `<files...>` | One or more `.pipe` files or glob patterns. |
| `--source <id>` | Override the source component ID used for validation. |
| `--json` | Print a machine-readable JSON report (`files` + `summary`) to stdout. |

Exit codes: `0` — all files valid; `1` — at least one file failed validation
(a file that cannot be read or parsed counts as invalid); `2` — usage error,
connection failure, or no file could be processed at all (no file received a
server validation verdict).

> Runs in CI too: the
> [validate-pipes GitHub Action](https://github.com/rocketride-org/rocketride-server/tree/develop/.github/actions/validate-pipes)
> starts an engine container and runs `rocketride validate` on your
> repository's `.pipe` files.

### list

Use `list` to display all active tasks for your account — handy when you have
multiple pipelines running and need to find a task token.

```bash
rocketride list
rocketride list --json
```

Key flags:

| Flag | Description |
| --- | --- |
| `--json` | Output results as JSON instead of human-readable text. |

### otel

Use `otel` to export live pipeline traces and metrics to any OpenTelemetry
collector over OTLP — Jaeger, Grafana Tempo, Datadog, Langfuse, LangSmith, or
anything else that speaks OTLP. The command is a pure consumer of the engine's
[monitor event stream](/connect/websocket/observability): it subscribes to all
tasks your API key owns and maps lifecycle, flow, and status events to OTel
spans and metrics. It runs until interrupted (Ctrl+C), closing open spans and
flushing exporters on shutdown.

```bash
# Requires the optional OpenTelemetry extra
pip install 'rocketride[otel]'

# Export to a local collector (default endpoint http://localhost:4318)
rocketride otel

# Export to a specific backend — pass auth via the env var so the secret
# stays out of shell history and process listings
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_VALUE}"
rocketride otel --endpoint https://cloud.langfuse.com/api/public/otel --no-metrics

# Include pipeline payload content in spans (excluded by default, 8 KB cap)
rocketride otel --include-content
```

Key flags:

| Flag | Description |
| --- | --- |
| `--endpoint <url>` | OTLP base URL; `/v1/traces` and `/v1/metrics` are appended automatically. Defaults to `OTEL_EXPORTER_OTLP_ENDPOINT`, honoring the signal-specific `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` variables when neither is set, else the exporter default (`http://localhost:4318` for http, `localhost:4317` for grpc). |
| `--protocol <http\|grpc>` | OTLP transport. Default `http` (http/protobuf); `grpc` needs the separate gRPC exporter package. |
| `--service-name <name>` | `service.name` resource attribute. Defaults to `OTEL_SERVICE_NAME` or `rocketride-engine`. |
| `--headers <k=v,k=v>` | Headers sent with every OTLP request. Prefer `OTEL_EXPORTER_OTLP_HEADERS` for secrets — command-line arguments are visible in shell history and `ps` output. |
| `--include-content` | Include pipeline payload content in spans, size-capped. By default no payload content is exported. |
| `--no-metrics` | Export traces only. |
| `--insecure` | Allow credential-bearing OTLP headers over cleartext transport to a non-loopback collector. Without it the bridge exits `2` rather than putting an `Authorization` / `x-api-key` value on the wire in the clear. Also settable with `ROCKETRIDE_OTEL_ALLOW_INSECURE=1`. |

Per-component flow spans appear only for runs started with a
`pipelineTraceLevel` (e.g. `client.use(..., pipelineTraceLevel='summary')`) —
the bridge cannot change the trace level of runs it did not start. Task
lifecycle spans and metrics are exported regardless.

> Available in the Python CLI only. Requires `pip install 'rocketride[otel]'`.
> The [OpenTelemetry bridge](/clients/python/otel-bridge) guide covers the span
> model, the exported attributes, and per-backend recipes; the
> [WebSocket Events](/connect/websocket/observability) page documents the
> underlying event stream.

### store

Use `store` to inspect or write files in the engine's built-in file store. This
is useful for debugging pipeline outputs or seeding input data.

```bash
# List the root of the file store
rocketride store dir /

# List a subdirectory
rocketride store dir /pipeline-outputs

# Print the contents of a file
rocketride store type /pipeline-outputs/result.json

# Write a local file into the store
rocketride store write /pipeline-inputs/source.txt --file ./local-source.txt

# Write inline content without a local file
rocketride store write /pipeline-inputs/prompt.txt --content "Summarize this document"

# Delete a file from the store
rocketride store rm /pipeline-outputs/old-result.json

# Create a directory in the store
rocketride store mkdir /pipeline-outputs/archive

# Print metadata for a file or directory
rocketride store stat /pipeline-outputs/result.json
```

Sub-commands:

| Sub-command | Description |
| --- | --- |
| `dir <path>` | List directory contents at `<path>`. |
| `type <path>` | Print the contents of the file at `<path>`. |
| `write <path> --file <local>` | Upload `<local>` to the store at `<path>`. |
| `write <path> --content <text>` | Write inline text to the store at `<path>`. |
| `rm <path>` | Delete a file from the store. |
| `mkdir <path>` | Create a directory in the store. |
| `stat <path>` | Print metadata (size, type, modified time) for `<path>`. |

## Related

- [Run from the CLI](/quickstart/cli): the five-step tutorial.
- [TypeScript SDK](/clients/typescript) · [Python SDK](/clients/python): the
  same operations, in code.
- [MCP server](/connect/mcp/stdio): the same operations, as AI-assistant tools.
- [WebSocket protocol](/connect/websocket): what the CLI sends to the engine.
- [Cloud](/operate/cloud) · [Self-hosting](/operate/self-hosting): where the engine runs.


---

# HTTP MCP Server

Route: /connect/mcp/http

---
title: HTTP MCP Server
sidebar_position: 0
sidebar_label: Overview
---

import { LuPlug, LuWrench, LuLayoutGrid, LuServer } from 'react-icons/lu';

# HTTP MCP Server

The RocketRide engine has a built-in MCP server — nothing to install, nothing to
run. Connect an AI assistant to it and the assistant can **build, validate, run,
and observe** RocketRide pipelines, manage deployments, and read your account
file store.

## Endpoint

```text
https://api.rocketride.ai/mcp
```

Self-hosted engines serve the same endpoint automatically at
`http://<host>:5565/mcp` as soon as the engine is up (see
[Self-hosting](/connect/mcp/http/self-hosting)).

## Authentication

Clients like Claude and ChatGPT authenticate with OAuth — the first connection
triggers an interactive login, and users without a RocketRide account can sign
up from the same screen. Header-capable clients (Cursor, scripts, CLIs) can
instead send a RocketRide API key: `Authorization: Bearer rr_...`.

Task-scoped keys (`tk_`/`pk_`) are never accepted on this endpoint. Setup steps
for each client are on [Connect a client](/connect/mcp/http/connect).

## What you can do

The server exposes 29 tools, organized by capability — the full parameter-level
reference is on [Tools](/connect/mcp/http/tools):

| Capability | Tools |
| --- | --- |
| [Discover components](/connect/mcp/http/tools#discover-components) | `list_components`, `describe_component`, `resolve_config`, `list_integrations` |
| [Author pipelines](/connect/mcp/http/tools#author-pipelines) | `validate_pipeline`, `describe_pipeline`, `scaffold_node`, `save_template`, `load_template` |
| [Run pipelines](/connect/mcp/http/tools#run-pipelines) | `run_pipeline`, `run_dropper_pipe`, `send_data`, `send_files`, `terminate` |
| [Watch what's running](/connect/mcp/http/tools#watch-whats-running) | `monitor`, `list_running_pipelines` |
| [Read the file store](/connect/mcp/http/tools#read-the-file-store) | `store_read`, `store_list`, `store_stat`, `store_get_url` |
| [Manage deployments](/connect/mcp/http/tools#manage-deployments) | `deploy_add`, `deploy_list`, `deploy_status`, `deploy_remove`, `deploy_update` |
| [Replay past runs](/connect/mcp/http/tools#replay-past-runs) | `log_chapters`, `log_read`, `log_traces`, `log_trace` |

Two things to know when working with the tools:

- **Pipelines travel inline.** No tool accepts a pipeline filepath — a client
  that has a `.pipe` file reads it itself and sends the JSON.
- **Files come in over a separate channel.** `run_dropper_pipe` returns an
  `upload_url` for programmatic uploads and a `dropper_url` — a browser page
  where a person can drag and drop files into the running pipeline.

## Example prompts

> Build and run a pipeline that summarizes the PDFs I upload.

> Which components can I use right now without setting up any credentials?

> Show me what happened in my last run — where did the second document fail?

> Deploy this pipeline to run every night at 2am.

## Security model

- **Inline-only pipelines** — no tool accepts a server-local pipeline path, so
  a caller can never make the engine read pipeline definitions off its own
  disk.
- **Store-scoped reads** — the four `store_*` tools resolve paths through your
  account's file store on the engine, nothing else. (`send_files` is the one
  exception: its paths resolve on the machine the engine runs on — see its
  [reference entry](/connect/mcp/http/tools#send_files).)
- **Credential names, never values** — integration-readiness tools report which
  environment variables are configured; the values never transit MCP.
- **Audience-enforced OAuth** — tokens must be minted for this resource;
  task-scoped keys and PKCE codes are rejected outright.
- **Per-caller identity** — every request acts as the account behind the
  presented credential; tools see that caller's own store, deployments, and
  environment.

## Explore

<div className="rr-card-grid">

<a className="rr-side-card" href="/connect/mcp/http/connect">
  <span className="rr-side-card__head"><LuPlug className="rr-card-icon" /><span className="rr-side-card__title">Connect a client</span></span>
  <span className="rr-side-card__body">Setup for Claude, Claude Code, Cursor, and VS Code; OAuth and API-key auth; transport details.</span>
</a>

<a className="rr-side-card" href="/connect/mcp/http/tools">
  <span className="rr-side-card__head"><LuWrench className="rr-card-icon" /><span className="rr-side-card__title">Tools</span></span>
  <span className="rr-side-card__body">All 29 tools with parameters, return shapes, and the error contract.</span>
</a>

<a className="rr-side-card" href="/connect/mcp/http/resources-and-widgets">
  <span className="rr-side-card__head"><LuLayoutGrid className="rr-card-icon" /><span className="rr-side-card__title">Resources &amp; Widgets</span></span>
  <span className="rr-side-card__body">Live MCP resources and the interactive widgets rendered in MCP Apps hosts.</span>
</a>

<a className="rr-side-card" href="/connect/mcp/http/self-hosting">
  <span className="rr-side-card__head"><LuServer className="rr-card-icon" /><span className="rr-side-card__title">Self-hosting</span></span>
  <span className="rr-side-card__body">OAuth configuration, environment variables, and the dev-mode auth bypass.</span>
</a>

</div>

Looking for the stdio PyPI package (`rocketride-mcp`) that exposes *running
pipelines* as tools instead? That's the
[stdio MCP server](/connect/mcp/stdio).


---

# Connect a Client

Route: /connect/mcp/http/connect

---
title: Connect a Client
sidebar_position: 1
---

# Connect a Client

The endpoint is the same for every client:

```text
https://api.rocketride.ai/mcp
```

(Self-hosted: `http://<host>:5565/mcp` — see
[Self-hosting](/connect/mcp/http/self-hosting).)

## Setup

### Claude

On claude.ai or Claude Desktop, go to **Settings → Connectors → Add custom
connector** and enter the endpoint URL. Complete the OAuth flow on first use.

### Claude Code

```bash
claude mcp add --transport http rocketride https://api.rocketride.ai/mcp
```

### Cursor

Add to `.cursor/mcp.json` in your workspace:

```json
{
	"mcpServers": {
		"rocketride": {
			"url": "https://api.rocketride.ai/mcp",
			"headers": { "Authorization": "Bearer rr_..." }
		}
	}
}
```

### VS Code

Command Palette → **MCP: Add Server** → **HTTP** → enter the endpoint URL.

### Other clients

Any Streamable-HTTP MCP client works — current and older MCP protocol revisions
are negotiated on the same endpoint, so no version configuration is needed.

## Authentication

Two credential shapes are accepted; everything else is rejected at the `/mcp`
boundary:

| Credential | Who uses it | How |
| --- | --- | --- |
| **OAuth access token** | Claude, ChatGPT, and other OAuth-only clients | Automatic: the client discovers the login flow from the endpoint itself (below) |
| **RocketRide API key** (`rr_...`) | Cursor, scripts, CLIs — anything that can set a header | `Authorization: Bearer rr_...` |

Task-scoped keys (`tk_`/`pk_`) and PKCE exchange codes (`cd_`) are refused
outright — they scope a single task, not an account, and never grant access to
`/mcp`.

### How the OAuth flow bootstraps

OAuth clients need no pre-configuration beyond the URL:

1. The client `POST`s to `/mcp` with no credentials and receives a `401` whose
   `WWW-Authenticate` header names the resource-metadata URL.
2. `GET` that URL → the RFC 9728 document, which names the authorization
   server (`https://auth.rocketride.ai`).
3. The client fetches the authorization server's RFC 8414 metadata and runs a
   standard authorization-code + PKCE login.
4. It calls `/mcp` again with `Authorization: Bearer <access_token>`.

Users without a RocketRide account can sign up from the login screen and
continue through the same flow. Dynamic client registration is deliberately
disabled; client ids are issued — [contact us](https://discord.gg/PMXrtenMsY)
to register a client.

Every request acts as the account behind the presented credential: tools see
that caller's own file store, deployments, environment variables, and run logs.

## Transport details

- **Streamable HTTP, stateless.** Each POST is independent — there is no
  `Mcp-Session-Id`, so load balancers need no sticky sessions.
- **Responses may stream.** Replies arrive as SSE frames inside the POST
  response; clients must accept both `application/json` and
  `text/event-stream` (every compliant Streamable-HTTP client does).
- **Not served:** the legacy HTTP+SSE transport (no separate `/sse` endpoint)
  and WebSocket upgrades on `/mcp` (refused with close code 1008). There is no
  event replay (`Last-Event-ID`) — the server keeps no session state to replay.
- **No rate limiting** is applied at the MCP layer.

## FAQ

**I get a 401 — is something broken?**
No — that is the discovery flow. A compliant client follows the
`WWW-Authenticate` header on the 401 to the OAuth metadata and starts the
login. If your client cannot do OAuth, use an API key header instead.

**Where do I get an OAuth client id?**
Dynamic client registration is deliberately disabled; client ids are issued.
[Contact us](https://discord.gg/PMXrtenMsY) to register a client.


---

# Resources & Widgets

Route: /connect/mcp/http/resources-and-widgets

---
title: Resources & Widgets
sidebar_position: 3
---

# Resources & Widgets

Beyond the [tools](/connect/mcp/http/tools), the server exposes two read-only
MCP resources for live engine state, and renders some tool results as
interactive widgets in hosts that support MCP Apps.

## Resources

| URI | Contents | Freshness |
| --- | --- | --- |
| `rocketride://status` | Connection state and currently running tasks: `{"connected": true, "pipeline_count": N, "pipelines": ["name", ...]}` | Live, never cached |
| `rocketride://pipelines` | Your registered deployments — the same deployment objects `deploy_list` returns, as a bare JSON array without the tool's `ok`/`count` envelope | Cached up to 30 s |

In a resource-aware host the two appear in the resource picker automatically;
programmatic clients read them with a standard `resources/read` request.

A host listing resources will also see up to three `ui://rocketride/*.html`
entries — those are the widget bundles below, published as resources per the
MCP Apps spec, not data to read directly.

## No prompts

The server deliberately exposes **no MCP prompt templates**. Task knowledge
ships as agent skills instead (see
[Agents & Tools](/concepts/agents-tools-skills)), so the prompt surface stays
empty rather than duplicating them.

## Widgets

In hosts that support MCP Apps, three tool results render as interactive
widgets. Hosts without MCP Apps see the same results as plain JSON — the
widget is a rendering hint, never a different payload.

| Widget | Rendered for | What it does |
| --- | --- | --- |
| Pipelines table | `list_running_pipelines` | Live table of running pipelines with refresh and terminate actions |
| File dropper | `run_dropper_pipe` | In-chat drag-and-drop upload into the running pipeline, with progress |
| Trace viewer | `log_traces`, `log_trace` | Replay a run object-by-object: components entered, lane data, narration |

**Self-hosters:** the widget bundles are built with `./builder
mcp-widgets:build`; until they exist on disk the server simply advertises no
MCP Apps capability and every host gets the JSON results.


---

# Self-hosting

Route: /connect/mcp/http/self-hosting

---
title: Self-hosting
sidebar_position: 4
---

# Self-hosting

Every RocketRide engine serves the MCP endpoint automatically — there is
nothing extra to install or start:

```text
http://<host>:5565/mcp
```

The engine binds `localhost` by default, so the endpoint is only reachable
from the machine itself until you configure a wider bind host. The moment you
do, OAuth requires `MCP_EXPECTED_AUDIENCE` (below); API-key auth
(`Authorization: Bearer rr_...`) works in every configuration.

## Configuration

| Variable | Default | Meaning |
| --- | --- | --- |
| `MCP_RESOURCE_IDENTIFIER` | `https://api.rocketride.ai/mcp` | Public URL of your `/mcp` endpoint (the OAuth resource identifier). Must match the deployed URL exactly. |
| `MCP_AUTHORIZATION_SERVER` | `https://auth.rocketride.ai` | OAuth authorization server advertised in discovery metadata. |
| `MCP_EXPECTED_AUDIENCE` | _(unset)_ | Audience OAuth tokens must carry — for the default Zitadel setup this is a **project id**, not a URL. When unset, OAuth tokens are accepted only on loopback binds. |
| `MCP_JWKS_URL` | `<issuer>/oauth/v2/keys` | Where token signing keys are fetched from. |

Two related guards to know about:

- On a non-loopback bind with `MCP_EXPECTED_AUDIENCE` unset, **all** OAuth
  tokens are refused with an explicit error — a deploy that forgets the
  audience fails loudly instead of accepting every token.
- Once an audience is configured, opaque (non-JWT) OAuth tokens are refused
  too, so a misconfigured identity provider cannot silently bypass the
  audience check.

### Local development

`MCP_DEV_NO_AUTH=1` (or the engine config key `mcp_dev_no_auth`) disables
authentication on `/mcp` — honored only when the engine binds a loopback host
(`localhost`, `127.0.0.1`, `::1`); on any other bind the bypass is ignored
and auth stays on.

### OAuth discovery document

The discovery document at `/.well-known/oauth-protected-resource/mcp` is
served publicly by design — it is how an unauthenticated client learns where
to authenticate. Publishing it does not open `/mcp` itself. (Its path is
derived from `MCP_RESOURCE_IDENTIFIER`; if you set a resource identifier with
no `/mcp` path, the document moves to `/.well-known/oauth-protected-resource`
accordingly.)

## Security notes for operators

- **Inline-only pipelines** — no tool accepts a server-local pipeline path, so
  an authenticated caller cannot make the engine read pipeline definitions off
  its host filesystem.
- **`send_files` reads the engine host's disk.** Unlike the `store_*` tools
  (which are scoped to the caller's account file store), `send_files` resolves
  its paths on the machine the engine runs on. Treat access to this tool as
  read access to files the engine process can open — see its
  [reference entry](/connect/mcp/http/tools#send_files).
- **Credential names, never values** — integration-readiness tools report
  which environment variables are configured; the values never transit MCP.
- **No rate limiting** is applied at the MCP layer; put the endpoint behind
  your own gateway if you need throttling.
- **Stateless transport** — no sessions and no sticky-session requirement, so
  the endpoint load-balances freely.

## FAQ

**My self-hosted server refuses OAuth tokens.**
On a non-loopback bind, OAuth tokens are refused until
`MCP_EXPECTED_AUDIENCE` is set — a deploy that forgets it fails loudly instead
of accepting every token. API-key auth is unaffected.

**Do widgets work on my server?**
Only after the widget bundles are built (`./builder mcp-widgets:build`) — see
[Resources & Widgets](/connect/mcp/http/resources-and-widgets#widgets).


---

# Tools

Route: /connect/mcp/http/tools

---
title: Tools
sidebar_position: 2
---

# Tools

The server exposes **29 tools**. This page is the full reference; the
[overview](/connect/mcp/http/) has the one-table summary.

## How every tool behaves

- **One result, two encodings.** Every tool returns a JSON object, serialized
  once and delivered both as the text content and as `structuredContent` — they
  can never diverge.
- **`ok` is the contract.** Success payloads carry `ok: true`. Recoverable
  failures come back in-band as
  `{ok: false, error_type, message, hint}` with the MCP `isError` flag set:
  `BadRequest` (bad or missing arguments), `Timeout` (one engine call ran past
  its budget — the hint says how to recover), `NotFound`/`TraceExpired` (log
  tools), `UnknownTool`. Hard failures (lost engine connection, auth) surface
  as MCP protocol errors with the original message preserved.
- **Timeouts.** Read-side engine calls are budgeted at 30 seconds; the
  execution tools (`run_pipeline`, `run_dropper_pipe`, `send_data`,
  `send_files`, `terminate`) get 120 seconds per engine call.
- **Per-caller identity.** Tools act as the account behind your credential —
  your store, your deployments, your environment variables, your run logs.
- **Pipelines are inline-only.** Every `pipeline` parameter takes the pipeline
  JSON itself (a `{"pipeline": {...}}` wrapper is auto-unwrapped). File paths
  are rejected — the client reads its own `.pipe` file and sends the contents.

## Discover components

### list_components

List the components ready to use right now: every engine service definition,
minus credentialed integrations that are not fully configured (call
[`list_integrations`](#list_integrations) to see those and how to finish their
setup).

- **Parameters:** none.
- **Returns:** `{ok, components: [{name, category, summary, wiring?}], note?}`.
  `wiring` (a config-path → `${ENV_VAR}` map) appears only for configured
  credentialed integrations; `note` appears when unconfigured integrations were
  omitted.

### describe_component

Return one component's full service definition — metadata, lanes, and config
schema — plus a credential-readiness block when the component is a credentialed
integration.

- **Parameters:** `name` (string, required) — a component name from
  `list_components`.
- **Returns:** the engine's whole service definition at top level, plus
  `ok: true` and, for integrations, `credentials: {status, missing, candidates,
  wiring | setup}`.

### resolve_config

Show what a component config resolves to at load — the engine applies profile
and default merging, so the `.pipe` rarely says what the node actually
receives.

- **Parameters:** `provider` (string, required) — a provider from
  `list_components`; `config` (object, optional) — the component's config
  block, omitted for pure defaults.
- **Returns:** the resolved config the node would receive, plus `ok: true`.
- **Notable:** keys the resolver discarded (for example a key written beside
  `profile` instead of inside it) are reported with a `hint` explaining where
  to move them — a silent drop a schema cannot express.

### list_integrations

Report credential setup status for integrations — the discovery counterpart to
`list_components`, which hides unready ones. Only integrations with a matching
node on the connected engine are listed.

- **Parameters:** `name` (string, optional) — request full field detail for one
  integration.
- **Returns (bare call):** `{ok, integrations: [{name, title, status,
  missing_count}], note}` with status one of `configured`, `available`
  (needs setup — no matching variables found), or `unconfirmed` (candidate
  variables found for you to confirm, or the variable read failed).
- **Returns (with `name`):** `{ok, name, title, fields, caller_variables,
  status, missing, candidates, wiring | setup}` — `setup` carries the
  suggested variable names, instructions to relay to the user, and a docs
  link.
- **Notable:** only environment-variable **names** are read and reported —
  values never transit MCP. Wiring values are emitted as `${VAR}` placeholder
  strings for use in a pipeline config.

## Author pipelines

### validate_pipeline

Validate an inline pipeline with the engine's own validator — the same rules
`use()` applies, so there is no client-side drift — plus one check the engine's
pipeline path does not cover: every component must name a provider the engine
has a service for.

- **Parameters:** `pipeline` (object, required).
- **Returns:** `{ok, errors: [], warnings: []}` — `ok` is true only when there
  are no errors.

### describe_pipeline

Statically parse an inline pipeline into its components, enriched with a
best-effort engine lookup per provider (title, category).

- **Parameters:** `pipeline` (object, required).
- **Returns:** `{ok, source, components: [{id, provider, title, classType,
  inputs}]}`.
- **Notable:** lookups share one 30-second budget; providers the engine cannot
  resolve fall back to the pipeline's own metadata instead of failing the
  parse.

### scaffold_node

Emit a local node skeleton that loads on the first try, with the manifest keys
and file layout the engine requires. It returns files to write — it writes
nothing itself.

- **Parameters:** `name` (string, required) — a lowercase Python identifier;
  `lane_in` (string, optional, default `text`); `lane_out` (string, optional,
  defaults to `lane_in`); `class_type` (string, optional, defaults to
  `lane_in`).
- **Returns:** `{ok, name, provider, files, next_steps}` — `files` maps
  `local_nodes/<name>/...` paths to file contents.
- **Notable:** lanes and `class_type` are validated against the connected
  engine's live catalog, so the allowed sets never drift from what is actually
  in service.

### save_template

Save an inline pipeline as a reusable template under an id (stored in your
account file store at `.templates/<id>.json`).

- **Parameters:** `template_id` (string, required); `pipeline` (object,
  required).
- **Returns:** `{ok, template_id}`.

### load_template

Load a previously saved pipeline template.

- **Parameters:** `template_id` (string, required).
- **Returns:** `{ok, template_id, pipeline}`.

## Run pipelines

The three start/send tools share these optional start parameters: `ttl`
(integer — task TTL in seconds, 0 = no timeout), `use_existing` (boolean —
reuse an already-running task), `source` (string — source label), `threads`
(integer), and `pipelineTraceLevel` (`none | metadata | summary | full`).
Runs default to `summary` tracing so the [replay tools](#replay-past-runs)
have content.

### run_pipeline

Start a pipeline from an inline definition, returning a `task_token`;
optionally send data in the same call and get the result back synchronously.

- **Parameters:** `pipeline` (object, required); `inputs` (string, optional —
  data to send immediately after start); plus the shared start parameters.
- **Returns:** `{ok, task_token, projectId, source, result?}` — `result` only
  when `inputs` was passed. Keep `projectId` and `source`: they key the
  [replay tools](#replay-past-runs).
- **Notable:** if the initial send times out, the error hint still reports the
  token so you can `monitor` the task instead of losing it.

### run_dropper_pipe

Start a pipeline and get two self-contained URLs for sending file bytes over a
separate HTTP channel (bytes cannot ride an MCP tool call).

- **Parameters:** `pipeline` (object, required); plus the shared start
  parameters (no `inputs`).
- **Returns:** `{ok, task_token, upload_url, dropper_url, projectId, source}`.
  `upload_url` accepts programmatic multipart POSTs; `dropper_url` is a
  browser page where a person can drag and drop files into the running
  pipeline.
- **Notable:** the URLs embed only the task's public key (`pk_`); the control
  token never appears in a URL. If the pipeline has no data-ingress source, the
  task is cleaned up and the call fails with a `BadRequest` instead of leaving
  an orphaned run. In MCP Apps hosts the result renders as the
  [file-dropper widget](/connect/mcp/http/resources-and-widgets#widgets).

### send_data

Send data to a running task and return its result.

- **Parameters:** `task_token` (string, required); `input` (string, required).
- **Returns:** `{ok, result}`.

### send_files

Upload files to a running task by token.

- **Parameters:** `task_token` (string, required); `files` (array of strings,
  at least one, required).
- **Returns:** `{ok, result}` — per-file upload results (status, timing,
  processing results).
- **Caution:** paths are resolved on the machine the engine runs on — **not**
  through your account file store. Against RocketRide Cloud this tool is only
  useful for files the engine host can already see; to get local files into a
  pipeline, use `run_dropper_pipe` and its `upload_url` instead.

### terminate

Terminate a running task by token — also the way to stop a runaway run.

- **Parameters:** `task_token` (string, required).
- **Returns:** `{ok, terminated}`.

## Watch what's running

### monitor

Poll a task until it reaches a terminal state or the timeout elapses, then
return a status snapshot. This is bounded polling, not an event stream — it
always returns within the timeout.

- **Parameters:** `task_token` (string, required); `timeout` (number, optional,
  default 30, clamped to 0–300 seconds); `interval` (number, optional, default
  1, minimum 0.25 seconds).
- **Returns:** `{ok, task_token, state, state_label, completed, terminal,
  status, counts: {completedCount, failedCount, totalCount}, errors, warnings,
  polls, poll_timed_out?}`.
- **Notable:** `state` is an integer enum (0 none, 1 starting,
  2 initializing, 3 running, 4 stopping, 5 completed, 6 cancelled);
  `state_label` is the readable form. Long-lived pipelines (webhook sources)
  legitimately sit at `running` forever — a timeout then returns the current
  snapshot with `terminal: false`, which is not an error.

### list_running_pipelines

List the running pipelines on the connected server.

- **Parameters:** none.
- **Returns:** `{ok, tasks, count}` — task tokens, names, and state, ready to
  feed `monitor`, `send_data`, or `terminate`. In MCP Apps hosts the result
  renders as the
  [pipelines-table widget](/connect/mcp/http/resources-and-widgets#widgets).

## Read the file store

All four tools resolve store-relative paths on the engine, scoped to your
account's file store.

### store_read

Read a text file from the store.

- **Parameters:** `path` (string, required).
- **Returns:** `{ok, path, content}`.

### store_list

List the entries under a store directory.

- **Parameters:** `path` (string, optional — defaults to the store root).
- **Returns:** `{ok, path, listing}`.

### store_stat

Get metadata for a store file or directory.

- **Parameters:** `path` (string, required).
- **Returns:** `{ok, path, stat}` — existence, type, size, modified time.

### store_get_url

Get a time-limited signed download URL for a store file — the out-of-band
counterpart to `store_read` for large or binary files.

- **Parameters:** `path` (string, required); `expires_in` (integer ≥ 1,
  optional, default 3600 seconds); `download_name` (string, optional —
  filename the browser saves as).
- **Returns:** `{ok, path, url, expires_in}`.

## Manage deployments

### deploy_add

Register an inline pipeline as a deployment, optionally on a cron schedule.

- **Parameters:** `pipeline` (object, required); `schedule` (string, optional
  cron expression).
- **Returns:** `{ok, deployment}`.
- **Notable:** creation is not idempotent — after a timeout, call
  `deploy_list` before retrying, since the deployment may already exist.

### deploy_list

List your deployments.

- **Parameters:** none.
- **Returns:** `{ok, deployments, count}`.

### deploy_status

Detailed status of one deployment.

- **Parameters:** `project_id` (string, required).
- **Returns:** `{ok, deployment}`.

### deploy_remove

Undeploy and remove a deployment.

- **Parameters:** `project_id` (string, required).
- **Returns:** `{ok, removed}`.

### deploy_update

Update a deployment's pipeline and/or schedule.

- **Parameters:** `project_id` (string, required); `pipeline` (object,
  optional); `schedule` (string, optional — a replacement cron expression or
  `"manual"`). At least one of `pipeline`/`schedule` is required.
- **Returns:** `{ok, project_id, updated}` — which of the two changed.

## Replay past runs

The run-log (DVR) tools are keyed by **`projectId` + `source`** — the values
`run_pipeline`/`run_dropper_pipe` return — never by task token, so they work
for runs that have already finished. All four accept `teamId` (string,
optional) to address a team's deploy continuum instead of your own dev stream.

Retention: runs are evicted after 7 days (dev) / 30 days (deploy), or earlier
under storage caps. Runs recorded with `pipelineTraceLevel: 'none'` still have
chapters and console output but empty traces.

### log_chapters

List the recorded runs (chapters) for a pipeline — begin/end times, outcome,
and each chapter's `beginSeq`. Works for past and live runs.

- **Parameters:** `projectId`, `source` (strings, required); `teamId`
  (string, optional).
- **Returns:** `{ok, chapters, horizonSeq}`.

### log_read

Read raw run-log events, cursor-paged.

- **Parameters:** the key parameters; `fromSeq` (integer, optional — sequence
  to start from); `cursor` (integer, optional — from a previous `nextCursor`);
  `maxEvents` (integer, optional, default and maximum 200); `types` (array of
  strings, optional — event-type filter, e.g. `["output"]` for console lines
  only).
- **Returns:** `{ok, events, nextCursor, truncatedAtSeq}`.
- **Notable:** pages are additionally capped at 1 MiB.

### log_traces

List per-object trace summaries — one per file or document that traveled the
pipeline — for the latest run or a specific past run.

- **Parameters:** the key parameters; `n` (integer, optional, default 20,
  clamped 1–100); `chapterBeginSeq` (integer, optional — address a specific
  past run by its chapter `beginSeq` from `log_chapters`).
- **Returns:** `{ok, traces, open, context, note?}` — `traces` are finished
  journeys, `open` are still in flight; each summary carries `beginSeq`, the
  permanent trace id. In MCP Apps hosts the result renders in the
  [trace-viewer widget](/connect/mcp/http/resources-and-widgets#widgets).

### log_trace

Fetch one object's full begin-to-end journey: every component enter/leave with
lane data, plus node narration.

- **Parameters:** the key parameters; `beginSeq` (integer, required — a trace
  id from `log_traces`).
- **Returns:** `{ok, beginSeq, summary, events, context}`.
- **Errors:** a trace below the retention horizon returns
  `{ok: false, error_type: 'TraceExpired', ...}`.


---

# RocketRide MCP Server

Route: /connect/mcp/stdio

# RocketRide MCP Server

<!-- This README is both a docs:export source and, unlike the other package
     READMEs, the site page itself for /connect/mcp/stdio, and gather never
     stages assets/, so a relative image link here would 404 on the
     published page. Keep this one banner absolute. -->
<p align="center">
  <img src="https://raw.githubusercontent.com/rocketride-org/rocketride-server/develop/docs/public/mcp/stdio/assets/banner-mcp.png" alt="RocketRide MCP Server" width="900" />
</p>

<p align="center">
  Let AI assistants run your RocketRide pipelines via the Model Context Protocol.
</p>

<p align="center">
  <a href="https://glama.ai/mcp/servers/rocketride-org/rocketride-server"><img src="https://glama.ai/mcp/servers/rocketride-org/rocketride-server/badges/score.svg" alt="Glama MCP Score" /></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/rocketride-mcp/"><img src="https://img.shields.io/pypi/v/rocketride-mcp?color=222223&label=PyPI" alt="PyPI" /></a>
  <a href="https://github.com/rocketride-org/rocketride-server"><img src="https://img.shields.io/github/stars/rocketride-org/rocketride-server?style=flat&color=238636&label=GitHub&logo=github&logoColor=white" alt="GitHub" /></a>
  <a href="https://discord.gg/PMXrtenMsY"><img src="https://img.shields.io/badge/Discord-Join-370b7a?logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="https://github.com/rocketride-org/rocketride-server/blob/develop/LICENSE"><img src="https://img.shields.io/badge/License-MIT-41b6e6" alt="MIT License" /></a>
</p>

> [!WARNING]
> **This package is deprecated.** The RocketRide engine now ships a built-in
> **HTTP MCP server** with a far larger tool surface — create, validate, run,
> and trace pipelines directly from your AI assistant. Use it instead:
>
> ```bash
> claude mcp add --transport http rocketride https://api.rocketride.ai/mcp
> ```
>
> Self-hosted engines serve the same endpoint automatically at
> `http://<host>:5565/mcp` — nothing extra to install. See the
> [HTTP MCP Server documentation](https://docs.rocketride.org/connect/mcp/http)
> for Claude, Cursor, and ChatGPT setup.
>
> `rocketride-mcp` 1.5.0 is the final release. It continues to work against
> existing engines, but receives no new features or fixes.

## Quick Start

```bash
pip install rocketride-mcp
```

Configure your MCP client to use the server (see examples below), then ask your AI assistant to process files through your running RocketRide pipelines.

## How It Works

The MCP server connects to a running RocketRide engine and dynamically exposes your pipelines as MCP tools. When an AI assistant calls a tool, the server sends the file to the corresponding pipeline and returns the result.

```text
AI Assistant (Claude, Cursor, ...)
        |
   MCP Protocol
        |
  rocketride-mcp server
        |
   WebSocket (DAP)
        |
  RocketRide Engine
        |
   Your Pipelines
```

Running pipelines are discovered automatically - start a pipeline in VS Code or via the SDK, and it appears as a callable tool in your AI assistant.

## What is RocketRide?

[RocketRide](https://rocketride.org) is an open-source, developer-native AI pipeline platform.
It lets you build, debug, and deploy production AI workflows without leaving your IDE --
using a visual drag-and-drop canvas or code-first with TypeScript and Python SDKs.

- **100+ ready-to-use nodes** - 15+ LLM providers, 9 vector databases, OCR, NER, PII anonymization, and more
- **High-performance C++ engine** - production-grade speed and reliability
- **Deploy anywhere** - locally, on-premises, or self-hosted with Docker
- **MIT licensed** - fully open-source, OSI-compliant

## How pipelines become tools

Every pipeline you start in RocketRide is automatically registered as an MCP
tool by the server — no extra configuration required.

When you start a pipeline (via the VS Code extension, the CLI, or an SDK), the
engine assigns it a **task token**. The MCP server discovers all running tasks
for your API key and exposes each one as a callable tool. The tool name is
derived from the pipeline name; the tool schema is derived from the pipeline's
input lanes.

```
You start a pipeline          →  engine assigns a task token
                                    ↓
rocketride-mcp discovers it   →  registers it as an MCP tool
                                    ↓
Claude calls the tool         →  MCP server forwards the request to the pipeline
                                    ↓
Pipeline processes it         →  result streamed back to Claude
```

Stop the pipeline and the tool disappears from the next tool-list refresh.
Start a new pipeline and it appears automatically.

## Worked example

**1. Start the MCP server** (if not already running via a client config):

```bash
export ROCKETRIDE_URI=ws://localhost:5565
export ROCKETRIDE_AUTH=your-api-key
rocketride-mcp
```

**2. Start a pipeline** — for example, a simple chat pipeline (`chat.pipe`):

```json
{
  "nodes": [
    { "id": "source_1", "provider": "webhook" },
    {
      "id": "llm_1", "provider": "llm_openai",
      "config": { "profile": "openai-4o-mini", "apikey": "${OPENAI_API_KEY}" },
      "input": [{ "lane": "questions", "from": "source_1" }]
    },
    { "id": "target_1", "provider": "response",
      "input": [{ "lane": "answers", "from": "llm_1" }] }
  ]
}
```

```bash
rocketride start ./chat.pipe
```

**3. Ask Claude to use it.** Open Claude Desktop (configured with the
`mcpServers` block above) and type:

> Use the RocketRide pipeline to answer: what is the boiling point of water?

Claude discovers the tool, calls it with the question, and returns the answer
streamed from your pipeline.

**4. Inspect resources** — Claude can also list your pipelines and check server
status using MCP resources:

> Show me the available RocketRide pipelines.

This reads `rocketride://pipelines` and returns the list of running tasks.

## Installation

```bash
pip install rocketride-mcp
```

Requires Python 3.10+ and `rocketride` >= 1.0.4.

## Client Configuration

### Claude Desktop

Add to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
	"mcpServers": {
		"rocketride": {
			"command": "rocketride-mcp",
			"env": {
				"ROCKETRIDE_URI": "ws://localhost:5565",
				"ROCKETRIDE_AUTH": "your-api-key"
			}
		}
	}
}
```

### Cursor

Add to `.cursor/mcp.json` in your workspace:

```json
{
	"mcpServers": {
		"rocketride": {
			"command": "rocketride-mcp",
			"env": {
				"ROCKETRIDE_URI": "ws://localhost:5565",
				"ROCKETRIDE_AUTH": "your-api-key"
			}
		}
	}
}
```

### Claude Code

```bash
claude mcp add rocketride -- rocketride-mcp
```

Set `ROCKETRIDE_URI` and `ROCKETRIDE_AUTH` in your environment before running.

### Command line

```bash
# Using the installed entry point
rocketride-mcp

# Or using Python module
python -m rocketride_mcp
```

## Available Tools

Tools are **discovered from the RocketRide server** (pipelines/tasks available to your account) plus a built-in convenience tool:

- **Server tasks** - Any pipelines or tasks returned by the server for your API key are exposed as MCP tools. Each tool accepts a `filepath` argument and sends that file's contents to the corresponding pipeline.
- **RocketRide_Document_Processor** - A convenience tool that runs the bundled document-parsing pipeline (`simpleparser.json`) without requiring a pre-started task. Supports multi-modal parsing (text, images, video, tables, audio).

All tools accept a single `filepath` parameter (path to the file to process). File paths support:

- Absolute and relative paths
- `file://` URIs (automatically decoded)
- `~` home directory expansion

### Response format

Tool results include both human-readable text and structured data:

- **Text content**: Confirmation message plus extracted text from the pipeline result
- **Structured content**: Raw pipeline result in `structuredContent.result` for programmatic access

## MCP Resources

The server exposes three read-only **MCP Resources** that provide live information about the connected RocketRide engine. Resources use the `rocketride://` URI scheme and return JSON payloads.

| URI                      | Name          | Description                                                                          |
| ------------------------ | ------------- | ------------------------------------------------------------------------------------ |
| `rocketride://pipelines` | Pipeline List | JSON array of all available pipelines (name and description) on the connected server |
| `rocketride://status`    | Server Status | Connection status, pipeline count, and list of loaded pipeline names                 |
| `rocketride://nodes`     | Node Registry | Available pipeline node types and their schemas (via `rrext_get_nodes`)              |

### Reading resources

In Claude Desktop or any MCP-compatible client, resources are listed automatically. You can also access them programmatically:

```python
# Example: read the pipeline list resource
result = await session.read_resource('rocketride://pipelines')
# Returns: {"pipelines": [{"name": "my-pipeline", "description": "..."}, ...]}

# Example: check server status
result = await session.read_resource('rocketride://status')
# Returns: {"connected": true, "pipeline_count": 3, "pipelines": ["pipe-a", "pipe-b", "pipe-c"]}

# Example: list available node types
result = await session.read_resource('rocketride://nodes')
# Returns: {"nodes": [{"name": "llm_openai", "type": "processor"}, ...]}
```

When the RocketRide client is not connected, resources return a JSON error payload (e.g. `{"pipelines": [], "error": "Client is not connected"}`) instead of raising an exception. Unknown URIs raise a `ValueError`.

## MCP Prompt Templates

The server provides three reusable **MCP Prompt Templates** for common RocketRide operations. These templates generate pre-formatted user messages that can be sent to an LLM.

### analyze-document

Analyze a document through a RocketRide pipeline.

| Argument   | Required | Description                       |
| ---------- | -------- | --------------------------------- |
| `pipeline` | Yes      | Pipeline name to use for analysis |
| `query`    | Yes      | Analysis question or instruction  |

**Example usage in Claude Desktop:**

Select the "analyze-document" prompt, then fill in:

- **pipeline**: `invoice-parser`
- **query**: `Extract all line items and totals`

This generates the message: _"Please analyze the document using the RocketRide pipeline "invoice-parser". Focus on the following: Extract all line items and totals"_

### chat-with-data

Start a conversation about data processed by RocketRide.

| Argument   | Required | Description                  |
| ---------- | -------- | ---------------------------- |
| `pipeline` | Yes      | Pipeline name                |
| `question` | Yes      | Your question about the data |

**Example usage:**

- **pipeline**: `quarterly-reports`
- **question**: `What was the revenue growth in Q3?`

This generates the message: _"I would like to discuss data processed by the RocketRide pipeline "quarterly-reports". My question is: What was the revenue growth in Q3?"_

### evaluate-pipeline

Evaluate a pipeline's output quality using test data.

| Argument          | Required | Description                    |
| ----------------- | -------- | ------------------------------ |
| `pipeline`        | Yes      | Pipeline to evaluate           |
| `test_input`      | Yes      | Test input data                |
| `expected_output` | No       | Expected output for comparison |

**Example usage:**

- **pipeline**: `sentiment-classifier`
- **test_input**: `This product is fantastic!`
- **expected_output**: `positive`

This generates the message: _"Evaluate the output quality of the RocketRide pipeline "sentiment-classifier" using the following test input: This product is fantastic! Expected output: positive"_

### Using prompts programmatically

```python
# List available prompts
prompts = await session.list_prompts()

# Get a rendered prompt
result = await session.get_prompt(
    'analyze-document', arguments={'pipeline': 'my-pipeline', 'query': 'Summarize the key findings'}
)
# result.messages[0].content.text contains the rendered message
```

## SSE Mode

For remote or Docker deployments, the server can run as an HTTP/SSE server instead of stdio:

```bash
pip install rocketride-mcp[sse]
export MCP_API_KEY=your-secret-token
rocketride-mcp-sse --host 0.0.0.0 --port 8080
```

SSE mode supports Bearer token authentication via the `MCP_API_KEY` environment variable — optional when binding localhost, but mandatory for non-loopback binds (the server refuses to start on hosts like `0.0.0.0` without it). The `/health` endpoint is always accessible for monitoring.

## Configuration

Set these environment variables (required; no config file is used):

| Variable            | Required | Description                                                         |
| ------------------- | -------- | ------------------------------------------------------------------- |
| `ROCKETRIDE_URI`    | Yes      | WebSocket URI of the RocketRide engine (e.g. `ws://localhost:5565`) |
| `ROCKETRIDE_AUTH`   | Yes\*    | API authentication token                                            |
| `ROCKETRIDE_APIKEY` | Yes\*    | Alternative to `ROCKETRIDE_AUTH`                                    |
| `MCP_API_KEY`       | No (loopback) / Yes (non-loopback binds) | Bearer token for SSE server authentication      |

\*Either `ROCKETRIDE_AUTH` or `ROCKETRIDE_APIKEY` must be set.

## Links

- [Documentation](https://docs.rocketride.org/)
- [GitHub](https://github.com/rocketride-org/rocketride-server)
- [Discord](https://discord.gg/PMXrtenMsY)
- [Contributing](https://github.com/rocketride-org/rocketride-server/blob/develop/CONTRIBUTING.md)

## License

MIT - see [LICENSE](https://github.com/rocketride-org/rocketride-server/blob/develop/LICENSE).


---

# n8n

Route: /connect/n8n

---
title: n8n
sidebar_position: 4
---

# n8n

RocketRide and [n8n](https://n8n.io) connect in both directions:

- **RocketRide → n8n:** the [`tool_n8n` node](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/tool_n8n/README.md) triggers n8n
  workflows from a pipeline step or an agent tool.
- **n8n → RocketRide:** any n8n workflow calls a RocketRide pipeline through the pipeline's
  webhook endpoint, using n8n's built-in **HTTP Request** node.

Combining the two gives **round-trips**: RocketRide → n8n → RocketRide.

> Templates: [`examples/n8n-roundtrip.pipe`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n-roundtrip.pipe) (RocketRide side) and
> [`examples/n8n-call-rocketride.workflow.json`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n-call-rocketride.workflow.json)
> (n8n side, importable).
>
> **Runnable pipelines** that exercise every mode (sync / async / sequential / agent / round-trip)
> live in [`examples/n8n/`](https://github.com/rocketride-org/rocketride-server/tree/develop/examples/n8n) — open them in the IDE.

---

## RocketRide → n8n (the `tool_n8n` node)

Drop the **n8n** node into a pipeline (wired by lanes) or attach it to an agent (tool channel).
Full reference: [`tool_n8n` node](https://github.com/rocketride-org/rocketride-server/blob/develop/nodes/src/nodes/tool_n8n/README.md).

The essentials:

1. The target n8n workflow needs a **Webhook trigger** node — triggering is webhook-only;
   manual/cron workflows can't be called over HTTP.
2. **Activate/publish** the workflow — the production `/webhook/...` route 404s until then.
3. End the workflow with a **"Respond to Webhook"** node so a result comes back (`sync` mode).
   For long runs, switch the node to `async` mode: it injects a correlation id, then polls
   executions via the public API (API key required) until the run finishes.

### Sending files / structured data

- **Structured data:** set the node's **Payload shape** to `structured` — the pipeline step sends
  `{text, documents:[{content, metadata}]}` (preserving document boundaries + metadata) instead of
  flattening to `{"data": "..."}`. The `simple` default stays back-compatible.
- **Files / binary:** wire an `image` / `audio` / `video` lane into the node — it uploads the bytes
  to n8n as `multipart/form-data` (binary part `image_0` etc., text alongside as form fields), and
  if the workflow Responds with a Binary File, the bytes come back onto the matching lane. Capped at
  16 MB (n8n's default `N8N_PAYLOAD_SIZE_MAX`) with a clear error.

### Reaching non-webhook workflows (cron / manual / event)

Triggering is webhook-only, and n8n's public API has no "run-by-id" — so a workflow whose trigger is
a **Schedule/Cron**, **Manual**, or an **app event** (Gmail, etc.) can't be invoked on demand
directly. (Such workflows still run on their own schedule; this is only about invoking them on demand
from RocketRide.)

**Escape hatch — a thin webhook dispatcher** that calls the target via n8n's **Execute Sub-Workflow** node:

```text
[RR tool_n8n] → POST /webhook/my-dispatch
                  │
n8n dispatcher: [Webhook] → [Execute Sub-Workflow → target] → [Respond to Webhook]
                  │ returns the target's output
```

1. On the **target** workflow, add an **"Execute Sub-Workflow Trigger"** ("When Executed by Another Workflow") as an entry point.
2. Import [`examples/n8n/n8n-dispatch.workflow.json`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n/n8n-dispatch.workflow.json), point its **Execute Workflow** node at the target, and **activate** it.
3. Set `tool_n8n`'s **Workflow** to the dispatcher's webhook path (`my-dispatch`); it's triggered like any webhook and the target's output flows back.

## n8n → RocketRide

Any RocketRide pipeline that starts with a **webhook**, **chat**, or **dropper** source node is
HTTP-callable. When such a pipeline starts, the source node publishes its connection details
(shown in the IDE): the **interface URL** (e.g. `http://localhost:5567/webhook`), a **public
authorization key**, and a **private token**.

### The RocketRide community node (preferred)

We publish an official n8n community package, **`n8n-nodes-rocketride`**, so you do not have to
hand-roll HTTP calls. It has zero runtime dependencies and requires n8n **1.94.0+**. It ships two
nodes:

- **RocketRide** (action) — calls a deployed pipeline. Operations: **Run Pipeline** (text, JSON, or
  structured `text` + `documents` payloads), **Upload Files** (n8n binary fields as
  `multipart/form-data`), and **Chat**. It is marked `usableAsTool`, so an n8n **AI Agent** can call
  RocketRide directly; and it normalizes the response, lifting a single pipeline result to the top
  level instead of hard-coding RocketRide's dynamic output-lane names.
- **RocketRide Trigger** — a branded replacement for a generic Webhook node for the
  RocketRide → n8n direction. Paste its URL into the `tool_n8n` node. Supports an optional shared
  secret on the `Authorization` header and a configurable respond mode.

Only the **RocketRide** action node uses a credential — a single **RocketRide API**
credential holding the gateway **Base URL** (e.g. `http://localhost:5567`) and the
pipeline's public `pk_…` **API Key**, sent as a Bearer token. **RocketRide Trigger** takes
no credential: RocketRide calls *it*, so its only authentication is the optional shared
secret above.

Once the package is published to npm, self-hosted instance owners install it from
**Settings → Community Nodes → Install** by entering `n8n-nodes-rocketride`; on n8n Cloud it appears
in the Nodes panel after n8n approves it as a verified community node. To let n8n's AI Agent call it
as a tool, set `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true` on your instance.

Source, full node/credential reference, and an importable example workflow:
[`packages/n8n-nodes/`](https://github.com/rocketride-org/rocketride-server/tree/develop/packages/n8n-nodes).

### Without the community node (HTTP Request)

If you cannot install community packages, add an **HTTP Request** node:

| Setting | Value |
| ------- | ----- |
| Method  | `POST` |
| URL     | the pipeline's interface URL, e.g. `http://localhost:5567/webhook` |
| Header  | `Authorization: <public auth key>` |
| Body    | JSON payload for the pipeline |

The pipeline's `response_*` node determines what comes back to n8n. Import
[`examples/n8n-call-rocketride.workflow.json`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n-call-rocketride.workflow.json)
for a ready-made Webhook → HTTP Request → Respond to Webhook workflow.

## Round-trips (RocketRide → n8n → RocketRide)

Chain the two directions:

```text
RR pipeline A: [source] → [tool_n8n: workflow "rocketride-demo"] → [response]
                                  │ POST /webhook/rocketride-demo
n8n workflow:  [Webhook] → [HTTP Request → RR pipeline B's webhook] → [Respond to Webhook]
                                  │ POST http://.../webhook (pipeline B)
RR pipeline B: [webhook] → … → [response]   — its result returns to n8n, then up to pipeline A
```

Pipeline A's `tool_n8n` step waits for n8n's response, which itself contains pipeline B's
response — synchronous nesting across both systems. Start from
[`examples/n8n-roundtrip.pipe`](https://github.com/rocketride-org/rocketride-server/blob/develop/examples/n8n-roundtrip.pipe) for the A side.

---

## Reach any SaaS via n8n (credential vault)

RocketRide ships no built-in SaaS connectors — but n8n has 1000+ (Slack, Gmail, HubSpot, Google
Sheets, Notion, S3, …), each authenticated by n8n's own credential store. So an RR pipeline (or
agent) can act on almost any app by triggering an n8n workflow that does the work:
`Webhook → <app node(s)> → Respond to Webhook`, then drop `tool_n8n` in the pipeline (or attach it
to an agent) pointed at that workflow. The agent-tool face lets an LLM pick which automation to fire
at runtime.

**Payload contract** — what your workflow receives:
- `simple` mode → `$json.body` = `{ "data": "<text>" }`
- `structured` mode → `$json.body` = `{ "text": "...", "documents": [{ "content", "metadata" }] }`
- binary lanes → `multipart/form-data`: text fields in `$json.body`, files in `$binary` (`image_0`, `audio_0`, …)
- `async` mode also injects `_rr_correlation_id` — echo it through so polling can match the run

Return data via a **Respond to Webhook** node (sync) or read it from the execution (async).

## Human-in-the-loop (approvals)

Gate an RR run on a human decision with n8n's **Wait** node. Use **async** mode (a sync HTTP call
would time out waiting for a person): `tool_n8n` (async) → a workflow that pauses on **Wait → On
Webhook Call** (or the **Human in the Loop** node), which exposes `$execution.resumeUrl`; notify the
approver, and when they act n8n resumes and the run returns the decision. (Async requires the API key.)

## Failure handling (error workflows)

Centralize alerting/dead-lettering with an n8n **error workflow**: build one whose first node is the
**Error Trigger**, then in each target workflow's *Settings → Error workflow* select it. On failure
n8n routes the execution + error there (Slack alert, ticket, retry…) — independent of `tool_n8n`,
which still surfaces its own clear errors (404 → activate, ack → add a Respond node, timeout, …).

## Observability

In **async** mode (and from `n8n.get_execution` / `n8n.list_executions`), results carry a `url`
deep-link straight to the run in n8n's execution view — useful for tracing a RocketRide step to its
n8n execution.

## Reachability appendix (read this if anything 404s or times out)

Both directions are plain HTTP, so what matters is **where each process runs**:

| RocketRide deployment | n8n on your machine (`localhost:5678`) | What to enter as the n8n Base URL |
| --------------------- | -------------------------------------- | --------------------------------- |
| **Local** (IDE-managed, native process) | ✅ reachable | `http://localhost:5678` |
| **Docker / On-Prem** (engine in a container) | ❌ `localhost` is the container | `http://host.docker.internal:5678` — on Linux add `extra_hosts: ["host.docker.internal:host-gateway"]`; or run n8n on the same Docker network and use `http://n8n:5678` |
| **Cloud** | ❌ private hosts unreachable | expose n8n publicly or via a tunnel (e.g. Cloudflare Tunnel) and use that URL |

The `tool_n8n` node detects the Docker case at runtime and suggests the fix in its error message.

**The reverse direction has the same physics.** If n8n runs in Docker and RocketRide runs
natively, n8n's HTTP Request node must call `http://host.docker.internal:<port>/webhook`,
not `localhost`.

**n8n behind Docker or a reverse proxy:** set n8n's `WEBHOOK_URL` environment variable to its
externally reachable URL — otherwise n8n displays (and registers) webhook URLs based on what it
sees internally (`localhost:5678`), which other systems can't reach.

**TLS:** a self-signed local n8n over HTTPS fails certificate verification by default — turn off
the node's "Verify TLS certificate" toggle for that case only.


---

# WebSocket

Route: /connect/websocket

---
title: WebSocket
---

# WebSocket protocol

The RocketRide [engine](/concepts/runtime-engine) speaks a native **WebSocket**
protocol. Every consumer (the [TypeScript](/clients/typescript) and
[Python](/clients/python) SDKs and the [MCP server](/connect/mcp/stdio)) connects
over this one socket to start pipelines and stream results. You rarely touch it
directly; the SDKs frame the messages for you. This page documents what they
send so you can debug, trace, or build your own client.

## Connection

- **Endpoint:** `ws://<host>:<port>/task/service`. The engine listens on port
  **5565** by default, so a local engine is `ws://localhost:5565/task/service`.
- **Cloud:** managed engines are reached at `https://api.rocketride.ai`; the
  client upgrades to a WebSocket from there. See [Cloud](/operate/cloud).
- **Encoding:** JSON messages framed per the engine protocol (described below).
- **Auth:** the first frame on the socket is an `auth` request carrying your API
  key (`{ "auth": "$ROCKETRIDE_APIKEY", "clientName": "...", "clientVersion": "..." }`);
  the SDKs read the key from the `ROCKETRIDE_APIKEY` env var (engine URI from
  `ROCKETRIDE_URI`). If `auth` fails the request errors. Once authenticated, each
  task request carries the task `token` returned by `execute` (the SDK's `use()`)
  in its `arguments`.
  Cloud requires a key; a local engine typically does not.

The default port is applied only when the URI omits one, point the client at a
different host or port to reach a remote or self-hosted engine.

### Pre-auth probe (`rrext_public_probe`)

Before authenticating, a client may open a public connection and send
`rrext_public_probe`. The response body carries `version`, `capabilities`,
`platform`, the public `apps` list, `stripePublishableKey` (when billing is
configured), and `endpoints` — the server's public addresses:

```json
{ "endpoints": { "api": "origin", "ui": "origin" } }
```

Each value is an absolute URL or the literal `origin`, meaning "the address
you probed me at" (the SDKs substitute it client-side before returning, so
callers always see absolute URLs). The server reads `RR_BACKEND_ORIGIN` /
`RR_FRONTEND_ORIGIN` for the two values; unset means `origin`, correct for
any single-host deployment. They differ only on split deployments — e.g. a
CDN-served UI whose live traffic should connect directly to the API host.

## Message format

The engine protocol is a DAP-style (Debug Adapter Protocol) message exchange.
Every frame is a JSON object with a `type` of `request`, `response`, or `event`,
and a monotonically increasing `seq` used to correlate replies with the requests
that triggered them.

### Requests

The client sends a **request** naming a `command`. Arguments (including the auth
`token`) travel in `arguments`; raw file bytes, when a command carries a
payload, travel in `data` -- but never as an in-JSON value. The SDK strips
`data` out of `arguments`, appends a single `\n` byte after the JSON header,
then the raw bytes, so the frame on the wire is `<json-header>\n<binary-payload>`.

```json
{
	"type": "request",
	"seq": 1,
	"command": "rrext_process",
	"arguments": { "subcommand": "open", "object": "...", "mimeType": "...", "provider": "...", "token": "$TASK_TOKEN" }
}
```

This particular request -- opening a data pipe -- carries the task's own
`token` (returned by `execute`): a pipe is always opened on an already-running
task. Every request on the pipe (`write`, `close`, ...) carries that same
`token` in `arguments`, for example:

```json
{
	"type": "request",
	"seq": 3,
	"command": "rrext_process",
	"arguments": { "subcommand": "write", "pipe_id": 1, "token": "$TASK_TOKEN" }
}
```

followed immediately by the `\n` byte and the raw payload bytes -- `data` never
appears in the JSON itself.

### Responses

The engine answers each request with a **response** that echoes the original
`command` and points back at the request via `request_seq`. `success` tells you
whether the command worked; a successful response carries a `body`.

```json
{
	"type": "response",
	"seq": 2,
	"request_seq": 1,
	"command": "rrext_process",
	"success": true,
	"body": { "pipe_id": 1 }
}
```

On failure, `success` is `false` and the frame carries a `message` plus a
`trace` (`file`, `lineno`) instead of a body. A failure the engine can name
also carries a machine-readable `code`:

```json
{
	"type": "response",
	"seq": 2,
	"request_seq": 1,
	"command": "rrext_process",
	"success": false,
	"message": "Your pipeline is not running",
	"code": "TASK_NOT_REGISTERED",
	"trace": { "file": "task_server.py", "lineno": 722 }
}
```

`message` is written for a person and may be reworded or translated; `code` is
the contract. Classify a failure on `code` and never on the message text.
Absent `code`, the failure has no named class — treat it as unclassified rather
than inferring one from the prose.

| `code` | Meaning |
| --- | --- |
| `TASK_NOT_REGISTERED` | The token, public key or project/source names no live task: never started, terminated, replaced by another client, or the engine restarted (the task registry is in-memory and rebuilt at boot, so every previously issued token is invalid after a restart). |
| `TASK_AMBIGUOUS` | An unscoped lookup matched several running tasks; retry with a scope. |
| `TASK_COMPLETED` | The task finished before the request could be served. |
| `TASK_STOPPED` | The task was stopped or cancelled before the request. |

These codes ride command replies. A task key rejected while the connection is
still being established — on the HTTP request or the WebSocket upgrade — is
answered by the web layer with a generic `400 Bad request` carrying neither a
message nor a code, deliberately, so that a rejected credential reveals nothing
about why it was rejected. A client therefore cannot tell an invalidated task
key from any other bad credential at connect time; the codes above appear only
once a command is in flight.

### Events

The engine pushes **events** that are not replies to any request: this is how
pipeline output streams back. An event names an `event` and carries a `body`;
the client matches it to the task it started.

```json
{ "type": "event", "seq": 7, "event": "apaevt_sse", "body": { "pipe_id": 1, "type": "...", "data": {} } }
```

The engine can also push a dedicated monitoring stream (task lifecycle, periodic
status snapshots, resource metrics, and per-component flow traces) over this same
socket. See [Observability](/connect/websocket/observability).

## A session, end to end

A typical run is one request/response/event conversation over a single open
socket, opened with the `auth` handshake above. The SDK methods map onto engine
commands:

1. **Start**: `use()` starts the pipeline (`execute`) and gets back a task
   token.
2. **Feed**: `send()` / `pipe()` push input (`rrext_process` / `write`), with
   file bytes in the request's `data` field; `chat()` drives a streaming,
   conversational exchange.
3. **Stream**: the engine emits `event` frames as nodes produce output, so
   responses arrive incrementally rather than in one block (see the
   [Execution model](/concepts/execution-model)).
4. **Stop**: `terminate()` closes the task (`terminate`) and releases its
   resources; closing a data pipe (`rrext_process` / `close`) returns that
   pipe's result.

The pipeline JSON sent over the socket is identical to the JSON you author
visually or by hand, the protocol just transports it.

## MIME type selects the lane

Every write carries a MIME type — the `mimeType` argument of `rrext_process` /
`open`, which the HTTP `/webhook/{project_id}/{source}` route fills in from the
request's `Content-Type` header. That MIME type is **routing, not metadata**: it
picks which lane the body is delivered on.

The choice is made against the pipeline's live wiring, not a fixed table. A
branch is taken only when the MIME type matches **and** some component actually
reads that lane; anything unmatched falls through to the raw/tags lane.

| MIME type | Lane, when a component reads it |
| --- | --- |
| `application/json` | `json` |
| `text/*` | `text` |
| `image/*`, `video/*`, `audio/*` | `image`, `video`, `audio` |
| `application/rocketride-question+json` | `questions` |
| `application/rocketlib-tag` | `tags` |
| anything else, or no reader above | raw, delivered on `tags` |

The prefix `lane/<name>` bypasses detection and targets a lane directly.

### When nothing reads the chosen lane

The write still succeeds. The object is accepted, counted as completed and
answered `200 OK`; only `resultTypes` comes back empty, because no component
received the body. Nothing about the response, the HTTP log line or the task
counters distinguishes this from a successful run.

Because that outcome is indistinguishable from success, the engine emits a task
**warning** naming the lane the data went to and the lanes the pipeline reads.
It is a warning rather than an error: a source may legitimately offer several
lanes while a pipeline wires up one, so an unread lane is not by itself a fault
— but *this object reaching nobody* is never what the sender intended, and the
warning is the only signal that separates the two.

Read the warnings from `get_task_status(token)['warnings']`, or subscribe to
`apaevt_status_warning` (see [Observability](/connect/websocket/observability)).

Note that the mismatch is symmetric: `text/plain` into a pipeline whose first
component reads `json` fails exactly the way `application/json` fails into a
`text`-first one. There is no single header that is correct for every pipeline,
which is why the endpoint panel offers one example per lane and preselects the
one the running pipeline reads.

## Keepalive & timeouts

The connection is long-lived: a task stays open while it streams. The SDK
clients keep it healthy with WebSocket pings and a periodic `rrext_ping`
command.

| Setting             | Default | Meaning                                                 |
| ------------------- | ------- | ------------------------------------------------------- |
| Ping interval       | 15 s    | How often a ping frame is sent.                         |
| Ping timeout        | 60 s (TypeScript) / 300 s (Python) | No pong within this window → the connection is closed. |
| Socket timeout      | 180 s   | Connection open/close timeout in both SDKs; Python also applies it to sends. |

## Related

- [Observability](/connect/websocket/observability): monitoring events and
  metrics over this socket.
- [MCP](/connect/mcp/stdio): pipelines-as-tools for AI assistants, transported over
  this socket.
- [TypeScript SDK](/clients/typescript) · [Python SDK](/clients/python): the
  clients that speak this protocol.
- [Pipeline JSON Reference](/reference/pipeline-reference): the `.pipe` payload shape.
- [Execution model](/concepts/execution-model): how a run streams once started.


---

# WebSocket Events

Route: /connect/websocket/observability

---
title: WebSocket Events
---

# WebSocket Events

RocketRide exposes runtime observability (task lifecycle, periodic status,
resource metrics, and per-component flow traces) as a **live event stream over
the same [WebSocket](/connect/websocket) the engine already speaks**. You open a
socket, subscribe to the event types you care about, and the engine pushes events
as a run unfolds. There is no external metrics endpoint to scrape: it is **not**
OpenTelemetry, Prometheus, Sentry, or webhooks. The engine does keep a persistent
run-log continuum queryable over this same socket (the `rrext_log` command and its
subcommands; SDK `LogApi`); you can also connect, subscribe, and persist the
events yourself as they arrive.

The [TypeScript](/clients/typescript) and [Python](/clients/python) SDKs frame all
of this for you (`getTaskStatus()`, `onEvent`, `setEvents()` / `add_monitor`), so
you rarely touch the wire directly. This page documents the protocol surface so you
can debug it, build a dashboard, or write your own ingester.

<!-- Maintainers: docs/agents/context/ROCKETRIDE_OBSERVABILITY.md restates this same wire
     protocol (rrext_monitor, the bitmask table, the apaevt_* schemas) because it
     is bundled into .rocketride/docs/ for offline use by AI assistants and cannot
     be reduced to a link. Change the protocol and both files must move together. -->

## Subscribing: `rrext_monitor`

Subscriptions are managed with the `rrext_monitor` [DAP
request](/connect/websocket#requests). The engine keeps a per-connection registry
of which event types you want and which tasks they cover. Send it once the
connection is authenticated (the initial `auth` handshake described on the
[WebSocket](/connect/websocket#connection) page):

```json
{
	"type": "request",
	"seq": 2,
	"command": "rrext_monitor",
	"arguments": {
		"token": "*",
		"types": ["TASK", "SUMMARY", "FLOW", "OUTPUT", "SSE"]
	}
}
```

`token: "*"` subscribes to every task your API token owns: the recommended scope
for an ingestion service. Subscriptions are per-connection and not durable: on
reconnect, resubscribe.

### Event types

`types` accepts case-insensitive `EVENT_TYPE` strings (or the equivalent integer
bitmask, e.g. `36` = `SUMMARY | TASK`):

| String      | Bit  | What you get                                                         |
| ----------- | ---- | -------------------------------------------------------------------- |
| `NONE`      | 0    | Unsubscribe (clears the registry entry)                              |
| `DEBUGGER`  | 1    | DAP debug-protocol passthrough (stopped, threads, …)                 |
| `DETAIL`    | 2    | Real-time per-object processing updates                              |
| `SUMMARY`   | 4    | Periodic full `TASK_STATUS` snapshots, best for dashboards           |
| `OUTPUT`    | 8    | Engine log / output lines                                            |
| `FLOW`      | 16   | Pipeline component flow events (requires a trace level, see below)   |
| `TASK`      | 32   | Lifecycle: `running`, `begin`, `end`, `restart`                      |
| `SSE`       | 64   | Custom node-to-UI messages emitted by nodes via `monitorSSE()`       |
| `DASHBOARD` | 128  | Server-level events (connections, monitor changes)                   |
| `BILLING`   | 256  | Billing ledger events (credits/debits), org-scoped                   |
| `DEPLOY`    | 512  | Deployment-change invalidations (`apaevt_deploy`: pointer, state, schedule, and run mutations), org-scoped — re-fetch on receipt, the body carries identity only |
| `ALL`       | 1023 | Everything above                                                     |

### Subscription scope

Replace `token: "*"` to narrow or widen what you receive. The scope IS the
kind: adding `teamId` addresses the team's DEPLOYED run of the pipeline;
omitting it addresses your own dev run (there is no run-kind argument).

| Scope                      | Set with                                    | Receives                                       |
| -------------------------- | ------------------------------------------- | ---------------------------------------------- |
| One running task           | `token`                                     | Events for that task only                      |
| Your dev run (any restart) | `projectId` + `source`                      | Your own dev run of that pipeline              |
| A team's deployed run      | `teamId` + `projectId` + `source`           | That team's deploy run of the pipeline         |
| One pipe within a pipeline | `projectId` + `source` + `pipeId`           | That one pipe                                  |
| All sources in a project   | `projectId` + `source: "*"` (+ `teamId`)    | Project-wide within the chosen scope           |
| All your tasks             | `token: "*"`                                | Everything your token owns                     |

A project/source subscription only ever receives YOUR OWN dev runs —
another user's dev run of the same pipeline is watchable only via its task
token.

### Seeded on subscribe

You don't poll for the initial state: subscribing seeds it. Turning on `TASK`
triggers an immediate `apaevt_task` with `action: "running"` listing the active
tasks; turning on `SUMMARY` triggers an immediate `apaevt_status_update` with the
current status (or an empty "not running" placeholder).

### Flow traces need a trace level

`apaevt_flow` events fire only when the task was **started** with a
`pipelineTraceLevel`. If you don't control the executor, flow is silent for that
run. When you start the pipeline (`use()` / `execute`), pass:

| Level            | Captured                          |
| ---------------- | --------------------------------- |
| `none` (default) | No flow traces                    |
| `metadata`       | Component / lane structure only   |
| `summary`        | Lane writes and final results     |
| `full`           | Every lane write and invoke call  |

`summary` is the practical default: inputs and outputs without per-call noise.

## Events

The engine pushes [events](/connect/websocket#events) whose `event` field is the
type discriminator and whose `body` carries the payload. Authoritative type
definitions live in the SDK type modules
(`packages/client-typescript/src/client/types/events.ts`,
`packages/client-python/src/rocketride/types/events.py`, and the matching `task`
modules -- `packages/client-typescript/src/client/types/task.ts` and
`packages/client-python/src/rocketride/types/task.py`).

| Event                  | Subscribe to | Fires on                                          |
| ---------------------- | ------------ | ------------------------------------------------- |
| `apaevt_task`          | `TASK`       | Lifecycle: `running` / `begin` / `end` / `restart`|
| `apaevt_status_update` | `SUMMARY`    | Periodic full `TASK_STATUS` snapshot              |
| `apaevt_flow`          | `FLOW`       | Component entry / exit, per pipe, per op          |
| `output`              | `OUTPUT`     | Engine stdout/stderr-style log lines              |
| `apaevt_sse`           | `SSE`        | Node-emitted custom messages (`monitorSSE()`)     |
| `apaevt_status_upload` | — (SDK-local) | File-upload progress, synthesized by the client SDK during file sends |
| `apaevt_dashboard`     | `DASHBOARD`  | Server-level connection / monitor-change events   |

### `apaevt_task`: lifecycle

`body.action` is one of `running`, `begin`, `end`, or `restart`. The `running`
snapshot lists active tasks with their `id`; `begin` / `end` / `restart` carry
`name`, `projectId`, and `source` (`begin` also carries `beginSeq`, the run's
chapter key in the run-log continuum; `end` carries a `reason` when a stop
reason exists) but **no per-event id**: correlate them by
`projectId` + `source`, using the `running` snapshot for the id ↔ project+source
map.

```json
{ "action": "running", "tasks": [{ "id": "…", "name": "…", "projectId": "…", "source": "…", "runKind": "…", "teamId": "…" }] }
{ "action": "begin", "name": "…", "projectId": "…", "source": "…", "beginSeq": 42 }
```

### `apaevt_status_update`: full status

`body` is a `TASK_STATUS` snapshot: the same shape the SDKs return from
`getTaskStatus()`. Key groups:

- **Identity / lifecycle:** `name`, `project_id`, `source`, `state`
  (`0` NONE · `1` STARTING · `2` INITIALIZING · `3` RUNNING · `4` STOPPING ·
  `5` COMPLETED · `6` CANCELLED), `completed`, `startTime`, `endTime`.
- **Activity:** `status`, `currentObject`, `currentSize`.
- **Counts:** `totalCount` / `completedCount` / `failedCount`, the matching
  `*Size` fields, `wordsCount` / `wordsSize`.
- **Rates:** `rateCount`, `rateSize` (instantaneous).
- **History:** `errors`, `warnings`, `notes`; `errors` and `warnings` are
  **capped at the last 1000 entries**, so persist them as they arrive or older
  ones are lost on long runs.
- **Termination:** `exitCode`, `exitMessage`.
- **Pipeline flow:** `pipeflow.{totalPipes, byPipe}`, where `byPipe` maps each pipe
  id to its currently-active component stack (a live snapshot of what is running).
- **Resource metrics:** `metrics.{cpu_percent, cpu_memory_mb, gpu_memory_mb}` plus
  `peak_*` and `avg_*` variants of each.
- **Billing tokens:** `tokens.{cpu_utilization, cpu_memory, gpu_memory, total}`
  (100 tokens = $1).

### `apaevt_flow`: execution trace

The data that lets you reconstruct *why* a pipeline produced what it did: each
component's entry and exit with its lane data and any error.

```ts
{
  id: number,                              // pipe index within the pipeline
  op: "begin" | "enter" | "leave" | "end",
  pipes: string[],                         // current component stack for this pipe
  component?: string,                      // component this op refers to (on "leave", the leaving one) — pair enter/leave by identity, not stack position
  trace: { lane?: string, data?: object, result?: string, error?: string },
  result?: PIPELINE_RESULT,                // on op === "end", level >= summary
  project_id: string,
  source: string
}
```

`trace` is free-form and varies by node and trace level, store it as JSON, don't
flatten it.

The lifecycle lanes (`open`, `closing`, `close`) are dispatched from the pipe head in
dependency order — `closing`/`close` upstream-first, `open` downstream-first — so their
`enter`/`leave` frames appear as siblings under the head rather than nested per branch.
`enter`/`leave` pairs still balance; pair them by `component` identity, not by nesting
depth. Data-lane writes emitted while a component flushes still nest inside that
component's `closing` frame.

A control node's inline sub-pipeline (for example `tool_pipe`) is dispatched the same way,
but from that control node rather than the pipe head: the sub-pipeline's lifecycle frames
appear as siblings under the control node, once per invocation. To confirm each node runs
its lifecycle exactly once per pass, count `open`/`closing`/`close` `enter` frames per
`component` within one dispatch pass — each appears once (a control node's sub-pipeline
repeats once per invocation, each invocation being its own pass).

### `apaevt_sse`: node-to-UI messages

Nodes call `monitorSSE(pipe_id, type, data)` to broadcast custom updates
("thinking", "tool_call", progress, …). The body is `{ pipe_id, type, data }`; the
schema is intentionally open: interpret it per node type.

### `output`: log lines

The engine's DAP `output` events are re-emitted to subscribers. The body carries an
`output` string plus the DAP-standard output fields (`category`, …).

### `apaevt_status_upload`: upload progress

`{ action: "begin" | "write" | "complete" | "error", filepath, bytes_sent?, file_size? }`.
Synthesized locally by the SDK during file sends and delivered to your own event
callback; the engine never emits it on the wire.

### `apaevt_dashboard`: admin events

Connection lifecycle and monitor-change audit events, useful if you want to record
*who* subscribed to which monitors.

## Related commands

Besides `rrext_monitor`, sent the same way over the socket:

| Command                 | Uses                                  | Returns       | Purpose                                          |
| ----------------------- | ------------------------------------- | ------------- | ------------------------------------------------ |
| `rrext_get_task_status` | `token`                               | `TASK_STATUS` | Fetch current status synchronously               |
| `rrext_get_token`       | `projectId` + `source` (+ `teamId`)   | `{ token }`   | Resolve a running task's token — `teamId` addresses the team's deployed run, omitted = your dev run |
| `execute`               | `{ pipeline, pipelineTraceLevel?, … }`| `{ token }`   | Start a pipeline; sets the trace level that gates `FLOW` |

## Notes

- **No global run id.** There is no `event_id`, but task-built event bodies are
  stamped with `eventTime` and `logSeq` — a per-task sequence, strictly monotonic
  across runs and engine restarts — and the `apaevt_task` `begin` body carries
  `beginSeq` as the run's chapter key. Correlate a run by
  `(project_id, source, startTime)` or `beginSeq`, and order within a task by
  `body.logSeq` (the DAP envelope `seq` is only per-connection monotonic).
- **No dead-letter queue.** If your consumer is offline it misses that window; the
  next `running` snapshot is the only crash-recovery handle.
- **Tenant scoped.** You only receive events for tasks started with your own API
  token.

## Related

- [WebSocket](/connect/websocket): the protocol this stream rides on.
- [TypeScript SDK](/clients/typescript) · [Python SDK](/clients/python): clients
  that wrap subscriptions behind `getTaskStatus()`, `onEvent`, and `setEvents()` /
  `add_monitor`.
- [Execution model](/concepts/execution-model): how a run streams once started.


---

# Choose How to Run RocketRide

Route: /operate

---
title: Choose How to Run RocketRide
sidebar_label: Choose How to Run
---

# Choose How to Run RocketRide

One engine, two ways to run it: point your clients at managed
[RocketRide Cloud](/operate/cloud), or [run the engine
yourself](/operate/self-hosting). The pipeline JSON is identical either way —
the same `.pipe` file runs unchanged against Cloud or your own engine, so the
choice is operational, not architectural, and you can switch later.

|          | [Cloud](/operate/cloud)           | [Self-hosting](/operate/self-hosting)  |
| -------- | --------------------------------- | -------------------------------------- |
| Engine   | Managed for you                   | You run it (Docker / on-prem)          |
| Endpoint | `https://api.rocketride.ai`       | `ws://localhost:5565` (or your host)   |
| Auth     | API token required                | Optional locally                       |
| Best for | Getting started, hosted workloads | Private data, full control, air-gapped |

While you build, there is a third option that is really the second in disguise:
the [VS Code extension](/clients/vscode) deploys and manages a **local engine**
for you — self-hosting without the setup, ideal for the inner loop.

## Related

- [Cloud](/operate/cloud): connect a client to the managed endpoint.
- [Self-hosting](/operate/self-hosting): download, run, and secure your own engine.
- [Security](/operate/security): credentials, ports, and TLS.


---

# Cloud

Route: /operate/cloud

---
title: Cloud
---

# Cloud

RocketRide Cloud is a managed [engine](/concepts/runtime-engine): the same
runtime you can [self-host](/operate/self-hosting), operated for you. Instead of running
the engine yourself, you point a client at the Cloud endpoint and start building
pipelines, no infrastructure to provision.

## Connecting

Set two values and any [SDK](/clients/typescript) or the [CLI](/connect/cli) connects:

| Variable            | Value                       |
| ------------------- | --------------------------- |
| `ROCKETRIDE_URI`    | `https://api.rocketride.ai` |
| `ROCKETRIDE_APIKEY` | Your API token.             |

```bash
ROCKETRIDE_URI=https://api.rocketride.ai
ROCKETRIDE_APIKEY=your-api-token
```

The SDKs and CLIs read `ROCKETRIDE_APIKEY`. The MCP servers (the standalone
`rocketride-mcp` server and the engine's MCP module) additionally read
`ROCKETRIDE_AUTH`; in the standalone MCP server it takes precedence over
`ROCKETRIDE_APIKEY`.

> **Always use `https://` or `wss://` for Cloud.** An `http://`, `ws://`, or
> bare `host:port` URI silently downgrades to an unencrypted connection. The
> secure scheme upgrades to `wss://` under the hood, see the
> [WebSocket protocol](/connect/websocket).

Weighing Cloud against running the engine yourself? The comparison lives on
[Choose How to Run RocketRide](/operate).

## Related

- [Quickstart](/quickstart): run your first pipeline.
- [Choose How to Run RocketRide](/operate): Cloud vs. self-hosting.
- [Self-hosting](/operate/self-hosting): run the engine yourself.
- [TypeScript SDK](/clients/typescript) · [Python SDK](/clients/python) ·
  [CLI](/connect/cli): clients that connect to Cloud.


---

# Security

Route: /operate/security

---
title: Security
---

# Security

An overview of how RocketRide handles credentials, network exposure, and
authentication across its components.

## Credential isolation

API keys are configured **per node** inside the pipeline definition. Each node
holds only its own credentials — there are no shared global secrets, no
credential store, and no key that grants access to more than one provider.

```json
{
  "id": "llm_1",
  "provider": "llm_openai",
  "config": {
    "profile": "openai-4o",
    "openai-4o": { "apikey": "${ROCKETRIDE_OPENAI_KEY}" }
  }
}
```

Nodes use `${ENV_VAR}` substitution so the key itself never has to appear in the
`.pipe` file. Only `ROCKETRIDE_`-prefixed variables are substituted — a
reference to any other variable is replaced with `<REDACTED>`. See [Best Practices: Credential management](/guides/best-practices#credential-management)
for how to keep keys out of version control.

## Network exposure

The engine binds to `localhost` by default:

- **Port 5565** — WebSocket API (SDK / CLI connections).
- **Source-node HTTP endpoints** (Webhook, Chat, Dropper) — the port is set
  per node in the pipeline config; 5567 is the conventional choice used in
  examples and integrations, not a fixed engine bind.

Only the source-node HTTP port needs to be accessible to external callers when
you're using a webhook-based source. Port 5565 is a management interface;
expose it only to trusted clients on a private network or behind a VPN.

For production deployments, put the engine behind a reverse proxy (nginx,
Caddy, AWS ALB) that terminates TLS and enforces rate limiting before traffic
reaches the engine.

## Endpoint authentication

When a Webhook, Chat, or Dropper source node starts, the engine generates two
credentials and writes them to the Project Log:

- **Public authorization key** - presented by external callers in the
  `Authorization: Bearer <key>` header. Safe to share with trusted API clients.
- **Private token** - the internal credential for the endpoint. Used by the SDK
  to connect to a running task via `--token`. Do not share this publicly.

The Project Log is local to the operator who started the pipeline (it is not a
shared or exportable log), so the private token is only visible to that
operator. Retrieve it from your own Project Log when you need to connect a client
with `--token`.

Both are generated fresh each time the pipeline starts. There is no persistent
credential to rotate — stopping and restarting the pipeline issues new
credentials automatically.

## MCP authentication

The [MCP server](/connect/mcp/stdio) authenticates callers in two ways:

- **`ROCKETRIDE_AUTH` / `ROCKETRIDE_APIKEY`** — the API key used to connect the
  MCP server to the RocketRide engine. Required; set in the environment.
- **`MCP_API_KEY`** — a Bearer token that clients must present to the MCP
  server when it is running in SSE (HTTP) mode. Optional for stdio mode,
  required for any network-exposed SSE deployment.

## Pipeline file security

A `.pipe` file is plain JSON. When you use `${ENV_VAR}` substitution, the key
stays in the environment and never touches disk in the pipeline file. When you
embed a key directly (for quick local testing), it is stored in plain text —
treat the file as a secret.

Do not commit `.pipe` files containing embedded credentials to version control.
Add them to `.gitignore`:

```gitignore
*.pipe
```

In CI/CD, pass the pipeline file through a secrets-expansion step before
passing it to `rocketride start`, or inject keys via environment variables and
use `${...}` references.

## Dependency scanning

The RocketRide codebase runs automated dependency scanning: CodeQL via
GitHub's default setup, plus Trivy and OpenSSF Scorecard on pushes to
`develop`/`main` and on scheduled runs. See [Security](/support/security-policy) for the
vulnerability reporting process and SLA.

## Related

- [Best Practices](/guides/best-practices): credential management patterns.
- [Self-hosting](/operate/self-hosting): network configuration.
- [MCP Server](/connect/mcp/stdio): MCP-specific authentication.
- [Security policy](/support/security-policy): vulnerability reporting.


---

# Self-hosting

Route: /operate/self-hosting

---
title: Self-hosting
---

# Self-hosting

Run the RocketRide [engine](/concepts/runtime-engine) on your own machine when you
want full control over where data and model calls go. It is the same engine that
powers [Cloud](/operate/cloud); only the operator changes.

> **Fastest path:** the [VS Code extension](/clients/vscode) manages a
> local runtime for you while you build, with no manual setup. Use the steps below
> when you want to run the engine as a standalone service.

## Get the engine

Download a release build, no build toolchain required.

1. Open the
   [releases page](https://github.com/rocketride-org/rocketride-server/releases)
   and choose the latest **RocketRide Server** release (tags look like
   `server-v3.2.2`; ignore the client and extension releases).
2. Download the archive for your platform:

   | Platform              | Asset                                          |
   | --------------------- | ---------------------------------------------- |
   | Linux (x64)           | `rocketride-server-<version>-linux-x64.tar.gz` |
   | macOS (Apple Silicon) | `rocketride-server-<version>-darwin-arm64.tar.gz` |
   | Windows (x64)         | `rocketride-server-<version>-win64.zip`        |

3. Extract it. The folder is your **runtime directory**: it contains the `engine`
   binary and its `ai/` runtime.

```bash
mkdir rocketride-engine && tar -xzf rocketride-server-<version>-linux-x64.tar.gz -C rocketride-engine
cd rocketride-engine
```

> **Building from source instead?** That path is for contributors and is documented
> in the repository's development guide
> ([`docs/development/index.md`](https://github.com/rocketride-org/rocketride-server/blob/develop/docs/development/index.md)),
> which also covers the Docker Compose stack that bundles the engine with its data
> stores. The steps below apply to the runtime directory either way.

## Set up and start listening

The extracted archive is your runtime directory.

On Linux, install the runtime dependencies (`libc++1`, `libc++abi1`, `libgomp1`)
before starting:

```bash
# Debian / Ubuntu
sudo apt install libc++1 libc++abi1 libgomp1
# Fedora / RHEL
sudo dnf install libcxx libcxxabi libgomp
# Alpine
sudo apk add libc++ libgomp
```

From inside the runtime directory, start the engine. This binds to `127.0.0.1`
(localhost only) by default:

```bash
# Linux / macOS
./engine ./ai/eaas.py --host=127.0.0.1

# Windows
engine.exe ./ai/eaas.py --host=127.0.0.1
```

The engine now listens for the [WebSocket protocol](/connect/websocket) on port
**5565**. Only pass `--host=0.0.0.0` (all interfaces) once the engine sits behind
TLS and authentication — see [Connect a client](#connect-a-client) below.

## Verify it is running

The engine serves a public version endpoint on port 5565:

```bash
curl http://localhost:5565/version
```

## Connect a client

Point any [SDK](/clients/typescript) or the [CLI](/connect/cli) at the engine. A local
engine typically needs no auth token:

```bash
ROCKETRIDE_URI=ws://localhost:5565
```

```typescript
import { RocketRideClient } from 'rocketride';

const client = new RocketRideClient({ uri: 'ws://localhost:5565' });
await client.connect();
```

Expose the engine beyond localhost and you should put it behind TLS and
authentication (set `ROCKETRIDE_APIKEY`). For a clustered deployment, see the Helm
chart under `deploy/helm/rocketride/`.

## Provider credentials

Pipelines that call external models or stores need those providers' API keys.
Supply them as environment variables in the engine's environment (never committed);
a node's `config` references the variable rather than the literal secret. See
[Nodes](/nodes) for each provider's required keys.

## Related

- [Cloud](/operate/cloud): the managed alternative.
- [WebSocket protocol](/connect/websocket): what clients speak to the engine.
- [Runtime & engine](/concepts/runtime-engine): what the engine does with a
  pipeline.


---

# Docker

Route: /operate/self-hosting/docker

---
title: Docker
---

# Run the Engine in Docker

The engine ships as a published container image — the same one the
[VS Code extension's Docker mode](/clients/vscode) pulls:

```text
ghcr.io/rocketride-org/rocketride-engine
```

## Quickstart

```bash
docker run -d --name rocketride-engine \
  -p 127.0.0.1:5565:5565 \
  -v rocketride-data:/opt/data \
  --restart unless-stopped \
  ghcr.io/rocketride-org/rocketride-engine:latest
```

Point any client at it and go:

```bash
export ROCKETRIDE_URI=ws://localhost:5565
```

The `127.0.0.1:` prefix keeps the engine reachable only from the machine
itself — the right default, since a fresh engine accepts unauthenticated
connections. Widen it only behind TLS and authentication (see
[Security](/operate/security)).

## The image

- **Tags:** each release publishes its version tag plus `latest`; prerelease
  builds carry a `-prerelease` suffix. Pin a version tag in production.
- **Platform:** `linux/amd64` only. On Apple Silicon add
  `--platform linux/amd64` (Docker runs it under emulation — fine for
  development; the VS Code extension does the same).
- **Runs as non-root** (user `rocketride`), listens on **5565**, and starts
  the engine bound to all container interfaces — the port mapping above is
  what controls actual exposure.
- **Signed:** images are cosign-signed from CI. Verify keyless:

  ```bash
  cosign verify \
    --certificate-identity-regexp 'https://github.com/rocketride-org/rocketride-server/' \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    ghcr.io/rocketride-org/rocketride-engine:latest
  ```

## Configuration

The engine reads configuration from its environment — pass variables with
`-e`/`--env-file`:

- **Provider credentials** for your pipelines (OpenAI, Anthropic, database
  DSNs, …): set them in the engine's environment and reference them from
  node config as `${VAR}` — see
  [Self-hosting](/operate/self-hosting#provider-credentials).
- **MCP OAuth settings** if AI assistants will connect to `/mcp` on this
  engine: `MCP_EXPECTED_AUDIENCE` and friends — see
  [MCP self-hosting](/connect/mcp/http/self-hosting).

## Persistence

The engine writes runtime data to `/opt/data` (declared as a volume). Mount a
named volume or host path there — it's the only path that needs to survive
container replacement, and the one to back up.

## Health and upgrades

The image has a built-in healthcheck against the engine's public version
endpoint, so `docker ps` shows real health:

```bash
curl http://localhost:5565/version
```

(Use `/version`, not `/ping`: the engine entrypoint starts its web server
without the standard endpoints, so `/ping` is never registered and returns
404. `/version` is always registered and public.)

Upgrading is pull-and-replace; state lives in the volume:

```bash
docker pull ghcr.io/rocketride-org/rocketride-engine:latest
docker rm -f rocketride-engine
# re-run the docker run command above
```

## Compose

A minimal production compose file:

```yaml
services:
  engine:
    image: ghcr.io/rocketride-org/rocketride-engine:latest
    ports:
      - '127.0.0.1:5565:5565'
    volumes:
      - rocketride-data:/opt/data
    env_file: .env # provider credentials
    restart: unless-stopped

volumes:
  rocketride-data:
```

> The repository's own `docker/docker-compose.yml` is a **development stack**:
> it builds the image from a local source build and bundles Postgres, Milvus,
> and Chroma with default passwords. Use it for hacking on RocketRide, not
> for serving it.

## Next

- [Kubernetes](/operate/self-hosting/kubernetes): the Helm chart, for
  clustered deployments.
- [Production](/operate/self-hosting/production): topology and sizing.
- [Security](/operate/security): TLS, authentication, and exposure.


---

# Kubernetes

Route: /operate/self-hosting/kubernetes

---
title: Kubernetes
---

# Deploy on Kubernetes

The repository ships a Helm chart for clustered deployments at
[`deploy/helm/rocketride/`](https://github.com/rocketride-org/rocketride-server/tree/develop/deploy/helm/rocketride)
— a deployment, service, config/secret handling, HPA, and ingress, linted and
schema-validated in CI. The chart is not published to a chart registry:
install it from a checkout of the repository.

## Quickstart

```bash
git clone https://github.com/rocketride-org/rocketride-server.git
cd rocketride-server

# Preview what will be created
helm install rocketride deploy/helm/rocketride/ --values my-values.yaml --dry-run --debug

# Install
helm install rocketride deploy/helm/rocketride/ --values my-values.yaml
```

The chart refuses to render until credentials are configured — set
`engine.secrets` or `engine.existingSecret` in your values file first (see
the table below).

Upgrades and removal are standard Helm:

```bash
helm upgrade rocketride deploy/helm/rocketride/ --values my-values.yaml
helm uninstall rocketride
```

The chart deploys the same published engine image the
[Docker page](/operate/self-hosting/docker) documents
(`ghcr.io/rocketride-org/rocketride-engine`, tag defaults to the chart's
`appVersion`), serving the engine API on port 5565.

## The values that matter

| Value | What it does |
| --- | --- |
| `engine.image.repository` / `engine.image.tag` | Engine image; pin a version tag in production |
| `engine.env` | Plain environment for the pods (goes into a ConfigMap) — log level, worker threads, and any non-secret engine settings |
| `engine.secrets` | Provider credentials (`ROCKETRIDE_OPENAI_API_KEY`, …) — rendered into a Kubernetes Secret and referenced from node config as `${VAR}`. Names must start with `ROCKETRIDE_`: the engine resolves only that prefix and replaces any other `${VAR}` reference with the literal `<REDACTED>` |
| `engine.existingSecret` (+ `existingSecretChecksum`) | Use a secret you manage instead of chart-created; bump the checksum on rotation to force a rollout |
| `engine.resources` | Requests/limits (defaults: 250m/512Mi requested, 2 CPU/2Gi limit) |
| `engine.autoscaling` | Built-in HPA (off by default; CPU/memory targets) |
| `engine.gpu` | GPU requests plus GPU node selectors/tolerations |
| `ingress` | Expose the engine beyond the cluster — only behind TLS and auth |

Pods run hardened by default: non-root, read-only root filesystem, all
capabilities dropped.

## Example values files

Four ready-made examples under
[`deploy/helm/examples/`](https://github.com/rocketride-org/rocketride-server/tree/develop/deploy/helm/examples)
show the common setups:

- **`external-postgres.yaml`** — wire the engine to an external Postgres:

  ```bash
  helm install rocketride deploy/helm/rocketride/ -f deploy/helm/examples/external-postgres.yaml
  ```

- **`external-chroma.yaml`** — external Chroma vector store.
- **`gpu-values.yaml`** — GPU resource requests, node selection, tolerations.
- **`keda-gpu-scaling.yaml`** — autoscale GPU workloads with KEDA instead of
  the built-in HPA (CPU/memory HPA is a poor fit for GPU inference). Not a
  values file — a `ScaledObject` you `kubectl apply` alongside the release.

## Databases are external

The chart deliberately bundles no databases. Point pipelines at your own
Postgres, vector store, or graph database through `engine.env` /
`engine.secrets` — the [production topology page](/operate/self-hosting/production)
covers co-location and sizing.

## Health probes

The chart's default readiness/liveness/startup probes call `/ping` on 5565.
The engine entrypoint, however, starts its web server without the standard
endpoints, so `/ping` is never registered and returns 404 to the kubelet's
probes, which recycles healthy pods. `/version` is always registered and
public. Point all three probes at the version endpoint:

```yaml
engine:
  readinessProbe:
    httpGet: { path: /version, port: 5565 }
  livenessProbe:
    httpGet: { path: /version, port: 5565 }
  startupProbe:
    httpGet: { path: /version, port: 5565 }
```

## Next

- [Docker](/operate/self-hosting/docker): the image itself — tags, signing,
  persistence.
- [Production](/operate/self-hosting/production): topology and sizing.
- [Security](/operate/security): TLS, authentication, and exposure.


---

# Production

Route: /operate/self-hosting/production

---
title: Production
---

# Production

Guidance for running the engine as a production workload. This page grows with
the self-hosting docs; deployment topology is the load-bearing decision today.

## Deployment topology

- **Local**: engine and nodes on the same machine. Zero network latency between
  nodes; API calls to LLM/vector store providers cross the internet normally.
- **Self-hosted**: engine in Docker or Kubernetes, co-located with vector store.
  Reduces vector store latency significantly.
- **Cloud**: managed engine. Best for production — automatic scaling, managed
  auth, no infrastructure to operate.

For high-throughput workloads, run the vector store and embedding service on the
same network as the engine to minimise round-trip latency on the embedding and
upsert steps.

## Related

- [Self-hosting overview](/operate/self-hosting): install and run the engine.
- [Security](/operate/security): credentials, ports, and TLS before you expose anything.
- [Performance](/guides/performance): tuning levers inside the pipeline.


---

# Glossary

Route: /reference/glossary

---
title: Glossary
---

# Glossary

Terms used across the RocketRide docs.

## Pipeline

A directed graph of [components](#component--node) that moves and transforms
data, authored as a [`.pipe`](#pipe-file) file. The unit of work in RocketRide.
See [Pipelines](/concepts/pipelines).

## Component / node

One vertex of the pipeline graph: a single unit that does one job (call a model,
embed text, query a store, run a tool). Has a unique `id`, a
[provider](#provider), and `config`. See
[Nodes](/concepts/nodes).

## Provider

What a component _is_: the value that determines its behaviour (e.g.
`llm_openai`, `qdrant`, `webhook`). Swapping providers is a config change, not a
code change.

## Connector

A [node](#component--node) at the edge of the graph that reads from or writes to
an external system: a **source** (brings data in) or a **target** (sends results
out).

## Class type

The category a provider belongs to (`llm`, `tool`, `agent`, `memory`, `store`,
`source`, `target`, …), which governs how the node is wired.

## Data lane

A typed channel carrying data between nodes (`questions`, `answers`, `text`,
`image`, …). A node's `input` declares which lanes it consumes and from where.
See the [Execution model](/concepts/execution-model).

## Control (invoke) connection

A side-channel connection by which an [agent](#agent) invokes a helper (LLM,
tool, memory) instead of streaming data through a lane. Declared as `control` on
the helper, pointing back at the invoker.

## Agent

A node that reasons in a loop, choosing which model to call and which tools to
use, over one or more **waves** until it produces a result. See
[Agents & tools](/concepts/agents-tools-skills).

## Tool

A capability an agent can invoke at runtime (HTTP request, web search, shell,
another pipeline). Tools have no data lanes; they are wired by `control`.

## Memory

State an agent carries across turns (`memory_internal`, `memory_persistent`).
Only `agent_rocketride` has a memory port.

## Engine

The multithreaded C++ runtime that loads a [`.pipe`](#pipe-file), instantiates
its nodes, and streams data through the graph. Runs locally, [self-hosted](/operate/self-hosting),
or on [Cloud](/operate/cloud). See [Runtime & engine](/concepts/runtime-engine).

## `.pipe` file

The JSON file that defines a pipeline, conforming to the
[Pipeline JSON Reference](/reference/pipeline-reference). The same file runs unchanged in
every environment.

## Task

A single running instance of a pipeline on the engine, identified by a token and
controlled over the [WebSocket protocol](/connect/websocket).

## MCP

The Model Context Protocol: exposes running pipelines as tools for AI
assistants. See [MCP](/connect/mcp/stdio).

## WebSocket protocol

The engine's native protocol (port 5565) that SDKs and the MCP server use to
start pipelines and stream results. See [WebSocket](/connect/websocket).


---

# Pipeline JSON Reference

Route: /reference/pipeline-reference

---
title: Pipeline JSON Reference
slug: /reference/pipeline-reference
---

# Pipeline JSON Reference

A `.pipe` file is JSON conforming to the interfaces below. The schema is the
contract the [engine](/concepts/runtime-engine) loads and the SDKs send over
the [WebSocket protocol](/connect/websocket) — the same JSON whether you
author it visually or by hand. For the concepts behind these fields, see
[Pipelines](/concepts/pipelines) and the [Execution model](/concepts/execution-model).

## Top-level shape

A pipeline is an object with a `components` array (the nodes of the graph) and,
when agents or other invokers are involved, a `control` array describing the
invoke connections. Each component declares its `id`, `provider`, `config`, and
the input lanes it consumes.

```json
{
  "components": [
    { "id": "in", "provider": "webhook", "config": {} },
    {
      "id": "out",
      "provider": "response",
      "config": { "laneName": "text" },
      "input": [{ "lane": "text", "from": "in" }]
    }
  ]
}
```

## Interfaces

The definitions below are generated from the `.pipe` schema types in
`packages/client-typescript/src/client/types/pipeline.ts`; a `.pipe` file is JSON
conforming to them.

## PipelineInputConnection

Data flow connection between pipeline components.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lane` | `string` | Yes | Data lane/channel name (e.g., 'text', 'data', 'image') |
| `from` | `string` | Yes | Source component ID providing the data |

## PipelineControlConnection

Invoke (control-flow) connection from one component to another.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `classType` | `string` | Yes | Class type of the invoke channel (e.g., 'llm', 'tool', 'memory') |
| `from` | `string` | Yes | Source component ID providing the invocation |

## PipelineComponent

Pipeline component that processes data. Each component has a unique ID, a provider type that determines its behavior, and provider-specific configuration. Components receive data through input connections from other components.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | Unique identifier for this component within the pipeline |
| `provider` | `string` | Yes | Component type/provider (e.g., 'webhook', 'response', 'ai_chat') |
| `name` | `string` | No | Human-readable component name |
| `description` | `string` | No | Component description for documentation |
| `config` | `Record<string, unknown>` | Yes | Component-specific configuration parameters |
| `ui` | `Record<string, unknown>` | No | UI-specific configuration for visual editors |
| `input` | `PipelineInputConnection[]` | No | Input connections from other components |
| `control` | `PipelineControlConnection[]` | No | Invoke (control-flow) connections from other components |

## PipelineConfig

Pipeline configuration for RocketRide data processing workflows. Defines a complete pipeline with components, data flow connections, and execution parameters. Pipelines process data through a series of connected components that transform, analyze, or route information.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | No | Human-readable pipeline name — the registry's pipelineName renders it on every deploy surface, and publish requires it. |
| `description` | `string` | No | Pipeline description |
| `version` | `number` | No | Pipeline version number |
| `components` | `PipelineComponent[]` | Yes | Array of pipeline components that process data |
| `source` | `string` | No | ID of the component that serves as the pipeline entry point |
| `project_id` | `string` | No | Project identifier for organization and permissions |
| `viewport` | `{ x: number; y: number; zoom: number }` | No | UI viewport settings for visual editors |
| `docRevision` | `number` | No | Editor document revision counter for change tracking (undo/redo, echo detection). |
| `isLocked` | `boolean` | No | Whether the canvas is locked from editing |
| `snapToGrid` | `boolean` | No | Whether node snapping to grid is enabled |
| `snapGridSize` | `[number, number]` | No | Grid size for snapping [x, y] |
| `editorMode` | `string` | No | Active editor mode (e.g. 'design', 'status', 'flow') |


---

# Contributing

Route: /support/contributing

---
title: Contributing
---

# Contributing

RocketRide is MIT-licensed and developed in the open at
[rocketride-org/rocketride-server](https://github.com/rocketride-org/rocketride-server).
There are more ways in than writing C++ — pick the one that fits:

| I want to… | Start here |
| --- | --- |
| Report a bug or request a feature | [Issue templates](https://github.com/rocketride-org/rocketride-server/issues/new/choose) |
| Improve these docs | [Improve the docs](#improve-the-docs) |
| Add an example | [Docs & examples](#improve-the-docs) |
| Build a new node | [Build a node](#build-a-node) |
| Work on the engine, SDKs, or protocol | [Contribute code](#contribute-code) |
| Help other users | [GitHub Discussions](https://github.com/rocketride-org/rocketride-server/discussions), [Discord](https://discord.gg/PMXrtenMsY) |

All participation falls under the
[Code of Conduct](https://github.com/rocketride-org/rocketride-server/blob/develop/CODE_OF_CONDUCT.md).

## Report bugs & request features

Use the
[issue templates](https://github.com/rocketride-org/rocketride-server/issues/new/choose)
— the [Get Help page](/support/get-help#before-you-ask) lists what to include
so a report lands in one round-trip. **Security vulnerabilities are the
exception:** report them privately via
[GitHub Security Advisories](https://github.com/rocketride-org/rocketride-server/security/advisories/new)
or security@rocketride.ai, never as a public issue
([security policy](/support/security-policy)).

## Every change starts with an issue

Every pull request must be linked to an issue (`Fixes #123` — enforced by
CI), and branch names embed the issue number. The difference is how long to
wait:

- **Docs and examples**: open the issue and PR right away — no discussion
  needed.
- **New nodes, engine core, and protocol changes**: open the issue first and
  get a nod before building. It protects your time — a node or engine change
  that conflicts with platform direction is hard to accept after the fact.

## Improve the docs

Docs live in the same repo as the code, under
[`docs/`](https://github.com/rocketride-org/rocketride-server/tree/develop/docs)
— what you're reading is built from `docs/public/`. Two things to know:

- Some content is **generated** (node parameter tables, SDK references,
  package README copies) — regenerated by the build, never edited by hand.
  Hand-written prose is fair game.
- Validate before you push: `node scripts/build.js docs:build` builds the
  site with a broken-link gate, and `./builder docs:check` catches generated
  drift.

Prose fixes are the easiest first contribution there is.

## Build a node

Nodes are self-contained Python packages under
[`nodes/src/nodes/`](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes)
— most of the [node catalog](/nodes) was built with the same contract you'd
use. Open an issue describing the node first (see above), then follow the
contributor guides in the repo:

- [Node authoring](https://github.com/rocketride-org/rocketride-server/tree/develop/docs/development/nodes)
  — the README and `services.json` contracts, and the catalog.
- Contract tests: `./builder nodes:test`, plus
  `python3 scripts/validate-node-readme.py <node-dir>` for the README.

## Contribute code

1. Fork, then branch off `develop`. Branch names follow
   `<type>/RR-<issue>-<short-description>` (e.g.
   `fix/RR-123-sql-injection-prevention`) — a ruleset enforces this.
2. Read
   [AGENTS.md](https://github.com/rocketride-org/rocketride-server/blob/develop/AGENTS.md)
   — the repo's contributor guide — and
   [`docs/development/`](https://github.com/rocketride-org/rocketride-server/tree/develop/docs/development)
   for setup, builder usage, and engine internals.
3. Build and test with the builder: `./builder build`, `./builder test`.
4. Use conventional commits (`feat(scope):`, `fix(scope):`, `docs(scope):`).

The repo's
[CONTRIBUTING.md](https://github.com/rocketride-org/rocketride-server/blob/develop/CONTRIBUTING.md)
is the canonical process reference.

## Review

Pull requests target `develop`. CI runs the build, the test suites, and the
docs gates; a maintainer reviews from there. Unsure whether something is worth
building? Ask first in
[Discussions](https://github.com/rocketride-org/rocketride-server/discussions)
— a five-minute conversation beats a closed PR.


---

# FAQ / Get Help

Route: /support/get-help

---
title: FAQ / Get Help
---

# Get Help

## Where to ask

| You need | Go to |
| --- | --- |
| A question answered | [GitHub Discussions](https://github.com/rocketride-org/rocketride-server/discussions), [Stack Overflow (`rocketride`)](https://stackoverflow.com/questions/tagged/rocketride), or [Discord](https://discord.gg/PMXrtenMsY) |
| To report a bug | The [bug report template](https://github.com/rocketride-org/rocketride-server/issues/new/choose) |
| To request a feature | The [feature request template](https://github.com/rocketride-org/rocketride-server/issues/new/choose) |
| To report a security vulnerability | **Privately only**: [GitHub Security Advisories](https://github.com/rocketride-org/rocketride-server/security/advisories/new) or security@rocketride.ai — never a public issue. See the [security policy](/support/security-policy). |

Support questions opened as issues get converted to Discussions — starting
there is faster.

## Before you ask

Bug reports that include these get answered in one round-trip instead of
three:

- Engine version and how it runs (VS Code local, Docker, Cloud, self-hosted)
- Client and version (Python/TypeScript SDK, CLI, VS Code extension, MCP)
- The smallest `.pipe` that reproduces the problem
- The exact error text, and the output of `validate()` /
  `validate_pipeline` on your pipeline
- What you expected instead

## Frequently asked questions

### I can't connect — connection refused. Is the engine down?

Nothing is listening on the URI you're pointing at. Start a local engine (the
[VS Code extension](/clients/vscode) or a
[self-hosted container](/operate/self-hosting) on port 5565), or set
`ROCKETRIDE_URI` to your Cloud endpoint. Details:
[Troubleshooting](/support/troubleshooting).

### I get 401 / Unauthorized against Cloud — which variable do I set?

Set `ROCKETRIDE_APIKEY`. `ROCKETRIDE_AUTH` is read only by the MCP servers,
not by the SDKs or CLI. See the
[configuration pages](/clients/python/configuration) for the full environment
table.

### My MCP client gets a 401 — is the server broken?

No — that's the OAuth discovery flow working as designed: the client follows
the `WWW-Authenticate` header to the login. If your client can't do OAuth,
send an `rr_` API key header instead. See the
[MCP connection FAQ](/connect/mcp/http/connect#faq).

### The pipeline runs but nothing comes back.

Match the method to the pipeline's source node: a `chat` source answers
`chat()`, a webhook/dropper source answers `send()` / `pipe()`. Also check
you're not reusing a stale task token.
[Troubleshooting](/support/troubleshooting) walks through it.

### How do I catch pipeline errors before running?

`validate()` in the SDKs — or the `validate_pipeline` MCP tool — runs the
engine's own validator server-side without starting a task. See
[Running Pipelines](/clients/python/pipelines).

### What does "Lane mismatch / lane not supported" mean?

The output lane of one node must match an input lane the next node accepts.
Check both ends against the [node catalog](/nodes) and the lane table on
[Execution Model](/concepts/execution-model).

### Which API key goes where — `rr_` vs `tk_`/`pk_`?

`rr_` account keys authenticate the SDKs and MCP. Task-scoped `tk_`/`pk_`
keys control a single task and are refused at the MCP endpoint; `pk_` is the
task's public key, seen in dropper/upload URLs and webhook Bearer
credentials. See
[MCP authentication](/connect/mcp/http/connect#authentication).

### How do I set up credentials for an integration node?

Call the `list_integrations` MCP tool — bare for the status of every
integration, with a `name` for field detail and the suggested environment
variables. Values never transit MCP; wiring uses `${VAR}` placeholders. See
[its reference entry](/connect/mcp/http/tools#list_integrations).

### Why are my replayed traces empty?

The run started with `pipelineTraceLevel: 'none'` — chapters and console
output survive, traces don't. Start with `summary` (or `full` when
debugging). See [run logs](/clients/python/logs) and the
[MCP replay tools](/connect/mcp/http/tools#replay-past-runs).

### How long are run logs kept?

7 days for dev runs, 30 days for deployments, on a bounded log ring —
evicted earlier under storage pressure. See [run logs](/clients/python/logs).

### My pipeline stopped by itself after ~15 minutes.

That's the idle TTL — the VS Code default is 900 seconds. Pass `ttl: 0`
("run forever") for long-lived pipelines and terminate them yourself. See
[VS Code usage](/clients/vscode/usage) and
[Running Pipelines](/clients/python/pipelines).

### My agent pipeline won't start.

Agent helpers wire via `control` connections, and each agent node has
requirements — `agent_rocketride` needs exactly one LLM and one memory node.
See [Troubleshooting](/support/troubleshooting) and
[Agents & Tools](/concepts/agents-tools-skills).

### Is my connection to Cloud encrypted?

Only if you ask for it: `http://`, `ws://`, or a bare `host:port` URI runs
unencrypted. Always use `https://` / `wss://` against Cloud. See
[Troubleshooting](/support/troubleshooting).

### The response is empty, or under a key I didn't expect.

A `response` node with a custom `laneName` puts the result under that key;
read the result's `result_types` to see which key carries which lane. See
[Troubleshooting](/support/troubleshooting).

Didn't find your problem? [Troubleshooting](/support/troubleshooting) covers
errors in depth — and the channels at the top of this page are watched.


---

# Release Notes

Route: /support/release-notes

---
title: Release Notes
description: What shipped in each RocketRide release, generated from GitHub releases.
format: md
---

# Release Notes

Stable releases of every RocketRide component, generated from [GitHub releases](https://github.com/rocketride-org/rocketride-server/releases)
at build time — newest first. Components version independently, so entries interleave.

## RocketRide Server v3.3.1

**Server** · v3.3.1 · July 7, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.3.1)

### ⚠ Breaking Changes: Client SDKs (`rocketride` / `rocketride-python`)

These changes affect code that imports and calls the Python or TypeScript client SDKs directly. The old `connect()` / `disconnect()` signatures are preserved as backward-compatible wrappers, but callers should migrate to the new layered API.

#### Connection API (both SDKs)

| Before (1.0.x) | After (1.1.0) | Notes |
|---|---|---|
| `connect(auth?, uri?, timeout?)` → `void` | `connect(credential?, { uri?, timeout? })` → `ConnectResult` | Now returns full user identity (userId, organizations, apps, teams). The `auth` param is renamed `credential` to reflect that it accepts API keys, Zitadel access tokens, and `rr_*` user tokens. Old positional `auth`/`uri` kwargs still accepted but deprecated. |
| `disconnect()` → `void` | `disconnect()` → `void` | Signature unchanged; internally calls `logout()` + `detach()`. |
| *(not available)* | `attach(uri?)` → `void` | Opens the WebSocket **without** authenticating. Required for public/unauthenticated operations like catalog browsing. |
| *(not available)* | `login(credential?)` → `ConnectResult` | Sends the DAP `auth` command over an attached transport. Supports credential rotation (auto-logout if credential differs). |
| *(not available)* | `logout()` → `void` | Sends new `deauth` DAP command, reverts the connection to unauthenticated without closing the socket. |
| *(not available)* | `detach()` → `void` | Tears down the WebSocket and cancels the reconnect engine. |
| `isConnected()` | `isConnected()` *(unchanged)* | Returns `true` only when both attached **and** authenticated. |
| *(not available)* | `isAttached()` | `true` when the WebSocket is open, regardless of auth state. |
| *(not available)* | `isAuthenticated()` | `true` when the auth handshake has succeeded on the current connection. |

**Reconnection engine rewritten**: the old flag soup (`_manualDisconnect`, `_authRejected`, `_didNotifyConnected`) is replaced by a `_desiredState` model (`'detached'` | `'attached'` | `'authenticated'`). Linear backoff (250ms increments, 15s cap) replaces exponential backoff, reconnection now **never gives up**. `maxRetryTime` is accepted for backward compatibility but **ignored**.

#### Python-specific breaking changes

- **`async with` context manager removed**: `__aenter__` / `__aexit__` are deleted. Replace `async with RocketRideClient(...) as client:` with explicit `await client.connect()` / `await client.disconnect()` in a try/finally.
- **`connect()` now returns `ConnectResult`**: previously returned `None`. Callers that did `await client.connect()` without capturing the result are unaffected; callers that typed the return as `None` will need to update.
- **`use()` no longer substitutes `${ROCKETRIDE_*}` client-side**: the raw pipeline is sent to the server, which handles all variable resolution via `get_merged_env()`. If you were relying on client-side `.env` interpolation, variables must now be set server-side (via the Variables page or `client.account.set_env()`).
- **Event type renames**: `EVENT_STATUS_UPDATE` → `EVENT_STATUS`; `EVENT_TASK` → split into `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART`. Code that imports the old names will get `ImportError`.
- **`auth` credential removed from transport layer**: `TransportWebSocket` no longer stores or exposes `auth`. Auth is exclusively managed by the `ConnectionMixin` / `RocketRideClient` layer.

#### TypeScript-specific breaking changes

- **`connect()` signature changed**: old: `connect(options?: number | { uri?, auth?, timeout? })` → `void`. New: `connect(credential?, options?: { uri?, timeout? })` → `Promise<ConnectResult>`. The `auth` property inside options is removed; pass the credential as the first argument. The numeric-only shorthand `connect(5000)` is removed.
- **`DataPipe` errors changed from `Error` to `PipeException`**: `open()`, `write()`, and `close()` now throw `PipeException` (extends `Error`) instead of plain `Error` when the server reports a failure. Callers catching `Error` are still compatible; callers matching on error message strings may need to update. `PipeException` carries the full DAP response body.
- **`setConnectionParams()` removed**: use `login(credential, { uri })` or call `attach(newUri)` + `login()` instead.
- **Project store methods removed**: `saveProject()`, `getProject()`, `deleteProject()`, `getAllProjects()` are deleted. Use the new filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`.
- **`validate()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ValidationResult` (typed interface with `valid`, `errors`, `warnings` fields).
- **`getServices()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ServicesResponse` (typed interface).

#### Both SDKs: new exception types

- **`PipeException`** (Python: subclass of `RuntimeError`; TypeScript: subclass of `Error`): thrown by `DataPipe.open()`, `.write()`, `.close()` when the server reports failure. Carries the full DAP response including `message`, `body`, and error code. Replaces generic `RuntimeError` / `Error`.
- **`ConnectionException`** (TypeScript): thrown on transport-level failures.

### Added

#### New Nodes
- **Exa Search**: semantic web search node integrating with the Exa API (exa.ai) for real-time data enrichment in pipelines. Agents invoke the tool to search the web and retrieve structured results including titles, URLs, text content, relevance scores, and published dates. Includes configurable `numResults` with min/max validation, retry exception sanitization to prevent API key leakage, and defensive boolean config parsing (#386, #509)
- **Bland AI**: voice call tool node for AI-driven phone calls via the Bland AI platform (#521)
- **OpenAI Compatible**: generic LLM node supporting any OpenAI-compatible API endpoint, allowing connection to self-hosted or third-party inference servers that follow the OpenAI chat completions API (#518)
- **GMI Cloud**: LLM connector for GMI Cloud inference platform (api.gmi-serving.com) hosting 100+ models on H100/H200 GPUs. Two tiers: shared (always-on, key-only: DeepSeek, GPT, Claude, Gemini) and deploy-on-demand (endpoint URL + key: Llama 4, Qwen3). Custom profile for arbitrary model/endpoint combinations (#540)
- **Guardrails**: AI safety node with comprehensive input/output validation. Input: prompt injection detection (regex + keyword scoring), topic restriction (allowed/blocked keyword lists), input length enforcement (char + token limits). Output: hallucination detection (sentence-level grounding), content safety (self-harm, violence, illegal activity patterns), PII leak detection (email, phone, SSN, credit card, IP), format compliance (JSON, markdown, bullet/numbered lists). Policy modes: block/warn/log. Profiles: basic (injection + PII), strict (all checks), custom. 87 tests (#534)
- **Video Embedding**: extracts frames from video input (MP4, AVI, MOV, WebM) at configurable intervals and generates vector embeddings using CLIP/ViT models for semantic search and RAG pipelines. Configurable frame interval, max frames, start time, duration, and max video file size (default 500 MB) to prevent unbounded memory. VideoCapture resource leak fixed with finally block (#516)
- **Kokoro TTS**: self-contained text-to-speech node using the Kokoro engine. Slim requirements (no piper/transformers/cloud). KokoroLoader, spacy_en_model, wav_to_mp3 utilities. Supports question, answer, and document lanes (RR-411, #662)
- **Telegram Bot**: source node connecting a Telegram bot to a pipeline via long polling or webhook. Routes incoming messages to appropriate lanes by content type (text, image, audio, video, documents) and sends pipeline responses back as replies (#659)
- **GitHub Tool**: tool node for GitHub API operations (issues, PRs, repositories) with full test suite for tool calling (#640)
- **Git Tool**: self-contained Git operations using pygit2 (libgit2), no host git binary required. Capabilities: clone, init, status, log, show, diff, blame, file_at, ls_files, grep, stage, commit, stash, branch create/checkout/merge/delete, fetch, pull, push (token + SSH auth), write_file with path-traversal guard. Safe mode (default on) blocks force-push and force branch deletion. Full unit test suite + integration tests (activated via `GIT_TEST_REPO_PATH` env). Includes `git_agent_example.pipe` (#654, #731)
- **Filesystem Tool**: file system operations (read, write, list, mkdir, delete) with path whitelist security check via `_prepare()` method. Operations can be selectively enabled/disabled at the node level. Shared prologue extraction via keyword flags (path_required, needs_encoding, needs_content) (#682)
- **Pipeline Tool**: run pipelines as tool calls from other pipelines, enabling pipeline composition and hierarchical agent workflows (#647)
- **LLM Vision (Gemini)**: image understanding via Gemini models with cache management (non-symmetric cache + empty frame guard)
- **LLM Vision (OpenAI)**: image understanding via OpenAI vision models
- **Webhook**: question lane support for webhook-triggered pipelines (#431)
- **CrewAI Orchestrator**: multi-agent orchestration via CrewAI framework. Exposes expert config fields (goal, backstory, expected_output, max_iter) for both agent and orchestrator node types. Advanced mode for fine-grained control. Sub-agent config propagated through `crewai.describe()`. Manager node renamed from Orchestrator, tool invoke removed from manager (#608)

#### VS Code Extension
- **Engine management overhaul**: replaced scattered engine lifecycle code (connection/, deploy/) with a clean `EngineBackend` hierarchy under `src/engine/`. Each connection mode (local, service, docker, cloud, onprem) gets its own backend implementation. `EngineRegistry` singleton reconciler detects config changes (API key, host URL, etc.) via checksums and auto-restarts affected engines on settings save. Eliminated `engine:status` event, all progress flows through `shell:statusChange`. `ConnectionManager` becomes passive: connects on engine `ready`, disconnects on `idle`. Unified `ioControl` message pattern for all panel operations. Migration from legacy layout (`globalStorage` + `config.json`) to new structure. Welcome page uses same `applyAllSettings` + reconcile path as Settings (#922)
- **Settings overhaul & target panels**: atomic settings save via `ConfigManager.applyAllSettings()` with `isBatchApplying` flag suppressing intermediate change events (eliminates race conditions from writing 20+ config keys individually, which caused connection managers to react to half-written state). Self-contained panels per mode (Local, Cloud, OnPrem, Docker, Service) handling both configuration and operational UI (status, install/start/stop/remove/update, progress, version selection). `EngineOperations` service extracted from `PageDeployProvider`. Deploy page command redirected to Settings. `useTheme` hook for VS Code dark/light detection. Embedded Docker/Service SVG logos. Build config consolidated: `.config` as single source of truth for Zitadel URLs/client IDs, esbuild loads `.config` first then `.env` on top, stopped name remapping of Zitadel keys. Cloud mode no longer hardcodes a non-existent URL, uses `config.hostUrl` at runtime (#725)
- **Standalone Variables page**: new "Variables" webview accessible from sidebar footer for managing `ROCKETRIDE_*` environment variables per connection slot (Development/Deployment). `EnvironmentProvider` with per-slot client resolution, `EnvironmentWebview` with pill bar for slot selection. OSS servers show single "Server Variables" card; SaaS servers show Organization/Team/User cards gated by permissions. `set_env` now updates `os.environ` in-memory before writing `.env` file. Deploy connection fix: removed `isSharedMode()` guard that skipped engine status listener registration. `commonStyles.tabContent` now uses `border-box` sizing. Removed capabilities filter that hid Cloud option. All "Environment" labels renamed to "Variables"
- **`${ROCKETRIDE_*}` variable autocomplete**: node config fields now offer autocomplete suggestions for defined pipeline variables. `useEnvVarAutocomplete` hook detects `${` trigger and filters keys by partial match. `EnvVarSuggestions` popover with arrow-key navigation. Wired into `BaseInputTemplate`, `TextareaWidget`, and `ApiKeyWidget`. `transformErrors` suppresses RJSF validation errors for fields containing `${ROCKETRIDE_*}`. `rrext_validate` now resolves env vars before validation using the same merged env as pipeline execution. Fixed `getHttpUrl()` to normalize engineUri before parsing
- **Category headers in QuickAddPopup**: compatible services grouped by bold uppercase category headers with indented items. Shared `CATEGORY_TITLES` extracted to `categoryTitles.ts`. `CreateNodePanel` auto-expands matching categories during search, restores previous expand/collapse state when search is cleared. Environment protocol types extracted to prevent build errors
- **Server Monitor panel**: real-time dashboard showing connections, tasks, and aggregate metrics via new `getDashboard()` / `get_dashboard()` SDK methods (DAP `rrext_dashboard` command). Client identification (`clientName`/`clientVersion`) forwarded during auth handshake so server can distinguish "VS Code 0.9.4" vs "CLI 1.2.0". Python DAP client skips auth message when transport lacks `get_auth()` (fixes crash for non-WebSocket transports). Consolidated `ServicePython` log level into `DebugOut` (#595)
- **Other task viewer via ProjectWebview**: `PageStatusProvider` completely rewritten. Previously opened a lightweight `StatusWebview` that couldn't show the node graph (nodes squashed at top, no toolbar, missing servicesJson). Now fetches unresolved pipeline via `getTaskToken` + `getTaskPipeline`, creates panel using the full Canvas/ProjectView stack, sends `project:load` with `isReadonly:true`. Falls back to synthesized single-node project if fetch fails. `StatusWebview` deleted (#803)
- **Readonly canvas**: single `isReadonly` prop replaces two inconsistent lock mechanisms (14-boolean `IFlowFeatures` and partially-implemented `isLocked`). `effectiveLock = isReadonly || internalIsLocked`. Guards added to `addNode()`, `updateNode()`, `deleteNode()`, paste, context-menu, lane click, config panel Save, all previously unguarded. Lock button hidden when `isReadonly` (#803)
- **Save button in canvas toolbar**: always-visible floppy disk icon with dirty-state tracking; grayed when clean, brand-colored when dirty. `isDirty`/`isNew`/`onSave` threaded through `IFlowProps` → `FlowContainer` → `FlowProvider` → `FlowProjectProvider`. `FlowCanvas` defers ReactFlow render until container has non-zero dimensions via `ResizeObserver`. `canvas:requestSave` calls `document.save()` directly (#678)
- **Dirty-state save pattern for settings**: card header starts clean (no buttons); on edit, Cancel and Save appear; on save, buttons disappear and "Saved" flashes for 5 seconds then fades; Cancel reverts to last-saved snapshot. Applied to all 5 VS Code settings tabs and shell-ui settings page (#877)
- **Play button shows actionable text**: renamed idle label from "Play" to "Run Pipeline". Added STOPPING state with "Stopping..." disabled button to prevent double-clicks. Widened hover expansion for longer label. Smooth CSS transitions with easing functions (#575)
- **Improved stop button feedback**: Pipeline Observability screen handles `TASK_STATE.STOPPING` with "Stopping..." disabled state and distinct orange styling, preventing duplicate clicks (#549)
- **Simplified sidebar footer**: replaced popup menu (three redundant gear icons all opening Settings) with flat layout when connection is shared and no cloud account. Documentation and Settings buttons rendered directly, connection status inline, announcements ticker rotates cards every 7 seconds. Full popup preserved for cloud account or independent connections. Panel sash restyled with native `--vscode-sash-hoverBorder` token, widened from 2px to 4px
- **Test Connection button**: available on service/docker/onprem panels via `ioControl('test')`
- **Docker GHCR tag fetching**: global cache for prerelease resolution with 15s timeout on HTTPS requests. Split-button dropdowns with grouped "Recommended" / "All versions" headers. Version metadata persisted per instance lifecycle. Linux package manager auto-detection (apt/dnf/yum/pacman) instead of hardcoded apt-get
- **Version tracking**: persistent `version.local.json`, `version.service.json`, `version.docker.json` files. PID liveness check before preserving `.pid` files during engine dir clear. Guard against phantom installs (missing binary). UAC-cancel fallback and uninstall.ps1 fixes
- **Event naming unification**: all connection events renamed to `shell:*` namespace matching cloud-ui vocabulary. `'event'` → `'shell:event'`, `'connected'` → `'shell:connected'`, `'connectionStateChanged'` → `'shell:statusChange'`, etc. All 10 providers renamed to drop redundant `Page` prefix. All 9 view directories renamed similarly (#803)
- **`.env` file management removed**: ~350 lines of env file handling removed from `ConfigManager` (envFileWatcher, envRawText, parseEnvFile, saveEnvFile, syncSettingsToEnv, etc.). Environment variables for pipeline variable replacement are now managed server-side (layered env in DB). Extension no longer maintains workspace `.env` file. URL resolution consolidated into `ConnectionManager` (per-group, not hardcoded to dev group) (#803)
- **On-demand env loading**: replaced 7 env-specific `AccountView` props with 2 generic callbacks (`onLoadEnv`, `onSaveEnv`) plus `refreshSignal`. Each `EnvScopeCard` requests its own data on mount. Promise-based messaging with 10s timeout. `shell:accountUpdate` as first-class event (no longer filtered from generic stream). Standalone `BillingProvider` deleted; billing is a tab inside Account (#803)
- **Welcome page simplification**: `welcomeDismissed` set automatically on save (no manual checkbox). Works from both Welcome and Settings pages (#803)

#### Shell UI (Web Host)
- **Shell-ui replaces cloud-ui**: new Module Federation host application served by Python `shell` module (`ai.modules.shell`) with public HTTP routes for SPA and all static assets under `/shell/`. Unifies OSS and SaaS into single codebase. Server-side app manifest delivery via `get_public_apps()` / `get_apps_for_user()` on AccountBase. Pre-auth info probe returns public apps for marketplace. Connect response includes authenticated user's full entitled app list (#803)
- **MUI removal**: replaced Material UI with plain CSS/HTML across entire shared-ui package; runtime theme system with light/dark JSON tokens
- **Theme rebrand**: replaced legacy purple (#5900FF) with cyan (#00b9ec) TOKENS palette. Light theme updated to warm-neutral (cream/stone backgrounds instead of pure white) (#803)
- **Theme flash fix**: `index.html` inline script sets `--rr-bg-default` and body background synchronously before React renders. `createShellConfig` reads saved theme from localStorage instead of always defaulting to rocketride-light, eliminating tan background during 1.5s OAuth code-exchange window (#878)
- **Chat module**: host-agnostic chat surface following established module pattern (props-in, callbacks-out, `--rr-*` CSS tokens). `ChatView` (MessageList + ChatInputField), `MessageBubble` (user/bot/system/status with markdown), `MarkdownRenderer` (react-markdown + GFM + syntax highlighting + charts), `ChartRenderer` (chart.js with circular-reference guard), `TypingIndicator` (animated bouncing dots), `useChatMessages` hook (message state + sendMessage + monotonic IDs) (#724)
- **Canvas state persistence**: viewport (zoom/pan), lock state, snap-to-grid, and editor mode now persist in `.pipe` files via `PipelineConfig` schema (TypeScript + Python SDKs). New `isFlowReady` boolean state tracks when all nodes have been rendered/measured by ReactFlow, replacing scattered `setTimeout`/`requestAnimationFrame` workarounds. Centralized `loadCanvas(nodes, edges)` as single entry point for structural canvas changes. Viewport restored on load via `isFlowReady` cycle, falls back to fitView. Spiral search for non-overlapping node placement. `EmptyCanvasPrompt` only shown when `nodes.length === 0 AND isFlowReady` (#670)
- **ProjectView architecture**: decomposed monolithic `modules/flow/` canvas module into composable multi-view project architecture (#670)
- **Style consolidation**: added `buttonPrimarySmall`, `buttonSecondarySmall`, `buttonDangerSmall`, `modalDialog`, `modalHeader`, `modalBody`, `modalFooter` to `commonStyles`. Added `cardHeaderButton`/`cardBodyButton` size modifiers for card contexts. Eliminated `Btn` wrapper component. Account `shared.tsx` trimmed from ~30 to 9 entries. All emojis removed from account UI (#803)
- **Shared connection types**: `ConnectionState` enum, `ConnectionMode`, `IAuthProvider`, `IConnectionManager` interface, `ShellAppEntry`, `ShellConnectionEventMap` with typed payloads for all `shell:*` events. Index signature for app-defined events (#803)

#### Billing, Account & Auth
- **Billing detail**: `BillingDetail` type gains `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart` in both SDKs. Subscription cards show detail grid with plan info. Cancel subscription requires confirmation modal. App display name shown instead of raw appId. Credit grant summary per subscription using `creditLabels` from Stripe metadata (#803)
- **Account/Billing merge**: Billing is now a tab inside Account (2nd pill) via `BillingPanel`. Standalone Billing page and provider deleted
- **Permission enforcement**: frontend computes `isOrgAdmin`/`isTeamAdmin` from profile; action buttons hidden for users without required permissions; `OrganizationPanel` read-only for non-admins; destructive actions go through confirmation modals. Team admin enforcement: must always have ≥1 admin (UI + server guard). Permission key fixed: `'admin'` → `'team.admin'`. `_require_team_admin` queries DB directly instead of stale cache (#803)
- **Team-based task permissions**: replaced all `control.userId == caller.userId` ownership checks with `resolve_task_permissions()` so teammates and org admins can monitor/control each other's tasks. Permission strings (e.g. `'task.control'`, `'task.monitor'`) checked against resolved list (#803)
- **Layered environment secrets**: pipeline variables (`ROCKETRIDE_*`) stored encrypted (Fernet) in database per org/team/user scope, merged server-side during task execution. Merge order: `.env` → org → team → user → caller env. `get_merged_env()` on `AccountBase` with OSS (`.env` only) and SaaS (DB) implementations. `client.use()` `env` param for caller overrides (only `ROCKETRIDE_*` accepted). Client-side `processEnvSubstitution` removed, resolution is server-only (#803)
- **Session keys**: API keys are now true PATs inheriting user identity. `is_session` flag on `ApiKey` model. `ensure_session_key()` on every OAuth login: refreshes 90-day expiry if active, creates fresh key if expired/missing. Session keys cannot be self-revoked. Admin revoke is hard-delete. Housekeeping: keys revoked >30d purged on login. UI shows "Session" / "Interactive login" badge (#803)
- **Scoped PATs**: PATs optionally restricted to single team with explicit permissions. Effective permissions intersected with user's actual permissions at auth time (can never escalate). Optional `team_id` on `ApiKey`. Create key modal: team dropdown + conditional `PermGrid`. Key list shows team scope badge (#803)
- **userToken → userId refactor**: server-side event tenant scoping uses `userId` instead of `userToken`. Fixes bug where two connections from same user with different keys wouldn't see each other's dashboard events (#803)
- **Account UI overhaul**: all card headers use `commonStyles.labelUppercase`. Save button pattern: hidden until dirty, shows [Cancel][Save], "Saved" green text with 5s timer. `ProfilePanel`: single "Organizations / Workspaces" card with nested teams. `TeamsPanel`: Delete moved to list with confirm modal. `PermGrid`: `PERM_DISPLAY` labels, alphabetized, added `task.store`, contrasting text on checked tiles (#803)
- **Client SDK attach/login split**: replace monolithic `connect()`/`disconnect()` with layered API: `attach(uri?)` opens WebSocket without auth (for public APIs like catalog), `login(credential?)` sends DAP auth, `logout()` sends new `deauth` command (reverts to unauthenticated without closing socket), `detach()` tears down WebSocket. Old `connect()`/`disconnect()` preserved as backward-compatible wrappers. Reconnection engine rewritten around `_desiredState` model ('detached' | 'attached' | 'authenticated'). Linear backoff (250ms increments, 15s cap), reconnection never gives up. Auth credential removed from transport layer (#803)
- **Server-driven appStatus**: replaced `subscriptionStatus` with server-computed `appStatus` ('auth' | 'free' | 'unsubscribed' | 'subscribed' | 'trialing' | 'past_due' | 'canceled') and `onDesktop` boolean per app manifest entry. Eliminates client-side reconciliation races (#803)
- **App mode & subscription gating**: `mode` field (free/subscription/paywall) in app manifests. Shell-level subscription gate blocks app iframe until active subscription exists. Desktop app management moved into account identity flow (#803)
- **Token storage hardened**: moved from `localStorage` to `sessionStorage` (cleared when tab closes) addressing CodeQL "Clear text storage of sensitive information" alert (#803)

#### Profiler
- **DAP-based cProfile system**: replaced HTTP-endpoint profiler module with per-process cProfile profiling over DAP connections. Any connected client can profile any process (task server, data engine subprocesses, model server). `CProfileManager` singleton with start/stop/status/report/release API. Owner tracking per connection with disconnect cleanup. SDK methods: `cprofileStart`/`cprofileStop`/`cprofileStatus`/`cprofileReport` (TS + Python) with optional `target` parameter for pipeline profiling. New `profiler-ui` Module Federation remote app with `ProfilerView`, `ConnectionManagerView`, and `ProfilerSidebar` (#803)

#### Module Federation
- **MF stability**: added `runtime: false` to all remote apps (shell-ui provides shared runtime; without it each remote embeds its own runtime copy, causing remoteEntry.js to change on every rebuild and version-mismatch errors during HMR). Added `eager: true` to react/react-dom shared configs (breaks async shared-scope negotiation deadlock where host waits for remote's async chunk and remote waits for host). App loader filters out server-only entries with no `remoteEntry` URL (prevents `normalizeRemote()` crash on `undefined`) (#877)

#### Engine & Core
- **Database EXECUTE**: direct SQL/Cypher execution via `QuestionType.EXECUTE` with `client.database.query()` namespace on both SDKs, bypassing LLM translation and safety gating. Gated behind opt-in `allow_execute` config (default off). Results bounded with `fetchmany(max_execute_rows+1)` (default 25000). Neo4j results capped at same limit. `allow_execute` parses strings strictly: only `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive). EXECUTE output wrapped in try/except; serialized with `default=str`. SDK validates non-empty token/sql before dispatching
- **Database DIALECT**: `QuestionType.DIALECT` for engine capability discovery. SDK callers can ask which engine a database pipeline is connected to (`DatabaseDialect` enum). `_db_dialect()` abstract method on `DatabaseInstanceBase`. `services.json` now exposes UI-toggleable `allow_execute` boolean
- **Handle-based streaming I/O**: generic filesystem-style interface (`open`/`read`/`write`/`close`/`delete`/`stat`/`mkdir`/`list_dir`) on `FileStore`, replacing monolithic in-memory buffering. Domain methods become thin convenience wrappers on client SDKs. Supports S3 multipart upload (5 MB buffer), Azure staged blocks (4 MB buffer), and local filesystem. Handles tagged with owning `connection_id` and force-closed on connection termination (#600)
- **`@tool_function` decorators**: collapsed the two-class pattern (IInstance + ToolsBase driver) into a single class. Any `IInstanceBase` subclass can declare tool entry points with a decorator; the method name becomes the tool ID, decorator carries schema/description, base class `invoke()` dispatches automatically. Eliminates parallel driver classes, factory methods, and boilerplate delegation (#599)
- **Experimental + Deprecated capability flags**: `DEPRECATED = BIT(15)`, `EXPERIMENTAL = BIT(16)` in `PROTOCOL_CAPS`. Both flags wired through C++ parser, pybind11 bindings, both client SDKs, and shared-ui. Yellow "EXPERIMENTAL" badge rendered on canvas nodes, Add Node slider, and Quick Add popup (#606)
- **Docker-compose and healthcheck**: `HEALTHCHECK` instruction in `Dockerfile.engine` using curl to `/ping`. `docker-compose.yml` with engine, PostgreSQL+pgvector, Milvus (+ etcd, MinIO), ChromaDB. Override file for dev hot-reloading. All images pinned to specific versions. Security warnings in `.env.example` (#496)
- **Billing commands mixin**: `BillingCommands` in TaskConn's MRO for `rrext_account_billing`. OSS implementation routes on `arguments.subcommand` with stubs so UI doesn't hang in half-rendered state (#692)
- **Task engine extraction**: `task_engine` and `cmd_data` extracted as standalone modules (#661)
- **GPU inference billing**: `metrics.resource('gpu')` context manager times inference. `CONST_RATE_GPU_INFERENCE_SECOND` for billing. Custom node counters (`pagesProcessed`, etc.) with configurable rates. All 9 AI model files wrapped with `metrics.counter('gpu_inference_count')` + `metrics.resource('gpu')`. Billing reports include `gpu_inference` and `custom` token fields (#803)
- **Metrics rewrite**: replaced Timer class and `resource()` context manager with flat `MetricsManager`: `timer()`, `add_time()`, `counter()`, `event()`. Thread-safe via single lock. Removed per-pipe `ContextVar`, metrics are per-subprocess. ModelClient auto-records server-reported perf dict (#803)
- **ModelClient refactor**: derived from `RocketRideClient` with `ws_path='/models'` so URI normalization, protocol selection, and auth are handled by SDK. Python SDK gains `ws_path` kwarg. Sync `disconnect()` override for worker thread callers. All 9 model wrappers updated. `get_model_server_address()` simplified to return raw string (#877)
- **Model server DAP namespace**: all model server commands renamed to `rrext_ms_*` prefix (load_model → rrext_ms_load_model, etc.) for disambiguation from core DAP commands (#803)
- **GPU guard**: `install_gpu_guard()` blocks direct torch/tensorflow imports in model server mode; all GPU inference must go through ModelClient RPC (#803)
- **Pipeline error surfacing**: `binder.cpp` sets `completionCode` on Entry when `callMethods` encounters error. `bindings.cpp` exposes `completionError` read-only property. `data_conn.py` rewrites `close_sync()` to always extract results even when end/close throws, surfaces `Entry.completionError` when `objectFailed` is True. Errors now reach dropper UI (#803)
- **`rrext_get_pipeline` DAP command**: returns task's unresolved pipeline (with `${...}` placeholders intact) so VS Code can reconstruct node graph without exposing secrets. `_build_task()` now accepts explicit resolved pipeline, `self._pipeline` retains original unresolved form (#803)

#### Client SDKs: New Features

**Layered connection API (both SDKs):**
- `attach()` / `detach()`: open/close the WebSocket without authentication. Enables unauthenticated operations (public catalog browsing, server probes) before the user logs in
- `login()` / `logout()`: authenticate/deauthenticate over an attached transport. `login()` returns `ConnectResult` with full user identity (userId, organizations, apps, teams, permissions). `logout()` sends new `deauth` DAP command, reverting to unauthenticated without closing the socket. Supports credential rotation (auto-logout if a different credential is supplied)
- `connect()` / `disconnect()` preserved as backward-compatible wrappers (`attach` + `login` / `logout` + `detach`), but `connect()` now returns `ConnectResult` instead of void
- `isAttached()`: true when WebSocket is open (regardless of auth)
- `isAuthenticated()`: true when auth handshake has succeeded

**Namespaced API accessors (both SDKs):**
- `client.account`: profile, API keys, org, members, teams, environment variables (`get_env()` / `set_env()` / `get_environment_keys()`)
- `client.billing`: subscriptions, checkout, credits, cancel
- `client.database`: `client.database.query()` for direct SQL/Cypher execution; `client.database.dialect()` for engine discovery (`DatabaseDialect` enum)

**New methods:**
- `RocketRideClient.getServerInfo(uri)` (static): probe a server for capabilities without authenticating. Returns `ServerInfoResult` with version, capabilities, platform, and public apps
- `getTaskToken(projectId, source)`: resolve a running task's session token
- `getTaskPipeline(token)`: retrieve the unresolved pipeline for a running task (placeholders intact, no secrets)
- `getDashboard()`: real-time server dashboard (connections, tasks, metrics)
- `cprofileStart/Stop/Status/Report`: per-process cProfile profiling over DAP
- `call(command, token?, **kwargs)` (Python): single public entry point for all typed DAP operations with optional `on_trace` callback

**TypeScript-specific additions:**
- `wsPath` config option for custom WebSocket paths (e.g. `'/models'` for model server)
- `onTrace` callback for observing all `call()` traffic
- `MonitorKey` type and `addMonitor()` / `removeMonitor()` for reference-counted monitor subscriptions
- `restart()` method for restarting pipeline tasks
- Filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`: replaces the old project store methods
- `getTaskStatus()` applies default 15s timeout (configurable via `options.timeout` or `{ timeout: false }`)
- `validate()` now returns typed `ValidationResult` (was `Record<string, unknown>`)
- `getServices()` now returns typed `ServicesResponse`; `getService()` returns `ServiceDefinition`
- `DataPipe.open()` sets `_opened` only after successful SSE setup with rollback on failure
- `normalizeUri()` preserves user-specified port (was being stripped for scheme-default ports like :443)

**Python-specific additions:**
- `ws_path` kwarg for custom WebSocket paths
- `client_name` / `client_version` kwargs forwarded in auth handshake for client identification
- `on_trace` callback for observing all `call()` traffic
- `public` mode for permanently unauthenticated connections (only `rrext_public_*` commands)
- `DashboardMixin`, `CProfileMixin`, `StoreMixin` added to MRO
- Improved `send()` pipe error context with `PipeException` (catchable as `RuntimeError`)

**New types (both SDKs):**
- `ConnectResult`, `ServerInfoResult`, `AppManifestEntry`, `StripePriceEntry`
- `AccountProfile`, `AccountOrganization`, `AccountOrgTeam`, `ApiKeyRecord`, `OrgDetail`, `MemberRecord`, `TeamRecord`, `TeamDetail`, `TeamMemberRecord`
- `BillingDetail` (extended with `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart`, `credits`, `creditLabels`), `StripePlan`, `CreditBalance` (extended with `labels`), `CreditPack`
- `PROTOCOL_CAPS` enum with all 17 capability flags
- `SERVICE_DEFINITION`, `SERVICES_RESPONSE`, `VALIDATION_ERROR`, `VALIDATION_RESULT`
- `DASHBOARD_OVERVIEW`, `DASHBOARD_MONITOR`, `DASHBOARD_CONNECTION`, `DASHBOARD_TASK`, `DASHBOARD_RESPONSE`, `DASHBOARD_EVENT` and 7 event subtypes
- `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART` (replace old `EVENT_TASK`)
- `EVENT_STATUS` (replaces `EVENT_STATUS_UPDATE`)
- `TASK_TOKENS` extended with `gpu_inference` and `custom` fields
- `CreateKeyParams` accepts optional `teamId` for scoped PATs
- `EVENT_TYPE.DASHBOARD` flag (bit 7) for server-level events; `EVENT_TYPE.ALL` updated to include it
- **Config**: `Config.getNodeConfig()` emits warnings for deprecated profiles with migration guidance from profile's `migration` field

#### MCP
- **MCP Resources and Prompts**: `rocketride://` URI resources (pipeline list, server status, node registry) with graceful error handling for disconnected clients. Three prompt templates (analyze-document, chat-with-data, evaluate-pipeline) with required argument validation and message rendering. 44 tests (#541)

#### Agents & Pipelines
- **Agent framework overhaul**: ProjectView architecture with shared-ui migration (#670)
- **Example pipeline templates** for common AI workflows (#572)

#### Build System
- **Rsbuild upgrade**: all UI apps upgraded from pinned 0.4/1.1 to ~1.7.5, eliminating Node.js `DEP0180` deprecation warnings in Node 22+. ESM config migration (`.ts` → `.mts`). cmake minimum bumped from 3.14 to 3.19. `@rspack/binding-*` platform pins removed. Service config renamed `config.json` → `service-config.json` with migration (#905)
- **Build-input caching**: source fingerprinting (`buildInputHash()` + `hasBuildInputChanged()`) skips UI modules whose inputs haven't changed. `appModule.js` factory eliminates ~80 lines of boilerplate per app. Shell-ui tracks own src/ + shared-ui/src + package.json. `--force` flag bypasses caching. Clean actions clear cached hashes (#877)
- **Builder CLI**: `server:run` action (build + run without shell-ui dev server). `--taskserver=ADDR` replaces `--testport`. `--modelserver` semantics clarified (bare flag = start local, `=ADDR` = use existing). `--simulate-gpus=N` forwarded to model server. `parseServerAddress()` utility (#803, #877)

#### CI/CD
- **Cosign container signing**: keyless signing of rocketride-engine image via Sigstore + GitHub OIDC (signs by digest). GPG detached-signature step for server tarballs/zips, gated on `GPG_SIGNING_KEY` secret (#798)
- **Dependabot**: weekly version updates with smoke tests for litellm and pipeline-node deps. Blocked rsbuild/rslib/rspack 0.x churn and pip major bumps. Semver-major ignores across all 10+ ecosystems (#788, #843, #842, #862)
- **Experimental-release workflow**: `workflow_dispatch`-only, builds from arbitrary branch under configurable tag suffix. Per-product release jobs. No marketplace publishing. `prerelease: true`. First use case: workshop builds (#848)
- **Nightly prereleases**: initially from stage branch (#631), moved to develop on green CI (#713). `workflow_dispatch` expanded to develop/stage/main (#906)
- **Daily Actions storage cleanup** workflow (#636)
- **Discord notifications**: PRs, issues, discussions with live CI check status and PR state tracking in embed (#612, #614, #638). Duplicate posts on discussion edits prevented (#698). Retry/backoff for webhook calls (#797)
- **Ruff and gitleaks**: pre-commit checks (#722); gitleaks made blocking (#681); `ruff format` applied to all Python files (#723)
- **Sequential builder tests** to isolate cross-suite flakes (#734)
- **cmake 4** support (#807)
- **Actions pinned** to immutable commit hashes (#483)
- **Artifact retention** dropped to 1 day for 0.5 GB storage cap (#779)
- **CodeQL** switched from advanced to default setup (#768)

#### Documentation
- **Observability & tracing**: integration guide documenting how external services consume runtime logs, lifecycle events, and pipeline traces over the WebSocket DAP channel. Wired into all agent stubs (Claude Code, Cursor, Windsurf, Copilot) (#716)
- **Node usage guides**: `db_neo4j` with practical examples (#490), `llm_openai` with provider examples (#493), source connectors (#650)
- **Per-node documentation** overhaul, added and updated docs for each node (#639, #660)
- **Engine**: Tika ExternalParser media tool requirements (#729)
- **Python client**: clarified `send()` sources and `.pipe` usage (#705); updated Python 3.8 → 3.10 references (#657); added `.env.example` (#492)
- **Contributing**: require green CI checks before review (#627)
- **SOC2-ready SECURITY.md**: explicit triage/remediation SLA (critical 7d, high 30d, medium 90d), scanning toolchain documentation (CodeQL, Scorecard, Trivy, Dependabot, secret scanning), quarterly access reviews (#762)
- **Two-person control** on alert dismissals documented (#800)
- **Code of Conduct** (#591)
- **README improvements**: onboarding wording, absolute image URLs, GIFs, Product Hunt badge (#706, #506, #478, #590)

#### Security Policies
- **Workflow permissions**: top-level permissions added to 5 reusable workflows (#790); storage-cleanup narrowed to job-level (#794)
- **Stale lockfile removed**: `packages/client-typescript/pnpm-lock.yaml` deleted, override declared in root (#796)

### Changed

- **LLM provider migration**: all LLM providers migrated to `ai.common.LLMBase` (#719); automated LLM model sync tool fetches models from provider APIs, smoke-tests new ones, merges into `services.json` with smart deprecation and three-source token limit resolution (provider API → OpenRouter → LiteLLM). `modelSource` field tracks discovery origin. Weekly CI workflow opens PR with sync report. `builder models:update` command (#651)
- **llm_gemini model profiles**: added `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-image-preview`; standardized `gemini-2.5-*` dot notation; deprecated profiles retained with migration guidance
- **Removed `llm_vertex` node**: Vertex AI now supported via `llm_gemini`; migrated vision nodes to `LLMBase`; fixed `llm_gemini` API key validation (dropped strict `startsWith('AI')` check, added sub-key fallback for old pipe files where sub-key is `profile.split('_',1)[1]`); fixed `validateConfig` to early-return when apikey is empty (secure fields not decrypted at validate time); removed vertex icon from UI; bumped client-typescript SDK to 1.1.0 (#902)
- **OpenAI models** updated to latest (#503); deprecated Gemini models removed (#500)
- **Service config cleanup**: removed obsolete `input` section from 72 service configuration files (was duplicate of lane declaration, closes #629) (#728)
- **Milvus node**: configurable timeout (default 60s, was hardcoded 20), connection error handling with meaningful messages, bulk insert with configurable batch size (default 50, was one-at-a-time), `_batchUpsertResults()` helper for markDeleted/markActive, timeout on `remove()`, COSINE distance score range [0,2] rescaling documented (#562)
- **Node tests parallelized** with pytest-xdist (#700)
- **Tool input helpers**: `normalize_tool_input()` replaces 4 copy-pasted variants across tool nodes. `require_str`/`require_int`/`optional_str` replace local validators (44 callsites in `tool_github`). `require_str` now raises `ValueError` cleanly on non-string inputs (was `AttributeError`). `require_int` rejects `bool` (an `int` subclass). 41 unit tests (#759, #766)
- **Backward-compat DAP token fallback**: `get_task_token()` checks `arguments.token` first, falls back to `request.token` for older clients (#902)
- **pnpm** pinned via `packageManager` field (#623)
- **Version bump**: all release packages bumped to next minor (server 3.1.2 → 3.2.0, chat/dropper-ui 2.0.1 → 2.1.0, all others 1.0.x → 1.1.0)
- **engines.node** bumped from ≥18.0.0 to ≥20.0.0 (aligns with serialize-javascript@7 requirement and CI reality)
- **Provisioning**: creates Development + Production teams (Production default); `build_api_key` uses random nonce
- **VSCode detection**: chat-ui/dropper-ui changed from `window.parent !== window` to checking for `acquireVsCodeApi` (canonical detection)
- **Lefthook**: sequential mode; disabled colors to fix terminal corruption on Windows

### Fixed

#### Security
- **Critical: RCE**: prevent arbitrary module injection via `/use` endpoint. Added `ALLOWED_MODULES` frozenset whitelist restricting dynamic imports to 10 known service modules. Requests for any other module return 400 (#342)
- **Critical: Injection**: prevent filter expression injection in Milvus vector store (#355)
- **Auth**: require authentication for profiler endpoints; escape HTML output (#362)
- **Env expansion**: restrict `${VAR}` expansion in pipeline configs to allowlisted prefixes (`ROCKETRIDE_`, `PIPELINE_`, `NODE_`, `ROCKET_`); all others replaced with `<REDACTED>` to prevent exfiltration of AWS keys, DB URLs, tokens (#359)
- **Temp files**: use secure temporary file creation in task engine (#356)
- **SQL safety**: switch from blacklist to allowlist approach (#577)
- **Path traversal**: use `pathlib.is_relative_to` checks (#580)
- **Redaction**: expand sensitive field redaction patterns in VS Code logger (#578)
- **Input validation**: add validation/sanitization to LLM chat drivers (#559)
- **Rate limiting**: add rate limiting to `tool_http_request` node (#560)
- **Remote nodes**: improve error handling in remote node execution (#565)
- **Pinned deps**: handlebars + protobufjs via pnpm.overrides (#783)

#### Client SDKs: Fixes
- **Python client**: break drain cycle causing `RecursionError` on disconnect, `_drain_message_tasks` walks each candidate's `_fut_waiter` chain and excludes tasks that transitively await the drainer itself, so the gather can never close back on itself. `dap_client.request()`'s `ConnectionError` handler now uses fire-and-forget `self._transport.disconnect()` instead of `await self.disconnect()` (develop's `disconnect()` is sync-returns-Task). Two regression tests pinning each fix (#792)
- **Python client**: clean pending DAP request on send failure, prevents zombie futures accumulating on flaky connections when the WebSocket drops mid-request (#736)
- **Python client**: align `requires-python` with monorepo target (py310), was still declaring py38 (#491)
- **Python client**: `set_env` now updates `os.environ` in-memory (removes stale `ROCKETRIDE_*` keys, then sets new values) before writing the `.env` file, so `get_env` reflects changes immediately without a server restart. Uses `sys.executable` instead of `sys.argv[0]` for the `.env` file location
- **Python client**: `ws_path` composition uses `parsed._replace` instead of string concatenation to avoid malformed URIs
- **Python client**: popped consumed kwargs (`ws_path`, `client_name`, `env`, etc.) before passing to `super().__init__()` to avoid "multiple values for keyword argument" `TypeError`
- **TypeScript client**: preserve user-specified port in `normalizeUri`, the URL API silently strips scheme-default ports (:443 on https, :80 on http); now checks raw input for explicit `:digits` after the scheme before deciding whether to add default port (#377)
- **TypeScript client**: `DataPipe.open()` sets `_opened` only after successful SSE setup; on `setEvents` failure, rolls back via `close()` so the server pipe is not left half-open. `close()` now also handles the case where server assigned `pipe_id` but `_opened` was never set to true (#704)
- **TypeScript client**: `DataPipe.close()` sets `_opened = false` in the finally block, preventing double-close races
- **TypeScript client**: `connect()` treats empty or whitespace-only `ROCKETRIDE_APIKEY` in the client env snapshot as **unset**, so it does not override constructor-provided auth (#704)
- **TypeScript client**: `getTaskStatus` applies a default per-request timeout of 15s so CI doesn't hang indefinitely on a dead task; callers can pass `options.timeout` (ms) or `{ timeout: false }` to skip (#704)
- **Both clients**: pipe error messages now include common-cause diagnostics (pipeline not running, wrong source type, MIME mismatch) to reduce debugging time
- **SDK connect error callback type** corrected, was typed incorrectly in the TypeScript client (#576)
- **`CreditBalance` type** aligned with backend camelCase wire shape (#714)

#### VS Code Extension
- **Chat webview blank screen**: realigned `view:ready` handshake so chat panel renders after extension reload (#688)
- **Explorer empty-state**: clicking +File/+Folder on empty PIPELINES tree was silent no-op (input row gated on `entries.length > 0`). Now renders input when root-level create is pending. Stale `selectedPath` falls through to root when all entries deleted (#901)
- **Annotation double-click**: annotation nodes advertised "Double-click gear to add content..." but gear was hidden until hover (CSS opacity:0→1), opened on single-click not double-click, and body had no `onDoubleClick`. Added `onDoubleClick` on annotation root, updated placeholder text (#901)
- **Team selector**: cloud team selector not appearing after sign-in because team fetching was embedded inside cached `probeServerInfo()`. Decoupled into separate `fetchCloudTeams()` driven by `useEffect([isSaas, cloudSignedIn])` (#877)
- **Billing app names**: subscription cards showing raw `appId` instead of human-readable name. Added full `apps` manifest prop chain so components build own `appId → app` lookup map (#877)
- **Canvas-played pipelines** now register in sidebar menu (#571)
- **Missing hostname** handled in URI parsing (#530)
- **OSX Python path** for Python-EaaS debugger (#693)
- **Dark mode**: fixed icon and edge visibility in flow builder (#597)
- **UI validation** fixes (#767)
- **Icons and coloring** for Bland, GMI, and trash bin (#634)
- **QuickAdd popup** label copy improved (#679)
- **Product Hunt badge**: converted SVG to PNG (marketplace rejects SVGs)

#### Engine & Nodes
- **LLM**: clear correct `_chat` reference in `endGlobal` across all LLM nodes (#531)
- **Milvus**: apply `retrieval_score_threshold` filter in `searchSemantic` (#726)
- **Database**: bound Neo4j EXECUTE rows; parse `allow_execute` strictly (only '1'/'true'/'yes'/'on')
- **Frame grabber**: user-configured interval was being ignored (#675)
- **Pipeline configs**: error handling for missing configuration files (#544)
- **Mutable defaults**: replaced mutable default arguments with `None` across Python nodes (#582)
- **Chunk scoping**: `_processFullTables` used stale `doc` variable from outer loop and called `Doc()` with invalid constructor params. Fixed to reset `page_content` on chunk itself. Follow-up: fixed score assignment that replaced Doc with float, and first-chunk aliasing that dropped text (#776)
- **Mock truthiness**: `psycopg2`: `isinstance(False, int)` is True, so `isDeleted=False` was matched as LIMIT value (added `not isinstance(p, bool)` guard). `chromadb`: `if limit and ...` treated `limit=0` as falsy (changed to `limit is not None`). `weaviate`: `distance if distance else 1.0` collapsed 0.0 (exact match) to 1.0 (changed to `distance is not None`) (#748)
- **Async safety**: `_message_tasks` set accessed from multiple async contexts without a lock (#535)
- **CLI shutdown**: SIGINT/SIGTERM handlers with proper exit codes (130/143), double-signal force exit, 5s cleanup timeout, idempotent `cleanupClient` via dedup promise, `isCancelled` guards on command actions, `run()`/`main()` shutdown awareness via `awaitShutdown()` (RR-655, #891)
- **setuptools**: bootstrapped alongside wheel for `uv pip compile`, legacy sdists (e.g. `docopt 0.6.2` via kokoro → misaki → num2words chain) need setup.py but uv doesn't supply setuptools when build isolation is off (#871)
- **Cloud port**: corrected from 433 to 443 in `services.json` (#684)
- **LLM providers**: small cleanup across all LLM nodes (#645)
- **Auth token precedence**: URL auth param prioritized over stale sessionStorage token from previous task (#902)
- **AVIReader**: capture errors from background `_data_process` thread and re-raise on `stop()` so pipeline errors surface as task errors (#803)
- **Webhook/Telegram nodes**: removed `server.use('profiler')` calls (profiler module was deleted; these caused "Module 'profiler' is not allowed" crash) (#803)
- **Task auth**: removed early `ValueError` on empty credential that prevented anonymous/no-key OSS connections from reaching auth check (#803)

#### CI/CD
- **Open VSX**: handle 'already published' error in release workflow (#480)
- **Docs-only PRs**: build passthrough so they don't block CI (#607)
- **Flaky tests**: resolve timeouts and hanging in concurrent pipeline tests, shared hardcoded `project_id` caused server-side contention serializing subprocess launches (#561, #877)
- **Discord webhooks**: retry/backoff for webhook calls (#797); prevent duplicate posts on discussion edits (#698)
- **Nightly workflow**: explicit branch check on `workflow_run` trigger (#771); allow `workflow_dispatch` from stage and main (#906)
- **Release tags**: push via `WORKFLOW_PAT` with repo+workflow scope (#774)
- **pytest-xdist race**: all 6 path-traversal test methods shared same `outside.txt` in system temp root; fixed by wrapping `workdir` in per-test tempdir (#872)
- **pnpm-lock.yaml**: restore libc fields (#622); fix lucide-react dependency (#621)
- **CI API key**: use literal `ROCKETRIDE_APIKEY` in Test step instead of secret (#742); match GraphQL github-actions author login (#699)
- **ruff format**: pure whitespace fixes for vision node files that left develop CI red (#902)

#### Tests
- **AI unit-test coverage** grown from 8% to 43% (395 → 945 passing tests). Covers: sql_safety, common/util/validation/table, dap_conn, pipeline_validation, web endpoints, auth middleware, sandbox execution, profiler lifecycle, account/reporter/keystore, all command handlers, data_conn, task_engine state, task_server background loops, transports, task_http, store providers (S3 + Azure), DB base classes, dropper path-traversal guard. Assertions tightened per CodeRabbit review. CodeQL auth-callback URL assertions anchored (#831)
- **Tests realigned** with team-based permissions and metrics rewrite, updated mocks for `teamId`, `organizations`, `resolve_task_permissions`, `tokens.gpu_inference`/`tokens.custom`, renamed `apikey` → `user_id`. Dropped tests for deleted code. Added `test_cmd_public.py` (#870)
- **Node tests**: full improvements and mock cleanup (#687)

### Dependency Updates
- litellm ~1.50 → ~1.83 (#816)
- DOMPurify → 3.4.x (resolves 16 alerts / 8 GHSAs) (#886)
- cryptography pinned to 46.0.7 (#884)
- SQLAlchemy owned at ai layer, pinned ≥2.0,<2.1 (#804)
- Patched via pnpm.overrides:
  - **Routing**: react-router 6.26→6.30.3, @remix-run/router inlined (#914)
  - **Parsers**: ajv@8→≥8.18.0, markdown-it→≥14.1.1, postcss→≥8.5.10, prismjs→≥1.30.0, yaml@1→≥1.10.3 (#915)
  - **Middleware**: koa→≥2.16.4 (3 advisories), qs→≥6.14.2 (#916)
  - **Util/SVG**: svgo@2→≥2.8.1, flatted→≥3.4.2, immutable@5→≥5.1.5, underscore→≥1.13.8 (#917)
  - **Security**: picomatch@2→≥2.3.2, picomatch@4→≥4.0.4, fast-uri→≥3.1.2, serialize-javascript→≥7.0.5 (#890)
  - **Minimatch**: all 4 major lines patched (3→≥3.1.4, 5→≥5.1.8, 9→≥9.0.7, 10→≥10.2.3) (#887)
  - **Core**: undici→≥7.24.0 (6 advisories), lodash→≥4.18.0, lodash-es→≥4.18.0 (#888)
  - handlebars→≥4.7.9, protobufjs→≥7.5.5 (#783)
- Bumped: aiohttp, pygit2 1.15→1.19, soundfile 0.12→0.13, requests, ws 8.19→8.20, postcss 8.5.6→8.5.10, nltk, spacy, spacy-transformers, cymem, murmurhash, preshed, srsly, thinc, psycopg2-binary, pymysql, opensearch-py, npm-production group (adm-zip, tar, lucide-react, dockerode, web-vitals), shared-ui devDependencies (rollup, @types/react, @types/react-dom), cosign-installer, ossf/scorecard-action, gh-actions group (pnpm/action-setup, github/codeql-action, softprops/action-gh-release, dorny/paths-filter)

---

## RocketRide VS Code Extension v1.3.0

**VS Code Extension** · v1.3.0 · July 7, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.3.0)

### ⚠ Breaking Changes: Client SDKs (`rocketride` / `rocketride-python`)

These changes affect code that imports and calls the Python or TypeScript client SDKs directly. The old `connect()` / `disconnect()` signatures are preserved as backward-compatible wrappers, but callers should migrate to the new layered API.

#### Connection API (both SDKs)

| Before (1.0.x) | After (1.1.0) | Notes |
|---|---|---|
| `connect(auth?, uri?, timeout?)` → `void` | `connect(credential?, { uri?, timeout? })` → `ConnectResult` | Now returns full user identity (userId, organizations, apps, teams). The `auth` param is renamed `credential` to reflect that it accepts API keys, Zitadel access tokens, and `rr_*` user tokens. Old positional `auth`/`uri` kwargs still accepted but deprecated. |
| `disconnect()` → `void` | `disconnect()` → `void` | Signature unchanged; internally calls `logout()` + `detach()`. |
| *(not available)* | `attach(uri?)` → `void` | Opens the WebSocket **without** authenticating. Required for public/unauthenticated operations like catalog browsing. |
| *(not available)* | `login(credential?)` → `ConnectResult` | Sends the DAP `auth` command over an attached transport. Supports credential rotation (auto-logout if credential differs). |
| *(not available)* | `logout()` → `void` | Sends new `deauth` DAP command, reverts the connection to unauthenticated without closing the socket. |
| *(not available)* | `detach()` → `void` | Tears down the WebSocket and cancels the reconnect engine. |
| `isConnected()` | `isConnected()` *(unchanged)* | Returns `true` only when both attached **and** authenticated. |
| *(not available)* | `isAttached()` | `true` when the WebSocket is open, regardless of auth state. |
| *(not available)* | `isAuthenticated()` | `true` when the auth handshake has succeeded on the current connection. |

**Reconnection engine rewritten**: the old flag soup (`_manualDisconnect`, `_authRejected`, `_didNotifyConnected`) is replaced by a `_desiredState` model (`'detached'` | `'attached'` | `'authenticated'`). Linear backoff (250ms increments, 15s cap) replaces exponential backoff, reconnection now **never gives up**. `maxRetryTime` is accepted for backward compatibility but **ignored**.

#### Python-specific breaking changes

- **`async with` context manager removed**: `__aenter__` / `__aexit__` are deleted. Replace `async with RocketRideClient(...) as client:` with explicit `await client.connect()` / `await client.disconnect()` in a try/finally.
- **`connect()` now returns `ConnectResult`**: previously returned `None`. Callers that did `await client.connect()` without capturing the result are unaffected; callers that typed the return as `None` will need to update.
- **`use()` no longer substitutes `${ROCKETRIDE_*}` client-side**: the raw pipeline is sent to the server, which handles all variable resolution via `get_merged_env()`. If you were relying on client-side `.env` interpolation, variables must now be set server-side (via the Variables page or `client.account.set_env()`).
- **Event type renames**: `EVENT_STATUS_UPDATE` → `EVENT_STATUS`; `EVENT_TASK` → split into `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART`. Code that imports the old names will get `ImportError`.
- **`auth` credential removed from transport layer**: `TransportWebSocket` no longer stores or exposes `auth`. Auth is exclusively managed by the `ConnectionMixin` / `RocketRideClient` layer.

#### TypeScript-specific breaking changes

- **`connect()` signature changed**: old: `connect(options?: number | { uri?, auth?, timeout? })` → `void`. New: `connect(credential?, options?: { uri?, timeout? })` → `Promise<ConnectResult>`. The `auth` property inside options is removed; pass the credential as the first argument. The numeric-only shorthand `connect(5000)` is removed.
- **`DataPipe` errors changed from `Error` to `PipeException`**: `open()`, `write()`, and `close()` now throw `PipeException` (extends `Error`) instead of plain `Error` when the server reports a failure. Callers catching `Error` are still compatible; callers matching on error message strings may need to update. `PipeException` carries the full DAP response body.
- **`setConnectionParams()` removed**: use `login(credential, { uri })` or call `attach(newUri)` + `login()` instead.
- **Project store methods removed**: `saveProject()`, `getProject()`, `deleteProject()`, `getAllProjects()` are deleted. Use the new filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`.
- **`validate()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ValidationResult` (typed interface with `valid`, `errors`, `warnings` fields).
- **`getServices()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ServicesResponse` (typed interface).

#### Both SDKs: new exception types

- **`PipeException`** (Python: subclass of `RuntimeError`; TypeScript: subclass of `Error`): thrown by `DataPipe.open()`, `.write()`, `.close()` when the server reports failure. Carries the full DAP response including `message`, `body`, and error code. Replaces generic `RuntimeError` / `Error`.
- **`ConnectionException`** (TypeScript): thrown on transport-level failures.

### Added

#### New Nodes
- **Exa Search**: semantic web search node integrating with the Exa API (exa.ai) for real-time data enrichment in pipelines. Agents invoke the tool to search the web and retrieve structured results including titles, URLs, text content, relevance scores, and published dates. Includes configurable `numResults` with min/max validation, retry exception sanitization to prevent API key leakage, and defensive boolean config parsing (#386, #509)
- **Bland AI**: voice call tool node for AI-driven phone calls via the Bland AI platform (#521)
- **OpenAI Compatible**: generic LLM node supporting any OpenAI-compatible API endpoint, allowing connection to self-hosted or third-party inference servers that follow the OpenAI chat completions API (#518)
- **GMI Cloud**: LLM connector for GMI Cloud inference platform (api.gmi-serving.com) hosting 100+ models on H100/H200 GPUs. Two tiers: shared (always-on, key-only: DeepSeek, GPT, Claude, Gemini) and deploy-on-demand (endpoint URL + key: Llama 4, Qwen3). Custom profile for arbitrary model/endpoint combinations (#540)
- **Guardrails**: AI safety node with comprehensive input/output validation. Input: prompt injection detection (regex + keyword scoring), topic restriction (allowed/blocked keyword lists), input length enforcement (char + token limits). Output: hallucination detection (sentence-level grounding), content safety (self-harm, violence, illegal activity patterns), PII leak detection (email, phone, SSN, credit card, IP), format compliance (JSON, markdown, bullet/numbered lists). Policy modes: block/warn/log. Profiles: basic (injection + PII), strict (all checks), custom. 87 tests (#534)
- **Video Embedding**: extracts frames from video input (MP4, AVI, MOV, WebM) at configurable intervals and generates vector embeddings using CLIP/ViT models for semantic search and RAG pipelines. Configurable frame interval, max frames, start time, duration, and max video file size (default 500 MB) to prevent unbounded memory. VideoCapture resource leak fixed with finally block (#516)
- **Kokoro TTS**: self-contained text-to-speech node using the Kokoro engine. Slim requirements (no piper/transformers/cloud). KokoroLoader, spacy_en_model, wav_to_mp3 utilities. Supports question, answer, and document lanes (RR-411, #662)
- **Telegram Bot**: source node connecting a Telegram bot to a pipeline via long polling or webhook. Routes incoming messages to appropriate lanes by content type (text, image, audio, video, documents) and sends pipeline responses back as replies (#659)
- **GitHub Tool**: tool node for GitHub API operations (issues, PRs, repositories) with full test suite for tool calling (#640)
- **Git Tool**: self-contained Git operations using pygit2 (libgit2), no host git binary required. Capabilities: clone, init, status, log, show, diff, blame, file_at, ls_files, grep, stage, commit, stash, branch create/checkout/merge/delete, fetch, pull, push (token + SSH auth), write_file with path-traversal guard. Safe mode (default on) blocks force-push and force branch deletion. Full unit test suite + integration tests (activated via `GIT_TEST_REPO_PATH` env). Includes `git_agent_example.pipe` (#654, #731)
- **Filesystem Tool**: file system operations (read, write, list, mkdir, delete) with path whitelist security check via `_prepare()` method. Operations can be selectively enabled/disabled at the node level. Shared prologue extraction via keyword flags (path_required, needs_encoding, needs_content) (#682)
- **Pipeline Tool**: run pipelines as tool calls from other pipelines, enabling pipeline composition and hierarchical agent workflows (#647)
- **LLM Vision (Gemini)**: image understanding via Gemini models with cache management (non-symmetric cache + empty frame guard)
- **LLM Vision (OpenAI)**: image understanding via OpenAI vision models
- **Webhook**: question lane support for webhook-triggered pipelines (#431)
- **CrewAI Orchestrator**: multi-agent orchestration via CrewAI framework. Exposes expert config fields (goal, backstory, expected_output, max_iter) for both agent and orchestrator node types. Advanced mode for fine-grained control. Sub-agent config propagated through `crewai.describe()`. Manager node renamed from Orchestrator, tool invoke removed from manager (#608)

#### VS Code Extension
- **Engine management overhaul**: replaced scattered engine lifecycle code (connection/, deploy/) with a clean `EngineBackend` hierarchy under `src/engine/`. Each connection mode (local, service, docker, cloud, onprem) gets its own backend implementation. `EngineRegistry` singleton reconciler detects config changes (API key, host URL, etc.) via checksums and auto-restarts affected engines on settings save. Eliminated `engine:status` event, all progress flows through `shell:statusChange`. `ConnectionManager` becomes passive: connects on engine `ready`, disconnects on `idle`. Unified `ioControl` message pattern for all panel operations. Migration from legacy layout (`globalStorage` + `config.json`) to new structure. Welcome page uses same `applyAllSettings` + reconcile path as Settings (#922)
- **Settings overhaul & target panels**: atomic settings save via `ConfigManager.applyAllSettings()` with `isBatchApplying` flag suppressing intermediate change events (eliminates race conditions from writing 20+ config keys individually, which caused connection managers to react to half-written state). Self-contained panels per mode (Local, Cloud, OnPrem, Docker, Service) handling both configuration and operational UI (status, install/start/stop/remove/update, progress, version selection). `EngineOperations` service extracted from `PageDeployProvider`. Deploy page command redirected to Settings. `useTheme` hook for VS Code dark/light detection. Embedded Docker/Service SVG logos. Build config consolidated: `.config` as single source of truth for Zitadel URLs/client IDs, esbuild loads `.config` first then `.env` on top, stopped name remapping of Zitadel keys. Cloud mode no longer hardcodes a non-existent URL, uses `config.hostUrl` at runtime (#725)
- **Standalone Variables page**: new "Variables" webview accessible from sidebar footer for managing `ROCKETRIDE_*` environment variables per connection slot (Development/Deployment). `EnvironmentProvider` with per-slot client resolution, `EnvironmentWebview` with pill bar for slot selection. OSS servers show single "Server Variables" card; SaaS servers show Organization/Team/User cards gated by permissions. `set_env` now updates `os.environ` in-memory before writing `.env` file. Deploy connection fix: removed `isSharedMode()` guard that skipped engine status listener registration. `commonStyles.tabContent` now uses `border-box` sizing. Removed capabilities filter that hid Cloud option. All "Environment" labels renamed to "Variables"
- **`${ROCKETRIDE_*}` variable autocomplete**: node config fields now offer autocomplete suggestions for defined pipeline variables. `useEnvVarAutocomplete` hook detects `${` trigger and filters keys by partial match. `EnvVarSuggestions` popover with arrow-key navigation. Wired into `BaseInputTemplate`, `TextareaWidget`, and `ApiKeyWidget`. `transformErrors` suppresses RJSF validation errors for fields containing `${ROCKETRIDE_*}`. `rrext_validate` now resolves env vars before validation using the same merged env as pipeline execution. Fixed `getHttpUrl()` to normalize engineUri before parsing
- **Category headers in QuickAddPopup**: compatible services grouped by bold uppercase category headers with indented items. Shared `CATEGORY_TITLES` extracted to `categoryTitles.ts`. `CreateNodePanel` auto-expands matching categories during search, restores previous expand/collapse state when search is cleared. Environment protocol types extracted to prevent build errors
- **Server Monitor panel**: real-time dashboard showing connections, tasks, and aggregate metrics via new `getDashboard()` / `get_dashboard()` SDK methods (DAP `rrext_dashboard` command). Client identification (`clientName`/`clientVersion`) forwarded during auth handshake so server can distinguish "VS Code 0.9.4" vs "CLI 1.2.0". Python DAP client skips auth message when transport lacks `get_auth()` (fixes crash for non-WebSocket transports). Consolidated `ServicePython` log level into `DebugOut` (#595)
- **Other task viewer via ProjectWebview**: `PageStatusProvider` completely rewritten. Previously opened a lightweight `StatusWebview` that couldn't show the node graph (nodes squashed at top, no toolbar, missing servicesJson). Now fetches unresolved pipeline via `getTaskToken` + `getTaskPipeline`, creates panel using the full Canvas/ProjectView stack, sends `project:load` with `isReadonly:true`. Falls back to synthesized single-node project if fetch fails. `StatusWebview` deleted (#803)
- **Readonly canvas**: single `isReadonly` prop replaces two inconsistent lock mechanisms (14-boolean `IFlowFeatures` and partially-implemented `isLocked`). `effectiveLock = isReadonly || internalIsLocked`. Guards added to `addNode()`, `updateNode()`, `deleteNode()`, paste, context-menu, lane click, config panel Save, all previously unguarded. Lock button hidden when `isReadonly` (#803)
- **Save button in canvas toolbar**: always-visible floppy disk icon with dirty-state tracking; grayed when clean, brand-colored when dirty. `isDirty`/`isNew`/`onSave` threaded through `IFlowProps` → `FlowContainer` → `FlowProvider` → `FlowProjectProvider`. `FlowCanvas` defers ReactFlow render until container has non-zero dimensions via `ResizeObserver`. `canvas:requestSave` calls `document.save()` directly (#678)
- **Dirty-state save pattern for settings**: card header starts clean (no buttons); on edit, Cancel and Save appear; on save, buttons disappear and "Saved" flashes for 5 seconds then fades; Cancel reverts to last-saved snapshot. Applied to all 5 VS Code settings tabs and shell-ui settings page (#877)
- **Play button shows actionable text**: renamed idle label from "Play" to "Run Pipeline". Added STOPPING state with "Stopping..." disabled button to prevent double-clicks. Widened hover expansion for longer label. Smooth CSS transitions with easing functions (#575)
- **Improved stop button feedback**: Pipeline Observability screen handles `TASK_STATE.STOPPING` with "Stopping..." disabled state and distinct orange styling, preventing duplicate clicks (#549)
- **Simplified sidebar footer**: replaced popup menu (three redundant gear icons all opening Settings) with flat layout when connection is shared and no cloud account. Documentation and Settings buttons rendered directly, connection status inline, announcements ticker rotates cards every 7 seconds. Full popup preserved for cloud account or independent connections. Panel sash restyled with native `--vscode-sash-hoverBorder` token, widened from 2px to 4px
- **Test Connection button**: available on service/docker/onprem panels via `ioControl('test')`
- **Docker GHCR tag fetching**: global cache for prerelease resolution with 15s timeout on HTTPS requests. Split-button dropdowns with grouped "Recommended" / "All versions" headers. Version metadata persisted per instance lifecycle. Linux package manager auto-detection (apt/dnf/yum/pacman) instead of hardcoded apt-get
- **Version tracking**: persistent `version.local.json`, `version.service.json`, `version.docker.json` files. PID liveness check before preserving `.pid` files during engine dir clear. Guard against phantom installs (missing binary). UAC-cancel fallback and uninstall.ps1 fixes
- **Event naming unification**: all connection events renamed to `shell:*` namespace matching cloud-ui vocabulary. `'event'` → `'shell:event'`, `'connected'` → `'shell:connected'`, `'connectionStateChanged'` → `'shell:statusChange'`, etc. All 10 providers renamed to drop redundant `Page` prefix. All 9 view directories renamed similarly (#803)
- **`.env` file management removed**: ~350 lines of env file handling removed from `ConfigManager` (envFileWatcher, envRawText, parseEnvFile, saveEnvFile, syncSettingsToEnv, etc.). Environment variables for pipeline variable replacement are now managed server-side (layered env in DB). Extension no longer maintains workspace `.env` file. URL resolution consolidated into `ConnectionManager` (per-group, not hardcoded to dev group) (#803)
- **On-demand env loading**: replaced 7 env-specific `AccountView` props with 2 generic callbacks (`onLoadEnv`, `onSaveEnv`) plus `refreshSignal`. Each `EnvScopeCard` requests its own data on mount. Promise-based messaging with 10s timeout. `shell:accountUpdate` as first-class event (no longer filtered from generic stream). Standalone `BillingProvider` deleted; billing is a tab inside Account (#803)
- **Welcome page simplification**: `welcomeDismissed` set automatically on save (no manual checkbox). Works from both Welcome and Settings pages (#803)

#### Shell UI (Web Host)
- **Shell-ui replaces cloud-ui**: new Module Federation host application served by Python `shell` module (`ai.modules.shell`) with public HTTP routes for SPA and all static assets under `/shell/`. Unifies OSS and SaaS into single codebase. Server-side app manifest delivery via `get_public_apps()` / `get_apps_for_user()` on AccountBase. Pre-auth info probe returns public apps for marketplace. Connect response includes authenticated user's full entitled app list (#803)
- **MUI removal**: replaced Material UI with plain CSS/HTML across entire shared-ui package; runtime theme system with light/dark JSON tokens
- **Theme rebrand**: replaced legacy purple (#5900FF) with cyan (#00b9ec) TOKENS palette. Light theme updated to warm-neutral (cream/stone backgrounds instead of pure white) (#803)
- **Theme flash fix**: `index.html` inline script sets `--rr-bg-default` and body background synchronously before React renders. `createShellConfig` reads saved theme from localStorage instead of always defaulting to rocketride-light, eliminating tan background during 1.5s OAuth code-exchange window (#878)
- **Chat module**: host-agnostic chat surface following established module pattern (props-in, callbacks-out, `--rr-*` CSS tokens). `ChatView` (MessageList + ChatInputField), `MessageBubble` (user/bot/system/status with markdown), `MarkdownRenderer` (react-markdown + GFM + syntax highlighting + charts), `ChartRenderer` (chart.js with circular-reference guard), `TypingIndicator` (animated bouncing dots), `useChatMessages` hook (message state + sendMessage + monotonic IDs) (#724)
- **Canvas state persistence**: viewport (zoom/pan), lock state, snap-to-grid, and editor mode now persist in `.pipe` files via `PipelineConfig` schema (TypeScript + Python SDKs). New `isFlowReady` boolean state tracks when all nodes have been rendered/measured by ReactFlow, replacing scattered `setTimeout`/`requestAnimationFrame` workarounds. Centralized `loadCanvas(nodes, edges)` as single entry point for structural canvas changes. Viewport restored on load via `isFlowReady` cycle, falls back to fitView. Spiral search for non-overlapping node placement. `EmptyCanvasPrompt` only shown when `nodes.length === 0 AND isFlowReady` (#670)
- **ProjectView architecture**: decomposed monolithic `modules/flow/` canvas module into composable multi-view project architecture (#670)
- **Style consolidation**: added `buttonPrimarySmall`, `buttonSecondarySmall`, `buttonDangerSmall`, `modalDialog`, `modalHeader`, `modalBody`, `modalFooter` to `commonStyles`. Added `cardHeaderButton`/`cardBodyButton` size modifiers for card contexts. Eliminated `Btn` wrapper component. Account `shared.tsx` trimmed from ~30 to 9 entries. All emojis removed from account UI (#803)
- **Shared connection types**: `ConnectionState` enum, `ConnectionMode`, `IAuthProvider`, `IConnectionManager` interface, `ShellAppEntry`, `ShellConnectionEventMap` with typed payloads for all `shell:*` events. Index signature for app-defined events (#803)

#### Billing, Account & Auth
- **Billing detail**: `BillingDetail` type gains `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart` in both SDKs. Subscription cards show detail grid with plan info. Cancel subscription requires confirmation modal. App display name shown instead of raw appId. Credit grant summary per subscription using `creditLabels` from Stripe metadata (#803)
- **Account/Billing merge**: Billing is now a tab inside Account (2nd pill) via `BillingPanel`. Standalone Billing page and provider deleted
- **Permission enforcement**: frontend computes `isOrgAdmin`/`isTeamAdmin` from profile; action buttons hidden for users without required permissions; `OrganizationPanel` read-only for non-admins; destructive actions go through confirmation modals. Team admin enforcement: must always have ≥1 admin (UI + server guard). Permission key fixed: `'admin'` → `'team.admin'`. `_require_team_admin` queries DB directly instead of stale cache (#803)
- **Team-based task permissions**: replaced all `control.userId == caller.userId` ownership checks with `resolve_task_permissions()` so teammates and org admins can monitor/control each other's tasks. Permission strings (e.g. `'task.control'`, `'task.monitor'`) checked against resolved list (#803)
- **Layered environment secrets**: pipeline variables (`ROCKETRIDE_*`) stored encrypted (Fernet) in database per org/team/user scope, merged server-side during task execution. Merge order: `.env` → org → team → user → caller env. `get_merged_env()` on `AccountBase` with OSS (`.env` only) and SaaS (DB) implementations. `client.use()` `env` param for caller overrides (only `ROCKETRIDE_*` accepted). Client-side `processEnvSubstitution` removed, resolution is server-only (#803)
- **Session keys**: API keys are now true PATs inheriting user identity. `is_session` flag on `ApiKey` model. `ensure_session_key()` on every OAuth login: refreshes 90-day expiry if active, creates fresh key if expired/missing. Session keys cannot be self-revoked. Admin revoke is hard-delete. Housekeeping: keys revoked >30d purged on login. UI shows "Session" / "Interactive login" badge (#803)
- **Scoped PATs**: PATs optionally restricted to single team with explicit permissions. Effective permissions intersected with user's actual permissions at auth time (can never escalate). Optional `team_id` on `ApiKey`. Create key modal: team dropdown + conditional `PermGrid`. Key list shows team scope badge (#803)
- **userToken → userId refactor**: server-side event tenant scoping uses `userId` instead of `userToken`. Fixes bug where two connections from same user with different keys wouldn't see each other's dashboard events (#803)
- **Account UI overhaul**: all card headers use `commonStyles.labelUppercase`. Save button pattern: hidden until dirty, shows [Cancel][Save], "Saved" green text with 5s timer. `ProfilePanel`: single "Organizations / Workspaces" card with nested teams. `TeamsPanel`: Delete moved to list with confirm modal. `PermGrid`: `PERM_DISPLAY` labels, alphabetized, added `task.store`, contrasting text on checked tiles (#803)
- **Client SDK attach/login split**: replace monolithic `connect()`/`disconnect()` with layered API: `attach(uri?)` opens WebSocket without auth (for public APIs like catalog), `login(credential?)` sends DAP auth, `logout()` sends new `deauth` command (reverts to unauthenticated without closing socket), `detach()` tears down WebSocket. Old `connect()`/`disconnect()` preserved as backward-compatible wrappers. Reconnection engine rewritten around `_desiredState` model ('detached' | 'attached' | 'authenticated'). Linear backoff (250ms increments, 15s cap), reconnection never gives up. Auth credential removed from transport layer (#803)
- **Server-driven appStatus**: replaced `subscriptionStatus` with server-computed `appStatus` ('auth' | 'free' | 'unsubscribed' | 'subscribed' | 'trialing' | 'past_due' | 'canceled') and `onDesktop` boolean per app manifest entry. Eliminates client-side reconciliation races (#803)
- **App mode & subscription gating**: `mode` field (free/subscription/paywall) in app manifests. Shell-level subscription gate blocks app iframe until active subscription exists. Desktop app management moved into account identity flow (#803)
- **Token storage hardened**: moved from `localStorage` to `sessionStorage` (cleared when tab closes) addressing CodeQL "Clear text storage of sensitive information" alert (#803)

#### Profiler
- **DAP-based cProfile system**: replaced HTTP-endpoint profiler module with per-process cProfile profiling over DAP connections. Any connected client can profile any process (task server, data engine subprocesses, model server). `CProfileManager` singleton with start/stop/status/report/release API. Owner tracking per connection with disconnect cleanup. SDK methods: `cprofileStart`/`cprofileStop`/`cprofileStatus`/`cprofileReport` (TS + Python) with optional `target` parameter for pipeline profiling. New `profiler-ui` Module Federation remote app with `ProfilerView`, `ConnectionManagerView`, and `ProfilerSidebar` (#803)

#### Module Federation
- **MF stability**: added `runtime: false` to all remote apps (shell-ui provides shared runtime; without it each remote embeds its own runtime copy, causing remoteEntry.js to change on every rebuild and version-mismatch errors during HMR). Added `eager: true` to react/react-dom shared configs (breaks async shared-scope negotiation deadlock where host waits for remote's async chunk and remote waits for host). App loader filters out server-only entries with no `remoteEntry` URL (prevents `normalizeRemote()` crash on `undefined`) (#877)

#### Engine & Core
- **Database EXECUTE**: direct SQL/Cypher execution via `QuestionType.EXECUTE` with `client.database.query()` namespace on both SDKs, bypassing LLM translation and safety gating. Gated behind opt-in `allow_execute` config (default off). Results bounded with `fetchmany(max_execute_rows+1)` (default 25000). Neo4j results capped at same limit. `allow_execute` parses strings strictly: only `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive). EXECUTE output wrapped in try/except; serialized with `default=str`. SDK validates non-empty token/sql before dispatching
- **Database DIALECT**: `QuestionType.DIALECT` for engine capability discovery. SDK callers can ask which engine a database pipeline is connected to (`DatabaseDialect` enum). `_db_dialect()` abstract method on `DatabaseInstanceBase`. `services.json` now exposes UI-toggleable `allow_execute` boolean
- **Handle-based streaming I/O**: generic filesystem-style interface (`open`/`read`/`write`/`close`/`delete`/`stat`/`mkdir`/`list_dir`) on `FileStore`, replacing monolithic in-memory buffering. Domain methods become thin convenience wrappers on client SDKs. Supports S3 multipart upload (5 MB buffer), Azure staged blocks (4 MB buffer), and local filesystem. Handles tagged with owning `connection_id` and force-closed on connection termination (#600)
- **`@tool_function` decorators**: collapsed the two-class pattern (IInstance + ToolsBase driver) into a single class. Any `IInstanceBase` subclass can declare tool entry points with a decorator; the method name becomes the tool ID, decorator carries schema/description, base class `invoke()` dispatches automatically. Eliminates parallel driver classes, factory methods, and boilerplate delegation (#599)
- **Experimental + Deprecated capability flags**: `DEPRECATED = BIT(15)`, `EXPERIMENTAL = BIT(16)` in `PROTOCOL_CAPS`. Both flags wired through C++ parser, pybind11 bindings, both client SDKs, and shared-ui. Yellow "EXPERIMENTAL" badge rendered on canvas nodes, Add Node slider, and Quick Add popup (#606)
- **Docker-compose and healthcheck**: `HEALTHCHECK` instruction in `Dockerfile.engine` using curl to `/ping`. `docker-compose.yml` with engine, PostgreSQL+pgvector, Milvus (+ etcd, MinIO), ChromaDB. Override file for dev hot-reloading. All images pinned to specific versions. Security warnings in `.env.example` (#496)
- **Billing commands mixin**: `BillingCommands` in TaskConn's MRO for `rrext_account_billing`. OSS implementation routes on `arguments.subcommand` with stubs so UI doesn't hang in half-rendered state (#692)
- **Task engine extraction**: `task_engine` and `cmd_data` extracted as standalone modules (#661)
- **GPU inference billing**: `metrics.resource('gpu')` context manager times inference. `CONST_RATE_GPU_INFERENCE_SECOND` for billing. Custom node counters (`pagesProcessed`, etc.) with configurable rates. All 9 AI model files wrapped with `metrics.counter('gpu_inference_count')` + `metrics.resource('gpu')`. Billing reports include `gpu_inference` and `custom` token fields (#803)
- **Metrics rewrite**: replaced Timer class and `resource()` context manager with flat `MetricsManager`: `timer()`, `add_time()`, `counter()`, `event()`. Thread-safe via single lock. Removed per-pipe `ContextVar`, metrics are per-subprocess. ModelClient auto-records server-reported perf dict (#803)
- **ModelClient refactor**: derived from `RocketRideClient` with `ws_path='/models'` so URI normalization, protocol selection, and auth are handled by SDK. Python SDK gains `ws_path` kwarg. Sync `disconnect()` override for worker thread callers. All 9 model wrappers updated. `get_model_server_address()` simplified to return raw string (#877)
- **Model server DAP namespace**: all model server commands renamed to `rrext_ms_*` prefix (load_model → rrext_ms_load_model, etc.) for disambiguation from core DAP commands (#803)
- **GPU guard**: `install_gpu_guard()` blocks direct torch/tensorflow imports in model server mode; all GPU inference must go through ModelClient RPC (#803)
- **Pipeline error surfacing**: `binder.cpp` sets `completionCode` on Entry when `callMethods` encounters error. `bindings.cpp` exposes `completionError` read-only property. `data_conn.py` rewrites `close_sync()` to always extract results even when end/close throws, surfaces `Entry.completionError` when `objectFailed` is True. Errors now reach dropper UI (#803)
- **`rrext_get_pipeline` DAP command**: returns task's unresolved pipeline (with `${...}` placeholders intact) so VS Code can reconstruct node graph without exposing secrets. `_build_task()` now accepts explicit resolved pipeline, `self._pipeline` retains original unresolved form (#803)

#### Client SDKs: New Features

**Layered connection API (both SDKs):**
- `attach()` / `detach()`: open/close the WebSocket without authentication. Enables unauthenticated operations (public catalog browsing, server probes) before the user logs in
- `login()` / `logout()`: authenticate/deauthenticate over an attached transport. `login()` returns `ConnectResult` with full user identity (userId, organizations, apps, teams, permissions). `logout()` sends new `deauth` DAP command, reverting to unauthenticated without closing the socket. Supports credential rotation (auto-logout if a different credential is supplied)
- `connect()` / `disconnect()` preserved as backward-compatible wrappers (`attach` + `login` / `logout` + `detach`), but `connect()` now returns `ConnectResult` instead of void
- `isAttached()`: true when WebSocket is open (regardless of auth)
- `isAuthenticated()`: true when auth handshake has succeeded

**Namespaced API accessors (both SDKs):**
- `client.account`: profile, API keys, org, members, teams, environment variables (`get_env()` / `set_env()` / `get_environment_keys()`)
- `client.billing`: subscriptions, checkout, credits, cancel
- `client.database`: `client.database.query()` for direct SQL/Cypher execution; `client.database.dialect()` for engine discovery (`DatabaseDialect` enum)

**New methods:**
- `RocketRideClient.getServerInfo(uri)` (static): probe a server for capabilities without authenticating. Returns `ServerInfoResult` with version, capabilities, platform, and public apps
- `getTaskToken(projectId, source)`: resolve a running task's session token
- `getTaskPipeline(token)`: retrieve the unresolved pipeline for a running task (placeholders intact, no secrets)
- `getDashboard()`: real-time server dashboard (connections, tasks, metrics)
- `cprofileStart/Stop/Status/Report`: per-process cProfile profiling over DAP
- `call(command, token?, **kwargs)` (Python): single public entry point for all typed DAP operations with optional `on_trace` callback

**TypeScript-specific additions:**
- `wsPath` config option for custom WebSocket paths (e.g. `'/models'` for model server)
- `onTrace` callback for observing all `call()` traffic
- `MonitorKey` type and `addMonitor()` / `removeMonitor()` for reference-counted monitor subscriptions
- `restart()` method for restarting pipeline tasks
- Filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`: replaces the old project store methods
- `getTaskStatus()` applies default 15s timeout (configurable via `options.timeout` or `{ timeout: false }`)
- `validate()` now returns typed `ValidationResult` (was `Record<string, unknown>`)
- `getServices()` now returns typed `ServicesResponse`; `getService()` returns `ServiceDefinition`
- `DataPipe.open()` sets `_opened` only after successful SSE setup with rollback on failure
- `normalizeUri()` preserves user-specified port (was being stripped for scheme-default ports like :443)

**Python-specific additions:**
- `ws_path` kwarg for custom WebSocket paths
- `client_name` / `client_version` kwargs forwarded in auth handshake for client identification
- `on_trace` callback for observing all `call()` traffic
- `public` mode for permanently unauthenticated connections (only `rrext_public_*` commands)
- `DashboardMixin`, `CProfileMixin`, `StoreMixin` added to MRO
- Improved `send()` pipe error context with `PipeException` (catchable as `RuntimeError`)

**New types (both SDKs):**
- `ConnectResult`, `ServerInfoResult`, `AppManifestEntry`, `StripePriceEntry`
- `AccountProfile`, `AccountOrganization`, `AccountOrgTeam`, `ApiKeyRecord`, `OrgDetail`, `MemberRecord`, `TeamRecord`, `TeamDetail`, `TeamMemberRecord`
- `BillingDetail` (extended with `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart`, `credits`, `creditLabels`), `StripePlan`, `CreditBalance` (extended with `labels`), `CreditPack`
- `PROTOCOL_CAPS` enum with all 17 capability flags
- `SERVICE_DEFINITION`, `SERVICES_RESPONSE`, `VALIDATION_ERROR`, `VALIDATION_RESULT`
- `DASHBOARD_OVERVIEW`, `DASHBOARD_MONITOR`, `DASHBOARD_CONNECTION`, `DASHBOARD_TASK`, `DASHBOARD_RESPONSE`, `DASHBOARD_EVENT` and 7 event subtypes
- `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART` (replace old `EVENT_TASK`)
- `EVENT_STATUS` (replaces `EVENT_STATUS_UPDATE`)
- `TASK_TOKENS` extended with `gpu_inference` and `custom` fields
- `CreateKeyParams` accepts optional `teamId` for scoped PATs
- `EVENT_TYPE.DASHBOARD` flag (bit 7) for server-level events; `EVENT_TYPE.ALL` updated to include it
- **Config**: `Config.getNodeConfig()` emits warnings for deprecated profiles with migration guidance from profile's `migration` field

#### MCP
- **MCP Resources and Prompts**: `rocketride://` URI resources (pipeline list, server status, node registry) with graceful error handling for disconnected clients. Three prompt templates (analyze-document, chat-with-data, evaluate-pipeline) with required argument validation and message rendering. 44 tests (#541)

#### Agents & Pipelines
- **Agent framework overhaul**: ProjectView architecture with shared-ui migration (#670)
- **Example pipeline templates** for common AI workflows (#572)

#### Build System
- **Rsbuild upgrade**: all UI apps upgraded from pinned 0.4/1.1 to ~1.7.5, eliminating Node.js `DEP0180` deprecation warnings in Node 22+. ESM config migration (`.ts` → `.mts`). cmake minimum bumped from 3.14 to 3.19. `@rspack/binding-*` platform pins removed. Service config renamed `config.json` → `service-config.json` with migration (#905)
- **Build-input caching**: source fingerprinting (`buildInputHash()` + `hasBuildInputChanged()`) skips UI modules whose inputs haven't changed. `appModule.js` factory eliminates ~80 lines of boilerplate per app. Shell-ui tracks own src/ + shared-ui/src + package.json. `--force` flag bypasses caching. Clean actions clear cached hashes (#877)
- **Builder CLI**: `server:run` action (build + run without shell-ui dev server). `--taskserver=ADDR` replaces `--testport`. `--modelserver` semantics clarified (bare flag = start local, `=ADDR` = use existing). `--simulate-gpus=N` forwarded to model server. `parseServerAddress()` utility (#803, #877)

#### CI/CD
- **Cosign container signing**: keyless signing of rocketride-engine image via Sigstore + GitHub OIDC (signs by digest). GPG detached-signature step for server tarballs/zips, gated on `GPG_SIGNING_KEY` secret (#798)
- **Dependabot**: weekly version updates with smoke tests for litellm and pipeline-node deps. Blocked rsbuild/rslib/rspack 0.x churn and pip major bumps. Semver-major ignores across all 10+ ecosystems (#788, #843, #842, #862)
- **Experimental-release workflow**: `workflow_dispatch`-only, builds from arbitrary branch under configurable tag suffix. Per-product release jobs. No marketplace publishing. `prerelease: true`. First use case: workshop builds (#848)
- **Nightly prereleases**: initially from stage branch (#631), moved to develop on green CI (#713). `workflow_dispatch` expanded to develop/stage/main (#906)
- **Daily Actions storage cleanup** workflow (#636)
- **Discord notifications**: PRs, issues, discussions with live CI check status and PR state tracking in embed (#612, #614, #638). Duplicate posts on discussion edits prevented (#698). Retry/backoff for webhook calls (#797)
- **Ruff and gitleaks**: pre-commit checks (#722); gitleaks made blocking (#681); `ruff format` applied to all Python files (#723)
- **Sequential builder tests** to isolate cross-suite flakes (#734)
- **cmake 4** support (#807)
- **Actions pinned** to immutable commit hashes (#483)
- **Artifact retention** dropped to 1 day for 0.5 GB storage cap (#779)
- **CodeQL** switched from advanced to default setup (#768)

#### Documentation
- **Observability & tracing**: integration guide documenting how external services consume runtime logs, lifecycle events, and pipeline traces over the WebSocket DAP channel. Wired into all agent stubs (Claude Code, Cursor, Windsurf, Copilot) (#716)
- **Node usage guides**: `db_neo4j` with practical examples (#490), `llm_openai` with provider examples (#493), source connectors (#650)
- **Per-node documentation** overhaul, added and updated docs for each node (#639, #660)
- **Engine**: Tika ExternalParser media tool requirements (#729)
- **Python client**: clarified `send()` sources and `.pipe` usage (#705); updated Python 3.8 → 3.10 references (#657); added `.env.example` (#492)
- **Contributing**: require green CI checks before review (#627)
- **SOC2-ready SECURITY.md**: explicit triage/remediation SLA (critical 7d, high 30d, medium 90d), scanning toolchain documentation (CodeQL, Scorecard, Trivy, Dependabot, secret scanning), quarterly access reviews (#762)
- **Two-person control** on alert dismissals documented (#800)
- **Code of Conduct** (#591)
- **README improvements**: onboarding wording, absolute image URLs, GIFs, Product Hunt badge (#706, #506, #478, #590)

#### Security Policies
- **Workflow permissions**: top-level permissions added to 5 reusable workflows (#790); storage-cleanup narrowed to job-level (#794)
- **Stale lockfile removed**: `packages/client-typescript/pnpm-lock.yaml` deleted, override declared in root (#796)

### Changed

- **LLM provider migration**: all LLM providers migrated to `ai.common.LLMBase` (#719); automated LLM model sync tool fetches models from provider APIs, smoke-tests new ones, merges into `services.json` with smart deprecation and three-source token limit resolution (provider API → OpenRouter → LiteLLM). `modelSource` field tracks discovery origin. Weekly CI workflow opens PR with sync report. `builder models:update` command (#651)
- **llm_gemini model profiles**: added `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-image-preview`; standardized `gemini-2.5-*` dot notation; deprecated profiles retained with migration guidance
- **Removed `llm_vertex` node**: Vertex AI now supported via `llm_gemini`; migrated vision nodes to `LLMBase`; fixed `llm_gemini` API key validation (dropped strict `startsWith('AI')` check, added sub-key fallback for old pipe files where sub-key is `profile.split('_',1)[1]`); fixed `validateConfig` to early-return when apikey is empty (secure fields not decrypted at validate time); removed vertex icon from UI; bumped client-typescript SDK to 1.1.0 (#902)
- **OpenAI models** updated to latest (#503); deprecated Gemini models removed (#500)
- **Service config cleanup**: removed obsolete `input` section from 72 service configuration files (was duplicate of lane declaration, closes #629) (#728)
- **Milvus node**: configurable timeout (default 60s, was hardcoded 20), connection error handling with meaningful messages, bulk insert with configurable batch size (default 50, was one-at-a-time), `_batchUpsertResults()` helper for markDeleted/markActive, timeout on `remove()`, COSINE distance score range [0,2] rescaling documented (#562)
- **Node tests parallelized** with pytest-xdist (#700)
- **Tool input helpers**: `normalize_tool_input()` replaces 4 copy-pasted variants across tool nodes. `require_str`/`require_int`/`optional_str` replace local validators (44 callsites in `tool_github`). `require_str` now raises `ValueError` cleanly on non-string inputs (was `AttributeError`). `require_int` rejects `bool` (an `int` subclass). 41 unit tests (#759, #766)
- **Backward-compat DAP token fallback**: `get_task_token()` checks `arguments.token` first, falls back to `request.token` for older clients (#902)
- **pnpm** pinned via `packageManager` field (#623)
- **Version bump**: all release packages bumped to next minor (server 3.1.2 → 3.2.0, chat/dropper-ui 2.0.1 → 2.1.0, all others 1.0.x → 1.1.0)
- **engines.node** bumped from ≥18.0.0 to ≥20.0.0 (aligns with serialize-javascript@7 requirement and CI reality)
- **Provisioning**: creates Development + Production teams (Production default); `build_api_key` uses random nonce
- **VSCode detection**: chat-ui/dropper-ui changed from `window.parent !== window` to checking for `acquireVsCodeApi` (canonical detection)
- **Lefthook**: sequential mode; disabled colors to fix terminal corruption on Windows

### Fixed

#### Security
- **Critical: RCE**: prevent arbitrary module injection via `/use` endpoint. Added `ALLOWED_MODULES` frozenset whitelist restricting dynamic imports to 10 known service modules. Requests for any other module return 400 (#342)
- **Critical: Injection**: prevent filter expression injection in Milvus vector store (#355)
- **Auth**: require authentication for profiler endpoints; escape HTML output (#362)
- **Env expansion**: restrict `${VAR}` expansion in pipeline configs to allowlisted prefixes (`ROCKETRIDE_`, `PIPELINE_`, `NODE_`, `ROCKET_`); all others replaced with `<REDACTED>` to prevent exfiltration of AWS keys, DB URLs, tokens (#359)
- **Temp files**: use secure temporary file creation in task engine (#356)
- **SQL safety**: switch from blacklist to allowlist approach (#577)
- **Path traversal**: use `pathlib.is_relative_to` checks (#580)
- **Redaction**: expand sensitive field redaction patterns in VS Code logger (#578)
- **Input validation**: add validation/sanitization to LLM chat drivers (#559)
- **Rate limiting**: add rate limiting to `tool_http_request` node (#560)
- **Remote nodes**: improve error handling in remote node execution (#565)
- **Pinned deps**: handlebars + protobufjs via pnpm.overrides (#783)

#### Client SDKs: Fixes
- **Python client**: break drain cycle causing `RecursionError` on disconnect, `_drain_message_tasks` walks each candidate's `_fut_waiter` chain and excludes tasks that transitively await the drainer itself, so the gather can never close back on itself. `dap_client.request()`'s `ConnectionError` handler now uses fire-and-forget `self._transport.disconnect()` instead of `await self.disconnect()` (develop's `disconnect()` is sync-returns-Task). Two regression tests pinning each fix (#792)
- **Python client**: clean pending DAP request on send failure, prevents zombie futures accumulating on flaky connections when the WebSocket drops mid-request (#736)
- **Python client**: align `requires-python` with monorepo target (py310), was still declaring py38 (#491)
- **Python client**: `set_env` now updates `os.environ` in-memory (removes stale `ROCKETRIDE_*` keys, then sets new values) before writing the `.env` file, so `get_env` reflects changes immediately without a server restart. Uses `sys.executable` instead of `sys.argv[0]` for the `.env` file location
- **Python client**: `ws_path` composition uses `parsed._replace` instead of string concatenation to avoid malformed URIs
- **Python client**: popped consumed kwargs (`ws_path`, `client_name`, `env`, etc.) before passing to `super().__init__()` to avoid "multiple values for keyword argument" `TypeError`
- **TypeScript client**: preserve user-specified port in `normalizeUri`, the URL API silently strips scheme-default ports (:443 on https, :80 on http); now checks raw input for explicit `:digits` after the scheme before deciding whether to add default port (#377)
- **TypeScript client**: `DataPipe.open()` sets `_opened` only after successful SSE setup; on `setEvents` failure, rolls back via `close()` so the server pipe is not left half-open. `close()` now also handles the case where server assigned `pipe_id` but `_opened` was never set to true (#704)
- **TypeScript client**: `DataPipe.close()` sets `_opened = false` in the finally block, preventing double-close races
- **TypeScript client**: `connect()` treats empty or whitespace-only `ROCKETRIDE_APIKEY` in the client env snapshot as **unset**, so it does not override constructor-provided auth (#704)
- **TypeScript client**: `getTaskStatus` applies a default per-request timeout of 15s so CI doesn't hang indefinitely on a dead task; callers can pass `options.timeout` (ms) or `{ timeout: false }` to skip (#704)
- **Both clients**: pipe error messages now include common-cause diagnostics (pipeline not running, wrong source type, MIME mismatch) to reduce debugging time
- **SDK connect error callback type** corrected, was typed incorrectly in the TypeScript client (#576)
- **`CreditBalance` type** aligned with backend camelCase wire shape (#714)

#### VS Code Extension
- **Chat webview blank screen**: realigned `view:ready` handshake so chat panel renders after extension reload (#688)
- **Explorer empty-state**: clicking +File/+Folder on empty PIPELINES tree was silent no-op (input row gated on `entries.length > 0`). Now renders input when root-level create is pending. Stale `selectedPath` falls through to root when all entries deleted (#901)
- **Annotation double-click**: annotation nodes advertised "Double-click gear to add content..." but gear was hidden until hover (CSS opacity:0→1), opened on single-click not double-click, and body had no `onDoubleClick`. Added `onDoubleClick` on annotation root, updated placeholder text (#901)
- **Team selector**: cloud team selector not appearing after sign-in because team fetching was embedded inside cached `probeServerInfo()`. Decoupled into separate `fetchCloudTeams()` driven by `useEffect([isSaas, cloudSignedIn])` (#877)
- **Billing app names**: subscription cards showing raw `appId` instead of human-readable name. Added full `apps` manifest prop chain so components build own `appId → app` lookup map (#877)
- **Canvas-played pipelines** now register in sidebar menu (#571)
- **Missing hostname** handled in URI parsing (#530)
- **OSX Python path** for Python-EaaS debugger (#693)
- **Dark mode**: fixed icon and edge visibility in flow builder (#597)
- **UI validation** fixes (#767)
- **Icons and coloring** for Bland, GMI, and trash bin (#634)
- **QuickAdd popup** label copy improved (#679)
- **Product Hunt badge**: converted SVG to PNG (marketplace rejects SVGs)

#### Engine & Nodes
- **LLM**: clear correct `_chat` reference in `endGlobal` across all LLM nodes (#531)
- **Milvus**: apply `retrieval_score_threshold` filter in `searchSemantic` (#726)
- **Database**: bound Neo4j EXECUTE rows; parse `allow_execute` strictly (only '1'/'true'/'yes'/'on')
- **Frame grabber**: user-configured interval was being ignored (#675)
- **Pipeline configs**: error handling for missing configuration files (#544)
- **Mutable defaults**: replaced mutable default arguments with `None` across Python nodes (#582)
- **Chunk scoping**: `_processFullTables` used stale `doc` variable from outer loop and called `Doc()` with invalid constructor params. Fixed to reset `page_content` on chunk itself. Follow-up: fixed score assignment that replaced Doc with float, and first-chunk aliasing that dropped text (#776)
- **Mock truthiness**: `psycopg2`: `isinstance(False, int)` is True, so `isDeleted=False` was matched as LIMIT value (added `not isinstance(p, bool)` guard). `chromadb`: `if limit and ...` treated `limit=0` as falsy (changed to `limit is not None`). `weaviate`: `distance if distance else 1.0` collapsed 0.0 (exact match) to 1.0 (changed to `distance is not None`) (#748)
- **Async safety**: `_message_tasks` set accessed from multiple async contexts without a lock (#535)
- **CLI shutdown**: SIGINT/SIGTERM handlers with proper exit codes (130/143), double-signal force exit, 5s cleanup timeout, idempotent `cleanupClient` via dedup promise, `isCancelled` guards on command actions, `run()`/`main()` shutdown awareness via `awaitShutdown()` (RR-655, #891)
- **setuptools**: bootstrapped alongside wheel for `uv pip compile`, legacy sdists (e.g. `docopt 0.6.2` via kokoro → misaki → num2words chain) need setup.py but uv doesn't supply setuptools when build isolation is off (#871)
- **Cloud port**: corrected from 433 to 443 in `services.json` (#684)
- **LLM providers**: small cleanup across all LLM nodes (#645)
- **Auth token precedence**: URL auth param prioritized over stale sessionStorage token from previous task (#902)
- **AVIReader**: capture errors from background `_data_process` thread and re-raise on `stop()` so pipeline errors surface as task errors (#803)
- **Webhook/Telegram nodes**: removed `server.use('profiler')` calls (profiler module was deleted; these caused "Module 'profiler' is not allowed" crash) (#803)
- **Task auth**: removed early `ValueError` on empty credential that prevented anonymous/no-key OSS connections from reaching auth check (#803)

#### CI/CD
- **Open VSX**: handle 'already published' error in release workflow (#480)
- **Docs-only PRs**: build passthrough so they don't block CI (#607)
- **Flaky tests**: resolve timeouts and hanging in concurrent pipeline tests, shared hardcoded `project_id` caused server-side contention serializing subprocess launches (#561, #877)
- **Discord webhooks**: retry/backoff for webhook calls (#797); prevent duplicate posts on discussion edits (#698)
- **Nightly workflow**: explicit branch check on `workflow_run` trigger (#771); allow `workflow_dispatch` from stage and main (#906)
- **Release tags**: push via `WORKFLOW_PAT` with repo+workflow scope (#774)
- **pytest-xdist race**: all 6 path-traversal test methods shared same `outside.txt` in system temp root; fixed by wrapping `workdir` in per-test tempdir (#872)
- **pnpm-lock.yaml**: restore libc fields (#622); fix lucide-react dependency (#621)
- **CI API key**: use literal `ROCKETRIDE_APIKEY` in Test step instead of secret (#742); match GraphQL github-actions author login (#699)
- **ruff format**: pure whitespace fixes for vision node files that left develop CI red (#902)

#### Tests
- **AI unit-test coverage** grown from 8% to 43% (395 → 945 passing tests). Covers: sql_safety, common/util/validation/table, dap_conn, pipeline_validation, web endpoints, auth middleware, sandbox execution, profiler lifecycle, account/reporter/keystore, all command handlers, data_conn, task_engine state, task_server background loops, transports, task_http, store providers (S3 + Azure), DB base classes, dropper path-traversal guard. Assertions tightened per CodeRabbit review. CodeQL auth-callback URL assertions anchored (#831)
- **Tests realigned** with team-based permissions and metrics rewrite, updated mocks for `teamId`, `organizations`, `resolve_task_permissions`, `tokens.gpu_inference`/`tokens.custom`, renamed `apikey` → `user_id`. Dropped tests for deleted code. Added `test_cmd_public.py` (#870)
- **Node tests**: full improvements and mock cleanup (#687)

### Dependency Updates
- litellm ~1.50 → ~1.83 (#816)
- DOMPurify → 3.4.x (resolves 16 alerts / 8 GHSAs) (#886)
- cryptography pinned to 46.0.7 (#884)
- SQLAlchemy owned at ai layer, pinned ≥2.0,<2.1 (#804)
- Patched via pnpm.overrides:
  - **Routing**: react-router 6.26→6.30.3, @remix-run/router inlined (#914)
  - **Parsers**: ajv@8→≥8.18.0, markdown-it→≥14.1.1, postcss→≥8.5.10, prismjs→≥1.30.0, yaml@1→≥1.10.3 (#915)
  - **Middleware**: koa→≥2.16.4 (3 advisories), qs→≥6.14.2 (#916)
  - **Util/SVG**: svgo@2→≥2.8.1, flatted→≥3.4.2, immutable@5→≥5.1.5, underscore→≥1.13.8 (#917)
  - **Security**: picomatch@2→≥2.3.2, picomatch@4→≥4.0.4, fast-uri→≥3.1.2, serialize-javascript→≥7.0.5 (#890)
  - **Minimatch**: all 4 major lines patched (3→≥3.1.4, 5→≥5.1.8, 9→≥9.0.7, 10→≥10.2.3) (#887)
  - **Core**: undici→≥7.24.0 (6 advisories), lodash→≥4.18.0, lodash-es→≥4.18.0 (#888)
  - handlebars→≥4.7.9, protobufjs→≥7.5.5 (#783)
- Bumped: aiohttp, pygit2 1.15→1.19, soundfile 0.12→0.13, requests, ws 8.19→8.20, postcss 8.5.6→8.5.10, nltk, spacy, spacy-transformers, cymem, murmurhash, preshed, srsly, thinc, psycopg2-binary, pymysql, opensearch-py, npm-production group (adm-zip, tar, lucide-react, dockerode, web-vitals), shared-ui devDependencies (rollup, @types/react, @types/react-dom), cosign-installer, ossf/scorecard-action, gh-actions group (pnpm/action-setup, github/codeql-action, softprops/action-gh-release, dorny/paths-filter)

---

## RocketRide Server v3.3.0

**Server** · v3.3.0 · July 7, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.3.0)

### ⚠ Breaking Changes: Client SDKs (`rocketride` / `rocketride-python`)

These changes affect code that imports and calls the Python or TypeScript client SDKs directly. The old `connect()` / `disconnect()` signatures are preserved as backward-compatible wrappers, but callers should migrate to the new layered API.

#### Connection API (both SDKs)

| Before (1.0.x) | After (1.1.0) | Notes |
|---|---|---|
| `connect(auth?, uri?, timeout?)` → `void` | `connect(credential?, { uri?, timeout? })` → `ConnectResult` | Now returns full user identity (userId, organizations, apps, teams). The `auth` param is renamed `credential` to reflect that it accepts API keys, Zitadel access tokens, and `rr_*` user tokens. Old positional `auth`/`uri` kwargs still accepted but deprecated. |
| `disconnect()` → `void` | `disconnect()` → `void` | Signature unchanged; internally calls `logout()` + `detach()`. |
| *(not available)* | `attach(uri?)` → `void` | Opens the WebSocket **without** authenticating. Required for public/unauthenticated operations like catalog browsing. |
| *(not available)* | `login(credential?)` → `ConnectResult` | Sends the DAP `auth` command over an attached transport. Supports credential rotation (auto-logout if credential differs). |
| *(not available)* | `logout()` → `void` | Sends new `deauth` DAP command, reverts the connection to unauthenticated without closing the socket. |
| *(not available)* | `detach()` → `void` | Tears down the WebSocket and cancels the reconnect engine. |
| `isConnected()` | `isConnected()` *(unchanged)* | Returns `true` only when both attached **and** authenticated. |
| *(not available)* | `isAttached()` | `true` when the WebSocket is open, regardless of auth state. |
| *(not available)* | `isAuthenticated()` | `true` when the auth handshake has succeeded on the current connection. |

**Reconnection engine rewritten**: the old flag soup (`_manualDisconnect`, `_authRejected`, `_didNotifyConnected`) is replaced by a `_desiredState` model (`'detached'` | `'attached'` | `'authenticated'`). Linear backoff (250ms increments, 15s cap) replaces exponential backoff, reconnection now **never gives up**. `maxRetryTime` is accepted for backward compatibility but **ignored**.

#### Python-specific breaking changes

- **`async with` context manager removed**: `__aenter__` / `__aexit__` are deleted. Replace `async with RocketRideClient(...) as client:` with explicit `await client.connect()` / `await client.disconnect()` in a try/finally.
- **`connect()` now returns `ConnectResult`**: previously returned `None`. Callers that did `await client.connect()` without capturing the result are unaffected; callers that typed the return as `None` will need to update.
- **`use()` no longer substitutes `${ROCKETRIDE_*}` client-side**: the raw pipeline is sent to the server, which handles all variable resolution via `get_merged_env()`. If you were relying on client-side `.env` interpolation, variables must now be set server-side (via the Variables page or `client.account.set_env()`).
- **Event type renames**: `EVENT_STATUS_UPDATE` → `EVENT_STATUS`; `EVENT_TASK` → split into `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART`. Code that imports the old names will get `ImportError`.
- **`auth` credential removed from transport layer**: `TransportWebSocket` no longer stores or exposes `auth`. Auth is exclusively managed by the `ConnectionMixin` / `RocketRideClient` layer.

#### TypeScript-specific breaking changes

- **`connect()` signature changed**: old: `connect(options?: number | { uri?, auth?, timeout? })` → `void`. New: `connect(credential?, options?: { uri?, timeout? })` → `Promise<ConnectResult>`. The `auth` property inside options is removed; pass the credential as the first argument. The numeric-only shorthand `connect(5000)` is removed.
- **`DataPipe` errors changed from `Error` to `PipeException`**: `open()`, `write()`, and `close()` now throw `PipeException` (extends `Error`) instead of plain `Error` when the server reports a failure. Callers catching `Error` are still compatible; callers matching on error message strings may need to update. `PipeException` carries the full DAP response body.
- **`setConnectionParams()` removed**: use `login(credential, { uri })` or call `attach(newUri)` + `login()` instead.
- **Project store methods removed**: `saveProject()`, `getProject()`, `deleteProject()`, `getAllProjects()` are deleted. Use the new filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`.
- **`validate()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ValidationResult` (typed interface with `valid`, `errors`, `warnings` fields).
- **`getServices()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ServicesResponse` (typed interface).

#### Both SDKs: new exception types

- **`PipeException`** (Python: subclass of `RuntimeError`; TypeScript: subclass of `Error`): thrown by `DataPipe.open()`, `.write()`, `.close()` when the server reports failure. Carries the full DAP response including `message`, `body`, and error code. Replaces generic `RuntimeError` / `Error`.
- **`ConnectionException`** (TypeScript): thrown on transport-level failures.

### Added

#### New Nodes
- **Exa Search**: semantic web search node integrating with the Exa API (exa.ai) for real-time data enrichment in pipelines. Agents invoke the tool to search the web and retrieve structured results including titles, URLs, text content, relevance scores, and published dates. Includes configurable `numResults` with min/max validation, retry exception sanitization to prevent API key leakage, and defensive boolean config parsing (#386, #509)
- **Bland AI**: voice call tool node for AI-driven phone calls via the Bland AI platform (#521)
- **OpenAI Compatible**: generic LLM node supporting any OpenAI-compatible API endpoint, allowing connection to self-hosted or third-party inference servers that follow the OpenAI chat completions API (#518)
- **GMI Cloud**: LLM connector for GMI Cloud inference platform (api.gmi-serving.com) hosting 100+ models on H100/H200 GPUs. Two tiers: shared (always-on, key-only: DeepSeek, GPT, Claude, Gemini) and deploy-on-demand (endpoint URL + key: Llama 4, Qwen3). Custom profile for arbitrary model/endpoint combinations (#540)
- **Guardrails**: AI safety node with comprehensive input/output validation. Input: prompt injection detection (regex + keyword scoring), topic restriction (allowed/blocked keyword lists), input length enforcement (char + token limits). Output: hallucination detection (sentence-level grounding), content safety (self-harm, violence, illegal activity patterns), PII leak detection (email, phone, SSN, credit card, IP), format compliance (JSON, markdown, bullet/numbered lists). Policy modes: block/warn/log. Profiles: basic (injection + PII), strict (all checks), custom. 87 tests (#534)
- **Video Embedding**: extracts frames from video input (MP4, AVI, MOV, WebM) at configurable intervals and generates vector embeddings using CLIP/ViT models for semantic search and RAG pipelines. Configurable frame interval, max frames, start time, duration, and max video file size (default 500 MB) to prevent unbounded memory. VideoCapture resource leak fixed with finally block (#516)
- **Kokoro TTS**: self-contained text-to-speech node using the Kokoro engine. Slim requirements (no piper/transformers/cloud). KokoroLoader, spacy_en_model, wav_to_mp3 utilities. Supports question, answer, and document lanes (RR-411, #662)
- **Telegram Bot**: source node connecting a Telegram bot to a pipeline via long polling or webhook. Routes incoming messages to appropriate lanes by content type (text, image, audio, video, documents) and sends pipeline responses back as replies (#659)
- **GitHub Tool**: tool node for GitHub API operations (issues, PRs, repositories) with full test suite for tool calling (#640)
- **Git Tool**: self-contained Git operations using pygit2 (libgit2), no host git binary required. Capabilities: clone, init, status, log, show, diff, blame, file_at, ls_files, grep, stage, commit, stash, branch create/checkout/merge/delete, fetch, pull, push (token + SSH auth), write_file with path-traversal guard. Safe mode (default on) blocks force-push and force branch deletion. Full unit test suite + integration tests (activated via `GIT_TEST_REPO_PATH` env). Includes `git_agent_example.pipe` (#654, #731)
- **Filesystem Tool**: file system operations (read, write, list, mkdir, delete) with path whitelist security check via `_prepare()` method. Operations can be selectively enabled/disabled at the node level. Shared prologue extraction via keyword flags (path_required, needs_encoding, needs_content) (#682)
- **Pipeline Tool**: run pipelines as tool calls from other pipelines, enabling pipeline composition and hierarchical agent workflows (#647)
- **LLM Vision (Gemini)**: image understanding via Gemini models with cache management (non-symmetric cache + empty frame guard)
- **LLM Vision (OpenAI)**: image understanding via OpenAI vision models
- **Webhook**: question lane support for webhook-triggered pipelines (#431)
- **CrewAI Orchestrator**: multi-agent orchestration via CrewAI framework. Exposes expert config fields (goal, backstory, expected_output, max_iter) for both agent and orchestrator node types. Advanced mode for fine-grained control. Sub-agent config propagated through `crewai.describe()`. Manager node renamed from Orchestrator, tool invoke removed from manager (#608)

#### VS Code Extension
- **Engine management overhaul**: replaced scattered engine lifecycle code (connection/, deploy/) with a clean `EngineBackend` hierarchy under `src/engine/`. Each connection mode (local, service, docker, cloud, onprem) gets its own backend implementation. `EngineRegistry` singleton reconciler detects config changes (API key, host URL, etc.) via checksums and auto-restarts affected engines on settings save. Eliminated `engine:status` event, all progress flows through `shell:statusChange`. `ConnectionManager` becomes passive: connects on engine `ready`, disconnects on `idle`. Unified `ioControl` message pattern for all panel operations. Migration from legacy layout (`globalStorage` + `config.json`) to new structure. Welcome page uses same `applyAllSettings` + reconcile path as Settings (#922)
- **Settings overhaul & target panels**: atomic settings save via `ConfigManager.applyAllSettings()` with `isBatchApplying` flag suppressing intermediate change events (eliminates race conditions from writing 20+ config keys individually, which caused connection managers to react to half-written state). Self-contained panels per mode (Local, Cloud, OnPrem, Docker, Service) handling both configuration and operational UI (status, install/start/stop/remove/update, progress, version selection). `EngineOperations` service extracted from `PageDeployProvider`. Deploy page command redirected to Settings. `useTheme` hook for VS Code dark/light detection. Embedded Docker/Service SVG logos. Build config consolidated: `.config` as single source of truth for Zitadel URLs/client IDs, esbuild loads `.config` first then `.env` on top, stopped name remapping of Zitadel keys. Cloud mode no longer hardcodes a non-existent URL, uses `config.hostUrl` at runtime (#725)
- **Standalone Variables page**: new "Variables" webview accessible from sidebar footer for managing `ROCKETRIDE_*` environment variables per connection slot (Development/Deployment). `EnvironmentProvider` with per-slot client resolution, `EnvironmentWebview` with pill bar for slot selection. OSS servers show single "Server Variables" card; SaaS servers show Organization/Team/User cards gated by permissions. `set_env` now updates `os.environ` in-memory before writing `.env` file. Deploy connection fix: removed `isSharedMode()` guard that skipped engine status listener registration. `commonStyles.tabContent` now uses `border-box` sizing. Removed capabilities filter that hid Cloud option. All "Environment" labels renamed to "Variables"
- **`${ROCKETRIDE_*}` variable autocomplete**: node config fields now offer autocomplete suggestions for defined pipeline variables. `useEnvVarAutocomplete` hook detects `${` trigger and filters keys by partial match. `EnvVarSuggestions` popover with arrow-key navigation. Wired into `BaseInputTemplate`, `TextareaWidget`, and `ApiKeyWidget`. `transformErrors` suppresses RJSF validation errors for fields containing `${ROCKETRIDE_*}`. `rrext_validate` now resolves env vars before validation using the same merged env as pipeline execution. Fixed `getHttpUrl()` to normalize engineUri before parsing
- **Category headers in QuickAddPopup**: compatible services grouped by bold uppercase category headers with indented items. Shared `CATEGORY_TITLES` extracted to `categoryTitles.ts`. `CreateNodePanel` auto-expands matching categories during search, restores previous expand/collapse state when search is cleared. Environment protocol types extracted to prevent build errors
- **Server Monitor panel**: real-time dashboard showing connections, tasks, and aggregate metrics via new `getDashboard()` / `get_dashboard()` SDK methods (DAP `rrext_dashboard` command). Client identification (`clientName`/`clientVersion`) forwarded during auth handshake so server can distinguish "VS Code 0.9.4" vs "CLI 1.2.0". Python DAP client skips auth message when transport lacks `get_auth()` (fixes crash for non-WebSocket transports). Consolidated `ServicePython` log level into `DebugOut` (#595)
- **Other task viewer via ProjectWebview**: `PageStatusProvider` completely rewritten. Previously opened a lightweight `StatusWebview` that couldn't show the node graph (nodes squashed at top, no toolbar, missing servicesJson). Now fetches unresolved pipeline via `getTaskToken` + `getTaskPipeline`, creates panel using the full Canvas/ProjectView stack, sends `project:load` with `isReadonly:true`. Falls back to synthesized single-node project if fetch fails. `StatusWebview` deleted (#803)
- **Readonly canvas**: single `isReadonly` prop replaces two inconsistent lock mechanisms (14-boolean `IFlowFeatures` and partially-implemented `isLocked`). `effectiveLock = isReadonly || internalIsLocked`. Guards added to `addNode()`, `updateNode()`, `deleteNode()`, paste, context-menu, lane click, config panel Save, all previously unguarded. Lock button hidden when `isReadonly` (#803)
- **Save button in canvas toolbar**: always-visible floppy disk icon with dirty-state tracking; grayed when clean, brand-colored when dirty. `isDirty`/`isNew`/`onSave` threaded through `IFlowProps` → `FlowContainer` → `FlowProvider` → `FlowProjectProvider`. `FlowCanvas` defers ReactFlow render until container has non-zero dimensions via `ResizeObserver`. `canvas:requestSave` calls `document.save()` directly (#678)
- **Dirty-state save pattern for settings**: card header starts clean (no buttons); on edit, Cancel and Save appear; on save, buttons disappear and "Saved" flashes for 5 seconds then fades; Cancel reverts to last-saved snapshot. Applied to all 5 VS Code settings tabs and shell-ui settings page (#877)
- **Play button shows actionable text**: renamed idle label from "Play" to "Run Pipeline". Added STOPPING state with "Stopping..." disabled button to prevent double-clicks. Widened hover expansion for longer label. Smooth CSS transitions with easing functions (#575)
- **Improved stop button feedback**: Pipeline Observability screen handles `TASK_STATE.STOPPING` with "Stopping..." disabled state and distinct orange styling, preventing duplicate clicks (#549)
- **Simplified sidebar footer**: replaced popup menu (three redundant gear icons all opening Settings) with flat layout when connection is shared and no cloud account. Documentation and Settings buttons rendered directly, connection status inline, announcements ticker rotates cards every 7 seconds. Full popup preserved for cloud account or independent connections. Panel sash restyled with native `--vscode-sash-hoverBorder` token, widened from 2px to 4px
- **Test Connection button**: available on service/docker/onprem panels via `ioControl('test')`
- **Docker GHCR tag fetching**: global cache for prerelease resolution with 15s timeout on HTTPS requests. Split-button dropdowns with grouped "Recommended" / "All versions" headers. Version metadata persisted per instance lifecycle. Linux package manager auto-detection (apt/dnf/yum/pacman) instead of hardcoded apt-get
- **Version tracking**: persistent `version.local.json`, `version.service.json`, `version.docker.json` files. PID liveness check before preserving `.pid` files during engine dir clear. Guard against phantom installs (missing binary). UAC-cancel fallback and uninstall.ps1 fixes
- **Event naming unification**: all connection events renamed to `shell:*` namespace matching cloud-ui vocabulary. `'event'` → `'shell:event'`, `'connected'` → `'shell:connected'`, `'connectionStateChanged'` → `'shell:statusChange'`, etc. All 10 providers renamed to drop redundant `Page` prefix. All 9 view directories renamed similarly (#803)
- **`.env` file management removed**: ~350 lines of env file handling removed from `ConfigManager` (envFileWatcher, envRawText, parseEnvFile, saveEnvFile, syncSettingsToEnv, etc.). Environment variables for pipeline variable replacement are now managed server-side (layered env in DB). Extension no longer maintains workspace `.env` file. URL resolution consolidated into `ConnectionManager` (per-group, not hardcoded to dev group) (#803)
- **On-demand env loading**: replaced 7 env-specific `AccountView` props with 2 generic callbacks (`onLoadEnv`, `onSaveEnv`) plus `refreshSignal`. Each `EnvScopeCard` requests its own data on mount. Promise-based messaging with 10s timeout. `shell:accountUpdate` as first-class event (no longer filtered from generic stream). Standalone `BillingProvider` deleted; billing is a tab inside Account (#803)
- **Welcome page simplification**: `welcomeDismissed` set automatically on save (no manual checkbox). Works from both Welcome and Settings pages (#803)

#### Shell UI (Web Host)
- **Shell-ui replaces cloud-ui**: new Module Federation host application served by Python `shell` module (`ai.modules.shell`) with public HTTP routes for SPA and all static assets under `/shell/`. Unifies OSS and SaaS into single codebase. Server-side app manifest delivery via `get_public_apps()` / `get_apps_for_user()` on AccountBase. Pre-auth info probe returns public apps for marketplace. Connect response includes authenticated user's full entitled app list (#803)
- **MUI removal**: replaced Material UI with plain CSS/HTML across entire shared-ui package; runtime theme system with light/dark JSON tokens
- **Theme rebrand**: replaced legacy purple (#5900FF) with cyan (#00b9ec) TOKENS palette. Light theme updated to warm-neutral (cream/stone backgrounds instead of pure white) (#803)
- **Theme flash fix**: `index.html` inline script sets `--rr-bg-default` and body background synchronously before React renders. `createShellConfig` reads saved theme from localStorage instead of always defaulting to rocketride-light, eliminating tan background during 1.5s OAuth code-exchange window (#878)
- **Chat module**: host-agnostic chat surface following established module pattern (props-in, callbacks-out, `--rr-*` CSS tokens). `ChatView` (MessageList + ChatInputField), `MessageBubble` (user/bot/system/status with markdown), `MarkdownRenderer` (react-markdown + GFM + syntax highlighting + charts), `ChartRenderer` (chart.js with circular-reference guard), `TypingIndicator` (animated bouncing dots), `useChatMessages` hook (message state + sendMessage + monotonic IDs) (#724)
- **Canvas state persistence**: viewport (zoom/pan), lock state, snap-to-grid, and editor mode now persist in `.pipe` files via `PipelineConfig` schema (TypeScript + Python SDKs). New `isFlowReady` boolean state tracks when all nodes have been rendered/measured by ReactFlow, replacing scattered `setTimeout`/`requestAnimationFrame` workarounds. Centralized `loadCanvas(nodes, edges)` as single entry point for structural canvas changes. Viewport restored on load via `isFlowReady` cycle, falls back to fitView. Spiral search for non-overlapping node placement. `EmptyCanvasPrompt` only shown when `nodes.length === 0 AND isFlowReady` (#670)
- **ProjectView architecture**: decomposed monolithic `modules/flow/` canvas module into composable multi-view project architecture (#670)
- **Style consolidation**: added `buttonPrimarySmall`, `buttonSecondarySmall`, `buttonDangerSmall`, `modalDialog`, `modalHeader`, `modalBody`, `modalFooter` to `commonStyles`. Added `cardHeaderButton`/`cardBodyButton` size modifiers for card contexts. Eliminated `Btn` wrapper component. Account `shared.tsx` trimmed from ~30 to 9 entries. All emojis removed from account UI (#803)
- **Shared connection types**: `ConnectionState` enum, `ConnectionMode`, `IAuthProvider`, `IConnectionManager` interface, `ShellAppEntry`, `ShellConnectionEventMap` with typed payloads for all `shell:*` events. Index signature for app-defined events (#803)

#### Billing, Account & Auth
- **Billing detail**: `BillingDetail` type gains `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart` in both SDKs. Subscription cards show detail grid with plan info. Cancel subscription requires confirmation modal. App display name shown instead of raw appId. Credit grant summary per subscription using `creditLabels` from Stripe metadata (#803)
- **Account/Billing merge**: Billing is now a tab inside Account (2nd pill) via `BillingPanel`. Standalone Billing page and provider deleted
- **Permission enforcement**: frontend computes `isOrgAdmin`/`isTeamAdmin` from profile; action buttons hidden for users without required permissions; `OrganizationPanel` read-only for non-admins; destructive actions go through confirmation modals. Team admin enforcement: must always have ≥1 admin (UI + server guard). Permission key fixed: `'admin'` → `'team.admin'`. `_require_team_admin` queries DB directly instead of stale cache (#803)
- **Team-based task permissions**: replaced all `control.userId == caller.userId` ownership checks with `resolve_task_permissions()` so teammates and org admins can monitor/control each other's tasks. Permission strings (e.g. `'task.control'`, `'task.monitor'`) checked against resolved list (#803)
- **Layered environment secrets**: pipeline variables (`ROCKETRIDE_*`) stored encrypted (Fernet) in database per org/team/user scope, merged server-side during task execution. Merge order: `.env` → org → team → user → caller env. `get_merged_env()` on `AccountBase` with OSS (`.env` only) and SaaS (DB) implementations. `client.use()` `env` param for caller overrides (only `ROCKETRIDE_*` accepted). Client-side `processEnvSubstitution` removed, resolution is server-only (#803)
- **Session keys**: API keys are now true PATs inheriting user identity. `is_session` flag on `ApiKey` model. `ensure_session_key()` on every OAuth login: refreshes 90-day expiry if active, creates fresh key if expired/missing. Session keys cannot be self-revoked. Admin revoke is hard-delete. Housekeeping: keys revoked >30d purged on login. UI shows "Session" / "Interactive login" badge (#803)
- **Scoped PATs**: PATs optionally restricted to single team with explicit permissions. Effective permissions intersected with user's actual permissions at auth time (can never escalate). Optional `team_id` on `ApiKey`. Create key modal: team dropdown + conditional `PermGrid`. Key list shows team scope badge (#803)
- **userToken → userId refactor**: server-side event tenant scoping uses `userId` instead of `userToken`. Fixes bug where two connections from same user with different keys wouldn't see each other's dashboard events (#803)
- **Account UI overhaul**: all card headers use `commonStyles.labelUppercase`. Save button pattern: hidden until dirty, shows [Cancel][Save], "Saved" green text with 5s timer. `ProfilePanel`: single "Organizations / Workspaces" card with nested teams. `TeamsPanel`: Delete moved to list with confirm modal. `PermGrid`: `PERM_DISPLAY` labels, alphabetized, added `task.store`, contrasting text on checked tiles (#803)
- **Client SDK attach/login split**: replace monolithic `connect()`/`disconnect()` with layered API: `attach(uri?)` opens WebSocket without auth (for public APIs like catalog), `login(credential?)` sends DAP auth, `logout()` sends new `deauth` command (reverts to unauthenticated without closing socket), `detach()` tears down WebSocket. Old `connect()`/`disconnect()` preserved as backward-compatible wrappers. Reconnection engine rewritten around `_desiredState` model ('detached' | 'attached' | 'authenticated'). Linear backoff (250ms increments, 15s cap), reconnection never gives up. Auth credential removed from transport layer (#803)
- **Server-driven appStatus**: replaced `subscriptionStatus` with server-computed `appStatus` ('auth' | 'free' | 'unsubscribed' | 'subscribed' | 'trialing' | 'past_due' | 'canceled') and `onDesktop` boolean per app manifest entry. Eliminates client-side reconciliation races (#803)
- **App mode & subscription gating**: `mode` field (free/subscription/paywall) in app manifests. Shell-level subscription gate blocks app iframe until active subscription exists. Desktop app management moved into account identity flow (#803)
- **Token storage hardened**: moved from `localStorage` to `sessionStorage` (cleared when tab closes) addressing CodeQL "Clear text storage of sensitive information" alert (#803)

#### Profiler
- **DAP-based cProfile system**: replaced HTTP-endpoint profiler module with per-process cProfile profiling over DAP connections. Any connected client can profile any process (task server, data engine subprocesses, model server). `CProfileManager` singleton with start/stop/status/report/release API. Owner tracking per connection with disconnect cleanup. SDK methods: `cprofileStart`/`cprofileStop`/`cprofileStatus`/`cprofileReport` (TS + Python) with optional `target` parameter for pipeline profiling. New `profiler-ui` Module Federation remote app with `ProfilerView`, `ConnectionManagerView`, and `ProfilerSidebar` (#803)

#### Module Federation
- **MF stability**: added `runtime: false` to all remote apps (shell-ui provides shared runtime; without it each remote embeds its own runtime copy, causing remoteEntry.js to change on every rebuild and version-mismatch errors during HMR). Added `eager: true` to react/react-dom shared configs (breaks async shared-scope negotiation deadlock where host waits for remote's async chunk and remote waits for host). App loader filters out server-only entries with no `remoteEntry` URL (prevents `normalizeRemote()` crash on `undefined`) (#877)

#### Engine & Core
- **Database EXECUTE**: direct SQL/Cypher execution via `QuestionType.EXECUTE` with `client.database.query()` namespace on both SDKs, bypassing LLM translation and safety gating. Gated behind opt-in `allow_execute` config (default off). Results bounded with `fetchmany(max_execute_rows+1)` (default 25000). Neo4j results capped at same limit. `allow_execute` parses strings strictly: only `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive). EXECUTE output wrapped in try/except; serialized with `default=str`. SDK validates non-empty token/sql before dispatching
- **Database DIALECT**: `QuestionType.DIALECT` for engine capability discovery. SDK callers can ask which engine a database pipeline is connected to (`DatabaseDialect` enum). `_db_dialect()` abstract method on `DatabaseInstanceBase`. `services.json` now exposes UI-toggleable `allow_execute` boolean
- **Handle-based streaming I/O**: generic filesystem-style interface (`open`/`read`/`write`/`close`/`delete`/`stat`/`mkdir`/`list_dir`) on `FileStore`, replacing monolithic in-memory buffering. Domain methods become thin convenience wrappers on client SDKs. Supports S3 multipart upload (5 MB buffer), Azure staged blocks (4 MB buffer), and local filesystem. Handles tagged with owning `connection_id` and force-closed on connection termination (#600)
- **`@tool_function` decorators**: collapsed the two-class pattern (IInstance + ToolsBase driver) into a single class. Any `IInstanceBase` subclass can declare tool entry points with a decorator; the method name becomes the tool ID, decorator carries schema/description, base class `invoke()` dispatches automatically. Eliminates parallel driver classes, factory methods, and boilerplate delegation (#599)
- **Experimental + Deprecated capability flags**: `DEPRECATED = BIT(15)`, `EXPERIMENTAL = BIT(16)` in `PROTOCOL_CAPS`. Both flags wired through C++ parser, pybind11 bindings, both client SDKs, and shared-ui. Yellow "EXPERIMENTAL" badge rendered on canvas nodes, Add Node slider, and Quick Add popup (#606)
- **Docker-compose and healthcheck**: `HEALTHCHECK` instruction in `Dockerfile.engine` using curl to `/ping`. `docker-compose.yml` with engine, PostgreSQL+pgvector, Milvus (+ etcd, MinIO), ChromaDB. Override file for dev hot-reloading. All images pinned to specific versions. Security warnings in `.env.example` (#496)
- **Billing commands mixin**: `BillingCommands` in TaskConn's MRO for `rrext_account_billing`. OSS implementation routes on `arguments.subcommand` with stubs so UI doesn't hang in half-rendered state (#692)
- **Task engine extraction**: `task_engine` and `cmd_data` extracted as standalone modules (#661)
- **GPU inference billing**: `metrics.resource('gpu')` context manager times inference. `CONST_RATE_GPU_INFERENCE_SECOND` for billing. Custom node counters (`pagesProcessed`, etc.) with configurable rates. All 9 AI model files wrapped with `metrics.counter('gpu_inference_count')` + `metrics.resource('gpu')`. Billing reports include `gpu_inference` and `custom` token fields (#803)
- **Metrics rewrite**: replaced Timer class and `resource()` context manager with flat `MetricsManager`: `timer()`, `add_time()`, `counter()`, `event()`. Thread-safe via single lock. Removed per-pipe `ContextVar`, metrics are per-subprocess. ModelClient auto-records server-reported perf dict (#803)
- **ModelClient refactor**: derived from `RocketRideClient` with `ws_path='/models'` so URI normalization, protocol selection, and auth are handled by SDK. Python SDK gains `ws_path` kwarg. Sync `disconnect()` override for worker thread callers. All 9 model wrappers updated. `get_model_server_address()` simplified to return raw string (#877)
- **Model server DAP namespace**: all model server commands renamed to `rrext_ms_*` prefix (load_model → rrext_ms_load_model, etc.) for disambiguation from core DAP commands (#803)
- **GPU guard**: `install_gpu_guard()` blocks direct torch/tensorflow imports in model server mode; all GPU inference must go through ModelClient RPC (#803)
- **Pipeline error surfacing**: `binder.cpp` sets `completionCode` on Entry when `callMethods` encounters error. `bindings.cpp` exposes `completionError` read-only property. `data_conn.py` rewrites `close_sync()` to always extract results even when end/close throws, surfaces `Entry.completionError` when `objectFailed` is True. Errors now reach dropper UI (#803)
- **`rrext_get_pipeline` DAP command**: returns task's unresolved pipeline (with `${...}` placeholders intact) so VS Code can reconstruct node graph without exposing secrets. `_build_task()` now accepts explicit resolved pipeline, `self._pipeline` retains original unresolved form (#803)

#### Client SDKs: New Features

**Layered connection API (both SDKs):**
- `attach()` / `detach()`: open/close the WebSocket without authentication. Enables unauthenticated operations (public catalog browsing, server probes) before the user logs in
- `login()` / `logout()`: authenticate/deauthenticate over an attached transport. `login()` returns `ConnectResult` with full user identity (userId, organizations, apps, teams, permissions). `logout()` sends new `deauth` DAP command, reverting to unauthenticated without closing the socket. Supports credential rotation (auto-logout if a different credential is supplied)
- `connect()` / `disconnect()` preserved as backward-compatible wrappers (`attach` + `login` / `logout` + `detach`), but `connect()` now returns `ConnectResult` instead of void
- `isAttached()`: true when WebSocket is open (regardless of auth)
- `isAuthenticated()`: true when auth handshake has succeeded

**Namespaced API accessors (both SDKs):**
- `client.account`: profile, API keys, org, members, teams, environment variables (`get_env()` / `set_env()` / `get_environment_keys()`)
- `client.billing`: subscriptions, checkout, credits, cancel
- `client.database`: `client.database.query()` for direct SQL/Cypher execution; `client.database.dialect()` for engine discovery (`DatabaseDialect` enum)

**New methods:**
- `RocketRideClient.getServerInfo(uri)` (static): probe a server for capabilities without authenticating. Returns `ServerInfoResult` with version, capabilities, platform, and public apps
- `getTaskToken(projectId, source)`: resolve a running task's session token
- `getTaskPipeline(token)`: retrieve the unresolved pipeline for a running task (placeholders intact, no secrets)
- `getDashboard()`: real-time server dashboard (connections, tasks, metrics)
- `cprofileStart/Stop/Status/Report`: per-process cProfile profiling over DAP
- `call(command, token?, **kwargs)` (Python): single public entry point for all typed DAP operations with optional `on_trace` callback

**TypeScript-specific additions:**
- `wsPath` config option for custom WebSocket paths (e.g. `'/models'` for model server)
- `onTrace` callback for observing all `call()` traffic
- `MonitorKey` type and `addMonitor()` / `removeMonitor()` for reference-counted monitor subscriptions
- `restart()` method for restarting pipeline tasks
- Filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`: replaces the old project store methods
- `getTaskStatus()` applies default 15s timeout (configurable via `options.timeout` or `{ timeout: false }`)
- `validate()` now returns typed `ValidationResult` (was `Record<string, unknown>`)
- `getServices()` now returns typed `ServicesResponse`; `getService()` returns `ServiceDefinition`
- `DataPipe.open()` sets `_opened` only after successful SSE setup with rollback on failure
- `normalizeUri()` preserves user-specified port (was being stripped for scheme-default ports like :443)

**Python-specific additions:**
- `ws_path` kwarg for custom WebSocket paths
- `client_name` / `client_version` kwargs forwarded in auth handshake for client identification
- `on_trace` callback for observing all `call()` traffic
- `public` mode for permanently unauthenticated connections (only `rrext_public_*` commands)
- `DashboardMixin`, `CProfileMixin`, `StoreMixin` added to MRO
- Improved `send()` pipe error context with `PipeException` (catchable as `RuntimeError`)

**New types (both SDKs):**
- `ConnectResult`, `ServerInfoResult`, `AppManifestEntry`, `StripePriceEntry`
- `AccountProfile`, `AccountOrganization`, `AccountOrgTeam`, `ApiKeyRecord`, `OrgDetail`, `MemberRecord`, `TeamRecord`, `TeamDetail`, `TeamMemberRecord`
- `BillingDetail` (extended with `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart`, `credits`, `creditLabels`), `StripePlan`, `CreditBalance` (extended with `labels`), `CreditPack`
- `PROTOCOL_CAPS` enum with all 17 capability flags
- `SERVICE_DEFINITION`, `SERVICES_RESPONSE`, `VALIDATION_ERROR`, `VALIDATION_RESULT`
- `DASHBOARD_OVERVIEW`, `DASHBOARD_MONITOR`, `DASHBOARD_CONNECTION`, `DASHBOARD_TASK`, `DASHBOARD_RESPONSE`, `DASHBOARD_EVENT` and 7 event subtypes
- `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART` (replace old `EVENT_TASK`)
- `EVENT_STATUS` (replaces `EVENT_STATUS_UPDATE`)
- `TASK_TOKENS` extended with `gpu_inference` and `custom` fields
- `CreateKeyParams` accepts optional `teamId` for scoped PATs
- `EVENT_TYPE.DASHBOARD` flag (bit 7) for server-level events; `EVENT_TYPE.ALL` updated to include it
- **Config**: `Config.getNodeConfig()` emits warnings for deprecated profiles with migration guidance from profile's `migration` field

#### MCP
- **MCP Resources and Prompts**: `rocketride://` URI resources (pipeline list, server status, node registry) with graceful error handling for disconnected clients. Three prompt templates (analyze-document, chat-with-data, evaluate-pipeline) with required argument validation and message rendering. 44 tests (#541)

#### Agents & Pipelines
- **Agent framework overhaul**: ProjectView architecture with shared-ui migration (#670)
- **Example pipeline templates** for common AI workflows (#572)

#### Build System
- **Rsbuild upgrade**: all UI apps upgraded from pinned 0.4/1.1 to ~1.7.5, eliminating Node.js `DEP0180` deprecation warnings in Node 22+. ESM config migration (`.ts` → `.mts`). cmake minimum bumped from 3.14 to 3.19. `@rspack/binding-*` platform pins removed. Service config renamed `config.json` → `service-config.json` with migration (#905)
- **Build-input caching**: source fingerprinting (`buildInputHash()` + `hasBuildInputChanged()`) skips UI modules whose inputs haven't changed. `appModule.js` factory eliminates ~80 lines of boilerplate per app. Shell-ui tracks own src/ + shared-ui/src + package.json. `--force` flag bypasses caching. Clean actions clear cached hashes (#877)
- **Builder CLI**: `server:run` action (build + run without shell-ui dev server). `--taskserver=ADDR` replaces `--testport`. `--modelserver` semantics clarified (bare flag = start local, `=ADDR` = use existing). `--simulate-gpus=N` forwarded to model server. `parseServerAddress()` utility (#803, #877)

#### CI/CD
- **Cosign container signing**: keyless signing of rocketride-engine image via Sigstore + GitHub OIDC (signs by digest). GPG detached-signature step for server tarballs/zips, gated on `GPG_SIGNING_KEY` secret (#798)
- **Dependabot**: weekly version updates with smoke tests for litellm and pipeline-node deps. Blocked rsbuild/rslib/rspack 0.x churn and pip major bumps. Semver-major ignores across all 10+ ecosystems (#788, #843, #842, #862)
- **Experimental-release workflow**: `workflow_dispatch`-only, builds from arbitrary branch under configurable tag suffix. Per-product release jobs. No marketplace publishing. `prerelease: true`. First use case: workshop builds (#848)
- **Nightly prereleases**: initially from stage branch (#631), moved to develop on green CI (#713). `workflow_dispatch` expanded to develop/stage/main (#906)
- **Daily Actions storage cleanup** workflow (#636)
- **Discord notifications**: PRs, issues, discussions with live CI check status and PR state tracking in embed (#612, #614, #638). Duplicate posts on discussion edits prevented (#698). Retry/backoff for webhook calls (#797)
- **Ruff and gitleaks**: pre-commit checks (#722); gitleaks made blocking (#681); `ruff format` applied to all Python files (#723)
- **Sequential builder tests** to isolate cross-suite flakes (#734)
- **cmake 4** support (#807)
- **Actions pinned** to immutable commit hashes (#483)
- **Artifact retention** dropped to 1 day for 0.5 GB storage cap (#779)
- **CodeQL** switched from advanced to default setup (#768)

#### Documentation
- **Observability & tracing**: integration guide documenting how external services consume runtime logs, lifecycle events, and pipeline traces over the WebSocket DAP channel. Wired into all agent stubs (Claude Code, Cursor, Windsurf, Copilot) (#716)
- **Node usage guides**: `db_neo4j` with practical examples (#490), `llm_openai` with provider examples (#493), source connectors (#650)
- **Per-node documentation** overhaul, added and updated docs for each node (#639, #660)
- **Engine**: Tika ExternalParser media tool requirements (#729)
- **Python client**: clarified `send()` sources and `.pipe` usage (#705); updated Python 3.8 → 3.10 references (#657); added `.env.example` (#492)
- **Contributing**: require green CI checks before review (#627)
- **SOC2-ready SECURITY.md**: explicit triage/remediation SLA (critical 7d, high 30d, medium 90d), scanning toolchain documentation (CodeQL, Scorecard, Trivy, Dependabot, secret scanning), quarterly access reviews (#762)
- **Two-person control** on alert dismissals documented (#800)
- **Code of Conduct** (#591)
- **README improvements**: onboarding wording, absolute image URLs, GIFs, Product Hunt badge (#706, #506, #478, #590)

#### Security Policies
- **Workflow permissions**: top-level permissions added to 5 reusable workflows (#790); storage-cleanup narrowed to job-level (#794)
- **Stale lockfile removed**: `packages/client-typescript/pnpm-lock.yaml` deleted, override declared in root (#796)

### Changed

- **LLM provider migration**: all LLM providers migrated to `ai.common.LLMBase` (#719); automated LLM model sync tool fetches models from provider APIs, smoke-tests new ones, merges into `services.json` with smart deprecation and three-source token limit resolution (provider API → OpenRouter → LiteLLM). `modelSource` field tracks discovery origin. Weekly CI workflow opens PR with sync report. `builder models:update` command (#651)
- **llm_gemini model profiles**: added `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-image-preview`; standardized `gemini-2.5-*` dot notation; deprecated profiles retained with migration guidance
- **Removed `llm_vertex` node**: Vertex AI now supported via `llm_gemini`; migrated vision nodes to `LLMBase`; fixed `llm_gemini` API key validation (dropped strict `startsWith('AI')` check, added sub-key fallback for old pipe files where sub-key is `profile.split('_',1)[1]`); fixed `validateConfig` to early-return when apikey is empty (secure fields not decrypted at validate time); removed vertex icon from UI; bumped client-typescript SDK to 1.1.0 (#902)
- **OpenAI models** updated to latest (#503); deprecated Gemini models removed (#500)
- **Service config cleanup**: removed obsolete `input` section from 72 service configuration files (was duplicate of lane declaration, closes #629) (#728)
- **Milvus node**: configurable timeout (default 60s, was hardcoded 20), connection error handling with meaningful messages, bulk insert with configurable batch size (default 50, was one-at-a-time), `_batchUpsertResults()` helper for markDeleted/markActive, timeout on `remove()`, COSINE distance score range [0,2] rescaling documented (#562)
- **Node tests parallelized** with pytest-xdist (#700)
- **Tool input helpers**: `normalize_tool_input()` replaces 4 copy-pasted variants across tool nodes. `require_str`/`require_int`/`optional_str` replace local validators (44 callsites in `tool_github`). `require_str` now raises `ValueError` cleanly on non-string inputs (was `AttributeError`). `require_int` rejects `bool` (an `int` subclass). 41 unit tests (#759, #766)
- **Backward-compat DAP token fallback**: `get_task_token()` checks `arguments.token` first, falls back to `request.token` for older clients (#902)
- **pnpm** pinned via `packageManager` field (#623)
- **Version bump**: all release packages bumped to next minor (server 3.1.2 → 3.2.0, chat/dropper-ui 2.0.1 → 2.1.0, all others 1.0.x → 1.1.0)
- **engines.node** bumped from ≥18.0.0 to ≥20.0.0 (aligns with serialize-javascript@7 requirement and CI reality)
- **Provisioning**: creates Development + Production teams (Production default); `build_api_key` uses random nonce
- **VSCode detection**: chat-ui/dropper-ui changed from `window.parent !== window` to checking for `acquireVsCodeApi` (canonical detection)
- **Lefthook**: sequential mode; disabled colors to fix terminal corruption on Windows

### Fixed

#### Security
- **Critical: RCE**: prevent arbitrary module injection via `/use` endpoint. Added `ALLOWED_MODULES` frozenset whitelist restricting dynamic imports to 10 known service modules. Requests for any other module return 400 (#342)
- **Critical: Injection**: prevent filter expression injection in Milvus vector store (#355)
- **Auth**: require authentication for profiler endpoints; escape HTML output (#362)
- **Env expansion**: restrict `${VAR}` expansion in pipeline configs to allowlisted prefixes (`ROCKETRIDE_`, `PIPELINE_`, `NODE_`, `ROCKET_`); all others replaced with `<REDACTED>` to prevent exfiltration of AWS keys, DB URLs, tokens (#359)
- **Temp files**: use secure temporary file creation in task engine (#356)
- **SQL safety**: switch from blacklist to allowlist approach (#577)
- **Path traversal**: use `pathlib.is_relative_to` checks (#580)
- **Redaction**: expand sensitive field redaction patterns in VS Code logger (#578)
- **Input validation**: add validation/sanitization to LLM chat drivers (#559)
- **Rate limiting**: add rate limiting to `tool_http_request` node (#560)
- **Remote nodes**: improve error handling in remote node execution (#565)
- **Pinned deps**: handlebars + protobufjs via pnpm.overrides (#783)

#### Client SDKs: Fixes
- **Python client**: break drain cycle causing `RecursionError` on disconnect, `_drain_message_tasks` walks each candidate's `_fut_waiter` chain and excludes tasks that transitively await the drainer itself, so the gather can never close back on itself. `dap_client.request()`'s `ConnectionError` handler now uses fire-and-forget `self._transport.disconnect()` instead of `await self.disconnect()` (develop's `disconnect()` is sync-returns-Task). Two regression tests pinning each fix (#792)
- **Python client**: clean pending DAP request on send failure, prevents zombie futures accumulating on flaky connections when the WebSocket drops mid-request (#736)
- **Python client**: align `requires-python` with monorepo target (py310), was still declaring py38 (#491)
- **Python client**: `set_env` now updates `os.environ` in-memory (removes stale `ROCKETRIDE_*` keys, then sets new values) before writing the `.env` file, so `get_env` reflects changes immediately without a server restart. Uses `sys.executable` instead of `sys.argv[0]` for the `.env` file location
- **Python client**: `ws_path` composition uses `parsed._replace` instead of string concatenation to avoid malformed URIs
- **Python client**: popped consumed kwargs (`ws_path`, `client_name`, `env`, etc.) before passing to `super().__init__()` to avoid "multiple values for keyword argument" `TypeError`
- **TypeScript client**: preserve user-specified port in `normalizeUri`, the URL API silently strips scheme-default ports (:443 on https, :80 on http); now checks raw input for explicit `:digits` after the scheme before deciding whether to add default port (#377)
- **TypeScript client**: `DataPipe.open()` sets `_opened` only after successful SSE setup; on `setEvents` failure, rolls back via `close()` so the server pipe is not left half-open. `close()` now also handles the case where server assigned `pipe_id` but `_opened` was never set to true (#704)
- **TypeScript client**: `DataPipe.close()` sets `_opened = false` in the finally block, preventing double-close races
- **TypeScript client**: `connect()` treats empty or whitespace-only `ROCKETRIDE_APIKEY` in the client env snapshot as **unset**, so it does not override constructor-provided auth (#704)
- **TypeScript client**: `getTaskStatus` applies a default per-request timeout of 15s so CI doesn't hang indefinitely on a dead task; callers can pass `options.timeout` (ms) or `{ timeout: false }` to skip (#704)
- **Both clients**: pipe error messages now include common-cause diagnostics (pipeline not running, wrong source type, MIME mismatch) to reduce debugging time
- **SDK connect error callback type** corrected, was typed incorrectly in the TypeScript client (#576)
- **`CreditBalance` type** aligned with backend camelCase wire shape (#714)

#### VS Code Extension
- **Chat webview blank screen**: realigned `view:ready` handshake so chat panel renders after extension reload (#688)
- **Explorer empty-state**: clicking +File/+Folder on empty PIPELINES tree was silent no-op (input row gated on `entries.length > 0`). Now renders input when root-level create is pending. Stale `selectedPath` falls through to root when all entries deleted (#901)
- **Annotation double-click**: annotation nodes advertised "Double-click gear to add content..." but gear was hidden until hover (CSS opacity:0→1), opened on single-click not double-click, and body had no `onDoubleClick`. Added `onDoubleClick` on annotation root, updated placeholder text (#901)
- **Team selector**: cloud team selector not appearing after sign-in because team fetching was embedded inside cached `probeServerInfo()`. Decoupled into separate `fetchCloudTeams()` driven by `useEffect([isSaas, cloudSignedIn])` (#877)
- **Billing app names**: subscription cards showing raw `appId` instead of human-readable name. Added full `apps` manifest prop chain so components build own `appId → app` lookup map (#877)
- **Canvas-played pipelines** now register in sidebar menu (#571)
- **Missing hostname** handled in URI parsing (#530)
- **OSX Python path** for Python-EaaS debugger (#693)
- **Dark mode**: fixed icon and edge visibility in flow builder (#597)
- **UI validation** fixes (#767)
- **Icons and coloring** for Bland, GMI, and trash bin (#634)
- **QuickAdd popup** label copy improved (#679)
- **Product Hunt badge**: converted SVG to PNG (marketplace rejects SVGs)

#### Engine & Nodes
- **LLM**: clear correct `_chat` reference in `endGlobal` across all LLM nodes (#531)
- **Milvus**: apply `retrieval_score_threshold` filter in `searchSemantic` (#726)
- **Database**: bound Neo4j EXECUTE rows; parse `allow_execute` strictly (only '1'/'true'/'yes'/'on')
- **Frame grabber**: user-configured interval was being ignored (#675)
- **Pipeline configs**: error handling for missing configuration files (#544)
- **Mutable defaults**: replaced mutable default arguments with `None` across Python nodes (#582)
- **Chunk scoping**: `_processFullTables` used stale `doc` variable from outer loop and called `Doc()` with invalid constructor params. Fixed to reset `page_content` on chunk itself. Follow-up: fixed score assignment that replaced Doc with float, and first-chunk aliasing that dropped text (#776)
- **Mock truthiness**: `psycopg2`: `isinstance(False, int)` is True, so `isDeleted=False` was matched as LIMIT value (added `not isinstance(p, bool)` guard). `chromadb`: `if limit and ...` treated `limit=0` as falsy (changed to `limit is not None`). `weaviate`: `distance if distance else 1.0` collapsed 0.0 (exact match) to 1.0 (changed to `distance is not None`) (#748)
- **Async safety**: `_message_tasks` set accessed from multiple async contexts without a lock (#535)
- **CLI shutdown**: SIGINT/SIGTERM handlers with proper exit codes (130/143), double-signal force exit, 5s cleanup timeout, idempotent `cleanupClient` via dedup promise, `isCancelled` guards on command actions, `run()`/`main()` shutdown awareness via `awaitShutdown()` (RR-655, #891)
- **setuptools**: bootstrapped alongside wheel for `uv pip compile`, legacy sdists (e.g. `docopt 0.6.2` via kokoro → misaki → num2words chain) need setup.py but uv doesn't supply setuptools when build isolation is off (#871)
- **Cloud port**: corrected from 433 to 443 in `services.json` (#684)
- **LLM providers**: small cleanup across all LLM nodes (#645)
- **Auth token precedence**: URL auth param prioritized over stale sessionStorage token from previous task (#902)
- **AVIReader**: capture errors from background `_data_process` thread and re-raise on `stop()` so pipeline errors surface as task errors (#803)
- **Webhook/Telegram nodes**: removed `server.use('profiler')` calls (profiler module was deleted; these caused "Module 'profiler' is not allowed" crash) (#803)
- **Task auth**: removed early `ValueError` on empty credential that prevented anonymous/no-key OSS connections from reaching auth check (#803)

#### CI/CD
- **Open VSX**: handle 'already published' error in release workflow (#480)
- **Docs-only PRs**: build passthrough so they don't block CI (#607)
- **Flaky tests**: resolve timeouts and hanging in concurrent pipeline tests, shared hardcoded `project_id` caused server-side contention serializing subprocess launches (#561, #877)
- **Discord webhooks**: retry/backoff for webhook calls (#797); prevent duplicate posts on discussion edits (#698)
- **Nightly workflow**: explicit branch check on `workflow_run` trigger (#771); allow `workflow_dispatch` from stage and main (#906)
- **Release tags**: push via `WORKFLOW_PAT` with repo+workflow scope (#774)
- **pytest-xdist race**: all 6 path-traversal test methods shared same `outside.txt` in system temp root; fixed by wrapping `workdir` in per-test tempdir (#872)
- **pnpm-lock.yaml**: restore libc fields (#622); fix lucide-react dependency (#621)
- **CI API key**: use literal `ROCKETRIDE_APIKEY` in Test step instead of secret (#742); match GraphQL github-actions author login (#699)
- **ruff format**: pure whitespace fixes for vision node files that left develop CI red (#902)

#### Tests
- **AI unit-test coverage** grown from 8% to 43% (395 → 945 passing tests). Covers: sql_safety, common/util/validation/table, dap_conn, pipeline_validation, web endpoints, auth middleware, sandbox execution, profiler lifecycle, account/reporter/keystore, all command handlers, data_conn, task_engine state, task_server background loops, transports, task_http, store providers (S3 + Azure), DB base classes, dropper path-traversal guard. Assertions tightened per CodeRabbit review. CodeQL auth-callback URL assertions anchored (#831)
- **Tests realigned** with team-based permissions and metrics rewrite, updated mocks for `teamId`, `organizations`, `resolve_task_permissions`, `tokens.gpu_inference`/`tokens.custom`, renamed `apikey` → `user_id`. Dropped tests for deleted code. Added `test_cmd_public.py` (#870)
- **Node tests**: full improvements and mock cleanup (#687)

### Dependency Updates
- litellm ~1.50 → ~1.83 (#816)
- DOMPurify → 3.4.x (resolves 16 alerts / 8 GHSAs) (#886)
- cryptography pinned to 46.0.7 (#884)
- SQLAlchemy owned at ai layer, pinned ≥2.0,<2.1 (#804)
- Patched via pnpm.overrides:
  - **Routing**: react-router 6.26→6.30.3, @remix-run/router inlined (#914)
  - **Parsers**: ajv@8→≥8.18.0, markdown-it→≥14.1.1, postcss→≥8.5.10, prismjs→≥1.30.0, yaml@1→≥1.10.3 (#915)
  - **Middleware**: koa→≥2.16.4 (3 advisories), qs→≥6.14.2 (#916)
  - **Util/SVG**: svgo@2→≥2.8.1, flatted→≥3.4.2, immutable@5→≥5.1.5, underscore→≥1.13.8 (#917)
  - **Security**: picomatch@2→≥2.3.2, picomatch@4→≥4.0.4, fast-uri→≥3.1.2, serialize-javascript→≥7.0.5 (#890)
  - **Minimatch**: all 4 major lines patched (3→≥3.1.4, 5→≥5.1.8, 9→≥9.0.7, 10→≥10.2.3) (#887)
  - **Core**: undici→≥7.24.0 (6 advisories), lodash→≥4.18.0, lodash-es→≥4.18.0 (#888)
  - handlebars→≥4.7.9, protobufjs→≥7.5.5 (#783)
- Bumped: aiohttp, pygit2 1.15→1.19, soundfile 0.12→0.13, requests, ws 8.19→8.20, postcss 8.5.6→8.5.10, nltk, spacy, spacy-transformers, cymem, murmurhash, preshed, srsly, thinc, psycopg2-binary, pymysql, opensearch-py, npm-production group (adm-zip, tar, lucide-react, dockerode, web-vitals), shared-ui devDependencies (rollup, @types/react, @types/react-dom), cosign-installer, ossf/scorecard-action, gh-actions group (pnpm/action-setup, github/codeql-action, softprops/action-gh-release, dorny/paths-filter)

---

## RocketRide MCP Client v1.3.0

**MCP Client** · v1.3.0 · July 7, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.3.0)

### ⚠ Breaking Changes: Client SDKs (`rocketride` / `rocketride-python`)

These changes affect code that imports and calls the Python or TypeScript client SDKs directly. The old `connect()` / `disconnect()` signatures are preserved as backward-compatible wrappers, but callers should migrate to the new layered API.

#### Connection API (both SDKs)

| Before (1.0.x) | After (1.1.0) | Notes |
|---|---|---|
| `connect(auth?, uri?, timeout?)` → `void` | `connect(credential?, { uri?, timeout? })` → `ConnectResult` | Now returns full user identity (userId, organizations, apps, teams). The `auth` param is renamed `credential` to reflect that it accepts API keys, Zitadel access tokens, and `rr_*` user tokens. Old positional `auth`/`uri` kwargs still accepted but deprecated. |
| `disconnect()` → `void` | `disconnect()` → `void` | Signature unchanged; internally calls `logout()` + `detach()`. |
| *(not available)* | `attach(uri?)` → `void` | Opens the WebSocket **without** authenticating. Required for public/unauthenticated operations like catalog browsing. |
| *(not available)* | `login(credential?)` → `ConnectResult` | Sends the DAP `auth` command over an attached transport. Supports credential rotation (auto-logout if credential differs). |
| *(not available)* | `logout()` → `void` | Sends new `deauth` DAP command, reverts the connection to unauthenticated without closing the socket. |
| *(not available)* | `detach()` → `void` | Tears down the WebSocket and cancels the reconnect engine. |
| `isConnected()` | `isConnected()` *(unchanged)* | Returns `true` only when both attached **and** authenticated. |
| *(not available)* | `isAttached()` | `true` when the WebSocket is open, regardless of auth state. |
| *(not available)* | `isAuthenticated()` | `true` when the auth handshake has succeeded on the current connection. |

**Reconnection engine rewritten**: the old flag soup (`_manualDisconnect`, `_authRejected`, `_didNotifyConnected`) is replaced by a `_desiredState` model (`'detached'` | `'attached'` | `'authenticated'`). Linear backoff (250ms increments, 15s cap) replaces exponential backoff, reconnection now **never gives up**. `maxRetryTime` is accepted for backward compatibility but **ignored**.

#### Python-specific breaking changes

- **`async with` context manager removed**: `__aenter__` / `__aexit__` are deleted. Replace `async with RocketRideClient(...) as client:` with explicit `await client.connect()` / `await client.disconnect()` in a try/finally.
- **`connect()` now returns `ConnectResult`**: previously returned `None`. Callers that did `await client.connect()` without capturing the result are unaffected; callers that typed the return as `None` will need to update.
- **`use()` no longer substitutes `${ROCKETRIDE_*}` client-side**: the raw pipeline is sent to the server, which handles all variable resolution via `get_merged_env()`. If you were relying on client-side `.env` interpolation, variables must now be set server-side (via the Variables page or `client.account.set_env()`).
- **Event type renames**: `EVENT_STATUS_UPDATE` → `EVENT_STATUS`; `EVENT_TASK` → split into `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART`. Code that imports the old names will get `ImportError`.
- **`auth` credential removed from transport layer**: `TransportWebSocket` no longer stores or exposes `auth`. Auth is exclusively managed by the `ConnectionMixin` / `RocketRideClient` layer.

#### TypeScript-specific breaking changes

- **`connect()` signature changed**: old: `connect(options?: number | { uri?, auth?, timeout? })` → `void`. New: `connect(credential?, options?: { uri?, timeout? })` → `Promise<ConnectResult>`. The `auth` property inside options is removed; pass the credential as the first argument. The numeric-only shorthand `connect(5000)` is removed.
- **`DataPipe` errors changed from `Error` to `PipeException`**: `open()`, `write()`, and `close()` now throw `PipeException` (extends `Error`) instead of plain `Error` when the server reports a failure. Callers catching `Error` are still compatible; callers matching on error message strings may need to update. `PipeException` carries the full DAP response body.
- **`setConnectionParams()` removed**: use `login(credential, { uri })` or call `attach(newUri)` + `login()` instead.
- **Project store methods removed**: `saveProject()`, `getProject()`, `deleteProject()`, `getAllProjects()` are deleted. Use the new filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`.
- **`validate()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ValidationResult` (typed interface with `valid`, `errors`, `warnings` fields).
- **`getServices()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ServicesResponse` (typed interface).

#### Both SDKs: new exception types

- **`PipeException`** (Python: subclass of `RuntimeError`; TypeScript: subclass of `Error`): thrown by `DataPipe.open()`, `.write()`, `.close()` when the server reports failure. Carries the full DAP response including `message`, `body`, and error code. Replaces generic `RuntimeError` / `Error`.
- **`ConnectionException`** (TypeScript): thrown on transport-level failures.

### Added

#### New Nodes
- **Exa Search**: semantic web search node integrating with the Exa API (exa.ai) for real-time data enrichment in pipelines. Agents invoke the tool to search the web and retrieve structured results including titles, URLs, text content, relevance scores, and published dates. Includes configurable `numResults` with min/max validation, retry exception sanitization to prevent API key leakage, and defensive boolean config parsing (#386, #509)
- **Bland AI**: voice call tool node for AI-driven phone calls via the Bland AI platform (#521)
- **OpenAI Compatible**: generic LLM node supporting any OpenAI-compatible API endpoint, allowing connection to self-hosted or third-party inference servers that follow the OpenAI chat completions API (#518)
- **GMI Cloud**: LLM connector for GMI Cloud inference platform (api.gmi-serving.com) hosting 100+ models on H100/H200 GPUs. Two tiers: shared (always-on, key-only: DeepSeek, GPT, Claude, Gemini) and deploy-on-demand (endpoint URL + key: Llama 4, Qwen3). Custom profile for arbitrary model/endpoint combinations (#540)
- **Guardrails**: AI safety node with comprehensive input/output validation. Input: prompt injection detection (regex + keyword scoring), topic restriction (allowed/blocked keyword lists), input length enforcement (char + token limits). Output: hallucination detection (sentence-level grounding), content safety (self-harm, violence, illegal activity patterns), PII leak detection (email, phone, SSN, credit card, IP), format compliance (JSON, markdown, bullet/numbered lists). Policy modes: block/warn/log. Profiles: basic (injection + PII), strict (all checks), custom. 87 tests (#534)
- **Video Embedding**: extracts frames from video input (MP4, AVI, MOV, WebM) at configurable intervals and generates vector embeddings using CLIP/ViT models for semantic search and RAG pipelines. Configurable frame interval, max frames, start time, duration, and max video file size (default 500 MB) to prevent unbounded memory. VideoCapture resource leak fixed with finally block (#516)
- **Kokoro TTS**: self-contained text-to-speech node using the Kokoro engine. Slim requirements (no piper/transformers/cloud). KokoroLoader, spacy_en_model, wav_to_mp3 utilities. Supports question, answer, and document lanes (RR-411, #662)
- **Telegram Bot**: source node connecting a Telegram bot to a pipeline via long polling or webhook. Routes incoming messages to appropriate lanes by content type (text, image, audio, video, documents) and sends pipeline responses back as replies (#659)
- **GitHub Tool**: tool node for GitHub API operations (issues, PRs, repositories) with full test suite for tool calling (#640)
- **Git Tool**: self-contained Git operations using pygit2 (libgit2), no host git binary required. Capabilities: clone, init, status, log, show, diff, blame, file_at, ls_files, grep, stage, commit, stash, branch create/checkout/merge/delete, fetch, pull, push (token + SSH auth), write_file with path-traversal guard. Safe mode (default on) blocks force-push and force branch deletion. Full unit test suite + integration tests (activated via `GIT_TEST_REPO_PATH` env). Includes `git_agent_example.pipe` (#654, #731)
- **Filesystem Tool**: file system operations (read, write, list, mkdir, delete) with path whitelist security check via `_prepare()` method. Operations can be selectively enabled/disabled at the node level. Shared prologue extraction via keyword flags (path_required, needs_encoding, needs_content) (#682)
- **Pipeline Tool**: run pipelines as tool calls from other pipelines, enabling pipeline composition and hierarchical agent workflows (#647)
- **LLM Vision (Gemini)**: image understanding via Gemini models with cache management (non-symmetric cache + empty frame guard)
- **LLM Vision (OpenAI)**: image understanding via OpenAI vision models
- **Webhook**: question lane support for webhook-triggered pipelines (#431)
- **CrewAI Orchestrator**: multi-agent orchestration via CrewAI framework. Exposes expert config fields (goal, backstory, expected_output, max_iter) for both agent and orchestrator node types. Advanced mode for fine-grained control. Sub-agent config propagated through `crewai.describe()`. Manager node renamed from Orchestrator, tool invoke removed from manager (#608)

#### VS Code Extension
- **Engine management overhaul**: replaced scattered engine lifecycle code (connection/, deploy/) with a clean `EngineBackend` hierarchy under `src/engine/`. Each connection mode (local, service, docker, cloud, onprem) gets its own backend implementation. `EngineRegistry` singleton reconciler detects config changes (API key, host URL, etc.) via checksums and auto-restarts affected engines on settings save. Eliminated `engine:status` event, all progress flows through `shell:statusChange`. `ConnectionManager` becomes passive: connects on engine `ready`, disconnects on `idle`. Unified `ioControl` message pattern for all panel operations. Migration from legacy layout (`globalStorage` + `config.json`) to new structure. Welcome page uses same `applyAllSettings` + reconcile path as Settings (#922)
- **Settings overhaul & target panels**: atomic settings save via `ConfigManager.applyAllSettings()` with `isBatchApplying` flag suppressing intermediate change events (eliminates race conditions from writing 20+ config keys individually, which caused connection managers to react to half-written state). Self-contained panels per mode (Local, Cloud, OnPrem, Docker, Service) handling both configuration and operational UI (status, install/start/stop/remove/update, progress, version selection). `EngineOperations` service extracted from `PageDeployProvider`. Deploy page command redirected to Settings. `useTheme` hook for VS Code dark/light detection. Embedded Docker/Service SVG logos. Build config consolidated: `.config` as single source of truth for Zitadel URLs/client IDs, esbuild loads `.config` first then `.env` on top, stopped name remapping of Zitadel keys. Cloud mode no longer hardcodes a non-existent URL, uses `config.hostUrl` at runtime (#725)
- **Standalone Variables page**: new "Variables" webview accessible from sidebar footer for managing `ROCKETRIDE_*` environment variables per connection slot (Development/Deployment). `EnvironmentProvider` with per-slot client resolution, `EnvironmentWebview` with pill bar for slot selection. OSS servers show single "Server Variables" card; SaaS servers show Organization/Team/User cards gated by permissions. `set_env` now updates `os.environ` in-memory before writing `.env` file. Deploy connection fix: removed `isSharedMode()` guard that skipped engine status listener registration. `commonStyles.tabContent` now uses `border-box` sizing. Removed capabilities filter that hid Cloud option. All "Environment" labels renamed to "Variables"
- **`${ROCKETRIDE_*}` variable autocomplete**: node config fields now offer autocomplete suggestions for defined pipeline variables. `useEnvVarAutocomplete` hook detects `${` trigger and filters keys by partial match. `EnvVarSuggestions` popover with arrow-key navigation. Wired into `BaseInputTemplate`, `TextareaWidget`, and `ApiKeyWidget`. `transformErrors` suppresses RJSF validation errors for fields containing `${ROCKETRIDE_*}`. `rrext_validate` now resolves env vars before validation using the same merged env as pipeline execution. Fixed `getHttpUrl()` to normalize engineUri before parsing
- **Category headers in QuickAddPopup**: compatible services grouped by bold uppercase category headers with indented items. Shared `CATEGORY_TITLES` extracted to `categoryTitles.ts`. `CreateNodePanel` auto-expands matching categories during search, restores previous expand/collapse state when search is cleared. Environment protocol types extracted to prevent build errors
- **Server Monitor panel**: real-time dashboard showing connections, tasks, and aggregate metrics via new `getDashboard()` / `get_dashboard()` SDK methods (DAP `rrext_dashboard` command). Client identification (`clientName`/`clientVersion`) forwarded during auth handshake so server can distinguish "VS Code 0.9.4" vs "CLI 1.2.0". Python DAP client skips auth message when transport lacks `get_auth()` (fixes crash for non-WebSocket transports). Consolidated `ServicePython` log level into `DebugOut` (#595)
- **Other task viewer via ProjectWebview**: `PageStatusProvider` completely rewritten. Previously opened a lightweight `StatusWebview` that couldn't show the node graph (nodes squashed at top, no toolbar, missing servicesJson). Now fetches unresolved pipeline via `getTaskToken` + `getTaskPipeline`, creates panel using the full Canvas/ProjectView stack, sends `project:load` with `isReadonly:true`. Falls back to synthesized single-node project if fetch fails. `StatusWebview` deleted (#803)
- **Readonly canvas**: single `isReadonly` prop replaces two inconsistent lock mechanisms (14-boolean `IFlowFeatures` and partially-implemented `isLocked`). `effectiveLock = isReadonly || internalIsLocked`. Guards added to `addNode()`, `updateNode()`, `deleteNode()`, paste, context-menu, lane click, config panel Save, all previously unguarded. Lock button hidden when `isReadonly` (#803)
- **Save button in canvas toolbar**: always-visible floppy disk icon with dirty-state tracking; grayed when clean, brand-colored when dirty. `isDirty`/`isNew`/`onSave` threaded through `IFlowProps` → `FlowContainer` → `FlowProvider` → `FlowProjectProvider`. `FlowCanvas` defers ReactFlow render until container has non-zero dimensions via `ResizeObserver`. `canvas:requestSave` calls `document.save()` directly (#678)
- **Dirty-state save pattern for settings**: card header starts clean (no buttons); on edit, Cancel and Save appear; on save, buttons disappear and "Saved" flashes for 5 seconds then fades; Cancel reverts to last-saved snapshot. Applied to all 5 VS Code settings tabs and shell-ui settings page (#877)
- **Play button shows actionable text**: renamed idle label from "Play" to "Run Pipeline". Added STOPPING state with "Stopping..." disabled button to prevent double-clicks. Widened hover expansion for longer label. Smooth CSS transitions with easing functions (#575)
- **Improved stop button feedback**: Pipeline Observability screen handles `TASK_STATE.STOPPING` with "Stopping..." disabled state and distinct orange styling, preventing duplicate clicks (#549)
- **Simplified sidebar footer**: replaced popup menu (three redundant gear icons all opening Settings) with flat layout when connection is shared and no cloud account. Documentation and Settings buttons rendered directly, connection status inline, announcements ticker rotates cards every 7 seconds. Full popup preserved for cloud account or independent connections. Panel sash restyled with native `--vscode-sash-hoverBorder` token, widened from 2px to 4px
- **Test Connection button**: available on service/docker/onprem panels via `ioControl('test')`
- **Docker GHCR tag fetching**: global cache for prerelease resolution with 15s timeout on HTTPS requests. Split-button dropdowns with grouped "Recommended" / "All versions" headers. Version metadata persisted per instance lifecycle. Linux package manager auto-detection (apt/dnf/yum/pacman) instead of hardcoded apt-get
- **Version tracking**: persistent `version.local.json`, `version.service.json`, `version.docker.json` files. PID liveness check before preserving `.pid` files during engine dir clear. Guard against phantom installs (missing binary). UAC-cancel fallback and uninstall.ps1 fixes
- **Event naming unification**: all connection events renamed to `shell:*` namespace matching cloud-ui vocabulary. `'event'` → `'shell:event'`, `'connected'` → `'shell:connected'`, `'connectionStateChanged'` → `'shell:statusChange'`, etc. All 10 providers renamed to drop redundant `Page` prefix. All 9 view directories renamed similarly (#803)
- **`.env` file management removed**: ~350 lines of env file handling removed from `ConfigManager` (envFileWatcher, envRawText, parseEnvFile, saveEnvFile, syncSettingsToEnv, etc.). Environment variables for pipeline variable replacement are now managed server-side (layered env in DB). Extension no longer maintains workspace `.env` file. URL resolution consolidated into `ConnectionManager` (per-group, not hardcoded to dev group) (#803)
- **On-demand env loading**: replaced 7 env-specific `AccountView` props with 2 generic callbacks (`onLoadEnv`, `onSaveEnv`) plus `refreshSignal`. Each `EnvScopeCard` requests its own data on mount. Promise-based messaging with 10s timeout. `shell:accountUpdate` as first-class event (no longer filtered from generic stream). Standalone `BillingProvider` deleted; billing is a tab inside Account (#803)
- **Welcome page simplification**: `welcomeDismissed` set automatically on save (no manual checkbox). Works from both Welcome and Settings pages (#803)

#### Shell UI (Web Host)
- **Shell-ui replaces cloud-ui**: new Module Federation host application served by Python `shell` module (`ai.modules.shell`) with public HTTP routes for SPA and all static assets under `/shell/`. Unifies OSS and SaaS into single codebase. Server-side app manifest delivery via `get_public_apps()` / `get_apps_for_user()` on AccountBase. Pre-auth info probe returns public apps for marketplace. Connect response includes authenticated user's full entitled app list (#803)
- **MUI removal**: replaced Material UI with plain CSS/HTML across entire shared-ui package; runtime theme system with light/dark JSON tokens
- **Theme rebrand**: replaced legacy purple (#5900FF) with cyan (#00b9ec) TOKENS palette. Light theme updated to warm-neutral (cream/stone backgrounds instead of pure white) (#803)
- **Theme flash fix**: `index.html` inline script sets `--rr-bg-default` and body background synchronously before React renders. `createShellConfig` reads saved theme from localStorage instead of always defaulting to rocketride-light, eliminating tan background during 1.5s OAuth code-exchange window (#878)
- **Chat module**: host-agnostic chat surface following established module pattern (props-in, callbacks-out, `--rr-*` CSS tokens). `ChatView` (MessageList + ChatInputField), `MessageBubble` (user/bot/system/status with markdown), `MarkdownRenderer` (react-markdown + GFM + syntax highlighting + charts), `ChartRenderer` (chart.js with circular-reference guard), `TypingIndicator` (animated bouncing dots), `useChatMessages` hook (message state + sendMessage + monotonic IDs) (#724)
- **Canvas state persistence**: viewport (zoom/pan), lock state, snap-to-grid, and editor mode now persist in `.pipe` files via `PipelineConfig` schema (TypeScript + Python SDKs). New `isFlowReady` boolean state tracks when all nodes have been rendered/measured by ReactFlow, replacing scattered `setTimeout`/`requestAnimationFrame` workarounds. Centralized `loadCanvas(nodes, edges)` as single entry point for structural canvas changes. Viewport restored on load via `isFlowReady` cycle, falls back to fitView. Spiral search for non-overlapping node placement. `EmptyCanvasPrompt` only shown when `nodes.length === 0 AND isFlowReady` (#670)
- **ProjectView architecture**: decomposed monolithic `modules/flow/` canvas module into composable multi-view project architecture (#670)
- **Style consolidation**: added `buttonPrimarySmall`, `buttonSecondarySmall`, `buttonDangerSmall`, `modalDialog`, `modalHeader`, `modalBody`, `modalFooter` to `commonStyles`. Added `cardHeaderButton`/`cardBodyButton` size modifiers for card contexts. Eliminated `Btn` wrapper component. Account `shared.tsx` trimmed from ~30 to 9 entries. All emojis removed from account UI (#803)
- **Shared connection types**: `ConnectionState` enum, `ConnectionMode`, `IAuthProvider`, `IConnectionManager` interface, `ShellAppEntry`, `ShellConnectionEventMap` with typed payloads for all `shell:*` events. Index signature for app-defined events (#803)

#### Billing, Account & Auth
- **Billing detail**: `BillingDetail` type gains `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart` in both SDKs. Subscription cards show detail grid with plan info. Cancel subscription requires confirmation modal. App display name shown instead of raw appId. Credit grant summary per subscription using `creditLabels` from Stripe metadata (#803)
- **Account/Billing merge**: Billing is now a tab inside Account (2nd pill) via `BillingPanel`. Standalone Billing page and provider deleted
- **Permission enforcement**: frontend computes `isOrgAdmin`/`isTeamAdmin` from profile; action buttons hidden for users without required permissions; `OrganizationPanel` read-only for non-admins; destructive actions go through confirmation modals. Team admin enforcement: must always have ≥1 admin (UI + server guard). Permission key fixed: `'admin'` → `'team.admin'`. `_require_team_admin` queries DB directly instead of stale cache (#803)
- **Team-based task permissions**: replaced all `control.userId == caller.userId` ownership checks with `resolve_task_permissions()` so teammates and org admins can monitor/control each other's tasks. Permission strings (e.g. `'task.control'`, `'task.monitor'`) checked against resolved list (#803)
- **Layered environment secrets**: pipeline variables (`ROCKETRIDE_*`) stored encrypted (Fernet) in database per org/team/user scope, merged server-side during task execution. Merge order: `.env` → org → team → user → caller env. `get_merged_env()` on `AccountBase` with OSS (`.env` only) and SaaS (DB) implementations. `client.use()` `env` param for caller overrides (only `ROCKETRIDE_*` accepted). Client-side `processEnvSubstitution` removed, resolution is server-only (#803)
- **Session keys**: API keys are now true PATs inheriting user identity. `is_session` flag on `ApiKey` model. `ensure_session_key()` on every OAuth login: refreshes 90-day expiry if active, creates fresh key if expired/missing. Session keys cannot be self-revoked. Admin revoke is hard-delete. Housekeeping: keys revoked >30d purged on login. UI shows "Session" / "Interactive login" badge (#803)
- **Scoped PATs**: PATs optionally restricted to single team with explicit permissions. Effective permissions intersected with user's actual permissions at auth time (can never escalate). Optional `team_id` on `ApiKey`. Create key modal: team dropdown + conditional `PermGrid`. Key list shows team scope badge (#803)
- **userToken → userId refactor**: server-side event tenant scoping uses `userId` instead of `userToken`. Fixes bug where two connections from same user with different keys wouldn't see each other's dashboard events (#803)
- **Account UI overhaul**: all card headers use `commonStyles.labelUppercase`. Save button pattern: hidden until dirty, shows [Cancel][Save], "Saved" green text with 5s timer. `ProfilePanel`: single "Organizations / Workspaces" card with nested teams. `TeamsPanel`: Delete moved to list with confirm modal. `PermGrid`: `PERM_DISPLAY` labels, alphabetized, added `task.store`, contrasting text on checked tiles (#803)
- **Client SDK attach/login split**: replace monolithic `connect()`/`disconnect()` with layered API: `attach(uri?)` opens WebSocket without auth (for public APIs like catalog), `login(credential?)` sends DAP auth, `logout()` sends new `deauth` command (reverts to unauthenticated without closing socket), `detach()` tears down WebSocket. Old `connect()`/`disconnect()` preserved as backward-compatible wrappers. Reconnection engine rewritten around `_desiredState` model ('detached' | 'attached' | 'authenticated'). Linear backoff (250ms increments, 15s cap), reconnection never gives up. Auth credential removed from transport layer (#803)
- **Server-driven appStatus**: replaced `subscriptionStatus` with server-computed `appStatus` ('auth' | 'free' | 'unsubscribed' | 'subscribed' | 'trialing' | 'past_due' | 'canceled') and `onDesktop` boolean per app manifest entry. Eliminates client-side reconciliation races (#803)
- **App mode & subscription gating**: `mode` field (free/subscription/paywall) in app manifests. Shell-level subscription gate blocks app iframe until active subscription exists. Desktop app management moved into account identity flow (#803)
- **Token storage hardened**: moved from `localStorage` to `sessionStorage` (cleared when tab closes) addressing CodeQL "Clear text storage of sensitive information" alert (#803)

#### Profiler
- **DAP-based cProfile system**: replaced HTTP-endpoint profiler module with per-process cProfile profiling over DAP connections. Any connected client can profile any process (task server, data engine subprocesses, model server). `CProfileManager` singleton with start/stop/status/report/release API. Owner tracking per connection with disconnect cleanup. SDK methods: `cprofileStart`/`cprofileStop`/`cprofileStatus`/`cprofileReport` (TS + Python) with optional `target` parameter for pipeline profiling. New `profiler-ui` Module Federation remote app with `ProfilerView`, `ConnectionManagerView`, and `ProfilerSidebar` (#803)

#### Module Federation
- **MF stability**: added `runtime: false` to all remote apps (shell-ui provides shared runtime; without it each remote embeds its own runtime copy, causing remoteEntry.js to change on every rebuild and version-mismatch errors during HMR). Added `eager: true` to react/react-dom shared configs (breaks async shared-scope negotiation deadlock where host waits for remote's async chunk and remote waits for host). App loader filters out server-only entries with no `remoteEntry` URL (prevents `normalizeRemote()` crash on `undefined`) (#877)

#### Engine & Core
- **Database EXECUTE**: direct SQL/Cypher execution via `QuestionType.EXECUTE` with `client.database.query()` namespace on both SDKs, bypassing LLM translation and safety gating. Gated behind opt-in `allow_execute` config (default off). Results bounded with `fetchmany(max_execute_rows+1)` (default 25000). Neo4j results capped at same limit. `allow_execute` parses strings strictly: only `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive). EXECUTE output wrapped in try/except; serialized with `default=str`. SDK validates non-empty token/sql before dispatching
- **Database DIALECT**: `QuestionType.DIALECT` for engine capability discovery. SDK callers can ask which engine a database pipeline is connected to (`DatabaseDialect` enum). `_db_dialect()` abstract method on `DatabaseInstanceBase`. `services.json` now exposes UI-toggleable `allow_execute` boolean
- **Handle-based streaming I/O**: generic filesystem-style interface (`open`/`read`/`write`/`close`/`delete`/`stat`/`mkdir`/`list_dir`) on `FileStore`, replacing monolithic in-memory buffering. Domain methods become thin convenience wrappers on client SDKs. Supports S3 multipart upload (5 MB buffer), Azure staged blocks (4 MB buffer), and local filesystem. Handles tagged with owning `connection_id` and force-closed on connection termination (#600)
- **`@tool_function` decorators**: collapsed the two-class pattern (IInstance + ToolsBase driver) into a single class. Any `IInstanceBase` subclass can declare tool entry points with a decorator; the method name becomes the tool ID, decorator carries schema/description, base class `invoke()` dispatches automatically. Eliminates parallel driver classes, factory methods, and boilerplate delegation (#599)
- **Experimental + Deprecated capability flags**: `DEPRECATED = BIT(15)`, `EXPERIMENTAL = BIT(16)` in `PROTOCOL_CAPS`. Both flags wired through C++ parser, pybind11 bindings, both client SDKs, and shared-ui. Yellow "EXPERIMENTAL" badge rendered on canvas nodes, Add Node slider, and Quick Add popup (#606)
- **Docker-compose and healthcheck**: `HEALTHCHECK` instruction in `Dockerfile.engine` using curl to `/ping`. `docker-compose.yml` with engine, PostgreSQL+pgvector, Milvus (+ etcd, MinIO), ChromaDB. Override file for dev hot-reloading. All images pinned to specific versions. Security warnings in `.env.example` (#496)
- **Billing commands mixin**: `BillingCommands` in TaskConn's MRO for `rrext_account_billing`. OSS implementation routes on `arguments.subcommand` with stubs so UI doesn't hang in half-rendered state (#692)
- **Task engine extraction**: `task_engine` and `cmd_data` extracted as standalone modules (#661)
- **GPU inference billing**: `metrics.resource('gpu')` context manager times inference. `CONST_RATE_GPU_INFERENCE_SECOND` for billing. Custom node counters (`pagesProcessed`, etc.) with configurable rates. All 9 AI model files wrapped with `metrics.counter('gpu_inference_count')` + `metrics.resource('gpu')`. Billing reports include `gpu_inference` and `custom` token fields (#803)
- **Metrics rewrite**: replaced Timer class and `resource()` context manager with flat `MetricsManager`: `timer()`, `add_time()`, `counter()`, `event()`. Thread-safe via single lock. Removed per-pipe `ContextVar`, metrics are per-subprocess. ModelClient auto-records server-reported perf dict (#803)
- **ModelClient refactor**: derived from `RocketRideClient` with `ws_path='/models'` so URI normalization, protocol selection, and auth are handled by SDK. Python SDK gains `ws_path` kwarg. Sync `disconnect()` override for worker thread callers. All 9 model wrappers updated. `get_model_server_address()` simplified to return raw string (#877)
- **Model server DAP namespace**: all model server commands renamed to `rrext_ms_*` prefix (load_model → rrext_ms_load_model, etc.) for disambiguation from core DAP commands (#803)
- **GPU guard**: `install_gpu_guard()` blocks direct torch/tensorflow imports in model server mode; all GPU inference must go through ModelClient RPC (#803)
- **Pipeline error surfacing**: `binder.cpp` sets `completionCode` on Entry when `callMethods` encounters error. `bindings.cpp` exposes `completionError` read-only property. `data_conn.py` rewrites `close_sync()` to always extract results even when end/close throws, surfaces `Entry.completionError` when `objectFailed` is True. Errors now reach dropper UI (#803)
- **`rrext_get_pipeline` DAP command**: returns task's unresolved pipeline (with `${...}` placeholders intact) so VS Code can reconstruct node graph without exposing secrets. `_build_task()` now accepts explicit resolved pipeline, `self._pipeline` retains original unresolved form (#803)

#### Client SDKs: New Features

**Layered connection API (both SDKs):**
- `attach()` / `detach()`: open/close the WebSocket without authentication. Enables unauthenticated operations (public catalog browsing, server probes) before the user logs in
- `login()` / `logout()`: authenticate/deauthenticate over an attached transport. `login()` returns `ConnectResult` with full user identity (userId, organizations, apps, teams, permissions). `logout()` sends new `deauth` DAP command, reverting to unauthenticated without closing the socket. Supports credential rotation (auto-logout if a different credential is supplied)
- `connect()` / `disconnect()` preserved as backward-compatible wrappers (`attach` + `login` / `logout` + `detach`), but `connect()` now returns `ConnectResult` instead of void
- `isAttached()`: true when WebSocket is open (regardless of auth)
- `isAuthenticated()`: true when auth handshake has succeeded

**Namespaced API accessors (both SDKs):**
- `client.account`: profile, API keys, org, members, teams, environment variables (`get_env()` / `set_env()` / `get_environment_keys()`)
- `client.billing`: subscriptions, checkout, credits, cancel
- `client.database`: `client.database.query()` for direct SQL/Cypher execution; `client.database.dialect()` for engine discovery (`DatabaseDialect` enum)

**New methods:**
- `RocketRideClient.getServerInfo(uri)` (static): probe a server for capabilities without authenticating. Returns `ServerInfoResult` with version, capabilities, platform, and public apps
- `getTaskToken(projectId, source)`: resolve a running task's session token
- `getTaskPipeline(token)`: retrieve the unresolved pipeline for a running task (placeholders intact, no secrets)
- `getDashboard()`: real-time server dashboard (connections, tasks, metrics)
- `cprofileStart/Stop/Status/Report`: per-process cProfile profiling over DAP
- `call(command, token?, **kwargs)` (Python): single public entry point for all typed DAP operations with optional `on_trace` callback

**TypeScript-specific additions:**
- `wsPath` config option for custom WebSocket paths (e.g. `'/models'` for model server)
- `onTrace` callback for observing all `call()` traffic
- `MonitorKey` type and `addMonitor()` / `removeMonitor()` for reference-counted monitor subscriptions
- `restart()` method for restarting pipeline tasks
- Filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`: replaces the old project store methods
- `getTaskStatus()` applies default 15s timeout (configurable via `options.timeout` or `{ timeout: false }`)
- `validate()` now returns typed `ValidationResult` (was `Record<string, unknown>`)
- `getServices()` now returns typed `ServicesResponse`; `getService()` returns `ServiceDefinition`
- `DataPipe.open()` sets `_opened` only after successful SSE setup with rollback on failure
- `normalizeUri()` preserves user-specified port (was being stripped for scheme-default ports like :443)

**Python-specific additions:**
- `ws_path` kwarg for custom WebSocket paths
- `client_name` / `client_version` kwargs forwarded in auth handshake for client identification
- `on_trace` callback for observing all `call()` traffic
- `public` mode for permanently unauthenticated connections (only `rrext_public_*` commands)
- `DashboardMixin`, `CProfileMixin`, `StoreMixin` added to MRO
- Improved `send()` pipe error context with `PipeException` (catchable as `RuntimeError`)

**New types (both SDKs):**
- `ConnectResult`, `ServerInfoResult`, `AppManifestEntry`, `StripePriceEntry`
- `AccountProfile`, `AccountOrganization`, `AccountOrgTeam`, `ApiKeyRecord`, `OrgDetail`, `MemberRecord`, `TeamRecord`, `TeamDetail`, `TeamMemberRecord`
- `BillingDetail` (extended with `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart`, `credits`, `creditLabels`), `StripePlan`, `CreditBalance` (extended with `labels`), `CreditPack`
- `PROTOCOL_CAPS` enum with all 17 capability flags
- `SERVICE_DEFINITION`, `SERVICES_RESPONSE`, `VALIDATION_ERROR`, `VALIDATION_RESULT`
- `DASHBOARD_OVERVIEW`, `DASHBOARD_MONITOR`, `DASHBOARD_CONNECTION`, `DASHBOARD_TASK`, `DASHBOARD_RESPONSE`, `DASHBOARD_EVENT` and 7 event subtypes
- `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART` (replace old `EVENT_TASK`)
- `EVENT_STATUS` (replaces `EVENT_STATUS_UPDATE`)
- `TASK_TOKENS` extended with `gpu_inference` and `custom` fields
- `CreateKeyParams` accepts optional `teamId` for scoped PATs
- `EVENT_TYPE.DASHBOARD` flag (bit 7) for server-level events; `EVENT_TYPE.ALL` updated to include it
- **Config**: `Config.getNodeConfig()` emits warnings for deprecated profiles with migration guidance from profile's `migration` field

#### MCP
- **MCP Resources and Prompts**: `rocketride://` URI resources (pipeline list, server status, node registry) with graceful error handling for disconnected clients. Three prompt templates (analyze-document, chat-with-data, evaluate-pipeline) with required argument validation and message rendering. 44 tests (#541)

#### Agents & Pipelines
- **Agent framework overhaul**: ProjectView architecture with shared-ui migration (#670)
- **Example pipeline templates** for common AI workflows (#572)

#### Build System
- **Rsbuild upgrade**: all UI apps upgraded from pinned 0.4/1.1 to ~1.7.5, eliminating Node.js `DEP0180` deprecation warnings in Node 22+. ESM config migration (`.ts` → `.mts`). cmake minimum bumped from 3.14 to 3.19. `@rspack/binding-*` platform pins removed. Service config renamed `config.json` → `service-config.json` with migration (#905)
- **Build-input caching**: source fingerprinting (`buildInputHash()` + `hasBuildInputChanged()`) skips UI modules whose inputs haven't changed. `appModule.js` factory eliminates ~80 lines of boilerplate per app. Shell-ui tracks own src/ + shared-ui/src + package.json. `--force` flag bypasses caching. Clean actions clear cached hashes (#877)
- **Builder CLI**: `server:run` action (build + run without shell-ui dev server). `--taskserver=ADDR` replaces `--testport`. `--modelserver` semantics clarified (bare flag = start local, `=ADDR` = use existing). `--simulate-gpus=N` forwarded to model server. `parseServerAddress()` utility (#803, #877)

#### CI/CD
- **Cosign container signing**: keyless signing of rocketride-engine image via Sigstore + GitHub OIDC (signs by digest). GPG detached-signature step for server tarballs/zips, gated on `GPG_SIGNING_KEY` secret (#798)
- **Dependabot**: weekly version updates with smoke tests for litellm and pipeline-node deps. Blocked rsbuild/rslib/rspack 0.x churn and pip major bumps. Semver-major ignores across all 10+ ecosystems (#788, #843, #842, #862)
- **Experimental-release workflow**: `workflow_dispatch`-only, builds from arbitrary branch under configurable tag suffix. Per-product release jobs. No marketplace publishing. `prerelease: true`. First use case: workshop builds (#848)
- **Nightly prereleases**: initially from stage branch (#631), moved to develop on green CI (#713). `workflow_dispatch` expanded to develop/stage/main (#906)
- **Daily Actions storage cleanup** workflow (#636)
- **Discord notifications**: PRs, issues, discussions with live CI check status and PR state tracking in embed (#612, #614, #638). Duplicate posts on discussion edits prevented (#698). Retry/backoff for webhook calls (#797)
- **Ruff and gitleaks**: pre-commit checks (#722); gitleaks made blocking (#681); `ruff format` applied to all Python files (#723)
- **Sequential builder tests** to isolate cross-suite flakes (#734)
- **cmake 4** support (#807)
- **Actions pinned** to immutable commit hashes (#483)
- **Artifact retention** dropped to 1 day for 0.5 GB storage cap (#779)
- **CodeQL** switched from advanced to default setup (#768)

#### Documentation
- **Observability & tracing**: integration guide documenting how external services consume runtime logs, lifecycle events, and pipeline traces over the WebSocket DAP channel. Wired into all agent stubs (Claude Code, Cursor, Windsurf, Copilot) (#716)
- **Node usage guides**: `db_neo4j` with practical examples (#490), `llm_openai` with provider examples (#493), source connectors (#650)
- **Per-node documentation** overhaul, added and updated docs for each node (#639, #660)
- **Engine**: Tika ExternalParser media tool requirements (#729)
- **Python client**: clarified `send()` sources and `.pipe` usage (#705); updated Python 3.8 → 3.10 references (#657); added `.env.example` (#492)
- **Contributing**: require green CI checks before review (#627)
- **SOC2-ready SECURITY.md**: explicit triage/remediation SLA (critical 7d, high 30d, medium 90d), scanning toolchain documentation (CodeQL, Scorecard, Trivy, Dependabot, secret scanning), quarterly access reviews (#762)
- **Two-person control** on alert dismissals documented (#800)
- **Code of Conduct** (#591)
- **README improvements**: onboarding wording, absolute image URLs, GIFs, Product Hunt badge (#706, #506, #478, #590)

#### Security Policies
- **Workflow permissions**: top-level permissions added to 5 reusable workflows (#790); storage-cleanup narrowed to job-level (#794)
- **Stale lockfile removed**: `packages/client-typescript/pnpm-lock.yaml` deleted, override declared in root (#796)

### Changed

- **LLM provider migration**: all LLM providers migrated to `ai.common.LLMBase` (#719); automated LLM model sync tool fetches models from provider APIs, smoke-tests new ones, merges into `services.json` with smart deprecation and three-source token limit resolution (provider API → OpenRouter → LiteLLM). `modelSource` field tracks discovery origin. Weekly CI workflow opens PR with sync report. `builder models:update` command (#651)
- **llm_gemini model profiles**: added `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-image-preview`; standardized `gemini-2.5-*` dot notation; deprecated profiles retained with migration guidance
- **Removed `llm_vertex` node**: Vertex AI now supported via `llm_gemini`; migrated vision nodes to `LLMBase`; fixed `llm_gemini` API key validation (dropped strict `startsWith('AI')` check, added sub-key fallback for old pipe files where sub-key is `profile.split('_',1)[1]`); fixed `validateConfig` to early-return when apikey is empty (secure fields not decrypted at validate time); removed vertex icon from UI; bumped client-typescript SDK to 1.1.0 (#902)
- **OpenAI models** updated to latest (#503); deprecated Gemini models removed (#500)
- **Service config cleanup**: removed obsolete `input` section from 72 service configuration files (was duplicate of lane declaration, closes #629) (#728)
- **Milvus node**: configurable timeout (default 60s, was hardcoded 20), connection error handling with meaningful messages, bulk insert with configurable batch size (default 50, was one-at-a-time), `_batchUpsertResults()` helper for markDeleted/markActive, timeout on `remove()`, COSINE distance score range [0,2] rescaling documented (#562)
- **Node tests parallelized** with pytest-xdist (#700)
- **Tool input helpers**: `normalize_tool_input()` replaces 4 copy-pasted variants across tool nodes. `require_str`/`require_int`/`optional_str` replace local validators (44 callsites in `tool_github`). `require_str` now raises `ValueError` cleanly on non-string inputs (was `AttributeError`). `require_int` rejects `bool` (an `int` subclass). 41 unit tests (#759, #766)
- **Backward-compat DAP token fallback**: `get_task_token()` checks `arguments.token` first, falls back to `request.token` for older clients (#902)
- **pnpm** pinned via `packageManager` field (#623)
- **Version bump**: all release packages bumped to next minor (server 3.1.2 → 3.2.0, chat/dropper-ui 2.0.1 → 2.1.0, all others 1.0.x → 1.1.0)
- **engines.node** bumped from ≥18.0.0 to ≥20.0.0 (aligns with serialize-javascript@7 requirement and CI reality)
- **Provisioning**: creates Development + Production teams (Production default); `build_api_key` uses random nonce
- **VSCode detection**: chat-ui/dropper-ui changed from `window.parent !== window` to checking for `acquireVsCodeApi` (canonical detection)
- **Lefthook**: sequential mode; disabled colors to fix terminal corruption on Windows

### Fixed

#### Security
- **Critical: RCE**: prevent arbitrary module injection via `/use` endpoint. Added `ALLOWED_MODULES` frozenset whitelist restricting dynamic imports to 10 known service modules. Requests for any other module return 400 (#342)
- **Critical: Injection**: prevent filter expression injection in Milvus vector store (#355)
- **Auth**: require authentication for profiler endpoints; escape HTML output (#362)
- **Env expansion**: restrict `${VAR}` expansion in pipeline configs to allowlisted prefixes (`ROCKETRIDE_`, `PIPELINE_`, `NODE_`, `ROCKET_`); all others replaced with `<REDACTED>` to prevent exfiltration of AWS keys, DB URLs, tokens (#359)
- **Temp files**: use secure temporary file creation in task engine (#356)
- **SQL safety**: switch from blacklist to allowlist approach (#577)
- **Path traversal**: use `pathlib.is_relative_to` checks (#580)
- **Redaction**: expand sensitive field redaction patterns in VS Code logger (#578)
- **Input validation**: add validation/sanitization to LLM chat drivers (#559)
- **Rate limiting**: add rate limiting to `tool_http_request` node (#560)
- **Remote nodes**: improve error handling in remote node execution (#565)
- **Pinned deps**: handlebars + protobufjs via pnpm.overrides (#783)

#### Client SDKs: Fixes
- **Python client**: break drain cycle causing `RecursionError` on disconnect, `_drain_message_tasks` walks each candidate's `_fut_waiter` chain and excludes tasks that transitively await the drainer itself, so the gather can never close back on itself. `dap_client.request()`'s `ConnectionError` handler now uses fire-and-forget `self._transport.disconnect()` instead of `await self.disconnect()` (develop's `disconnect()` is sync-returns-Task). Two regression tests pinning each fix (#792)
- **Python client**: clean pending DAP request on send failure, prevents zombie futures accumulating on flaky connections when the WebSocket drops mid-request (#736)
- **Python client**: align `requires-python` with monorepo target (py310), was still declaring py38 (#491)
- **Python client**: `set_env` now updates `os.environ` in-memory (removes stale `ROCKETRIDE_*` keys, then sets new values) before writing the `.env` file, so `get_env` reflects changes immediately without a server restart. Uses `sys.executable` instead of `sys.argv[0]` for the `.env` file location
- **Python client**: `ws_path` composition uses `parsed._replace` instead of string concatenation to avoid malformed URIs
- **Python client**: popped consumed kwargs (`ws_path`, `client_name`, `env`, etc.) before passing to `super().__init__()` to avoid "multiple values for keyword argument" `TypeError`
- **TypeScript client**: preserve user-specified port in `normalizeUri`, the URL API silently strips scheme-default ports (:443 on https, :80 on http); now checks raw input for explicit `:digits` after the scheme before deciding whether to add default port (#377)
- **TypeScript client**: `DataPipe.open()` sets `_opened` only after successful SSE setup; on `setEvents` failure, rolls back via `close()` so the server pipe is not left half-open. `close()` now also handles the case where server assigned `pipe_id` but `_opened` was never set to true (#704)
- **TypeScript client**: `DataPipe.close()` sets `_opened = false` in the finally block, preventing double-close races
- **TypeScript client**: `connect()` treats empty or whitespace-only `ROCKETRIDE_APIKEY` in the client env snapshot as **unset**, so it does not override constructor-provided auth (#704)
- **TypeScript client**: `getTaskStatus` applies a default per-request timeout of 15s so CI doesn't hang indefinitely on a dead task; callers can pass `options.timeout` (ms) or `{ timeout: false }` to skip (#704)
- **Both clients**: pipe error messages now include common-cause diagnostics (pipeline not running, wrong source type, MIME mismatch) to reduce debugging time
- **SDK connect error callback type** corrected, was typed incorrectly in the TypeScript client (#576)
- **`CreditBalance` type** aligned with backend camelCase wire shape (#714)

#### VS Code Extension
- **Chat webview blank screen**: realigned `view:ready` handshake so chat panel renders after extension reload (#688)
- **Explorer empty-state**: clicking +File/+Folder on empty PIPELINES tree was silent no-op (input row gated on `entries.length > 0`). Now renders input when root-level create is pending. Stale `selectedPath` falls through to root when all entries deleted (#901)
- **Annotation double-click**: annotation nodes advertised "Double-click gear to add content..." but gear was hidden until hover (CSS opacity:0→1), opened on single-click not double-click, and body had no `onDoubleClick`. Added `onDoubleClick` on annotation root, updated placeholder text (#901)
- **Team selector**: cloud team selector not appearing after sign-in because team fetching was embedded inside cached `probeServerInfo()`. Decoupled into separate `fetchCloudTeams()` driven by `useEffect([isSaas, cloudSignedIn])` (#877)
- **Billing app names**: subscription cards showing raw `appId` instead of human-readable name. Added full `apps` manifest prop chain so components build own `appId → app` lookup map (#877)
- **Canvas-played pipelines** now register in sidebar menu (#571)
- **Missing hostname** handled in URI parsing (#530)
- **OSX Python path** for Python-EaaS debugger (#693)
- **Dark mode**: fixed icon and edge visibility in flow builder (#597)
- **UI validation** fixes (#767)
- **Icons and coloring** for Bland, GMI, and trash bin (#634)
- **QuickAdd popup** label copy improved (#679)
- **Product Hunt badge**: converted SVG to PNG (marketplace rejects SVGs)

#### Engine & Nodes
- **LLM**: clear correct `_chat` reference in `endGlobal` across all LLM nodes (#531)
- **Milvus**: apply `retrieval_score_threshold` filter in `searchSemantic` (#726)
- **Database**: bound Neo4j EXECUTE rows; parse `allow_execute` strictly (only '1'/'true'/'yes'/'on')
- **Frame grabber**: user-configured interval was being ignored (#675)
- **Pipeline configs**: error handling for missing configuration files (#544)
- **Mutable defaults**: replaced mutable default arguments with `None` across Python nodes (#582)
- **Chunk scoping**: `_processFullTables` used stale `doc` variable from outer loop and called `Doc()` with invalid constructor params. Fixed to reset `page_content` on chunk itself. Follow-up: fixed score assignment that replaced Doc with float, and first-chunk aliasing that dropped text (#776)
- **Mock truthiness**: `psycopg2`: `isinstance(False, int)` is True, so `isDeleted=False` was matched as LIMIT value (added `not isinstance(p, bool)` guard). `chromadb`: `if limit and ...` treated `limit=0` as falsy (changed to `limit is not None`). `weaviate`: `distance if distance else 1.0` collapsed 0.0 (exact match) to 1.0 (changed to `distance is not None`) (#748)
- **Async safety**: `_message_tasks` set accessed from multiple async contexts without a lock (#535)
- **CLI shutdown**: SIGINT/SIGTERM handlers with proper exit codes (130/143), double-signal force exit, 5s cleanup timeout, idempotent `cleanupClient` via dedup promise, `isCancelled` guards on command actions, `run()`/`main()` shutdown awareness via `awaitShutdown()` (RR-655, #891)
- **setuptools**: bootstrapped alongside wheel for `uv pip compile`, legacy sdists (e.g. `docopt 0.6.2` via kokoro → misaki → num2words chain) need setup.py but uv doesn't supply setuptools when build isolation is off (#871)
- **Cloud port**: corrected from 433 to 443 in `services.json` (#684)
- **LLM providers**: small cleanup across all LLM nodes (#645)
- **Auth token precedence**: URL auth param prioritized over stale sessionStorage token from previous task (#902)
- **AVIReader**: capture errors from background `_data_process` thread and re-raise on `stop()` so pipeline errors surface as task errors (#803)
- **Webhook/Telegram nodes**: removed `server.use('profiler')` calls (profiler module was deleted; these caused "Module 'profiler' is not allowed" crash) (#803)
- **Task auth**: removed early `ValueError` on empty credential that prevented anonymous/no-key OSS connections from reaching auth check (#803)

#### CI/CD
- **Open VSX**: handle 'already published' error in release workflow (#480)
- **Docs-only PRs**: build passthrough so they don't block CI (#607)
- **Flaky tests**: resolve timeouts and hanging in concurrent pipeline tests, shared hardcoded `project_id` caused server-side contention serializing subprocess launches (#561, #877)
- **Discord webhooks**: retry/backoff for webhook calls (#797); prevent duplicate posts on discussion edits (#698)
- **Nightly workflow**: explicit branch check on `workflow_run` trigger (#771); allow `workflow_dispatch` from stage and main (#906)
- **Release tags**: push via `WORKFLOW_PAT` with repo+workflow scope (#774)
- **pytest-xdist race**: all 6 path-traversal test methods shared same `outside.txt` in system temp root; fixed by wrapping `workdir` in per-test tempdir (#872)
- **pnpm-lock.yaml**: restore libc fields (#622); fix lucide-react dependency (#621)
- **CI API key**: use literal `ROCKETRIDE_APIKEY` in Test step instead of secret (#742); match GraphQL github-actions author login (#699)
- **ruff format**: pure whitespace fixes for vision node files that left develop CI red (#902)

#### Tests
- **AI unit-test coverage** grown from 8% to 43% (395 → 945 passing tests). Covers: sql_safety, common/util/validation/table, dap_conn, pipeline_validation, web endpoints, auth middleware, sandbox execution, profiler lifecycle, account/reporter/keystore, all command handlers, data_conn, task_engine state, task_server background loops, transports, task_http, store providers (S3 + Azure), DB base classes, dropper path-traversal guard. Assertions tightened per CodeRabbit review. CodeQL auth-callback URL assertions anchored (#831)
- **Tests realigned** with team-based permissions and metrics rewrite, updated mocks for `teamId`, `organizations`, `resolve_task_permissions`, `tokens.gpu_inference`/`tokens.custom`, renamed `apikey` → `user_id`. Dropped tests for deleted code. Added `test_cmd_public.py` (#870)
- **Node tests**: full improvements and mock cleanup (#687)

### Dependency Updates
- litellm ~1.50 → ~1.83 (#816)
- DOMPurify → 3.4.x (resolves 16 alerts / 8 GHSAs) (#886)
- cryptography pinned to 46.0.7 (#884)
- SQLAlchemy owned at ai layer, pinned ≥2.0,<2.1 (#804)
- Patched via pnpm.overrides:
  - **Routing**: react-router 6.26→6.30.3, @remix-run/router inlined (#914)
  - **Parsers**: ajv@8→≥8.18.0, markdown-it→≥14.1.1, postcss→≥8.5.10, prismjs→≥1.30.0, yaml@1→≥1.10.3 (#915)
  - **Middleware**: koa→≥2.16.4 (3 advisories), qs→≥6.14.2 (#916)
  - **Util/SVG**: svgo@2→≥2.8.1, flatted→≥3.4.2, immutable@5→≥5.1.5, underscore→≥1.13.8 (#917)
  - **Security**: picomatch@2→≥2.3.2, picomatch@4→≥4.0.4, fast-uri→≥3.1.2, serialize-javascript→≥7.0.5 (#890)
  - **Minimatch**: all 4 major lines patched (3→≥3.1.4, 5→≥5.1.8, 9→≥9.0.7, 10→≥10.2.3) (#887)
  - **Core**: undici→≥7.24.0 (6 advisories), lodash→≥4.18.0, lodash-es→≥4.18.0 (#888)
  - handlebars→≥4.7.9, protobufjs→≥7.5.5 (#783)
- Bumped: aiohttp, pygit2 1.15→1.19, soundfile 0.12→0.13, requests, ws 8.19→8.20, postcss 8.5.6→8.5.10, nltk, spacy, spacy-transformers, cymem, murmurhash, preshed, srsly, thinc, psycopg2-binary, pymysql, opensearch-py, npm-production group (adm-zip, tar, lucide-react, dockerode, web-vitals), shared-ui devDependencies (rollup, @types/react, @types/react-dom), cosign-installer, ossf/scorecard-action, gh-actions group (pnpm/action-setup, github/codeql-action, softprops/action-gh-release, dorny/paths-filter)

---

## RocketRide TypeScript Client v1.3.0

**TypeScript SDK** · v1.3.0 · July 7, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.3.0)

### ⚠ Breaking Changes: Client SDKs (`rocketride` / `rocketride-python`)

These changes affect code that imports and calls the Python or TypeScript client SDKs directly. The old `connect()` / `disconnect()` signatures are preserved as backward-compatible wrappers, but callers should migrate to the new layered API.

#### Connection API (both SDKs)

| Before (1.0.x) | After (1.1.0) | Notes |
|---|---|---|
| `connect(auth?, uri?, timeout?)` → `void` | `connect(credential?, { uri?, timeout? })` → `ConnectResult` | Now returns full user identity (userId, organizations, apps, teams). The `auth` param is renamed `credential` to reflect that it accepts API keys, Zitadel access tokens, and `rr_*` user tokens. Old positional `auth`/`uri` kwargs still accepted but deprecated. |
| `disconnect()` → `void` | `disconnect()` → `void` | Signature unchanged; internally calls `logout()` + `detach()`. |
| *(not available)* | `attach(uri?)` → `void` | Opens the WebSocket **without** authenticating. Required for public/unauthenticated operations like catalog browsing. |
| *(not available)* | `login(credential?)` → `ConnectResult` | Sends the DAP `auth` command over an attached transport. Supports credential rotation (auto-logout if credential differs). |
| *(not available)* | `logout()` → `void` | Sends new `deauth` DAP command, reverts the connection to unauthenticated without closing the socket. |
| *(not available)* | `detach()` → `void` | Tears down the WebSocket and cancels the reconnect engine. |
| `isConnected()` | `isConnected()` *(unchanged)* | Returns `true` only when both attached **and** authenticated. |
| *(not available)* | `isAttached()` | `true` when the WebSocket is open, regardless of auth state. |
| *(not available)* | `isAuthenticated()` | `true` when the auth handshake has succeeded on the current connection. |

**Reconnection engine rewritten**: the old flag soup (`_manualDisconnect`, `_authRejected`, `_didNotifyConnected`) is replaced by a `_desiredState` model (`'detached'` | `'attached'` | `'authenticated'`). Linear backoff (250ms increments, 15s cap) replaces exponential backoff, reconnection now **never gives up**. `maxRetryTime` is accepted for backward compatibility but **ignored**.

#### Python-specific breaking changes

- **`async with` context manager removed**: `__aenter__` / `__aexit__` are deleted. Replace `async with RocketRideClient(...) as client:` with explicit `await client.connect()` / `await client.disconnect()` in a try/finally.
- **`connect()` now returns `ConnectResult`**: previously returned `None`. Callers that did `await client.connect()` without capturing the result are unaffected; callers that typed the return as `None` will need to update.
- **`use()` no longer substitutes `${ROCKETRIDE_*}` client-side**: the raw pipeline is sent to the server, which handles all variable resolution via `get_merged_env()`. If you were relying on client-side `.env` interpolation, variables must now be set server-side (via the Variables page or `client.account.set_env()`).
- **Event type renames**: `EVENT_STATUS_UPDATE` → `EVENT_STATUS`; `EVENT_TASK` → split into `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART`. Code that imports the old names will get `ImportError`.
- **`auth` credential removed from transport layer**: `TransportWebSocket` no longer stores or exposes `auth`. Auth is exclusively managed by the `ConnectionMixin` / `RocketRideClient` layer.

#### TypeScript-specific breaking changes

- **`connect()` signature changed**: old: `connect(options?: number | { uri?, auth?, timeout? })` → `void`. New: `connect(credential?, options?: { uri?, timeout? })` → `Promise<ConnectResult>`. The `auth` property inside options is removed; pass the credential as the first argument. The numeric-only shorthand `connect(5000)` is removed.
- **`DataPipe` errors changed from `Error` to `PipeException`**: `open()`, `write()`, and `close()` now throw `PipeException` (extends `Error`) instead of plain `Error` when the server reports a failure. Callers catching `Error` are still compatible; callers matching on error message strings may need to update. `PipeException` carries the full DAP response body.
- **`setConnectionParams()` removed**: use `login(credential, { uri })` or call `attach(newUri)` + `login()` instead.
- **Project store methods removed**: `saveProject()`, `getProject()`, `deleteProject()`, `getAllProjects()` are deleted. Use the new filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`.
- **`validate()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ValidationResult` (typed interface with `valid`, `errors`, `warnings` fields).
- **`getServices()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ServicesResponse` (typed interface).

#### Both SDKs: new exception types

- **`PipeException`** (Python: subclass of `RuntimeError`; TypeScript: subclass of `Error`): thrown by `DataPipe.open()`, `.write()`, `.close()` when the server reports failure. Carries the full DAP response including `message`, `body`, and error code. Replaces generic `RuntimeError` / `Error`.
- **`ConnectionException`** (TypeScript): thrown on transport-level failures.

### Added

#### New Nodes
- **Exa Search**: semantic web search node integrating with the Exa API (exa.ai) for real-time data enrichment in pipelines. Agents invoke the tool to search the web and retrieve structured results including titles, URLs, text content, relevance scores, and published dates. Includes configurable `numResults` with min/max validation, retry exception sanitization to prevent API key leakage, and defensive boolean config parsing (#386, #509)
- **Bland AI**: voice call tool node for AI-driven phone calls via the Bland AI platform (#521)
- **OpenAI Compatible**: generic LLM node supporting any OpenAI-compatible API endpoint, allowing connection to self-hosted or third-party inference servers that follow the OpenAI chat completions API (#518)
- **GMI Cloud**: LLM connector for GMI Cloud inference platform (api.gmi-serving.com) hosting 100+ models on H100/H200 GPUs. Two tiers: shared (always-on, key-only: DeepSeek, GPT, Claude, Gemini) and deploy-on-demand (endpoint URL + key: Llama 4, Qwen3). Custom profile for arbitrary model/endpoint combinations (#540)
- **Guardrails**: AI safety node with comprehensive input/output validation. Input: prompt injection detection (regex + keyword scoring), topic restriction (allowed/blocked keyword lists), input length enforcement (char + token limits). Output: hallucination detection (sentence-level grounding), content safety (self-harm, violence, illegal activity patterns), PII leak detection (email, phone, SSN, credit card, IP), format compliance (JSON, markdown, bullet/numbered lists). Policy modes: block/warn/log. Profiles: basic (injection + PII), strict (all checks), custom. 87 tests (#534)
- **Video Embedding**: extracts frames from video input (MP4, AVI, MOV, WebM) at configurable intervals and generates vector embeddings using CLIP/ViT models for semantic search and RAG pipelines. Configurable frame interval, max frames, start time, duration, and max video file size (default 500 MB) to prevent unbounded memory. VideoCapture resource leak fixed with finally block (#516)
- **Kokoro TTS**: self-contained text-to-speech node using the Kokoro engine. Slim requirements (no piper/transformers/cloud). KokoroLoader, spacy_en_model, wav_to_mp3 utilities. Supports question, answer, and document lanes (RR-411, #662)
- **Telegram Bot**: source node connecting a Telegram bot to a pipeline via long polling or webhook. Routes incoming messages to appropriate lanes by content type (text, image, audio, video, documents) and sends pipeline responses back as replies (#659)
- **GitHub Tool**: tool node for GitHub API operations (issues, PRs, repositories) with full test suite for tool calling (#640)
- **Git Tool**: self-contained Git operations using pygit2 (libgit2), no host git binary required. Capabilities: clone, init, status, log, show, diff, blame, file_at, ls_files, grep, stage, commit, stash, branch create/checkout/merge/delete, fetch, pull, push (token + SSH auth), write_file with path-traversal guard. Safe mode (default on) blocks force-push and force branch deletion. Full unit test suite + integration tests (activated via `GIT_TEST_REPO_PATH` env). Includes `git_agent_example.pipe` (#654, #731)
- **Filesystem Tool**: file system operations (read, write, list, mkdir, delete) with path whitelist security check via `_prepare()` method. Operations can be selectively enabled/disabled at the node level. Shared prologue extraction via keyword flags (path_required, needs_encoding, needs_content) (#682)
- **Pipeline Tool**: run pipelines as tool calls from other pipelines, enabling pipeline composition and hierarchical agent workflows (#647)
- **LLM Vision (Gemini)**: image understanding via Gemini models with cache management (non-symmetric cache + empty frame guard)
- **LLM Vision (OpenAI)**: image understanding via OpenAI vision models
- **Webhook**: question lane support for webhook-triggered pipelines (#431)
- **CrewAI Orchestrator**: multi-agent orchestration via CrewAI framework. Exposes expert config fields (goal, backstory, expected_output, max_iter) for both agent and orchestrator node types. Advanced mode for fine-grained control. Sub-agent config propagated through `crewai.describe()`. Manager node renamed from Orchestrator, tool invoke removed from manager (#608)

#### VS Code Extension
- **Engine management overhaul**: replaced scattered engine lifecycle code (connection/, deploy/) with a clean `EngineBackend` hierarchy under `src/engine/`. Each connection mode (local, service, docker, cloud, onprem) gets its own backend implementation. `EngineRegistry` singleton reconciler detects config changes (API key, host URL, etc.) via checksums and auto-restarts affected engines on settings save. Eliminated `engine:status` event, all progress flows through `shell:statusChange`. `ConnectionManager` becomes passive: connects on engine `ready`, disconnects on `idle`. Unified `ioControl` message pattern for all panel operations. Migration from legacy layout (`globalStorage` + `config.json`) to new structure. Welcome page uses same `applyAllSettings` + reconcile path as Settings (#922)
- **Settings overhaul & target panels**: atomic settings save via `ConfigManager.applyAllSettings()` with `isBatchApplying` flag suppressing intermediate change events (eliminates race conditions from writing 20+ config keys individually, which caused connection managers to react to half-written state). Self-contained panels per mode (Local, Cloud, OnPrem, Docker, Service) handling both configuration and operational UI (status, install/start/stop/remove/update, progress, version selection). `EngineOperations` service extracted from `PageDeployProvider`. Deploy page command redirected to Settings. `useTheme` hook for VS Code dark/light detection. Embedded Docker/Service SVG logos. Build config consolidated: `.config` as single source of truth for Zitadel URLs/client IDs, esbuild loads `.config` first then `.env` on top, stopped name remapping of Zitadel keys. Cloud mode no longer hardcodes a non-existent URL, uses `config.hostUrl` at runtime (#725)
- **Standalone Variables page**: new "Variables" webview accessible from sidebar footer for managing `ROCKETRIDE_*` environment variables per connection slot (Development/Deployment). `EnvironmentProvider` with per-slot client resolution, `EnvironmentWebview` with pill bar for slot selection. OSS servers show single "Server Variables" card; SaaS servers show Organization/Team/User cards gated by permissions. `set_env` now updates `os.environ` in-memory before writing `.env` file. Deploy connection fix: removed `isSharedMode()` guard that skipped engine status listener registration. `commonStyles.tabContent` now uses `border-box` sizing. Removed capabilities filter that hid Cloud option. All "Environment" labels renamed to "Variables"
- **`${ROCKETRIDE_*}` variable autocomplete**: node config fields now offer autocomplete suggestions for defined pipeline variables. `useEnvVarAutocomplete` hook detects `${` trigger and filters keys by partial match. `EnvVarSuggestions` popover with arrow-key navigation. Wired into `BaseInputTemplate`, `TextareaWidget`, and `ApiKeyWidget`. `transformErrors` suppresses RJSF validation errors for fields containing `${ROCKETRIDE_*}`. `rrext_validate` now resolves env vars before validation using the same merged env as pipeline execution. Fixed `getHttpUrl()` to normalize engineUri before parsing
- **Category headers in QuickAddPopup**: compatible services grouped by bold uppercase category headers with indented items. Shared `CATEGORY_TITLES` extracted to `categoryTitles.ts`. `CreateNodePanel` auto-expands matching categories during search, restores previous expand/collapse state when search is cleared. Environment protocol types extracted to prevent build errors
- **Server Monitor panel**: real-time dashboard showing connections, tasks, and aggregate metrics via new `getDashboard()` / `get_dashboard()` SDK methods (DAP `rrext_dashboard` command). Client identification (`clientName`/`clientVersion`) forwarded during auth handshake so server can distinguish "VS Code 0.9.4" vs "CLI 1.2.0". Python DAP client skips auth message when transport lacks `get_auth()` (fixes crash for non-WebSocket transports). Consolidated `ServicePython` log level into `DebugOut` (#595)
- **Other task viewer via ProjectWebview**: `PageStatusProvider` completely rewritten. Previously opened a lightweight `StatusWebview` that couldn't show the node graph (nodes squashed at top, no toolbar, missing servicesJson). Now fetches unresolved pipeline via `getTaskToken` + `getTaskPipeline`, creates panel using the full Canvas/ProjectView stack, sends `project:load` with `isReadonly:true`. Falls back to synthesized single-node project if fetch fails. `StatusWebview` deleted (#803)
- **Readonly canvas**: single `isReadonly` prop replaces two inconsistent lock mechanisms (14-boolean `IFlowFeatures` and partially-implemented `isLocked`). `effectiveLock = isReadonly || internalIsLocked`. Guards added to `addNode()`, `updateNode()`, `deleteNode()`, paste, context-menu, lane click, config panel Save, all previously unguarded. Lock button hidden when `isReadonly` (#803)
- **Save button in canvas toolbar**: always-visible floppy disk icon with dirty-state tracking; grayed when clean, brand-colored when dirty. `isDirty`/`isNew`/`onSave` threaded through `IFlowProps` → `FlowContainer` → `FlowProvider` → `FlowProjectProvider`. `FlowCanvas` defers ReactFlow render until container has non-zero dimensions via `ResizeObserver`. `canvas:requestSave` calls `document.save()` directly (#678)
- **Dirty-state save pattern for settings**: card header starts clean (no buttons); on edit, Cancel and Save appear; on save, buttons disappear and "Saved" flashes for 5 seconds then fades; Cancel reverts to last-saved snapshot. Applied to all 5 VS Code settings tabs and shell-ui settings page (#877)
- **Play button shows actionable text**: renamed idle label from "Play" to "Run Pipeline". Added STOPPING state with "Stopping..." disabled button to prevent double-clicks. Widened hover expansion for longer label. Smooth CSS transitions with easing functions (#575)
- **Improved stop button feedback**: Pipeline Observability screen handles `TASK_STATE.STOPPING` with "Stopping..." disabled state and distinct orange styling, preventing duplicate clicks (#549)
- **Simplified sidebar footer**: replaced popup menu (three redundant gear icons all opening Settings) with flat layout when connection is shared and no cloud account. Documentation and Settings buttons rendered directly, connection status inline, announcements ticker rotates cards every 7 seconds. Full popup preserved for cloud account or independent connections. Panel sash restyled with native `--vscode-sash-hoverBorder` token, widened from 2px to 4px
- **Test Connection button**: available on service/docker/onprem panels via `ioControl('test')`
- **Docker GHCR tag fetching**: global cache for prerelease resolution with 15s timeout on HTTPS requests. Split-button dropdowns with grouped "Recommended" / "All versions" headers. Version metadata persisted per instance lifecycle. Linux package manager auto-detection (apt/dnf/yum/pacman) instead of hardcoded apt-get
- **Version tracking**: persistent `version.local.json`, `version.service.json`, `version.docker.json` files. PID liveness check before preserving `.pid` files during engine dir clear. Guard against phantom installs (missing binary). UAC-cancel fallback and uninstall.ps1 fixes
- **Event naming unification**: all connection events renamed to `shell:*` namespace matching cloud-ui vocabulary. `'event'` → `'shell:event'`, `'connected'` → `'shell:connected'`, `'connectionStateChanged'` → `'shell:statusChange'`, etc. All 10 providers renamed to drop redundant `Page` prefix. All 9 view directories renamed similarly (#803)
- **`.env` file management removed**: ~350 lines of env file handling removed from `ConfigManager` (envFileWatcher, envRawText, parseEnvFile, saveEnvFile, syncSettingsToEnv, etc.). Environment variables for pipeline variable replacement are now managed server-side (layered env in DB). Extension no longer maintains workspace `.env` file. URL resolution consolidated into `ConnectionManager` (per-group, not hardcoded to dev group) (#803)
- **On-demand env loading**: replaced 7 env-specific `AccountView` props with 2 generic callbacks (`onLoadEnv`, `onSaveEnv`) plus `refreshSignal`. Each `EnvScopeCard` requests its own data on mount. Promise-based messaging with 10s timeout. `shell:accountUpdate` as first-class event (no longer filtered from generic stream). Standalone `BillingProvider` deleted; billing is a tab inside Account (#803)
- **Welcome page simplification**: `welcomeDismissed` set automatically on save (no manual checkbox). Works from both Welcome and Settings pages (#803)

#### Shell UI (Web Host)
- **Shell-ui replaces cloud-ui**: new Module Federation host application served by Python `shell` module (`ai.modules.shell`) with public HTTP routes for SPA and all static assets under `/shell/`. Unifies OSS and SaaS into single codebase. Server-side app manifest delivery via `get_public_apps()` / `get_apps_for_user()` on AccountBase. Pre-auth info probe returns public apps for marketplace. Connect response includes authenticated user's full entitled app list (#803)
- **MUI removal**: replaced Material UI with plain CSS/HTML across entire shared-ui package; runtime theme system with light/dark JSON tokens
- **Theme rebrand**: replaced legacy purple (#5900FF) with cyan (#00b9ec) TOKENS palette. Light theme updated to warm-neutral (cream/stone backgrounds instead of pure white) (#803)
- **Theme flash fix**: `index.html` inline script sets `--rr-bg-default` and body background synchronously before React renders. `createShellConfig` reads saved theme from localStorage instead of always defaulting to rocketride-light, eliminating tan background during 1.5s OAuth code-exchange window (#878)
- **Chat module**: host-agnostic chat surface following established module pattern (props-in, callbacks-out, `--rr-*` CSS tokens). `ChatView` (MessageList + ChatInputField), `MessageBubble` (user/bot/system/status with markdown), `MarkdownRenderer` (react-markdown + GFM + syntax highlighting + charts), `ChartRenderer` (chart.js with circular-reference guard), `TypingIndicator` (animated bouncing dots), `useChatMessages` hook (message state + sendMessage + monotonic IDs) (#724)
- **Canvas state persistence**: viewport (zoom/pan), lock state, snap-to-grid, and editor mode now persist in `.pipe` files via `PipelineConfig` schema (TypeScript + Python SDKs). New `isFlowReady` boolean state tracks when all nodes have been rendered/measured by ReactFlow, replacing scattered `setTimeout`/`requestAnimationFrame` workarounds. Centralized `loadCanvas(nodes, edges)` as single entry point for structural canvas changes. Viewport restored on load via `isFlowReady` cycle, falls back to fitView. Spiral search for non-overlapping node placement. `EmptyCanvasPrompt` only shown when `nodes.length === 0 AND isFlowReady` (#670)
- **ProjectView architecture**: decomposed monolithic `modules/flow/` canvas module into composable multi-view project architecture (#670)
- **Style consolidation**: added `buttonPrimarySmall`, `buttonSecondarySmall`, `buttonDangerSmall`, `modalDialog`, `modalHeader`, `modalBody`, `modalFooter` to `commonStyles`. Added `cardHeaderButton`/`cardBodyButton` size modifiers for card contexts. Eliminated `Btn` wrapper component. Account `shared.tsx` trimmed from ~30 to 9 entries. All emojis removed from account UI (#803)
- **Shared connection types**: `ConnectionState` enum, `ConnectionMode`, `IAuthProvider`, `IConnectionManager` interface, `ShellAppEntry`, `ShellConnectionEventMap` with typed payloads for all `shell:*` events. Index signature for app-defined events (#803)

#### Billing, Account & Auth
- **Billing detail**: `BillingDetail` type gains `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart` in both SDKs. Subscription cards show detail grid with plan info. Cancel subscription requires confirmation modal. App display name shown instead of raw appId. Credit grant summary per subscription using `creditLabels` from Stripe metadata (#803)
- **Account/Billing merge**: Billing is now a tab inside Account (2nd pill) via `BillingPanel`. Standalone Billing page and provider deleted
- **Permission enforcement**: frontend computes `isOrgAdmin`/`isTeamAdmin` from profile; action buttons hidden for users without required permissions; `OrganizationPanel` read-only for non-admins; destructive actions go through confirmation modals. Team admin enforcement: must always have ≥1 admin (UI + server guard). Permission key fixed: `'admin'` → `'team.admin'`. `_require_team_admin` queries DB directly instead of stale cache (#803)
- **Team-based task permissions**: replaced all `control.userId == caller.userId` ownership checks with `resolve_task_permissions()` so teammates and org admins can monitor/control each other's tasks. Permission strings (e.g. `'task.control'`, `'task.monitor'`) checked against resolved list (#803)
- **Layered environment secrets**: pipeline variables (`ROCKETRIDE_*`) stored encrypted (Fernet) in database per org/team/user scope, merged server-side during task execution. Merge order: `.env` → org → team → user → caller env. `get_merged_env()` on `AccountBase` with OSS (`.env` only) and SaaS (DB) implementations. `client.use()` `env` param for caller overrides (only `ROCKETRIDE_*` accepted). Client-side `processEnvSubstitution` removed, resolution is server-only (#803)
- **Session keys**: API keys are now true PATs inheriting user identity. `is_session` flag on `ApiKey` model. `ensure_session_key()` on every OAuth login: refreshes 90-day expiry if active, creates fresh key if expired/missing. Session keys cannot be self-revoked. Admin revoke is hard-delete. Housekeeping: keys revoked >30d purged on login. UI shows "Session" / "Interactive login" badge (#803)
- **Scoped PATs**: PATs optionally restricted to single team with explicit permissions. Effective permissions intersected with user's actual permissions at auth time (can never escalate). Optional `team_id` on `ApiKey`. Create key modal: team dropdown + conditional `PermGrid`. Key list shows team scope badge (#803)
- **userToken → userId refactor**: server-side event tenant scoping uses `userId` instead of `userToken`. Fixes bug where two connections from same user with different keys wouldn't see each other's dashboard events (#803)
- **Account UI overhaul**: all card headers use `commonStyles.labelUppercase`. Save button pattern: hidden until dirty, shows [Cancel][Save], "Saved" green text with 5s timer. `ProfilePanel`: single "Organizations / Workspaces" card with nested teams. `TeamsPanel`: Delete moved to list with confirm modal. `PermGrid`: `PERM_DISPLAY` labels, alphabetized, added `task.store`, contrasting text on checked tiles (#803)
- **Client SDK attach/login split**: replace monolithic `connect()`/`disconnect()` with layered API: `attach(uri?)` opens WebSocket without auth (for public APIs like catalog), `login(credential?)` sends DAP auth, `logout()` sends new `deauth` command (reverts to unauthenticated without closing socket), `detach()` tears down WebSocket. Old `connect()`/`disconnect()` preserved as backward-compatible wrappers. Reconnection engine rewritten around `_desiredState` model ('detached' | 'attached' | 'authenticated'). Linear backoff (250ms increments, 15s cap), reconnection never gives up. Auth credential removed from transport layer (#803)
- **Server-driven appStatus**: replaced `subscriptionStatus` with server-computed `appStatus` ('auth' | 'free' | 'unsubscribed' | 'subscribed' | 'trialing' | 'past_due' | 'canceled') and `onDesktop` boolean per app manifest entry. Eliminates client-side reconciliation races (#803)
- **App mode & subscription gating**: `mode` field (free/subscription/paywall) in app manifests. Shell-level subscription gate blocks app iframe until active subscription exists. Desktop app management moved into account identity flow (#803)
- **Token storage hardened**: moved from `localStorage` to `sessionStorage` (cleared when tab closes) addressing CodeQL "Clear text storage of sensitive information" alert (#803)

#### Profiler
- **DAP-based cProfile system**: replaced HTTP-endpoint profiler module with per-process cProfile profiling over DAP connections. Any connected client can profile any process (task server, data engine subprocesses, model server). `CProfileManager` singleton with start/stop/status/report/release API. Owner tracking per connection with disconnect cleanup. SDK methods: `cprofileStart`/`cprofileStop`/`cprofileStatus`/`cprofileReport` (TS + Python) with optional `target` parameter for pipeline profiling. New `profiler-ui` Module Federation remote app with `ProfilerView`, `ConnectionManagerView`, and `ProfilerSidebar` (#803)

#### Module Federation
- **MF stability**: added `runtime: false` to all remote apps (shell-ui provides shared runtime; without it each remote embeds its own runtime copy, causing remoteEntry.js to change on every rebuild and version-mismatch errors during HMR). Added `eager: true` to react/react-dom shared configs (breaks async shared-scope negotiation deadlock where host waits for remote's async chunk and remote waits for host). App loader filters out server-only entries with no `remoteEntry` URL (prevents `normalizeRemote()` crash on `undefined`) (#877)

#### Engine & Core
- **Database EXECUTE**: direct SQL/Cypher execution via `QuestionType.EXECUTE` with `client.database.query()` namespace on both SDKs, bypassing LLM translation and safety gating. Gated behind opt-in `allow_execute` config (default off). Results bounded with `fetchmany(max_execute_rows+1)` (default 25000). Neo4j results capped at same limit. `allow_execute` parses strings strictly: only `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive). EXECUTE output wrapped in try/except; serialized with `default=str`. SDK validates non-empty token/sql before dispatching
- **Database DIALECT**: `QuestionType.DIALECT` for engine capability discovery. SDK callers can ask which engine a database pipeline is connected to (`DatabaseDialect` enum). `_db_dialect()` abstract method on `DatabaseInstanceBase`. `services.json` now exposes UI-toggleable `allow_execute` boolean
- **Handle-based streaming I/O**: generic filesystem-style interface (`open`/`read`/`write`/`close`/`delete`/`stat`/`mkdir`/`list_dir`) on `FileStore`, replacing monolithic in-memory buffering. Domain methods become thin convenience wrappers on client SDKs. Supports S3 multipart upload (5 MB buffer), Azure staged blocks (4 MB buffer), and local filesystem. Handles tagged with owning `connection_id` and force-closed on connection termination (#600)
- **`@tool_function` decorators**: collapsed the two-class pattern (IInstance + ToolsBase driver) into a single class. Any `IInstanceBase` subclass can declare tool entry points with a decorator; the method name becomes the tool ID, decorator carries schema/description, base class `invoke()` dispatches automatically. Eliminates parallel driver classes, factory methods, and boilerplate delegation (#599)
- **Experimental + Deprecated capability flags**: `DEPRECATED = BIT(15)`, `EXPERIMENTAL = BIT(16)` in `PROTOCOL_CAPS`. Both flags wired through C++ parser, pybind11 bindings, both client SDKs, and shared-ui. Yellow "EXPERIMENTAL" badge rendered on canvas nodes, Add Node slider, and Quick Add popup (#606)
- **Docker-compose and healthcheck**: `HEALTHCHECK` instruction in `Dockerfile.engine` using curl to `/ping`. `docker-compose.yml` with engine, PostgreSQL+pgvector, Milvus (+ etcd, MinIO), ChromaDB. Override file for dev hot-reloading. All images pinned to specific versions. Security warnings in `.env.example` (#496)
- **Billing commands mixin**: `BillingCommands` in TaskConn's MRO for `rrext_account_billing`. OSS implementation routes on `arguments.subcommand` with stubs so UI doesn't hang in half-rendered state (#692)
- **Task engine extraction**: `task_engine` and `cmd_data` extracted as standalone modules (#661)
- **GPU inference billing**: `metrics.resource('gpu')` context manager times inference. `CONST_RATE_GPU_INFERENCE_SECOND` for billing. Custom node counters (`pagesProcessed`, etc.) with configurable rates. All 9 AI model files wrapped with `metrics.counter('gpu_inference_count')` + `metrics.resource('gpu')`. Billing reports include `gpu_inference` and `custom` token fields (#803)
- **Metrics rewrite**: replaced Timer class and `resource()` context manager with flat `MetricsManager`: `timer()`, `add_time()`, `counter()`, `event()`. Thread-safe via single lock. Removed per-pipe `ContextVar`, metrics are per-subprocess. ModelClient auto-records server-reported perf dict (#803)
- **ModelClient refactor**: derived from `RocketRideClient` with `ws_path='/models'` so URI normalization, protocol selection, and auth are handled by SDK. Python SDK gains `ws_path` kwarg. Sync `disconnect()` override for worker thread callers. All 9 model wrappers updated. `get_model_server_address()` simplified to return raw string (#877)
- **Model server DAP namespace**: all model server commands renamed to `rrext_ms_*` prefix (load_model → rrext_ms_load_model, etc.) for disambiguation from core DAP commands (#803)
- **GPU guard**: `install_gpu_guard()` blocks direct torch/tensorflow imports in model server mode; all GPU inference must go through ModelClient RPC (#803)
- **Pipeline error surfacing**: `binder.cpp` sets `completionCode` on Entry when `callMethods` encounters error. `bindings.cpp` exposes `completionError` read-only property. `data_conn.py` rewrites `close_sync()` to always extract results even when end/close throws, surfaces `Entry.completionError` when `objectFailed` is True. Errors now reach dropper UI (#803)
- **`rrext_get_pipeline` DAP command**: returns task's unresolved pipeline (with `${...}` placeholders intact) so VS Code can reconstruct node graph without exposing secrets. `_build_task()` now accepts explicit resolved pipeline, `self._pipeline` retains original unresolved form (#803)

#### Client SDKs: New Features

**Layered connection API (both SDKs):**
- `attach()` / `detach()`: open/close the WebSocket without authentication. Enables unauthenticated operations (public catalog browsing, server probes) before the user logs in
- `login()` / `logout()`: authenticate/deauthenticate over an attached transport. `login()` returns `ConnectResult` with full user identity (userId, organizations, apps, teams, permissions). `logout()` sends new `deauth` DAP command, reverting to unauthenticated without closing the socket. Supports credential rotation (auto-logout if a different credential is supplied)
- `connect()` / `disconnect()` preserved as backward-compatible wrappers (`attach` + `login` / `logout` + `detach`), but `connect()` now returns `ConnectResult` instead of void
- `isAttached()`: true when WebSocket is open (regardless of auth)
- `isAuthenticated()`: true when auth handshake has succeeded

**Namespaced API accessors (both SDKs):**
- `client.account`: profile, API keys, org, members, teams, environment variables (`get_env()` / `set_env()` / `get_environment_keys()`)
- `client.billing`: subscriptions, checkout, credits, cancel
- `client.database`: `client.database.query()` for direct SQL/Cypher execution; `client.database.dialect()` for engine discovery (`DatabaseDialect` enum)

**New methods:**
- `RocketRideClient.getServerInfo(uri)` (static): probe a server for capabilities without authenticating. Returns `ServerInfoResult` with version, capabilities, platform, and public apps
- `getTaskToken(projectId, source)`: resolve a running task's session token
- `getTaskPipeline(token)`: retrieve the unresolved pipeline for a running task (placeholders intact, no secrets)
- `getDashboard()`: real-time server dashboard (connections, tasks, metrics)
- `cprofileStart/Stop/Status/Report`: per-process cProfile profiling over DAP
- `call(command, token?, **kwargs)` (Python): single public entry point for all typed DAP operations with optional `on_trace` callback

**TypeScript-specific additions:**
- `wsPath` config option for custom WebSocket paths (e.g. `'/models'` for model server)
- `onTrace` callback for observing all `call()` traffic
- `MonitorKey` type and `addMonitor()` / `removeMonitor()` for reference-counted monitor subscriptions
- `restart()` method for restarting pipeline tasks
- Filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`: replaces the old project store methods
- `getTaskStatus()` applies default 15s timeout (configurable via `options.timeout` or `{ timeout: false }`)
- `validate()` now returns typed `ValidationResult` (was `Record<string, unknown>`)
- `getServices()` now returns typed `ServicesResponse`; `getService()` returns `ServiceDefinition`
- `DataPipe.open()` sets `_opened` only after successful SSE setup with rollback on failure
- `normalizeUri()` preserves user-specified port (was being stripped for scheme-default ports like :443)

**Python-specific additions:**
- `ws_path` kwarg for custom WebSocket paths
- `client_name` / `client_version` kwargs forwarded in auth handshake for client identification
- `on_trace` callback for observing all `call()` traffic
- `public` mode for permanently unauthenticated connections (only `rrext_public_*` commands)
- `DashboardMixin`, `CProfileMixin`, `StoreMixin` added to MRO
- Improved `send()` pipe error context with `PipeException` (catchable as `RuntimeError`)

**New types (both SDKs):**
- `ConnectResult`, `ServerInfoResult`, `AppManifestEntry`, `StripePriceEntry`
- `AccountProfile`, `AccountOrganization`, `AccountOrgTeam`, `ApiKeyRecord`, `OrgDetail`, `MemberRecord`, `TeamRecord`, `TeamDetail`, `TeamMemberRecord`
- `BillingDetail` (extended with `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart`, `credits`, `creditLabels`), `StripePlan`, `CreditBalance` (extended with `labels`), `CreditPack`
- `PROTOCOL_CAPS` enum with all 17 capability flags
- `SERVICE_DEFINITION`, `SERVICES_RESPONSE`, `VALIDATION_ERROR`, `VALIDATION_RESULT`
- `DASHBOARD_OVERVIEW`, `DASHBOARD_MONITOR`, `DASHBOARD_CONNECTION`, `DASHBOARD_TASK`, `DASHBOARD_RESPONSE`, `DASHBOARD_EVENT` and 7 event subtypes
- `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART` (replace old `EVENT_TASK`)
- `EVENT_STATUS` (replaces `EVENT_STATUS_UPDATE`)
- `TASK_TOKENS` extended with `gpu_inference` and `custom` fields
- `CreateKeyParams` accepts optional `teamId` for scoped PATs
- `EVENT_TYPE.DASHBOARD` flag (bit 7) for server-level events; `EVENT_TYPE.ALL` updated to include it
- **Config**: `Config.getNodeConfig()` emits warnings for deprecated profiles with migration guidance from profile's `migration` field

#### MCP
- **MCP Resources and Prompts**: `rocketride://` URI resources (pipeline list, server status, node registry) with graceful error handling for disconnected clients. Three prompt templates (analyze-document, chat-with-data, evaluate-pipeline) with required argument validation and message rendering. 44 tests (#541)

#### Agents & Pipelines
- **Agent framework overhaul**: ProjectView architecture with shared-ui migration (#670)
- **Example pipeline templates** for common AI workflows (#572)

#### Build System
- **Rsbuild upgrade**: all UI apps upgraded from pinned 0.4/1.1 to ~1.7.5, eliminating Node.js `DEP0180` deprecation warnings in Node 22+. ESM config migration (`.ts` → `.mts`). cmake minimum bumped from 3.14 to 3.19. `@rspack/binding-*` platform pins removed. Service config renamed `config.json` → `service-config.json` with migration (#905)
- **Build-input caching**: source fingerprinting (`buildInputHash()` + `hasBuildInputChanged()`) skips UI modules whose inputs haven't changed. `appModule.js` factory eliminates ~80 lines of boilerplate per app. Shell-ui tracks own src/ + shared-ui/src + package.json. `--force` flag bypasses caching. Clean actions clear cached hashes (#877)
- **Builder CLI**: `server:run` action (build + run without shell-ui dev server). `--taskserver=ADDR` replaces `--testport`. `--modelserver` semantics clarified (bare flag = start local, `=ADDR` = use existing). `--simulate-gpus=N` forwarded to model server. `parseServerAddress()` utility (#803, #877)

#### CI/CD
- **Cosign container signing**: keyless signing of rocketride-engine image via Sigstore + GitHub OIDC (signs by digest). GPG detached-signature step for server tarballs/zips, gated on `GPG_SIGNING_KEY` secret (#798)
- **Dependabot**: weekly version updates with smoke tests for litellm and pipeline-node deps. Blocked rsbuild/rslib/rspack 0.x churn and pip major bumps. Semver-major ignores across all 10+ ecosystems (#788, #843, #842, #862)
- **Experimental-release workflow**: `workflow_dispatch`-only, builds from arbitrary branch under configurable tag suffix. Per-product release jobs. No marketplace publishing. `prerelease: true`. First use case: workshop builds (#848)
- **Nightly prereleases**: initially from stage branch (#631), moved to develop on green CI (#713). `workflow_dispatch` expanded to develop/stage/main (#906)
- **Daily Actions storage cleanup** workflow (#636)
- **Discord notifications**: PRs, issues, discussions with live CI check status and PR state tracking in embed (#612, #614, #638). Duplicate posts on discussion edits prevented (#698). Retry/backoff for webhook calls (#797)
- **Ruff and gitleaks**: pre-commit checks (#722); gitleaks made blocking (#681); `ruff format` applied to all Python files (#723)
- **Sequential builder tests** to isolate cross-suite flakes (#734)
- **cmake 4** support (#807)
- **Actions pinned** to immutable commit hashes (#483)
- **Artifact retention** dropped to 1 day for 0.5 GB storage cap (#779)
- **CodeQL** switched from advanced to default setup (#768)

#### Documentation
- **Observability & tracing**: integration guide documenting how external services consume runtime logs, lifecycle events, and pipeline traces over the WebSocket DAP channel. Wired into all agent stubs (Claude Code, Cursor, Windsurf, Copilot) (#716)
- **Node usage guides**: `db_neo4j` with practical examples (#490), `llm_openai` with provider examples (#493), source connectors (#650)
- **Per-node documentation** overhaul, added and updated docs for each node (#639, #660)
- **Engine**: Tika ExternalParser media tool requirements (#729)
- **Python client**: clarified `send()` sources and `.pipe` usage (#705); updated Python 3.8 → 3.10 references (#657); added `.env.example` (#492)
- **Contributing**: require green CI checks before review (#627)
- **SOC2-ready SECURITY.md**: explicit triage/remediation SLA (critical 7d, high 30d, medium 90d), scanning toolchain documentation (CodeQL, Scorecard, Trivy, Dependabot, secret scanning), quarterly access reviews (#762)
- **Two-person control** on alert dismissals documented (#800)
- **Code of Conduct** (#591)
- **README improvements**: onboarding wording, absolute image URLs, GIFs, Product Hunt badge (#706, #506, #478, #590)

#### Security Policies
- **Workflow permissions**: top-level permissions added to 5 reusable workflows (#790); storage-cleanup narrowed to job-level (#794)
- **Stale lockfile removed**: `packages/client-typescript/pnpm-lock.yaml` deleted, override declared in root (#796)

### Changed

- **LLM provider migration**: all LLM providers migrated to `ai.common.LLMBase` (#719); automated LLM model sync tool fetches models from provider APIs, smoke-tests new ones, merges into `services.json` with smart deprecation and three-source token limit resolution (provider API → OpenRouter → LiteLLM). `modelSource` field tracks discovery origin. Weekly CI workflow opens PR with sync report. `builder models:update` command (#651)
- **llm_gemini model profiles**: added `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-image-preview`; standardized `gemini-2.5-*` dot notation; deprecated profiles retained with migration guidance
- **Removed `llm_vertex` node**: Vertex AI now supported via `llm_gemini`; migrated vision nodes to `LLMBase`; fixed `llm_gemini` API key validation (dropped strict `startsWith('AI')` check, added sub-key fallback for old pipe files where sub-key is `profile.split('_',1)[1]`); fixed `validateConfig` to early-return when apikey is empty (secure fields not decrypted at validate time); removed vertex icon from UI; bumped client-typescript SDK to 1.1.0 (#902)
- **OpenAI models** updated to latest (#503); deprecated Gemini models removed (#500)
- **Service config cleanup**: removed obsolete `input` section from 72 service configuration files (was duplicate of lane declaration, closes #629) (#728)
- **Milvus node**: configurable timeout (default 60s, was hardcoded 20), connection error handling with meaningful messages, bulk insert with configurable batch size (default 50, was one-at-a-time), `_batchUpsertResults()` helper for markDeleted/markActive, timeout on `remove()`, COSINE distance score range [0,2] rescaling documented (#562)
- **Node tests parallelized** with pytest-xdist (#700)
- **Tool input helpers**: `normalize_tool_input()` replaces 4 copy-pasted variants across tool nodes. `require_str`/`require_int`/`optional_str` replace local validators (44 callsites in `tool_github`). `require_str` now raises `ValueError` cleanly on non-string inputs (was `AttributeError`). `require_int` rejects `bool` (an `int` subclass). 41 unit tests (#759, #766)
- **Backward-compat DAP token fallback**: `get_task_token()` checks `arguments.token` first, falls back to `request.token` for older clients (#902)
- **pnpm** pinned via `packageManager` field (#623)
- **Version bump**: all release packages bumped to next minor (server 3.1.2 → 3.2.0, chat/dropper-ui 2.0.1 → 2.1.0, all others 1.0.x → 1.1.0)
- **engines.node** bumped from ≥18.0.0 to ≥20.0.0 (aligns with serialize-javascript@7 requirement and CI reality)
- **Provisioning**: creates Development + Production teams (Production default); `build_api_key` uses random nonce
- **VSCode detection**: chat-ui/dropper-ui changed from `window.parent !== window` to checking for `acquireVsCodeApi` (canonical detection)
- **Lefthook**: sequential mode; disabled colors to fix terminal corruption on Windows

### Fixed

#### Security
- **Critical: RCE**: prevent arbitrary module injection via `/use` endpoint. Added `ALLOWED_MODULES` frozenset whitelist restricting dynamic imports to 10 known service modules. Requests for any other module return 400 (#342)
- **Critical: Injection**: prevent filter expression injection in Milvus vector store (#355)
- **Auth**: require authentication for profiler endpoints; escape HTML output (#362)
- **Env expansion**: restrict `${VAR}` expansion in pipeline configs to allowlisted prefixes (`ROCKETRIDE_`, `PIPELINE_`, `NODE_`, `ROCKET_`); all others replaced with `<REDACTED>` to prevent exfiltration of AWS keys, DB URLs, tokens (#359)
- **Temp files**: use secure temporary file creation in task engine (#356)
- **SQL safety**: switch from blacklist to allowlist approach (#577)
- **Path traversal**: use `pathlib.is_relative_to` checks (#580)
- **Redaction**: expand sensitive field redaction patterns in VS Code logger (#578)
- **Input validation**: add validation/sanitization to LLM chat drivers (#559)
- **Rate limiting**: add rate limiting to `tool_http_request` node (#560)
- **Remote nodes**: improve error handling in remote node execution (#565)
- **Pinned deps**: handlebars + protobufjs via pnpm.overrides (#783)

#### Client SDKs: Fixes
- **Python client**: break drain cycle causing `RecursionError` on disconnect, `_drain_message_tasks` walks each candidate's `_fut_waiter` chain and excludes tasks that transitively await the drainer itself, so the gather can never close back on itself. `dap_client.request()`'s `ConnectionError` handler now uses fire-and-forget `self._transport.disconnect()` instead of `await self.disconnect()` (develop's `disconnect()` is sync-returns-Task). Two regression tests pinning each fix (#792)
- **Python client**: clean pending DAP request on send failure, prevents zombie futures accumulating on flaky connections when the WebSocket drops mid-request (#736)
- **Python client**: align `requires-python` with monorepo target (py310), was still declaring py38 (#491)
- **Python client**: `set_env` now updates `os.environ` in-memory (removes stale `ROCKETRIDE_*` keys, then sets new values) before writing the `.env` file, so `get_env` reflects changes immediately without a server restart. Uses `sys.executable` instead of `sys.argv[0]` for the `.env` file location
- **Python client**: `ws_path` composition uses `parsed._replace` instead of string concatenation to avoid malformed URIs
- **Python client**: popped consumed kwargs (`ws_path`, `client_name`, `env`, etc.) before passing to `super().__init__()` to avoid "multiple values for keyword argument" `TypeError`
- **TypeScript client**: preserve user-specified port in `normalizeUri`, the URL API silently strips scheme-default ports (:443 on https, :80 on http); now checks raw input for explicit `:digits` after the scheme before deciding whether to add default port (#377)
- **TypeScript client**: `DataPipe.open()` sets `_opened` only after successful SSE setup; on `setEvents` failure, rolls back via `close()` so the server pipe is not left half-open. `close()` now also handles the case where server assigned `pipe_id` but `_opened` was never set to true (#704)
- **TypeScript client**: `DataPipe.close()` sets `_opened = false` in the finally block, preventing double-close races
- **TypeScript client**: `connect()` treats empty or whitespace-only `ROCKETRIDE_APIKEY` in the client env snapshot as **unset**, so it does not override constructor-provided auth (#704)
- **TypeScript client**: `getTaskStatus` applies a default per-request timeout of 15s so CI doesn't hang indefinitely on a dead task; callers can pass `options.timeout` (ms) or `{ timeout: false }` to skip (#704)
- **Both clients**: pipe error messages now include common-cause diagnostics (pipeline not running, wrong source type, MIME mismatch) to reduce debugging time
- **SDK connect error callback type** corrected, was typed incorrectly in the TypeScript client (#576)
- **`CreditBalance` type** aligned with backend camelCase wire shape (#714)

#### VS Code Extension
- **Chat webview blank screen**: realigned `view:ready` handshake so chat panel renders after extension reload (#688)
- **Explorer empty-state**: clicking +File/+Folder on empty PIPELINES tree was silent no-op (input row gated on `entries.length > 0`). Now renders input when root-level create is pending. Stale `selectedPath` falls through to root when all entries deleted (#901)
- **Annotation double-click**: annotation nodes advertised "Double-click gear to add content..." but gear was hidden until hover (CSS opacity:0→1), opened on single-click not double-click, and body had no `onDoubleClick`. Added `onDoubleClick` on annotation root, updated placeholder text (#901)
- **Team selector**: cloud team selector not appearing after sign-in because team fetching was embedded inside cached `probeServerInfo()`. Decoupled into separate `fetchCloudTeams()` driven by `useEffect([isSaas, cloudSignedIn])` (#877)
- **Billing app names**: subscription cards showing raw `appId` instead of human-readable name. Added full `apps` manifest prop chain so components build own `appId → app` lookup map (#877)
- **Canvas-played pipelines** now register in sidebar menu (#571)
- **Missing hostname** handled in URI parsing (#530)
- **OSX Python path** for Python-EaaS debugger (#693)
- **Dark mode**: fixed icon and edge visibility in flow builder (#597)
- **UI validation** fixes (#767)
- **Icons and coloring** for Bland, GMI, and trash bin (#634)
- **QuickAdd popup** label copy improved (#679)
- **Product Hunt badge**: converted SVG to PNG (marketplace rejects SVGs)

#### Engine & Nodes
- **LLM**: clear correct `_chat` reference in `endGlobal` across all LLM nodes (#531)
- **Milvus**: apply `retrieval_score_threshold` filter in `searchSemantic` (#726)
- **Database**: bound Neo4j EXECUTE rows; parse `allow_execute` strictly (only '1'/'true'/'yes'/'on')
- **Frame grabber**: user-configured interval was being ignored (#675)
- **Pipeline configs**: error handling for missing configuration files (#544)
- **Mutable defaults**: replaced mutable default arguments with `None` across Python nodes (#582)
- **Chunk scoping**: `_processFullTables` used stale `doc` variable from outer loop and called `Doc()` with invalid constructor params. Fixed to reset `page_content` on chunk itself. Follow-up: fixed score assignment that replaced Doc with float, and first-chunk aliasing that dropped text (#776)
- **Mock truthiness**: `psycopg2`: `isinstance(False, int)` is True, so `isDeleted=False` was matched as LIMIT value (added `not isinstance(p, bool)` guard). `chromadb`: `if limit and ...` treated `limit=0` as falsy (changed to `limit is not None`). `weaviate`: `distance if distance else 1.0` collapsed 0.0 (exact match) to 1.0 (changed to `distance is not None`) (#748)
- **Async safety**: `_message_tasks` set accessed from multiple async contexts without a lock (#535)
- **CLI shutdown**: SIGINT/SIGTERM handlers with proper exit codes (130/143), double-signal force exit, 5s cleanup timeout, idempotent `cleanupClient` via dedup promise, `isCancelled` guards on command actions, `run()`/`main()` shutdown awareness via `awaitShutdown()` (RR-655, #891)
- **setuptools**: bootstrapped alongside wheel for `uv pip compile`, legacy sdists (e.g. `docopt 0.6.2` via kokoro → misaki → num2words chain) need setup.py but uv doesn't supply setuptools when build isolation is off (#871)
- **Cloud port**: corrected from 433 to 443 in `services.json` (#684)
- **LLM providers**: small cleanup across all LLM nodes (#645)
- **Auth token precedence**: URL auth param prioritized over stale sessionStorage token from previous task (#902)
- **AVIReader**: capture errors from background `_data_process` thread and re-raise on `stop()` so pipeline errors surface as task errors (#803)
- **Webhook/Telegram nodes**: removed `server.use('profiler')` calls (profiler module was deleted; these caused "Module 'profiler' is not allowed" crash) (#803)
- **Task auth**: removed early `ValueError` on empty credential that prevented anonymous/no-key OSS connections from reaching auth check (#803)

#### CI/CD
- **Open VSX**: handle 'already published' error in release workflow (#480)
- **Docs-only PRs**: build passthrough so they don't block CI (#607)
- **Flaky tests**: resolve timeouts and hanging in concurrent pipeline tests, shared hardcoded `project_id` caused server-side contention serializing subprocess launches (#561, #877)
- **Discord webhooks**: retry/backoff for webhook calls (#797); prevent duplicate posts on discussion edits (#698)
- **Nightly workflow**: explicit branch check on `workflow_run` trigger (#771); allow `workflow_dispatch` from stage and main (#906)
- **Release tags**: push via `WORKFLOW_PAT` with repo+workflow scope (#774)
- **pytest-xdist race**: all 6 path-traversal test methods shared same `outside.txt` in system temp root; fixed by wrapping `workdir` in per-test tempdir (#872)
- **pnpm-lock.yaml**: restore libc fields (#622); fix lucide-react dependency (#621)
- **CI API key**: use literal `ROCKETRIDE_APIKEY` in Test step instead of secret (#742); match GraphQL github-actions author login (#699)
- **ruff format**: pure whitespace fixes for vision node files that left develop CI red (#902)

#### Tests
- **AI unit-test coverage** grown from 8% to 43% (395 → 945 passing tests). Covers: sql_safety, common/util/validation/table, dap_conn, pipeline_validation, web endpoints, auth middleware, sandbox execution, profiler lifecycle, account/reporter/keystore, all command handlers, data_conn, task_engine state, task_server background loops, transports, task_http, store providers (S3 + Azure), DB base classes, dropper path-traversal guard. Assertions tightened per CodeRabbit review. CodeQL auth-callback URL assertions anchored (#831)
- **Tests realigned** with team-based permissions and metrics rewrite, updated mocks for `teamId`, `organizations`, `resolve_task_permissions`, `tokens.gpu_inference`/`tokens.custom`, renamed `apikey` → `user_id`. Dropped tests for deleted code. Added `test_cmd_public.py` (#870)
- **Node tests**: full improvements and mock cleanup (#687)

### Dependency Updates
- litellm ~1.50 → ~1.83 (#816)
- DOMPurify → 3.4.x (resolves 16 alerts / 8 GHSAs) (#886)
- cryptography pinned to 46.0.7 (#884)
- SQLAlchemy owned at ai layer, pinned ≥2.0,<2.1 (#804)
- Patched via pnpm.overrides:
  - **Routing**: react-router 6.26→6.30.3, @remix-run/router inlined (#914)
  - **Parsers**: ajv@8→≥8.18.0, markdown-it→≥14.1.1, postcss→≥8.5.10, prismjs→≥1.30.0, yaml@1→≥1.10.3 (#915)
  - **Middleware**: koa→≥2.16.4 (3 advisories), qs→≥6.14.2 (#916)
  - **Util/SVG**: svgo@2→≥2.8.1, flatted→≥3.4.2, immutable@5→≥5.1.5, underscore→≥1.13.8 (#917)
  - **Security**: picomatch@2→≥2.3.2, picomatch@4→≥4.0.4, fast-uri→≥3.1.2, serialize-javascript→≥7.0.5 (#890)
  - **Minimatch**: all 4 major lines patched (3→≥3.1.4, 5→≥5.1.8, 9→≥9.0.7, 10→≥10.2.3) (#887)
  - **Core**: undici→≥7.24.0 (6 advisories), lodash→≥4.18.0, lodash-es→≥4.18.0 (#888)
  - handlebars→≥4.7.9, protobufjs→≥7.5.5 (#783)
- Bumped: aiohttp, pygit2 1.15→1.19, soundfile 0.12→0.13, requests, ws 8.19→8.20, postcss 8.5.6→8.5.10, nltk, spacy, spacy-transformers, cymem, murmurhash, preshed, srsly, thinc, psycopg2-binary, pymysql, opensearch-py, npm-production group (adm-zip, tar, lucide-react, dockerode, web-vitals), shared-ui devDependencies (rollup, @types/react, @types/react-dom), cosign-installer, ossf/scorecard-action, gh-actions group (pnpm/action-setup, github/codeql-action, softprops/action-gh-release, dorny/paths-filter)

---

## RocketRide Python Client v1.3.0

**Python SDK** · v1.3.0 · July 7, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.3.0)

### ⚠ Breaking Changes: Client SDKs (`rocketride` / `rocketride-python`)

These changes affect code that imports and calls the Python or TypeScript client SDKs directly. The old `connect()` / `disconnect()` signatures are preserved as backward-compatible wrappers, but callers should migrate to the new layered API.

#### Connection API (both SDKs)

| Before (1.0.x) | After (1.1.0) | Notes |
|---|---|---|
| `connect(auth?, uri?, timeout?)` → `void` | `connect(credential?, { uri?, timeout? })` → `ConnectResult` | Now returns full user identity (userId, organizations, apps, teams). The `auth` param is renamed `credential` to reflect that it accepts API keys, Zitadel access tokens, and `rr_*` user tokens. Old positional `auth`/`uri` kwargs still accepted but deprecated. |
| `disconnect()` → `void` | `disconnect()` → `void` | Signature unchanged; internally calls `logout()` + `detach()`. |
| *(not available)* | `attach(uri?)` → `void` | Opens the WebSocket **without** authenticating. Required for public/unauthenticated operations like catalog browsing. |
| *(not available)* | `login(credential?)` → `ConnectResult` | Sends the DAP `auth` command over an attached transport. Supports credential rotation (auto-logout if credential differs). |
| *(not available)* | `logout()` → `void` | Sends new `deauth` DAP command, reverts the connection to unauthenticated without closing the socket. |
| *(not available)* | `detach()` → `void` | Tears down the WebSocket and cancels the reconnect engine. |
| `isConnected()` | `isConnected()` *(unchanged)* | Returns `true` only when both attached **and** authenticated. |
| *(not available)* | `isAttached()` | `true` when the WebSocket is open, regardless of auth state. |
| *(not available)* | `isAuthenticated()` | `true` when the auth handshake has succeeded on the current connection. |

**Reconnection engine rewritten**: the old flag soup (`_manualDisconnect`, `_authRejected`, `_didNotifyConnected`) is replaced by a `_desiredState` model (`'detached'` | `'attached'` | `'authenticated'`). Linear backoff (250ms increments, 15s cap) replaces exponential backoff, reconnection now **never gives up**. `maxRetryTime` is accepted for backward compatibility but **ignored**.

#### Python-specific breaking changes

- **`async with` context manager removed**: `__aenter__` / `__aexit__` are deleted. Replace `async with RocketRideClient(...) as client:` with explicit `await client.connect()` / `await client.disconnect()` in a try/finally.
- **`connect()` now returns `ConnectResult`**: previously returned `None`. Callers that did `await client.connect()` without capturing the result are unaffected; callers that typed the return as `None` will need to update.
- **`use()` no longer substitutes `${ROCKETRIDE_*}` client-side**: the raw pipeline is sent to the server, which handles all variable resolution via `get_merged_env()`. If you were relying on client-side `.env` interpolation, variables must now be set server-side (via the Variables page or `client.account.set_env()`).
- **Event type renames**: `EVENT_STATUS_UPDATE` → `EVENT_STATUS`; `EVENT_TASK` → split into `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART`. Code that imports the old names will get `ImportError`.
- **`auth` credential removed from transport layer**: `TransportWebSocket` no longer stores or exposes `auth`. Auth is exclusively managed by the `ConnectionMixin` / `RocketRideClient` layer.

#### TypeScript-specific breaking changes

- **`connect()` signature changed**: old: `connect(options?: number | { uri?, auth?, timeout? })` → `void`. New: `connect(credential?, options?: { uri?, timeout? })` → `Promise<ConnectResult>`. The `auth` property inside options is removed; pass the credential as the first argument. The numeric-only shorthand `connect(5000)` is removed.
- **`DataPipe` errors changed from `Error` to `PipeException`**: `open()`, `write()`, and `close()` now throw `PipeException` (extends `Error`) instead of plain `Error` when the server reports a failure. Callers catching `Error` are still compatible; callers matching on error message strings may need to update. `PipeException` carries the full DAP response body.
- **`setConnectionParams()` removed**: use `login(credential, { uri })` or call `attach(newUri)` + `login()` instead.
- **Project store methods removed**: `saveProject()`, `getProject()`, `deleteProject()`, `getAllProjects()` are deleted. Use the new filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`.
- **`validate()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ValidationResult` (typed interface with `valid`, `errors`, `warnings` fields).
- **`getServices()` return type changed**: previously returned `Record<string, unknown>`. Now returns `ServicesResponse` (typed interface).

#### Both SDKs: new exception types

- **`PipeException`** (Python: subclass of `RuntimeError`; TypeScript: subclass of `Error`): thrown by `DataPipe.open()`, `.write()`, `.close()` when the server reports failure. Carries the full DAP response including `message`, `body`, and error code. Replaces generic `RuntimeError` / `Error`.
- **`ConnectionException`** (TypeScript): thrown on transport-level failures.

### Added

#### New Nodes
- **Exa Search**: semantic web search node integrating with the Exa API (exa.ai) for real-time data enrichment in pipelines. Agents invoke the tool to search the web and retrieve structured results including titles, URLs, text content, relevance scores, and published dates. Includes configurable `numResults` with min/max validation, retry exception sanitization to prevent API key leakage, and defensive boolean config parsing (#386, #509)
- **Bland AI**: voice call tool node for AI-driven phone calls via the Bland AI platform (#521)
- **OpenAI Compatible**: generic LLM node supporting any OpenAI-compatible API endpoint, allowing connection to self-hosted or third-party inference servers that follow the OpenAI chat completions API (#518)
- **GMI Cloud**: LLM connector for GMI Cloud inference platform (api.gmi-serving.com) hosting 100+ models on H100/H200 GPUs. Two tiers: shared (always-on, key-only: DeepSeek, GPT, Claude, Gemini) and deploy-on-demand (endpoint URL + key: Llama 4, Qwen3). Custom profile for arbitrary model/endpoint combinations (#540)
- **Guardrails**: AI safety node with comprehensive input/output validation. Input: prompt injection detection (regex + keyword scoring), topic restriction (allowed/blocked keyword lists), input length enforcement (char + token limits). Output: hallucination detection (sentence-level grounding), content safety (self-harm, violence, illegal activity patterns), PII leak detection (email, phone, SSN, credit card, IP), format compliance (JSON, markdown, bullet/numbered lists). Policy modes: block/warn/log. Profiles: basic (injection + PII), strict (all checks), custom. 87 tests (#534)
- **Video Embedding**: extracts frames from video input (MP4, AVI, MOV, WebM) at configurable intervals and generates vector embeddings using CLIP/ViT models for semantic search and RAG pipelines. Configurable frame interval, max frames, start time, duration, and max video file size (default 500 MB) to prevent unbounded memory. VideoCapture resource leak fixed with finally block (#516)
- **Kokoro TTS**: self-contained text-to-speech node using the Kokoro engine. Slim requirements (no piper/transformers/cloud). KokoroLoader, spacy_en_model, wav_to_mp3 utilities. Supports question, answer, and document lanes (RR-411, #662)
- **Telegram Bot**: source node connecting a Telegram bot to a pipeline via long polling or webhook. Routes incoming messages to appropriate lanes by content type (text, image, audio, video, documents) and sends pipeline responses back as replies (#659)
- **GitHub Tool**: tool node for GitHub API operations (issues, PRs, repositories) with full test suite for tool calling (#640)
- **Git Tool**: self-contained Git operations using pygit2 (libgit2), no host git binary required. Capabilities: clone, init, status, log, show, diff, blame, file_at, ls_files, grep, stage, commit, stash, branch create/checkout/merge/delete, fetch, pull, push (token + SSH auth), write_file with path-traversal guard. Safe mode (default on) blocks force-push and force branch deletion. Full unit test suite + integration tests (activated via `GIT_TEST_REPO_PATH` env). Includes `git_agent_example.pipe` (#654, #731)
- **Filesystem Tool**: file system operations (read, write, list, mkdir, delete) with path whitelist security check via `_prepare()` method. Operations can be selectively enabled/disabled at the node level. Shared prologue extraction via keyword flags (path_required, needs_encoding, needs_content) (#682)
- **Pipeline Tool**: run pipelines as tool calls from other pipelines, enabling pipeline composition and hierarchical agent workflows (#647)
- **LLM Vision (Gemini)**: image understanding via Gemini models with cache management (non-symmetric cache + empty frame guard)
- **LLM Vision (OpenAI)**: image understanding via OpenAI vision models
- **Webhook**: question lane support for webhook-triggered pipelines (#431)
- **CrewAI Orchestrator**: multi-agent orchestration via CrewAI framework. Exposes expert config fields (goal, backstory, expected_output, max_iter) for both agent and orchestrator node types. Advanced mode for fine-grained control. Sub-agent config propagated through `crewai.describe()`. Manager node renamed from Orchestrator, tool invoke removed from manager (#608)

#### VS Code Extension
- **Engine management overhaul**: replaced scattered engine lifecycle code (connection/, deploy/) with a clean `EngineBackend` hierarchy under `src/engine/`. Each connection mode (local, service, docker, cloud, onprem) gets its own backend implementation. `EngineRegistry` singleton reconciler detects config changes (API key, host URL, etc.) via checksums and auto-restarts affected engines on settings save. Eliminated `engine:status` event, all progress flows through `shell:statusChange`. `ConnectionManager` becomes passive: connects on engine `ready`, disconnects on `idle`. Unified `ioControl` message pattern for all panel operations. Migration from legacy layout (`globalStorage` + `config.json`) to new structure. Welcome page uses same `applyAllSettings` + reconcile path as Settings (#922)
- **Settings overhaul & target panels**: atomic settings save via `ConfigManager.applyAllSettings()` with `isBatchApplying` flag suppressing intermediate change events (eliminates race conditions from writing 20+ config keys individually, which caused connection managers to react to half-written state). Self-contained panels per mode (Local, Cloud, OnPrem, Docker, Service) handling both configuration and operational UI (status, install/start/stop/remove/update, progress, version selection). `EngineOperations` service extracted from `PageDeployProvider`. Deploy page command redirected to Settings. `useTheme` hook for VS Code dark/light detection. Embedded Docker/Service SVG logos. Build config consolidated: `.config` as single source of truth for Zitadel URLs/client IDs, esbuild loads `.config` first then `.env` on top, stopped name remapping of Zitadel keys. Cloud mode no longer hardcodes a non-existent URL, uses `config.hostUrl` at runtime (#725)
- **Standalone Variables page**: new "Variables" webview accessible from sidebar footer for managing `ROCKETRIDE_*` environment variables per connection slot (Development/Deployment). `EnvironmentProvider` with per-slot client resolution, `EnvironmentWebview` with pill bar for slot selection. OSS servers show single "Server Variables" card; SaaS servers show Organization/Team/User cards gated by permissions. `set_env` now updates `os.environ` in-memory before writing `.env` file. Deploy connection fix: removed `isSharedMode()` guard that skipped engine status listener registration. `commonStyles.tabContent` now uses `border-box` sizing. Removed capabilities filter that hid Cloud option. All "Environment" labels renamed to "Variables"
- **`${ROCKETRIDE_*}` variable autocomplete**: node config fields now offer autocomplete suggestions for defined pipeline variables. `useEnvVarAutocomplete` hook detects `${` trigger and filters keys by partial match. `EnvVarSuggestions` popover with arrow-key navigation. Wired into `BaseInputTemplate`, `TextareaWidget`, and `ApiKeyWidget`. `transformErrors` suppresses RJSF validation errors for fields containing `${ROCKETRIDE_*}`. `rrext_validate` now resolves env vars before validation using the same merged env as pipeline execution. Fixed `getHttpUrl()` to normalize engineUri before parsing
- **Category headers in QuickAddPopup**: compatible services grouped by bold uppercase category headers with indented items. Shared `CATEGORY_TITLES` extracted to `categoryTitles.ts`. `CreateNodePanel` auto-expands matching categories during search, restores previous expand/collapse state when search is cleared. Environment protocol types extracted to prevent build errors
- **Server Monitor panel**: real-time dashboard showing connections, tasks, and aggregate metrics via new `getDashboard()` / `get_dashboard()` SDK methods (DAP `rrext_dashboard` command). Client identification (`clientName`/`clientVersion`) forwarded during auth handshake so server can distinguish "VS Code 0.9.4" vs "CLI 1.2.0". Python DAP client skips auth message when transport lacks `get_auth()` (fixes crash for non-WebSocket transports). Consolidated `ServicePython` log level into `DebugOut` (#595)
- **Other task viewer via ProjectWebview**: `PageStatusProvider` completely rewritten. Previously opened a lightweight `StatusWebview` that couldn't show the node graph (nodes squashed at top, no toolbar, missing servicesJson). Now fetches unresolved pipeline via `getTaskToken` + `getTaskPipeline`, creates panel using the full Canvas/ProjectView stack, sends `project:load` with `isReadonly:true`. Falls back to synthesized single-node project if fetch fails. `StatusWebview` deleted (#803)
- **Readonly canvas**: single `isReadonly` prop replaces two inconsistent lock mechanisms (14-boolean `IFlowFeatures` and partially-implemented `isLocked`). `effectiveLock = isReadonly || internalIsLocked`. Guards added to `addNode()`, `updateNode()`, `deleteNode()`, paste, context-menu, lane click, config panel Save, all previously unguarded. Lock button hidden when `isReadonly` (#803)
- **Save button in canvas toolbar**: always-visible floppy disk icon with dirty-state tracking; grayed when clean, brand-colored when dirty. `isDirty`/`isNew`/`onSave` threaded through `IFlowProps` → `FlowContainer` → `FlowProvider` → `FlowProjectProvider`. `FlowCanvas` defers ReactFlow render until container has non-zero dimensions via `ResizeObserver`. `canvas:requestSave` calls `document.save()` directly (#678)
- **Dirty-state save pattern for settings**: card header starts clean (no buttons); on edit, Cancel and Save appear; on save, buttons disappear and "Saved" flashes for 5 seconds then fades; Cancel reverts to last-saved snapshot. Applied to all 5 VS Code settings tabs and shell-ui settings page (#877)
- **Play button shows actionable text**: renamed idle label from "Play" to "Run Pipeline". Added STOPPING state with "Stopping..." disabled button to prevent double-clicks. Widened hover expansion for longer label. Smooth CSS transitions with easing functions (#575)
- **Improved stop button feedback**: Pipeline Observability screen handles `TASK_STATE.STOPPING` with "Stopping..." disabled state and distinct orange styling, preventing duplicate clicks (#549)
- **Simplified sidebar footer**: replaced popup menu (three redundant gear icons all opening Settings) with flat layout when connection is shared and no cloud account. Documentation and Settings buttons rendered directly, connection status inline, announcements ticker rotates cards every 7 seconds. Full popup preserved for cloud account or independent connections. Panel sash restyled with native `--vscode-sash-hoverBorder` token, widened from 2px to 4px
- **Test Connection button**: available on service/docker/onprem panels via `ioControl('test')`
- **Docker GHCR tag fetching**: global cache for prerelease resolution with 15s timeout on HTTPS requests. Split-button dropdowns with grouped "Recommended" / "All versions" headers. Version metadata persisted per instance lifecycle. Linux package manager auto-detection (apt/dnf/yum/pacman) instead of hardcoded apt-get
- **Version tracking**: persistent `version.local.json`, `version.service.json`, `version.docker.json` files. PID liveness check before preserving `.pid` files during engine dir clear. Guard against phantom installs (missing binary). UAC-cancel fallback and uninstall.ps1 fixes
- **Event naming unification**: all connection events renamed to `shell:*` namespace matching cloud-ui vocabulary. `'event'` → `'shell:event'`, `'connected'` → `'shell:connected'`, `'connectionStateChanged'` → `'shell:statusChange'`, etc. All 10 providers renamed to drop redundant `Page` prefix. All 9 view directories renamed similarly (#803)
- **`.env` file management removed**: ~350 lines of env file handling removed from `ConfigManager` (envFileWatcher, envRawText, parseEnvFile, saveEnvFile, syncSettingsToEnv, etc.). Environment variables for pipeline variable replacement are now managed server-side (layered env in DB). Extension no longer maintains workspace `.env` file. URL resolution consolidated into `ConnectionManager` (per-group, not hardcoded to dev group) (#803)
- **On-demand env loading**: replaced 7 env-specific `AccountView` props with 2 generic callbacks (`onLoadEnv`, `onSaveEnv`) plus `refreshSignal`. Each `EnvScopeCard` requests its own data on mount. Promise-based messaging with 10s timeout. `shell:accountUpdate` as first-class event (no longer filtered from generic stream). Standalone `BillingProvider` deleted; billing is a tab inside Account (#803)
- **Welcome page simplification**: `welcomeDismissed` set automatically on save (no manual checkbox). Works from both Welcome and Settings pages (#803)

#### Shell UI (Web Host)
- **Shell-ui replaces cloud-ui**: new Module Federation host application served by Python `shell` module (`ai.modules.shell`) with public HTTP routes for SPA and all static assets under `/shell/`. Unifies OSS and SaaS into single codebase. Server-side app manifest delivery via `get_public_apps()` / `get_apps_for_user()` on AccountBase. Pre-auth info probe returns public apps for marketplace. Connect response includes authenticated user's full entitled app list (#803)
- **MUI removal**: replaced Material UI with plain CSS/HTML across entire shared-ui package; runtime theme system with light/dark JSON tokens
- **Theme rebrand**: replaced legacy purple (#5900FF) with cyan (#00b9ec) TOKENS palette. Light theme updated to warm-neutral (cream/stone backgrounds instead of pure white) (#803)
- **Theme flash fix**: `index.html` inline script sets `--rr-bg-default` and body background synchronously before React renders. `createShellConfig` reads saved theme from localStorage instead of always defaulting to rocketride-light, eliminating tan background during 1.5s OAuth code-exchange window (#878)
- **Chat module**: host-agnostic chat surface following established module pattern (props-in, callbacks-out, `--rr-*` CSS tokens). `ChatView` (MessageList + ChatInputField), `MessageBubble` (user/bot/system/status with markdown), `MarkdownRenderer` (react-markdown + GFM + syntax highlighting + charts), `ChartRenderer` (chart.js with circular-reference guard), `TypingIndicator` (animated bouncing dots), `useChatMessages` hook (message state + sendMessage + monotonic IDs) (#724)
- **Canvas state persistence**: viewport (zoom/pan), lock state, snap-to-grid, and editor mode now persist in `.pipe` files via `PipelineConfig` schema (TypeScript + Python SDKs). New `isFlowReady` boolean state tracks when all nodes have been rendered/measured by ReactFlow, replacing scattered `setTimeout`/`requestAnimationFrame` workarounds. Centralized `loadCanvas(nodes, edges)` as single entry point for structural canvas changes. Viewport restored on load via `isFlowReady` cycle, falls back to fitView. Spiral search for non-overlapping node placement. `EmptyCanvasPrompt` only shown when `nodes.length === 0 AND isFlowReady` (#670)
- **ProjectView architecture**: decomposed monolithic `modules/flow/` canvas module into composable multi-view project architecture (#670)
- **Style consolidation**: added `buttonPrimarySmall`, `buttonSecondarySmall`, `buttonDangerSmall`, `modalDialog`, `modalHeader`, `modalBody`, `modalFooter` to `commonStyles`. Added `cardHeaderButton`/`cardBodyButton` size modifiers for card contexts. Eliminated `Btn` wrapper component. Account `shared.tsx` trimmed from ~30 to 9 entries. All emojis removed from account UI (#803)
- **Shared connection types**: `ConnectionState` enum, `ConnectionMode`, `IAuthProvider`, `IConnectionManager` interface, `ShellAppEntry`, `ShellConnectionEventMap` with typed payloads for all `shell:*` events. Index signature for app-defined events (#803)

#### Billing, Account & Auth
- **Billing detail**: `BillingDetail` type gains `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart` in both SDKs. Subscription cards show detail grid with plan info. Cancel subscription requires confirmation modal. App display name shown instead of raw appId. Credit grant summary per subscription using `creditLabels` from Stripe metadata (#803)
- **Account/Billing merge**: Billing is now a tab inside Account (2nd pill) via `BillingPanel`. Standalone Billing page and provider deleted
- **Permission enforcement**: frontend computes `isOrgAdmin`/`isTeamAdmin` from profile; action buttons hidden for users without required permissions; `OrganizationPanel` read-only for non-admins; destructive actions go through confirmation modals. Team admin enforcement: must always have ≥1 admin (UI + server guard). Permission key fixed: `'admin'` → `'team.admin'`. `_require_team_admin` queries DB directly instead of stale cache (#803)
- **Team-based task permissions**: replaced all `control.userId == caller.userId` ownership checks with `resolve_task_permissions()` so teammates and org admins can monitor/control each other's tasks. Permission strings (e.g. `'task.control'`, `'task.monitor'`) checked against resolved list (#803)
- **Layered environment secrets**: pipeline variables (`ROCKETRIDE_*`) stored encrypted (Fernet) in database per org/team/user scope, merged server-side during task execution. Merge order: `.env` → org → team → user → caller env. `get_merged_env()` on `AccountBase` with OSS (`.env` only) and SaaS (DB) implementations. `client.use()` `env` param for caller overrides (only `ROCKETRIDE_*` accepted). Client-side `processEnvSubstitution` removed, resolution is server-only (#803)
- **Session keys**: API keys are now true PATs inheriting user identity. `is_session` flag on `ApiKey` model. `ensure_session_key()` on every OAuth login: refreshes 90-day expiry if active, creates fresh key if expired/missing. Session keys cannot be self-revoked. Admin revoke is hard-delete. Housekeeping: keys revoked >30d purged on login. UI shows "Session" / "Interactive login" badge (#803)
- **Scoped PATs**: PATs optionally restricted to single team with explicit permissions. Effective permissions intersected with user's actual permissions at auth time (can never escalate). Optional `team_id` on `ApiKey`. Create key modal: team dropdown + conditional `PermGrid`. Key list shows team scope badge (#803)
- **userToken → userId refactor**: server-side event tenant scoping uses `userId` instead of `userToken`. Fixes bug where two connections from same user with different keys wouldn't see each other's dashboard events (#803)
- **Account UI overhaul**: all card headers use `commonStyles.labelUppercase`. Save button pattern: hidden until dirty, shows [Cancel][Save], "Saved" green text with 5s timer. `ProfilePanel`: single "Organizations / Workspaces" card with nested teams. `TeamsPanel`: Delete moved to list with confirm modal. `PermGrid`: `PERM_DISPLAY` labels, alphabetized, added `task.store`, contrasting text on checked tiles (#803)
- **Client SDK attach/login split**: replace monolithic `connect()`/`disconnect()` with layered API: `attach(uri?)` opens WebSocket without auth (for public APIs like catalog), `login(credential?)` sends DAP auth, `logout()` sends new `deauth` command (reverts to unauthenticated without closing socket), `detach()` tears down WebSocket. Old `connect()`/`disconnect()` preserved as backward-compatible wrappers. Reconnection engine rewritten around `_desiredState` model ('detached' | 'attached' | 'authenticated'). Linear backoff (250ms increments, 15s cap), reconnection never gives up. Auth credential removed from transport layer (#803)
- **Server-driven appStatus**: replaced `subscriptionStatus` with server-computed `appStatus` ('auth' | 'free' | 'unsubscribed' | 'subscribed' | 'trialing' | 'past_due' | 'canceled') and `onDesktop` boolean per app manifest entry. Eliminates client-side reconciliation races (#803)
- **App mode & subscription gating**: `mode` field (free/subscription/paywall) in app manifests. Shell-level subscription gate blocks app iframe until active subscription exists. Desktop app management moved into account identity flow (#803)
- **Token storage hardened**: moved from `localStorage` to `sessionStorage` (cleared when tab closes) addressing CodeQL "Clear text storage of sensitive information" alert (#803)

#### Profiler
- **DAP-based cProfile system**: replaced HTTP-endpoint profiler module with per-process cProfile profiling over DAP connections. Any connected client can profile any process (task server, data engine subprocesses, model server). `CProfileManager` singleton with start/stop/status/report/release API. Owner tracking per connection with disconnect cleanup. SDK methods: `cprofileStart`/`cprofileStop`/`cprofileStatus`/`cprofileReport` (TS + Python) with optional `target` parameter for pipeline profiling. New `profiler-ui` Module Federation remote app with `ProfilerView`, `ConnectionManagerView`, and `ProfilerSidebar` (#803)

#### Module Federation
- **MF stability**: added `runtime: false` to all remote apps (shell-ui provides shared runtime; without it each remote embeds its own runtime copy, causing remoteEntry.js to change on every rebuild and version-mismatch errors during HMR). Added `eager: true` to react/react-dom shared configs (breaks async shared-scope negotiation deadlock where host waits for remote's async chunk and remote waits for host). App loader filters out server-only entries with no `remoteEntry` URL (prevents `normalizeRemote()` crash on `undefined`) (#877)

#### Engine & Core
- **Database EXECUTE**: direct SQL/Cypher execution via `QuestionType.EXECUTE` with `client.database.query()` namespace on both SDKs, bypassing LLM translation and safety gating. Gated behind opt-in `allow_execute` config (default off). Results bounded with `fetchmany(max_execute_rows+1)` (default 25000). Neo4j results capped at same limit. `allow_execute` parses strings strictly: only `'1'`, `'true'`, `'yes'`, `'on'` (case-insensitive). EXECUTE output wrapped in try/except; serialized with `default=str`. SDK validates non-empty token/sql before dispatching
- **Database DIALECT**: `QuestionType.DIALECT` for engine capability discovery. SDK callers can ask which engine a database pipeline is connected to (`DatabaseDialect` enum). `_db_dialect()` abstract method on `DatabaseInstanceBase`. `services.json` now exposes UI-toggleable `allow_execute` boolean
- **Handle-based streaming I/O**: generic filesystem-style interface (`open`/`read`/`write`/`close`/`delete`/`stat`/`mkdir`/`list_dir`) on `FileStore`, replacing monolithic in-memory buffering. Domain methods become thin convenience wrappers on client SDKs. Supports S3 multipart upload (5 MB buffer), Azure staged blocks (4 MB buffer), and local filesystem. Handles tagged with owning `connection_id` and force-closed on connection termination (#600)
- **`@tool_function` decorators**: collapsed the two-class pattern (IInstance + ToolsBase driver) into a single class. Any `IInstanceBase` subclass can declare tool entry points with a decorator; the method name becomes the tool ID, decorator carries schema/description, base class `invoke()` dispatches automatically. Eliminates parallel driver classes, factory methods, and boilerplate delegation (#599)
- **Experimental + Deprecated capability flags**: `DEPRECATED = BIT(15)`, `EXPERIMENTAL = BIT(16)` in `PROTOCOL_CAPS`. Both flags wired through C++ parser, pybind11 bindings, both client SDKs, and shared-ui. Yellow "EXPERIMENTAL" badge rendered on canvas nodes, Add Node slider, and Quick Add popup (#606)
- **Docker-compose and healthcheck**: `HEALTHCHECK` instruction in `Dockerfile.engine` using curl to `/ping`. `docker-compose.yml` with engine, PostgreSQL+pgvector, Milvus (+ etcd, MinIO), ChromaDB. Override file for dev hot-reloading. All images pinned to specific versions. Security warnings in `.env.example` (#496)
- **Billing commands mixin**: `BillingCommands` in TaskConn's MRO for `rrext_account_billing`. OSS implementation routes on `arguments.subcommand` with stubs so UI doesn't hang in half-rendered state (#692)
- **Task engine extraction**: `task_engine` and `cmd_data` extracted as standalone modules (#661)
- **GPU inference billing**: `metrics.resource('gpu')` context manager times inference. `CONST_RATE_GPU_INFERENCE_SECOND` for billing. Custom node counters (`pagesProcessed`, etc.) with configurable rates. All 9 AI model files wrapped with `metrics.counter('gpu_inference_count')` + `metrics.resource('gpu')`. Billing reports include `gpu_inference` and `custom` token fields (#803)
- **Metrics rewrite**: replaced Timer class and `resource()` context manager with flat `MetricsManager`: `timer()`, `add_time()`, `counter()`, `event()`. Thread-safe via single lock. Removed per-pipe `ContextVar`, metrics are per-subprocess. ModelClient auto-records server-reported perf dict (#803)
- **ModelClient refactor**: derived from `RocketRideClient` with `ws_path='/models'` so URI normalization, protocol selection, and auth are handled by SDK. Python SDK gains `ws_path` kwarg. Sync `disconnect()` override for worker thread callers. All 9 model wrappers updated. `get_model_server_address()` simplified to return raw string (#877)
- **Model server DAP namespace**: all model server commands renamed to `rrext_ms_*` prefix (load_model → rrext_ms_load_model, etc.) for disambiguation from core DAP commands (#803)
- **GPU guard**: `install_gpu_guard()` blocks direct torch/tensorflow imports in model server mode; all GPU inference must go through ModelClient RPC (#803)
- **Pipeline error surfacing**: `binder.cpp` sets `completionCode` on Entry when `callMethods` encounters error. `bindings.cpp` exposes `completionError` read-only property. `data_conn.py` rewrites `close_sync()` to always extract results even when end/close throws, surfaces `Entry.completionError` when `objectFailed` is True. Errors now reach dropper UI (#803)
- **`rrext_get_pipeline` DAP command**: returns task's unresolved pipeline (with `${...}` placeholders intact) so VS Code can reconstruct node graph without exposing secrets. `_build_task()` now accepts explicit resolved pipeline, `self._pipeline` retains original unresolved form (#803)

#### Client SDKs: New Features

**Layered connection API (both SDKs):**
- `attach()` / `detach()`: open/close the WebSocket without authentication. Enables unauthenticated operations (public catalog browsing, server probes) before the user logs in
- `login()` / `logout()`: authenticate/deauthenticate over an attached transport. `login()` returns `ConnectResult` with full user identity (userId, organizations, apps, teams, permissions). `logout()` sends new `deauth` DAP command, reverting to unauthenticated without closing the socket. Supports credential rotation (auto-logout if a different credential is supplied)
- `connect()` / `disconnect()` preserved as backward-compatible wrappers (`attach` + `login` / `logout` + `detach`), but `connect()` now returns `ConnectResult` instead of void
- `isAttached()`: true when WebSocket is open (regardless of auth)
- `isAuthenticated()`: true when auth handshake has succeeded

**Namespaced API accessors (both SDKs):**
- `client.account`: profile, API keys, org, members, teams, environment variables (`get_env()` / `set_env()` / `get_environment_keys()`)
- `client.billing`: subscriptions, checkout, credits, cancel
- `client.database`: `client.database.query()` for direct SQL/Cypher execution; `client.database.dialect()` for engine discovery (`DatabaseDialect` enum)

**New methods:**
- `RocketRideClient.getServerInfo(uri)` (static): probe a server for capabilities without authenticating. Returns `ServerInfoResult` with version, capabilities, platform, and public apps
- `getTaskToken(projectId, source)`: resolve a running task's session token
- `getTaskPipeline(token)`: retrieve the unresolved pipeline for a running task (placeholders intact, no secrets)
- `getDashboard()`: real-time server dashboard (connections, tasks, metrics)
- `cprofileStart/Stop/Status/Report`: per-process cProfile profiling over DAP
- `call(command, token?, **kwargs)` (Python): single public entry point for all typed DAP operations with optional `on_trace` callback

**TypeScript-specific additions:**
- `wsPath` config option for custom WebSocket paths (e.g. `'/models'` for model server)
- `onTrace` callback for observing all `call()` traffic
- `MonitorKey` type and `addMonitor()` / `removeMonitor()` for reference-counted monitor subscriptions
- `restart()` method for restarting pipeline tasks
- Filesystem API: `fsOpen()`, `fsRead()`, `fsWrite()`, `fsClose()`, `fsDelete()`, `fsListDir()`, `fsMkdir()`, `fsRmdir()`, `fsStat()`, `fsRename()`, `fsReadString()`, `fsWriteString()`, `fsReadJson()`, `fsWriteJson()`: replaces the old project store methods
- `getTaskStatus()` applies default 15s timeout (configurable via `options.timeout` or `{ timeout: false }`)
- `validate()` now returns typed `ValidationResult` (was `Record<string, unknown>`)
- `getServices()` now returns typed `ServicesResponse`; `getService()` returns `ServiceDefinition`
- `DataPipe.open()` sets `_opened` only after successful SSE setup with rollback on failure
- `normalizeUri()` preserves user-specified port (was being stripped for scheme-default ports like :443)

**Python-specific additions:**
- `ws_path` kwarg for custom WebSocket paths
- `client_name` / `client_version` kwargs forwarded in auth handshake for client identification
- `on_trace` callback for observing all `call()` traffic
- `public` mode for permanently unauthenticated connections (only `rrext_public_*` commands)
- `DashboardMixin`, `CProfileMixin`, `StoreMixin` added to MRO
- Improved `send()` pipe error context with `PipeException` (catchable as `RuntimeError`)

**New types (both SDKs):**
- `ConnectResult`, `ServerInfoResult`, `AppManifestEntry`, `StripePriceEntry`
- `AccountProfile`, `AccountOrganization`, `AccountOrgTeam`, `ApiKeyRecord`, `OrgDetail`, `MemberRecord`, `TeamRecord`, `TeamDetail`, `TeamMemberRecord`
- `BillingDetail` (extended with `planNickname`, `unitAmount`, `billingInterval`, `currentPeriodStart`, `credits`, `creditLabels`), `StripePlan`, `CreditBalance` (extended with `labels`), `CreditPack`
- `PROTOCOL_CAPS` enum with all 17 capability flags
- `SERVICE_DEFINITION`, `SERVICES_RESPONSE`, `VALIDATION_ERROR`, `VALIDATION_RESULT`
- `DASHBOARD_OVERVIEW`, `DASHBOARD_MONITOR`, `DASHBOARD_CONNECTION`, `DASHBOARD_TASK`, `DASHBOARD_RESPONSE`, `DASHBOARD_EVENT` and 7 event subtypes
- `TASK_EVENT`, `TASK_EVENT_FLOW`, `TASK_EVENT_RUNNING`, `TASK_EVENT_BEGIN`, `TASK_EVENT_END`, `TASK_EVENT_RESTART` (replace old `EVENT_TASK`)
- `EVENT_STATUS` (replaces `EVENT_STATUS_UPDATE`)
- `TASK_TOKENS` extended with `gpu_inference` and `custom` fields
- `CreateKeyParams` accepts optional `teamId` for scoped PATs
- `EVENT_TYPE.DASHBOARD` flag (bit 7) for server-level events; `EVENT_TYPE.ALL` updated to include it
- **Config**: `Config.getNodeConfig()` emits warnings for deprecated profiles with migration guidance from profile's `migration` field

#### MCP
- **MCP Resources and Prompts**: `rocketride://` URI resources (pipeline list, server status, node registry) with graceful error handling for disconnected clients. Three prompt templates (analyze-document, chat-with-data, evaluate-pipeline) with required argument validation and message rendering. 44 tests (#541)

#### Agents & Pipelines
- **Agent framework overhaul**: ProjectView architecture with shared-ui migration (#670)
- **Example pipeline templates** for common AI workflows (#572)

#### Build System
- **Rsbuild upgrade**: all UI apps upgraded from pinned 0.4/1.1 to ~1.7.5, eliminating Node.js `DEP0180` deprecation warnings in Node 22+. ESM config migration (`.ts` → `.mts`). cmake minimum bumped from 3.14 to 3.19. `@rspack/binding-*` platform pins removed. Service config renamed `config.json` → `service-config.json` with migration (#905)
- **Build-input caching**: source fingerprinting (`buildInputHash()` + `hasBuildInputChanged()`) skips UI modules whose inputs haven't changed. `appModule.js` factory eliminates ~80 lines of boilerplate per app. Shell-ui tracks own src/ + shared-ui/src + package.json. `--force` flag bypasses caching. Clean actions clear cached hashes (#877)
- **Builder CLI**: `server:run` action (build + run without shell-ui dev server). `--taskserver=ADDR` replaces `--testport`. `--modelserver` semantics clarified (bare flag = start local, `=ADDR` = use existing). `--simulate-gpus=N` forwarded to model server. `parseServerAddress()` utility (#803, #877)

#### CI/CD
- **Cosign container signing**: keyless signing of rocketride-engine image via Sigstore + GitHub OIDC (signs by digest). GPG detached-signature step for server tarballs/zips, gated on `GPG_SIGNING_KEY` secret (#798)
- **Dependabot**: weekly version updates with smoke tests for litellm and pipeline-node deps. Blocked rsbuild/rslib/rspack 0.x churn and pip major bumps. Semver-major ignores across all 10+ ecosystems (#788, #843, #842, #862)
- **Experimental-release workflow**: `workflow_dispatch`-only, builds from arbitrary branch under configurable tag suffix. Per-product release jobs. No marketplace publishing. `prerelease: true`. First use case: workshop builds (#848)
- **Nightly prereleases**: initially from stage branch (#631), moved to develop on green CI (#713). `workflow_dispatch` expanded to develop/stage/main (#906)
- **Daily Actions storage cleanup** workflow (#636)
- **Discord notifications**: PRs, issues, discussions with live CI check status and PR state tracking in embed (#612, #614, #638). Duplicate posts on discussion edits prevented (#698). Retry/backoff for webhook calls (#797)
- **Ruff and gitleaks**: pre-commit checks (#722); gitleaks made blocking (#681); `ruff format` applied to all Python files (#723)
- **Sequential builder tests** to isolate cross-suite flakes (#734)
- **cmake 4** support (#807)
- **Actions pinned** to immutable commit hashes (#483)
- **Artifact retention** dropped to 1 day for 0.5 GB storage cap (#779)
- **CodeQL** switched from advanced to default setup (#768)

#### Documentation
- **Observability & tracing**: integration guide documenting how external services consume runtime logs, lifecycle events, and pipeline traces over the WebSocket DAP channel. Wired into all agent stubs (Claude Code, Cursor, Windsurf, Copilot) (#716)
- **Node usage guides**: `db_neo4j` with practical examples (#490), `llm_openai` with provider examples (#493), source connectors (#650)
- **Per-node documentation** overhaul, added and updated docs for each node (#639, #660)
- **Engine**: Tika ExternalParser media tool requirements (#729)
- **Python client**: clarified `send()` sources and `.pipe` usage (#705); updated Python 3.8 → 3.10 references (#657); added `.env.example` (#492)
- **Contributing**: require green CI checks before review (#627)
- **SOC2-ready SECURITY.md**: explicit triage/remediation SLA (critical 7d, high 30d, medium 90d), scanning toolchain documentation (CodeQL, Scorecard, Trivy, Dependabot, secret scanning), quarterly access reviews (#762)
- **Two-person control** on alert dismissals documented (#800)
- **Code of Conduct** (#591)
- **README improvements**: onboarding wording, absolute image URLs, GIFs, Product Hunt badge (#706, #506, #478, #590)

#### Security Policies
- **Workflow permissions**: top-level permissions added to 5 reusable workflows (#790); storage-cleanup narrowed to job-level (#794)
- **Stale lockfile removed**: `packages/client-typescript/pnpm-lock.yaml` deleted, override declared in root (#796)

### Changed

- **LLM provider migration**: all LLM providers migrated to `ai.common.LLMBase` (#719); automated LLM model sync tool fetches models from provider APIs, smoke-tests new ones, merges into `services.json` with smart deprecation and three-source token limit resolution (provider API → OpenRouter → LiteLLM). `modelSource` field tracks discovery origin. Weekly CI workflow opens PR with sync report. `builder models:update` command (#651)
- **llm_gemini model profiles**: added `gemini-3.1-pro-preview`, `gemini-3.1-flash-image-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-3-pro-image-preview`; standardized `gemini-2.5-*` dot notation; deprecated profiles retained with migration guidance
- **Removed `llm_vertex` node**: Vertex AI now supported via `llm_gemini`; migrated vision nodes to `LLMBase`; fixed `llm_gemini` API key validation (dropped strict `startsWith('AI')` check, added sub-key fallback for old pipe files where sub-key is `profile.split('_',1)[1]`); fixed `validateConfig` to early-return when apikey is empty (secure fields not decrypted at validate time); removed vertex icon from UI; bumped client-typescript SDK to 1.1.0 (#902)
- **OpenAI models** updated to latest (#503); deprecated Gemini models removed (#500)
- **Service config cleanup**: removed obsolete `input` section from 72 service configuration files (was duplicate of lane declaration, closes #629) (#728)
- **Milvus node**: configurable timeout (default 60s, was hardcoded 20), connection error handling with meaningful messages, bulk insert with configurable batch size (default 50, was one-at-a-time), `_batchUpsertResults()` helper for markDeleted/markActive, timeout on `remove()`, COSINE distance score range [0,2] rescaling documented (#562)
- **Node tests parallelized** with pytest-xdist (#700)
- **Tool input helpers**: `normalize_tool_input()` replaces 4 copy-pasted variants across tool nodes. `require_str`/`require_int`/`optional_str` replace local validators (44 callsites in `tool_github`). `require_str` now raises `ValueError` cleanly on non-string inputs (was `AttributeError`). `require_int` rejects `bool` (an `int` subclass). 41 unit tests (#759, #766)
- **Backward-compat DAP token fallback**: `get_task_token()` checks `arguments.token` first, falls back to `request.token` for older clients (#902)
- **pnpm** pinned via `packageManager` field (#623)
- **Version bump**: all release packages bumped to next minor (server 3.1.2 → 3.2.0, chat/dropper-ui 2.0.1 → 2.1.0, all others 1.0.x → 1.1.0)
- **engines.node** bumped from ≥18.0.0 to ≥20.0.0 (aligns with serialize-javascript@7 requirement and CI reality)
- **Provisioning**: creates Development + Production teams (Production default); `build_api_key` uses random nonce
- **VSCode detection**: chat-ui/dropper-ui changed from `window.parent !== window` to checking for `acquireVsCodeApi` (canonical detection)
- **Lefthook**: sequential mode; disabled colors to fix terminal corruption on Windows

### Fixed

#### Security
- **Critical: RCE**: prevent arbitrary module injection via `/use` endpoint. Added `ALLOWED_MODULES` frozenset whitelist restricting dynamic imports to 10 known service modules. Requests for any other module return 400 (#342)
- **Critical: Injection**: prevent filter expression injection in Milvus vector store (#355)
- **Auth**: require authentication for profiler endpoints; escape HTML output (#362)
- **Env expansion**: restrict `${VAR}` expansion in pipeline configs to allowlisted prefixes (`ROCKETRIDE_`, `PIPELINE_`, `NODE_`, `ROCKET_`); all others replaced with `<REDACTED>` to prevent exfiltration of AWS keys, DB URLs, tokens (#359)
- **Temp files**: use secure temporary file creation in task engine (#356)
- **SQL safety**: switch from blacklist to allowlist approach (#577)
- **Path traversal**: use `pathlib.is_relative_to` checks (#580)
- **Redaction**: expand sensitive field redaction patterns in VS Code logger (#578)
- **Input validation**: add validation/sanitization to LLM chat drivers (#559)
- **Rate limiting**: add rate limiting to `tool_http_request` node (#560)
- **Remote nodes**: improve error handling in remote node execution (#565)
- **Pinned deps**: handlebars + protobufjs via pnpm.overrides (#783)

#### Client SDKs: Fixes
- **Python client**: break drain cycle causing `RecursionError` on disconnect, `_drain_message_tasks` walks each candidate's `_fut_waiter` chain and excludes tasks that transitively await the drainer itself, so the gather can never close back on itself. `dap_client.request()`'s `ConnectionError` handler now uses fire-and-forget `self._transport.disconnect()` instead of `await self.disconnect()` (develop's `disconnect()` is sync-returns-Task). Two regression tests pinning each fix (#792)
- **Python client**: clean pending DAP request on send failure, prevents zombie futures accumulating on flaky connections when the WebSocket drops mid-request (#736)
- **Python client**: align `requires-python` with monorepo target (py310), was still declaring py38 (#491)
- **Python client**: `set_env` now updates `os.environ` in-memory (removes stale `ROCKETRIDE_*` keys, then sets new values) before writing the `.env` file, so `get_env` reflects changes immediately without a server restart. Uses `sys.executable` instead of `sys.argv[0]` for the `.env` file location
- **Python client**: `ws_path` composition uses `parsed._replace` instead of string concatenation to avoid malformed URIs
- **Python client**: popped consumed kwargs (`ws_path`, `client_name`, `env`, etc.) before passing to `super().__init__()` to avoid "multiple values for keyword argument" `TypeError`
- **TypeScript client**: preserve user-specified port in `normalizeUri`, the URL API silently strips scheme-default ports (:443 on https, :80 on http); now checks raw input for explicit `:digits` after the scheme before deciding whether to add default port (#377)
- **TypeScript client**: `DataPipe.open()` sets `_opened` only after successful SSE setup; on `setEvents` failure, rolls back via `close()` so the server pipe is not left half-open. `close()` now also handles the case where server assigned `pipe_id` but `_opened` was never set to true (#704)
- **TypeScript client**: `DataPipe.close()` sets `_opened = false` in the finally block, preventing double-close races
- **TypeScript client**: `connect()` treats empty or whitespace-only `ROCKETRIDE_APIKEY` in the client env snapshot as **unset**, so it does not override constructor-provided auth (#704)
- **TypeScript client**: `getTaskStatus` applies a default per-request timeout of 15s so CI doesn't hang indefinitely on a dead task; callers can pass `options.timeout` (ms) or `{ timeout: false }` to skip (#704)
- **Both clients**: pipe error messages now include common-cause diagnostics (pipeline not running, wrong source type, MIME mismatch) to reduce debugging time
- **SDK connect error callback type** corrected, was typed incorrectly in the TypeScript client (#576)
- **`CreditBalance` type** aligned with backend camelCase wire shape (#714)

#### VS Code Extension
- **Chat webview blank screen**: realigned `view:ready` handshake so chat panel renders after extension reload (#688)
- **Explorer empty-state**: clicking +File/+Folder on empty PIPELINES tree was silent no-op (input row gated on `entries.length > 0`). Now renders input when root-level create is pending. Stale `selectedPath` falls through to root when all entries deleted (#901)
- **Annotation double-click**: annotation nodes advertised "Double-click gear to add content..." but gear was hidden until hover (CSS opacity:0→1), opened on single-click not double-click, and body had no `onDoubleClick`. Added `onDoubleClick` on annotation root, updated placeholder text (#901)
- **Team selector**: cloud team selector not appearing after sign-in because team fetching was embedded inside cached `probeServerInfo()`. Decoupled into separate `fetchCloudTeams()` driven by `useEffect([isSaas, cloudSignedIn])` (#877)
- **Billing app names**: subscription cards showing raw `appId` instead of human-readable name. Added full `apps` manifest prop chain so components build own `appId → app` lookup map (#877)
- **Canvas-played pipelines** now register in sidebar menu (#571)
- **Missing hostname** handled in URI parsing (#530)
- **OSX Python path** for Python-EaaS debugger (#693)
- **Dark mode**: fixed icon and edge visibility in flow builder (#597)
- **UI validation** fixes (#767)
- **Icons and coloring** for Bland, GMI, and trash bin (#634)
- **QuickAdd popup** label copy improved (#679)
- **Product Hunt badge**: converted SVG to PNG (marketplace rejects SVGs)

#### Engine & Nodes
- **LLM**: clear correct `_chat` reference in `endGlobal` across all LLM nodes (#531)
- **Milvus**: apply `retrieval_score_threshold` filter in `searchSemantic` (#726)
- **Database**: bound Neo4j EXECUTE rows; parse `allow_execute` strictly (only '1'/'true'/'yes'/'on')
- **Frame grabber**: user-configured interval was being ignored (#675)
- **Pipeline configs**: error handling for missing configuration files (#544)
- **Mutable defaults**: replaced mutable default arguments with `None` across Python nodes (#582)
- **Chunk scoping**: `_processFullTables` used stale `doc` variable from outer loop and called `Doc()` with invalid constructor params. Fixed to reset `page_content` on chunk itself. Follow-up: fixed score assignment that replaced Doc with float, and first-chunk aliasing that dropped text (#776)
- **Mock truthiness**: `psycopg2`: `isinstance(False, int)` is True, so `isDeleted=False` was matched as LIMIT value (added `not isinstance(p, bool)` guard). `chromadb`: `if limit and ...` treated `limit=0` as falsy (changed to `limit is not None`). `weaviate`: `distance if distance else 1.0` collapsed 0.0 (exact match) to 1.0 (changed to `distance is not None`) (#748)
- **Async safety**: `_message_tasks` set accessed from multiple async contexts without a lock (#535)
- **CLI shutdown**: SIGINT/SIGTERM handlers with proper exit codes (130/143), double-signal force exit, 5s cleanup timeout, idempotent `cleanupClient` via dedup promise, `isCancelled` guards on command actions, `run()`/`main()` shutdown awareness via `awaitShutdown()` (RR-655, #891)
- **setuptools**: bootstrapped alongside wheel for `uv pip compile`, legacy sdists (e.g. `docopt 0.6.2` via kokoro → misaki → num2words chain) need setup.py but uv doesn't supply setuptools when build isolation is off (#871)
- **Cloud port**: corrected from 433 to 443 in `services.json` (#684)
- **LLM providers**: small cleanup across all LLM nodes (#645)
- **Auth token precedence**: URL auth param prioritized over stale sessionStorage token from previous task (#902)
- **AVIReader**: capture errors from background `_data_process` thread and re-raise on `stop()` so pipeline errors surface as task errors (#803)
- **Webhook/Telegram nodes**: removed `server.use('profiler')` calls (profiler module was deleted; these caused "Module 'profiler' is not allowed" crash) (#803)
- **Task auth**: removed early `ValueError` on empty credential that prevented anonymous/no-key OSS connections from reaching auth check (#803)

#### CI/CD
- **Open VSX**: handle 'already published' error in release workflow (#480)
- **Docs-only PRs**: build passthrough so they don't block CI (#607)
- **Flaky tests**: resolve timeouts and hanging in concurrent pipeline tests, shared hardcoded `project_id` caused server-side contention serializing subprocess launches (#561, #877)
- **Discord webhooks**: retry/backoff for webhook calls (#797); prevent duplicate posts on discussion edits (#698)
- **Nightly workflow**: explicit branch check on `workflow_run` trigger (#771); allow `workflow_dispatch` from stage and main (#906)
- **Release tags**: push via `WORKFLOW_PAT` with repo+workflow scope (#774)
- **pytest-xdist race**: all 6 path-traversal test methods shared same `outside.txt` in system temp root; fixed by wrapping `workdir` in per-test tempdir (#872)
- **pnpm-lock.yaml**: restore libc fields (#622); fix lucide-react dependency (#621)
- **CI API key**: use literal `ROCKETRIDE_APIKEY` in Test step instead of secret (#742); match GraphQL github-actions author login (#699)
- **ruff format**: pure whitespace fixes for vision node files that left develop CI red (#902)

#### Tests
- **AI unit-test coverage** grown from 8% to 43% (395 → 945 passing tests). Covers: sql_safety, common/util/validation/table, dap_conn, pipeline_validation, web endpoints, auth middleware, sandbox execution, profiler lifecycle, account/reporter/keystore, all command handlers, data_conn, task_engine state, task_server background loops, transports, task_http, store providers (S3 + Azure), DB base classes, dropper path-traversal guard. Assertions tightened per CodeRabbit review. CodeQL auth-callback URL assertions anchored (#831)
- **Tests realigned** with team-based permissions and metrics rewrite, updated mocks for `teamId`, `organizations`, `resolve_task_permissions`, `tokens.gpu_inference`/`tokens.custom`, renamed `apikey` → `user_id`. Dropped tests for deleted code. Added `test_cmd_public.py` (#870)
- **Node tests**: full improvements and mock cleanup (#687)

### Dependency Updates
- litellm ~1.50 → ~1.83 (#816)
- DOMPurify → 3.4.x (resolves 16 alerts / 8 GHSAs) (#886)
- cryptography pinned to 46.0.7 (#884)
- SQLAlchemy owned at ai layer, pinned ≥2.0,<2.1 (#804)
- Patched via pnpm.overrides:
  - **Routing**: react-router 6.26→6.30.3, @remix-run/router inlined (#914)
  - **Parsers**: ajv@8→≥8.18.0, markdown-it→≥14.1.1, postcss→≥8.5.10, prismjs→≥1.30.0, yaml@1→≥1.10.3 (#915)
  - **Middleware**: koa→≥2.16.4 (3 advisories), qs→≥6.14.2 (#916)
  - **Util/SVG**: svgo@2→≥2.8.1, flatted→≥3.4.2, immutable@5→≥5.1.5, underscore→≥1.13.8 (#917)
  - **Security**: picomatch@2→≥2.3.2, picomatch@4→≥4.0.4, fast-uri→≥3.1.2, serialize-javascript→≥7.0.5 (#890)
  - **Minimatch**: all 4 major lines patched (3→≥3.1.4, 5→≥5.1.8, 9→≥9.0.7, 10→≥10.2.3) (#887)
  - **Core**: undici→≥7.24.0 (6 advisories), lodash→≥4.18.0, lodash-es→≥4.18.0 (#888)
  - handlebars→≥4.7.9, protobufjs→≥7.5.5 (#783)
- Bumped: aiohttp, pygit2 1.15→1.19, soundfile 0.12→0.13, requests, ws 8.19→8.20, postcss 8.5.6→8.5.10, nltk, spacy, spacy-transformers, cymem, murmurhash, preshed, srsly, thinc, psycopg2-binary, pymysql, opensearch-py, npm-production group (adm-zip, tar, lucide-react, dockerode, web-vitals), shared-ui devDependencies (rollup, @types/react, @types/react-dom), cosign-installer, ossf/scorecard-action, gh-actions group (pnpm/action-setup, github/codeql-action, softprops/action-gh-release, dorny/paths-filter)

---

## RocketRide Server v3.2.2

**Server** · v3.2.2 · June 11, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.2.2)

### What's Changed
* hotfix(3.2.2): deepagent transformers-free token counting + App-token release flow by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/1225


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-python-v1.2.0...server-v3.2.2

---

## RocketRide VS Code Extension v1.2.0

**VS Code Extension** · v1.2.0 · June 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.2.0)

### RocketRide 1.2.0 — Highlights

### ✨ New nodes & integrations
- **MiniMax** — including the new **M3** frontier multimodal coding model (1M-token context), plus the M2 family. (#967, #1046)
- **ClickHouse** — query as a pipeline step or an agent tool; read-only by default, ClickHouse Cloud TLS toggle. (#1064)
- **Tavily** — live web search for your agents. (#1097)
- **xTrace Memory** — long-term, shared agent memory across runs (remember / recall). (#1065)
- **Butterbase MCP** — provision and operate a full backend (schema, auth, data, storage, functions, deploy) from inside a pipeline. (#1069)
- One-click presets: **Supabase** (Postgres) (#1084) and **Nebius Token Factory** (Llama 3.3 70B, Qwen3 235B, DeepSeek V3) (#1071).

### ⚡ Agents & performance
- **Parallel sub-agents (DeepAgent)** — sub-tasks now run concurrently; total run time drops to the slowest task instead of the sum. (#990)

### 💳 Plans & onboarding
- Redesigned **plan picker** (monthly/annual) and streamlined **checkout**; apps that require a subscription now prompt for one. (#1078)

### 📣 Product
- **In-app announcements ticker** in the sidebar (and fixed so it loads in VS Code). (#1131)

### 🛠️ Quality & reliability
- Cloud apps now show a **clear error + Retry** instead of an endless "Loading…". (#1087)
- **More reliable multi-turn agent tool calls** — parallel calls no longer mis-attribute results across turns. (#1068)
- **Node config warnings** now reliably surface missing required fields (AJV validator). (#1078)
- Stability fixes: OCR under heavy load (#1070), Whisper on newer GPUs (#1036/#1043/#1052), VS Code project-editor reliability (#1104), corrected GMI Cloud Gemini model IDs (#1010), engine port-binding for embedded clients (#993).

### 📦 Client SDKs (Python & TypeScript)
- SDK reference docs audited and expanded; billing/plan types kept in sync across both SDKs.
- ⚠️ **Breaking:** the connection API was refactored into a layered `attach` / `login` / `logout` model (old `connect()` / `disconnect()` kept as compatible wrappers). See the CHANGELOG "Breaking Changes — Client SDKs" section before upgrading SDK code.

---
**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.1.1...vscode-v1.2.0

---

## RocketRide TypeScript Client v1.2.0

**TypeScript SDK** · v1.2.0 · June 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.2.0)

### RocketRide 1.2.0 — Highlights

### ✨ New nodes & integrations
- **MiniMax** — including the new **M3** frontier multimodal coding model (1M-token context), plus the M2 family. (#967, #1046)
- **ClickHouse** — query as a pipeline step or an agent tool; read-only by default, ClickHouse Cloud TLS toggle. (#1064)
- **Tavily** — live web search for your agents. (#1097)
- **xTrace Memory** — long-term, shared agent memory across runs (remember / recall). (#1065)
- **Butterbase MCP** — provision and operate a full backend (schema, auth, data, storage, functions, deploy) from inside a pipeline. (#1069)
- One-click presets: **Supabase** (Postgres) (#1084) and **Nebius Token Factory** (Llama 3.3 70B, Qwen3 235B, DeepSeek V3) (#1071).

### ⚡ Agents & performance
- **Parallel sub-agents (DeepAgent)** — sub-tasks now run concurrently; total run time drops to the slowest task instead of the sum. (#990)

### 💳 Plans & onboarding
- Redesigned **plan picker** (monthly/annual) and streamlined **checkout**; apps that require a subscription now prompt for one. (#1078)

### 📣 Product
- **In-app announcements ticker** in the sidebar (and fixed so it loads in VS Code). (#1131)

### 🛠️ Quality & reliability
- Cloud apps now show a **clear error + Retry** instead of an endless "Loading…". (#1087)
- **More reliable multi-turn agent tool calls** — parallel calls no longer mis-attribute results across turns. (#1068)
- **Node config warnings** now reliably surface missing required fields (AJV validator). (#1078)
- Stability fixes: OCR under heavy load (#1070), Whisper on newer GPUs (#1036/#1043/#1052), VS Code project-editor reliability (#1104), corrected GMI Cloud Gemini model IDs (#1010), engine port-binding for embedded clients (#993).

### 📦 Client SDKs (Python & TypeScript)
- SDK reference docs audited and expanded; billing/plan types kept in sync across both SDKs.
- ⚠️ **Breaking:** the connection API was refactored into a layered `attach` / `login` / `logout` model (old `connect()` / `disconnect()` kept as compatible wrappers). See the CHANGELOG "Breaking Changes — Client SDKs" section before upgrading SDK code.

---
**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.1.1...client-typescript-v1.2.0

---

## RocketRide Python Client v1.2.0

**Python SDK** · v1.2.0 · June 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.2.0)

### RocketRide 1.2.0 — Highlights

### ✨ New nodes & integrations
- **MiniMax** — including the new **M3** frontier multimodal coding model (1M-token context), plus the M2 family. (#967, #1046)
- **ClickHouse** — query as a pipeline step or an agent tool; read-only by default, ClickHouse Cloud TLS toggle. (#1064)
- **Tavily** — live web search for your agents. (#1097)
- **xTrace Memory** — long-term, shared agent memory across runs (remember / recall). (#1065)
- **Butterbase MCP** — provision and operate a full backend (schema, auth, data, storage, functions, deploy) from inside a pipeline. (#1069)
- One-click presets: **Supabase** (Postgres) (#1084) and **Nebius Token Factory** (Llama 3.3 70B, Qwen3 235B, DeepSeek V3) (#1071).

### ⚡ Agents & performance
- **Parallel sub-agents (DeepAgent)** — sub-tasks now run concurrently; total run time drops to the slowest task instead of the sum. (#990)

### 💳 Plans & onboarding
- Redesigned **plan picker** (monthly/annual) and streamlined **checkout**; apps that require a subscription now prompt for one. (#1078)

### 📣 Product
- **In-app announcements ticker** in the sidebar (and fixed so it loads in VS Code). (#1131)

### 🛠️ Quality & reliability
- Cloud apps now show a **clear error + Retry** instead of an endless "Loading…". (#1087)
- **More reliable multi-turn agent tool calls** — parallel calls no longer mis-attribute results across turns. (#1068)
- **Node config warnings** now reliably surface missing required fields (AJV validator). (#1078)
- Stability fixes: OCR under heavy load (#1070), Whisper on newer GPUs (#1036/#1043/#1052), VS Code project-editor reliability (#1104), corrected GMI Cloud Gemini model IDs (#1010), engine port-binding for embedded clients (#993).

### 📦 Client SDKs (Python & TypeScript)
- SDK reference docs audited and expanded; billing/plan types kept in sync across both SDKs.
- ⚠️ **Breaking:** the connection API was refactored into a layered `attach` / `login` / `logout` model (old `connect()` / `disconnect()` kept as compatible wrappers). See the CHANGELOG "Breaking Changes — Client SDKs" section before upgrading SDK code.

---
**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.1.1...client-python-v1.2.0

---

## RocketRide VS Code Extension v1.1.1

**VS Code Extension** · v1.1.1 · May 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.1.1)

### What's Changed
* release: stage → main (dot release 2026-05-27) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/1014


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.1.0...vscode-v1.1.1

---

## RocketRide Server v3.2.1

**Server** · v3.2.1 · May 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.2.1)

### What's Changed
* release: stage → main (dot release 2026-05-27) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/1014


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.1.0...server-v3.2.1

---

## RocketRide TypeScript Client v1.1.1

**TypeScript SDK** · v1.1.1 · May 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.1.1)

### What's Changed
* release: stage → main (dot release 2026-05-27) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/1014


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.1.0...client-typescript-v1.1.1

---

## RocketRide MCP Client v1.1.1

**MCP Client** · v1.1.1 · May 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.1.1)

### What's Changed
* release: stage → main (dot release 2026-05-27) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/1014


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.1.0...client-mcp-v1.1.1

---

## RocketRide Python Client v1.1.1

**Python SDK** · v1.1.1 · May 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.1.1)

### What's Changed
* release: stage → main (dot release 2026-05-27) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/1014


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.1.0...client-python-v1.1.1

---

## RocketRide TypeScript Client v1.1.0

**TypeScript SDK** · v1.1.0 · May 23, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.1.0)

### What's Changed
* ci(release): switch TS client npm publish to OIDC trusted publishing by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/976
* ci(release): drop registry-url to unblock OIDC npm publish by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/977
* ci(release): add diagnostic logging to TS publish to debug OIDC by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/978


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.1.0...client-typescript-v1.1.0

---

## RocketRide VS Code Extension v1.1.0

**VS Code Extension** · v1.1.0 · May 22, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.1.0)

### What's Changed
* docs: add gifs to readme by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/478
* chore: sync develop to main — README gifs by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/479
* fix(ci): handle Open VSX 'already published' error by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/480
* chore: sync develop to main — Open VSX fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/481
* release: stage → main (VS Code release 2026-05-22) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/971


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.7...vscode-v1.1.0

---

## RocketRide Server v3.2.0

**Server** · v3.2.0 · May 22, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.2.0)

### RocketRide 1.2.0 — Highlights

### ✨ New nodes & integrations
- **MiniMax** — including the new **M3** frontier multimodal coding model (1M-token context), plus the M2 family. (#967, #1046)
- **ClickHouse** — query as a pipeline step or an agent tool; read-only by default, ClickHouse Cloud TLS toggle. (#1064)
- **Tavily** — live web search for your agents. (#1097)
- **xTrace Memory** — long-term, shared agent memory across runs (remember / recall). (#1065)
- **Butterbase MCP** — provision and operate a full backend (schema, auth, data, storage, functions, deploy) from inside a pipeline. (#1069)
- One-click presets: **Supabase** (Postgres) (#1084) and **Nebius Token Factory** (Llama 3.3 70B, Qwen3 235B, DeepSeek V3) (#1071).

### ⚡ Agents & performance
- **Parallel sub-agents (DeepAgent)** — sub-tasks now run concurrently; total run time drops to the slowest task instead of the sum. (#990)

### 💳 Plans & onboarding
- Redesigned **plan picker** (monthly/annual) and streamlined **checkout**; apps that require a subscription now prompt for one. (#1078)

### 📣 Product
- **In-app announcements ticker** in the sidebar (and fixed so it loads in VS Code). (#1131)

### 🛠️ Quality & reliability
- Cloud apps now show a **clear error + Retry** instead of an endless "Loading…". (#1087)
- **More reliable multi-turn agent tool calls** — parallel calls no longer mis-attribute results across turns. (#1068)
- **Node config warnings** now reliably surface missing required fields (AJV validator). (#1078)
- Stability fixes: OCR under heavy load (#1070), Whisper on newer GPUs (#1036/#1043/#1052), VS Code project-editor reliability (#1104), corrected GMI Cloud Gemini model IDs (#1010), engine port-binding for embedded clients (#993).

### 📦 Client SDKs (Python & TypeScript)
- SDK reference docs audited and expanded; billing/plan types kept in sync across both SDKs.
- ⚠️ **Breaking:** the connection API was refactored into a layered `attach` / `login` / `logout` model (old `connect()` / `disconnect()` kept as compatible wrappers). See the CHANGELOG "Breaking Changes — Client SDKs" section before upgrading SDK code.

---
**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.7...server-v3.2.0

---

## RocketRide Python Client v1.1.0

**Python SDK** · v1.1.0 · May 22, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.1.0)

### What's Changed
* docs: add gifs to readme by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/478
* chore: sync develop to main — README gifs by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/479
* fix(ci): handle Open VSX 'already published' error by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/480
* chore: sync develop to main — Open VSX fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/481
* release: stage → main (VS Code release 2026-05-22) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/971


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.7...client-python-v1.1.0

---

## RocketRide MCP Client v1.1.0

**MCP Client** · v1.1.0 · May 22, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.1.0)

### What's Changed
* docs: add gifs to readme by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/478
* chore: sync develop to main — README gifs by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/479
* fix(ci): handle Open VSX 'already published' error by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/480
* chore: sync develop to main — Open VSX fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/481
* release: stage → main (VS Code release 2026-05-22) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/971


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.7...client-mcp-v1.1.0

---

## RocketRide MCP Client v1.0.7

**MCP Client** · v1.0.7 · March 30, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.0.7)

### What's Changed
* chore: bump rocketride-mcp to 1.0.7 for PyPI banner by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/476
* chore: release MCP 1.0.7 banner fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/477


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.6...client-mcp-v1.0.7

---

## RocketRide Python Client v1.0.6

**Python SDK** · v1.0.6 · March 30, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.0.6)

### What's Changed
* fix: convert all banner SVGs to PNG + absolute URLs for npm/PyPI/marketplace by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/472
* chore: merge develop into main for banner fix release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/473
* chore(versions): bump to 1.0.6 for banner fix release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/474
* chore: release 1.0.6 — banner fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/475


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-python-v1.0.5...client-python-v1.0.6

---

## RocketRide MCP Client v1.0.6

**MCP Client** · v1.0.6 · March 30, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.0.6)

### What's Changed
* fix: convert all banner SVGs to PNG + absolute URLs for npm/PyPI/marketplace by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/472
* chore: merge develop into main for banner fix release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/473
* chore(versions): bump to 1.0.6 for banner fix release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/474
* chore: release 1.0.6 — banner fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/475


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-python-v1.0.5...client-mcp-v1.0.6

---

## RocketRide TypeScript Client v1.0.6

**TypeScript SDK** · v1.0.6 · March 30, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.0.6)

### What's Changed
* fix: convert all banner SVGs to PNG + absolute URLs for npm/PyPI/marketplace by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/472
* chore: merge develop into main for banner fix release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/473
* chore(versions): bump to 1.0.6 for banner fix release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/474
* chore: release 1.0.6 — banner fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/475


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-python-v1.0.5...client-typescript-v1.0.6

---

## RocketRide Server v3.1.2

**Server** · v3.1.2 · March 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.1.2)

### What's Changed
* feat(node): Add documents lane to frame grabber and vision nodes by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/459
* feat(trace): interactive JSON tree viewer in trace detail panel by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/466
* chore(versions): bump patch versions for release by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/467
* docs: redesign root README and standardize package README styling (RR-405) by @joshuadarron in https://github.com/rocketride-org/rocketride-server/pull/465
* chore(release): New release pushed out on all releasable modules  by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/468
* fix(ci): add permissions to release and docker jobs by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/469
* fix(vscode): convert banner SVG to PNG for marketplace by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/471
* chore: merge develop into main for release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/470


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.5-prerelease...server-v3.1.2

---

## RocketRide Python Client v1.0.5

**Python SDK** · v1.0.5 · March 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.0.5)

### What's Changed
* feat(node): Add documents lane to frame grabber and vision nodes by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/459
* feat(trace): interactive JSON tree viewer in trace detail panel by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/466
* chore(versions): bump patch versions for release by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/467
* docs: redesign root README and standardize package README styling (RR-405) by @joshuadarron in https://github.com/rocketride-org/rocketride-server/pull/465
* chore(release): New release pushed out on all releasable modules  by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/468
* fix(ci): add permissions to release and docker jobs by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/469
* fix(vscode): convert banner SVG to PNG for marketplace by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/471
* chore: merge develop into main for release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/470


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.5-prerelease...client-python-v1.0.5

---

## RocketRide TypeScript Client v1.0.5

**TypeScript SDK** · v1.0.5 · March 29, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.0.5)

### What's Changed
* feat(node): Add documents lane to frame grabber and vision nodes by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/459
* feat(trace): interactive JSON tree viewer in trace detail panel by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/466
* chore(versions): bump patch versions for release by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/467
* docs: redesign root README and standardize package README styling (RR-405) by @joshuadarron in https://github.com/rocketride-org/rocketride-server/pull/465
* chore(release): New release pushed out on all releasable modules  by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/468
* fix(ci): add permissions to release and docker jobs by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/469
* fix(vscode): convert banner SVG to PNG for marketplace by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/471
* chore: merge develop into main for release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/470


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.5-prerelease...client-typescript-v1.0.5

---

## RocketRide VS Code Extension v1.0.5

**VS Code Extension** · v1.0.5 · March 27, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.0.5)

### What's Changed
* fix(vscode): complete README packaging fix (from #323) by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/324
* fix(vscode): add missing glob dependency for vsix packaging by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/330
* fix(vscode): use @vscode/vsce for vsix packaging by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/449
* fix(ci): remove main from scorecard push trigger by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/452
* fix(vscode): restore marketplace extension name in vsix staging by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/458


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/vscode-v1.0.3...vscode-v1.0.5

---

## RocketRide VS Code Extension v1.0.3

**VS Code Extension** · v1.0.3 · March 22, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.0.3)

### What's Changed
* fix(vscode): include README.md in vsix package by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/322


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.4...vscode-v1.0.3

---

## RocketRide VS Code Extension v1.0.2

**VS Code Extension** · v1.0.2 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.0.2)

### What's Changed
* chore: bump package versions for hackathon release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/318


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.3...vscode-v1.0.2

---

## RocketRide MCP Client v1.0.4

**MCP Client** · v1.0.4 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.0.4)

### What's Changed
* chore: bump package versions for hackathon release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/318


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.3...client-mcp-v1.0.4

---

## RocketRide Python Client v1.0.4

**Python SDK** · v1.0.4 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.0.4)

### What's Changed
* chore: bump package versions for hackathon release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/318


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.3...client-python-v1.0.4

---

## RocketRide TypeScript Client v1.0.4

**TypeScript SDK** · v1.0.4 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.0.4)

### What's Changed
* chore: bump package versions for hackathon release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/318


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.3...client-typescript-v1.0.4

---

## RocketRide VS Code Extension v1.0.1

**VS Code Extension** · v1.0.1 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.0.1)

### What's Changed
* docs: cherry-pick README updates for hackathon by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/303


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.0.2...vscode-v1.0.1

---

## RocketRide MCP Client v1.0.3

**MCP Client** · v1.0.3 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.0.3)

### What's Changed
* docs: cherry-pick README updates for hackathon by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/303


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.0.2...client-mcp-v1.0.3

---

## RocketRide TypeScript Client v1.0.3

**TypeScript SDK** · v1.0.3 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.0.3)

### What's Changed
* docs: cherry-pick README updates for hackathon by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/303


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.0.2...client-typescript-v1.0.3

---

## RocketRide Python Client v1.0.3

**Python SDK** · v1.0.3 · March 21, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.0.3)

### What's Changed
* docs: cherry-pick README updates for hackathon by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/303


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-typescript-v1.0.2...client-python-v1.0.3

---

## RocketRide TypeScript Client v1.0.2

**TypeScript SDK** · v1.0.2 · March 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-typescript-v1.0.2)

### What's Changed
* fix(ci): npm trusted publishers and publish path fix by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/198


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/client-mcp-v1.0.2...client-typescript-v1.0.2

---

## RocketRide VS Code Extension v1.0.0

**VS Code Extension** · v1.0.0 · March 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/vscode-v1.0.0)

### What's Changed
* chore(deps-dev): bump rollup from 4.50.2 to 4.59.0 in /packages/shared-ui by @dependabot[bot] in https://github.com/rocketride-org/rocketride-server/pull/41
* fix: add missing fields to issue/PR templates by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/49
* fix(server): use runtime-relative path for static UI files by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/51
* fix(ui): Fix notification banner and remove emoji from button by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/55
* fix: Remove system performance page by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/36
* feat(vscode): UX improvements for welcome, settings, pipelines, and U… by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/52
* fix: Remove unused source connectors by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/34
* fix: Improve index_search node for Elasticsearch and OpenSearch by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/24
* fix: Query vector shape in embedding node so vector DB retrieval works with any prompt. by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/35
* fix(ui): Improve chat usability by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/56
* feat: OSS security posture for public release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/27
* fix(tests): make event filtering test resilient to unsolicited events by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/46
* feat(ci): add GitHub Agentic Workflows by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/53
* fix(vscode): prevent connection mode setting from reverting on save by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/54
* chore: trigger release process by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/194


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/server-v1.0.3...vscode-v1.0.0

---

## RocketRide Server v3.1.0

**Server** · v3.1.0 · March 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v3.1.0)

### What's Changed
* chore(deps-dev): bump rollup from 4.50.2 to 4.59.0 in /packages/shared-ui by @dependabot[bot] in https://github.com/rocketride-org/rocketride-server/pull/41
* fix: add missing fields to issue/PR templates by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/49
* fix(server): use runtime-relative path for static UI files by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/51
* fix(ui): Fix notification banner and remove emoji from button by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/55
* fix: Remove system performance page by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/36
* feat(vscode): UX improvements for welcome, settings, pipelines, and U… by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/52
* fix: Remove unused source connectors by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/34
* fix: Improve index_search node for Elasticsearch and OpenSearch by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/24
* fix: Query vector shape in embedding node so vector DB retrieval works with any prompt. by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/35
* fix(ui): Improve chat usability by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/56
* feat: OSS security posture for public release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/27
* fix(tests): make event filtering test resilient to unsolicited events by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/46
* feat(ci): add GitHub Agentic Workflows by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/53
* fix(vscode): prevent connection mode setting from reverting on save by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/54
* chore: trigger release process by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/194


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/server-v1.0.3...server-v3.1.0

---

## RocketRide Python Client v1.0.2

**Python SDK** · v1.0.2 · March 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-python-v1.0.2)

### What's Changed
* chore(deps-dev): bump rollup from 4.50.2 to 4.59.0 in /packages/shared-ui by @dependabot[bot] in https://github.com/rocketride-org/rocketride-server/pull/41
* fix: add missing fields to issue/PR templates by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/49
* fix(server): use runtime-relative path for static UI files by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/51
* fix(ui): Fix notification banner and remove emoji from button by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/55
* fix: Remove system performance page by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/36
* feat(vscode): UX improvements for welcome, settings, pipelines, and U… by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/52
* fix: Remove unused source connectors by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/34
* fix: Improve index_search node for Elasticsearch and OpenSearch by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/24
* fix: Query vector shape in embedding node so vector DB retrieval works with any prompt. by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/35
* fix(ui): Improve chat usability by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/56
* feat: OSS security posture for public release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/27
* fix(tests): make event filtering test resilient to unsolicited events by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/46
* feat(ci): add GitHub Agentic Workflows by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/53
* fix(vscode): prevent connection mode setting from reverting on save by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/54
* chore: trigger release process by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/194


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/server-v1.0.3...client-python-v1.0.2

---

## RocketRide MCP Client v1.0.2

**MCP Client** · v1.0.2 · March 5, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/client-mcp-v1.0.2)

### What's Changed
* chore(deps-dev): bump rollup from 4.50.2 to 4.59.0 in /packages/shared-ui by @dependabot[bot] in https://github.com/rocketride-org/rocketride-server/pull/41
* fix: add missing fields to issue/PR templates by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/49
* fix(server): use runtime-relative path for static UI files by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/51
* fix(ui): Fix notification banner and remove emoji from button by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/55
* fix: Remove system performance page by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/36
* feat(vscode): UX improvements for welcome, settings, pipelines, and U… by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/52
* fix: Remove unused source connectors by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/34
* fix: Improve index_search node for Elasticsearch and OpenSearch by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/24
* fix: Query vector shape in embedding node so vector DB retrieval works with any prompt. by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/35
* fix(ui): Improve chat usability by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/56
* feat: OSS security posture for public release by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/27
* fix(tests): make event filtering test resilient to unsolicited events by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/46
* feat(ci): add GitHub Agentic Workflows by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/53
* fix(vscode): prevent connection mode setting from reverting on save by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/54
* chore: trigger release process by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/194


**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/server-v1.0.3...client-mcp-v1.0.2

---

## RocketRide Server v1.0.3

**Server** · v1.0.3 · February 26, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v1.0.3)

### What's Changed
* chore(deps): bump tar from 7.5.7 to 7.5.8 by @dependabot[bot] in https://github.com/rocketride-org/rocketride-server/pull/28
* fix(vscode): preserve .env comments, formatting, and user variables by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/45
* feat: upgrade issue templates to YAML forms, add PR template by @kwit75 in https://github.com/rocketride-org/rocketride-server/pull/47
* fix(server): add static directory sync to package action by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/48
* fix(build): fix contentHash cross-platform determinism and output by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/43

### New Contributors
* @dependabot[bot] made their first contribution in https://github.com/rocketride-org/rocketride-server/pull/28
* @kwit75 made their first contribution in https://github.com/rocketride-org/rocketride-server/pull/47

**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/server-v1.0.2...server-v1.0.3

---

## RocketRide Server v1.0.2

**Server** · v1.0.2 · February 26, 2026 · [View on GitHub](https://github.com/rocketride-org/rocketride-server/releases/tag/server-v1.0.2)

### What's Changed
* feat(ci): VS Code extension artifact by @stepmikhaylov in https://github.com/rocketride-org/rocketride-server/pull/18
* Fix/docs by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/16
* feat(ci): upload client artifacts by @stepmikhaylov in https://github.com/rocketride-org/rocketride-server/pull/20
* chore: Prepare Python and TypeScript client packages for publishing by @JoshuaDarron in https://github.com/rocketride-org/rocketride-server/pull/15
* chore: Adding test configuration for nodes that not requires external dependencies by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/12
* fix(ci): read client-python and client-mcp version from pyproject.toml by @stepmikhaylov in https://github.com/rocketride-org/rocketride-server/pull/21
* fix: improve chat and llm nodes by @ryan-t-christensen in https://github.com/rocketride-org/rocketride-server/pull/17
* fix:  Qdrant client running on local env without SSL by @dsapandora in https://github.com/rocketride-org/rocketride-server/pull/7
* fix: update readme files by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/25
* fix: Preserve index URLs in constraints so install can resolve extra-index packages by @asclearuc in https://github.com/rocketride-org/rocketride-server/pull/39
* fix: documentation update by @asclearuc in https://github.com/rocketride-org/rocketride-server/pull/40
* feat: content hash download validation, submodule build restructure by @Rod-Christensen in https://github.com/rocketride-org/rocketride-server/pull/23
* feat(builder): fix server download check by @stepmikhaylov in https://github.com/rocketride-org/rocketride-server/pull/42

### New Contributors
* @JoshuaDarron made their first contribution in https://github.com/rocketride-org/rocketride-server/pull/15
* @ryan-t-christensen made their first contribution in https://github.com/rocketride-org/rocketride-server/pull/17

**Full Changelog**: https://github.com/rocketride-org/rocketride-server/compare/server-v1.0.1...server-v1.0.2


---

# Security Policy

Route: /support/security-policy

---
title: Security Policy
sidebar_label: Security Policy
---

# Security Policy

RocketRide is open-source and developed in the open with a documented security process. This
page summarizes it; the authoritative policy is
[`SECURITY.md`](https://github.com/rocketride-org/rocketride-server/blob/develop/SECURITY.md)
in the repository.

## Reporting a vulnerability

Report security issues privately, **do not** open a public issue. Use
[GitHub Security Advisories](https://github.com/rocketride-org/rocketride-server/security/advisories/new)
on the repository, or email **security@rocketride.ai**. You'll get an acknowledgement and a
coordinated-disclosure timeline.

## Triage & remediation SLAs

Reports are triaged and fixed on severity-based timelines (critical issues fastest, down to
low). The exact triage and remediation windows per severity are listed in
[`SECURITY.md`](https://github.com/rocketride-org/rocketride-server/blob/develop/SECURITY.md).

## How the codebase is protected

- **Automated scanning** on every change: CodeQL (static analysis), OpenSSF Scorecard, Trivy
  (dependencies & containers), Dependabot, and secret scanning.
- **Two-person control** on dismissing security findings: no single maintainer can wave a
  finding through.
- **Branch protection** on `develop`: required reviews and status checks before merge, with
  admin bypass disabled so the rules apply to everyone, including org owners.
- **Periodic access reviews** of who can write to the repository.

## Deployment & data

Pipelines are portable JSON you control. You choose where the engine runs (locally,
on-premises behind your own network controls, or on [RocketRide Cloud](/operate/cloud)), so sensitive
data and model credentials stay within the boundary you operate. When connecting to a remote
engine, always use an encrypted transport (`https://` / `wss://`); a plain `ws://` URI
downgrades to an unencrypted connection.

## Read the full policy

See [`SECURITY.md`](https://github.com/rocketride-org/rocketride-server/blob/develop/SECURITY.md)
for supported versions, the complete reporting process, and the full SLA table.


---

# Troubleshooting

Route: /support/troubleshooting

---
title: Troubleshooting
---

# Troubleshooting

Common issues when building and running pipelines, and how to fix them.

## How errors are classified

Errors fall into two categories depending on when they occur:

- **Startup errors (init-time)** happen while the engine validates and
  initialises the pipeline, before any data flows: invalid configuration (a
  required field missing, a value out of range, a referenced profile that does
  not exist), a missing Python dependency, a failed validation call (nodes like
  `llm_openai` make a test API call on startup to verify the key and model),
  or a lane mismatch. The engine reports the error immediately and the
  pipeline does not run — no data is processed.
- **Runtime errors** happen during execution: an LLM API error (rate limit,
  context overflow, outage), a vector store timeout, a malformed document that
  cannot be chunked, or an agent exceeding its iteration cap. A runtime error
  **stops the current pipeline run**; nodes that already streamed output are
  not rolled back, and concurrent runs on the same pipeline are unaffected.

Either way the engine emits a structured error event over the
[WebSocket protocol](/connect/websocket) with the node ID, message and type,
and a stack trace for Python-level errors. The CLI prints these as they
arrive; SDK clients receive them on the event stream. The full schema is in
[WebSocket Events](/connect/websocket/observability), and recovery patterns
(retries, fallbacks, guardrails) live in
[Error Handling](/guides/error-handling).

## Can't connect to the engine

- **Connection refused / timeout.** Nothing is listening on the URI. Start a
  local engine (the [VS Code extension](/clients/vscode) or a
  [self-hosted](/operate/self-hosting) container on port 5565), or point
  `ROCKETRIDE_URI` at your [Cloud](/operate/cloud) endpoint.
- **Unauthorized against Cloud.** Set `ROCKETRIDE_APIKEY` to a valid API token
  (`ROCKETRIDE_AUTH` is read only by the MCP servers, not the SDKs or CLI).
- **Silent insecure downgrade.** Against Cloud, an `http://`/`ws://` (or bare
  `host:port`) URI drops to an unencrypted connection. Use `https://` or
  `wss://`, see the [WebSocket protocol](/connect/websocket).

## Pipeline starts but no output comes back

- **Wrong source for the job.** A `chat` source expects `chat()`; a `webhook` /
  file source expects `send()` / `pipe()` (or [`upload`](/connect/cli)). Driving a chat
  pipeline with `send()` (or vice versa) produces nothing. Match the method to
  the source node.
- **Pipeline isn't actually running.** Uploads against a stale or terminated
  task token return nothing. Start the pipeline, then feed it.

## The response is empty or under the wrong key

- **Response key mismatch.** A `response` node with a custom `laneName` puts the
  result under that name, not the default. Read the key your pipeline actually
  emits (the result's `result_types` tells you which key carries which
  [lane](/concepts/execution-model)), or use the default response config.

## "Lane not supported" / "Lane mismatch" errors

The output [lane](/concepts/execution-model) of one node must match the input
lane of the next. Check both ends against the
[Nodes](/nodes) and fix the mismatched `input` connection.

## Agent pipeline fails to start

- **Missing control connections.** Agents need their helpers wired via
  `control` on the helper, not the agent. `agent_rocketride` requires exactly
  one LLM **and** one memory; `agent_crewai` / `agent_langchain` take no memory.
  See [Agents & tools](/concepts/agents-tools-skills).

## Resources leak / connections pile up

Always close the client when done (use the SDK's context manager / `terminate()`),
and start a long-lived pipeline **once** rather than per request.

## Related

- [Execution model](/concepts/execution-model): how lanes and control flow.
- [Pipeline JSON Reference](/reference/pipeline-reference): every field of a `.pipe`.
- [Glossary](/reference/glossary): terms used across the docs.