@far-world-labs/verblets 0.1.1 → 0.1.3

package/src/verblets/list-reduce/index.spec.jsx

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+import listReduce from './index.js';
+
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn((prompt) => {
+    const listMatch = prompt.match(/<list>\n([\s\S]*?)\n<\/list>/);
+    const accMatch = prompt.match(/<accumulator>\n([\s\S]*?)\n<\/accumulator>/);
+
+    if (listMatch && accMatch) {
+      const acc = accMatch[1].trim();
+      const lines = listMatch[1]
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+      return `${acc}+${lines.join('+')}`;
+    }
+    // Return the joined result as expected
+    return [acc, ...lines].join('+');
+  }),
+}));
+
+describe('list-reduce verblet', () => {
+  it('reduces items using instructions', async () => {
+    const result = await listReduce('0', ['a', 'b', 'c'], 'join');
+    expect(result).toBe('0+a+b+c');
+  });
+});

package/src/verblets/name/README.md

@@ -0,0 +1,15 @@
+# name
+Generate a short, descriptive name for any text or concept.
+
+This verblet taps into the language model's understanding of nuance to create names that capture the essence of your content. Use it whenever a simple keyword search isn't enough and you want an evocative title.
+
+## Usage
+
+```javascript
+import { name } from '@far-world-labs';
+
+const diaryTitle = await name(
+  'Voice memos from friends sharing their hopes and worries'
+);
+console.log(diaryTitle); // "Shared Reflections" (example)
+```

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

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { longTestTimeout } from '../../constants/common.js';
+import name from './index.js';
+
+const examples = [
+  { got: { text: 'Chat logs for customer support' }, want: 'chatSupportLogs' },
+  { got: { text: 'Sensor readings from smart home devices' }, want: 'smartHomeSensorReadings' },
+  {
+    got: {
+      text: 'Voice memos from friends sharing their hopes and worries',
+    },
+    want: 'voiceMemos',
+  },
+];
+
+describe('name verblet', () => {
+  examples.forEach((example) => {
+    it(
+      example.got.text,
+      async () => {
+        const result = await name(example.got.text);
+        expect(typeof result).toBe('string');
+        expect(result.length).toBeGreaterThan(0);
+      },
+      longTestTimeout
+    );
+  });
+});

package/src/verblets/name/index.js

@@ -0,0 +1,19 @@
+import chatGPT from '../../lib/chatgpt/index.js';
+import stripResponse from '../../lib/strip-response/index.js';
+import wrapVariable from '../../prompts/wrap-variable.js';
+import { constants as promptConstants } from '../../prompts/index.js';
+
+const { asUndefinedByDefault, contentIsQuestion } = promptConstants;
+
+export default async function name(subject, config = {}) {
+  const { llm, ...options } = config;
+  const prompt = `${contentIsQuestion} Suggest a concise, memorable name for the <subject>.\n\n${wrapVariable(
+    subject,
+    {
+      tag: 'subject',
+    }
+  )} ${asUndefinedByDefault}`;
+  const response = await chatGPT(prompt, { modelOptions: { ...llm }, ...options });
+  const [firstLine] = stripResponse(response).split('\n');
+  return firstLine.trim();
+}

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

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import name from './index.js';
+
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn().mockImplementation((text) => {
+    if (/weather pattern/i.test(text)) {
+      return 'BlueSkies';
+    }
+    return 'undefined';
+  }),
+}));
+
+const examples = [
+  {
+    name: 'Generates descriptive name',
+    inputs: { text: 'Dataset of weather pattern observations' },
+    want: { result: 'BlueSkies' },
+  },
+  {
+    name: 'Returns undefined when unsure',
+    inputs: { text: '???' },
+    want: { result: 'undefined' },
+  },
+];
+
+describe('name verblet', () => {
+  examples.forEach((example) => {
+    it(example.name, async () => {
+      expect(await name(example.inputs.text)).toStrictEqual(example.want.result);
+    });
+  });
+});

package/src/verblets/name-similar-to/README.md

