pi-skill-search 0.1.0

package/skills/generate-image/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: generate-image
+description: Generate or edit images using AI models (FLUX, Nano Banana 2). Use for general-purpose image generation including photos, illustrations, artwork, visual assets, concept art, and any image that is not a technical diagram or schematic. For flowcharts, circuits, pathways, and technical diagrams, use the scientific-schematics skill instead.
+---
+
+# Generate Image
+
+Generate and edit high-quality images using OpenRouter's image generation models including FLUX.2 Pro and Gemini 3.1 Flash Image Preview.
+
+## When to Use This Skill
+
+**Use generate-image for:**
+- Photos and photorealistic images
+- Artistic illustrations and artwork
+- Concept art and visual concepts
+- Visual assets for presentations or documents
+- Image editing and modifications
+- Any general-purpose image generation needs
+
+**Use scientific-schematics instead for:**
+- Flowcharts and process diagrams
+- Circuit diagrams and electrical schematics
+- Biological pathways and signaling cascades
+- System architecture diagrams
+- CONSORT diagrams and methodology flowcharts
+- Any technical/schematic diagrams
+
+## Quick Start
+
+Use the `scripts/generate_image.py` script to generate or edit images:
+
+```bash
+# Generate a new image
+python scripts/generate_image.py "A beautiful sunset over mountains"
+
+# Edit an existing image
+python scripts/generate_image.py "Make the sky purple" --input photo.jpg
+```
+
+This generates/edits an image and saves it as `generated_image.png` in the current directory.
+
+## API Key Setup
+
+**CRITICAL**: The script requires an OpenRouter API key. Before running, check if the user has configured their API key:
+
+1. Look for a `.env` file in the project directory or parent directories
+2. Check for `OPENROUTER_API_KEY=<key>` in the `.env` file
+3. If not found, inform the user they need to:
+   - Create a `.env` file with `OPENROUTER_API_KEY=your-api-key-here`
+   - Or set the environment variable: `export OPENROUTER_API_KEY=your-api-key-here`
+   - Get an API key from: https://openrouter.ai/keys
+
+The script will automatically detect the `.env` file and provide clear error messages if the API key is missing.
+
+## Model Selection
+
+**Default model**: `google/gemini-3.1-flash-image-preview` (high quality, recommended)
+
+**Available models for generation and editing**:
+- `google/gemini-3.1-flash-image-preview` - High quality, supports generation + editing
+- `black-forest-labs/flux.2-pro` - Fast, high quality, supports generation + editing
+
+**Generation only**:
+- `black-forest-labs/flux.2-flex` - Fast and cheap, but not as high quality as pro
+
+Select based on:
+- **Quality**: Use gemini-3.1-flash-image-preview or flux.2-pro
+- **Editing**: Use gemini-3.1-flash-image-preview or flux.2-pro (both support image editing)
+- **Cost**: Use flux.2-flex for generation only
+
+## Common Usage Patterns
+
+### Basic generation
+```bash
+python scripts/generate_image.py "Your prompt here"
+```
+
+### Specify model
+```bash
+python scripts/generate_image.py "A cat in space" --model "black-forest-labs/flux.2-pro"
+```
+
+### Custom output path
+```bash
+python scripts/generate_image.py "Abstract art" --output artwork.png
+```
+
+### Edit an existing image
+```bash
+python scripts/generate_image.py "Make the background blue" --input photo.jpg
+```
+
+### Edit with a specific model
+```bash
+python scripts/generate_image.py "Add sunglasses to the person" --input portrait.png --model "black-forest-labs/flux.2-pro"
+```
+
+### Edit with custom output
+```bash
+python scripts/generate_image.py "Remove the text from the image" --input screenshot.png --output cleaned.png
+```
+
+### Multiple images
+Run the script multiple times with different prompts or output paths:
+```bash
+python scripts/generate_image.py "Image 1 description" --output image1.png
+python scripts/generate_image.py "Image 2 description" --output image2.png
+```

