@far-world-labs/verblets 0.1.1 → 0.1.3

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

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

@@ -0,0 +1,134 @@
+import list from '../list/index.js';
+import retry from '../../lib/retry/index.js';
+import modelService from '../../services/llm-model/index.js';
+
+/**
+ * Core prompt template for sample generation using cognitive science principles
+ */
+export const SAMPLE_GENERATION_PROMPT = `Generate sample items for the category "{categoryName}" using cognitive science principles.
+
+{context}
+
+COGNITIVE PRINCIPLES:
+1. Prototype Theory: Include items across the typicality spectrum
+2. Family Resemblance: Ensure items share overlapping but not identical features
+3. Category Structure: {diversityInstructions}
+
+REQUIREMENTS:
+- Include highly typical/prototypical members
+- Include moderately typical members
+- {diversityRequirement}
+- Ensure good coverage of category space
+- Avoid redundant or near-identical items
+
+IMPORTANT: Return only clean item names without numbering, descriptions, or explanations.`;
+
+/**
+ * Build sample generation prompt with specific parameters
+ * @param {string} categoryName - Name of the category
+ * @param {Object} config - Configuration options
+ * @returns {string} Complete prompt for sample generation
+ */
+export function buildSeedGenerationPrompt(
+  categoryName,
+  { context = '', diversityLevel = 'balanced' } = {}
+) {
+  const diversityInstructions = {
+    high: 'Include very diverse examples spanning edge cases and borderline members',
+    balanced: 'Include a mix of typical, moderately typical, and some atypical members',
+    focused: 'Focus on highly typical, central members with clear category membership',
+  };
+
+  const diversityRequirement = {
+    high: 'Include many atypical but valid members',
+    balanced: 'Include some moderately atypical members',
+    focused: 'Focus primarily on typical members',
+  };
+
+  const contextLine = context ? `Context: ${context}` : '';
+
+  return SAMPLE_GENERATION_PROMPT.replace('{categoryName}', categoryName)
+    .replace('{context}', contextLine)
+    .replace(
+      '{diversityInstructions}',
+      diversityInstructions[diversityLevel] || diversityInstructions.balanced
+    )
+    .replace(
+      '{diversityRequirement}',
+      diversityRequirement[diversityLevel] || diversityRequirement.balanced
+    );
+}
+
+/**
+ * Generate sample items for a category using cognitive science principles.
+ * Creates diverse, representative examples across the typicality spectrum.
+ *
+ * @param {string} categoryName - Name of the category
+ * @param {Object} [options={}] - Configuration options
+ * @param {string} [options.context=''] - Context for sample generation
+ * @param {number} [options.count=30] - Number of sample items to generate
+ * @param {string} [options.diversityLevel='balanced'] - 'high', 'balanced', or 'focused'
+ * @param {string|Object} [options.llm='fastGoodCheap'] - LLM model to use
+ * @param {number} [options.maxRetries=3] - Maximum number of retry attempts
+ * @param {number} [options.retryDelay=1000] - Delay between retries in milliseconds
+ * @returns {Promise<string[]>}
+ */
+export default async function categorySamples(categoryName, options = {}) {
+  if (!categoryName || typeof categoryName !== 'string') {
+    throw new Error('categoryName must be a non-empty string');
+  }
+
+  const {
+    context = '',
+    count = 30,
+    diversityLevel = 'balanced',
+    llm = 'fastGoodCheap',
+    maxRetries = 3,
+    retryDelay = 1000,
+  } = options;
+
+  const generateWithRetry = async () => {
+    const prompt = buildSeedGenerationPrompt(categoryName, { context, diversityLevel });
+
+    // Get the model object from the model service
+    const model = typeof llm === 'string' ? modelService.getModel(llm) : llm;
+
+    const results = await list(prompt, {
+      llm: model,
+      shouldStop: ({ resultsAll }) => resultsAll.length >= count,
+    });
+
+    if (!results || results.length === 0) {
+      throw new Error(`No sample items generated for category: ${categoryName}`);
+    }
+
+    // Return only the requested count
+    return results.slice(0, count);
+  };
+
+  return await retry(generateWithRetry, {
+    maxRetries,
+    retryDelay,
+    retryCondition: (error) => {
+      // Retry on network errors, timeouts, or empty results
+      return (
+        error.message.includes('No sample items generated') ||
+        error.message.includes('timeout') ||
+        error.message.includes('network') ||
+        error.message.includes('ECONNRESET')
+      );
+    },
+  });
+}
+
+/**
+ * Generate sample items for a category using list generation
+ * @param {string} category - The category to generate samples for
+ * @param {number} _count - Target number of samples (unused, kept for API compatibility)
+ * @param {Object} options - Additional options
+ * @returns {Promise<string[]>} Array of sample items
+ */
+export function categorySamplesList(category, _count = 10, options = {}) {
+  // Use the list chain to generate samples for the category
+  return list(category, options);
+}

