Skill: aipoch-ai/clinicaltrials-gov-parser (version 0.1.0)

--- name: clinicaltrials-gov-parser description: 'Monitor and summarize competitor clinical trial status changes from ClinicalTrials.gov. Trigger: When user asks to track clinical trials, monitor trial status changes, get updates on specific trials, or analyze competitor trial activities. Use cases: Pharma competitive intelligence, trial monitoring, status tracking, recruitment updates, completion alerts. ' version: 1.0.0 category: Pharma tags: - pharma - clinical-trials - monitoring - api - competitive-intelligence author: AIPOCH license: MIT status: Draft risk_level: High skill_type: Hybrid (Tool/Script + Network/API) owner: AIPOCH reviewer: '' last_updated: '2026-02-06' --- # ClinicalTrials.gov Parser Monitor and summarize competitor clinical trial status changes from ClinicalTrials.gov. ## Use Cases - **Trial Monitoring**: Track status changes of specific clinical trials - **Competitive Intelligence**: Monitor competitor trial activities and milestones - **Recruitment Tracking**: Get updates on enrollment status - **Completion Alerts**: Monitor trial completion and results posting ## Parameters | Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | `--sponsor` | string | - | No | Trial sponsor name | | `--condition` | string | - | No | Medical condition/disease | | `--status` | string | - | No | Trial status (Recruiting, Completed, etc.) | | `--trials` | string | - | No | Comma-separated trial IDs (NCT numbers) | | `--output` | string | json | No | Output format (json, csv) | | `--days` | int | 30 | No | Number of days for monitoring | ## Usage ```python from scripts.main import ClinicalTrialsMonitor # Initialize monitor monitor = ClinicalTrialsMonitor() # Search for trials trials = monitor.search_trials( sponsor="Pfizer", condition="Diabetes", status="Recruiting" ) # Get trial details trial = monitor.get_trial("NCT05108922") # Check for status changes changes = monitor.check_status_changes(trial_ids=["NCT05108922"]) ``` ## CLI Usage ```bash # Search trials python scripts/main.py search --sponsor "Pfizer" --condition "Diabetes" # Get trial details python scripts/main.py get NCT05108922 # Monitor status changes python scripts/main.py monitor --trials NCT05108922,NCT05108923 --output json # Generate summary report python scripts/main.py report --sponsor "Pfizer" --days 30 ``` ## API Methods | Method | Description | |--------|-------------| | `search_trials()` | Search trials with filters | | `get_trial(nct_id)` | Get detailed trial information | | `check_status_changes()` | Check for status updates | | `get_recruitment_status()` | Get enrollment updates | | `generate_summary()` | Generate competitor summary | ## Technical Details - **API**: ClinicalTrials.gov API v2 - **Rate Limit**: 10 requests/second - **Data Format**: JSON - **Difficulty**: Medium ## References - See `references/api-docs.md` for API documentation - See `references/status-codes.md` for trial status definitions - See `references/examples.md` for usage examples ## Risk Assessment | Risk Indicator | Assessment | Level | |----------------|------------|-------| | Code Execution | Python scripts with tools | High | | Network Access | External API calls | High | | File System Access | Read/write data | Medium | | Instruction Tampering | Standard prompt guidelines | Low | | Data Exposure | Data handled securely | Medium | ## Security Checklist - [ ] No hardcoded credentials or API keys - [ ] No unauthorized file system access (../) - [ ] Output does not expose sensitive information - [ ] Prompt injection protections in place - [ ] API requests use HTTPS only - [ ] Input validated against allowed patterns - [ ] API timeout and retry mechanisms implemented - [ ] Output directory restricted to workspace - [ ] Script execution in sandboxed environment - [ ] Error messages sanitized (no internal paths exposed) - [ ] Dependencies audited - [ ] No exposure of internal service architecture ## Prerequisites ```bash # Python dependencies pip install -r requirements.txt ``` ## Evaluation Criteria ### Success Metrics - [ ] Successfully executes main functionality - [ ] Output meets quality standards - [ ] Handles edge cases gracefully - [ ] Performance is acceptable ### Test Cases 1. **Basic Functionality**: Standard input → Expected output 2. **Edge Case**: Invalid input → Graceful error handling 3. **Performance**: Large dataset → Acceptable processing time ## Lifecycle Status - **Current Stage**: Draft - **Next Review Date**: 2026-03-06 - **Known Issues**: None - **Planned Improvements**: - Performance optimization - Additional feature support

path: references/api-docs.md
content: # ClinicalTrials.gov API v2 Documentation

## Overview

The ClinicalTrials.gov API v2 provides programmatic access to the ClinicalTrials.gov database containing registry and results information for clinical trials.

- **Base URL**: `https://clinicaltrials.gov/api/v2`
- **Documentation**: https://clinicaltrials.gov/data-api/api
- **Rate Limit**: 10 requests per second

## Authentication

No API key required. The API is publicly accessible.

## Key Endpoints

### Search Studies
```
GET /studies
```

Query Parameters:
- `pageSize`: Number of results (1-1000)
- `query.term`: Free text search
- `filter`: Structured filters

Filter Options:
- `sponsor:SponsorName` - Filter by sponsor
- `condition:ConditionName` - Filter by condition
- `overallStatus:STATUS` - Filter by status
- `phase:PHASE` - Filter by phase

### Get Study Details
```
GET /studies/{nctId}
```

Returns full protocol and results sections for a specific trial.

## Response Structure