package/skills/geniml/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: geniml
+description: This skill should be used when working with genomic interval data (BED files) for machine learning tasks. Use for training region embeddings (Region2Vec, BEDspace), single-cell ATAC-seq analysis (scEmbed), building consensus peaks (universes), or any ML-based analysis of genomic regions. Applies to BED file collections, scATAC-seq data, chromatin accessibility datasets, and region-based genomic feature learning.
+---
+
+# Geniml: Genomic Interval Machine Learning
+
+## Overview
+
+Geniml is a Python package for building machine learning models on genomic interval data from BED files. It provides unsupervised methods for learning embeddings of genomic regions, single cells, and metadata labels, enabling similarity searches, clustering, and downstream ML tasks.
+
+## Core Capabilities
+
+Geniml provides five primary capabilities, each detailed in dedicated reference files:
+
+### 1. Region2Vec: Genomic Region Embeddings
+
+Train unsupervised embeddings of genomic regions using word2vec-style learning.
+
+**Use for:** Dimensionality reduction of BED files, region similarity analysis, feature vectors for downstream ML.
+
+**Workflow:**
+1. Tokenize BED files using a universe reference
+2. Train Region2Vec model on tokens
+3. Generate embeddings for regions
+
+**Reference:** See `(see docs)` for detailed workflow, parameters, and examples.
+
+### 2. BEDspace: Joint Region and Metadata Embeddings
+
+Train shared embeddings for region sets and metadata labels using StarSpace.
+
+**Use for:** Metadata-aware searches, cross-modal queries (region→label or label→region), joint analysis of genomic content and experimental conditions.
+
+**Workflow:**
+1. Preprocess regions and metadata
+2. Train BEDspace model
+3. Compute distances
+4. Query across regions and labels
+
+**Reference:** See `(see docs)` for detailed workflow, search types, and examples.
+
+### 3. scEmbed: Single-Cell Chromatin Accessibility Embeddings
+
+Train Region2Vec models on single-cell ATAC-seq data for cell-level embeddings.
+
+**Use for:** scATAC-seq clustering, cell-type annotation, dimensionality reduction of single cells, integration with scanpy workflows.
+
+**Workflow:**
+1. Prepare AnnData with peak coordinates
+2. Pre-tokenize cells
+3. Train scEmbed model
+4. Generate cell embeddings
+5. Cluster and visualize with scanpy
+
+**Reference:** See `(see docs)` for detailed workflow, parameters, and examples.
+
+### 4. Consensus Peaks: Universe Building
+
+Build reference peak sets (universes) from BED file collections using multiple statistical methods.
+
+**Use for:** Creating tokenization references, standardizing regions across datasets, defining consensus features with statistical rigor.
+
+**Workflow:**
+1. Combine BED files
+2. Generate coverage tracks
+3. Build universe using CC, CCF, ML, or HMM method
+
+**Methods:**
+- **CC (Coverage Cutoff)**: Simple threshold-based
+- **CCF (Coverage Cutoff Flexible)**: Confidence intervals for boundaries
+- **ML (Maximum Likelihood)**: Probabilistic modeling of positions
+
+### 5. Utilities: Supporting Tools
+
+Additional tools for caching, randomization, evaluation, and search.
+
+**Available utilities:**
+- **BBClient**: BED file caching for repeated access
+- **BEDshift**: Randomization preserving genomic context
+- **Evaluation**: Metrics for embedding quality (silhouette, Davies-Bouldin, etc.)
+- **Tokenization**: Region tokenization utilities (hard, soft, universe-based)
+- **Text2BedNN**: Neural search backends for genomic queries
+
+**Reference:** See `(see docs)` for detailed usage of each utility.
+
+## Common Workflows
+
+### Basic Region Embedding Pipeline
+
+```python
+from geniml.tokenization import hard_tokenization
+from geniml.region2vec import region2vec
+from geniml.evaluation import evaluate_embeddings
+
+# Step 1: Tokenize BED files
+hard_tokenization(
+    src_folder='bed_files/',
+    dst_folder='tokens/',
+    universe_file='universe.bed',
+    p_value_threshold=1e-9
+)
+
+# Step 2: Train Region2Vec
+region2vec(
+    token_folder='tokens/',
+    save_dir='model/',
+    num_shufflings=1000,
+    embedding_dim=100
+)
+
+# Step 3: Evaluate
+metrics = evaluate_embeddings(
+    embeddings_file='model/embeddings.npy',
+    labels_file='metadata.csv'
+)
+```

