# rtx-rustybooks

Integration bridge between RustyBooks GPU crates and RustyTorch ML framework.

> **Note**: The rustybooks project (rustybooks) has been merged into horizon. This integration crate is currently disabled pending refactoring to work with the new unified architecture.

## Status

| Backend | Status | Tests |
|---------|--------|-------|
| Metal (Apple Silicon) | **Disabled** | Awaiting integration refactor |
| CUDA | **Disabled** | Awaiting integration refactor |

## Features

```toml
[dependencies]
rtx-rustybooks = { path = "crates/integration/rtx-rustybooks", features = ["metal"] }
```

### Available Features

| Feature | Description | Status |
|---------|-------------|--------|
| `metal` | Full Metal backend (macOS) | Working |
| `direct-storage-metal` | NVMe→GPU transfers | Working |
| `profiling-metal` | GPU profiling/counters | Working |
| `tma-metal` | Tensor Memory Accelerator | Working |
| `cuda` | CUDA backend | Needs fixes |

## Modules

### memory - Direct Storage Integration

Wraps `gpu-direct` for zero-copy NVMe→GPU transfers.

```rust
use rtx_rustybooks::memory::{DirectStoragePool, DirectBuffer};

let pool = DirectStoragePool::new()?;
let mut buffer = pool.allocate(1024 * 1024)?; // 1MB

// Load directly from NVMe to GPU
pool.load_from_storage(Path::new("weights.bin"), &mut buffer).await?;
```

### profiler - Extended Kernel Profiling

Wraps `gpu-profiler` for detailed GPU metrics.

```rust
use rtx_rustybooks::profiler::{ExtendedKernelProfiler, ReportFormat};

let profiler = ExtendedKernelProfiler::new()?;

let result = profiler.profile_launch("matmul", || {
    // GPU kernel execution
});

println!("Occupancy: {:.1}%", result.warp_occupancy() * 100.0);
println!("Bandwidth: {:.1} GB/s", result.achieved_bandwidth_gbps());

// Export report
let report = profiler.export_report(ReportFormat::Html);
```

### tensor - TMA Operations

Wraps `tensor-accelerator` for optimized tensor operations.

```rust
use rtx_rustybooks::tensor::{TmaOps, TileConfig, TensorOp, Architecture};

// Generate optimized kernel for architecture
let kernel = generate_tiled_kernel(
    TensorOp::Gemm,
    &[1024, 1024],
    Architecture::AppleSilicon
);

// TMA-accelerated matmul
let c = a.matmul_tma(&b)?;
```

## Architecture Support

| Architecture | Tile Config | Shared Memory |
|--------------|-------------|---------------|
| Apple Silicon (M1-M4) | 64x64x32 | 32 KB |
| NVIDIA Ampere (A100) | 128x128x32 | 164 KB |
| NVIDIA Blackwell (B200) | 128x128x64 | 228 KB |

## Known Issues

### CUDA Backend

The CUDA backend has conditional compilation conflicts in `gpu-direct`:
- `GPUBuffer` type defined in both `memory.rs` and `fallback.rs`
- When CUDA feature is enabled but runtime is absent, type mismatches occur

**Workaround**: Use Metal backend on macOS, or ensure CUDA toolkit is installed for CUDA builds.

## Testing

```bash
# Run all tests with Metal
cargo test -p rtx-rustybooks --features "metal"

# Run without GPU features (basic tests only)
cargo test -p rtx-rustybooks
```

## Dependencies

This crate was designed to bridge:
- `gpu-direct` → Direct storage I/O
- `gpu-profiler` → GPU performance counters
- `tensor-accelerator` → TMA primitives

These crates were originally in RustyBooks (`rustybooks`) and have been merged into `horizon`.