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-11 20:41:44 +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,275 @@
+# Neural Network Implementation Plan
+## Temporal Micro-Net with Sublinear Solver Integration
+
+### Executive Summary
+Implementation of a temporal prediction neural network system that combines traditional micro-nets with sublinear solver gating for improved latency and stability in short-horizon predictions. The system will be deployed to HuggingFace with comprehensive benchmarking.
+
+## Project Structure
+```
+neural-network-implementation/
+├── plan/                    # Project planning documents
+│   ├── IMPLEMENTATION_PLAN.md
+│   ├── architecture.md
+│   └── milestones.md
+├── src/                     # Source code
+│   ├── models/             # Neural network models
+│   │   ├── traditional_micronet.py
+│   │   ├── temporal_solver_net.py
+│   │   └── base_model.py
+│   ├── solvers/            # Sublinear solver integration
+│   │   ├── solver_gate.py
+│   │   ├── projection.py
+│   │   └── pagerank_selector.py
+│   ├── data/               # Data processing
+│   │   ├── preprocessing.py
+│   │   ├── loaders.py
+│   │   └── augmentation.py
+│   ├── training/           # Training pipelines
+│   │   ├── trainer.py
+│   │   ├── active_selection.py
+│   │   └── callbacks.py
+│   └── inference/          # Inference engine
+│       ├── predictor.py
+│       ├── kalman_filter.py
+│       └── quantization.py
+├── tests/                   # Test suite
+│   ├── unit/
+│   ├── integration/
+│   └── performance/
+├── models/                  # Saved model checkpoints
+├── data/                    # Dataset storage
+├── benchmarks/              # Benchmark results
+├── configs/                 # Configuration files
+│   ├── A_traditional.yaml
+│   ├── B_temporal_solver.yaml
+│   └── common.yaml
+└── docs/                    # Documentation
+
+```
+
+## Implementation Phases
+
+### Phase 1: Core Infrastructure (Day 1-2)
+1. **Base Model Architecture**
+   - Abstract base class for micro-nets
+   - Common interfaces for training/inference
+   - Configuration management system
+
+2. **Data Pipeline**
+   - Preprocessing for time series data
+   - Sliding window generation
+   - Z-score normalization
+   - Train/val/test temporal splits
+
+3. **Sublinear Solver Integration**
+   - Wrapper for solve_projection API
+   - Certificate error handling
+   - Budget management
+
+### Phase 2: Model Implementation (Day 2-3)
+1. **System A - Traditional Micro-Net**
+   - Residual GRU implementation
+   - TCN alternative
+   - FP32 training, INT8 inference
+   - 128ms window, 500ms horizon prediction
+
+2. **System B - Temporal Solver Net**
+   - Same architecture as System A
+   - Kalman filter prior integration
+   - Residual learning approach
+   - Solver gate implementation
+   - Active selection with PageRank
+
+### Phase 3: Training Pipeline (Day 3-4)
+1. **Standard Training**
+   - Adam optimizer setup
+   - MSE loss with smoothness penalty
+   - Early stopping on validation
+   - Batch size 256, 15 epochs
+
+2. **Active Selection Training**
+   - kNN graph construction
+   - PageRank scoring
+   - Sample selection strategy
+   - Error-guided sampling
+
+### Phase 4: Inference Optimization (Day 4-5)
+1. **Latency Optimization**
+   - INT8 quantization
+   - Single-core CPU optimization
+   - Memory pinning
+   - Thread locking
+
+2. **Real-time Processing**
+   - Sub-millisecond inference
+   - Certificate validation
+   - Safe fallback mechanisms
+
+### Phase 5: Benchmarking & Evaluation (Day 5-6)
+1. **Performance Metrics**
+   - MSE at 500ms horizon
+   - P90/P99 absolute error
+   - P50/P99.9 latency
+   - Gate pass rate
+   - Certificate error tracking
+
+2. **A/B Testing Framework**
+   - Paired t-tests
+   - Mann-Whitney U tests
+   - Effect size calculation
+   - Statistical significance
+
+### Phase 6: HuggingFace Deployment (Day 6-7)
+1. **Model Packaging**
+   - Model card creation
+   - Dataset documentation
+   - Training scripts
+   - Inference examples
+
+2. **Repository Setup**
+   - Model weights upload
+   - Configuration files
+   - README and documentation
+   - Demo application
+
+## Technical Specifications
+
+### Model Architecture
+```yaml
+common:
+  horizon_ms: 500
+  window_ms: 128
+  sample_rate_hz: 2000
+  features: [x, y, vx, vy]
+  quantize: int8
+  optimizer: adam
+  lr: 1e-3
+  batch: 256
+  epochs: 15
+
+A_traditional:
+  model: micro_gru
+  hidden: 32
+
+B_temporal_solver:
+  model: micro_gru
+  hidden: 32
+  prior: kalman
+  solver_gate:
+    eps: 0.02
+    budget: 200000
+  active_selection:
+    k: 15
+    eps: 0.03
+```
+
+### Performance Targets
+- **Latency Budget (per tick)**:
+  - Ingest: 0.10ms
+  - Prior: 0.10ms
+  - Network: 0.30ms
+  - Gate: 0.20ms
+  - Actuation: 0.10ms
+  - **Total P99.9 ≤ 0.90ms**
+
+### Success Criteria
+1. System B reduces P99.9 latency by ≥20% OR
+2. System B reduces P99 error by ≥15% with equal latency
+3. Gate pass rate ≥90% with avg cert.error ≤0.02
+
+## Dependencies
+```python
+# Core
+pytorch >= 2.0
+numpy >= 1.24
+scipy >= 1.10
+scikit-learn >= 1.3
+
+# Optimization
+onnx >= 1.14
+onnxruntime >= 1.16
+torch-quantization >= 2.1
+
+# Sublinear Solver
+sublinear-time-solver >= 0.1.0
+
+# Deployment
+huggingface-hub >= 0.19
+transformers >= 4.35
+accelerate >= 0.24
+
+# Monitoring
+tensorboard >= 2.14
+wandb >= 0.16
+```
+
+## Risk Mitigation
+1. **Performance Risks**
+   - Fallback to traditional method if solver fails
+   - Adjustable epsilon parameters
+   - Multiple budget configurations
+
+2. **Training Risks**
+   - Checkpoint saving every epoch
+   - Multiple seed runs
+   - Gradient clipping
+
+3. **Deployment Risks**
+   - Thorough testing on diverse data
+   - Graceful degradation
+   - Version control for models
+
+## Testing Strategy
+1. **Unit Tests**
+   - Model components
+   - Solver integration
+   - Data processing
+
+2. **Integration Tests**
+   - End-to-end training
+   - Inference pipeline
+   - A/B comparison
+
+3. **Performance Tests**
+   - Latency benchmarks
+   - Memory usage
+   - Throughput testing
+
+## Documentation Requirements
+1. **Code Documentation**
+   - Docstrings for all functions
+   - Type hints
+   - Inline comments for complex logic
+
+2. **User Documentation**
+   - Installation guide
+   - Training tutorial
+   - Inference examples
+   - API reference
+
+3. **HuggingFace Model Card**
+   - Model description
+   - Training procedure
+   - Evaluation results
+   - Limitations and biases
+   - Citation information
+
+## Deliverables
+1. **Week 1**
+   - Complete implementation of Systems A & B
+   - Training pipelines
+   - Basic evaluation
+
+2. **Week 2**
+   - Full benchmarking suite
+   - Statistical analysis
+   - HuggingFace deployment
+   - Final documentation
+
+## Success Metrics
+- ✅ Both systems fully implemented
+- ✅ All tests passing
+- ✅ Performance targets met
+- ✅ HuggingFace model published
+- ✅ Documentation complete
+- ✅ Reproducible results