package/src/chains/collect-terms/README.md

@@ -0,0 +1,12 @@
+# collect-terms
+
+Extract the most difficult or technical terms from any passage. Useful for building a glossary or highlighting vocabulary that needs clarification.
+
+## Usage
+
+```javascript
+import collectTerms from './collect-terms/index.js';
+
+const terms = await collectTerms(longText, { topN: 15 });
+// => ['usufructuary rights', 'riparian', 'hydrological cycle', ...]
+```

package/src/chains/collect-terms/index.examples.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { longTestTimeout } from '../../constants/common.js';
+import collectTerms from './index.js';
+
+const sample = `Quantum entanglement and the observer effect are central to modern physics. Understanding Heisenberg's uncertainty principle alongside quantum decoherence helps explain particle behavior at subatomic scales.`;
+
+describe('collectTerms chain', () => {
+  it(
+    'Example',
+    async () => {
+      const terms = await collectTerms(sample, { topN: 5 });
+      expect(Array.isArray(terms)).toBe(true);
+    },
+    longTestTimeout
+  );
+});

package/src/chains/collect-terms/index.js

@@ -0,0 +1,44 @@
+import list from '../list/index.js';
+import listReduce from '../../verblets/list-reduce/index.js';
+
+const splitIntoChunks = (text, maxLen) => {
+  const words = text.split(/\s+/);
+  const chunks = [];
+  let current = '';
+  for (const word of words) {
+    if (current.length + word.length + 1 > maxLen) {
+      if (current) chunks.push(current.trim());
+      current = word;
+    } else {
+      current += (current ? ' ' : '') + word;
+    }
+  }
+  if (current) chunks.push(current.trim());
+  return chunks;
+};
+
+export default async function collectTerms(text, config = {}) {
+  const { chunkLen = 1000, topN = 20, llm, ...options } = config;
+  const chunks = splitIntoChunks(text, chunkLen);
+  const allTerms = [];
+  for (const chunk of chunks) {
+    const terms = await list(`important complex or technical terms from: ${chunk}`, {
+      llm,
+      ...options,
+    });
+    allTerms.push(...terms);
+  }
+  const uniqueTerms = Array.from(new Set(allTerms.map((t) => t.trim())));
+  if (uniqueTerms.length <= topN) return uniqueTerms;
+  const reduced = await listReduce(
+    '',
+    uniqueTerms,
+    `Return the top ${topN} terms as a comma-separated list`,
+    { llm, ...options }
+  );
+  return reduced
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .slice(0, topN);
+}

package/src/chains/collect-terms/index.spec.js

@@ -0,0 +1,25 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+import collectTerms from './index.js';
+import list from '../list/index.js';
+import listReduce from '../../verblets/list-reduce/index.js';
+
+vi.mock('../list/index.js');
+vi.mock('../../verblets/list-reduce/index.js');
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+describe('collectTerms chain', () => {
+  it('deduplicates and reduces to top terms', async () => {
+    list.mockResolvedValueOnce(['alpha', 'beta']).mockResolvedValueOnce(['beta', 'gamma']);
+    listReduce.mockResolvedValue('alpha, beta, gamma');
+
+    const text = 'p1\n\np2';
+    const result = await collectTerms(text, { chunkLen: 2, topN: 2 });
+
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(result).toStrictEqual(['alpha', 'beta']);
+    expect(listReduce).toHaveBeenCalled();
+  });
+});

package/src/chains/date/README.md

@@ -0,0 +1,12 @@
+# date
+
+Iteratively refine LLM answers until they produce a valid JavaScript `Date` object that satisfies the prompt. Before asking for a date, the chain asks the language model to suggest a few quick checks that a correct answer should satisfy. Each returned date is evaluated against those expectations with the `bool` verblt and retried if any fail.
+
+```javascript
+import date from './index.js';
+
+const release = await date('When was the original Star Wars film released?');
+// => new Date('1977-05-25')
+```
+
+The chain asks for a date using prompt constants shared with primitive verblets. It then verifies the result with the `bool` verblet and retries until the date is deemed correct or attempts run out.

