ruvector/docs/integration/PSYCHO-SYMBOLIC-INTEGRATION.md

🧠 Psycho-Symbolic Integration for Ruvector

Overview

The Ruvector ecosystem now includes psycho-symbolic-reasoner, adding ultra-fast symbolic AI reasoning capabilities to complement vector databases and synthetic data generation.

🎯 What is Psycho-Symbolic Reasoning?

Psycho-symbolic reasoning combines:

• Symbolic AI: Fast, deterministic logical reasoning (0.3ms queries)
• Psychological Modeling: Human-centric factors (sentiment, preferences, affect)
• Graph Intelligence: Knowledge representation and traversal

Performance Comparison

System	Simple Query	Complex Reasoning	Memory
Psycho-Symbolic	0.3ms	2.1ms	8MB
GPT-4 Reasoning	150ms	800ms	2GB+
Traditional Reasoners	5-25ms	50-200ms	64-512MB

100-500x faster than neural approaches!

🚀 Quick Start

Installation

# Install psycho-symbolic-reasoner
npm install psycho-symbolic-reasoner

# Install integration package
npm install psycho-symbolic-integration

Basic Usage

import { quickStart } from 'psycho-symbolic-integration';

// Initialize integrated system
const system = await quickStart(process.env.GEMINI_API_KEY);

// Analyze text for sentiment and preferences
const analysis = await system.analyzeText(
  "I prefer quick, easy activities for stress relief"
);

console.log(analysis.sentiment);    // { score: 0.7, emotion: 'calm' }
console.log(analysis.preferences);  // Extracted preferences

// Generate data with psychological guidance
const result = await system.generateIntelligently('structured', {
  count: 100,
  schema: { activity: 'string', duration: 'number' }
}, {
  targetSentiment: { score: 0.7, emotion: 'happy' },
  userPreferences: ['I like quick results'],
  qualityThreshold: 0.9
});

🔗 Integration with Ruvector Ecosystem

1. With Agentic-Synth

Psychologically-guided synthetic data generation:

import { AgenticSynth } from '@ruvector/agentic-synth';
import { PsychoSymbolicReasoner } from 'psycho-symbolic-reasoner';
import { AgenticSynthAdapter } from 'psycho-symbolic-integration/adapters';

const reasoner = new PsychoSymbolicReasoner();
const synth = new AgenticSynth();
const adapter = new AgenticSynthAdapter(reasoner, synth);

// Generate data guided by preferences
const result = await adapter.generateWithPsychoGuidance('structured', {
  count: 100,
  schema: productSchema
}, {
  userPreferences: ['I prefer eco-friendly products', 'Quality over price'],
  targetSentiment: { score: 0.8, emotion: 'satisfied' }
});

console.log(`Preference alignment: ${result.psychoMetrics.preferenceAlignment}`);
console.log(`Sentiment match: ${result.psychoMetrics.sentimentMatch}`);

2. With Ruvector Vector Database

Hybrid symbolic + vector queries:

import { Ruvector } from 'ruvector';
import { RuvectorAdapter } from 'psycho-symbolic-integration/adapters';

const reasoner = new PsychoSymbolicReasoner();
const vectorAdapter = new RuvectorAdapter(reasoner, {
  dbPath: './data/vectors.db',
  dimensions: 768
});

await vectorAdapter.initialize();

// Load knowledge graph
await vectorAdapter.storeKnowledgeGraph({
  nodes: [ /* entities */ ],
  edges: [ /* relationships */ ]
});

// Hybrid query: 60% symbolic logic, 40% vector similarity
const results = await vectorAdapter.hybridQuery(
  'Find stress management techniques',
  { symbolicWeight: 0.6, vectorWeight: 0.4 }
);

// Results combine logical reasoning with semantic search
results.forEach(r => {
  console.log(`${r.nodes[0].id}: ${r.reasoning.combinedScore}`);
  console.log(`  Symbolic: ${r.reasoning.symbolicMatch}`);
  console.log(`  Semantic: ${r.reasoning.semanticMatch}`);
});

3. Complete Integration

All three systems working together:

import { IntegratedPsychoSymbolicSystem } from 'psycho-symbolic-integration';

