@wentorai/research-plugins 1.0.0

package/skills/analysis/wrangling/text-mining-guide/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: text-mining-guide
+description: "Apply NLP and text mining techniques to research text data"
+metadata:
+  openclaw:
+    emoji: "mag"
+    category: "analysis"
+    subcategory: "wrangling"
+    keywords: ["text mining", "NLP", "topic modeling", "sentiment analysis", "text preprocessing", "natural language processing"]
+    source: "wentor-research-plugins"
+---
+
+# Text Mining Guide
+
+A skill for applying natural language processing (NLP) and text mining techniques to research data. Covers text preprocessing, feature extraction, topic modeling, sentiment analysis, and named entity recognition for analyzing surveys, abstracts, social media, and document corpora.
+
+## Text Preprocessing Pipeline
+
+### Standard Cleaning Steps
+
+```python
+import re
+from collections import Counter
+
+
+def preprocess_text(text: str, lowercase: bool = True,
+                    remove_numbers: bool = False,
+                    min_word_length: int = 2) -> list[str]:
+    """
+    Preprocess text for NLP analysis.
+
+    Args:
+        text: Raw input text
+        lowercase: Convert to lowercase
+        remove_numbers: Remove numeric tokens
+        min_word_length: Minimum token length to keep
+    """
+    if lowercase:
+        text = text.lower()
+
+    # Remove URLs
+    text = re.sub(r"http\S+|www\.\S+", "", text)
+
+    # Remove HTML tags
+    text = re.sub(r"<[^>]+>", "", text)
+
+    # Remove special characters (keep apostrophes for contractions)
+    text = re.sub(r"[^a-zA-Z0-9\s']", " ", text)
+
+    # Tokenize
+    tokens = text.split()
+
+    if remove_numbers:
+        tokens = [t for t in tokens if not t.isdigit()]
+
+    # Remove short tokens
+    tokens = [t for t in tokens if len(t) >= min_word_length]
+
+    return tokens
+
+
+def remove_stopwords(tokens: list[str],
+                     custom_stopwords: list[str] = None) -> list[str]:
+    """
+    Remove stopwords from token list.
+    """
+    # Minimal English stopwords (extend as needed)
+    default_stops = {
+        "the", "a", "an", "and", "or", "but", "in", "on", "at",
+        "to", "for", "of", "with", "by", "is", "was", "are", "were",
+        "be", "been", "being", "have", "has", "had", "do", "does",
+        "did", "will", "would", "could", "should", "may", "might",
+        "this", "that", "these", "those", "it", "its", "not", "no"
+    }
+
+    if custom_stopwords:
+        default_stops.update(custom_stopwords)
+
+    return [t for t in tokens if t not in default_stops]
+```
+
+### Document-Term Matrix
+
+```python
+from sklearn.feature_extraction.text import TfidfVectorizer
+
+
+def build_tfidf_matrix(documents: list[str],
+                       max_features: int = 5000) -> dict:
+    """
+    Build a TF-IDF document-term matrix.
+
+    Args:
+        documents: List of document strings
+        max_features: Maximum vocabulary size
+    """
+    vectorizer = TfidfVectorizer(
+        max_features=max_features,
+        stop_words="english",
+        min_df=2,           # Appear in at least 2 documents
+        max_df=0.95,        # Ignore terms in >95% of documents
+        ngram_range=(1, 2)  # Unigrams and bigrams
+    )
+
+    tfidf_matrix = vectorizer.fit_transform(documents)
+
+    return {
+        "matrix_shape": tfidf_matrix.shape,
+        "vocabulary_size": len(vectorizer.vocabulary_),
+        "top_terms": sorted(
+            vectorizer.vocabulary_.items(),
+            key=lambda x: x[1]
+        )[:20],
+        "vectorizer": vectorizer,
+        "matrix": tfidf_matrix
+    }
+```
+
+## Topic Modeling
+
+### Latent Dirichlet Allocation (LDA)
+
+```python
+from sklearn.decomposition import LatentDirichletAllocation
+
+
+def run_topic_model(tfidf_matrix, vectorizer,
+                    n_topics: int = 10) -> list[dict]:
+    """
+    Run LDA topic modeling on a document-term matrix.
+
+    Args:
+        tfidf_matrix: Sparse TF-IDF matrix
+        vectorizer: Fitted TfidfVectorizer
+        n_topics: Number of topics to extract
+    """
+    lda = LatentDirichletAllocation(
+        n_components=n_topics,
+        random_state=42,
+        max_iter=50,
+        learning_method="online"
+    )
+    lda.fit(tfidf_matrix)
+
+    feature_names = vectorizer.get_feature_names_out()
+    topics = []
+
+    for idx, topic_weights in enumerate(lda.components_):
+        top_indices = topic_weights.argsort()[-10:][::-1]
+        top_words = [feature_names[i] for i in top_indices]
+        topics.append({
+            "topic_id": idx,
+            "top_words": top_words,
+            "label": "Assign a human-readable label based on top words"
+        })
+
+    return topics
+```
+
+### Choosing the Number of Topics
+
+```
+Methods for selecting k (number of topics):
+  - Coherence score: Higher is better (use gensim's CoherenceModel)
+  - Perplexity: Lower is better (but can overfit)
+  - Human judgment: Do topics make interpretive sense?
+  - Domain knowledge: Expected number of themes in the corpus
+
+Practical advice:
+  - Start with k = 5, 10, 15, 20 and compare
+  - Examine top words for each k -- look for coherent themes
+  - If topics are too broad, increase k
+  - If topics overlap heavily, decrease k
+```
+
+## Sentiment Analysis
+
+### Lexicon-Based Approach
+
+```python
+def simple_sentiment(text: str, positive_words: set,
+                     negative_words: set) -> dict:
+    """
+    Basic lexicon-based sentiment scoring.
+
+    Args:
+        text: Input text
+        positive_words: Set of positive sentiment words
+        negative_words: Set of negative sentiment words
+    """
+    tokens = text.lower().split()
+
+    pos_count = sum(1 for t in tokens if t in positive_words)
+    neg_count = sum(1 for t in tokens if t in negative_words)
+    total = len(tokens)
+
+    score = (pos_count - neg_count) / max(total, 1)
+
+    return {
+        "positive_count": pos_count,
+        "negative_count": neg_count,
+        "score": score,
+        "label": (
+            "positive" if score > 0.05
+            else "negative" if score < -0.05
+            else "neutral"
+        )
+    }
+```
+
+## Research Applications
+
+### Common Text Mining Tasks in Research
+
+| Task | Method | Application |
+|------|--------|-------------|
+| Literature mapping | Topic modeling | Identify research themes in a corpus of abstracts |
+| Survey analysis | Thematic coding + sentiment | Analyze open-ended survey responses |
+| Social media analysis | NER + sentiment | Track public discourse on a topic |
+| Content analysis | Classification + keyword extraction | Code qualitative data at scale |
+| Bibliometrics | Co-word analysis | Map intellectual structure of a field |
+
+## Validation and Reporting
+
+Always validate text mining results against human judgment. Report preprocessing steps, parameter choices (e.g., number of topics, min_df, max_df), and model evaluation metrics. For topic models, include the top 10-15 words per topic and representative documents. For classification, report precision, recall, and F1 on a held-out test set. Acknowledge that automated text analysis supplements but does not replace close reading.

