agentic-flow 1.6.6 → 1.7.1

package/docs/AGENTDB_TESTING.md

@@ -0,0 +1,411 @@
+# AgentDB CLI - Local Testing Guide
+
+## Quick Start
+
+### Option 1: Run the Full Test Suite (Recommended)
+```bash
+# From the project root: /workspaces/agentic-flow/agentic-flow
+./scripts/test-agentdb.sh
+```
+
+This will run 13 comprehensive tests covering all CLI features!
+
+### Option 2: Manual Testing
+
+#### 1. Ensure you're in the correct directory
+```bash
+cd /workspaces/agentic-flow/agentic-flow
+pwd  # Should show: /workspaces/agentic-flow/agentic-flow
+```
+
+#### 2. Build the Project (if not already built)
+```bash
+npm run build
+```
+
+#### 3. Test the CLI Directly
+```bash
+# Show help (all 17 commands)
+node dist/agentdb/cli/agentdb-cli.js --help
+
+# Or use npx (if globally installed)
+npx agentdb --help
+```
+
+### 3. Create a Test Database
+```bash
+# Set database path
+export AGENTDB_PATH=./test-agentdb.db
+
+# Or specify inline for each command
+AGENTDB_PATH=./test-agentdb.db node dist/agentdb/cli/agentdb-cli.js db stats
+```
+
+## Test Each Command Category
+
+### 🧠 Reflexion Memory (Episodic Replay)
+```bash
+# Store an episode with self-critique
+node dist/agentdb/cli/agentdb-cli.js reflexion store \
+  "session-1" \
+  "implement_authentication" \
+  0.95 \
+  true \
+  "Successfully used OAuth2 with JWT tokens" \
+  "User login requirement" \
+  "Working auth system" \
+  1200 \
+  5000
+
+# Store a failed episode
+node dist/agentdb/cli/agentdb-cli.js reflexion store \
+  "session-1" \
+  "implement_authentication" \
+  0.3 \
+  false \
+  "Forgot to validate tokens properly" \
+  "User login requirement" \
+  "Insecure auth" \
+  800 \
+  3000
+
+# Retrieve relevant episodes
+node dist/agentdb/cli/agentdb-cli.js reflexion retrieve \
+  "authentication" \
+  5 \
+  0.5
+
+# Get critique summary from failures
+node dist/agentdb/cli/agentdb-cli.js reflexion critique-summary \
+  "authentication" \
+  true
+
+# Prune old episodes
+node dist/agentdb/cli/agentdb-cli.js reflexion prune 30 0.2
+```
+
+### 🛠️ Skill Library (Lifelong Learning)
+```bash
+# Create a skill manually
+node dist/agentdb/cli/agentdb-cli.js skill create \
+  "jwt_authentication" \
+  "Generate and validate JWT tokens for user authentication" \
+  "function generateJWT(payload) { return jwt.sign(payload, secret); }"
+
+# Search for skills
+node dist/agentdb/cli/agentdb-cli.js skill search \
+  "authentication tokens" \
+  5
+
+# Auto-consolidate episodes into skills
+node dist/agentdb/cli/agentdb-cli.js skill consolidate \
+  3 \
+  0.7 \
+  7
+
+# Prune underperforming skills
+node dist/agentdb/cli/agentdb-cli.js skill prune \
+  3 \
+  0.4 \
+  60
+```
+
+### 🔗 Causal Memory Graph (Intervention-Based)
+```bash
+# Add a causal edge manually
+node dist/agentdb/cli/agentdb-cli.js causal add-edge \
+  "add_unit_tests" \
+  "code_quality_score" \
+  0.25 \
+  0.95 \
+  100
+
+# Create an A/B experiment
+node dist/agentdb/cli/agentdb-cli.js causal experiment create \
+  "test-coverage-vs-bugs" \
+  "test_coverage" \
+  "bug_rate"
+
+# Add observations (treatment group)
+node dist/agentdb/cli/agentdb-cli.js causal experiment add-observation \
+  1 \
+  true \
+  0.15 \
+  '{"coverage": 0.85}'
+
+# Add observations (control group)
+node dist/agentdb/cli/agentdb-cli.js causal experiment add-observation \
+  1 \
+  false \
+  0.35 \
+  '{"coverage": 0.45}'
+
+# Calculate uplift
+node dist/agentdb/cli/agentdb-cli.js causal experiment calculate 1
+
+# Query causal edges
+node dist/agentdb/cli/agentdb-cli.js causal query \
+  "test" \
+  "quality" \
+  0.6 \
+  0.1 \
+  10
+```
+
+### 🔍 Causal Recall (Utility-Based Reranking)
+```bash
+# Retrieve with causal utility and provenance certificate
+node dist/agentdb/cli/agentdb-cli.js recall with-certificate \
+  "implement secure authentication" \
+  10 \
+  0.7 \
+  0.2 \
+  0.1
+```
+
+### 🌙 Nightly Learner (Automated Discovery)
+```bash
+# Discover causal edges from patterns (dry run)
+node dist/agentdb/cli/agentdb-cli.js learner run \
+  3 \
+  0.6 \
+  0.7 \
+  true
+
+# Discover and save edges
+node dist/agentdb/cli/agentdb-cli.js learner run \
+  3 \
+  0.6 \
+  0.7 \
+  false
+
+# Prune low-quality edges
+node dist/agentdb/cli/agentdb-cli.js learner prune \
+  0.5 \
+  0.05 \
+  90
+```
+
+### 📊 Database Stats
+```bash
+# Get comprehensive database statistics
+node dist/agentdb/cli/agentdb-cli.js db stats
+```
+
+## Full Workflow Example
+
+### Scenario: Learning from Authentication Implementation
+
+```bash
+#!/bin/bash
+
+# Set up test database
+export AGENTDB_PATH=./auth-learning.db
+
+# 1. Store successful attempts
+node dist/agentdb/cli/agentdb-cli.js reflexion store \
+  "session-auth-1" "oauth2_implementation" 0.95 true \
+  "Used industry-standard OAuth2 flow" \
+  "Implement secure login" "Working OAuth2 system" 1500 6000
+
+node dist/agentdb/cli/agentdb-cli.js reflexion store \
+  "session-auth-2" "jwt_tokens" 0.90 true \
+  "JWT with proper expiration and refresh tokens" \
+  "Token management" "Secure JWT system" 1200 5500
+
+# 2. Store failed attempts
+node dist/agentdb/cli/agentdb-cli.js reflexion store \
+  "session-auth-3" "session_storage" 0.35 false \
+  "Insecure session storage in localStorage" \
+  "Session management" "Security vulnerability" 800 3000
+
+# 3. Create a skill from successful pattern
+node dist/agentdb/cli/agentdb-cli.js skill create \
+  "secure_oauth2_jwt" \
+  "OAuth2 flow with JWT token management" \
+  "const auth = { oauth2: true, jwt: true, refresh: true }"
+
+# 4. Add causal edge
+node dist/agentdb/cli/agentdb-cli.js causal add-edge \
+  "add_token_refresh" "session_security" 0.40 0.92 50
+
+# 5. Query for authentication guidance
+node dist/agentdb/cli/agentdb-cli.js reflexion retrieve \
+  "secure authentication" 5 0.8
+
+# 6. Get critique summary of what NOT to do
+node dist/agentdb/cli/agentdb-cli.js reflexion critique-summary \
+  "authentication" true
+
+# 7. Search for applicable skills
+node dist/agentdb/cli/agentdb-cli.js skill search \
+  "oauth jwt tokens" 3
+
+# 8. Check database stats
+node dist/agentdb/cli/agentdb-cli.js db stats
+```
+
+## Verify Installation
+
+### Check Binary Links
+```bash
+# Should show the CLI binary path
+which agentdb
+
+# Or check npm bin
+npm bin agentdb
+```
+
+### Run from Package
+```bash
+# If you've run npm install -g or npm link
+agentdb --help
+```
+
+## Environment Variables
+
+```bash
+# Database path (default: ./agentdb.db)
+export AGENTDB_PATH=/path/to/your/database.db
+
+# Example with custom path
+AGENTDB_PATH=~/my-agent-memory.db node dist/agentdb/cli/agentdb-cli.js db stats
+```
+
+## Expected Output Examples
+
+### Successful Episode Storage
+```
+✓ Stored episode #1 (session: session-1, task: implement_authentication)
+  Reward: 0.95 | Success: true | Latency: 1200ms | Tokens: 5000
+```
+
+### Skill Search Results
+```
+🔍 Found 3 skills for "authentication"
+
+#1: jwt_authentication (success rate: 0.90, uses: 5)
+    Generate and validate JWT tokens for user authentication
+
+#2: oauth2_flow (success rate: 0.85, uses: 3)
+    Complete OAuth2 authorization code flow
+```
+
+### Database Stats
+```
+AgentDB Statistics
+
+Episodes:          15
+Skills:            8
+Causal Edges:      12
+Experiments:       3
+Certificates:      5
+
+Total Size:        2.4 MB
+```
+
+## Troubleshooting
+
+### Issue: "Cannot find module"
+```bash
+# Rebuild the project
+npm run build
+
+# Check dist folder exists
+ls dist/agentdb/cli/agentdb-cli.js
+```
+
+### Issue: "Database is locked"
+```bash
+# Close any open database connections
+# Or use a different database path
+export AGENTDB_PATH=./test2-agentdb.db
+```
+
+### Issue: "Permission denied"
+```bash
+# Make CLI executable
+chmod +x dist/agentdb/cli/agentdb-cli.js
+```
+
+## Advanced Testing
+
+### Test with Programmatic API
+```typescript
+import { AgentDBCLI } from './dist/agentdb/cli/agentdb-cli.js';
+
+const cli = new AgentDBCLI('./test.db');
+
+// Store episode
+await cli.reflexionStore({
+  sessionId: 'test-1',
+  task: 'example',
+  reward: 0.9,
+  success: true,
+  critique: 'Good approach'
+});
+
+// Retrieve episodes
+await cli.reflexionRetrieve({
+  task: 'example',
+  k: 5
+});
+```
+
+### Integration with Your Project
+```typescript
+// In your agent code
+import { AgentDBCLI } from 'agentic-flow/agentdb';
+
+const memory = new AgentDBCLI();
+
+// Learn from task outcomes
+async function learnFromTask(task, outcome) {
+  await memory.reflexionStore({
+    sessionId: getCurrentSession(),
+    task: task.name,
+    reward: outcome.score,
+    success: outcome.passed,
+    critique: outcome.feedback,
+    input: task.input,
+    output: outcome.result,
+    latencyMs: outcome.duration,
+    tokensUsed: outcome.tokens
+  });
+}
+
+// Retrieve similar past experiences
+async function recallSimilar(task) {
+  return await memory.reflexionRetrieve({
+    task: task.name,
+    k: 5,
+    minReward: 0.7
+  });
+}
+```
+
+## Performance Benchmarks
+
+```bash
+# Time a full workflow
+time bash full-workflow-example.sh
+
+# Check database performance
+node dist/agentdb/cli/agentdb-cli.js db stats
+```
+
+## Next Steps
+
+1. ✅ Test basic commands (reflexion, skill)
+2. ✅ Test causal features (edges, experiments)
+3. ✅ Run nightly learner for discovery
+4. ✅ Verify causal recall with certificates
+5. ✅ Check database stats
+6. 🚀 Integrate into your agent workflows
+
+## Resources
+
+- **AgentDB Controllers**: `/src/agentdb/controllers/`
+- **CLI Source**: `/src/agentdb/cli/agentdb-cli.ts`
+- **Tests**: `/src/agentdb/tests/frontier-features.test.ts`
+- **Binary**: `/dist/agentdb/cli/agentdb-cli.js`

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "agentic-flow",
-  "version": "1.6.6",
+  "version": "1.7.1",
   "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, ReasoningBank learning memory, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "agentic-flow": "dist/cli-proxy.js"
