@far-world-labs/verblets 0.2.0 → 0.3.2

package/README.md

@@ -1,253 +1,126 @@
 # Verblets
 
-Verblets is a library of AI-powered utilities that transform natural language and structured data into reliable, structured outputs. Each function uses language model intelligence while constraining outputs to limit hallucination and ensure software reliability.
+Verblets /ˈvaɪb.ləts/ is a utility library of AI-powered functions for creating new kinds of applications. Verblets are composable and reusable while constraining outputs to ensure software reliability. Many of the API interfaces are familiar to developers but support intelligent operations in ways classical analogues do not, sometimes via complex algorithms that have surprising results.
+
+Instead of mimicking humans in order to automate tasks, an AI standard library *extends* people in *new* ways via intelligent software applications that are built on those utilities. Top-down AI approaches to automate people lead to forgetful, error-prone NPC-like replicas that can't be shaped the way software can. By contrast, AI-based software tools lead to new roles and new ways of working together for us humans.
+
+Why the name? Verblets are *verbally* based: they're LLM-powered; and you can think of functions as verbs.
 
 ## Repository Guide
 
 ### Quick Links
 
-- [Chains](./src/chains/) - AI-powered workflows and operations
-- [Verblets](./src/verblets/) - Core AI utility functions
+- [Chains](./src/chains/) - Prompt chains and algorithms based on LLMs
+- [Verblets](./src/verblets/) - Core AI utility functions. At most a single LLM call, no prompt chains. 
 - [Library Helpers](./src/lib/) - Utility functions and wrappers
 - [Prompts](./src/prompts/) - Reusable prompt templates
 - [JSON Schemas](./src/json-schemas/) - Data validation schemas
 
-## Verblets
+## Utilities
 
 ### Primitives
 
 Primitive verblets extract basic data types from natural language with high reliability. They constrain LLM outputs to prevent hallucination while handling the complexity of human expression.
 
-- [bool](./src/verblets/bool) - interpret text as true/false decisions
-- [enum](./src/verblets/enum) - map text to predefined options
-- [number](./src/verblets/number) - extract numeric values from text
-- [number-with-units](./src/verblets/number-with-units) - parse numbers with units and conversions
-- [date](./src/chains/date) - return Date objects from natural language prompts
+- [bool](./src/verblets/bool) - Interpret yes/no, true/false, and conditional statements
+- [date](./src/chains/date) - Parse dates from relative expressions, natural language, standard formats, and longer descriptions
+- [enum](./src/verblets/enum) - Convert free-form input to exactly one of several predefined options
+- [number](./src/verblets/number) - Convert a block of text to a single number
+- [number-with-units](./src/verblets/number-with-units) - Parse measurements and convert between unit systems
+
+### Math
+
+Math chains transform values using conceptual reasoning and subjective judgments beyond simple calculations.
+
+- [scale](./src/chains/scale) - Convert qualitative descriptions to numeric values. Uses a specification generator to maintain consistency across invocations.
 
 ### Lists
 