package/src/chains/date/index.examples.js

@@ -0,0 +1,47 @@
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import date from './index.js';
+import { expect as llmExpect } from '../../chains/expect/index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('date examples', () => {
+  const originalMode = process.env.LLM_EXPECT_MODE;
+
+  beforeAll(() => {
+    process.env.LLM_EXPECT_MODE = 'none';
+  });
+
+  afterAll(() => {
+    if (originalMode !== undefined) {
+      process.env.LLM_EXPECT_MODE = originalMode;
+    } else {
+      delete process.env.LLM_EXPECT_MODE;
+    }
+  });
+
+  it(
+    'gets Star Wars release date',
+    async () => {
+      const result = await date('When was the original Star Wars released?');
+      expect(result instanceof Date).toBe(true);
+      const [reasonable] = await llmExpect(
+        `Star Wars release date: ${result.toISOString()}`,
+        undefined,
+        'Is this close to the actual release date of the first Star Wars movie?'
+      );
+      expect(reasonable).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'finds Christmas 2025',
+    async () => {
+      const result = await date('When is Christmas Day in 2025?');
+      expect(result instanceof Date).toBe(true);
+      expect(result.getUTCFullYear()).toBe(2025);
+      expect(result.getUTCMonth()).toBe(11); // December
+      expect(result.getUTCDate()).toBe(25);
+    },
+    longTestTimeout
+  );
+});

package/src/chains/date/index.js

@@ -0,0 +1,74 @@
+import chatGPT from '../../lib/chatgpt/index.js';
+import stripResponse from '../../lib/strip-response/index.js';
+import toDate from '../../lib/to-date/index.js';
+import toObject from '../../verblets/to-object/index.js';
+import bool from '../../verblets/bool/index.js';
+import { constants as promptConstants } from '../../prompts/index.js';
+
+const {
+  asDate,
+  asUndefinedByDefault,
+  contentIsQuestion,
+  explainAndSeparate,
+  explainAndSeparatePrimitive,
+  onlyJSONArray,
+} = promptConstants;
+
+const expectationPrompt = (question) => `${contentIsQuestion} ${question}
+
+List up to three short yes/no checks that would confirm a date answer is correct. If nothing specific comes to mind, respond with ["The result is a valid date"].
+
+${onlyJSONArray}`;
+
+const buildCheckPrompt = (dateValue, check) => {
+  const iso = dateValue.toISOString();
+  const human = dateValue.toUTCString();
+  const utcDate = new Date(
+    Date.UTC(dateValue.getUTCFullYear(), dateValue.getUTCMonth(), dateValue.getUTCDate())
+  );
+  return `Date in ISO: ${iso} (UTC: ${human}, UTC date: ${utcDate.toISOString()}). Does this satisfy "${check}"?`;
+};
+
+export default async function date(text, config = {}) {
+  const { maxAttempts = 3, llm, ...options } = config;
+  const llmExpectations = (await toObject(
+    await chatGPT(expectationPrompt(text), { modelOptions: { ...llm }, ...options }),
+    null,
+    { llm, ...options }
+  )) || ['The result is a valid date'];
+
+  let attemptText = text;
+  let response;
+  for (let i = 0; i < maxAttempts; i += 1) {
+    const datePrompt = `${contentIsQuestion} ${attemptText}\n\n${explainAndSeparate} ${explainAndSeparatePrimitive}\n\n${asDate} ${asUndefinedByDefault}`;
+    // eslint-disable-next-line no-await-in-loop
+    response = await chatGPT(datePrompt, { modelOptions: { ...llm }, ...options });
+    const value = toDate(stripResponse(response));
+    if (value === undefined) return undefined;
+
+    // Convert to UTC date for consistent checks
+    const utcValue = new Date(
+      Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate())
+    );
+
+    let failedCheck;
+    for (const check of llmExpectations) {
+      // eslint-disable-next-line no-await-in-loop
+      const passed = await bool(buildCheckPrompt(utcValue, check), { llm, ...options });
+      if (!passed) {
+        failedCheck = check;
+        break;
+      }
+    }
+
+    if (!failedCheck) return utcValue;
+
+    attemptText = `${text} The previous answer (${utcValue.toISOString()}) failed to satisfy: "${failedCheck}". Try again.`;
+  }
+  const finalValue = toDate(stripResponse(response));
+  return finalValue
+    ? new Date(
+        Date.UTC(finalValue.getUTCFullYear(), finalValue.getUTCMonth(), finalValue.getUTCDate())
+      )
+    : undefined;
+}