package/skills/domains/ai-ml/computer-vision-guide/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: computer-vision-guide
+description: "Apply computer vision research methods, models, and evaluation tools"
+metadata:
+  openclaw:
+    emoji: "eye"
+    category: "domains"
+    subcategory: "ai-ml"
+    keywords: ["computer vision", "image classification", "object detection", "CNN", "vision transformer", "deep learning"]
+    source: "wentor-research-plugins"
+---
+
+# Computer Vision Guide
+
+A skill for conducting computer vision research, covering model architectures, dataset preparation, training pipelines, evaluation metrics, and common experimental protocols for image classification, object detection, and segmentation tasks.
+
+## Core Tasks and Architectures
+
+### Computer Vision Task Taxonomy
+
+```
+Image Classification:
+  Input: Single image
+  Output: Class label(s)
+  Models: ResNet, EfficientNet, ViT, ConvNeXt
+
+Object Detection:
+  Input: Single image
+  Output: Bounding boxes + class labels
+  Models: YOLO (v5-v9), Faster R-CNN, DETR, RT-DETR
+
+Semantic Segmentation:
+  Input: Single image
+  Output: Per-pixel class label
+  Models: U-Net, DeepLab, SegFormer, Mask2Former
+
+Instance Segmentation:
+  Input: Single image
+  Output: Per-pixel labels distinguishing individual objects
+  Models: Mask R-CNN, Mask2Former, SAM
+
+Image Generation:
+  Input: Text prompt or noise
+  Output: Generated image
+  Models: Stable Diffusion, DALL-E, Imagen
+```
+
+### Model Architecture Evolution
+
+```
+CNNs (Convolutional Neural Networks):
+  LeNet (1998) -> AlexNet (2012) -> VGG (2014) -> ResNet (2015)
+  -> EfficientNet (2019) -> ConvNeXt (2022)
+
+Vision Transformers:
+  ViT (2020) -> DeiT (2021) -> Swin Transformer (2021)
+  -> BEiT (2021) -> DINOv2 (2023)
+
+Trend: Transformers are competitive with CNNs at scale.
+Hybrid architectures combining convolutions and attention are common.
+```
+
+## Dataset Preparation
+
+### Building a Research Dataset
+
+```python
+import os
+from pathlib import Path
+
+
+def organize_image_dataset(source_dir: str,
+                            split_ratios: dict = None) -> dict:
+    """
+    Organize images into train/val/test splits.
+
+    Args:
+        source_dir: Directory containing class subdirectories
+        split_ratios: Dict with 'train', 'val', 'test' ratios
+    """
+    if split_ratios is None:
+        split_ratios = {"train": 0.7, "val": 0.15, "test": 0.15}
+
+    import random
+    random.seed(42)
+
+    stats = {}
+    for class_dir in sorted(Path(source_dir).iterdir()):
+        if not class_dir.is_dir():
+            continue
+
+        images = list(class_dir.glob("*.jpg")) + list(class_dir.glob("*.png"))
+        random.shuffle(images)
+
+        n = len(images)
+        n_train = int(n * split_ratios["train"])
+        n_val = int(n * split_ratios["val"])
+
+        stats[class_dir.name] = {
+            "total": n,
+            "train": n_train,
+            "val": n_val,
+            "test": n - n_train - n_val
+        }
+
+    return stats
+```
+
+### Data Augmentation
+
+```python
+from torchvision import transforms
+
+
+def get_training_transforms(img_size: int = 224) -> transforms.Compose:
+    """
+    Standard data augmentation pipeline for training.
+
+    Args:
+        img_size: Target image size
+    """
+    return transforms.Compose([
+        transforms.RandomResizedCrop(img_size, scale=(0.8, 1.0)),
+        transforms.RandomHorizontalFlip(p=0.5),
+        transforms.ColorJitter(brightness=0.2, contrast=0.2,
+                               saturation=0.2, hue=0.1),
+        transforms.RandomRotation(15),
+        transforms.ToTensor(),
+        transforms.Normalize(
+            mean=[0.485, 0.456, 0.406],
+            std=[0.229, 0.224, 0.225]
+        )
+    ])
+```
+
+## Training Pipeline
+
+### Transfer Learning Workflow
+
+```python
+import torch
+import torch.nn as nn
+from torchvision import models
+
+
+def create_classifier(num_classes: int,
+                      backbone: str = "resnet50",
+                      pretrained: bool = True) -> nn.Module:
+    """
+    Create an image classifier using transfer learning.
+
+    Args:
+        num_classes: Number of target classes
+        backbone: Model architecture name
+        pretrained: Whether to use ImageNet-pretrained weights
+    """
+    if backbone == "resnet50":
+        weights = models.ResNet50_Weights.DEFAULT if pretrained else None
+        model = models.resnet50(weights=weights)
+        model.fc = nn.Linear(model.fc.in_features, num_classes)
+    elif backbone == "vit_b_16":
+        weights = models.ViT_B_16_Weights.DEFAULT if pretrained else None
+        model = models.vit_b_16(weights=weights)
+        model.heads.head = nn.Linear(
+            model.heads.head.in_features, num_classes
+        )
+    else:
+        raise ValueError(f"Unknown backbone: {backbone}")
+
+    return model
+```
+
+## Evaluation Metrics
+
+### Metrics by Task
+
+```
+Classification:
+  - Top-1 Accuracy: Fraction of correct predictions
+  - Top-5 Accuracy: Correct class in top 5 predictions
+  - Precision, Recall, F1: Per-class and macro-averaged
+  - Confusion Matrix: Visualize class-level errors
+
+Object Detection:
+  - mAP (mean Average Precision): Standard COCO metric
+  - mAP@0.5: AP at IoU threshold 0.5
+  - mAP@0.5:0.95: AP averaged over IoU thresholds 0.5 to 0.95
+  - AP per class: Identifies weak categories
+
+Segmentation:
+  - mIoU (mean Intersection over Union): Standard metric
+  - Pixel Accuracy: Fraction of correctly classified pixels
+  - Dice Coefficient: F1 score at the pixel level
+```
+
+## Reproducibility Checklist
+
+### What to Report in Papers
+
+```
+1. Architecture: Exact model name, number of parameters
+2. Pretraining: Dataset and weights used for initialization
+3. Training: Optimizer, learning rate schedule, batch size, epochs
+4. Augmentation: Full list of augmentations with parameters
+5. Hardware: GPU type, number, training time
+6. Evaluation: Exact metrics, test set version, evaluation protocol
+7. Code: Link to repository with training and evaluation scripts
+8. Random seeds: Report seeds used; ideally report mean over 3+ seeds
+```
+
+## Ethical Considerations
+
+When collecting or using image datasets, consider consent (especially for images of people), geographic and demographic representation, potential for bias amplification, and dual-use concerns. Document the dataset's composition and limitations. Follow the Datasheets for Datasets framework. For generative models, implement safeguards against generating harmful content.

