@far-world-labs/verblets 0.2.0 → 0.4.0

package/src/chains/bulk-map/index.js

@@ -1,86 +0,0 @@
-import listMap from '../../verblets/list-map/index.js';
-
-/**
- * Map over a list of fragments by calling `listMap` on newline-delimited batches.
- * Missing or mismatched output results in `undefined` entries so callers can
- * selectively retry.
- *
- * @param { string[] } list - array of fragments to process
- * @param { string } instructions - mapping instructions passed to `listMap`
- * @param { object } [config={}] - configuration options
- * @param { number } [config.chunkSize=10] - how many items to send per batch
- * @param { object } [config.llm] - LLM configuration
- * @returns { Promise<(string|undefined)[]> } results aligned with input order
- */
-const bulkMap = async function (list, instructions, config = {}) {
-  const { chunkSize = 10, llm, ...options } = config;
-  const results = new Array(list.length);
-  const promises = [];
-
-  for (let i = 0; i < list.length; i += chunkSize) {
-    const batch = list.slice(i, i + chunkSize);
-    const startIndex = i;
-
-    const p = Promise.resolve()
-      .then(() => listMap(batch, instructions, { llm, ...options }))
-      .then((output) => {
-        if (output.length !== batch.length) {
-          for (let j = 0; j < batch.length; j += 1) {
-            results[startIndex + j] = undefined;
-          }
-          return;
-        }
-        output.forEach((line, j) => {
-          results[startIndex + j] = line;
-        });
-      })
-      .catch(() => {
-        for (let j = 0; j < batch.length; j += 1) {
-          results[startIndex + j] = undefined;
-        }
-      });
-    promises.push(p);
-  }
-
-  await Promise.all(promises);
-  return results;
-};
-
-/**
- * Retry only the undefined results from `map` until maxAttempts is reached.
- *
- * @param { string[] } list - array of fragments
- * @param { string } instructions - mapping instructions passed to `listMap`
- * @param { object } [config={}] - configuration options
- * @param { number } [config.chunkSize=10]
- * @param { number } [config.maxAttempts=3]
- * @param { object } [config.llm] - LLM configuration
- * @returns { Promise<(string|undefined)[]> }
- */
-export const bulkMapRetry = async function (list, instructions, config = {}) {
-  const { chunkSize = 10, maxAttempts = 3, llm, ...options } = config;
-  const results = await bulkMap(list, instructions, { chunkSize, llm, ...options });
-  for (let attempt = 1; attempt < maxAttempts; attempt += 1) {
-    const missingIdx = [];
-    const missingFragments = [];
-    results.forEach((val, idx) => {
-      if (val === undefined) {
-        missingIdx.push(idx);
-        missingFragments.push(list[idx]);
-      }
-    });
-    if (missingFragments.length === 0) break;
-    // eslint-disable-next-line no-await-in-loop
-    const retryResults = await bulkMap(missingFragments, instructions, {
-      chunkSize,
-      llm,
-      ...options,
-    });
-    retryResults.forEach((val, i) => {
-      results[missingIdx[i]] = val;
-    });
-  }
-  return results;
-};
-
-export default bulkMap;

package/src/chains/bulk-map/index.spec.js

@@ -1,44 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import bulkMap, { bulkMapRetry } from './index.js';
-import listMap from '../../verblets/list-map/index.js';
-
-vi.mock('../../verblets/list-map/index.js', () => ({
-  default: vi.fn(async (items, instructions) => {
-    if (items.includes('FAIL')) throw new Error('fail');
-    return items.map((i) => `${i}-${instructions}`);
-  }),
-}));
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe('bulkmap', () => {
-  it('maps fragments in batches', async () => {
-    const result = await bulkMap(['a', 'b', 'c'], 'x', { chunkSize: 2 });
-    expect(result).toStrictEqual(['a-x', 'b-x', 'c-x']);
-    expect(listMap).toHaveBeenCalledTimes(2);
-  });
-
-  it('leaves undefined on error', async () => {
-    listMap.mockRejectedValueOnce(new Error('fail'));
-    const result = await bulkMap(['FAIL', 'oops'], 'x', { chunkSize: 2 });
-    expect(result).toStrictEqual([undefined, undefined]);
-  });
-
-  it('retries only failed fragments', async () => {
-    let call = 0;
-    listMap.mockImplementation(async (items) => {
-      call += 1;
-      if (call === 1) throw new Error('fail');
-      return items.map((l) => l.toUpperCase());
-    });
-
-    const result = await bulkMapRetry(['alpha', 'beta'], 'upper', {
-      chunkSize: 2,
-      maxAttempts: 2,
-    });
-    expect(result).toStrictEqual(['ALPHA', 'BETA']);
-    expect(listMap).toHaveBeenCalledTimes(2);
-  });
-});

