@hourslabs/domovoi 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -7,11 +7,17 @@
  *   - `@hourslabs/domovoi/testing` — mockProvider for unit tests.
  */
 import { memoryCache as memoryCacheFactory } from "./cache.js";
+import { bind as bindFn, currentScope as currentScopeFn, scope as scopeFn } from "./scope.js";
 import { boolean as booleanVerb } from "./verbs/boolean.js";
 import { classifier as classifierFactory } from "./verbs/classifier.js";
 import { classify as classifyVerb } from "./verbs/classify.js";
+export type { BudgetMode, BudgetSnapshot, ScopeBudget } from "./budget-tracker.js";
 export type { Cache, CacheStats, CacheWithStats } from "./cache.js";
-export { BudgetExhaustedError, ConfigError, DomovoiError, type ErrorCode, ProviderError, } from "./errors.js";
+export type { ContextStorage } from "./context-storage.js";
+export { configureContextStorage, resetContextStorage } from "./context-storage.js";
+export { BudgetExceededError, BudgetExhaustedError, ConfigError, DomovoiError, type ErrorCode, ProviderError, } from "./errors.js";
+export type { ResolvedScope, ScopeOptions } from "./scope.js";
+export type { AttributeValue, Span, Tracer } from "./tracer.js";
 export type { Budget, Classified, Distribution, Filterable, Label, PromptTemplate, ProviderCapabilities, SerializableError, Thresholds, Uncertain, Unknown, UnknownVerdictCause, Verdict, VerdictMeta, } from "./types.js";
 export type { BooleanOptions } from "./verbs/boolean.js";
 export type { Classifier, ClassifierConfig } from "./verbs/classifier.js";
@@ -24,11 +30,20 @@ export { filter, isClassified, isUncertain, isUnknown, match } from "./verdict.j
  *   import { domovoi, isClassified } from "@hourslabs/domovoi";
  *   const v = await domovoi.classify(input, ["a","b","c"] as const);
  *   if (isClassified(v)) console.log(v.value);
+ *
+ * @example v0.2 ambient context
+ *   await domovoi.scope({ budget: { tokens: 10_000 } }, async () => {
+ *     const v = await domovoi.classify(input, ["a","b","c"]);
+ *     // v0.2: classify call inherits budget enforcement from scope
+ *   });
  */
 export declare const domovoi: {
     readonly classify: typeof classifyVerb;
     readonly boolean: typeof booleanVerb;
     readonly classifier: typeof classifierFactory;
     readonly memoryCache: typeof memoryCacheFactory;
+    readonly scope: typeof scopeFn;
+    readonly bind: typeof bindFn;
+    readonly currentScope: typeof currentScopeFn;
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,IAAI,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE/D,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,KAAK,SAAS,EACd,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,MAAM,EACN,UAAU,EACV,YAAY,EACZ,UAAU,EACV,KAAK,EACL,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,OAAO,EACP,mBAAmB,EACnB,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO;;;;;CAKV,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,IAAI,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,YAAY,IAAI,cAAc,EAAE,KAAK,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE/D,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACnF,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,KAAK,SAAS,EACd,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EACV,MAAM,EACN,UAAU,EACV,YAAY,EACZ,UAAU,EACV,KAAK,EACL,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,OAAO,EACP,mBAAmB,EACnB,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,OAAO;;;;;;;;CAQV,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 import { createHash } from 'crypto';
+import { AsyncLocalStorage } from 'async_hooks';
 import OpenAI from 'openai';
 import { get_encoding } from 'tiktoken';
 
@@ -158,6 +159,19 @@ var BudgetExhaustedError = class extends DomovoiError {
     this.elapsedMs = options.elapsedMs;
   }
 };
