@attest-ai/core 1.0.0-rc.1 → 1.0.0-rc.2

package/dist/esm/index.js

@@ -12,6 +12,8 @@ var REASON_PROVIDER_NOT_CONFIGURED = "provider_not_configured";
 var REASON_SIMULATION = "simulation";
 var REASON_MISSING_EVIDENCE = "missing_evidence";
 var REASON_SHORT_CIRCUITED = "short_circuited";
+var REASON_BUDGET_EXHAUSTED = "budget_exhausted";
+var REASON_JUDGE_ABSTAINED = "judge_abstained";
 var OUTCOME_PASS = "pass";
 var OUTCOME_FAIL = "fail";
 var OUTCOME_SKIP = "skip";
@@ -102,6 +104,12 @@ var ProtocolDesyncError = class extends Error {
     this.diagnostics = diagnostics;
   }
 };
+var OTLPConversionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OTLPConversionError";
+  }
+};
 
 // src/proto/diagnostics.ts
 var DEFAULT_BUFFER_SIZE = 32;
@@ -208,8 +216,8 @@ function extractId(response) {
 }
 
 // src/version.ts
-var VERSION = "1.0.0-rc.1";
-var ENGINE_VERSION = "1.0.0-rc.1";
+var VERSION = "1.0.0-rc.2";
+var ENGINE_VERSION = "1.0.0-rc.2";
 
 // src/engine-manager.ts
 import { spawn, spawnSync } from "child_process";
@@ -602,6 +610,76 @@ function resetConfig() {
   _sampleRate = 0;
 }
 
+// src/usage.ts
+var INT_FIELDS = [
+  "model_calls",
+  "judge_calls",
+  "input_tokens",
+  "output_tokens",
+  "cached_tokens",
+  "unpriced_calls",
+  "budget_refused"
+];
+var USD_FIELDS = ["cost_usd", "retry_cost_usd"];
+function zeroUsage() {
+  return {
+    model_calls: 0,
+    judge_calls: 0,
+    input_tokens: 0,
+    output_tokens: 0,
+    cached_tokens: 0,
+    cost_usd: 0,
+    retry_cost_usd: 0,
+    unpriced_calls: 0,
+    budget_refused: 0
+  };
+}
+function addUsage(a, b) {
+  return {
+    model_calls: a.model_calls + b.model_calls,
+    judge_calls: a.judge_calls + b.judge_calls,
+    input_tokens: a.input_tokens + b.input_tokens,
+    output_tokens: a.output_tokens + b.output_tokens,
+    cached_tokens: a.cached_tokens + b.cached_tokens,
+    cost_usd: a.cost_usd + b.cost_usd,
+    retry_cost_usd: a.retry_cost_usd + b.retry_cost_usd,
+    unpriced_calls: a.unpriced_calls + b.unpriced_calls,
+    budget_refused: a.budget_refused + b.budget_refused
+  };
+}
+function sumUsage(usages) {
+  let total = zeroUsage();
+  for (const u of usages) total = addUsage(total, u);
+  return total;
+}
+function parseUsage(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError(`evaluate_batch result: usage must be an object, got ${JSON.stringify(raw)}`);
+  }
+  const obj = raw;
+  const field = (name, integer) => {
+    const v = obj[name];
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0 || integer && !Number.isInteger(v)) {
+      const kind = integer ? "a non-negative integer" : "a non-negative number";
+      throw new TypeError(`evaluate_batch result: usage.${name} must be ${kind}, got ${JSON.stringify(v)}`);
+    }
+    return v;
+  };
+  const ints = Object.fromEntries(INT_FIELDS.map((f) => [f, field(f, true)]));
+  const usd = Object.fromEntries(USD_FIELDS.map((f) => [f, field(f, false)]));
+  return { ...ints, ...usd };
+}
+function formatUsage(u) {
+  let line = `${u.model_calls} model calls \xB7 ${u.input_tokens + u.output_tokens} tokens (${u.cached_tokens} cached) \xB7 $${u.cost_usd.toFixed(4)} \xB7 retry cost $${u.retry_cost_usd.toFixed(4)}`;
+  if (u.budget_refused > 0) line += ` \xB7 ${u.budget_refused} calls refused by budget`;
+  if (u.unpriced_calls > 0) line += ` \xB7 ${u.unpriced_calls} unpriced calls not in $`;
+  return line;
+}
+function usageSummaryLine(u) {
+  if (u.model_calls === 0 && u.budget_refused === 0) return void 0;
+  return `attest usage: ${formatUsage(u)}`;
+}
+
 // src/client.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_DIAGNOSTIC_BUFFER = 32;
