{
  "skill": "alterlab-clinicaltrials",
  "evals": [
    {
      "id": "recruiting-by-condition",
      "prompt": "Find me currently recruiting trials for type 2 diabetes, sorted by most recently updated — I want the NCT IDs and titles.",
      "expected_output": "Triggers the ClinicalTrials.gov skill. Calls search_studies with condition='type 2 diabetes' and status='RECRUITING' (filter.overallStatus / query.cond) via API v2, sorting by LastUpdatePostDate:desc, and extracts nctId plus briefTitle from each study's protocolSection.identificationModule.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "RECRUITING" },
        { "type": "behavior", "value": "Searches ClinicalTrials.gov API v2 by condition with a recruiting status filter and returns NCT IDs and titles." }
      ]
    },
    {
      "id": "trial-detail-by-nct",
      "prompt": "Give me the eligibility criteria and recruitment status for trial NCT04852770.",
      "expected_output": "Triggers the ClinicalTrials.gov skill. Calls get_study_details('NCT04852770') against the API v2 studies/{nctId} endpoint and reads eligibilityModule (minimumAge, maximumAge, sex, eligibilityCriteria) and statusModule.overallStatus. Treats NCT04852770 as a trial identifier.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "NCT04852770" },
        { "type": "behavior", "value": "Retrieves a single trial by NCT ID and extracts eligibility and status from the protocolSection modules." }
      ]
    },
    {
      "id": "phase-intervention-geo-filter",
      "prompt": "I'm looking for Phase 2 or 3 immunotherapy trials for lung cancer in California that are recruiting or not yet recruiting.",
      "expected_output": "Triggers the ClinicalTrials.gov skill. Runs a combined search_studies with condition='lung cancer', intervention='immunotherapy' (query.intr), location='California' (query.locn), and status in [RECRUITING, NOT_YET_RECRUITING], then filters results on designModule.phases for PHASE2/PHASE3.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Combines condition, intervention, location, and status filters and post-filters by trial phase." }
      ]
    },
    {
      "id": "sponsor-portfolio",
      "prompt": "List the trials sponsored by the National Cancer Institute and show their lead sponsor and collaborators.",
      "expected_output": "Triggers the ClinicalTrials.gov skill. Calls search_studies with sponsor='National Cancer Institute' (query.spons) and reads sponsorCollaboratorsModule.leadSponsor.name and collaborators for each study.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Searches trials by sponsor organization and extracts lead sponsor and collaborator names." }
      ]
    },
    {
      "id": "near-miss-pubmed",
      "prompt": "Find me published journal articles reporting the results of pembrolizumab trials in melanoma — I want the peer-reviewed papers with abstracts.",
      "expected_output": "Should NOT trigger the ClinicalTrials.gov skill. The user wants published, peer-reviewed journal articles (results papers with abstracts), not registry trial records. This should defer to the pubmed database skill (alterlab-pubmed) for indexed literature.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "pubmed" }
      ]
    },
    {
      "id": "near-miss-drugbank",
      "prompt": "What is the mechanism of action of pembrolizumab and which drugs does it interact with?",
      "expected_output": "Should NOT trigger the ClinicalTrials.gov skill. This asks for drug pharmacology (mechanism of action) and drug-drug interactions, not clinical trial records. It should defer to the drugbank database skill (alterlab-drugbank) for mechanism and interaction data.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "drugbank" }
      ]
    }
  ]
}

# 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` |
| `aggFilters` | string | Faceted filtering, incl. phase. Values within a facet are space-separated | `phase:2 3`, `results:with` |
| `filter.advanced` | string | Essie-syntax advanced query (supports AREA[...] and OR/AND) | `AREA[Phase](PHASE2 OR PHASE3)` |
| `sort` | string | Result ordering | `LastUpdatePostDate:desc` |
| `pageSize` | integer | Results per page (max 1000) | `100` |
| `pageToken` | string | Pagination cursor — pass back the `nextPageToken` from the previous response | `<token>` |
| `countTotal` | boolean | Include `totalCount` in the response (omitted by default) | `true` |
| `format` | string | Response format (`json` or `csv`) | `json` |

> **There is no `filter.phase` parameter** — it returns HTTP 400. Filter phases
> via `aggFilters=phase:N` (N = 0–4) or `filter.advanced=AREA[Phase]...`. Phases
> can also be post-filtered client-side on `designModule.phases`.

**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&countTotal=true&format=json"
```

**Example Response Structure:**
```json
{
  "totalCount": 1234,
  "studies": [
    {
      "protocolSection": { ... },
      "derivedSection": { ... },
      "hasResults": false
    }
  ],
  "nextPageToken": "next_page_token_here"
}
```

> `totalCount` appears only when the request includes `countTotal=true`. The
> pagination cursor is named `nextPageToken` in the response; feed it back into
> the request as the `pageToken` parameter to fetch the next page. When there are
> no further pages, `nextPageToken` is absent.

### 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",
    "countTotal": "true"  # needed for data['totalCount']
}

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",
    "aggFilters": "phase:3",  # NOT filter.phase (that returns HTTP 400)
    "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. The response field is 'nextPageToken';
    # it is passed back in as the 'pageToken' request parameter (above).
    page_token = data.get('nextPageToken')
    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

#!/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


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,
    count_total: bool = True,
    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 (use 'nextPageToken' from a prior response)
        count_total: Request totalCount in the response (API omits it unless
                     countTotal=true). Ignored for CSV format.
        format: Response format ("json" or "csv")

    Returns:
        Dictionary containing search results with studies and metadata.
        When count_total is True, the JSON response includes 'totalCount'.
        The pagination token, when present, is returned as 'nextPageToken'.
    """
    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

    # totalCount is omitted unless explicitly requested (JSON only)
    if count_total and format == "json":
        params['countTotal'] = 'true'

    # 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,
            count_total=False  # Not needed while paging; saves work server-side
        )

        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 (the API returns 'nextPageToken', not 'pageToken')
        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))