synapse-orchestrator

Parallel tool execution — auto-detect dependencies, maximize speed

Python 3.10+ TypeScript 5+ MIT License 3-10x Speedup

Modern AI agents orchestrate dozens of tool calls per request. A naive implementation runs them sequentially. Synapse analyses the calls, builds a dependency DAG, and fires independent ones in parallel — dramatically cutting pipeline latency.

fetch_wikipedia --+ fetch_arxiv --+ fetch_github --+--> aggregate --> format_report fetch_news --+ fetch_patents --+ Stage 0 (5 calls in parallel) -> 200 ms Stage 1 (1 call) -> 100 ms Stage 2 (1 call) -> 50 ms Wall clock: 350 ms vs 1150 ms sequential => 3.3x speedup

# Install

Python

$ pip install synapse-orchestrator
# With provider extras:
$ pip install synapse-orchestrator[openai]
$ pip install synapse-orchestrator[anthropic]

TypeScript / Node.js

$ npm install synapse-orchestrator

# Quick Start

Python

import asyncio
from synapse import Orchestrator, ToolCall

async def main():
    orch = Orchestrator(tools={
        "fetch_user":    fetch_user,
        "fetch_catalog": fetch_catalog,
        "build_cart":    build_cart,
        "send_receipt":  send_receipt,
    })

    # $results.<id> references tell Synapse about data dependencies.
    # Independent calls run in parallel automatically.
    report = await orch.run([
        ToolCall(id="user",    name="fetch_user",    inputs={"user_id": 42}),
        ToolCall(id="catalog", name="fetch_catalog", inputs={"category": "widgets"}),
        ToolCall(id="cart",    name="build_cart",
                 inputs={"user": "$results.user", "catalog": "$results.catalog"}),
        ToolCall(id="receipt", name="send_receipt",
                 inputs={"cart": "$results.cart"}),
    ])

    print(report)
    # Wall clock: 312 ms | Stages: 3 | Speedup: 1.46x

asyncio.run(main())

TypeScript

import { Orchestrator, ToolCall } from "synapse-orchestrator";

const orch = new Orchestrator({
  tools: { fetchUser, fetchCatalog, buildCart, sendReceipt },
});

const report = await orch.run([
  { id: "user",    name: "fetchUser",    inputs: { userId: 42 } },
  { id: "catalog", name: "fetchCatalog", inputs: { category: "widgets" } },
  { id: "cart",    name: "buildCart",
    inputs: { user: "$results.user", catalog: "$results.catalog" } },
  { id: "receipt", name: "sendReceipt",
    inputs: { cart: "$results.cart" } },
]);

console.log(`Speedup: ${report.speedupEstimate.toFixed(2)}x`);

# API Reference

Orchestrator

MethodDescription
analyze(calls)Build dependency graph without executing
plan(calls)Build execution plan (staged DAG) without executing
run(calls)Full pipeline: analyze > plan > execute. Returns ExecutionReport
run_raw(dicts)Same as run but accepts plain dicts

ToolCall

FieldTypeDescription
idstrUnique id within the plan
namestrName of the registered tool function
inputsdictArguments passed to the tool. May contain $results.* refs
depends_onlist[str]Explicit dependency ids
timeoutfloatPer-call timeout in seconds
retriesintNumber of retries on failure

# Benchmarks

Pipeline ShapeSequentialSynapseSpeedup
2 independent > 1 > 1450 ms310 ms1.45x
5-way fan-out > aggregate > format1150 ms355 ms3.24x
10-way fan-out > 2 reduce > 1 merge2250 ms460 ms4.89x
Chain of 6 (no parallelism)900 ms905 ms1.00x

# Key Features