@saibolla/ada 0.1.2

package/skills/pytorch-lightning/scripts/template_datamodule.py

@@ -0,0 +1,328 @@
+"""
+Template for creating a PyTorch Lightning DataModule.
+
+This template provides a complete boilerplate for building a LightningDataModule
+with all essential methods and best practices for data handling.
+"""
+
+import lightning as L
+from torch.utils.data import Dataset, DataLoader, random_split
+import torch
+
+
+class CustomDataset(Dataset):
+    """
+    Custom Dataset implementation.
+
+    Replace this with your actual dataset implementation.
+    """
+
+    def __init__(self, data_path, transform=None):
+        """
+        Initialize the dataset.
+
+        Args:
+            data_path: Path to data directory
+            transform: Optional transforms to apply
+        """
+        self.data_path = data_path
+        self.transform = transform
+
+        # Load your data here
+        # self.data = load_data(data_path)
+        # self.labels = load_labels(data_path)
+
+        # Placeholder data
+        self.data = torch.randn(1000, 3, 224, 224)
+        self.labels = torch.randint(0, 10, (1000,))
+
+    def __len__(self):
+        """Return the size of the dataset."""
+        return len(self.data)
+
+    def __getitem__(self, idx):
+        """
+        Get a single item from the dataset.
+
+        Args:
+            idx: Index of the item
+
+        Returns:
+            Tuple of (data, label)
+        """
+        sample = self.data[idx]
+        label = self.labels[idx]
+
+        if self.transform:
+            sample = self.transform(sample)
+
+        return sample, label
+
+
+class TemplateDataModule(L.LightningDataModule):
+    """
+    Template LightningDataModule for data handling.
+
+    This class encapsulates all data processing steps:
+    1. Download/prepare data (prepare_data)
+    2. Create datasets (setup)
+    3. Create dataloaders (train/val/test/predict_dataloader)
+
+    Args:
+        data_dir: Directory containing the data
+        batch_size: Batch size for dataloaders
+        num_workers: Number of workers for data loading
+        train_val_split: Train/validation split ratio
+        pin_memory: Whether to pin memory for faster GPU transfer
+    """
+
+    def __init__(
+        self,
+        data_dir: str = "./data",
+        batch_size: int = 32,
+        num_workers: int = 4,
+        train_val_split: float = 0.8,
+        pin_memory: bool = True,
+    ):
+        super().__init__()
+
+        # Save hyperparameters
+        self.save_hyperparameters()
+
+        # Initialize as None (will be set in setup)
+        self.train_dataset = None
+        self.val_dataset = None
+        self.test_dataset = None
+        self.predict_dataset = None
+
+    def prepare_data(self):
+        """
+        Download and prepare data.
+
+        This method is called only once and on a single process.
+        Do not set state here (e.g., self.x = y) because it's not
+        transferred to other processes.
+
+        Use this for:
+        - Downloading datasets
+        - Tokenizing text
+        - Saving processed data to disk
+        """
+        # Example: Download data if not exists
+        # if not os.path.exists(self.hparams.data_dir):
+        #     download_dataset(self.hparams.data_dir)
+
+        # Example: Process and save data
+        # process_and_save(self.hparams.data_dir)
+
+        pass
+
+    def setup(self, stage: str = None):
+        """
+        Create datasets for each stage.
+
+        This method is called on every process in distributed training.
+        Set state here (e.g., self.train_dataset = ...).
+
+        Args:
+            stage: Current stage ('fit', 'validate', 'test', or 'predict')
+        """
+        # Define transforms
+        train_transform = self._get_train_transforms()
+        test_transform = self._get_test_transforms()
+
+        # Setup for training and validation
+        if stage == "fit" or stage is None:
+            # Load full dataset
+            full_dataset = CustomDataset(
+                self.hparams.data_dir, transform=train_transform
+            )
+
+            # Split into train and validation
+            train_size = int(self.hparams.train_val_split * len(full_dataset))
+            val_size = len(full_dataset) - train_size
+
+            self.train_dataset, self.val_dataset = random_split(
+                full_dataset,
+                [train_size, val_size],
+                generator=torch.Generator().manual_seed(42),
+            )
+
+            # Apply test transforms to validation set
+            # (Note: random_split doesn't support different transforms,
+            # you may need to implement a custom wrapper)
+
+        # Setup for testing
+        if stage == "test" or stage is None:
+            self.test_dataset = CustomDataset(
+                self.hparams.data_dir, transform=test_transform
+            )
+
+        # Setup for prediction
+        if stage == "predict":
+            self.predict_dataset = CustomDataset(
+                self.hparams.data_dir, transform=test_transform
+            )
+
+    def _get_train_transforms(self):
+        """
+        Define training transforms/augmentations.
+
+        Returns:
+            Training transforms
+        """
+        # Example with torchvision:
+        # from torchvision import transforms
+        # return transforms.Compose([
+        #     transforms.RandomHorizontalFlip(),
+        #     transforms.RandomRotation(10),
+        #     transforms.Normalize(mean=[0.485, 0.456, 0.406],
+        #                         std=[0.229, 0.224, 0.225])
+        # ])
+
+        return None
+
+    def _get_test_transforms(self):
+        """
+        Define test/validation transforms (no augmentation).
+
+        Returns:
+            Test/validation transforms
+        """
+        # Example with torchvision:
+        # from torchvision import transforms
+        # return transforms.Compose([
+        #     transforms.Normalize(mean=[0.485, 0.456, 0.406],
+        #                         std=[0.229, 0.224, 0.225])
+        # ])
+
+        return None
+
+    def train_dataloader(self):
+        """
+        Create training dataloader.
+
+        Returns:
+            Training DataLoader
+        """
+        return DataLoader(
+            self.train_dataset,
+            batch_size=self.hparams.batch_size,
+            shuffle=True,
+            num_workers=self.hparams.num_workers,
+            pin_memory=self.hparams.pin_memory,
+            persistent_workers=True if self.hparams.num_workers > 0 else False,
+            drop_last=True,  # Drop last incomplete batch
+        )
+
+    def val_dataloader(self):
+        """
+        Create validation dataloader.
+
+        Returns:
+            Validation DataLoader
+        """
+        return DataLoader(
+            self.val_dataset,
+            batch_size=self.hparams.batch_size,
+            shuffle=False,
+            num_workers=self.hparams.num_workers,
+            pin_memory=self.hparams.pin_memory,
+            persistent_workers=True if self.hparams.num_workers > 0 else False,
+        )
+
+    def test_dataloader(self):
+        """
+        Create test dataloader.
+
+        Returns:
+            Test DataLoader
+        """
+        return DataLoader(
+            self.test_dataset,
+            batch_size=self.hparams.batch_size,
+            shuffle=False,
+            num_workers=self.hparams.num_workers,
+        )
+
+    def predict_dataloader(self):
+        """
+        Create prediction dataloader.
+
+        Returns:
+            Prediction DataLoader
+        """
+        return DataLoader(
+            self.predict_dataset,
+            batch_size=self.hparams.batch_size,
+            shuffle=False,
+            num_workers=self.hparams.num_workers,
+        )
+
+    # Optional: State management for checkpointing
+
+    def state_dict(self):
+        """
+        Save DataModule state for checkpointing.
+
+        Returns:
+            State dictionary
+        """
+        return {"train_val_split": self.hparams.train_val_split}
+
+    def load_state_dict(self, state_dict):
+        """
+        Restore DataModule state from checkpoint.
+
+        Args:
+            state_dict: State dictionary
+        """
+        self.hparams.train_val_split = state_dict["train_val_split"]
+
+    # Optional: Teardown for cleanup
+
+    def teardown(self, stage: str = None):
+        """
+        Cleanup after training/testing/prediction.
+
+        Args:
+            stage: Current stage ('fit', 'validate', 'test', or 'predict')
+        """
+        # Clean up resources
+        if stage == "fit":
+            self.train_dataset = None
+            self.val_dataset = None
+        elif stage == "test":
+            self.test_dataset = None
+        elif stage == "predict":
+            self.predict_dataset = None
+
+
+# Example usage
+if __name__ == "__main__":
+    # Create DataModule
+    dm = TemplateDataModule(
+        data_dir="./data",
+        batch_size=64,
+        num_workers=8,
+        train_val_split=0.8,
+    )
+
+    # Setup for training
+    dm.prepare_data()
+    dm.setup(stage="fit")
+
+    # Get dataloaders
+    train_loader = dm.train_dataloader()
+    val_loader = dm.val_dataloader()
+
+    print(f"Train dataset size: {len(dm.train_dataset)}")
+    print(f"Validation dataset size: {len(dm.val_dataset)}")
+    print(f"Train batches: {len(train_loader)}")
+    print(f"Validation batches: {len(val_loader)}")
+
+    # Example: Use with Trainer
+    # from template_lightning_module import TemplateLightningModule
+    # model = TemplateLightningModule()
+    # trainer = L.Trainer(max_epochs=10)
+    # trainer.fit(model, datamodule=dm)

