@far-world-labs/verblets 0.1.1 → 0.1.3

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

@@ -0,0 +1,386 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import glossary from './index.js';
+import aiExpect from '../../verblets/expect/index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('glossary examples', () => {
+  // Set environment mode to 'none' for all tests to avoid throwing
+  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(
+    'extracts terms from a science paragraph',
+    async () => {
+      const text = `The chef explained how umami develops through the Maillard reaction alongside sous-vide techniques.`;
+      const result = await glossary(text, { maxTerms: 2 });
+
+      expect(result.length).toBeGreaterThan(0);
+      expect(Array.isArray(result)).toBe(true);
+
+      // LLM assertion to validate that extracted terms are technical/complex
+      const areTermsTechnical = await aiExpect(
+        `From the text "${text}", these terms were extracted: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are these terms technical or complex enough that a casual reader might need definitions?',
+        {
+          message: `Expected extracted terms to be technical/complex, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        areTermsTechnical,
+        `Expected extracted terms to be technical/complex, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion to validate terms are relevant to the source text
+      const areTermsRelevant = await aiExpect(
+        `Original text: "${text}" | Extracted terms: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are all these extracted terms actually present or directly related to the original text?',
+        {
+          message: `Expected terms to be relevant to source text, but extracted: ${result.join(
+            ', '
+          )} from: "${text}"`,
+        }
+      );
+      expect(
+        areTermsRelevant,
+        `Expected terms to be relevant to source text, but extracted: ${result.join(
+          ', '
+        )} from: "${text}"`
+      ).toBe(true);
+
+      // LLM assertion to validate term selection quality
+      const isGoodSelection = await aiExpect(
+        `For a cooking/culinary text, these terms were selected for a glossary: ${result.join(
+          ', '
+        )}`
+      ).toSatisfy(
+        'Are these appropriate terms for a culinary glossary that would help readers understand cooking concepts?',
+        { message: `Expected appropriate culinary terms, but got: ${result.join(', ')}` }
+      );
+      expect(
+        isGoodSelection,
+        `Expected appropriate culinary terms, but got: ${result.join(', ')}`
+      ).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'handles technical documentation with multiple complex terms',
+    async () => {
+      const sourceText = `Our microservice architecture uses an API gateway for routing. Authentication is handled via OAuth 2.0 and JWT tokens. We also employ load balancing to distribute traffic.`;
+      const result = await glossary(sourceText, { maxTerms: 5 });
+      expect(result).toBeDefined();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+      // Check that the extracted terms cover the key technical concepts in the source text.
+      const keyConcepts = ['microservice', 'API gateway', 'OAuth', 'JWT', 'load balancing'];
+      const coverage = keyConcepts.every((concept) =>
+        result.some((term) => term.toLowerCase().includes(concept.toLowerCase()))
+      );
+      expect(coverage).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'filters out common words and focuses on specialized terms',
+    async () => {
+      const text = `The quantum entanglement phenomenon occurs when particles become interconnected, 
+      demonstrating superposition states that challenge classical physics understanding. 
+      This behavior is fundamental to quantum computing applications.`;
+
+      const result = await glossary(text, { maxTerms: 4 });
+
+      expect(result.length).toBeGreaterThan(0);
+
+      // LLM assertion to ensure no common words are included
+      const noCommonWords = await aiExpect(
+        `These terms were selected for a glossary: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are all of these terms specialized/technical rather than common everyday words?',
+        {
+          message: `Expected only specialized/technical terms, but some may be common words: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        noCommonWords,
+        `Expected only specialized/technical terms, but some may be common words: ${result.join(
+          ', '
+        )}`
+      ).toBe(true);
+
+      // LLM assertion for scientific accuracy
+      const scientificallyAccurate = await aiExpect(
+        `From a quantum physics text, these terms were extracted: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are these reasonable terms that relate to quantum physics or scientific concepts? They should be legitimate scientific terminology, even if not all are highly technical quantum physics terms.',
+        {
+          message: `Expected reasonable scientific terms related to quantum physics, but got: ${result.join(
+            ', '
+          )}. Terms should be legitimate scientific concepts.`,
+        }
+      );
+      expect(
+        scientificallyAccurate,
+        `Expected reasonable scientific terms related to quantum physics, but got: ${result.join(
+          ', '
+        )}. Terms should be legitimate scientific concepts.`
+      ).toBe(true);
+
+      // LLM assertion for educational value
+      const educationalValue = await aiExpect(
+        `For someone learning about quantum physics, these glossary terms were provided: ${result.join(
+          ', '
+        )}`
+      ).toSatisfy(
+        'Would defining these terms be helpful for understanding the quantum physics concepts in the text? Focus on whether they contribute to comprehension rather than requiring perfect technical precision.',
+        {
+          message: `Expected terms that would help with understanding quantum physics concepts, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        educationalValue,
+        `Expected terms that would help with understanding quantum physics concepts, but got: ${result.join(
+          ', '
+        )}`
+      ).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'handles empty or simple text appropriately',
+    async () => {
+      const simpleText = `The cat sat on the mat. It was a sunny day.`;
+      const result = await glossary(simpleText, { maxTerms: 3 });
+
+      // Should return empty array or very few terms for simple text
+      expect(Array.isArray(result)).toBe(true);
+
+      if (result.length > 0) {
+        // If any terms are returned, they should still be reasonable
+        const reasonableForSimpleText = await aiExpect(
+          `From simple text "${simpleText}", these terms were extracted: ${result.join(', ')}`
+        ).toSatisfy(
+          'If any terms were extracted from this simple text, are they reasonable choices?',
+          {
+            message: `Expected reasonable terms for simple text, but extracted: ${result.join(
+              ', '
+            )} from: "${simpleText}"`,
+          }
+        );
+        expect(
+          reasonableForSimpleText,
+          `Expected reasonable terms for simple text, but extracted: ${result.join(
+            ', '
+          )} from: "${simpleText}"`
+        ).toBe(true);
+      } else {
+        // LLM assertion that empty result is appropriate for simple text
+        const appropriatelyEmpty = await aiExpect(
+          `For the simple text "${simpleText}", no glossary terms were extracted`
+        ).toSatisfy(
+          'Is it appropriate to extract no glossary terms from this simple, everyday text?',
+          { message: `Expected empty result to be appropriate for simple text: "${simpleText}"` }
+        );
+        expect(
+          appropriatelyEmpty,
+          `Expected empty result to be appropriate for simple text: "${simpleText}"`
+        ).toBe(true);
+      }
+    },
+    longTestTimeout
+  );
+
+  it(
+    'extracts operative philosophical terms for conceptual clarity',
+    async () => {
+      const philosophyText = `Heidegger's concept of Dasein fundamentally challenges the Cartesian subject-object distinction 
+      through his analysis of Being-in-the-world. The phenomenological reduction, as developed by Husserl, 
+      brackets the natural attitude to reveal the intentional structure of consciousness. This hermeneutic circle 
+      demonstrates how our pre-understanding shapes interpretation, while the ontological difference between 
+      beings and Being itself remains concealed in everyday thrownness. Gadamer's fusion of horizons extends 
+      this analysis to show how tradition and prejudice constitute the productive ground of understanding.`;
+
+      const result = await glossary(philosophyText, { maxTerms: 8 });
+
+      expect(result.length).toBeGreaterThan(0);
+      expect(result.length).toBeLessThanOrEqual(8);
+
+      // LLM assertion for philosophical term appropriateness - abstract concepts
+      const arePhilosophicalConcepts = await aiExpect(
+        `From philosophical text, these terms were extracted: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are these terms that would genuinely benefit from precise definition to avoid misunderstanding or ambiguity in philosophical discourse?'
+      );
+      expect(arePhilosophicalConcepts).toBe(true);
+
+      // LLM assertion for conceptual precision - terms that need clarification
+      const needDefinition = await aiExpect(
+        `These philosophical terms: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are these terms that would genuinely benefit from precise definition to avoid misunderstanding or ambiguity in philosophical discourse?',
+        {
+          message: `Expected terms needing precise definition for clarity, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        needDefinition,
+        `Expected terms needing precise definition for clarity, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion for operative significance - terms central to the argument
+      const operativeTerms = await aiExpect(
+        `In the context of phenomenology and hermeneutics, these terms were selected: ${result.join(
+          ', '
+        )}`
+      ).toSatisfy(
+        'Are these terms operatively significant - meaning they carry specific technical weight and are central to understanding the philosophical arguments being made?'
+      );
+      expect(operativeTerms).toBe(true);
+
+      // LLM assertion for avoiding common words - focus on technical terminology
+      const avoidCommonPhilosophical = await aiExpect(
+        `These terms from philosophical text: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are these specialized philosophical terms rather than common words that happen to appear in philosophical contexts?'
+      );
+      expect(avoidCommonPhilosophical).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'extracts operative tech terms across multiple categories',
+    async () => {
+      const techText = `The team implemented Domain-Driven Design using the Repository pattern and CQRS architecture. 
+      Martin Fowler's Strangler Fig pattern helped migrate the legacy system while Kent Beck's Test-Driven Development 
+      approach ensured code quality. We used Docker containers orchestrated by Kubernetes, with Redis for caching 
+      and PostgreSQL for persistence. The CI/CD pipeline leveraged Jenkins and implemented the Blue-Green deployment 
+      strategy. Uncle Bob's Clean Architecture principles guided the service boundaries, while Eric Evans' 
+      Bounded Context concept helped define microservice boundaries. The team followed Scrum methodology with 
+      pair programming sessions.`;
+
+      const result = await glossary(techText, {
+        maxTerms: 12,
+        sortBy:
+          'importance for understanding the content, prioritizing concrete tools and technologies (Docker, Kubernetes, Redis, PostgreSQL, Jenkins) equally with architectural patterns and methodologies',
+      });
+
+      expect(result.length).toBeGreaterThan(0);
+      expect(result.length).toBeLessThanOrEqual(12);
+
+      // LLM assertion for technical tools identification
+      const includesTools = await aiExpect(
+        `From tech text, these terms were extracted: ${result.join(', ')}`
+      ).toSatisfy(
+        'Do these terms include technical tools, technologies, or software systems (like Docker, Kubernetes, Redis, PostgreSQL, Jenkins)?',
+        {
+          message: `Expected to include technical tools/technologies, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        includesTools,
+        `Expected to include technical tools/technologies, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion for design patterns identification
+      const includesPatterns = await aiExpect(
+        `These terms from software development: ${result.join(', ')}`
+      ).toSatisfy(
+        'Do these terms include software design patterns, architectural patterns, or development patterns (like Repository, CQRS, Strangler Fig, Blue-Green)?',
+        {
+          message: `Expected to include design/architectural patterns, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        includesPatterns,
+        `Expected to include design/architectural patterns, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion for methodologies and practices
+      const includesMethodologies = await aiExpect(
+        `From development context, these terms: ${result.join(', ')}`
+      ).toSatisfy(
+        'Do these terms include software development methodologies, practices, or approaches (like Domain-Driven Design, Test-Driven Development, Clean Architecture, Scrum)?',
+        {
+          message: `Expected to include development methodologies/practices, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        includesMethodologies,
+        `Expected to include development methodologies/practices, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion for key people/thought leaders (optional but valuable)
+      const mayIncludePeople = await aiExpect(`These tech terms: ${result.join(', ')}`).toSatisfy(
+        'Do these terms appropriately focus on concepts, tools, and patterns rather than just including person names, while potentially including key thought leaders if they are central to understanding specific methodologies?',
+        {
+          message: `Expected focus on concepts/tools over person names, but got: ${result.join(
+            ', '
+          )}`,
+        }
+      );
+      expect(
+        mayIncludePeople,
+        `Expected focus on concepts/tools over person names, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion for operative significance in tech context
+      const operativeTechTerms = await aiExpect(
+        `In a software development context, these terms: ${result.join(', ')}`
+      ).toSatisfy(
+        'Are these terms operatively significant for understanding the technical architecture, development practices, and implementation decisions being described?',
+        { message: `Expected operatively significant tech terms, but got: ${result.join(', ')}` }
+      );
+      expect(
+        operativeTechTerms,
+        `Expected operatively significant tech terms, but got: ${result.join(', ')}`
+      ).toBe(true);
+
+      // LLM assertion for practical utility - terms that need definition
+      const practicalUtility = await aiExpect(
+        `For someone learning about software architecture and development, these terms: ${result.join(
+          ', '
+        )}`
+      ).toSatisfy(
+        'Are these terms that would genuinely benefit from clear definitions to understand modern software development practices and architectural decisions?',
+        {
+          message: `Expected terms needing definition for learning, but got: ${result.join(', ')}`,
+        }
+      );
+      expect(
+        practicalUtility,
+        `Expected terms needing definition for learning, but got: ${result.join(', ')}`
+      ).toBe(true);
+    },
+    longTestTimeout
+  );
+});

package/src/chains/glossary/index.js

@@ -0,0 +1,75 @@
+import nlp from 'compromise';
+import sort from '../sort/index.js';
+import { bulkMapRetry } from '../bulk-map/index.js';
+import { constants as promptConstants } from '../../prompts/index.js';
+import parseLLMList from '../../lib/parse-llm-list/index.js';
+
+const { onlyJSONStringArrayPerLine } = promptConstants;
+
+/**
+ * Extract uncommon or technical terms from text that would benefit from definition.
+ *
+ * @param {string} text - source text
+ * @param {object} [options]
+ * @param {number} [options.maxTerms=10] - maximum terms to return
+ * @param {number} [options.batchSize=3] - number of sentences per batch
+ * @param {number} [options.overlap=1] - number of overlapping sentences between batches
+ * @param {number} [options.chunkSize=1] - number of text chunks to process in parallel
+ * @param {string} [options.sortBy='importance for understanding the content'] - sorting criteria
+ * @returns {Promise<string[]>} list of important terms, sorted by relevance
+ */
+export default async function glossary(
+  text,
+  {
+    maxTerms = 10,
+    batchSize = 3,
+    overlap = 1,
+    chunkSize = 1,
+    sortBy = 'importance for understanding the content',
+  } = {}
+) {
+  if (!text || !text.trim()) return [];
+
+  // Parse sentences using compromise
+  const doc = nlp(text);
+  const sentences = doc.sentences().out('array');
+
+  if (sentences.length === 0) return [];
+
+  // Create batches of sentences with overlap
+  const textChunks = [];
+  for (let i = 0; i < sentences.length; i += batchSize - overlap) {
+    const batch = sentences.slice(i, i + batchSize);
+    if (batch.length > 0) {
+      textChunks.push(batch.join(' '));
+    }
+  }
+
+  const instructions = `For each text chunk, extract specialized terms that would benefit from definition in a glossary.
+
+Focus on terms that:
+- Are technical, academic, or domain-specific
+- Would be unfamiliar to a general audience  
+- Carry precise meaning in their field
+- Are essential for understanding the content
+
+${onlyJSONStringArrayPerLine}`;
+
+  const mapped = await bulkMapRetry(textChunks, instructions, { chunkSize });
+
+  const termSet = new Set();
+  mapped.forEach((line) => {
+    const terms = parseLLMList(line);
+    terms.forEach((term) => {
+      termSet.add(term);
+    });
+  });
+
+  const terms = Array.from(termSet);
+  if (terms.length === 0) return [];
+
+  // Sort by importance for understanding the content
+  const sorted = await sort(terms, sortBy);
+
+  return sorted.slice(0, maxTerms);
+}

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

@@ -0,0 +1,19 @@
+import { describe, it, expect, vi } from 'vitest';
+import glossary from './index.js';
+
+vi.mock('../bulk-map/index.js', () => ({
+  bulkMapRetry: vi.fn(() => Promise.resolve(['qubits, entanglement', 'decoherence, qubits'])),
+  default: vi.fn(),
+}));
+
+vi.mock('../sort/index.js', () => ({
+  default: vi.fn((list, _criteria, _config) => Promise.resolve(list)),
+}));
+
+describe('glossary', () => {
+  it('collects unique terms', async () => {
+    const text = 'para1\n\npara2';
+    const result = await glossary(text, { maxTerms: 5 });
+    expect(result).toStrictEqual(['qubits', 'entanglement', 'decoherence']);
+  });
+});

package/src/chains/intersections/README.md

@@ -0,0 +1,152 @@
+# Intersections Chain
+
+The intersections chain finds comprehensive intersections for all combinations of items, ensuring consistent and exhaustive results through example-driven improvement with built-in quality validation.
+
+## Real-World Example: Planning a Perfect Weekend
+
+Imagine you're planning activities that work for different groups of people. Let's find intersections between "outdoor enthusiasts", "food lovers", and "budget-conscious friends":
+
+```javascript
+import intersections from './index.js';
+
+const result = await intersections([
+  'outdoor enthusiasts', 
+  'food lovers', 
+  'budget-conscious friends'
+]);
+
+console.log(result);
+```
+
+**Sample Output:**
+```javascript
+{
+  "outdoor enthusiasts + food lovers": {
+    combination: ["outdoor enthusiasts", "food lovers"],
+    description: "Activities that combine outdoor adventure with culinary experiences",
+    elements: [
+      "camping with gourmet cooking",
+      "food truck festivals in parks",
+      "farmers market visits",
+      "outdoor barbecue competitions",
+      "hiking to scenic picnic spots",
+      "beach cookouts",
+      "food foraging tours"
+    ]
+  },
+  "outdoor enthusiasts + budget-conscious friends": {
+    combination: ["outdoor enthusiasts", "budget-conscious friends"],
+    description: "Affordable outdoor activities that don't break the bank",
+    elements: [
+      "free hiking trails",
+      "public beach visits",
+      "city park activities",
+      "free outdoor concerts",
+      "community garden volunteering",
+      "geocaching adventures",
+      "sunset watching spots"
+    ]
+  },
+  "food lovers + budget-conscious friends": {
+    combination: ["food lovers", "budget-conscious friends"],
+    description: "Delicious food experiences that are wallet-friendly",
+    elements: [
+      "happy hour specials",
+      "food truck meals",
+      "potluck dinner parties",
+      "cooking classes at community centers",
+      "ethnic food markets",
+      "restaurant week deals",
+      "home cooking challenges"
+    ]
+  },
+  "outdoor enthusiasts + food lovers + budget-conscious friends": {
+    combination: ["outdoor enthusiasts", "food lovers", "budget-conscious friends"],
+    description: "Perfect activities that satisfy adventure, food, and budget needs",
+    elements: [
+      "picnic in free parks with homemade food",
+      "food truck festivals in public spaces",
+      "community garden potlucks",
+      "beach barbecues with shared costs",
+      "hiking with packed gourmet sandwiches",
+      "free outdoor farmers markets"
+    ]
+  }
+}
+```
+
+## How it Works
+
+1. **Generate Combinations** - Creates all possible combinations of the input items (including single items)
+2. **Shuffle & Score** - Randomly orders combinations and uses AI to score quality (1-10 scale)
+3. **Find Best Examples** - Identifies the first 3 combinations that score above the threshold
+4. **Validate Examples** - Ensures the top examples are high-quality intersections
+5. **Improve All Results** - Uses the best examples as patterns to enhance all intersection results
+6. **Error Handling** - Throws an error if no combinations meet the quality threshold
+
+This approach finds good examples organically, uses them to improve the quality of all results, and validates quality at key checkpoints.
+
+## API Reference
+
+### `intersections(items, options)`
+
+**Parameters:**
+- `items` (Array): Array of items to find intersections between
+- `options` (Object, optional): Configuration options
+  - `instructions` (string): Custom instructions for intersection finding
+  - `minSize` (number, default: 1): Minimum combination size
+  - `maxSize` (number, default: items.length): Maximum combination size  
+  - `batchSize` (number, default: 5): Number of combinations to process in parallel
+  - `goodnessScore` (number, default: 7): Minimum score threshold for good examples (1-10 scale)
+
+**Returns:** Object with intersection results
+
+**Throws:** Error when no combinations score above the goodness threshold
+
+### Usage Examples
+
+```javascript
+// Basic usage
+const results = await intersections(['cats', 'dogs', 'birds']);
+
+// Custom configuration
+const results = await intersections(['hiking', 'photography', 'meditation'], {
+  instructions: 'Focus on peaceful, mindful activities',
+  batchSize: 10,        // Process more combinations in parallel
+  goodnessScore: 8,     // Higher quality threshold
+  minSize: 2,           // Only combinations of 2+ items
+  maxSize: 3            // Maximum 3 items per combination
+});
+
+// Error handling
+try {
+  const results = await intersections(['incompatible', 'categories'], {
+    goodnessScore: 9  // Very high threshold
+  });
+} catch (error) {
+  console.log(error.message); 
+  // "No intersections found with score above 9. Consider lowering the goodnessScore threshold or improving input quality."
+}
+```
+
+## Configuration Tips
+
+- **Lower `goodnessScore`** (5-6) for more permissive quality standards
+- **Higher `goodnessScore`** (8-9) for stricter quality requirements  
+- **Increase `batchSize`** (10-15) for faster processing with good API limits
+- **Decrease `batchSize`** (2-3) to be gentler on API rate limits
+- **Use `instructions`** to guide the AI toward specific types of intersections
+
+## Quality Assurance
+
+The chain includes built-in quality validation:
+
+- **Example Validation**: Ensures the top 3 examples have meaningful descriptions, good element counts, and represent quality intersections
+- **Error Handling**: Throws descriptive errors when quality thresholds aren't met
+- **Parallel Processing**: Efficiently processes combinations in configurable batches
+
+The system learns from its best results and applies those patterns to enhance the quality of all intersections, moving away from predefined categorization methods.
+
+## Usage
+
+```javascript