EvoScientist 0.0.1.dev3__py3-none-any.whl → 0.1.0rc1__py3-none-any.whl

EvoScientist/skills/find-skills/scripts/install_skill.py

@@ -1,211 +0,0 @@
-#!/usr/bin/env python3
-"""Install a skill from GitHub into a local skills directory.
-
-Self-contained installer — no external dependencies beyond git.
-
-Usage examples:
-    # Install from a GitHub URL (auto-detects repo, ref, path)
-    python install_skill.py --url https://github.com/anthropics/skills/tree/main/excel
-
-    # Install from repo + path
-    python install_skill.py --repo anthropics/skills --path excel
-
-    # Install multiple skills from the same repo
-    python install_skill.py --repo anthropics/skills --path excel --path pdf
-
-    # Install with a specific git ref
-    python install_skill.py --repo org/repo --path my-skill --ref v2.0
-"""
-
-from __future__ import annotations
-
-import argparse
-import os
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-
-
-def parse_github_url(url: str) -> tuple[str, str | None, str | None]:
-    """Parse a GitHub URL into (repo, ref, path).
-
-    Supports formats:
-        https://github.com/owner/repo
-        https://github.com/owner/repo/tree/main/path/to/skill
-        github.com/owner/repo/tree/branch/path
-        owner/repo@skill-name  (shorthand from skills.sh)
-
-    Returns:
-        (repo, ref_or_none, path_or_none)
-    """
-    # Shorthand: owner/repo@path
-    if "@" in url and "://" not in url:
-        repo, path = url.split("@", 1)
-        return repo.strip(), None, path.strip()
-
-    # Strip protocol and github.com prefix
-    cleaned = re.sub(r"^https?://", "", url)
-    cleaned = re.sub(r"^github\.com/", "", cleaned)
-    cleaned = cleaned.rstrip("/")
-
-    # Match: owner/repo/tree/ref/path...
-    m = re.match(r"^([^/]+/[^/]+)/tree/([^/]+)(?:/(.+))?$", cleaned)
-    if m:
-        return m.group(1), m.group(2), m.group(3)
-
-    # Match: owner/repo (no tree)
-    m = re.match(r"^([^/]+/[^/]+)$", cleaned)
-    if m:
-        return m.group(1), None, None
-
-    raise ValueError(f"Cannot parse GitHub URL: {url}")
-
-
-def clone_repo(repo: str, ref: str | None, dest: str) -> None:
-    """Shallow-clone a GitHub repo."""
-    clone_url = f"https://github.com/{repo}.git"
-    cmd = ["git", "clone", "--depth", "1"]
-    if ref:
-        cmd += ["--branch", ref]
-    cmd += [clone_url, dest]
-
-    result = subprocess.run(cmd, capture_output=True, text=True)
-    if result.returncode != 0:
-        raise RuntimeError(f"git clone failed: {result.stderr.strip()}")
-
-
-def copy_skill(src: str, dest_dir: str) -> str:
-    """Copy a skill directory to the destination.
-
-    Returns:
-        The skill name (directory basename).
-    """
-    skill_name = os.path.basename(src.rstrip("/"))
-    target = os.path.join(dest_dir, skill_name)
-
-    if os.path.exists(target):
-        shutil.rmtree(target)
-        print(f"  Replaced existing: {skill_name}")
-
-    shutil.copytree(src, target)
-    return skill_name
-
-
-def validate_skill(path: str) -> bool:
-    """Check that a directory looks like a valid skill (has SKILL.md)."""
-    return os.path.isfile(os.path.join(path, "SKILL.md"))
-
-
-def install(
-    repo: str,
-    paths: list[str],
-    ref: str | None,
-    dest: str,
-) -> list[str]:
-    """Install skill(s) from a GitHub repo.
-
-    Returns:
-        List of installed skill names.
-    """
-    os.makedirs(dest, exist_ok=True)
-    installed: list[str] = []
-
-    with tempfile.TemporaryDirectory(prefix="skill-install-") as tmp:
-        clone_dir = os.path.join(tmp, "repo")
-        print(f"Cloning {repo}" + (f" @{ref}" if ref else "") + "...")
-        clone_repo(repo, ref, clone_dir)
-
-        if not paths:
-            # No path specified — treat entire repo as a single skill
-            if validate_skill(clone_dir):
-                name = copy_skill(clone_dir, dest)
-                installed.append(name)
-            else:
-                # List top-level directories that look like skills
-                for entry in sorted(os.listdir(clone_dir)):
-                    entry_path = os.path.join(clone_dir, entry)
-                    if os.path.isdir(entry_path) and validate_skill(entry_path):
-                        name = copy_skill(entry_path, dest)
-                        installed.append(name)
-
-                if not installed:
-                    print("No valid skills found in repository root.", file=sys.stderr)
-        else:
-            for p in paths:
-                skill_path = os.path.join(clone_dir, p.strip("/"))
-                if not os.path.isdir(skill_path):
-                    print(f"  Path not found: {p}", file=sys.stderr)
-                    continue
-                if not validate_skill(skill_path):
-                    print(f"  No SKILL.md in: {p}", file=sys.stderr)
-                    continue
-                name = copy_skill(skill_path, dest)
-                installed.append(name)
-
-    return installed
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description="Install skills from GitHub into a local skills directory.",
-    )
-    src = parser.add_mutually_exclusive_group(required=True)
-    src.add_argument(
-        "--url",
-        help="GitHub URL (e.g. https://github.com/owner/repo/tree/main/skill-name)",
-    )
-    src.add_argument(
-        "--repo",
-        help="GitHub repo (e.g. owner/repo)",
-    )
-    parser.add_argument(
-        "--path",
-        action="append",
-        default=[],
-        help="Path to skill inside repo (repeatable)",
-    )
-    parser.add_argument(
-        "--ref",
-        default=None,
-        help="Git branch or tag (default: repo default branch)",
-    )
-    parser.add_argument(
-        "--dest",
-        default="./skills",
-        help="Destination directory (default: ./skills)",
-    )
-
-    args = parser.parse_args()
-    dest = args.dest
-
-    # Parse source
-    if args.url:
-        repo, ref, path = parse_github_url(args.url)
-        ref = args.ref or ref
-        paths = [path] if path else args.path
-    else:
-        repo = args.repo
-        ref = args.ref
-        paths = args.path
-
-    try:
-        installed = install(repo, paths, ref, dest)
-    except RuntimeError as e:
-        print(f"Error: {e}", file=sys.stderr)
-        return 1
-
-    if installed:
-        print(f"\nInstalled {len(installed)} skill(s) to {dest}/:")
-        for name in installed:
-            print(f"  - {name}")
-    else:
-        print("No skills were installed.", file=sys.stderr)
-        return 1
-
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

