@polyweave/flex (1.0.2)

Published 2026-07-10 23:46:06 +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/flex@1.0.2

or add it to the package.json file:

"@polyweave/flex": "1.0.2"

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

flex

FLEX (Feedback Learning from EXperience) as a bt-harness tool.

Published as @polyweave/flex.

Synopsis

import { createFlexTool } from '@polyweave/flex';

const tool = createFlexTool({
  apiKey: process.env.API_KEY,
  model: 'deepseek-v4-flash',
  dataset: ['Write a sorting function', 'Handle null inputs', 'Add error logging'],
  retriever: myRetrieverAdapter,
  explorer: myExplorerAdapter,
  scorer: myScorerAdapter,
  updater: myUpdaterAdapter
});

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

Install

npm install @polyweave/flex

Description

FLEX (Feedback Learning from EXperience) is a behavior-tree-driven experience accumulation framework for LLM agents. It processes a dataset of items through a four-stage pipeline: retrieve relevant past experiences from a golden/warning library, explore to produce an output using those experiences, score the output quality, and update the experience library with new golden or warning entries.

The experience library accumulates "golden" (successful) and "warning" (problematic) entries across iterations. Retrieval, exploration, scoring, and updating can each be handled by injected adapters or fall back to default behavior (library-as-retrieval, passthrough, binary score, direct application).

The behavior tree spec (FLEX_SPEC) defines the sequential pipeline: retrieve → explore → score → update. The tree iterates over items, incrementing @itemIndex on each successful update, until all items are processed.

API

`createFlexTool(options)`

Creates a Polyweave frame duplex tool implementing the FLEX pipeline.

Parameters:

options.apiKey — API key for LLM calls.
options.model — Model name (default 'deepseek-v4-flash').
options.dataset — Array of items to process.
options.retriever — Adapter (function or duplex) for experience retrieval. Falls back to returning current library.
options.explorer — Adapter for generating output from item + retrieved experiences.
options.scorer — Adapter for scoring output quality.
options.updater — Adapter for determining library updates (golden/warning).
options.initialLibrary — Initial experience library { golden: [...], warning: [...] } or array of golden entries.
options.state — External state store { docStore, textStore } for persistence.
options.maxGolden — Maximum golden entries retained (default 200).
options.maxWarning — Maximum warning entries retained (default 200).
options.createAdapter — Custom adapter factory.
options.adapterConfig — Adapter factory configuration.
options.debug — Enable debug output.

TOOL_CALL args: { dataset } — Override or provide a dataset at call time.

Returns: { source, sink, _toolName: 'flex', getLibrary, close }

Methods:

getLibrary() — Returns the current { golden, warning } library.
close() — Closes the internal document store.

Tool calls exposed to agents:

flex_read(sectionId) — Read any document section.
flex_retrieve(item) — Retrieve relevant experiences for an item.
flex_explore(output, experiences, success) — Store exploration output.
flex_score(score) — Store and return score.
flex_update(experiences) — Apply experience updates to the library.
flex_search(query, limit) — Search indexed experiences (requires textStore).

Events on source:

TOOL_RESULT — Final result with { library, itemCount, itemsProcessed, failed }.

Examples

// With external state and pre-populated library
import { createDocumentStore, createTextStore } from '@polyweave/state';

const tool = createFlexTool({
  apiKey: process.env.API_KEY,
  state: { docStore: createDocumentStore(), textStore: createTextStore() },
  initialLibrary: {
    golden: [{ text: 'Use guard clauses for null checks', metadata: { zone: 'golden' } }],
    warning: [{ text: 'Avoid deep nesting in sort functions', metadata: { zone: 'warning' } }]
  },
  dataset: trainingItems,
  retriever: myRetriever
});

tool.getLibrary();
tool.close();

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

Tests

npm test

Tests cover tool instantiation with various options, FLEX pipeline execution over multi-item datasets, experience library accumulation, golden/warning deduplication, adapter fallback behavior, tick-driven advancement, and CANCEL/ABORT handling.

Requirements

Node.js 18 or later. ESM only.

Caveats

Each adapter (retriever, explorer, scorer, updater) can be either a duplex object { source, sink } or a callback function (payload, callback). Duplex adapters are preferred for streaming support.
The experience library is bounded by maxGolden and maxWarning. Oldest entries are truncated when limits are exceeded.
Without a textStore, the flex_search tool is not registered and in-library text search is unavailable.
The behavior tree uses maxTreeLoops: 0 and relies on external TICK for item advancement.

License

MIT

Dependencies

ID	Version
@polyweave/bt-harness	*
@polyweave/core	*
@polyweave/loop-utils	*
@polyweave/state	*
@polyweave/tools	*

Development Dependencies

ID	Version
@rigor/core	*

polyweave flex feedback-learning behavior-tree

Details

npm

2026-07-10 23:46:06 +00:00

John Dvorak

SEE LICENSE IN LICENSE

6.7 KiB

Assets (1)

flex-1.0.2.tgz 6.7 KiB

Versions (3) View all

1.0.5

2026-07-11

1.0.2

2026-07-10

1.0.1