+    "agentic-flow": "dist/cli-proxy.js",
+    "agentdb": "dist/agentdb/cli/agentdb-cli.js"
   },
   "exports": {
     ".": "./dist/index.js",
@@ -14,7 +15,6 @@
       "browser": "./dist/reasoningbank/wasm-adapter.js",
       "default": "./dist/reasoningbank/index.js"
     },
-    "./reasoningbank/agentdb": "./dist/reasoningbank/agentdb-adapter.js",
     "./reasoningbank/backend-selector": "./dist/reasoningbank/backend-selector.js",
     "./reasoningbank/wasm-adapter": "./dist/reasoningbank/wasm-adapter.js",
     "./router": "./dist/router/index.js",
@@ -142,7 +142,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.1.5",
     "@anthropic-ai/sdk": "^0.65.0",
     "@google/genai": "^1.22.0",
-    "agentdb": "^1.0.5",
+    "agentdb": "^1.3.9",
     "agentic-payments": "^0.1.3",
     "axios": "^1.12.2",
     "better-sqlite3": "^12.4.1",

package/scripts/run-validation.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# Comprehensive Validation Script for v1.7.0
+# Runs Docker-based validation and generates report
+
+set -e
+
+echo "================================================================"
+echo "AGENTIC-FLOW v1.7.0 - DOCKER VALIDATION"
+echo "================================================================"
+echo "Started: $(date)"
+echo "================================================================"
+echo ""
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Create results directory
+mkdir -p validation-results
+mkdir -p benchmark-results
+
+# Function to print colored messages
+print_status() {
+    echo -e "${GREEN}✓${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}✗${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠${NC} $1"
+}
+
+# Step 1: Clean previous runs
+echo "Step 1: Cleaning previous validation runs..."
+docker-compose -f docker-compose.validation.yml down -v 2>/dev/null || true
+rm -rf validation-results/* benchmark-results/*
+print_status "Cleaned previous runs"
+echo ""
+
+# Step 2: Build validation image
+echo "Step 2: Building validation Docker image..."
+if docker-compose -f docker-compose.validation.yml build validation; then
+    print_status "Validation image built successfully"
+else
+    print_error "Failed to build validation image"
+    exit 1
+fi
+echo ""
+
+# Step 3: Run validation suite
+echo "Step 3: Running comprehensive validation suite..."
+echo "  This will test:"
+echo "    - Backwards compatibility"
+echo "    - New HybridReasoningBank capabilities"
+echo "    - SharedMemoryPool performance"
+echo "    - AdvancedMemorySystem features"
+echo "    - Memory profiling"
+echo "    - Regression detection"
+echo ""
+
+if docker-compose -f docker-compose.validation.yml run --rm validation; then
+    print_status "Validation suite PASSED"
+    VALIDATION_STATUS=0
+else
+    print_error "Validation suite FAILED"
+    VALIDATION_STATUS=1
+fi
+echo ""
+
+# Step 4: Copy results from container
+echo "Step 4: Extracting validation results..."
+docker cp agentic-flow-validation:/app/validation-results.json validation-results/ 2>/dev/null || true
+if [ -f "validation-results/validation-results.json" ]; then
+    print_status "Results extracted successfully"
+else
+    print_warning "Could not extract results file"
+fi
+echo ""
+
+# Step 5: Display results summary
+echo "Step 5: Validation Results Summary"
+echo "================================================================"
+if [ -f "validation-results/validation-results.json" ]; then
+    # Extract key metrics using jq if available
+    if command -v jq &> /dev/null; then
+        TOTAL=$(jq '.summary.total' validation-results/validation-results.json)
+        PASSED=$(jq '.summary.passed' validation-results/validation-results.json)
+        FAILED=$(jq '.summary.failed' validation-results/validation-results.json)
+        PASS_RATE=$(jq '.summary.passRate' validation-results/validation-results.json)
+
+        echo "Total Tests: $TOTAL"
+        echo "Passed: $PASSED"
+        echo "Failed: $FAILED"
+        echo "Pass Rate: $PASS_RATE%"
+        echo ""
+
+        if [ "$FAILED" -gt 0 ]; then
+            echo "Failed Tests:"
+            jq -r '.results[] | select(.status == "FAIL") | "  - \(.test): \(.error)"' validation-results/validation-results.json
+            echo ""
+        fi
+    else
+        cat validation-results/validation-results.json
+    fi
+else
+    print_warning "No results file found - check Docker logs"
+fi
+echo "================================================================"
+echo ""
+
+# Step 6: Run regression tests (optional - if validation passed)
+if [ $VALIDATION_STATUS -eq 0 ]; then
+    echo "Step 6: Running regression tests..."
+    if docker-compose -f docker-compose.validation.yml run --rm regression 2>/dev/null; then
+        print_status "Regression tests PASSED"
+    else
+        print_warning "Some regression tests failed (check logs)"
+    fi
+    echo ""
+fi
+
+# Step 7: Run performance benchmarks (optional)
+echo "Step 7: Running performance benchmarks..."
+echo "  (This may take several minutes)"
+if docker-compose -f docker-compose.validation.yml run --rm benchmark 2>/dev/null; then
+    print_status "Benchmarks completed"
+else
+    print_warning "Benchmarks incomplete (check logs)"
+fi
+echo ""
+
+# Step 8: Cleanup
+echo "Step 8: Cleaning up Docker resources..."
+docker-compose -f docker-compose.validation.yml down -v
+print_status "Cleanup complete"
+echo ""
+
+# Final Summary
+echo "================================================================"
+echo "VALIDATION COMPLETE"
+echo "================================================================"
+echo "Completed: $(date)"
+echo ""
+
+if [ $VALIDATION_STATUS -eq 0 ]; then
+    echo -e "${GREEN}✓✓✓ ALL VALIDATIONS PASSED ✓✓✓${NC}"
+    echo ""
+    echo "Next steps:"
+    echo "  1. Review results in validation-results/"
+    echo "  2. Check benchmark-results/ for performance metrics"
+    echo "  3. Proceed with release"
+    exit 0
+else
+    echo -e "${RED}✗✗✗ VALIDATION FAILED ✗✗✗${NC}"
+    echo ""
+    echo "Action required:"
+    echo "  1. Review failed tests in validation-results/"
+    echo "  2. Check Docker logs: docker-compose -f docker-compose.validation.yml logs"
+    echo "  3. Fix issues before release"
+    exit 1
+fi