@far-world-labs/verblets 0.1.4 → 0.2.0

package/src/chains/llm-logger/index.spec.js

@@ -1,6 +1,8 @@
 import { beforeEach, describe, expect, it, vi, afterEach } from 'vitest';
+
+vi.useFakeTimers();
 import { createLLMLogger, createConsoleWriter, createFileWriter } from './index.js';
-import { setLogger, resetLogger } from '../../lib/logger-service/index.js';
+import { resetLogger } from '../../lib/logger-service/index.js';
 
 // Mock console methods
 const mockConsoleLog = vi.fn();
@@ -58,15 +60,18 @@ describe('LLM Logger - Factory Pattern', () => {
   describe('Global Logger Service Integration', () => {
     it('should work as global logger', async () => {
       const logger = createLLMLogger({
+        immediateFlush: true, // Enable immediate flushing for tests
         lanes: [
           {
-            laneId: 'console',
+            laneId: 'global',
             writer: createConsoleWriter('[GLOBAL] '),
           },
         ],
       });
 
-      setLogger(logger);
+      logger.log('test log');
+      logger.info('test info');
+      logger.error('test error');
 
       // Use global logger service methods
       const { log, info, error } = await import('../../lib/logger-service/index.js');
@@ -76,11 +81,17 @@ describe('LLM Logger - Factory Pattern', () => {
       error('test error');
 
       // Allow flush loops to complete
-      await new Promise((resolve) => setTimeout(resolve, 150));
+      await vi.advanceTimersByTimeAsync(150);
 
-      expect(mockConsoleLog).toHaveBeenCalledWith('[GLOBAL] test log');
-      expect(mockConsoleLog).toHaveBeenCalledWith('[GLOBAL] test info');
-      expect(mockConsoleLog).toHaveBeenCalledWith('[GLOBAL] test error');
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        expect.stringContaining('[GLOBAL] {"data":"test log"')
+      );
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        expect.stringContaining('[GLOBAL] {"data":"test info"')
+      );
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        expect.stringContaining('[GLOBAL] {"data":"test error"')
+      );
     });
   });
 
@@ -125,16 +136,17 @@ describe('LLM Logger - Factory Pattern', () => {
       const infoWriter = vi.fn();
 
       const logger = createLLMLogger({
+        immediateFlush: true, // Enable immediate flushing for tests
         lanes: [
           {
             laneId: 'errors',
-            filters: (log) => log.meta.get('level') === 'error',
             writer: errorWriter,
+            filters: (log) => log.meta.get('level') === 'error',
           },
           {
             laneId: 'info',
-            filters: (log) => log.meta.get('level') === 'info',
             writer: infoWriter,
+            filters: (log) => log.meta.get('level') === 'info',
           },
         ],
       });
@@ -144,16 +156,27 @@ describe('LLM Logger - Factory Pattern', () => {
       logger.debug('debug message'); // Should not match any lane
 
       // Allow flush loops to complete
-      await new Promise((resolve) => setTimeout(resolve, 150));
-
-      expect(errorWriter).toHaveBeenCalledWith(['error message']);
-      expect(infoWriter).toHaveBeenCalledWith(['info message']);
+      await vi.advanceTimersByTimeAsync(150);
+
+      expect(errorWriter).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'error',
+          data: 'error message',
+        }),
+      ]);
+      expect(infoWriter).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'info',
+          data: 'info message',
+        }),
+      ]);
     });
 
     it('should handle lanes without filters', async () => {
       const allWriter = vi.fn();
 
       const logger = createLLMLogger({
+        immediateFlush: true, // Enable immediate flushing for tests
         lanes: [
           {
             laneId: 'all',
@@ -166,11 +189,21 @@ describe('LLM Logger - Factory Pattern', () => {
       logger.info({ type: 'object log' });
 
       // Allow flush loops to complete
-      await new Promise((resolve) => setTimeout(resolve, 150));
+      await vi.advanceTimersByTimeAsync(150);
 
       expect(allWriter).toHaveBeenCalledTimes(2);
-      expect(allWriter).toHaveBeenCalledWith(['string log']);
-      expect(allWriter).toHaveBeenCalledWith(['{"type":"object log"}']);
+      expect(allWriter).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'log',
+          data: 'string log',
+        }),
+      ]);
+      expect(allWriter).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'info',
+          type: 'object log',
+        }),
+      ]);
     });
   });
 
