@far-world-labs/verblets 0.1.1 → 0.1.3

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

@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from 'vitest';
+import aiExpect from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+// Mock the chatgpt function to avoid actual API calls
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn().mockImplementation((prompt) => {
+    // Handle exact equality checks
+    if (prompt.includes('Does the actual value strictly equal the expected value?')) {
+      if (prompt.includes('Actual: "hello"') && prompt.includes('Expected: "hello"')) {
+        return 'True';
+      }
+      if (prompt.includes('Actual: "goodbye"') && prompt.includes('Expected: "hello"')) {
+        return 'False';
+      }
+    }
+
+    // Handle constraint-based validations (format: "Given this constraint:")
+    if (prompt.includes('Given this constraint:')) {
+      if (prompt.includes('Is this a greeting?') && prompt.includes('Hello world!')) {
+        return 'True';
+      }
+
+      if (prompt.includes('Is this text professional and grammatically correct?')) {
+        if (prompt.includes('well-written, professional email')) {
+          return 'True';
+        }
+      }
+
+      if (prompt.includes('Does this person data look realistic?')) {
+        if (prompt.includes('John Doe') && prompt.includes('"age": 30')) {
+          return 'True';
+        }
+      }
+
+      if (prompt.includes('Is this recommendation specific and actionable?')) {
+        if (prompt.includes('Increase marketing budget by 20%')) {
+          return 'True';
+        }
+      }
+    }
+
+    // Default to False for unmatched cases
+    return 'False';
+  }),
+}));
+
+describe('expect verblet', () => {
+  it(
+    'should pass for exact equality',
+    async () => {
+      const result = await aiExpect('hello').toEqual('hello', { throws: false });
+      expect(result).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should pass for constraint-based validation',
+    async () => {
+      const result = await aiExpect('Hello world!').toSatisfy('Is this a greeting?', {
+        throws: false,
+      });
+      expect(result).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should fail for non-matching values',
+    async () => {
+      const result = await aiExpect('goodbye').toEqual('hello', {
+        throws: false,
+      });
+      expect(result).toBe(false);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should validate content quality',
+    async () => {
+      const result = await aiExpect(
+        'This is a well-written, professional email with proper grammar.'
+      ).toSatisfy('Is this text professional and grammatically correct?', {
+        throws: false,
+      });
+      expect(result).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should validate data structures',
+    async () => {
+      const result = await aiExpect({ name: 'John Doe', age: 30, city: 'New York' }).toSatisfy(
+        'Does this person data look realistic?',
+        { throws: false }
+      );
+      expect(result).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should handle business logic validation',
+    async () => {
+      const result = await aiExpect(
+        'Increase marketing budget by 20% for Q4 to boost holiday sales'
+      ).toSatisfy('Is this recommendation specific and actionable?', {
+        throws: false,
+      });
+      expect(result).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should throw by default on failure',
+    async () => {
+      await expect(async () => {
+        await aiExpect('hello').toEqual('goodbye');
+      }).rejects.toThrow('LLM assertion failed');
+    },
+    longTestTimeout
+  );
+});

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

@@ -1,29 +1,50 @@
 import Ajv from 'ajv';
 import fs from 'node:fs/promises';
-import { describe, expect, it } from 'vitest';
-
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import { expect as aiExpect } from '../../chains/expect/index.js';
 import { longTestTimeout } from '../../constants/common.js';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
 import intent from './index.js';
 
-const resultSchema = async () => {
-  return JSON.parse(await fs.readFile('./src/json-schemas/intent.json'));
-};
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+async function getIntentSchema() {
+  return JSON.parse(await fs.readFile(join(__dirname, '../../json-schemas/intent.json')));
+}
 
 const examples = [
   {
     inputs: { text: 'Give me a flight to Burgas' },
-    want: { resultSchema },
+    want: { resultSchema: getIntentSchema },
   },
   {
     inputs: {
       text: 'Lookup a song by the quote \
 "I just gotta tell you how I\'m feeling"',
     },
-    want: { resultSchema },
+    want: { resultSchema: getIntentSchema },
   },
 ];
 
 describe('Intent 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,
@@ -43,9 +64,76 @@ describe('Intent verblet', () => {
             console.error(JSON.stringify(result, null, 2));
           }
           expect(isValid).toStrictEqual(true);
+
+          // LLM assertion to validate intent extraction quality
+          const intentMakesSense = await aiExpect(
+            `Original text: "${example.inputs.text}" was parsed into an intent object`
+          ).toSatisfy('Does this seem like a reasonable intent extraction?');
+          expect(intentMakesSense).toBe(true);
+
+          // Additional assertion for intent completeness
+          const hasBasicInfo = await aiExpect(JSON.stringify(result)).toSatisfy(
+            'Does this intent object contain some useful information?'
+          );
+          expect(hasBasicInfo).toBe(true);
         }
       },
       longTestTimeout
     );
   });
+
+  it(
+    'should extract travel booking intent correctly',
+    async () => {
+      const travelRequest =
+        'Book me a round-trip flight from New York to Tokyo for next month, preferably business class';
+      const result = await intent({ text: travelRequest });
+
+      // Traditional schema validation
+      const schema = await getIntentSchema();
+      const ajv = new Ajv();
+      const validate = ajv.compile(schema);
+      expect(validate(result)).toBe(true);
+
+      // LLM assertions for travel-specific validation
+      const isTravelRelated = await aiExpect(`Intent extracted from: "${travelRequest}"`).toSatisfy(
+        'Is this request related to travel or transportation?'
+      );
+      expect(isTravelRelated).toBe(true);
+
+      const hasLocationInfo = await aiExpect(JSON.stringify(result)).toSatisfy(
+        'Does this intent mention any locations or destinations?'
+      );
+      expect(hasLocationInfo).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should handle entertainment search intent',
+    async () => {
+      const musicQuery =
+        'Find that song that goes "Never gonna give you up, never gonna let you down"';
+      const result = await intent({ text: musicQuery });
+
+      // Schema validation
+      const schema = await getIntentSchema();
+      const ajv = new Ajv();
+      const validate = ajv.compile(schema);
+      expect(validate(result)).toBe(true);
+
+      // LLM assertion for entertainment intent
+      const isEntertainmentRelated = await aiExpect(
+        `Intent extracted from: "${musicQuery}"`
+      ).toSatisfy('Is this request related to music or entertainment?');
+      expect(isEntertainmentRelated).toBe(true);
+
+      // Validate that the intent captures the search criteria
+      const mentionsLyrics = await aiExpect(JSON.stringify(result)).toSatisfy(
+        'Does this intent mention song lyrics or music search?'
+      );
+      expect(mentionsLyrics).toBe(true);
+    },
+    longTestTimeout
+  );
 });

package/src/verblets/intent/index.js

@@ -1,72 +1,60 @@
-import enums from '../enum/index.js';
-import toObject from '../to-object/index.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import chatGPT from '../../lib/chatgpt/index.js';
-import stripResponse from '../../lib/strip-response/index.js';
-
-import { constants, intent, wrapVariable } from '../../prompts/index.js';
-
-const { contentHasIntent } = constants;
-const example1 =
-  'The intent of "Buy me a flight to Burgas" might be "buy-flight"';
-const example2 =
-  'The intent of "What is the tempature outside" might be "get-temperature"';
-
-const enumPrompt = (text) => `${contentHasIntent} ${wrapVariable(text, {
-  tag: 'message',
-})}
-
-${wrapVariable(example1, { tag: 'example' })}
-${wrapVariable(example2, { tag: 'example' })}`;
-
-const completionIntent = (text) => ({
-  queryText: text,
-  intent: {
-    operation: 'completion',
-    displayName: 'Completion',
-  },
-  parameters: {
-    text,
-  },
-});
-
-export default async ({
-  text,
-  operations,
-  defaultIntent = completionIntent,
-  options,
-} = {}) => {
-  let operationsFound;
-  let parametersFound;
-  if (operations) {
-    const operationsEnum = operations.reduce(
-      (acc, item, idx) => ({
-        ...acc,
-        [item.name]: idx,
-      }),
-      {}
-    );
-
-    const operationNameFound = await enums(enumPrompt(text), operationsEnum);
-
-    const operationFound = operations.find(
-      (o) => o.name === operationNameFound
-    );
-
-    if (!operationFound) {
-      return defaultIntent(text);
-    }
-
-    operationsFound = [operationFound.name];
-    parametersFound = operationFound.parameters;
+import { constants as promptConstants } from '../../prompts/index.js';
+
+const { contentIsQuestion } = promptConstants;
+
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Load the JSON schema for intent results
+ * @returns {Promise<Object>} JSON schema for validation
+ */
+async function getIntentSchema() {
+  const schemaPath = path.resolve(__dirname, '../../json-schemas/intent.json');
+  return JSON.parse(await fs.readFile(schemaPath, 'utf8'));
+}
+
+/**
+ * Create model options for structured outputs
+ * @param {string|Object} llm - LLM model name or configuration object
+ * @returns {Promise<Object>} Model options for chatGPT
+ */
+async function createModelOptions(llm = 'fastGoodCheap') {
+  const schema = await getIntentSchema();
+
+  const responseFormat = {
+    type: 'json_schema',
+    json_schema: {
+      name: 'intent_result',
+      schema,
+    },
+  };
+
+  if (typeof llm === 'string') {
+    return {
+      modelName: llm,
+      response_format: responseFormat,
+    };
+  } else {
+    return {
+      ...llm,
+      response_format: responseFormat,
+    };
   }
+}
+
+export default async function intent({ text, config = {} } = {}) {
+  const { llm, ...options } = config;
+  const prompt = `${contentIsQuestion} What is the intent of this text?\n\n${text}`;
 
-  const result = await chatGPT(
-    intent(text, {
-      operations: operationsFound,
-      parameters: parametersFound,
-    }),
-    options
-  );
+  const modelOptions = await createModelOptions(llm);
+  const response = await chatGPT(prompt, { modelOptions, ...options });
 
-  return toObject(stripResponse(result));
-};
+  // With structured outputs, response should already be parsed
+  return typeof response === 'string' ? JSON.parse(response) : response;
+}

package/src/verblets/intersection/README.md

@@ -0,0 +1,16 @@
+# intersection
+
+Find common threads between multiple items using an LLM. The verblet checks every combination from pairs up to the full set. If no relationship is obvious, an empty array is returned.
+
+```javascript
+import intersection from './index.js';
+
+await intersection(['smartphone', 'tablet', 'laptop']);
+// => ['Portable electronics', 'Portable computers']
+
+// Provide custom instructions for how to find intersections
+await intersection(['car', 'bicycle', 'train'], {
+  instructions: 'focus on transportation methods available in a city',
+});
+// => ['Wheeled vehicles', 'Public transit']
+```

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

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import intersection from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+import aiExpect from '../expect/index.js';
+
+describe('intersection examples', () => {
+  it(
+    'finds commonalities among devices',
+    async () => {
+      const result = await intersection(['smartphone', 'laptop', 'tablet']);
+      expect(Array.isArray(result), `Saw: ${JSON.stringify(result)}`).toBe(true);
+
+      // LLM assertion to verify the intersection contains meaningful commonalities
+      await aiExpect(result).toSatisfy(
+        'should be an array of strings that could reasonably represent commonalities between technology devices',
+        {
+          context: 'Testing intersection verblet with electronic devices',
+        }
+      );
+    },
+    longTestTimeout
+  );
+
+  it(
+    'finds commonalities among animals',
+    async () => {
+      const result = await intersection(['dog', 'cat', 'bird']);
+      expect(Array.isArray(result), `Saw: ${JSON.stringify(result)}`).toBe(true);
+
+      // LLM assertion for animal traits - be more lenient
+      await aiExpect(result).toSatisfy(
+        'should be an array that represents some form of analysis or commonalities related to animals',
+        {
+          context: 'Testing intersection verblet with animals',
+        }
+      );
+
+      // Just check that it's an array - don't require specific content
+      expect(Array.isArray(result)).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'handles abstract concepts',
+    async () => {
+      const result = await intersection(['love', 'friendship', 'trust']);
+      expect(Array.isArray(result), `Saw: ${JSON.stringify(result)}`).toBe(true);
+
+      // LLM assertion for abstract concept intersections - be more specific
+      await aiExpect(result).toSatisfy(
+        'should be an array of strings representing common emotional or relational concepts that love, friendship, and trust share (like emotional connection, mutual respect, care, etc.)',
+        {
+          context: 'Testing intersection verblet with abstract concepts: love, friendship, trust',
+        }
+      );
+
+      // Verify it's a non-empty array with string elements
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+      expect(result.every((item) => typeof item === 'string')).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'works with single item',
+    async () => {
+      const result = await intersection(['bicycle']);
+      expect(Array.isArray(result), `Saw: ${JSON.stringify(result)}`).toBe(true);
+
+      // Single items should return empty array based on the implementation
+      expect(result.length).toBe(0);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'handles empty input gracefully',
+    async () => {
+      const result = await intersection([]);
+      expect(Array.isArray(result), `Saw: ${JSON.stringify(result)}`).toBe(true);
+
+      // Empty input should return empty array
+      expect(result.length).toBe(0);
+    },
+    longTestTimeout
+  );
+});

package/src/verblets/intersection/index.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chatGPT from '../../lib/chatgpt/index.js';
+import wrapVariable from '../../prompts/wrap-variable.js';
+import { constants as promptConstants } from '../../prompts/index.js';
+
+const { contentIsQuestion, tryCompleteData, onlyJSONStringArray } = promptConstants;
+
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * 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'));
+}
+
+/**
+ * Create model options for structured outputs
+ * @param {string|Object} llm - LLM model name or configuration object
+ * @returns {Promise<Object>} Model options for chatGPT
+ */
+async function createModelOptions(llm = 'fastGoodCheap') {
+  const schema = await getIntersectionSchema();
+
+  const responseFormat = {
+    type: 'json_schema',
+    json_schema: {
+      name: 'intersection_result',
+      schema,
+    },
+  };
+
+  if (typeof llm === 'string') {
+    return {
+      modelName: llm,
+      response_format: responseFormat,
+    };
+  } else {
+    return {
+      ...llm,
+      response_format: responseFormat,
+    };
+  }
+}
+
+export const buildPrompt = (items, { instructions } = {}) => {
+  const itemsList = items.join(' | ');
+  const itemsBlock = wrapVariable(itemsList, { tag: 'items' });
+  const intro =
+    instructions ||
+    'List the common features, instances, or relational links that all items share.';
+
+  return `${contentIsQuestion} ${intro}
+
+${itemsBlock}
+
+The array should specify items without context, groupings, or any other data--just names.
+
+${tryCompleteData} ${onlyJSONStringArray}`;
+};
+
+export default async function intersection(items, config = {}) {
+  if (!Array.isArray(items) || items.length < 2) return [];
+
+  const { llm, ...options } = config;
+  const modelOptions = await createModelOptions(llm);
+
+  const output = await chatGPT(buildPrompt(items, options), {
+    modelOptions,
+  });
+
+  // With structured outputs, response should already be parsed and validated
+  const parsed = typeof output === 'string' ? JSON.parse(output) : output;
+
+  // Extract the items array from the object structure
+  const resultArray = parsed?.items || parsed;
+  return Array.isArray(resultArray) ? resultArray.filter(Boolean) : [];
+}

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

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi } from 'vitest';
+import intersection from './index.js';
+
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn(async (prompt) => {
+    console.log('Mock received prompt:', prompt);
+    // Look for quoted items in the prompt
+    const match = prompt.match(/"([^"]+)"/);
+    if (match) {
+      const itemsLine = match[1];
+      const items = itemsLine.split(' | ');
+      const commonalities = items.map((item) => `common: ${item}`);
+      // Add combinations
+      for (let i = 0; i < items.length; i++) {
+        for (let j = i + 1; j < items.length; j++) {
+          commonalities.push(`common: ${items[i]} | ${items[j]}`);
+        }
+      }
+      // Add all items combination
+      if (items.length > 2) {
+        commonalities.push(`common: ${items.join(' | ')}`);
+      }
+      console.log('Mock returning:', JSON.stringify(commonalities));
+      return JSON.stringify(commonalities);
+    }
+    console.log('Mock: no match found, returning empty array');
+    return JSON.stringify([]);
+  }),
+}));
+
+describe('intersection verblet', () => {
+  it('describes commonalities between sets', async () => {
+    const result = await intersection(['a', 'b', 'c']);
+    expect(result).toStrictEqual([
+      'common: a',
+      'common: b',
+      'common: c',
+      'common: a | b',
+      'common: a | c',
+      'common: b | c',
+      'common: a | b | c',
+    ]);
+  });
+
+  it('includes custom instructions in the prompt', async () => {
+    const chatGPT = (await import('../../lib/chatgpt/index.js')).default;
+    await intersection(['x', 'y', 'z'], { instructions: 'focus on features' });
+    expect(chatGPT).toHaveBeenCalledWith(
+      expect.stringContaining('focus on features'),
+      expect.any(Object)
+    );
+  });
+
+  it('returns empty array when model returns empty response', async () => {
+    const chatGPT = (await import('../../lib/chatgpt/index.js')).default;
+    chatGPT.mockResolvedValueOnce('[]');
+    const result = await intersection(['x', 'y']);
+    expect(result).toStrictEqual([]);
+  });
+});

package/src/verblets/intersection/intersection-result.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "items": {
+      "type": "array",
+      "description": "Array of common features, instances, or relational links shared by all items",
+      "items": {
+        "type": "string",
+        "description": "A common feature, instance, or relational link"
+      }
+    }
+  },
+  "required": ["items"],
+  "additionalProperties": false
+} 

package/src/verblets/list-expand/README.md

@@ -0,0 +1,10 @@
+# list-expand
+
+Generate additional items that fit naturally with the given list. The function sends the provided items to ChatGPT and requests more entries of the same kind, returning the expanded list.
+
+```javascript
+import listExpand from './index.js';
+
+await listExpand(['red', 'green'], 5);
+// => ['red', 'green', 'blue', 'yellow', 'purple']
+```

package/src/verblets/list-expand/index.examples.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import listExpand from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('list-expand examples', () => {
+  it(
+    'expands a short list of fruits',
+    async () => {
+      const result = await listExpand(['apple', 'banana'], 5);
+      expect(result.length).toBeGreaterThanOrEqual(5);
+    },
+    longTestTimeout
+  );
+});