@@ -0,0 +1,26 @@
+# name-similar-to
+
+Generate a short, catchy name for something using the style of existing names. This verblet relies on a language model to capture the tone and brevity of your sample names.
+
+```javascript
+import nameSimilarTo from './index.js';
+
+const newName = await nameSimilarTo(
+  'dataset of daily coffee tasting notes',
+  ['BeanDiary', 'RoastLog', 'BrewIndex']
+);
+// => 'TastingLog'
+```
+
+## Example: naming a hiking journal
+
+Imagine cataloging your weekend trail adventures. You already use names like `TrailNotes`, `GearTips`, and `CampfireStories`. Ask the verblet to suggest a matching name for your wildlife sightings log:
+
+```javascript
+const exampleNames = ['TrailNotes', 'GearTips', 'CampfireStories'];
+const wildlifeLog = await nameSimilarTo(
+  'journal of wildlife spotted on each hike',
+  exampleNames
+);
+// => 'WildlifeWatch'
+```

package/src/verblets/name-similar-to/index.examples.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import nameSimilarTo from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('nameSimilarTo examples', () => {
+  it(
+    'suggests a matching name',
+    async () => {
+      const result = await nameSimilarTo('record of coffee tasting notes', [
+        'BeanDiary',
+        'RoastLog',
+        'BrewIndex',
+      ]);
+      expect(typeof result).toBe('string');
+    },
+    longTestTimeout
+  );
+});

package/src/verblets/name-similar-to/index.js

@@ -0,0 +1,20 @@
+import chatGPT from '../../lib/chatgpt/index.js';
+import wrapVariable from '../../prompts/wrap-variable.js';
+
+const buildPrompt = (description, exampleNames) => {
+  const descriptionBlock = wrapVariable(description, { tag: 'description' });
+  const exampleNamesBlock = wrapVariable(exampleNames.join('\n'), { tag: 'example-names' });
+
+  return `Generate a name similar to the <example-names> that fits the <description>. Return only the name, nothing else.
+
+${descriptionBlock}
+
+${exampleNamesBlock}`;
+};
+
+export default async function nameSimilarTo(description, exampleNames = [], config = {}) {
+  const { llm, ...options } = config;
+  const prompt = buildPrompt(description, exampleNames);
+  const output = await chatGPT(prompt, { modelOptions: { ...llm }, ...options });
+  return output.split('\n')[0].trim();
+}

package/src/verblets/name-similar-to/index.spec.js

@@ -0,0 +1,13 @@
+import { describe, expect, it, vi } from 'vitest';
+import nameSimilarTo from './index.js';
+
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn(async () => 'freshName'),
+}));
+
+describe('nameSimilarTo verblet', () => {
+  it('generates a name matching the example style', async () => {
+    const result = await nameSimilarTo('some data about sales', ['salesStats', 'revenueReport']);
+    expect(result).toBe('freshName');
+  });
+});

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

@@ -1,16 +1,17 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
 
 import number from './index.js';
+import aiExpect from '../expect/index.js';
 import { longTestTimeout } from '../../constants/common.js';
 
 const examples = [
   {
     inputs: { text: 'What is the height of Everest in feet' },
-    want: { result: 29029 },
+    want: { range: [29000, 29100] }, // Tolerant range around 29032
   },
   {
     inputs: { text: 'What is the length of the Nile in km' },
-    want: { result: 6650 },
+    want: { range: [6000, 7000] }, // Tolerant range around 6650
   },
   {
     inputs: { text: 'What is the my age in years' },
@@ -19,15 +20,180 @@ const examples = [
 ];
 
 describe('Number 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,
+      `${example.inputs.text}`,
       async () => {
-        expect(await number(example.inputs.text)).toStrictEqual(
-          example.want.result
-        );
+        const result = await number(example.inputs.text);
+
+        if (example.want.range) {
+          expect(result).toBeGreaterThanOrEqual(example.want.range[0]);
+          expect(result).toBeLessThanOrEqual(example.want.range[1]);
+
+          // LLM assertion for range validation
+          const isReasonableValue = await aiExpect(
+            `Question: "${example.inputs.text}" Answer: ${result}`
+          ).toSatisfy('Is this a reasonable numeric answer for a geographic question?');
+          expect(isReasonableValue).toBe(true);
+        } else if (example.want.result !== undefined) {
+          expect(result).toStrictEqual(example.want.result);
+        } else {
+          expect(result).toStrictEqual(example.want.result);
+
+          // LLM assertion for undefined results
+          if (example.want.result === undefined) {
+            const shouldBeUndefined = await aiExpect(
+              `Question: "${example.inputs.text}"`
+            ).toSatisfy('Does this question lack enough context to give a specific number?');
+            expect(shouldBeUndefined).toBe(true);
+          }
+        }
       },
       longTestTimeout
     );
   });
