wotann 0.5.80 → 0.5.83

package/skills/scientific/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
+

package/skills/scientific/labarchive-integration/references/api_reference.md

@@ -0,0 +1,342 @@
+# LabArchives API Reference
+
+## API Structure
+
+All LabArchives API calls follow this URL pattern:
+
+```
+https://<base_url>/api/<api_class>/<api_method>?<authentication_parameters>&<method_parameters>
+```
+
+## Regional API Endpoints
+
+| Region | Base URL |
+|--------|----------|
+| US/International | `https://api.labarchives.com/api` |
+| Australia | `https://auapi.labarchives.com/api` |
+| UK | `https://ukapi.labarchives.com/api` |
+
+## Authentication
+
+All API calls require authentication parameters:
+
+- `access_key_id`: Provided by LabArchives administrator
+- `access_password`: Provided by LabArchives administrator
+- Additional user-specific credentials may be required for certain operations
+
+## API Classes and Methods
+
+### Users API Class
+
+#### `users/user_access_info`
+
+Retrieve user ID and notebook access information.
+
+**Parameters:**
+- `login_or_email` (required): User's email address or login username
+- `password` (required): User's external applications password (not regular login password)
+
+**Returns:** XML or JSON response containing:
+- User ID (uid)
+- List of accessible notebooks with IDs (nbid)
+- Account status and permissions
+
+**Example:**
+```python
+params = {
+    'login_or_email': 'researcher@university.edu',
+    'password': 'external_app_password'
+}
+response = client.make_call('users', 'user_access_info', params=params)
+```
+
+#### `users/user_info_via_id`
+
+Retrieve detailed user information by user ID.
+
+**Parameters:**
+- `uid` (required): User ID obtained from user_access_info
+
+**Returns:** User profile information including:
+- Name and email
+- Account creation date
+- Institution affiliation
+- Role and permissions
+- Storage quota and usage
+
+**Example:**
+```python
+params = {'uid': '12345'}
+response = client.make_call('users', 'user_info_via_id', params=params)
+```
+
+### Notebooks API Class
+
+#### `notebooks/notebook_backup`
+
+Download complete notebook data including entries, attachments, and metadata.
+
+**Parameters:**
+- `uid` (required): User ID
+- `nbid` (required): Notebook ID
+- `json` (optional, default: false): Return data in JSON format instead of XML
+- `no_attachments` (optional, default: false): Exclude attachments from backup
+
+**Returns:**
+- When `no_attachments=false`: 7z compressed archive containing all notebook data
+- When `no_attachments=true`: XML or JSON structured data with entry content
+
+**File format:**
+The returned archive includes:
+- Entry text content in HTML format
+- File attachments in original formats
+- Metadata XML files with timestamps, authors, and version history
+- Comment threads and annotations
+
+**Example:**
+```python
+# Full backup with attachments
+params = {
+    'uid': '12345',
+    'nbid': '67890',
+    'json': 'false',
+    'no_attachments': 'false'
+}
+response = client.make_call('notebooks', 'notebook_backup', params=params)
+
+# Write to file
+with open('notebook_backup.7z', 'wb') as f:
+    f.write(response.content)
+```
+
+```python
+# Metadata only backup (JSON format, no attachments)
+params = {
+    'uid': '12345',
+    'nbid': '67890',
+    'json': 'true',
+    'no_attachments': 'true'
+}
+response = client.make_call('notebooks', 'notebook_backup', params=params)
+import json
+notebook_data = json.loads(response.content)
+```
+
+#### `notebooks/list_notebooks`
+
+Retrieve all notebooks accessible to a user (method name may vary by API version).
+
+**Parameters:**
+- `uid` (required): User ID
+
+**Returns:** List of notebooks with:
+- Notebook ID (nbid)
+- Notebook name
+- Creation and modification dates
+- Access level (owner, editor, viewer)
+- Member count
+
+### Entries API Class
+
+#### `entries/create_entry`
+
+Create a new entry in a notebook.
+
+**Parameters:**
+- `uid` (required): User ID
+- `nbid` (required): Notebook ID
+- `title` (required): Entry title
+- `content` (optional): HTML-formatted entry content
+- `date` (optional): Entry date (defaults to current date)
+
+**Returns:** Entry ID and creation confirmation
+
+**Example:**
+```python
+params = {
+    'uid': '12345',
+    'nbid': '67890',
+    'title': 'Experiment 2025-10-20',
+    'content': '<p>Conducted PCR amplification of target gene...</p>',
+    'date': '2025-10-20'
+}
+response = client.make_call('entries', 'create_entry', params=params)
+```
+
+#### `entries/create_comment`
+
+Add a comment to an existing entry.
+
+**Parameters:**
+- `uid` (required): User ID
+- `nbid` (required): Notebook ID
+- `entry_id` (required): Target entry ID
+- `comment` (required): Comment text (HTML supported)
+
+**Returns:** Comment ID and timestamp
+
+#### `entries/create_part`
+
+Add a component/part to an entry (e.g., text section, table, image).
+
+**Parameters:**
+- `uid` (required): User ID
+- `nbid` (required): Notebook ID
+- `entry_id` (required): Target entry ID
+- `part_type` (required): Type of part (text, table, image, etc.)
+- `content` (required): Part content in appropriate format
+
+**Returns:** Part ID and creation confirmation
+
+#### `entries/upload_attachment`
+
+Upload a file attachment to an entry.
+
+**Parameters:**
+- `uid` (required): User ID
+- `nbid` (required): Notebook ID
+- `entry_id` (required): Target entry ID
+- `file` (required): File data (multipart/form-data)
+- `filename` (required): Original filename
+
+**Returns:** Attachment ID and upload confirmation
+
+**Example using requests library:**
+```python
+import requests
+
+url = f'{api_url}/entries/upload_attachment'
+files = {'file': open('/path/to/data.csv', 'rb')}
+params = {
+    'uid': '12345',
+    'nbid': '67890',
+    'entry_id': '11111',
+    'filename': 'data.csv',
+    'access_key_id': access_key_id,
+    'access_password': access_password
+}
+response = requests.post(url, files=files, data=params)
+```
+
+### Site Reports API Class
+
+Enterprise-only features for institutional reporting and analytics.
+
+#### `site_reports/detailed_usage_report`
+
+Generate comprehensive usage statistics for the institution.
+
+**Parameters:**
+- `start_date` (required): Report start date (YYYY-MM-DD)
+- `end_date` (required): Report end date (YYYY-MM-DD)
+- `format` (optional): Output format (csv, json, xml)
+
+**Returns:** Usage metrics including:
+- User login frequency
+- Entry creation counts
+- Storage utilization
+- Collaboration statistics
+- Time-based activity patterns
+
+#### `site_reports/detailed_notebook_report`
+
+Generate detailed report on all notebooks in the institution.
+
+**Parameters:**
+- `include_settings` (optional, default: false): Include notebook settings
+- `include_members` (optional, default: false): Include member lists
+
+**Returns:** Notebook inventory with:
+- Notebook names and IDs
+- Owner information
+- Creation and last modified dates
+- Member count and access levels
+- Storage size
+- Settings (if requested)
+
+#### `site_reports/pdf_offline_generation_report`
+
+Track PDF exports for compliance and auditing purposes.
+
+**Parameters:**
+- `start_date` (required): Report start date
+- `end_date` (required): Report end date
+
+**Returns:** Export activity log with:
+- User who generated PDF
+- Notebook and entry exported
+- Export timestamp
+- IP address
+
+### Utilities API Class
+
+#### `utilities/institutional_login_urls`
+
+Retrieve institutional login URLs for SSO integration.
+
+**Parameters:** None required (uses access key authentication)
+
+**Returns:** List of institutional login endpoints
+
+## Response Formats
+
+### XML Response Example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<response>
+    <uid>12345</uid>
+    <email>researcher@university.edu</email>
+    <notebooks>
+        <notebook>
+            <nbid>67890</nbid>
+            <name>Lab Notebook 2025</name>
+            <role>owner</role>
+        </notebook>
+    </notebooks>
+</response>
+```
+
+### JSON Response Example
+
+```json
+{
+    "uid": "12345",
+    "email": "researcher@university.edu",
+    "notebooks": [
+        {
+            "nbid": "67890",
+            "name": "Lab Notebook 2025",
+            "role": "owner"
+        }
+    ]
+}
+```
+
+## Error Codes
+
+| Code | Message | Meaning | Solution |
+|------|---------|---------|----------|
+| 401 | Unauthorized | Invalid credentials | Verify access_key_id and access_password |
+| 403 | Forbidden | Insufficient permissions | Check user role and notebook access |
+| 404 | Not Found | Resource doesn't exist | Verify uid, nbid, or entry_id are correct |
+| 429 | Too Many Requests | Rate limit exceeded | Implement exponential backoff |
+| 500 | Internal Server Error | Server-side issue | Retry request or contact support |
+
+## Rate Limiting
+
+LabArchives implements rate limiting to ensure service stability:
+
+- **Recommended:** Maximum 60 requests per minute per API key
+- **Burst allowance:** Short bursts up to 100 requests may be tolerated
+- **Best practice:** Implement 1-2 second delays between requests for batch operations
+
+## API Versioning
+
+LabArchives API is backward compatible. New methods are added without breaking existing implementations. Monitor LabArchives announcements for new capabilities.
+
+## Support and Documentation
+
+For API access requests, technical questions, or feature requests:
+- Email: support@labarchives.com
+- Include your institution name and specific use case for faster assistance