@far-world-labs/verblets 0.1.7 → 0.3.2

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

@@ -1,129 +0,0 @@
-{
-  "$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"]
-    },
-    "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",
-          "enum": ["PostalAddress"]
-        },
-        "streetAddress": {
-          "type": "string"
-        },
-        "addressLocality": {
-          "type": "string"
-        },
-        "addressRegion": {
-          "type": "string"
-        },
-        "postalCode": {
-          "type": "string"
-        },
-        "addressCountry": {
-          "type": "string"
-        }
-      }
-    },
-    "geo": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "@type": {
-          "type": "string",
-          "enum": ["GeoCoordinates"]
-        },
-        "latitude": {
-          "type": "number"
-        },
-        "longitude": {
-          "type": "number"
-        }
-      }
-    },
-    "areaServed": {
-      "oneOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "@type": {
-              "type": "string",
-              "enum": ["AdministrativeArea"]
-            },
-            "name": {
-              "type": "string"
-            }
-          }
-        }
-      ]
-    },
-    "additionalType": {
-      "type": "string"
-    },
-    "sameAs": {
-      "type": "string"
-    }
-  },
-  "required": ["@type", "name"]
-}

package/src/lib/README.md

@@ -1,26 +0,0 @@
-# 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/any-signal/index.js

@@ -1,28 +0,0 @@
-/**
- * Creates a new AbortSignal that is triggered when any of the given signals are aborted.
- *
- * @param {AbortSignal[]} signals - An array of AbortSignal instances to listen to.
- * @returns {AbortSignal} - A new AbortSignal that is aborted when any of the input signals are aborted.
- *
- * @example
- * const abortController1 = new AbortController();
- * const abortController2 = new AbortController();
- * const combinedSignal = anySignal([abortController1.signal, abortController2.signal]);
- * fetch('https://example.com', { signal: combinedSignal });
- * abortController1.abort(); // This will abort the fetch operation
- */
-export default (signalsInitial) => {
-  const signals = signalsInitial.filter((s) => s);
-
-  const controller = new AbortController();
-  for (const signal of signals) {
-    if (signal.aborted) {
-      controller.abort();
-      break;
-    }
-    signal.addEventListener('abort', () => {
-      controller.abort();
-    });
-  }
-  return controller.signal;
-};

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