+
+  it(
+    'should extract numbers from recipe contexts',
+    async () => {
+      const recipeText =
+        'What temperature should I bake the cookies at? They need to be baked for 12 minutes until golden brown';
+      const result = await number(recipeText);
+
+      expect(typeof result).toBe('number');
+      expect(result).toBeGreaterThan(0);
+
+      // LLM assertion to validate recipe number extraction
+      const isCorrectBakeTime = await aiExpect(
+        `Recipe: "${recipeText}" Extracted number: ${result}`
+      ).toSatisfy('Is this number related to baking time or temperature?');
+      expect(isCorrectBakeTime).toBe(true);
+
+      // LLM assertion to validate temperature unit
+      const hasTemperatureUnit = await aiExpect(
+        `Recipe text: "${recipeText}" Extracted number: ${result}`
+      ).toSatisfy('Is this number likely a temperature in Fahrenheit (e.g. 350°F)?');
+      expect(hasTemperatureUnit).toBe(true);
+
+      // Additional assertion about reasonableness
+      const isReasonableBakeTime = await aiExpect(
+        `Extracted number: ${result} from a baking recipe`
+      ).toSatisfy('Is this a reasonable number for cooking?');
+      expect(isReasonableBakeTime).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should handle financial calculations',
+    async () => {
+      const financialQuery =
+        'If I invest $1000 at 5% annual compound interest for 10 years, how much will I have?';
+      const result = await number(financialQuery);
+
+      expect(typeof result).toBe('number');
+      expect(result).toBeGreaterThan(1000); // Should be more than principal
+
+      // LLM assertion for financial calculation accuracy
+      const isReasonableReturn = await aiExpect(
+        `Investment question about $1000 at 5% for 10 years. Answer: $${result}`
+      ).toSatisfy('Is this a reasonable amount for a 10-year investment?');
+      expect(isReasonableReturn).toBe(true);
+
+      // Validate the calculation makes financial sense
+      const followsCompoundInterest = await aiExpect(
+        `Starting with $1000, ending with $${result} after 10 years`
+      ).toSatisfy('Does this show reasonable investment growth?');
+      expect(followsCompoundInterest).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should handle financial calculations with compound interest',
+    async () => {
+      const result = await number(
+        'If I invest $1000 at 5% annual interest for 10 years, what will be the final amount?'
+      );
+
+      expect(typeof result).toBe('number');
+      // Simple interest would be 1000 + (1000 * 0.05 * 10) = 1500
+      expect(result).toBeGreaterThan(1500);
+
+      // LLM assertion for financial calculation accuracy
+      const isReasonableReturn = await aiExpect(
+        `Investment: $1000 at 5% for 10 years. Final amount: $${result}`
+      ).toSatisfy(
+        'Is this a reasonable final amount for compound interest over 10 years? It should be significantly more than the principal due to compound growth.',
+        {
+          message: `Expected reasonable compound interest growth, but got: $${result}`,
+        }
+      );
+      expect(isReasonableReturn).toBe(true);
+
+      // LLM assertion for compound interest validation
+      const followsCompoundInterest = await aiExpect(
+        `Starting with $1000 at 5% annual interest for 10 years, the final amount is $${result}`
+      ).toSatisfy(
+        'Does this final amount follow the expected pattern of compound interest growth? It should be more than simple interest (which would be $1500) and less than exponential growth.',
+        {
+          message: `Expected compound interest growth pattern, but got: $${result}`,
+        }
+      );
+      expect(followsCompoundInterest).toBe(true);
+    },
+    longTestTimeout
+  );
+
+  it(
+    'should handle financial calculations with compound interest',
+    async () => {
+      const result = await number(
+        'If I invest $1000 at 5% annual interest for 10 years, what will be the final amount?'
+      );
+
+      expect(typeof result).toBe('number');
+      // Simple interest would be 1000 + (1000 * 0.05 * 10) = 1500
+      // Compound interest should be more than simple interest
+      expect(result).toBeGreaterThan(1500);
+
+      // LLM assertion for financial calculation accuracy
+      const isReasonableReturn = await aiExpect(
+        `Investment: $1000 at 5% for 10 years. Final amount: $${result}`
+      ).toSatisfy(
+        'Is this a reasonable final amount for compound interest over 10 years? It should be significantly more than the principal due to compound growth.',
+        {
+          message: `Expected reasonable compound interest growth, but got: $${result}`,
+        }
+      );
+      expect(isReasonableReturn).toBe(true);
+
+      // LLM assertion for compound interest validation
+      const followsCompoundInterest = await aiExpect(
+        `Starting with $1000 at 5% annual interest for 10 years, the final amount is $${result}`
+      ).toSatisfy(
+        'Does this final amount follow the expected pattern of compound interest growth? It should be more than simple interest (which would be $1500) and less than exponential growth.',
+        {
+          message: `Expected compound interest growth pattern, but got: $${result}`,
+        }
+      );
+      expect(followsCompoundInterest).toBe(true);
+    },
+    longTestTimeout
+  );
 });