package/skills/geomaster/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: geomaster
+description: Comprehensive geospatial science skill covering remote sensing, GIS, spatial analysis, machine learning for earth observation, and 30+ scientific domains. Supports satellite imagery processing (Sentinel, Landsat, MODIS, SAR, hyperspectral), vector and raster data operations, spatial statistics, point cloud processing, network analysis, cloud-native workflows (STAC, COG, Planetary Computer), and 8 programming languages (Python, R, Julia, JavaScript, C++, Java, Go, Rust) with 500+ code examples. Use for remote sensing workflows, GIS analysis, spatial ML, Earth observation data processing, terrain analysis, hydrological modeling, marine spatial analysis, atmospheric science, and any geospatial computation task.
+---
+
+# GeoMaster
+
+Comprehensive geospatial science skill covering GIS, remote sensing, spatial analysis, and ML for Earth observation across 70+ topics with 500+ code examples in 8 programming languages.
+
+# Core Python stack (conda recommended)
+conda install -c conda-forge gdal rasterio fiona shapely pyproj geopandas
+
+# Remote sensing & ML
+uv pip install rsgislib torchgeo earthengine-api
+uv pip install scikit-learn xgboost torch-geometric
+
+# Network & visualization
+uv pip install osmnx networkx folium keplergl
+uv pip install cartopy contextily mapclassify
+
+# Big data & cloud
+uv pip install xarray rioxarray dask-geopandas
+uv pip install pystac-client planetary-computer
+
+# Point clouds
+uv pip install laspy pylas open3d pdal
+
+# Databases
+conda install -c conda-forge postgis spatialite
+```
+
+## Quick Start
+
+### NDVI from Sentinel-2
+
+```python
+import rasterio
+import numpy as np
+
+with rasterio.open('sentinel2.tif') as src:
+    red = src.read(4).astype(float)   # B04
+    nir = src.read(8).astype(float)   # B08
+    ndvi = (nir - red) / (nir + red + 1e-8)
+    ndvi = np.nan_to_num(ndvi, nan=0)
+
+    profile = src.profile
+    profile.update(count=1, dtype=rasterio.float32)
+
+
+### Spatial Analysis with GeoPandas
+
+```python
+import geopandas as gpd
+
+# Load and ensure same CRS
+zones = gpd.read_file('zones.geojson')
+points = gpd.read_file('points.geojson')
+
+if zones.crs != points.crs:
+    points = points.to_crs(zones.crs)
+
+# Spatial join and statistics
+joined = gpd.sjoin(points, zones, how='inner', predicate='within')
+stats = joined.groupby('zone_id').agg({
+    'value': ['count', 'mean', 'std', 'min', 'max']
+}).round(2)
+```
+
+### Google Earth Engine Time Series
+
+```python
+import ee
+import pandas as pd
+
+ee.Initialize(project='your-project')
+roi = ee.Geometry.Point([-122.4, 37.7]).buffer(10000)
+
+s2 = (ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED')
+      .filterBounds(roi)
+      .filterDate('2020-01-01', '2023-12-31')
+      .filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE', 20)))
+
+def add_ndvi(img):
+
+## Core Concepts
+
+### Data Types
+
+| Type | Examples | Libraries |
+|------|----------|-----------|
+| Vector | Shapefile, GeoJSON, GeoPackage | GeoPandas, Fiona, GDAL |
+| Raster | GeoTIFF, NetCDF, COG | Rasterio, Xarray, GDAL |
+| Point Cloud | LAS, LAZ | Laspy, PDAL, Open3D |
+
+### Coordinate Systems
+
+- **EPSG:4326** (WGS 84) - Geographic, lat/lon, use for storage
+- **EPSG:3857** (Web Mercator) - Web maps only (don't use for area/distance!)
+- **EPSG:326xx/327xx** (UTM) - Metric calculations, <1% distortion per zone
+- Use `gdf.estimate_utm_crs()` for automatic UTM detection
+
+```python
+# Always check CRS before operations
+assert gdf1.crs == gdf2.crs, "CRS mismatch!"
+
+# For area/distance calculations, use projected CRS
+gdf_metric = gdf.to_crs(gdf.estimate_utm_crs())
+
+

