@synsci/cli-darwin-x64 1.1.77 → 1.1.78

package/bin/skills/clinicaltrials-database/references/api_reference.md

@@ -0,0 +1,358 @@
+# ClinicalTrials.gov API v2 Reference Documentation
+
+## Overview
+
+The ClinicalTrials.gov API v2 is a modern REST API that provides programmatic access to the ClinicalTrials.gov database, which contains information about clinical studies conducted around the world. The API follows the OpenAPI Specification 3.0 and provides both JSON and CSV response formats.
+
+**Base URL:** `https://clinicaltrials.gov/api/v2`
+
+**API Version:** 2.0 (released March 2024, replacing the classic API)
+
+## Authentication & Rate Limits
+
+- **Authentication:** Not required (public API)
+- **Rate Limit:** Approximately 50 requests per minute per IP address
+- **Response Formats:** JSON (default) or CSV
+- **Standards:** Uses ISO 8601 for dates, CommonMark Markdown for rich text
+
+## Core Endpoints
+
+### 1. Search Studies
+
+**Endpoint:** `GET /api/v2/studies`
+
+Search for clinical trials using various query parameters and filters.
+
+**Query Parameters:**
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `query.cond` | string | Disease or condition search | `lung cancer`, `diabetes` |
+| `query.intr` | string | Treatment or intervention search | `Pembrolizumab`, `exercise` |
+| `query.locn` | string | Geographic location filtering | `New York`, `California, USA` |
+| `query.spons` | string | Sponsor or collaborator name | `National Cancer Institute` |
+| `query.term` | string | General full-text search | `breast cancer treatment` |
+| `filter.overallStatus` | string | Status-based filtering (comma-separated) | `RECRUITING,NOT_YET_RECRUITING` |
+| `filter.ids` | string | NCT ID intersection filtering (comma-separated) | `NCT04852770,NCT01728545` |
+| `filter.phase` | string | Study phase filtering | `PHASE1,PHASE2` |
+| `sort` | string | Result ordering | `LastUpdatePostDate:desc` |
+| `pageSize` | integer | Results per page (max 1000) | `100` |
+| `pageToken` | string | Pagination token from previous response | `<token>` |
+| `format` | string | Response format (`json` or `csv`) | `json` |
+
+**Valid Status Values:**
+- `RECRUITING` - Currently recruiting participants
+- `NOT_YET_RECRUITING` - Not yet open for recruitment
+- `ENROLLING_BY_INVITATION` - Only enrolling by invitation
+- `ACTIVE_NOT_RECRUITING` - Active but no longer recruiting
+- `SUSPENDED` - Temporarily halted
+- `TERMINATED` - Stopped prematurely
+- `COMPLETED` - Study has concluded
+- `WITHDRAWN` - Withdrawn prior to enrollment
+
+**Valid Phase Values:**
+- `EARLY_PHASE1` - Early Phase 1 (formerly Phase 0)
+- `PHASE1` - Phase 1
+- `PHASE2` - Phase 2
+- `PHASE3` - Phase 3
+- `PHASE4` - Phase 4
+- `NA` - Not Applicable
+
+**Sort Options:**
+- `LastUpdatePostDate:asc` / `LastUpdatePostDate:desc` - Sort by last update date
+- `EnrollmentCount:asc` / `EnrollmentCount:desc` - Sort by enrollment count
+- `StartDate:asc` / `StartDate:desc` - Sort by start date
+- `StudyFirstPostDate:asc` / `StudyFirstPostDate:desc` - Sort by first posted date
+
+**Example Request:**
+```bash
+curl "https://clinicaltrials.gov/api/v2/studies?query.cond=lung+cancer&filter.overallStatus=RECRUITING&pageSize=10&format=json"
+```
+
+**Example Response Structure:**
+```json
+{
+  "studies": [
+    {
+      "protocolSection": { ... },
+      "derivedSection": { ... },
+      "hasResults": false
+    }
+  ],
+  "totalCount": 1234,
+  "pageToken": "next_page_token_here"
+}
+```
+
+### 2. Get Study Details
+
+**Endpoint:** `GET /api/v2/studies/{NCT_ID}`
+
+Retrieve comprehensive information about a specific clinical trial.
+
+**Path Parameters:**
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `NCT_ID` | string | The unique NCT identifier | `NCT04852770` |
+
+**Query Parameters:**
+
+| Parameter | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `format` | string | Response format (`json` or `csv`) | `json` |
+
+**Example Request:**
+```bash
+curl "https://clinicaltrials.gov/api/v2/studies/NCT04852770?format=json"
+```
+
+## Response Data Structure
+
+The API returns study data organized into hierarchical modules. Key sections include:
+
+### protocolSection
+
+Core study information and design:
+
+- **identificationModule** - NCT ID, official title, brief title, organization
+- **statusModule** - Overall status, start date, completion date, last update
+- **sponsorCollaboratorsModule** - Lead sponsor, collaborators, responsible party
+- **descriptionModule** - Brief summary, detailed description
+- **conditionsModule** - Conditions being studied
+- **designModule** - Study type, phases, enrollment info, design details
+- **armsInterventionsModule** - Study arms and interventions
+- **outcomesModule** - Primary and secondary outcomes
+- **eligibilityModule** - Inclusion/exclusion criteria, age/sex requirements
+- **contactsLocationsModule** - Overall contacts, study locations
+- **referencesModule** - References, links, citations
+
+### derivedSection
+
+Computed/derived information:
+
+- **miscInfoModule** - Version holder, removed countries
+- **conditionBrowseModule** - Condition mesh terms
+- **interventionBrowseModule** - Intervention mesh terms
+
+### resultsSection
+
+Study results (when available):
+
+- **participantFlowModule** - Participant flow through study
+- **baselineCharacteristicsModule** - Baseline participant characteristics
+- **outcomeMeasuresModule** - Outcome measure results
+- **adverseEventsModule** - Adverse events data
+
+### hasResults
+
+Boolean indicating if results are available for the study.
+
+## Common Use Cases
+
+### Use Case 1: Find Recruiting Trials for a Condition
+
+Search for trials currently recruiting participants for a specific disease or condition:
+
+```python
+import requests
+
+url = "https://clinicaltrials.gov/api/v2/studies"
+params = {
+    "query.cond": "breast cancer",
+    "filter.overallStatus": "RECRUITING",
+    "pageSize": 20,
+    "sort": "LastUpdatePostDate:desc"
+}
+
+response = requests.get(url, params=params)
+data = response.json()
+
+print(f"Found {data['totalCount']} recruiting breast cancer trials")
+for study in data['studies']:
+    nct_id = study['protocolSection']['identificationModule']['nctId']
+    title = study['protocolSection']['identificationModule']['briefTitle']
+    print(f"{nct_id}: {title}")
+```
+
+### Use Case 2: Search by Intervention/Drug
+
+Find trials testing a specific intervention or drug:
+
+```python
+params = {
+    "query.intr": "Pembrolizumab",
+    "filter.phase": "PHASE3",
+    "pageSize": 50
+}
+
+response = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params)
+```
+
+### Use Case 3: Geographic Search
+
+Find trials in a specific location:
+
+```python
+params = {
+    "query.cond": "diabetes",
+    "query.locn": "Boston, Massachusetts",
+    "filter.overallStatus": "RECRUITING"
+}
+
+response = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params)
+```
+
+### Use Case 4: Retrieve Full Study Details
+
+Get comprehensive information about a specific trial:
+
+```python
+nct_id = "NCT04852770"
+url = f"https://clinicaltrials.gov/api/v2/studies/{nct_id}"
+
+response = requests.get(url)
+study = response.json()
+
+# Access specific information
+eligibility = study['protocolSection']['eligibilityModule']
+contacts = study['protocolSection']['contactsLocationsModule']
+```
+
+### Use Case 5: Pagination Through Results
+
+Handle large result sets with pagination:
+
+```python
+all_studies = []
+page_token = None
+
+while True:
+    params = {
+        "query.cond": "cancer",
+        "pageSize": 1000
+    }
+    if page_token:
+        params['pageToken'] = page_token
+
+    response = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params)
+    data = response.json()
+
+    all_studies.extend(data['studies'])
+
+    # Check if there are more pages
+    page_token = data.get('pageToken')
+    if not page_token:
+        break
+
+print(f"Retrieved {len(all_studies)} total studies")
+```
+
+### Use Case 6: Export to CSV
+
+Retrieve data in CSV format for analysis:
+
+```python
+params = {
+    "query.cond": "alzheimer",
+    "format": "csv",
+    "pageSize": 100
+}
+
+response = requests.get("https://clinicaltrials.gov/api/v2/studies", params=params)
+csv_data = response.text
+
+# Save to file
+with open("alzheimer_trials.csv", "w") as f:
+    f.write(csv_data)
+```
+
+## Error Handling
+
+### Common HTTP Status Codes
+
+- **200 OK** - Request succeeded
+- **400 Bad Request** - Invalid parameters or malformed request
+- **404 Not Found** - NCT ID not found
+- **429 Too Many Requests** - Rate limit exceeded
+- **500 Internal Server Error** - Server error
+
+### Example Error Response
+
+```json
+{
+  "error": {
+    "code": 400,
+    "message": "Invalid parameter: filter.overallStatus must be one of: RECRUITING, NOT_YET_RECRUITING, ..."
+  }
+}
+```
+
+### Best Practices for Error Handling
+
+```python
+import requests
+import time
+
+def search_with_retry(params, max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = requests.get(
+                "https://clinicaltrials.gov/api/v2/studies",
+                params=params,
+                timeout=30
+            )
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 429:
+                # Rate limited - wait and retry
+                wait_time = 60  # Wait 1 minute
+                print(f"Rate limited. Waiting {wait_time} seconds...")
+                time.sleep(wait_time)
+            else:
+                raise
+        except requests.exceptions.RequestException as e:
+            if attempt == max_retries - 1:
+                raise
+            time.sleep(2 ** attempt)  # Exponential backoff
+
+    raise Exception("Max retries exceeded")
+```
+
+## Data Standards
+
+### Date Format
+
+All dates use ISO 8601 format with structured objects:
+
+```json
+"lastUpdatePostDateStruct": {
+  "date": "2024-03-15",
+  "type": "ACTUAL"
+}
+```
+
+### Rich Text
+
+Descriptive text fields use CommonMark Markdown format, allowing for structured formatting:
+
+```json
+"briefSummary": "This is a **Phase 2** study evaluating:\n\n- Safety\n- Efficacy\n- Tolerability"
+```
+
+### Enumerated Values
+
+Many fields use standardized enumerated values (e.g., study status, phase) rather than free-form text, improving data consistency and query reliability.
+
+## Migration from Classic API
+
+The API v2 replaced the classic API (retired June 2024). Key improvements:
+
+1. **Structured Data** - Enumerated values instead of free text
+2. **Modern Standards** - ISO 8601 dates, CommonMark markdown
+3. **Better Performance** - Optimized queries and pagination
+4. **OpenAPI Spec** - Standard API specification format
+5. **Consistent Fields** - Number fields properly typed
+
+For detailed migration guidance, see: https://clinicaltrials.gov/data-api/about-api/api-migration

