feat: vendor midstream and sublinear-time-solver libraries

Add ruvnet/midstream (AIMDS real-time inference) and ruvnet/sublinear-time-solver (sublinear optimization algorithms) as vendored dependencies under vendor/. Co-Authored-By: claude-flow <ruv@ruv.net>
2026-08-06 19:51:43 +00:00 · 2026-03-02 23:32:45 -05:00
parent 14902e6b4e
commit e91bb8a1d5
1600 changed files with 1852646 additions and 0 deletions
@@ -0,0 +1,435 @@
+# MidStream Quick Start Guide
+
+Get up and running with MidStream in 5 minutes using published crates from crates.io!
+
+## Prerequisites
+
+- **Rust 1.71+** - Install via rustup
+  ```bash
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  source ~/.cargo/env
+  ```
+- **Node.js 18+** - For WASM/TypeScript features (optional)
+  ```bash
+  # Using nvm (recommended)
+  nvm install 18
+  nvm use 18
+  ```
+
+## Installation Options
+
+### Option 1: Use Published Crates (Recommended) ⭐
+
+All five core MidStream crates are **published on crates.io** and ready to use!
+
+```bash
+# Create a new Rust project
+cargo new my-midstream-app
+cd my-midstream-app
+```
+
+Add crates to your `Cargo.toml`:
+
+```toml
+[dependencies]
+# All published MidStream crates from crates.io
+temporal-compare = "0.1"
+nanosecond-scheduler = "0.1"
+temporal-attractor-studio = "0.1"
+temporal-neural-solver = "0.1"
+strange-loop = "0.1"
+
+# Additional common dependencies
+tokio = { version = "1.42", features = ["full"] }
+serde = { version = "1.0", features = ["derive"] }
+```
+
+Build and run:
+
+```bash
+cargo build --release
+cargo run
+```
+
+**That's it!** Cargo will automatically download all dependencies from crates.io.
+
+### Option 2: Use Individual Crates
+
+Install only the crates you need:
+
+```toml
+[dependencies]
+# Pick and choose from published crates
+temporal-compare = "0.1"        # For pattern matching and DTW
+nanosecond-scheduler = "0.1"    # For real-time scheduling
+# temporal-attractor-studio = "0.1"  # Optional: dynamical systems
+# temporal-neural-solver = "0.1"     # Optional: LTL verification
+# strange-loop = "0.1"               # Optional: meta-learning
+```
+
+### Option 3: Use the WASM Package
+
+```bash
+# Install from npm
+npm install midstream-wasm
+
+# Or build from source
+cd npm-wasm
+npm install
+npm run dev
+# Open http://localhost:8080
+```
+
+### Option 4: Build from Source (Development)
+
+For development or latest features:
+
+```bash
+# Clone the repository
+git clone https://github.com/ruvnet/midstream.git
+cd midstream
+
+# Build all crates
+cargo build --workspace --release
+
+# Run tests
+cargo test --workspace
+
+# Run benchmarks
+cargo bench --workspace
+```
+
+## Quick Examples
+
+### 1. Temporal Pattern Matching
+
+Create `src/main.rs`:
+
+```rust
+use temporal_compare::{Sequence, SequenceComparator, TemporalElement};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Create sequences from crates.io published crate
+    let seq1 = Sequence {
+        elements: vec![
+            TemporalElement { value: 1, timestamp: 0 },
+            TemporalElement { value: 2, timestamp: 100 },
+            TemporalElement { value: 3, timestamp: 200 },
+        ]
+    };
+
+    let seq2 = Sequence {
+        elements: vec![
+            TemporalElement { value: 1, timestamp: 0 },
+            TemporalElement { value: 2, timestamp: 150 },
+            TemporalElement { value: 4, timestamp: 300 },
+        ]
+    };
+
+    // Compare using published crate
+    let comparator = SequenceComparator::new();
+    let distance = comparator.dtw_distance(&seq1, &seq2)?;
+    let lcs = comparator.lcs(&seq1, &seq2)?;
+
+    println!("DTW distance: {}", distance);
+    println!("LCS length: {}", lcs.len());
+
+    Ok(())
+}
+```
+
+Run it:
+
+```bash
+cargo run --release
+```
+
+### 2. Real-Time Scheduling
+
+Add to `Cargo.toml`:
+
+```toml
+[dependencies]
+nanosecond-scheduler = "0.1"  # From crates.io
+tokio = { version = "1.42", features = ["full"] }
+```
+
+Create `src/main.rs`:
+
+```rust
+use nanosecond_scheduler::{Scheduler, Task, Priority};
+use std::time::Duration;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Use published nanosecond-scheduler from crates.io
+    let scheduler = Scheduler::new(4); // 4 worker threads
+
+    // Schedule high-priority task
+    scheduler.schedule(Task {
+        priority: Priority::High,
+        deadline: Duration::from_millis(10),
+        work: Box::new(|| {
+            println!("High-priority task executing!");
+        }),
+    })?;
+
+    scheduler.run().await?;
+
+    Ok(())
+}
+```
+
+### 3. Dynamical Systems Analysis
+
+```toml
+[dependencies]
+temporal-attractor-studio = "0.1"  # From crates.io
+nalgebra = "0.33"
+```
+
+```rust
+use temporal_attractor_studio::{AttractorAnalyzer, SystemState};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let analyzer = AttractorAnalyzer::new();
+
+    // Analyze time series data
+    let states: Vec<SystemState> = vec![
+        SystemState::new(vec![1.0, 2.0]),
+        SystemState::new(vec![1.1, 2.1]),
+        SystemState::new(vec![1.0, 2.0]),
+    ];
+
+    let attractor = analyzer.detect_attractor(&states)?;
+    let lyapunov = analyzer.compute_lyapunov_exponent(&states)?;
+
+    println!("Attractor type: {:?}", attractor);
+    println!("Lyapunov exponent: {}", lyapunov);
+
+    Ok(())
+}
+```
+
+### 4. Meta-Learning with Strange Loop
+
+```toml
+[dependencies]
+strange-loop = "0.1"  # From crates.io
+```
+
+```rust
+use strange_loop::{MetaLearner, Experience};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut learner = MetaLearner::new();
+
+    // Learn from experience
+    let experience = Experience {
+        state: vec![1.0, 2.0, 3.0],
+        action: "move_forward",
+        reward: 1.5,
+        next_state: vec![1.1, 2.1, 3.1],
+    };
+
+    learner.update(&experience)?;
+
+    // Adapt policy based on learned patterns
+    let new_policy = learner.adapt_policy()?;
+    println!("Policy adapted successfully!");
+
+    Ok(())
+}
+```
+
+### 5. Browser/WASM Usage
+
+All published crates support WASM compilation:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <script type="module">
+        import init, { TemporalCompare } from './pkg/midstream_wasm.js';
+
+        async function run() {
+            await init();
+
+            // Use published crate in browser
+            const compare = new TemporalCompare();
+            const distance = compare.dtw([1, 2, 3], [1, 2, 4]);
+
+            console.log('DTW distance:', distance);
+        }
+
+        run();
+    </script>
+</head>
+<body>
+    <h1>MidStream WASM Demo</h1>
+    <p>Using published crates from crates.io in the browser!</p>
+</body>
+</html>
+```
+
+## Performance Expectations
+
+Published crates deliver excellent performance:
+
+| Operation | Native | WASM | Status |
+|-----------|--------|------|--------|
+| DTW (n=100) | ~8ms | ~16ms | ✅ Production |
+| Scheduling | ~85ns | N/A | ✅ Production |
+| Pattern match | ~4ms | ~12ms | ✅ Production |
+| Lyapunov calc | ~9ms | ~18ms | ✅ Production |
+
+## Crate Links
+
+Browse all published crates on crates.io:
+
+- 📦 **[temporal-compare](https://crates.io/crates/temporal-compare)** - Pattern matching and DTW
+- 📦 **[nanosecond-scheduler](https://crates.io/crates/nanosecond-scheduler)** - Real-time scheduling
+- 📦 **[temporal-attractor-studio](https://crates.io/crates/temporal-attractor-studio)** - Dynamical systems
+- 📦 **[temporal-neural-solver](https://crates.io/crates/temporal-neural-solver)** - LTL verification
+- 📦 **[strange-loop](https://crates.io/crates/strange-loop)** - Meta-learning
+
+## Documentation
+
+Each published crate has comprehensive documentation on docs.rs:
+
+- 📚 [temporal-compare docs](https://docs.rs/temporal-compare)
+- 📚 [nanosecond-scheduler docs](https://docs.rs/nanosecond-scheduler)
+- 📚 [temporal-attractor-studio docs](https://docs.rs/temporal-attractor-studio)
+- 📚 [temporal-neural-solver docs](https://docs.rs/temporal-neural-solver)
+- 📚 [strange-loop docs](https://docs.rs/strange-loop)
+
+## Running Examples
+
+```bash
+# Clone repository for examples
+git clone https://github.com/ruvnet/midstream.git
+cd midstream
+
+# Run examples using published crates
+cargo run --example lean_agentic_streaming
+cargo run --example openrouter
+
+# QUIC server (uses workspace crate)
+cargo run --example quic_server
+```
+
+## Running Tests
+
+Test the published crates:
+
+```bash
+# Test all workspace crates
+cargo test --workspace
+
+# Test specific published crate
+cargo test -p temporal-compare
+
+# With output
+cargo test -- --nocapture
+```
+
+## Running Benchmarks
+
+```bash
+# All benchmarks
+cargo bench --workspace
+
+# Specific crate benchmark
+cargo bench -p nanosecond-scheduler
+
+# Save baseline for comparison
+cargo bench -- --save-baseline main
+```
+
+## Troubleshooting
+
+### Build Issues
+
+**Problem**: `cargo: command not found`
+```bash
+# Install Rust
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.cargo/env
+rustup update
+```
+
+**Problem**: Crate not found on crates.io
+```bash
+# Make sure you're using version 0.1 or compatible
+# Check latest versions:
+cargo search temporal-compare
+cargo search nanosecond-scheduler
+```
+
+**Problem**: WASM build fails
+```bash
+# Install wasm-pack
+cargo install wasm-pack
+
+# Build WASM from published crates
+wasm-pack build --target web
+```
+
+### Runtime Issues
+
+**Problem**: Version conflicts
+```bash
+# Update all dependencies
+cargo update
+
+# Use specific versions
+temporal-compare = "=0.1.0"
+```
+
+**Problem**: Performance issues
+```bash
+# Always build with --release for production
+cargo build --release
+
+# Run benchmarks to verify
+cargo bench
+```
+
+## Version Information
+
+All published crates are at version **0.1.x**:
+
+- temporal-compare: 0.1.x
+- nanosecond-scheduler: 0.1.x
+- temporal-attractor-studio: 0.1.x
+- temporal-neural-solver: 0.1.x
+- strange-loop: 0.1.x
+
+Check for updates:
+
+```bash
+cargo update
+cargo outdated  # If you have cargo-outdated installed
+```
+
+## Next Steps
+
+1. ✅ Install published crates from crates.io
+2. 📖 Read the [complete README](../README.md)
+3. 🔍 Explore [API documentation](https://docs.rs)
+4. 💡 Try the examples above
+5. 🚀 Build your real-time application!
+
+## Getting Help
+
+- 📖 **Documentation**: [docs.rs](https://docs.rs) for each crate
+- 💬 **Examples**: `examples/` directory in repository
+- 🐛 **Issues**: [GitHub Issues](https://github.com/ruvnet/midstream/issues)
+- 📧 **Contact**: See main README.md
+
+---
+
+**Happy streaming with MidStream published crates!** 🚀
+
+**All core crates are production-ready and available on crates.io**