package/skills/geopandas/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: geopandas
+description: Python library for working with geospatial vector data including shapefiles, GeoJSON, and GeoPackage files. Use when working with geographic data for spatial analysis, geometric operations, coordinate transformations, spatial joins, overlay operations, choropleth mapping, or any task involving reading/writing/analyzing vector geographic data. Supports PostGIS databases, interactive maps, and integration with matplotlib/folium/cartopy. Use for tasks like buffer analysis, spatial joins between datasets, dissolving boundaries, clipping data, calculating areas/distances, reprojecting coordinate systems, creating maps, or converting between spatial file formats.
+---
+
+# GeoPandas
+
+GeoPandas extends pandas to enable spatial operations on geometric types. It combines the capabilities of pandas and shapely for geospatial data analysis.
+
+### Optional Dependencies
+
+```bash
+# For interactive maps
+uv pip install folium
+
+# For classification schemes in mapping
+uv pip install mapclassify
+
+# For faster I/O operations (2-4x speedup)
+uv pip install pyarrow
+
+# For PostGIS database support
+uv pip install psycopg2
+uv pip install geoalchemy2
+
+# For basemaps
+uv pip install contextily
+
+# For cartographic projections
+uv pip install cartopy
+```
+
+## Quick Start
+
+```python
+import geopandas as gpd
+
+# Read spatial data
+gdf = gpd.read_file("data.geojson")
+
+# Basic exploration
+print(gdf.head())
+print(gdf.crs)
+print(gdf.geometry.geom_type)
+
+# Simple plot
+gdf.plot()
+
+# Reproject to different CRS
+gdf_projected = gdf.to_crs("EPSG:3857")
+
+# Calculate area (use projected CRS for accuracy)
+gdf_projected['area'] = gdf_projected.geometry.area
+
+# Save to file
+gdf.to_file("output.gpkg")
+```
+
+## Core Concepts
+
+### Data Structures
+
+- **GeoSeries**: Vector of geometries with spatial operations
+- **GeoDataFrame**: Tabular data structure with geometry column
+
+See data-structures.md for details.
+
+### Reading and Writing Data
+
+GeoPandas reads/writes multiple formats: Shapefile, GeoJSON, GeoPackage, PostGIS, Parquet.
+
+```python
+# Read with filtering
+gdf = gpd.read_file("data.gpkg", bbox=(xmin, ymin, xmax, ymax))
+
+# Write with Arrow acceleration
+gdf.to_file("output.gpkg", use_arrow=True)
+```
+
+See data-io.md for comprehensive I/O operations.
+
+### Coordinate Reference Systems
+
+Always check and manage CRS for accurate spatial operations:
+
+```python
+# Check CRS
+print(gdf.crs)
+
+# Reproject (transforms coordinates)
+gdf_projected = gdf.to_crs("EPSG:3857")
+
+# Set CRS (only when metadata missing)
+gdf = gdf.set_crs("EPSG:4326")
+```
+
+See crs-management.md for CRS operations.
+
+## Common Operations
+
+### Geometric Operations
+
+Buffer, simplify, centroid, convex hull, affine transformations:
+
+```python
+# Buffer by 10 units
+buffered = gdf.geometry.buffer(10)
+
+# Simplify with tolerance
+simplified = gdf.geometry.simplify(tolerance=5, preserve_topology=True)
+
+# Get centroids
+centroids = gdf.geometry.centroid
+```

