@far-world-labs/verblets 0.2.0 → 0.3.2

package/package.json

@@ -1,25 +1,40 @@
 {
   "name": "@far-world-labs/verblets",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Verblets is a collection of tools for building LLM-powered applications.",
-  "main": "src/index.js",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
   "type": "module",
+  "exports": {
+    ".": {
+      "node": "./dist/index.js",
+      "browser": "./dist/index.browser.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Far-World-Labs/Verblets.git"
   },
   "scripts": {
+    "prepublishOnly": "npm run build",
     "start": "node scripts/runner/index.js",
     "dev": "nodemon --no-warnings scripts/runner/index.js",
     "editor": "node scripts/simple-editor/index.js",
     "--": "npm run script -- generate-verblet foo",
     "script": "./scripts/run.sh",
     "test": "vitest",
-    "clear-test-cache": "node scripts/clear-redis.js",
-    "examples:warn": "source .env && LLM_EXPECT_MODE=info EXAMPLES=true vitest --config .vitest.config.examples.js",
-    "examples": "source .env && LLM_EXPECT_MODE=error EXAMPLES=true ENABLE_LONG_EXAMPLES=false vitest --config .vitest.config.examples.js",
-    "examples:all": "source .env && LLM_EXPECT_MODE=error EXAMPLES=true ENABLE_LONG_EXAMPLES=true vitest --config .vitest.config.examples.js",
-    "examples:fresh": "npm run clear-test-cache && npm run examples:all",
+    "test:browser": "vitest --config vitest.config.browser.js",
+    "examples": "source .env && USE_REDIS_CACHE=true node_modules/.bin/vitest --config vitest.config.examples.js",
+    "examples:browser": "source .env && USE_REDIS_CACHE=true vitest --config vitest.config.browser.examples.js",
+    "arch": "source .env && vitest --config vitest.config.arch.js",
+    "clear-cache": "node scripts/clear-redis.js",
+    "arch:debug": "source .env && ARCH_DEBUG=true vitest --config .vitest.config.arch.js --run",
+    "build": "vite build",
+    "build:watch": "vite build --watch",
     "lint": "eslint 'src/**/*.{js,jsx}'",
     "lint:fix": "eslint 'src/**/*.{js,jsx}' --fix",
     "check:deps": "npx npm-deprecated-check current",
@@ -46,26 +61,29 @@
     "change-case": "^4.1.2",
     "commander": "^11.0.0",
     "compromise": "^14.14.4",
-    "dependency-tree": "^10.0.1",
     "dotenv": "^16.0.3",
+    "fast-xml-parser": "^5.2.5",
+    "glob": "^11.0.3",
     "gpt-tokenizer": "^2.1.2",
     "gpt4-tokenizer": "^1.3.0",
-    "lodash": "^4.17.21",
     "mocha": "^10.2.0",
+    "natural": "^8.1.0",
     "node-fetch": "^3.3.0",
     "node-record-lpcm16": "^1.0.1",
+    "p-limit": "^6.2.0",
     "ramda": "^0.29.0",
     "redis": "^4.6.5",
     "uuid": "^9.0.0",
     "vitest": "^3.1.3",
-    "whisper-node": "^1.1.1",
     "yargs": "^17.7.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.28.0",
     "@stylistic/eslint-plugin": "^4.4.0",
-    "@types/node": "^18.16.3",
+    "@types/node": "^20.19.0",
     "@vitest/ui": "^3.1.3",
+    "dependency-cruiser": "^16.10.3",
+    "dependency-tree": "^10.0.1",
     "eslint": "^9.28.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-import": "^2.31.0",
@@ -75,11 +93,14 @@
     "eslint-plugin-vitest": "^0.5.4",
     "husky": "^8.0.3",
     "install-peerdeps": "^3.0.3",
+    "jsdom": "^26.1.0",
     "lint-staged": "^13.2.2",
     "nodemon": "^3.1.10",
     "npm-deprecated-check": "^1.5.0",
     "prettier": "^2.8.8",
     "release-it": "^19.0.3",
+    "terminal-kit": "^3.1.2",
+    "vite": "^7.0.6",
     "why-is-node-running": "^2.2.2"
   },
   "lint-staged": {

package/.cursor/launch.json

@@ -1,30 +0,0 @@
-{
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Run Regular Tests",
-            "autoAttachChildProcesses": true,
-            "skipFiles": ["<node_internals>/**"],
-            "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
-            "args": ["run", "--config", ".vitest.config.js"],
-            "smartStep": true,
-            "console": "integratedTerminal"
-        },
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Run Example Tests",
-            "autoAttachChildProcesses": true,
-            "skipFiles": ["<node_internals>/**"],
-            "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
-            "args": ["run", "--config", ".vitest.config.examples.js"],
-            "env": {
-                "EXAMPLES": "true"
-            },
-            "smartStep": true,
-            "console": "integratedTerminal"
-        }
-    ]
-} 

