Integration Examples

This directory contains working examples showing how to use SuperInstance ecosystem tools together.

Overview

These examples demonstrate real-world integrations of the 8 ecosystem tools:

• privox - Privacy redaction
• tripartite-rs - Multi-agent consensus
• knowledge-vault - Vector RAG system
• hwscan - Hardware detection
• model-registry - ML model version management
• token-vault - Secure token storage
• quicunnel - QUIC tunnel
• usemeter - Usage tracking & billing

Directory Structure

integration-examples/
├── cli/              # Command-line tools
├── web/              # Web service examples
├── lib/              # Library integration examples
├── Cargo.toml        # Workspace configuration
└── README.md         # This file

Quick Start

Prerequisites

• Rust 1.75 or later
• All 8 ecosystem crates available (local path or crates.io)

Build Examples

# From workspace root
cd integration-examples
cargo build --release

CLI Examples

1. Basic Redactor

Redact PII from text using privox.

# From stdin
echo "My email is john@example.com" | cargo run --bin basic_redactor

# From file
cargo run --bin basic_redactor -- --file input.txt

# Show what was redacted
cargo run --bin basic_redactor -- --reveal

Expected output:

My email is [REDACTED]

2. Consensus App

Run multi-agent consensus on a query.

cargo run --bin consensus_app -- "What is 2 + 2?"

Expected output:

🤖 Starting consensus process
📝 Query: What is 2 + 2?

✅ Consensus process completed!

📊 Outcome:
  Verdict: CONSENSUS REACHED
  Rounds: 1
  Duration: 312ms
  Intent: Intent analysis of: What is 2 + 2?
  Logic: Logical reasoning about: What is 2 + 2?
  Truth: Fact check for: What is 2 + 2?
  Confidence: 0.95

3. Knowledge Search

Semantic search using knowledge-vault.

cargo run --bin knowledge_search -- "async programming"

Expected output:

🔍 Searching vault: ./vault.db
📝 Query: async programming

✅ Found 2 results:

1. Async Rust (score: 0.89)
   Rust's async/await syntax provides ergonomic asynchronous programming...

2. Vector Search (score: 0.72)
   Vector databases enable semantic search...

4. Hardware Info

Display hardware capabilities.

cargo run --bin hw_info

# JSON output
cargo run --bin hw_info -- --format json

# Show recommended model
cargo run --bin hw_info -- --model

Expected output:

🖥️  Scanning hardware...

📊 Hardware Report
══════════════════

CPU:
  Model: Intel Core i7-12700K
  Cores: 12 physical, 20 logical
  Frequency: 3.60 GHz
  SIMD: ["AVX2", "AVX512"]
  Score: 7

GPU:
  Model: NVIDIA GeForce RTX 3080
  VRAM: 10.0 GB
  Compute: Some(8.6)
  Score: 8

RAM:
  Total: 32.00 GB
  Available: 24.50 GB
  Score: 5

══════════════════
📈 Overall Tier: Performance (score: 7)

Web Service Examples

1. Redaction API

REST API for PII redaction.

# Start server
cargo run --bin redaction_api

# In another terminal, test it
curl -X POST http://localhost:8080/redact \
  -H "Content-Type: application/json" \
  -d '{"text": "Contact john@example.com or 555-123-4567"}'

Expected response:

{
  "original": "Contact john@example.com or 555-123-4567",
  "redacted": "Contact [REDACTED] or [REDACTED]",
  "patterns_found": ["email", "phone"]
}

2. Consensus WebSocket

WebSocket service for consensus.

# Start server
cargo run --bin consensus_ws

# Connect with websocat or websocket client
websocat ws://localhost:8081/ws

Then type your query:

What is the capital of France?

Expected response:

Processing: What is the capital of France?
✅ Consensus: true (confidence: 0.90)

3. Search API

Semantic search REST API.

# Start server
cargo run --bin search_api