package/src/verblets/number/index.js

@@ -11,12 +11,15 @@ const {
   explainAndSeparatePrimitive,
 } = promptConstants;
 
-export default async (text) => {
+export default async (text, config = {}) => {
+  const { llm, ...options } = config;
   const numberText = `${contentIsQuestion} ${text}
 
 ${explainAndSeparate} ${explainAndSeparatePrimitive}
 
 ${asNumber} ${asUndefinedByDefault}`;
 
-  return toNumber(stripResponse(await chatGPT(numberText)));
+  return toNumber(
+    stripResponse(await chatGPT(numberText, { modelOptions: { ...llm }, ...options }))
+  );
 };

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

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

package/src/verblets/number-with-units/index.examples.js

@@ -6,7 +6,7 @@ import { longTestTimeout } from '../../constants/common.js';
 const examples = [
   {
     inputs: { text: 'What is the height of Everest in feet' },
-    want: { value: 29029, unit: 'feet' },
+    want: { valueRange: [29029, 29032], unit: 'feet' },
   },
   {
     inputs: { text: 'What is my age in years' },
@@ -24,6 +24,10 @@ describe('Number with units verblet', () => {
         if (example.want.value) {
           expect(result?.value).toStrictEqual(example.want.value);
         }
+        if (example.want.valueRange) {
+          expect(result?.value).toBeGreaterThanOrEqual(example.want.valueRange[0]);
+          expect(result?.value).toBeLessThanOrEqual(example.want.valueRange[1]);
+        }
         if (example.want.unit) {
           expect(result?.unit).toStrictEqual(example.want.unit);
         }

package/src/verblets/number-with-units/index.js

@@ -1,19 +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 stripResponse from '../../lib/strip-response/index.js';
 import toNumberWithUnits from '../../lib/to-number-with-units/index.js';
 import { constants as promptConstants } from '../../prompts/index.js';
 
-const {
-  asNumberWithUnits,
-  contentIsQuestion,
-  explainAndSeparate,
-  explainAndSeparateJSON,
-} = promptConstants;
+const { asNumberWithUnits, contentIsQuestion, explainAndSeparate, explainAndSeparateJSON } =
+  promptConstants;
 
-export default async (text) => {
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Load the JSON schema for number with units results
+ * @returns {Promise<Object>} JSON schema for validation
+ */
+async function getNumberWithUnitsSchema() {
+  const schemaPath = path.join(__dirname, 'number-with-units-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 getNumberWithUnitsSchema();
+
+  const responseFormat = {
+    type: 'json_schema',
+    json_schema: {
+      name: 'number_with_units_result',
+      schema,
+    },
+  };
+
+  if (typeof llm === 'string') {
+    return {
+      modelName: llm,
+      response_format: responseFormat,
+    };
+  } else {
+    return {
+      ...llm,
+      response_format: responseFormat,
+    };
+  }
+}
+
+export default async (text, config = {}) => {
+  const { llm, ...options } = config;
   const numberText = `${contentIsQuestion} ${text} \n\n${explainAndSeparate} ${explainAndSeparateJSON}
 
+Extract the numeric value and unit from the question. If you cannot determine the specific numeric value, set "value" to null but still identify the unit being asked for.
+
 ${asNumberWithUnits}`;
 
-  return toNumberWithUnits(stripResponse(await chatGPT(numberText)));
+  const modelOptions = await createModelOptions(llm);
+  const response = await chatGPT(numberText, { modelOptions, ...options });
+
+  // With structured outputs, response should already be parsed, but we still use
+  // toNumberWithUnits for additional validation and processing
+  let rawResult;
+  if (typeof response === 'string') {
+    // Handle the case where response might be "undefined" or other non-JSON strings
+    if (response.trim() === 'undefined') {
+      rawResult = { value: undefined, unit: undefined };
+    } else {
+      try {
+        rawResult = JSON.parse(response);
+      } catch {
+        // If parsing fails, create a default structure
+        rawResult = { value: undefined, unit: undefined };
+      }
+    }
+  } else {
+    rawResult = response;
+  }
+
+  return toNumberWithUnits(JSON.stringify(rawResult));
 };

package/src/verblets/number-with-units/number-with-units-result.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "value": {
+      "oneOf": [
+        { "type": "number" },
+        { "type": "string" },
+        { "type": "null" }
+      ],
+      "description": "The numeric value extracted from the text"
+    },
+    "unit": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "null" }
+      ],
+      "description": "The unit of measurement, if any"
+    }
+  },
+  "required": ["value", "unit"],
+  "additionalProperties": false
+} 

package/src/verblets/schema-org/index.examples.js

@@ -7,9 +7,7 @@ import schemaOrg from './index.js';
 
 const resultSchemaWith = (type) => async () => {
   return JSON.parse(
-    await fs.readFile(
-      `./src/json-schemas/schema-dot-org-${type.toLowerCase()}.json`
-    )
+    await fs.readFile(`./src/json-schemas/schema-dot-org-${type.toLowerCase()}.json`)
   );
 };
 
@@ -30,10 +28,7 @@ describe('Schema.org verblet', () => {
     it(
       `${example.inputs.text}${typeDisplay}`,
       async () => {
-        const result = await schemaOrg(
-          example.inputs.text,
-          example.inputs.type
-        );
+        const result = await schemaOrg(example.inputs.text, example.inputs.type);
 
         if (example.want.resultSchema) {
           const schema = await example.want.resultSchema();

package/src/verblets/schema-org/index.js

@@ -1,8 +1,37 @@
+import fs from 'node:fs/promises';
 import chatGPT from '../../lib/chatgpt/index.js';
 import stripResponse from '../../lib/strip-response/index.js';
 import { asSchemaOrgText } from '../../prompts/index.js';
-import toObject from '../to-object/index.js';
 
-export default async (text, type) => {
-  return toObject(stripResponse(await chatGPT(asSchemaOrgText(text, type))));
+const getSchema = async (type) => {
+  return JSON.parse(
+    await fs.readFile(`./src/json-schemas/schema-dot-org-${type.toLowerCase()}.json`)
+  );
+};
+
+export default async (text, type, config = {}) => {
+  const { llm, ...options } = config;
+  const schema = type ? await getSchema(type) : undefined;
+
+  const modelOptions = schema
+    ? {
+        response_format: {
+          type: 'json_schema',
+          json_schema: {
+            name: `schema_org_${type.toLowerCase()}`,
+            schema,
+          },
+        },
+        ...llm,
+      }
+    : {
+        response_format: { type: 'json_object' },
+        ...llm,
+      };
+
+  const response = await chatGPT(asSchemaOrgText(text, type, schema), {
+    modelOptions,
+    ...options,
+  });
+  return JSON.parse(stripResponse(response));
 };

package/src/verblets/sentiment/README.md

@@ -0,0 +1,10 @@
+# sentiment
+
+Determine whether a piece of text expresses a positive, negative, or neutral tone.
+
+```javascript
+import sentiment from './index.js';
+
+const mood = await sentiment('I feel fantastic about the future!');
+// mood === 'positive'
+```