@turingpulse/sdk 1.0.1

package/scripts/bump-version.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "Usage: $0 <new-version>"
+  echo "Example: $0 1.2.0"
+  exit 1
+fi
+
+NEW_VERSION="$1"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+if ! [[ "$NEW_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "Error: version must be in semver format (e.g. 1.2.0)"
+  exit 1
+fi
+
+echo "Bumping all packages to version ${NEW_VERSION}..."
+
+update_package_json() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo "  SKIP (not found): $file"
+    return
+  fi
+
+  node -e "
+    const fs = require('fs');
+    const pkg = JSON.parse(fs.readFileSync('$file', 'utf8'));
+    pkg.version = '${NEW_VERSION}';
+    if (pkg.dependencies) {
+      for (const [key, val] of Object.entries(pkg.dependencies)) {
+        if (key.startsWith('@turingpulse/')) {
+          pkg.dependencies[key] = '>=${NEW_VERSION}';
+        }
+      }
+    }
+    fs.writeFileSync('$file', JSON.stringify(pkg, null, 2) + '\n');
+  "
+  echo "  Updated: $file"
+}
+
+update_package_json "${REPO_ROOT}/package.json"
+
+for pkg_dir in "${REPO_ROOT}"/packages/*/; do
+  if [ -f "${pkg_dir}package.json" ]; then
+    update_package_json "${pkg_dir}package.json"
+  fi
+done
+
+echo ""
+echo "Done. All packages bumped to ${NEW_VERSION}."
+echo "Next steps:"
+echo "  1. Review changes: git diff"
+echo "  2. Commit: git add -A && git commit -m 'release: v${NEW_VERSION}'"
+echo "  3. Tag: git tag v${NEW_VERSION}"
+echo "  4. Push: git push origin main v${NEW_VERSION}"
+echo "  5. Create a GitHub Release from the tag to trigger publish"

package/scripts/update-readme-compat.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Generate Shields.io badges and a compatibility matrix table in README.md.
+ *
+ * Usage:
+ *   node scripts/update-readme-compat.mjs <results-dir> <readme-path>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BADGE_START = '<!-- COMPAT-BADGES:START -->';
+const BADGE_END = '<!-- COMPAT-BADGES:END -->';
+const MATRIX_START = '<!-- COMPAT-MATRIX:START -->';
+const MATRIX_END = '<!-- COMPAT-MATRIX:END -->';
+
+const FRAMEWORK_DISPLAY = {
+  openai: 'OpenAI',
+  anthropic: 'Anthropic',
+  'google-genai': 'Google GenAI',
+  langchain: 'LangChain',
+  'langchain-openai': 'LangChain-OpenAI',
+  'vercel-ai': 'Vercel AI',
+  cohere: 'Cohere',
+  mistral: 'Mistral',
+};
+
+const FRAMEWORK_ORDER = Object.keys(FRAMEWORK_DISPLAY);
+
+function loadResults(dir) {
+  const results = [];
+  const walk = (d) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.name.endsWith('.json')) {
+        try {
+          results.push(JSON.parse(fs.readFileSync(full, 'utf-8')));
+        } catch {
+          // skip bad files
+        }
+      }
+    }
+  };
+  walk(dir);
+  return results;
+}
+
+function makeBadge(label, passed) {
+  const status = passed ? 'passing' : 'failing';
+  const color = passed ? 'brightgreen' : 'red';
+  const encoded = encodeURIComponent(label);
+  return `![${label}](https://img.shields.io/badge/${encoded}-${status}-${color})`;
+}
+
+function generateBadges(results) {
+  const fwStatus = {};
+  for (const r of results) {
+    const fw = r.framework;
+    if (!(fw in fwStatus)) fwStatus[fw] = true;
+    if (!r.passed) fwStatus[fw] = false;
+  }
+
+  const badges = [];
+  for (const fw of FRAMEWORK_ORDER) {
+    if (fw in fwStatus) {
+      badges.push(makeBadge(FRAMEWORK_DISPLAY[fw] || fw, fwStatus[fw]));
+    }
+  }
+  return badges.join(' ');
+}
+
+function generateMatrix(results) {
+  const grouped = {};
+  const nodeVersions = new Set();
+
+  for (const r of results) {
+    const fw = r.framework;
+    const ver = r.installed_version || r.requested_version || '?';
+    const nv = r.node_version || '?';
+    nodeVersions.add(nv);
+
+    if (!grouped[fw]) grouped[fw] = {};
+    if (!grouped[fw][ver]) grouped[fw][ver] = {};
+    grouped[fw][ver][nv] = r.passed;
+  }
+
+  const sortedNV = [...nodeVersions].sort();
+  const nvHeaders = sortedNV.map((nv) => `Node ${nv}`).join(' | ');
+
+  const lines = [];
+  lines.push(`| Framework | Version | ${nvHeaders} |`);
+  lines.push(`|---|---| ${sortedNV.map(() => '---').join(' | ')} |`);
+
+  for (const fw of FRAMEWORK_ORDER) {
+    if (!grouped[fw]) continue;
+    const display = FRAMEWORK_DISPLAY[fw] || fw;
+    for (const ver of Object.keys(grouped[fw]).sort()) {
+      const cells = sortedNV.map((nv) => {
+        if (nv in grouped[fw][ver]) {
+          return grouped[fw][ver][nv] ? 'pass' : 'fail';
+        }
+        return '--';
+      });
+      lines.push(`| ${display} | ${ver} | ${cells.join(' | ')} |`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function replaceSection(content, startMarker, endMarker, replacement) {
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx === -1 || endIdx === -1) return content;
+  return (
+    content.slice(0, startIdx + startMarker.length) +
+    '\n' +
+    replacement +
+    '\n' +
+    content.slice(endIdx)
+  );
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length !== 2) {
+    console.error(`Usage: node ${path.basename(process.argv[1])} <results-dir> <readme-path>`);
+    process.exit(1);
+  }
+
+  const [resultsDir, readmePath] = args;
+  const results = loadResults(resultsDir);
+  if (results.length === 0) {
+    console.error('No results found, skipping README update.');
+    return;
+  }
+
+  let content = fs.readFileSync(readmePath, 'utf-8');
+
+  const badges = generateBadges(results);
+  content = replaceSection(content, BADGE_START, BADGE_END, badges);
+
+  const matrix = generateMatrix(results);
+  content = replaceSection(content, MATRIX_START, MATRIX_END, matrix);
+
+  fs.writeFileSync(readmePath, content);
+  console.log(`Updated ${readmePath} with ${results.length} result(s).`);
+}
+
+main();

package/src/__tests__/fingerprint.test.ts

@@ -0,0 +1,328 @@
+/**
+ * Unit tests for fingerprinting and change detection.
+ */
+
+import {
+  FingerprintBuilder,
+  FingerprintConfig,
+  DEFAULT_FINGERPRINT_CONFIG,
+  extractPromptFromMessages,
+  extractConfigSubset,
+} from '../fingerprint';
+import {
+  LLMDetector,
+  ToolDetector,
+  detectNodeType,
+} from '../llmDetector';
+
+describe('FingerprintConfig', () => {
+  test('default config has expected values', () => {
+    const config = DEFAULT_FINGERPRINT_CONFIG;
+    expect(config.enabled).toBe(true);
+    expect(config.capturePrompts).toBe(true);
+    expect(config.captureConfigs).toBe(true);
+    expect(config.captureStructure).toBe(true);
+    expect(config.sendAsync).toBe(true);
+    expect(config.sendOnFailure).toBe(true);
+    expect(config.sensitiveConfigKeys).toContain('apiKey');
+    expect(config.promptHashAlgorithm).toBe('sha256');
+  });
+});
+
+describe('FingerprintBuilder', () => {
+  test('records nodes correctly', () => {
+    const builder = new FingerprintBuilder();
+    
+    builder.recordNode('llm_call', 'llm', { model: 'gpt-4' }, 'You are helpful');
+    builder.recordNode('search_tool', 'tool', { api: 'google' });
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.node_sequence).toContain('llm_call');
+    expect(fingerprint.node_sequence).toContain('search_tool');
+    expect(fingerprint.node_types['llm']).toBe(1);
+    expect(fingerprint.node_types['tool']).toBe(1);
+  });
+
+  test('counts node types correctly', () => {
+    const builder = new FingerprintBuilder();
+    
+    builder.recordNode('llm1', 'llm');
+    builder.recordNode('llm2', 'llm');
+    builder.recordNode('tool1', 'tool');
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.node_types['llm']).toBe(2);
+    expect(fingerprint.node_types['tool']).toBe(1);
+  });
+
+  test('tracks parent-child edges', () => {
+    const builder = new FingerprintBuilder();
+    
+    builder.recordNode('parent', 'function');
+    builder.pushParent('parent');
+    builder.recordNode('child1', 'llm');
+    builder.recordNode('child2', 'tool');
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.edges).toContain('parent->child1');
+    expect(fingerprint.edges).toContain('parent->child2');
+  });
+
+  test('tracks nested edges correctly', () => {
+    const builder = new FingerprintBuilder();
+    
+    builder.recordNode('root', 'function');
+    builder.pushParent('root');
+    builder.recordNode('middle', 'function');
+    builder.pushParent('middle');
+    builder.recordNode('leaf', 'llm');
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.edges).toContain('root->middle');
+    expect(fingerprint.edges).toContain('middle->leaf');
+    expect(fingerprint.edges).not.toContain('root->leaf');
+  });
+
+  test('skips duplicate nodes', () => {
+    const builder = new FingerprintBuilder();
+    
+    builder.recordNode('same_name', 'llm');
+    builder.recordNode('same_name', 'tool'); // Should be skipped
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.node_sequence.length).toBe(1);
+    expect(fingerprint.node_types['llm']).toBe(1);
+    expect(fingerprint.node_types['tool']).toBeUndefined();
+  });
+
+  test('produces deterministic structure hash', () => {
+    const builder1 = new FingerprintBuilder();
+    builder1.recordNode('a', 'llm');
+    builder1.recordNode('b', 'tool');
+    const fp1 = builder1.getFingerprint();
+    
+    const builder2 = new FingerprintBuilder();
+    builder2.recordNode('a', 'llm');
+    builder2.recordNode('b', 'tool');
+    const fp2 = builder2.getFingerprint();
+    
+    expect(fp1.structure_hash).toBe(fp2.structure_hash);
+  });
+
+  test('different structures produce different hashes', () => {
+    const builder1 = new FingerprintBuilder();
+    builder1.recordNode('a', 'llm');
+    builder1.recordNode('b', 'tool');
+    const fp1 = builder1.getFingerprint();
+    
+    const builder2 = new FingerprintBuilder();
+    builder2.recordNode('a', 'tool'); // Different type
+    builder2.recordNode('b', 'llm');
+    const fp2 = builder2.getFingerprint();
+    
+    expect(fp1.structure_hash).not.toBe(fp2.structure_hash);
+  });
+
+  test('hashes config for nodes', () => {
+    const builder = new FingerprintBuilder();
+    builder.recordNode('llm', 'llm', { model: 'gpt-4', temperature: 0.7 });
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.node_config_hashes['llm']).toBeDefined();
+    expect(fingerprint.node_config_hashes['llm'].length).toBeGreaterThan(0);
+  });
+
+  test('hashes prompts for LLM nodes', () => {
+    const builder = new FingerprintBuilder();
+    builder.recordNode('llm', 'llm', undefined, 'You are a helpful assistant');
+    
+    const fingerprint = builder.getFingerprint();
+    
+    expect(fingerprint.node_prompt_hashes['llm']).toBeDefined();
+    expect(fingerprint.node_prompt_hashes['llm'].length).toBeGreaterThan(0);
+  });
+
+  test('redacts sensitive config keys', () => {
+    const builder = new FingerprintBuilder({
+      sensitiveConfigKeys: ['secret'],
+    });
+    
+    // Record with sensitive key
+    builder.recordNode('llm', 'llm', { model: 'gpt-4', secret: 'my-secret' });
+    
+    const fingerprint = builder.getFingerprint();
+    
+    // The hash should exist (meaning config was processed)
+    expect(fingerprint.node_config_hashes['llm']).toBeDefined();
+  });
+});
+
+describe('LLMDetector', () => {
+  test('detects OpenAI chat completions', () => {
+    const result = LLMDetector.detectLLMCall(
+      'create',
+      'chat.completions.create',
+      [],
+      {
+        model: 'gpt-4',
+        temperature: 0.7,
+        messages: [
+          { role: 'system', content: 'You are helpful' },
+          { role: 'user', content: 'Hello' },
+        ],
+      }
+    );
+    
+    expect(result).toBeDefined();
+    expect(result?.provider).toBe('openai');
+    expect(result?.model).toBe('gpt-4');
+    expect(result?.prompt).toBe('You are helpful');
+    expect(result?.config.temperature).toBe(0.7);
+  });
+
+  test('detects Anthropic messages', () => {
+    const result = LLMDetector.detectLLMCall(
+      'create',
+      'messages.create',
+      [],
+      {
+        model: 'claude-3',
+        system: 'You are Claude',
+        messages: [{ role: 'user', content: 'Hello' }],
+      }
+    );
+    
+    expect(result).toBeDefined();
+    expect(result?.provider).toBe('anthropic');
+    expect(result?.prompt).toBe('You are Claude');
+  });
+
+  test('returns undefined for non-LLM calls', () => {
+    const result = LLMDetector.detectLLMCall(
+      'process_data',
+      'DataProcessor.process_data',
+      [],
+      {}
+    );
+    
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('ToolDetector', () => {
+  test('detects search tools', () => {
+    const result = ToolDetector.detectToolCall(
+      'search_web',
+      'Tools.search_web',
+      [],
+      {}
+    );
+    
+    expect(result).toBe('tool');
+  });
+
+  test('detects retrievers', () => {
+    const result = ToolDetector.detectToolCall(
+      'retrieve',
+      'VectorStoreRetriever.retrieve',
+      [],
+      {}
+    );
+    
+    expect(result).toBe('retriever');
+  });
+
+  test('returns undefined for non-tool calls', () => {
+    const result = ToolDetector.detectToolCall(
+      'calculate',
+      'Math.calculate',
+      [],
+      {}
+    );
+    
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('detectNodeType', () => {
+  test('detects LLM nodes', () => {
+    const [nodeType, llmInfo] = detectNodeType(
+      'create',
+      'chat.completions.create',
+      [],
+      { model: 'gpt-4', messages: [] }
+    );
+    
+    expect(nodeType).toBe('llm');
+    expect(llmInfo).toBeDefined();
+    expect(llmInfo?.provider).toBe('openai');
+  });
+
+  test('detects tool nodes', () => {
+    const [nodeType, llmInfo] = detectNodeType(
+      'search',
+      'tools.search',
+      [],
+      {}
+    );
+    
+    expect(nodeType).toBe('tool');
+    expect(llmInfo).toBeUndefined();
+  });
+
+  test('falls back to function type', () => {
+    const [nodeType, llmInfo] = detectNodeType(
+      'my_function',
+      'module.my_function',
+      [],
+      {}
+    );
+    
+    expect(nodeType).toBe('function');
+    expect(llmInfo).toBeUndefined();
+  });
+});
+
+describe('Helper Functions', () => {
+  test('extractPromptFromMessages finds system message', () => {
+    const messages = [
+      { role: 'system', content: 'You are helpful' },
+      { role: 'user', content: 'Hello' },
+    ];
+    
+    const prompt = extractPromptFromMessages(messages);
+    
+    expect(prompt).toBe('You are helpful');
+  });
+
+  test('extractPromptFromMessages returns undefined when no system message', () => {
+    const messages = [
+      { role: 'user', content: 'Hello' },
+    ];
+    
+    const prompt = extractPromptFromMessages(messages);
+    
+    expect(prompt).toBeUndefined();
+  });
+
+  test('extractConfigSubset extracts only specified keys', () => {
+    const kwargs = {
+      model: 'gpt-4',
+      temperature: 0.7,
+      max_tokens: 100,
+      irrelevant: 'value',
+    };
+    
+    const subset = extractConfigSubset(kwargs, ['model', 'temperature', 'missing']);
+    
+    expect(subset).toEqual({ model: 'gpt-4', temperature: 0.7 });
+    expect(subset['irrelevant']).toBeUndefined();
+  });
+});
+

package/src/attachments.ts

@@ -0,0 +1,88 @@
+/**
+ * Document attachment support for the TuringPulse TypeScript SDK.
+ *
+ * Provides AttachmentManager for uploading documents to the ingestion service
+ * and injecting attachment metadata into the current span.
+ *
+ * Design principle: NEVER crash customer code. All upload failures are logged
+ * and silently ignored.
+ */
+
+import { TuringPulseConfig } from './config';
+
+export interface AttachmentResult {
+  attachmentId: string;
+  filename: string;
+  mimeType: string;
+  sizeBytes: number;
+  storagePath: string;
+  direction: string;
+  deduplicated: boolean;
+}
+
+export class AttachmentManager {
+  private readonly baseUrl: string;
+  private readonly config: TuringPulseConfig;
+  private readonly enabled: boolean;
+
+  constructor(config: TuringPulseConfig, enabled = true) {
+    this.config = config;
+    this.baseUrl = config.endpoint;
+    this.enabled = enabled;
+  }
+
+  async attachBytes(
+    data: Uint8Array | Buffer,
+    filename: string,
+    direction: 'input' | 'output' = 'input',
+    mimeType?: string,
+  ): Promise<AttachmentResult | undefined> {
+    if (!this.enabled) return undefined;
+
+    try {
+      const formData = new FormData();
+      const blob = new Blob([data as BlobPart], { type: mimeType ?? 'application/octet-stream' });
+      formData.append('file', blob, filename);
+      formData.append('direction', direction);
+
+      const fetchImpl = this.config.fetchImpl ?? globalThis.fetch;
+      const response = await fetchImpl(`${this.baseUrl}/api/v1/attachments`, {
+        method: 'POST',
+        headers: {
+          'X-API-Key': this.config.apiKey,
+        },
+        body: formData,
+      });
+
+      if (!response.ok) {
+        // eslint-disable-next-line no-console
+        console.warn(`TuringPulse attachment upload failed: ${response.status}`);
+        return undefined;
+      }
+
+      const result = (await response.json()) as Record<string, unknown>;
+      return {
+        attachmentId: result.attachment_id as string,
+        filename: result.filename as string,
+        mimeType: result.mime_type as string,
+        sizeBytes: result.size_bytes as number,
+        storagePath: result.storage_path as string,
+        direction,
+        deduplicated: Boolean(result.deduplicated),
+      };
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn('TuringPulse attachment upload failed:', err instanceof Error ? err.message : String(err));
+      return undefined;
+    }
+  }
+
+  async attachText(
+    text: string,
+    filename = 'document.txt',
+    direction: 'input' | 'output' = 'input',
+  ): Promise<AttachmentResult | undefined> {
+    const encoder = new TextEncoder();
+    return this.attachBytes(encoder.encode(text), filename, direction, 'text/plain');
+  }
+}