SmileSherlock

A high-performance, production-grade tool for SMILES validation, PubChem lookup, and chemical structure retrieval.

Features

• SMILES Validation & Canonicalization - Validate and standardize SMILES strings using RDKit
• Multi-format Input - Support for CSV, TSV, XLSX, SMI, SDF, and TXT files
• Smart Auto-detection - Automatically identify SMILES columns
• PubChem Lookup - Search by SMILES, CID, Name, InChI, and InChIKey
• Rich Metadata - Retrieve IUPAC name, molecular formula, mass, descriptors
• Structure Downloads - Get 2D/3D SDF, MOL, PDB, and PNG formats
• Batch Processing - Process hundreds of compounds with progress tracking
• Async/Multithreading - Fast parallel downloads with retry logic
• Caching - SQLite database for storing results locally
• Multiple Exports - Save results as CSV, Excel, or JSON
• Python API - Use directly in your scripts via smilesherlock module
• CLI Tool - Full-featured command-line interface with smilesherlock command

Installation

From PyPI

pip install smilesherlock

Development Installation

Clone the repository and install in editable mode:

git clone https://github.com/AtharvaTilewale/SmileSherlock.git
cd SmileSherlock
pip install -e ".[dev]"

Quick Start

CLI Usage

# Show configuration and status
smilesherlock status

# Initialize directories and database
smilesherlock init

# Lookup a single compound
smilesherlock lookup "c1ccccc1"  # Benzene
smilesherlock lookup 5282253 --cid

# Batch process a file
smilesherlock batch compounds.csv --output results.xlsx --format xlsx

# Download structure
smilesherlock download 5282253 --format sdf --3d

Python API

from smilesherlock import lookup, lookup_file, download_structure

# Lookup single compound
result = lookup("c1ccccc1")
print(result.cid, result.iupac_name)

# Process file
results = lookup_file("compounds.csv", output_format="xlsx")

# Download structure
download_structure(5282253, format="sdf", dimension="3d")

For more detailed API documentation, see the API Reference page.

Documentation

For complete tutorials and advanced usage examples, see the Practical Guide or visit the official documentation on Read the Docs.

Requirements

• Python 3.10+
• RDKit (cheminformatics library)
• pandas (data handling)
• requests/aiohttp (HTTP)
• typer (CLI framework)
• rich/tqdm (UI/progress)

Configuration

For configuration and architecture details, see the Configuration & Architecture page.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For more details, see the Contributing Guide.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use SmileSherlock in your research, please cite:

@software{smilesherlock2026,
  author={Atharva Tilewale},
  title={SmileSherlock: High-performance SMILES validation and PubChem lookup},
  version={1.1.0},
  year={2026},
  url={https://github.com/AtharvaTilewale/SmileSherlock}
}

Support

• Documentation: https://smilesherlock.readthedocs.io
• Issues: https://github.com/AtharvaTilewale/SmileSherlock/issues
• Discussions: https://github.com/AtharvaTilewale/SmileSherlock/discussions

Changelog

See CHANGELOG.md for version history.

Made with ❤️ for the cheminformatics community