### Study Object
```json
{
  "protocolSection": {
    "identificationModule": {
      "nctId": "NCT05108922",
      "briefTitle": "Study Title",
      "officialTitle": "Official Study Title"
    },
    "statusModule": {
      "overallStatus": "RECRUITING",
      "startDateStruct": {"date": "2022-01-15"},
      "completionDateStruct": {"date": "2024-12-31"},
      "statusVerifiedDate": "2024-01-15"
    },
    "sponsorCollaboratorsModule": {
      "leadSponsor": {"name": "Pfizer"}
    },
    "conditionsModule": {
      "conditions": ["Diabetes Mellitus", "Type 2"]
    },
    "designModule": {
      "phases": ["PHASE2", "PHASE3"],
      "enrollmentInfo": {"count": 500}
    }
  }
}
```

## Rate Limiting

- Maximum: 10 requests per second
- Recommended delay: 100-150ms between requests
- Exceeding limits returns HTTP 429

## Error Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 400 | Bad Request |
| 404 | Study not found |
| 429 | Rate limit exceeded |
| 500 | Server error |


path: references/examples.md
content: # ClinicalTrials.gov Parser - Usage Examples

## Example 1: Monitor Competitor Trials

```python
from scripts.main import ClinicalTrialsMonitor

monitor = ClinicalTrialsMonitor()

# Find all Pfizer diabetes trials
pfizer_trials = monitor.search_trials(
    sponsor="Pfizer",
    condition="Diabetes",
    limit=50
)

print(f"Found {len(pfizer_trials)} Pfizer diabetes trials")

# Extract NCT IDs for monitoring
nct_ids = [t.nct_id for t in pfizer_trials]

# Check for recent status changes
changes = monitor.check_status_changes(nct_ids, days=7)
for change in changes:
    print(f"{change['nct_id']}: {change['status']}")
```

## Example 2: Track Recruitment Status

```python
# Monitor enrollment progress
for nct_id in ["NCT05108922", "NCT05108923"]:
    recruitment = monitor.get_recruitment_status(nct_id)
    if recruitment:
        print(f"{recruitment['nct_id']}: {recruitment['enrollment_count']} enrolled")
```

## Example 3: Generate Weekly Report

```python
# Weekly competitive intelligence report
report = monitor.generate_summary(
    sponsor="Novartis",
    days=7
)

print(f"Total trials: {report['total_trials']}")
print(f"Recent updates: {report['recent_update_count']}")

# Status breakdown
for status, count in report['status_breakdown'].items():
    print(f"  {status}: {count}")
```

## Example 4: CLI Usage

### Search by sponsor
```bash
python scripts/main.py search --sponsor "Pfizer" --limit 20
```

### Get specific trial
```bash
python scripts/main.py get NCT05108922
```

### Monitor multiple trials
```bash
python scripts/main.py monitor --trials "NCT05108922,NCT05108923" --days 7
```

### Generate JSON report
```bash
python scripts/main.py report --sponsor "Pfizer" --days 30 --output json
```

## Example 5: Batch Processing

```python
# Monitor multiple sponsors
sponsors = ["Pfizer", "Novartis", "Roche"]
all_trials = []

for sponsor in sponsors:
    trials = monitor.search_trials(sponsor=sponsor, limit=100)
    all_trials.extend(trials)

# Find recruiting phase 3 trials
phase3_recruiting = [
    t for t in all_trials 
    if t.status == "RECRUITING" and t.phase == "PHASE3"
]

print(f"Phase 3 recruiting trials: {len(phase3_recruiting)}")
```


path: references/status-codes.md
content: # Clinical Trial Status Codes

## Overall Status Values

| Status | Description |
|--------|-------------|
| `RECRUITING` | Actively enrolling participants |
| `ACTIVE_NOT_RECRUITING` | Ongoing but not recruiting |
| `NOT_YET_RECRUITING` | Not yet open for recruitment |
| `COMPLETED` | Study completed normally |
| `SUSPENDED` | Temporarily halted |
| `TERMINATED` | Prematurely ended |
| `WITHDRAWN` | Withdrawn before enrollment |
| `WITHHELD` | Withheld from public view |
| `UNKNOWN` | Status unknown |

## Phase Values

| Phase | Description |
|-------|-------------|
| `EARLY_PHASE1` | Early Phase 1 (exploratory) |
| `PHASE1` | Phase 1 (safety/dosage) |
| `PHASE2` | Phase 2 (efficacy) |
| `PHASE3` | Phase 3 (efficacy/monitoring) |
| `PHASE4` | Phase 4 (post-marketing) |

## Why Status Changes

### Common Status Transitions

1. `NOT_YET_RECRUITING` → `RECRUITING`
   - Study opens for enrollment

2. `RECRUITING` → `ACTIVE_NOT_RECRUITING`
   - Enrollment target reached

3. `RECRUITING` → `SUSPENDED`
   - Temporary hold (safety, administrative)

4. `RECRUITING`/`ACTIVE_NOT_RECRUITING` → `COMPLETED`
   - Study finished successfully

5. `RECRUITING` → `TERMINATED`
   - Early termination (futility, safety, business)

## Monitoring Priority

### High Priority Changes
- RECRUITING → SUSPENDED (safety concern)
- RECRUITING → TERMINATED (competitive impact)
- ACTIVE_NOT_RECRUITING → COMPLETED (results coming)

### Medium Priority Changes
- NOT_YET_RECRUITING → RECRUITING (new competition)
- Phase advancement (PHASE1 → PHASE2)

### Low Priority Changes
- WITHDRAWN (no competitive impact)
- Date updates without status change


path: requirements.txt
content: dataclasses
requests


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)