const system = new IntegratedPsychoSymbolicSystem({
  reasoner: {
    enableGraphReasoning: true,
    enableAffectExtraction: true,
    enablePlanning: true
  },
  synth: {
    provider: 'gemini',
    apiKey: process.env.GEMINI_API_KEY,
    cache: { enabled: true }
  },
  vector: {
    dbPath: './data/vectors.db',
    dimensions: 768
  }
});

await system.initialize();

// Now you can:
// 1. Analyze sentiment and preferences (0.4ms)
// 2. Generate psychologically-guided data (2-5s)
// 3. Perform hybrid reasoning queries (10-50ms)
// 4. Plan data strategies with GOAP (2ms)

const plan = await system.planDataGeneration(
  'Generate 1000 wellness activities',
  { targetQuality: 0.9, maxDuration: 30 }
);

📊 Key Capabilities

1. Sentiment Analysis (0.4ms)

const sentiment = await system.reasoner.extractSentiment(
  "I'm feeling overwhelmed with work deadlines"
);
// { score: -0.6, primaryEmotion: 'stressed', confidence: 0.87 }

2. Preference Extraction (0.6ms)

const prefs = await system.reasoner.extractPreferences(
  "I prefer quiet environments for deep thinking"
);
// [ { type: 'likes', subject: 'environments', object: 'quiet', strength: 0.9 } ]

3. Graph Reasoning (1.2ms)

const results = await system.reasoner.queryGraph({
  pattern: 'find activities that help with stress',
  maxResults: 5
});

4. Goal-Oriented Planning (2ms)

const plan = await system.reasoner.plan({
  goal: 'reduce user stress',
  currentState: { stressLevel: 0.8 },
  availableActions: ['meditate', 'exercise', 'rest']
});

🎯 Use Cases

Healthcare & Wellness

• Patient analysis: Extract sentiment and preferences from patient feedback
• Treatment planning: Goal-oriented planning for personalized care
• Data generation: Create realistic patient scenarios for training

Customer Analytics

• Feedback analysis: Instant sentiment extraction from reviews
• Preference modeling: Build user preference profiles
• Synthetic data: Generate customer scenarios for testing

AI Training

• Quality data: Psychologically-validated training datasets
• Preference alignment: Ensure AI matches user expectations
• Sentiment control: Generate data with specific emotional tones

Business Intelligence

• Fast rules: Execute thousands of business rules per second
• Recommendations: Instant, explainable recommendations
• Decision support: Real-time what-if analysis

🔬 Technical Details

Architecture

┌────────────────────────────────────────────────┐
│        IntegratedPsychoSymbolicSystem          │
├─────────────┬────────────────┬─────────────────┤
│ Psycho-     │ Agentic-       │ Ruvector        │
│ Symbolic    │ Synth          │ (Optional)      │
│ Reasoner    │ Adapter        │ Adapter         │
├─────────────┼────────────────┼─────────────────┤
│             │                │                 │
│ WASM/Rust   │ Preference     │ Vector search   │
│ 0.3ms       │ guidance       │ Embeddings      │
│ Symbolic    │ Sentiment      │ Hybrid queries  │
│ Graph       │ validation     │ Semantic cache  │
│ Planning    │ Quality score  │                 │
└─────────────┴────────────────┴─────────────────┘

Why It's Fast

1. WebAssembly: Near-native performance (Rust compiled to WASM)
2. Zero-Copy: Direct memory access between JS and WASM
3. Lock-Free: Wait-free algorithms for concurrent access
4. Intelligent Caching: Multi-level cache hierarchy
5. SIMD: Vectorized operations for batch processing

Memory Efficiency

• Compact: ~8MB memory footprint
• Efficient: Bit-packed data structures
• Pooling: Reusable allocation pools
• Lazy: On-demand module initialization

📚 Documentation

• Integration Guide: INTEGRATION-GUIDE.md
• API Reference: README.md
• Examples: examples/

🔗 Links

• Psycho-Symbolic Reasoner: npm
• Integration Package: psycho-symbolic-integration
• Agentic-Synth: @ruvector/agentic-synth
• Ruvector: Main repo

🎉 Getting Started

# Install dependencies
npm install psycho-symbolic-reasoner @ruvector/agentic-synth psycho-symbolic-integration

# Run the complete integration example
cd packages/psycho-symbolic-integration
npx tsx examples/complete-integration.ts

Experience 100x faster reasoning with psychological intelligence! 🚀