@far-world-labs/verblets 0.6.1 → 0.6.4

package/README.md

@@ -6,6 +6,74 @@ Instead of mimicking humans in order to automate tasks, an AI standard library *
 
 Why the name? Verblets are *verbally* based: they're LLM-powered; and you can think of functions as verbs.
 
+## Install
+
+```sh
+npm install @far-world-labs/verblets
+```
+
+Set an API key as an environment variable — either works:
+
+```sh
+export OPENAI_API_KEY=sk-...
+# or
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Or use a `.env` file in your project root (loaded automatically via dotenv).
+
+Then initialize and call a function:
+
+```js
+import { init } from '@far-world-labs/verblets';
+
+const { score } = init();
+
+const results = await score(
+  ['reliability', 'performance', 'ease of use'],
+  'Rate each quality for a bicycle',
+);
+```
+
+`init()` validates that an API key is present, creates a fresh model service, and returns an object of wrapped functions with services pre-injected. Destructure the functions you need:
+
+```js
+const { filter, map, bool, llm } = init({
+  embed: true,            // enable local embedding model
+  redis: redisClient,     // pre-configured Redis client for caching
+  models: {               // extend the model catalog (additive)
+    'my-llama': { provider: 'openai', apiUrl: 'http://localhost:11434/v1', endpoint: '/chat/completions', maxContextWindow: 8192, maxOutputTokens: 4096 },
+  },
+  rules: [                // override negotiation rules (first match wins)
+    { match: { sensitive: true, good: true }, use: 'my-llama' },
+    { match: { sensitive: true }, use: 'my-llama' },
+    { match: { reasoning: true }, use: 'claude-opus-4-6' },
+    { match: { cheap: true, good: false }, use: 'gpt-4.1-nano' },
+    { use: 'gpt-4.1-mini' },  // catch-all default
+  ],
+  policy: {               // base policy for all LLM calls
+    temperature: () => 0.7,
+  },
+});
+```
+
+Each `init()` call creates an isolated instance with its own ModelService, so two instances do not share model configuration or caches:
+
+```js
+const a = init({ rules: [{ use: 'gpt-4.1' }] });
+const b = init({ rules: [{ use: 'claude-sonnet-4-20250514' }] });
+await a.filter(items, 'urgent');   // uses gpt-4.1
+await b.filter(items, 'urgent');   // uses claude-sonnet-4-20250514
+```
+
+The library selects models through ordered pattern-matching rules. Each rule has an optional `match` (capability conditions) and a `use` (model name). The first matching rule wins. A rule's `match` maps capabilities to `true` (must be requested) or `false` (must NOT be requested). Unmentioned capabilities are don't-care.
+
+Consumers express intent as capability objects: `{ fast: true }`, `{ reasoning: true }`, `{ sensitive: true, good: true }`. The value `'prefer'` acts as a soft preference that falls through gracefully when unavailable. Capabilities: `fast`, `cheap`, `good`, `reasoning`, `multi`, `sensitive`.
+
+Sensitive and reasoning capabilities are gated by default — they only match rules that explicitly mention them, preventing sensitive data from reaching cloud models or expensive reasoning models from being selected without opt-in.
+
+Without Redis, caching is disabled and the library operates statelessly.
+
 ## Repository Guide
 
 ### Quick Links
@@ -129,7 +197,7 @@ Codebase utilities analyze, test, and improve code quality using AI reasoning.
 Low-level utilities that support chains and verblets. Most are synchronous and make no LLM calls.
 
 - [llm](./src/lib/llm) - Core LLM wrapper with capability-based model selection and structured output
-- [context](./src/lib/context) - Config resolution: `getOption`, `getOptions`, `withPolicy`, `scopeOperation`
+- [context](./src/lib/context) - Config resolution: `nameStep`, `getOption`, `getOptions`, `withPolicy`
 - [prompt-cache](./src/lib/prompt-cache) - Cache LLM prompts and responses
 - [retry](./src/lib/retry) - Config-aware async retry
 - [parallel-batch](./src/lib/parallel-batch) - Parallel execution with concurrency limits

package/dist/index.browser.js

@@ -1,225 +1,238 @@
-import { cC as a } from "./shared-7kx0H5BO.js";
-import { cz as i, F as r, C as c, G as n, aQ as o, D as l, E as b, ao as p, Q as u, bg as m, bj as g, c1 as d, bx as S, c0 as I, $ as T, A as y, a8 as h, _ as R, b6 as v, o as C, au as f, aE as E, bv as F, f as M, aN as B, a5 as N, y as P, z as x, aM as A, bt as O, a1 as L, a2 as k, ch as w, bW as D, i as G, aO as z, bU as U, aP as V, ci as W, bl as _, cB as q, e as Q, aR as Y, cj as j, bY as K, B as J, H as X, a9 as H, c as Z, b7 as $, p as aa, aF as sa, aG as ea, R as ta, g as ia, bX as ra, a as ca, O as na, a3 as oa, a4 as la, ap as ba, aS as pa, aU as ua, aW as ma, aX as ga, bD as da, bS as Sa, bE as Ia, bQ as Ta, bF as ya, bR as ha, bK as Ra, bP as va, bO as Ca, bJ as fa, bN as Ea, bI as Fa, bT as Ma, bL as Ba, bM as Na, bG as Pa, a6 as xa, ab as Aa, ad as Oa, ae as La, aa as ka, ac as wa, a7 as Da, Y as Ga, Z as za, S as Ua, bw as Va, af as Wa, c8 as _a, aY as qa, ag as Qa, aZ as Ya, ah as ja, am as Ka, cy as Ja, aT as Xa, K as Ha, L as Za, M as $a, ai as as, aj as ss, cA as es, by as ts, ak as is, a_ as rs, ck as cs, al as ns, an as os, aq as ls, a as bs, bz as ps, bA as us, ar as ms, a$ as gs, b0 as ds, n as Ss, bZ as Is, h as Ts, k as ys, I as hs, J as Rs, cl as vs, b_ as Cs, b$ as fs, cg as Es, b8 as Fs, b9 as Ms, b1 as Bs, bA as Ns, cm as Ps, cs as xs, b2 as As, x as Os, cv as Ls, cw as ks, ct as ws, b3 as Ds, bV as Gs, r as zs, b5 as Us, b4 as Vs, bb as Ws, bd as _s, be as qs, ba as Qs, bc as Ys, cx as js, d as Ks, c3 as Js, l as Xs, t as Hs, v as Zs, w as $s, q as ae, u as se, m as ee, bf as te, cu as ie, bs as re, c4 as ce, as as ne, ax as oe, az as le, aA as be, av as pe, aw as ue, ay as me, at as ge, bB as de, s as Se, bH as Ie, bC as Te, cr as ye, aV as he, bh as Re, bu as ve, aB as Ce, cn as fe, bi as Ee, ca as Fe, c9 as Me, a0 as Be, aD as Ne, bk as Pe, aC as xe, aI as Ae, aK as Oe, aL as Le, aH as ke, aJ as we, U as De, V as Ge, T as ze, X as Ue, c2 as Ve, bm as We, bn as _e, cb as qe, cd as Qe, ce as Ye, cc as je, cf as Ke, bo as Je, bp as Xe, co as He, W as Ze, P as $e, cp as at, br as st, bq as et, c5 as tt, c6 as it, c7 as rt, N as ct, cq as nt } from "./shared-7kx0H5BO.js";
+import { cU as a } from "./shared-CsrVgt_K.js";
+import { cR as c, N as i, K as r, P as n, cg as o, aX as l, M as b, cf as p, L as u, ci as m, cj as d, av as g, c7 as S, cQ as I, cl as T, O as y, cm as h, Q as R, bn as v, ck as E, bq as C, ch as M, cc as f, bH as F, bC as O, bD as P, cb as L, a6 as N, I as B, af as x, a5 as A, bd as D, y as k, aB as w, aL as G, bF as z, o as K, aU as U, bE as V, ac as _, G as j, H as Q, aT as W, bA as Y, a8 as q, a9 as J, cz as H, c4 as X, q as Z, aV as $, c2 as aa, aW as sa, cA as ea, bs as ta, cT as ca, m as ia, aY as ra, cB as na, c6 as oa, J as la, R as ba, ag as pa, c as ua, be as ma, z as da, aM as ga, aN as Sa, Y as Ia, p as Ta, c5 as ya, r as ha, W as Ra, aa as va, ab as Ea, aw as Ca, aZ as Ma, a$ as fa, b1 as Fa, b2 as Oa, bN as Pa, c0 as La, bO as Na, b_ as Ba, bP as xa, b$ as Aa, bU as Da, bZ as ka, bY as wa, bT as Ga, bX as za, bS as Ka, c1 as Ua, bV as Va, bW as _a, bQ as ja, ad as Qa, ai as Wa, ak as Ya, al as qa, ah as Ja, aj as Ha, ae as Xa, a3 as Za, a4 as $a, Z as as, bG as ss, am as es, cq as ts, b3 as cs, an as is, b4 as rs, ao as ns, at as os, a_ as ls, U as bs, V as ps, g as us, ap as ms, aq as ds, cS as gs, bI as Ss, ar as Is, b5 as Ts, j as ys, cC as hs, as as Rs, au as vs, ax as Es, r as Cs, bJ as Ms, bK as fs, ay as Fs, b6 as Os, b7 as Ps, n as Ls, c8 as Ns, t as Bs, u as xs, S as As, T as Ds, cD as ks, c9 as ws, ca as Gs, cy as zs, bf as Ks, bg as Us, b8 as Vs, bK as _s, cE as js, cK as Qs, b9 as Ws, F as Ys, cN as qs, cO as Js, cL as Hs, ba as Xs, c3 as Zs, d as $s, bc as ae, bb as se, bi as ee, bk as te, bl as ce, bh as ie, bj as re, cP as ne, f as oe, ce as le, v as be, B as pe, D as ue, E as me, A as de, C as ge, x as Se, bm as Ie, cM as Te, bz as ye, s as he, az as Re, aE as ve, aG as Ee, aH as Ce, aC as Me, aD as fe, aF as Fe, aA as Oe, bL as Pe, bR as Le, bM as Ne, cJ as Be, b0 as xe, bo as Ae, bB as De, aI as ke, cF as we, bp as Ge, cs as ze, cr as Ke, a7 as Ue, aK as Ve, br as _e, aJ as je, aP as Qe, aR as We, aS as Ye, aO as qe, aQ as Je, $ as He, a0 as Xe, _ as Ze, a2 as $e, cd as at, bt as st, bu as et, ct as tt, cv as ct, cw as it, cu as rt, cx as nt, bv as ot, bw as lt, cG as bt, a1 as pt, X as ut, cH as mt, by as dt, bx as gt, cn as St, co as It, cp as Tt, w as yt, cI as ht } from "./shared-CsrVgt_K.js";
 a();
 export {
-  i as CAPABILITY_KEYS,
-  r as COMPLIANCE,
-  c as CONTEXT_KINDS,
+  c as CAPABILITY_KEYS,
+  i as COMPLIANCE,
+  r as CONTEXT_KINDS,
   n as COST_POSTURE,
-  o as Conversation,
-  l as DOMAIN,
-  b as ENVIRONMENT,
-  p as ListStyle,
-  u as QUALITY_INTENT,
-  m as SocraticMethod,
-  g as SummaryMap,
-  d as TimedAbortController,
-  S as aiExpect,
-  I as anySignal,
-  T as applyAllTargetingRules,
-  y as applyCalibrate,
-  h as applyEntities,
-  R as applyFirstTargetingRule,
-  v as applyRelations,
-  C as applyScale,
-  f as applyScore,
-  E as applyTags,
-  F as auto,
-  M as bool,
-  B as buildSeedGenerationPrompt,
-  N as calculateStatistics,
-  P as calibrate,
-  x as calibrateSpec,
-  A as categorySamples,
-  O as causalFramePrompt,
-  L as centralTendency,
-  k as centralTendencyLines,
-  w as chunk,
-  D as chunkSentences,
-  G as classify,
-  z as collectTerms,
-  U as combinations,
-  V as commonalities,
-  W as compact,
-  _ as computeTagStatistics,
-  q as config,
-  Q as constants,
-  Y as conversationTurnReduce,
-  j as cosineSimilarity,
-  K as createBatches,
-  J as createCalibratedClassifier,
-  X as createContextBuilder,
-  H as createEntityExtractor,
-  Z as createProgressEmitter,
-  $ as createRelationExtractor,
-  aa as createScale,
-  sa as createTagExtractor,
-  ea as createTagger,
-  ta as createTraceCollector,
-  ia as date,
-  ra as debug,
-  ca as default,
-  na as descriptorToSchema,
-  oa as detectPatterns,
-  la as detectThreshold,
-  ba as determineStyle,
-  pa as disambiguate,
-  ua as dismantle,
-  ma as dismantleFactory,
-  ga as documentShrink,
-  da as embed,
-  Sa as embedAssembleSpan,
-  Ia as embedBatch,
-  Ta as embedBuildIndex,
-  ya as embedChunked,
-  ha as embedMergeRanges,
-  Ra as embedMultiQuery,
-  va as embedNeighborChunks,
-  Ca as embedNormalizeText,
-  fa as embedRewriteQuery,
-  Ea as embedRewriteToOutputDoc,
-  Fa as embedScore,
-  Ma as embedStandaloneSpan,
-  Ba as embedStepBack,
-  Na as embedSubquestions,
-  Pa as embedWarmup,
-  xa as entities,
-  Aa as entitiesFilterInstructions,
-  Oa as entitiesFindInstructions,
-  La as entitiesGroupInstructions,
-  ka as entitiesMapInstructions,
-  wa as entitiesReduceInstructions,
-  Da as entitySpec,
-  Ga as evaluateTargetingClause,
-  za as evaluateTargetingRule,
-  Ua as eventToTrace,
-  Va as expect,
-  Wa as extractBlocks,
-  _a as extractJson,
-  qa as fillMissing,
-  Qa as filter,
-  Ya as filterAmbiguous,
-  ja as find,
-  Ka as generateList,
-  Ja as getCapabilities,
-  Xa as getMeanings,
-  Ha as getOption,
-  Za as getOptionDetail,
-  $a as getOptions,
-  as as glossary,
-  ss as group,
-  es as init,
-  ts as intent,
-  is as intersections,
-  rs as join,
-  cs as last,
-  ns as list,
-  os as listBatch,
-  ls as listExpand,
-  bs as llm,
-  ps as llmLogger,
-  us as makePrompt,
-  ms as map,
-  gs as name,
-  ds as nameSimilarTo,
-  Ss as nameStep,
-  Is as normalizeLlm,
-  Ts as number,
-  ys as numberWithUnits,
-  hs as observeApplication,
-  Rs as observeProviders,
-  vs as omit,
-  Cs as parallel,
-  fs as parallelMap,
-  Es as parseLLMList,
-  Fs as parseRDFLiteral,
-  Ms as parseRelations,
-  Bs as people,
-  Ns as phailForge,
-  Ps as pick,
-  xs as pipe,
-  As as popReference,
-  Os as probeScan,
-  Ls as promptCache,
-  ks as promptPiece,
-  ws as prompts,
-  Ds as questions,
-  Gs as rangeCombinations,
-  zs as reduce,
-  Us as relationSpec,
-  Vs as relations,
-  Ws as relationsFilterInstructions,
-  _s as relationsFindInstructions,
-  qs as relationsGroupInstructions,
-  Qs as relationsMapInstructions,
-  Ys as relationsReduceInstructions,
-  js as resolveModel,
-  Ks as retry,
-  Js as ringBuffer,
-  Xs as scale,
-  Hs as scaleFilterInstructions,
-  Zs as scaleFindInstructions,
-  $s as scaleGroupInstructions,
-  ae as scaleMapInstructions,
-  se as scaleReduceInstructions,
-  ee as scaleSpec,
-  te as schemaOrg,
-  ie as schemas,
-  re as scientificFramingPrompt,
-  ce as scopePhase,
-  ne as score,
-  oe as scoreFilterInstructions,
-  le as scoreFindInstructions,
-  be as scoreGroupInstructions,
-  pe as scoreItem,
-  ue as scoreMapInstructions,
-  me as scoreReduceInstructions,
-  ge as scoreSpec,
-  de as sentiment,
-  Se as services,
-  Ie as setEmbedEnabled,
-  Te as setInterval,
-  ye as shuffle,
-  he as simplifyTree,
-  Re as socratic,
-  ve as softCoverPrompt,
-  Ce as sort,
-  fe as sortBy,
-  Ee as split,
-  Fe as stripNumeric,
-  Me as stripResponse,
-  Be as suggestTargetingRules,
-  Ne as tagSpec,
-  Pe as tagVocabulary,
-  xe as tags,
-  Ae as tagsFilterInstructions,
-  Oe as tagsFindInstructions,
-  Le as tagsGroupInstructions,
-  ke as tagsMapInstructions,
-  we as tagsReduceInstructions,
-  De as targetingClause,
-  Ge as targetingRule,
-  ze as targetingRuleOps,
-  Ue as targetingRuleSchema,
-  Ve as templateReplace,
-  We as themes,
-  _e as timeline,
-  qe as toBool,
-  Qe as toDate,
-  Ye as toEnum,
-  je as toNumber,
-  Ke as toNumberWithUnits,
-  Je as toObject,
-  Xe as truncate,
-  He as unionBy,
-  Ze as validateTargetingRules,
-  $e as valueArbitrate,
-  at as vectorSearch,
-  st as veiledVariantStrategies,
-  et as veiledVariants,
-  tt as version,
-  it as windowFor,
-  rt as withInactivityTimeout,
-  ct as withPolicy,
-  nt as zipWith
+  o as ChainEvent,
+  l as Conversation,
+  b as DOMAIN,
+  p as DomainEvent,
+  u as ENVIRONMENT,
+  m as Kind,
+  d as Level,
+  g as ListStyle,
+  S as MODEL_KEYS,
+  I as ModelService,
+  T as ModelSource,
+  y as OpEvent,
+  h as OptionSource,
+  R as QUALITY_INTENT,
+  v as SocraticMethod,
+  E as StatusCode,
+  C as SummaryMap,
+  M as TelemetryEvent,
+  f as TimedAbortController,
+  F as aiExpect,
+  O as analyzeImage,
+  P as analyzeImageMapDetail,
+  L as anySignal,
+  N as applyAllTargetingRules,
+  B as applyCalibrate,
+  x as applyEntities,
+  A as applyFirstTargetingRule,
+  D as applyRelations,
+  k as applyScale,
+  w as applyScore,
+  G as applyTags,
+  z as auto,
+  K as bool,
+  U as buildSeedGenerationPrompt,
+  V as buildVisionPrompt,
+  _ as calculateStatistics,
+  j as calibrate,
+  Q as calibrateSpec,
+  W as categorySamples,
+  Y as causalFramePrompt,
+  q as centralTendency,
+  J as centralTendencyLines,
+  H as chunk,
+  X as chunkSentences,
+  Z as classify,
+  $ as collectTerms,
+  aa as combinations,
+  sa as commonalities,
+  ea as compact,
+  ta as computeTagStatistics,
+  ca as config,
+  ia as constants,
+  ra as conversationTurnReduce,
+  na as cosineSimilarity,
+  oa as createBatches,
+  la as createCalibratedClassifier,
+  ba as createContextBuilder,
+  pa as createEntityExtractor,
+  ua as createProgressEmitter,
+  ma as createRelationExtractor,
+  da as createScale,
+  ga as createTagExtractor,
+  Sa as createTagger,
+  Ia as createTraceCollector,
+  Ta as date,
+  ya as debug,
+  ha as default,
+  Ra as descriptorToSchema,
+  va as detectPatterns,
+  Ea as detectThreshold,
+  Ca as determineStyle,
+  Ma as disambiguate,
+  fa as dismantle,
+  Fa as dismantleFactory,
+  Oa as documentShrink,
+  Pa as embed,
+  La as embedAssembleSpan,
+  Na as embedBatch,
+  Ba as embedBuildIndex,
+  xa as embedChunked,
+  Aa as embedMergeRanges,
+  Da as embedMultiQuery,
+  ka as embedNeighborChunks,
+  wa as embedNormalizeText,
+  Ga as embedRewriteQuery,
+  za as embedRewriteToOutputDoc,
+  Ka as embedScore,
+  Ua as embedStandaloneSpan,
+  Va as embedStepBack,
+  _a as embedSubquestions,
+  ja as embedWarmup,
+  Qa as entities,
+  Wa as entitiesFilterInstructions,
+  Ya as entitiesFindInstructions,
+  qa as entitiesGroupInstructions,
+  Ja as entitiesMapInstructions,
+  Ha as entitiesReduceInstructions,
+  Xa as entitySpec,
+  Za as evaluateTargetingClause,
+  $a as evaluateTargetingRule,
+  as as eventToTrace,
+  ss as expect,
+  es as extractBlocks,
+  ts as extractJson,
+  cs as fillMissing,
+  is as filter,
+  rs as filterAmbiguous,
+  ns as find,
+  os as generateList,
+  ls as getMeanings,
+  bs as getOption,
+  ps as getOptionDetail,
+  us as getOptions,
+  ms as glossary,
+  ds as group,
+  gs as init,
+  Ss as intent,
+  Is as intersections,
+  Ts as join,
+  ys as jsonSchema,
+  hs as last,
+  Rs as list,
+  vs as listBatch,
+  Es as listExpand,
+  Cs as llm,
+  Ms as llmLogger,
+  fs as makePrompt,
+  Fs as map,
+  Os as name,
+  Ps as nameSimilarTo,
+  Ls as nameStep,
+  Ns as normalizeLlm,
+  Bs as number,
+  xs as numberWithUnits,
+  As as observeApplication,
+  Ds as observeProviders,
+  ks as omit,
+  ws as parallel,
+  Gs as parallelMap,
+  zs as parseLLMList,
+  Ks as parseRDFLiteral,
+  Us as parseRelations,
+  Vs as people,
+  _s as phailForge,
+  js as pick,
+  Qs as pipe,
+  Ws as popReference,
+  Ys as probeScan,
+  qs as promptCache,
+  Js as promptPiece,
+  Hs as prompts,
+  Xs as questions,
+  Zs as rangeCombinations,
+  $s as reduce,
+  ae as relationSpec,
+  se as relations,
+  ee as relationsFilterInstructions,
+  te as relationsFindInstructions,
+  ce as relationsGroupInstructions,
+  ie as relationsMapInstructions,
+  re as relationsReduceInstructions,
+  ne as resolveModel,
+  oe as retry,
+  le as ringBuffer,
+  be as scale,
+  pe as scaleFilterInstructions,
+  ue as scaleFindInstructions,
+  me as scaleGroupInstructions,
+  de as scaleMapInstructions,
+  ge as scaleReduceInstructions,
+  Se as scaleSpec,
+  Ie as schemaOrg,
+  Te as schemas,
+  ye as scientificFramingPrompt,
+  he as scopePhase,
+  Re as score,
+  ve as scoreFilterInstructions,
+  Ee as scoreFindInstructions,
+  Ce as scoreGroupInstructions,
+  Me as scoreItem,
+  fe as scoreMapInstructions,
+  Fe as scoreReduceInstructions,
+  Oe as scoreSpec,
+  Pe as sentiment,
+  Le as setEmbedEnabled,
+  Ne as setInterval,
+  Be as shuffle,
+  xe as simplifyTree,
+  Ae as socratic,
+  De as softCoverPrompt,
+  ke as sort,
+  we as sortBy,
+  Ge as split,
+  ze as stripNumeric,
+  Ke as stripResponse,
+  Ue as suggestTargetingRules,
+  Ve as tagSpec,
+  _e as tagVocabulary,
+  je as tags,
+  Qe as tagsFilterInstructions,
+  We as tagsFindInstructions,
+  Ye as tagsGroupInstructions,
+  qe as tagsMapInstructions,
+  Je as tagsReduceInstructions,
+  He as targetingClause,
+  Xe as targetingRule,
+  Ze as targetingRuleOps,
+  $e as targetingRuleSchema,
+  at as templateReplace,
+  st as themes,
+  et as timeline,
+  tt as toBool,
+  ct as toDate,
+  it as toEnum,
+  rt as toNumber,
+  nt as toNumberWithUnits,
+  ot as toObject,
+  lt as truncate,
+  bt as unionBy,
+  pt as validateTargetingRules,
+  ut as valueArbitrate,
+  mt as vectorSearch,
+  dt as veiledVariantStrategies,
+  gt as veiledVariants,
+  St as version,
+  It as windowFor,
+  Tt as withInactivityTimeout,
+  yt as withPolicy,
+  ht as zipWith
 };