Polyweave

Repositories

1

Projects Packages

@polyweave/nursery (1.0.2)

Published 2026-07-10 19:54:56 +00:00 by Dvorak

Installation

Set up this registry in your project .npmrc file:

@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/

To install the package using npm, run the following command:

npm install @polyweave/nursery@1.0.2

or add it to the package.json file:

"@polyweave/nursery": "1.0.2"

For more information on the npm registry, see the documentation.

About this package

nursery

Reliability-economic protocol grower for Polyweave harnesses.

Published as @polyweave/nursery.

Synopsis

import { createNurseryTool, growProtocol, scoreProtocolCandidate } from '@polyweave/nursery';

const tool = createNurseryTool({
  executionGraph: myGraph,
  scoringProfile: { /* custom weights */ }
});

tool.sink.write({ type: 'TOOL_CALL', content: { domain: myDomain, seeds: mySeeds } });
tool.source.pipe(mySink);

Install

npm install @polyweave/nursery

Description

The nursery package implements a reliability-economic protocol grower — a system that scores, evolves, and selects Polyweave behavior tree protocols (BT specs) based on multi-objective optimization. It evaluates protocol candidates against calibration instances from a domain specification, computing weighted scores across dimensions like reliability gain, validity rate, quorum consensus, temperature diversity, correction/corruption efficiency, and cost.

The package provides two main entry points: createNurseryTool, a frame duplex tool for synchronous protocol growing, and createNurseryGrowTool, a bt-harness-driven loop that uses sampler-based variant generation with redflag filtering and quorum voting for iterative protocol improvement. A domain specification system (createDomainFromSpec) generates calibration instances from structured domain definitions, and JS escape hatches allow domain authors to embed custom validation logic.

API

createNurseryTool(options)

Creates a frame duplex tool for protocol growing.

Parameters:

• options.executionGraph — Execution graph for tracking protocol runs.
• options.scoringProfile — Custom scoring weight profile (see DEFAULT_SCORING_PROFILE).
• options.* — All options are passed through to growProtocol.

TOOL_CALL args: { domain, seeds, scoringProfile, ... }

Returns: { source, sink }

createNurseryGrowTool(options)

Creates a bt-harness-driven nursery grow loop tool. Uses sampler variants, redflag filtering, quorum voting, and experience-based refinement.

Parameters:

• options.apiKey — API key for LLM calls.
• options.model — Model name.
• options.domain or options.domainSpec — Domain definition for calibration instances.
• options.initialSpec — Starting BT spec.
• options.scoringProfile — Custom scoring weight profile.
• options.packageInventory — Polyweave package inventory with role descriptions.
• options.executionGraph — Execution graph.
• options.maxImprovements — Maximum refinement iterations.
• options.patience — Stagnation patience.
• options.debug — Debug output.

Returns: { source, sink, close }

growProtocol(options)

Synchronous protocol growing function. Evaluates seed candidates, scores them, and returns the best.

Parameters:

• options.domain — Domain specification object.
• options.seeds — Array of BT spec string candidates.
• options.scoringProfile — Scoring weights (defaults to DEFAULT_SCORING_PROFILE).
• options.executionGraph — Execution graph.

Returns: { bestSpec, bestScore, scores, history, metadata }

scoreProtocolCandidate(spec, instances, options)

Scores a single BT specification against calibration instances.

Parameters:

• spec — BT spec string.
• instances — Array of calibration instance objects.
• options.scoringProfile — Scoring weights.
• options.executionGraph — Execution graph.

Returns: { score, objectiveScores, dimensions, traces }

defaultProtocolSeeds

Array of default seed BT specs for initial protocol generation.

createDomainFromSpec(domainSpec, options)

Creates a domain object from a specification, producing calibration instances.

Parameters:

• domainSpec — Domain specification with type system, goals, methods, primitives.
• options.jsEscapeHatch — JS escape hatch for custom validation logic.

Returns: { generateInstances(count, seed), validate(spec, instances) }

DEFAULT_PACKAGE_ROLES

Array of Polyweave package names with their roles in the protocol ecosystem. Used for inventory-aware protocol scoring.

summarizePackageInventory(inventory)

Summarizes a package inventory into a compact format for prompt context.

NURSERY_GROW_SPEC

BT spec string for the nursery grow loop: generate variants → redflag → quorum → score → promote.

Prompt Builders

• buildBtHarnessSystemPrompt(options) — Builds the system prompt for bt-harness protocol generation.
• buildBtHarnessFeedbackPrompt(options) — Builds the feedback prompt with scoring context.
• buildDomainContextForPrompt(domain, inventory) — Builds domain-aware context.

Examples

// Domain-driven protocol growing
import { createDomainFromSpec } from '@polyweave/nursery';

const domainObj = createDomainFromSpec(myDomainSpec);
const instances = domainObj.generateInstances(50, 42);

const result = growProtocol({
  domain: myDomainSpec,
  seeds: defaultProtocolSeeds,
  scoringProfile: { objectiveWeights: { validRate: 5.0, costEfficiency: 4.0 } }
});
console.log('Best spec:', result.bestSpec);
console.log('Score:', result.bestScore);

// Grow loop with tick-driven advancement
const tool = createNurseryGrowTool({
  apiKey: process.env.API_KEY,
  domain: myDomain,
  initialSpec: baseSpec,
  maxImprovements: 10,
  patience: 3
});

tool.sink.write({ type: 'TOOL_CALL', content: {} });
tool.sink.write({ type: 'TICK' });

Tests

npm test

Tests cover protocol scoring against calibration instances, domain instance generation, nursery tool creation and execution, grow loop lifecycle, scoring profile customization, seed evaluation, and growth with various domain configurations.

Requirements

Node.js 18 or later. ESM only.

Caveats

• Protocol scoring is an approximation; actual reliability depends on real-world execution against diverse inputs.
• Domain specifications require careful construction — poorly calibrated domains produce misleading scores.
• The execution graph is optional but recommended for tracking protocol provenance and scoring traces.
• Large calibration instance sets increase scoring time linearly; consider sampling for large domains.

License

MIT

Dependencies

Dependencies

ID	Version
@polyweave/bt-harness	*
@polyweave/core	*
@polyweave/creativity	*
@polyweave/execution-graph	*
@polyweave/protocol-metrics	*
@polyweave/quorum	*
@polyweave/redflag	*
@polyweave/sampler	*
@polyweave/self-improving	*
@polyweave/state	*
@polyweave/uncertainty	*

Development Dependencies

ID	Version
@rigor/core	*

Peer Dependencies

ID	Version
@polyweave/agent-loop	*
@polyweave/feedback-descent	*
@polyweave/flex	*
@polyweave/grpo	*
@polyweave/harness-base	*
@polyweave/meta-bt-harness	*
@polyweave/pool	*
@polyweave/prompt-manager	*
@polyweave/routing	*
@polyweave/smart-templates	*
@polyweave/state-search	*
@polyweave/tool-adapter	*
@polyweave/tools	*

Keywords

polyweave nursery protocol optimization

Details

npm

2026-07-10 19:54:56 +00:00

10

John Dvorak

SEE LICENSE IN LICENSE

30 KiB

Assets (1)

nursery-1.0.2.tgz 30 KiB

Versions (3) View all

1.0.6 2026-07-11

1.0.3 2026-07-11

1.0.2 2026-07-10