package/src/chains/bulk-reduce/README.md

@@ -1,12 +0,0 @@
-# bulk-reduce
-
-Reduce long lists by processing them in smaller batches. Each batch is combined
-with the accumulated result using `listReduce`.
-
-```javascript
-import bulkReduce from './index.js';
-
-const logs = ['step one', 'step two', 'step three'];
-const result = await bulkReduce(logs, 'summarize');
-// => 'summary of steps'
-```

package/src/chains/bulk-reduce/index.examples.js

@@ -1,15 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import bulkReduce from './index.js';
-import { longTestTimeout } from '../../constants/common.js';
-
-describe('bulk-reduce examples', () => {
-  it(
-    'reduces a long list sequentially',
-    async () => {
-      const items = ['one', 'two', 'three', 'four'];
-      const result = await bulkReduce(items, 'concatenate', { chunkSize: 2 });
-      expect(result).toBeDefined();
-    },
-    longTestTimeout
-  );
-});

package/src/chains/bulk-reduce/index.js

@@ -1,13 +0,0 @@
-import listReduce from '../../verblets/list-reduce/index.js';
-
-export default async function bulkReduce(list, instructions, config = {}) {
-  const { chunkSize = 10, initial, llm, ...options } = config;
-  let acc = initial;
-  for (let i = 0; i < list.length; i += chunkSize) {
-    const batch = list.slice(i, i + chunkSize);
-
-    // eslint-disable-next-line no-await-in-loop
-    acc = await listReduce(acc, batch, instructions, { llm, ...options });
-  }
-  return acc;
-}

package/src/chains/bulk-reduce/index.spec.js

@@ -1,25 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import bulkReduce from './index.js';
-import listReduce from '../../verblets/list-reduce/index.js';
-
-vi.mock('../../verblets/list-reduce/index.js', () => ({
-  default: vi.fn(async (acc, list) => [acc, ...list].filter(Boolean).join('-')),
-}));
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe('bulk-reduce chain', () => {
-  it('reduces in batches', async () => {
-    const result = await bulkReduce(['a', 'b', 'c', 'd'], 'join', { chunkSize: 2 });
-    expect(result).toBe('a-b-c-d');
-    expect(listReduce).toHaveBeenCalledTimes(2);
-  });
-
-  it('uses initial value', async () => {
-    const result = await bulkReduce(['x', 'y'], 'join', { initial: '0', chunkSize: 2 });
-    expect(result).toBe('0-x-y');
-    expect(listReduce).toHaveBeenCalledTimes(1);
-  });
-});

package/src/chains/bulk-score/README.md

@@ -1,16 +0,0 @@
-# bulk-score
-
-Score lines of text on a 0–10 scale with automatic calibration. Each batch returns a JSON array so parsing stays reliable even with long lists. The chain first scores everything, then rescors a few low, middle, and high examples to calibrate. Those references feed a second scoring pass so every item is ranked consistently using OpenAI's JSON schema enforcement.
-
-```javascript
-import bulkScore from './index.js';
-
-const slogans = [
-  'Amazing deals every day!',
-  'Unlock a world of wonder',
-  'Buy stuff now',
-];
-
-const { scores } = await bulkScore(slogans, 'How catchy is this marketing slogan?');
-// scores like [6, 9, 2]
-```

package/src/chains/bulk-score/bulk-score-result.json

