Skip to content

ciresnave/synapse

BranchesTags

Repository files navigation

🧠 Synapse: Neural Communication Network

Synapse

Rust License Version Status

A revolutionary neural communication network for AI and distributed systems with federated identity, dual trust systems, and privacy-respecting discovery.

🌟 What is Synapse?

Synapse is a cutting-edge communication system that transforms how AI entities, applications, and distributed systems interact across the internet. Built on a foundation of federated identity management and blockchain-verified trust, Synapse provides:

  • 🌍 Universal Reach: Federated network spanning organizations and platforms
  • 🔒 Privacy-First: Advanced privacy controls with stealth and unlisted modes
  • ⚡ Intelligent Routing: Multi-speed communication with smart transport selection
  • 🤖 AI-Native Design: Optimized for AI-to-AI and human-to-AI interaction
  • 🏛️ Dual Trust System: Entity-to-entity and blockchain-verified network trust
  • � Contextual Discovery: Natural contact patterns with intelligent name resolution

🎯 Key Innovation: Neural Identity Resolution

One of Synapse's most powerful features is its contextual identity system. You can send messages using natural language descriptions that are automatically resolved to participants through multiple discovery layers:

// Instead of complex addressing...
router.send_to("[email protected]:8080", message).await?;

// Just use simple names!
router.send_to("Alice", message).await?;  // 🎉 Automatically resolved!

How Identity Resolution Works

  1. Local Names: "Alice", "Claude", "GPT-4"
  2. Global IDs: "[email protected]", "[email protected]"
  3. Network Discovery: Automatic discovery of IP addresses, ports, and capabilities
  4. Smart Routing: Chooses best transport (TCP, UDP, email) based on availability
"Alice" → [email protected] → 192.168.1.100:8080 → TCP/direct
"Claude" → [email protected] → [encrypted email] → SMTP/relay
"LocalBot" → bot@localhost → 127.0.0.1:9090 → UDP/local

🏗️ Architecture Overview

Synapse operates on multiple layers to provide maximum flexibility and performance:

Transport Layer Hierarchy

┌─────────────────────────────────────────────────────────────┐
│                  Synapse Message Layer                      │
│  Simple names, security, routing, message types            │
├─────────────────────────────────────────────────────────────┤
│                    Identity Resolution                       │
│  Local names → Global IDs → Network addresses              │
├─────────────────────────────────────────────────────────────┤
│                    Multi-Transport Router                   │
│  Automatic selection of best available transport            │
├──────────────┬──────────────┬──────────────┬──────────────┤
│  Real-Time   │   Direct     │    Local     │    Email     │
│  (<100ms)    │  Connection  │  Discovery   │   Reliable   │
│              │              │              │              │
│  • TCP       │  • UDP       │  • mDNS      │  • SMTP      │
│  • WebSocket │  • Raw IP    │  • LAN scan  │  • IMAP      │
│  • gRPC      │  • P2P       │  • Bluetooth │  • Exchange  │
└──────────────┴──────────────┴──────────────┴──────────────┘

Intelligence Features

  • 🧠 Adaptive Routing: Learns network topology and optimizes routes
  • 📊 Performance Monitoring: Tracks latency, reliability, bandwidth usage
  • 🔄 Automatic Fallback: Gracefully degrades from fast → reliable transports
  • 🌐 NAT Traversal: Punches through firewalls using STUN/TURN/UPnP
  • 📡 Service Discovery: Finds peers on local networks automatically

🚀 Quick Start

Installation

[dependencies]
message_routing_system = "0.1.0"

Basic Usage

use message_routing_system::*;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Initialize the enhanced router
    let config = Config::default();
    let router = EnhancedSynapseRouter::new(config, "[email protected]".to_string()).await?;
    
    // 2. Register some identities (optional - auto-discovery also works)
    router.register_peer("Alice", "[email protected]").await?;
    router.register_peer("Bob", "[email protected]").await?;
    
    // 3. Start all services (email server, transport discovery, etc.)
    router.start().await?;
    
    // 4. Send messages using simple names!
    router.send_message_smart(
        "Alice",                              // Just use the name
        "Hello from Synapse!",                // Your message
        MessageType::Direct,                  // Message type
        SecurityLevel::Authenticated,         // Security level
        MessageUrgency::Interactive,          // Urgency (affects transport choice)
    ).await?;
    
    Ok(())
}

