skills/scientific-schematics/references/iterative_refinement.md
How the generate-review-refine loop works: the initial generation, the quality review, the decision to continue or stop, subsequent iterations, and the review log. Then the advanced generation options (Python API, command-line options, prompt engineering) and four worked examples.
The AI generation system uses smart iteration - it only regenerates if quality is below the threshold for your document type:
┌─────────────────────────────────────────────────────┐
│ 1. Generate image with Nano Banana 2 │
│ ↓ │
│ 2. Review quality with Gemini 3.6 Flash │
│ ↓ │
│ 3. Score >= threshold? │
│ YES → DONE! (early stop) │
│ NO → Improve prompt, go to step 1 │
│ ↓ │
│ 4. Repeat until quality met OR max iterations │
└─────────────────────────────────────────────────────┘
Prompt Construction:
Scientific diagram guidelines + User request
Output: diagram_v1.png
Gemini 3.6 Flash evaluates the diagram on:
Example Review Output:
SCORE: 8.0
STRENGTHS:
- Clear flow from top to bottom
- All phases properly labeled
- Professional typography
ISSUES:
- Participant counts slightly small
- Minor overlap on exclusion box
VERDICT: ACCEPTABLE (for poster, threshold 7.0)
| If Score... | Action |
|---|---|
| >= threshold | STOP - Quality is good enough for this document type |
| < threshold | Continue to next iteration with improved prompt |
Example:
If quality is below threshold, the system:
All iterations are saved with a JSON review log that includes early-stop information:
{
"user_prompt": "CONSORT participant flow diagram...",
"doc_type": "poster",
"quality_threshold": 7.0,
"iterations": [
{
"iteration": 1,
"image_path": "figures/consort_v1.png",
"score": 7.5,
"needs_improvement": false,
"critique": "SCORE: 7.5\nSTRENGTHS:..."
}
],
"final_score": 7.5,
"early_stop": true,
"early_stop_reason": "Quality score 7.5 meets threshold 7.0 for poster"
}
Note: With smart iteration, you may see only 1 iteration instead of the full 2 if quality is achieved early!
from scripts.generate_schematic_ai import ScientificSchematicGenerator
# Initialize generator
generator = ScientificSchematicGenerator(
api_key="your_openrouter_key",
verbose=True
)
# Generate with iterative refinement (max 2 iterations)
results = generator.generate_iterative(
user_prompt="Transformer architecture diagram",
output_path="figures/transformer.png",
iterations=2
)
# Access results
print(f"Final score: {results['final_score']}/10")
print(f"Final image: {results['final_image']}")
# Review individual iterations
for iteration in results['iterations']:
print(f"Iteration {iteration['iteration']}: {iteration['score']}/10")
print(f"Critique: {iteration['critique']}")
# Basic usage (default threshold 7.5/10)
python scripts/generate_schematic.py "diagram description" -o output.png
# Specify document type for appropriate quality threshold
python scripts/generate_schematic.py "diagram" -o out.png --doc-type journal # 8.5/10
python scripts/generate_schematic.py "diagram" -o out.png --doc-type conference # 8.0/10
python scripts/generate_schematic.py "diagram" -o out.png --doc-type poster # 7.0/10
python scripts/generate_schematic.py "diagram" -o out.png --doc-type presentation # 6.5/10
# Custom max iterations (1-2)
python scripts/generate_schematic.py "complex diagram" -o diagram.png --iterations 2
# Verbose output (see all API calls and reviews)
python scripts/generate_schematic.py "flowchart" -o flow.png -v
# Provide API key via flag
python scripts/generate_schematic.py "diagram" -o out.png --api-key "sk-or-v1-..."
# Combine options
python scripts/generate_schematic.py "neural network" -o nn.png --doc-type journal --iterations 2 -v
1. Be Specific About Layout:
✓ "Flowchart with vertical flow, top to bottom"
✓ "Architecture diagram with encoder on left, decoder on right"
✓ "Circular pathway diagram with clockwise flow"
2. Include Quantitative Details:
✓ "Neural network with input layer (784 nodes), hidden layer (128 nodes), output (10 nodes)"
✓ "Flowchart showing n=500 screened, n=150 excluded, n=350 randomized"
✓ "Circuit with 1kΩ resistor, 10µF capacitor, 5V source"
3. Specify Visual Style:
✓ "Minimalist block diagram with clean lines"
✓ "Detailed biological pathway with protein structures"
✓ "Technical schematic with engineering notation"
4. Request Specific Labels:
✓ "Label all arrows with activation/inhibition"
✓ "Include layer dimensions in each box"
✓ "Show time progression with timestamps"
5. Mention Color Requirements:
✓ "Use colorblind-friendly colors"
✓ "Grayscale-compatible design"
✓ "Color-code by function: blue for input, green for processing, red for output"
python scripts/generate_schematic.py \
"CONSORT participant flow diagram for randomized controlled trial. \
Start with 'Assessed for eligibility (n=500)' at top. \
Show 'Excluded (n=150)' with reasons: age<18 (n=80), declined (n=50), other (n=20). \
Then 'Randomized (n=350)' splits into two arms: \
'Treatment group (n=175)' and 'Control group (n=175)'. \
Each arm shows 'Lost to follow-up' (n=15 and n=10). \
End with 'Analyzed' (n=160 and n=165). \
Use blue boxes for process steps, orange for exclusion, green for final analysis." \
-o figures/consort.png
python scripts/generate_schematic.py \
"Transformer encoder-decoder architecture diagram. \
Left side: Encoder stack with input embedding, positional encoding, \
multi-head self-attention, add & norm, feed-forward, add & norm. \
Right side: Decoder stack with output embedding, positional encoding, \
masked self-attention, add & norm, cross-attention (receiving from encoder), \
add & norm, feed-forward, add & norm, linear & softmax. \
Show cross-attention connection from encoder to decoder with dashed line. \
Use light blue for encoder, light red for decoder. \
Label all components clearly." \
-o figures/transformer.png --iterations 2
python scripts/generate_schematic.py \
"MAPK signaling pathway diagram. \
Start with EGFR receptor at cell membrane (top). \
Arrow down to RAS (with GTP label). \
Arrow to RAF kinase. \
Arrow to MEK kinase. \
Arrow to ERK kinase. \
Final arrow to nucleus showing gene transcription. \
Label each arrow with 'phosphorylation' or 'activation'. \
Use rounded rectangles for proteins, different colors for each. \
Include membrane boundary line at top." \
-o figures/mapk_pathway.png
python scripts/generate_schematic.py \
"IoT system architecture block diagram. \
Bottom layer: Sensors (temperature, humidity, motion) in green boxes. \
Middle layer: Microcontroller (ESP32) in blue box. \
Connections to WiFi module (orange box) and Display (purple box). \
Top layer: Cloud server (gray box) connected to mobile app (light blue box). \
Show data flow arrows between all components. \
Label connections with protocols: I2C, UART, WiFi, HTTPS." \
-o figures/iot_architecture.png