package/src/chains/date/index.spec.js

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import date from './index.js';
+import bool from '../../verblets/bool/index.js';
+
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn(),
+}));
+
+vi.mock('../../verblets/bool/index.js', () => ({
+  default: vi.fn(),
+}));
+
+vi.mock('../../verblets/to-object/index.js', () => ({
+  default: vi.fn(),
+}));
+
+const chatGPT = (await import('../../lib/chatgpt/index.js')).default;
+const toObjectMock = (await import('../../verblets/to-object/index.js')).default;
+
+describe('date chain', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it('returns a date when bool approves', async () => {
+    chatGPT.mockResolvedValueOnce('["check"]');
+    toObjectMock.mockResolvedValueOnce(['check']);
+    chatGPT.mockResolvedValueOnce('2023-01-02');
+    bool.mockResolvedValueOnce(true);
+    const result = await date('When is tomorrow?');
+    expect(result instanceof Date).toBe(true);
+    expect(result.toISOString().startsWith('2023-01-02')).toBe(true);
+    expect(chatGPT).toHaveBeenCalledTimes(2);
+    expect(toObjectMock).toHaveBeenCalledTimes(1);
+    expect(bool).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries until bool approves', async () => {
+    chatGPT.mockResolvedValueOnce('["check"]');
+    toObjectMock.mockResolvedValueOnce(['check']);
+    chatGPT.mockResolvedValueOnce('2023-01-02');
+    chatGPT.mockResolvedValueOnce('2023-02-03');
+    bool.mockResolvedValueOnce(false);
+    bool.mockResolvedValueOnce(true);
+
+    const result = await date('When is tomorrow?', { maxAttempts: 2 });
+    expect(result.toISOString().startsWith('2023-02-03')).toBe(true);
+    expect(chatGPT).toHaveBeenCalledTimes(3);
+    expect(toObjectMock).toHaveBeenCalledTimes(1);
+    expect(bool).toHaveBeenCalledTimes(2);
+  });
+
+  it('returns undefined when chatGPT says undefined', async () => {
+    chatGPT.mockResolvedValueOnce('["check"]');
+    toObjectMock.mockResolvedValueOnce(['check']);
+    chatGPT.mockResolvedValueOnce('undefined');
+    const result = await date('Unknown date');
+    expect(result).toBeUndefined();
+    expect(chatGPT).toHaveBeenCalledTimes(2);
+    expect(toObjectMock).toHaveBeenCalledTimes(1);
+    expect(bool).not.toHaveBeenCalled();
+  });
+});

package/src/chains/disambiguate/README.md

@@ -0,0 +1,22 @@
+# disambiguate
+
+Determine the intended meaning of a polysemous word or short phrase based on surrounding context.
+The chain lists common meanings and filters them down to the one that fits best.
+
+```javascript
+import disambiguate from './index.js';
+
+const result = await disambiguate({
+  term: 'bat',
+  context: 'The child swung the bat at the baseball.'
+});
+
+console.log(result.meaning);
+// => "a club used in sports like baseball"
+```
+
+## Use case: clarifying travel conversations
+
+When a traveler says, "I spoke with the coach about my seat," it helps to know
+whether they mean a sports instructor or an airline seating class. This chain
+uses language model reasoning to resolve that ambiguity automatically.

package/src/chains/disambiguate/disambiguate-meanings-result.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "meanings": {
+      "type": "array",
+      "description": "Array of distinct dictionary meanings or common uses of a term",
+      "items": {
+        "type": "string",
+        "description": "A distinct meaning or common use of the term"
+      }
+    }
+  },
+  "required": ["meanings"],
+  "additionalProperties": false
+} 

package/src/chains/disambiguate/index.examples.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import disambiguate from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('Disambiguate chain', () => {
+  it(
+    'contextual meaning: bank',
+    async () => {
+      const result = await disambiguate({
+        term: 'bank',
+        context: 'She waited in line at the bank to deposit her paycheck.',
+      });
+      expect(typeof result.meaning).toBe('string');
+      expect(result.meaning.length).toBeGreaterThan(0);
+    },
+    longTestTimeout
+  );
+});