@far-world-labs/verblets 0.2.0 → 0.3.2

package/src/chains/list/index.js

@@ -1,214 +0,0 @@
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { operationTimeoutMultiplier } from '../../constants/models.js';
-import chatGPT from '../../lib/chatgpt/index.js';
-import {
-  asObjectWithSchema as asObjectWithSchemaPrompt,
-  generateList as generateListPrompt,
-  constants as promptConstants,
-} from '../../prompts/index.js';
-import modelService from '../../services/llm-model/index.js';
-
-const { onlyJSON, contentIsTransformationSource, onlyJSONArray } = promptConstants;
-
-// Get the directory of this module
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Load the JSON schema for list results
- * @returns {Promise<Object>} JSON schema for validation
- */
-async function getListSchema() {
-  const schemaPath = path.join(__dirname, 'list-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 getListSchema();
-
-  const responseFormat = {
-    type: 'json_schema',
-    json_schema: {
-      name: 'list_result',
-      schema,
-    },
-  };
-
-  if (typeof llm === 'string') {
-    return {
-      modelName: llm,
-      response_format: responseFormat,
-    };
-  } else {
-    return {
-      ...llm,
-      response_format: responseFormat,
-    };
-  }
-}
-
-const outputTransformPrompt = (result, schema) => {
-  return `${contentIsTransformationSource} ${result}
-
-${asObjectWithSchemaPrompt(schema)}
-
-${onlyJSON}`;
-};
-
-const shouldSkipDefault = ({ result, resultsAll } = {}) => {
-  return resultsAll.includes(result);
-};
-
-const shouldStopDefault = ({ queryCount, startTime } = {}) => {
-  return (
-    queryCount > 5 ||
-    new Date() - startTime >
-      operationTimeoutMultiplier * modelService.getBestPublicModel().requestTimeout
-  );
-};
-
-export const generateList = async function* generateListGenerator(text, options = {}) {
-  const resultsAll = [];
-  const resultsAllMap = {};
-  let isDone = false;
-  const {
-    shouldSkip = shouldSkipDefault,
-    shouldStop = shouldStopDefault,
-    model = 'fastGoodCheap',
-    // eslint-disable-next-line no-unused-vars
-    _schema,
-    ...passThroughOptions
-  } = options;
-
-  const startTime = new Date();
-  let queryCount = 0;
-
-  while (!isDone) {
-    const listPrompt = generateListPrompt(text, {
-      ...options,
-      existing: resultsAll,
-    });
-
-    let resultsNew = [];
-    try {
-      const modelOptions = await createModelOptions(model);
-      // eslint-disable-next-line no-await-in-loop
-      const results = await chatGPT(listPrompt, {
-        modelOptions,
-        ...passThroughOptions,
-      });
-
-      // With structured outputs, response should already be parsed and validated
-      const parsed = typeof results === 'string' ? JSON.parse(results) : results;
-      // Extract items from the object structure
-      const resultArray = parsed?.items || parsed;
-      resultsNew = Array.isArray(resultArray) ? resultArray.filter(Boolean) : [];
-    } catch (error) {
-      if (/The operation was aborted/.test(error.message)) {
-        // eslint-disable-next-line no-console
-        console.error('Generate list [error]: Aborted');
-        resultsNew = []; // continue
-      } else {
-        // eslint-disable-next-line no-console
-        console.error(
-          `Generate list [error]: ${error.message}`,
-          listPrompt.slice(0, 100).replace('\n', '\\n')
-        );
-        isDone = true;
-        break;
-      }
-    }
-
-    const resultsNewUnique = resultsNew.filter((item) => !(item in resultsAllMap));
-
-    queryCount += 1;
-
-    for (const result of resultsNewUnique) {
-      const perResultControlFactors = {
-        result,
-        resultsAll,
-        resultsNew,
-        queryCount,
-        startTime,
-      };
-
-      // eslint-disable-next-line no-await-in-loop
-      if (await shouldStop(perResultControlFactors)) {
-        isDone = true;
-        break;
-      }
-
-      // eslint-disable-next-line no-await-in-loop
-      if (!(await shouldSkip(perResultControlFactors))) {
-        resultsAllMap[result] = true;
-        resultsAll.push(result);
-
-        // debug helper:
-        // console.error(R.sort((a, b) => a.localeCompare(b), resultsAll));
-
-        yield result;
-      }
-    }
-
-    const perQueryControlFactors = {
-      result: undefined,
-      resultsAll: [],
-      resultsNew: [],
-      queryCount,
-      startTime,
-    };
-
-    // eslint-disable-next-line no-await-in-loop
-    if (await shouldStop(perQueryControlFactors)) {
-      isDone = true;
-    }
-  }
-};
-
-export default async function list(prompt, config = {}) {
-  const { llm, schema, ...options } = config;
-  const fullPrompt = `${prompt}\n\n${onlyJSONArray}`;
-
-  const modelOptions = await createModelOptions(llm);
-  const response = await chatGPT(fullPrompt, {
-    modelOptions,
-    ...options,
-  });
-
-  // With structured outputs, response should already be parsed and validated
-  const result = typeof response === 'string' ? JSON.parse(response) : response;
-  // Extract items from the object structure
-  const resultArray = result?.items || result;
-  const items = Array.isArray(resultArray) ? resultArray : [];
-
-  // If schema is provided, transform each item to match the schema
-  if (schema && items.length > 0) {
-    const transformedItems = [];
-    for (const item of items) {
-      const transformPrompt = outputTransformPrompt(item, schema);
-      const transformResponse = await chatGPT(transformPrompt, {
-        modelOptions: {
-          ...llm,
-        },
-        ...options,
-      });
-      try {
-        const transformedItem = JSON.parse(transformResponse);
-        transformedItems.push(transformedItem);
-      } catch {
-        // If transformation fails, keep the original item
-        transformedItems.push(item);
-      }
-    }
-    return transformedItems;
-  }
-
-  return items;
-}

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

@@ -1,67 +0,0 @@
-import fs from 'node:fs/promises';
-import { describe, expect, it, vi } from 'vitest';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-import toObject from '../../verblets/to-object/index.js';
-import list from './index.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const loadSchema = async () => {
-  const file = (await fs.readFile(join(__dirname, '../../json-schemas/cars-test.json'))).toString();
-
-  return toObject(file);
-};
-
-vi.mock('../../lib/chatgpt/index.js', () => ({
-  default: vi.fn().mockImplementation((text) => {
-    if (/Transform/.test(text) && /Model Y/.test(text)) {
-      return '{"make":"Tesla", "model": "Model Y"}';
-    }
-    if (/EV cars/.test(text)) {
-      return '["Tesla Model Y"]';
-    }
-    return 'undefined';
-  }),
-}));
-
-const examples = [
-  {
-    name: 'Basic usage',
-    inputs: { description: '2021 EV cars' },
-    want: { listContains: /Model Y/ },
-  },
-  {
-    name: 'Basic usage with schema',
-    inputs: {
-      description: '2021 EV cars',
-      schema: loadSchema,
-    },
-    want: { listModelContains: /Model Y/ },
-  },
-];
-
-describe('List verblet', () => {
-  examples.forEach((example) => {
-    it(example.name, async () => {
-      let schema;
-      if (example.inputs.schema) {
-        schema = await example.inputs.schema();
-      }
-      const result = await list(example.inputs.description, {
-        shouldStop: ({ queryCount }) => queryCount > 1,
-        schema,
-      });
-
-      if (example.want.listContains) {
-        expect(result.some((item) => example.want.listContains.test(item))).equals(true);
-      }
-
-      if (example.want.listModelContains) {
-        expect(result.some((item) => example.want.listModelContains.test(item.model))).equals(true);
-      }
-    });
-  });
-});

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

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