-List operations transform, filter, and organize collections using natural language criteria. They handle both small lists with individual verblets and large datasets with batch processing chains.
-
-- [bulk-map](./src/chains/bulk-map) - process long lists in retryable batches
-- [bulk-reduce](./src/chains/bulk-reduce) - reduce long lists in manageable chunks
-- [bulk-find](./src/chains/bulk-find) - locate the best match in large datasets
-- [bulk-group](./src/chains/bulk-group) - group large datasets efficiently
-- [bulk-filter](./src/chains/bulk-filter) - filter huge lists in batches
-- [intersections](./src/chains/intersections) - find comprehensive intersections for all combinations
-- [list](./src/chains/list) - generate contextual lists from prompts
-- [list-map](./src/verblets/list-map) - transform each item in a list
-- [list-reduce](./src/verblets/list-reduce) - combine list items using custom logic
-- [list-find](./src/verblets/list-find) - pick the single best item from a list
-- [list-filter](./src/verblets/list-filter) - filter lists with natural language criteria
-- [list-group](./src/verblets/list-group) - categorize list items into groups
-- [list-expand](./src/verblets/list-expand) - generate additional similar items
-- [intersection](./src/verblets/intersection) - describe common traits between items
-- [sort](./src/chains/sort) - order lists by any describable criteria
-- [bulk-score](./src/chains/bulk-score) - score lists with calibrated examples
+List operations transform, filter, and organize collections. They handle both individual items and batch processing for datasets larger than a context window. Many list operations support bulk operation with built-in retry. Many have alternative single invocation versions in the verblets directory. Many utilities have list support via specification-generators that maintain continuity, or prompt fragments that adapt single-invcation behavior to list processing.
+
+- [central-tendency](./src/chains/central-tendency) - Find the most representative examples from a collection
+- [detect-patterns](./src/chains/detect-patterns) - Identify repeating structures, sequences, or relationships in data
+- [detect-threshold](./src/chains/detect-threshold) - Find meaningful breakpoints in numeric values, for use in metrics and alerting
+- [entities](./src/chains/entities) - Extract names, places, organizations, and custom entity types
+- [filter](./src/chains/filter) - Keep items matching natural language criteria through parallel batch processing
+- [find](./src/chains/find) - Return the single best match using parallel evaluation with early stopping
+- [glossary](./src/chains/glossary) - Extract key terms and generate definitions from their usage
+- [group](./src/chains/group) - Cluster items by first discovering categories then assigning members
+- [intersections](./src/chains/intersections) - Find overlapping concepts between all item pairs
+- [list](./src/chains/list) - Extract lists from prose, tables, or generate from descriptions
+- [list-expand](./src/verblets/list-expand) - Add similar items matching the pattern of existing ones
+- [map](./src/chains/map) - Transform each item using consistent rules applied in parallel batches
+- [reduce](./src/chains/reduce) - Combine items sequentially, building up a result across batches
+- [score](./src/chains/score) - Rate items on multiple criteria using weighted evaluation
+- [sort](./src/chains/sort) - Order by complex criteria using tournament-style comparisons
+- [tags](./src/chains/tags) - Apply vocabulary-based tags to categorize items
 
 ### Content
 
-Content utilities generate, transform, and analyze text while maintaining structure and meaning. They excel at creative tasks, system analysis, and privacy-aware text processing.
-
-- [anonymize](./src/chains/anonymize) - scrub personal details from text
-- [collect-terms](./src/chains/collect-terms) - extract difficult vocabulary
-- [dismantle](./src/chains/dismantle) - break systems into components
-- [disambiguate](./src/chains/disambiguate) - resolve ambiguous word meanings using context
-- [filter-ambiguous](./src/chains/filter-ambiguous) - find and rank unclear terms for disambiguation
-- [name](./src/verblets/name) - name something from a definition or description
-- [name-similar-to](./src/verblets/name-similar-to) - suggest short names that match a style
-- [questions](./src/chains/questions) - produce clarifying questions
-- [schema-org](./src/verblets/schema-org) - create schema.org objects
-- [socratic](./src/chains/socratic) - explore assumptions using a Socratic dialogue
-- [summary-map](./src/chains/summary-map) - summarize a collection
-- [themes](./src/chains/themes) - identify themes in text
-- [category-samples](./src/chains/category-samples) - generate diverse examples for any category
-- [to-object](./src/verblets/to-object) - convert descriptions to structured objects
-- [veiled-variants](./src/chains/veiled-variants) - rephrase sensitive queries safely
+Content utilities generate, transform, and analyze text while maintaining structure and meaning. They handle creative tasks, system analysis, and privacy-aware text processing.
+
+- [anonymize](./src/chains/anonymize) - Replace names, dates, and identifying details with placeholders
+- [category-samples](./src/chains/category-samples) - Create examples ranging from typical to edge cases
+- [collect-terms](./src/chains/collect-terms) - Find domain-specific or complex vocabulary
+- [commonalities](./src/verblets/commonalities) - Identify what items share conceptually, not just literally
+- [conversation](./src/chains/conversation) - Manage multi-turn dialogues with memory and context tracking
+- [disambiguate](./src/chains/disambiguate) - Determine which meaning of ambiguous terms fits the context
+- [dismantle](./src/chains/dismantle) - Break down systems into parts, subparts, and their connections
+- [document-shrink](./src/chains/document-shrink) - Remove less relevant sections while keeping query-related content
+- [fill-missing](./src/verblets/fill-missing) - Predict likely content for redacted or corrupted sections
+- [filter-ambiguous](./src/chains/filter-ambiguous) - Flag items that need human clarification
+- [join](./src/chains/join) - Connect text fragments by adding transitions and maintaining flow
+- [name](./src/verblets/name) - Parse names handling titles, suffixes, and cultural variations
+- [name-similar-to](./src/verblets/name-similar-to) - Generate names following example patterns
+- [people](./src/chains/people) - Build artificial person profiles with consistent demographics and traits. Useful as LLM roles.
+- [pop-reference](./src/chains/pop-reference) - Match concepts to movies, songs, memes, or cultural touchstones
+- [questions](./src/chains/questions) - Generate follow-up questions that branch from initial inquiry
+- [relations](./src/chains/relations) - Extract relationship tuples from text
+- [schema-org](./src/verblets/schema-org) - Convert unstructured data to schema.org JSON-LD format
+- [socratic](./src/chains/socratic) - Ask questions that reveal hidden assumptions and logic gaps
+- [split](./src/chains/split) - Find topic boundaries in continuous text
+- [summary-map](./src/chains/summary-map) - Build layered summaries for navigating large documents
+- [tag-vocabulary](./src/chains/tag-vocabulary) - Generate and refine tag vocabularies through iterative analysis
+- [themes](./src/chains/themes) - Surface recurring ideas through multi-pass extraction and merging
+- [timeline](./src/chains/timeline) - Order events chronologically from scattered mentions
+- [to-object](./src/chains/to-object) - Extract key-value pairs from natural language descriptions
+- [truncate](./src/chains/truncate) - Remove trailing content after a semantic boundary
+- [veiled-variants](./src/chains/veiled-variants) - Reword queries to avoid triggering content filters
+
 
 ### Utility Operations
 
