psycho-symbolic-integration

A unified integration layer that combines ultra-fast symbolic AI reasoning with intelligent synthetic data generation. This package bridges the gap between traditional rule-based AI and modern generative systems, enabling applications that understand context, sentiment, and user preferences at unprecedented speed.

What Is Psycho-Symbolic Integration?

Traditional AI systems face a fundamental trade-off: rule-based systems are fast but rigid, while neural systems are flexible but slow and opaque. Psycho-symbolic integration eliminates this trade-off by combining:

1. Symbolic Reasoning - Lightning-fast rule execution, graph queries, and logical inference
2. Psychological Modeling - Sentiment analysis, preference extraction, and emotional context
3. Synthetic Generation - AI-powered data creation guided by psychological insights

The result is an AI system that can reason about user intent in milliseconds while generating contextually appropriate content with measurable quality metrics.

Key Features

| Feature | Description | |---------|-------------| | Ultra-Fast Reasoning | Sub-millisecond sentiment analysis (0.3ms) and preference extraction (0.6ms) | | Intelligent Generation | AI-powered synthetic data guided by psychological insights | | Hybrid Queries | Combine symbolic logic with vector similarity search | | Quality Metrics | Built-in validation with sentiment matching and quality scoring | | GOAP Planning | Goal-Oriented Action Planning for complex data generation strategies | | LRU Caching | Memory-efficient caching with automatic eviction |

Performance Benchmarks

| Operation | Time | Speedup vs Traditional | |-----------|------|------------------------| | Sentiment Analysis | 0.3-0.4ms | 500x faster than API calls | | Preference Extraction | 0.6ms | 300x faster than NLP pipelines | | Graph Reasoning | 1.2ms | 100x faster than graph databases | | Hybrid Query (symbolic + vector) | 10-50ms | 10x faster than separate queries | | Psycho-Guided Generation | 2-5s | 25% higher quality output |

Memory Efficiency

• LRU cache with 1000 entry limit (~6MB max)
• Automatic eviction prevents memory leaks
• Session-based history with 100 entry cap per type

Benefits

For Developers:

• Single unified API instead of managing multiple AI systems
• TypeScript-first with full type definitions
• Works with or without optional vector database

For Applications:

• Real-time user sentiment understanding
• Personalized content that matches user preferences
• Measurable quality metrics for generated data

For Business:

• Reduce API costs with local symbolic reasoning
• Faster iteration with sub-second feedback loops
• Higher quality training data for downstream ML

Installation

npm install psycho-symbolic-integration

Dependencies are bundled automatically:

• psycho-symbolic-reasoner - Symbolic AI reasoning engine
• @ruvector/agentic-synth - Synthetic data generation

Optional peer dependency for hybrid queries:

npm install ruvector

Tutorial

Quick Start

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

// Initialize with API key (uses Gemini by default)
const system = await quickStart(process.env.GEMINI_API_KEY);

// Generate sentiment-targeted data
const result = await system.generateIntelligently('structured', {
  count: 100,
  schema: { name: 'string', mood: 'string' }
}, {
  targetSentiment: { score: 0.8, emotion: 'happy' },
  userPreferences: ['I prefer concise content'],
  qualityThreshold: 0.9
});

console.log(`Quality: ${result.psychoMetrics.qualityScore * 100}%`);
console.log(`Sentiment match: ${result.psychoMetrics.sentimentMatch * 100}%`);

Basic Usage

1. Initialize the System

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

const system = createIntegratedSystem({
  // Reasoning configuration
  reasoner: {
    enableGraphReasoning: true,
    enableAffectExtraction: true,
    enablePlanning: true,
    logLevel: 'info'
  },

  // Synthetic data generation
  synth: {
    provider: 'gemini',  // or 'openrouter'
    apiKey: process.env.GEMINI_API_KEY,
    cache: { enabled: true, maxSize: 1000 }
  },

  // Optional: Vector database for hybrid queries
  vector: {
    dbPath: './data/knowledge.db',
    collectionName: 'psycho-knowledge',
    dimensions: 768,
    enableSemanticCache: true
  }
});

await system.initialize();

2. Analyze Text for Sentiment and Preferences

const analysis = await system.analyzeText(
  "I really love fast, responsive interfaces. Slow loading times frustrate me."
);

console.log(analysis);
// {
//   sentiment: {
//     score: 0.3,  // Mixed: positive about fast, negative about slow
//     primaryEmotion: 'frustration',
//     confidence: 0.85
//   },
//   preferences: {
//     preferences: [
//       { type: 'likes', subject: 'interfaces', object: 'fast', strength: 0.9 },
//       { type: 'dislikes', subject: 'loading', object: 'slow', strength: 0.8 }
//     ]
//   }
// }

3. Generate Data with Psychological Guidance

// Generate customer feedback data that matches a positive sentiment
const feedback = await system.generateIntelligently('structured', {
  count: 50,
  schema: {
    customer_id: 'uuid',
    feedback_text: 'string',
    rating: 'number',
    category: 'string'
  }
}, {
  targetSentiment: { score: 0.7, emotion: 'satisfied' },
  userPreferences: ['Focus on product quality', 'Mention customer service'],
  contextualFactors: {
    emotionalState: 'appreciative',
    environment: 'post-purchase'
  },
  qualityThreshold: 0.85
});

// Check generation quality
console.log(`Generated: ${feedback.data.length} items`);
console.log(`Sentiment match: ${feedback.psychoMetrics.sentimentMatch * 100}%`);
console.log(`Quality score: ${feedback.psychoMetrics.qualityScore * 100}%`);

