{
  "skill": "alterlab-chembl",
  "evals": [
    {
      "id": "target-inhibitors-ic50",
      "prompt": "Find me potent EGFR inhibitors from ChEMBL — I want compounds with an IC50 of 100 nM or lower against the EGFR target.",
      "expected_output": "Invokes alterlab-chembl. Resolves EGFR to its target ChEMBL ID (CHEMBL203) via new_client.target, then queries new_client.activity filtered by target_chembl_id, standard_type='IC50', standard_value__lte=100, standard_units='nM', and returns the matching molecule_chembl_ids with their potencies.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "IC50" },
        { "type": "behavior", "value": "Uses the ChEMBL Python client (new_client) to map the target then filter activities by IC50 threshold and units." }
      ]
    },
    {
      "id": "similarity-search",
      "prompt": "I have the SMILES for aspirin (CC(=O)Oc1ccccc1C(=O)O). Search ChEMBL for compounds that are at least 85% structurally similar.",
      "expected_output": "Invokes alterlab-chembl. Uses new_client.similarity.filter with the supplied SMILES and a similarity=85 threshold to return structurally related ChEMBL compounds.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Runs a structure similarity search against ChEMBL using the SMILES and a percent-similarity threshold." }
      ]
    },
    {
      "id": "drug-mechanism-indications",
      "prompt": "Look up the approved drug with ChEMBL ID CHEMBL25 — I want its mechanism of action and the disease indications it's used for.",
      "expected_output": "Invokes alterlab-chembl. Retrieves drug data via new_client.drug, mechanisms via new_client.mechanism.filter(molecule_chembl_id='CHEMBL25'), and indications via new_client.drug_indication.filter, summarizing how the drug works and what it treats.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Queries the ChEMBL mechanism and drug_indication endpoints for the given ChEMBL ID." }
      ]
    },
    {
      "id": "property-virtual-screen",
      "prompt": "Pull drug-like small molecules from ChEMBL for a virtual screen: molecular weight between 300 and 500, ALogP at or below 5, no more than 10 H-bond acceptors and 5 donors.",
      "expected_output": "Invokes alterlab-chembl. Uses new_client.molecule.filter on molecule_properties (mw_freebase__range, alogp__lte, hba__lte, hbd__lte) to return compounds matching the Lipinski-style property window for virtual screening.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Filters ChEMBL molecules by physicochemical properties (MW, ALogP, HBA, HBD) for a property-based screen." }
      ]
    },
    {
      "id": "near-miss-bindingdb",
      "prompt": "I need the measured binding affinity (Kd, Ki) data points for the BRD4 bromodomain from BindingDB specifically — the curated binding measurements, not ChEMBL bioactivities.",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-bindingdb. The user explicitly wants measured binding affinities from BindingDB; per this skill's own description, for measured binding affinities prefer bindingdb.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-bindingdb" }
      ]
    },
    {
      "id": "near-miss-pubchem",
      "prompt": "Give me the canonical SMILES, InChIKey, and basic physical properties for PubChem CID 2244.",
      "expected_output": "Does NOT invoke this skill; defers to alterlab-pubchem. The user is querying a PubChem compound by CID for chemical identifiers and properties, not mining ChEMBL bioactivity or drug-target data.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-pubchem" }
      ]
    }
  ]
}

# ChEMBL Web Services API Reference

## Overview

ChEMBL is a manually curated database of bioactive molecules with drug-like properties maintained by the European Bioinformatics Institute (EBI). It contains information about compounds, targets, assays, bioactivity data, and approved drugs.

The ChEMBL database contains:
- Over 2 million compound records
- Over 1.4 million assay records
- Over 19 million activity values
- Information on 13,000+ drug targets
- Data on 16,000+ approved drugs and clinical candidates

## Python Client Installation

```bash
uv pip install chembl_webresource_client
```

## Key Resources and Endpoints

ChEMBL provides access to 30+ specialized endpoints:

### Core Data Types

- **molecule** - Compound structures, properties, and synonyms
- **target** - Protein and non-protein biological targets
- **activity** - Bioassay measurement results
- **assay** - Experimental assay details
- **drug** - Approved pharmaceutical information
- **mechanism** - Drug mechanism of action data
- **document** - Literature sources and references
- **cell_line** - Cell line information
- **tissue** - Tissue types
- **protein_class** - Protein classification
- **target_component** - Target component details
- **compound_structural_alert** - Structural alerts for toxicity