-Utility operations provide meta-functionality like automatic tool selection, intent parsing, and context compression. They're essential for building intelligent systems that can adapt and scale.
+Utility operations are uncategorized functionality like automatic tool selection, intent parsing, and context compression.
 
-- [auto](./src/verblets/auto) - automatically select the best verblet for a task
-- [expect](./src/verblets/expect) - simple LLM assertions
-- [expect chain](./src/chains/expect) - assert things about data with LLM reasoning
-- [intent](./src/verblets/intent) - extract user intent and structured parameters
-- [sentiment](./src/verblets/sentiment) - detect emotional tone of text
-- [summary-map](./src/chains/summary-map) - store self-resizing hash table values. Useful for fixed-sized contexts.
-- [set-interval](./src/chains/set-interval) - Conversational scheduler
+- [ai-arch-expect](./src/chains/ai-arch-expect) - Validate AI architecture constraints and patterns
+- [auto](./src/verblets/auto) - Match task descriptions to available tools using function calling
+- [expect](./src/verblets/expect) - Check if conditions are met and explain why if not
+- [expect chain](./src/chains/expect) - Validate complex data relationships with detailed failure analysis
+- [intent](./src/verblets/intent) - Extract action and parameters from natural language commands
+- [llm-logger](./src/chains/llm-logger) - Summarize log patterns and detect anomalies across time windows
+- [sentiment](./src/verblets/sentiment) - Classify as positive, negative, or neutral with nuance detection
+- [set-interval](./src/chains/set-interval) - Schedule tasks using natural language time descriptions
 
 ### Codebase
 
-Codebase utilities analyze, test, and improve code quality using AI reasoning. They provide insights that traditional static analysis tools miss by understanding context and intent.
+Codebase utilities analyze, test, and improve code quality using AI reasoning.
 
-- [scan-js](./src/chains/scan-js) - analyze JavaScript code quality
-- [test](./src/chains/test) - run AI-driven software tests
-- [test-advice](./src/chains/test-advice) - get feedback on test coverage
+- [scan-js](./src/chains/scan-js) - Examine JavaScript for patterns, anti-patterns, and potential issues
+- [test](./src/chains/test) - Generate test cases covering happy paths, edge cases, and error conditions
+- [test-advice](./src/chains/test-advice) - Identify untested code paths and suggest test scenarios
 
 ## Library Helpers
 
