@far-world-labs/verblets 0.1.7 → 0.3.2

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

@@ -1,279 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import intersections from './index.js';
-import { expect as aiExpect } from '../expect/index.js';
-import { longTestTimeout } from '../../constants/common.js';
-
-describe('intersections chain examples', () => {
-  it(
-    'analyzes technology categories comprehensively',
-    async () => {
-      const result = await intersections(['software', 'hardware', 'networking']);
-
-      // Basic validation
-      expect(typeof result).toBe('object');
-      expect(result).not.toBeNull();
-
-      // Should have meaningful intersections
-      expect(Object.keys(result).length).toBeGreaterThan(0);
-
-      // Validate structure of each intersection
-      // eslint-disable-next-line no-unused-vars
-      for (const [_comboKey, intersection] of Object.entries(result)) {
-        expect(intersection.combination).toBeDefined();
-        expect(intersection.description).toBeDefined();
-        expect(intersection.elements).toBeDefined();
-        expect(Array.isArray(intersection.combination)).toBe(true);
-        expect(Array.isArray(intersection.elements)).toBe(true);
-        expect(typeof intersection.description).toBe('string');
-        expect(intersection.combination.length).toBeGreaterThanOrEqual(2);
-      }
-
-      // AI validation of technology intersections
-      const [hasValidTechIntersections] = await aiExpect(
-        result,
-        undefined,
-        'Should contain meaningful intersections between technology categories with relevant examples'
-      );
-      expect(hasValidTechIntersections).toBe(true);
-    },
-    longTestTimeout
-  );
-
-  it(
-    'handles diverse categories with meaningful intersections',
-    async () => {
-      const result = await intersections(['art', 'science']);
-
-      // Basic validation
-      expect(typeof result).toBe('object');
-      expect(result).not.toBeNull();
-
-      // Should have at least one intersection for these broad categories
-      if (Object.keys(result).length > 0) {
-        const firstIntersection = Object.values(result)[0];
-        expect(Array.isArray(firstIntersection.elements)).toBe(true);
-        expect(typeof firstIntersection.description).toBe('string');
-        expect(Array.isArray(firstIntersection.combination)).toBe(true);
-        expect(firstIntersection.combination).toContain('art');
-        expect(firstIntersection.combination).toContain('science');
-
-        // AI validation of meaningful intersections
-        const [hasMeaningfulIntersections] = await aiExpect(
-          result,
-          undefined,
-          'Should contain meaningful intersections between art and science with relevant examples'
-        );
-        expect(hasMeaningfulIntersections).toBe(true);
-      }
-    },
-    longTestTimeout
-  );
-
-  it(
-    'validates schema compliance and structure quality',
-    async () => {
-      const result = await intersections(['music', 'mathematics']);
-
-      // Schema validation - should be an object
-      expect(typeof result).toBe('object');
-      expect(result).not.toBeNull();
-      expect(Array.isArray(result)).toBe(false);
-
-      // If we have results, validate strict schema compliance
-      if (Object.keys(result).length > 0) {
-        for (const [comboKey, intersection] of Object.entries(result)) {
-          // Key format validation (should be "category + category")
-          expect(comboKey).toMatch(/^.+ \+ .+$/);
-
-          // Required properties
-          expect(intersection).toHaveProperty('combination');
-          expect(intersection).toHaveProperty('description');
-          expect(intersection).toHaveProperty('elements');
-
-          // Type validation
-          expect(Array.isArray(intersection.combination)).toBe(true);
-          expect(typeof intersection.description).toBe('string');
-          expect(Array.isArray(intersection.elements)).toBe(true);
-
-          // Content validation
-          expect(intersection.combination.length).toBeGreaterThanOrEqual(2);
-          expect(intersection.description.length).toBeGreaterThan(0);
-          expect(intersection.combination).toContain('music');
-          expect(intersection.combination).toContain('mathematics');
-        }
-
-        // AI validation of music-math intersections
-        const [hasValidMusicMathIntersections] = await aiExpect(
-          Object.values(result)[0].elements,
-          undefined,
-          'Should contain examples that genuinely belong to both music and mathematics'
-        );
-        expect(hasValidMusicMathIntersections).toBe(true);
-      }
-    },
-    longTestTimeout
-  );
-
-  it(
-    'handles complex multi-category intersections',
-    async () => {
-      const result = await intersections(['biology', 'chemistry', 'physics'], {
-        maxSize: 3,
-        minSize: 2,
-      });
-
-      // Basic validation
-      expect(typeof result).toBe('object');
-      expect(result).not.toBeNull();
-
-      // Should handle multiple intersection types
-      if (Object.keys(result).length > 0) {
-        let hasTwoWayIntersection = false;
-        let _hasThreeWayIntersection = false;
-
-        // eslint-disable-next-line no-unused-vars
-        for (const [_comboKey, intersection] of Object.entries(result)) {
-          const comboSize = intersection.combination.length;
-
-          if (comboSize === 2) hasTwoWayIntersection = true;
-          // eslint-disable-next-line no-unused-vars
-          if (comboSize === 3) _hasThreeWayIntersection = true;
-
-          // Validate structure
-          expect(Array.isArray(intersection.combination)).toBe(true);
-          expect(typeof intersection.description).toBe('string');
-          expect(Array.isArray(intersection.elements)).toBe(true);
-
-          // All combinations should be from our input categories
-          for (const category of intersection.combination) {
-            expect(['biology', 'chemistry', 'physics']).toContain(category);
-          }
-        }
-
-        // Should have at least two-way intersections for science categories
-        expect(hasTwoWayIntersection).toBe(true);
-
-        // AI validation of scientific intersections
-        const [hasValidScienceIntersections] = await aiExpect(
-          result,
-          undefined,
-          'Should contain meaningful intersections between scientific disciplines with relevant examples'
-        );
-        expect(hasValidScienceIntersections).toBe(true);
-      }
-    },
-    longTestTimeout
-  );
-
-  it(
-    'handles single category appropriately',
-    async () => {
-      const result = await intersections(['photography']);
-
-      // Should return empty object since intersections require multiple items
-      expect(Object.keys(result).length).toBe(0);
-
-      // Validate single category handling
-      const [isEmptyObject] = await aiExpect(
-        result,
-        undefined,
-        'Should be an empty object since intersections require multiple categories'
-      );
-      expect(isEmptyObject).toBe(true);
-    },
-    longTestTimeout
-  );
-
-  it(
-    'produces consistent and logical results with quality validation',
-    async () => {
-      const result = await intersections(['literature', 'psychology'], {
-        goodnessScore: 8, // Higher quality threshold
-      });
-
-      // Basic validation - should be an object
-      expect(typeof result).toBe('object');
-      expect(result).not.toBeNull();
-
-      // If we have results, validate high-quality structure
-      if (Object.keys(result).length > 0) {
-        // eslint-disable-next-line no-unused-vars
-        for (const [_comboKey, intersection] of Object.entries(result)) {
-          // Basic structure checks
-          expect(intersection.combination).toBeDefined();
-          expect(intersection.description).toBeDefined();
-          expect(intersection.elements).toBeDefined();
-          expect(Array.isArray(intersection.combination)).toBe(true);
-          expect(Array.isArray(intersection.elements)).toBe(true);
-          expect(typeof intersection.description).toBe('string');
-
-          // Quality checks - should have meaningful content
-          expect(intersection.description.length).toBeGreaterThan(10);
-          expect(intersection.elements.length).toBeGreaterThan(0);
-        }
-
-        // AI validation of literature-psychology intersections
-        const [hasQualityIntersections] = await aiExpect(
-          result,
-          undefined,
-          'Should contain high-quality intersections between literature and psychology with meaningful examples'
-        );
-        expect(hasQualityIntersections).toBe(true);
-      }
-    },
-    longTestTimeout
-  );
-
-  it(
-    'handles edge cases gracefully',
-    async () => {
-      const result = await intersections([]);
-
-      // Validate empty input handling
-      const [isEmptyForEmptyInput] = await aiExpect(
-        result,
-        undefined,
-        'Should be an empty object for empty input'
-      );
-      expect(isEmptyForEmptyInput).toBe(true);
-
-      // Validate empty result structure
-      expect(Object.keys(result).length).toBe(0);
-    },
-    longTestTimeout
-  );
-
-  it(
-    'validates custom instructions and configuration',
-    async () => {
-      const customInstructions = 'Focus on practical applications and real-world examples';
-      const result = await intersections(['engineering', 'design'], {
-        instructions: customInstructions,
-        batchSize: 2,
-      });
-
-      // Basic validation
-      expect(typeof result).toBe('object');
-      expect(result).not.toBeNull();
-
-      // If we have results, validate they follow custom instructions
-      if (Object.keys(result).length > 0) {
-        const firstIntersection = Object.values(result)[0];
-
-        // Structure validation
-        expect(Array.isArray(firstIntersection.combination)).toBe(true);
-        expect(typeof firstIntersection.description).toBe('string');
-        expect(Array.isArray(firstIntersection.elements)).toBe(true);
-
-        // AI validation that results follow custom instructions
-        const [followsInstructions] = await aiExpect(
-          firstIntersection,
-          undefined,
-          'Should contain practical applications and real-world examples as requested in custom instructions'
-        );
-        expect(followsInstructions).toBe(true);
-      }
-    },
-    longTestTimeout
-  );
-});