package/bin/skills/clinicaltrials-database/scripts/query_clinicaltrials.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""
+ClinicalTrials.gov API Query Helper
+
+A comprehensive Python script for querying the ClinicalTrials.gov API v2.
+Provides convenient functions for common query patterns including searching
+by condition, intervention, location, sponsor, and retrieving specific trials.
+
+API Documentation: https://clinicaltrials.gov/data-api/api
+Rate Limit: ~50 requests per minute per IP address
+"""
+
+import requests
+import json
+from typing import Dict, List, Optional, Union
+from urllib.parse import urlencode
+
+
+BASE_URL = "https://clinicaltrials.gov/api/v2"
+
+
+def search_studies(
+    condition: Optional[str] = None,
+    intervention: Optional[str] = None,
+    location: Optional[str] = None,
+    sponsor: Optional[str] = None,
+    status: Optional[Union[str, List[str]]] = None,
+    nct_ids: Optional[List[str]] = None,
+    sort: str = "LastUpdatePostDate:desc",
+    page_size: int = 10,
+    page_token: Optional[str] = None,
+    format: str = "json"
+) -> Dict:
+    """
+    Search for clinical trials using various filters.
+
+    Args:
+        condition: Disease or condition (e.g., "lung cancer", "diabetes")
+        intervention: Treatment or intervention (e.g., "Pembrolizumab", "exercise")
+        location: Geographic location (e.g., "New York", "California")
+        sponsor: Sponsor or collaborator name (e.g., "National Cancer Institute")
+        status: Study status(es). Can be string or list. Valid values:
+                RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION,
+                ACTIVE_NOT_RECRUITING, SUSPENDED, TERMINATED, COMPLETED, WITHDRAWN
+        nct_ids: List of NCT IDs to filter by
+        sort: Sort order (e.g., "LastUpdatePostDate:desc", "EnrollmentCount:desc")
+        page_size: Number of results per page (default: 10, max: 1000)
+        page_token: Token for pagination (returned from previous query)
+        format: Response format ("json" or "csv")
+
+    Returns:
+        Dictionary containing search results with studies and metadata
+    """
+    params = {}
+
+    # Build query parameters
+    if condition:
+        params['query.cond'] = condition
+    if intervention:
+        params['query.intr'] = intervention
+    if location:
+        params['query.locn'] = location
+    if sponsor:
+        params['query.spons'] = sponsor
+
+    # Handle status filter (can be list or string)
+    if status:
+        if isinstance(status, list):
+            params['filter.overallStatus'] = ','.join(status)
+        else:
+            params['filter.overallStatus'] = status
+
+    # Handle NCT IDs filter
+    if nct_ids:
+        params['filter.ids'] = ','.join(nct_ids)
+
+    # Add pagination and sorting
+    params['sort'] = sort
+    params['pageSize'] = page_size
+    if page_token:
+        params['pageToken'] = page_token
+
+    # Set format
+    params['format'] = format
+
+    url = f"{BASE_URL}/studies"
+    response = requests.get(url, params=params)
+    response.raise_for_status()
+
+    if format == "json":
+        return response.json()
+    else:
+        return response.text
+
+
+def get_study_details(nct_id: str, format: str = "json") -> Dict:
+    """
+    Retrieve detailed information about a specific clinical trial.
+
+    Args:
+        nct_id: The NCT ID of the trial (e.g., "NCT04852770")
+        format: Response format ("json" or "csv")
+
+    Returns:
+        Dictionary containing comprehensive study information
+    """
+    params = {'format': format}
+    url = f"{BASE_URL}/studies/{nct_id}"
+
+    response = requests.get(url, params=params)
+    response.raise_for_status()
+
+    if format == "json":
+        return response.json()
+    else:
+        return response.text
+
+
+def search_with_all_results(
+    condition: Optional[str] = None,
+    intervention: Optional[str] = None,
+    location: Optional[str] = None,
+    sponsor: Optional[str] = None,
+    status: Optional[Union[str, List[str]]] = None,
+    max_results: Optional[int] = None
+) -> List[Dict]:
+    """
+    Search for clinical trials and automatically paginate through all results.
+
+    Args:
+        condition: Disease or condition to search for
+        intervention: Treatment or intervention to search for
+        location: Geographic location to search in
+        sponsor: Sponsor or collaborator name
+        status: Study status(es) to filter by
+        max_results: Maximum number of results to retrieve (None for all)
+
+    Returns:
+        List of all matching studies
+    """
+    all_studies = []
+    page_token = None
+
+    while True:
+        result = search_studies(
+            condition=condition,
+            intervention=intervention,
+            location=location,
+            sponsor=sponsor,
+            status=status,
+            page_size=1000,  # Use max page size for efficiency
+            page_token=page_token
+        )
+
+        studies = result.get('studies', [])
+        all_studies.extend(studies)
+
+        # Check if we've reached the max or there are no more results
+        if max_results and len(all_studies) >= max_results:
+            return all_studies[:max_results]
+
+        # Check for next page
+        page_token = result.get('nextPageToken')
+        if not page_token:
+            break
+
+    return all_studies
+
+
+def extract_study_summary(study: Dict) -> Dict:
+    """
+    Extract key information from a study for quick overview.
+
+    Args:
+        study: A study dictionary from the API response
+
+    Returns:
+        Dictionary with essential study information
+    """
+    protocol = study.get('protocolSection', {})
+    identification = protocol.get('identificationModule', {})
+    status_module = protocol.get('statusModule', {})
+    description = protocol.get('descriptionModule', {})
+
+    return {
+        'nct_id': identification.get('nctId'),
+        'title': identification.get('officialTitle') or identification.get('briefTitle'),
+        'status': status_module.get('overallStatus'),
+        'phase': protocol.get('designModule', {}).get('phases', []),
+        'enrollment': protocol.get('designModule', {}).get('enrollmentInfo', {}).get('count'),
+        'brief_summary': description.get('briefSummary'),
+        'last_update': status_module.get('lastUpdatePostDateStruct', {}).get('date')
+    }
+
+
+# Example usage
+if __name__ == "__main__":
+    # Example 1: Search for recruiting lung cancer trials
+    print("Example 1: Searching for recruiting lung cancer trials...")
+    results = search_studies(
+        condition="lung cancer",
+        status="RECRUITING",
+        page_size=5
+    )
+    print(f"Found {results.get('totalCount', 0)} total trials")
+    print(f"Showing first {len(results.get('studies', []))} trials\n")
+
+    # Example 2: Get details for a specific trial
+    if results.get('studies'):
+        first_study = results['studies'][0]
+        nct_id = first_study['protocolSection']['identificationModule']['nctId']
+        print(f"Example 2: Getting details for {nct_id}...")
+        details = get_study_details(nct_id)
+        summary = extract_study_summary(details)
+        print(json.dumps(summary, indent=2))