-- [chatgpt](./src/lib/chatgpt) - OpenAI ChatGPT wrapper
-- [prompt-cache](./src/lib/prompt-cache) - cache prompts and responses
-- [retry](./src/lib/retry) - retry asynchronous calls
-- [search-best-first](./src/lib/search-best-first) - best-first search algorithm
-- [search-js-files](./src/lib/search-js-files) - scan JavaScript sources
-- [combinations](./src/lib/combinations) - generate array combinations
-- [shorten-text](./src/lib/shorten-text) - shorten text using a model
-- [strip-numeric](./src/lib/strip-numeric) - remove non-digit characters
-- [strip-response](./src/lib/strip-response) - clean up model responses
-- [to-bool](./src/lib/to-bool) - parse text to boolean
-- [to-enum](./src/lib/to-enum) - parse text to enum values
-- [to-number](./src/lib/to-number) - parse text to numbers
-- [to-number-with-units](./src/lib/to-number-with-units) - parse numbers with units
-- [to-date](./src/lib/to-date) - parse text to JavaScript Date objects
-- [transcribe](./src/lib/transcribe) - microphone transcription via Whisper
-
-## Example: Intelligent Customer Support System
-
-This example shows how verblets enable building systems that understand context, make nuanced decisions, and adapt to complex real-world scenarios - capabilities that would be nearly impossible with traditional programming approaches.
-
-```javascript
-import bulkMap from './src/chains/bulk-map/index.js';
-import list from './src/chains/list/index.js';
-import {
-  anonymize,
-  bool,
-  enum,
-  intent,
-  listFilter,
-  questions,
-  sort,
-  toObject,
-  sentiment,
-  bulkScore
-} from 'verblets';
-
-// Intelligent customer support system that handles complex, contextual requests
-async function handleCustomerRequest(message, history, catalog) {
-  const customerIntent = await intent({
-    text: message,
-    operations: [
-      { name: 'refund-request', parameters: { reason: 'string', orderNumber: 'string?' } },
-      { name: 'product-inquiry', parameters: { productType: 'string', feature: 'string?' } },
-      { name: 'technical-support', parameters: { issue: 'string', urgency: 'string' } },
-      { name: 'complaint', parameters: { category: 'string', severity: 'string' } }
-    ]
-  });
-
-  const emotion = await sentiment(message);
-  const urgent = await bool(`Is this urgent? ${message}`);
-
-  const strategy = await enum(message, {
-    immediate_escalation: 'Customer is very upset, escalate to human agent',
-    detailed_help: 'Customer needs comprehensive assistance',
-    quick_resolution: 'Simple issue that can be resolved quickly',
-    educational: 'Customer needs to understand how something works'
-  });
-
-  const followUpQuestions = await questions(
-    `Customer says: "${message}". What should we ask to help them better?`
-  );
-
-  const candidates = await listFilter(
-    catalog,
-    `Products that might solve: ${
-      customerIntent.parameters.issue || customerIntent.parameters.productType
-    }`
-  );
-
-  const scores = await bulkScore(candidates, 'resolution likelihood');
-  const prioritized = await sort(candidates, `by likelihood score ${scores.join(', ')}`);
-
-  const bulletPoints = await bulkMap(
-    prioritized.map(p => p.name),
-    'Write a friendly one-line apology referencing <list>.'
-  );
-
-  const sampleReplies = await list('3 reassuring follow-up messages for this customer');
-
-  const caseSummary = await anonymize(
-    `Customer ${customerIntent.intent.operation}: ${message}.
-     History: ${history}. Resolution: ${prioritized[0]}`
-  );
-
-  const response = await toObject(
-    `
-    Customer needs ${customerIntent.intent.operation} help.
-    They are ${emotion} and ${urgent ? 'urgent' : 'not urgent'}.
-    Best approach: ${strategy}.
-    Top solution: ${prioritized[0]?.name}
-  `,
-    {
-      type: 'object',
-      properties: {
-        intent: { type: 'string' },
-        urgency: { type: 'string' },
-        emotion: { type: 'string' },
-        strategy: { type: 'string' },
-        recommendedSolution: { type: 'string' },
-        followUpQuestions: { type: 'array' }
-      }
-    }
-  );
-
-
-  return {
-    ...response,
-    followUpQuestions: followUpQuestions.slice(0, 3),
-    anonymizedCase: caseSummary,
-    bulletPoints,
-    sampleReplies
-  };
-}
-
-// Usage: Handle a complex customer scenario
-const result = await handleCustomerRequest(
-  "I'm really frustrated! I ordered your premium headphones 2 weeks ago for my daughter's birthday tomorrow and they still haven't arrived. The tracking says 'processing' but I paid for 2-day shipping. This is completely unacceptable and I want my money back immediately!",
-  'Previous orders: 3 successful deliveries, 1 late delivery complaint resolved',
-  [
-    {
-      name: 'Premium Wireless Headphones',
-      category: 'audio',
-      features: ['noise-canceling', 'wireless']
-    },
-    { name: 'Express Shipping Upgrade', category: 'service', features: ['priority', 'tracking'] },
-    { name: 'Gift Card', category: 'compensation', features: ['flexible', 'immediate'] }
-  ]
-);
-
-/* Returns something like:
-{
-  intent: "refund-request",
-  urgency: "high",
-  emotion: "frustrated",
-  strategy: "immediate_escalation",
-  recommendedSolution: "Express Shipping Upgrade",
-  followUpQuestions: [
-    "What's your order number so I can track this immediately?",
-    "Would you like us to expedite a replacement for tomorrow delivery?",
-    "How can we make this right for your daughter's birthday?"
-  ],
-  anonymizedCase: "Customer refund-request: Customer frustrated about delayed premium headphones order for child's birthday..."
-  bulletPoints: ["Apologies for the delay on Premium Wireless Headphones", ...],
-  sampleReplies: ["We're monitoring shipping updates...", ...]
-}
-*/
-```
-
-This system demonstrates capabilities that would require thousands of lines of traditional code and extensive machine learning expertise:
-
-- **Contextual understanding** of customer emotions and intent
-- **Dynamic decision making** based on multiple factors
-- **Adaptive questioning** that changes based on the situation
-- **Intelligent prioritization** of solutions
-- **Privacy-aware data handling** for compliance
-- **Structured output** that integrates with existing systems
+Helpers support higher-level operations. They make no LLM calls and are often synchronous.
 