## Query Patterns and Filters

### Filter Operators

The API supports Django-style filter operators:

- `__exact` - Exact match
- `__iexact` - Case-insensitive exact match
- `__contains` - Contains substring
- `__icontains` - Case-insensitive contains
- `__startswith` - Starts with prefix
- `__endswith` - Ends with suffix
- `__gt` - Greater than
- `__gte` - Greater than or equal
- `__lt` - Less than
- `__lte` - Less than or equal
- `__range` - Value in range
- `__in` - Value in list
- `__isnull` - Is null/not null
- `__regex` - Regular expression match
- `__search` - Full text search

### Example Filter Queries

**Molecular weight filtering:**
```python
molecules.filter(molecule_properties__mw_freebase__lte=300)
```

**Name pattern matching:**
```python
molecules.filter(pref_name__endswith='nib')
```

**Multiple conditions:**
```python
molecules.filter(
    molecule_properties__mw_freebase__lte=300,
    pref_name__endswith='nib'
)
```

## Chemical Structure Searches

### Substructure Search
Search for compounds containing a specific substructure using SMILES:

```python
from chembl_webresource_client.new_client import new_client
substructure = new_client.substructure
# Substructure search takes a SMILES/SMARTS pattern, NOT a similarity threshold
results = substructure.filter(smiles='c1ccccc1')
```

### Similarity Search
Find compounds similar to a query structure:

```python
similarity = new_client.similarity
results = similarity.filter(smiles='CC(=O)Oc1ccccc1C(=O)O', similarity=85)
```

## Common Data Retrieval Patterns

### Get Molecule by ChEMBL ID
```python
molecule = new_client.molecule.get('CHEMBL25')
```

### Get Target Information
```python
target = new_client.target.get('CHEMBL240')
```

### Get Activity Data
```python
activities = new_client.activity.filter(
    target_chembl_id='CHEMBL240',
    standard_type='IC50',
    standard_value__lte=100
)
```

### Get Drug Information
```python
drug = new_client.drug.get('CHEMBL1234')
```

## Response Formats

The API supports multiple response formats:
- JSON (default)
- XML
- YAML

## Caching and Performance

The Python client automatically caches results locally:
- **Default cache duration**: 24 hours
- **Cache location**: Local file system
- **Lazy evaluation**: Queries execute only when data is accessed

### Configuration Settings

```python
from chembl_webresource_client.settings import Settings

# Disable caching
Settings.Instance().CACHING = False

# Adjust cache expiration (in seconds)
Settings.Instance().CACHE_EXPIRE = 86400  # 24 hours

# Set timeout
Settings.Instance().TIMEOUT = 30

# Set retries
Settings.Instance().TOTAL_RETRIES = 3
```

## Molecular Properties

Common molecular properties available:

- `mw_freebase` - Molecular weight
- `alogp` - Calculated LogP
- `hba` - Hydrogen bond acceptors
- `hbd` - Hydrogen bond donors
- `psa` - Polar surface area
- `rtb` - Rotatable bonds
- `ro3_pass` - Rule of 3 compliance
- `num_ro5_violations` - Lipinski rule of 5 violations
- `cx_most_apka` - Most acidic pKa
- `cx_most_bpka` - Most basic pKa
- `molecular_species` - Molecular species
- `full_mwt` - Full molecular weight

## Bioactivity Data Fields

Key bioactivity fields:

- `standard_type` - Activity type (IC50, Ki, Kd, EC50, etc.)
- `standard_value` - Numerical activity value
- `standard_units` - Units (nM, uM, etc.)
- `pchembl_value` - Normalized activity value (-log scale)
- `activity_comment` - Activity annotations
- `data_validity_comment` - Data validity flags
- `potential_duplicate` - Duplicate flag

## Target Information Fields

Target data includes:

- `target_chembl_id` - ChEMBL target identifier
- `pref_name` - Preferred target name
- `target_type` - Type (PROTEIN, ORGANISM, etc.)
- `organism` - Target organism
- `tax_id` - NCBI taxonomy ID
- `target_components` - Component details

## Advanced Query Examples

### Find Kinase Inhibitors
```python
# Get kinase targets
targets = new_client.target.filter(
    target_type='SINGLE PROTEIN',
    pref_name__icontains='kinase'
)

# Get activities for these targets
activities = new_client.activity.filter(
    target_chembl_id__in=[t['target_chembl_id'] for t in targets],
    standard_type='IC50',
    standard_value__lte=100
)
```