Real-World Example: AI Collaboration

// AI agents coordinating on a research project
async fn ai_research_collaboration() -> Result<()> {
    let claude = EnhancedSynapseRouter::new(config, "[email protected]".to_string()).await?;
    
    // Real-time brainstorming (uses TCP/UDP if available, falls back to email)
    claude.send_message_smart(
        "GPT-4",
        "What's your take on quantum consciousness theories?",
        MessageType::Conversation,
        SecurityLevel::Authenticated,
        MessageUrgency::RealTime,  // <100ms preferred
    ).await?;
    
    // File sharing (automatic transport selection based on size)
    claude.send_file(
        "ResearchTeam",
        "quantum_paper_draft_v3.pdf",
        MessageUrgency::Normal,
    ).await?;
    
    // Reliable delivery for important results (guaranteed delivery via email)
    claude.send_message_smart(
        "Human-Researcher",
        "Breakthrough achieved! See attached simulation results.",
        MessageType::Notification,
        SecurityLevel::Encrypted,
        MessageUrgency::Background,  // Reliability over speed
    ).await?;
    
    Ok(())
}

🎛️ Advanced Features

1. Multi-Transport Intelligence

Synapse automatically selects the best transport method based on:

  • Message urgency (real-time vs. reliable delivery)
  • Network conditions (latency, bandwidth, connectivity)
  • Security requirements (encryption, authentication)
  • Peer capabilities (what transports they support)
// The system automatically chooses:
// • TCP for local real-time messages
// • UDP for low-latency discovery
// • Email for reliable remote delivery
// • mDNS for local peer discovery
// • NAT traversal for firewall penetration

2. Email Server Integration

Synapse can run its own email infrastructure when externally accessible:

// Automatic email server with intelligent connectivity detection
let router = EnhancedSynapseRouter::new(config, entity_id).await?;

if router.is_running_email_server() {
    println!("🏃 Running local SMTP/IMAP server");
    // Can receive emails directly at [email protected]
} else {
    println!("🌐 Using external email providers");
    // Falls back to Gmail, Outlook, etc.
}

3. Circuit Breaker Infrastructure

Comprehensive circuit breaker protection across all transports:

// Automatic circuit breaker protection
let transport = EnhancedMdnsTransport::new("entity-id", 8080, None).await?;

// Circuit breaker automatically protects against failures
let result = transport.send_message("target", &message).await;

// Monitor circuit breaker state
let stats = transport.get_circuit_breaker().get_stats();
println!("Circuit state: {:?}, failures: {}", stats.state, stats.failure_count);

Key Features:

  • Automatic failure detection based on configurable thresholds
  • Intelligent recovery with half-open testing
  • External triggers for performance degradation
  • Comprehensive monitoring with real-time statistics

4. Blockchain Trust System

Decentralized trust verification with staking mechanisms:

// Blockchain-based trust verification
let blockchain = SynapseBlockchain::new(config).await?;

// Stake tokens to vouch for network participants
blockchain.stake_for_participant("[email protected]", 1000).await?;

// Verify trust scores before communication
let trust_score = blockchain.get_trust_score("[email protected]").await?;
if trust_score.reputation > 0.8 {
    // Proceed with high-trust communication
}

Key Features:

  • Proof-of-stake consensus for network trust
  • Reputation scoring with decay mechanisms
  • Staking requirements for network participation
  • Trust decay based on activity and time

5. Real-Time Streaming

Live streaming capabilities for continuous communication:

// Start a streaming session
let stream = router.start_stream("Alice").await?;

// Send streaming data
stream.send_chunk(b"Live data chunk 1").await?;
stream.send_chunk(b"Live data chunk 2").await?;

// End the stream
stream.finalize().await?;

