@far-world-labs/verblets 0.2.0 → 0.4.0

package/src/chains/dismantle/index.js

@@ -1,303 +0,0 @@
-import { v4 as uuid } from 'uuid';
-
-import chatGPT from '../../lib/chatgpt/index.js';
-import { outputSuccinctNames, constants as promptConstants } from '../../prompts/index.js';
-import modelService from '../../services/llm-model/index.js';
-import toObject from '../../verblets/to-object/index.js';
-
-const { onlyJSONStringArray } = promptConstants;
-
-const subComponentsPrompt = (component, thing, fixes = '') => {
-  let focus = '';
-  if (component !== thing) {
-    focus = `"${component}" within "${thing}"`;
-  } else {
-    focus = thing;
-  }
-
-  return `
-${onlyJSONStringArray}
-
-Exhaustively enumerate all physical and logical subcomponents of ${focus}, including containers or abstract components.
-
-Apply the specifics listed here when dealing with component or entity:
- - ${outputSuccinctNames()}
- - If some components are subcomponents of others in the list, don't include them.
- - The output must not include "${thing}" or "${component}" in the list.
- - Only subcomponents, no accessories.
-${fixes}
-
-${onlyJSONStringArray}
-`;
-};
-
-const componentOptionsPrompt = (component, thing, fixes = '') => {
-  let focus = '';
-  if (component !== thing) {
-    focus = `Considering "${component}" as a separate component within "${thing}" entity`;
-  } else {
-    focus = `Considering "${component}"`;
-  }
-  return `
-${onlyJSONStringArray}
-
-${focus}, list specific variants for this component. Only provide known variants, don't speculate. Output an empty list if you must.
-
-Apply the specifics listed here when dealing with component or entity:
- - ${outputSuccinctNames()}
- - Do not list subcomponents, that's not what this is about.
-${fixes}
-
-${onlyJSONStringArray}
-`;
-};
-
-const defaultMatch = () => false;
-
-const deepClone = (obj) => JSON.parse(JSON.stringify(obj));
-
-const search = (node, { match = defaultMatch, matches = [] } = {}) => {
-  if (match(node)) {
-    matches.push(node);
-  }
-
-  if (!node.children) {
-    return matches.length > 0 ? matches : undefined;
-  }
-
-  for (const child of node.children) {
-    search(child, { match, matches });
-  }
-
-  return matches.length > 0 ? matches : undefined;
-};
-
-const defaultDecompose = async ({
-  name,
-  focus,
-  rootName,
-  fixes,
-  model = modelService.getBestPublicModel(),
-} = {}) => {
-  const focusFormatted = focus ? `: ${focus}` : '';
-
-  const promptCreated = subComponentsPrompt(`${name}${focusFormatted}`, rootName, fixes);
-  const budget = model.budgetTokens(promptCreated);
-  return toObject(
-    await chatGPT(promptCreated, {
-      modelOptions: {
-        maxTokens: budget.completion,
-        frequencyPenalty: 0.7,
-        temperature: 0.7,
-      },
-    })
-  );
-};
-
-const defaultEnhance = async ({
-  name,
-  rootName,
-  fixes,
-  model = modelService.getBestPublicModel(),
-} = {}) => {
-  const promptCreated = componentOptionsPrompt(name, rootName, fixes);
-  const budget = model.budgetTokens(promptCreated);
-  const options = toObject(
-    await chatGPT(promptCreated, {
-      maxTokens: budget.completion,
-      frequencyPenalty: 0.5,
-      temperature: 0.3,
-    })
-  );
-
-  return {
-    name,
-    options,
-    topOptionName: options?.[0],
-  };
-};
-
-const makeNode = async ({
-  node = {},
-  name: nameInitial,
-  rootName,
-  decompose = defaultDecompose,
-  enhance = defaultEnhance,
-  makeId = uuid,
-  enhanceFixes,
-  decomposeFixes,
-} = {}) => {
-  const name = nameInitial ?? rootName;
-
-  let nodeNew = node;
-
-  if (!node.isEnhanced) {
-    nodeNew = await enhance({
-      name,
-      rootName,
-      fixes: enhanceFixes,
-    });
-    nodeNew.isEnhanced = true;
-
-    const focus = node.options?.[0];
-
-    const childNames = await decompose({
-      name,
-      focus,
-      rootName,
-      fixes: decomposeFixes,
-    });
-    nodeNew.children = childNames.map((childName) => ({
-      id: makeId(),
-      name: childName,
-    }));
-  }
-
-  if (!node.id) {
-    nodeNew.id = makeId();
-  }
-
-  return {
-    ...node,
-    ...nodeNew,
-  };
-};
-
-const makeSubtree = async ({
-  name,
-  rootName,
-  tree: treeInitial,
-  depth = 0,
-  decompose,
-  enhance,
-  enhanceFixes,
-  decomposeFixes,
-  makeId,
-} = {}) => {
-  let tree = { ...(treeInitial ?? {}) };
-
-  const nodeNew = await makeNode({
-    node: tree,
-    name: name ?? tree.name,
-    rootName,
-    enhance,
-    decompose,
-    makeId,
-    enhanceFixes,
-    decomposeFixes,
-  });
-
-  tree = {
-    ...tree,
-    ...nodeNew,
-  };
-
-  if (depth <= 0) {
-    return tree;
-  }
-
-  const children = [];
-  for (const child of tree.children) {
-    // eslint-disable-next-line no-await-in-loop
-    const subtree = await makeSubtree({
-      tree: child,
-      rootName,
-      decompose,
-      enhance,
-      depth: depth - 1,
-      makeId,
-      enhanceFixes,
-      decomposeFixes,
-    });
-
-    children.push(subtree);
-  }
-
-  tree.children = children;
-
-  return tree;
-};
-
-export const simplifyTree = (node) => {
-  if (!node.children || node.children.length === 0) {
-    const parts = (node.children ?? []).map((child) => child.name);
-    return {
-      id: node.id,
-      name: `${node.name}${node.options?.[0] ? `: ${node.options?.[0]}` : ''}`,
-      parts: parts.length ? parts : undefined,
-    };
-  }
-
-  const parts = node.children.map((child) => simplifyTree(child));
-  return {
-    id: node.id,
-    name: `${node.name}${node.options?.[0] ? `: ${node.options?.[0]}` : ''}`,
-    parts: parts.length ? parts : undefined,
-  };
-};
-
-class ChainTree {
-  constructor(name, { decompose, enhance, makeId, enhanceFixes, decomposeFixes } = {}) {
-    this.rootName = name;
-    this.tree = {};
-    this.decompose = decompose;
-    this.enhance = enhance;
-    this.makeId = makeId;
-    this.enhanceFixes = enhanceFixes;
-    this.decomposeFixes = decomposeFixes;
-  }
-
-  getTree() {
-    return this.tree;
-  }
-
-  async attachSubtree({ find, depth }) {
-    const clonedTree = deepClone(this.tree);
-
-    // Find the node to attach the subtree to in the cloned tree
-    const targetNodes = search(clonedTree, { match: find });
-
-    if (!targetNodes || targetNodes.length !== 1) {
-      return undefined;
-    }
-
-    const targetNode = targetNodes[0];
-
-    const newNode = await makeSubtree({
-      ...this,
-      rootName: clonedTree.name,
-      tree: targetNode,
-      depth,
-    });
-
-    Object.assign(targetNode, newNode);
-
-    const nodeStripped = {
-      ...newNode,
-      children: newNode.children.map((child) => ({
-        ...child,
-        children: [],
-      })),
-    };
-
-    this.tree = clonedTree;
-
-    return nodeStripped;
-  }
-
-  async makeSubtree(config = {}) {
-    this.tree = await makeSubtree({
-      ...this,
-      rootName: this.tree.name || this.rootName,
-      ...config,
-    });
-
-    return this.tree;
-  }
-}
-
-export const dismantle = (text, options) => {
-  return new ChainTree(text, options);
-};
-
-export default ChainTree;

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

