Polyweave
Repositories
1
 Projects Packages

@polyweave/self-improving (1.0.2)

Published 2026-07-10 22:04:26 +00:00 by Dvorak

Installation

@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/
npm install @polyweave/self-improving@1.0.2
"@polyweave/self-improving": "1.0.2"

About this package

self-improving

Self-improving prompt optimization loops (GEPA + Training-Free GRPO).

Published as @polyweave/self-improving.

Synopsis

import {
  createGepaLoop,
  createTrainingFreeGrpoLoop,
  createCombinedLoop,
  createFeedbackDescentLoop,
  createDiversityFilter,
  cosineDistance
} from '@polyweave/self-improving';

const loop = createGepaLoop({
  initialPrompts: { system: 'You are a helpful assistant.' },
  trainset: trainingExamples,
  valset: validationExamples,
  iterations: 5,
  rollout: myRolloutFn,
  score: myScoreFn,
  proposeNewTexts: myPrompterFn
});

loop.run((err, result) => {
  console.log('Best prompt:', result.candidate);
});

Install

npm install @polyweave/self-improving

Description

The self-improving package implements optimization loops that automatically improve LLM prompts (system prompts, few-shot examples, etc.) through iterative trial-and-error. Rather than requiring gradient-based fine-tuning, these algorithms use LLM "rollouts" (generation attempts) scored against a training/validation dataset to iteratively propose better prompt text.

Five primary optimization strategies are provided:

  • GEPA (Generative Evolutionary Prompt Algorithm) — Evolutionary approach using Pareto-front candidate selection, module-level text mutation, batch evaluation, and reflective dataset generation.
  • Training-Free GRPO — Group-based rollout optimization accumulating successful outputs into an experience library, with epsilon-greedy exploration.
  • Combined Loop — Interleaved GEPA + GRPO, where GRPO's experience library feeds into GEPA's rollouts for richer generation.
  • Feedback Descent — Iterative propose→evaluate refinement of text artifacts using accumulated critique.
  • Diversity Filter — Post-hoc pruning of candidate prompts to maintain semantic diversity using embedding distance.

Additional modules include ACE (Automatic Chain-of-thought Elicitation), RSA (Rational Speech Acts reasoning), Flex integration, Brew (prompt brewing), Supermemory integration, Gleuth (Sleuth-based improvement), INCO (In-Context Optimization), and various HGN wrappers.

API

createGepaLoop(options)

Creates a GEPA optimization loop.

Parameters:

  • options.initialPrompts — Starting prompt { system, user? }.
  • options.trainset — Training examples for rollout scoring.
  • options.valset — Validation examples for final selection.
  • options.iterations — Number of GEPA iterations (default 5).
  • options.minibatchSize — Batch size for candidate evaluation (default 8).
  • options.candidateSelector — 'pareto' or 'best' (default 'pareto').
  • options.moduleSelector — 'round-robin' or 'random' (default 'round-robin').
  • options.rollout(prompt, item, done) — Function executing a rollout and calling done(err, { output, metadata }).
  • options.score(item, output, done) — Function scoring an output and calling done(err, score).
  • options.proposeNewTexts(candidate, batchScores, done) — Function proposing new prompt texts.
  • options.makeReflectiveDataset(candidate, items) — Optional function for reflective dataset generation.
  • options.shouldPromote(candidate, best) — Optional promotion predicate.
  • options.batchSampler(dataset, size) — Optional batch sampling strategy.
  • options.rng — Seeded random number generator for reproducibility.

Returns: { run(dataset, done), getBestCandidate, getHistory }

createTrainingFreeGrpoLoop(options)

Creates a Training-Free GRPO loop.

Parameters:

  • options.groupSize — Candidates per item (default 4).
  • options.epochs — Number of passes over dataset (default 1).
  • options.epsilon — Exploration rate for epsilon-greedy (default 0.1).
  • options.rollout, options.score — Same signatures as GEPA.
  • options.initialExperiences — Seed experience library.
  • options.rng — Seeded random number generator.

Returns: { runEpoch(batch, done), getExperienceLibrary, setExperienceLibrary }

createCombinedLoop(options)

Creates a combined GEPA + GRPO loop.

Parameters:

  • options.gepa — GEPA options (without rollout, which is auto-wired).
  • options.grpo — GRPO options.
  • options.iterations — Number of combined iterations (default 3).

Returns: { run(dataset, done), getBestCandidate, getExperienceLibrary }

createFeedbackDescentLoop(options)

Creates a feedback descent optimization loop.