+var BudgetExceededError = class extends DomovoiError {
+  spent;
+  limit;
+  constructor(options) {
+    super(`Scope budget exceeded: ${options.spent} / ${options.limit} tokens`, {
+      code: "tokens_exceeded",
+      cause: options.cause
+    });
+    this.name = "BudgetExceededError";
+    this.spent = options.spent;
+    this.limit = options.limit;
+  }
+};
 function canonicalizeProviderThrow(thrown) {
   if (thrown instanceof DomovoiError) return thrown;
   if (thrown instanceof Error) {
@@ -186,6 +200,109 @@ function serializeError(err) {
   };
 }
 
+// src/budget-tracker.ts
+var BudgetTracker = class _BudgetTracker {
+  constructor(limit, mode) {
+    this.limit = limit;
+    this.mode = mode;
+  }
+  limit;
+  mode;
+  spent = 0;
+  /**
+   * Build a tracker from a public `ScopeBudget`, or return `undefined` if
+   * the budget is absent / has no `tokens` field. Used during scope merge.
+   *
+   * Throws `ConfigError` if `tokens` is non-finite or non-positive — these
+   * are construction-time validation failures, not runtime budget exhaustion.
+   */
+  static from(budget) {
+    if (budget?.tokens === void 0) return void 0;
+    if (!Number.isFinite(budget.tokens) || budget.tokens <= 0) {
+      throw new ConfigError(
+        `Scope budget tokens must be a finite positive number, got ${budget.tokens}`,
+        { code: "invalid_scope_budget" }
+      );
+    }
+    return new _BudgetTracker(budget.tokens, budget.onExceeded ?? "graceful");
+  }
+  /** Check whether the budget is already exhausted. Called pre-call. */
+  precheck() {
+    if (this.isExhausted()) {
+      return { ok: false, spent: this.spent, limit: this.limit };
+    }
+    return { ok: true };
+  }
+  /**
+   * Accumulate spend. Called post-call with the actual token cost.
+   * Negative or non-finite values are silently clamped to 0 — provider
+   * adapters occasionally return malformed token counts, and a budget
+   * tracker shouldn't panic on bad telemetry from upstream.
+   */
+  charge(tokens) {
+    if (!Number.isFinite(tokens) || tokens <= 0) return;
+    this.spent += tokens;
+  }
+  /**
+   * Throw `BudgetExceededError` if mode is `"throw"` and budget is exhausted.
+   * Caller invokes after `charge()` to enforce hard-fail semantics; under
+   * `"graceful"` mode this is a no-op and the next `precheck()` returns
+   * `{ ok: false, ... }` for graceful Unknown construction.
+   */
+  enforce() {
+    if (this.isExhausted() && this.mode === "throw") {
+      throw new BudgetExceededError({ spent: this.spent, limit: this.limit });
+    }
+  }
+  snapshot() {
+    return { spent: this.spent, limit: this.limit, mode: this.mode };
+  }
+  isExhausted() {
+    return this.spent >= this.limit;
+  }
+};
+var storage = new AsyncLocalStorage();
+function getContextStorage() {
+  return storage;
+}
+function configureContextStorage(custom) {
+  storage = custom;
+}
+function resetContextStorage() {
+  storage = new AsyncLocalStorage();
+}
+
+// src/scope.ts
+function scope(opts, fn) {
+  const parent = currentScope();
+  const merged = mergeScopes(parent, opts);
+  return getContextStorage().run(merged, fn);
+}
+function currentScope() {
+  return getContextStorage().getStore();
+}
+function bind(fn) {
+  const captured = currentScope();
+  if (!captured) return fn;
+  const storage2 = getContextStorage();
+  return ((...args) => storage2.run(captured, () => fn(...args)));
+}
+function mergeScopes(parent, child) {
+  const signal = mergeSignals(parent?.signal, child.signal);
+  const tracer = child.tracer ?? parent?.tracer;
+  const budgetTracker = child.budget ? BudgetTracker.from(child.budget) : parent?.budgetTracker;
+  return {
+    ...signal ? { signal } : {},
+    ...tracer ? { tracer } : {},
+    ...budgetTracker ? { budgetTracker } : {}
+  };
+}
+function mergeSignals(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return AbortSignal.any([a, b]);
+}
+
 // src/calibration/index.ts
 var identity = {
   kind: "identity",
@@ -380,6 +497,21 @@ function validateClassifierConfig(input) {
   }
 }
 
+// src/tracer.ts
+var noopSpan = {
+  setAttribute: () => {
+  },
+  recordException: () => {
+  },
+  setStatus: () => {
+  },
+  end: () => {
+  }
+};
+var noopTracer = {
+  startSpan: () => noopSpan
+};
+
 // src/engine/meta.ts
 function makeMetaBuilder() {
   return {
@@ -433,11 +565,11 @@ function buildCancelledVerdict(meta, reason, provider) {
     meta: buildMetaForFailure(meta, provider)
   };
 }
-function buildBudgetExhaustedVerdict(meta, scope, policy, provider) {
+function buildBudgetExhaustedVerdict(meta, scope2, policy, provider) {
   if (policy === "throw") return void 0;
   return {
     kind: "unknown",
-    reason: { type: "budget_exhausted", scope },
+    reason: { type: "budget_exhausted", scope: scope2 },
     meta: buildMetaForFailure(meta, provider)
   };
 }
@@ -469,9 +601,10 @@ function computeProviderCacheKey(provider, formattedInput, config) {
     formattedInput
   });
 }
-function mergeSignals(userSignal, timeoutSignal) {
+function mergeSignals2(userSignal, timeoutSignal, scopeSignal) {
   const signals = [timeoutSignal];
-  if (userSignal !== void 0) signals.push(userSignal);
+  if (userSignal) signals.push(userSignal);
+  if (scopeSignal) signals.push(scopeSignal);
   return AbortSignal.any(signals);
 }
 async function loadDistribution(provider, formattedInput, config, meta, signal, cacheKey) {
@@ -583,6 +716,16 @@ function makeCancelledFromMeta(meta, reason) {
     meta: buildMetaForFailure(meta)
   };
 }
+function makeBudgetExceededVerdict(meta, spent, limit, mode) {
+  if (mode === "throw") {
+    throw new BudgetExceededError({ spent, limit });
+  }
+  return {
+    kind: "unknown",
+    reason: { type: "budget_exceeded", spent, limit },
+    meta: buildMetaForFailure(meta)
+  };
+}
 function finalizeChainExhausted(meta, lastCalibrated, attempts, config) {
   const allErrored = lastCalibrated === void 0 && meta.providerErrors.length > 0 && meta.providerErrors.length === meta.providersAttempted.length;
   if (allErrored) {
@@ -666,7 +809,8 @@ function applyMultiClassRule(top, second, t) {
 // src/engine/decide.ts
 async function decide(formattedInput, config, signal) {
   const meta = makeMetaBuilder();
-  const preAbort = abortReason(signal);
+  const scope2 = currentScope();
+  const preAbort = firstAbortReason(signal, scope2?.signal);
   if (preAbort !== void 0) {
     return makeCancelledFromMeta(meta, preAbort);
   }
@@ -687,7 +831,20 @@ async function decide(formattedInput, config, signal) {
       fireAndForget(config.hooks?.onResult, chainBudgetVerdict);
       return chainBudgetVerdict;
     }
-    const midAbort = abortReason(signal);
+    if (scope2?.budgetTracker) {
+      const pre = scope2.budgetTracker.precheck();
+      if (!pre.ok) {
+        const verdict = makeBudgetExceededVerdict(
+          meta,
+          pre.spent,
+          pre.limit,
+          scope2.budgetTracker.mode
+        );
+        fireAndForget(config.hooks?.onResult, verdict);
+        return verdict;
+      }
+    }
+    const midAbort = firstAbortReason(signal, scope2?.signal);
     if (midAbort !== void 0) {
       const verdict = buildCancelledVerdict(meta, midAbort, provider);
       fireAndForget(config.hooks?.onResult, verdict);
@@ -703,7 +860,8 @@ async function decide(formattedInput, config, signal) {
       i,
       chainStartMs,
       limits.perCallTimeoutMs,
-      isLastProvider
+      isLastProvider,
+      scope2
     );
     if (outcome.kind === "verdict") {
       fireAndForget(config.hooks?.onResult, outcome.verdict);
@@ -725,40 +883,84 @@ function computeLimits(config) {
     maxCalls: config.budget?.maxCalls ?? config.providers.length
   };
 }
-async function attemptProvider(provider, formattedInput, config, meta, userSignal, index, chainStartMs, perCallTimeoutMs, isLastProvider) {
-  const cacheKey = computeProviderCacheKey(provider, formattedInput, config);
-  const timeoutSignal = AbortSignal.timeout(perCallTimeoutMs);
-  const mergedSignal = mergeSignals(userSignal, timeoutSignal);
-  let distribution;
-  try {
-    distribution = await loadDistribution(
-      provider,
-      formattedInput,
-      config,
-      meta,
-      mergedSignal,
-      cacheKey
-    );
-  } catch (err) {
-    return handleDistributionError(
-      err,
-      provider,
-      meta,
-      config,
-      userSignal,
-      timeoutSignal,
-      index,
-      chainStartMs,
-      cacheKey
-    );
+function firstAbortReason(...signals) {
+  for (const s of signals) {
+    const reason = abortReason(s);
+    if (reason !== void 0) return reason;
   }
+  return void 0;
+}
+function estimateInputTokens(formattedInput) {
+  return Math.ceil(formattedInput.length / 4);
+}
+function estimateOutputTokens() {
+  return 20;
+}
+async function attemptProvider(provider, formattedInput, config, meta, userSignal, index, chainStartMs, perCallTimeoutMs, isLastProvider, scope2) {
+  const tracer = scope2?.tracer ?? noopTracer;
+  const span = tracer.startSpan(`chat ${provider.id}`, {
+    "gen_ai.provider.name": provider.id,
+    "gen_ai.operation.name": "chat",
+    "gen_ai.request.model": provider.modelId,
+    "domovoi.label_space": [...config.space]
+  });
   try {
-    validateDistribution(distribution, config.space);
+    const cacheKey = computeProviderCacheKey(provider, formattedInput, config);
+    const timeoutSignal = AbortSignal.timeout(perCallTimeoutMs);
+    const mergedSignal = mergeSignals2(userSignal, timeoutSignal, scope2?.signal);
+    let distribution;
+    try {
+      distribution = await loadDistribution(
+        provider,
+        formattedInput,
+        config,
+        meta,
+        mergedSignal,
+        cacheKey
+      );
+    } catch (err) {
+      span.recordException(err);
+      span.setStatus("error");
+      return handleDistributionError(
+        err,
+        provider,
+        meta,
+        config,
+        userSignal,
+        timeoutSignal,
+        index,
+        chainStartMs,
+        cacheKey
+      );
+    }
+    span.setAttribute("domovoi.cache.hit", meta.cacheHit);
+    if (!meta.cacheHit) {
+      const inputTokens = estimateInputTokens(formattedInput);
+      const outputTokens = estimateOutputTokens();
+      span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
+      span.setAttribute("gen_ai.usage.output_tokens", outputTokens);
+      scope2?.budgetTracker?.charge(inputTokens + outputTokens);
+      scope2?.budgetTracker?.enforce();
+    }
+    try {
+      validateDistribution(distribution, config.space);
+    } catch (err) {
+      span.recordException(err);
+      span.setStatus("error");
+      return recordValidationError(err, provider, meta, config, index, cacheKey);
+    }
+    const calibrated = config.calibrator.apply(distribution);
+    const result = applyThresholds(calibrated, config.thresholds, config.space);
+    return finalizeOutcome(result, calibrated, provider, meta, isLastProvider, span);
   } catch (err) {
-    return recordValidationError(err, provider, meta, config, index, cacheKey);
+    span.recordException(err);
+    span.setStatus("error");
+    throw err;
+  } finally {
+    span.end();
   }
-  const calibrated = config.calibrator.apply(distribution);
-  const result = applyThresholds(calibrated, config.thresholds, config.space);
+}
+function finalizeOutcome(result, calibrated, provider, meta, isLastProvider, span) {
   if (result.kind === "classified") {
     const verdict = {
       kind: "classified",
@@ -766,6 +968,10 @@ async function attemptProvider(provider, formattedInput, config, meta, userSigna
       probability: result.probability,
       meta: buildMeta(meta, provider)
     };
+    span.setAttribute("domovoi.verdict.kind", verdict.kind);
+    span.setAttribute("domovoi.verdict.value", verdict.value);
+    span.setAttribute("domovoi.verdict.probability", verdict.probability);
+    span.setStatus("ok");
     return { kind: "verdict", verdict };
   }
   if (result.kind === "out_of_distribution") {
@@ -779,6 +985,8 @@ async function attemptProvider(provider, formattedInput, config, meta, userSigna
       },
       meta: buildMeta(meta, provider)
     };
+    span.setAttribute("domovoi.verdict.kind", verdict.kind);
+    span.setStatus("ok");
     return { kind: "verdict", verdict };
   }
   if (isLastProvider) {
@@ -790,8 +998,13 @@ async function attemptProvider(provider, formattedInput, config, meta, userSigna
       distribution: calibrated,
       meta: buildMeta(meta, provider)
     };
+    span.setAttribute("domovoi.verdict.kind", verdict.kind);
+    span.setAttribute("domovoi.verdict.probability", verdict.probability);
+    span.setStatus("ok");
     return { kind: "lastUncertain", verdict, calibrated };
   }
+  span.setAttribute("domovoi.verdict.kind", "continue");
+  span.setStatus("ok");
   return { kind: "continue", calibrated };
 }
 var cl100kSingleton;
@@ -1126,6 +1339,7 @@ function convertCause(cause) {
     case "predicate_rejected":
     case "provider_failure":
     case "budget_exhausted":
+    case "budget_exceeded":
     case "cancelled":
       return cause;
   }
@@ -1255,9 +1469,12 @@ var domovoi = {
   classify,
   boolean,
   classifier,
-  memoryCache
+  memoryCache,
+  scope,
+  bind,
+  currentScope
 };
 
-export { BudgetExhaustedError, ConfigError, DomovoiError, ProviderError, domovoi, filter, isClassified, isUncertain, isUnknown, match };
+export { BudgetExceededError, BudgetExhaustedError, ConfigError, DomovoiError, ProviderError, configureContextStorage, domovoi, filter, isClassified, isUncertain, isUnknown, match, resetContextStorage };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map