Polyweave
Repositories
1
 Projects Packages

@polyweave/sampler (1.0.5)

Published 2026-07-11 15:31:45 +00:00 by Dvorak

Installation

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

About this package

@polyweave/sampler

Prompt decorrelation and test-time sampling utilities — generates unique nonce tags to decorrelate LLM prompt variants for diversity-gated sampling.

Synopsis

import { createSampler, createSampleTag, createDecorrelatedPrompt, createSampleVariants, DEFAULT_WORDS } from '@polyweave/sampler';

const sampler = createSampler({ words: ['alpha', 'beta', 'gamma'] });

const tag = sampler.sampleTag();
// { id: 'uuid-...', uuids: ['uuid-...'], words: ['alpha', 'gamma', 'beta'], index: null, temperature: null, promptVariant: null }

const decorated = sampler.decoratePrompt('What is the capital of France?');
// { prompt: '[POLYWEAVE_SAMPLE uuid-... alpha-gamma-beta]\nUse this nonce only to decorrelate sampling; do not mention it in the answer.\n\nWhat is the capital of France?', prefix: '[POLYWEAVE_SAMPLE uuid-... alpha-gamma-beta]', tag: { ... } }

const variants = sampler.variants('Explain gravity', 3);
// Array of 3 decorrelated prompt variants, each with a unique tag and index

Install

npm install @polyweave/sampler

Why

When calling an LLM multiple times with the same prompt, LLMs often return identical or near-identical outputs. This package decorrelates prompt variants by prepending a unique [POLYWEAVE_SAMPLE <uuid> <words>] nonce prefix. The nonce does not modify the semantic meaning of the prompt — it only breaks token-level determinism so that multiple samples are genuinely diverse. This is critical for Monte Carlo sampling, ensemble voting, and diversity-gated LLM workflows.

API

createSampler(options)

Convenience factory that returns a bound sampler object with three methods. The options provide defaults that can be overridden per call.

Name Type Required Default Description
options object no {} Base options forwarded to each method call.

Returns: { sampleTag, decoratePrompt, variants }

  • sampler.sampleTag(overrides = {}) — Calls createSampleTag({ ...options, ...overrides }).
  • sampler.decoratePrompt(prompt, overrides = {}) — Calls createDecorrelatedPrompt(prompt, { ...options, ...overrides }).
  • sampler.variants(prompt, count, overrides = {}) — Calls createSampleVariants(prompt, count, { ...options, ...overrides }).

createSampleTag(options)

Generates a nonce tag with randomly selected words and UUIDs.

Name Type Required Default Description
options.words string[] no DEFAULT_WORDS Word list to pick from.
options.wordCount number no 3 Number of words to sample.
options.uuidCount number no 1 Number of UUIDs to generate.
options.random function no Math.random PRNG function returning [0,1).
options.uuid function no crypto.randomUUID or fallback UUID generator function.
options.index number or null no null Optional variant index.
options.temperature number or null no null Optional temperature hint.
options.promptVariant any or null no null Optional variant identifier.

Returns: { id, uuids, words, index, temperature, promptVariant }

Field Type Description
id string Joins all UUIDs with : delimiter.
uuids string[] Array of generated UUIDs.
words string[] Array of randomly picked words.
index number or null Index from options.
temperature number or null Temperature from options.
promptVariant any or null Variant identifier from options.

Error conditions:

  • Error('wordCount must be a positive integer') — when wordCount is not a finite integer >= 1.
  • Error('uuidCount must be a positive integer') — when uuidCount is not a finite integer >= 1.

createDecorrelatedPrompt(prompt, options)

Prepends a nonce prefix and decorrelation instruction to a prompt string.

Name Type Required Default Description
prompt string no '' The prompt text to decorate.
options.marker string no 'POLYWEAVE_SAMPLE' Tag name used in the prefix.
options.instruction string no 'Use this nonce only to decorrelate sampling; do not mention it in the answer.' Instruction prepended after the nonce.
options object no {} All other options forwarded to createSampleTag.

Returns: { prompt, prefix, tag }

Field Type Description
prompt string Full decorated prompt: [MARKER UUID WORDS]\nINSTRUCTION\n\nPROMPT.
prefix string The prefix portion: [MARKER UUID WORDS].
tag object The tag object returned by createSampleTag.

Error conditions: Propagates any error from createSampleTag (see createSampleTag error conditions).

createSampleVariants(prompt, count, options)

Generates count decorrelated prompt variants.

Name Type Required Default Description
prompt string no '' The prompt text to decorate for each variant.
count number yes 1 Number of variants to generate.
options object no {} Options forwarded to createDecorrelatedPrompt. An index (0..count-1) is added to each call.

Returns: Array<{ prompt, prefix, tag }> — Array of decorated prompt objects, each with a unique tag and incrementing tag.index.

Error conditions:

  • Error('count must be a positive integer') — when count is not a finite integer >= 1.
  • Propagates any error from createSampleTag or createDecorrelatedPrompt.

DEFAULT_WORDS

Frozen array of 30 words used as default word list for nonce generation.

['amber', 'atlas', 'bamboo', 'binary', 'canyon', 'cedar', 'cipher', 'comet',
 'delta', 'ember', 'falcon', 'fable', 'glacier', 'harbor', 'indigo', 'jigsaw',
 'keystone', 'lantern', 'mesa', 'nebula', 'onyx', 'prairie', 'quartz', 'raven',
 'signal', 'tundra', 'umbra', 'velvet', 'willow', 'zenith']

Tests

npm test

Runs node --test test/*.test.js. Covers tag generation with deterministic inputs (injected random and uuid), prompt decoration format, variant generation with correct count, wordCount/uuidCount validation, and DEFAULT_WORDS immutability.

Requirements

Node.js 22 or later. ESM only. Zero dependencies.

Dependencies

Development Dependencies

ID Version
@rigor/core *

Keywords

polyweave sampler decorrelation llm prompt nonce
Details
npm
2026-07-11 15:31:45 +00:00
83
John Dvorak
SEE LICENSE IN LICENSE
latest
4.1 KiB
Assets (1)
sampler-1.0.5.tgz 4.1 KiB
Versions (4) View all
1.0.5 2026-07-11
1.0.4 2026-07-11
1.0.2 2026-07-11
1.0.0 2026-07-10