Chemistry Query Agent v1.4.0
Overview
Full-stack chemistry toolkit combining PubChem data retrieval with RDKit molecule processing, visualization, analysis, retrosynthesis, and synthesis planning. All outputs are structured JSON for easy downstream chaining. Generates PNG/SVG images on demand.
Key capabilities:
- PubChem compound lookup (info, structure, synthesis refs, similarity search)
- RDKit molecular properties (MW, logP, TPSA, HBD/HBA, rotatable bonds, aromatic rings)
- 2D molecule visualization (PNG/SVG)
- BRICS retrosynthesis with recursive depth control
- Multi-step synthesis route planning
- Forward reaction simulation with SMARTS templates
- Morgan fingerprints and similarity/substructure search
- 21 named reaction templates (Suzuki, Heck, Grignard, Wittig, Diels-Alder, etc.)
Quick Start
# PubChem compound info
exec python scripts/query_pubchem.py --compound "aspirin" --type info
# Molecular properties from SMILES
exec python scripts/rdkit_mol.py --smiles "CC(=O)Oc1ccccc1C(=O)O" --action props
# Retrosynthesis
exec python scripts/rdkit_mol.py --target "CC(=O)Oc1ccccc1C(=O)O" --action retro --depth 2
# Full chain (name → props + draw + retro)
exec python scripts/chain_entry.py --input-json '{"name": "caffeine", "context": "user"}'
Scripts
scripts/query_pubchem.py
PubChem REST API queries with automatic name→CID resolution and timeout handling.
--compound <name|CID> --type <info|structure|synthesis|similar> [--format smiles|inchi|image|json] [--threshold 80]
- info: Formula, MW, IUPAC name, InChIKey (JSON)
- structure: SMILES, InChI, image URL, or full JSON
- synthesis: Synonyms/references for a compound
- similar: Similar compounds by 2D fingerprint (top 20)
scripts/rdkit_mol.py
RDKit cheminformatics engine. Resolves names via PubChem automatically.
--smiles <SMILES> --action <props|draw|fingerprint|similarity|substruct|xyz|react|retro|plan>
| Action |
Description |
Key Args |
| props |
MW, logP, TPSA, HBD, HBA, rotB, aromRings |
--smiles |
| draw |
2D PNG/SVG (300×300) |
--smiles --output file.png --format png|svg |
| retro |
BRICS recursive retrosynthesis |
--target <SMILES|name> --depth N |
| plan |
Multi-step retro route |
--target <SMILES|name> --steps N |
| react |
Forward reaction via SMARTS |
--reactants "smi1 smi2" --smarts "<SMARTS>" |
| fingerprint |
Morgan fingerprint bitvector |
--smiles --radius 2 |
| similarity |
Tanimoto similarity scoring |
--query_smiles --target_smiles "smi1,smi2" |
| substruct |
Substructure matching |
--query_smiles --target_smiles "smi1,smi2" |
| xyz |
3D coordinates (MMFF optimized) |
--smiles |
scripts/chain_entry.py
Standard agent chain interface. Accepts {"smiles": "...", "context": "..."} or {"name": "...", "context": "..."}. Returns unified JSON with props, visualization, and retrosynthesis.
python scripts/chain_entry.py --input-json '{"name": "sotorasib", "context": "user"}'
Output schema:
{
"agent": "chemistry-query",
"version": "1.4.0",
"smiles": "<canonical>",
"status": "success|error",
"report": {"props": {...}, "draw": {...}, "retro": {...}},
"risks": [],
"viz": ["path/to/image.png"],
"recommend_next": ["pharmacology", "toxicology"],
"confidence": 0.95,
"warnings": [],
"timestamp": "ISO8601"
}
scripts/templates.json
21 named reaction templates with SMARTS, expected yields, conditions, and references. Includes: Suzuki, Heck, Buchwald-Hartwig, Grignard, Wittig, Diels-Alder, Click, Sonogashira, Negishi, and more.
Chaining
- Name → Full Profile:
chain_entry.py with {"name": "ibuprofen"} → props + draw + retro
- Chemistry → Pharmacology: Output feeds directly into
pharma-pharmacology-agent
- Retro + Viz: Get precursors, then draw each one
- Suzuki Test:
--action react --reactants "c1ccccc1Br c1ccccc1B(O)O" --smarts "[c:1][Br:2].[c:3][B]([c:4])(O)O>>[c:1][c:3]"
Tested With
All features verified end-to-end with RDKit 2024.03+:
| Molecule |
SMILES |
Tests Passed |
| Caffeine |
CN1C=NC2=C1C(=O)N(C(=O)N2C)C |
info, structure, props, draw, retro, plan, chain |
| Aspirin |
CC(=O)Oc1ccccc1C(=O)O |
info, structure, props, draw, retro, plan, chain |
| Sotorasib |
PubChem name lookup |
info, structure, props, draw, retro, chain |
| Ibuprofen |
PubChem name lookup |
info, structure, props, chain |
| Invalid SMILES |
XXXINVALID |
Graceful JSON error |
| Empty input |
{} |
Graceful JSON error |
Resources
references/api_endpoints.md — PubChem API endpoint reference and rate limitsscripts/rdkit_reaction.py — Legacy reaction modulescripts/chembl_query.py, scripts/pubmed_search.py, scripts/admet_predict.py — Additional query modules
Changelog
v1.4.0 (2026-02-14)
- Fixed PubChem SMILES/InChI endpoint (property/CanonicalSMILES/TXT)
- Fixed chain_entry.py HTML entity corruption
- Fixed brics_retro to handle BRICSDecompose string output correctly
- Added request timeouts (15s) to all PubChem calls
- Graceful error handling for invalid SMILES and empty input
- Updated chain output version and schema
- Comprehensive end-to-end testing
v1.3.0
- RDKit props NoneType fixes, invalid SMILES graceful errors
- React fix: ReactionFromSmarts import
- Name resolution via PubChem for all RDKit actions
v1.2.0
- BRICS retrosynthesis + 21 reaction templates library
- Multi-step synthesis planning
1---2name: chemistry-query3description: Chemistry agent skill for PubChem API queries (compound info/properties, structures/SMILES/images, synthesis routes/references) + RDKit cheminformatics (SMILES to molecule props/logP/TPSA, 2D PNG/SVG viz, Morgan fingerprints, retrosynthesis/BRICS disconnects, multi-step synth planning). Use for chemistry tasks involving compounds, molecules, structures, PubChem data, RDKit analysis, SMILES processing, synthesis routes, retrosynthesis, reaction simulation. Triggers on chemistry, compounds, molecules, chemical data/properties, PubChem, RDKit, SMILES, structures, synthesis, reactions, retrosynthesis, synth plan/route.4---5
6# Chemistry Query Agent v1.4.0
7
8## Overview
9
10Full-stack chemistry toolkit combining PubChem data retrieval with RDKit molecule processing, visualization, analysis, retrosynthesis, and synthesis planning. All outputs are structured JSON for easy downstream chaining. Generates PNG/SVG images on demand.
11
12**Key capabilities:**
13- PubChem compound lookup (info, structure, synthesis refs, similarity search)
14- RDKit molecular properties (MW, logP, TPSA, HBD/HBA, rotatable bonds, aromatic rings)
15- 2D molecule visualization (PNG/SVG)
16- BRICS retrosynthesis with recursive depth control
17- Multi-step synthesis route planning
18- Forward reaction simulation with SMARTS templates
19- Morgan fingerprints and similarity/substructure search
20- 21 named reaction templates (Suzuki, Heck, Grignard, Wittig, Diels-Alder, etc.)
21
22## Quick Start
23
24```bash
25# PubChem compound info
26exec python scripts/query_pubchem.py --compound "aspirin" --type info
27
28# Molecular properties from SMILES
29exec python scripts/rdkit_mol.py --smiles "CC(=O)Oc1ccccc1C(=O)O" --action props
30
31# Retrosynthesis
32exec python scripts/rdkit_mol.py --target "CC(=O)Oc1ccccc1C(=O)O" --action retro --depth 2
33
34# Full chain (name → props + draw + retro)
35exec python scripts/chain_entry.py --input-json '{"name": "caffeine", "context": "user"}'
36```
37
38## Scripts
39
40### `scripts/query_pubchem.py`
41PubChem REST API queries with automatic name→CID resolution and timeout handling.
42
43```
44--compound <name|CID> --type <info|structure|synthesis|similar> [--format smiles|inchi|image|json] [--threshold 80]
45```
46
47- **info:** Formula, MW, IUPAC name, InChIKey (JSON)
48- **structure:** SMILES, InChI, image URL, or full JSON
49- **synthesis:** Synonyms/references for a compound
50- **similar:** Similar compounds by 2D fingerprint (top 20)
51
52### `scripts/rdkit_mol.py`
53RDKit cheminformatics engine. Resolves names via PubChem automatically.
54
55```
56--smiles <SMILES> --action <props|draw|fingerprint|similarity|substruct|xyz|react|retro|plan>
57```
58
59| Action | Description | Key Args |
60|--------|-------------|----------|
61| props | MW, logP, TPSA, HBD, HBA, rotB, aromRings | `--smiles` |
62| draw | 2D PNG/SVG (300×300) | `--smiles --output file.png --format png\|svg` |
63| retro | BRICS recursive retrosynthesis | `--target <SMILES\|name> --depth N` |
64| plan | Multi-step retro route | `--target <SMILES\|name> --steps N` |
65| react | Forward reaction via SMARTS | `--reactants "smi1 smi2" --smarts "<SMARTS>"` |
66| fingerprint | Morgan fingerprint bitvector | `--smiles --radius 2` |
67| similarity | Tanimoto similarity scoring | `--query_smiles --target_smiles "smi1,smi2"` |
68| substruct | Substructure matching | `--query_smiles --target_smiles "smi1,smi2"` |
69| xyz | 3D coordinates (MMFF optimized) | `--smiles` |
70
71### `scripts/chain_entry.py`
72Standard agent chain interface. Accepts `{"smiles": "...", "context": "..."}` or `{"name": "...", "context": "..."}`. Returns unified JSON with props, visualization, and retrosynthesis.
73
74```bash
75python scripts/chain_entry.py --input-json '{"name": "sotorasib", "context": "user"}'
76```
77
78Output schema:
79```json
80{
81 "agent": "chemistry-query",
82 "version": "1.4.0",
83 "smiles": "<canonical>",
84 "status": "success|error",
85 "report": {"props": {...}, "draw": {...}, "retro": {...}},
86 "risks": [],
87 "viz": ["path/to/image.png"],
88 "recommend_next": ["pharmacology", "toxicology"],
89 "confidence": 0.95,
90 "warnings": [],
91 "timestamp": "ISO8601"
92}
93```
94
95### `scripts/templates.json`
9621 named reaction templates with SMARTS, expected yields, conditions, and references. Includes: Suzuki, Heck, Buchwald-Hartwig, Grignard, Wittig, Diels-Alder, Click, Sonogashira, Negishi, and more.
97
98## Chaining
99
1001. **Name → Full Profile:** `chain_entry.py` with `{"name": "ibuprofen"}` → props + draw + retro
1012. **Chemistry → Pharmacology:** Output feeds directly into `pharma-pharmacology-agent`
1023. **Retro + Viz:** Get precursors, then draw each one
1034. **Suzuki Test:** `--action react --reactants "c1ccccc1Br c1ccccc1B(O)O" --smarts "[c:1][Br:2].[c:3][B]([c:4])(O)O>>[c:1][c:3]"`
104
105## Tested With
106
107All features verified end-to-end with RDKit 2024.03+:
108
109| Molecule | SMILES | Tests Passed |
110|----------|--------|-------------|
111| Caffeine | `CN1C=NC2=C1C(=O)N(C(=O)N2C)C` | info, structure, props, draw, retro, plan, chain |
112| Aspirin | `CC(=O)Oc1ccccc1C(=O)O` | info, structure, props, draw, retro, plan, chain |
113| Sotorasib | PubChem name lookup | info, structure, props, draw, retro, chain |
114| Ibuprofen | PubChem name lookup | info, structure, props, chain |
115| Invalid SMILES | `XXXINVALID` | Graceful JSON error |
116| Empty input | `{}` | Graceful JSON error |
117
118## Resources
119
120- `references/api_endpoints.md` — PubChem API endpoint reference and rate limits
121- `scripts/rdkit_reaction.py` — Legacy reaction module
122- `scripts/chembl_query.py`, `scripts/pubmed_search.py`, `scripts/admet_predict.py` — Additional query modules
123
124## Changelog
125
126**v1.4.0** (2026-02-14)
127- Fixed PubChem SMILES/InChI endpoint (property/CanonicalSMILES/TXT)
128- Fixed chain_entry.py HTML entity corruption
129- Fixed brics_retro to handle BRICSDecompose string output correctly
130- Added request timeouts (15s) to all PubChem calls
131- Graceful error handling for invalid SMILES and empty input
132- Updated chain output version and schema
133- Comprehensive end-to-end testing
134
135**v1.3.0**
136- RDKit props NoneType fixes, invalid SMILES graceful errors
137- React fix: ReactionFromSmarts import
138- Name resolution via PubChem for all RDKit actions
139
140**v1.2.0**
141- BRICS retrosynthesis + 21 reaction templates library
142- Multi-step synthesis planning
modbender