# Chem Similarity Search

> Find structurally similar chemical compounds using PubChem's 2D fast similarity engine via the PUG-REST API.

- **Type:** Skill
- **Install:** `agentstack add skill-learningmatter-mit-atomisticskills-chem-similarity-search`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [learningmatter-mit](https://agentstack.voostack.com/s/learningmatter-mit)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [learningmatter-mit](https://github.com/learningmatter-mit)
- **Source:** https://github.com/learningmatter-mit/AtomisticSkills/tree/main/.agents/skills/chem-similarity-search
- **Website:** https://arxiv.org/abs/2605.24002

## Install

```sh
agentstack add skill-learningmatter-mit-atomisticskills-chem-similarity-search
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Chemical Similarity Search

## Goal
To programmatically find chemical analogs, alternative precursors, and structurally similar compounds for a given target molecule using PubChem's "fastsimilarity_2d" endpoint. The skill retrieves lists of similar compounds ranked by sequence alignment of their 2D molecular fingerprints, providing CIDs, molecular weights, formulas, and SMILES strings.

## Instructions

### 1. Search by SMILES String
Search for similar compounds by providing the canonical or isomeric SMILES.
Adjust the `--threshold` (similarity cutoff 0-100, default is 95) to widen or narrow the search radius. Higher threshold equals higher similarity.
Adjust `--max_records` to limit the output length.

```bash
# Env: base-agent
python .agents/skills/chem-similarity-search/scripts/similarity_search.py \
  --smiles "CC(=O)Oc1ccccc1C(=O)O" \
  --threshold 95 \
  --max_records 5 \
  --outdir research/aspirin_similar \
  --output aspirin_similar.json
```

### 2. Search by PubChem CID
Search directly using an exact compound's CID. This avoids translation steps for SMILES parsing.

```bash
# Env: base-agent
python .agents/skills/chem-similarity-search/scripts/similarity_search.py \
  --cid 2244 \
  --threshold 90 \
  --max_records 10 \
  --outdir research/aspirin_similar \
  --output cid_2244_similar.json
```

## Examples

We can test extracting highly similar analogs (Threshold 95) for Aspirin (CID: 2244 or SMILES: `CC(=O)Oc1ccccc1C(=O)O`).

```bash
# Env: base-agent
python .agents/skills/chem-similarity-search/scripts/similarity_search.py \
  --cid 2244 \
  --threshold 95 \
  --max_records 5 \
  --outdir .agents/skills/chem-similarity-search/examples/aspirin_analogs \
  --output aspirin_analogs.json
```

## Constraints
- **Rate Limiting**: PubChem PUG REST API enforces per-user throttling limits. Heavy bursts will result in `HTTP 503 Server Busy` errors. The script implements an exponential backoff retry mechanism.
- **2D Similarity**: Uses exact structural bit-vector fingerprints. Stereochemical and 3D properties do not strongly affect the score.
- **Network**: Internet access is required.

---
---

**Author:** Bowen Deng
**Contact:** [GitHub @learningmatter-mit](https://github.com/learningmatter-mit)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [learningmatter-mit](https://github.com/learningmatter-mit)
- **Source:** [learningmatter-mit/AtomisticSkills](https://github.com/learningmatter-mit/AtomisticSkills)
- **License:** MIT
- **Homepage:** https://arxiv.org/abs/2605.24002

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-learningmatter-mit-atomisticskills-chem-similarity-search
- Seller: https://agentstack.voostack.com/s/learningmatter-mit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.