agentic-flow 1.8.15 → 1.9.0

package/agentic-flow/examples/crispr-cas13-pipeline/.github/workflows/ci.yml

@@ -0,0 +1,341 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  # Job 1: Code quality checks
+  lint:
+    name: Lint and Format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          components: rustfmt, clippy
+          override: true
+
+      - name: Cache cargo registry
+        uses: actions/cache@v3
+        with:
+          path: ~/.cargo/registry
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo index
+        uses: actions/cache@v3
+        with:
+          path: ~/.cargo/git
+          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo build
+        uses: actions/cache@v3
+        with:
+          path: target
+          key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Check code formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+
+  # Job 2: Build project
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Cache cargo dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Build workspace
+        run: cargo build --release --all-features
+
+      - name: Archive build artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: build-artifacts
+          path: target/release/
+          retention-days: 7
+
+  # Job 3: Unit and integration tests
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: build
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: test_user
+          POSTGRES_PASSWORD: test_password
+          POSTGRES_DB: crispr_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      mongodb:
+        image: mongo:7
+        env:
+          MONGO_INITDB_ROOT_USERNAME: test_user
+          MONGO_INITDB_ROOT_PASSWORD: test_password
+        ports:
+          - 27017:27017
+        options: >-
+          --health-cmd "mongosh --eval 'db.runCommand({ping: 1})'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Cache cargo dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run unit tests
+        env:
+          DATABASE_URL: postgres://test_user:test_password@localhost:5432/crispr_test
+          MONGODB_URL: mongodb://test_user:test_password@localhost:27017/crispr_test
+          REDIS_URL: redis://localhost:6379
+        run: cargo test --lib --all-features -- --nocapture
+
+      - name: Run integration tests
+        env:
+          DATABASE_URL: postgres://test_user:test_password@localhost:5432/crispr_test
+          MONGODB_URL: mongodb://test_user:test_password@localhost:27017/crispr_test
+          REDIS_URL: redis://localhost:6379
+        run: cargo test --test '*' --all-features -- --nocapture
+
+      - name: Run doc tests
+        run: cargo test --doc --all-features
+
+  # Job 4: Code coverage
+  coverage:
+    name: Code Coverage
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Install tarpaulin
+        run: cargo install cargo-tarpaulin
+
+      - name: Generate coverage report
+        run: cargo tarpaulin --all-features --workspace --timeout 300 --out Xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./cobertura.xml
+          fail_ci_if_error: false
+
+      - name: Check coverage threshold
+        run: |
+          COVERAGE=$(cargo tarpaulin --all-features --workspace --timeout 300 --out Stdout | grep -oP '\d+\.\d+(?=%)' | head -1)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 85" | bc -l) )); then
+            echo "Coverage $COVERAGE% is below 85% threshold"
+            exit 1
+          fi
+
+  # Job 5: Performance benchmarks
+  benchmark:
+    name: Performance Benchmarks
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Cache cargo dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Run benchmarks
+        run: cargo bench --all-features -- --output-format bencher | tee benchmark_results.txt
+
+      - name: Download baseline benchmarks
+        uses: actions/cache@v3
+        with:
+          path: ./target/criterion
+          key: ${{ runner.os }}-benchmark-${{ github.base_ref }}
+
+      - name: Compare with baseline
+        run: |
+          if [ -f ./target/criterion/baseline.txt ]; then
+            echo "Comparing with baseline..."
+            # TODO: Add benchmark comparison logic
+          else
+            echo "No baseline found, saving current as baseline"
+            cp benchmark_results.txt ./target/criterion/baseline.txt
+          fi
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v3
+        with:
+          name: benchmark-results
+          path: |
+            benchmark_results.txt
+            target/criterion/**/*.html
+          retention-days: 30
+
+      - name: Post benchmark comment
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            const fs = require('fs');
+            const results = fs.readFileSync('benchmark_results.txt', 'utf8');
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `## 📊 Benchmark Results\n\n\`\`\`\n${results}\n\`\`\``
+            });
+
+  # Job 6: Security audit
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install cargo-audit
+        run: cargo install cargo-audit
+
+      - name: Run security audit
+        run: cargo audit
+
+  # Job 7: Deploy documentation (on main branch only)
+  docs:
+    name: Build and Deploy Docs
+    runs-on: ubuntu-latest
+    needs: [test, coverage]
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Generate documentation
+        run: cargo doc --no-deps --all-features
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./target/doc
+          cname: docs.crispr-pipeline.dev
+
+  # Job 8: Performance regression detection
+  performance-check:
+    name: Performance Regression Check
+    runs-on: ubuntu-latest
+    needs: benchmark
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download benchmark artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: benchmark-results
+
+      - name: Check for performance regressions
+        run: |
+          echo "Checking for performance regressions..."
+          # TODO: Implement regression detection logic
+          # Fail CI if performance degrades by >10%
+
+  # Job 9: Notification
+  notify:
+    name: Notify on Completion
+    runs-on: ubuntu-latest
+    needs: [lint, build, test, coverage, security]
+    if: always()
+    steps:
+      - name: Send notification
+        run: |
+          echo "CI/CD pipeline completed"
+          echo "Status: ${{ job.status }}"