package/src/chains/list/schema.json

@@ -1,24 +0,0 @@
-{
-  "name": "list",
-  "description": "Generate a list based on the input text, optionally specifying a JSON schema for the subsequent output to conform to",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "name": {
-        "type": "string",
-        "description": "Name or description of the list to be generated"
-      },
-      "options": {
-        "type": "object",
-        "description": "Options for list generation and transformation",
-        "properties": {
-          "jsonSchema": {
-            "type": "object",
-            "description": "The JSONSchema used for transforming list results"
-          }
-        }
-      }
-    },
-    "required": []
-  }
-}

package/src/chains/llm-logger/README.md

@@ -1,366 +0,0 @@
-# Enhanced LLM Logger
-
-Advanced logging system with non-destructive parallel processing, designed for AI/LLM applications that need to enhance logs without modifying original data.
-
-## 🚀 Key Features
-
-### Core Innovations
-- **Fully Parallel Processing**: No coordination overhead - processors run independently
-- **Non-Destructive Enhancement**: Original logs remain unchanged, enhancements stored as attachments
-- **NDJSON Bulk Processing**: Efficient batch processing for LLM interaction
-- **Smart Filtering**: AI metadata controls output without affecting stored data
-- **Ordered Adjustments**: Processor order determines adjustment priority
-
-### Architecture
-- **Ring Buffer**: High-performance circular buffer for log storage
-- **Parallel Processors**: Independent processors with individual read offsets
-- **Attachment System**: JSON-path syntax for non-destructive data enhancement
-- **Lane System**: Multiple output channels with independent filtering
-- **AI Metadata**: Separate metadata layer for AI-specific flags
-
-## 📋 Quick Start
-
-```javascript
-import { createLLMLogger, createConsoleWriter } from './index.js';
-
-// Create logger with processors
-const logger = createLLMLogger({
-  ringBufferSize: 1000,
-  processors: [
-    {
-      processorId: 'sentiment-analyzer',
-      description: 'Analyzes log sentiment',
-      batchSize: 10,
-      async process(ndjsonInput) {
-        // Process NDJSON batch and return bulk adjustments
-        const logs = parseNDJSON(ndjsonInput);
-        return logs.map(log => ({
-          logId: log.id,
-          adjustments: {
-            'analysis.sentiment': analyzeSentiment(log.data),
-            'analysis.confidence': 0.95
-          },
-          aiMeta: {
-            skip: shouldSkip(log),
-            confidence: 0.95
-          }
-        }));
-      }
-    }
-  ],
-  lanes: [
-    {
-      laneId: 'console',
-      writer: createConsoleWriter('[LOG] '),
-      filters: (log) => log.meta.get('level') !== 'debug'
-    }
-  ]
-});
-
-// Use the logger
-logger.info('User logged in');
-logger.error('Database error');
-```
-
-## 🔧 API Reference
-
-### Logger Creation
-
-```javascript
-createLLMLogger(config)
-```
-
-**Config Options:**
-- `ringBufferSize` (number): Ring buffer capacity (default: 5000)
-- `processors` (LogProcessor[]): Array of log processors
-- `lanes` (LogLaneConfig[]): Output lane configurations
-- `flushInterval` (number): Flush interval in ms (default: 1000)
-- `immediateFlush` (boolean): Immediate vs batched flushing (default: false)
-
-### Log Processors
-
-```javascript
-{
-  processorId: 'unique-id',
-  description: 'Human readable description',
-  batchSize: 10,
-  async process(ndjsonInput) {
-    // Return array of BulkAdjustment objects
-    return [{
-      logId: 'log-id',
-      adjustments: {
-        'path.to.field': 'value'
-      },
-      aiMeta: {
-        skip: false,
-        confidence: 0.95
-      }
-    }];
-  }
-}
-```
-
-### Lane Configuration
-
-```javascript
-{
-  laneId: 'unique-lane-id',
-  writer: (logs) => { /* write logs array */ },
-  filters: (log) => { /* return boolean */ }
-}
-```
-
-### Logger Methods
-
-#### Standard Logging
-```javascript
-logger.log(data)
-logger.info(data)
-logger.warn(data)
-logger.error(data)
-logger.debug(data)
-logger.trace(data)
-logger.fatal(data)
-```
-
-#### Enhancement API
-```javascript
-// Attach data to specific log
-logger.attachToLog(logId, 'path.to.field', value)
-
-// Get attachment data
-logger.getLogAttachment(logId, 'path.to.field')
-
-// Mark log as skippable
-logger.markLogSkippable(logId, true)
-```
-
-#### Ring Buffer Access
-```javascript
-logger.ringBuffer.all()        // Get all logs
-logger.ringBuffer.tail(n)      // Get last n logs
-logger.ringBuffer.head(n)      // Get first n logs
-logger.ringBuffer.filter(fn)   // Filter logs
-logger.ringBuffer.clear()      // Clear buffer
-```
-
-#### Utility Methods
-```javascript
-logger.flush()                 // Force flush all lanes
-logger.clear()                 // Clear all data
-logger.getStats()              // Get processing statistics
-logger.getProcessorOffsets()   // Get processor progress
-```
-
-## 🔄 Processing Flow
-
-1. **Log Entry**: Log data enters the system
-2. **Ring Buffer**: Stored in circular buffer with metadata
-3. **Parallel Processing**: Multiple processors work independently
-4. **NDJSON Conversion**: Logs converted to NDJSON for LLM processing
-5. **Bulk Adjustments**: Processors return structured adjustments
-6. **Attachment Application**: Adjustments applied as attachments
-7. **Lane Filtering**: Logs filtered through output lanes
-8. **AI Metadata Filtering**: Skip flags respected during output
-9. **Writer Output**: Final logs sent to configured writers
-
-## 📊 Data Structures
-
-### LogEntry
-```javascript
-{
-  id: 'unique-id',
-  ts: Date,
-  raw: 'original-data',
-  meta: Map,
-  attachments: {}, // Non-destructive enhancements
-  aiMeta: {}      // AI-specific metadata (not output)
-}
-```
-
-### BulkAdjustment
-```javascript
-{
-  logId: 'target-log-id',
-  adjustments: {
-    'path.to.field': 'value',
-    'nested.object': { key: 'value' }
-  },
-  aiMeta: {
-    skip: false,
-    confidence: 0.95,
-    // ... other AI metadata
-  }
-}
-```
-
-### NDJSON Format
-```
-{"id":"log-1","ts":"2024-01-01T00:00:00Z","level":"info","data":"message","attachments":{}}
-{"id":"log-2","ts":"2024-01-01T00:00:01Z","level":"error","data":"error","attachments":{}}
-```
-
-## 🎯 Use Cases
-
-### AI Log Analysis
-```javascript
-const aiProcessor = {
-  processorId: 'ai-analyzer',
-  description: 'AI-powered log analysis',
-  batchSize: 20,
-  async process(ndjsonInput) {
-    const analysis = await callLLM(ndjsonInput);
-    return analysis.map(item => ({
-      logId: item.logId,
-      adjustments: {
-        'ai.category': item.category,
-        'ai.severity': item.severity,
-        'ai.suggestions': item.suggestions
-      },
-      aiMeta: {
-        skip: item.severity === 'low',
-        confidence: item.confidence
-      }
-    }));
-  }
-};
-```
-
-### Multi-Stage Processing
-```javascript
-const processors = [
-  sentimentProcessor,    // Order 0: First to process
-  categoryProcessor,     // Order 1: Sees sentiment results
-  priorityProcessor      // Order 2: Sees all previous results
-];
-```
-
-### Conditional Output
-```javascript
-const lanes = [
-  {
-    laneId: 'all-logs',
-    writer: fileWriter('all.log'),
-    filters: () => true
-  },
-  {
-    laneId: 'errors-only',
-    writer: alertWriter,
-    filters: (log) => log.meta.get('level') === 'error'
-  },
-  {
-    laneId: 'high-confidence',
-    writer: analyticsWriter,
-    filters: (log) => log.attachments?.ai?.confidence > 0.8
-  }
-];
-```
-
-## 🔍 Monitoring & Debugging
-
-### Statistics
-```javascript
-const stats = logger.getStats();
-console.log('Ring buffer usage:', stats.writeIndex, '/', stats.maxSize);
-console.log('Processors:', stats.processors);
-```
-
-### Processor Progress
-```javascript
-const offsets = logger.getProcessorOffsets();
-for (const [processorId, offset] of offsets) {
-  console.log(`${processorId}: processed up to offset ${offset}`);
-}
-```
-
-### Log Inspection
-```javascript
-const recentLogs = logger.ringBuffer.tail(10);
-recentLogs.forEach(log => {
-  console.log('Original:', log.raw);
-  console.log('Enhanced:', log.attachments);
-  console.log('AI Meta:', log.aiMeta);
-});
-```
-
-## ⚡ Performance Characteristics
-
-- **Parallel Processing**: No blocking between processors
-- **Ring Buffer**: O(1) write operations
-- **Batch Processing**: Configurable batch sizes for efficiency
-- **Memory Bounded**: Fixed memory usage via ring buffer
-- **Non-Blocking**: Async processing doesn't block logging
-
-## 🔧 Configuration Examples
-
-### High-Throughput Setup
-```javascript
-const logger = createLLMLogger({
-  ringBufferSize: 10000,
-  flushInterval: 100,
-  processors: processors.map(p => ({
-    ...p,
-    batchSize: 50
-  }))
-});
-```
-
-### Real-Time Setup
-```javascript
-const logger = createLLMLogger({
-  immediateFlush: true,
-  processors: processors.map(p => ({
-    ...p,
-    batchSize: 1
-  }))
-});
-```
-
-### Development Setup
-```javascript
-const logger = createLLMLogger({
-  ringBufferSize: 100,
-  immediateFlush: true,
-  lanes: [{
-    laneId: 'console',
-    writer: createConsoleWriter('[DEV] ')
-  }]
-});
-```
-
-## 🚨 Error Handling
-
-Processors handle errors gracefully:
-- Failed processors retry after delay
-- Other processors continue unaffected
-- Original logs always preserved
-- Error logs available in statistics
-
-## 📈 Migration Guide
-
-### From Basic Logger
-```javascript
-// Before
-const logger = createBasicLogger();
-logger.info('message');
-
-// After
-const logger = createLLMLogger({
-  lanes: [{ laneId: 'console', writer: createConsoleWriter() }]
-});
-logger.info('message');
-```
-
-### Adding Processors
-```javascript
-// Add processors incrementally
-const logger = createLLMLogger({
-  // ... existing config
-  processors: [
-    ...existingProcessors,
-    newProcessor
-  ]
-});
-```
-
-This enhanced logger provides a powerful foundation for AI-driven log processing while maintaining compatibility with existing logging patterns.