@polyweave/feedback-descent (1.0.2)

Published 2026-07-10 23:40:10 +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/feedback-descent@1.0.2

or add it to the package.json file:

"@polyweave/feedback-descent": "1.0.2"

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

feedback-descent

Feedback Descent optimization loop as a bt-harness duplex tool. Iteratively improves text artifacts through propose→evaluate cycles with accumulated critique.

Published as @polyweave/feedback-descent.

Synopsis

import { createFeedbackDescentTool } from '@polyweave/feedback-descent';

const tool = createFeedbackDescentTool({
  apiKey: process.env.API_KEY,
  model: 'deepseek-v4-flash',
  initialArtifact: 'Draft version of text...',
  maxIterations: 10,
  patience: 3
});

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

Install

npm install @polyweave/feedback-descent

Description

Feedback Descent is an iterative optimization loop that improves text artifacts using propose-evaluate cycles driven by a behavior tree harness (@polyweave/bt-harness). An LLM agent proposes improvements to a current "best" artifact based on accumulated critique from prior evaluations. An evaluator LLM judges whether the candidate is better than the current best. If improved, the candidate is promoted; if stagnant, a stagnation counter increments. The loop terminates when the stagnation count reaches the configured patience threshold.

The behavior tree specification (FD_SPEC) defines the structure: propose → evaluate → promote_best (if improved) or increment_stagnant (if not). The tree loops until postcondition @stagnant >= @patience. The tool exposes internal document sections (fd/best, fd/candidate, fd/critique) through dedicated read/propose/evaluate tools that the agent and evaluator call.

API

`createFeedbackDescentTool(options)`

Creates a Polyweave frame duplex tool for Feedback Descent optimization.

Parameters:

options.apiKey — API key for LLM calls.
options.model — Model name (default 'deepseek-v4-flash').
options.initialArtifact — Starting artifact text.
options.maxIterations — Maximum promote cycles (default 10).
options.patience — Stagnation threshold before termination (default 3).
options.createAdapter — Custom adapter factory function.
options.adapterConfig — Configuration passed to the adapter factory.
options.debug — Enable debug output.

TOOL_CALL args: { initialArtifact, maxIterations, patience }

Returns: { source, sink, _toolName: 'feedback_descent', getBest, close }

Events on source:

bt:tree_complete — Optimization finished successfully. Result includes artifact and iterations.
bt:tree_failed — Optimization failed. Result includes artifact and failed: true.
bt:error — Error during execution.

Methods:

getBest() — Returns the current best artifact text synchronously.
close() — Closes the internal document store.

`FD_SPEC`

The behavior tree specification string (exported for inspection). Defines the propose → evaluate → promote/stagnate tree with symbolic state tracking (@iteration, @stagnant, @preferred, @done).

Examples

// With custom initial artifact and patience
const tool = createFeedbackDescentTool({
  apiKey: process.env.API_KEY,
  initialArtifact: 'function add(a, b) { return a + b; }',
  maxIterations: 20,
  patience: 5
});

tool.sink.write({
  type: 'TOOL_CALL',
  content: { maxIterations: 15, patience: 3 }
});

const sink = createFrameSink((frame) => {
  if (frame.type === 'TOOL_RESULT') {
    console.log('Final artifact:', frame.content.artifact);
  }
});
tool.source.pipe(sink);

// Tick-driven operation
tool.sink.write({ type: 'TOOL_CALL', content: {} });
// Advance each tick:
tool.sink.write({ type: 'TICK' });
// Cancel:
tool.sink.write({ type: 'CANCEL' });

Tests

npm test

Tests cover tool creation, propose-evaluate-promote cycle, stagnation-driven termination, custom maxIterations/patience from TOOL_CALL args, getBest() during and after execution, CANCEL/ABORT handling, and error propagation.

Requirements

Node.js 18 or later. ESM only.

Caveats

Requires a valid apiKey or createAdapter for LLM model access. Without both, the harness will fail to initialize.
The behavior tree uses maxTreeLoops: 0 and relies on the postcondition (@stagnant >= @patience) to terminate, which is checked per-tick. Ensure TICK frames are delivered if using tick-driven operation.
Results are stored in an in-memory document store and are not persisted across restarts.

License

MIT

Dependencies

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

Development Dependencies

ID	Version
@rigor/core	*

Peer Dependencies

ID	Version
@polyweave/core	*

polyweave feedback-descent behavior-tree optimization llm

Details

npm

2026-07-10 23:40:10 +00:00

John Dvorak

SEE LICENSE IN LICENSE

5.2 KiB

Assets (1)

feedback-descent-1.0.2.tgz 5.2 KiB

Versions (3) View all

1.0.5

2026-07-11

1.0.2

2026-07-10

1.0.1