agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/src/cli/examples.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# AgentDB CLI Examples - Frontier Features
+
+set -e
+
+echo "🚀 AgentDB CLI Examples - Frontier Features"
+echo "==========================================="
+echo ""
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Set database path
+export AGENTDB_PATH="./agentdb-example.db"
+
+echo -e "${BLUE}📊 Example 1: Manual Causal Edge${NC}"
+echo "Adding causal relationship: add_tests → code_quality"
+npx tsx src/agentdb/cli/agentdb-cli.ts causal add-edge \
+  "add_tests" "code_quality" 0.25 0.95 100
+echo ""
+
+echo -e "${BLUE}🧪 Example 2: A/B Experiment${NC}"
+echo "Testing hypothesis: Higher test coverage reduces bug rate"
+echo ""
+
+# Create experiment
+echo "Creating experiment..."
+npx tsx src/agentdb/cli/agentdb-cli.ts causal experiment create \
+  "test-coverage-experiment" "test_coverage_high" "bug_rate"
+echo ""
+
+# Add treatment group observations (high coverage → lower bugs)
+echo "Adding treatment observations (high coverage)..."
+for i in {1..10}; do
+  OUTCOME=$(awk -v min=0.05 -v max=0.20 'BEGIN{srand(); print min+rand()*(max-min)}')
+  npx tsx src/agentdb/cli/agentdb-cli.ts causal experiment add-observation \
+    1 true $OUTCOME '{"coverage": 0.85}'
+done
+echo ""
+
+# Add control group observations (low coverage → higher bugs)
+echo "Adding control observations (low coverage)..."
+for i in {1..10}; do
+  OUTCOME=$(awk -v min=0.25 -v max=0.45 'BEGIN{srand(); print min+rand()*(max-min)}')
+  npx tsx src/agentdb/cli/agentdb-cli.ts causal experiment add-observation \
+    1 false $OUTCOME '{"coverage": 0.45}'
+done
+echo ""
+
+# Calculate uplift
+echo "Calculating uplift and significance..."
+npx tsx src/agentdb/cli/agentdb-cli.ts causal experiment calculate 1
+echo ""
+
+echo -e "${BLUE}🔍 Example 3: Causal Query${NC}"
+echo "Finding all high-confidence causal edges..."
+npx tsx src/agentdb/cli/agentdb-cli.ts causal query \
+  "" "" 0.7 0.1 10
+echo ""
+
+echo -e "${BLUE}📈 Example 4: Database Statistics${NC}"
+npx tsx src/agentdb/cli/agentdb-cli.ts db stats
+echo ""
+
+echo -e "${GREEN}✅ Examples Complete!${NC}"
+echo ""
+echo "Try these commands yourself:"
+echo ""
+echo -e "${YELLOW}# Query causal edges for specific effect${NC}"
+echo "npx agentdb causal query '' 'code_quality' 0.8"
+echo ""
+echo -e "${YELLOW}# Retrieve with causal utility${NC}"
+echo "npx agentdb recall with-certificate 'implement authentication' 10"
+echo ""
+echo -e "${YELLOW}# Run nightly learner${NC}"
+echo "npx agentdb learner run 3 0.6 0.7"
+echo ""
+echo -e "${YELLOW}# Prune low-quality edges${NC}"
+echo "npx agentdb learner prune 0.5 0.05 90"
+echo ""

package/src/cli/lib/attention-config.ts