EvoScientist/skills/flash-attention/SKILL.md

@@ -1,367 +0,0 @@
----
-name: flash-attention
-description: Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. Use when training/running transformers with long sequences (>512 tokens), encountering GPU memory issues with attention, or need faster inference. Supports PyTorch native SDPA, flash-attn library, H100 FP8, and sliding window attention.
-version: 1.0.0
-author: Orchestra Research
-license: MIT
-tags: [Optimization, Flash Attention, Attention Optimization, Memory Efficiency, Speed Optimization, Long Context, PyTorch, SDPA, H100, FP8, Transformers]
-dependencies: [flash-attn, torch, transformers]
----
-
-# 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:
-```python
-with torch.backends.cuda.sdp_kernel(
-    enable_flash=True,
-    enable_math=False,
-    enable_mem_efficient=False
-):
-    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:
-        with torch.backends.cuda.sdp_kernel(enable_flash=True):
-            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 H100 GPUs.
-
-```
-FP8 Setup:
-- [ ] Step 1: Verify H100 GPU available
-- [ ] Step 2: Install flash-attn with FP8 support
-- [ ] Step 3: Convert inputs to FP8
-- [ ] Step 4: Run with FP8 attention
-```
-
-**Step 1: Verify H100 GPU**
-
-```bash
-nvidia-smi --query-gpu=name --format=csv
-# Should show "H100" or "H800"
-```
-
-**Step 2: Install flash-attn with FP8 support**
-
-```bash
-pip install flash-attn --no-build-isolation
-# FP8 support included for H100
-```
-
-**Step 3: Convert inputs to FP8**
-
-```python
-import torch
-
-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)
-
-# Convert to float8_e4m3 (FP8)
-q_fp8 = q.to(torch.float8_e4m3fn)
-k_fp8 = k.to(torch.float8_e4m3fn)
-v_fp8 = v.to(torch.float8_e4m3fn)
-```
-
-**Step 4: Run with FP8 attention**
-
-```python
-from flash_attn import flash_attn_func
-
-# FlashAttention-3 automatically uses FP8 kernels on H100
-out = flash_attn_func(q_fp8, k_fp8, v_fp8)
-# Result: ~1.2 PFLOPS, 1.5-2x faster than FP16
-```
-
-## 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 <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:
-- <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](references/transformers-integration.md) for enabling Flash Attention in BERT, GPT, Llama models.
-
-**Performance benchmarks**: See [references/benchmarks.md](references/benchmarks.md) for detailed speed and memory comparisons across GPUs and sequence lengths.
-
-**Algorithm details**: See [references/algorithm.md](references/algorithm.md) for tiling strategy, recomputation, and IO complexity analysis.
-
-**Advanced features**: See [references/advanced-features.md](references/advanced-features.md) for rotary embeddings, ALiBi, paged KV cache, and custom attention masks.
-
-## 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
-
-
-