package/skills/get-available-resources/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: get-available-resources
+description: This skill should be used at the start of any computationally intensive scientific task to detect and report available system resources (CPU cores, GPUs, memory, disk space). It creates a JSON file with resource information and strategic recommendations that inform computational approach decisions such as whether to use parallel processing (joblib, multiprocessing), out-of-core computing (Dask, Zarr), GPU acceleration (PyTorch, JAX), or memory-efficient strategies. Use this skill before running analyses, training models, processing large datasets, or any task where resource constraints matter.
+---
+
+# Get Available Resources
+
+## Overview
+
+Detect available computational resources and generate strategic recommendations for scientific computing tasks. This skill automatically identifies CPU capabilities, GPU availability (NVIDIA CUDA, AMD ROCm, Apple Silicon Metal), memory constraints, and disk space to help make informed decisions about computational approaches.
+
+## When to Use This Skill
+
+Use this skill proactively before any computationally intensive task:
+
+- **Before data analysis**: Determine if datasets can be loaded into memory or require out-of-core processing
+- **Before model training**: Check if GPU acceleration is available and which backend to use
+- **Before parallel processing**: Identify optimal number of workers for joblib, multiprocessing, or Dask
+- **Before large file operations**: Verify sufficient disk space and appropriate storage strategies
+- **At project initialization**: Understand baseline capabilities for making architectural decisions
+
+**Example scenarios:**
+- "Help me analyze this 50GB genomics dataset" → Use this skill first to determine if Dask/Zarr are needed
+- "Train a neural network on this data" → Use this skill to detect available GPUs and backends
+- "Process 10,000 files in parallel" → Use this skill to determine optimal worker count
+- "Run a computationally intensive simulation" → Use this skill to understand resource constraints
+
+### Resource Detection
+
+The skill runs `scripts/detect_resources.py` to automatically detect:
+
+1. **CPU Information**
+   - Physical and logical core counts
+   - Processor architecture and model
+   - CPU frequency information
+
+2. **GPU Information**
+   - NVIDIA GPUs: Detects via nvidia-smi, reports VRAM, driver version, compute capability
+   - AMD GPUs: Detects via rocm-smi
+   - Apple Silicon: Detects M1/M2/M3/M4 chips with Metal support and unified memory
+
+3. **Memory Information**
+
+### Strategic Recommendations
+
+The skill generates context-aware recommendations:
+
+**Parallel Processing Recommendations:**
+- **High parallelism (8+ cores)**: Use Dask, joblib, or multiprocessing with workers = cores - 2
+- **Moderate parallelism (4-7 cores)**: Use joblib or multiprocessing with workers = cores - 1
+- **Sequential (< 4 cores)**: Prefer sequential processing to avoid overhead
+
+**Memory Strategy Recommendations:**
+- **Memory constrained (< 4GB available)**: Use Zarr, Dask, or H5py for out-of-core processing
+- **Moderate memory (4-16GB available)**: Use Dask/Zarr for datasets > 2GB
+- **Memory abundant (> 16GB available)**: Can load most datasets into memory directly
+
+**GPU Acceleration Recommendations:**
+
+## Usage Instructions
+
+### Step 1: Run Resource Detection
+
+Execute the detection script at the start of any computationally intensive task:
+
+```bash
+python scripts/detect_resources.py
+```
+
+Optional arguments:
+- `-o, --output <path>`: Specify custom output path (default: `.claude_resources.json`)
+- `-v, --verbose`: Print full resource information to stdout
+
+### Step 2: Read and Apply Recommendations
+
+After running detection, read the generated `.claude_resources.json` file to inform computational decisions:
+
+```python
+# Example: Use recommendations in code
+import json
+
+with open('.claude_resources.json', 'r') as f:
+    resources = json.load(f)
+
+# Check parallel processing strategy
+if resources['recommendations']['parallel_processing']['strategy'] == 'high_parallelism':
+    n_jobs = resources['recommendations']['parallel_processing']['suggested_workers']
+    # Use joblib, Dask, or multiprocessing with n_jobs workers
+
+# Check memory strategy
+if resources['recommendations']['memory_strategy']['strategy'] == 'memory_constrained':
+    # Use Dask, Zarr, or H5py for out-of-core processing
+    import dask.array as da
+    # Load data in chunks
+
+# Check GPU availability
+if resources['recommendations']['gpu_acceleration']['available']:
+    backends = resources['recommendations']['gpu_acceleration']['backends']
+    # Use appropriate GPU library based on available backend
+```

