@far-world-labs/verblets 0.1.1 → 0.1.3

package/src/verblets/auto/index.spec.js

@@ -6,9 +6,8 @@ vi.mock('../../lib/chatgpt/index.js', () => ({
   default: vi.fn().mockImplementation((text) => {
     if (/prompt text to match/.test(text)) {
       return 'True';
-    } else {
-      return 'undefined';
     }
+    return 'undefined';
   }),
 }));
 
@@ -16,8 +15,8 @@ const examples = [
   {
     name: 'Basic usage',
     inputs: { text: 'test' },
-    want: { result: true }
-  }
+    want: { result: true },
+  },
 ];
 
 describe('Auto verblet', () => {
@@ -26,8 +25,7 @@ describe('Auto verblet', () => {
       const result = await auto(example.inputs.text);
 
       if (example.want.typeOfResult) {
-        expect(typeof result)
-          .toStrictEqual(example.want.typeOfResult);
+        expect(typeof result).toStrictEqual(example.want.typeOfResult);
       }
     });
   });

package/src/verblets/bool/README.md

@@ -0,0 +1,36 @@
+# bool
+
+Interpret natural language questions as yes/no decisions and return a boolean.
+The verblet uses ChatGPT to reason about the provided text and responds with
+`true` or `false`.
+
+```javascript
+import bool from './index.js';
+
+const result = await bool('Does Mace Windu have a purple lightsaber?');
+// result === true
+```
+
+## Use case: deployment gate
+
+You can feed dynamic context to `bool` to make policy decisions. Combine local
+variables with text to create nuanced yes/no prompts that a large language model
+can reason about:
+
+```javascript
+const filesChanged = 3;
+const testsPassing = 247;
+const isFriday = true;
+
+const shouldDeploy = await bool(`
+  It's ${isFriday ? 'Friday' : 'a weekday'} at 4:45 PM.
+  ${filesChanged} files changed and all ${testsPassing} tests are passing.
+  The deployment window closes at 5 PM. Should we deploy to production?
+`);
+
+console.log(shouldDeploy);
+// => false  (A cautious answer based on the context)
+```
+
+This approach enables policy checks and decision gates that rely on natural
+language reasoning rather than hard‑coded rules.

package/src/verblets/bool/index.examples.js

@@ -1,6 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
 
 import bool from './index.js';
+import aiExpect from '../expect/index.js';
 import { longTestTimeout } from '../../constants/common.js';
 
 const examples = [
@@ -15,14 +16,65 @@ const examples = [
 ];
 
 describe('Bool verblet', () => {
+  // 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;
+    }
+  });
+
   examples.forEach((example) => {
     it(
       `${example.inputs.text}`,
       async () => {
         const result = await bool(example.inputs.text);
         expect(result).toStrictEqual(example.want.result);
+
+        // Additional LLM assertion to validate the boolean result makes sense
+        const resultMakesSense = await aiExpect({
+          question: example.inputs.text,
+          answer: result,
+        }).toSatisfy('Is this a reasonable yes/no answer to a Star Wars question?');
+        expect(resultMakesSense).toBe(true);
       },
       longTestTimeout
     );
   });
+
+  it(
+    'should handle complex contextual decisions',
+    async () => {
+      const complexQuestion = `
+      Given the context: It's Friday at 4:45 PM, we have 3 files changed (150+ lines, 20- lines), 
+      all 247 tests are passing, and the deployment window closes at 5 PM.
+      Should we deploy this change to production?
+    `;
+
+      const result = await bool(complexQuestion);
+
+      // Traditional assertion
+      expect(typeof result).toBe('boolean');
+
+      // LLM assertion to validate the decision reasoning
+      const decisionIsReasonable = await aiExpect(
+        `The question was about Friday afternoon deployment with passing tests. The decision was: ${result}`
+      ).toSatisfy('Does this sound like a reasonable deployment decision?');
+      expect(decisionIsReasonable).toBe(true);
+
+      // Additional assertion about the decision being conservative
+      const isConservativeDecision = await aiExpect(
+        `A boolean decision of ${result} for Friday afternoon deployment`
+      ).toSatisfy('Is this a cautious approach to deployment timing?');
+      expect(isConservativeDecision).toBe(true);
+    },
+    longTestTimeout
+  );
 });