4. Hybrid Queries (Symbolic + Vector)

Combine fast symbolic reasoning with semantic vector search:

// Load knowledge base
await system.loadKnowledgeBase({
  nodes: [
    { id: 'stress', type: 'condition', properties: { severity: 'variable' } },
    { id: 'exercise', type: 'activity', properties: { benefit: 'high' } },
    { id: 'meditation', type: 'activity', properties: { benefit: 'high' } }
  ],
  edges: [
    { from: 'exercise', to: 'stress', relationship: 'reduces' },
    { from: 'meditation', to: 'stress', relationship: 'reduces' }
  ]
});

// Query with adjustable weights
const results = await system.intelligentQuery(
  'Find activities that help with stress management',
  {
    symbolicWeight: 0.6,  // Prioritize logical relationships
    vectorWeight: 0.4,    // Include semantic similarity
    maxResults: 10
  }
);

// Results include reasoning breakdown
results.forEach(r => {
  console.log(`${r.nodes[0].id}: ${r.reasoning.combinedScore.toFixed(2)}`);
  console.log(`  Symbolic: ${r.reasoning.symbolicMatch}`);
  console.log(`  Semantic: ${r.reasoning.semanticMatch}`);
});

5. Plan Generation Strategies with GOAP

Use Goal-Oriented Action Planning to optimize data generation:

const plan = await system.planDataGeneration(
  'Generate 10,000 high-quality training samples',
  {
    maxTime: '1 hour',
    minQuality: 0.9,
    diversity: 'high'
  }
);

console.log('Execution Plan:');
plan.steps.forEach((step, i) => {
  console.log(`${i + 1}. ${step.action}: ${step.description}`);
});

console.log(`Estimated time: ${plan.estimatedTime}ms`);
console.log(`Expected quality: ${plan.estimatedQuality * 100}%`);

Advanced Configuration

Custom Adapters

Access underlying adapters for fine-grained control:

// Direct access to psycho-symbolic reasoner
const sentiment = await system.reasoner.extractSentiment('I love this!');

// Direct access to synthetic data generator
const rawData = await system.synth.generate('timeseries', {
  count: 100,
  interval: '1h'
});

// Access generation history and insights
const insights = system.synthAdapter.getGenerationInsights();
console.log(`Total generations: ${insights.structured?.count || 0}`);
console.log(`Average quality: ${insights.structured?.avgQuality || 0}`);

System Monitoring

// Get comprehensive system stats
const stats = system.getSystemInsights();

console.log('System Status:', stats);
// {
//   initialized: true,
//   components: {
//     reasoner: 'psycho-symbolic-reasoner',
//     synth: 'agentic-synth',
//     vector: 'ruvector' | 'not-available'
//   },
//   adapters: {
//     synthHistory: { structured: { count: 5, avgQuality: 0.87 } },
//     vectorCache: { size: 150, available: true }
//   }
// }

Cleanup

// Graceful shutdown
await system.shutdown();

Use Cases

Healthcare Analytics

// Analyze patient feedback for emotional patterns
const patientAnalysis = await system.analyzeText(patientFeedback);

// Generate realistic test data for healthcare apps
const testPatients = await system.generateIntelligently('structured', {
  count: 1000,
  schema: {
    patient_id: 'uuid',
    symptoms: 'array',
    mood_score: 'number',
    notes: 'string'
  }
}, {
  contextualFactors: { environment: 'clinical' },
  qualityThreshold: 0.95
});

Customer Intelligence

// Extract preferences from support tickets
const prefs = await system.analyzeText(ticketText);

// Generate training data for sentiment classifiers
const trainingData = await system.generateIntelligently('structured', {
  count: 5000,
  schema: { text: 'string', sentiment: 'number', category: 'string' }
}, {
  targetSentiment: { score: 0.0, emotion: 'neutral' },  // Balanced
  qualityThreshold: 0.9
});

AI Training Data

// Plan large-scale data generation
const plan = await system.planDataGeneration(
  'Generate diverse training corpus',
  { diversity: 'maximum', minQuality: 0.85 }
);

// Execute with psychological validation
const corpus = await system.generateIntelligently('structured', {
  count: 10000,
  schema: { input: 'string', output: 'string', context: 'object' }
}, {
  qualityThreshold: 0.85
});

API Reference

IntegratedPsychoSymbolicSystem

| Method | Description | |--------|-------------| | initialize() | Initialize all components | | generateIntelligently(type, options, psychoConfig) | Generate data with psychological guidance | | intelligentQuery(query, options) | Hybrid symbolic + vector query | | analyzeText(text) | Extract sentiment and preferences | | loadKnowledgeBase(kb) | Load knowledge into both stores | | planDataGeneration(goal, constraints) | GOAP-based generation planning | | getSystemInsights() | Get system statistics | | shutdown() | Cleanup and shutdown |

PsychoGuidedGenerationConfig

| Field | Type | Description | |-------|------|-------------| | targetSentiment | { score: number, emotion: string } | Target sentiment for generated data | | userPreferences | string[] | Natural language preferences | | contextualFactors | object | Environmental context | | qualityThreshold | number | Minimum quality score (0-1) |

Related Packages

| Package | Description | |---------|-------------| | psycho-symbolic-reasoner | Core symbolic AI reasoning engine | | @ruvector/agentic-synth | AI-powered synthetic data generation | | ruvector | High-performance vector database |

License

MIT © rUv

Links

• Homepage: ruv.io
• GitHub: github.com/ruvnet/ruvector
• Issues: github.com/ruvnet/ruvector/issues