@@ -1,32 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-
-import { dismantle } from './index.js';
-
-vi.mock('../../lib/chatgpt/index.js', () => ({
-  default: vi.fn().mockImplementation((text) => {
-    if (/prompt text to match/.test(text)) {
-      return 'True';
-    }
-    return 'undefined';
-  }),
-}));
-
-const examples = [
-  {
-    name: 'Basic usage',
-    inputs: { text: 'test' },
-    want: { result: {} },
-  },
-];
-
-describe('Dismantle chain', () => {
-  examples.forEach((example) => {
-    it(example.name, async () => {
-      const result = await dismantle(example.inputs.text);
-
-      if (example.want.typeOfResult) {
-        expect(JSON.stringify(result.tree)).toStrictEqual(JSON.stringify(example.want.result));
-      }
-    });
-  });
-});

package/src/chains/expect/README.md

@@ -1,171 +0,0 @@
-# LLM Expect Chain
-
-Advanced intelligent assertions with debugging features, environment variable modes, and structured results. This chain provides enhanced functionality beyond the basic [expect verblet](../../verblets/expect/).
-
-## Why Use the Chain?
-
-While the verblet provides simple pass/fail assertions, the chain offers:
-
-- **Advanced Debugging**: Automatic code context analysis and intelligent advice
-- **Environment Modes**: Different behaviors for development, testing, and CI
-- **Structured Results**: Detailed information about assertions and failures
-- **Stack Trace Integration**: Automatic detection of calling file and line
-
-## Environment Variable Modes
-
-Control behavior with the `LLM_EXPECT_MODE` environment variable:
-
-### `none` (default)
-Silent mode - returns structured results without throwing or logging
-```bash
-export LLM_EXPECT_MODE=none
-```
-
-### `info` 
-Development mode - logs failures with context and advice to console
-```bash
-export LLM_EXPECT_MODE=info
-```
-
-### `error`
-CI/Testing mode - throws detailed errors on assertion failures
-```bash
-export LLM_EXPECT_MODE=error
-```
-
-## API Reference
-
-### Enhanced API: `expect(actual, expected?, constraint?)`
-
-Returns a tuple `[passed, details]` with structured results:
-
-```javascript
-import { expect } from './index.js';
-
-const [passed, details] = await expect(
-  actualValue,
-  "Does this meet our quality standards?"
-);
-
-console.log(details);
-/* Returns:
-{
-  passed: false,
-  advice: "ISSUE: Content lacks specific examples...",
-  file: "/path/to/test.js",
-  line: 42
-}
-*/
-```
-
-### Simple API: `expect(actual, expected?, constraint?)`
-
-Backward compatible with the verblet - returns boolean:
-
-```javascript
-import expect from './index.js';
-
-const result = await expect("hello", "hello");
-// Returns: true
-```
-
-## Real-World Use Cases
-
-### Content Quality Assurance with Debugging
-
-```javascript
-import { expect } from './index.js';
-
-// Set development mode for detailed feedback
-process.env.LLM_EXPECT_MODE = 'info';
-
-const [passed, details] = await expect(
-  generatedCopy,
-  "Is this marketing copy professional, engaging, and free of grammatical errors?"
-);
-
-if (!passed) {
-  console.log(`Failed at ${details.file}:${details.line}`);
-  console.log(details.advice);
-  // ISSUE: Copy contains informal language and lacks call-to-action
-  // FIX: Replace casual phrases with professional alternatives and add clear CTA
-  // CONTEXT: Marketing copy should maintain professional tone while being engaging
-}
-```
-
-## Advanced Features
-
-### Automatic Code Context Analysis
-
-The chain automatically:
-- Detects the calling file and line number
-- Reads 400 lines before and 100 lines after the assertion
-- Provides this context to the LLM for better debugging advice
-
-### Intelligent Advice Generation
-
-Failed assertions generate structured advice:
-- **ISSUE**: Brief description of why the assertion failed
-- **FIX**: Specific actionable steps to resolve the issue  
-- **CONTEXT**: Additional context about the problem and root causes
-
-### Environment-Aware Behavior
-
-Different modes for different environments:
-- **Development**: Rich console output with advice
-- **Testing**: Detailed error throwing for CI/CD
-- **Production**: Silent operation with structured results
-
-## Best Practices
-
-### **Write Specific Constraints**
-```javascript
-// ❌ Vague
-await expect(text, "Is this good?");
-
-// ✅ Specific  
-await expect(text, "Is this text grammatically correct, under 100 words, and written in a professional tone?");
-```
-
-### **Use Structured Results**
-```javascript
-const [passed, details] = await expect(content, constraint);
-
-// Access rich debugging information
-console.log('File:', details.file);
-console.log('Line:', details.line);
-console.log('Advice:', details.advice);
-```
-
-### **Combine with Traditional Tests**
-```javascript
-// Traditional assertion for structure
-expect(response).toHaveProperty('status');
-expect(response.status).toBe(200);
-
-// LLM assertion for content quality
-const [passed] = await expect(
-  response.message,
-  "Is this error message helpful and user-friendly?"
-);
-```
-
-### Environment Modes
-
-```bash
-# Silent operation (default)
-export LLM_EXPECT_MODE=none
-
-# Log debugging advice on failures
-export LLM_EXPECT_MODE=info
-
-# Throw with detailed debugging advice
-export LLM_EXPECT_MODE=error
-```
-
-## Best Practices
-
-- **Be specific**: Use clear, detailed constraints
-- **Test qualitatively**: Verify qualitative details with a clear yes/no answer
-- **Use robust constraints**: Write criteria to pass under a wide range of input hallucinations. Assert cases that classical software can't. Tune the level of rigorousness to the model performing the eval.
-- **Performance**: Remember this makes an LLM call - use judiciously