package/skills/gget/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: gget
+description: "Fast CLI/Python queries to 20+ bioinformatics databases. Use for quick lookups: gene info, BLAST searches, AlphaFold structures, enrichment analysis. Best for interactive exploration, simple queries. For batch processing or advanced BLAST use biopython; for multi-database Python workflows use bioservices."
+---
+
+# gget
+
+## Overview
+
+gget is a command-line bioinformatics tool and Python package providing unified access to 20+ genomic databases and analysis methods. Query gene information, sequence analysis, protein structures, expression data, and disease associations through a consistent interface. All gget modules work both as command-line tools and as Python functions.
+
+**Important**: The databases queried by gget are continuously updated, which sometimes changes their structure. gget modules are tested automatically on a biweekly basis and updated to match new database structures when necessary.
+
+# Using uv (recommended)
+uv uv pip install gget
+
+# Or using pip
+uv pip install --upgrade gget
+
+# In Python/Jupyter
+import gget
+```
+
+## Quick Start
+
+Basic usage pattern for all modules:
+
+```bash
+# Command-line
+gget <module> [arguments] [options]
+
+# Python
+gget.module(arguments, options)
+```
+
+Most modules return:
+- **Command-line**: JSON (default) or CSV with `-csv` flag
+- **Python**: DataFrame or dictionary
+
+Common flags across modules:
+- `-o/--out`: Save results to file
+- `-q/--quiet`: Suppress progress information
+- `-csv`: Return CSV format (command-line only)
+
+## Module Categories
+
+# List available species
+gget ref --list_species
+
+# Get all reference files for human
+gget ref homo_sapiens
+
+# Download only GTF annotation for mouse
+gget ref -w gtf -d mouse
+```
+
+```python
+# Python
+gget.ref("homo_sapiens")
+gget.ref("mus_musculus", which="gtf", download=True)
+```
+
+#### gget search - Gene Search
+
+Locate genes by name or description across species.
+
+**Parameters**:
+- `searchwords`: One or more search terms (case-insensitive)
+- `-s/--species`: Target species (e.g., 'homo_sapiens', 'mouse')
+- `-r/--release`: Ensembl release number
+- `-t/--id_type`: Return 'gene' (default) or 'transcript'
+- `-ao/--andor`: 'or' (default) finds ANY searchword; 'and' requires ALL
+
+# Search for GABA-related genes in human
+gget search -s human gaba gamma-aminobutyric
+
+# Find specific gene, require all terms
+gget search -s mouse -ao and pax7 transcription
+```
+
+```python
+# Python
+gget.search(["gaba", "gamma-aminobutyric"], species="homo_sapiens")
+```
+
+#### gget info - Gene/Transcript Information
+
+Retrieve comprehensive gene and transcript metadata from Ensembl, UniProt, and NCBI.
+
+**Parameters**:
+- `ens_ids`: One or more Ensembl IDs (also supports WormBase, Flybase IDs). Limit: ~1000 IDs
+- `-n/--ncbi`: Disable NCBI data retrieval
+- `-u/--uniprot`: Disable UniProt data retrieval
+- `-pdb`: Include PDB identifiers (increases runtime)
+
+**Returns**: UniProt ID, NCBI gene ID, primary gene name, synonyms, protein names, descriptions, biotype, canonical transcript
+
+**Examples**:
+```bash
+# Get info for multiple genes
+gget info ENSG00000034713 ENSG00000104853 ENSG00000170296
+
+# Include PDB IDs
+gget info ENSG00000034713 -pdb
+```
+
+```python
+# Python
+gget.info(["ENSG00000034713", "ENSG00000104853"], pdb=True)
+
+