@@ -1,18 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "scores": {
-      "type": "array",
-      "description": "Array of numeric scores corresponding to input items",
-      "items": {
-        "type": "number",
-        "minimum": 0,
-        "maximum": 10,
-        "description": "Score from 0 (worst) to 10 (best)"
-      }
-    }
-  },
-  "required": ["scores"],
-  "additionalProperties": false
-} 

package/src/chains/bulk-score/index.examples.js

@@ -1,22 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { longTestTimeout } from '../../constants/common.js';
-import bulkScore from './index.js';
-
-describe('bulkScore examples', () => {
-  it(
-    'ranks jokes by humor',
-    async () => {
-      const jokes = [
-        'Why did the chicken cross the road? To get to the other side!',
-        "Parallel lines have so much in common. It's a shame they'll never meet.",
-        "I told my computer I needed a break, and it said 'I'll go to sleep.'",
-      ];
-
-      const { scores } = await bulkScore(jokes, 'How funny is this joke?');
-
-      expect(scores).toHaveLength(jokes.length);
-      scores.forEach((s) => expect(typeof s).toBe('number'));
-    },
-    longTestTimeout
-  );
-});

package/src/chains/bulk-score/index.js

@@ -1,133 +0,0 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import chatGPT from '../../lib/chatgpt/index.js';
-import wrapVariable from '../../prompts/wrap-variable.js';
-import { constants as promptConstants } from '../../prompts/index.js';
-
-const { onlyJSONArray } = promptConstants;
-
-// Get the directory of this module
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Load the JSON schema for bulk score results
- * @returns {Promise<Object>} JSON schema for validation
- */
-async function getBulkScoreSchema() {
-  const schemaPath = path.join(__dirname, 'bulk-score-result.json');
-  return JSON.parse(await fs.readFile(schemaPath, 'utf8'));
-}
-
-/**
- * Create model options for structured outputs
- * @param {string|Object} llm - LLM model name or configuration object
- * @returns {Promise<Object>} Model options for chatGPT
- */
-async function createModelOptions(llm = 'fastGoodCheap') {
-  const schema = await getBulkScoreSchema();
-
-  const responseFormat = {
-    type: 'json_schema',
-    json_schema: {
-      name: 'bulk_score_result',
-      schema,
-    },
-  };
-
-  if (typeof llm === 'string') {
-    return {
-      modelName: llm,
-      response_format: responseFormat,
-    };
-  } else {
-    return {
-      ...llm,
-      response_format: responseFormat,
-    };
-  }
-}
-
-async function scoreBatch(items, instructions, reference = [], config = {}) {
-  const { llm, ...options } = config;
-  const listBlock = wrapVariable(items.join('\n'), { tag: 'items' });
-  const refBlock = reference.length
-    ? `\nCalibration examples (score - text):\n${wrapVariable(
-        reference.map((r) => `${r.score} - ${r.item}`).join('\n'),
-        { tag: 'reference' }
-      )}`
-    : '';
-
-  const prompt =
-    `Score each line in <items> from 0 (worst) to 10 (best) based on: ${instructions}.` +
-    `\nRespond with a JSON object containing a "scores" array of numbers in the same order.` +
-    `${refBlock}\n${onlyJSONArray}\n${listBlock}`;
-
-  const modelOptions = await createModelOptions(llm);
-  const response = await chatGPT(prompt, {
-    modelOptions,
-    ...options,
-  });
-
-  // With structured outputs, response should already be parsed and validated
-  const parsed = typeof response === 'string' ? JSON.parse(response) : response;
-  // Extract scores from the object structure
-  const arr = parsed?.scores || parsed;
-
-  if (!Array.isArray(arr) || arr.length !== items.length) {
-    throw new Error('Score batch mismatch');
-  }
-  return arr.map((n) => Number(n));
-}
-
-export default async function bulkScore(list, instructions, config = {}) {
-  const { chunkSize = 10, examples, llm, ...options } = config;
-  if (!Array.isArray(list) || list.length === 0) {
-    return { scores: [], reference: [] };
-  }
-
-  const firstScores = [];
-  for (let i = 0; i < list.length; i += chunkSize) {
-    // eslint-disable-next-line no-await-in-loop
-    const scores = await scoreBatch(list.slice(i, i + chunkSize), instructions, [], {
-      llm,
-      ...options,
-    });
-    firstScores.push(...scores);
-  }
-
-  const scored = list.map((item, idx) => ({ item, score: firstScores[idx] }));
-
-  let reference = examples;
-  if (!reference) {
-    const valid = scored.filter((s) => Number.isFinite(s.score));
-    if (valid.length) {
-      valid.sort((a, b) => a.score - b.score);
-      const lows = valid.slice(0, 3);
-      const highs = valid.slice(-3);
-      const midStart = Math.max(0, Math.floor(valid.length / 2) - 1);
-      const mids = valid.slice(midStart, midStart + 3);
-      reference = [...lows, ...mids, ...highs];
-      const refItems = reference.map((r) => r.item);
-      const rescored = await scoreBatch(refItems, instructions, [], { llm, ...options });
-      rescored.forEach((score, idx) => {
-        reference[idx].score = score;
-      });
-    } else {
-      reference = [];
-    }
-  }
-
-  const finalScores = [];
-  for (let i = 0; i < list.length; i += chunkSize) {
-    // eslint-disable-next-line no-await-in-loop
-    const scores = await scoreBatch(list.slice(i, i + chunkSize), instructions, reference, {
-      llm,
-      ...options,
-    });
-    finalScores.push(...scores);
-  }
-
-  return { scores: finalScores, reference };
-}