package/src/chains/expect/index.examples.js

@@ -1,146 +0,0 @@
-import { describe, expect, it, beforeAll, afterAll } from 'vitest';
-
-import { expect as aiExpect } from './index.js';
-import { longTestTimeout } from '../../constants/common.js';
-
-const examples = [
-  {
-    inputs: {
-      actual: 'Hello world!',
-      constraint: 'Is this a greeting?',
-    },
-    want: { result: true },
-  },
-  {
-    inputs: {
-      actual: 'Goodbye cruel world',
-      constraint: 'Is this a greeting?',
-    },
-    want: { result: false },
-  },
-  {
-    inputs: {
-      actual: 'hello',
-      expected: 'hello',
-    },
-    want: { result: true },
-  },
-  {
-    inputs: {
-      actual: 'hello',
-      expected: 'goodbye',
-    },
-    want: { result: false },
-  },
-  {
-    inputs: {
-      actual: 'This is a well-written, professional email with proper grammar and clear intent.',
-      constraint: 'Is this text professional and grammatically correct?',
-    },
-    want: { result: true },
-  },
-  {
-    inputs: {
-      actual: { name: 'John Doe', age: 30, city: 'New York' },
-      constraint: 'Does this person data look realistic?',
-    },
-    want: { result: true },
-  },
-];
-
-describe('LLM Expect Chain', () => {
-  // Set environment mode to 'none' for all tests to avoid throwing
-  const originalMode = process.env.LLM_EXPECT_MODE;
-
-  beforeAll(() => {
-    process.env.LLM_EXPECT_MODE = 'none';
-  });
-
-  afterAll(() => {
-    if (originalMode !== undefined) {
-      process.env.LLM_EXPECT_MODE = originalMode;
-    } else {
-      delete process.env.LLM_EXPECT_MODE;
-    }
-  });
-
-  examples.forEach((example) => {
-    const description = example.inputs.constraint
-      ? `${JSON.stringify(example.inputs.actual).slice(0, 30)}... - ${example.inputs.constraint}`
-      : `${JSON.stringify(example.inputs.actual)} === ${JSON.stringify(example.inputs.expected)}`;
-
-    it(
-      description,
-      async () => {
-        const [result, details] = await aiExpect(
-          example.inputs.actual,
-          example.inputs.expected,
-          example.inputs.constraint
-        );
-
-        expect(result).toBe(example.want.result);
-        expect(details).toHaveProperty('passed', example.want.result);
-        expect(details).toHaveProperty('file');
-        expect(details).toHaveProperty('line');
-        expect(typeof details.line).toBe('number');
-      },
-      longTestTimeout
-    );
-  });
-
-  it(
-    'should provide detailed debugging information on failure',
-    async () => {
-      const [result, details] = await aiExpect(
-        'This is clearly wrong content',
-        undefined,
-        'Is this a professional business email?'
-      );
-
-      expect(result).toBe(false);
-      expect(details.passed).toBe(false);
-      expect(details.file).toBeDefined();
-      expect(details.line).toBeGreaterThan(0);
-
-      // In none mode, advice should be null for failures
-      expect(details.advice).toBeNull();
-    },
-    longTestTimeout
-  );
-
-  it(
-    'should handle complex business logic validation',
-    async () => {
-      const businessRecommendation =
-        'Increase marketing budget by 20% for Q4 to boost holiday sales and target demographics aged 25-45 through social media campaigns';
-
-      const [result, details] = await aiExpect(
-        businessRecommendation,
-        undefined,
-        'Is this recommendation specific, actionable, and includes measurable targets?'
-      );
-
-      expect(result).toBe(true);
-      expect(details.passed).toBe(true);
-      expect(details.file).toBeDefined();
-    },
-    longTestTimeout
-  );
-
-  it(
-    'should validate creative content quality',
-    async () => {
-      const storyOpening =
-        'Once upon a time, in a land far away, there lived a brave knight who embarked on a quest to save the kingdom from an ancient curse that had plagued the realm for centuries.';
-
-      const [result] = await aiExpect(
-        storyOpening,
-        undefined,
-        'Is this story opening engaging, sets up clear conflict, and follows good narrative structure?'
-      );
-
-      expect(result).toBe(true);
-    },
-    longTestTimeout
-  );
-});