@far-world-labs/verblets 0.1.1 → 0.1.3

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

@@ -0,0 +1,30 @@
+import listFind from '../../verblets/list-find/index.js';
+
+export const bulkFind = async function (list, instructions, config = {}) {
+  const { chunkSize = 10, llm, ...options } = config;
+  let candidate = '';
+  for (let i = 0; i < list.length; i += chunkSize) {
+    const batch = list.slice(i, i + chunkSize);
+    const combined = candidate ? [candidate, ...batch] : batch;
+    // eslint-disable-next-line no-await-in-loop
+    candidate = await listFind(combined, instructions, { llm, ...options });
+  }
+  return candidate;
+};
+
+export const bulkFindRetry = async function (list, instructions, config = {}) {
+  const { chunkSize = 10, maxAttempts = 3, llm, ...options } = config;
+  let result;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      result = await bulkFind(list, instructions, { chunkSize, llm, ...options });
+      if (result) break;
+    } catch {
+      // continue
+    }
+  }
+  return result;
+};
+
+export default bulkFind;

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

@@ -0,0 +1,26 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import bulkFind, { bulkFindRetry } from './index.js';
+import listFind from '../../verblets/list-find/index.js';
+
+vi.mock('../../verblets/list-find/index.js', () => ({
+  default: vi.fn(async (items) => items[items.length - 1]),
+}));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('bulk-find chain', () => {
+  it('scans batches to find best item', async () => {
+    const result = await bulkFind(['a', 'b', 'c', 'd'], 'find', { chunkSize: 2 });
+    expect(result).toBe('d');
+    expect(listFind).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries on failure', async () => {
+    listFind.mockRejectedValueOnce(new Error('fail'));
+    const result = await bulkFindRetry(['x', 'y'], 'find', { chunkSize: 2, maxAttempts: 2 });
+    expect(result).toBe('y');
+    expect(listFind).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -0,0 +1,23 @@
+# bulk-group
+
+Group long lists by first discovering the best categories and then grouping
+items into those categories in smaller batches.
+
+```javascript
+import bulkGroup from './index.js';
+
+const feedback = [
+  'Great interface and onboarding',
+  'Price is a bit steep',
+  'Love the mobile app',
+  'Needs more integrations',
+];
+const result = await bulkGroup(
+  feedback,
+  'Is each line praise, criticism, or a feature request?',
+  { chunkSize: 2, topN: 3 }
+);
+// => { praise: ['Great interface and onboarding', 'Love the mobile app'],
+//      criticism: ['Price is a bit steep'],
+//      'feature request': ['Needs more integrations'] }
+```

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

@@ -0,0 +1,18 @@
+import bulkGroup from './index.js';
+import { describe, it, expect } from 'vitest';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('bulk-group examples', () => {
+  it(
+    'groups a long list',
+    async () => {
+      const items = ['dog', 'fish', 'cat', 'whale', 'bird', 'shark', 'horse', 'dolphin'];
+      const result = await bulkGroup(items, 'Is each creature terrestrial or aquatic?', {
+        chunkSize: 4,
+      });
+      expect(typeof result).toBe('object');
+      expect(Object.keys(result).length).toBeGreaterThan(0);
+    },
+    longTestTimeout
+  );
+});

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

@@ -0,0 +1,34 @@
+import listGroup from '../../verblets/list-group/index.js';
+
+export default async function bulkGroup(list, instructions, config = {}) {
+  const { chunkSize = 10, topN, llm, ...options } = config;
+  let categories;
+  const groups = {};
+
+  for (let i = 0; i < list.length; i += chunkSize) {
+    const batch = list.slice(i, i + chunkSize);
+
+    // eslint-disable-next-line no-await-in-loop
+    const result = await listGroup(batch, instructions, categories, { llm, ...options });
+
+    // Use categories from first batch for consistency
+    if (!categories) {
+      categories = Object.keys(result);
+    }
+
+    for (const [key, items] of Object.entries(result)) {
+      if (!groups[key]) groups[key] = [];
+      groups[key].push(...items);
+    }
+  }
+
+  // Apply topN filtering if specified
+  if (topN) {
+    const sortedEntries = Object.entries(groups)
+      .sort(([, a], [, b]) => b.length - a.length)
+      .slice(0, topN);
+    return Object.fromEntries(sortedEntries);
+  }
+
+  return groups;
+}

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

@@ -0,0 +1,41 @@
+import bulkGroup from './index.js';
+import listGroup from '../../verblets/list-group/index.js';
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+vi.mock('../../verblets/list-group/index.js', () => ({
+  default: vi.fn(),
+}));
+
+describe('bulk-group chain', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('groups in batches', async () => {
+    const items = ['a', 'bb', 'ccc', 'dddd', 'eeeee'];
+
+    // Mock the calls in order - with chunkSize=2, we'll have 3 batches: [a,bb], [ccc,dddd], [eeeee]
+    listGroup
+      .mockResolvedValueOnce({ odd: ['a'], even: ['bb'] }) // First batch
+      .mockResolvedValueOnce({ odd: ['ccc'], even: ['dddd'] }) // Second batch
+      .mockResolvedValueOnce({ odd: ['eeeee'] }); // Third batch
+
+    const result = await bulkGroup(items, 'odd or even', {
+      chunkSize: 2,
+    });
+
+    expect(result).toStrictEqual({ odd: ['a', 'ccc', 'eeeee'], even: ['bb', 'dddd'] });
+    expect(listGroup).toHaveBeenCalledTimes(3);
+
+    // Verify the calls were made with the right parameters
+    expect(listGroup).toHaveBeenNthCalledWith(1, ['a', 'bb'], 'odd or even', undefined, {
+      llm: undefined,
+    });
+    expect(listGroup).toHaveBeenNthCalledWith(2, ['ccc', 'dddd'], 'odd or even', ['odd', 'even'], {
+      llm: undefined,
+    });
+    expect(listGroup).toHaveBeenNthCalledWith(3, ['eeeee'], 'odd or even', ['odd', 'even'], {
+      llm: undefined,
+    });
+  });
+});

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);
+  });
+});