PharmaClaw Chemistry Query

Chemistry agent skill for PubChem API queries (compound info/properties, structures/SMILES/images, synthesis routes/references) + RDKit cheminformatics (SMIL...

Security Scan

The skill's code, scripts, and runtime instructions match its stated chemistry/RDKit/PubChem purpose and request no unrelated credentials, but it performs network calls, writes files, and includes an optional cross-skill dashboard hook you should review before use.

Purpose & Capability

Name/description (PubChem + RDKit + synthesis tooling) align with the contained scripts (query_pubchem.py, rdkit_mol.py, rdkit_reaction.py, opsin downloader, ChEMBL and PubMed queries). Declared package deps (rdkit, gradio, pandas, Pillow) are appropriate for the features described. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

Runtime instructions and scripts perform exactly the expected tasks (PubChem/ChEMBL/PubMed HTTP requests, RDKit processing, image generation). They also: (1) download an OPSIN JAR at runtime (from GitHub) when name→SMILES conversion is used; (2) write visualization files under the skill tree (viz/ and script-local files) and save opsin.jar into scripts/; (3) call local scripts via subprocess.run. Additionally, chain_entry.py will attempt to import and call lab_update from a relative 'pharmaclaw-lab-ui' path if present — this is a cross-skill/dashboard hook that can transmit analyzed compound names/SMILES to that component if installed.

Install Mechanism

No install spec is provided (instruction-only skill with bundled code). The only runtime download is OPSIN JAR from a GitHub release; the code verifies a pinned SHA-256 before accepting it, which is good. There is no indication of arbitrary third-party binaries or untrusted shortener/IP downloads.

Credentials

The skill declares no required environment variables or secrets and does not attempt to read system config paths. Network calls are limited to public chemistry APIs (PubChem, ChEMBL, NCBI). The permissions requested are proportional to the chemistry-data/cheminformatics functionality.

Persistence & Privilege

always:false and no model-invocation restrictions — normal. The skill writes files into its own tree (viz images, downloaded opsin.jar) and can create directories under the skill. The only cross-component privilege is the optional import of a 'pharmaclaw-lab-ui' lab_hook (if present in the relative path) which allows the skill to call lab_update; this could forward compound context to that dashboard if you also have that component installed.

Assessment

This skill appears to be what it claims: a PubChem + RDKit chemistry toolkit. Before installing/running it, consider: (1) RDKit and the declared Python packages must be present (RDKit is large); (2) Java (JRE) is only needed if you use IUPAC→SMILES conversion — the skill will download an OPSIN JAR into the skill directory and verifies its SHA-256 (you can validate the pinned checksum yourself); (3) the scripts make HTTP(S) calls to public APIs (PubChem, ChEMBL, NCBI) and will write image and JSON outputs into the skill folder (viz/ and scripts/); (4) chain_entry.py attempts to import and call a lab_update hook from a relative 'pharmaclaw-lab-ui' path if that package/directory exists — if you have that component installed, review it to understand what data (compound names/SMILES/status) may be forwarded; (5) the reaction templates and multi-step planning are powerful and could be used for risky chemical synthesis — if that is a concern, run the skill in an isolated environment without network access or inspect/disable the reaction/template files. If you want higher assurance, review the lab_hook implementation (if present), confirm the OPSIN checksum, and run the skill in a sandboxed environment.

Chemistry Query Agent v1.4.1

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

1. Name → Full Profile: chain_entry.py with {"name": "ibuprofen"} → props + draw + retro
2. Chemistry → Pharmacology: Output feeds directly into pharma-pharmacology-agent
3. Retro + Viz: Get precursors, then draw each one
4. 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 limits
• scripts/rdkit_reaction.py — Legacy reaction module
• scripts/chembl_query.py, scripts/pubmed_search.py, scripts/admet_predict.py — Additional query modules

scripts/advanced_chem.py

Advanced cheminformatics engine with 6 Tier 1 capabilities.

--action <standardize|descriptors|scaffold|mcs|mmpa|chemspace> --smiles <SMILES> [options]

Action	Description	Key Args
standardize	Salt stripping, charge normalization, tautomer enumeration	--smiles
descriptors	217+ molecular descriptors (RDKit full set), QED, SA Score, Lipinski/Veber rules	--smiles --descriptor_set all|druglike|physical|topological
scaffold	Murcko scaffold extraction, generic scaffolds, diversity analysis, R-group decomposition	--smiles or --target_smiles "smi1,smi2,..." --rgroup_core <SMARTS>
mcs	Maximum Common Substructure across 2+ molecules	--target_smiles "smi1,smi2,..."
mmpa	Matched Molecular Pair Analysis — find single-point transformations	--target_smiles "smi1,smi2,..."
chemspace	Chemical space visualization (PCA/t-SNE/UMAP scatter plot PNG)	--target_smiles "smi1,smi2,..." --method pca|tsne|umap --output plot.png

Examples:

# Standardize a salt form
python scripts/advanced_chem.py --action standardize --smiles "[Na+].CC(=O)[O-]"

# Full descriptors (217+)
python scripts/advanced_chem.py --action descriptors --smiles "CC(=O)Oc1ccccc1C(=O)O" --descriptor_set all

# Scaffold diversity of a set
python scripts/advanced_chem.py --action scaffold --target_smiles "CC(=O)Oc1ccccc1C(=O)O,CN1C=NC2=C1C(=O)N(C(=O)N2C)C,CC(C)Cc1ccc(cc1)C(C)C(=O)O"

# MCS of aspirin and salicylic acid
python scripts/advanced_chem.py --action mcs --target_smiles "CC(=O)Oc1ccccc1C(=O)O,c1ccccc1C(=O)O"

# Matched molecular pairs
python scripts/advanced_chem.py --action mmpa --target_smiles "c1ccc(CC(=O)O)cc1,c1ccc(CCC(=O)O)cc1"

# Chemical space PCA plot
python scripts/advanced_chem.py --action chemspace --target_smiles "CC(=O)Oc1ccccc1C(=O)O,CN1C=NC2=C1C(=O)N(C(=O)N2C)C,c1ccccc1" --method pca --output space.png

Changelog

v2.0.0 (2026-02-28)

• NEW: advanced_chem.py with 6 Tier 1 cheminformatics capabilities
  • Molecular Standardization & Tautomer Enumeration (salt stripping, charge normalization, canonical tautomers)
  • Extended Descriptors (217+ RDKit descriptors, QED, SA Score, Lipinski, Veber)
  • Scaffold Analysis (Murcko, generic scaffolds, diversity ratio, R-group decomposition)
  • Maximum Common Substructure (rdFMCS with coverage per molecule)
  • Matched Molecular Pair Analysis (rdMMPA fragmentation, transformation detection)
  • Chemical Space Visualization (PCA/t-SNE/UMAP with matplotlib scatter plots)
• Dependencies: scikit-learn, matplotlib (added)

v1.4.1 (2026-02-25)

• Security hardening: input sanitization for all subprocess calls (SMILES, compound names, output paths)
• Added _sanitize_input() — length limits, null-byte rejection for all user inputs
• Added _sanitize_output_path() — prevents path traversal, restricts extensions, blocks arbitrary file writes
• Added shell metacharacter rejection in resolve_target()
• Added SMILES validation via RDKit in chem_ui.py before subprocess calls
• Added compound input validation in query_pubchem.py (length/null-byte checks)
• Added timeout to resolve_target() PubChem subprocess call
• Addresses VirusTotal "suspicious" classification for argument injection vectors

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