brainy/docs/guides/intelligent-verb-scoring.md

Intelligent Verb Scoring

The Intelligent Verb Scoring feature in Brainy automatically generates weight and confidence scores for verb relationships using semantic analysis, frequency patterns, and temporal factors. This feature is off by default and requires explicit configuration to enable.

Quick Start

The simplest way to enable intelligent verb scoring with no configuration:

import { BrainyData } from '@soulcraft/brainy'

// Enable with minimal configuration
const db = new BrainyData({
  intelligentVerbScoring: {
    enabled: true  // That's it! Uses intelligent defaults
  }
})

await db.init()

// Now when you add verbs without specifying weight, they get intelligent scores
await db.addVerb('user123', 'project456', 'contributesTo')
// ↳ Automatically gets semantic similarity score, frequency boost, etc.

How It Works

When you add a verb relationship without specifying a weight (or with the default weight of 0.5), the system:

1. Semantic Analysis: Calculates similarity between entity embeddings
2. Frequency Amplification: Boosts weight for repeated relationships
3. Temporal Decay: Applies time-based decay to relationship strength
4. Learning Adaptation: Uses historical patterns to refine scores

Configuration Options

const db = new BrainyData({
  intelligentVerbScoring: {
    enabled: true,                        // Required: enable the feature
    enableSemanticScoring: true,          // Use entity embeddings (default: true)
    enableFrequencyAmplification: true,   // Boost repeated relationships (default: true)
    enableTemporalDecay: true,            // Apply time decay (default: true)
    temporalDecayRate: 0.01,              // 1% decay per day (default: 0.01)
    minWeight: 0.1,                       // Minimum weight (default: 0.1)
    maxWeight: 1.0,                       // Maximum weight (default: 1.0)
    baseConfidence: 0.5,                  // Starting confidence (default: 0.5)
    learningRate: 0.1                     // How fast to learn (default: 0.1)
  }
})

Usage Examples

Basic Usage (Zero Configuration)

const db = new BrainyData({
  intelligentVerbScoring: { enabled: true }
})
await db.init()

// Add entities
await db.add('john', 'John is a software developer')
await db.add('project-x', 'Project X is a web application')

// Add relationship - gets intelligent scoring automatically
const relationId = await db.addVerb('john', 'project-x', 'worksOn')

// The system computed weight and confidence based on:
// - Semantic similarity between "software developer" and "web application"
// - This being the first occurrence (no frequency boost yet)
// - Current timestamp (no temporal decay)

Learning from Feedback

// Provide feedback to improve future scoring
await db.provideFeedbackForVerbScoring(
  'john', 'project-x', 'worksOn',
  0.9,         // corrected weight
  0.85,        // corrected confidence  
  'correction' // feedback type
)

// Future similar relationships will use this learning
await db.addVerb('jane', 'project-y', 'worksOn')
// ↳ Benefits from previous feedback about 'worksOn' relationships

Monitoring Learning Progress

// Get learning statistics
const stats = db.getVerbScoringStats()
console.log(stats)
// {
//   totalRelationships: 150,
//   averageConfidence: 0.73,
//   feedbackCount: 12,
//   topRelationships: [
//     { relationship: "user-worksOn-project", count: 45, averageWeight: 0.82 },
//     { relationship: "user-contributesTo-repo", count: 23, averageWeight: 0.67 }
//   ]
// }

Export and Import Learning Data

// Backup learning data
const learningData = db.exportVerbScoringLearningData()
localStorage.setItem('verb-scoring-backup', learningData)

// Restore learning data
const savedData = localStorage.getItem('verb-scoring-backup')
if (savedData) {
  db.importVerbScoringLearningData(savedData)
}

Advanced Usage

Custom Scoring Strategy

const db = new BrainyData({
  intelligentVerbScoring: {
    enabled: true,
    
    // Emphasize semantic similarity over frequency
    enableSemanticScoring: true,
    enableFrequencyAmplification: false,
    enableTemporalDecay: false,
    
    // More conservative scoring
    baseConfidence: 0.3,
    minWeight: 0.2,
    maxWeight: 0.8
  }
})

High-Frequency Learning Setup

const db = new BrainyData({
  intelligentVerbScoring: {
    enabled: true,
    
    // Fast adaptation for real-time systems
    learningRate: 0.3,              // Learn quickly from feedback
    enableFrequencyAmplification: true,
    temporalDecayRate: 0.05,        // Faster decay (5% per day)
    
    // Confident scoring for established patterns
    baseConfidence: 0.7
  }
})

