@turingpulse/sdk 1.0.1

package/src/fingerprint.ts

@@ -0,0 +1,421 @@
+/**
+ * Fingerprinting for workflow structure and change detection.
+ *
+ * The fingerprint builder captures a compact representation of every workflow
+ * run so the backend can automatically detect **8 change types** by comparing
+ * consecutive fingerprints:
+ *
+ *   1. structure          — node/edge additions or removals
+ *   2. config             — general configuration changes
+ *   3. prompt             — system prompt changes on LLM nodes
+ *   4. model_change       — LLM model identity or generation parameters changed
+ *   5. eval_config_change — evaluation / scoring / judging config changed
+ *   6. policy_change      — guardrail / safety / moderation config changed
+ *   7. graph_version_change — (detected server-side from graph_snapshot_id)
+ *   8. deploy             — (registered externally via CI/CD; not from fingerprint)
+ */
+
+import { createHash } from 'node:crypto';
+import { FORBIDDEN_KEYS } from './utils';
+
+function sortKeysDeep(obj: unknown, depth = 0): unknown {
+  if (depth > 20 || typeof obj !== 'object' || obj === null) return obj;
+  if (Array.isArray(obj)) return obj.map((v) => sortKeysDeep(v, depth + 1));
+  const sorted: Record<string, unknown> = {};
+  for (const k of Object.keys(obj as Record<string, unknown>).sort()) {
+    if (!FORBIDDEN_KEYS.has(k)) {
+      sorted[k] = sortKeysDeep((obj as Record<string, unknown>)[k], depth + 1);
+    }
+  }
+  return sorted;
+}
+
+function sha256hex(data: string): string {
+  try {
+    return createHash('sha256').update(data, 'utf8').digest('hex');
+  } catch {
+    let hash = 5381;
+    for (let i = 0; i < data.length; i++) {
+      hash = ((hash << 5) + hash + data.charCodeAt(i)) >>> 0;
+    }
+    return hash.toString(16).padStart(16, '0');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config key classification
+// ---------------------------------------------------------------------------
+
+const MODEL_CONFIG_KEYS = new Set([
+  // Identity (snake_case + camelCase across all providers)
+  'model', 'model_name', 'modelname', 'model_id', 'modelid',
+  // Generation parameters — snake_case
+  'temperature', 'top_p', 'top_k', 'max_tokens', 'max_output_tokens',
+  'frequency_penalty', 'presence_penalty',
+  'stop', 'stop_sequences',
+  'candidate_count', 'response_format', 'context_window', 'model_kwargs',
+  // Generation parameters — camelCase (JS SDKs, Bedrock, Google)
+  'maxtokens', 'maxoutputtokens', 'topp', 'topk',
+  'frequencypenalty', 'presencepenalty',
+  'stopsequences', 'candidatecount', 'responseformat',
+  'contextwindow', 'modelkwargs',
+  // Cohere aliases (p = top_p, k = top_k)
+  'p', 'k',
+]);
+
+const EVAL_CONFIG_KEYS = new Set([
+  'eval_model', 'eval_prompt', 'eval_criteria', 'eval_rubric',
+  'eval_config', 'eval_threshold', 'eval_type', 'eval_template',
+  'evaluation_model', 'evaluation_prompt', 'evaluation_criteria',
+  'scoring_rubric', 'scoring_model', 'scoring_prompt', 'scoring_criteria',
+  'judge_model', 'judge_prompt', 'judge_criteria', 'judge_config',
+  'grading_rubric', 'grading_model', 'grading_criteria',
+  'rubric', 'criteria', 'judge',
+]);
+
+const POLICY_CONFIG_KEYS = new Set([
+  'policy', 'policy_config', 'policy_rules', 'policy_model',
+  'guard', 'guardrail', 'guardrails', 'guard_config',
+  'guardrail_config', 'guardrail_rules',
+  'filter', 'content_filter', 'content_filter_config',
+  'moderation', 'moderation_config', 'moderation_model',
+  'safety', 'safety_config', 'safety_threshold',
+  'rate_limit', 'rate_limit_config',
+  'max_retries', 'timeout',
+]);
+
+/**
+ * Classify a config key into a hash category.
+ * Returns one of: "model", "eval", "policy", or "general".
+ */
+export function classifyConfigKey(key: string): string {
+  const lower = key.toLowerCase();
+
+  if (MODEL_CONFIG_KEYS.has(lower)) return 'model';
+  if (EVAL_CONFIG_KEYS.has(lower)) return 'eval';
+  if (POLICY_CONFIG_KEYS.has(lower)) return 'policy';
+
+  // Prefix-based fallback
+  if (/^(eval_|evaluation_|scoring_|judge_|grading_)/.test(lower)) return 'eval';
+  if (/^(policy_|guard|guardrail|filter_|moderation_|safety_)/.test(lower)) return 'policy';
+
+  return 'general';
+}
+
+/**
+ * Split a flat config object into categorised sub-objects.
+ */
+export function splitConfig(
+  config: Record<string, unknown>,
+): Record<string, Record<string, unknown>> {
+  const buckets: Record<string, Record<string, unknown>> = {};
+  for (const [key, value] of Object.entries(config)) {
+    const category = classifyConfigKey(key);
+    if (!buckets[category]) buckets[category] = {};
+    buckets[category][key] = value;
+  }
+  return buckets;
+}
+
+/**
+ * Configuration for fingerprinting and change detection.
+ */
+export interface FingerprintConfig {
+  /** Master switch for fingerprinting. Default: true */
+  enabled?: boolean;
+  /** Hash prompts for change detection. Default: true */
+  capturePrompts?: boolean;
+  /** Hash configs for change detection. Default: true */
+  captureConfigs?: boolean;
+  /** Track DAG structure and edges. Default: true */
+  captureStructure?: boolean;
+  /** Config keys to redact before hashing. Default: ["apiKey", "password", "secret"] */
+  sensitiveConfigKeys?: string[];
+  /** Send fingerprint asynchronously. Default: true */
+  sendAsync?: boolean;
+  /** Send fingerprint even if run fails. Default: true */
+  sendOnFailure?: boolean;
+}
+
+/**
+ * Default fingerprint configuration values.
+ */
+export const DEFAULT_FINGERPRINT_CONFIG: Required<FingerprintConfig> = {
+  enabled: true,
+  capturePrompts: true,
+  captureConfigs: true,
+  captureStructure: true,
+  sensitiveConfigKeys: ['apiKey', 'password', 'secret', 'token', 'key', 'credential'],
+  sendAsync: true,
+  sendOnFailure: true,
+};
+
+/**
+ * Fingerprint data to be sent to backend.
+ */
+export interface FingerprintData {
+  /** Hash of the overall workflow structure */
+  structure_hash: string;
+  /** Ordered sequence of node names */
+  node_sequence: string[];
+  /** Count of nodes by type: {"llm": 2, "tool": 1} */
+  node_types: Record<string, number>;
+  /** Per-node type mapping: {"my_llm_node": "llm", "my_tool_node": "tool"} */
+  node_type_mapping: Record<string, string>;
+  /** Parent->child edges: ["parent->child", ...] */
+  edges: string[];
+  /** Hash of each node's full config (backward compat) */
+  node_config_hashes: Record<string, string>;
+  /** Hash of each LLM node's prompt */
+  node_prompt_hashes: Record<string, string>;
+  /** Hash of model-identity + generation params per LLM node */
+  node_model_hashes: Record<string, string>;
+  /** Hash of evaluation/scoring config per node */
+  node_eval_config_hashes: Record<string, string>;
+  /** Hash of guardrail/safety/policy config per node */
+  node_policy_config_hashes: Record<string, string>;
+}
+
+/**
+ * Builds workflow fingerprints during execution.
+ * 
+ * This class collects information about nodes, their types, configs, and prompts
+ * during workflow execution to create a fingerprint that enables change detection.
+ * 
+ * @example
+ * ```typescript
+ * const builder = new FingerprintBuilder(config);
+ * builder.recordNode("chat_llm", "llm", { model: "gpt-4" }, "You are a helpful assistant");
+ * builder.recordNode("search_tool", "tool", { api: "google" });
+ * const fingerprint = builder.getFingerprint();
+ * ```
+ */
+export class FingerprintBuilder {
+  private config: Required<FingerprintConfig>;
+  private nodes: string[] = [];
+  private nodeTypes: Record<string, string> = {};
+  private nodeTypeCounts: Record<string, number> = {};
+  private edgeSet: Set<string> = new Set();
+  private parentStack: string[] = [];
+  private sensitiveKeysLower: Set<string>;
+
+  // Legacy combined config hash (backward compat)
+  private nodeConfigs: Record<string, string> = {};
+  private nodePrompts: Record<string, string> = {};
+
+  // Categorised config hashes
+  private nodeModelConfigs: Record<string, string> = {};
+  private nodeEvalConfigs: Record<string, string> = {};
+  private nodePolicyConfigs: Record<string, string> = {};
+
+  constructor(config: FingerprintConfig = {}) {
+    this.config = { ...DEFAULT_FINGERPRINT_CONFIG, ...config };
+    this.sensitiveKeysLower = new Set(
+      this.config.sensitiveConfigKeys.map((k) => k.toLowerCase())
+    );
+  }
+
+  /**
+   * Push a node onto the parent stack for edge tracking.
+   */
+  pushParent(nodeName: string): void {
+    this.parentStack.push(nodeName);
+  }
+
+  /**
+   * Pop the current parent from the stack.
+   */
+  popParent(): string | undefined {
+    return this.parentStack.pop();
+  }
+
+  /**
+   * Get the current parent node (top of stack).
+   */
+  currentParent(): string | undefined {
+    return this.parentStack.length > 0 ? this.parentStack[this.parentStack.length - 1] : undefined;
+  }
+
+  /**
+   * Record a node in the fingerprint.
+   *
+   * The config object is automatically split into categories (model, eval,
+   * policy, general) and hashed separately.  The combined hash is also
+   * retained for backward compatibility with older backend versions.
+   *
+   * @param name - Unique name for this node
+   * @param nodeType - Type of node (e.g., "llm", "tool", "function", "retriever")
+   * @param config - Configuration dict for the node (will be categorised and hashed)
+   * @param prompt - System prompt for LLM nodes (will be hashed)
+   */
+  recordNode(
+    name: string,
+    nodeType: string,
+    config?: unknown,
+    prompt?: string
+  ): void {
+    if (this.nodeTypes[name] !== undefined) {
+      return;
+    }
+
+    this.nodes.push(name);
+    this.nodeTypes[name] = nodeType;
+    this.nodeTypeCounts[nodeType] = (this.nodeTypeCounts[nodeType] || 0) + 1;
+
+    // Record edge from parent
+    if (this.config.captureStructure) {
+      const parent = this.currentParent();
+      if (parent) {
+        this.edgeSet.add(`${parent}->${name}`);
+      }
+    }
+
+    // Hash and store config (both combined and per-category)
+    if (this.config.captureConfigs && config !== undefined) {
+      const sanitized = this.sanitizeConfig(config);
+
+      // Legacy combined hash
+      this.nodeConfigs[name] = this.hashValue(sanitized);
+
+      // Categorised hashes
+      if (typeof sanitized === 'object' && sanitized !== null && !Array.isArray(sanitized)) {
+        const buckets = splitConfig(sanitized as Record<string, unknown>);
+        if (buckets.model) this.nodeModelConfigs[name] = this.hashValue(buckets.model);
+        if (buckets.eval) this.nodeEvalConfigs[name] = this.hashValue(buckets.eval);
+        if (buckets.policy) this.nodePolicyConfigs[name] = this.hashValue(buckets.policy);
+      }
+    }
+
+    // Hash and store prompt
+    if (this.config.capturePrompts && prompt !== undefined) {
+      this.nodePrompts[name] = this.hashValue(prompt);
+    }
+  }
+
+  /**
+   * Build and return the final fingerprint data.
+   */
+  getFingerprint(): FingerprintData {
+    const structureData = {
+      nodes: this.nodes,
+      node_types: this.nodeTypes,
+      edges: [...this.edgeSet],
+    };
+    const structureHash = this.hashValue(structureData);
+
+    return {
+      structure_hash: structureHash,
+      node_sequence: [...this.nodes],
+      node_types: { ...this.nodeTypeCounts },
+      node_type_mapping: { ...this.nodeTypes },
+      edges: [...this.edgeSet],
+      node_config_hashes: { ...this.nodeConfigs },
+      node_prompt_hashes: { ...this.nodePrompts },
+      node_model_hashes: { ...this.nodeModelConfigs },
+      node_eval_config_hashes: { ...this.nodeEvalConfigs },
+      node_policy_config_hashes: { ...this.nodePolicyConfigs },
+    };
+  }
+
+  /**
+   * Remove sensitive keys from config before hashing.
+   */
+  private sanitizeConfig(config: unknown, depth = 0): unknown {
+    if (depth > 20 || typeof config !== 'object' || config === null) {
+      return config;
+    }
+
+    if (Array.isArray(config)) {
+      return config.map((item) => this.sanitizeConfig(item, depth + 1));
+    }
+
+    const sanitized: Record<string, unknown> = Object.create(null);
+    for (const [key, value] of Object.entries(config as Record<string, unknown>)) {
+      if (FORBIDDEN_KEYS.has(key)) continue;
+      if (this.sensitiveKeysLower.has(key.toLowerCase())) {
+        sanitized[key] = '[REDACTED]';
+      } else if (typeof value === 'object' && value !== null) {
+        sanitized[key] = this.sanitizeConfig(value, depth + 1);
+      } else {
+        sanitized[key] = value;
+      }
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Hash a value using the configured algorithm.
+   */
+  private hashValue(value: unknown): string {
+    let data: string;
+    if (typeof value === 'string') {
+      data = value;
+    } else {
+      try {
+        data = JSON.stringify(sortKeysDeep(value));
+      } catch {
+        data = String(value);
+      }
+    }
+
+    return sha256hex(data).substring(0, 16);
+  }
+}
+
+/**
+ * Extract system prompt from a list of chat messages.
+ * 
+ * @param messages - List of message objects with 'role' and 'content' keys
+ * @returns The system prompt if found, otherwise undefined
+ */
+export function extractPromptFromMessages(
+  messages: Array<{ role?: string; content?: string | unknown[] }>
+): string | undefined {
+  if (!messages || !Array.isArray(messages)) {
+    return undefined;
+  }
+
+  for (const msg of messages) {
+    if (msg.role === 'system') {
+      const content = msg.content;
+      if (typeof content === 'string') {
+        return content;
+      } else if (Array.isArray(content)) {
+        // Handle structured content
+        const parts: string[] = [];
+        for (const part of content) {
+          if (typeof part === 'string') {
+            parts.push(part);
+          } else if (typeof part === 'object' && part !== null && 'text' in part) {
+            parts.push((part as { text: string }).text);
+          }
+        }
+        return parts.length > 0 ? parts.join(' ') : undefined;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract a subset of config keys from an object.
+ * 
+ * @param obj - Full object
+ * @param keys - Keys to extract
+ * @returns Object with only the specified keys that exist
+ */
+export function extractConfigSubset(
+  obj: Record<string, unknown>,
+  keys: string[]
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const key of keys) {
+    if (key in obj && obj[key] !== undefined) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+

package/src/governance.ts

@@ -0,0 +1,156 @@
+import { TuringPulseConfig } from './config';
+import { ExecutionContext } from './context';
+import { TuringPulseHttpClient } from './http';
+import { KPIResult, kpiMetadata } from './kpi';
+import { safeErrorMessage } from './utils';
+
+export type GovernanceMode = 'hitl' | 'hatl' | 'hotl';
+
+export interface GovernanceDirectiveOptions {
+  hitl?: boolean;
+  hatl?: boolean;
+  hotl?: boolean;
+  reviewers?: string[];
+  escalationChannels?: string[];
+  title?: string;
+  notes?: string;
+  metadata?: Record<string, string>;
+  severity?: string;
+  /** Escalation timeout — enforced by the backend, not the SDK. */
+  autoEscalateAfterSeconds?: number;
+  taskPrefix?: string;
+}
+
+export class GovernanceDirective {
+  readonly hitl: boolean;
+  readonly hatl: boolean;
+  readonly hotl: boolean;
+  readonly reviewers: string[];
+  readonly escalationChannels: string[];
+  readonly title?: string;
+  readonly notes?: string;
+  readonly metadata: Record<string, string>;
+  readonly severity: string;
+  readonly autoEscalateAfterSeconds?: number;
+  readonly taskPrefix?: string;
+
+  constructor(options: GovernanceDirectiveOptions = {}) {
+    this.hitl = Boolean(options.hitl);
+    this.hatl = Boolean(options.hatl);
+    this.hotl = Boolean(options.hotl);
+    this.reviewers = options.reviewers ?? [];
+    this.escalationChannels = options.escalationChannels ?? [];
+    this.title = options.title;
+    this.notes = options.notes;
+    this.metadata = { ...(options.metadata ?? {}) };
+    this.severity = options.severity ?? 'medium';
+    this.autoEscalateAfterSeconds = options.autoEscalateAfterSeconds;
+    this.taskPrefix = options.taskPrefix;
+  }
+
+  modes(): GovernanceMode[] {
+    const modes: GovernanceMode[] = [];
+    if (this.hitl) modes.push('hitl');
+    if (this.hatl) modes.push('hatl');
+    if (this.hotl) modes.push('hotl');
+    return modes;
+  }
+}
+
+export interface GovernanceTaskResult {
+  mode: GovernanceMode;
+  taskId?: string;
+}
+
+export class GovernanceManager {
+  constructor(private readonly client: TuringPulseHttpClient, private readonly config: TuringPulseConfig) {}
+
+  async enforce(
+    directive: GovernanceDirective | undefined,
+    context: ExecutionContext,
+    kpiResults: KPIResult[],
+  ): Promise<GovernanceTaskResult[]> {
+    if (!directive) {
+      return [];
+    }
+    const metadata = this.buildMetadata(directive, context, kpiResults);
+    const tasks: GovernanceTaskResult[] = [];
+    for (const mode of directive.modes()) {
+      const payload = this.buildTaskPayload(mode, directive, context, metadata);
+      try {
+        const taskId = await this.client.createTask(payload);
+        tasks.push({ mode, taskId });
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn(`Failed to create governance task for ${mode}:`, safeErrorMessage(error));
+      }
+    }
+    return tasks;
+  }
+
+  private buildMetadata(
+    directive: GovernanceDirective,
+    context: ExecutionContext,
+    kpiResults: KPIResult[],
+  ): Record<string, string> {
+    const metadata: Record<string, string> = {
+      ...this.config.governanceDefaults.metadata,
+      ...directive.metadata,
+      severity: directive.severity || this.config.governanceDefaults.severity,
+      'agent.run_id': context.runId,
+      'agent.operation': context.operation,
+      'agent.hidden_entrypoint': String(context.hiddenEntrypoint),
+    };
+    for (const result of kpiResults) {
+      Object.assign(metadata, kpiMetadata(result));
+    }
+    return metadata;
+  }
+
+  private buildTaskPayload(
+    mode: GovernanceMode,
+    directive: GovernanceDirective,
+    context: ExecutionContext,
+    metadata: Record<string, string>,
+  ): Record<string, unknown> {
+    const title = directive.title ?? `${mode.toUpperCase()} review for ${context.operation}`;
+    const taskIdPrefix = directive.taskPrefix ?? context.runId;
+    const reviewers = directive.reviewers.length ? directive.reviewers : this.config.governanceDefaults.reviewers;
+    const channels = directive.escalationChannels.length
+      ? directive.escalationChannels
+      : this.config.governanceDefaults.escalationChannels;
+
+    return {
+      taskId: `${taskIdPrefix}-${mode}`,
+      title,
+      status: defaultTaskStatus(mode),
+      agentRunId: context.runId,
+      hitlRequired: mode === 'hitl',
+      metadata: {
+        ...metadata,
+        'governance.mode': mode,
+        'governance.reviewers': reviewers.join(','),
+        'governance.channels': channels.join(','),
+        ...(directive.notes ? { 'governance.notes': directive.notes } : {}),
+        ...((directive.autoEscalateAfterSeconds ?? this.config.governanceDefaults.autoEscalateAfterSeconds) != null
+          ? {
+              'governance.auto_escalate_after_seconds': String(
+                directive.autoEscalateAfterSeconds ?? this.config.governanceDefaults.autoEscalateAfterSeconds,
+              ),
+            }
+          : {}),
+      },
+    };
+  }
+}
+
+function defaultTaskStatus(mode: GovernanceMode): string {
+  switch (mode) {
+    case 'hitl':
+      return 'needs_human';
+    case 'hotl':
+      return 'in_progress';
+    default:
+      return 'todo';
+  }
+}