package/src/chains/bulk-score/index.spec.js

@@ -1,30 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import bulkScore from './index.js';
-import chatGPT from '../../lib/chatgpt/index.js';
-
-vi.mock('../../lib/chatgpt/index.js', () => ({
-  default: vi.fn(),
-}));
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe('bulkScore chain', () => {
-  it('scores items using two passes', async () => {
-    chatGPT
-      .mockResolvedValueOnce('[1,2,3]')
-      .mockResolvedValueOnce('[1,2,3,4,5,6,7,8,9]')
-      .mockResolvedValueOnce('[1,2,3]');
-    const { scores, reference } = await bulkScore(['a', 'bb', 'ccc'], 'length');
-    expect(scores).toStrictEqual([1, 2, 3]);
-    expect(reference.length).toBeGreaterThan(0);
-    expect(chatGPT).toHaveBeenCalled();
-  });
-
-  it('uses provided examples', async () => {
-    chatGPT.mockResolvedValueOnce('[1]').mockResolvedValueOnce('[1]');
-    const { scores } = await bulkScore(['x'], 'length', { examples: [{ item: 'y', score: 2 }] });
-    expect(scores[0]).toBe(1);
-  });
-});

package/src/chains/category-samples/README.md

@@ -1,61 +0,0 @@
-# Category Samples Chain
-
-Generate diverse, representative examples for any category. This chain applies prototype theory and related cognitive science principles to output a well-rounded set of sample items.
-
-## Features
-
-- **Cognitive Science Foundation**: Uses prototype theory and family resemblance principles
-- **Diversity Control**: Configurable diversity levels (focused, balanced, high)
-- **Context Awareness**: Supports contextual constraints for targeted generation
-- **Robust Retry Logic**: Built-in retry mechanisms for reliable generation
-- **Scalable Architecture**: Leverages the list chain infrastructure for efficient processing
-
-## Usage
-
-### Basic Usage
-
-```javascript
-import categorySamples from './src/chains/category-samples/index.js';
-
-// Generate basic fruit samples
-const fruitSamples = await categorySamples('fruit', {
-  count: 5,
-  diversityLevel: 'balanced'
-});
-// Result: ['apple', 'orange', 'durian', 'banana', 'kiwi']
-```
-
-### With Context
-
-```javascript
-// Generate contextually relevant samples
-const birdSamples = await categorySamples('bird', {
-  context: 'Common backyard birds in North America',
-  count: 4,
-  diversityLevel: 'focused'
-});
-// Result: ['robin', 'cardinal', 'blue jay', 'sparrow']
-```
-
-### High Diversity Generation
-
-```javascript
-// Generate diverse vehicle types
-const vehicleSamples = await categorySamples('vehicle', {
-  count: 6,
-  diversityLevel: 'high'
-});
-// Result: ['car', 'bicycle', 'helicopter', 'submarine', 'skateboard', 'spaceship']
-```
-
-## API Reference
-
-### `categorySamples(categoryName, options)`
-
-Returns an array of sample items for the given category. Options let you control diversity, add context, and configure retry logic.
-
-**Common Options**
-
-- `count` (number): How many samples to return (default: 10)
-- `context` (string): Extra context to guide generation
-- `diversityLevel` ('focused' | 'balanced' | 'high'): Adjusts how typical or atypical the samples are

