Tooluniverse Chemical Compound Retrieval

Chemical Compound Information Retrieval

Retrieve comprehensive chemical compound data with proper disambiguation and cross-database validation.

LOOK UP DON'T GUESS: Never assume a CID, ChEMBL ID, or molecular property value. Always retrieve from PubChem/ChEMBL.

English-first: Always use English compound names in tool calls. Respond in user's language.

Domain Reasoning: Disambiguation

"Aspirin" = one compound. "Vitamin D" = multiple forms (D2/D3/active metabolite). For generic class names (steroids, vitamins, acids), present candidates and confirm before proceeding.

---

Workflow

Phase 0: Clarify (only if highly ambiguous -- skip for unambiguous names or specific IDs)
Phase 1: Disambiguate → resolve PubChem CID + ChEMBL ID
Phase 2: Retrieve data (silent)
Phase 3: Report compound profile

Phase 1: Disambiguation

# By name
result = tu.tools.PubChem_get_CID_by_compound_name(compound_name=name)
# By SYSTEMATIC (IUPAC) name -> structure, deterministic parser (no DB lookup)
opsin = tu.tools.OPSIN_name_to_structure(name="2-acetoxybenzoic acid")
# Returns {parsed, smiles, inchi, inchikey}; use the SMILES/InChIKey to anchor a
# PubChem_get_CID_by_SMILES lookup. Trade/trivial names give parsed=false -> fall
# back to PubChem_get_CID_by_compound_name for those.
# By SMILES
result = tu.tools.PubChem_get_CID_by_SMILES(smiles=smiles)
# Cross-reference
chembl_result = tu.tools.ChEMBL_search_molecules(query=name, limit=5)

Verify: CID + ChEMBL ID + canonical SMILES + stereochemistry + salt forms.

Phase 2: Data Retrieval

PubChem: PubChem_get_compound_properties_by_CID, PubChemBioAssay_get_assay_summary, PubChemTox_get_acute_effects, PubChem_get_compound_2D_image_by_CID

ChEMBL: ChEMBL_get_compound_record_activities, ChEMBL_get_molecule_targets, ChEMBL_get_assay_activities

Optional: PubChem_get_associated_patents_by_CID, PubChem_search_compounds_by_similarity

Phase 3: Report

Compound Profile with: Identity (CID, ChEMBL ID, IUPAC, SMILES), Chemical Properties (MW, LogP, HBD, HBA, PSA, Lipinski), Bioactivity (targets, IC50/Ki), Drug Info (if approved), Data Sources.

---

Fallback Chains

---

Evidence Grading

Bioactivity: ChEMBL > PubChem BioAssay for curated data. IC50/Ki < 100nM = potent, 100nM-1uM = moderate, >10uM = weak. Lipinski violations reduce oral bioavailability but don't disqualify.

---

SMILES Verification

Always verify novel SMILES: python3 src/tooluniverse/tools/smiles_verifier.py --smiles "SMILES_STRING". Invalid SMILES produce wrong results or cryptic errors.

---

Tool Reference

PubChem: PubChem_get_CID_by_compound_name, PubChem_get_CID_by_SMILES, PubChem_get_compound_properties_by_CID, PubChem_get_compound_2D_image_by_CID, PubChemBioAssay_get_assay_summary, PubChemTox_get_acute_effects, PubChem_get_associated_patents_by_CID, PubChem_search_compounds_by_similarity, PubChem_search_compounds_by_substructure

ChEMBL: ChEMBL_search_drugs, ChEMBL_get_molecule, ChEMBL_get_activity, ChEMBL_get_target, ChEMBL_search_targets, ChEMBL_search_assays

Name parsing: OPSIN_name_to_structure (param name) — deterministic IUPAC/systematic-name → SMILES/InChI/InChIKey parser; the go-to for resolving a systematic name to structure without a DB round-trip. Trade/trivial names return parsed=false (use PubChem name lookup for those).

Chemical Compound Retrieval Checklist

Use this checklist to ensure complete compound profiles.

Identity Resolution

• [ ] PubChem CID established
• [ ] ChEMBL ID cross-referenced (or "N/A" noted)
• [ ] Canonical SMILES captured
• [ ] IUPAC name recorded
• [ ] Naming collisions handled (if applicable)

Chemical Properties

• [ ] Molecular formula
• [ ] Molecular weight
• [ ] LogP (lipophilicity)
• [ ] Hydrogen bond donors/acceptors
• [ ] Polar surface area
• [ ] Lipinski rule assessment

Bioactivity Data

• [ ] Activity summary included (or "No data")
• [ ] Primary targets listed (or "Unknown")
• [ ] Key assays noted (if available)

Drug Information (If Approved)

• [ ] Approval status
• [ ] Drug class
• [ ] Indications
• [ ] Safety warnings (if any)

Report Quality

• [ ] Data quality tier assigned (●●●/●●○/●○○/○○○)
• [ ] Data sources cited with links
• [ ] Retrieval date included
• [ ] Search process NOT shown in output
• [ ] Results presented in clean report format

Fallback Handling

