Metadata-Version: 2.4
Name: search-species
Version: 0.1.0
Summary: A command-line tool that can search for chemical substances through PubChem, OPSIN, and Wikidata, and supports rendering of search results.
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pytest>=9.0.2
Requires-Dist: rdkit>=2025.9.6
Requires-Dist: requests>=2.32.5
Description-Content-Type: text/markdown

# docs for agent skill are written in ./docs4agentSkill

---

# Engine Backends Reference

## Search Backend Comparison Reference

`search-species` integrates three distinct backends for chemical information retrieval. 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. |


### 1. OPSIN (Open Parser for Systematic IUPAC Nomenclature)
* **Capabilities**:
    * **Structure Derivation**: Interprets IUPAC names using grammar-based rules rather than searching a fixed list, allowing it to "build" molecules that may not exist in any database.
    * **Real-time Rendering**: Automatically generates a 2D molecular image based on the parsed structure.
    * **RDKit Integration**: Since OPSIN only returns the structure, `search-species` uses **`rdkit.Chem`** to calculate the **Molecular Formula** and **Relative Atomic Mass** from the resulting SMILES.
* **Deficiencies**:
    * **Strict Nomenclature Only**: Cannot recognize **Common Names** or trade names. For example, it understands `2-acetyloxybenzoic acid` but will fail on `Aspirin`.

### 2. PubChem
* **Capabilities**:
    * **Established Alias Support**: Successfully matches queries against a massive index of common chemical aliases and trade names known in the industry.
    * **Comprehensive Metadata**: Matches queries against the world's largest free chemical database with high reliability for known substances.
    * **Standardized Images**: Provides professional, high-quality 2D structural diagrams for nearly all entries.
* **Deficiencies**:
    * **Scope Limited to Knowns**: Cannot interpret or generate data for molecules that have not been cataloged in the NCBI registry.

### 3. Wikidata
* **Capabilities**:
    * **Common & Multilingual Names**: As a global knowledge graph, it is the primary engine for **Common Names** and non-English terms. It handles vernacular nomenclature across different scripts with high flexibility.
        * *Examples*: `阿司匹林` (Chinese), `アスピリン` (Japanese), `Аспирин` (Russian), `Aspirin` (German/English).
* **Deficiencies**:
    * **Image Scarcity**: Unlike specialized chemical databases, Wikidata entries frequently lack standard molecular diagrams or structural images.
    * **Disabled Cross-Indexing**: Although Wikidata acts as a hub for IDs (CAS, ChemSpider, etc.), cross-database indexing is **not currently enabled** in this tool. It will only return data natively stored in Wikidata.
* **Data Processing Note (Character Normalization)**:
    * Unlike standard chemical databases, raw Wikidata entries often contain non-standard Unicode formatting. `search-species` automatically cleanses these formulas into standard ASCII. 
    * *Note*: This means the tool's normalized output will look different from a direct web search on Wikidata.
        * **Sub/Superscripts**: $₀₁₂₃₄₅₆₇₈₉$ and $⁰¹²³⁴⁵⁶⁷⁸⁹$ $\to$ `0-9`
        * **Charges & Symbols**: $⁺ ⁻ ·$ $\to$ `+ - *`
        * *Example Conversion*: $Fe³⁺$ $\to$ `Fe3+` ; $CuSO₄·5H₂O$ $\to$ `CuSO4*5H2O`


## Current Scope & Limitations

**⚠️ Important**: `search-species` is focused on core structural identification. The following data points are **NOT** provided:
* ❌ Physical properties (Melting point, Solubility, etc.)
* ❌ Toxicity/Safety data (MSDS)
* ❌ Literature references and Patent links

**Currently Supported Data Fields**:
1.  **Name**: Primary common or systematic name.
2.  **Formula**: Normalized ASCII molecular formula.
3.  **Relative Atomic Mass**: Numerical mass value.
4.  **SMILES**: Canonical structural string.
5.  **Molecular Image**: Visual 2D structure (where available).

---

# Render Module Reference

The `render` module is responsible for taking the structured JSON outputs from the search engines and converting them into a unified, human-readable visual gallery (grid of cards).

## 1. Input Handling & Dependencies
* **JSON-Driven**: The renderer takes paths to `.json` candidate files as its primary input.
* **⚠️ Image Locality (Strict Constraint)**: The module expects the associated 2D structure image to be located in the **exact same directory** as the `.json` file. **Do not move or isolate the JSON files** from their original output directory before rendering. If the image is not found alongside the JSON, the renderer will automatically fallback to an "Image Not Found" placeholder.
* **Fault Tolerance**: Invalid JSON paths or corrupted files are safely skipped with a warning. The rendering process will continue for the remaining valid candidates.

## 2. Card Layout & Grid System
Instead of generating individual image files for each candidate, the module aggregates them into a single comprehensive gallery image.
* **Grid Format**: Cards are arranged in a dynamic multi-column grid. The number of rows scales automatically based on the input count.
* **Card Structure**: Each card has a fixed layout containing:
  * **Left side**: A bounded area for the 2D molecular structure. Original images are proportionally scaled to fit without distortion.
  * **Right side**: A text area displaying the extracted metadata.

## 3. Displayed Data & Constraints
Each card visually displays the following properties:
1. Candidate Index
2. Source Engine (PubChem, OPSIN, or Wikidata)
3. Name
4. Formula
5. Weight (Relative Atomic Mass)
6. SMILES

**⚠️ Important Constraints (Data Truncation):**
To prevent text from breaking the visual layout, strings are strictly managed. Any single property string exceeding the maximum character limit is forcibly truncated. This is highly relevant for **SMILES** strings of large macromolecules, which may not be fully visible on the rendered card. (The complete SMILES is still preserved in the source JSON).

## 4. Output Convention
* **File Naming**: The final merged gallery image is saved using a timestamped format to prevent overwriting previous renders: 
  `renderResult_YYYYMMDDHHMMSS_{number_of_cards}.png`
* **Return Value**: Upon successful execution, the CLI prints the absolute path of the generated gallery image.