Parameters:

  • options.initialArtifact — Starting text.
  • options.maxIterations — Maximum refinement iterations.
  • options.patience — Stagnation patience.
  • options.propose(artifact, critique, done) — Generates an improved version.
  • options.evaluate(candidate, current, done) — Evaluates the candidate.

Returns: { run(done), getBest }

createDiversityFilter(options)

Creates a diversity-based candidate pruner.

Parameters:

  • options.threshold — Cosine distance threshold (default 0.35).
  • options.embeddingFn(text) — Optional embedding function.

Returns: { filter(candidates): { kept, pruned } }

Utilities

  • cosineDistance(a, b) — Cosine distance between two vectors.
  • computeParetoFront(candidates) — Computes the Pareto frontier from multi-objective candidate scores.
  • sampleDataset(dataset, size, rng) — Randomly samples a dataset.
  • invokeMaybeFrame(handler, payload, callback) — Invokes an adapter (duplex or callback).

Other Optimization Loops

  • createAceLoop(options) — Automatic Chain-of-thought Elicitation.
  • createRsaLoop(options) — Rational Speech Acts reasoning optimization.
  • createFlexLoop(options) — FLEX integration for experience-based improvement.
  • createBrewLoop(options) — Prompt brewing from compositional ingredients.
  • createSupermemoryLoop(options) — Supermemory-enabled improvement.
  • createSleuthLoop(options) — Sleuth retrieval-enhanced improvement.
  • createIncoLoop(options) — In-Context Optimization.
  • createLoopHgnLoop(options) — HGN domain-driven optimization.
  • createUncertaintyHgnLoop(options) — Uncertainty-driven HGN optimization.

GEPA-specific Utilities

  • createGepaEvaluator(options) — Creates an evaluator adapter for GEPA candidate scoring.
  • createGepaDiversityReducer(options) — Creates a diversity reducer for GEPA prompt proposals.

Judge Utilities

  • createJudgeTool(options) — Creates pairwise/ranking judge tools.
  • createPairwiseEvaluator(options) — Pairwise comparison evaluator.

Examples

// GEPA loop with custom scoring
const rollout = (prompt, item, done) => {
  llmAdapter.sink.write(textFrame(prompt.system + '\n\n' + item.input));
  collectResponse(llmAdapter.source, done);
};

const score = (item, output, done) => {
  const correct = output.trim() === item.expected.trim();
  done(null, correct ? 1.0 : 0.0);
};

const loop = createGepaLoop({
  initialPrompts: { system: 'Answer the question concisely.' },
  trainset: [{ input: '2+2', expected: '4' }],
  iterations: 10,
  rollout,
  score,
  proposeNewTexts: myPrompter
});

// Combined GEPA + GRPO loop
const loop = createCombinedLoop({
  gepa: {
    initialPrompts: basePrompt,
    trainset,
    proposalAdapter: myLlm,
    scoreAdapter: myScorer
  },
  grpo: {
    groupSize: 8,
    epochs: 3
  },
  iterations: 5
});

loop.run(dataset, (err, result) => {
  console.log('Best prompt:', result.candidate.system);
  console.log('Experience entries:', result.experienceLibrary.length);
});

Tests

npm test

Tests cover GEPA loop creation and execution, candidate selection strategies, Pareto frontier computation, minibatch evaluation, module-level text mutation, reflective dataset generation, GRPO loop epochs and experience accumulation, combined loop interleaving, diversity filtering, cosine distance computation, dataset sampling, and all utility functions.

Requirements

Node.js 18 or later. ESM only.

Caveats

  • All loops require injected rollout and scoring functions; these must be idempotent and handle concurrency safely.
  • GEPA is computationally intensive — each iteration runs minibatchSize × candidates rollouts. Budget accordingly.
  • Epsilon-greedy exploration in GRPO requires a diverse experience library to be effective; too-small libraries cause over-exploitation.
  • Seed control via rng is recommended for reproducible optimization runs.
  • Score functions should be normalized (0 to 1 range) for consistent Pareto-front selection.

License

MIT

Dependencies

Dependencies

ID Version
@polyweave/pool *
@polyweave/state *
@polyweave/tools *
@polyweave/uncertainty *
syllable-count-english ^1.0.6

Development Dependencies

ID Version
@rigor/core *

Peer Dependencies

ID Version
@polyweave/core *
@polyweave/smart-templates *

Keywords

polyweave prompt optimization gepa training-free grpo
Details
npm
2026-07-10 22:04:26 +00:00
344
John Dvorak
SEE LICENSE IN LICENSE
39 KiB
Assets (1)
self-improving-1.0.2.tgz 39 KiB
Versions (3) View all
1.0.3 2026-07-11
1.0.2 2026-07-10
1.0.1 2026-07-10