@far-world-labs/verblets 0.1.1 → 0.1.3

package/src/services/llm-model/negotiate.spec.js

@@ -0,0 +1,447 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import modelService from './index.js';
+import Model from './model.js';
+
+// helper tokenizer
+const tokenizer = (t) => t.split(' ');
+
+describe('Model negotiation', () => {
+  beforeEach(() => {
+    // Reset models before each test
+    modelService.models = {};
+    modelService.bestPublicModelKey = 'fastGood';
+  });
+
+  describe('Privacy models', () => {
+    it('prefers privacy model when requested and available', () => {
+      modelService.models = {
+        privacy: new Model({
+          name: 'privacy-model',
+          maxContextWindow: 128000,
+          maxOutputTokens: 8192,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastGood: new Model({
+          name: 'fast-good-model',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+
+      const key = modelService.negotiateModel('fastGood', { privacy: true });
+      expect(key).toBe('privacy');
+    });
+
+    it('throws error when privacy requested but not configured', () => {
+      modelService.models = {
+        fastGood: new Model({
+          name: 'fast-good-model',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+
+      expect(modelService.negotiateModel('fastGood', { privacy: true })).toBe(undefined);
+    });
+  });
+
+  describe('Exact model key matching', () => {
+    beforeEach(() => {
+      modelService.models = {
+        fastGood: new Model({
+          name: 'fast-good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastCheap: new Model({
+          name: 'fast-cheap',
+          maxContextWindow: 128000,
+          maxOutputTokens: 8192,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastReasoning: new Model({
+          name: 'fast-reasoning',
+          maxContextWindow: 200000,
+          maxOutputTokens: 100000,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastCheapReasoning: new Model({
+          name: 'fast-cheap-reasoning',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastGoodMulti: new Model({
+          name: 'fast-good-multi',
+          maxContextWindow: 1000000,
+          maxOutputTokens: 32768,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastCheapReasoningMulti: new Model({
+          name: 'fast-cheap-reasoning-multi',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        good: new Model({
+          name: 'good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        reasoning: new Model({
+          name: 'reasoning',
+          maxContextWindow: 200000,
+          maxOutputTokens: 100000,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fast: new Model({
+          name: 'fast',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        cheap: new Model({
+          name: 'cheap',
+          maxContextWindow: 128000,
+          maxOutputTokens: 8192,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+    });
+
+    it('returns highest priority match for fast + cheap', () => {
+      // Should find fastCheap since it has both fast and cheap
+      const key = modelService.negotiateModel(null, { fast: true, cheap: true });
+      expect(key).toBe('fastCheap'); // fastCheap matches both requirements
+    });
+
+    it('returns highest priority match for fast + reasoning', () => {
+      // Should find fastReasoning since it has both fast and reasoning
+      const key = modelService.negotiateModel(null, { fast: true, reasoning: true });
+      expect(key).toBe('fastCheapReasoning'); // fastReasoning matches both requirements
+    });
+
+    it('returns exact match when it exists and has high priority', () => {
+      const key = modelService.negotiateModel(null, { fast: true, cheap: true, reasoning: true });
+      expect(key).toBe('fastCheapReasoning'); // Exact match exists
+    });
+
+    it('returns exact match for fast + good + multi', () => {
+      const key = modelService.negotiateModel(null, { fast: true, good: true, multi: true });
+      expect(key).toBe('fastGoodMulti'); // Exact match exists
+    });
+
+    it('returns exact match for fast + cheap + reasoning + multi', () => {
+      const key = modelService.negotiateModel(null, {
+        fast: true,
+        cheap: true,
+        reasoning: true,
+        multi: true,
+      });
+      expect(key).toBe('fastCheapReasoningMulti'); // Exact match exists
+    });
+  });
+
+  describe('Fallback logic', () => {
+    beforeEach(() => {
+      modelService.models = {
+        fastGoodCheap: new Model({
+          name: 'fast-good-cheap',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastGood: new Model({
+          name: 'fast-good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastCheap: new Model({
+          name: 'fast-cheap',
+          maxContextWindow: 128000,
+          maxOutputTokens: 8192,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastReasoning: new Model({
+          name: 'fast-reasoning',
+          maxContextWindow: 200000,
+          maxOutputTokens: 100000,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        good: new Model({
+          name: 'good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        reasoning: new Model({
+          name: 'reasoning',
+          maxContextWindow: 200000,
+          maxOutputTokens: 100000,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fast: new Model({
+          name: 'fast',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        cheap: new Model({
+          name: 'cheap',
+          maxContextWindow: 128000,
+          maxOutputTokens: 8192,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+    });
+
+    it('finds exact match when available', () => {
+      const key = modelService.negotiateModel(null, { fast: true, good: true });
+      expect(key).toBe('fastGoodCheap');
+    });
+
+    it('requires all specified features to match', () => {
+      // Request multi but no multi models exist - should return undefined
+      expect(modelService.negotiateModel(null, { fast: true, multi: true })).toBe(undefined);
+    });
+
+    it('picks higher priority model when multiple match', () => {
+      // Both fastGoodCheap, fastGood and good match { good: true }, should pick fastGoodCheap (highest priority)
+      const key = modelService.negotiateModel(null, { good: true });
+      expect(key).toBe('fastGoodCheap');
+    });
+
+    it('respects all requirements strictly', () => {
+      // Request fast + cheap + reasoning - no exact match available, should return undefined since reasoning is requested
+      expect(modelService.negotiateModel(null, { fast: true, cheap: true, reasoning: true })).toBe(
+        undefined
+      );
+    });
+
+    it('works with single requirements', () => {
+      const key = modelService.negotiateModel(null, { reasoning: true });
+      expect(key).toBe('fastReasoning');
+    });
+
+    it('works with multi requirement when available', () => {
+      modelService.models.fastGoodMulti = new Model({
+        name: 'fast-good-multi',
+        maxContextWindow: 1000000,
+        maxOutputTokens: 32768,
+        requestTimeout: 1000,
+        tokenizer,
+      });
+
+      const key = modelService.negotiateModel(null, { fast: true, good: true, multi: true });
+      expect(key).toBe('fastGoodMulti');
+    });
+
+    it('falls back to best public model when no matches found', () => {
+      // Request something that doesn't exist with reasoning - should return undefined
+      expect(
+        modelService.negotiateModel(null, {
+          fast: true,
+          cheap: true,
+          good: true,
+          reasoning: true,
+          multi: true,
+        })
+      ).toBe(undefined);
+    });
+
+    it('prioritizes better combinations over individual features', () => {
+      // Both fast and fastGoodCheap match { fast: true }, should pick fastGoodCheap
+      const key = modelService.negotiateModel(null, { fast: true });
+      expect(key).toBe('fastGoodCheap');
+    });
+  });
+
+  describe('Preferred model handling', () => {
+    beforeEach(() => {
+      modelService.models = {
+        fastGood: new Model({
+          name: 'fast-good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        customModel: new Model({
+          name: 'custom',
+          maxContextWindow: 64000,
+          maxOutputTokens: 8192,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+    });
+
+    it('returns preferred model when available and no privacy requested', () => {
+      const key = modelService.negotiateModel('customModel', { fast: true });
+      expect(key).toBe('fastGood');
+    });
+
+    it('ignores preferred model when privacy is requested', () => {
+      modelService.models.privacy = new Model({
+        name: 'privacy',
+        maxContextWindow: 128000,
+        maxOutputTokens: 8192,
+        requestTimeout: 1000,
+        tokenizer,
+      });
+
+      const key = modelService.negotiateModel('customModel', { privacy: true });
+      expect(key).toBe('privacy');
+    });
+
+    it('falls back to negotiation when preferred model does not exist', () => {
+      const key = modelService.negotiateModel('nonExistentModel', { fast: true });
+      expect(key).toBe('fastGood');
+    });
+  });
+
+  describe('Edge cases', () => {
+    beforeEach(() => {
+      modelService.models = {
+        fastGood: new Model({
+          name: 'fast-good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+    });
+
+    it('handles empty negotiation object', () => {
+      const key = modelService.negotiateModel(null, {});
+      expect(key).toBe('fastGood');
+    });
+
+    it('handles undefined negotiation', () => {
+      const key = modelService.negotiateModel(null);
+      expect(key).toBe('fastGood');
+    });
+
+    it('handles single flag requests', () => {
+      const key = modelService.negotiateModel(null, { fast: true });
+      expect(key).toBe('fastGood');
+    });
+
+    it('prioritizes reasoning over good when both are requested', () => {
+      modelService.models.fastReasoning = new Model({
+        name: 'fast-reasoning',
+        maxContextWindow: 200000,
+        maxOutputTokens: 100000,
+        requestTimeout: 1000,
+        tokenizer,
+      });
+
+      // Request fast + reasoning + good but no model has all three - should return undefined
+      expect(modelService.negotiateModel(null, { fast: true, reasoning: true, good: true })).toBe(
+        undefined
+      );
+    });
+  });
+
+  describe('Property negation', () => {
+    beforeEach(() => {
+      modelService.models = {
+        fastGoodCheap: new Model({
+          name: 'fast-good-cheap',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fastGood: new Model({
+          name: 'fast-good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        good: new Model({
+          name: 'good',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        fast: new Model({
+          name: 'fast',
+          maxContextWindow: 128000,
+          maxOutputTokens: 16384,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+        reasoning: new Model({
+          name: 'reasoning',
+          maxContextWindow: 200000,
+          maxOutputTokens: 100000,
+          requestTimeout: 1000,
+          tokenizer,
+        }),
+      };
+    });
+
+    it('excludes models with negated properties', () => {
+      // Request good but NOT fast - should pick 'good' over 'fastGood'
+      const key = modelService.negotiateModel(null, { good: true, fast: false });
+      expect(key).toBe('good');
+    });
+
+    it('excludes models with multiple negated properties', () => {
+      // Request good but NOT fast and NOT cheap - should pick 'good'
+      const key = modelService.negotiateModel(null, { good: true, fast: false, cheap: false });
+      expect(key).toBe('good');
+    });
+
+    it('works with only negated properties', () => {
+      // Request NOT fast - should pick 'good' (first non-fast model in priority)
+      const key = modelService.negotiateModel(null, { fast: false });
+      expect(key).toBe('good');
+    });
+
+    it('combines positive and negative requirements', () => {
+      // Request fast but NOT good - should pick 'fast' over 'fastGood'
+      // fastGoodCheap has both fast and good, so it's excluded by good: false
+      // fastGood has both fast and good, so it's excluded by good: false
+      // fast has fast but no good, so it matches
+      const key = modelService.negotiateModel(null, { fast: true, good: false });
+      expect(key).toBe('fast');
+    });
+
+    it('falls back when negation eliminates all matches', () => {
+      // Request NOT reasoning (all models are non-reasoning, so should pick first priority)
+      const key = modelService.negotiateModel(null, { good: false });
+      expect(key).toBe('fast');
+    });
+  });
+});

package/src/services/redis/index.js

@@ -8,25 +8,84 @@ class NullRedisClient {
     this.store = {};
   }
 
-  async get(key) {
+  get(key) {
     // Redis returns null, not undefined
     return this.store[key] ?? null;
   }
 
-  async del(key) {
+  del(key) {
     delete this.store[key];
   }
 
-  async set(key, value) {
+  set(key, value, _options) {
     this.store[key] = value;
   }
 
-  // eslint-disable-next-line class-methods-use-this, no-empty-function
-  async disconnect() {
+  disconnect() {
     // no implementation
   }
 }
 
+class SafeRedisClient {
+  constructor(redisClient) {
+    this.redisClient = redisClient;
+    this.fallbackClient = new NullRedisClient();
+  }
+
+  async get(key) {
+    try {
+      return await this.redisClient.get(key);
+    } catch (error) {
+      if (this.isConnectionError(error)) {
+        console.warn('Redis connection lost, falling back to in-memory cache');
+        return this.fallbackClient.get(key);
+      }
+      throw error;
+    }
+  }
+
+  async set(key, value, options) {
+    try {
+      return await this.redisClient.set(key, value, options);
+    } catch (error) {
+      if (this.isConnectionError(error)) {
+        console.warn('Redis connection lost, falling back to in-memory cache');
+        return this.fallbackClient.set(key, value, options);
+      }
+      throw error;
+    }
+  }
+
+  async del(key) {
+    try {
+      return await this.redisClient.del(key);
+    } catch (error) {
+      if (this.isConnectionError(error)) {
+        console.warn('Redis connection lost, falling back to in-memory cache');
+        return this.fallbackClient.del(key);
+      }
+      throw error;
+    }
+  }
+
+  async disconnect() {
+    try {
+      return await this.redisClient.disconnect();
+    } catch {
+      // Ignore disconnect errors
+    }
+  }
+
+  isConnectionError(error) {
+    return (
+      error.message.includes('client is closed') ||
+      error.message.includes('ECONNREFUSED') ||
+      error.message.includes('connection') ||
+      error.code === 'ECONNREFUSED'
+    );
+  }
+}
+
 const constructClient = async () => {
   if (process.env.TEST === 'true' && process.env.EXAMPLES !== 'true') {
     client = new NullRedisClient();
@@ -50,14 +109,18 @@ const constructClient = async () => {
       client = new NullRedisClient();
     } else {
       console.error(`Redis service [error]: ${error.message}`);
+      client = new NullRedisClient();
     }
 
-    redisClient.disconnect();
+    // Safely disconnect the Redis client
+    redisClient.disconnect().catch(() => {
+      // Ignore disconnect errors
+    });
   });
 
   try {
     await redisClient.connect();
-    client = redisClient;
+    client = new SafeRedisClient(redisClient);
   } catch (error) {
     console.error(
       `Redis service create [warning]: "${error.message}" Falling back to mock Redis client. This may incur greater usage costs and have slower response times.`

package/src/test/setup.js

@@ -0,0 +1,20 @@
+import { afterAll, beforeEach } from 'vitest';
+import dotenv from 'dotenv';
+import { getClient as getRedis } from '../services/redis/index.js';
+
+// Load environment variables from .env file
+dotenv.config();
+
+let redisClient;
+
+beforeEach(async () => {
+  // Get a fresh Redis client for each test
+  redisClient = await getRedis();
+});
+
+afterAll(async () => {
+  // Clean up Redis client after all tests
+  if (redisClient) {
+    await redisClient.disconnect();
+  }
+});

package/src/verblets/README.md

@@ -0,0 +1,26 @@
+# Verblets
+
+The `verblets` directory contains individual utilities that wrap specific language-model workflows. Each verblet exports a single function and usually includes its own examples, tests and optional JSON schema.
+
+Available verblets:
+
+- [auto](./auto)
+- [bool](./bool)
+- [name](./name) - generate evocative names from text
+- [enum](./enum)
+- [intent](./intent)
+- [number](./number)
+- [number-with-units](./number-with-units)
+- [date](../chains/date)
+- [sentiment](./sentiment) - classify text sentiment
+- [schema-org](./schema-org)
+- [name-similar-to](./name-similar-to) - suggest short names matching a style
+- [name](./name) - name something from a definition or description
+- [to-object](./to-object) – see its [README](./to-object/README.md) for details.
+- [list-map](./list-map) - map lists with prompts
+- [list-reduce](./list-reduce) - reduce lists prompts
+- [list-filter](./list-filter) - filter lists with custom instructions
+- [list-group](./list-group) - group lists into categories with prompts
+- [list-expand](./list-expand) - expand lists with similar items with prompts
+
+Use these modules directly or compose them inside [chains](../chains/README.md).

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

@@ -1,27 +1,30 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
 import auto from './index.js';
 
 const examples = [
   {
     inputs: { text: 'test' },
-    want: { result: true }
-  }
+    want: {
+      typeOfResult: 'object',
+      hasProperties: ['functionArgsAsArray'],
+    },
+  },
 ];
 
 describe('Auto verblet', () => {
   examples.forEach((example) => {
     it(example.inputs.text, async () => {
-      const result = await auto(example.inputs.text)
+      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);
       }
 
-      if (example.want.result) {
-        expect(result)
-          .toStrictEqual(example.want.result);
+      if (example.want.hasProperties) {
+        example.want.hasProperties.forEach((prop) => {
+          expect(result).toHaveProperty(prop);
+        });
       }
     });
   });

package/src/verblets/auto/index.js

@@ -1,20 +1,20 @@
 import chatGPT from '../../lib/chatgpt/index.js';
-import toObject from '../../verblets/to-object/index.js';
-import schemas from '../../json-schemas/index.js'
+import schemas from '../../json-schemas/index.js';
 
-export default async (text, options={}) => {
-  const tools = schemas
-    .map(schema => ({
-      type: 'function',
-      function: schema
-    }))
+export default async (text, config = {}) => {
+  const { llm, ...options } = config;
+  const tools = schemas.map((schema) => ({
+    type: 'function',
+    function: schema,
+  }));
 
   const functionFound = await chatGPT(text, {
     modelOptions: {
       // toolChoice: 'auto' // by default
       tools,
+      ...llm,
     },
-    ...options
+    ...options,
   });
 
   const functionArgs = functionFound.arguments;
@@ -23,6 +23,6 @@ export default async (text, options={}) => {
 
   return {
     ...functionFound,
-    functionArgsAsArray
+    functionArgsAsArray,
   };
 };