Understanding the Output

When intelligent scoring is active, verb metadata includes additional fields:

// Retrieve a verb to see intelligent scoring data
const verb = await db.getVerb(relationId)
console.log(verb.metadata)

// Output includes:
{
  sourceId: 'john',
  targetId: 'project-x', 
  type: 'worksOn',
  weight: 0.73,                    // ← Computed weight
  confidence: 0.68,                // ← Computed confidence
  intelligentScoring: {            // ← Scoring details
    reasoning: [
      'Semantic similarity: 0.821',
      'Frequency boost: 0.602', 
      'Temporal factor: 1.000',
      'Final weight: 0.730, confidence: 0.680'
    ],
    computedAt: '2024-01-15T10:30:00Z'
  },
  createdAt: '2024-01-15T10:30:00Z',
  // ... other metadata
}

Best Practices

1. Start Simple

Begin with just enabled: true and let the system use intelligent defaults.

2. Provide Feedback

The system learns best when you provide feedback on incorrect scores:

// When you notice a weight should be higher/lower
await db.provideFeedbackForVerbScoring(
  sourceId, targetId, verbType,
  correctWeight, correctConfidence, 'correction'
)

3. Monitor Learning

Regularly check learning statistics to ensure the system is improving:

const stats = db.getVerbScoringStats()
if (stats.feedbackCount < 10) {
  console.log('Consider providing more feedback for better learning')
}

4. Backup Learning Data

Export learning data periodically to preserve improvements:

// Weekly backup
setInterval(() => {
  const backup = db.exportVerbScoringLearningData()
  saveToStorage('verb-scoring-backup', backup)
}, 7 * 24 * 60 * 60 * 1000)

When to Use

Good for:

• Knowledge graphs where relationship strength matters
• Systems that need to distinguish between weak and strong connections
• Applications that can provide user feedback on relationship quality
• Long-running systems that benefit from learning patterns

Not ideal for:

• Simple binary relationships (exists/doesn't exist)
• Systems where all relationships have equal weight
• One-time data imports without ongoing usage
• Performance-critical paths where extra computation isn't acceptable

Performance Considerations

• Minimal overhead: Only computes scores when weight isn't explicitly provided
• Semantic calculation: Requires loading entity embeddings (cached after first access)
• Learning storage: Relationship statistics are stored in memory (export for persistence)
• Adaptive complexity: More relationships = better accuracy but slightly more computation

Troubleshooting

Scores seem too conservative

// Increase base confidence and learning rate
intelligentVerbScoring: {
  baseConfidence: 0.7,  // instead of default 0.5
  learningRate: 0.2     // instead of default 0.1
}

Scores change too quickly

// Reduce learning rate and temporal decay
intelligentVerbScoring: {
  learningRate: 0.05,      // slower adaptation
  temporalDecayRate: 0.005 // slower decay
}

Not seeing semantic benefits

// Ensure semantic scoring is enabled and entities have good embeddings
intelligentVerbScoring: {
  enableSemanticScoring: true,
  // Add more descriptive content to your entities
  // The system works better with rich entity descriptions
}

Integration Examples

With Existing Workflows

// Migrate existing data to use intelligent scoring
const existingVerbs = await db.getAllVerbs()

for (const verb of existingVerbs) {
  if (!verb.metadata.weight || verb.metadata.weight === 0.5) {
    // Let intelligent scoring re-evaluate
    await db.addVerb(
      verb.metadata.sourceId,
      verb.metadata.targetId, 
      verb.metadata.type
      // No weight specified - triggers intelligent scoring
    )
  }
}

With User Interfaces

// Allow users to correct relationship strengths
async function updateRelationshipStrength(relationId, userWeight) {
  const verb = await db.getVerb(relationId)
  
  await db.provideFeedbackForVerbScoring(
    verb.metadata.sourceId,
    verb.metadata.targetId,
    verb.metadata.type,
    userWeight,
    undefined,
    'correction'
  )
  
  // Update the actual relationship
  await db.updateVerb(relationId, { weight: userWeight })
}

---

The Intelligent Verb Scoring system provides a powerful way to automatically assess relationship quality while learning from your specific use case. Start with the defaults, provide feedback when possible, and watch the system improve over time.