@far-world-labs/verblets 0.1.1 → 0.1.3

package/src/constants/models.js

@@ -0,0 +1,172 @@
+// Importing dotenv config to load environment variables from .env file
+// eslint-disable-next-line no-unused-vars
+import dotenv from 'dotenv/config';
+
+const _models = {};
+
+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. 
+Aim to be direct, accurate, correct, and concise.
+You'll often be given complex inputs alongside your instructions. Consider the inputs carefully and think through your answer in relation to the inputs and instructions.
+Most prompts will ask for a specific output format, so comply with those details exactly as well.`;
+
+// // $0.10-0.40/1M tokens
+// // cutoff: 5/2024
+// // supports image inputs, very high speed, 1M token context, 32K output
+// // low intelligence, but > 3.5 turbo
+// _models.fastCheapMulti = {
+//   endpoint: 'v1/chat/completions',
+//   name: 'gpt-4.1-nano-2025-04-14',
+//   maxContextWindow: 1_047_576,
+//   maxOutputTokens: 32_768,
+//   requestTimeout: 20_000,
+//   apiKey: process.env.OPENAI_API_KEY,
+//   apiUrl: 'https://api.openai.com/',
+//   systemPrompt,
+// };
+
+// // $.40-$1.60/1M tokens
+// // cutoff: 05/2024
+// // supports image inputs, high speed, 1M token context, 32K output
+// _models.fastGoodMulti = {
+//   endpoint: 'v1/chat/completions',
+//   name: 'gpt-4.1-mini-2025-04-14',
+//   maxContextWindow: 1_047_576,
+//   maxOutputTokens: 32_768,
+//   requestTimeout: 20_000,
+//   apiKey: process.env.OPENAI_API_KEY,
+//   apiUrl: 'https://api.openai.com/',
+//   systemPrompt,
+// };
+_models.fastCheapMulti = {
+  endpoint: 'v1/chat/completions',
+  name: 'gpt-4o',
+  maxContextWindow: 128_000,
+  maxOutputTokens: 16_384,
+  requestTimeout: 20_000,
+  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  apiUrl: 'https://api.openai.com/',
+  systemPrompt,
+};
+
+// $2.5-$10.00/1M tokens
+// cutoff: 09/2023
+// supports image inputs, moderate speed
+_models.goodMulti = {
+  endpoint: 'v1/chat/completions',
+  name: 'gpt-4o-2024-11-20',
+  maxContextWindow: 128_000,
+  maxOutputTokens: 16_384,
+  requestTimeout: 20_000,
+  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  apiUrl: 'https://api.openai.com/',
+  systemPrompt,
+};
+
+// Caution!: $1.1-4.4/1M tokens
+// cutoff: 05/2024
+// supports image inputs, moderate speed
+_models.fastCheapReasoningMulti = {
+  endpoint: 'v1/chat/completions',
+  name: 'o4-mini-2025-04-16',
+  maxContextWindow: 128_000,
+  maxOutputTokens: 16_384,
+  requestTimeout: 40_000,
+  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  apiUrl: 'https://api.openai.com/',
+  systemPrompt,
+};
+
+// Caution!: $10-40/1M tokens
+// cutoff: 05/2024
+// supports image inputs
+_models.reasoningNoImage = {
+  endpoint: 'v1/chat/completions',
+  name: 'o3-2025-04-16',
+  maxContextWindow: 200_000,
+  maxOutputTokens: 100_000,
+  requestTimeout: 120_000,
+  apiKey: process.env.OPENAI_API_KEY ?? 'undefined',
+  apiUrl: 'https://api.openai.com/',
+  systemPrompt,
+};
+
+// Full matrix with explicit names (no aliases)
+_models.fastGoodMulti = _models.fastCheapMulti;
+_models.fastGoodCheapMulti = _models.fastGoodMulti; // Default system model
+_models.fastGoodCheap = _models.fastGoodMulti;
+_models.fastMulti = _models.fastGoodMulti;
+_models.fast = _models.fastGoodMulti;
+_models.fastGood = _models.fastGoodMulti;
+_models.fastReasoningMulti = _models.fastCheapReasoningMulti;
+_models.fastReasoning = _models.fastCheapReasoningMulti;
+
+// eslint-disable-next-line no-self-assign
+_models.fastCheapMulti = _models.fastCheapMulti;
+_models.fastCheap = _models.fastCheapMulti;
+_models.fastCheapReasoning = _models.fastCheapReasoningMulti;
+
+_models.cheapMulti = _models.fastCheapMulti;
+_models.cheap = _models.fastCheapMulti;
+_models.cheapGoodMulti = _models.fastGoodMulti;
+_models.cheapGood = _models.fastGoodMulti;
+_models.cheapReasoningMulti = _models.fastCheapReasoningMulti;
+_models.cheapReasoning = _models.fastCheapReasoningMulti;
+
+// eslint-disable-next-line no-self-assign
+_models.goodMulti = _models.goodMulti; // Caution: Moderate cost
+_models.good = _models.goodMulti; // Caution: Moderate cost
+
+_models.reasoningMulti = _models.fastCheapReasoningMulti; // Caution: Moderate cost
+_models.reasoning = _models.reasoningNoImage; // Caution: High cost
+
+// cutoff: 03/2024
+// Supports image inputs
+_models.privacy = {
+  name: 'gemma3:latest', // same as gemma3:4b
+  endpoint: 'api/chat/completions',
+  maxContextWindow: 128_000,
+  maxOutputTokens: 8_192,
+  requestTimeout: 120_000,
+  apiUrl: (process.env.OPENWEBUI_API_URL ?? '').endsWith('/')
+    ? process.env.OPENWEBUI_API_URL
+    : `${process.env.OPENWEBUI_API_URL}/`,
+  apiKey: process.env.OPENWEBUI_API_KEY ?? 'undefined',
+  systemPrompt,
+  modelOptions: {
+    stop: ['</s>'],
+  },
+};
+
+// Allow tests to run without requiring an API key
+if (process.env.NODE_ENV !== 'test') {
+  // expect(process.env.OPENAI_API_KEY).to.exist;
+}
+
+const secondsInDay = 60 * 60 * 24;
+export const cacheTTL = process.env.CHATGPT_CACHE_TTL ?? secondsInDay;
+
+// Caching can be disabled by setting DISABLE_CACHE=true
+// By default, caching is enabled when Redis is available and working
+export const cachingEnabled = process.env.DISABLE_CACHE !== 'true';
+
+export const debugPromptGlobally = process.env.CHATGPT_DEBUG_PROMPT ?? false;
+
+export const debugPromptGloballyIfChanged = process.env.CHATGPT_DEBUG_REQUEST_IF_CHANGED ?? false;
+
+export const debugResultGlobally = process.env.CHATGPT_DEBUG_RESPONSE ?? false;
+
+export const debugResultGloballyIfChanged = process.env.CHATGPT_DEBUG_RESPONSE_IF_CHANGED ?? false;
+
+export const frequencyPenalty = process.env.CHATGPT_FREQUENCY_PENALTY ?? 0;
+
+export const models = _models;
+
+export const operationTimeoutMultiplier = 2;
+
+export const presencePenalty = process.env.CHATGPT_PRESENCE_PENALTY ?? 0;
+
+export const temperature = process.env.CHATGPT_TEMPERATURE ?? 0;
+
+export const topP = process.env.CHATGPT_TOPP ?? 0.5;

package/src/index.js

@@ -1,33 +1,193 @@
- // Importing dotenv config to load environment variables from .env file
+// Importing dotenv config to load environment variables from .env file
 // eslint-disable-next-line no-unused-vars
 import dotenv from 'dotenv/config';
 
-export { default as Dismantle } from './chains/dismantle/index.js';
-export { default as list } from './chains/list/index.js';
+import chatGPT from './lib/chatgpt/index.js';
 
-export { default as questions } from './chains/questions/index.js';
-export { default as scanJS } from './chains/scan-js/index.js';
-export { default as sort } from './chains/sort/index.js';
-export { default as SummaryMap } from './chains/summary-map/index.js';
+// chains are consumed as verblets
 
-export { default as schemas } from './json-schemas/index.js';
+import anonymize from './chains/anonymize/index.js';
+
+import Dismantle from './chains/dismantle/index.js';
+
+import intersections from './chains/intersections/index.js';
+
+import list from './chains/list/index.js';
+import glossary from './chains/glossary/index.js';
+
+import questions from './chains/questions/index.js';
+
+import SocraticMethod from './chains/socratic/index.js';
+
+import scanJS from './chains/scan-js/index.js';
+
+import sort from './chains/sort/index.js';
+import date from './chains/date/index.js';
+import setInterval from './chains/set-interval/index.js';
+import bulkScore from './chains/bulk-score/index.js';
+import filterAmbiguous from './chains/filter-ambiguous/index.js';
+
+import SummaryMap from './chains/summary-map/index.js';
+import themes from './chains/themes/index.js';
+
+import test from './chains/test/index.js';
+
+import testAdvice from './chains/test-advice/index.js';
+
+import schemas from './json-schemas/index.js';
+import * as common from './constants/common.js';
+import * as messages from './constants/messages.js';
+import * as models from './constants/models.js';
+
+// exported lib utilities
+// internal-only: anySignal, editor, parseJsParts, pathAliases, pave, TimedAbortController
+import * as promptCache from './lib/prompt-cache/index.js';
+import retry from './lib/retry/index.js';
+import searchBestFirst from './lib/search-best-first/index.js';
+import searchJSFiles from './lib/search-js-files/index.js';
+import shortenText from './lib/shorten-text/index.js';
+import bulkMap, { bulkMapRetry } from './chains/bulk-map/index.js';
+import bulkFind, { bulkFindRetry } from './chains/bulk-find/index.js';
+import bulkFilter, { bulkFilterRetry } from './chains/bulk-filter/index.js';
+import stripNumeric from './lib/strip-numeric/index.js';
+import stripResponse from './lib/strip-response/index.js';
+import toBool from './lib/to-bool/index.js';
+import toEnum from './lib/to-enum/index.js';
+import toNumber from './lib/to-number/index.js';
+import toNumberWithUnits from './lib/to-number-with-units/index.js';
+import toDate from './lib/to-date/index.js';
+import transcribe from './lib/transcribe/index.js';
+import combinations, { rangeCombinations } from './lib/combinations/index.js';
+
+// prompts
+import * as prompts from './prompts/index.js';
+
+// services
+import * as redis from './services/redis/index.js';
+import modelService from './services/llm-model/index.js';
+
+// verblets
+
+import auto from './verblets/auto/index.js';
+
+import bool from './verblets/bool/index.js';
+
+import enums from './verblets/enum/index.js';
+
+import intent from './verblets/intent/index.js';
+
+import number from './verblets/number/index.js';
+
+import numberWithUnits from './verblets/number-with-units/index.js';
+
+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 toObject from './verblets/to-object/index.js';
+
+import listMap from './verblets/list-map/index.js';
+import listFind from './verblets/list-find/index.js';
+
+import bulkGroup from './chains/bulk-group/index.js';
+
+import listGroup from './verblets/list-group/index.js';
+import intersection from './verblets/intersection/index.js';
+
+// # Concept Science
+import centralTendency from './verblets/central-tendency/index.js';
+import bulkCentralTendency, {
+  bulkCentralTendencyRetry,
+} from './chains/bulk-central-tendency/index.js';
 
-import chatGPT from './lib/chatgpt/index.js';
 export { default as retry } from './lib/retry/index.js';
 export { default as stripResponse } from './lib/strip-response/index.js';
 export { default as searchJSFiles } from './lib/search-js-files/index.js';
+export { default as searchBestFirst } from './lib/search-best-first/index.js';
+export {
+  bulkMap,
+  bulkMapRetry,
+  bulkFind,
+  bulkFindRetry,
+  bulkFilter,
+  bulkFilterRetry,
+  bulkCentralTendency,
+  bulkCentralTendencyRetry,
+};
+export { rangeCombinations } from './lib/combinations/index.js';
+
+export const lib = {
+  chatGPT,
+  promptCache,
+  retry,
+  searchBestFirst,
+  searchJSFiles,
+  shortenText,
+  stripNumeric,
+  stripResponse,
+  toBool,
+  toEnum,
+  toNumber,
+  toNumberWithUnits,
+  toDate,
+  transcribe,
+  combinations,
+  rangeCombinations,
+};
 
-export * as prompts from './prompts/index.js';
+export const verblets = {
+  auto,
+  bool,
+  enums,
+  intent,
+  number,
+  numberWithUnits,
+  schemaOrg,
+  nameSimilarTo,
+  name,
+  toObject,
+  listMap,
+  listFind,
+  bulkMap,
+  bulkFind,
+  anonymize,
+  Dismantle,
+  intersections,
+  list,
+  glossary,
+  questions,
+  SocraticMethod,
+  scanJS,
+  sort,
+  date,
+  SummaryMap,
+  themes,
+  setInterval,
+  test,
+  testAdvice,
+  bulkScore,
+  filterAmbiguous,
+  bulkGroup,
+  bulkFilter,
+  listGroup,
+  intersection,
+  // # Concept Science
+  centralTendency,
+  bulkCentralTendency,
+};
 
-export { getClient as getRedis } from './services/redis/index.js';
+export const services = {
+  redis,
+  modelService,
+};
 
-export { default as auto } from './verblets/auto/index.js';
-export { default as bool } from './verblets/bool/index.js';
-export { default as enums } from './verblets/enum/index.js';
-export { default as intent } from './verblets/intent/index.js';
-export { default as number } from './verblets/number/index.js';
-export { default as schemaOrg } from './verblets/schema-org/index.js';
-export { default as toObject } from './verblets/to-object/index.js';
+export const constants = {
+  common,
+  messages,
+  models,
+};
 
+export { prompts, schemas };
 
 export default chatGPT;

package/src/json-schemas/README.md

@@ -0,0 +1,13 @@
+# JSON Schemas
+
+This folder contains example schemas used throughout the project. Schemas are referenced by certain verblets and chains for validating or shaping structured output.
+
+Included files:
+
+- `cars-test.json`
+- `intent.json`
+- `schema-dot-org-photograph.json`
+- `schema-dot-org-place.json`
+- `index.js` – helper that loads a subset of schemas for quick access.
+
+Additional schemas may live alongside the modules that use them (for example in `../verblets` or `../chains`).

package/src/json-schemas/index.js

@@ -1,18 +1,12 @@
 import fs from 'node:fs/promises';
 
-const schemaFileNames = [
-  '../verblets/bool/index.schema.json',
-  '../chains/list/schema.json'
-];
-
-const schemas = [];
-
-for (let schemaFileName of schemaFileNames) {
-  const schemaText = await fs.readFile(
-    new URL(schemaFileName, import.meta.url)
-  );
-  const schema = JSON.parse(schemaText);
-  schemas.push(schema)
-}
+const schemaFileNames = ['../verblets/bool/index.schema.json', '../chains/list/schema.json'];
+
+const schemas = await Promise.all(
+  schemaFileNames.map(async (schemaFileName) => {
+    const schemaText = await fs.readFile(new URL(schemaFileName, import.meta.url));
+    return JSON.parse(schemaText);
+  })
+);
 
 export default schemas;

package/src/json-schemas/schema-dot-org-photograph.json

@@ -2,6 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://example.com/schemas/photograph.json",
   "type": "object",
+  "additionalProperties": false,
   "properties": {
     "@context": {
       "type": "string",
@@ -28,6 +29,7 @@
     },
     "thumbnail": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "@type": {
           "type": "string",
@@ -45,10 +47,11 @@
           "minimum": 1
         }
       },
-      "required": ["url"]
+      "required": ["@type", "url"]
     },
     "image": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "@type": {
           "type": "string",
@@ -66,10 +69,11 @@
           "minimum": 1
         }
       },
-      "required": ["url"]
+      "required": ["@type", "url"]
     },
     "contentLocation": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "@type": {
           "type": "string",
@@ -80,6 +84,7 @@
         },
         "address": {
           "type": "object",
+          "additionalProperties": false,
           "properties": {
             "@type": {
               "type": "string",
@@ -101,10 +106,11 @@
               "type": "string"
             }
           },
-          "required": ["streetAddress", "addressLocality", "addressRegion", "postalCode", "addressCountry"]
+          "required": ["@type", "addressLocality", "addressCountry"]
         },
         "geo": {
           "type": "object",
+          "additionalProperties": false,
           "properties": {
             "@type": {
               "type": "string",
@@ -117,10 +123,10 @@
               "type": "number"
             }
           },
-          "required": ["latitude", "longitude"]
+          "required": ["@type", "latitude", "longitude"]
         }
       },
-      "required": ["name"]
+      "required": ["@type", "name"]
     }
   },
   "required": ["@context", "@type", "name"]

package/src/json-schemas/schema-dot-org-place.json

@@ -1,7 +1,12 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
+  "additionalProperties": false,
   "properties": {
+    "@context": {
+      "type": "string",
+      "pattern": "^https://schema.org$"
+    },
     "@type": {
       "type": "string",
       "enum": ["Place", "City"]
@@ -9,8 +14,52 @@
     "name": {
       "type": "string"
     },
+    "alternateName": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "population": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "area": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "@type": {
+          "type": "string",
+          "enum": ["QuantitativeValue"]
+        },
+        "value": {
+          "type": "number",
+          "minimum": 0
+        },
+        "unitCode": {
+          "type": "string"
+        }
+      }
+    },
+    "elevation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "@type": {
+          "type": "string",
+          "enum": ["QuantitativeValue"]
+        },
+        "value": {
+          "type": "number"
+        },
+        "unitCode": {
+          "type": "string"
+        }
+      }
+    },
     "address": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "@type": {
           "type": "string",
@@ -31,11 +80,11 @@
         "addressCountry": {
           "type": "string"
         }
-      },
-      "additionalProperties": true
+      }
     },
     "geo": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "@type": {
           "type": "string",
@@ -47,10 +96,34 @@
         "longitude": {
           "type": "number"
         }
-      },
-      "additionalProperties": true
+      }
+    },
+    "areaServed": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "@type": {
+              "type": "string",
+              "enum": ["AdministrativeArea"]
+            },
+            "name": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    },
+    "additionalType": {
+      "type": "string"
+    },
+    "sameAs": {
+      "type": "string"
     }
   },
-  "additionalProperties": true,
   "required": ["@type", "name"]
 }

package/src/lib/README.md

@@ -0,0 +1,26 @@
+# Library Helpers
+
+The `lib` directory houses reusable utilities used by verblets and chains. Each subfolder contains a focused helper function or class.
+
+Modules include:
+
+<!-- commonly used utilities -->
+- [chatgpt](./chatgpt) – wrapper around OpenAI's ChatGPT API.
+- [prompt-cache](./prompt-cache) – cache prompts/responses locally.
+- [retry](./retry) – generic async retry helper.
+- [search-best-first](./search-best-first) – best-first tree search algorithm.
+- [search-js-files](./search-js-files) – locate and analyze JavaScript files.
+- [combinations](./combinations) – generate array combinations.
+- [rangeCombinations](./combinations) – combinations across multiple sizes.
+- [shorten-text](./shorten-text) – shorten text using an LLM.
+- [bulk-map](./bulk-map) – map lists in retryable batches.
+- [bulk-filter](./bulk-filter) – filter lists in retryable batches.
+- [strip-numeric](./strip-numeric) – remove non-digit characters.
+- [strip-response](./strip-response) – clean up model responses.
+- [to-bool](./to-bool) – parse text into a boolean.
+- [to-enum](./to-enum) – parse text into an enum value.
+- [to-number](./to-number) – parse text into a number.
+- [to-number-with-units](./to-number-with-units) – parse numbers that include units.
+- [transcribe](./transcribe) – microphone transcription via Whisper.
+
+These helpers are building blocks used throughout the rest of the project.

package/src/lib/bulk-filter/README.md

@@ -0,0 +1,22 @@
+# bulk-filter
+
+Filter long lists in batches using `listFilter`. Batches that fail can be retried.
+
+```javascript
+import bulkFilter from './index.js';
+
+const reflections = [
+  'Losing that match taught me the value of persistence.',
+  "I hate losing and it proves I'm worthless.",
+  'After failing my exam, I studied harder and passed the retake.',
+  "No matter what I do, I'll never succeed.",
+];
+const growth = await bulkFilter(
+  reflections,
+  'keep only reflections that show personal growth or learning from mistakes'
+);
+// growth === [
+//   'Losing that match taught me the value of persistence.',
+//   'After failing my exam, I studied harder and passed the retake.',
+// ]
+```