@far-world-labs/verblets 0.1.1 → 0.1.2

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

@@ -0,0 +1,43 @@
+# bulk-map
+
+Chunk large lists and map each chunk with `listMap`. Failed chunks can be retried.
+
+## Usage
+
+```javascript
+import { bulkMap } from '../../index.js';
+
+const films = [
+  'sci-fi epic',
+  'romantic comedy',
+  'time-travel thriller',
+  // ...more titles
+];
+const results = await bulkMap(films, 'Describe each as a Shakespearean play', { chunkSize: 5 });
+// results[0] === 'A saga among the stars'
+// results[1] === 'Where hearts and humor entwine'
+```
+
+## API
+
+### `bulkMap(list, instructions, [chunkSize])`
+
+Break `list` into batches and map each batch using `listMap`.
+
+- `list` (`string[]`): fragments to process.
+- `instructions` (`string`): mapping instructions.
+- `chunkSize` (`number`, default `10`): number of items per batch.
+
+Returns `Promise<(string|undefined)[]>` where undefined entries represent failed items.
+
+### `bulkMapRetry(list, instructions, [options])`
+
+Retry undefined entries from `bulkMap` until `maxAttempts` is reached.
+
+- `list` (`string[]`): fragments to process.
+- `instructions` (`string`): mapping instructions.
+- `options.chunkSize` (`number`, default `10`): size of each batch.
+- `options.maxAttempts` (`number`, default `3`): number of passes over failed items.
+
+Returns `Promise<(string|undefined)[]>` aligned with input order.
+

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

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import bulkMap from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('bulkmap examples', () => {
+  it(
+    'maps with listMap',
+    async () => {
+      const animals = ['dog', 'cat', 'cow', 'sheep', 'duck'];
+      const result = await bulkMap(animals, 'Return the sound each animal makes', { chunkSize: 3 });
+      // e.g. result[0] === 'bark'
+      //      result[2] === 'moo'
+      expect(result.length).toBe(5);
+    },
+    longTestTimeout
+  );
+});

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

@@ -0,0 +1,86 @@
+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

@@ -0,0 +1,44 @@
+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

@@ -0,0 +1,12 @@
+# 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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,18 @@
+{
+  "$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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,133 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,61 @@
+# 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

@@ -0,0 +1,103 @@
+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
+  );
+});