package/.cursor/settings.json

@@ -1,20 +0,0 @@
-{
-    "vitest.enable": true,
-    "vitest.configPath": ".vitest.config.examples.js",
-    "vitest.env": {
-        "EXAMPLES": "true"
-    },
-    "testExplorer": {
-        "showOnRun": true,
-        "showOutputOnFailure": true,
-        "configPath": ".vitest.config.examples.js"
-    },
-    "vitest.testExplorer": {
-        "showOutputOnFailure": true,
-        "showOutputOnRun": true,
-        "configPath": ".vitest.config.examples.js"
-    },
-    "vitest.testFiles": ["**/*.examples.js"],
-    "vitest.include": ["src/**/*.examples.js"],
-    "vitest.commandLine": "vitest --config .vitest.config.examples.js"
-} 

package/.github/workflows/branch-protection.yml

@@ -1,22 +0,0 @@
-name: Branch Protection
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-jobs:
-  # Simple gate that waits for essential checks
-  merge-gate:
-    name: 🚪 Merge Gate
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    steps:
-      - name: Wait for essential checks
-        run: |
-          echo "This job serves as a merge gate."
-          echo "Configure branch protection rules in GitHub to require:"
-          echo "- 🔍 Lint Code"
-          echo "- At least one 🧪 Test on Node job"
-          echo "- This 🚪 Merge Gate job"
-          echo ""
-          echo "✅ Merge gate check passed" 

package/.github/workflows/ci.yml

