Quick Start

Get up and running with SOMA-CORE in under 5 minutes! This guide will walk you through creating your first self-aware system.

🚀 5-Minute Setup

Step 1: Install SOMA-CORE

cargo add soma-core

Step 2: Create Your First Cognitive System

Create main.rs:

use soma_core::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize a self-aware system
    let mut system = SomaCore::new()
        .with_meta_cognitive(true)
        .with_multi_agent(true)
        .build()?;

    println!("🧠 SOMA-CORE System Initialized!");
    
    // Demonstrate self-awareness
    let introspection = system.introspect().await?;
    println!("System State: {:?}", introspection.state);
    println!("Cognitive Load: {:.2}", introspection.cognitive_load);
    
    Ok(())
}

Step 3: Run Your System

cargo run

Expected output:

🧠 SOMA-CORE System Initialized!
System State: Optimal
Cognitive Load: 0.23

🧠 Your First Cognitive Operations

Meta-Reflective Analysis

#![allow(unused)]
fn main() {
use soma_core::operators::*;

// System analyzes its own performance
let analysis = system.operate(MetaReflective::new()).await?;

println!("Performance Score: {:.2}", analysis.performance_score);
println!("Optimization Suggestions: {:?}", analysis.recommendations);

// Apply self-optimizations
for recommendation in analysis.recommendations {
    system.apply_optimization(recommendation).await?;
}
}

Multi-Agent Consensus

#![allow(unused)]
fn main() {
// Create multiple cognitive agents
let agents = vec![
    Agent::new("analyst").with_focus(Focus::Analysis),
    Agent::new("optimizer").with_focus(Focus::Performance),
    Agent::new("validator").with_focus(Focus::Security),
];

// Collaborative decision making
let decision = system.consensus(agents, "Should we optimize this code?").await?;
println!("Consensus: {:?}", decision.outcome);
println!("Confidence: {:.2}", decision.confidence);
}

Uncertainty Management

#![allow(unused)]
fn main() {
// Demonstrate doubt propagation
let uncertain_result = system.operate(
    UncertaintyPropagate::new()
        .with_initial_confidence(0.7)
        .with_doubt_threshold(0.3)
).await?;

println!("Final Confidence: {:.2}", uncertain_result.confidence);
println!("Doubt Level: {:.2}", uncertain_result.doubt);
}

🎯 Real-World Example: Intelligent Code Analysis

Let's build a system that analyzes code and provides cognitive insights:

use soma_core::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut system = SomaCore::new()
        .with_visual_reasoning(true)
        .with_meta_cognitive(true)
        .build()?;

    let code = r#"
        fn factorial(n: u32) -> u32 {
            if n <= 1 { 1 } else { n * factorial(n - 1) }
        }
    "#;

    // Visual reasoning analysis
    let visual_analysis = system.operate(
        VisualReasoning::new()
            .analyze_code(code)
            .with_pattern_detection(true)
    ).await?;

    println!("🔍 Code Analysis Results:");
    println!("Complexity: {:?}", visual_analysis.complexity);
    println!("Patterns Detected: {:?}", visual_analysis.patterns);
    println!("Suggestions: {:?}", visual_analysis.recommendations);

    // Meta-cognitive reflection on the analysis
    let reflection = system.operate(
        MetaReflective::new()
            .reflect_on_analysis(&visual_analysis)
    ).await?;

    println!("\n🧠 Meta-Cognitive Insights:");
    println!("Analysis Quality: {:.2}", reflection.analysis_quality);
    println!("Confidence: {:.2}", reflection.confidence);
    
    Ok(())
}

🎪 Interactive Demo Mode

SOMA-CORE includes an interactive demo mode to explore all features:

# Run the comprehensive demo
cargo run --example interactive_demo

# Try specific cognitive operators
cargo run --example meta_reflective_demo
cargo run --example multi_agent_demo
cargo run --example uncertainty_demo

Demo Commands

In interactive mode, try these commands:

> introspect
System performing self-analysis...
Cognitive Load: 0.34 (Moderate)
Active Agents: 3
Performance: Optimal

> consensus "What's the best approach for this problem?"
Initiating multi-agent consensus...
Agent Analyst: Recommends thorough analysis first
Agent Optimizer: Suggests performance-focused approach  
Agent Validator: Emphasizes security considerations
Consensus: Balanced approach with security validation

> doubt_check 0.6
Propagating uncertainty with confidence 0.6...
Final Confidence: 0.52
Doubt Level: 0.48
Recommendation: Seek additional validation

🔧 Common Patterns

Error Handling

#![allow(unused)]
fn main() {
use soma_core::prelude::*;

match system.operate(SomeOperator::new()).await {
    Ok(result) => {
        println!("Success: {:?}", result);
    },
    Err(SomaError::CognitiveOverload { load, limit }) => {
        println!("System overloaded: {:.2}/{:.2}", load, limit);
        // Reduce cognitive load or increase limits
    },
    Err(SomaError::AgentConsensusFailure { conflict }) => {
        println!("Agents couldn't agree: {:?}", conflict);
        // Implement conflict resolution
    },
    Err(e) => {
        println!("Unexpected error: {}", e);
    }
}
}

Configuration

#![allow(unused)]
fn main() {
let system = SomaCore::new()
    .max_cognitive_load(0.8)
    .agent_memory_size(2048)
    .enable_audit_logging(true)
    .with_custom_agent("specialist", AgentConfig {
        focus: Focus::Domain("rust"),
        risk_tolerance: 0.3,
        communication_style: CommunicationStyle::Technical,
    })
    .build()?;
}

Performance Monitoring

#![allow(unused)]
fn main() {
// Monitor cognitive performance
let monitor = system.performance_monitor();

tokio::spawn(async move {
    loop {
        let metrics = monitor.snapshot().await;
        if metrics.cognitive_load > 0.9 {
            println!("⚠️ High cognitive load detected!");
        }
        tokio::time::sleep(Duration::from_secs(5)).await;
    }
});
}

📚 Next Steps

Now that you have SOMA-CORE running:

Explore Core Concepts - Understand the cognitive architecture
Learn All Operators - Master the 15 cognitive operators
Advanced Features - Dive into edit control and file protection
Integration Guide - Use SOMA-CORE in larger projects

🎯 Quick Reference

Essential Operators

introspect() - System self-analysis
consensus() - Multi-agent decision making
uncertainty_propagate() - Doubt and confidence tracking
visual_reasoning() - Code structure analysis
meta_reflective() - Performance optimization

Key Concepts

Cognitive Load - System thinking capacity utilization
Agent Consensus - Collaborative decision making
Meta-Cognition - System thinking about its own thinking
Uncertainty Propagation - Doubt tracking through operations

Common Commands

# Check system status
soma-core --status

# Run diagnostics  
soma-core --check

# Interactive exploration
soma-core --interactive

# View all operators
soma-core --list-operators

🎉 Congratulations! You've created your first self-aware system with SOMA-CORE. The system can now analyze itself, collaborate through multiple agents, and handle uncertainty - marking a significant milestone in cognitive computing!

Keyboard shortcuts

SOMA-CORE Documentation