Shaunebu.Common.Intelligence 1.0.0

A powerful, privacy-first local intelligence framework for .NET applications. Analyze user behavior, generate insights, and discover patterns entirely offline without external dependencies.

🌟 Features

🎯 Core Intelligence

• Local Behavior Tracking - Monitor user interactions and feature usage

• Automatic Insight Generation - Get recommendations and suggestions based on usage patterns

• Pattern Detection - Discover usage sequences, correlations, and time-based patterns

• Real-time Analytics - Analyze behavior as it happens

🛡️ Enterprise Ready

• 100% Offline - No internet connection required

• Privacy First - All data stays on device

• Thread Safe - Built for multi-threaded environments

• Error Resilient - Robust error handling and recovery

• Performance Optimized - Efficient memory and storage usage

📊 Advanced Analytics

• Usage Frequency - Track most-used features

• Behavior Sequences - Discover common workflow patterns

• Time-based Analysis - Identify peak usage times

• Feature Correlations - Find related features

• Confidence Scoring - Measure pattern reliability

📊 Feature Comparison Table

🚀 Quick Start

Installation

dotnet add package Shaunebu.Common.Intelligence

Basic Usage

using Microsoft.Extensions.DependencyInjection;
using Shaunebu.Common.Intelligence.Extensions;

// Setup DI
var services = new ServiceCollection();
services.AddLocalIntelligence();

var provider = services.BuildServiceProvider();
var intelligence = provider.GetRequiredService<ILocalIntelligenceService>();

// Track user behavior
await intelligence.TrackFeatureUsageAsync("ExportData", "clicked", new Dictionary<string, object>
{
    ["FileType"] = "PDF",
    ["SizeKB"] = 2048
});

// Get insights
var insights = await intelligence.GetActiveInsightsAsync();
foreach (var insight in insights)
{
    Console.WriteLine($"{insight.Title}: {insight.Message}");
}

📖 Documentation

Configuration

services.AddLocalIntelligence(options =>
{
    options.StoragePath = "path/to/your/data";
    options.DataRetentionPeriod = TimeSpan.FromDays(90);
    options.MaxBehaviorsInMemory = 5000;
    options.RateLimitPerMinute = 100;
    options.EnableEncryption = true;
    options.MinimumBehaviorsForAnalysis = 10;
});

Tracking Behavior

// Simple feature tracking
await intelligence.TrackFeatureUsageAsync("Search", "executed");

// With metadata
await intelligence.TrackFeatureUsageAsync("DocumentEdit", "saved", new Dictionary<string, object>
{
    ["DocumentType"] = "Presentation",
    ["Changes"] = 15,
    ["DurationSeconds"] = 45
});

// Custom behavior object
var behavior = new UserBehavior
{
    Feature = "Export",
    Action = "completed",
    Duration = TimeSpan.FromSeconds(30),
    Metadata = new Dictionary<string, object>
    {
        ["Format"] = "PDF",
        ["Pages"] = 25
    }
};
await intelligence.TrackBehaviorAsync(behavior);

Generating Insights

// Generate insights from current data
var newInsights = await intelligence.GenerateInsightsAsync();

// Get active insights
var activeInsights = await intelligence.GetActiveInsightsAsync();

// Dismiss an insight
await intelligence.DismissInsightAsync(insightId);

Analytics & Patterns

// Get usage patterns
var patterns = await intelligence.GetUsagePatternsAsync(TimeSpan.FromDays(30));

// Top features
var topFeatures = await intelligence.GetTopFeaturesAsync(5);

// Behavior sequences
var sequences = await intelligence.GetBehaviorSequencesAsync();

// Feature correlations  
var correlations = await intelligence.GetFeatureCorrelationsAsync();

// Analysis summary
var summary = await intelligence.GetAnalysisSummaryAsync();

Data Management

// Export data
await intelligence.ExportDataAsync("path/to/export.json");

// Clear old data
await intelligence.ClearOldDataAsync(TimeSpan.FromDays(365));

// Get statistics
var totalBehaviors = await intelligence.GetTotalBehaviorsCountAsync();
var counters = intelligence.GetPerformanceCounters();

