@polyweave/meta-bt-harness (1.0.2)

Published 2026-07-10 23:48:11 +00:00 by Dvorak

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/meta-bt-harness@1.0.2

or add it to the package.json file:

"@polyweave/meta-bt-harness": "1.0.2"

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

meta-bt-harness

Meta harness that searches over BT harness specs and returns the strongest scored candidate.

Published as @polyweave/meta-bt-harness.

Synopsis

import { createMetaBtHarnessTool } from '@polyweave/meta-bt-harness';

const tool = createMetaBtHarnessTool({
  apiKey: process.env.API_KEY,
  model: 'deepseek-v4-flash',
  evaluator: myEvaluatorAdapter,
  proposals: 8,
  maxImprovements: 3
});

tool.sink.write({ type: 'TOOL_CALL', content: { task: 'Optimize sorting pipeline' } });
tool.source.pipe(mySink);

Install

npm install @polyweave/meta-bt-harness

Description

The meta-bt-harness implements a meta-optimization harness that searches over behavior tree specifications. Given a task description and a base spec, it generates multiple candidate BT specs, evaluates each one (either through a provided evaluator adapter or a built-in structural quality heuristic), and promotes the highest-scoring candidate through iterative improvement.

The process is multi-objective: candidate specs are compared using Pareto dominance (each objective score dimension must be at least as good, with at least one strictly better). The built-in default evaluator scores specs on structural quality — number of actions, conditions, symbols, and checks.

The behavior tree spec (META_BT_SPEC) orchestrates: propose candidate specs → evaluate each → compare against best → promote if dominant. The loop terminates when maximum improvements are reached or no further improvement is found.

API

`createMetaBtHarnessTool(options)`

Creates a meta behavior tree harness tool.

Parameters:

options.apiKey — API key for LLM calls.
options.model — Model name (default 'deepseek-v4-flash').
options.task — Task description for spec generation.
options.baseSpec — Base BT spec to improve upon.
options.evaluator — Evaluator adapter (duplex or callback (payload, callback)) for scoring generated specs. Falls back to structural quality heuristic.
options.proposals — Number of candidate specs to generate per improvement iteration (default 8).
options.maxImprovements — Maximum improvement iterations (default 3).
options.objectiveLabels — Labels for multi-objective score dimensions.
options.createAdapter — Custom adapter factory.
options.adapterConfig — Adapter factory configuration.
options.debug — Enable debug output.

TOOL_CALL args: { task, baseSpec, proposals, maxImprovements } — Can override constructor options.

Returns: { source, sink, close }

Events on source:

TOOL_RESULT — Final result with { bestSpec, bestScore, objectiveScores, history, improvements }.

`META_BT_SPEC`

The behavior tree specification string for the meta harness. Defines the propose → evaluate → compare → promote pipeline with multi-objective dominance scoring.

`dominatesObjectives(a, b)`

Compares two objective score arrays using Pareto dominance.

Parameters:

a — number[] candidate scores.
b — number[] current best scores.
Both arrays must have the same non-zero length.

Returns: boolean — True if a dominates b (all elements >=, at least one >).

Examples

// With a custom evaluator adapter
const evaluator = {
  source: { pipe(s) { this._sink = s; } },
  sink: {
    write(frame) {
      if (frame.type === 'TOOL_CALL') {
        const result = runSpecAgainstTestHarness(frame.content.spec);
        const sink = this._sink;
        if (sink) sink.write({ type: 'TOOL_RESULT', content: result });
      }
    }
  }
};

const tool = createMetaBtHarnessTool({
  apiKey: process.env.API_KEY,
  evaluator,
  task: 'Generate a code review BT spec',
  baseSpec: existingSpec,
  proposals: 12,
  maxImprovements: 5
});

// Tick-driven operation
tool.sink.write({ type: 'TOOL_CALL', content: { task: 'My task' } });
tool.sink.write({ type: 'TICK' });
tool.sink.write({ type: 'CANCEL' });

Tests

npm test

Tests cover meta harness creation with evaluator and without (default heuristic), spec proposal generation, Pareto dominance scoring, multi-objective comparison, candidate promotion, history tracking, improvement iteration limits, and tick/CANCEL/ABORT handling.

Requirements

Node.js 18 or later. ESM only.

Caveats

The default evaluator is a structural heuristic and does not execute generated specs against real test harnesses. For meaningful evaluation, provide a custom evaluator adapter that runs actual test scenarios.
Pareto dominance requires equal-length objective score arrays. Ensure evaluators produce consistent score dimensions.
Generated specs must pass parseBtSpec validation; invalid specs receive a score of 0.

License

MIT

Dependencies

ID	Version
@polyweave/bt-harness	*
@polyweave/state	*

Development Dependencies

ID	Version
@rigor/core	*

Peer Dependencies

ID	Version
@polyweave/core	*

polyweave meta-harness behavior-tree optimization llm

Details

npm

2026-07-10 23:48:11 +00:00

John Dvorak

SEE LICENSE IN LICENSE

7.5 KiB

Assets (1)

meta-bt-harness-1.0.2.tgz 7.5 KiB

Versions (3) View all

1.0.3

2026-07-11

1.0.2

2026-07-10

1.0.1