Organic Chemistry Agent

Documentation for the paramus.ai Organic Chemistry Agent, currently including ASKCOS from MIT for retrosynthetic analysis and synthetic route planning.

Documentation Index or back to Homepage

Known Issue

The AskCOS public API is currently experiencing availability issues. You may see error messages like:

"Synthesis encountered an issue accessing the AskCOS API and will skip the task."

This is expected behavior when the external API is unavailable.

Recommended: Local AskCOS Installation

For reliable functionality, we recommend setting up a local AskCOS instance:

A local installation will eliminate the API connectivity issues described below and provide more reliable synthesis planning capabilities.

Test Examples (When API is Available)

Try these examples to verify the agent is working when the AskCOS API is accessible:

Test Type Purpose Example Query Expected Behavior
Basic Retrosynthesis Verify retrosynthetic analysis functionality
Can you find synthesis routes for ethanol? Target: CCO
                            
Should return multiple routes with precursors like acetaldehyde (CC=O). If API is down, will show skip message.
                            
Forward Prediction Test product prediction capabilities
What happens when I react benzene with acetyl chloride? 
Reactants: C1=CC=CC=C1.CC(=O)Cl
                            
Should predict acetophenone as main product. Common test for Friedel-Crafts functionality.
                            
Atom Mapping Verify reaction mapping tools
Map the atoms in this reaction:
Reactants: CC(=O)Cl.c1ccccc1  
Products: CC(=O)c1ccccc1.Cl
                            
Should return atom-mapped SMILES with numbered atoms showing connectivity changes.
                            

AskCOS Tools (Full API Dependent)

Tool Name Description Example Prompt Expected Response Pattern
AskCOSRetrosynthesis Find synthetic routes for simple molecules using retrosynthetic analysis.
Can you help me find synthesis routes for ethanol? I need to understand what precursors are available.

Target molecule: CCO
                            
Retrosynthetic Analysis for CCO:

Route 1:
Score: 0.95
Precursors: CC=O
Reaction Template: reduction

Route 2: 
Score: 0.87
Precursors: CC(=O)O
Reaction Template: decarboxylation

Task complete.
                            
AskCOSRetrosynthesis Analyze synthetic routes for pharmaceutical compounds.
I need to plan the synthesis of aspirin for my chemistry class. What are the main synthetic approaches?

Target: CC(=O)OC1=CC=CC=C1C(=O)O
                            
Retrosynthetic Analysis for CC(=O)OC1=CC=CC=C1C(=O)O:

Route 1:
Score: 0.89
Precursors: OC1=CC=CC=C1C(=O)O, CC(=O)O
Reaction Template: esterification

Route 2:
Score: 0.75
Precursors: OC1=CC=CC=C1C(=O)O, CC(=O)Cl
Reaction Template: acylation

Task complete.
                            
AskCOSForwardSynthesis Predict products of simple organic reactions.
What products would I get from the reaction of benzene with acetyl chloride? This is for a Friedel-Crafts reaction.

Reactants: C1=CC=CC=C1.CC(=O)Cl
                            
Forward Synthesis Prediction for C1=CC=CC=C1.CC(=O)Cl:

Outcome 1:
Product: CC(=O)C1=CC=CC=C1
Probability: 0.924
Template: friedel_crafts

Outcome 2:
Product: C1=CC=CC=C1
Probability: 0.076
Template: no_reaction

Task complete.
                            
askcos_atom_mapping Generate atom mapping for simple reactions.
I need to understand the atom mapping for the Friedel-Crafts acylation. Can you map the atoms?

Reactants: CC(=O)Cl.c1ccccc1
Products: CC(=O)c1ccccc1.Cl
                            
Atom-mapped reaction: [CH3:1][C:2](=[O:3])[Cl:4].[c:5]1[cH:6][cH:7][cH:8][cH:9][cH:10]1>>[CH3:1][C:2](=[O:3])[c:5]1[cH:6][cH:7][cH:8][cH:9][cH:10]1.[Cl:4]

Task complete.
                            
askcos_reaction_similarity Find similar reactions for comparison and literature search.
I'm looking for similar reactions to this Friedel-Crafts acylation. Can you find related reactions?