package/agentic-flow/examples/crispr-cas13-pipeline/CONTRIBUTING.md

@@ -0,0 +1,388 @@
+# Contributing to CRISPR-Cas13 Pipeline
+
+Thank you for your interest in contributing! This project was built using [SPARC methodology](https://github.com/ruvnet/agentic-flow) and [rUv.io](https://ruv.io) AI coordination.
+
+## 🚀 Quick Start
+
+1. **Fork the repository**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/agentic-flow.git
+   cd agentic-flow/agentic-flow/examples/crispr-cas13-pipeline
+   ```
+
+2. **Set up development environment**
+   ```bash
+   # Install Rust (if not already installed)
+   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+   # Install development tools
+   cargo install cargo-tarpaulin  # Code coverage
+   cargo install cargo-audit      # Security auditing
+   cargo install cargo-machete    # Unused dependency detection
+
+   # Build and test
+   cargo build
+   cargo test --all
+   ```
+
+## 📋 Development Workflow
+
+### 1. Create a Feature Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Write Tests First (TDD)
+
+We follow Test-Driven Development:
+
+```rust
+// tests/my_feature_test.rs
+#[test]
+fn test_my_new_feature() {
+    let result = my_new_feature();
+    assert_eq!(result.status, "success");
+}
+```
+
+### 3. Implement Your Feature
+
+```rust
+// crates/my-crate/src/lib.rs
+pub fn my_new_feature() -> Result<Output> {
+    // Implementation here
+    Ok(Output { status: "success" })
+}
+```
+
+### 4. Run Quality Checks
+
+```bash
+# Run all tests
+cargo test --all
+
+# Check formatting
+cargo fmt --all -- --check
+
+# Run linter
+cargo clippy -- -D warnings
+
+# Security audit
+cargo audit
+
+# Check for unused dependencies
+cargo machete
+
+# Test coverage (minimum 80%)
+cargo tarpaulin --out Html
+```
+
+### 5. Update Documentation
+
+```bash
+# Generate and check documentation
+cargo doc --no-deps --open
+
+# Update relevant markdown files
+# - README.md (if public API changed)
+# - CHANGELOG.md (add your changes)
+# - docs/ (if architecture/algorithms changed)
+```
+
+### 6. Commit Your Changes
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+git add .
+git commit -m "feat: add new off-target scoring algorithm"
+# or
+git commit -m "fix: correct DESeq2 normalization edge case"
+# or
+git commit -m "docs: update API documentation for immune analyzer"
+```
+
+Commit types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style changes (formatting)
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+- `test`: Adding tests
+- `chore`: Maintenance tasks
+
+### 7. Push and Create Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then open a Pull Request on GitHub.
+
+## 🧪 Testing Guidelines
+
+### Unit Tests
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_function_name() {
+        // Arrange
+        let input = setup_test_data();
+
+        // Act
+        let result = function_under_test(input);
+
+        // Assert
+        assert_eq!(result.expected_field, expected_value);
+    }
+}
+```
+
+### Integration Tests
+
+```rust
+// tests/integration_test.rs
+use crispr_cas13_pipeline::prelude::*;
+
+#[tokio::test]
+async fn test_complete_workflow() {
+    let target = create_test_target();
+    let predictor = DefaultPredictor::new(Default::default()).unwrap();
+    let prediction = predictor.predict(&target).await.unwrap();
+    assert!(!prediction.off_targets.is_empty());
+}
+```
+
+### Property-Based Tests
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn test_score_normalization(score in 0.0f64..1.0f64) {
+        let normalized = normalize_score(score);
+        assert!(normalized >= 0.0 && normalized <= 1.0);
+    }
+}
+```
+
+### Benchmark Tests
+
+```rust
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn alignment_benchmark(c: &mut Criterion) {
+    c.bench_function("align 1000 reads", |b| {
+        let reads = generate_test_reads(1000);
+        b.iter(|| align_reads(black_box(&reads)))
+    });
+}
+
+criterion_group!(benches, alignment_benchmark);
+criterion_main!(benches);
+```
+
+## 📝 Code Standards
+
+### Style Guide
+
+- Use `rustfmt` for formatting (enforced by CI)
+- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- Maximum line length: 100 characters
+- Use meaningful variable names (no single-letter variables except in math formulas)
+
+### Documentation
+
+```rust
+/// Calculate CFD (Cutting Frequency Determination) score for off-target sites.
+///
+/// # Arguments
+///
+/// * `guide` - Guide RNA sequence (22-30nt)
+/// * `target` - Target RNA sequence to score
+///
+/// # Returns
+///
+/// Returns a score between 0.0 (no match) and 1.0 (perfect match).
+///
+/// # Examples
+///
+/// ```
+/// use crispr_cas13_pipeline::scoring::CfdScorer;
+///
+/// let score = CfdScorer::score("ACGUACGU", "ACGUACGU");
+/// assert_eq!(score, 1.0);
+/// ```
+///
+/// # References
+///
+/// Doench et al. (2016) Nature Biotechnology 34(2)
+pub fn score(guide: &str, target: &str) -> f64 {
+    // Implementation
+}
+```
+
+### Error Handling
+
+Use `thiserror` for custom errors:
+
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum PredictionError {
+    #[error("Invalid guide RNA length: {0} (expected 22-30nt)")]
+    InvalidGuideLength(usize),
+
+    #[error("ML model not found at path: {0}")]
+    ModelNotFound(String),
+
+    #[error("Prediction failed: {0}")]
+    PredictionFailed(#[from] anyhow::Error),
+}
+```
+
+### Performance
+
+- Use `rayon` for CPU-bound parallel work
+- Use `tokio` for I/O-bound async work
+- Minimize allocations (use `&str` over `String` when possible)
+- Benchmark critical paths with `criterion`
+
+## 🏗️ Architecture Guidelines
+
+### Crate Organization
+
+Each crate should have:
+- Clear single responsibility
+- Well-defined public API
+- Comprehensive tests (>80% coverage)
+- Examples in `examples/` directory
+
+### Adding a New Crate
+
+```bash
+# Create new crate
+cargo new --lib crates/my-new-crate
+
+# Add to workspace in root Cargo.toml
+[workspace]
+members = [
+    "crates/data-models",
+    # ... existing crates
+    "crates/my-new-crate",  # Add here
+]
+```
+
+### Dependencies
+
+- Minimize external dependencies
+- Use well-maintained crates only
+- Lock versions for stability
+- Document why each dependency is needed
+
+## 🤝 Code Review Process
+
+### As a Contributor
+
+- Respond to review comments promptly
+- Make requested changes in new commits (don't force push)
+- Mark conversations as resolved when addressed
+- Be open to feedback and suggestions
+
+### As a Reviewer
+
+- Be respectful and constructive
+- Focus on code quality, not personal preferences
+- Provide specific suggestions for improvement
+- Approve when all concerns are addressed
+
+## 🐛 Bug Reports
+
+Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md):
+
+```markdown
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Run command '...'
+2. With input '...'
+3. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened.
+
+**Environment**
+- OS: [e.g. Ubuntu 22.04]
+- Rust version: [e.g. 1.75.0]
+- Package version: [e.g. 0.1.0]
+```
+
+## ✨ Feature Requests
+
+Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md):
+
+```markdown
+**Is your feature request related to a problem?**
+A clear description of the problem.
+
+**Describe the solution you'd like**
+A clear description of what you want to happen.
+
+**Describe alternatives you've considered**
+Any alternative solutions or features you've considered.
+
+**Additional context**
+Any other context or screenshots about the feature request.
+```
+
+## 📚 Resources
+
+### Documentation
+- [Rust Book](https://doc.rust-lang.org/book/)
+- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- [SPARC Methodology](https://github.com/ruvnet/agentic-flow)
+- [rUv.io Platform](https://ruv.io)
+
+### Scientific References
+- [CRISPR-Cas13 Overview](https://www.nature.com/articles/s41576-018-0059-1)
+- [Off-Target Analysis](https://www.nature.com/articles/nbt.3437)
+- [DESeq2 Algorithm](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-014-0550-8)
+
+## 🎯 Current Priorities
+
+See [GitHub Projects](https://github.com/ruvnet/agentic-flow/projects) for current roadmap.
+
+High-priority areas:
+- [ ] GPU acceleration for ML models
+- [ ] Additional Cas13 variant support
+- [ ] Frontend UI development
+- [ ] Real-world validation studies
+
+## 💬 Communication
+
+- **GitHub Discussions**: For questions and general discussion
+- **Discord**: [Join our community](https://discord.gg/ruv)
+- **Email**: contribute@ruv.io
+
+## 📜 License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to CRISPR-Cas13 Pipeline! 🧬✨