v0.1.0 to v0.1.0

10 added, 40 removed. Audit A to A.

---

name: search-species

- description: 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.

+ description: >

+ 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.

compatibility: Requires `uv` installed.

metadata:

author: light-cyan

version: 0.1.0

repository: https://github.com/light-cyan/search-species

---

# Search Species

- This toolkit consists of **two core tools**—`search` and `render`—designed to retrieve chemical structural information and generate visual species cards.

## 🔄 Core Workflow (CRITICAL)

- When assisting users with chemical searches, you **MUST** adhere to the following step-by-step workflow:

+ When assisting users with chemical searches, you **MUST** adhere to the following step-by-step workflow. **Note: Searching can be highly time-consuming; always prioritize efficiency.**

1. **Acquire Target**: Identify the chemical name, identifier, or SMILES the user wants to query.

- 1. **Select Engine**: Choose the most appropriate search backend (`pubchem`, `opsin`, `wikidata`, or `all`) based on the query type.

- 1. **Execute Search**: Use the `search` command to query the database.

- 1. **Evaluate Results**: Carefully review the returned summary data and candidate JSON file paths in the output. **Do not blindly render all results.**

- 1. **Render Card**: Select the most accurate candidate JSON file and use the `render` command to generate a visual species card.

- 1. **Confirm & Iterate**: Present the generated card/data to the user for confirmation. If the result is ambiguous or incorrect, communicate with the user to adjust the search keywords and restart the process.

+ 1. **Select Engine**: Choose the most targeted search backend (`pubchem`, `opsin`, `wikidata`, or `all`) based on the query type. Avoid using `all` unless strictly necessary, to minimize search times.

+ 1. **Execute Search**: Use the `search` command to query the database. You must set an appropriate `max_cands` limit to prevent excessively long processing times and reduce data noise.

+ 1. **Evaluate Results**: Carefully review the returned summary data in the output.

+ 1. **Confirm & Iterate**: Present the retrieved data to the user for confirmation. If the result is ambiguous or incorrect, communicate with the user to adjust the search keywords and restart the process.

______________________________________________________________________

## Search Backend Overview

`search-species` integrates three distinct backends. Each serves a specific purpose in the chemical informatics workflow:

| :------------------ | :----------------------------- | :------------------------ | :------------------------------ |

- *(For detailed engine capabilities, limitations, and data normalization behavior, see `reference/backends.md`)*

+ *(For more detailed engine capabilities, limitations, and data normalization behavior, see `reference/backends.md`)*

## Quick Start & Command Outputs

Typical search syntax:

```bash

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:

```bash

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`).

- ## Core Tasks

- ### 1) Universal search

- Search across all available backends (PubChem, OPSIN, and Wikidata) for a common name:

- ```bash

- uvx search-species all "Aspirin"

- ```

- ### 2) Engine-specific searches

+ ## Example

**PubChem** (Standard database lookups):

```bash

uvx search-species pubchem "benzene" 5 -o ./results

```

**OPSIN** (Theoretical molecules & strict IUPAC):

```bash

uvx search-species opsin "2-acetyloxybenzoic acid"

```

**Wikidata** (Multilingual & common/trade names):

```bash

uvx search-species wikidata "Аспирин"

uvx search-species wikidata "TNT"

```

- ### 3) Render species cards

- Generate visual image cards from specific JSON files (selected after reviewing search results):

- ```bash

- 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):

- ```bash

- uvx --from search-species render-species ./cache/*.json -o ./gallery

- ```

## Agent Checklist

When using this toolkit for users, ensure you cross-check these points with the Core Workflow:

- **Engine Match:** Match the engine to the query type based on the overview table.

- **Data Scope:** Remember this tool *only* retrieves structural identity (Name, Formula, Mass, SMILES, 2D Image).

- **Fallback:** If `pubchem` fails on a systematic name, fallback to `opsin`.

- - **Selective Rendering:** Evaluate the printed data from the `search` command output before passing specific paths to the `render` command.

- **Quoting:** Always wrap the chemical `<query>` in quotes.

## References

- Engine Details & Limitations: `reference/backends.md`

- - Render Rules & Constraints: `reference/render.md`