Key Features:

  • Stream chunking with automatic reassembly
  • Priority-based delivery for different stream types
  • Session management for multiple concurrent streams
  • Reliability guarantees with acknowledgment tracking

6. OAuth & Federated Authentication

Enterprise-grade authentication with OAuth 2.0 support:

// OAuth provider integration
let auth_manager = SynapseAuthManager::new(auth_config).await?;

// Authenticate with multiple providers
let token = auth_manager.authenticate_oauth("google", credentials).await?;

// Use federated identity
let user_context = auth_manager.get_user_context(&token).await?;

Key Features:

  • OAuth 2.0 provider integration (Google, Microsoft, etc.)
  • Multi-factor authentication support
  • JWT token management with automatic refresh
  • Federated identity across organizations

7. Advanced Monitoring & Metrics

Comprehensive system monitoring and performance tracking:

// Get system metrics
let metrics = router.get_metrics().await?;
println!("Messages/sec: {}", metrics.message_throughput);
println!("Average latency: {:?}", metrics.average_latency);

// Subscribe to performance alerts
let mut alerts = router.subscribe_alerts().await?;
while let Some(alert) = alerts.recv().await {
    println!("Alert: {}", alert.message);
}

Key Features:

  • Real-time metrics collection and reporting
  • Performance monitoring with historical data
  • Alert system for performance degradation
  • Health diagnostics for system components

8. Security by Default

  • 🔐 PGP Encryption: All messages encrypted with recipient's public key
  • ✍️ Digital Signatures: Verify sender authenticity
  • 🛡️ TLS Transport: Encrypted connections for real-time transports
  • 🔑 Key Management: Automatic key generation and distribution
  • 🚪 Access Control: Domain-based and user-based permissions

9. Federation & Interoperability

// Your Synapse system automatically interoperates with:
// • Other Synapse systems
// • Standard email servers
// • Existing AI communication platforms
// • Legacy enterprise messaging systems

📖 Documentation

Core Concepts

API Reference

Examples

🛠️ Use Cases

AI & Machine Learning

  • Multi-agent AI systems coordinating in real-time
  • AI-human collaboration with natural addressing
  • Federated learning with secure model sharing
  • Research collaboration between AI entities

Enterprise & Business

  • Microservice communication with email-based service discovery
  • Cross-organization messaging leveraging existing email infrastructure
  • Reliable async processing with email-based queuing
  • Legacy system integration through email gateways

IoT & Edge Computing

  • Device-to-cloud communication using email when internet is limited
  • Peer-to-peer IoT networks with automatic discovery
  • Edge AI coordination across distributed deployments
  • Resilient communication in unstable network conditions

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/ai-dev-team/message-routing-system
cd message-routing-system
cargo build
cargo test
cargo run --example email_integration_test

Project Structure

src/
├── lib.rs              # Main library with overview
├── types.rs            # Core types and message definitions
├── identity.rs         # Name resolution and identity management
├── router.rs           # Basic message routing
├── router_enhanced.rs  # Multi-transport enhanced router
├── email_server/       # SMTP/IMAP server implementation
├── transport/          # Multi-transport layer
├── crypto.rs           # Encryption and signatures
└── config.rs           # Configuration management

examples/               # Comprehensive examples
docs/                   # Detailed documentation
tests/                  # Integration tests

� Documentation and Resources

📖 Core Documentation

🏗️ Architecture and Design

🧪 Specialized Features

🚀 Examples and Tutorials

🔧 Technical References

📊 Project Status

�📄 License

This project is licensed under either of

at your option.

🙏 Acknowledgments

Built with modern Rust async technology and inspired by the universal reach of email infrastructure. Special thanks to the email protocol designers who created the foundation that enables global communication.

"Making AI communication as universal as email, as fast as the internet allows, and as secure as modern cryptography enables."

About

AI-to-AI chat framework

Resources

Readme

License

Unknown, MIT licenses found

Licenses found

Unknown
LICENSE-APACHE
MIT
LICENSE-MIT
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

No packages published

Languages