@@ -1,165 +0,0 @@
-name: CI/CD Pipeline
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-env:
-  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-jobs:
-  get-lts-versions:
-    name: 🧱 Get LTS Node Versions
-    runs-on: ubuntu-latest
-    outputs:
-      matrix: ${{ steps.set-matrix.outputs.matrix }}
-    steps:
-      - name: Fetch Node LTS versions
-        id: set-matrix
-        run: |
-          LTS_VERSIONS=$(curl -s https://raw.githubusercontent.com/nodejs/Release/main/schedule.json | \
-            jq -cr 'to_entries | map(select(.value.lts != false and .value.end > (now | strftime("%Y-%m-%d")))) | map(.key)')
-          echo "matrix={\"node-version\": $LTS_VERSIONS}" >> $GITHUB_OUTPUT
-
-  lint:
-    name: 🔍 Lint Code
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-          cache: 'npm'
-          cache-dependency-path: '**/package-lock.json'
-      - run: npm ci
-      - name: Run ESLint
-        run: npm run lint
-
-  test:
-    name: 🧪 Test on Node ${{ matrix.node-version }}
-    needs: get-lts-versions
-    runs-on: ubuntu-latest
-    strategy:
-      matrix: ${{ fromJson(needs.get-lts-versions.outputs.matrix) }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-          cache-dependency-path: '**/package-lock.json'
-      - name: Cache npm global
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: npm-global-${{ runner.os }}-${{ matrix.node-version }}
-      - run: npm ci
-      - name: Run tests
-        run: npm test -- --run
-
-  build:
-    name: 🛠️ Build
-    runs-on: ubuntu-latest
-    needs: [lint, test]
-    steps:
-      - name: Build complete
-        run: |
-          echo "✅ All tests passed across Node.js LTS versions"
-          echo "✅ ESLint checks completed"
-          echo "✅ Library is ready for deployment"
-
-  # Required status check that gates merge operations
-  pr-ready-to-merge:
-    name: ✅ PR Ready to Merge
-    runs-on: ubuntu-latest
-    needs: [lint, test, build]
-    if: github.event_name == 'pull_request'
-    steps:
-      - name: All checks passed
-        run: |
-          echo "🎉 All required checks have passed!"
-          echo "✅ Linting: Passed"
-          echo "✅ Tests: Passed on all LTS Node versions"
-          echo "✅ Build: Successful"
-          echo "ℹ️ Version: Will be checked on merge (publish only if bumped)"
-          echo ""
-          echo "This PR is now ready for squash and merge."
-
-  # Publish to NPM and create git tag - only if version was bumped
-  release:
-    name: 🚀 Publish to NPM
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20.x
-          registry-url: 'https://registry.npmjs.org'
-          cache: 'npm'
-      - run: npm ci
-      
-      - name: Check if version was bumped
-        id: version-check
-        run: |
-          CURRENT_VERSION=$(node -p "require('./package.json').version")
-          PUBLISHED_VERSION=$(npm view @far-world-labs/verblets version 2>/dev/null || echo "0.0.0")
-          
-          echo "📦 Current version in package.json: $CURRENT_VERSION"
-          echo "📦 Published version on npm: $PUBLISHED_VERSION"
-          
-          if [ "$CURRENT_VERSION" = "$PUBLISHED_VERSION" ]; then
-            echo "should-publish=false" >> $GITHUB_OUTPUT
-            echo "ℹ️ No version bump detected - skipping publish"
-          else
-            echo "should-publish=true" >> $GITHUB_OUTPUT
-            echo "✅ Version bump detected: $PUBLISHED_VERSION → $CURRENT_VERSION - will publish"
-          fi
-      
-      - name: Create Git Tag
-        if: steps.version-check.outputs.should-publish == 'true'
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "v$VERSION" -m "Release v$VERSION"
-          git push origin "v$VERSION"
-      
-      - name: Publish to NPM
-        if: steps.version-check.outputs.should-publish == 'true'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          # Version was manually bumped and validated in PR
-          npm publish --access public
-          
-      - name: Create GitHub Release
-        if: steps.version-check.outputs.should-publish == 'true'
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Get version from package.json
-          VERSION=$(node -p "require('./package.json').version")
-          
-          # Create GitHub release
-          gh release create "v$VERSION" \
-            --title "Release v$VERSION" \
-            --notes "Automated release of version $VERSION" \
-            --latest
-      
-      - name: Skip publish
-        if: steps.version-check.outputs.should-publish == 'false'
-        run: |
-          echo "ℹ️ No version bump detected - publish skipped"
-          echo "This merge completed without triggering a release"

package/.husky/pre-commit

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npm run lint

package/.prettierrc

@@ -1,6 +0,0 @@
-{
-  "singleQuote": true,
-  "trailingComma": "es5",
-  "semi": true,
-  "printWidth": 100
-} 

package/.release-it.json

@@ -1,12 +0,0 @@
-{
-  "git": {
-    "commitMessage": "chore: release v${version}",
-    "tagName": "v${version}"
-  },
-  "npm": {
-    "publish": true
-  },
-  "github": {
-    "release": true
-  }
-}

package/.vitest.config.examples.js

@@ -1,12 +0,0 @@
-import { configDefaults, defineConfig } from 'vitest/config'
-import dotenv from 'dotenv'
-
-// Load environment variables from .env file
-dotenv.config()
-
-export default defineConfig({
-  test: {
-    exclude: [...configDefaults.exclude],
-    include: ['src/**/*.examples.js']
-  },
-});

package/.vitest.config.js

@@ -1,8 +0,0 @@
-import { configDefaults, defineConfig } from 'vitest/config'
-
-export default defineConfig({
-  test: {
-    exclude: [...configDefaults.exclude],
-    include: ['**/*.spec.js']
-  },
-});

package/.vscode/launch.json

@@ -1,31 +0,0 @@
-{
-    "version": "0.2.0",
-    "configurations": [
-
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Run Regular Tests",
-            "autoAttachChildProcesses": true,
-            "skipFiles": ["<node_internals>/**"],
-            "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
-            "args": ["run"],
-            "smartStep": true,
-            "console": "integratedTerminal"
-        },
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Run Example Tests",
-            "autoAttachChildProcesses": true,
-            "skipFiles": ["<node_internals>/**"],
-            "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
-            "args": ["run", "--config", ".vitest.config.examples.js"],
-            "env": {
-                "EXAMPLES": "true"
-            },
-            "smartStep": true,
-            "console": "integratedTerminal"
-        }
-    ]
-} 

package/AGENTS.md

