Prompt Strategy

DeepRetro keeps its reusable prompt templates in deepretro/utils/variables.py. The templates are organized by provider-specific behavior, reasoning depth, and prompt modifiers so the runtime can select the narrowest prompt that matches the requested model.

How prompt selection works

At runtime, src/utils/llm.py chooses a prompt pair based on the model name and whether the model is invoked with the :adv suffix.

Runtime case	System prompt	User prompt
Default providers	SYS_PROMPT	USER_PROMPT
Default providers with :adv	SYS_PROMPT_V4	USER_PROMPT_V4
OpenAI-family models	SYS_PROMPT_OPENAI	USER_PROMPT_OPENAI
DeepSeek-family models	SYS_PROMPT_DEEPSEEK	USER_PROMPT_DEEPSEEK
DeepSeek-family models with :adv	SYS_PROMPT_V4	USER_PROMPT_DEEPSEEK_V4

This split keeps the high-level retrosynthesis framing stable while allowing provider-specific output constraints where the models need them.

Prompt families

The prompt constants fall into three groups:

Group	Purpose
Baseline prompts	SYS_PROMPT and USER_PROMPT provide the default single-step retrosynthesis framing and JSON output contract.
Advanced prompts	SYS_PROMPT_V4 and USER_PROMPT_V4 ask for a more explicit staged reasoning process and richer practical analysis.
Provider-specific prompts	SYS_PROMPT_OPENAI, USER_PROMPT_OPENAI, SYS_PROMPT_DEEPSEEK, USER_PROMPT_DEEPSEEK, and USER_PROMPT_DEEPSEEK_V4 adapt the output contract to known provider differences.

Prompt modifiers

The base prompt pair can be extended with targeted add-ons:

Constant	When it is added
ADDON_PROMPT_7_MEMBER	Appended when the molecule contains a seven-membered ring so the model pays extra attention to that motif.
PROTECTING_GROUP_CONTEXT	Appended when protecting groups are detected so the prompt explains the masking symbols and asks for real SMILES plus deprotection-aware reasoning.

Design intent

The prompt strategy follows a few simple rules:

1. Keep a stable baseline contract for ordinary retrosynthesis calls.

2. Isolate advanced reasoning prompts instead of mutating the baseline prompt in place.

3. Add provider-specific variants only where output formatting or model behavior diverges.

4. Layer structural context, such as protecting-group handling, as explicit modifiers instead of duplicating full prompt templates.

This structure makes prompt changes easier to review because each change tends to fall into one of three categories: base behavior, provider tuning, or context-specific add-ons.