better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/mlops/mlops-faiss.md

@@ -1,240 +0,0 @@
----
-title: "Faiss — Fast vector similarity search at billion scale"
-sidebar_label: "Faiss"
-description: "Fast vector similarity search at billion scale"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Faiss
-
-Fast vector similarity search at billion scale.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/mlops/faiss` |
-| Path | `optional-skills/mlops\faiss` |
-| Version | `1.0.0` |
-| Author | Orchestra Research |
-| License | MIT |
-| Dependencies | `faiss-cpu`, `faiss-gpu`, `numpy` |
-| Platforms | linux, macos |
-| Tags | `RAG`, `FAISS`, `Similarity Search`, `Vector Search`, `Facebook AI`, `GPU Acceleration`, `Billion-Scale`, `K-NN`, `HNSW`, `High Performance`, `Large Scale` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# FAISS - Efficient Similarity Search
-
-Facebook AI's library for billion-scale vector similarity search.
-
-## When to use FAISS
-
-**Use FAISS when:**
-- Need fast similarity search on large vector datasets (millions/billions)
-- GPU acceleration required
-- Pure vector similarity (no metadata filtering needed)
-- High throughput, low latency critical
-- Offline/batch processing of embeddings
-
-**Metrics**:
-- **31,700+ GitHub stars**
-- Meta/Facebook AI Research
-- **Handles billions of vectors**
-- **C++** with Python bindings
-
-**Use alternatives instead**:
-- **Chroma/Pinecone**: Need metadata filtering
-- **Weaviate**: Need full database features
-- **Annoy**: Simpler, fewer features
-
-## Quick start
-
-### Installation
-
-```bash
-# CPU only
-pip install faiss-cpu
-
-# GPU support
-pip install faiss-gpu
-```
-
-### Basic usage
-
-```python
-import faiss
-import numpy as np
-
-# Create sample data (1000 vectors, 128 dimensions)
-d = 128
-nb = 1000
-vectors = np.random.random((nb, d)).astype('float32')
-
-# Create index
-index = faiss.IndexFlatL2(d)  # L2 distance
-index.add(vectors)             # Add vectors
-
-# Search
-k = 5  # Find 5 nearest neighbors
-query = np.random.random((1, d)).astype('float32')
-distances, indices = index.search(query, k)
-
-print(f"Nearest neighbors: {indices}")
-print(f"Distances: {distances}")
-```
-
-## Index types
-
-### 1. Flat (exact search)
-
-```python
-# L2 (Euclidean) distance
-index = faiss.IndexFlatL2(d)
-
-# Inner product (cosine similarity if normalized)
-index = faiss.IndexFlatIP(d)
-
-# Slowest, most accurate
-```
-
-### 2. IVF (inverted file) - Fast approximate
-
-```python
-# Create quantizer
-quantizer = faiss.IndexFlatL2(d)
-
-# IVF index with 100 clusters
-nlist = 100
-index = faiss.IndexIVFFlat(quantizer, d, nlist)
-
-# Train on data
-index.train(vectors)
-
-# Add vectors
-index.add(vectors)
-
-# Search (nprobe = clusters to search)
-index.nprobe = 10
-distances, indices = index.search(query, k)
-```
-
-### 3. HNSW (Hierarchical NSW) - Best quality/speed
-
-```python
-# HNSW index
-M = 32  # Number of connections per layer
-index = faiss.IndexHNSWFlat(d, M)
-
-# No training needed
-index.add(vectors)
-
-# Search
-distances, indices = index.search(query, k)
-```
-
-### 4. Product Quantization - Memory efficient
-
-```python
-# PQ reduces memory by 16-32×
-m = 8   # Number of subquantizers
-nbits = 8
-index = faiss.IndexPQ(d, m, nbits)
-
-# Train and add
-index.train(vectors)
-index.add(vectors)
-```
-
-## Save and load
-
-```python
-# Save index
-faiss.write_index(index, "large.index")
-
-# Load index
-index = faiss.read_index("large.index")
-
-# Continue using
-distances, indices = index.search(query, k)
-```
-
-## GPU acceleration
-
-```python
-# Single GPU
-res = faiss.StandardGpuResources()
-index_cpu = faiss.IndexFlatL2(d)
-index_gpu = faiss.index_cpu_to_gpu(res, 0, index_cpu)  # GPU 0
-
-# Multi-GPU
-index_gpu = faiss.index_cpu_to_all_gpus(index_cpu)
-
-# 10-100× faster than CPU
-```
-
-## LangChain integration
-
-```python
-from langchain_community.vectorstores import FAISS
-from langchain_openai import OpenAIEmbeddings
-
-# Create FAISS vector store
-vectorstore = FAISS.from_documents(docs, OpenAIEmbeddings())
-
-# Save
-vectorstore.save_local("faiss_index")
-
-# Load
-vectorstore = FAISS.load_local(
-    "faiss_index",
-    OpenAIEmbeddings(),
-    allow_dangerous_deserialization=True
-)
-
-# Search
-results = vectorstore.similarity_search("query", k=5)
-```
-
-## LlamaIndex integration
-
-```python
-from llama_index.vector_stores.faiss import FaissVectorStore
-import faiss
-
-# Create FAISS index
-d = 1536
-faiss_index = faiss.IndexFlatL2(d)
-
-vector_store = FaissVectorStore(faiss_index=faiss_index)
-```
-
-## Best practices
-
-1. **Choose right index type** - Flat for <10K, IVF for 10K-1M, HNSW for quality
-2. **Normalize for cosine** - Use IndexFlatIP with normalized vectors
-3. **Use GPU for large datasets** - 10-100× faster
-4. **Save trained indices** - Training is expensive
-5. **Tune nprobe/ef_search** - Balance speed/accuracy
-6. **Monitor memory** - PQ for large datasets
-7. **Batch queries** - Better GPU utilization
-
-## Performance
-
-| Index Type | Build Time | Search Time | Memory | Accuracy |
-|------------|------------|-------------|--------|----------|
-| Flat | Fast | Slow | High | 100% |
-| IVF | Medium | Fast | Medium | 95-99% |
-| HNSW | Slow | Fastest | High | 99% |
-| PQ | Medium | Fast | Low | 90-95% |
-
-## Resources
-
-- **GitHub**: https://github.com/facebookresearch/faiss ⭐ 31,700+
-- **Wiki**: https://github.com/facebookresearch/faiss/wiki
-- **License**: MIT

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/mlops/mlops-flash-attention.md

@@ -1,388 +0,0 @@
----
-title: "Flash Attention — Speed up long-sequence transformer training and inference"
-sidebar_label: "Flash Attention"
-description: "Speed up long-sequence transformer training and inference"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Flash Attention
-
-Speed up long-sequence transformer training and inference.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/mlops/flash-attention` |
-| Path | `optional-skills/mlops\flash-attention` |
-| Version | `1.0.1` |
-| Author | Orchestra Research |
-| License | MIT |
-| Dependencies | `flash-attn`, `torch`, `transformers` |
-| Platforms | linux, macos |
-| Tags | `Optimization`, `Flash Attention`, `Attention Optimization`, `Memory Efficiency`, `Speed Optimization`, `Long Context`, `PyTorch`, `SDPA`, `H100`, `FP8`, `Transformers` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Flash Attention - Fast Memory-Efficient Attention
-
-## Quick start
-
-Flash Attention provides 2-4x speedup and 10-20x memory reduction for transformer attention through IO-aware tiling and recomputation.
-
-**PyTorch native (easiest, PyTorch 2.2+)**:
-```python
-import torch
-import torch.nn.functional as F
-
-q = torch.randn(2, 8, 512, 64, device='cuda', dtype=torch.float16)  # [batch, heads, seq, dim]
-k = torch.randn(2, 8, 512, 64, device='cuda', dtype=torch.float16)
-v = torch.randn(2, 8, 512, 64, device='cuda', dtype=torch.float16)
-
-# Automatically uses Flash Attention if available
-out = F.scaled_dot_product_attention(q, k, v)
-```
-
-**flash-attn library (more features)**:
-```bash
-pip install flash-attn --no-build-isolation
-```
-
-```python
-from flash_attn import flash_attn_func
-
-# q, k, v: [batch, seqlen, nheads, headdim]
-out = flash_attn_func(q, k, v, dropout_p=0.0, causal=True)
-```
-
-## Common workflows
-
-### Workflow 1: Enable in existing PyTorch model
-
-Copy this checklist:
-
-```
-Flash Attention Integration:
-- [ ] Step 1: Check PyTorch version (≥2.2)
-- [ ] Step 2: Enable Flash Attention backend
-- [ ] Step 3: Verify speedup with profiling
-- [ ] Step 4: Test accuracy matches baseline
-```
-
-**Step 1: Check PyTorch version**
-
-```bash
-python -c "import torch; print(torch.__version__)"
-# Should be ≥2.2.0
-```
-
-If <2.2, upgrade:
-```bash
-pip install --upgrade torch
-```
-
-**Step 2: Enable Flash Attention backend**
-
-Replace standard attention:
-```python
-# Before (standard attention)
-attn_weights = torch.softmax(q @ k.transpose(-2, -1) / math.sqrt(d_k), dim=-1)
-out = attn_weights @ v
-
-# After (Flash Attention)
-import torch.nn.functional as F
-out = F.scaled_dot_product_attention(q, k, v, attn_mask=mask)
-```
-
-Force Flash Attention backend (`torch.backends.cuda.sdp_kernel` is deprecated; use
-`torch.nn.attention.sdpa_kernel` with `SDPBackend`):
-```python
-from torch.nn.attention import SDPBackend, sdpa_kernel
-
-with sdpa_kernel(SDPBackend.FLASH_ATTENTION):
-    out = F.scaled_dot_product_attention(q, k, v)
-```
-
-**Step 3: Verify speedup with profiling**
-
-```python
-import torch.utils.benchmark as benchmark
-
-def test_attention(use_flash):
-    q, k, v = [torch.randn(2, 8, 2048, 64, device='cuda', dtype=torch.float16) for _ in range(3)]
-
-    if use_flash:
-        from torch.nn.attention import SDPBackend, sdpa_kernel
-        with sdpa_kernel(SDPBackend.FLASH_ATTENTION):
-            return F.scaled_dot_product_attention(q, k, v)
-    else:
-        attn = (q @ k.transpose(-2, -1) / 8.0).softmax(dim=-1)
-        return attn @ v
-
-# Benchmark
-t_flash = benchmark.Timer(stmt='test_attention(True)', globals=globals())
-t_standard = benchmark.Timer(stmt='test_attention(False)', globals=globals())
-
-print(f"Flash: {t_flash.timeit(100).mean:.3f}s")
-print(f"Standard: {t_standard.timeit(100).mean:.3f}s")
-```
-
-Expected: 2-4x speedup for sequences >512 tokens.
-
-**Step 4: Test accuracy matches baseline**
-
-```python
-# Compare outputs
-q, k, v = [torch.randn(1, 8, 512, 64, device='cuda', dtype=torch.float16) for _ in range(3)]
-
-# Flash Attention
-out_flash = F.scaled_dot_product_attention(q, k, v)
-
-# Standard attention
-attn_weights = torch.softmax(q @ k.transpose(-2, -1) / 8.0, dim=-1)
-out_standard = attn_weights @ v
-
-# Check difference
-diff = (out_flash - out_standard).abs().max()
-print(f"Max difference: {diff:.6f}")
-# Should be <1e-3 for float16
-```
-
-### Workflow 2: Use flash-attn library for advanced features
-
-For multi-query attention, sliding window, or H100 FP8.
-
-Copy this checklist:
-
-```
-flash-attn Library Setup:
-- [ ] Step 1: Install flash-attn library
-- [ ] Step 2: Modify attention code
-- [ ] Step 3: Enable advanced features
-- [ ] Step 4: Benchmark performance
-```
-
-**Step 1: Install flash-attn library**
-
-```bash
-# NVIDIA GPUs (CUDA 12.0+)
-pip install flash-attn --no-build-isolation
-
-# Verify installation
-python -c "from flash_attn import flash_attn_func; print('Success')"
-```
-
-**Step 2: Modify attention code**
-
-```python
-from flash_attn import flash_attn_func
-
-# Input: [batch_size, seq_len, num_heads, head_dim]
-# Transpose from [batch, heads, seq, dim] if needed
-q = q.transpose(1, 2)  # [batch, seq, heads, dim]
-k = k.transpose(1, 2)
-v = v.transpose(1, 2)
-
-out = flash_attn_func(
-    q, k, v,
-    dropout_p=0.1,
-    causal=True,  # For autoregressive models
-    window_size=(-1, -1),  # No sliding window
-    softmax_scale=None  # Auto-scale
-)
-
-out = out.transpose(1, 2)  # Back to [batch, heads, seq, dim]
-```
-
-**Step 3: Enable advanced features**
-
-Multi-query attention (shared K/V across heads):
-```python
-from flash_attn import flash_attn_func
-
-# q: [batch, seq, num_q_heads, dim]
-# k, v: [batch, seq, num_kv_heads, dim]  # Fewer KV heads
-out = flash_attn_func(q, k, v)  # Automatically handles MQA
-```
-
-Sliding window attention (local attention):
-```python
-# Only attend to window of 256 tokens before/after
-out = flash_attn_func(
-    q, k, v,
-    window_size=(256, 256),  # (left, right) window
-    causal=True
-)
-```
-
-**Step 4: Benchmark performance**
-
-```python
-import torch
-from flash_attn import flash_attn_func
-import time
-
-q, k, v = [torch.randn(4, 4096, 32, 64, device='cuda', dtype=torch.float16) for _ in range(3)]
-
-# Warmup
-for _ in range(10):
-    _ = flash_attn_func(q, k, v)
-
-# Benchmark
-torch.cuda.synchronize()
-start = time.time()
-for _ in range(100):
-    out = flash_attn_func(q, k, v)
-    torch.cuda.synchronize()
-end = time.time()
-
-print(f"Time per iteration: {(end-start)/100*1000:.2f}ms")
-print(f"Memory allocated: {torch.cuda.max_memory_allocated()/1e9:.2f}GB")
-```
-
-### Workflow 3: H100 FP8 optimization (FlashAttention-3)
-
-For maximum performance on Hopper GPUs (H100).
-
-> **Important:** The pip package `flash-attn` (2.8.x) ships **FlashAttention-2 only** — it does
-> **not** contain FA3 or FP8 H100 kernels, and `flash_attn_func` does **not** auto-use FP8.
-> FlashAttention-3 is a separate **beta** build compiled from source from the repo's `hopper/`
-> directory, exposed via the `flash_attn_interface` module. FA3 supports FP16/BF16 forward+backward
-> and **FP8 forward only**.
-
-```
-FP8 Setup:
-- [ ] Step 1: Verify Hopper (H100) GPU available
-- [ ] Step 2: Build & install FlashAttention-3 from source (hopper/)
-- [ ] Step 3: Use the FA3 interface (FP8 forward)
-```
-
-**Step 1: Verify H100 GPU**
-
-```bash
-nvidia-smi --query-gpu=name --format=csv
-# Should show "H100" or "H800"
-```
-
-**Step 2: Build & install FlashAttention-3 from source**
-
-FA3 is NOT included in `pip install flash-attn`. Build it from the `hopper/` subdirectory:
-
-```bash
-git clone https://github.com/Dao-AILab/flash-attention.git
-cd flash-attention/hopper
-python setup.py install
-# (compilation is heavy and requires a CUDA toolchain + Hopper GPU)
-```
-
-**Step 3: Use the FA3 interface (FP8 forward)**
-
-FA3 exposes its own module `flash_attn_interface` (distinct from the FA2 `flash_attn`).
-FP8 is a **forward-only** path and expects `float8_e4m3fn` inputs:
-
-```python
-import torch
-from flash_attn_interface import flash_attn_func  # FA3 (hopper build), not `flash_attn`
-
-# q, k, v: [batch, seqlen, nheads, headdim]
-q = torch.randn(2, 4096, 32, 64, device='cuda', dtype=torch.float16)
-k = torch.randn(2, 4096, 32, 64, device='cuda', dtype=torch.float16)
-v = torch.randn(2, 4096, 32, 64, device='cuda', dtype=torch.float16)
-
-# FP8 forward (inference / forward-only): cast to float8_e4m3fn
-q_fp8 = q.to(torch.float8_e4m3fn)
-k_fp8 = k.to(torch.float8_e4m3fn)
-v_fp8 = v.to(torch.float8_e4m3fn)
-
-out = flash_attn_func(q_fp8, k_fp8, v_fp8, causal=True)
-# FP16/BF16 forward+backward is also supported by the FA3 interface.
-```
-
-## When to use vs alternatives
-
-**Use Flash Attention when:**
-- Training transformers with sequences >512 tokens
-- Running inference with long context (>2K tokens)
-- GPU memory constrained (OOM with standard attention)
-- Need 2-4x speedup without accuracy loss
-- Using PyTorch 2.2+ or can install flash-attn
-
-**Use alternatives instead:**
-- **Standard attention**: Sequences &lt;256 tokens (overhead not worth it)
-- **xFormers**: Need more attention variants (not just speed)
-- **Memory-efficient attention**: CPU inference (Flash Attention needs GPU)
-
-## Common issues
-
-**Issue: ImportError: cannot import flash_attn**
-
-Install with no-build-isolation flag:
-```bash
-pip install flash-attn --no-build-isolation
-```
-
-Or install CUDA toolkit first:
-```bash
-conda install cuda -c nvidia
-pip install flash-attn --no-build-isolation
-```
-
-**Issue: Slower than expected (no speedup)**
-
-Flash Attention benefits increase with sequence length:
-- &lt;512 tokens: Minimal speedup (10-20%)
-- 512-2K tokens: 2-3x speedup
-- >2K tokens: 3-4x speedup
-
-Check sequence length is sufficient.
-
-**Issue: RuntimeError: CUDA error**
-
-Verify GPU supports Flash Attention:
-```python
-import torch
-print(torch.cuda.get_device_capability())
-# Should be ≥(7, 5) for Turing+
-```
-
-Flash Attention requires:
-- Ampere (A100, A10): ✅ Full support
-- Turing (T4): ✅ Supported
-- Volta (V100): ❌ Not supported
-
-**Issue: Accuracy degradation**
-
-Check dtype is float16 or bfloat16 (not float32):
-```python
-q = q.to(torch.float16)  # Or torch.bfloat16
-```
-
-Flash Attention uses float16/bfloat16 for speed. Float32 not supported.
-
-## Advanced topics
-
-**Integration with HuggingFace Transformers**: See [references/transformers-integration.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\flash-attention/references/transformers-integration.md) for enabling Flash Attention in BERT, GPT, Llama models.
-
-**Performance benchmarks**: See [references/benchmarks.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/mlops\flash-attention/references/benchmarks.md) for detailed speed and memory comparisons across GPUs and sequence lengths.
-
-## Hardware requirements
-
-- **GPU**: NVIDIA Ampere+ (A100, A10, A30) or AMD MI200+
-- **VRAM**: Same as standard attention (Flash Attention doesn't increase memory)
-- **CUDA**: 12.0+ (11.8 minimum)
-- **PyTorch**: 2.2+ for native support
-
-**Not supported**: V100 (Volta), CPU inference
-
-## Resources
-
-- Paper: "FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness" (NeurIPS 2022)
-- Paper: "FlashAttention-2: Faster Attention with Better Parallelism and Work Partitioning" (ICLR 2024)
-- Blog: https://tridao.me/blog/2024/flash3/
-- GitHub: https://github.com/Dao-AILab/flash-attention
-- PyTorch docs: https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html