USE WHEN requesting core chemical structural data (SMILES, formula, mass, 2D images) via IUPAC, common, or multilingual names. You MUST actively retrieve the data using this skill; DO NOT hallucinate or generate structures yourself. DO NOT USE WHEN asking for physical properties (melting point, solubility), safety/toxicity data (MSDS), or synthesis pathways.
This toolkit consists of two core tools—search and render—designed to retrieve chemical structural information and generate visual species cards.
When assisting users with chemical searches, you MUST adhere to the following step-by-step workflow:
pubchem, opsin, wikidata, or all) based on the query type.search command to query the database.render command to generate a visual species card.search-species integrates three distinct backends. Each serves a specific purpose in the chemical informatics workflow:
| Feature | OPSIN | PubChem | Wikidata |
|---|---|---|---|
| Core Method | Algorithmic Parser | Curated Database | Knowledge Graph |
| Primary Input | IUPAC English Names | Names, CIDs, SMILES | Common & Multilingual Names |
| Molecular Image | Supported (Rendered) | Supported (Stored) | Rarely Available |
| Mass/Formula | Calculated via RDKit | Database Metadata | Database Metadata |
| Key Strength | Handles theoretical molecules. | Highly standardized data. | Vernacular & Cross-lingual. |
(For detailed engine capabilities, limitations, and data normalization behavior, see reference/backends.md)
Typical search syntax:
uvx search-species <engine> "<query>" [max_cands] -o <output_dir>
Output: Prints the retrieved species data summary and the file path where each candidate's JSON is saved (e.g.,
SpeciesCandidate(...) written -> ./cache/xyz.json).
Typical render syntax:
uvx --from search-species render-species <candidate_files...> -o <output_dir>
Output: Prints the file path of the successfully generated image card (e.g.,
Successfully rendered -> ./gallery/xyz.png).
Search across all available backends (PubChem, OPSIN, and Wikidata) for a common name:
uvx search-species all "Aspirin"
PubChem (Standard database lookups):
uvx search-species pubchem "benzene" 5 -o ./results
OPSIN (Theoretical molecules & strict IUPAC):
uvx search-species opsin "2-acetyloxybenzoic acid"
Wikidata (Multilingual & common/trade names):
uvx search-species wikidata "Аспирин"
uvx search-species wikidata "TNT"
Generate visual image cards from specific JSON files (selected after reviewing search results):
uvx --from search-species render-species ./cache/candidate_1.json ./cache/candidate_2.json -o ./gallery
Render all JSON files in a directory (Use with caution):
uvx --from search-species render-species ./cache/*.json -o ./gallery
When using this toolkit for users, ensure you cross-check these points with the Core Workflow:
pubchem fails on a systematic name, fallback to opsin.search command output before passing specific paths to the render command.<query> in quotes.reference/backends.mdreference/render.md