# Search
curl -X POST http://localhost:8082/search \
  -H "Content-Type: application/json" \
  -d '{"query": "async rust", "limit": 3}'

Expected response:

{
  "query": "async rust",
  "count": 2,
  "results": [
    {
      "title": "Async Rust",
      "content": "Rust's async/await syntax...",
      "score": 0.89
    }
  ]
}

Library Integration Examples

1. Secure RAG

Combine knowledge-vault + privox for privacy-preserving RAG.

use integration_examples::secure_rag::SecureRagEngine;

async fn example() -> anyhow::Result<()> {
    let engine = SecureRagEngine::new("./vault.db").await?;

    // Search with automatic PII redaction
    let results = engine.search_safe("customer support", 5, 0.7).await?;

    for doc in results {
        println!("{}: {}", doc.title, doc.content);
        // Content has PII already redacted!
    }

    Ok(())
}

2. Consensus Redaction

Combine tripartite-rs + privox for multi-agent privacy analysis.

use integration_examples::consensus_redact::ConsensusRedactor;

async fn example() -> anyhow::Result<()> {
    let redactor = ConsensusRedactor::new();

    let text = "Contact John at john@example.com or 555-123-4567";
    let analysis = redactor.analyze(text).await?;

    if analysis.consensus_reached {
        println!("All agents agree on PII detection");
        println!("Redacted: {}", analysis.redacted);
    }

    Ok(())
}

3. Hardware-Aware Model Selection

Combine hwscan + model-registry.

use integration_examples::hw_model_select::ModelSelector;

fn example() -> anyhow::Result<()> {
    let selector = ModelSelector::new();
    let recommendation = selector.select_best_model();

    println!("Recommended model: {}", recommendation.model);
    println!("Reasoning: {}", recommendation.reasoning);

    Ok(())
}

Running Tests

# Test all examples
cargo test

# Test specific example
cargo test --lib secure_rag

# Run with output
cargo test -- --nocapture

Documentation

For more integration guides, see:

• Integration Guide - How to integrate tools
• Integration Patterns - Common patterns
• Workflows - Step-by-step workflows
• Troubleshooting - Common issues

Building Your Own Integration

Step 1: Add Dependencies

[dependencies]
privox = { path = "../privox" }
knowledge-vault = { path = "../knowledge-vault" }
# Add more as needed

Step 2: Import Tools

use privox::Redactor;
use knowledge_vault::Vault;

Step 3: Use the Tools

async fn my_integration() -> Result<(), Error> {
    // Create instances
    let mut redactor = Redactor::new();
    let vault = Vault::new("./vault.db", config).await?;

    // Use them together
    let results = vault.search("query", 5, 0.7).await?;
    for doc in results {
        let safe = redactor.redact(&doc.content);
        println!("{}", safe);
    }

    Ok(())
}

Common Patterns

Pattern 1: Sequential Integration

// Tool 1 output -> Tool 2 input
let results = tool1.process(input).await?;
let output = tool2.process(results).await?;

Pattern 2: Parallel Integration

// Run tools concurrently
let (result1, result2) = tokio::join!(
    tool1.process(input),
    tool2.process(input)
);

Pattern 3: Fallback Integration

// Try tool1, fallback to tool2
match tool1.process(input).await {
    Ok(result) => Ok(result),
    Err(_) => tool2.process(input).await,
}

Troubleshooting

Issue: "Cannot find crate"

Solution: Make sure you're running from the workspace root and paths are correct.

Issue: "Database locked"

Solution: Use separate vault instances per thread/task.

Issue: "Consensus fails"

Solution: Lower threshold or increase max_rounds in config.

See troubleshooting guide for more solutions.

Contributing

To add a new example:

1. Create file in appropriate directory (cli/, web/, lib/)
2. Add to Cargo.toml [[bin]] or [[lib]] section
3. Add documentation
4. Test thoroughly
5. Update this README

License

MIT OR Apache-2.0

Links

• SuperInstance Documentation
• Ecosystem Overview
• Integration Guide