package/src/chains/category-samples/index.examples.js

@@ -1,103 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { longTestTimeout } from '../../constants/common.js';
-import { expect as aiExpect } from '../expect/index.js';
-import categorySamples from './index.js';
-
-describe('Category Samples Chain', () => {
-  it(
-    'generates basic seed items for a category',
-    async () => {
-      const seeds = await categorySamples('fruit', {
-        count: 5,
-        diversityLevel: 'balanced',
-      });
-
-      expect(seeds).toHaveLength(5);
-      expect(seeds.every((seed) => typeof seed === 'string')).toBe(true);
-      expect(seeds.every((seed) => seed.length > 0)).toBe(true);
-
-      // Use expect-chain for loose verification
-      const [isValidFruitList] = await aiExpect(
-        seeds,
-        undefined,
-        'Are these reasonable fruit names that represent a balanced mix of typical and moderately typical fruits?'
-      );
-      expect(isValidFruitList).toBe(true);
-    },
-    longTestTimeout
-  );
-
-  it(
-    'generates seeds with context',
-    async () => {
-      const seeds = await categorySamples('bird', {
-        context: 'Common backyard birds in North America',
-        count: 4,
-        diversityLevel: 'focused',
-      });
-
-      expect(seeds).toHaveLength(4);
-      expect(seeds.every((seed) => typeof seed === 'string')).toBe(true);
-
-      // Use expect-chain for loose verification
-      const [isValidBirdList] = await aiExpect(
-        seeds,
-        undefined,
-        'Are these reasonable names of common backyard birds that would be found in North America?'
-      );
-      expect(isValidBirdList).toBe(true);
-    },
-    longTestTimeout
-  );
-
-  it(
-    'generates diverse seeds with high diversity level',
-    async () => {
-      const seeds = await categorySamples('vehicle', {
-        count: 6,
-        diversityLevel: 'high',
-      });
-
-      expect(seeds).toHaveLength(6);
-      expect(seeds.every((seed) => typeof seed === 'string')).toBe(true);
-
-      // Use expect-chain for loose verification - check for diversity without being overly specific
-      const [isValidVehicleList] = await aiExpect(
-        seeds,
-        undefined,
-        'Are these vehicle names reasonably diverse, showing variety in the types of vehicles represented?'
-      );
-      expect(isValidVehicleList).toBe(true);
-    },
-    longTestTimeout
-  );
-
-  it('throws error for invalid category name', async () => {
-    await expect(categorySamples('')).rejects.toThrow('categoryName must be a non-empty string');
-    await expect(categorySamples(null)).rejects.toThrow('categoryName must be a non-empty string');
-  });
-
-  it(
-    'handles retry logic on failures',
-    async () => {
-      // This test ensures the retry mechanism works
-      const seeds = await categorySamples('animal', {
-        count: 3,
-        maxRetries: 2,
-        retryDelay: 100,
-      });
-
-      expect(seeds).toHaveLength(3);
-      expect(seeds.every((seed) => typeof seed === 'string')).toBe(true);
-
-      // Use expect-chain for loose verification
-      const [isValidAnimalList] = await aiExpect(
-        seeds,
-        undefined,
-        'Are these reasonable animal names?'
-      );
-      expect(isValidAnimalList).toBe(true);
-    },
-    longTestTimeout
-  );
-});