@@ -211,7 +244,13 @@ describe('LLM Logger - Factory Pattern', () => {
       // Manual flush
       logger.flush();
 
-      expect(writer).toHaveBeenCalledWith(['test message']);
+      // Check that writer received object with expected properties
+      expect(writer).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'log',
+          data: 'test message',
+        }),
+      ]);
     });
 
     it('should clear ring buffer and lane buffers', () => {
@@ -277,6 +316,7 @@ describe('LLM Logger - Factory Pattern', () => {
       const writer = vi.fn();
 
       const logger = createLLMLogger({
+        immediateFlush: true, // Enable immediate flushing for tests
         lanes: [
           {
             laneId: 'mixed',
@@ -291,18 +331,39 @@ describe('LLM Logger - Factory Pattern', () => {
       logger.log(null);
 
       // Allow flush loops to complete
-      await new Promise((resolve) => setTimeout(resolve, 150));
-
-      expect(writer).toHaveBeenCalledWith(['string']);
-      expect(writer).toHaveBeenCalledWith(['{"object":"data"}']);
-      expect(writer).toHaveBeenCalledWith(['123']);
-      expect(writer).toHaveBeenCalledWith(['null']);
+      await vi.advanceTimersByTimeAsync(150);
+
+      expect(writer).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'log',
+          data: 'string',
+        }),
+      ]);
+      expect(writer).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'log',
+          object: 'data',
+        }),
+      ]);
+      expect(writer).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'log',
+          data: 123,
+        }),
+      ]);
+      expect(writer).toHaveBeenCalledWith([
+        expect.objectContaining({
+          level: 'log',
+          data: null,
+        }),
+      ]);
     });
 
     it('should handle high-volume logging', async () => {
       const writer = vi.fn();
 
       const logger = createLLMLogger({
+        immediateFlush: true, // Enable immediate flushing for tests
         ringBufferSize: 100,
         lanes: [
           {
@@ -318,7 +379,7 @@ describe('LLM Logger - Factory Pattern', () => {
       }
 
       // Allow flush loops to complete
-      await new Promise((resolve) => setTimeout(resolve, 200));
+      await vi.advanceTimersByTimeAsync(200);
 
       // Should have processed all logs
       expect(writer).toHaveBeenCalledTimes(50);

package/src/chains/llm-logger/schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "LLM Logger Bulk Adjustments Schema",
+  "description": "Schema for bulk log adjustments returned by LLM processors",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "logId": {
+        "type": "string",
+        "description": "Unique identifier of the log entry to adjust"
+      },
+      "adjustments": {
+        "type": "object",
+        "description": "Key-value pairs of JSON paths to values for non-destructive enhancement",
+        "patternProperties": {
+          "^[a-zA-Z0-9_.]+$": {
+            "description": "JSON path (e.g., 'analysis.sentiment', 'meta.category') mapped to any value"
+          }
+        },
+        "additionalProperties": true,
+        "examples": [
+          {
+            "analysis.sentiment": "positive",
+            "analysis.confidence": 0.95,
+            "category.type": "user-activity",
+            "metadata.processed": true
+          }
+        ]
+      },
+      "aiMeta": {
+        "type": "object",
+        "description": "AI-specific metadata that controls processing but is not included in output",
+        "properties": {
+          "skip": {
+            "type": "boolean",
+            "description": "Whether this log should be skipped in output lanes",
+            "default": false
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Confidence score for the analysis (0.0 to 1.0)"
+          },
+          "processingOrder": {
+            "type": "integer",
+            "description": "Suggested processing order for multi-stage processing"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tags for categorization and filtering"
+          },
+          "priority": {
+            "type": "string",
+            "enum": ["low", "medium", "high", "critical"],
+            "description": "Priority level for the log entry"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "required": ["logId"],
+    "additionalProperties": false
+  },
+  "examples": [
+    [
+      {
+        "logId": "1750305969596-u6n7hyd9v",
+        "adjustments": {
+          "analysis.sentiment": "positive",
+          "analysis.confidence": 0.95,
+          "analysis.keywords": ["user", "authentication", "successful"],
+          "category.type": "user-activity",
+          "category.subcategory": "authentication"
+        },
+        "aiMeta": {
+          "skip": false,
+          "confidence": 0.95,
+          "tags": ["auth", "success"],
+          "priority": "medium"
+        }
+      },
+      {
+        "logId": "1750305969597-6t0ys0zat",
+        "adjustments": {
+          "analysis.sentiment": "negative",
+          "analysis.confidence": 0.88,
+          "analysis.error_type": "connection",
+          "category.type": "system-error",
+          "category.severity": "high"
+        },
+        "aiMeta": {
+          "skip": false,
+          "confidence": 0.88,
+          "tags": ["error", "database", "connection"],
+          "priority": "high"
+        }
+      }
+    ]
+  ]
+} 

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

@@ -1,4 +1,4 @@
-import { describe, it } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import setInterval from './index.js';
 import { longTestTimeout } from '../../constants/common.js';
 
@@ -6,14 +6,28 @@ describe('setInterval (example)', () => {
   it(
     'adjusts meditation sessions using wearable stress levels',
     async () => {
+      const results = [];
       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}`),
+        onTick: ({ data }) => {
+          results.push(data);
+        },
       });
-      await new Promise((r) => setTimeout(r, 5000));
+
+      // Wait longer to allow for LLM processing time
+      await new Promise((r) => setTimeout(r, 10000));
       stop();
+
+      // Assert that the function executed and collected stress data
+      expect(results.length).toBeGreaterThan(0);
+      expect(
+        results.every(
+          (result) =>
+            typeof result.stress === 'number' && result.stress >= 0 && result.stress <= 100
+        )
+      ).toBe(true);
     },
     longTestTimeout
   );
@@ -21,15 +35,29 @@ describe('setInterval (example)', () => {
   it(
     'paces game events to match player skill',
     async () => {
+      const results = [];
+
       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`),
+        onTick: ({ data }) => {
+          results.push(data);
+        },
       });
-      await new Promise((r) => setTimeout(r, 5000));
+
+      // Wait longer to allow for LLM processing time
+      await new Promise((r) => setTimeout(r, 10000));
       stop();
+
+      // Assert that the function executed and collected win rate data
+      expect(results.length).toBeGreaterThan(0);
+      expect(
+        results.every(
+          (result) =>
+            typeof result.winRate === 'number' && result.winRate >= 0 && result.winRate <= 100
+        )
+      ).toBe(true);
     },
     longTestTimeout
   );

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

@@ -74,18 +74,19 @@ export default function setInterval({
   const step = async () => {
     if (!active) return;
 
-    // Get data for AI decision making
-    lastResult = await getData({
-      count,
-      lastInvocationResult: lastResult,
-      initial,
-    });
+    try {
+      // 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);
+      // 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}
+      // Always invoke the prompt to determine the next interval
+      const intervalPrompt = `${contentIsInstructions} ${processedPrompt}
 
 ${explainAndSeparate} ${explainAndSeparatePrimitive}
 
@@ -95,30 +96,50 @@ ${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,
+      const intervalText = await chatGPT(intervalPrompt, {
+        modelOptions: model ? { modelName: model, ...llm } : { ...llm },
+        ...options,
       });
-    }
-
-    count += 1;
 
-    // Schedule the next iteration
-    timer = setTimeout(step, delay);
+      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);
+    } catch (error) {
+      console.error('Error in setInterval step:', error);
+
+      // Call onTick with the data we have, even if LLM failed
+      if (onTick && lastResult) {
+        await onTick({
+          timingString: 'error - using fallback',
+          data: lastResult,
+          nextDate: new Date(Date.now() + 1000), // 1 second fallback
+          error: error.message,
+        });
+      }
+
+      count += 1;
+
+      // Continue with a fallback delay of 1 second
+      if (active) {
+        timer = setTimeout(step, 1000);
+      }
+    }
   };
 
   // Start immediately - the prompt will determine the first interval

package/src/chains/themes/index.js

@@ -11,7 +11,7 @@ export default async function themes(text, config = {}) {
   const { chunkSize = 5, topN, llm, ...options } = config;
   const pieces = splitText(text);
   const reducePrompt =
-    'Update the accumulator with short themes from this text. Avoid duplicates. Return a comma-separated list of themes.';
+    'Update the accumulator with short themes from this text. Avoid duplicates. Return ONLY a comma-separated list of themes with no explanation or additional text.';
   const firstPass = await bulkReduce(shuffle(pieces), reducePrompt, { chunkSize, llm, ...options });
   const rawThemes = firstPass
     .split(',')
@@ -19,7 +19,7 @@ export default async function themes(text, config = {}) {
     .filter(Boolean);
 
   const limitText = topN ? `Limit to the top ${topN} themes.` : 'Return all meaningful themes.';
-  const refinePrompt = `Refine the accumulator by merging similar themes. ${limitText} Return a comma-separated list.`;
+  const refinePrompt = `Refine the accumulator by merging similar themes. ${limitText} Return ONLY a comma-separated list with no explanation or additional text.`;
   const final = await bulkReduce(rawThemes, refinePrompt, { chunkSize, llm, ...options });
   return final
     .split(',')

package/src/constants/common.js

@@ -1,7 +1,13 @@
-export const longTestTimeout = 120000;
+export const longTestTimeout = 10 * 60 * 1000; // 10 minutes
 
 export const maxRetries = 3;
 
 export const retryDelay = 1000;
 
 export const debugToObject = process.env.DEBUG_TO_OBJECT ?? false;
+
+// Utility to conditionally skip long-running examples
+// Set ENABLE_LONG_EXAMPLES=true to run all examples
+// Set ENABLE_LONG_EXAMPLES=false or leave unset to skip long examples
+export const shouldRunLongExamples =
+  process.env.ENABLE_LONG_EXAMPLES === 'true' || process.env.ENABLE_LONG_EXAMPLES === '1';

package/src/constants/models.js

@@ -1,9 +1,10 @@
-// Importing dotenv config to load environment variables from .env file
-// eslint-disable-next-line no-unused-vars
-import dotenv from 'dotenv/config';
+// Environment variables loaded in index.js
 
 const _models = {};
 
+// Function to get API key at runtime
+const getOpenAIKey = () => process.env.OPENAI_API_KEY;
+
 const systemPrompt = `You are a superintelligent processing unit, answering prompts with precise instructions.
 You are a small but critical component in a complex system, so your role in giving quality outputs to your given inputs and instructions is critical. 
 You must obey those instructions to the letter at all costs--do not deviate or add your own interpretation or flair. Stick to the instructions. 
@@ -45,7 +46,9 @@ _models.fastCheapMulti = {
   maxContextWindow: 128_000,
   maxOutputTokens: 16_384,
   requestTimeout: 20_000,
-  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  get apiKey() {
+    return getOpenAIKey();
+  },
   apiUrl: 'https://api.openai.com/',
   systemPrompt,
 };
@@ -59,7 +62,9 @@ _models.goodMulti = {
   maxContextWindow: 128_000,
   maxOutputTokens: 16_384,
   requestTimeout: 20_000,
-  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  get apiKey() {
+    return getOpenAIKey();
+  },
   apiUrl: 'https://api.openai.com/',
   systemPrompt,
 };
@@ -73,7 +78,9 @@ _models.fastCheapReasoningMulti = {
   maxContextWindow: 128_000,
   maxOutputTokens: 16_384,
   requestTimeout: 40_000,
-  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  get apiKey() {
+    return getOpenAIKey();
+  },
   apiUrl: 'https://api.openai.com/',
   systemPrompt,
 };
@@ -87,7 +94,9 @@ _models.reasoningNoImage = {
   maxContextWindow: 200_000,
   maxOutputTokens: 100_000,
   requestTimeout: 120_000,
-  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  get apiKey() {
+    return getOpenAIKey();
+  },
   apiUrl: 'https://api.openai.com/',
   systemPrompt,
 };
@@ -132,7 +141,9 @@ _models.privacy = {
   apiUrl: (process.env.OPENWEBUI_API_URL ?? '').endsWith('/')
     ? process.env.OPENWEBUI_API_URL
     : `${process.env.OPENWEBUI_API_URL}/`,
-  apiKey: process.env.OPENWEBUI_API_KEY ?? 'undefined',
+  get apiKey() {
+    return process.env.OPENWEBUI_API_KEY;
+  },
   systemPrompt,
   modelOptions: {
     stop: ['</s>'],
@@ -145,7 +156,8 @@ if (process.env.NODE_ENV !== 'test') {
 }
 
 const secondsInDay = 60 * 60 * 24;
-export const cacheTTL = process.env.CHATGPT_CACHE_TTL ?? secondsInDay;
+const secondsInYear = secondsInDay * 365; // 365 days
+export const cacheTTL = process.env.CHATGPT_CACHE_TTL ?? secondsInYear;
 
 // Caching can be disabled by setting DISABLE_CACHE=true
 // By default, caching is enabled when Redis is available and working

package/src/index.js

@@ -1,6 +1,6 @@
-// Importing dotenv config to load environment variables from .env file
-// eslint-disable-next-line no-unused-vars
-import dotenv from 'dotenv/config';
+// Load environment variables from .env file FIRST
+import dotenv from 'dotenv';
+dotenv.config();
 
 import chatGPT from './lib/chatgpt/index.js';
 
@@ -33,6 +33,8 @@ import themes from './chains/themes/index.js';
 import test from './chains/test/index.js';
 
 import testAdvice from './chains/test-advice/index.js';
+import Conversation from './chains/conversation/index.js';
+import * as turnPolicies from './chains/conversation/turn-policies.js';
 
 import schemas from './json-schemas/index.js';
 import * as common from './constants/common.js';
@@ -84,12 +86,16 @@ import schemaOrg from './verblets/schema-org/index.js';
 import nameSimilarTo from './verblets/name-similar-to/index.js';
 
 import name from './verblets/name/index.js';
+import peopleList from './verblets/people-list/index.js';
 
 import toObject from './verblets/to-object/index.js';
 
 import listMap from './verblets/list-map/index.js';
 import listFind from './verblets/list-find/index.js';
 
+import conversationTurn from './verblets/conversation-turn/index.js';
+import conversationTurnMulti from './verblets/conversation-turn-multi/index.js';
+
 import bulkGroup from './chains/bulk-group/index.js';
 
 import listGroup from './verblets/list-group/index.js';
@@ -146,6 +152,7 @@ export const verblets = {
   schemaOrg,
   nameSimilarTo,
   name,
+  peopleList,
   toObject,
   listMap,
   listFind,
@@ -166,6 +173,9 @@ export const verblets = {
   setInterval,
   test,
   testAdvice,
+  Conversation,
+  conversationTurn,
+  conversationTurnMulti,
   bulkScore,
   filterAmbiguous,
   bulkGroup,
@@ -188,6 +198,6 @@ export const constants = {
   models,
 };
 
-export { prompts, schemas };
+export { prompts, schemas, turnPolicies };
 
 export default chatGPT;