Reaction: CC(=O)Cl.c1ccccc1>>CC(=O)c1ccccc1.Cl
                            
Similar reactions to CC(=O)Cl.c1ccccc1>>CC(=O)c1ccccc1.Cl:

1. Reaction: CC(=O)Cl.c1ccc(C)cc1>>CC(=O)c1ccc(C)cc1.Cl
   Similarity: 0.892
   Reference: Similar acylation

2. Reaction: CC(=O)Br.c1ccccc1>>CC(=O)c1ccccc1.Br
   Similarity: 0.856
   Reference: Bromide leaving group

Task complete.
                            
askcos_site_selectivity Predict regioselectivity in substitution reactions.
I need to predict the regioselectivity for the acylation of toluene. Which position will be preferred?

Substrate: c1ccccc1C
Reagents: CC(=O)Cl
                            
Site selectivity prediction for c1ccccc1C:

Site 1:
  Atom index: 2
  Score: 0.678
  Product: CC(=O)c1ccccc1C

Site 2:
  Atom index: 4
  Score: 0.432
  Product: CC(=O)c1ccc(C)cc1

Task complete.
                            

Troubleshooting & Limitations

Common Issues

Issue Solution
Agent Skips Task
Problem: "Synthesis encountered an issue accessing the AskCOS API and will skip the task"
Solution: 
- This is the most common current issue
- The AskCOS public API may be down or restricted
- Check https://askcos.mit.edu/ for service status
- Try again later - API availability varies
- This is expected behavior, not a bug
                            
API Connection Error
Problem: "Network error accessing AskCOS"
Solution: 
- Check internet connection
- Verify AskCOS server status
- Try again after a brief wait
- The public API has rate limits
                            
Invalid SMILES
Problem: "AskCOS API error: Invalid SMILES"
Solution:
- Verify SMILES string format
- Use simple canonical SMILES
- Check for typos in molecular structure
- Try a chemistry structure validator first
                            
No Routes Found
Problem: "No synthetic routes found for [molecule]"
Solution:
- The molecule may be too complex for public API
- Try simpler fragments of the molecule
- Some molecules may not be in the database
- Consider alternative retrosynthetic approaches
                            
Timeout Errors
Problem: Request times out after 30 seconds
Solution:
- Complex molecules take longer to process
- Try again with simpler structures
- The public API has processing limits
- Consider breaking down the problem
                            

Configuring Local AskCOS

To configure the synthesis agent to use your local AskCOS instance:

  1. Set up local AskCOS following the installation guide above
  2. Update the ASKCOS_BASE_URL in the agent configuration
  3. Modify paramus/agents/synthesis_agent/tools/askcos_tools.py
  4. Change from https://askcos.mit.edu/api to your local URL (e.g., http://localhost:9999/api)
  5. Restart the Paramus system to apply changes

This will provide reliable synthesis planning without dependency on external API availability.

Future Features (Advanced Examples)

Note: The following examples represent advanced capabilities that may require enhanced API access or future development. They are included for reference and planning purposes.

Advanced Feature Example Query
Multi-Step Natural Product Synthesis
Query: "Design a complete synthetic strategy for taxol starting from simple 
precursors. Include stereochemical considerations and protecting group strategies."

Status: Requires enhanced computational resources and extended API access.
May work for simpler natural products.
                            
Reaction Condition Optimization
Query: "For the synthesis of compound X, what are the optimal reaction conditions 
including temperature, solvent, and catalyst loading?"

Status: Current API focuses on connectivity, not detailed conditions.
Future versions may include reaction condition prediction.
                            
Cost and Availability Analysis
Query: "Compare the costs and commercial availability of starting materials 
for different synthetic routes to aspirin."

Status: Requires integration with chemical supplier databases.
Not currently available through public API.
                            
Safety Assessment
Query: "Evaluate the safety profiles of intermediates and reagents in this 
synthetic route. Identify any particularly hazardous steps."

Status: Requires safety database integration.
Currently limited to basic chemical structure analysis.
                            
Environmental Impact Analysis
Query: "Calculate the environmental impact and green chemistry metrics 
for this synthetic route."

Status: Requires specialized environmental databases.
Future feature for sustainable chemistry applications.