@far-world-labs/verblets 0.1.1 → 0.1.3

package/.cursor/launch.json

@@ -0,0 +1,30 @@
+{
+    "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

@@ -0,0 +1,20 @@
+{
+    "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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,120 @@
+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 ""
+          echo "This PR is now ready for squash and merge."
+
+  release:
+    name: 🚀 Release
+    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: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npx release-it --ci

package/.prettierrc

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

package/.release-it.json

@@ -4,6 +4,9 @@
     "tagName": "v${version}"
   },
   "npm": {
-    "publish": false
+    "publish": true
+  },
+  "github": {
+    "release": true
   }
 }

package/.vscode/launch.json

@@ -0,0 +1,31 @@
+{
+    "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

@@ -0,0 +1,220 @@
+# 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. 

package/DEVELOPING.md

@@ -0,0 +1,105 @@
+# Developing Verblets
+
+This document explains the development workflow and testing strategy for the Verblets library.
+
+## Testing Strategy
+
+The Verblets library uses a dual testing approach with two types of test files:
+
+### 1. Spec Files (`*.spec.js`)
+- **Purpose**: Deterministic unit tests with mocked LLM responses
+- **Reliability**: Should always pass consistently
+- **LLM Usage**: Uses mocked responses, no actual API calls
+- **Caching**: Uses in-memory `NullRedisClient` or local mocking (no Redis required)
+- **Speed**: Fast execution
+- **Use Case**: CI/CD, development validation, regression testing
+
+### 2. Example Files (`*.examples.js`)
+- **Purpose**: Non-deterministic integration tests with real LLM calls
+- **Reliability**: May fail due to LLM response variability
+- **LLM Usage**: Makes actual API calls to language models
+- **Caching**: Uses Redis for response caching (when available)
+- **Speed**: Slower due to network calls (mitigated by caching)
+- **Use Case**: Manual testing, demonstrating real-world usage, validating LLM integration
+
+## Environment Configuration
+
+### Spec Tests
+```bash
+npm test                    # Runs spec tests with mocked responses
+```
+
+### Example Tests
+```bash
+npm run examples                # Runs example tests with real LLM calls
+EXAMPLES=true npm run examples  # Automatically set, enables Redis caching
+```
+
+### Caching Control
+```bash
+# Disable caching for all LLM calls (forces fresh API calls)
+DISABLE_CACHE=true npm run examples
+
+# Enable caching (default behavior when Redis is available)
+npm run examples
+```
+
+## Caching System
+
+### Redis Caching for Examples
+- Example tests use Redis to cache LLM responses based on prompt content
+- Cached responses reduce API costs and improve test speed
+- Falls back to in-memory caching if Redis is unavailable
+
+### Cache Behavior
+- **Cache Hit**: Returns cached response instantly
+- **Cache Miss**: Makes LLM API call and caches the response
+- **TTL**: Cached responses expire based on `cacheTTL` configuration
+- **Fallback**: Gracefully handles Redis connection failures
+
+## Development Workflow
+
+### Adding New Verblets or Chains
+
+When creating a new verblet or chain, you should add both types of tests:
+
+#### 1. Create Spec File (`index.spec.js`)
+```javascript
+import { describe, expect, it } from 'vitest';
+import myVerblet from './index.js';
+
+const examples = [
+  {
+    inputs: { text: 'test input' },
+    want: { result: 'expected output' },
+  },
+];
+
+describe('My Verblet', () => {
+  examples.forEach((example) => {
+    it(example.inputs.text, async () => {
+      const result = await myVerblet(example.inputs.text);
+      expect(result).toStrictEqual(example.want.result);
+    });
+  });
+});
+```
+
+#### 2. Create Example File (`index.examples.js`)
+```javascript
+import { describe, expect, it } from 'vitest';
+import myVerblet from './index.js';
+import { longTestTimeout } from '../../constants/common.js';
+
+describe('My Verblet Examples', () => {
+  it(
+    'processes real input',
+    async () => {
+      const result = await myVerblet('What is the capital of France?');
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(0);
+    },
+    longTestTimeout
+  );
+});
+```