package/skills/domains/ai-ml/deep-learning-papers-guide/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: deep-learning-papers-guide
+description: "Annotated deep learning paper implementations with code walkthroughs"
+metadata:
+  openclaw:
+    emoji: "🧠"
+    category: "domains"
+    subcategory: "ai-ml"
+    keywords: ["deep learning", "neural network", "Transformer", "CNN", "NLP", "computer vision"]
+    source: "https://github.com/labmlai/annotated_deep_learning_paper_implementations"
+---
+
+# Deep Learning Papers Guide
+
+## Overview
+
+Understanding deep learning architectures requires more than reading papers -- it requires reading and writing code. The annotated_deep_learning_paper_implementations repository (65,800+ stars) provides line-by-line annotated implementations of seminal deep learning papers in PyTorch, making it one of the most valuable learning resources in the field.
+
+This guide organizes the key architectures by category, provides implementation patterns for the most important building blocks, and offers strategies for going from paper to working code. Whether you are implementing a Transformer variant for your research, understanding a GAN architecture for your experiments, or teaching a deep learning course, these patterns accelerate the process.
+
+The focus is on practical understanding: what each component does, why it is designed that way, and how to implement it correctly in PyTorch.
+
+## Core Architecture Families
+
+### Transformer Architectures
+
+The Transformer (Vaswani et al., 2017) is the foundation of modern NLP and increasingly of computer vision.
+
+#### Multi-Head Self-Attention
+
+```python
+import torch
+import torch.nn as nn
+import math
+
+class MultiHeadAttention(nn.Module):
+    def __init__(self, d_model: int, n_heads: int):
+        super().__init__()
+        assert d_model % n_heads == 0
+        self.d_model = d_model
+        self.n_heads = n_heads
+        self.d_k = d_model // n_heads
+
+        self.W_q = nn.Linear(d_model, d_model)
+        self.W_k = nn.Linear(d_model, d_model)
+        self.W_v = nn.Linear(d_model, d_model)
+        self.W_o = nn.Linear(d_model, d_model)
+
+    def forward(self, query, key, value, mask=None):
+        batch_size = query.size(0)
+
+        # Linear projections and reshape to (batch, heads, seq, d_k)
+        Q = self.W_q(query).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2)
+        K = self.W_k(key).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2)
+        V = self.W_v(value).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2)
+
+        # Scaled dot-product attention
+        scores = torch.matmul(Q, K.transpose(-2, -1)) / math.sqrt(self.d_k)
+        if mask is not None:
+            scores = scores.masked_fill(mask == 0, float('-inf'))
+        attn = torch.softmax(scores, dim=-1)
+        context = torch.matmul(attn, V)
+
+        # Concatenate heads and project
+        context = context.transpose(1, 2).contiguous().view(batch_size, -1, self.d_model)
+        return self.W_o(context)
+```
+
+#### Transformer Encoder Block
+
+```python
+class TransformerBlock(nn.Module):
+    def __init__(self, d_model: int, n_heads: int, d_ff: int, dropout: float = 0.1):
+        super().__init__()
+        self.attention = MultiHeadAttention(d_model, n_heads)
+        self.norm1 = nn.LayerNorm(d_model)
+        self.norm2 = nn.LayerNorm(d_model)
+        self.ffn = nn.Sequential(
+            nn.Linear(d_model, d_ff),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(d_ff, d_model),
+            nn.Dropout(dropout)
+        )
+        self.dropout = nn.Dropout(dropout)
+
+    def forward(self, x, mask=None):
+        # Pre-norm variant (used in GPT-2, ViT, modern architectures)
+        attn_out = self.attention(self.norm1(x), self.norm1(x), self.norm1(x), mask)
+        x = x + self.dropout(attn_out)
+        x = x + self.ffn(self.norm2(x))
+        return x
+```
+
+### Convolutional Neural Networks
+
+#### ResNet Bottleneck Block
+
+```python
+class BottleneckBlock(nn.Module):
+    expansion = 4
+
+    def __init__(self, in_channels, out_channels, stride=1, downsample=None):
+        super().__init__()
+        self.conv1 = nn.Conv2d(in_channels, out_channels, 1, bias=False)
+        self.bn1 = nn.BatchNorm2d(out_channels)
+        self.conv2 = nn.Conv2d(out_channels, out_channels, 3,
+                               stride=stride, padding=1, bias=False)
+        self.bn2 = nn.BatchNorm2d(out_channels)
+        self.conv3 = nn.Conv2d(out_channels, out_channels * self.expansion, 1, bias=False)
+        self.bn3 = nn.BatchNorm2d(out_channels * self.expansion)
+        self.relu = nn.ReLU(inplace=True)
+        self.downsample = downsample
+
+    def forward(self, x):
+        identity = x
+        out = self.relu(self.bn1(self.conv1(x)))
+        out = self.relu(self.bn2(self.conv2(out)))
+        out = self.bn3(self.conv3(out))
+        if self.downsample is not None:
+            identity = self.downsample(x)
+        out += identity
+        return self.relu(out)
+```
+
+## Key Architecture Comparison
+
+| Architecture | Year | Parameters | Key Innovation | Primary Domain |
+|-------------|------|------------|----------------|---------------|
+| ResNet | 2015 | 25M (ResNet-50) | Skip connections | Vision |
+| Transformer | 2017 | Varies | Self-attention | NLP |
+| BERT | 2018 | 340M (Large) | Masked language modeling | NLP |
+| GPT-2 | 2019 | 1.5B | Autoregressive generation | NLP |
+| ViT | 2020 | 86M (Base) | Patch-based image tokenization | Vision |
+| Diffusion | 2020 | Varies | Iterative denoising | Generation |
+| LLaMA | 2023 | 7B-70B | Efficient open LLM | NLP |
+
+## Training Patterns
+
+### Standard Training Loop
+
+```python
+def train_epoch(model, dataloader, optimizer, criterion, device):
+    model.train()
+    total_loss = 0
+    for batch_idx, (data, targets) in enumerate(dataloader):
+        data, targets = data.to(device), targets.to(device)
+
+        optimizer.zero_grad()
+        outputs = model(data)
+        loss = criterion(outputs, targets)
+        loss.backward()
+
+        # Gradient clipping (crucial for Transformers)
+        torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
+
+        optimizer.step()
+        total_loss += loss.item()
+
+    return total_loss / len(dataloader)
+```
+
+### Learning Rate Scheduling
+
+```python
+# Cosine annealing with warmup (standard for Transformers)
+from torch.optim.lr_scheduler import CosineAnnealingLR, LinearLR, SequentialLR
+
+optimizer = torch.optim.AdamW(model.parameters(), lr=3e-4, weight_decay=0.01)
+warmup = LinearLR(optimizer, start_factor=0.01, total_iters=1000)
+cosine = CosineAnnealingLR(optimizer, T_max=50000)
+scheduler = SequentialLR(optimizer, schedulers=[warmup, cosine], milestones=[1000])
+```
+
+## From Paper to Code: A Methodology
+
+1. **Read the paper twice.** First pass for high-level understanding; second pass for implementation details.
+2. **Identify the core algorithm.** Usually in Section 3 or 4 of the paper.
+3. **List all hyperparameters.** Create a config dict before writing any code.
+4. **Implement bottom-up.** Start with the smallest building blocks (attention, normalization), then compose.
+5. **Test each component in isolation.** Verify tensor shapes and gradients at each level.
+6. **Reproduce a known result first.** Match the paper's numbers on a small dataset before scaling.
+7. **Use the official implementation as reference.** But write your own code for understanding.
+
+## Best Practices
+
+- **Always verify tensor shapes.** Add assert statements for dimensions during development.
+- **Use mixed precision training.** `torch.cuda.amp` provides 2x speedup with minimal accuracy loss.
+- **Log everything.** Use Weights & Biases or TensorBoard for experiment tracking.
+- **Start small.** Debug on a tiny dataset before running on the full one.
+- **Read the appendix.** Critical details (learning rates, initialization, data augmentation) are often in the supplementary material.
+- **Join the community.** Papers With Code, Reddit r/MachineLearning, and Twitter/X are where implementation details are discussed.
+
+## References
+
+- [annotated_deep_learning_paper_implementations](https://github.com/labmlai/annotated_deep_learning_paper_implementations) -- Line-by-line annotated implementations (65,800+ stars)
+- [Attention Is All You Need](https://arxiv.org/abs/1706.03762) -- Original Transformer paper
+- [Deep Residual Learning](https://arxiv.org/abs/1512.03385) -- ResNet paper
+- [The Illustrated Transformer](https://jalammar.github.io/illustrated-transformer/) -- Jay Alammar's visual guide
+- [Papers With Code](https://paperswithcode.com/) -- Paper-implementation pairs with benchmarks