package/src/chains/intersections/index.js

@@ -1,366 +0,0 @@
-import intersection from '../../verblets/intersection/index.js';
-import { rangeCombinations } from '../../lib/combinations/index.js';
-import chatGPT from '../../lib/chatgpt/index.js';
-import wrapVariable from '../../prompts/wrap-variable.js';
-import pkg from 'lodash';
-const { shuffle } = pkg;
-import number from '../../verblets/number/index.js';
-import { constants as promptConstants } from '../../prompts/index.js';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// Get the directory of this module
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const {
-  onlyJSONStringArray,
-  asNumber,
-  strictFormat,
-  contentIsQuestion,
-  explainAndSeparate,
-  explainAndSeparatePrimitive,
-} = promptConstants;
-
-/**
- * Load the JSON schema for intersection results
- * @returns {Promise<Object>} JSON schema for validation
- */
-async function getIntersectionSchema() {
-  const schemaPath = path.join(__dirname, 'intersection-result.json');
-  return JSON.parse(await fs.readFile(schemaPath, 'utf8'));
-}
-
-/**
- * Prompt for listing elements that belong to all categories
- */
-const ELEMENTS_PROMPT = (categories, instructions) => {
-  const basePrompt = `${contentIsQuestion} List specific examples, instances, or elements that belong to all of: ${categories.join(
-    ', '
-  )}.`;
-
-  const instructionsText = instructions ? `\n\nAdditional guidance: ${instructions}` : '';
-
-  return `${basePrompt}${instructionsText}
-
-${strictFormat} ${onlyJSONStringArray}`;
-};
-
-/**
- * Prompt for scoring intersection results
- */
-const SCORING_PROMPT = (
-  combo,
-  description,
-  elements
-) => `${contentIsQuestion} Rate this intersection result on a scale of 1-10:
-
-Combination: ${combo.join(' + ')}
-Description: ${description}
-Elements: ${elements.join(', ')}
-
-Criteria: Correctly lists specific examples, instances, or elements that belong to ALL categories simultaneously, with meaningful description.
-
-${explainAndSeparate} ${explainAndSeparatePrimitive}
-
-${asNumber}`;
-
-/**
- * Prompt for generating exhaustive elements using examples
- */
-const EXHAUSTIVE_PROMPT = (examplePrompts, combo, instructions) => {
-  const basePrompt = `Here are examples of well-enumerated intersections:
-
-${examplePrompts}
-
-${contentIsQuestion} For the combination: ${combo.join(' + ')}
-
-Provide an exhaustive list of specific examples, instances, or elements that belong to ALL of these categories simultaneously. Be as comprehensive as possible, following the pattern of the examples above.`;
-
-  const instructionsText = instructions ? `\n\nAdditional guidance: ${instructions}` : '';
-
-  return `${basePrompt}${instructionsText}
-
-${wrapVariable(combo.join(' | '), { tag: 'combination' })}
-
-${strictFormat} ${onlyJSONStringArray}`;
-};
-
-/**
- * Parse elements from LLM response (now expects JSON array)
- */
-const parseElements = (elementsText) => {
-  try {
-    const parsed = JSON.parse(elementsText.trim());
-    return Array.isArray(parsed) ? parsed.filter(Boolean) : [];
-  } catch {
-    // Fallback to old parsing method if JSON parsing fails
-    return elementsText
-      .split('\n')
-      .map((line) => line.replace(/^[-*•]\s*/, '').trim())
-      .filter(Boolean);
-  }
-};
-
-/**
- * Process a single combination to get elements, description, and score
- */
-const processCombo = async (combo, instructions, llm) => {
-  const comboKey = combo.join(' + ');
-
-  // Process elements, description, and scoring in parallel
-  const [elements, intersectionItems] = await Promise.all([
-    chatGPT(ELEMENTS_PROMPT(combo, instructions), { modelOptions: llm }),
-    intersection(combo, { instructions, llm }),
-  ]);
-
-  const elementList = parseElements(elements);
-  const description = Array.isArray(intersectionItems)
-    ? intersectionItems.join(', ')
-    : String(intersectionItems);
-  const score = await number(SCORING_PROMPT(combo, description, elementList), { llm });
-
-  return {
-    combo,
-    comboKey,
-    description,
-    elementList,
-    score,
-  };
-};
-
-/**
- * Process remaining combination using top examples as patterns
- */
-const processRemainingCombo = async (combo, instructions, examplePrompts, llm) => {
-  const comboKey = combo.join(' + ');
-
-  const [exhaustiveElements, intersectionItems] = await Promise.all([
-    chatGPT(EXHAUSTIVE_PROMPT(examplePrompts, combo, instructions), { modelOptions: llm }),
-    intersection(combo, { instructions, llm }),
-  ]);
-
-  const exhaustiveList = parseElements(exhaustiveElements);
-  const description = Array.isArray(intersectionItems)
-    ? intersectionItems.join(', ')
-    : String(intersectionItems);
-
-  return {
-    key: comboKey,
-    intersection: {
-      combination: combo,
-      description,
-      elements: exhaustiveList,
-    },
-  };
-};
-
-/**
- * Find intersections for all combinations of items with consistent, exhaustive results
- *
- * @param {Array} items - Array of items to find intersections between
- * @param {Object} options - Configuration options
- * @param {string} options.instructions - Custom instructions for intersection finding
- * @param {number} options.minSize - Minimum combination size (default: 2)
- * @param {number} options.maxSize - Maximum combination size (default: items.length)
- * @param {number} options.batchSize - Number of combinations to process in parallel (default: 5)
- * @param {number} options.goodnessScore - Minimum score threshold for good examples (default: 7)
- * @param {string|Object} options.llm - LLM model to use (default: 'fastGoodCheap' with extended timeout)
- * @param {boolean} options.useSchemaValidation - Whether to validate results with JSON schema (default: false)
- * @returns {Object} Results with combinations, elements, and exhaustive intersections
- * @throws {Error} When no combinations score above the goodness threshold
- */
-export default async function intersections(items, options = {}) {
-  if (!Array.isArray(items) || items.length < 2) {
-    return {};
-  }
-
-  const {
-    instructions,
-    minSize = 2,
-    maxSize = items.length,
-    batchSize = 5,
-    goodnessScore = 7,
-    llm = { modelName: 'fastGoodCheap', requestTimeout: 120_000 }, // Extended timeout for complex operations
-    useSchemaValidation = false, // Disabled by default due to OpenAI API limitations with patternProperties
-  } = options;
-
-  // Note: Schema validation is disabled by default because OpenAI's structured output
-  // doesn't handle patternProperties well. The function returns a dynamic object
-  // where keys are combination strings (e.g., "art + science") and values are
-  // intersection objects with combination, description, and elements properties.
-
-  // Step 1: Generate and shuffle combinations
-  const allCombinations = rangeCombinations(items, minSize, maxSize);
-  const combinations = shuffle(allCombinations);
-
-  if (combinations.length === 0) {
-    return {};
-  }
-
-  // Step 2: Find first 3 high-quality intersections in parallel
-  const topExamples = [];
-
-  for (let i = 0; i < combinations.length && topExamples.length < 3; i += batchSize) {
-    const batch = combinations.slice(i, i + batchSize);
-    const results = await Promise.all(batch.map((combo) => processCombo(combo, instructions, llm)));
-
-    for (const result of results) {
-      if (result.score > goodnessScore && topExamples.length < 3) {
-        topExamples.push({
-          key: result.comboKey,
-          intersection: {
-            combination: result.combo,
-            description: result.description,
-            elements: result.elementList,
-          },
-        });
-      }
-    }
-  }
-
-  // If no good examples found, lower the threshold and try again
-  if (topExamples.length === 0) {
-    const lowerThreshold = Math.max(1, goodnessScore - 3);
-    for (let i = 0; i < Math.min(combinations.length, 10) && topExamples.length < 3; i++) {
-      const result = await processCombo(combinations[i], instructions, llm);
-      if (result.score > lowerThreshold) {
-        topExamples.push({
-          key: result.comboKey,
-          intersection: {
-            combination: result.combo,
-            description: result.description,
-            elements: result.elementList,
-          },
-        });
-      }
-    }
-  }
-
-  // If still no examples, return empty object
-  if (topExamples.length === 0) {
-    return {};
-  }
-
-  // Step 3: Use top examples to generate all intersections in parallel
-  const examplePrompts = topExamples
-    .map(
-      ({ key, intersection }) =>
-        `${key}: ${intersection.description}\nElements: ${intersection.elements
-          .slice(0, 5)
-          .join(', ')}`
-    )
-    .join('\n\n');
-
-  const remainingCombinations = allCombinations.filter((combo) => {
-    const comboKey = combo.join(' + ');
-    return !topExamples.find((ex) => ex.key === comboKey); // Skip already processed examples
-  });
-
-  // Process remaining combinations in parallel
-  const remainingResults = await Promise.all(
-    remainingCombinations.map((combo) =>
-      processRemainingCombo(combo, instructions, examplePrompts, llm)
-    )
-  );
-
-  // Combine all results
-  const finalIntersections = {};
-
-  // Add top examples
-  for (const example of topExamples) {
-    finalIntersections[example.key] = example.intersection;
-  }
-
-  // Add remaining results
-  for (const result of remainingResults) {
-    finalIntersections[result.key] = result.intersection;
-  }
-
-  // Step 4: Validate results with JSON schema if enabled
-  if (useSchemaValidation && Object.keys(finalIntersections).length > 0) {
-    const validated = await validateIntersectionResults(finalIntersections, llm);
-    // Extract the intersections from the validated structure and return flat
-    return validated.intersections || finalIntersections;
-  }
-
-  return finalIntersections;
-}
-
-/**
- * Create model options with JSON schema validation
- * @param {string|Object} llm - LLM model to use
- * @param {string} schemaName - Name for the JSON schema
- * @returns {Promise<Object>} Model options with schema validation
- */
-async function createModelOptions(llm = 'fastGoodCheap', schemaName = 'intersection_result') {
-  const schema = await getIntersectionSchema();
-
-  const responseFormat = {
-    type: 'json_schema',
-    json_schema: {
-      name: schemaName,
-      schema,
-    },
-  };
-
-  if (typeof llm === 'string') {
-    return {
-      modelName: llm,
-      response_format: responseFormat,
-    };
-  } else {
-    return {
-      ...llm,
-      response_format: responseFormat,
-    };
-  }
-}
-
-/**
- * Validate and structure final results using JSON schema
- * @param {Object} intersections - Raw intersection results
- * @param {string|Object} llm - LLM model to use
- * @returns {Promise<Object>} Schema-validated intersection results
- */
-async function validateIntersectionResults(intersections, llm = 'fastGoodCheap') {
-  if (!intersections || Object.keys(intersections).length === 0) {
-    return { intersections: {} };
-  }
-
-  const prompt = `Validate and structure these intersection results according to the required schema:
-
-${JSON.stringify(intersections, null, 2)}
-
-Ensure each intersection has:
-- combination: array of category names
-- description: clear explanation of the intersection
-- elements: array of specific examples that belong to ALL categories
-
-Return the properly structured JSON object with an "intersections" property containing the results.`;
-
-  try {
-    const modelOptions = await createModelOptions(llm, 'intersection_result');
-    const response = await chatGPT(prompt, { modelOptions });
-    const parsed = typeof response === 'string' ? JSON.parse(response) : response;
-
-    // Extract intersections from the object structure
-    const resultIntersections = parsed?.intersections || parsed;
-
-    // Validate that the result is an object
-    if (
-      typeof resultIntersections !== 'object' ||
-      resultIntersections === null ||
-      Array.isArray(resultIntersections)
-    ) {
-      console.warn('Schema validation failed: invalid structure, returning original results');
-      return { intersections };
-    }
-
-    return { intersections: resultIntersections };
-  } catch (error) {
-    console.warn('Schema validation failed, returning original results:', error.message);
-    return { intersections };
-  }
-}

package/src/chains/intersections/intersection-result.json

@@ -1,38 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "description": "Intersection results between categories",
-  "properties": {
-    "intersections": {
-      "type": "object",
-      "description": "Map of intersection results keyed by combination identifier",
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "combination": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Array of category names that form this intersection"
-          },
-          "description": {
-            "type": "string",
-            "description": "Clear explanation of what this intersection represents"
-          },
-          "elements": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Specific examples that belong to ALL categories in the combination"
-          }
-        },
-        "required": ["combination", "description", "elements"],
-        "additionalProperties": false
-      }
-    }
-  },
-  "required": ["intersections"],
-  "additionalProperties": false
-}