package/src/verblets/bool/index.js

@@ -3,23 +3,20 @@ import stripResponse from '../../lib/strip-response/index.js';
 import toBool from '../../lib/to-bool/index.js';
 import { constants as promptConstants } from '../../prompts/index.js';
 
-const {
-  asBool,
-  asUndefinedByDefault,
-  contentIsQuestion,
-  explainAndSeparate,
-  explainAndSeparatePrimitive,
-} = promptConstants;
+const { asBool, asUndefinedByDefault, explainAndSeparate, explainAndSeparatePrimitive } =
+  promptConstants;
 
-export default async (text, options={}) => {
+export default async (text, config = {}) => {
+  const { llm, ...options } = config;
   const systemPrompt = `
 ${explainAndSeparate} ${explainAndSeparatePrimitive}
 
 ${asBool} ${asUndefinedByDefault}
-`
+`;
   const response = await chatGPT(text, {
     modelOptions: {
       systemPrompt,
+      ...llm,
     },
     ...options,
   });

package/src/verblets/bool/index.spec.js

@@ -27,9 +27,7 @@ const examples = [
 describe('bool verblet', () => {
   examples.forEach((example) => {
     it(example.name, async () => {
-      expect(await bool(example.inputs.text)).toStrictEqual(
-        example.want.result
-      );
+      expect(await bool(example.inputs.text)).toStrictEqual(example.want.result);
     });
   });
 });

package/src/verblets/central-tendency/README.md

@@ -0,0 +1,166 @@
+# Central Tendency Verblet
+
+A cognitive science-based function for evaluating how central or prototypical an item is within a category. Based on prototype theory and family resemblance principles from cognitive psychology.
+
+## Overview
+
+The `centralTendency` verblet assesses graded typicality by analyzing feature overlap, core characteristics, and functional alignment with seed items. It implements cognitive science principles to provide nuanced category membership evaluation beyond simple binary classification.
+
+## Cognitive Science Foundations
+
+### Prototype Theory
+Categories have graded structure with central (prototypical) and peripheral members. Some items are better examples of a category than others.
+
+### Family Resemblance
+Category members share overlapping features without requiring identical characteristics. Items can belong to a category through different combinations of shared features.
+
+### Graded Typicality
+Membership exists on a continuum from highly typical (central) to atypical (peripheral) rather than binary in/out classification.
+
+## Basic Usage
+
+```javascript
+import { centralTendency } from './index.js';
+
+// Evaluate bird centrality
+const birdSeeds = ['robin', 'sparrow', 'bluejay', 'cardinal'];
+const config = {
+  context: 'Evaluate based on typical bird characteristics and behavior',
+  coreFeatures: ['feathers', 'beak', 'lays eggs'],
+  llm: 'fastGoodCheap'
+};
+
+const result = await centralTendency('robin', birdSeeds, config);
+// Returns: { score: 0.92, reason: "Robin exemplifies core bird features...", confidence: 0.88 }
+
+const penguinResult = await centralTendency('penguin', birdSeeds, config);
+// Returns: { score: 0.65, reason: "Penguin is a bird but lacks flight...", confidence: 0.82 }
+```
+
+## Advanced Features
+
+### Sample Generation
+Generate representative category examples:
+
+```javascript
+import categorySamples from '../../chains/category-samples/index.js';
+
+const animalSamples = await categorySamples('animal', {
+  context: 'Diverse animal kingdom representation across phyla',
+  count: 6,
+  diversityLevel: 'high', // 'high', 'balanced', or 'focused'
+  llm: 'fastGoodCheap'
+});
+// Returns: ['dog', 'eagle', 'salmon', 'butterfly', 'octopus', 'frog']
+```
+
+### Bulk Processing
+Evaluate multiple items efficiently:
+
+```javascript
+import { bulkCentralTendency } from './index.js';
+
+const testAnimals = ['wolf', 'tiger', 'elephant', 'whale'];
+const mammalSeeds = ['dog', 'cat', 'horse', 'cow'];
+
+const results = await bulkCentralTendency(
+  testAnimals,
+  mammalSeeds,
+  {
+    context: 'Mammalian characteristics and traits',
+    coreFeatures: ['warm-blooded', 'hair/fur', 'mammary glands'],
+    llm: 'fastGoodCheap',
+    chunkSize: 3,
+    maxAttempts: 2
+  }
+);
+```
+
+## Parameters
+
+### centralTendency(item, seedItems, config)
+
+- **item** (string): The item to evaluate for centrality
+- **seedItems** (string[]): Array of known category members for comparison
+- **config** (Object): Configuration options
+  - **context** (string): Context description for evaluation (default: '')
+  - **coreFeatures** (string[]): Known core/definitional features of the category (default: [])
+  - **llm** (string): LLM model to use (default: 'fastGoodCheap')
+
+### categorySamples(categoryName, config)
+
+- **categoryName** (string): Name of the category
+- **config** (Object): Configuration options
+  - **context** (string): Context for seed generation (default: '')
+  - **count** (number): Number of seed items to generate (default: 8)
+  - **diversityLevel** (string): 'high', 'balanced', or 'focused' (default: 'balanced')
+  - **llm** (string): LLM model to use (default: 'fastGoodCheap')
+
+## Return Values
+
+### centralTendency Result
+```javascript
+{
+  score: 0.85,        // Centrality score (0.0-1.0)
+  reason: "...",      // Brief explanation of assessment
+  confidence: 0.82    // Confidence in assessment (0.0-1.0)
+}
+```
+
+## Cognitive Science Applications
+
+### Natural vs Artifact Categories
+```javascript
+// Natural categories often have clearer prototypes
+const fruitConfig = {
+  context: 'Botanical fruit classification based on plant biology',
+  coreFeatures: ['seed-bearing', 'develops from flower']
+};
+
+// Artifact categories may be more functionally defined
+const toolConfig = {
+  context: 'Hand tools for mechanical work and construction',
+  coreFeatures: ['handheld', 'mechanical advantage']
+};
+```
+
+### Context Effects on Categorization
+```javascript
+// Same item, different contexts
+const classicalConfig = {
+  context: 'Classical orchestral instruments for formal concerts',
+  coreFeatures: ['acoustic', 'complex technique', 'wide range']
+};
+
+const folkConfig = {
+  context: 'Portable folk instruments for informal music',
+  coreFeatures: ['portable', 'easy to learn', 'expressive']
+};
+
+// Harmonica will score differently in each context
+```
+
+### Category Types
+The verblet works best with:
+- **Natural categories**: Birds, mammals, fruits, minerals
+- **Artifact categories**: Tools, vehicles, furniture, instruments  
+- **Activity categories**: Sports, games, professions, hobbies
+- **Abstract categories**: Emotions, concepts, relationships
+
+Note: Avoid arbitrary collections (e.g., "things in my room") as these lack the coherent structure that prototype theory describes.
+
+## Integration with Concept Science Chains
+
+The `centralTendency` verblet integrates seamlessly with other concept science tools:
+
+```javascript
+// Generate seeds, then evaluate centrality
+const seeds = await categorySamples('vehicle', { context: 'Land transportation' });
+const centrality = await centralTendency('bicycle', seeds, { context: 'Personal transportation' });
+
+// Use in concept hierarchies
+const superordinateSeeds = await categorySamples('animal');
+const basicLevelSeeds = await categorySamples('bird');
+const subordinateResult = await centralTendency('robin', basicLevelSeeds);
+```
+

package/src/verblets/central-tendency/central-tendency-result.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Centrality score from 0.0 (peripheral) to 1.0 (prototypical)"
+    },
+    "reason": {
+      "type": "string",
+      "description": "Brief explanation of centrality assessment"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence in this assessment"
+    }
+  },
+  "required": ["score", "reason", "confidence"]
+} 

package/src/verblets/central-tendency/index.examples.js

@@ -0,0 +1,196 @@
+/**
+ * Examples for centralTendency verblet
+ * Demonstrates cognitive science applications in prototype theory and graded typicality
+ */
+
+import { describe, expect, it } from 'vitest';
+import centralTendency from './index.js';
+import categorySamples from '../../chains/category-samples/index.js';
+import bulkCentralTendency from '../../chains/bulk-central-tendency/index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('centralTendency examples', () => {
+  it(
+    'evaluates bird centrality with new config format',
+    async () => {
+      const birdSeeds = ['robin', 'sparrow', 'bluejay', 'cardinal'];
+
+      const config = {
+        context: 'Evaluate based on typical bird characteristics and behavior',
+        coreFeatures: ['feathers', 'beak', 'lays eggs', 'flight'],
+      };
+
+      // Test prototypical bird
+      const robinResult = await centralTendency('robin', birdSeeds, config);
+      expect(robinResult).toHaveProperty('score');
+      expect(robinResult).toHaveProperty('reason');
+      expect(robinResult).toHaveProperty('confidence');
+      expect(robinResult.score).toBeGreaterThanOrEqual(0.7); // Should be high centrality
+
+      // Test atypical but valid bird
+      const penguinResult = await centralTendency('penguin', birdSeeds, config);
+      expect(penguinResult.score).toBeGreaterThan(0.3);
+      expect(penguinResult.score).toBeLessThan(robinResult.score); // Should be lower than robin
+
+      // Test non-bird that flies
+      const batResult = await centralTendency('bat', birdSeeds, config);
+      expect(batResult.score).toBeLessThan(0.4); // Should be low centrality
+    },
+    longTestTimeout
+  );
+
+  it(
+    'compares natural vs artifact categories with fruit example',
+    async () => {
+      const fruitSeeds = ['apple', 'orange', 'banana', 'grape'];
+
+      // Biological/botanical context
+      const botanicalConfig = {
+        context: 'Judge by botanical definition and structure',
+        coreFeatures: ['seed-bearing', 'develops from flower', 'fleshy pericarp'],
+      };
+
+      // Culinary/folk context
+      const culinaryConfig = {
+        context: 'Judge by culinary use and folk categorization',
+        coreFeatures: ['sweet taste', 'eaten fresh', 'dessert-like'],
+      };
+
+      const botanicalResult = await centralTendency('tomato', fruitSeeds, botanicalConfig);
+      const culinaryResult = await centralTendency('tomato', fruitSeeds, culinaryConfig);
+
+      expect(botanicalResult.score).toBeGreaterThan(culinaryResult.score);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'evaluates tool centrality with core features',
+    async () => {
+      const toolSeeds = ['hammer', 'screwdriver', 'wrench', 'pliers'];
+
+      const config = {
+        context: 'Hand tools for mechanical work and construction',
+        coreFeatures: ['handheld', 'mechanical advantage', 'durable materials'],
+      };
+
+      const drillResult = await centralTendency('drill', toolSeeds, config);
+      const computerResult = await centralTendency('computer', toolSeeds, config);
+
+      expect(drillResult.score).toBeGreaterThan(computerResult.score);
+      expect(drillResult.score).toBeGreaterThanOrEqual(0.6); // Drill should be high (allow boundary)
+      expect(computerResult.score).toBeLessThan(0.5); // Computer should be low
+    },
+    longTestTimeout
+  );
+
+  it(
+    'generates seeds with different diversity levels',
+    async () => {
+      // High diversity seeds
+      const highDiversitySeeds = await categorySamples('animal', {
+        context: 'Diverse animal kingdom representation across phyla',
+        count: 6,
+        diversityLevel: 'high',
+      });
+
+      expect(Array.isArray(highDiversitySeeds)).toBe(true);
+      expect(highDiversitySeeds.length).toBeGreaterThan(0);
+      expect(highDiversitySeeds.length).toBeLessThanOrEqual(6);
+
+      // Focused seeds
+      const focusedSeeds = await categorySamples('bird', {
+        context: 'Common backyard birds',
+        count: 5,
+        diversityLevel: 'focused',
+      });
+
+      expect(Array.isArray(focusedSeeds)).toBe(true);
+      expect(focusedSeeds.length).toBeGreaterThan(0);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'processes bulk items with error handling',
+    async () => {
+      const mammalSeeds = ['dog', 'cat', 'horse', 'cow'];
+      const testAnimals = ['wolf', 'tiger', 'elephant', 'whale', 'bat'];
+
+      const config = {
+        context: 'Mammalian characteristics and traits',
+        coreFeatures: ['warm-blooded', 'hair/fur', 'mammary glands', 'live birth'],
+        chunkSize: 3,
+        maxAttempts: 2,
+      };
+
+      const results = await bulkCentralTendency(testAnimals, mammalSeeds, config);
+
+      expect(results).toHaveLength(testAnimals.length);
+
+      // Check that most results are valid
+      const validResults = results.filter((r) => r !== undefined);
+      expect(validResults.length).toBeGreaterThan(testAnimals.length * 0.6);
+
+      // Validate structure of valid results
+      validResults.forEach((result) => {
+        expect(result).toHaveProperty('score');
+        expect(result).toHaveProperty('reason');
+        expect(result).toHaveProperty('confidence');
+        expect(result.score).toBeGreaterThanOrEqual(0);
+        expect(result.score).toBeLessThanOrEqual(1);
+      });
+    },
+    longTestTimeout
+  );
+
+  it(
+    'demonstrates graded typicality in sports',
+    async () => {
+      const sportsSeeds = ['basketball', 'football', 'tennis', 'swimming'];
+
+      const config = {
+        context: 'Competitive physical activities with rules and scoring',
+        coreFeatures: ['rules', 'competition', 'physical skill', 'scoring'],
+      };
+
+      const soccerResult = await centralTendency('soccer', sportsSeeds, config);
+      const chessResult = await centralTendency('chess', sportsSeeds, config);
+      const videoGamesResult = await centralTendency('video games', sportsSeeds, config);
+
+      // Expect graded typicality: soccer should be more central than chess for physical sports
+      expect(soccerResult.score).toBeGreaterThan(chessResult.score);
+      // All results should be valid scores
+      expect(chessResult.score).toBeGreaterThanOrEqual(0);
+      expect(videoGamesResult.score).toBeGreaterThanOrEqual(0);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'demonstrates context steering effects',
+    async () => {
+      const musicSeeds = ['piano', 'guitar', 'violin', 'drums'];
+      const testItem = 'harmonica';
+
+      // Traditional/classical music context
+      const classicalConfig = {
+        context: 'Classical and orchestral instruments for formal concerts',
+        coreFeatures: ['acoustic', 'complex technique', 'wide range'],
+      };
+
+      // Folk/portable music context
+      const folkConfig = {
+        context: 'Portable folk and street instruments',
+        coreFeatures: ['portable', 'easy to learn', 'expressive'],
+      };
+
+      const classicalResult = await centralTendency(testItem, musicSeeds, classicalConfig);
+      const folkResult = await centralTendency(testItem, musicSeeds, folkConfig);
+
+      // Harmonica should score higher in folk context
+      expect(folkResult.score).toBeGreaterThan(classicalResult.score);
+    },
+    longTestTimeout
+  );
+});