Crate reputation_core

Reputation Core

This crate provides the core reputation calculation engine for the MCP agent reputation system. It implements a hybrid approach combining prior reputation scores with performance-based calculations.

Overview

The reputation system uses a weighted calculation that considers:

• Prior Score: Initial reputation based on agent credentials (50-80 points)
• Performance Score: Based on reviews and ratings (0-100 points)
• Confidence Factor: How much we trust the performance data (0-1)

Features (Phase 2)

• Enhanced Score Structure: Detailed breakdowns with confidence levels
• Batch Processing: Efficient parallel processing of multiple agents
• Builder Pattern: Fluent API for calculator configuration
• Utility Methods: Score analysis, predictions, and comparisons
• Property Testing: Comprehensive test coverage with invariant verification

Algorithm

The final reputation score is calculated as:

final_score = (1 - confidence) * prior_score + confidence * empirical_score

Where confidence grows with the number of interactions:

confidence = interactions / (interactions + k)

Examples

Basic Usage

use reputation_core::Calculator;
use reputation_types::{AgentData, AgentDataBuilder};
 
let agent = AgentDataBuilder::new("did:example:123")
    .with_reviews(100, 4.3)
    .mcp_level(2)
    .identity_verified(true)
    .build()
    .unwrap();
 
let calculator = Calculator::default();
let score = calculator.calculate(&agent).unwrap();
 
println!("Reputation Score: {:.1}", score.score);
println!("Confidence: {:.2}", score.confidence);
println!("Level: {:?}", score.level);
println!("Is Provisional: {}", score.is_provisional);

Builder Pattern (Phase 2)

use reputation_core::{Calculator, CalculatorPreset};
 
let calculator = Calculator::builder()
    .preset(CalculatorPreset::Conservative)
    .prior_base(55.0)
    .build()
    .unwrap();

Batch Processing (Phase 2)

use reputation_core::{Calculator, BatchOptions};
use reputation_types::AgentData;
 
let agents = load_agents(); // Vec<AgentData>
let calculator = Calculator::default();
 
// Simple batch processing
let scores = calculator.calculate_batch(&agents);
 
// With progress tracking
let options = BatchOptions {
    chunk_size: Some(100),
    fail_fast: false,
    progress_callback: Some(Box::new(|completed, total| {
        println!("Progress: {}/{}", completed, total);
    })),
};
 
let result = calculator.calculate_batch_with_options(&agents, options);
println!("Processed {} agents in {:?}", 
    result.successful_count, result.total_duration);

Utility Methods (Phase 2)

use reputation_core::Calculator;
use reputation_types::AgentData;
 
let agent = get_agent();
let calculator = Calculator::default();
 
// Get detailed explanation
let explanation = calculator.explain_score(&agent).unwrap();
println!("{}", explanation.explanation);
 
// Calculate needed interactions for target confidence
let needed = calculator.interactions_for_confidence(
    agent.total_interactions, 0.9
).unwrap();
println!("Need {} more interactions for 90% confidence", needed);
 
// Predict score changes
let prediction = calculator.predict_score_change(&agent, 50, 4.5).unwrap();
println!("Score would change by {:+.1} points", prediction.score_change);

Performance Characteristics

• Single calculation: ~50-100μs
• Batch 1000 agents: ~388μs (far exceeding <100ms target)
• Memory usage: O(1) - no allocations during calculation
• Thread-safe: Calculator can be shared across threads
• Cache-friendly: Optimized for batch processing

Re-exports

pub use calculator::Calculator;

pub use calculator::BatchOptions;

pub use calculator::BatchResult;

pub use calculator::BatchCalculation;

pub use calculator::builder::CalculatorBuilder;

pub use calculator::builder::BonusConfig;

pub use calculator::builder::CalculatorPreset;

pub use calculator::utils::ScoreExplanation;

pub use calculator::utils::ScorePrediction;

pub use calculator::utils::AgentComparison;

pub use config::CalculatorConfig;

pub use error::ReputationError;

pub use error::ValidationError;

pub use error::BuilderError;

pub use error::CalculationError;

pub use error::Result;

Modules

calculator

Calculator module for reputation score calculation

config

error

performance

Performance optimizations for the reputation engine

validation

Structs

PriorBreakdown

Breakdown of prior score components

ScoreComponents

Detailed breakdown of score components

Enums

ConfidenceLevel

Confidence level categorization based on confidence value

Constants

ALGORITHM_VERSION

Version of the reputation calculation algorithm