@@ -1,220 +0,0 @@
-# Agents Guide
-
-This document explains the internal architecture and development practices for the verblets project. It's intended for AI agents and developers working on the codebase.
-
-## Architecture Overview
-
-The verblets project has two main types of components:
-
-### **Chains** (`src/chains/`)
-LLM orchestrations that combine multiple verblets, other chains, and library utilities to perform complex workflows. Chains handle multi-step reasoning, batch processing, and sophisticated AI operations.
-
-**Examples:**
-- `anonymize` - Multi-step process to identify and replace sensitive information
-- `socratic` - Iterative questioning dialogue using multiple LLM calls
-- `bulk-map` - Parallel processing of large datasets with retry logic
-- `summary-map` - Self-resizing hash table with AI-powered summarization
-
-**Characteristics:**
-- Use multiple LLM calls or orchestrate other modules
-- Handle complex workflows and state management
-- Often include retry logic and error handling
-- May process data in chunks or batches
-
-### **Verblets** (`src/verblets/`)
-Single LLM calls with carefully crafted prompts and prompt-supporting functions. Each verblet performs one specific AI task with high reliability and constrained outputs.
-
-**Examples:**
-- `bool` - Extract true/false decisions from natural language
-- `enum` - Map text to predefined options with high accuracy
-- `intent` - Parse user intent and extract structured parameters
-- `to-object` - Convert descriptions to structured JSON objects
-
-**Characteristics:**
-- Single LLM call per operation
-- Substantial, optimized prompts with prompt variables
-- Constrained outputs to prevent hallucination
-- High reliability for specific tasks
-
-### **Library Utilities** (`src/lib/`)
-Supporting utilities that don't use LLMs directly. These provide infrastructure, data processing, and reusable functions that support both chains and verblets.
-
-**Examples:**
-- `chatgpt` - OpenAI API wrapper with error handling
-- `prompt-cache` - Caching layer for LLM responses
-- `retry` - Robust retry logic for async operations
-- `parse-js-parts` - JavaScript AST parsing utilities
-- `parse-llm-list` - Parse JSON arrays or CSV from LLM responses with filtering
-
-**Characteristics:**
-- No direct LLM usage
-- Pure functions or utility classes
-- Infrastructure and data processing
-- Reusable across verblets and chains
-
-## Module Structure
-
-Every module (chain, verblet, or lib utility) follows a consistent structure:
-
-```
-module-name/
-├── index.js          # Main implementation
-├── index.spec.js     # Deterministic tests with mocks
-├── index.examples.js # Non-deterministic tests with real LLM calls
-└── README.md         # Documentation with compelling examples and docs for the JS API
-```
-
-### Required Files
-
-#### `index.js`
-The main implementation. Should export a default function or class.
-
-#### `index.spec.js`
-Deterministic tests using table-driven examples. These tests:
-- Mock LLM interfaces (chatGPT, etc.)
-- Use predictable inputs and expected outputs
-- Run quickly and reliably in CI/CD
-- Follow the `examples` array pattern
-
-**Example:** See [`src/verblets/bool/index.spec.js`](src/verblets/bool/index.spec.js) for the table-driven testing pattern.
-
-#### `index.examples.js`
-Non-deterministic tests using real LLM calls. These tests:
-- Use actual API calls (require API keys)
-- Verify behavior with LLM assertion chains
-- Use the `expect` chain or verblet for intelligent assertions
-- Include `longTestTimeout` for API call delays
-
-**Example:** See [`src/verblets/bool/index.examples.js`](src/verblets/bool/index.examples.js) for LLM assertion usage.
-
-#### `README.md`
-Documentation with at least one compelling example that demonstrates how LLM programming changes what's possible. Should show real-world value and be accessible to developers.
-
-**Example:** See [`src/chains/socratic/README.md`](src/chains/socratic/README.md) for compelling documentation.
-
-## Testing Strategy
-
-### Two-Tier Testing Approach
-
-1. **Spec Tests** (`*.spec.js`)
-   - Fast, deterministic, mocked
-   - Table-driven with `examples` arrays
-   - Run with `npm run test`
-   - Essential for CI/CD and development
-
-2. **Example Tests** (`*.examples.js`)
-   - Slow, non-deterministic, real LLM calls
-  - LLM assertions using `expect` chain or verblet
-   - Run with `npm run examples` (requires API keys--not possible as an agent)
-   - Validate real-world behavior
-
-### Testing Patterns
-
-#### Table-Driven Examples
-All tests use a consistent `examples` array structure. See [`src/verblets/enum/index.spec.js`](src/verblets/enum/index.spec.js) for the standard pattern.
-
-#### LLM Assertion Chains
-For example tests, use the `expect` chain or verblet for assertions that blind assertions cannot handle:
-
-**Chain Usage:** See [`src/chains/expect/index.examples.js`](src/chains/expect/index.examples.js) for enhanced LLM assertions.
-
-**Verblet Usage:** See [`src/verblets/expect/index.examples.js`](src/verblets/expect/index.examples.js) for simple LLM assertions.
-
-**Real-World Usage:** See [`src/chains/intersections/index.examples.js`](src/chains/intersections/index.examples.js) for LLM assertions in practice.
-
-**Key Benefits of LLM Assertions:**
-- Verify semantic meaning, not just structure
-- Check content quality and appropriateness
-- Validate business logic and context understanding
-- Handle cases where traditional assertions are insufficient
-
-## Development Commands
-
-### Core Commands
-- `npm run test` - Run deterministic spec tests
-- `npm run lint` - Check code style
-- `npm run lint:fix` - Auto-fix linting issues
-
-### Example Commands (Require API Keys)
-- `npm run examples` - Run non-deterministic example tests
-- `npm run examples:warn` - Run examples with warning-level LLM expectations
-
-**Note for Agents:** The `npm run examples` command won't work for AI agents since it requires API keys that agents don't have access to.
-
-## Export Strategy
-
-### Internal Organization
-Internally, we maintain clear distinctions between chains, verblets, and lib utilities for architectural clarity and development organization.
-
-### Public API
-In the top-level README and `src/index.js`, we export everything as "verblets" to provide a unified, simple API for users. See [`src/index.js`](src/index.js) for the export structure.
-
-This approach:
-- Simplifies the user experience
-- Maintains internal architectural clarity
-- Allows for easy refactoring and organization
-- Provides a consistent mental model for users
-
-## Documentation Standards
-
-### README Requirements
-Every module README must include:
-
-1. **Clear description** of what the module does
-2. **At least one compelling example** showing real-world value
-3. **Demonstration of LLM capabilities** that would be difficult/impossible with traditional programming
-4. **Accessible code examples** that developers can immediately understand and use
-
-### Example Quality
-Examples should demonstrate transformative capabilities. See [`src/verblets/bool/README.md`](src/verblets/bool/README.md) and [`src/verblets/enum/README.md`](src/verblets/enum/README.md) for examples that show LLM understanding of context and nuance.
-
-### Linking Strategy
-- Most modules should be linked from the top-level README
-- Organize by functional categories (primitives, lists, content, etc.)
-- Prioritize modules that best demonstrate LLM capabilities
-- Include brief descriptions that highlight unique value
-
-## Development Environment
-
-### .cursor Directory
-The `.cursor` directory contains IDE-specific configuration and rules for the Cursor editor. This should include:
-- Code style preferences
-- AI assistant behavior guidelines
-- Project-specific linting rules
-- Development workflow configurations
-
-**Note:** The `.cursor` directory should have comprehensive rules to guide development practices, though these may not be fully implemented yet.
-
-## Best Practices
-
-### For Chains
-- Use clear step-by-step orchestration
-- Include robust error handling and retry logic
-- Document the workflow in comments
-- Consider chunking for large datasets
-- Provide progress feedback for long operations
-
-### For Verblets
-- Craft prompts carefully for reliability
-- Constrain outputs to prevent hallucination
-- Use JSON schemas for structured outputs
-- Test edge cases thoroughly
-- Optimize for single-call efficiency
-
-### For Library Utilities
-- Keep functions pure when possible
-- Provide comprehensive error handling
-- Include detailed JSDoc comments
-- Design for reusability across modules
-- Follow standard JavaScript patterns
-
-### Testing Guidelines
-- Write spec tests first (TDD approach)
-- Mock all external dependencies in spec tests
-- Use realistic but simple examples
-- Make example tests robust with LLM assertions
-- Include edge cases and error conditions
-- Test both success and failure paths
-- Use LLM assertions for content that traditional assertions cannot verify
-
-This architecture enables building sophisticated AI-powered applications while maintaining code quality, testability, and developer experience.