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:
- Setup Guide: AskCOS Core GitHub Repository
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:
- Set up local AskCOS following the installation guide above
- Update the
ASKCOS_BASE_URL
in the agent configuration - Modify
paramus/agents/synthesis_agent/tools/askcos_tools.py
- Change from
https://askcos.mit.edu/api
to your local URL (e.g.,http://localhost:9999/api
) - 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. |