package/skills/pytorch-lightning/scripts/template_lightning_module.py

@@ -0,0 +1,219 @@
+"""
+Template for creating a PyTorch Lightning Module.
+
+This template provides a complete boilerplate for building a LightningModule
+with all essential methods and best practices.
+"""
+
+import lightning as L
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.optim import Adam
+from torch.optim.lr_scheduler import ReduceLROnPlateau
+
+
+class TemplateLightningModule(L.LightningModule):
+    """
+    Template LightningModule for building deep learning models.
+
+    Args:
+        learning_rate: Learning rate for optimizer
+        hidden_dim: Hidden dimension size
+        dropout: Dropout probability
+    """
+
+    def __init__(
+        self,
+        learning_rate: float = 0.001,
+        hidden_dim: int = 256,
+        dropout: float = 0.1,
+    ):
+        super().__init__()
+
+        # Save hyperparameters (accessible via self.hparams)
+        self.save_hyperparameters()
+
+        # Define your model architecture
+        self.model = nn.Sequential(
+            nn.Linear(784, self.hparams.hidden_dim),
+            nn.ReLU(),
+            nn.Dropout(self.hparams.dropout),
+            nn.Linear(self.hparams.hidden_dim, 10),
+        )
+
+        # Optional: Define metrics
+        # from torchmetrics import Accuracy
+        # self.train_accuracy = Accuracy(task="multiclass", num_classes=10)
+        # self.val_accuracy = Accuracy(task="multiclass", num_classes=10)
+
+    def forward(self, x):
+        """
+        Forward pass of the model.
+
+        Args:
+            x: Input tensor
+
+        Returns:
+            Model output
+        """
+        return self.model(x)
+
+    def training_step(self, batch, batch_idx):
+        """
+        Training step (called for each training batch).
+
+        Args:
+            batch: Current batch of data
+            batch_idx: Index of the current batch
+
+        Returns:
+            Loss tensor
+        """
+        x, y = batch
+
+        # Forward pass
+        logits = self(x)
+        loss = F.cross_entropy(logits, y)
+
+        # Calculate accuracy (optional)
+        preds = torch.argmax(logits, dim=1)
+        acc = (preds == y).float().mean()
+
+        # Log metrics
+        self.log("train/loss", loss, on_step=True, on_epoch=True, prog_bar=True)
+        self.log("train/acc", acc, on_step=True, on_epoch=True)
+        self.log("learning_rate", self.optimizers().param_groups[0]["lr"])
+
+        return loss
+
+    def validation_step(self, batch, batch_idx):
+        """
+        Validation step (called for each validation batch).
+
+        Args:
+            batch: Current batch of data
+            batch_idx: Index of the current batch
+        """
+        x, y = batch
+
+        # Forward pass
+        logits = self(x)
+        loss = F.cross_entropy(logits, y)
+
+        # Calculate accuracy
+        preds = torch.argmax(logits, dim=1)
+        acc = (preds == y).float().mean()
+
+        # Log metrics (automatically aggregated across batches)
+        self.log("val/loss", loss, on_epoch=True, prog_bar=True, sync_dist=True)
+        self.log("val/acc", acc, on_epoch=True, prog_bar=True, sync_dist=True)
+
+    def test_step(self, batch, batch_idx):
+        """
+        Test step (called for each test batch).
+
+        Args:
+            batch: Current batch of data
+            batch_idx: Index of the current batch
+        """
+        x, y = batch
+
+        # Forward pass
+        logits = self(x)
+        loss = F.cross_entropy(logits, y)
+
+        # Calculate accuracy
+        preds = torch.argmax(logits, dim=1)
+        acc = (preds == y).float().mean()
+
+        # Log metrics
+        self.log("test/loss", loss, on_epoch=True)
+        self.log("test/acc", acc, on_epoch=True)
+
+    def predict_step(self, batch, batch_idx, dataloader_idx=0):
+        """
+        Prediction step (called for each prediction batch).
+
+        Args:
+            batch: Current batch of data
+            batch_idx: Index of the current batch
+            dataloader_idx: Index of the dataloader (if multiple)
+
+        Returns:
+            Predictions
+        """
+        x, y = batch
+        logits = self(x)
+        preds = torch.argmax(logits, dim=1)
+        return preds
+
+    def configure_optimizers(self):
+        """
+        Configure optimizers and learning rate schedulers.
+
+        Returns:
+            Optimizer and scheduler configuration
+        """
+        # Define optimizer
+        optimizer = Adam(
+            self.parameters(),
+            lr=self.hparams.learning_rate,
+            weight_decay=1e-5,
+        )
+
+        # Define scheduler
+        scheduler = ReduceLROnPlateau(
+            optimizer,
+            mode="min",
+            factor=0.5,
+            patience=5,
+            verbose=True,
+        )
+
+        # Return configuration
+        return {
+            "optimizer": optimizer,
+            "lr_scheduler": {
+                "scheduler": scheduler,
+                "monitor": "val/loss",
+                "interval": "epoch",
+                "frequency": 1,
+            },
+        }
+
+    # Optional: Add custom methods for model-specific logic
+
+    def on_train_epoch_end(self):
+        """Called at the end of each training epoch."""
+        # Example: Log custom metrics
+        pass
+
+    def on_validation_epoch_end(self):
+        """Called at the end of each validation epoch."""
+        # Example: Compute epoch-level metrics
+        pass
+
+
+# Example usage
+if __name__ == "__main__":
+    # Create model
+    model = TemplateLightningModule(
+        learning_rate=0.001,
+        hidden_dim=256,
+        dropout=0.1,
+    )
+
+    # Create trainer
+    trainer = L.Trainer(
+        max_epochs=10,
+        accelerator="auto",
+        devices="auto",
+        logger=True,
+    )
+
+    # Train (you need to provide train_dataloader and val_dataloader)
+    # trainer.fit(model, train_dataloader, val_dataloader)
+
+    print(f"Model created with {model.num_parameters:,} parameters")
+    print(f"Hyperparameters: {model.hparams}")

package/skills/pyzotero/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: pyzotero
+description: Interact with Zotero reference management libraries using the pyzotero Python client. Retrieve, create, update, and delete items, collections, tags, and attachments via the Zotero Web API v3. Use this skill when working with Zotero libraries programmatically, managing bibliographic references, exporting citations, searching library contents, uploading PDF attachments, or building research automation workflows that integrate with Zotero.
+allowed-tools: Read Write Edit Bash
+license: MIT License
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# Pyzotero
+
+Pyzotero is a Python wrapper for the [Zotero API v3](https://www.zotero.org/support/dev/web_api/v3/start). Use it to programmatically manage Zotero libraries: read items and collections, create and update references, upload attachments, manage tags, and export citations.
+
+## Authentication Setup
+
+**Required credentials** — get from https://www.zotero.org/settings/keys:
+- **User ID**: shown as "Your userID for use in API calls"
+- **API Key**: create at https://www.zotero.org/settings/keys/new
+- **Library ID**: for group libraries, the integer after `/groups/` in the group URL
+
+Store credentials in environment variables or a `.env` file:
+```
+ZOTERO_LIBRARY_ID=your_user_id
+ZOTERO_API_KEY=your_api_key
+ZOTERO_LIBRARY_TYPE=user  # or "group"
+```
+
+See [references/authentication.md](references/authentication.md) for full setup details.
+
+## Installation
+
+```bash
+uv add pyzotero
+# or with CLI support:
+uv add "pyzotero[cli]"
+```
+
+## Quick Start
+
+```python
+from pyzotero import Zotero
+
+zot = Zotero(library_id='123456', library_type='user', api_key='ABC1234XYZ')
+
+# Retrieve top-level items (returns 100 by default)
+items = zot.top(limit=10)
+for item in items:
+    print(item['data']['title'], item['data']['itemType'])
+
+# Search by keyword
+results = zot.items(q='machine learning', limit=20)
+
+# Retrieve all items (use everything() for complete results)
+all_items = zot.everything(zot.items())
+```
+
+## Core Concepts
+
+- A `Zotero` instance is bound to a single library (user or group). All methods operate on that library.
+- Item data lives in `item['data']`. Access fields like `item['data']['title']`, `item['data']['creators']`.
+- Pyzotero returns 100 items by default (API default is 25). Use `zot.everything(zot.items())` to get all items.
+- Write methods return `True` on success or raise a `ZoteroError`.
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [references/authentication.md](references/authentication.md) | Credentials, library types, local mode |
+| [references/read-api.md](references/read-api.md) | Retrieving items, collections, tags, groups |
+| [references/search-params.md](references/search-params.md) | Filtering, sorting, search parameters |
+| [references/write-api.md](references/write-api.md) | Creating, updating, deleting items |
+| [references/collections.md](references/collections.md) | Collection CRUD operations |
+| [references/tags.md](references/tags.md) | Tag retrieval and management |
+| [references/files-attachments.md](references/files-attachments.md) | File retrieval and attachment uploads |
+| [references/exports.md](references/exports.md) | BibTeX, CSL-JSON, bibliography export |
+| [references/pagination.md](references/pagination.md) | follow(), everything(), generators |
+| [references/full-text.md](references/full-text.md) | Full-text content indexing and retrieval |
+| [references/saved-searches.md](references/saved-searches.md) | Saved search management |
+| [references/cli.md](references/cli.md) | Command-line interface usage |
+| [references/error-handling.md](references/error-handling.md) | Errors and exception handling |
+
+## Common Patterns
+
+### Fetch and modify an item
+```python
+item = zot.item('ITEMKEY')
+item['data']['title'] = 'New Title'
+zot.update_item(item)
+```
+
+### Create an item from a template
+```python
+template = zot.item_template('journalArticle')
+template['title'] = 'My Paper'
+template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'}
+zot.create_items([template])
+```
+
+### Export as BibTeX
+```python
+zot.add_parameters(format='bibtex')
+bibtex = zot.top(limit=50)
+# bibtex is a bibtexparser BibDatabase object
+print(bibtex.entries)
+```
+
+### Local mode (read-only, no API key needed)
+```python
+zot = Zotero(library_id='123456', library_type='user', local=True)
+items = zot.items()
+```