@far-world-labs/verblets 0.1.1 → 0.1.3

package/src/chains/set-interval/README.md

@@ -0,0 +1,81 @@
+# setInterval
+
+AI-guided replacement for `setInterval`.
+Feed it your own natural-language heuristic; it will keep time, remember history, and supply your callback with rich context so you can build self-tuning workflows, creative generators, or living UIs.
+
+## Example: Photography Alarm
+
+*Because the universe waits for no one (but this will wait for the universe).*
+
+```javascript
+import setInterval from './index.js';
+import { getWeather, getCelestialEvents } from './apis.js';
+import chatGPT from '../../lib/chatgpt/index.js';
+
+const stop = setInterval({
+  prompt: `
+    Based on upcoming celestial events and weather, decide when to check next 
+    for photography opportunities. 
+    
+    Current conditions: {cloudCover}% clouds
+    
+    Upcoming celestial events: 
+    <options>
+    {events}
+    <options>
+  `,
+  
+  // Called every time to get data for AI scheduling decisions
+  async getData() {
+    const weather = await getWeather({ days: 1 });
+    const events = await getCelestialEvents({ days: 7 });
+    
+    return {
+      cloudCover: weather.current.cloudCover,
+      events: events.map(e => `${e.name} - ${e.description}`).join('\n')
+    };
+  },
+  
+  // Called when the tick happens - handle the scheduled event
+  async onTick({ timingString, data, nextDate }) {
+    // Get current conditions for photography
+    const currentWeather = await getWeather({ hours: 1 });
+    const currentEvents = await getCelestialEvents({ 
+      hours: 1, 
+      types: ['solar', 'lunar', 'meteor', 'planetary', 'aurora', 'eclipse'] 
+    });
+    
+    const description = await chatGPT(`
+      Describe what celestial event should be photographed right now based on current conditions.
+      Current Weather: ${JSON.stringify(currentWeather)}
+      Current Events: ${JSON.stringify(currentEvents)}
+      
+      Provide a clear description of the photography opportunity.
+    `);
+    
+    console.log(description);
+    console.log(`Next check in: ${timingString} (${nextDate.toLocaleString()})`);
+  }
+});
+
+Function to stop the interval timer.
+
+## API Reference
+
+### `setInterval(options)`
+
+Creates an AI-guided interval timer that uses natural language to determine timing.
+
+#### Parameters
+
+- **`prompt`** (string, required): Instructions for AI timing decisions. Supports `{variable}` interpolation from `getData` results
+- **`getData`** (function, required): Called to get data for AI decisions. Should return an object whose properties can be used as `{variable}` in the prompt
+- **`historySize`** (number, default: 5): How many timing decisions to remember
+- **`initial`** (any, default: null): Initial data to start with
+- **`model`** (string, optional): AI model to use
+- **`llm`** (object, optional): Model configuration
+- **`onTick`** (function, optional): Called when the tick happens
+
+#### Returns
+
+Function to stop the interval timer.

package/src/chains/set-interval/index.examples.js

@@ -0,0 +1,36 @@
+import { describe, it } from 'vitest';
+import setInterval from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('setInterval (example)', () => {
+  it(
+    'adjusts meditation sessions using wearable stress levels',
+    async () => {
+      const stop = setInterval({
+        prompt:
+          'Current stress level: {stress}. Start at 3 min. If stress > 70, shorten by 1 min; if below 30, lengthen by 2 min.',
+        getData: () => ({ stress: Math.floor(Math.random() * 100) }),
+        onTick: ({ data }) => console.log(`Meditation session with stress level: ${data.stress}`),
+      });
+      await new Promise((r) => setTimeout(r, 5000));
+      stop();
+    },
+    longTestTimeout
+  );
+
+  it(
+    'paces game events to match player skill',
+    async () => {
+      const stop = setInterval({
+        prompt:
+          'Player win rate: {winRate}%. Begin at 10 sec. If winRate > 80, decrease by 2 sec; if under 40, increase by 5 sec.',
+        getData: () => ({ winRate: Math.floor(Math.random() * 100) }),
+        onTick: ({ data }) =>
+          console.log(`Game event triggered for player with ${data.winRate}% win rate`),
+      });
+      await new Promise((r) => setTimeout(r, 5000));
+      stop();
+    },
+    longTestTimeout
+  );
+});

package/src/chains/set-interval/index.js

@@ -0,0 +1,131 @@
+import chatGPT from '../../lib/chatgpt/index.js';
+import numberWithUnits from '../../verblets/number-with-units/index.js';
+import number from '../../verblets/number/index.js';
+import date from '../date/index.js';
+import wrapVariable from '../../prompts/wrap-variable.js';
+import templateReplace from '../../lib/template-replace/index.js';
+import { constants as promptConstants } from '../../prompts/index.js';
+
+const { contentIsInstructions, explainAndSeparate, explainAndSeparatePrimitive } = promptConstants;
+
+const UNIT_MS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1000,
+  sec: 1000,
+  secs: 1000,
+  second: 1000,
+  seconds: 1000,
+  m: 60000,
+  min: 60000,
+  mins: 60000,
+  minute: 60000,
+  minutes: 60000,
+  h: 3600000,
+  hr: 3600000,
+  hrs: 3600000,
+  hour: 3600000,
+  hours: 3600000,
+  d: 86400000,
+  day: 86400000,
+  days: 86400000,
+};
+
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+
+async function toMs(text, config = {}) {
+  const clean = String(text).trim();
+  if (ISO_DATE_RE.test(clean)) {
+    const diff = new Date(clean).getTime() - Date.now();
+    if (diff > 0) return diff;
+  }
+  const nu = await numberWithUnits(clean, config);
+  if (nu && nu.value !== undefined) {
+    const unit = (nu.unit || 'ms').toLowerCase();
+    if (UNIT_MS[unit]) return nu.value * UNIT_MS[unit];
+  }
+  const dt = await date(clean, config);
+  if (dt instanceof Date) {
+    const diff = dt.getTime() - Date.now();
+    if (diff > 0) return diff;
+  }
+  const n = await number(clean, config);
+  if (typeof n === 'number') return n;
+  return 0;
+}
+
+export default function setInterval({
+  prompt,
+  getData,
+  historySize = 5,
+  initial = null,
+  onTick,
+  model,
+  llm,
+  ...options
+} = {}) {
+  let timer;
+  let count = 0;
+  let lastResult = initial;
+  const history = [];
+  let active = true;
+
+  const step = async () => {
+    if (!active) return;
+
+    // Get data for AI decision making
+    lastResult = await getData({
+      count,
+      lastInvocationResult: lastResult,
+      initial,
+    });
+
+    // Replace {variable} placeholders in the prompt with actual values from lastResult
+    const processedPrompt = templateReplace(prompt, lastResult);
+
+    // Always invoke the prompt to determine the next interval
+    const intervalPrompt = `${contentIsInstructions} ${processedPrompt}
+
+${explainAndSeparate} ${explainAndSeparatePrimitive}
+
+Your response should be an ISO date or a short duration like "10 minutes".
+${wrapVariable(lastResult, { tag: 'last-result', title: 'Last result:' })}
+${wrapVariable(history, { tag: 'history', title: 'History:', forceHTML: true })}
+${wrapVariable(count, { tag: 'count', title: 'Count:' })}
+Next wait:`;
+
+    const intervalText = await chatGPT(intervalPrompt, {
+      modelOptions: model ? { modelName: model, ...llm } : { ...llm },
+      ...options,
+    });
+
+    history.push(intervalText);
+    if (history.length > historySize) history.shift();
+
+    const delay = await toMs(intervalText, { llm, ...options });
+
+    // Call onTick callback if provided - this is when the tick happens
+    if (onTick) {
+      const nextTime = new Date(Date.now() + delay);
+      await onTick({
+        timingString: intervalText,
+        data: lastResult,
+        nextDate: nextTime,
+      });
+    }
+
+    count += 1;
+
+    // Schedule the next iteration
+    timer = setTimeout(step, delay);
+  };
+
+  // Start immediately - the prompt will determine the first interval
+  timer = setTimeout(step, 0);
+
+  return () => {
+    active = false;
+    clearTimeout(timer);
+  };
+}

package/src/chains/set-interval/index.spec.js

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from 'vitest';
+import setInterval from './index.js';
+
+vi.useFakeTimers();
+
+vi.mock('../../lib/chatgpt/index.js', () => ({
+  default: vi.fn(),
+}));
+vi.mock('../date/index.js', () => ({
+  default: vi.fn(),
+}));
+vi.mock('../../verblets/number-with-units/index.js', () => ({
+  default: vi.fn(),
+}));
+vi.mock('../../verblets/number/index.js', () => ({
+  default: vi.fn(),
+}));
+
+const chatGPT = (await import('../../lib/chatgpt/index.js')).default;
+const date = (await import('../date/index.js')).default;
+const numberWithUnits = (await import('../../verblets/number-with-units/index.js')).default;
+const number = (await import('../../verblets/number/index.js')).default;
+
+describe('setInterval', () => {
+  it('runs callback with dynamic delays', async () => {
+    chatGPT.mockResolvedValueOnce('1 second').mockResolvedValueOnce('2 seconds');
+    numberWithUnits
+      .mockResolvedValueOnce({ value: 1, unit: 'second' })
+      .mockResolvedValueOnce({ value: 2, unit: 'second' });
+    date.mockResolvedValue(undefined);
+    number.mockResolvedValue(undefined);
+
+    const getData = vi.fn().mockResolvedValue('test data');
+    const stop = setInterval({ prompt: 'prompt', getData });
+    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(getData).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(getData).toHaveBeenCalledTimes(2);
+    await vi.advanceTimersByTimeAsync(2000);
+    expect(getData).toHaveBeenCalledTimes(3);
+    stop();
+    await vi.runOnlyPendingTimersAsync();
+  });
+
+  it('interpolates variables from getData results in prompt', async () => {
+    chatGPT.mockResolvedValueOnce('1 second');
+    numberWithUnits.mockResolvedValueOnce({ value: 1, unit: 'second' });
+    date.mockResolvedValue(undefined);
+    number.mockResolvedValue(undefined);
+
+    const getData = vi.fn().mockResolvedValue({ stress: 85, mood: 'anxious' });
+    const stop = setInterval({
+      prompt: 'Current stress: {stress}, mood: {mood}. Wait time?',
+      getData,
+    });
+
+    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(0);
+
+    // Check that chatGPT was called with interpolated values
+    expect(chatGPT).toHaveBeenCalledWith(
+      expect.stringContaining('Current stress: 85, mood: anxious. Wait time?'),
+      expect.any(Object)
+    );
+
+    stop();
+    await vi.runOnlyPendingTimersAsync();
+  });
+});

package/src/chains/socratic/README.md

@@ -0,0 +1,17 @@
+# socratic
+
+Guide yourself or a user toward deeper understanding by automatically posing and answering a short series of Socratic questions. The chain uses your configured LLM to generate each question and then supplies a concise answer, building a dialogue.
+
+```javascript
+import { socratic } from './index.js';
+
+const dialogue = await socratic('I want to start exercising more').run(3);
+console.log(dialogue);
+/*
+[
+  { question: 'What benefits do you hope to gain from exercising?', answer: 'I want more energy during the day.' },
+  { question: 'Why is having more energy important to you?', answer: 'So I can keep up with my kids after work.' },
+  { question: 'How might regular exercise help you achieve that?', answer: 'It will improve my stamina and mood.' }
+]
+*/
+```

package/src/chains/socratic/index.js

@@ -0,0 +1,64 @@
+import chatGPT from '../../lib/chatgpt/index.js';
+import modelService from '../../services/llm-model/index.js';
+
+const defaultAsk = async ({
+  topic,
+  history = [],
+  model = modelService.getBestPublicModel(),
+} = {}) => {
+  const historyText = history.map((turn) => `Q: ${turn.question}\nA: ${turn.answer}`).join('\n');
+
+  const prompt = `${
+    historyText ? `${historyText}\n` : ''
+  }Using the Socratic method, ask one short question that challenges assumptions about "${topic}".`;
+  const budget = model.budgetTokens(prompt);
+  return await chatGPT(prompt, { maxTokens: budget.completion, temperature: 0.7 });
+};
+
+const defaultAnswer = async ({
+  question,
+  history = [],
+  _topic,
+  model = modelService.getBestPublicModel(),
+} = {}) => {
+  const historyText = history.map((turn) => `Q: ${turn.question}\nA: ${turn.answer}`).join('\n');
+
+  const prompt = `${
+    historyText ? `${historyText}\n` : ''
+  }Answer the question thoughtfully and briefly:\n"${question}"`;
+  const budget = model.budgetTokens(prompt);
+  return await chatGPT(prompt, { maxTokens: budget.completion, temperature: 0.7 });
+};
+
+class SocraticMethod {
+  constructor(statement, { ask = defaultAsk, answer = defaultAnswer } = {}) {
+    this.statement = statement;
+    this.ask = ask;
+    this.answer = answer;
+    this.history = [];
+  }
+
+  getDialogue() {
+    return this.history;
+  }
+
+  async step() {
+    const question = await this.ask({ topic: this.statement, history: this.history });
+    const answer = await this.answer({ question, history: this.history, topic: this.statement });
+    const turn = { question, answer };
+    this.history.push(turn);
+    return turn;
+  }
+
+  async run(depth = 3) {
+    for (let i = 0; i < depth; i += 1) {
+      // eslint-disable-next-line no-await-in-loop
+      await this.step();
+    }
+    return this.history;
+  }
+}
+
+export const socratic = (statement, options) => new SocraticMethod(statement, options);
+
+export default SocraticMethod;

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

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+import { socratic } from './index.js';
+
+vi.mock('../../lib/chatgpt/index.js', () => {
+  let call = 0;
+  return {
+    default: vi.fn(() => {
+      call += 1;
+      return call % 2 === 1 ? `Q${call}` : `A${call}`;
+    }),
+  };
+});
+
+describe('socratic chain', () => {
+  it('runs dialogue for specified depth', async () => {
+    const chain = socratic('topic');
+    const result = await chain.run(2);
+    expect(result).toHaveLength(2);
+    result.forEach((turn) => {
+      expect(turn).toHaveProperty('question');
+      expect(turn).toHaveProperty('answer');
+    });
+  });
+});

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

@@ -22,13 +22,9 @@ describe('Sort chain', () => {
       async () => {
         const listResults = await list(example.inputs.listText);
 
-        const result = await sort(
-          {
-            by: example.inputs.sortText,
-            iterations: 1,
-          },
-          listResults
-        );
+        const result = await sort(listResults, example.inputs.sortText, {
+          iterations: 1,
+        });
 
         // console.error(result);
 

package/src/chains/sort/index.js

@@ -1,10 +1,54 @@
 import * as R from 'ramda';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import chatGPT from '../../lib/chatgpt/index.js';
-import toObject from '../../verblets/to-object/index.js';
 import { sort as sortPromptInitial } from '../../prompts/index.js';
 import modelService from '../../services/llm-model/index.js';
 
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Load the JSON schema for sort results
+ * @returns {Promise<Object>} JSON schema for validation
+ */
+async function getSortSchema() {
+  const schemaPath = path.join(__dirname, 'sort-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 getSortSchema();
+
+  const responseFormat = {
+    type: 'json_schema',
+    json_schema: {
+      name: 'sort_result',
+      schema,
+    },
+  };
+
+  if (typeof llm === 'string') {
+    return {
+      modelName: llm,
+      response_format: responseFormat,
+    };
+  } else {
+    return {
+      ...llm,
+      response_format: responseFormat,
+    };
+  }
+}
+
 // redeclared so it's clearer how tests can override the sorter
 let sortPrompt = sortPromptInitial;
 
@@ -32,7 +76,8 @@ const sanitizeList = (list) => {
 const sort = async (
   options,
   listInitial,
-  model = modelService.getBestAvailableModel()
+  model = modelService.getBestPublicModel(),
+  config = {}
 ) => {
   const {
     by,
@@ -41,6 +86,8 @@ const sort = async (
     iterations = defaultSortIterations,
   } = options;
 
+  const { llm, ...passThroughOptions } = config;
+
   const list = sanitizeList(listInitial);
   let i = iterations;
   let top = [];
@@ -63,30 +110,30 @@ const sort = async (
       );
 
       const budget = model.budgetTokens(prompt);
+      const modelOptions = await createModelOptions(llm);
 
       // eslint-disable-next-line no-await-in-loop
       const result = await chatGPT(prompt, {
         modelOptions: {
+          ...modelOptions,
           maxTokens: budget.completion,
           requestTimeout: model.requestTimeout * 1.5,
         },
+        ...passThroughOptions,
       });
 
-      // eslint-disable-next-line no-await-in-loop
-      const batchSorted = await toObject(result);
+      // With structured outputs, response should already be parsed and validated
+      const batchSorted = typeof result === 'string' ? JSON.parse(result) : result;
+      // Extract items from the object structure
+      const resultArray = batchSorted?.items || batchSorted;
+      const sortedArray = Array.isArray(resultArray) ? resultArray.filter(Boolean) : [];
 
-      const batchTop = batchSorted.slice(0, extremeK);
-      const batchBottom = batchSorted.slice(-extremeK);
+      const batchTop = sortedArray.slice(0, extremeK);
+      const batchBottom = sortedArray.slice(-extremeK);
 
-      discardedTop = [
-        ...newTop.filter((x) => !batchTop.includes(x)),
-        ...discardedTop,
-      ];
+      discardedTop = [...newTop.filter((x) => !batchTop.includes(x)), ...discardedTop];
 
-      discardedBottom = [
-        ...discardedBottom,
-        ...newBottom.filter((x) => !batchBottom.includes(x)),
-      ];
+      discardedBottom = [...discardedBottom, ...newBottom.filter((x) => !batchBottom.includes(x))];
 
       newTop = batchTop;
       newBottom = batchBottom;
@@ -110,4 +157,7 @@ const sort = async (
   return finalList;
 };
 
-export default sort;
+export default async function sortWrapper(list, criteria, config = {}) {
+  const { model = modelService.getBestPublicModel(), ...options } = config;
+  return await sort({ by: criteria, ...options }, list, model, config);
+}

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

@@ -101,15 +101,12 @@ describe('Sort', () => {
   examples.forEach((example) => {
     it(example.name, async () => {
       const iterations = example.inputs.options.iterations ?? 1;
-      const result = await sort(example.inputs.options, example.inputs.list, {
-        budgetTokens: () => ({ completion: 0 }),
+      const result = await sort(example.inputs.list, example.inputs.options.by, {
+        model: { budgetTokens: () => ({ completion: 0 }) },
+        ...example.inputs.options,
       });
-      expect(result.slice(0, extremeK * iterations)).toStrictEqual(
-        example.want.highest
-      );
-      expect(result.slice(-(extremeK * iterations))).toStrictEqual(
-        example.want.lowest
-      );
+      expect(result.slice(0, extremeK * iterations)).toStrictEqual(example.want.highest);
+      expect(result.slice(-(extremeK * iterations))).toStrictEqual(example.want.lowest);
     });
   });
 });

package/src/chains/sort/sort-result.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "items": {
+      "type": "array",
+      "description": "Array of sorted items",
+      "items": {
+        "type": "string",
+        "description": "A sorted item"
+      }
+    }
+  },
+  "required": ["items"],
+  "additionalProperties": false
+} 

package/src/chains/summary-map/README.md

@@ -19,7 +19,7 @@ ${data.example.code}`;
 };
 
 const variableTokens = 100;