@@ -855,14 +933,15 @@ var AttestClient = class {
     }
     const params = {
       trace,
-      assertions: [...assertions]
+      assertions: [...assertions],
+      ...options?.budget !== void 0 ? { budget: options.budget } : {}
     };
     const raw = await this.sendRequest(
       "evaluate_batch",
       params,
       options?.timeout
     );
-    return raw;
+    return { ...raw, usage: parseUsage(raw["usage"]) };
   }
   async submitPluginResult(traceId2, pluginName, assertionId2, status, score, explanation, options) {
     const result = {
@@ -1050,11 +1129,14 @@ var AgentResult = class {
   assertionResults;
   totalCost;
   totalDurationMs;
-  constructor(trace, assertionResults = [], totalCost = 0, totalDurationMs = 0) {
+  /** Attest model usage of the evaluation that produced this result. */
+  usage;
+  constructor(trace, assertionResults = [], totalCost = 0, totalDurationMs = 0, usage = zeroUsage()) {
     this.trace = trace;
     this.assertionResults = assertionResults.map(normalizeAssertionResult);
     this.totalCost = totalCost;
     this.totalDurationMs = totalDurationMs;
+    this.usage = usage;
   }
   /** True if every assertion has status "pass". */
   get passed() {
@@ -1233,7 +1315,8 @@ function appendJudgeMetadata(lines, meta) {
     if (meta.rubric_version) {
       rubric = `${rubric} @ ${meta.rubric_version}`;
     }
-    lines.push(`      judge:      ${meta.model} / ${rubric}`);
+    const judge = meta.provider ? `${meta.provider}/${meta.model}` : meta.model;
+    lines.push(`      judge:      ${judge} / ${rubric}`);
   }
   if (meta.prompt_hash) {
     lines.push(`      prompt:     #${meta.prompt_hash}`);
@@ -1757,6 +1840,86 @@ var ExpectChain = class {
       soft: opts?.soft ?? false
     });
   }
+  // -- Layer 3: Behavior contracts (tool calls only, retries counted) --
+  /**
+   * Assert how many times a tool is called, per value of argument `per` when set.
+   *
+   * @example
+   * ```ts
+   * // fails with "issue_refund called 2× for order_id=O-1042 (max 1)"
+   * expect(result).toolCardinality("issue_refund", { per: "order_id", atMost: 1 });
+   * ```
+   */
+  toolCardinality(tool, opts) {
+    if (opts.atMost === void 0 && opts.atLeast === void 0) {
+      throw new Error("toolCardinality needs atMost, atLeast or both");
+    }
+    const spec = { check: "tool_cardinality", tool };
+    if (opts.per !== void 0) spec.per = opts.per;
+    if (opts.atLeast !== void 0) spec.min = opts.atLeast;
+    if (opts.atMost !== void 0) spec.max = opts.atMost;
+    spec.soft = opts.soft ?? false;
+    return this.add(TYPE_TRACE, spec);
+  }
+  /**
+   * Assert the tool-call trajectory matches `tools`: `strict` (same sequence,
+   * the default), `unordered` (same calls, any order), `subset` (no call
+   * outside `tools`) or `superset` (every call in `tools` made). Use
+   * {@link trajectoryPartialOrder} for ordering constraints.
+   */
+  trajectory(tools, opts) {
+    return this.add(TYPE_TRACE, {
+      check: "trajectory",
+      mode: opts?.mode ?? "strict",
+      tools,
+      soft: opts?.soft ?? false
+    });
+  }
+  /**
+   * Assert every tool in `tools` and `order` is called and each
+   * `[before, after]` pair holds as in {@link toolCalledBefore}.
+   */
+  trajectoryPartialOrder(order, opts) {
+    const spec = {
+      check: "trajectory",
+      mode: "partial_order",
+      order: order.map(([before, after]) => [before, after])
+    };
+    if (opts?.tools !== void 0) spec.tools = opts.tools;
+    spec.soft = opts?.soft ?? false;
+    return this.add(TYPE_TRACE, spec);
+  }
+  /** Assert every call to `after` has an earlier call to `before`; holds when `after` is never called. */
+  toolCalledBefore(before, after, opts) {
+    return this.add(TYPE_TRACE, { check: "tool_order", before, after, soft: opts?.soft ?? false });
+  }
+  /** Assert no block of `period` (1–4) tool calls repeats `minRepeats` (default 2) times in a row; A→B→A→B fails period 2. */
+  noToolCycles(period, opts) {
+    return this.add(TYPE_TRACE, {
+      check: "cycle",
+      period,
+      min_repeats: opts?.minRepeats ?? 2,
+      soft: opts?.soft ?? false
+    });
+  }
+  /** Assert at most `maxStreak` consecutive tool calls end in error (trace v2). */
+  maxToolFailureStreak(maxStreak, opts) {
+    return this.add(TYPE_TRACE, { check: "failure_streak", max: maxStreak, soft: opts?.soft ?? false });
+  }
+  /**
+   * Assert every call to `tool` has argument `arg` (a dot path) satisfying
+   * `op value`; holds when `tool` is never called.
+   */
+  toolArgSatisfies(tool, arg, op, value, opts) {
+    return this.add(TYPE_TRACE, {
+      check: "arg_predicate",
+      tool,
+      arg,
+      op,
+      value,
+      soft: opts?.soft ?? false
+    });
+  }
   // -- Layer 4: Content --
   /**
    * Assert the output message contains the given string.
@@ -2927,119 +3090,113 @@ var OllamaAdapter = class {
 };
 
 // src/adapters/otel.ts
+import { spawnSync as spawnSync2 } from "child_process";
+var CONVERT_TIMEOUT_MS = 6e4;
+var MAX_TRACE_OUTPUT_BYTES = 64 * 1024 * 1024;
+var STATUS_CODE_ERROR = 2;
 var OTelAdapter = class _OTelAdapter {
-  agentId;
-  constructor(agentId2) {
-    this.agentId = agentId2;
-  }
-  static fromSpans(spans, agentId2) {
-    const adapter = new _OTelAdapter(agentId2);
-    return adapter.buildTrace(spans);
+  /**
+   * Build a trace from finished OpenTelemetry spans of one trace.
+   *
+   * @param agentId Trace `agent_id`; defaults to the first turn's `gen_ai.agent.name`.
+   * @throws OTLPConversionError when the engine rejects the spans.
+   */
+  static async fromSpans(spans, agentId2) {
+    return _OTelAdapter.fromOtlp(spansToOtlp(spans), agentId2);
   }
-  buildTrace(spans) {
-    const sorted = [...spans].sort((a, b) => {
-      const aTime = a.startTime[0] * 1e9 + a.startTime[1];
-      const bTime = b.startTime[0] * 1e9 + b.startTime[1];
-      return aTime - bTime;
+  /**
+   * Convert an OTLP/JSON export (`resourceSpans` → `scopeSpans` → `spans`).
+   *
+   * @param agentId Trace `agent_id`; defaults to the first turn's `gen_ai.agent.name`.
+   * @throws OTLPConversionError when the engine rejects the export (malformed JSON, invalid
+   *   ids or timestamps, more than one trace, non-numeric token counts, ...).
+   * @throws RangeError when a parsed export holds a non-finite number.
+   * @throws OTLPConversionError when the engine times out, overflows the output buffer or
+   *   prints no trace.
+   * @throws Error from `spawnSync` when the engine cannot start.
+   */
+  static async fromOtlp(otlp, agentId2) {
+    const payload = typeof otlp === "string" || otlp instanceof Uint8Array ? otlp : JSON.stringify(otlp, (_key, v) => {
+      if (typeof v === "number" && !Number.isFinite(v)) {
+        throw new RangeError(`OTLP export holds a non-finite number: ${String(v)}`);
+      }
+      return v;
     });
-    const builder = new TraceBuilder(this.agentId);
-    const rootSpan = this.findRootSpan(sorted);
-    if (rootSpan) {
-      const traceId2 = rootSpan.spanContext().traceId;
-      if (traceId2) {
-        builder.setTraceId(`otel_${traceId2.slice(0, 16)}`);
+    const args = ["trace", "convert"];
+    if (agentId2 !== void 0) args.push("--agent-id", agentId2);
+    args.push("-");
+    const proc = spawnSync2(await resolveEngine(), args, {
+      input: payload,
+      timeout: CONVERT_TIMEOUT_MS,
+      maxBuffer: MAX_TRACE_OUTPUT_BYTES
+    });
+    if (proc.error) {
+      const code = proc.error.code;
+      if (code === "ETIMEDOUT") {
+        throw new OTLPConversionError(
+          `attest-engine trace convert timed out after ${CONVERT_TIMEOUT_MS / 1e3}s`
+        );
       }
-    }
-    let outputMessage = "";
-    let totalTokens;
-    let latencyMs;
-    let model;
-    for (const span of sorted) {
-      const attrs = span.attributes ?? {};
-      const stepType = this.classifySpan(attrs, span.name);
-      if (stepType === "llm_call") {
-        const [stepArgs, stepResult] = this.extractLlmStep(attrs);
-        builder.addLlmCall(span.name, {
-          args: stepArgs,
-          result: stepResult,
-          metadata: this.spanMetadata(span)
-        });
-        const completion = attrs["gen_ai.completion"];
-        if (completion) outputMessage = String(completion);
-        const inputTokens = Number(attrs["gen_ai.usage.input_tokens"] ?? 0);
-        const outputTokens = Number(attrs["gen_ai.usage.output_tokens"] ?? 0);
-        const spanTokens = inputTokens + outputTokens;
-        if (spanTokens > 0) totalTokens = (totalTokens ?? 0) + spanTokens;
-        if (model === void 0) {
-          const responseModel = attrs["gen_ai.response.model"];
-          const requestModel = attrs["gen_ai.request.model"];
-          if (responseModel) model = String(responseModel);
-          else if (requestModel) model = String(requestModel);
-        }
-      } else if (stepType === "tool_call") {
-        const [stepArgs, stepResult] = this.extractToolStep(attrs);
-        const toolName = String(attrs["gen_ai.tool.name"] ?? span.name);
-        builder.addToolCall(toolName, {
-          args: stepArgs,
-          result: stepResult,
-          metadata: this.spanMetadata(span)
-        });
+      if (code === "ENOBUFS") {
+        throw new OTLPConversionError(
+          `attest-engine trace convert printed more than ${MAX_TRACE_OUTPUT_BYTES} bytes`
+        );
       }
+      throw proc.error;
     }
-    if (rootSpan) {
-      const startNs = rootSpan.startTime[0] * 1e9 + rootSpan.startTime[1];
-      const endNs = rootSpan.endTime[0] * 1e9 + rootSpan.endTime[1];
-      latencyMs = Math.floor((endNs - startNs) / 1e6);
+    if (proc.status !== 0) {
+      const message = proc.stderr.toString("utf8").trim();
+      throw new OTLPConversionError(
+        message || `attest-engine trace convert exited ${String(proc.status ?? proc.signal)}`
+      );
     }
-    builder.setOutput({ message: outputMessage });
-    builder.setMetadata({ total_tokens: totalTokens, latency_ms: latencyMs, model });
-    return builder.build();
-  }
-  findRootSpan(spans) {
-    for (const span of spans) {
-      if (!span.parentSpanId) return span;
+    try {
+      return JSON.parse(proc.stdout.toString("utf8"));
+    } catch (err) {
+      throw new OTLPConversionError(
+        `attest-engine trace convert printed output that is not JSON: ${String(err)}`
+      );
     }
-    return spans[0];
   }
-  classifySpan(attrs, name) {
-    const op = String(attrs["gen_ai.operation.name"] ?? "");
-    if (op === "chat" || op === "completion" || op === "generate_content" || "gen_ai.completion" in attrs) {
-      return "llm_call";
-    }
-    if (op === "tool" || "gen_ai.tool.name" in attrs) {
-      return "tool_call";
-    }
-    const lower = name.toLowerCase();
-    if (lower.includes("completion") || lower.includes("chat")) return "llm_call";
-    if (lower.includes("tool")) return "tool_call";
-    return void 0;
+};
+function hrTimeToNanos(time, spanName) {
+  if (!Number.isSafeInteger(time[0]) || !Number.isSafeInteger(time[1])) {
+    throw new RangeError(`span ${JSON.stringify(spanName)} has a non-integer HrTime`);
   }
-  extractLlmStep(attrs) {
-    const args = {};
-    const result = {};
-    if ("gen_ai.request.model" in attrs) args.model = String(attrs["gen_ai.request.model"]);
-    if ("gen_ai.system" in attrs) args.system = String(attrs["gen_ai.system"]);
-    if ("gen_ai.prompt" in attrs) args.prompt = String(attrs["gen_ai.prompt"]);
-    if ("gen_ai.completion" in attrs) result.completion = String(attrs["gen_ai.completion"]);
-    if ("gen_ai.usage.input_tokens" in attrs) result.input_tokens = Number(attrs["gen_ai.usage.input_tokens"]);
-    if ("gen_ai.usage.output_tokens" in attrs) result.output_tokens = Number(attrs["gen_ai.usage.output_tokens"]);
-    if ("gen_ai.response.model" in attrs) result.model = String(attrs["gen_ai.response.model"]);
-    return [args, result];
-  }
-  extractToolStep(attrs) {
-    const args = {};
-    const result = {};
-    if ("gen_ai.tool.call.id" in attrs) args.call_id = String(attrs["gen_ai.tool.call.id"]);
-    if ("gen_ai.tool.parameters" in attrs) args.parameters = attrs["gen_ai.tool.parameters"];
-    if ("gen_ai.tool.output" in attrs) result.output = attrs["gen_ai.tool.output"];
-    return [args, result];
-  }
-  spanMetadata(span) {
-    const startNs = span.startTime[0] * 1e9 + span.startTime[1];
-    const endNs = span.endTime[0] * 1e9 + span.endTime[1];
-    return { duration_ms: Math.floor((endNs - startNs) / 1e6) };
+  return (BigInt(time[0]) * 1000000000n + BigInt(time[1])).toString();
+}
+function anyValue(value) {
+  if (value === null || value === void 0) return {};
+  if (typeof value === "boolean") return { boolValue: value };
+  if (typeof value === "string") return { stringValue: value };
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`OTel attribute value must be finite, got ${String(value)}`);
+    }
+    return Number.isSafeInteger(value) ? { intValue: String(value) } : { doubleValue: value };
   }
-};
+  return { arrayValue: { values: value.map((v) => anyValue(v)) } };
+}
+function spansToOtlp(spans) {
+  const encoded = spans.map((span) => {
+    const ctx = span.spanContext();
+    const out = {
+      traceId: ctx.traceId,
+      spanId: ctx.spanId,
+      name: span.name,
+      startTimeUnixNano: hrTimeToNanos(span.startTime, span.name),
+      endTimeUnixNano: hrTimeToNanos(span.endTime, span.name),
+      attributes: Object.entries(span.attributes ?? {}).filter(([, v]) => v !== void 0).map(([key, v]) => ({ key, value: anyValue(v) }))
+    };
+    const parent = span.parentSpanContext?.spanId ?? span.parentSpanId;
+    if (parent) out["parentSpanId"] = parent;
+    if (span.status?.code === STATUS_CODE_ERROR) {
+      out["status"] = { code: STATUS_CODE_ERROR, message: span.status.message ?? "" };
+    }
+    return out;
+  });
+  return { resourceSpans: [{ scopeSpans: [{ spans: encoded }] }] };
+}
 
 // src/adapters/langchain.ts
 var LangChainAdapter = class {
@@ -3162,6 +3319,7 @@ export {
   GeminiAdapter,
   LangChainAdapter,
   ManualAdapter,
+  OTLPConversionError,
   OTelAdapter,
   OUTCOME_FAIL,
   OUTCOME_PASS,
@@ -3172,6 +3330,8 @@ export {
   ProtocolDesyncError,
   ProtocolDiagnosticBuffer,
   ProtocolError,
+  REASON_BUDGET_EXHAUSTED,
+  REASON_JUDGE_ABSTAINED,
   REASON_MISSING_EVIDENCE,
   REASON_PROVIDER_NOT_CONFIGURED,
   REASON_PROVIDER_UNAVAILABLE,
@@ -3201,6 +3361,7 @@ export {
   TraceTree,
   VERSION,
   activeBuilder,
+  addUsage,
   agent,
   agentId,
   assertionId,
@@ -3213,11 +3374,13 @@ export {
   executePluginAssertion,
   extractId,
   extractResult,
+  formatUsage,
   getSampleRate,
   isSimulationMode,
   layerForType,
   loadLabelsCSV,
   loadLabelsJSONL,
+  parseUsage,
   previewLine,
   promptHash,
   renderAssertionFailure,
@@ -3226,7 +3389,10 @@ export {
   requireSimulationCapability,
   resetConfig,
   simulationEnvEnabled,
+  sumUsage,
   tier,
-  traceId
+  traceId,
+  usageSummaryLine,
+  zeroUsage
 };
 //# sourceMappingURL=index.js.map