Intelligent synthesis route planning for inorganic materials. Use this skill whenever the user needs a synthesis protocol.
This skill orchestrates synthesis route generation using a strict prioritization:
You MUST attempt mp_search_recipe before considering ML predictions or template_route_generator.
The core philosophy: Literature data is gold. ML predictions are silver. Templates are last resort.
mp_search_recipe — Literature Recipe SearchQueries Materials Project Synthesis Database for experimental synthesis procedures from published literature.
Key parameters:
target_formula: Material composition (e.g., 'LiCoO2', 'BaTiO3')synthesis_type: Filter by method ('solid-state', 'sol-gel', 'hydrothermal', etc.)precursor_formula: Find recipes using specific precursorsformat_routes: If True, automatically converts recipes to standardized routes (eliminates need for separate conversion step!)limit: Maximum number of recipes/routes to return (1-30, default 10). When format_routes=True, this controls the number of formatted routes returned.temperature_min, temperature_max, heating_time_min, heating_time_max: Filter recipes by min/max temperature/time directly in the searchReturns (when format_routes=False):
{
"success": True,
"count": 206, # Number of literature recipes found
"recipes": [
{
"target_formula": "LiCoO2",
"precursors_formula_s": ["Li2CO3", "Co3O4"],
"synthesis_type": "solid-state",
"reaction_string": "0.333 Co3O4 + 0.5 Li2CO3 + 0.083 O2 == 1 LiCoO2 + 0.5 CO2",
"operations": [
{
"type": "heating",
"conditions": {"heating_temperature": [850], "heating_time": [12], "heating_atmosphere": ["air"]}
}
]
}
]
}
Returns (when format_routes=True):
{
"success": True,
"target_composition": "LiCoO2",
"n_routes": 5,
"original_count": 206, # Total recipes found before formatting
"filtered_count": 0, # Number filtered by constraints
"routes": [
{
"route_id": 1,
"source": "literature",
"method": "solid_state",
"confidence": 0.90,
"precursors": [...],
"steps": [
{"step": 1, "action": "mix_and_grind", ...},
{"step": 2, "action": "calcine", "temperature_c": 850, ...}
],
"doi": "10.1234/example",
"basis": "Literature-derived from Materials Project"
}
]
}
When to use format_routes=True vs False:
True when you need standardized synthesis routes ready for execution or planning (most common for synthesis planning)False when you need raw recipe data for analysis, comparison, or custom processing of literature informationlimit parameter controls the number of recipes/routes returned (default 10, max 30)Coverage: ~10-20K materials with literature synthesis data. Common battery materials, perovskites, and simple oxides are well-represented.
er_predict_precursors — ML Precursor Prediction (Solid-State Only)NEW: ML-based precursor prediction using trained neural networks on synthesis literature.
CRITICAL LIMITATION: SOLID-STATE SYNTHESIS ONLY. Cannot be used for hydrothermal, sol-gel, or other synthesis methods.
Key parameters:
target_formula: Material composition (e.g., 'Li7La3Zr2O12', 'BaTiO3')top_k: Number of precursor sets to return (default 5, range 1-20)return_individual: If True, also return individual element predictions (not yet implemented)Returns:
{
"target": "Li7La3Zr2O12",
"precursor_sets": [
{"precursors": ["Li2CO3", "La2O3", "ZrO2"], "confidence": 0.6121},
{"precursors": ["Li2O", "La2O3", "ZrO2"], "confidence": 0.2341},
{"precursors": ["LiOH", "La2O3", "ZrO2"], "confidence": 0.0892}
],
"top_prediction": {"precursors": ["Li2CO3", "La2O3", "ZrO2"], "confidence": 0.6121},
"metadata": {"model": "elemwise_retro", "device": "cpu"}
}
Confidence interpretation:
When to use:
When NOT to use:
er_predict_temperature — ML Temperature Prediction (Solid-State Only)NEW: ML-based synthesis temperature prediction given target and precursors.
CRITICAL LIMITATION: SOLID-STATE SYNTHESIS ONLY. Cannot be used for hydrothermal, sol-gel, or other synthesis methods.
Key parameters:
target_formula: Material composition (e.g., 'Li7La3Zr2O12')precursors: List of precursor formulas (e.g., ['Li2CO3', 'La2O3', 'ZrO2'])Returns:
{
"target": "Li7La3Zr2O12",
"precursors": ["Li2CO3", "La2O3", "ZrO2"],
"temperature_celsius": 908.3,
"temperature_kelvin": 1181.5,
"metadata": {"model": "elemwise_retro", "device": "cpu"}
}
Typical accuracy:
When to use:
er_predict_precursors or other source)When NOT to use:
Element validation:
ValueError if mismatch detectedtemplate_route_generator — Heuristic Route GenerationGenerates template-based synthesis routes using Materials Project precursor data and heuristic process parameters.
Key parameters:
target_material: {'composition': 'LiCoO2'}synthesis_method: 'solid_state', 'hydrothermal', 'sol_gel', or 'auto'constraints: Optional limits (max_temperature, max_time, exclude_precursors, etc.)Returns:
{
"success": True,
"target_composition": "LiCoO2",
"routes": [
{
"method": "solid_state",
"source": "template_with_mp_precursors",
"confidence": 0.40, # Low - unvalidated heuristic
"precursors": [...], # From MP literature for this material
"steps": [...], # From heuristic templates
"requires_review": True, # Human approval needed
"warnings": ["Using 206 recipes from Materials Project for precursor selection"]
}
]
}
Key characteristics:
When templates are used:
IMPORTANT: This is not optional. Always follow this exact sequence.
Complete order you MUST follow:
CRITICAL RULES:
Input: User request for synthesis route of material with formula X
Step 1.1: Determine user's need for output format
IF user needs standardized routes for synthesis planning:
SET format_routes = True
ELSE IF user needs raw recipe data for analysis:
SET format_routes = False
ELSE:
# Default to standardized routes
SET format_routes = True
Step 1.2: Extract any constraints from user request
SET constraints = {
temperature_max: extract_from_request() OR None,
heating_time_max: extract_from_request() OR None,
synthesis_type: extract_from_request() OR None,
keywords: extract_keywords() OR None
}
Step 1.3: Search Materials Project literature database
CALL mp_search_recipe(
target_formula=X,
format_routes=format_routes,
limit=10, # Or user-specified limit
temperature_max=constraints.temperature_max,
heating_time_max=constraints.heating_time_max,
synthesis_type=constraints.synthesis_type
)
STORE result in mp_result
Step 1.4: Check search outcome
IF format_routes == True:
SET found_routes = (mp_result.success AND mp_result.n_routes > 0)
ELSE:
SET found_routes = (mp_result.success AND mp_result.count > 0)
IF found_routes:
GOTO STEP 2A (Literature path)
ELSE:
GOTO STEP 2B (ML prediction path)
Condition: Only execute if Step 1.4 found literature routes
Step 2A.1: Extract route information
IF format_routes == True:
SET routes = mp_result.routes
SET route_count = mp_result.n_routes
SET original_count = mp_result.original_count
ELSE:
SET recipes = mp_result.recipes
SET recipe_count = mp_result.count
Step 2A.2: Validate route quality
FOR each route in routes:
# Routes from literature are high confidence
ASSERT route.source == "literature"
ASSERT route.confidence >= 0.85
# Minimal review required
SET route.requires_intensive_review = False
SET route.autonomous_execution_approved = True # With standard safety checks
Step 2A.3: Format user message
MESSAGE = "Found {original_count} literature synthesis recipes for {target_formula} in Materials Project. "
MESSAGE += "Generated {route_count} validated routes based on actual experimental procedures. "
# Describe recommended route
best_route = routes[0]
MESSAGE += f"Recommended route uses {format_precursors(best_route.precursors)}, "
MESSAGE += f"{best_route.steps[main_step].description}. "
MESSAGE += f"This is a well-established synthesis with high confidence ({best_route.confidence:.2f})."
Step 2A.4: Return result
RETURN {
"success": True,
"source": "literature",
"confidence": "high",
"routes": routes,
"original_recipe_count": original_count,
"route_count": route_count,
"requires_review": "minimal",
"autonomous_execution": "approved_with_safety_checks",
"user_message": MESSAGE
}
Condition: Only execute if Step 1.4 found NO literature routes
IMPORTANT: This path only works for SOLID-STATE synthesis. Skip to Step 2C for other methods.
Step 2B.1: Check if ML prediction is applicable
IF constraints.synthesis_type is specified AND constraints.synthesis_type != "solid-state":
LOG "ML prediction not applicable for {constraints.synthesis_type}"
GOTO STEP 2C (Template fallback)
IF user_request explicitly mentions "hydrothermal", "sol-gel", "CVD", etc.:
LOG "ML prediction only supports solid-state synthesis"
GOTO STEP 2C (Template fallback)
# Default assumption: solid-state for inorganic oxides
SET use_ml = True
Step 2B.2: Predict precursor sets using ML
TRY:
CALL er_predict_precursors(
target_formula=target_formula,
top_k=5
)
STORE result in ml_precursors
EXCEPT Exception:
LOG "ML precursor prediction failed, falling back to templates"
GOTO STEP 2C (Template fallback)
IF ml_precursors.top_prediction.confidence < 0.2:
LOG "Low ML confidence ({confidence}), falling back to templates"
GOTO STEP 2C (Template fallback)
Step 2B.3: Predict synthesis temperature
FOR each precursor_set in ml_precursors.precursor_sets (top 3):
TRY:
CALL er_predict_temperature(
target_formula=target_formula,
precursors=precursor_set.precursors
)
STORE result in ml_temperature
BREAK # Success, use first valid prediction
EXCEPT ValueError as e:
LOG "Element mismatch for {precursor_set}: {e}"
CONTINUE # Try next precursor set
EXCEPT Exception as e:
LOG "Temperature prediction failed: {e}"
CONTINUE
IF no valid ml_temperature:
LOG "All ML temperature predictions failed, falling back to templates"
GOTO STEP 2C (Template fallback)
Step 2B.4: Format ML-based route
SET ml_route = {
"method": "solid_state",
"source": "ml_prediction",
"confidence": ml_precursors.top_prediction.confidence, # 0.2-0.8 typical
"precursors": [
{"compound": prec, "form": infer_form(prec)}
for prec in ml_precursors.top_prediction.precursors
],
"steps": [
{"step": 1, "action": "mix_and_grind", "description": "Mix precursors and grind"},
{
"step": 2,
"action": "calcine",
"description": f"Calcine at {ml_temperature.temperature_celsius}°C",
"temperature_c": ml_temperature.temperature_celsius,
"duration": infer_duration(ml_temperature.temperature_celsius), # Heuristic: 8-16h
"atmosphere": "air" # Default for oxides
}
],
"requires_review": True,
"ml_metadata": {
"precursor_confidence": ml_precursors.top_prediction.confidence,
"alternative_precursors": ml_precursors.precursor_sets[1:3],
"temperature_uncertainty": "±50-100°C"
},
"warnings": [
"ML-predicted route (not experimentally validated for this composition)",
f"Precursor confidence: {ml_precursors.top_prediction.confidence:.2f}",
"Temperature prediction has ±50-100°C uncertainty",
"Small-scale test recommended before scale-up"
]
}
Step 2B.5: Format user message
MESSAGE = f"No literature synthesis found for {target_formula}. "
MESSAGE += f"Generated ML-predicted solid-state route using neural network trained on synthesis literature.\n\n"
MESSAGE += f"**Predicted precursors** (confidence: {ml_precursors.top_prediction.confidence:.2f}):\n"
for prec in ml_precursors.top_prediction.precursors:
MESSAGE += f" - {prec}\n"
MESSAGE += f"\n**Predicted temperature**: {ml_temperature.temperature_celsius}°C (±50-100°C uncertainty)\n\n"
MESSAGE += f"This is a data-driven prediction with medium confidence ({ml_route['confidence']:.2f}). "
MESSAGE += "Recommended to cross-check with similar materials in literature and test at small scale first.\n\n"
MESSAGE += "**Alternative precursor sets:**\n"
for i, alt in enumerate(ml_precursors.precursor_sets[1:3], 2):
MESSAGE += f" {i}. {alt['precursors']} (confidence: {alt['confidence']:.2f})\n"
Step 2B.6: Return ML-predicted route
RETURN {
"success": True,
"source": "ml_prediction",
"confidence": "medium",
"routes": [ml_route],
"requires_review": "recommended",
"autonomous_execution": "with_validation",
"warnings": [
"ML-predicted route, not experimentally validated",
"Cross-reference with similar materials recommended",
"Small-scale test advised"
],
"user_message": MESSAGE
}
Condition: Execute if Step 2B (ML) failed, inapplicable, or low confidence
WARNING: This path generates unvalidated heuristic routes that REQUIRE human review
Step 2C.1: Log ML/literature search failure
LOG "WARNING: No literature routes found for {target_formula}"
LOG "Falling back to template-based generation (low confidence)"
Step 2C.2: Determine synthesis method
IF user specified method:
SET method = user_specified_method
ELSE IF constraints.temperature_max < 400:
SET method = "hydrothermal" # Prefer low-temp method
ELSE:
SET method = "auto" # Let template generator decide
Step 2C.3: Generate template routes
CALL template_route_generator(
target_material={"composition": target_formula},
synthesis_method=method,
constraints=constraints
)
STORE result in template_result
Step 2C.4: Validate template output and add warnings
FOR each route in template_result.routes:
# Template routes are low confidence
ASSERT route.source == "template_with_mp_precursors"
ASSERT route.confidence <= 0.50
# Add mandatory warnings
IF route.warnings is None:
SET route.warnings = []
APPEND "No literature or ML precedent found for this composition" to route.warnings
APPEND "Template based on heuristics - experimental validation required" to route.warnings
APPEND "DO NOT execute without expert review" to route.warnings
# Flag for mandatory review
SET route.requires_review = True
SET route.requires_expert_validation = True
SET route.autonomous_execution_approved = False
Step 2C.5: Format user warning message
MESSAGE = "⚠️ WARNING: No literature synthesis or ML prediction succeeded for {target_formula}. "
MESSAGE += "Generated template-based route using heuristics and precursor data from similar materials. "
MESSAGE += "\n\n**This route has NOT been validated experimentally** "
MESSAGE += "(confidence: {route.confidence:.2f}) and requires expert review before execution.\n\n"
MESSAGE += "Recommended starting point: {format_precursors(route.precursors)}, "
MESSAGE += "{route.steps[main_step].description}.\n\n"
MESSAGE += "**SAFETY REQUIREMENTS:**\n"
MESSAGE += "1. Expert review by materials scientist\n"
MESSAGE += "2. Literature search for similar materials\n"
MESSAGE += "3. Small-scale test (mg quantities) first\n"
MESSAGE += "4. Phase characterization plan (XRD, etc.)\n\n"
MESSAGE += "Consider searching for related compositions with known synthesis routes."
Step 2C.6: Return result with warnings
RETURN {
"success": True,
"source": "template",
"confidence": "low",
"routes": template_result.routes,
"requires_review": "MANDATORY",
"autonomous_execution": "FORBIDDEN",
"warnings": [
"No literature or ML precedent found",
"Template-based heuristics only",
"Expert validation required before execution",
"High risk of incorrect conditions or wrong phase"
],
"safety_requirements": [
"Expert review required",
"Small-scale test mandatory",
"Characterization plan needed"
],
"user_message": MESSAGE
}
Error Type 1: MP API failure in Step 1
IF mp_search_recipe fails with NetworkError:
TRY:
RETRY with exponential backoff (max 3 attempts)
EXCEPT all retries failed:
RETURN {
"success": False,
"error": "Materials Project API unavailable",
"recommendation": "Try again later or use cached data if available"
}
Error Type 2: Invalid formula
IF mp_search_recipe fails with FormulaError:
RETURN {
"success": False,
"error": "Invalid chemical formula: {target_formula}",
"recommendation": "Check formula formatting (e.g., 'LiCoO2' not 'Li1Co1O2')"
}
Error Type 3: Template generation failure
IF template_route_generator fails:
RETURN {
"success": False,
"error": "Cannot generate template route",
"recommendation": "Search for similar materials with known synthesis or consult literature"
}
High Confidence (0.85-1.0):
Medium Confidence (0.50-0.84):
Low Confidence (0.0-0.49):
# User: "Generate a synthesis route for LiCoO2"
# Single-step approach with format_routes=True
routes_result = mp_search_recipe(
target_formula="LiCoO2",
format_routes=True,
limit=5 # Controls number of routes returned
)
# Result: Directly returns standardized routes!
# {
# "success": true,
# "n_routes": 5,
# "original_count": 206,
# "routes": [...] # Fully formatted routes
# }
# Return high-confidence literature routes
# routes_result["routes"][0]:
# {
# "method": "solid_state",
# "source": "literature",
# "confidence": 0.90,
# "precursors": [
# {"compound": "Li2CO3", "amount": None, "form": "carbonate"},
# {"compound": "Co3O4", "amount": None, "form": "oxide"}
# ],
# "steps": [
# {"step": 1, "action": "MixingOperation", "description": "mix and grind"},
# {"step": 2, "action": "HeatingOperation", "description": "calcine at 850°C for 12 h in air",
# "temperature_c": 850, "duration": 12, "atmosphere": "air"}
# ],
# "doi": "10.1234/example",
# "basis": "Literature-derived from Materials Project"
# }
Agent message to user:
"Found 206 literature synthesis recipes for LiCoO2 in Materials Project. Generated 5 validated routes based on actual experimental procedures. Recommended route uses Li2CO3 + Co3O4 precursors, calcination at 850°C for 12h in air. This is a well-established synthesis with high confidence (0.90)."
# User: "Generate a solid-state synthesis route for Li7La3Zr2O12 (LLZO)"
# Step 1: Search MP for literature recipes
mp_result = mp_search_recipe(
target_formula="Li7La3Zr2O12",
format_routes=True
)
# Result: n_routes = 0 (novel composition) → Try ML prediction
# Step 2: ML precursor prediction
ml_precursors = er_predict_precursors(
target_formula="Li7La3Zr2O12",
top_k=5
)
# Result:
# {
# "top_prediction": {"precursors": ["Li2CO3", "La2O3", "ZrO2"], "confidence": 0.6121},
# "precursor_sets": [
# {"precursors": ["Li2CO3", "La2O3", "ZrO2"], "confidence": 0.6121},
# {"precursors": ["Li2O", "La2O3", "ZrO2"], "confidence": 0.2341},
# ...
# ]
# }
# Step 3: ML temperature prediction
ml_temperature = er_predict_temperature(
target_formula="Li7La3Zr2O12",
precursors=["Li2CO3", "La2O3", "ZrO2"]
)
# Result: {"temperature_celsius": 908.3, "temperature_kelvin": 1181.5}
# Step 4: Format ML-based route
ml_route = {
"method": "solid_state",
"source": "ml_prediction",
"confidence": 0.61,
"precursors": [
{"compound": "Li2CO3", "form": "carbonate"},
{"compound": "La2O3", "form": "oxide"},
{"compound": "ZrO2", "form": "oxide"}
],
"steps": [
{"step": 1, "action": "mix_and_grind", "description": "Mix and grind precursors"},
{
"step": 2,
"action": "calcine",
"description": "Calcine at 908°C for 12h in air",
"temperature_c": 908,
"duration": 12,
"atmosphere": "air"
}
],
"requires_review": True,
"ml_metadata": {
"precursor_confidence": 0.6121,
"temperature_uncertainty": "±50-100°C"
},
"warnings": [
"ML-predicted route (not experimentally validated)",
"Precursor confidence: 0.61",
"Temperature uncertainty: ±50-100°C"
]
}
Agent message to user:
"No literature synthesis found for Li7La3Zr2O12. Generated ML-predicted solid-state route using neural network trained on synthesis literature.
Predicted precursors (confidence: 0.61):
- Li2CO3
- La2O3
- ZrO2
Predicted temperature: 908°C (±50-100°C uncertainty)
This is a data-driven prediction with medium confidence (0.61). Recommended to cross-check with similar materials in literature and test at small scale first.
Alternative precursor sets: 2. ['Li2O', 'La2O3', 'ZrO2'] (confidence: 0.23) 3. ['LiOH', 'La2O3', 'ZrO2'] (confidence: 0.09)"
# User: "Generate a hydrothermal synthesis route for NiO nanowires"
# Step 1: Search MP for literature recipes
mp_result = mp_search_recipe(
target_formula="NiO",
synthesis_type="hydrothermal"
)
# Result: n_routes = 0 (no hydrothermal routes for NiO nanowires) → Skip ML (not solid-state)
# Step 2: ML prediction SKIPPED (user requested hydrothermal, not solid-state)
# Step 3: Fall back to template generator
template_result = template_route_generator(
target_material={"composition": "NiO"},
synthesis_method="hydrothermal"
)
# Step 3: Return low-confidence template routes with warnings
# template_result["routes"][0]:
# {
# "method": "hydrothermal",
# "source": "template_with_mp_precursors",
# "confidence": 0.35,
# "precursors": [
# {"compound": "Ni(NO3)2", "form": "nitrate"}, # From MP precursor data
# {"compound": "NaOH", "form": "base"}
# ],
# "steps": [
# {"action": "dissolve", "description": "Dissolve precursors in water"},
# {"action": "autoclave", "temperature_c": 180, "hold_time_h": 12, "atmosphere": "autogenous"}
# ],
# "requires_review": True,
# "warnings": [
# "No literature or ML precedent found for hydrothermal NiO nanowires",
# "Template based on heuristics - validation required",
# "ML tools not applicable (hydrothermal synthesis)"
# ]
# }
Agent message to user:
"⚠️ WARNING: No literature synthesis or ML prediction succeeded for hydrothermal NiO nanowires. Generated template-based route using heuristics. This route has NOT been validated experimentally (confidence: 0.35) and requires expert review before execution. ML tools are not applicable for hydrothermal synthesis (solid-state only). Consider searching for related compositions."
# User: "I need a low-temperature synthesis route for NiO (max 300°C)"
# Single-step with constraints
routes = mp_search_recipe(
target_formula="NiO",
format_routes=True,
temperature_max=300, # Filter by max temperature in search
keywords=["hydrothermal", "sol-gel"], # Hint for low-temp methods
limit=5 # Number of routes to return
)
if routes["success"] and routes["n_routes"] > 0:
# SUCCESS: Return literature-validated low-temp routes
return routes