-const promptTokens = modelService.getBestAvailableModel().toTokens(promptFunction).length;
+const promptTokens = modelService.getBestPublicModel().toTokens(promptFunction).length;
 const solutionTokens = 200;
 const maxTokens = promptTokens + variableTokens + solutionTokens
 
@@ -30,4 +30,12 @@ summaryMap.set('example.code', { value: 'Long code data...', weight: 0.5, type:
 const promptInputs = await summaryMap.pavedSummaryResult();
 const prompt = promptFunction(promptInputs);
 const response = await chatGPT(prompt, { modelOptions: { maxTokens }});
+
+// Privacy example
+const privacyMap = new SummaryMap({ targetTokens: 50 });
+privacyMap.set('example.text', {
+  value: 'Sensitive text with names',
+  privacy: { blacklist: 'names' },
+});
+const result = await privacyMap.pavedSummaryResult();
 ```

package/src/chains/summary-map/index.examples.js

@@ -37,9 +37,16 @@ describe('Summary map', () => {
   it(
     'Example',
     async () => {
-      const map = new SummaryMap({ targetTokens: 600 });
+      const map = new SummaryMap({
+        targetTokens: 600,
+        modelOptions: { modelName: 'fastGood' },
+      });
 
-      map.set('a.b.c', { value: legalText, weight: 0.01 });
+      map.set('a.b.c', {
+        value: legalText,
+        weight: 0.01,
+        privacy: { blacklist: 'names and addresses' },
+      });
       map.set('a.d', { value: codeText, type: 'code', weight: 0.7 });
       map.set('e.0', { value: 'abc', weight: 0.01 });
       map.set('e.3', {