> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pranavkrishnasuresh/chemAgent/llms.txt
> Use this file to discover all available pages before exploring further.
# Chemistry Tags
> Master the tag system for structuring chemistry queries in ChemAgent
ChemAgent uses a specialized tag system to precisely identify and structure chemical information in queries. Understanding these tags is essential for effective interaction with the system.
## Why Tags Matter
Tags serve three critical purposes:
Clearly identify which strings are chemical entities vs. natural language
Inform the LlaSMol model about the type of chemical information provided
Enable automatic SMILES canonicalization and validation
## Input Tags
Two tags are used to wrap chemical information in **queries**:
### `` Tag
Wraps SMILES (Simplified Molecular Input Line Entry System) strings:
```xml theme={null}
CCO
```
**Usage**:
```python theme={null}
query = "What is the molecular formula of CC(C)Cl ?"
```
**Characteristics**:
* Triggers automatic canonicalization via RDKit
* Must contain valid SMILES syntax
* Can represent any molecular structure
See plan\_execute\_agent/chem\_tools.py:26 for SMILES handling.
### `` Tag
Wraps IUPAC (International Union of Pure and Applied Chemistry) names:
```xml theme={null}
aspirin
```
**Usage**:
```python theme={null}
query = "Provide the SMILES for 4-ethyl-4-methyloxolan-2-one ."
```
**Characteristics**:
* Accepts systematic IUPAC names
* Also accepts common names (aspirin, caffeine, etc.)
* Whitespace and capitalization are preserved
See plan\_execute\_agent/chem\_tools.py:22 for IUPAC handling.
## Output Tags
Three tags appear in **model responses** from LlaSMol:
### `` Tag
Wraps molecular formulas:
```xml theme={null}
C9H8O4
```
**Example Response**:
```
Query: "What is the molecular formula of aspirin ?"
Response: " C9H8O4 "
```
See LLM4Chem/README.md:27 for examples.
### `` Tag
Wraps numerical predictions (solubility, logD, etc.):
```xml theme={null}
-1.41
```
**Example Response**:
```
Query: "How soluble is CC(C)Cl ?"
Response: "Its log solubility is -1.41 mol/L."
```
See LLM4Chem/README.md:56 for examples.
### `` Tag
Wraps yes/no predictions (toxicity, BBB permeability, etc.):
```xml theme={null}
Yes
```
or
```xml theme={null}
No
```
**Example Response**:
```
Query: "Is COC[C@@H](NC(C)=O)C(=O)NCC1=CC=CC=C1 toxic?"
Response: " No "
```
See LLM4Chem/README.md:77 for examples.
## Automatic Tagging
ChemAgent includes the `structure_chem_prompt` tool that automatically adds tags to unstructured queries:
### How It Works
```python theme={null}
@tool
def structure_chem_prompt(original_prompt):
"""Structure and tag IUPAC or SMILES chemical information."""
response = client.beta.chat.completions.parse(
model="gpt-4o",
messages=[{
"role": "system",
"content": SYSTEM_TAG_PROMPT,
}, {
"role": "user",
"content": f"Structure the input query: {original_prompt}",
}],
response_format=StructuredPrompt,
)
return {"new_prompt": simplified_prompt.get("new_prompt")}
```
See plan\_execute\_agent/chem\_tools.py:57 for implementation.
### System Prompt
The tagging tool uses a detailed system prompt:
```python theme={null}
SYSTEM_TAG_PROMPT = """
You are an EXPERT chemical information tagger. Your task is to format the input query
based on the information below. You MUST return ONLY the formatted input query!
When processing chemical information, use only two tags in the input query:
for SMILES representations and for IUPAC names.
Tag Definitions:
SMILES: ... for chemical structure in SMILES notation.
IUPAC: ... for the IUPAC name of the compound.
Instructions:
1. In the input query, use only the and tags to wrap the appropriate information.
2. Ensure no extra characters or spaces are present within the tags.
"""
```
See plan\_execute\_agent/chem\_tools.py:7 for the complete prompt.
### Tagging Examples
```python Input - No Tags theme={null}
"What is the molecular formula of aspirin?"
```
```python Output - Tagged theme={null}
"What is the molecular formula of aspirin ?"
```
```python Input - Mixed theme={null}
"Can you tell me the IUPAC name of C1CCOC1?"
```
```python Output - Tagged theme={null}
"Can you tell me the IUPAC name of C1CCOC1 ?"
```
```python Input - Complex theme={null}
"What is the molecular formula of 2,5-diphenyl-1,3-oxazole and what is the name of C1CCOC1?"
```
```python Output - Tagged theme={null}
"What is the molecular formula of 2,5-diphenyl-1,3-oxazole and what is the name of C1CCOC1 ?"
```
## SMILES Canonicalization
When SMILES are wrapped in tags, they are automatically canonicalized using RDKit:
### What is Canonicalization?
SMILES strings can represent the same molecule in multiple ways:
```python theme={null}
# All represent ethanol
"CCO" # Start from carbon
"OCC" # Start from oxygen
"C(O)C" # Explicit branching
```
Canonicalization converts all variants to a standard form:
```python theme={null}
from rdkit import Chem
mol = Chem.MolFromSmiles("OCC")
canonical = Chem.MolToSmiles(mol)
print(canonical) # Output: "CCO"
```
### Automatic Process
The LlaSMol generation pipeline handles this automatically:
```python theme={null}
def canonicalize_smiles_in_text(text: str) -> str:
"""Find tags and canonicalize their contents."""
pattern = r'\s*([^<]+)\s*'
def replace_smiles(match):
smiles = match.group(1).strip()
mol = Chem.MolFromSmiles(smiles)
if mol is None:
return match.group(0) # Keep original if invalid
canonical = Chem.MolToSmiles(mol)
return f" {canonical} "
return re.sub(pattern, replace_smiles, text)
```
See LLM4Chem/utils/smiles\_canonicalization.py for implementation.
### Benefits
The model receives standardized input regardless of how users write SMILES
Training and inference use the same canonical form, improving predictions
Canonicalization fails for invalid SMILES, providing early error detection
## Properly Formatted Query Examples
Here are complete examples showing correct tag usage:
### Name Conversion Queries
```python theme={null}
query = "Please provide the SMILES representation for 4-ethyl-4-methyloxolan-2-one ."
```
Expected response:
```
"Of course. It's CCC1(C)COC(=O)C1 ."
```
```python theme={null}
query = "Translate CCC(C)C1CNCCCNC1 to its IUPAC name."
```
Expected response:
```
" 3-butan-2-yl-1,5-diazocane "
```
```python theme={null}
query = "What is the molecular formula for S=P1(N(CCCl)CCCl)NCCCO1 ?"
```
Expected response:
```
"It is C7H15Cl2N2OPS ."
```
```python theme={null}
query = "What is the molecular formula of 2,5-diphenyl-1,3-oxazole ?"
```
Expected response:
```
" C15H11NO "
```
### Property Prediction Queries
```python theme={null}
query = "How soluble is CC(C)Cl ?"
```
Expected response:
```
"Its log solubility is -1.41 mol/L."
```
```python theme={null}
query = "Is COC[C@@H](NC(C)=O)C(=O)NCC1=CC=CC=C1 toxic?"
```
Expected response:
```
" No "
```
```python theme={null}
query = "Is blood-brain barrier permeability a property of CCNC(=O)/C=C/C1=CC=CC(Br)=C1 ?"
```
Expected response:
```
" Yes "
```
### Molecule Description Queries
```python theme={null}
query = "Describe this molecule: CCOC(=O)C1=CN=CN1[C@H](C)C1=CC=CC=C1 "
```
Expected response:
```
"The molecule is an imidazole derivative with short-acting sedative, hypnotic,
and general anesthetic properties..."
```
```python theme={null}
query = """Give me a molecule that satisfies: The molecule is a red-coloured pigment
with antibiotic properties. It has a role as an antimicrobial agent."""
```
No tags needed in description for molecule generation
Expected response:
```
"Here is a potential molecule: CCCCCC1=C(C)NC(/C=C2\N=C(C3=CC=CN3)C=C2OC)=C1 "
```
## Tag Validation
The system validates tags at multiple stages:
### 1. Structure Validation
GPT-4o ensures tags are correctly formatted:
```python theme={null}
class StructuredPrompt(BaseModel):
new_prompt: str # Must contain properly closed tags
```
See plan\_execute\_agent/chem\_tools.py:51 for validation.
### 2. SMILES Validation
RDKit validates SMILES content:
```python theme={null}
@tool
def validate_smiles_rdkit(smiles_string: str) -> dict:
"""Validate SMILES with detailed error reporting."""
parsing_details = parse_smiles(smiles_string)
return {
"valid": parsing_details["valid"],
"error_message": parsing_details["validity_vector"],
}
```
See plan\_execute\_agent/chem\_tools.py:180 for validation logic.
### 3. Output Extraction
The system extracts content between tags in responses:
```python theme={null}
import re
def extract_smiles(response: str) -> str:
"""Extract SMILES from tagged response."""
match = re.search(r'\s*([^<]+)\s*', response)
return match.group(1).strip() if match else ""
```
See LLM4Chem/extract\_prediction.py for extraction logic.
## Common Mistakes
**Avoid These Common Errors**:
### ❌ Incorrect: Missing Tags
```python theme={null}
query = "What is the SMILES for aspirin?"
# LlaSMol won't know "aspirin" is a chemical name
```
### ✅ Correct: Tagged IUPAC
```python theme={null}
query = "What is the SMILES for aspirin ?"
```
***
### ❌ Incorrect: Spaces in Tags
```python theme={null}
query = "Formula of < SMILES > CCO < /SMILES >?"
# Tag parser will fail
```
### ✅ Correct: No Extra Spaces
```python theme={null}
query = "Formula of CCO ?"
```
***
### ❌ Incorrect: Wrong Tag Type
```python theme={null}
query = "What is the IUPAC name of CCO ?"
# CCO is SMILES, not IUPAC
```
### ✅ Correct: Proper Tag Type
```python theme={null}
query = "What is the IUPAC name of CCO ?"
```
***
### ❌ Incorrect: Unclosed Tags
```python theme={null}
query = "Is CC(C)Cl toxic?"
# Missing closing tag
```
### ✅ Correct: Closed Tags
```python theme={null}
query = "Is CC(C)Cl toxic?"
```
## Best Practices
Let `structure_chem_prompt` handle tagging when possible:
```python theme={null}
# Agent automatically calls:
structured = structure_chem_prompt("What is aspirin's formula?")
# Result: "What is the molecular formula of aspirin ?"
```
Ensure chemical entities use the correct tag:
* Use `` for: `CCO`, `c1ccccc1`, `CC(=O)O`
* Use `` for: `ethanol`, `benzene`, `acetic acid`
Always validate SMILES outputs:
```python theme={null}
response = answer_chemistry_query(query)
validation = validate_smiles_rdkit(extract_smiles(response))
if not validation["valid"]:
# Handle error and replan
```
* Common names (aspirin) → Use ``
* Systematic names (2-acetoxybenzoic acid) → Use ``
* Abbreviations (EtOH) → Convert to SMILES first
## Tag System in Context
The complete tag workflow in ChemAgent:
```mermaid theme={null}
graph LR
A[User Query] --> B[structure_chem_prompt]
B --> C{Tags Added}
C --> D[Canonicalize SMILES]
D --> E[answer_chemistry_query]
E --> F{Response with Tags}
F --> G[Extract Tagged Content]
G --> H[validate_smiles_rdkit]
H --> I{Valid?}
I -->|Yes| J[Return to User]
I -->|No| K[Replan with Error Info]
K --> B
```
## Next Steps
Learn about the model that uses these tags
See how tags fit into the agent cycle