🎯 Use Cases

Document Processing App

public class DocumentService
{
    private readonly ILocalIntelligenceService _intelligence;
    
    public async Task ProcessDocumentAsync(string filePath)
    {
        await _intelligence.TrackFeatureUsageAsync("DocumentImport", "started");
        
        // Process document...
        
        await _intelligence.TrackFeatureUsageAsync("DocumentImport", "completed", new Dictionary<string, object>
        {
            ["FileSize"] = new FileInfo(filePath).Length,
            ["ProcessingTime"] = stopwatch.ElapsedMilliseconds
        });
        
        // Check for insights
        var insights = await _intelligence.GetActiveInsightsAsync();
        await ShowRelevantInsightsAsync(insights);
    }
}

E-commerce App

public class ProductService
{
    public async Task TrackUserJourneyAsync(string userId, string action, Dictionary<string, object> metadata)
    {
        await _intelligence.TrackFeatureUsageAsync($"User.{action}", "performed", metadata);
        
        // Insights might reveal:
        // - "Users who view electronics often check reviews"
        // - "Peak shopping time is 7-9 PM"
        // - "Mobile users prefer one-click checkout"
    }
}

🔧 Advanced Usage

Custom Insight Engine

public class CustomInsightEngine : IInsightEngine
{
    public async Task<List<LocalInsight>> AnalyzeBehaviorsAsync(List<UserBehavior> behaviors)
    {
        var insights = new List<LocalInsight>();
        
        // Your custom analysis logic
        if (behaviors.Count(b => b.Feature == "PremiumFeature") > 10)
        {
            insights.Add(new LocalInsight
            {
                Type = InsightType.Recommendation,
                Title = "Power User Detected",
                Message = "You're using premium features frequently. Consider upgrading?",
                Priority = InsightPriority.Medium
            });
        }
        
        return insights;
    }
}

// Registration
services.AddLocalIntelligenceWithCustomStorage<CustomInsightEngine>();

Custom Storage

public class DatabaseStorage : IBehaviorStorage
{
    public async Task SaveBehaviorsAsync(IEnumerable<UserBehavior> behaviors)
    {
        // Save to your database
        await _dbContext.Behaviors.AddRangeAsync(behaviors);
        await _dbContext.SaveChangesAsync();
    }
    
    // Implement other methods...
}

// Registration
services.AddLocalIntelligenceWithCustomStorage<DatabaseStorage>();

📊 Insight Types

🛡️ Privacy & Security

• No Data Leaves Device - All processing happens locally

• Encrypted Storage - Optional AES encryption for stored data

• PII Filtering - Automatic filtering of sensitive information

• Data Retention Control - Configurable data lifespan

• Export Control - Full control over data exports

📈 Performance

• Memory Efficient - Configurable in-memory limits

• Background Processing - Non-blocking operations

• Rate Limiting - Prevents excessive tracking

• Optimized Storage - Efficient serialization and compression

🔍 Monitoring

// Get performance metrics
var counters = intelligence.GetPerformanceCounters();
Console.WriteLine($"Behaviors tracked: {counters.TotalBehaviorsTracked}");
Console.WriteLine($"Insights generated: {counters.InsightsGenerated}");
Console.WriteLine($"Storage operations: {counters.StorageOperations}");

// Health check
try
{
    var count = await intelligence.GetTotalBehaviorsCountAsync();
    Console.WriteLine("Service is healthy");
}
catch (Exception ex)
{
    Console.WriteLine($"Service health check failed: {ex.Message}");
}

🐛 Troubleshooting

Common Issues

Q: Getting "Lock timeout" errors?
A: Ensure all lock acquisitions have matching releases in finally blocks. Q: Insights not generating?
A: Check MinimumBehaviorsForAnalysis configuration and ensure enough data is collected. Q: Storage corruption?
A: The library includes automatic recovery mechanisms. Use RecoverFromCorruptedDataAsync() if needed. Q: Performance issues?
A: Adjust MaxBehaviorsInMemory and enable compression in options.

Logging

Enable detailed logging to monitor operations:

services.AddLogging(builder => 
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug));