@saibolla/ada 0.1.2

package/skills/kegg-database/scripts/kegg_api.py

@@ -0,0 +1,251 @@
+"""
+KEGG REST API Helper Functions
+
+This module provides Python functions for interacting with the KEGG REST API.
+All functions return raw response text which can be parsed as needed.
+
+API Base URL: https://rest.kegg.jp
+Documentation: https://www.kegg.jp/kegg/rest/keggapi.html
+
+IMPORTANT: KEGG API is made available only for academic use by academic users.
+"""
+
+import urllib.request
+import urllib.parse
+import urllib.error
+from typing import Optional, List, Union
+
+
+KEGG_BASE_URL = "https://rest.kegg.jp"
+
+
+def kegg_info(database: str) -> str:
+    """
+    Get database metadata and statistics.
+
+    Args:
+        database: KEGG database name (e.g., 'kegg', 'pathway', 'enzyme', 'genes')
+
+    Returns:
+        str: Database information and statistics
+
+    Example:
+        info = kegg_info('pathway')
+    """
+    url = f"{KEGG_BASE_URL}/info/{database}"
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+def kegg_list(database: str, org: Optional[str] = None) -> str:
+    """
+    List entry identifiers and associated names.
+
+    Args:
+        database: KEGG database name or specific entry (e.g., 'pathway', 'enzyme', 'hsa:10458')
+        org: Optional organism code for pathway/module listings (e.g., 'hsa' for human)
+
+    Returns:
+        str: Tab-delimited list of entries
+
+    Examples:
+        pathways = kegg_list('pathway')  # List all reference pathways
+        hsa_pathways = kegg_list('pathway', 'hsa')  # List human pathways
+        genes = kegg_list('hsa:10458+ece:Z5100')  # List specific genes
+    """
+    if org:
+        url = f"{KEGG_BASE_URL}/list/{database}/{org}"
+    else:
+        url = f"{KEGG_BASE_URL}/list/{database}"
+
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+def kegg_find(database: str, query: str, option: Optional[str] = None) -> str:
+    """
+    Search for entries by keywords or molecular properties.
+
+    Args:
+        database: Database to search ('genes', 'compound', 'drug', etc.)
+        query: Search term or molecular property
+        option: Optional parameter for molecular searches:
+                'formula' - exact match to chemical formula
+                'exact_mass' - range search by exact mass (e.g., '174.05-174.15')
+                'mol_weight' - range search by molecular weight
+
+    Returns:
+        str: Tab-delimited search results
+
+    Examples:
+        # Keyword search
+        results = kegg_find('genes', 'shiga toxin')
+
+        # Formula search
+        compounds = kegg_find('compound', 'C7H10N4O2', 'formula')
+
+        # Mass range search
+        drugs = kegg_find('drug', '300-310', 'exact_mass')
+    """
+    query_encoded = urllib.parse.quote(query)
+
+    if option:
+        url = f"{KEGG_BASE_URL}/find/{database}/{query_encoded}/{option}"
+    else:
+        url = f"{KEGG_BASE_URL}/find/{database}/{query_encoded}"
+
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+def kegg_get(entries: Union[str, List[str]], option: Optional[str] = None) -> str:
+    """
+    Retrieve full database entries or specific data formats.
+
+    Args:
+        entries: Single entry ID or list of entry IDs (max 10)
+        option: Optional output format:
+                'aaseq' or 'ntseq' - FASTA sequence
+                'mol' - MOL format (for compounds)
+                'kcf' - KCF format (for compounds)
+                'image' - PNG image (pathway maps, single entry only)
+                'kgml' - KGML format (pathway XML, single entry only)
+                'json' - JSON format (pathway only, single entry only)
+
+    Returns:
+        str: Entry data in requested format
+
+    Examples:
+        # Get pathway entry
+        pathway = kegg_get('hsa00010')
+
+        # Get multiple entries
+        genes = kegg_get(['hsa:10458', 'ece:Z5100'])
+
+        # Get sequence
+        sequence = kegg_get('hsa:10458', 'aaseq')
+
+        # Get pathway as JSON
+        pathway_json = kegg_get('hsa05130', 'json')
+    """
+    if isinstance(entries, list):
+        entries_str = '+'.join(entries[:10])  # Max 10 entries
+    else:
+        entries_str = entries
+
+    if option:
+        url = f"{KEGG_BASE_URL}/get/{entries_str}/{option}"
+    else:
+        url = f"{KEGG_BASE_URL}/get/{entries_str}"
+
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+def kegg_conv(target_db: str, source_db: str) -> str:
+    """
+    Convert identifiers between KEGG and external databases.
+
+    Args:
+        target_db: Target database (e.g., 'ncbi-geneid', 'uniprot', 'pubchem')
+        source_db: Source database or entry (e.g., 'hsa', 'compound', 'hsa:10458')
+
+    Returns:
+        str: Tab-delimited conversion table
+
+    Examples:
+        # Convert all human genes to NCBI Gene IDs
+        conversions = kegg_conv('ncbi-geneid', 'hsa')
+
+        # Convert specific gene
+        gene_id = kegg_conv('ncbi-geneid', 'hsa:10458')
+
+        # Convert compounds to PubChem IDs
+        pubchem = kegg_conv('pubchem', 'compound')
+    """
+    url = f"{KEGG_BASE_URL}/conv/{target_db}/{source_db}"
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+def kegg_link(target_db: str, source_db: str) -> str:
+    """
+    Find related entries across KEGG databases.
+
+    Args:
+        target_db: Target database (e.g., 'pathway', 'enzyme', 'genes')
+        source_db: Source database or entry (e.g., 'hsa', 'pathway', 'hsa:10458')
+
+    Returns:
+        str: Tab-delimited list of linked entries
+
+    Examples:
+        # Find pathways linked to human genes
+        links = kegg_link('pathway', 'hsa')
+
+        # Find genes in a specific pathway
+        genes = kegg_link('genes', 'hsa00010')
+
+        # Find pathways for a specific gene
+        pathways = kegg_link('pathway', 'hsa:10458')
+    """
+    url = f"{KEGG_BASE_URL}/link/{target_db}/{source_db}"
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+def kegg_ddi(drug_entries: Union[str, List[str]]) -> str:
+    """
+    Check drug-drug interactions.
+
+    Args:
+        drug_entries: Single drug entry or list of drug entries (max 10)
+
+    Returns:
+        str: Drug interaction information
+
+    Example:
+        interactions = kegg_ddi(['D00001', 'D00002'])
+    """
+    if isinstance(drug_entries, list):
+        entries_str = '+'.join(drug_entries[:10])  # Max 10 entries
+    else:
+        entries_str = drug_entries
+
+    url = f"{KEGG_BASE_URL}/ddi/{entries_str}"
+    try:
+        with urllib.request.urlopen(url) as response:
+            return response.read().decode('utf-8')
+    except urllib.error.HTTPError as e:
+        return f"Error: {e.code} - {e.reason}"
+
+
+if __name__ == "__main__":
+    # Example usage
+    print("KEGG Info Example:")
+    print(kegg_info('pathway')[:200] + "...\n")
+
+    print("KEGG List Example (first 3 pathways):")
+    pathways = kegg_list('pathway')
+    print('\n'.join(pathways.split('\n')[:3]) + "\n")
+
+    print("KEGG Find Example:")
+    print(kegg_find('genes', 'p53')[:200] + "...")

package/skills/labarchive-integration/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: labarchive-integration
+description: Electronic lab notebook API integration. Access notebooks, manage entries/attachments, backup notebooks, integrate with Protocols.io/Jupyter/REDCap, for programmatic ELN workflows.
+license: Unknown
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# LabArchives Integration
+
+## Overview
+
+LabArchives is an electronic lab notebook platform for research documentation and data management. Access notebooks, manage entries and attachments, generate reports, and integrate with third-party tools programmatically via REST API.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Working with LabArchives REST API for notebook automation
+- Backing up notebooks programmatically
+- Creating or managing notebook entries and attachments
+- Generating site reports and analytics
+- Integrating LabArchives with third-party tools (Protocols.io, Jupyter, REDCap)
+- Automating data upload to electronic lab notebooks
+- Managing user access and permissions programmatically
+
+## Core Capabilities
+
+### 1. Authentication and Configuration
+
+Set up API access credentials and regional endpoints for LabArchives API integration.
+
+**Prerequisites:**
+- Enterprise LabArchives license with API access enabled
+- API access key ID and password from LabArchives administrator
+- User authentication credentials (email and external applications password)
+
+**Configuration setup:**
+
+Use the `scripts/setup_config.py` script to create a configuration file:
+
+```bash
+python3 scripts/setup_config.py
+```
+
+This creates a `config.yaml` file with the following structure:
+
+```yaml
+api_url: https://api.labarchives.com/api  # or regional endpoint
+access_key_id: YOUR_ACCESS_KEY_ID
+access_password: YOUR_ACCESS_PASSWORD
+```
+
+**Regional API endpoints:**
+- US/International: `https://api.labarchives.com/api`
+- Australia: `https://auapi.labarchives.com/api`
+- UK: `https://ukapi.labarchives.com/api`
+
+For detailed authentication instructions and troubleshooting, refer to `references/authentication_guide.md`.
+
+### 2. User Information Retrieval
+
+Obtain user ID (UID) and access information required for subsequent API operations.
+
+**Workflow:**
+
+1. Call the `users/user_access_info` API method with login credentials
+2. Parse the XML/JSON response to extract the user ID (UID)
+3. Use the UID to retrieve detailed user information via `users/user_info_via_id`
+
+**Example using Python wrapper:**
+
+```python
+from labarchivespy.client import Client
+
+# Initialize client
+client = Client(api_url, access_key_id, access_password)
+
+# Get user access info
+login_params = {'login_or_email': user_email, 'password': auth_token}
+response = client.make_call('users', 'user_access_info', params=login_params)
+
+# Extract UID from response
+import xml.etree.ElementTree as ET
+uid = ET.fromstring(response.content)[0].text
+
+# Get detailed user info
+params = {'uid': uid}
+user_info = client.make_call('users', 'user_info_via_id', params=params)
+```
+
+### 3. Notebook Operations
+
+Manage notebook access, backup, and metadata retrieval.
+
+**Key operations:**
+
+- **List notebooks:** Retrieve all notebooks accessible to a user
+- **Backup notebooks:** Download complete notebook data with optional attachment inclusion
+- **Get notebook IDs:** Retrieve institution-defined notebook identifiers for integration with grants/project management systems
+- **Get notebook members:** List all users with access to a specific notebook
+- **Get notebook settings:** Retrieve configuration and permissions for notebooks
+
+**Notebook backup example:**
+
+Use the `scripts/notebook_operations.py` script:
+
+```bash
+# Backup with attachments (default, creates 7z archive)
+python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID
+
+# Backup without attachments, JSON format
+python3 scripts/notebook_operations.py backup --uid USER_ID --nbid NOTEBOOK_ID --json --no-attachments
+```
+
+**API endpoint format:**
+```
+https://<api_url>/notebooks/notebook_backup?uid=<UID>&nbid=<NOTEBOOK_ID>&json=true&no_attachments=false
+```
+
+For comprehensive API method documentation, refer to `references/api_reference.md`.
+
+### 4. Entry and Attachment Management
+
+Create, modify, and manage notebook entries and file attachments.
+
+**Entry operations:**
+- Create new entries in notebooks
+- Add comments to existing entries
+- Create entry parts/components
+- Upload file attachments to entries
+
+**Attachment workflow:**
+
+Use the `scripts/entry_operations.py` script:
+
+```bash
+# Upload attachment to an entry
+python3 scripts/entry_operations.py upload --uid USER_ID --nbid NOTEBOOK_ID --entry-id ENTRY_ID --file /path/to/file.pdf
+
+# Create a new entry with text content
+python3 scripts/entry_operations.py create --uid USER_ID --nbid NOTEBOOK_ID --title "Experiment Results" --content "Results from today's experiment..."
+```
+
+**Supported file types:**
+- Documents (PDF, DOCX, TXT)
+- Images (PNG, JPG, TIFF)
+- Data files (CSV, XLSX, HDF5)
+- Scientific formats (CIF, MOL, PDB)
+- Archives (ZIP, 7Z)
+
+### 5. Site Reports and Analytics
+
+Generate institutional reports on notebook usage, activity, and compliance (Enterprise feature).
+
+**Available reports:**
+- Detailed Usage Report: User activity metrics and engagement statistics
+- Detailed Notebook Report: Notebook metadata, member lists, and settings
+- PDF/Offline Notebook Generation Report: Export tracking for compliance
+- Notebook Members Report: Access control and collaboration analytics
+- Notebook Settings Report: Configuration and permission auditing
+
+**Report generation:**
+
+```python
+# Generate detailed usage report
+response = client.make_call('site_reports', 'detailed_usage_report',
+                           params={'start_date': '2025-01-01', 'end_date': '2025-10-20'})
+```
+
+### 6. Third-Party Integrations
+
+LabArchives integrates with numerous scientific software platforms. This skill provides guidance on leveraging these integrations programmatically.
+
+**Supported integrations:**
+- **Protocols.io:** Export protocols directly to LabArchives notebooks
+- **GraphPad Prism:** Export analyses and figures (Version 8+)
+- **SnapGene:** Direct molecular biology workflow integration
+- **Geneious:** Bioinformatics analysis export
+- **Jupyter:** Embed Jupyter notebooks as entries
+- **REDCap:** Clinical data capture integration
+- **Qeios:** Research publishing platform
+- **SciSpace:** Literature management
+
+**OAuth authentication:**
+LabArchives now uses OAuth for all new integrations. Legacy integrations may use API key authentication.
+
+For detailed integration setup instructions and use cases, refer to `references/integrations.md`.
+
+## Common Workflows
+
+### Complete notebook backup workflow
+
+1. Authenticate and obtain user ID
+2. List all accessible notebooks
+3. Iterate through notebooks and backup each one
+4. Store backups with timestamp metadata
+
+```bash
+# Complete backup script
+python3 scripts/notebook_operations.py backup-all --email user@example.edu --password AUTH_TOKEN
+```
+
+### Automated data upload workflow
+
+1. Authenticate with LabArchives API
+2. Identify target notebook and entry
+3. Upload experimental data files
+4. Add metadata comments to entries
+5. Generate activity report
+
+### Integration workflow example (Jupyter → LabArchives)
+
+1. Export Jupyter notebook to HTML or PDF
+2. Use entry_operations.py to upload to LabArchives
+3. Add comment with execution timestamp and environment info
+4. Tag entry for easy retrieval
+
+## Python Package Installation
+
+Install the `labarchives-py` wrapper for simplified API access:
+
+```bash
+git clone https://github.com/mcmero/labarchives-py
+cd labarchives-py
+uv pip install .
+```
+
+Alternatively, use direct HTTP requests via Python's `requests` library for custom implementations.
+
+## Best Practices
+
+1. **Rate limiting:** Implement appropriate delays between API calls to avoid throttling
+2. **Error handling:** Always wrap API calls in try-except blocks with appropriate logging
+3. **Authentication security:** Store credentials in environment variables or secure config files (never in code)
+4. **Backup verification:** After notebook backup, verify file integrity and completeness
+5. **Incremental operations:** For large notebooks, use pagination and batch processing
+6. **Regional endpoints:** Use the correct regional API endpoint for optimal performance
+
+## Troubleshooting
+
+**Common issues:**
+
+- **401 Unauthorized:** Verify access key ID and password are correct; check API access is enabled for your account
+- **404 Not Found:** Confirm notebook ID (nbid) exists and user has access permissions
+- **403 Forbidden:** Check user permissions for the requested operation
+- **Empty response:** Ensure required parameters (uid, nbid) are provided correctly
+- **Attachment upload failures:** Verify file size limits and format compatibility
+
+For additional support, contact LabArchives at support@labarchives.com.
+
+## Resources
+
+This skill includes bundled resources to support LabArchives API integration:
+
+### scripts/
+
+- `setup_config.py`: Interactive configuration file generator for API credentials
+- `notebook_operations.py`: Utilities for listing, backing up, and managing notebooks
+- `entry_operations.py`: Tools for creating entries and uploading attachments
+
+### references/
+
+- `api_reference.md`: Comprehensive API endpoint documentation with parameters and examples
+- `authentication_guide.md`: Detailed authentication setup and configuration instructions
+- `integrations.md`: Third-party integration setup guides and use cases
+