Node.js SDK

npm install orchetree

Node.js uses function wrapping rather than decorators.

import { node, tool } from "orchetree";

function search(query: string) {
  return { query };
}

tool(
  {
    name: "Search",
    description: "Search an approved source.",
    schema: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"],
    },
  },
  search,
);

function researcher(input: unknown) {
  return input;
}

node(
  {
    tree: "Research",
    capability: "retrieval",
    business_prompt: "Find evidence relevant to the question.",
    system_prompt: "Use only the supplied sources.",
    execution_prompt: "Return concise findings with source identifiers.",
    output_prompt: 'Return {"findings": [...]} as JSON.',
  },
  researcher,
);

The wrapped function is returned unchanged. Registration synchronizes resource metadata; remote tree execution still uses Orchetree’s prompts, policies, connectors, and resolved AI connection.

Options

tool() requires a display name, description, and input schema.

node() accepts:

Option	Required	Purpose
`tree`	yes	Name of the tree that owns the node
`capability`	yes	Capability label shown in the editor
`business_prompt`	no	Business-owned goal and domain instructions
`system_prompt`	no	System-level model instructions
`execution_prompt`	no	Runtime procedure and constraints
`examples`	no	Few-shot examples
`output_prompt`	no	Expected output shape or formatting

Call tool() and node() at module top level. The SDK uses the call stack to identify the source file, so wrapping registrations inside unrelated closures can make source identity less reliable.

Synchronize

import { sync } from "orchetree";

const summary = await sync({
  url: "http://localhost:8000",
  projectId: 1,
});

console.log(summary.created, summary.updated, summary.deactivated);

sync() checks /api/v1/health, sends the current registry to the backend, and returns:

interface SyncSummary {
  synced: number;
  created: number;
  updated: number;
  deactivated: number;
}

Set ORCHETREE_URL to configure the default backend URL.

Watch source files

import { watch } from "orchetree";

watch({
  url: "http://localhost:8000",
  projectId: 1,
  directory: "./src",
});

watch() monitors JavaScript and TypeScript files, ignores node_modules and dist, and debounces synchronization by 200 milliseconds. Install chokidar if it is not already present:

npm install chokidar

CLI

orchetree sync --url=http://localhost:8000 --project-id=1
orchetree watch --url=http://localhost:8000 --project-id=1 --dir=./src

The CLI provides sync and watch, with --url, --project-id, and --dir options.

Synchronization rules

Source IDs are derived from the absolute file path, function name, and tree name for nodes, using the same algorithm as the Python SDK.
Repeated syncs update existing SDK-managed resources.
Removed registrations become sdk_inactive; they are not hard-deleted.
Interface-managed prompt edits are preserved during subsequent structure synchronization.
Python and Node.js registrations can coexist in the same Orchetree project.

See Creating nodes, AI connections, and Runs and traces.