@@ -0,0 +1,326 @@
+/**
+ * Attention Configuration Management
+ * Handles loading, saving, and validating attention mechanism configurations
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+export interface AttentionMechanismConfig {
+  enabled: boolean;
+  heads: number;
+  dimension: number;
+  [key: string]: any;
+}
+
+export interface AttentionConfig {
+  defaultMechanism: string;
+  mechanisms: {
+    flash: AttentionMechanismConfig & {
+      blockSize: number;
+    };
+    hyperbolic: AttentionMechanismConfig & {
+      curvature: number;
+    };
+    sparse: AttentionMechanismConfig & {
+      sparsity: number;
+    };
+    linear: AttentionMechanismConfig & {
+      kernelSize: number;
+    };
+    performer: AttentionMechanismConfig & {
+      randomFeatures: number;
+    };
+  };
+  featureFlags: {
+    enableBenchmarking: boolean;
+    enableOptimization: boolean;
+    cacheResults: boolean;
+  };
+}
+
+/**
+ * Default attention configuration
+ */
+export const DEFAULT_ATTENTION_CONFIG: AttentionConfig = {
+  defaultMechanism: 'flash',
+  mechanisms: {
+    flash: {
+      enabled: true,
+      heads: 8,
+      dimension: 384,
+      blockSize: 64,
+    },
+    hyperbolic: {
+      enabled: true,
+      curvature: -1.0,
+      heads: 8,
+      dimension: 384,
+    },
+    sparse: {
+      enabled: true,
+      sparsity: 0.9,
+      heads: 8,
+      dimension: 384,
+    },
+    linear: {
+      enabled: true,
+      kernelSize: 32,
+      heads: 8,
+      dimension: 384,
+    },
+    performer: {
+      enabled: true,
+      randomFeatures: 256,
+      heads: 8,
+      dimension: 384,
+    },
+  },
+  featureFlags: {
+    enableBenchmarking: true,
+    enableOptimization: true,
+    cacheResults: true,
+  },
+};
+
+/**
+ * Load attention configuration from file
+ */
+export async function loadAttentionConfig(configPath?: string): Promise<AttentionConfig> {
+  const defaultPath = path.join(process.cwd(), '.agentdb', 'attention-config.json');
+  const filePath = configPath || defaultPath;
+
+  try {
+    const data = await fs.readFile(filePath, 'utf-8');
+    const config = JSON.parse(data);
+    return validateConfig(config);
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      // Config file doesn't exist, return default
+      return DEFAULT_ATTENTION_CONFIG;
+    }
+    throw new Error(`Failed to load attention config: ${error.message}`);
+  }
+}
+
+/**
+ * Save attention configuration to file
+ */
+export async function saveAttentionConfig(
+  config: AttentionConfig,
+  configPath?: string
+): Promise<void> {
+  const defaultPath = path.join(process.cwd(), '.agentdb', 'attention-config.json');
+  const filePath = configPath || defaultPath;
+
+  // Ensure directory exists
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+  // Validate before saving
+  const validConfig = validateConfig(config);
+
+  // Save to file
+  await fs.writeFile(filePath, JSON.stringify(validConfig, null, 2));
+}
+
+/**
+ * Validate attention configuration
+ */
+export function validateConfig(config: any): AttentionConfig {
+  if (!config || typeof config !== 'object') {
+    throw new Error('Invalid configuration: must be an object');
+  }
+
+  // Validate default mechanism
+  if (!config.defaultMechanism) {
+    config.defaultMechanism = 'flash';
+  }
+
+  const validMechanisms = ['flash', 'hyperbolic', 'sparse', 'linear', 'performer'];
+  if (!validMechanisms.includes(config.defaultMechanism)) {
+    throw new Error(
+      `Invalid default mechanism: ${config.defaultMechanism}. Must be one of: ${validMechanisms.join(', ')}`
+    );
+  }
+
+  // Validate mechanisms
+  if (!config.mechanisms || typeof config.mechanisms !== 'object') {
+    config.mechanisms = DEFAULT_ATTENTION_CONFIG.mechanisms;
+  }
+
+  // Validate each mechanism
+  for (const mechanismName of validMechanisms) {
+    if (!config.mechanisms[mechanismName]) {
+      config.mechanisms[mechanismName] = DEFAULT_ATTENTION_CONFIG.mechanisms[mechanismName as keyof typeof DEFAULT_ATTENTION_CONFIG.mechanisms];
+      continue;
+    }
+
+    const mechanism = config.mechanisms[mechanismName];
+
+    // Validate common fields
+    if (typeof mechanism.enabled !== 'boolean') {
+      mechanism.enabled = true;
+    }
+
+    if (!Number.isInteger(mechanism.heads) || mechanism.heads < 1 || mechanism.heads > 32) {
+      throw new Error(`Invalid heads for ${mechanismName}: must be an integer between 1 and 32`);
+    }
+
+    if (!Number.isInteger(mechanism.dimension) || mechanism.dimension < 64 || mechanism.dimension > 2048) {
+      throw new Error(`Invalid dimension for ${mechanismName}: must be an integer between 64 and 2048`);
+    }
+
+    // Validate mechanism-specific fields
+    switch (mechanismName) {
+      case 'flash':
+        if (!Number.isInteger(mechanism.blockSize) || mechanism.blockSize < 16 || mechanism.blockSize > 256) {
+          throw new Error('Invalid blockSize for flash: must be an integer between 16 and 256');
+        }
+        break;
+
+      case 'hyperbolic':
+        if (typeof mechanism.curvature !== 'number' || mechanism.curvature >= 0) {
+          throw new Error('Invalid curvature for hyperbolic: must be a negative number');
+        }
+        break;
+
+      case 'sparse':
+        if (typeof mechanism.sparsity !== 'number' || mechanism.sparsity < 0 || mechanism.sparsity > 1) {
+          throw new Error('Invalid sparsity: must be a number between 0 and 1');
+        }
+        break;
+
+      case 'linear':
+        if (!Number.isInteger(mechanism.kernelSize) || mechanism.kernelSize < 8 || mechanism.kernelSize > 128) {
+          throw new Error('Invalid kernelSize for linear: must be an integer between 8 and 128');
+        }
+        break;
+
+      case 'performer':
+        if (!Number.isInteger(mechanism.randomFeatures) || mechanism.randomFeatures < 64 || mechanism.randomFeatures > 1024) {
+          throw new Error('Invalid randomFeatures for performer: must be an integer between 64 and 1024');
+        }
+        break;
+    }
+  }
+
+  // Validate feature flags
+  if (!config.featureFlags || typeof config.featureFlags !== 'object') {
+    config.featureFlags = DEFAULT_ATTENTION_CONFIG.featureFlags;
+  }
+
+  if (typeof config.featureFlags.enableBenchmarking !== 'boolean') {
+    config.featureFlags.enableBenchmarking = true;
+  }
+
+  if (typeof config.featureFlags.enableOptimization !== 'boolean') {
+    config.featureFlags.enableOptimization = true;
+  }
+
+  if (typeof config.featureFlags.cacheResults !== 'boolean') {
+    config.featureFlags.cacheResults = true;
+  }
+
+  return config as AttentionConfig;
+}
+
+/**
+ * Update a specific mechanism configuration
+ */
+export async function updateMechanismConfig(
+  mechanismName: string,
+  updates: Partial<AttentionMechanismConfig>,
+  configPath?: string
+): Promise<AttentionConfig> {
+  const config = await loadAttentionConfig(configPath);
+
+  if (!(mechanismName in config.mechanisms)) {
+    throw new Error(`Unknown mechanism: ${mechanismName}`);
+  }
+
+  // Apply updates
+  config.mechanisms[mechanismName as keyof typeof config.mechanisms] = {
+    ...config.mechanisms[mechanismName as keyof typeof config.mechanisms],
+    ...updates,
+  } as any;
+
+  // Validate and save
+  const validConfig = validateConfig(config);
+  await saveAttentionConfig(validConfig, configPath);
+
+  return validConfig;
+}
+
+/**
+ * Enable/disable a mechanism
+ */
+export async function toggleMechanism(
+  mechanismName: string,
+  enabled: boolean,
+  configPath?: string
+): Promise<AttentionConfig> {
+  return updateMechanismConfig(mechanismName, { enabled }, configPath);
+}
+
+/**
+ * Set default mechanism
+ */
+export async function setDefaultMechanism(
+  mechanismName: string,
+  configPath?: string
+): Promise<AttentionConfig> {
+  const config = await loadAttentionConfig(configPath);
+
+  const validMechanisms = ['flash', 'hyperbolic', 'sparse', 'linear', 'performer'];
+  if (!validMechanisms.includes(mechanismName)) {
+    throw new Error(
+      `Invalid mechanism: ${mechanismName}. Must be one of: ${validMechanisms.join(', ')}`
+    );
+  }
+
+  config.defaultMechanism = mechanismName;
+
+  const validConfig = validateConfig(config);
+  await saveAttentionConfig(validConfig, configPath);
+
+  return validConfig;
+}
+
+/**
+ * Get configuration for a specific mechanism
+ */
+export async function getMechanismConfig(
+  mechanismName: string,
+  configPath?: string
+): Promise<AttentionMechanismConfig> {
+  const config = await loadAttentionConfig(configPath);
+
+  if (!(mechanismName in config.mechanisms)) {
+    throw new Error(`Unknown mechanism: ${mechanismName}`);
+  }
+
+  return config.mechanisms[mechanismName as keyof typeof config.mechanisms];
+}
+
+/**
+ * Reset configuration to defaults
+ */
+export async function resetConfig(configPath?: string): Promise<AttentionConfig> {
+  await saveAttentionConfig(DEFAULT_ATTENTION_CONFIG, configPath);
+  return DEFAULT_ATTENTION_CONFIG;
+}
+
+/**
+ * Export configuration as JSON string
+ */
+export function exportConfig(config: AttentionConfig): string {
+  return JSON.stringify(config, null, 2);
+}
+
+/**
+ * Import configuration from JSON string
+ */
+export function importConfig(jsonString: string): AttentionConfig {
+  const config = JSON.parse(jsonString);
+  return validateConfig(config);
+}