### Retrieve Drug Mechanisms
```python
mechanisms = new_client.mechanism.filter(
    molecule_chembl_id='CHEMBL25'
)
```

### Get Compound Bioactivities
```python
activities = new_client.activity.filter(
    molecule_chembl_id='CHEMBL25',
    pchembl_value__isnull=False
)
```

## Image Generation

ChEMBL can generate SVG images of molecular structures:

```python
from chembl_webresource_client.new_client import new_client
image = new_client.image
svg = image.get('CHEMBL25')
```

## Pagination

Results are paginated automatically. To iterate through all results:

```python
activities = new_client.activity.filter(target_chembl_id='CHEMBL240')
for activity in activities:
    print(activity)
```

## Error Handling

Common errors:
- **404**: Resource not found
- **503**: Service temporarily unavailable
- **Timeout**: Request took too long

The client automatically retries failed requests based on `TOTAL_RETRIES` setting.

## Rate Limiting

ChEMBL has fair usage policies:
- Be respectful with query frequency
- Use caching to minimize repeated requests
- Consider bulk downloads for large datasets

## Additional Resources

- Official API documentation: https://www.ebi.ac.uk/chembl/api/data/docs
- Python client GitHub: https://github.com/chembl/chembl_webresource_client
- ChEMBL interface docs: https://chembl.gitbook.io/chembl-interface-documentation/
- Example notebooks: https://github.com/chembl/notebooks

#!/usr/bin/env python3
"""
ChEMBL Database Query Examples

This script demonstrates common query patterns for the ChEMBL database
using the chembl_webresource_client Python library.

Requirements:
    uv pip install chembl_webresource_client
    uv pip install pandas  # optional, for data manipulation
"""

from chembl_webresource_client.new_client import new_client


def get_molecule_info(chembl_id):
    """
    Retrieve detailed information about a molecule by ChEMBL ID.

    Args:
        chembl_id: ChEMBL identifier (e.g., 'CHEMBL25')

    Returns:
        Dictionary containing molecule information
    """
    molecule = new_client.molecule
    return molecule.get(chembl_id)


def search_molecules_by_name(name_pattern):
    """
    Search for molecules by name pattern.

    Args:
        name_pattern: Name or pattern to search for

    Returns:
        List of matching molecules
    """
    molecule = new_client.molecule
    results = molecule.filter(pref_name__icontains=name_pattern)
    return list(results)


def find_molecules_by_properties(max_mw=500, min_logp=None, max_logp=None):
    """
    Find molecules based on physicochemical properties.

    Args:
        max_mw: Maximum molecular weight
        min_logp: Minimum LogP value
        max_logp: Maximum LogP value

    Returns:
        List of matching molecules
    """
    molecule = new_client.molecule

    filters = {
        'molecule_properties__mw_freebase__lte': max_mw
    }

    if min_logp is not None:
        filters['molecule_properties__alogp__gte'] = min_logp
    if max_logp is not None:
        filters['molecule_properties__alogp__lte'] = max_logp

    results = molecule.filter(**filters)
    return list(results)


def get_target_info(target_chembl_id):
    """
    Retrieve information about a biological target.

    Args:
        target_chembl_id: ChEMBL target identifier (e.g., 'CHEMBL240')

    Returns:
        Dictionary containing target information
    """
    target = new_client.target
    return target.get(target_chembl_id)


def search_targets_by_name(target_name):
    """
    Search for targets by name or keyword.

    Args:
        target_name: Target name or keyword (e.g., 'kinase', 'EGFR')

    Returns:
        List of matching targets
    """
    target = new_client.target
    results = list(target.filter(
        target_type='SINGLE PROTEIN',
        pref_name__icontains=target_name
    ))
    if not results:
        # Gene symbols such as 'EGFR' are stored as synonyms, not in pref_name
        # (CHEMBL203 is "Epidermal growth factor receptor"). Substring matches
        # can include related targets (e.g. VEGFR1-3), so check pref_name.
        results = list(target.filter(
            target_type='SINGLE PROTEIN',
            target_synonym__icontains=target_name
        ))
    return results


