@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/adapters/llm/anthropic-direct.ts

@@ -8,6 +8,8 @@
  */
 
 import Anthropic from "@anthropic-ai/sdk";
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   ChatRequest,
   ChatResponse,
@@ -16,6 +18,11 @@ import type {
   StreamDelta,
 } from "../../ports/llm-provider.js";
 
+const ADAPTER_TRACER = trace.getTracer(
+  "vauban-agent-sdk.llm.anthropic",
+  "0.1.0"
+);
+
 export interface AnthropicDirectAdapterConfig {
   apiKey: string;
   /** Default model to use when ChatRequest.model is not specified. */
@@ -70,6 +77,50 @@ export class AnthropicDirectAdapter implements LLMProviderPort {
   }
 
   async complete(req: ChatRequest): Promise<ChatResponse> {
+    return ADAPTER_TRACER.startActiveSpan(
+      "llm-provider.complete",
+      {
+        attributes: {
+          "gen_ai.system": "anthropic",
+          "gen_ai.request.model": req.model ?? this.defaultModel,
+          "gen_ai.request.message_count": req.messages.length,
+          "vauban.port.name": "llm-provider",
+          "vauban.port.impl": "AnthropicDirectAdapter",
+        },
+      },
+      async (span: Span): Promise<ChatResponse> => {
+        try {
+          const response: ChatResponse = await this._doComplete(req);
+          span.setAttributes({
+            "gen_ai.usage.input_tokens": response.usage.inputTokens,
+            "gen_ai.usage.output_tokens": response.usage.outputTokens,
+            "gen_ai.response.model": response.model,
+            "gen_ai.response.finish_reasons": [response.finishReason],
+          });
+          if (response.usage.costUsd !== undefined) {
+            span.setAttribute("gen_ai.usage.cost_usd", response.usage.costUsd);
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          return response;
+        } catch (_err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "span wrapper caught exception",
+          });
+          return {
+            content: "",
+            usage: { inputTokens: 0, outputTokens: 0 },
+            model: req.model ?? this.defaultModel,
+            finishReason: "error" as const,
+          };
+        } finally {
+          span.end();
+        }
+      }
+    );
+  }
+
+  private async _doComplete(req: ChatRequest): Promise<ChatResponse> {
     const model = req.model ?? this.defaultModel;
 
     // Extract system message (Anthropic API separates system from messages)

package/src/adapters/llm/cascade.ts

@@ -12,6 +12,8 @@
  * BYOM: no default model hardcoded.
  */
 
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   ChatRequest,
   ChatResponse,
@@ -19,6 +21,8 @@ import type {
   StreamDelta,
 } from "../../ports/llm-provider.js";
 
+const ADAPTER_TRACER = trace.getTracer("vauban-agent-sdk.llm.cascade", "0.1.0");
+
 const ALL_FAIL_RESPONSE: ChatResponse = {
   content: "",
   usage: { inputTokens: 0, outputTokens: 0 },
@@ -51,26 +55,67 @@ export class CascadeAdapter implements LLMProviderPort {
   }
 
   async complete(req: ChatRequest): Promise<ChatResponse> {
-    for (const provider of this.providers) {
-      if (req.abortSignal?.aborted) {
-        return { ...ALL_FAIL_RESPONSE };
-      }
-
-      let response: ChatResponse;
-      try {
-        response = await provider.complete(req);
-      } catch {
-        // Unexpected throw — treat as failure, try next
-        continue;
-      }
-
-      if (response.finishReason !== "error") {
-        return response;
+    return ADAPTER_TRACER.startActiveSpan(
+      "llm-provider.complete",
+      {
+        attributes: {
+          "gen_ai.system": "cascade",
+          "gen_ai.request.model": req.model ?? "cascade",
+          "gen_ai.request.message_count": req.messages.length,
+          "vauban.port.name": "llm-provider",
+          "vauban.port.impl": "CascadeAdapter",
+          "vauban.cascade.provider_count": this.providers.length,
+        },
+      },
+      async (span: Span) => {
+        try {
+          let attemptCount = 0;
+          for (const provider of this.providers) {
+            attemptCount++;
+            if (req.abortSignal?.aborted) {
+              span.setAttribute("vauban.cascade.attempts", attemptCount);
+              span.setStatus({ code: SpanStatusCode.OK });
+              return { ...ALL_FAIL_RESPONSE };
+            }
+
+            let response: ChatResponse;
+            try {
+              response = await provider.complete(req);
+            } catch {
+              // Unexpected throw — treat as failure, try next
+              continue;
+            }
+
+            if (response.finishReason !== "error") {
+              span.setAttribute("vauban.cascade.attempts", attemptCount);
+              span.setAttributes({
+                "gen_ai.usage.input_tokens": response.usage.inputTokens,
+                "gen_ai.usage.output_tokens": response.usage.outputTokens,
+                "gen_ai.response.model": response.model,
+                "gen_ai.response.finish_reasons": [response.finishReason],
+              });
+              span.setStatus({ code: SpanStatusCode.OK });
+              return response;
+            }
+            // finishReason === "error" → try next provider
+          }
+          span.setAttribute("vauban.cascade.attempts", attemptCount);
+          span.setAttribute("vauban.cascade.all_failed", true);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "all providers failed",
+          });
+          return { ...ALL_FAIL_RESPONSE };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+          if (err instanceof Error) span.recordException(err);
+          return { ...ALL_FAIL_RESPONSE };
+        } finally {
+          span.end();
+        }
       }
-      // finishReason === "error" → try next provider
-    }
-
-    return { ...ALL_FAIL_RESPONSE };
+    );
   }
 
   async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {

package/src/adapters/llm/litellm.ts

@@ -9,6 +9,8 @@
  * No model string is hardcoded at module scope.
  */
 
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   ChatRequest,
   ChatResponse,
@@ -17,6 +19,8 @@ import type {
   StreamDelta,
 } from "../../ports/llm-provider.js";
 
+const ADAPTER_TRACER = trace.getTracer("vauban-agent-sdk.llm.litellm", "0.1.0");
+
 export interface LiteLLMAdapterConfig {
   baseUrl: string;
   apiKey?: string;
@@ -103,6 +107,51 @@ export class LiteLLMAdapter implements LLMProviderPort {
   }
 
   async complete(req: ChatRequest): Promise<ChatResponse> {
+    return ADAPTER_TRACER.startActiveSpan(
+      "llm-provider.complete",
+      {
+        attributes: {
+          "gen_ai.system": "litellm",
+          "gen_ai.request.model": req.model ?? this.defaultModel,
+          "gen_ai.request.message_count": req.messages.length,
+          "vauban.port.name": "llm-provider",
+          "vauban.port.impl": "LiteLLMAdapter",
+        },
+      },
+      async (span: Span): Promise<ChatResponse> => {
+        try {
+          const response: ChatResponse = await this._doComplete(req);
+          span.setAttributes({
+            "gen_ai.usage.input_tokens": response.usage.inputTokens,
+            "gen_ai.usage.output_tokens": response.usage.outputTokens,
+            "gen_ai.response.model": response.model,
+            "gen_ai.response.finish_reasons": [response.finishReason],
+          });
+          if (response.usage.costUsd !== undefined) {
+            span.setAttribute("gen_ai.usage.cost_usd", response.usage.costUsd);
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+          return response;
+        } catch (_err) {
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: "span wrapper caught exception",
+          });
+          return {
+            content: "",
+            usage: { inputTokens: 0, outputTokens: 0 },
+            model: req.model ?? this.defaultModel,
+            finishReason: "error" as const,
+          };
+        } finally {
+          span.end();
+        }
+      }
+    );
+  }
+
+  /** Internal completion logic — extracted from complete() for span instrumentation. */
+  private async _doComplete(req: ChatRequest): Promise<ChatResponse> {
     const model = req.model ?? this.defaultModel;
     const body = {
       model,

package/src/compute/difficulty-estimator.ts

@@ -0,0 +1,111 @@
+/**
+ * src/compute/difficulty-estimator.ts
+ *
+ * Deterministic task-difficulty classifier + strategy recommender.
+ *
+ * NOT an LLM call — pure feature extraction + rule-based classification.
+ * Routes input difficulty → recommended compute strategy.
+ *
+ * @experimental Public-experimental API per `contract-stability.md` (sprint-582).
+ */
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export type DifficultyClass = "simple" | "standard" | "complex" | "reasoning";
+
+export interface TaskFeatures {
+  /** Character count of input. */
+  inputLength: number;
+  /** Input contains "step", "then", or "first…then" pattern. */
+  hasMultipleSteps: boolean;
+  /** Input contains "why", "explain", "reason", "prove", "deduce". */
+  requiresReasoning: boolean;
+  /** Input contains "create", "generate", "design", "imagine". */
+  requiresCreativity: boolean;
+  /** Input contains digits or math operators. */
+  hasNumerics: boolean;
+  /** Input references multiple entities ("A and B", "compare"). */
+  hasCrossReference: boolean;
+  /** Length of optional context/system prompt. */
+  contextLength: number;
+}
+
+// ─── Regex patterns (case-insensitive, word-bounded where useful) ───────────
+
+const RE_STEPS = /\b(step|steps|then|first|next|finally)\b/i;
+const RE_REASONING =
+  /\b(why|explain|explains|reason|reasons|prove|proves|deduce|deduces|infer|justify)\b/i;
+const RE_CREATIVITY = /\b(create|generate|design|imagine|invent|compose)\b/i;
+const RE_NUMERICS = /[0-9]|[+\-*/^=]/;
+const RE_CROSS_REF = /\b(compare|and|versus|vs\.?|both)\b/i;
+
+// ─── Feature extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract task features from input + optional context.
+ * Deterministic, side-effect free.
+ */
+export function extractFeatures(input: string, context?: string): TaskFeatures {
+  const inputLength = input.length;
+  const contextLength = context?.length ?? 0;
+
+  return {
+    inputLength,
+    hasMultipleSteps: RE_STEPS.test(input),
+    requiresReasoning: RE_REASONING.test(input),
+    requiresCreativity: RE_CREATIVITY.test(input),
+    hasNumerics: RE_NUMERICS.test(input),
+    hasCrossReference: RE_CROSS_REF.test(input),
+    contextLength,
+  };
+}
+
+// ─── Difficulty classification ───────────────────────────────────────────────
+
+/**
+ * Classify difficulty from task features.
+ *
+ * Decision tree (most specific first):
+ *   - requiresReasoning → "reasoning"
+ *   - inputLength > 500 OR hasMultipleSteps OR requiresCreativity → "complex"
+ *   - inputLength in [100, 500] OR hasNumerics → "standard"
+ *   - else → "simple"
+ */
+export function estimateDifficulty(features: TaskFeatures): DifficultyClass {
+  if (features.requiresReasoning) return "reasoning";
+  if (features.inputLength > 500 || features.hasMultipleSteps || features.requiresCreativity) {
+    return "complex";
+  }
+  if (features.inputLength >= 100 || features.hasNumerics) {
+    return "standard";
+  }
+  return "simple";
+}
+
+// ─── Strategy recommendation ─────────────────────────────────────────────────
+
+/**
+ * Recommend a compute strategy for a given difficulty class.
+ *
+ * Map (per Sprint A bench results + Sprint-582 spec):
+ *   simple     → single-shot
+ *   standard   → bon-mav
+ *   complex    → tree-of-thoughts
+ *   reasoning  → mixture-of-agents
+ */
+export function recommendStrategy(difficulty: DifficultyClass): string {
+  switch (difficulty) {
+    case "simple":
+      return "single-shot";
+    case "standard":
+      return "bon-mav";
+    case "complex":
+      return "tree-of-thoughts";
+    case "reasoning":
+      return "mixture-of-agents";
+    default: {
+      const _exhaustive: never = difficulty;
+      throw new Error(`recommendStrategy: unknown difficulty "${String(_exhaustive)}"`);
+    }
+  }
+}

package/src/compute/strategies/mixture-of-agents.ts

@@ -0,0 +1,150 @@
+/**
+ * src/compute/strategies/mixture-of-agents.ts
+ *
+ * Mixture-of-Agents (MoA) compute strategy.
+ *
+ * Reference: Wang et al. 2024, "Mixture of Agents", arXiv:2406.04692.
+ *
+ * Algorithm:
+ *   - L rounds (layers). Each round runs M proposers (independent parallel calls).
+ *   - After each round, an aggregator synthesizes the M outputs into ONE result.
+ *   - The synthesized result becomes the seed for the next round (currently
+ *     opaque to the generator — synthesis is purely on the output side; the
+ *     same input is used each round, but the aggregated state is returned).
+ *   - Final aggregated output is the answer.
+ *
+ * Budget: M × L total generator calls.
+ *
+ * Default aggregation:
+ *   - string outputs : concatenate with "\n---\n" then take first non-empty
+ *   - number outputs : median
+ *   - other          : first element
+ *
+ * @experimental Public-experimental API per `contract-stability.md` (sprint-582).
+ */
+
+import type { ComputeContext, Strategy, StrategyResult } from "../types.js";
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export interface MoAConfig<TOutput> {
+  /** Number of rounds (L). Default: 2. */
+  rounds: number;
+  /** Proposers per round (M). Default: 3. */
+  proposersPerRound: number;
+  /** Aggregation function: M outputs → 1 synthesized output. */
+  aggregate?: (outputs: TOutput[]) => TOutput;
+}
+
+const STRATEGY_NAME = "mixture-of-agents";
+
+// ─── Default aggregator ──────────────────────────────────────────────────────
+
+function defaultAggregator<T>(outputs: T[]): T {
+  if (outputs.length === 0) {
+    throw new Error("mixtureOfAgentsStrategy: aggregator called with 0 outputs");
+  }
+  const first = outputs[0];
+
+  // Strings: concat for traceability, then return first non-empty after concat header.
+  // Per spec: "if outputs are strings, concatenate with '\n---\n' prefix and take
+  // the first non-empty (simple but correct for MVP)."
+  if (typeof first === "string") {
+    const nonEmpty = outputs.find((o) => typeof o === "string" && (o as string).length > 0);
+    return (nonEmpty ?? first) as T;
+  }
+
+  // Numbers: median.
+  if (typeof first === "number") {
+    const nums = (outputs as unknown as number[]).filter((n) => Number.isFinite(n));
+    if (nums.length === 0) return first;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+    return median as unknown as T;
+  }
+
+  // Other types: return first (identity fallback).
+  return first;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : new DOMException("Aborted", "AbortError");
+  }
+}
+
+// ─── Strategy factory ────────────────────────────────────────────────────────
+
+/**
+ * Construct a Mixture-of-Agents {@link Strategy}.
+ *
+ * @throws RangeError when `rounds` or `proposersPerRound` < 1.
+ */
+export function mixtureOfAgentsStrategy<TInput, TOutput>(
+  config?: Partial<MoAConfig<TOutput>>,
+): Strategy<TInput, TOutput> {
+  const rounds = config?.rounds ?? 2;
+  const proposersPerRound = config?.proposersPerRound ?? 3;
+  const aggregate = config?.aggregate ?? defaultAggregator;
+
+  if (!Number.isInteger(rounds) || rounds < 1) {
+    throw new RangeError(`mixtureOfAgentsStrategy: rounds must be >=1, got ${rounds}`);
+  }
+  if (!Number.isInteger(proposersPerRound) || proposersPerRound < 1) {
+    throw new RangeError(
+      `mixtureOfAgentsStrategy: proposersPerRound must be >=1, got ${proposersPerRound}`,
+    );
+  }
+
+  return {
+    name: STRATEGY_NAME,
+
+    async run(
+      input: TInput,
+      generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>,
+      ctx: ComputeContext = {},
+    ): Promise<StrategyResult<TOutput>> {
+      const start = performance.now();
+      const signal = ctx.signal;
+      throwIfAborted(signal);
+
+      const childCtx: ComputeContext = signal ? { signal } : {};
+
+      let aggregated: TOutput | undefined;
+      let totalCalls = 0;
+
+      for (let r = 0; r < rounds; r++) {
+        throwIfAborted(signal);
+        const outputs = await Promise.all(
+          Array.from({ length: proposersPerRound }, () => generator(input, childCtx)),
+        );
+        totalCalls += proposersPerRound;
+        throwIfAborted(signal);
+        aggregated = aggregate(outputs);
+      }
+
+      const latency_ms = performance.now() - start;
+
+      if (aggregated === undefined) {
+        // Unreachable: rounds >= 1 guarantees aggregated is set.
+        throw new Error("mixtureOfAgentsStrategy: no aggregated result");
+      }
+
+      return {
+        result: aggregated,
+        metadata: {
+          strategy: STRATEGY_NAME,
+          candidates: totalCalls,
+          verifier_scores: [],
+          cost: { calls: totalCalls },
+          latency_ms,
+        },
+      };
+    },
+  };
+}