• [ ] PubChem failure → ChEMBL search attempted
• [ ] Missing ChEMBL ID → noted as "N/A"
• [ ] No bioactivity → section exists with "No data available"
• [ ] API errors → noted as "(retrieval failed)"

Chemical Compound Retrieval Examples

Example 1: Find Aspirin Information

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Get CID from name
cid_result = tu.tools.PubChem_get_CID_by_compound_name(
    compound_name="aspirin"
)
cid = cid_result["data"]["cid"]  # 2244

# Get properties
props = tu.tools.PubChem_get_compound_properties_by_CID(cid=cid)

print(f"CID: {cid}")
print(f"Formula: {props['data']['MolecularFormula']}")
print(f"Weight: {props['data']['MolecularWeight']}")
print(f"SMILES: {props['data']['CanonicalSMILES']}")

Example 2: Search by Chemical Structure

# Search by SMILES
smiles = "CC(=O)Oc1ccccc1C(=O)O"  # Aspirin

cid_result = tu.tools.PubChem_get_CID_by_SMILES(smiles=smiles)
cid = cid_result["data"]["cid"]

# Get compound details
props = tu.tools.PubChem_get_compound_properties_by_CID(cid=cid)
print(f"Found: {props['data']['IUPACName']}")

Example 3: Find Similar Compounds

# Start with a known compound
cid = 2244  # Aspirin

# Find similar compounds
similar = tu.tools.PubChem_search_compounds_by_similarity(
    cid=cid,
    threshold=85  # 85% similarity
)

print(f"Found {len(similar['data'])} similar compounds")

# Get properties of similar compounds
for sim_cid in similar["data"][:5]:
    props = tu.tools.PubChem_get_compound_properties_by_CID(
        cid=sim_cid
    )
    print(f"CID {sim_cid}: {props['data']['MolecularFormula']}")

Example 4: Get Drug Information

# Find drug
cid_result = tu.tools.PubChem_get_CID_by_compound_name(
    compound_name="ibuprofen"
)
cid = cid_result["data"]["cid"]

# Get bioactivity
bioactivity = tu.tools.PubChem_get_compound_bioactivity(
    cid=cid
)

print(f"Active in {bioactivity['data']['active_assay_count']} assays")

# Get drug label information
# FDA labels are keyed by drug name, not CID -- resolve the name first
_syn = tu.tools.PubChem_get_compound_synonyms_by_CID(cid=cid)
_name = _syn['data'][0] if isinstance(_syn, dict) and _syn.get('data') else None
drug_info = tu.tools.FDA_get_drug_label(drug_name=_name)

# Get patents
patents = tu.tools.PubChem_get_associated_patents_by_CID(cid=cid)
print(f"Related patents: {len(patents['data'])}")

Example 5: ChEMBL Cross-Reference

# Find in PubChem
cid_result = tu.tools.PubChem_get_CID_by_compound_name(
    compound_name="gefitinib"
)

# Search in ChEMBL
chembl_result = tu.tools.ChEMBL_search_molecules(
    query="gefitinib",
    limit=5
)

if chembl_result["data"]:
    chembl_id = chembl_result["data"][0]["molecule_chembl_id"]
    
    # Get bioactivity from ChEMBL
    activity = tu.tools.ChEMBL_search_activities(
        chembl_id=chembl_id
    )
    
    # Get targets
    targets = tu.tools.ChEMBL_get_target(
        chembl_id=chembl_id
    )
    
    print(f"ChEMBL ID: {chembl_id}")
    print(f"Bioactivities: {len(activity['data'])}")
    print(f"Targets: {len(targets['data'])}")

Example 6: Substructure Search

# Search for compounds containing benzene ring
benzene_smiles = "c1ccccc1"

result = tu.tools.PubChem_search_compounds_by_substructure(
    smiles=benzene_smiles,
    limit=100
)

print(f"Found {len(result['data'])} compounds with benzene ring")

# Get properties of first 10
for cid in result["data"][:10]:
    props = tu.tools.PubChem_get_compound_properties_by_CID(cid=cid)
    print(f"CID {cid}: {props['data']['IUPACName'][:50]}...")

Example 7: Drug Discovery Workflow

# 1. Start with target compound
cid = tu.tools.PubChem_get_CID_by_compound_name(
    compound_name="erlotinib"
)["data"]["cid"]

# 2. Get properties (check drug-likeness)
props = tu.tools.PubChem_get_compound_properties_by_CID(cid=cid)
mw = props["data"]["MolecularWeight"]
logp = props["data"]["XLogP"]

print(f"MW: {mw}, LogP: {logp}")

# 3. Get bioactivity
bio = tu.tools.PubChem_get_compound_bioactivity(cid=cid)
print(f"Active in {bio['data']['active_assay_count']} assays")

# 4. Find similar active compounds
similar = tu.tools.PubChem_search_compounds_by_similarity(
    cid=cid,
    threshold=80
)

print(f"Found {len(similar['data'])} similar compounds for SAR analysis")

Example 8: Get 2D Structure Image

# Get compound
cid = 2244  # Aspirin

# Get structure image
image = tu.tools.PubChem_get_compound_2D_image_by_CID(cid=cid)

print(f"Image URL: {image['data']['url']}")
# Can be displayed or saved for documentation