def get_bioactivity_data(target_chembl_id, activity_type='IC50', max_value=100):
    """
    Retrieve bioactivity data for a specific target.

    Args:
        target_chembl_id: ChEMBL target identifier
        activity_type: Type of activity (IC50, Ki, EC50, etc.)
        max_value: Maximum activity value in nM

    Returns:
        List of activity records
    """
    activity = new_client.activity
    results = activity.filter(
        target_chembl_id=target_chembl_id,
        standard_type=activity_type,
        standard_value__lte=max_value,
        standard_units='nM'
    )
    return list(results)


def find_similar_compounds(smiles, similarity_threshold=85):
    """
    Find compounds similar to a query structure.

    Args:
        smiles: SMILES string of query molecule
        similarity_threshold: Minimum similarity percentage (0-100)

    Returns:
        List of similar compounds
    """
    similarity = new_client.similarity
    results = similarity.filter(
        smiles=smiles,
        similarity=similarity_threshold
    )
    return list(results)


def substructure_search(smiles):
    """
    Search for compounds containing a specific substructure.

    Args:
        smiles: SMILES string of substructure

    Returns:
        List of compounds containing the substructure
    """
    substructure = new_client.substructure
    results = substructure.filter(smiles=smiles)
    return list(results)


def get_drug_info(molecule_chembl_id):
    """
    Retrieve drug information including indications and mechanisms.

    Args:
        molecule_chembl_id: ChEMBL molecule identifier

    Returns:
        Tuple of (drug_info, mechanisms, indications)
    """
    drug = new_client.drug
    mechanism = new_client.mechanism
    drug_indication = new_client.drug_indication

    try:
        drug_info = drug.get(molecule_chembl_id)
    except Exception:
        drug_info = None

    mechanisms = list(mechanism.filter(molecule_chembl_id=molecule_chembl_id))
    indications = list(drug_indication.filter(molecule_chembl_id=molecule_chembl_id))

    return drug_info, mechanisms, indications


def find_kinase_inhibitors(max_ic50=100):
    """
    Find potent kinase inhibitors.

    Args:
        max_ic50: Maximum IC50 value in nM

    Returns:
        List of kinase inhibitor activities
    """
    target = new_client.target
    activity = new_client.activity

    # Find kinase targets
    kinase_targets = target.filter(
        target_type='SINGLE PROTEIN',
        pref_name__icontains='kinase'
    )

    # Get target IDs
    target_ids = [t['target_chembl_id'] for t in kinase_targets[:10]]  # Limit to first 10

    # Find activities
    results = activity.filter(
        target_chembl_id__in=target_ids,
        standard_type='IC50',
        standard_value__lte=max_ic50,
        standard_units='nM'
    )

    return list(results)


def get_compound_bioactivities(molecule_chembl_id):
    """
    Get all bioactivity data for a specific compound.

    Args:
        molecule_chembl_id: ChEMBL molecule identifier

    Returns:
        List of all activity records for the compound
    """
    activity = new_client.activity
    results = activity.filter(
        molecule_chembl_id=molecule_chembl_id,
        pchembl_value__isnull=False
    )
    return list(results)


def export_to_dataframe(data):
    """
    Convert ChEMBL data to pandas DataFrame (requires pandas).

    Args:
        data: List of ChEMBL records

    Returns:
        pandas DataFrame
    """
    try:
        import pandas as pd
        return pd.DataFrame(data)
    except ImportError:
        print("pandas not installed. Install with: uv pip install pandas")
        return None


# Example usage
if __name__ == "__main__":
    print("ChEMBL Database Query Examples")
    print("=" * 50)

    # Example 1: Get information about aspirin
    print("\n1. Getting information about aspirin (CHEMBL25)...")
    aspirin = get_molecule_info('CHEMBL25')
    print(f"Name: {aspirin.get('pref_name')}")
    print(f"Formula: {aspirin.get('molecule_properties', {}).get('full_molformula')}")

    # Example 2: Search for EGFR inhibitors
    print("\n2. Searching for EGFR targets...")
    egfr_targets = search_targets_by_name('EGFR')
    if egfr_targets:
        print(f"Found {len(egfr_targets)} EGFR-related targets")
        print(f"First target: {egfr_targets[0]['pref_name']}")

    # Example 3: Find potent activities for a target
    print("\n3. Finding potent compounds for EGFR (CHEMBL203)...")
    activities = get_bioactivity_data('CHEMBL203', 'IC50', max_value=10)
    print(f"Found {len(activities)} compounds with IC50 <= 10 nM")

    print("\n" + "=" * 50)
    print("Examples completed successfully!")