+- [chatgpt](./src/lib/chatgpt) - OpenAI ChatGPT wrapper
+- [prompt-cache](./src/lib/prompt-cache) - Cache prompts and responses
+- [retry](./src/lib/retry) - Retry asynchronous calls
+- [ring-buffer](./src/lib/ring-buffer) - Circular buffer implementation for running LLMs on streams of data
 
 ## Contributing
 
-Help us explore what's possible when we rebuild software primitives with intelligence at their core.
+Help us explore what's possible when we extend software primitives with language model intelligence.
 
 ## License
 

package/dist/index.browser.js

@@ -0,0 +1,74 @@
+import { ag as a } from "./shared-C6kPWghF.js";
+import { E as r, a3 as i, f as n, F as o, l as c, a as m, G as l, H as p, e as u, I as g, k as d, g as f, a as h, m as b, o as y, J as v, K as x, L as T, p as S, i as k, a4 as B, a5 as P, q as j, M as C, t as E, N as M, u as O, v as V, w as q, a6 as w, x as z, O as A, y as F, z as G, a7 as I, a8 as L, A as R, P as U, Q as W, n as D, h as H, R as J, a8 as K, S as N, ab as Q, ae as X, T as Y, r as Z, U as _, ac as $, ad as aa, j as sa, V as ea, af as ta, B as ra, a9 as ia, s as na, aa as oa, W as ca, C as ma, X as la, Y as pa, Z as ua, D as ga, _ as da, $ as fa, a0 as ha, a1 as ba, a2 as ya } from "./shared-C6kPWghF.js";
+a();
+export {
+  r as anonymize,
+  i as auto,
+  n as bool,
+  o as categorySamples,
+  c as centralTendency,
+  m as chatGPT,
+  l as collectTerms,
+  p as commonalities,
+  u as constants,
+  g as conversation,
+  d as createScale,
+  f as date,
+  h as default,
+  b as detectPatterns,
+  y as detectThreshold,
+  v as disambiguate,
+  x as dismantle,
+  T as documentShrink,
+  S as entities,
+  k as enums,
+  B as expect,
+  P as expectChain,
+  j as extractBlocks,
+  C as fillMissing,
+  E as filter,
+  M as filterAmbiguous,
+  O as find,
+  V as glossary,
+  q as group,
+  w as intent,
+  z as intersections,
+  A as join,
+  F as list,
+  G as listExpand,
+  I as llmLogger,
+  L as makePrompt,
+  R as map,
+  U as name,
+  W as nameSimilarTo,
+  D as number,
+  H as numberWithUnits,
+  J as people,
+  K as phailForge,
+  N as popReference,
+  Q as promptCache,
+  X as prompts,
+  Y as questions,
+  Z as reduce,
+  _ as relations,
+  $ as retry,
+  aa as ringBuffer,
+  sa as scale,
+  ea as schemaOrg,
+  ta as schemas,
+  ra as score,
+  ia as sentiment,
+  na as services,
+  oa as setInterval,
+  ca as socratic,
+  ma as sort,
+  la as split,
+  pa as summaryMap,
+  ua as tagVocabulary,
+  ga as tags,
+  da as themes,
+  fa as timeline,
+  ha as toObject,
+  ba as truncate,
+  ya as veiledVariants
+};