Riptide工作流

🚀 Install

Prerequisites: Python 3.11+. No compiler or other toolchain needed.

```bash pip install riptide-watergraph # core pip install "riptide-watergraph[server]" # + Studio web UI (riptide serve) pip install "riptide-watergraph[all]" # + LiteLLM, MCP, observability

Use a real model (installs the LiteLLM gateway + tracing extras)

pip install "riptide-watergraph[all]" export OPENAI_API_KEY=sk-... # and RIPTIDE_WATERGRAPH_MODEL=gpt-4o-mini riptide run "Summarize and save a note about water" # drop --offline

**Library API** — the same graph, embedded:

graph = build_graph( gateway=DemoGateway(), # swap for LiteLLMGateway(...) to use a real model registry=default_registry(), composer=HeuristicSwarmComposer(model="demo"), model="demo", ) result = graph.invoke({"task": "compute 21 * 2"}) print(result["final_answer"]) ```

More runnable examples in examples/; see CONTRIBUTING.md to hack on it and CHANGELOG.md for history.

pass `memory=` to build_graph — everything else is unchanged.

`psycopg` is imported lazily, so the core package never requires it.

</details>

<details>
<summary><strong>🐝 Dynamic swarm + on-demand tools (Stage 3)</strong></summary>

The orchestrator asks a cost-aware **composer** how to run each task. `HeuristicSwarmComposer` estimates
independent sub-goals and picks a parallel **swarm** only when the task genuinely decomposes *and* needs no
human-approved side effects (those serialize through the HITL gate); otherwise it stays a **single** agent
— avoiding the multi-agent token multiplier for work that wouldn't benefit. The decision carries both the
chosen-mode and single-agent cost so the trade-off is visible.

**Phase C deepens this:** an `LLMSwarmComposer` (`--llm-composer`) asks the model to decompose the task
into subtasks **with dependencies**. Execution is then **dependency-ordered waves** — independent subtasks
run in parallel within a wave, dependent ones run after, and a shared **blackboard** carries each subtask's
output to its dependents' prompts. **Model routing** (`planner_model` / `worker_model`) lets the
orchestrator/finalize use a premium model while workers use a cheaper one. The **tool registry** retrieves
only the top-k relevant tools per subtask (BM25), keeping schemas out of context, and supports versioned
tools (`get` / `list_versions`).

</details>

<details>
<summary><strong>🎭 Heterogeneous agents — roles, critic, supervisor, handoff</strong></summary>

The swarm runs **specialist** agents, not generic workers:

- **Roles** — each subtask is assigned a role with a role-specific prompt and a **scoped tool allow-list**
  (least privilege per agent). Always on; defaults to `generalist`.
- **Critic** (`--critic`) — an adversarial verifier checks each result (`pass`/`fail`) before finalize,
  which then builds the answer from **verified** results only.
- **Supervisor** (`--supervisor`, implies `--critic`) — reviews verdicts and appends **corrective
  subtasks** for the failures, looping back through the workers up to a hard `max_rounds` cap.
- **Handoff** — a worker can emit a `handoff(role, reason)` call to **delegate its subtask to a
  better-suited specialist** (capped at one per subtask).

</details>

<details>
<summary><strong>🔁 Smarter individual agents — ReAct, voting, structured output, clarify</strong></summary>

Each worker can do more than a single shot. Every capability below is **gated by a default that reduces
exactly to the prior single-shot behavior**, so it is purely opt-in:

- **Iterative tool use / ReAct** (`build_graph(max_steps=N)`, CLI `--react N`) — loop _think → act →
  observe_ over read-only tools; side-effecting tools still defer to the approval gate (run once).
- **Self-consistency / voting** (`build_graph(vote_k=K)`, CLI `--vote K`) — sample a direct answer `K`
  times and majority-vote; abandoned if any sample requests a tool (so tools run once).
- **Structured outputs** (`build_graph(final_schema=…)`, CLI `--schema PATH`) — finalize emits a JSON
  object validated against a JSON Schema (one retry on failure), as `RunResult.structured`.
- **Clarifying questions (HITL)** — a worker can emit `ask_human(question)` to pause and ask the operator;
  the graph `interrupt()`s, resumes with the answer, and re-runs the subtask (capped at one per subtask).

</details>

<details>
<summary><strong>🛡️ Production hardening — guardrails, multi-tenancy, cost (Stage 4)</strong></summary>

Guardrails wrap the graph: a **`guard_input`** node blocks prompt-injection attempts and redacts PII
before anything reaches the model; a **`guard_output`** node redacts PII from the final answer. Both are a
`GuardrailPipeline` of layered, swappable checks (defense in depth). **Multi-tenancy** gives each tenant an
isolated memory namespace (`--tenant`), so lessons never leak across tenants, and every run appends a
`UsageRecord` to a per-tenant usage log — `riptide costs` prints the dashboard, and per-tenant **budget
ceilings** reject over-budget runs (HTTP 402).

</details>

<details>
<summary><strong>🔌 Tools, roles & MCP interop</strong></summary>

The registry ships **230+ read-only, stdlib-only tools** (`tools/library.py`) across text, regex, JSON/CSV,
encoding, hashing, math/stats, datetime, units, collections, random, extract, code, color, and validation —
**238 tools out of the box** — plus a **219-role catalog** (`swarm/role_library.py`) of domain specialists
across engineering, data, devops/SRE, security, QA, product, writing, research, finance, ops, design, and
enterprise functions/verticals. Each role carries a category-scoped tool allow-list, so on-demand retrieval
keeps a worker's context small no matter how large the registry is.

**Enterprise connectors (opt-in, MCP-bindable).** `RIPTIDE_ENABLE_ENTERPRISE=1` registers ~518 connector
tools for ~37 vendors (Salesforce, Jira, GitHub, ServiceNow, Slack, Snowflake, Stripe, …) — **~750 tools in
the gallery**. Offline they are **deterministic stubs**; bind a real
[MCP](https://modelcontextprotocol.io) server for a vendor to make them execute for real. Write actions are
`side_effecting` (human-approval gated) and stay inert until bound.

**MCP interop.** Tools from external MCP servers plug straight into the registry — once registered they are
ordinary `ToolSpec`s the worker/swarm call with no graph changes. The core is dependency-free and testable
offline via `FakeMcpClient`; the real stdio transport (`StdioMcpClient`) needs the `[mcp]` extra:

registry = default_registry() client = StdioMcpClient(command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/data"]) await register_mcp_tools(registry, client, prefix="fs.") # fs.read_file, fs.write_file, ...

**Connect from the Studio (gated + allowlisted).** The Studio's **MCP Servers** view turns the catalog into
live tools without code — only when `RIPTIDE_ENABLE_MCP_CONNECT=1` **and** the server is pre-declared in the
allowlist:

Connected tools join a dynamic-spec store that default_registry() appends, so they persist across Chat, Playground, Workflows and the Tool Runner. See examples/mcp_connect.py for an offline end-to-end demo.

</details>

⚡ Quickstart

```bash

Run a task end-to-end, fully offline (no API key / network):