@@ -1,22 +0,0 @@
-# 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.',
-// ]
-```

package/src/lib/bulk-filter/index.examples.js

@@ -1,27 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import bulkFilter from './index.js';
-import { longTestTimeout } from '../../constants/common.js';
-
-describe('bulk-filter examples', () => {
-  it(
-    'filters items in batches',
-    async () => {
-      const entries = [
-        '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 result = await bulkFilter(
-        entries,
-        'keep only reflections that show personal growth or learning from mistakes',
-        2
-      );
-      expect(result).toStrictEqual([
-        'Losing that match taught me the value of persistence.',
-        'After failing my exam, I studied harder and passed the retake.',
-      ]);
-    },
-    longTestTimeout
-  );
-});

package/src/lib/bulk-filter/index.js

@@ -1,63 +0,0 @@
-import listFilter from '../../verblets/list-filter/index.js';
-
-/**
- * Filter a list by processing newline-delimited batches with `listFilter`.
- *
- * @param {string[]} list - array of items to evaluate
- * @param {string} instructions - filter instructions for `listFilter`
- * @param {number} [chunkSize=10] - how many items per batch
- * @returns {Promise<string[]>} filtered items preserving order
- */
-export default async function bulkFilter(list, instructions, chunkSize = 10) {
-  const batches = [];
-  for (let i = 0; i < list.length; i += chunkSize) {
-    const batch = list.slice(i, i + chunkSize);
-    const filtered = await listFilter(batch, instructions);
-    batches.push(filtered);
-  }
-  return batches.flat();
-}
-
-/**
- * Retry filtering failed batches until `maxAttempts` is reached.
- *
- * @param {string[]} list
- * @param {string} instructions
- * @param {object} [options]
- * @param {number} [options.chunkSize=10]
- * @param {number} [options.maxAttempts=3]
- * @returns {Promise<string[]>}
- */
-export async function bulkFilterRetry(
-  list,
-  instructions,
-  { chunkSize = 10, maxAttempts = 3 } = {}
-) {
-  const batches = [];
-  for (let i = 0; i < list.length; i += chunkSize) {
-    batches.push(list.slice(i, i + chunkSize));
-  }
-  const results = new Array(batches.length).fill(null);
-  let pending = batches.map((_, idx) => idx);
-
-  for (let attempt = 0; attempt < maxAttempts && pending.length > 0; attempt += 1) {
-    const newPending = [];
-    for (const idx of pending) {
-      const batch = batches[idx];
-      try {
-        const filtered = await listFilter(batch, instructions);
-        const valid = filtered.every((line) => batch.includes(line));
-        if (valid) {
-          results[idx] = filtered;
-        } else {
-          newPending.push(idx);
-        }
-      } catch {
-        newPending.push(idx);
-      }
-    }
-    pending = newPending;
-  }
-
-  return results.flat().filter(Boolean);
-}

package/src/lib/bulk-filter/index.spec.js

@@ -1,38 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from 'vitest';
-import bulkFilter, { bulkFilterRetry } from './index.js';
-import listFilter from '../../verblets/list-filter/index.js';
-
-vi.mock('../../verblets/list-filter/index.js', () => ({
-  default: vi.fn(async (items, instructions) => {
-    if (items.includes('FAIL')) throw new Error('fail');
-    return items.filter((l) => l.includes(instructions));
-  }),
-}));
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe('bulk-filter', () => {
-  it('filters fragments in batches', async () => {
-    const result = await bulkFilter(['aa', 'b', 'ca', 'd'], 'a', 2);
-    expect(result).toStrictEqual(['aa', 'ca']);
-    expect(listFilter).toHaveBeenCalledTimes(2);
-  });
-
-  it('retries failed batches', async () => {
-    let call = 0;
-    listFilter.mockImplementation(async (items) => {
-      call += 1;
-      if (call === 1) throw new Error('fail');
-      return items.filter((l) => l.includes('a'));
-    });
-
-    const result = await bulkFilterRetry(['aa', 'b', 'ca'], 'a', {
-      chunkSize: 2,
-      maxAttempts: 2,
-    });
-    expect(result).toStrictEqual(['aa', 'ca']);
-    expect(listFilter).toHaveBeenCalledTimes(3);
-  });
-});

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

@@ -1,18 +0,0 @@
-# bulk-find
-
-Search large lists in batches using `listFind` and return the first matching item.
-Failed batches can be retried with `bulkFindRetry`.
-
-```javascript
-import bulkFind, { bulkFindRetry } from './index.js';
-
-const diaryEntries = [
-  'Hiked up the mountains today and saw breathtaking views',
-  'Visited the local market and tried a spicy stew',
-  'Spotted penguins playing on the beach this morning'
-];
-const penguinMoment = await bulkFindRetry(diaryEntries, 'mentions penguins', {
-  chunkSize: 2
-});
-// penguinMoment === 'Spotted penguins playing on the beach this morning'
-```

package/src/lib/bulk-find/index.examples.js

@@ -1,19 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { bulkFindRetry } from './index.js';
-import { longTestTimeout } from '../../constants/common.js';
-
-describe('bulk-find examples', () => {
-  it(
-    'finds an item across batches',
-    async () => {
-      const diaryEntries = [
-        'Hiked up the mountains today and saw breathtaking views',
-        'Visited the local market and tried a spicy stew',
-        'Spotted penguins playing on the beach this morning',
-      ];
-      const result = await bulkFindRetry(diaryEntries, 'mentions penguins');
-      expect(result).toBeDefined();
-    },
-    longTestTimeout
-  );
-});

package/src/lib/bulk-find/index.js

@@ -1,30 +0,0 @@
-import listFind from '../../verblets/list-find/index.js';
-
-/**
- * Search a list in batches using `listFind`.
- *
- * @param { string[] } list - array of items to search
- * @param { string } instructions - criteria passed to `listFind`
- * @param { number } [chunkSize=10] - how many items per batch
- * @returns { Promise<string|undefined> } first match or undefined
- */
-export default async function bulkFind(list, instructions, chunkSize = 10) {
-  for (let i = 0; i < list.length; i += chunkSize) {
-    const batch = list.slice(i, i + chunkSize);
-    try {
-      const result = await listFind(batch, instructions);
-      if (result) return result;
-    } catch {
-      // ignore and continue to next batch
-    }
-  }
-  return undefined;
-}
-
-export async function bulkFindRetry(list, instructions, { chunkSize = 10, maxAttempts = 3 } = {}) {
-  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
-    const result = await bulkFind(list, instructions, chunkSize);
-    if (result) return result;
-  }
-  return undefined;
-}

package/src/lib/bulk-find/index.spec.js

@@ -1,41 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from 'vitest';
-import bulkFind, { bulkFindRetry } from './index.js';
-import listFind from '../../verblets/list-find/index.js';
-
-vi.mock('../../verblets/list-find/index.js', () => ({
-  default: vi.fn(async (list, instructions) => list.find((l) => l.includes(instructions)) || ''),
-}));
-
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-describe('bulk-find', () => {
-  it('returns first match across batches', async () => {
-    const result = await bulkFind(['a', 'b', 'c', 'd'], 'c', 2);
-    expect(result).toBe('c');
-    expect(listFind).toHaveBeenCalledTimes(2);
-  });
-
-  it('returns undefined when not found', async () => {
-    listFind.mockResolvedValueOnce('');
-    listFind.mockResolvedValueOnce('');
-    const result = await bulkFind(['a', 'b'], 'x', 1);
-    expect(result).toBeUndefined();
-  });
-
-  it('retries until a match is found', async () => {
-    listFind.mockResolvedValueOnce('');
-    listFind.mockResolvedValueOnce('c');
-    const result = await bulkFindRetry(['a', 'b', 'c'], 'c', { chunkSize: 2, maxAttempts: 2 });
-    expect(result).toBe('c');
-    expect(listFind).toHaveBeenCalledTimes(2);
-  });
-
-  it('returns undefined after maxAttempts', async () => {
-    listFind.mockResolvedValue('');
-    const result = await bulkFindRetry(['a', 'b'], 'x', { chunkSize: 1, maxAttempts: 2 });
-    expect(result).toBeUndefined();
-    expect(listFind).toHaveBeenCalledTimes(4);
-  });
-});

package/src/lib/chatgpt/index.js

@@ -1,163 +0,0 @@
-import fetch from 'node-fetch';
-
-import {
-  debugPromptGlobally,
-  debugPromptGloballyIfChanged,
-  debugResultGlobally,
-  debugResultGloballyIfChanged,
-  models,
-} from '../../constants/models.js';
-import anySignal from '../any-signal/index.js';
-import { get as getPromptResult, set as setPromptResult } from '../prompt-cache/index.js';
-import TimedAbortController from '../timed-abort-controller/index.js';
-import modelService from '../../services/llm-model/index.js';
-import { getClient as getRedis } from '../../services/redis/index.js';
-
-const shapeOutputDefault = (result) => {
-  // GPT-4
-  if (result.choices[0].message.tool_calls?.length) {
-    const toolCall = result.choices[0].message.tool_calls[0];
-    return {
-      name: toolCall.function.name,
-      arguments: JSON.parse(toolCall.function.arguments),
-      result: result.choices[0].message.tool_calls[0].function,
-    };
-  }
-  if (result.choices[0].message) {
-    return result.choices[0].message.content.trim();
-  }
-  return result.choices[0].text.trim();
-};
-
-const onBeforeRequestDefault = ({ debugPrompt, isCached, prompt }) => {
-  if (debugPrompt || debugPromptGlobally || (debugPromptGloballyIfChanged && !isCached)) {
-    console.error('+++ DEBUG PROMPT +++');
-    console.error(prompt);
-    console.error('+++ DEBUG PROMPT END +++');
-  }
-};
-
-const onAfterRequestDefault = ({ debugResult, isCached, resultShaped }) => {
-  if (debugResult || debugResultGlobally || (debugResultGloballyIfChanged && !isCached)) {
-    console.error('+++ DEBUG RESULT +++');
-    console.error(resultShaped);
-    console.error('+++ DEBUG RESULT END +++');
-  }
-};
-
-export const run = async (prompt, config = {}) => {
-  // Handle config parameter - can be string (model name) or object (full options)
-  let options;
-  if (typeof config === 'string') {
-    options = { modelOptions: { modelName: config } };
-  } else {
-    options = config;
-  }
-
-  const {
-    abortSignal,
-    debugPrompt,
-    debugResult,
-    forceQuery,
-    modelOptions = {},
-    onAfterRequest = onAfterRequestDefault,
-    onBeforeRequest = onBeforeRequestDefault,
-    shapeOutput = shapeOutputDefault,
-  } = options;
-
-  // Apply global overrides to model options
-  const modelOptionsWithOverrides = modelService.applyGlobalOverrides(modelOptions);
-
-  // Check if negotiation was applied via global override
-  const negotiationFromGlobalOverride = modelService.getGlobalOverride('negotiate');
-
-  const modelNameNegotiated = modelOptionsWithOverrides.negotiate
-    ? modelService.negotiateModel(
-        // If negotiation came from global override, don't use preferred model
-        negotiationFromGlobalOverride ? null : modelOptionsWithOverrides.modelName,
-        modelOptionsWithOverrides.negotiate
-      )
-    : modelOptionsWithOverrides.modelName;
-
-  const modelFound = modelService.getModel(modelNameNegotiated);
-
-  // Use model-specific API URL and key if defined, otherwise fall back to defaults
-  const apiUrl = modelFound?.apiUrl || models.fastGood.apiUrl;
-  const apiKey = modelFound?.apiKey || models.fastGood.apiKey;
-
-  const requestConfig = modelService.getRequestConfig({
-    prompt,
-    ...modelOptionsWithOverrides,
-    modelName: modelNameNegotiated,
-  });
-
-  // Check if caching is disabled via environment variable
-  const cachingDisabled = process.env.DISABLE_CACHE === 'true';
-
-  let cacheResult = null;
-  let cache = null;
-
-  if (!cachingDisabled) {
-    cache = await getRedis();
-    const { result } = await getPromptResult(cache, requestConfig);
-    cacheResult = result;
-  }
-
-  onBeforeRequest({
-    isCached: !!cacheResult,
-    debugPrompt,
-    prompt,
-    requestConfig,
-  });
-
-  let result = cacheResult;
-  if (!cacheResult || forceQuery) {
-    // Use custom requestTimeout from modelOptions if provided, otherwise use model default
-    const requestTimeout =
-      modelOptionsWithOverrides.requestTimeout ||
-      modelService.getModel(modelNameNegotiated).requestTimeout;
-
-    const timeoutController = new TimedAbortController(requestTimeout);
-
-    // console.log(requestConfig, `${apiUrl}${modelFound.endpoint}`)
-
-    const response = await fetch(`${apiUrl}${modelFound.endpoint}`, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(requestConfig),
-      signal: anySignal([abortSignal, timeoutController.signal]),
-    });
-
-    result = await response.json();
-
-    if (!response.ok) {
-      const vars = [`status: ${response?.status}`, `type: ${result?.error?.type}`].join(', ');
-      throw new Error(`Completions request [error]: ${result?.error?.message} (${vars})`);
-    }
-
-    timeoutController.clearTimeout();
-
-    // Only cache the result if caching is not disabled
-    if (!cachingDisabled && cache) {
-      await setPromptResult(cache, requestConfig, result);
-    }
-  }
-
-  const resultShaped = shapeOutput(result);
-
-  onAfterRequest({
-    debugResult,
-    isCached: !!cacheResult,
-    prompt,
-    requestConfig,
-    result,
-    resultShaped,
-  });
-
-  return resultShaped;
-};
-
-export default run;

package/src/lib/combinations/index.js

@@ -1,30 +0,0 @@
-export default function combinations(items, size = 2) {
-  const result = [];
-  if (!Array.isArray(items) || size < 1) return result;
-
-  const combo = [];
-  const generate = (start) => {
-    if (combo.length === size) {
-      result.push([...combo]);
-      return;
-    }
-    for (let i = start; i < items.length; i++) {
-      combo.push(items[i]);
-      generate(i + 1);
-      combo.pop();
-    }
-  };
-
-  generate(0);
-  return result;
-}
-
-export function rangeCombinations(items, minSize = 2, maxSize = items.length) {
-  const sets = [];
-  if (!Array.isArray(items)) return sets;
-  const upper = Math.min(items.length, maxSize);
-  for (let s = minSize; s <= upper; s++) {
-    sets.push(...combinations(items, s));
-  }
-  return sets;
-}

package/src/lib/combinations/index.spec.js

@@ -1,23 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import combinations, { rangeCombinations } from './index.js';
-
-describe('combinations helper', () => {
-  it('generates pairwise combinations', () => {
-    const result = combinations(['a', 'b', 'c'], 2);
-    expect(result).toStrictEqual([
-      ['a', 'b'],
-      ['a', 'c'],
-      ['b', 'c'],
-    ]);
-  });
-
-  it('generates combinations of varying sizes', () => {
-    const result = rangeCombinations(['a', 'b', 'c']);
-    expect(result).toStrictEqual([
-      ['a', 'b'],
-      ['a', 'c'],
-      ['b', 'c'],
-      ['a', 'b', 'c'],
-    ]);
-  });
-});