zhongwei/gh-k-dense-ai-claude-scientific-writer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:30:14 +08:00
commit 1dd5bee3b4
335 changed files with 147360 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

207
skills/scientific-schematics/QUICK_REFERENCE.md Normal file
View File

@@ -0,0 +1,207 @@
# Scientific Schematics - Quick Reference
**How it works:** Describe your diagram → Nano Banana Pro generates it automatically
## Setup (One-Time)
```bash
# Get API key from https://openrouter.ai/keys
export OPENROUTER_API_KEY='sk-or-v1-your_key_here'
# Add to shell profile for persistence
echo 'export OPENROUTER_API_KEY="sk-or-v1-your_key"' >> ~/.bashrc # or ~/.zshrc
```
## Basic Usage
```bash
# Describe your diagram, Nano Banana Pro creates it
python scripts/generate_schematic.py "your diagram description" -o output.png
# That's it! Automatic:
# - Iterative refinement (3 rounds)
# - Quality review and improvement
# - Publication-ready output
```
## Common Examples
### CONSORT Flowchart
```bash
python scripts/generate_schematic.py \
"CONSORT flow: screened n=500, excluded n=150, randomized n=350" \
-o consort.png
```
### Neural Network
```bash
python scripts/generate_schematic.py \
"Transformer architecture with encoder and decoder stacks" \
-o transformer.png
```
### Biological Pathway
```bash
python scripts/generate_schematic.py \
"MAPK pathway: EGFR → RAS → RAF → MEK → ERK" \
-o mapk.png
```
### Circuit Diagram
```bash
python scripts/generate_schematic.py \
"Op-amp circuit with 1kΩ resistor and 10µF capacitor" \
-o circuit.png
```
## Command Options
| Option | Description | Example |
|--------|-------------|---------|
| `-o, --output` | Output file path | `-o figures/diagram.png` |
| `--iterations N` | Number of refinements (1-10) | `--iterations 5` |
| `-v, --verbose` | Show detailed output | `-v` |
| `--api-key KEY` | Provide API key | `--api-key sk-or-v1-...` |
## Prompt Tips
### ✓ Good Prompts (Specific)
- "CONSORT flowchart with screening (n=500), exclusion (n=150), randomization (n=350)"
- "Transformer architecture: encoder on left with 6 layers, decoder on right, cross-attention connections"
- "MAPK signaling: receptor → RAS → RAF → MEK → ERK → nucleus, label each phosphorylation"
### ✗ Avoid (Too Vague)
- "Make a flowchart"
- "Neural network"
- "Pathway diagram"
## Output Files
For input `diagram.png`, you get:
- `diagram_v1.png` - First iteration
- `diagram_v2.png` - Second iteration
- `diagram_v3.png` - Final iteration
- `diagram.png` - Copy of final
- `diagram_review_log.json` - Quality scores and critiques
## Review Log
```json
{
"iterations": [
{
"iteration": 1,
"score": 7.0,
"critique": "Good start. Font too small..."
},
{
"iteration": 2,
"score": 8.5,
"critique": "Much improved. Minor spacing issues..."
},
{
"iteration": 3,
"score": 9.5,
"critique": "Excellent. Publication ready."
}
],
"final_score": 9.5
}
```
## Python API
```python
from scripts.generate_schematic_ai import ScientificSchematicGenerator
# Initialize
gen = ScientificSchematicGenerator(api_key="your_key")
# Generate
results = gen.generate_iterative(
user_prompt="diagram description",
output_path="output.png",
iterations=3
)
# Check quality
print(f"Score: {results['final_score']}/10")
```
## Troubleshooting
### API Key Not Found
```bash
# Check if set
echo $OPENROUTER_API_KEY
# Set it
export OPENROUTER_API_KEY='your_key'
```
### Import Error
```bash
# Install requests
pip install requests
```
### Low Quality Score
- Make prompt more specific
- Include layout details (left-to-right, top-to-bottom)
- Specify label requirements
- Increase iterations: `--iterations 5`
## Testing
```bash
# Verify installation
python test_ai_generation.py
# Should show: "6/6 tests passed"
```
## Cost
Typical cost per diagram (3 iterations):
- Simple: $0.10-0.30
- Complex: $0.30-0.50
## How Nano Banana Pro Works
**Simply describe your diagram in natural language:**
- ✓ No coding required
- ✓ No templates needed
- ✓ No manual drawing
- ✓ Automatic quality review
- ✓ Publication-ready output
- ✓ Works for any diagram type
**Just describe what you want, and it's generated automatically.**
## Getting Help
```bash
# Show help
python scripts/generate_schematic.py --help
# Verbose mode for debugging
python scripts/generate_schematic.py "diagram" -o out.png -v
```
## Quick Start Checklist
- [ ] Set `OPENROUTER_API_KEY` environment variable
- [ ] Run `python test_ai_generation.py` (should pass 6/6)
- [ ] Try: `python scripts/generate_schematic.py "test diagram" -o test.png`
- [ ] Review output files (test_v1.png, v2, v3, review_log.json)
- [ ] Read SKILL.md for detailed documentation
- [ ] Check README.md for examples
## Resources
- Full documentation: `SKILL.md`
- Detailed guide: `README.md`
- Implementation details: `IMPLEMENTATION_SUMMARY.md`
- Example script: `example_usage.sh`
- Get API key: https://openrouter.ai/keys

327
skills/scientific-schematics/README.md Normal file
View File

@@ -0,0 +1,327 @@
# Scientific Schematics - Nano Banana Pro
**Generate any scientific diagram by describing it in natural language.**
Nano Banana Pro creates publication-quality diagrams automatically - no coding, no templates, no manual drawing required.
## Quick Start
### Generate Any Diagram
```bash
# Set your OpenRouter API key
export OPENROUTER_API_KEY='your_api_key_here'
# Generate any scientific diagram
python scripts/generate_schematic.py "CONSORT participant flow diagram" -o figures/consort.png
# Neural network architecture
python scripts/generate_schematic.py "Transformer encoder-decoder architecture" -o figures/transformer.png
# Biological pathway
python scripts/generate_schematic.py "MAPK signaling pathway" -o figures/pathway.png
```
### What You Get
- **Three iterations** (v1, v2, v3) with progressive refinement
- **Automatic quality review** after each iteration
- **Detailed review log** with scores and critiques (JSON format)
- **Publication-ready images** following scientific standards
## Features
### Iterative Refinement Process
1. **Generation 1**: Create initial diagram from your description
2. **Review 1**: AI evaluates clarity, labels, accuracy, accessibility
3. **Generation 2**: Improve based on critique
4. **Review 2**: Second evaluation with specific feedback
5. **Generation 3**: Final polished version
### Automatic Quality Standards
All diagrams automatically follow:
- Clean white/light background
- High contrast for readability
- Clear labels (minimum 10pt font)
- Professional typography
- Colorblind-friendly colors
- Proper spacing between elements
- Scale bars, legends, axes where appropriate
## Installation
### For AI Generation
```bash
# Get OpenRouter API key
# Visit: https://openrouter.ai/keys
# Set environment variable
export OPENROUTER_API_KEY='sk-or-v1-...'
# Or add to .env file
echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env
# Install Python dependencies (if not already installed)
pip install requests
```
## Usage Examples
### Example 1: CONSORT Flowchart
```bash
python scripts/generate_schematic.py \
"CONSORT participant flow diagram for RCT. \
Assessed for eligibility (n=500). \
Excluded (n=150): age<18 (n=80), declined (n=50), other (n=20). \
Randomized (n=350) into Treatment (n=175) and Control (n=175). \
Lost to follow-up: 15 and 10 respectively. \
Final analysis: 160 and 165." \
-o figures/consort.png
```
**Output:**
- `figures/consort_v1.png` - Initial generation
- `figures/consort_v2.png` - After first review
- `figures/consort_v3.png` - Final version
- `figures/consort.png` - Copy of final version
- `figures/consort_review_log.json` - Detailed review log
### Example 2: Neural Network Architecture
```bash
python scripts/generate_schematic.py \
"Transformer architecture with encoder on left (input embedding, \
positional encoding, multi-head attention, feed-forward) and \
decoder on right (masked attention, cross-attention, feed-forward). \
Show cross-attention connection from encoder to decoder." \
-o figures/transformer.png \
--iterations 3
```
### Example 3: Biological Pathway
```bash
python scripts/generate_schematic.py \
"MAPK signaling pathway: EGFR receptor → RAS → RAF → MEK → ERK → nucleus. \
Label each step with phosphorylation. Use different colors for each kinase." \
-o figures/mapk.png
```
### Example 4: System Architecture
```bash
python scripts/generate_schematic.py \
"IoT system block diagram: sensors (bottom) → microcontroller → \
WiFi module and display (middle) → cloud server → mobile app (top). \
Label all connections with protocols." \
-o figures/iot_system.png
```
## Command-Line Options
```bash
python scripts/generate_schematic.py [OPTIONS] "description" -o output.png
Options:
--iterations N Number of AI refinement iterations (default: 3)
--api-key KEY OpenRouter API key (or use env var)
-v, --verbose Verbose output
-h, --help Show help message
```
## Python API
```python
from scripts.generate_schematic_ai import ScientificSchematicGenerator
# Initialize
generator = ScientificSchematicGenerator(
api_key="your_key",
verbose=True
)
# Generate with iterative refinement
results = generator.generate_iterative(
user_prompt="CONSORT flowchart",
output_path="figures/consort.png",
iterations=3
)
# Access results
print(f"Final score: {results['final_score']}/10")
print(f"Final image: {results['final_image']}")
# Review iterations
for iteration in results['iterations']:
print(f"Iteration {iteration['iteration']}: {iteration['score']}/10")
print(f"Critique: {iteration['critique']}")
```
## Prompt Engineering Tips
### Be Specific About Layout
✓ "Flowchart with vertical flow, top to bottom"
✓ "Architecture diagram with encoder on left, decoder on right"
✗ "Make a diagram" (too vague)
### Include Quantitative Details
✓ "Neural network: input (784), hidden (128), output (10)"
✓ "Flowchart: n=500 screened, n=150 excluded, n=350 randomized"
✗ "Some numbers" (not specific)
### Specify Visual Style
✓ "Minimalist block diagram with clean lines"
✓ "Detailed biological pathway with protein structures"
✓ "Technical schematic with engineering notation"
### Request Specific Labels
✓ "Label all arrows with activation/inhibition"
✓ "Include layer dimensions in each box"
✓ "Show time progression with timestamps"
### Mention Color Requirements
✓ "Use colorblind-friendly colors"
✓ "Grayscale-compatible design"
✓ "Color-code by function: blue=input, green=processing, red=output"
## Review Log Format
Each generation produces a JSON review log:
```json
{
"user_prompt": "CONSORT participant flow diagram...",
"iterations": [
{
"iteration": 1,
"image_path": "figures/consort_v1.png",
"prompt": "Full generation prompt...",
"critique": "Score: 7/10. Issues: font too small...",
"score": 7.0,
"success": true
},
{
"iteration": 2,
"image_path": "figures/consort_v2.png",
"score": 8.5,
"critique": "Much improved. Remaining issues..."
},
{
"iteration": 3,
"image_path": "figures/consort_v3.png",
"score": 9.5,
"critique": "Excellent. Publication ready."
}
],
"final_image": "figures/consort_v3.png",
"final_score": 9.5,
"success": true
}
```
## Why Use Nano Banana Pro
**Simply describe what you want - Nano Banana Pro creates it:**
- ✓ **Fast**: Results in minutes
- ✓ **Easy**: Natural language descriptions (no coding)
- ✓ **Quality**: Automatic review and refinement
- ✓ **Universal**: Works for all diagram types
- ✓ **Publication-ready**: High-quality output immediately
**Just describe your diagram, and it's generated automatically.**
## Troubleshooting
### API Key Issues
```bash
# Check if key is set
echo $OPENROUTER_API_KEY
# Set temporarily
export OPENROUTER_API_KEY='your_key'
# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export OPENROUTER_API_KEY="your_key"' >> ~/.bashrc
```
### Import Errors
```bash
# Install requests library
pip install requests
# Or use the package manager
pip install -r requirements.txt
```
### Generation Fails
```bash
# Use verbose mode to see detailed errors
python scripts/generate_schematic.py "diagram" -o out.png -v
# Check API status
curl https://openrouter.ai/api/v1/models
```
### Low Quality Scores
If iterations consistently score below 7/10:
1. Make your prompt more specific
2. Include more details about layout and labels
3. Specify visual requirements explicitly
4. Increase iterations: `--iterations 5`
## Testing
Run verification tests:
```bash
python test_ai_generation.py
```
This tests:
- File structure
- Module imports
- Class initialization
- Error handling
- Prompt engineering
- Wrapper script
## Cost Considerations
OpenRouter pricing for models used:
- **Nano Banana Pro**: ~$2/M input tokens, ~$12/M output tokens
Typical costs per diagram:
- Simple diagram (3 iterations): ~$0.10-0.30
- Complex diagram (5 iterations): ~$0.30-0.50
## Examples Gallery
See the full SKILL.md for extensive examples including:
- CONSORT flowcharts
- Neural network architectures (Transformers, CNNs, RNNs)
- Biological pathways
- Circuit diagrams
- System architectures
- Block diagrams
## Support
For issues or questions:
1. Check SKILL.md for detailed documentation
2. Run test_ai_generation.py to verify setup
3. Use verbose mode (-v) to see detailed errors
4. Review the review_log.json for quality feedback
## License
Part of the scientific-writer package. See main repository for license information.

598
skills/scientific-schematics/SKILL.md Normal file
View File

@@ -0,0 +1,598 @@
---
name: scientific-schematics
description: "Create publication-quality scientific diagrams using Nano Banana Pro AI with iterative refinement. AI generation is the default method for all diagram types. Generates high-fidelity images with automatic quality review. Specialized in neural network architectures, system diagrams, flowcharts, biological pathways, and complex scientific visualizations."
allowed-tools: [Read, Write, Edit, Bash]
---
# Scientific Schematics and Diagrams
## Overview
Scientific schematics and diagrams transform complex concepts into clear visual representations for publication. **This skill uses Nano Banana Pro AI for all diagram generation.**
**How it works:**
- Describe your diagram in natural language
- Nano Banana Pro generates publication-quality images automatically
- Automatic iterative refinement (3 iterations by default)
- Built-in quality review and improvement
- Publication-ready output in minutes
- No coding, templates, or manual drawing required
**Simply describe what you want, and Nano Banana Pro creates it.** All diagrams are stored in the figures/ subfolder and referenced in papers/posters.
## Quick Start: Generate Any Diagram
Create any scientific diagram by simply describing it. Nano Banana Pro handles everything automatically:
```bash
# Generate any scientific diagram from a description
python scripts/generate_schematic.py "CONSORT participant flow diagram with 500 screened, 150 excluded, 350 randomized" -o figures/consort.png
# Neural network architecture
python scripts/generate_schematic.py "Transformer encoder-decoder architecture showing multi-head attention, feed-forward layers, and residual connections" -o figures/transformer.png
# Biological pathway
python scripts/generate_schematic.py "MAPK signaling pathway from EGFR to gene transcription" -o figures/mapk_pathway.png
# Custom iterations for complex diagrams
python scripts/generate_schematic.py "Complex circuit diagram with op-amp, resistors, and capacitors" -o figures/circuit.png --iterations 5
```
**What happens behind the scenes:**
1. **Generation 1**: Nano Banana Pro creates initial image following scientific diagram best practices
2. **Review 1**: AI evaluates clarity, labels, accuracy, and accessibility
3. **Generation 2**: Improved prompt based on critique, regenerate
4. **Review 2**: Second evaluation with specific feedback
5. **Generation 3**: Final polished version addressing all critiques
**Output**: Three versions (v1, v2, v3) plus a detailed review log with quality scores and critiques.
### Configuration
Set your OpenRouter API key:
```bash
export OPENROUTER_API_KEY='your_api_key_here'
```
Get an API key at: https://openrouter.ai/keys
### AI Generation Best Practices
**Effective Prompts for Scientific Diagrams:**
✓ **Good prompts** (specific, detailed):
- "CONSORT flowchart showing participant flow from screening (n=500) through randomization to final analysis"
- "Transformer neural network architecture with encoder stack on left, decoder stack on right, showing multi-head attention and cross-attention connections"
- "Biological signaling cascade: EGFR receptor → RAS → RAF → MEK → ERK → nucleus, with phosphorylation steps labeled"
- "Block diagram of IoT system: sensors → microcontroller → WiFi module → cloud server → mobile app"
✗ **Avoid vague prompts**:
- "Make a flowchart" (too generic)
- "Neural network" (which type? what components?)
- "Pathway diagram" (which pathway? what molecules?)
**Key elements to include:**
- **Type**: Flowchart, architecture diagram, pathway, circuit, etc.
- **Components**: Specific elements to include
- **Flow/Direction**: How elements connect (left-to-right, top-to-bottom)
- **Labels**: Key annotations or text to include
- **Style**: Any specific visual requirements
**Scientific Quality Guidelines** (automatically applied):
- Clean white/light background
- High contrast for readability
- Clear, readable labels (minimum 10pt)
- Professional typography (sans-serif fonts)
- Colorblind-friendly colors (Okabe-Ito palette)
- Proper spacing to prevent crowding
- Scale bars, legends, axes where appropriate
## When to Use This Skill
This skill should be used when:
- Creating neural network architecture diagrams (Transformers, CNNs, RNNs, etc.)
- Illustrating system architectures and data flow diagrams
- Drawing methodology flowcharts for study design (CONSORT, PRISMA)
- Visualizing algorithm workflows and processing pipelines
- Creating circuit diagrams and electrical schematics
- Depicting biological pathways and molecular interactions
- Generating network topologies and hierarchical structures
- Illustrating conceptual frameworks and theoretical models
- Designing block diagrams for technical papers
## How to Use This Skill
**Simply describe your diagram in natural language.** Nano Banana Pro generates it automatically:
```bash
python scripts/generate_schematic.py "your diagram description" -o output.png
```
**That's it!** The AI handles:
- ✓ Layout and composition
- ✓ Labels and annotations
- ✓ Colors and styling
- ✓ Quality review and refinement
- ✓ Publication-ready output
**Works for all diagram types:**
- Flowcharts (CONSORT, PRISMA, etc.)
- Neural network architectures
- Biological pathways
- Circuit diagrams
- System architectures
- Block diagrams
- Any scientific visualization
**No coding, no templates, no manual drawing required.**
---
# AI Generation Mode (Nano Banana Pro)
## Iterative Refinement Workflow
The AI generation system uses a sophisticated three-iteration refinement process:
### Iteration 1: Initial Generation
**Prompt Construction:**
```
Scientific diagram guidelines + User request
```
**Example internal prompt:**
```
Create a high-quality scientific diagram with:
- Clean white background
- High contrast for readability
- Clear labels (minimum 10pt font)
- Professional typography
- Colorblind-friendly colors
- Proper spacing
USER REQUEST: CONSORT participant flow diagram showing screening,
exclusion, randomization, and analysis phases with participant counts
```
**Output:** `diagram_v1.png`
### Iteration 2: Review and Improve
**AI Quality Review:**
- Evaluates scientific accuracy
- Checks label clarity and readability
- Assesses layout and composition
- Verifies accessibility (grayscale, colorblind)
- Assigns quality score (0-10)
- Provides specific improvement suggestions
**Example critique:**
```
Score: 7/10
Strengths:
- Clear flow from top to bottom
- Good use of colors
- All phases labeled
Issues:
- Participant counts (n=X) are too small to read
- "Excluded" box overlaps with arrow
- Would benefit from reasons for exclusion
Suggestions:
- Increase font size for all numbers to at least 12pt
- Add more vertical spacing between boxes
- Include exclusion criteria in a separate annotation box
```
**Improved Prompt:**
```
[Original guidelines + user request]
ITERATION 2: Address these improvements:
- Increase font size for participant counts to 12pt minimum
- Add vertical spacing to prevent overlaps
- Include exclusion criteria in annotation box
```
**Output:** `diagram_v2.png`
### Iteration 3: Final Polish
**Second Review:**
- Verifies improvements were implemented
- Checks for any remaining issues
- Final quality assessment
**Final Generation:**
- Incorporates all feedback
- Produces publication-ready diagram
**Output:** `diagram_v3.png` (final version)
### Review Log
All iterations are saved with a JSON review log:
```json
{
"user_prompt": "CONSORT participant flow diagram...",
"iterations": [
{
"iteration": 1,
"image_path": "figures/consort_v1.png",
"score": 7.0,
"critique": "..."
},
{
"iteration": 2,
"image_path": "figures/consort_v2.png",
"score": 8.5,
"critique": "..."
},
{
"iteration": 3,
"image_path": "figures/consort_v3.png",
"score": 9.5,
"critique": "..."
}
],
"final_score": 9.5
}
```
## Advanced AI Generation Usage
### Python API
```python
from scripts.generate_schematic_ai import ScientificSchematicGenerator
# Initialize generator
generator = ScientificSchematicGenerator(
api_key="your_openrouter_key",
verbose=True
)
# Generate with iterative refinement
results = generator.generate_iterative(
user_prompt="Transformer architecture diagram",
output_path="figures/transformer.png",
iterations=3
)
# 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']}")
```
### Command-Line Options
```bash
# Basic usage
python scripts/generate_schematic.py "diagram description" -o output.png
# Custom iterations (1-10)
python scripts/generate_schematic.py "complex diagram" -o diagram.png --iterations 5
# 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-..."
```
### Prompt Engineering Tips
**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"
```
## AI Generation Examples
### Example 1: CONSORT Flowchart
```bash
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
```
### Example 2: Neural Network Architecture
```bash
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 3
```
### Example 3: Biological Pathway
```bash
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
```
### Example 4: System Architecture
```bash
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
```
---
## Command-Line Usage
The main entry point for generating scientific schematics:
```bash
# Basic usage
python scripts/generate_schematic.py "diagram description" -o output.png
# Custom iterations for complex diagrams
python scripts/generate_schematic.py "complex diagram" -o diagram.png --iterations 5
# Verbose mode
python scripts/generate_schematic.py "diagram" -o out.png -v
```
**Note:** The Nano Banana Pro AI generation system includes automatic quality review in its iterative refinement process. Each iteration is evaluated for scientific accuracy, clarity, and accessibility.
## Best Practices Summary
### Design Principles
1. **Clarity over complexity** - Simplify, remove unnecessary elements
2. **Consistent styling** - Use templates and style files
3. **Colorblind accessibility** - Use Okabe-Ito palette, redundant encoding
4. **Appropriate typography** - Sans-serif fonts, minimum 7-8 pt
5. **Vector format** - Always use PDF/SVG for publication
### Technical Requirements
1. **Resolution** - Vector preferred, or 300+ DPI for raster
2. **File format** - PDF for LaTeX, SVG for web, PNG as fallback
3. **Color space** - RGB for digital, CMYK for print (convert if needed)
4. **Line weights** - Minimum 0.5 pt, typical 1-2 pt
5. **Text size** - 7-8 pt minimum at final size
### Integration Guidelines
1. **Include in LaTeX** - Use `\includegraphics{}` for generated images
2. **Caption thoroughly** - Describe all elements and abbreviations
3. **Reference in text** - Explain diagram in narrative flow
4. **Maintain consistency** - Same style across all figures in paper
5. **Version control** - Keep prompts and generated images in repository
## Troubleshooting Common Issues
### AI Generation Issues
**Problem**: Overlapping text or elements
- **Solution**: AI generation automatically handles spacing
- **Solution**: Increase iterations: `--iterations 5` for better refinement
**Problem**: Elements not connecting properly
- **Solution**: Make your prompt more specific about connections and layout
- **Solution**: Increase iterations for better refinement
### Image Quality Issues
**Problem**: Export quality poor
- **Solution**: AI generation produces high-quality images automatically
- **Solution**: Increase iterations for better results: `--iterations 5`
**Problem**: Elements overlap after generation
- **Solution**: AI generation automatically handles spacing
- **Solution**: Increase iterations: `--iterations 5` for better refinement
- **Solution**: Make your prompt more specific about layout and spacing requirements
### Quality Check Issues
**Problem**: False positive overlap detection
- **Solution**: Adjust threshold: `detect_overlaps(image_path, threshold=0.98)`
- **Solution**: Manually review flagged regions in visual report
**Problem**: Generated image quality is low
- **Solution**: AI generation produces high-quality images by default
- **Solution**: Increase iterations for better results: `--iterations 5`
**Problem**: Colorblind simulation shows poor contrast
- **Solution**: Switch to Okabe-Ito palette explicitly in code
- **Solution**: Add redundant encoding (shapes, patterns, line styles)
- **Solution**: Increase color saturation and lightness differences
**Problem**: High-severity overlaps detected
- **Solution**: Review overlap_report.json for exact positions
- **Solution**: Increase spacing in those specific regions
- **Solution**: Re-run with adjusted parameters and verify again
**Problem**: Visual report generation fails
- **Solution**: Check Pillow and matplotlib installations
- **Solution**: Ensure image file is readable: `Image.open(path).verify()`
- **Solution**: Check sufficient disk space for report generation
### Accessibility Problems
**Problem**: Colors indistinguishable in grayscale
- **Solution**: Run accessibility checker: `verify_accessibility(image_path)`
- **Solution**: Add patterns, shapes, or line styles for redundancy
- **Solution**: Increase contrast between adjacent elements
**Problem**: Text too small when printed
- **Solution**: Run resolution validator: `validate_resolution(image_path)`
- **Solution**: Design at final size, use minimum 7-8 pt fonts
- **Solution**: Check physical dimensions in resolution report
**Problem**: Accessibility checks consistently fail
- **Solution**: Review accessibility_report.json for specific failures
- **Solution**: Increase color contrast by at least 20%
- **Solution**: Test with actual grayscale conversion before finalizing
## Resources and References
### Detailed References
Load these files for comprehensive information on specific topics:
- **`references/diagram_types.md`** - Catalog of scientific diagram types with examples
- **`references/best_practices.md`** - Publication standards and accessibility guidelines
### External Resources
**Python Libraries**
- Schemdraw Documentation: https://schemdraw.readthedocs.io/
- NetworkX Documentation: https://networkx.org/documentation/
- Matplotlib Documentation: https://matplotlib.org/
**Publication Standards**
- Nature Figure Guidelines: https://www.nature.com/nature/for-authors/final-submission
- Science Figure Guidelines: https://www.science.org/content/page/instructions-preparing-initial-manuscript
- CONSORT Diagram: http://www.consort-statement.org/consort-statement/flow-diagram
## Integration with Other Skills
This skill works synergistically with:
- **Scientific Writing** - Diagrams follow figure best practices
- **Scientific Visualization** - Shares color palettes and styling
- **LaTeX Posters** - Generate diagrams for poster presentations
- **Research Grants** - Methodology diagrams for proposals
- **Peer Review** - Evaluate diagram clarity and accessibility
## Quick Reference Checklist
Before submitting diagrams, verify:
### Visual Quality
- [ ] High-quality image format (PNG from AI generation)
- [ ] No overlapping elements (AI handles automatically)
- [ ] Adequate spacing between all components (AI optimizes)
- [ ] Clean, professional alignment
- [ ] All arrows connect properly to intended targets
### Accessibility
- [ ] Colorblind-safe palette (Okabe-Ito) used
- [ ] Works in grayscale (tested with accessibility checker)
- [ ] Sufficient contrast between elements (verified)
- [ ] Redundant encoding where appropriate (shapes + colors)
- [ ] Colorblind simulation passes all checks
### Typography and Readability
- [ ] Text minimum 7-8 pt at final size
- [ ] All elements labeled clearly and completely
- [ ] Consistent font family and sizing
- [ ] No text overlaps or cutoffs
- [ ] Units included where applicable
### Publication Standards
- [ ] Consistent styling with other figures in manuscript
- [ ] Comprehensive caption written with all abbreviations defined
- [ ] Referenced appropriately in manuscript text
- [ ] Meets journal-specific dimension requirements
- [ ] Exported in required format for journal (PDF/EPS/TIFF)
### Quality Verification (Required)
- [ ] Ran `run_quality_checks()` and achieved PASS status
- [ ] Reviewed overlap detection report (zero high-severity overlaps)
- [ ] Passed accessibility verification (grayscale and colorblind)
- [ ] Resolution validated at target DPI (300+ for print)
- [ ] Visual quality report generated and reviewed
- [ ] All quality reports saved with figure files
### Documentation and Version Control
- [ ] Source files (.tex, .py) saved for future revision
- [ ] Quality reports archived in `quality_reports/` directory
- [ ] Configuration parameters documented (colors, spacing, sizes)
- [ ] Git commit includes source, output, and quality reports
- [ ] README or comments explain how to regenerate figure
### Final Integration Check
- [ ] Figure displays correctly in compiled manuscript
- [ ] Cross-references work (`\ref{}` points to correct figure)
- [ ] Figure number matches text citations
- [ ] Caption appears on correct page relative to figure
- [ ] No compilation warnings or errors related to figure
## Environment Setup
```bash
# Required
export OPENROUTER_API_KEY='your_api_key_here'
# Get key at: https://openrouter.ai/keys
```
## Getting Started
**Simplest possible usage:**
```bash
python scripts/generate_schematic.py "your diagram description" -o output.png
```
---
Use this skill to create clear, accessible, publication-quality diagrams that effectively communicate complex scientific concepts. The AI-powered workflow with iterative refinement ensures diagrams meet professional standards.

89
skills/scientific-schematics/example_usage.sh Executable file
View File

@@ -0,0 +1,89 @@
#!/bin/bash
# Example usage of AI-powered scientific schematic generation
#
# Prerequisites:
# 1. Set OPENROUTER_API_KEY environment variable
# 2. Ensure Python 3.10+ is installed
# 3. Install requests: pip install requests
set -e
echo "=========================================="
echo "Scientific Schematics - AI Generation"
echo "Example Usage Demonstrations"
echo "=========================================="
echo ""
# Check for API key
if [ -z "$OPENROUTER_API_KEY" ]; then
echo "❌ Error: OPENROUTER_API_KEY environment variable not set"
echo ""
echo "Get an API key at: https://openrouter.ai/keys"
echo "Then set it with: export OPENROUTER_API_KEY='your_key'"
exit 1
fi
echo "✓ OPENROUTER_API_KEY is set"
echo ""
# Create output directory
mkdir -p figures
echo "✓ Created figures/ directory"
echo ""
# Example 1: Simple flowchart
echo "Example 1: CONSORT Flowchart"
echo "----------------------------"
python scripts/generate_schematic.py \
"CONSORT participant flow diagram. Assessed for eligibility (n=500). Excluded (n=150) with reasons: age<18 (n=80), declined (n=50), other (n=20). Randomized (n=350) into Treatment (n=175) and Control (n=175). Lost to follow-up: 15 and 10. Final analysis: 160 and 165." \
-o figures/consort_example.png \
--iterations 3
echo ""
echo "✓ Generated: figures/consort_example.png"
echo " - Also created: consort_example_v1.png, v2.png, v3.png"
echo " - Review log: consort_example_review_log.json"
echo ""
# Example 2: Neural network (shorter for demo)
echo "Example 2: Simple Neural Network"
echo "--------------------------------"
python scripts/generate_schematic.py \
"Simple feedforward neural network diagram. Input layer with 4 nodes, hidden layer with 6 nodes, output layer with 2 nodes. Show all connections. Label layers clearly." \
-o figures/neural_net_example.png \
--iterations 2
echo ""
echo "✓ Generated: figures/neural_net_example.png"
echo ""
# Example 3: Biological pathway (minimal)
echo "Example 3: Signaling Pathway"
echo "---------------------------"
python scripts/generate_schematic.py \
"Simple signaling pathway: Receptor → Kinase A → Kinase B → Transcription Factor → Gene. Show arrows with 'activation' labels. Use different colors for each component." \
-o figures/pathway_example.png \
--iterations 2
echo ""
echo "✓ Generated: figures/pathway_example.png"
echo ""
echo "=========================================="
echo "All examples completed successfully!"
echo "=========================================="
echo ""
echo "Generated files in figures/:"
ls -lh figures/*example*.png 2>/dev/null || echo " (Files will appear after running with valid API key)"
echo ""
echo "Review the review_log.json files to see:"
echo " - Quality scores for each iteration"
echo " - Detailed critiques and suggestions"
echo " - Improvement progression"
echo ""
echo "Next steps:"
echo " 1. View the generated images"
echo " 2. Review the quality scores in *_review_log.json"
echo " 3. Try your own prompts!"
echo ""

559
skills/scientific-schematics/references/best_practices.md Normal file
View File

@@ -0,0 +1,559 @@
# Best Practices for Scientific Diagrams
## Overview
This guide provides publication standards, accessibility guidelines, and best practices for creating high-quality scientific diagrams that meet journal requirements and communicate effectively to all readers.
## Publication Standards
### 1. File Format Requirements
**Vector Formats (Preferred)**
- **PDF**: Universal acceptance, preserves quality, works with LaTeX
- Use for: Line drawings, flowcharts, block diagrams, circuit diagrams
- Advantages: Scalable, small file size, embeds fonts
- Standard for LaTeX workflows
- **EPS (Encapsulated PostScript)**: Legacy format, still accepted
- Use for: Older publishing systems
- Compatible with most journals
- Can be converted from PDF
- **SVG (Scalable Vector Graphics)**: Web-friendly, increasingly accepted
- Use for: Online publications, interactive figures
- Can be edited in vector graphics software
- Not all journals accept SVG
**Raster Formats (When Necessary)**
- **TIFF**: Professional standard for raster graphics
- Use for: Microscopy images, photographs combined with diagrams
- Minimum 300 DPI at final print size
- Lossless compression (LZW)
- **PNG**: Web-friendly, lossless compression
- Use for: Online supplementary materials, presentations
- Minimum 300 DPI for print
- Supports transparency
**Never Use**
- **JPEG**: Lossy compression creates artifacts in diagrams
- **GIF**: Limited colors, inappropriate for scientific figures
- **BMP**: Uncompressed, unnecessarily large files
### 2. Resolution Requirements
**Vector Graphics**
- Infinite resolution (scalable)
- **Recommended**: Always use vector when possible
**Raster Graphics (when vector not possible)**
- **Publication quality**: 300-600 DPI
- **Line art**: 600-1200 DPI
- **Web/screen**: 150 DPI acceptable
- **Never**: Below 300 DPI for print
**Calculating DPI**
```
DPI = pixels / (inches at final size)
Example:
Image size: 2400 × 1800 pixels
Final print size: 8 × 6 inches
DPI = 2400 / 8 = 300 ✓ (acceptable)
```
### 3. Size and Dimensions
**Journal-Specific Column Widths**
- **Nature**: Single column 89 mm (3.5 in), Double 183 mm (7.2 in)
- **Science**: Single column 55 mm (2.17 in), Double 120 mm (4.72 in)
- **Cell**: Single column 85 mm (3.35 in), Double 178 mm (7 in)
- **PLOS**: Single column 83 mm (3.27 in), Double 173 mm (6.83 in)
- **IEEE**: Single column 3.5 in, Double 7.16 in
**Best Practices**
- Design at final print size (avoid scaling)
- Use journal templates when available
- Allow margins for cropping
- Test appearance at final size before submission
### 4. Typography Standards
**Font Selection**
- **Recommended**: Arial, Helvetica, Calibri (sans-serif)
- **Acceptable**: Times New Roman (serif) for mathematics-heavy
- **Avoid**: Decorative fonts, script fonts, system fonts that may not embed
**Font Sizes (at final print size)**
- **Minimum**: 6-7 pt (journal dependent)
- **Axis labels**: 8-9 pt
- **Figure labels**: 10-12 pt
- **Panel labels (A, B, C)**: 10-14 pt, bold
- **Main text**: Should match manuscript body text
**Text Clarity**
- Use sentence case: "Time (seconds)" not "TIME (SECONDS)"
- Include units in parentheses: "Temperature (°C)"
- Spell out abbreviations in figure caption
- Avoid rotated text when possible (exception: y-axis labels)
### 5. Line Weights and Strokes
**Recommended Line Widths**
- **Diagram outlines**: 0.5-1.0 pt
- **Connection lines/arrows**: 1.0-2.0 pt
- **Emphasis elements**: 2.0-3.0 pt
- **Minimum visible**: 0.25 pt at final size
**Consistency**
- Use same line weight for similar elements
- Vary line weight to show hierarchy
- Avoid hairline rules (too thin to print reliably)
## Accessibility and Colorblindness
### 1. Colorblind-Safe Palettes
**Okabe-Ito Palette (Recommended)**
Most distinguishable by all types of colorblindness:
```latex
% RGB values
Orange: #E69F00 (230, 159, 0)
Sky Blue: #56B4E9 ( 86, 180, 233)
Green: #009E73 ( 0, 158, 115)
Yellow: #F0E442 (240, 228, 66)
Blue: #0072B2 ( 0, 114, 178)
Vermillion: #D55E00 (213, 94, 0)
Purple: #CC79A7 (204, 121, 167)
Black: #000000 ( 0, 0, 0)
```
**Alternative: ColorBrewer Palettes**
- **Qualitative**: Set2, Paired, Dark2
- **Sequential**: Blues, Greens, Oranges (avoid Reds/Greens together)
- **Diverging**: RdBu (Red-Blue), PuOr (Purple-Orange)
**Colors to Avoid Together**
- Red-Green combinations (8% of males cannot distinguish)
- Blue-Purple combinations
- Yellow-Light green combinations
### 2. Redundant Encoding
Don't rely on color alone. Use multiple visual channels:
**Shape + Color**
```
Circle + Blue = Condition A
Square + Orange = Condition B
Triangle + Green = Condition C
```
**Line Style + Color**
```
Solid + Blue = Treatment 1
Dashed + Orange = Treatment 2
Dotted + Green = Control
```
**Pattern Fill + Color**
```
Solid fill + Blue = Group A
Diagonal stripes + Orange = Group B
Cross-hatch + Green = Group C
```
### 3. Grayscale Compatibility
**Test Requirement**: All diagrams must be interpretable in grayscale
**Strategies**
- Use different shades (light, medium, dark)
- Add patterns or textures to filled areas
- Vary line styles (solid, dashed, dotted)
- Use labels directly on elements
- Include text annotations
**Grayscale Test**
```bash
# Convert to grayscale to test
convert diagram.pdf -colorspace gray diagram_gray.pdf
```
### 4. Contrast Requirements
**Minimum Contrast Ratios (WCAG Guidelines)**
- **Normal text**: 4.5:1
- **Large text** (≥18pt): 3:1
- **Graphical elements**: 3:1
**High Contrast Practices**
- Dark text on light background (or vice versa)
- Avoid low-contrast color pairs (yellow on white, light gray on white)
- Use black or dark gray for critical text
- White text on dark backgrounds needs larger font size
### 5. Alternative Text and Descriptions
**Figure Captions Must Include**
- Description of diagram type
- All abbreviations spelled out
- Explanation of symbols and colors
- Sample sizes (n) where relevant
- Statistical annotations explained
- Reference to detailed methods if applicable
**Example Caption**
"Participant flow diagram following CONSORT guidelines. Rectangles represent study stages, with participant numbers (n) shown. Exclusion criteria are listed beside each screening stage. Final analysis included n=350 participants across two groups."
## Design Principles
### 1. Simplicity and Clarity
**Occam's Razor for Diagrams**
- Remove every element that doesn't add information
- Simplify complex relationships
- Break complex diagrams into multiple panels
- Use consistent layouts across related figures
**Visual Hierarchy**
- Most important elements: Largest, darkest, central
- Supporting elements: Smaller, lighter, peripheral
- Annotations: Minimal, clear labels only
### 2. Consistency
**Within a Figure**
- Same shape/color represents same concept
- Consistent arrow styles for same relationships
- Uniform spacing and alignment
- Matching font sizes for similar elements
**Across Figures in a Paper**
- Reuse color schemes
- Maintain consistent node styles
- Use same notation system
- Apply same layout principles
### 3. Professional Appearance
**Alignment**
- Use grids for node placement
- Align nodes horizontally or vertically
- Evenly space elements
- Center labels within shapes
**White Space**
- Don't overcrowd diagrams
- Leave breathing room around elements
- Use white space to group related items
- Margins around entire diagram
**Polish**
- No jagged lines or misaligned elements
- Smooth curves and precise angles
- Clean connection points
- No overlapping text
## Common Pitfalls and Solutions
### Pitfall 1: Overcomplicated Diagrams
**Problem**: Too much information in one diagram
**Solution**:
- Split into multiple panels (A, B, C)
- Create overview + detailed diagrams
- Move details to supplementary figures
- Use hierarchical presentation
### Pitfall 2: Inconsistent Styling
**Problem**: Different styles for same elements across figures
**Solution**:
- Create and use style templates
- Use the same color palette throughout
- Document your style choices
### Pitfall 3: Poor Label Placement
**Problem**: Labels overlap elements or are hard to read
**Solution**:
- Place labels outside shapes when possible
- Use leader lines for distant labels
- Rotate text only when necessary
- Ensure adequate contrast with background
### Pitfall 4: Tiny Text
**Problem**: Text too small to read at final print size
**Solution**:
- Design at final size from the start
- Test print at final size
- Minimum 7-8 pt font
- Simplify labels if space is limited
### Pitfall 5: Ambiguous Arrows
**Problem**: Unclear what arrows represent or where they point
**Solution**:
- Use different arrow styles for different meanings
- Add labels to arrows
- Include legend for arrow types
- Use anchor points for precise connections
### Pitfall 6: Color Overuse
**Problem**: Too many colors, confusing or inaccessible
**Solution**:
- Limit to 3-5 colors maximum
- Use color purposefully (categories, emphasis)
- Stick to colorblind-safe palette
- Provide redundant encoding
## Quality Control Checklist
### Before Submission
**Technical Requirements**
- [ ] Correct file format (PDF/EPS preferred for diagrams)
- [ ] Sufficient resolution (vector or 300+ DPI)
- [ ] Appropriate size (matches journal column width)
- [ ] Fonts embedded in PDF
- [ ] No compression artifacts
**Accessibility**
- [ ] Colorblind-safe palette used
- [ ] Works in grayscale (tested)
- [ ] Text minimum 7-8 pt at final size
- [ ] High contrast between elements
- [ ] Redundant encoding (not color alone)
**Design Quality**
- [ ] Elements aligned properly
- [ ] Consistent spacing and layout
- [ ] No overlapping text or elements
- [ ] Clear visual hierarchy
- [ ] Professional appearance
**Content**
- [ ] All elements labeled
- [ ] Abbreviations defined
- [ ] Units included where relevant
- [ ] Legend provided if needed
- [ ] Caption comprehensive
**Consistency**
- [ ] Matches other figures in style
- [ ] Same notation as text
- [ ] Consistent with journal guidelines
- [ ] Cross-references work
## Journal-Specific Guidelines
### Nature
**Figure Requirements**
- **Size**: 89 mm (single) or 183 mm (double column)
- **Format**: PDF, EPS, or high-res TIFF
- **Fonts**: Sans-serif preferred
- **File size**: <10 MB per file
- **Resolution**: 300 DPI minimum for raster
**Style Notes**
- Panel labels: lowercase bold (a, b, c)
- Simple, clean design
- Minimal colors
- Clear captions
### Science
**Figure Requirements**
- **Size**: 55 mm (single) or 120 mm (double column)
- **Format**: PDF, EPS, TIFF, or JPEG (high quality)
- **Resolution**: 300 DPI for photos, 600 DPI for line art
- **File size**: <10 MB
- **Fonts**: 6-7 pt minimum
**Style Notes**
- Panel labels: capital bold (A, B, C)
- High contrast
- Readable at small size
### Cell
**Figure Requirements**
- **Size**: 85 mm (single) or 178 mm (double column)
- **Format**: PDF preferred, TIFF, EPS acceptable
- **Resolution**: 300 DPI minimum
- **Fonts**: 8-10 pt for labels
- **Line weight**: 0.5 pt minimum
**Style Notes**
- Clean, professional
- Color or grayscale
- Panel labels capital (A, B, C)
### IEEE
**Figure Requirements**
- **Size**: 3.5 in (single) or 7.16 in (double column)
- **Format**: PDF, EPS (vector preferred)
- **Resolution**: 600 DPI for line art, 300 DPI for halftone
- **Fonts**: 8-10 pt minimum
- **Color**: Grayscale in print, color in digital
**Style Notes**
- Follow IEEE Graphics Manual
- Standard symbols for circuits
- Technical precision
- Clear axis labels
## Software-Specific Export Settings
### AI-Generated Images
AI-generated diagrams are exported as PNG images and can be included in LaTeX documents using:
```latex
\includegraphics[width=\textwidth]{diagram.png}
```
### Python (Matplotlib) Export
```python
import matplotlib.pyplot as plt
# Set publication quality
plt.rcParams['font.family'] = 'sans-serif'
plt.rcParams['font.sans-serif'] = ['Arial']
plt.rcParams['font.size'] = 8
plt.rcParams['pdf.fonttype'] = 42 # TrueType fonts in PDF
# Save with proper DPI and cropping
fig.savefig('diagram.pdf', dpi=300, bbox_inches='tight',
pad_inches=0.1, transparent=False)
fig.savefig('diagram.png', dpi=300, bbox_inches='tight')
```
### Schemdraw Export
```python
import schemdraw
d = schemdraw.Drawing()
# ... build circuit ...
# Export
d.save('circuit.svg') # Vector
d.save('circuit.pdf') # Vector
d.save('circuit.png', dpi=300) # Raster
```
### Inkscape Command Line
```bash
# PDF to high-res PNG
inkscape diagram.pdf --export-png=diagram.png --export-dpi=300
# SVG to PDF
inkscape diagram.svg --export-pdf=diagram.pdf
```
## Version Control Best Practices
**Keep Source Files**
- Save original .tex, .py, or .svg files
- Use descriptive filenames with versions
- Document color palette and style choices
- Include README with regeneration instructions
**Directory Structure**
```
figures/
├── source/ # Editable source files
│ ├── diagram1.tex
│ ├── circuit.py
│ └── pathway.svg
├── generated/ # Auto-generated outputs
│ ├── diagram1.pdf
│ ├── circuit.pdf
│ └── pathway.pdf
└── final/ # Final submission versions
├── figure1.pdf
└── figure2.pdf
```
**Git Tracking**
- Track source files (.tex, .py)
- Consider .gitignore for generated PDFs (large files)
- Use releases/tags for submission versions
- Document generation process in README
## Testing and Validation
### Pre-Submission Tests
**Visual Tests**
1. **Print test**: Print at final size, check readability
2. **Grayscale test**: Convert to grayscale, verify interpretability
3. **Zoom test**: View at 400% and 25% to check scalability
4. **Screen test**: View on different devices (phone, tablet, desktop)
**Technical Tests**
1. **Font embedding**: Check PDF properties
2. **Resolution check**: Verify DPI meets requirements
3. **File size**: Ensure under journal limits
4. **Format compliance**: Verify accepted format
**Accessibility Tests**
1. **Colorblind simulation**: Use tools like Color Oracle
2. **Contrast checker**: WCAG contrast ratio tools
3. **Screen reader**: Test alt text (for web figures)
### Tools for Testing
**Colorblind Simulation**
- Color Oracle (free, cross-platform)
- Coblis (Color Blindness Simulator)
- Photoshop/GIMP colorblind preview modes
**PDF Inspection**
```bash
# Check PDF properties
pdfinfo diagram.pdf
# Check fonts
pdffonts diagram.pdf
# Check image resolution
identify -verbose diagram.pdf
```
**Contrast Checking**
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
- Colorable: https://colorable.jxnblk.com/
## Summary: Golden Rules
1. **Vector first**: Always use vector formats when possible
2. **Design at final size**: Avoid scaling after creation
3. **Colorblind-safe palette**: Use Okabe-Ito or similar
4. **Test in grayscale**: Diagrams must work without color
5. **Minimum 7-8 pt text**: At final print size
6. **Consistent styling**: Across all figures in paper
7. **Keep it simple**: Remove unnecessary elements
8. **High contrast**: Ensure readability
9. **Align elements**: Professional appearance matters
10. **Comprehensive caption**: Explain everything
## Further Resources
- **Nature Figure Preparation**: https://www.nature.com/nature/for-authors/final-submission
- **Science Figure Guidelines**: https://www.science.org/content/page/instructions-preparing-initial-manuscript
- **WCAG Accessibility Standards**: https://www.w3.org/WAI/WCAG21/quickref/
- **Color Universal Design (CUD)**: https://jfly.uni-koeln.de/color/
- **ColorBrewer**: https://colorbrewer2.org/
Following these best practices ensures your diagrams meet publication standards and effectively communicate to all readers, regardless of colorblindness or viewing conditions.

109
skills/scientific-schematics/scripts/generate_schematic.py Normal file
View File

@@ -0,0 +1,109 @@
#!/usr/bin/env python3
"""
Scientific schematic generation using Nano Banana Pro.
Generate any scientific diagram by describing it in natural language.
Nano Banana Pro handles everything automatically with iterative refinement.
Usage:
# Generate any diagram
python generate_schematic.py "CONSORT flowchart" -o flowchart.png
# Neural network architecture
python generate_schematic.py "Transformer architecture" -o transformer.png
# Biological pathway
python generate_schematic.py "MAPK signaling pathway" -o pathway.png
"""
import argparse
import os
import subprocess
import sys
from pathlib import Path
def main():
"""Command-line interface."""
parser = argparse.ArgumentParser(
description="Generate scientific schematics using AI with iterative refinement",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
How it works:
Simply describe your diagram in natural language
Nano Banana Pro generates it automatically with:
- Iterative refinement (3 rounds by default)
- Automatic quality review and improvement
- Publication-ready output
Examples:
# Generate any diagram
python generate_schematic.py "CONSORT participant flow" -o flowchart.png
# Custom iterations for complex diagrams
python generate_schematic.py "Transformer architecture" -o arch.png --iterations 5
# Verbose output
python generate_schematic.py "Circuit diagram" -o circuit.png -v
Environment Variables:
OPENROUTER_API_KEY Required for AI generation
"""
)
parser.add_argument("prompt",
help="Description of the diagram to generate")
parser.add_argument("-o", "--output", required=True,
help="Output file path")
parser.add_argument("--iterations", type=int, default=3,
help="Number of AI refinement iterations (default: 3)")
parser.add_argument("--api-key",
help="OpenRouter API key (or use OPENROUTER_API_KEY env var)")
parser.add_argument("-v", "--verbose", action="store_true",
help="Verbose output")
args = parser.parse_args()
# Check for API key
api_key = args.api_key or os.getenv("OPENROUTER_API_KEY")
if not api_key:
print("Error: OPENROUTER_API_KEY environment variable not set")
print("\nFor AI generation, you need an OpenRouter API key.")
print("Get one at: https://openrouter.ai/keys")
print("\nSet it with:")
print(" export OPENROUTER_API_KEY='your_api_key'")
print("\nOr use --api-key flag")
sys.exit(1)
# Find AI generation script
script_dir = Path(__file__).parent
ai_script = script_dir / "generate_schematic_ai.py"
if not ai_script.exists():
print(f"Error: AI generation script not found: {ai_script}")
sys.exit(1)
# Build command
cmd = [sys.executable, str(ai_script), args.prompt, "-o", args.output]
if args.iterations != 3:
cmd.extend(["--iterations", str(args.iterations)])
if api_key:
cmd.extend(["--api-key", api_key])
if args.verbose:
cmd.append("-v")
# Execute
try:
result = subprocess.run(cmd, check=False)
sys.exit(result.returncode)
except Exception as e:
print(f"Error executing AI generation: {e}")
sys.exit(1)
if __name__ == "__main__":
main()

672
skills/scientific-schematics/scripts/generate_schematic_ai.py Normal file
View File

@@ -0,0 +1,672 @@
#!/usr/bin/env python3
"""
AI-powered scientific schematic generation using Nano Banana Pro.
This script uses an iterative refinement approach:
1. Generate initial image with Nano Banana Pro
2. AI quality review for scientific critique
3. Improve prompt based on critique and regenerate
4. Repeat for 3 iterations to achieve publication-quality results
Requirements:
- OPENROUTER_API_KEY environment variable
- requests library
Usage:
python generate_schematic_ai.py "Create a flowchart showing CONSORT participant flow" -o flowchart.png
python generate_schematic_ai.py "Neural network architecture diagram" -o architecture.png --iterations 3
"""
import argparse
import base64
import json
import os
import sys
import time
from pathlib import Path
from typing import Optional, Dict, Any, List, Tuple
try:
import requests
except ImportError:
print("Error: requests library not found. Install with: pip install requests")
sys.exit(1)
# Try to load .env file from multiple potential locations
def _load_env_file():
"""Load .env file from current directory, parent directories, or package directory."""
try:
from dotenv import load_dotenv
from pathlib import Path
# Try current working directory first
if load_dotenv():
return True
# Try parent directories (up to 5 levels)
cwd = Path.cwd()
for _ in range(5):
env_path = cwd / ".env"
if env_path.exists():
load_dotenv(dotenv_path=env_path)
return True
cwd = cwd.parent
if cwd == cwd.parent: # Reached root
break
# Try the package's parent directory (scientific-writer project root)
script_dir = Path(__file__).resolve().parent
for _ in range(5):
env_path = script_dir / ".env"
if env_path.exists():
load_dotenv(dotenv_path=env_path)
return True
script_dir = script_dir.parent
if script_dir == script_dir.parent:
break
return False
except ImportError:
return False # python-dotenv not installed
_load_env_file()
class ScientificSchematicGenerator:
"""Generate scientific schematics using AI with iterative refinement."""
# Scientific diagram best practices prompt template
SCIENTIFIC_DIAGRAM_GUIDELINES = """
Create a high-quality scientific diagram with these requirements:
VISUAL QUALITY:
- Clean white or light background (no textures or gradients)
- High contrast for readability and printing
- Professional, publication-ready appearance
- Sharp, clear lines and text
- Adequate spacing between elements to prevent crowding
TYPOGRAPHY:
- Clear, readable sans-serif fonts (Arial, Helvetica style)
- Minimum 10pt font size for all labels
- Consistent font sizes throughout
- All text horizontal or clearly readable
- No overlapping text
SCIENTIFIC STANDARDS:
- Accurate representation of concepts
- Clear labels for all components
- Include scale bars, legends, or axes where appropriate
- Use standard scientific notation and symbols
- Include units where applicable
ACCESSIBILITY:
- Colorblind-friendly color palette (use Okabe-Ito colors if using color)
- High contrast between elements
- Redundant encoding (shapes + colors, not just colors)
- Works well in grayscale
LAYOUT:
- Logical flow (left-to-right or top-to-bottom)
- Clear visual hierarchy
- Balanced composition
- Appropriate use of whitespace
- No clutter or unnecessary decorative elements
"""
def __init__(self, api_key: Optional[str] = None, verbose: bool = False):
"""
Initialize the generator.
Args:
api_key: OpenRouter API key (or use OPENROUTER_API_KEY env var)
verbose: Print detailed progress information
"""
self.api_key = api_key or os.getenv("OPENROUTER_API_KEY")
if not self.api_key:
raise ValueError("OPENROUTER_API_KEY environment variable not set or api_key not provided")
self.verbose = verbose
self.base_url = "https://openrouter.ai/api/v1"
self.image_model = "google/gemini-3-pro-image-preview"
# Use vision-capable model for review (Gemini Pro Vision or Claude Sonnet)
self.review_model = "google/gemini-pro-vision"
def _log(self, message: str):
"""Log message if verbose mode is enabled."""
if self.verbose:
print(f"[{time.strftime('%H:%M:%S')}] {message}")
def _make_request(self, model: str, messages: List[Dict[str, Any]],
modalities: Optional[List[str]] = None) -> Dict[str, Any]:
"""
Make a request to OpenRouter API.
Args:
model: Model identifier
messages: List of message dictionaries
modalities: Optional list of modalities (e.g., ["image", "text"])
Returns:
API response as dictionary
"""
headers = {
"Authorization": f"Bearer {self.api_key}",
"Content-Type": "application/json",
"HTTP-Referer": "https://github.com/scientific-writer",
"X-Title": "Scientific Schematic Generator"
}
payload = {
"model": model,
"messages": messages
}
if modalities:
payload["modalities"] = modalities
self._log(f"Making request to {model}...")
try:
response = requests.post(
f"{self.base_url}/chat/completions",
headers=headers,
json=payload,
timeout=120
)
# Try to get response body even on error
try:
response_json = response.json()
except json.JSONDecodeError:
response_json = {"raw_text": response.text[:500]}
# Check for HTTP errors but include response body in error message
if response.status_code != 200:
error_detail = response_json.get("error", response_json)
self._log(f"HTTP {response.status_code}: {error_detail}")
raise RuntimeError(f"API request failed (HTTP {response.status_code}): {error_detail}")
return response_json
except requests.exceptions.Timeout:
raise RuntimeError("API request timed out after 120 seconds")
except requests.exceptions.RequestException as e:
raise RuntimeError(f"API request failed: {str(e)}")
def _extract_image_from_response(self, response: Dict[str, Any]) -> Optional[bytes]:
"""
Extract base64-encoded image from API response.
For Nano Banana Pro, images are returned in the 'images' field of the message,
not in the 'content' field.
Args:
response: API response dictionary
Returns:
Image bytes or None if not found
"""
try:
choices = response.get("choices", [])
if not choices:
self._log("No choices in response")
return None
message = choices[0].get("message", {})
# IMPORTANT: Nano Banana Pro returns images in the 'images' field
images = message.get("images", [])
if images and len(images) > 0:
self._log(f"Found {len(images)} image(s) in 'images' field")
# Get first image
first_image = images[0]
if isinstance(first_image, dict):
# Extract image_url
if first_image.get("type") == "image_url":
url = first_image.get("image_url", {})
if isinstance(url, dict):
url = url.get("url", "")
if url and url.startswith("data:image"):
# Extract base64 data after comma
if "," in url:
base64_str = url.split(",", 1)[1]
# Clean whitespace
base64_str = base64_str.replace('\n', '').replace('\r', '').replace(' ', '')
self._log(f"Extracted base64 data (length: {len(base64_str)})")
return base64.b64decode(base64_str)
# Fallback: check content field (for other models or future changes)
content = message.get("content", "")
if self.verbose:
self._log(f"Content type: {type(content)}, length: {len(str(content))}")
# Handle string content
if isinstance(content, str) and "data:image" in content:
import re
match = re.search(r'data:image/[^;]+;base64,([A-Za-z0-9+/=\n\r]+)', content, re.DOTALL)
if match:
base64_str = match.group(1).replace('\n', '').replace('\r', '').replace(' ', '')
self._log(f"Found image in content field (length: {len(base64_str)})")
return base64.b64decode(base64_str)
# Handle list content
if isinstance(content, list):
for i, block in enumerate(content):
if isinstance(block, dict) and block.get("type") == "image_url":
url = block.get("image_url", {})
if isinstance(url, dict):
url = url.get("url", "")
if url and url.startswith("data:image") and "," in url:
base64_str = url.split(",", 1)[1].replace('\n', '').replace('\r', '').replace(' ', '')
self._log(f"Found image in content block {i}")
return base64.b64decode(base64_str)
self._log("No image data found in response")
return None
except Exception as e:
self._log(f"Error extracting image: {str(e)}")
import traceback
if self.verbose:
traceback.print_exc()
return None
def _image_to_base64(self, image_path: str) -> str:
"""
Convert image file to base64 data URL.
Args:
image_path: Path to image file
Returns:
Base64 data URL string
"""
with open(image_path, "rb") as f:
image_data = f.read()
# Determine image type from extension
ext = Path(image_path).suffix.lower()
mime_type = {
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".gif": "image/gif",
".webp": "image/webp"
}.get(ext, "image/png")
base64_data = base64.b64encode(image_data).decode("utf-8")
return f"data:{mime_type};base64,{base64_data}"
def generate_image(self, prompt: str) -> Optional[bytes]:
"""
Generate an image using Nano Banana Pro.
Args:
prompt: Description of the diagram to generate
Returns:
Image bytes or None if generation failed
"""
messages = [
{
"role": "user",
"content": prompt
}
]
try:
response = self._make_request(
model=self.image_model,
messages=messages,
modalities=["image", "text"]
)
# Debug: print response structure if verbose
if self.verbose:
self._log(f"Response keys: {response.keys()}")
if "error" in response:
self._log(f"API Error: {response['error']}")
if "choices" in response and response["choices"]:
msg = response["choices"][0].get("message", {})
self._log(f"Message keys: {msg.keys()}")
# Show content preview without printing huge base64 data
content = msg.get("content", "")
if isinstance(content, str):
preview = content[:200] + "..." if len(content) > 200 else content
self._log(f"Content preview: {preview}")
elif isinstance(content, list):
self._log(f"Content is list with {len(content)} items")
for i, item in enumerate(content[:3]):
if isinstance(item, dict):
self._log(f" Item {i}: type={item.get('type')}")
# Check for API errors in response
if "error" in response:
error_msg = response["error"]
if isinstance(error_msg, dict):
error_msg = error_msg.get("message", str(error_msg))
print(f"✗ API Error: {error_msg}")
return None
image_data = self._extract_image_from_response(response)
if image_data:
self._log(f"✓ Generated image ({len(image_data)} bytes)")
else:
self._log("✗ No image data in response")
# Additional debug info when image extraction fails
if self.verbose and "choices" in response:
msg = response["choices"][0].get("message", {})
self._log(f"Full message structure: {json.dumps({k: type(v).__name__ for k, v in msg.items()})}")
return image_data
except Exception as e:
self._log(f"✗ Generation failed: {str(e)}")
import traceback
if self.verbose:
traceback.print_exc()
return None
def review_image(self, image_path: str, original_prompt: str,
iteration: int) -> Tuple[str, float]:
"""
Review generated image using AI quality analysis.
Args:
image_path: Path to the generated image
original_prompt: Original user prompt
iteration: Current iteration number
Returns:
Tuple of (critique text, quality score 0-10)
"""
# For now, use Nano Banana Pro itself for review (it has vision capabilities)
# This is more reliable than using a separate vision model
image_data_url = self._image_to_base64(image_path)
review_prompt = f"""You are reviewing a scientific diagram you just generated.
ORIGINAL REQUEST: {original_prompt}
ITERATION: {iteration}/3
Evaluate this diagram on:
1. Scientific accuracy
2. Clarity and readability
3. Label quality
4. Layout and composition
5. Professional appearance
Provide a score (0-10) and specific suggestions for improvement."""
messages = [
{
"role": "user",
"content": [
{
"type": "text",
"text": review_prompt
},
{
"type": "image_url",
"image_url": {
"url": image_data_url
}
}
]
}
]
try:
# Use the same Nano Banana Pro model for review (it has vision)
response = self._make_request(
model=self.image_model, # Use Nano Banana Pro for review too
messages=messages
)
# Extract text response
choices = response.get("choices", [])
if not choices:
return "Image generated successfully", 8.0
message = choices[0].get("message", {})
content = message.get("content", "")
# Check reasoning field (Nano Banana Pro puts analysis here)
reasoning = message.get("reasoning", "")
if reasoning and not content:
content = reasoning
if isinstance(content, list):
# Extract text from content blocks
text_parts = []
for block in content:
if isinstance(block, dict) and block.get("type") == "text":
text_parts.append(block.get("text", ""))
content = "\n".join(text_parts)
# Try to extract score
score = 8.0 # Default to good score if review works
import re
score_match = re.search(r'(?:score|rating|quality)[:\s]+(\d+(?:\.\d+)?)\s*/\s*10', content, re.IGNORECASE)
if score_match:
score = float(score_match.group(1))
self._log(f"✓ Review complete (Score: {score}/10)")
return content if content else "Image generated successfully", score
except Exception as e:
self._log(f"Review skipped: {str(e)}")
# Don't fail the whole process if review fails
return "Image generated successfully (review skipped)", 8.0
def improve_prompt(self, original_prompt: str, critique: str,
iteration: int) -> str:
"""
Improve the generation prompt based on critique.
Args:
original_prompt: Original user prompt
critique: Review critique from previous iteration
iteration: Current iteration number
Returns:
Improved prompt for next generation
"""
improved_prompt = f"""{self.SCIENTIFIC_DIAGRAM_GUIDELINES}
USER REQUEST: {original_prompt}
ITERATION {iteration}: Based on previous feedback, address these specific improvements:
{critique}
Generate an improved version that addresses all the critique points while maintaining scientific accuracy and professional quality."""
return improved_prompt
def generate_iterative(self, user_prompt: str, output_path: str,
iterations: int = 3) -> Dict[str, Any]:
"""
Generate scientific schematic with iterative refinement.
Args:
user_prompt: User's description of desired diagram
output_path: Path to save final image
iterations: Number of refinement iterations (default: 3)
Returns:
Dictionary with generation results and metadata
"""
output_path = Path(output_path)
output_dir = output_path.parent
output_dir.mkdir(parents=True, exist_ok=True)
base_name = output_path.stem
extension = output_path.suffix or ".png"
results = {
"user_prompt": user_prompt,
"iterations": [],
"final_image": None,
"final_score": 0.0,
"success": False
}
current_prompt = f"""{self.SCIENTIFIC_DIAGRAM_GUIDELINES}
USER REQUEST: {user_prompt}
Generate a publication-quality scientific diagram that meets all the guidelines above."""
print(f"\n{'='*60}")
print(f"Generating Scientific Schematic")
print(f"{'='*60}")
print(f"Description: {user_prompt}")
print(f"Iterations: {iterations}")
print(f"Output: {output_path}")
print(f"{'='*60}\n")
for i in range(1, iterations + 1):
print(f"\n[Iteration {i}/{iterations}]")
print("-" * 40)
# Generate image
print(f"Generating image...")
image_data = self.generate_image(current_prompt)
if not image_data:
print(f"✗ Generation failed")
results["iterations"].append({
"iteration": i,
"success": False,
"error": "Image generation failed"
})
continue
# Save iteration image
iter_path = output_dir / f"{base_name}_v{i}{extension}"
with open(iter_path, "wb") as f:
f.write(image_data)
print(f"✓ Saved: {iter_path}")
# Review image (skip on last iteration if desired, but we'll do it for completeness)
print(f"Reviewing image...")
critique, score = self.review_image(str(iter_path), user_prompt, i)
print(f"✓ Score: {score}/10")
# Save iteration results
iteration_result = {
"iteration": i,
"image_path": str(iter_path),
"prompt": current_prompt,
"critique": critique,
"score": score,
"success": True
}
results["iterations"].append(iteration_result)
# If this is the last iteration, we're done
if i == iterations:
results["final_image"] = str(iter_path)
results["final_score"] = score
results["success"] = True
break
# Improve prompt for next iteration
print(f"Improving prompt based on feedback...")
current_prompt = self.improve_prompt(user_prompt, critique, i + 1)
# Copy final version to output path
if results["success"] and results["final_image"]:
final_iter_path = Path(results["final_image"])
if final_iter_path != output_path:
import shutil
shutil.copy(final_iter_path, output_path)
print(f"\n✓ Final image: {output_path}")
# Save review log
log_path = output_dir / f"{base_name}_review_log.json"
with open(log_path, "w") as f:
json.dump(results, f, indent=2)
print(f"✓ Review log: {log_path}")
print(f"\n{'='*60}")
print(f"Generation Complete!")
print(f"Final Score: {results['final_score']}/10")
print(f"{'='*60}\n")
return results
def main():
"""Command-line interface."""
parser = argparse.ArgumentParser(
description="Generate scientific schematics using AI with iterative refinement",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
Examples:
# Generate a flowchart
python generate_schematic_ai.py "CONSORT participant flow diagram" -o flowchart.png
# Generate neural network architecture
python generate_schematic_ai.py "Transformer encoder-decoder architecture" -o transformer.png
# Generate with custom iterations
python generate_schematic_ai.py "Biological signaling pathway" -o pathway.png --iterations 5
# Verbose output
python generate_schematic_ai.py "Circuit diagram" -o circuit.png -v
Environment:
OPENROUTER_API_KEY OpenRouter API key (required)
"""
)
parser.add_argument("prompt", help="Description of the diagram to generate")
parser.add_argument("-o", "--output", required=True,
help="Output image path (e.g., diagram.png)")
parser.add_argument("--iterations", type=int, default=3,
help="Number of refinement iterations (default: 3)")
parser.add_argument("--api-key", help="OpenRouter API key (or set OPENROUTER_API_KEY)")
parser.add_argument("-v", "--verbose", action="store_true",
help="Verbose output")
args = parser.parse_args()
# Check for API key
api_key = args.api_key or os.getenv("OPENROUTER_API_KEY")
if not api_key:
print("Error: OPENROUTER_API_KEY environment variable not set")
print("\nSet it with:")
print(" export OPENROUTER_API_KEY='your_api_key'")
print("\nOr provide via --api-key flag")
sys.exit(1)
# Validate iterations
if args.iterations < 1 or args.iterations > 10:
print("Error: Iterations must be between 1 and 10")
sys.exit(1)
try:
generator = ScientificSchematicGenerator(api_key=api_key, verbose=args.verbose)
results = generator.generate_iterative(
user_prompt=args.prompt,
output_path=args.output,
iterations=args.iterations
)
if results["success"]:
print(f"\n✓ Success! Image saved to: {args.output}")
sys.exit(0)
else:
print(f"\n✗ Generation failed. Check review log for details.")
sys.exit(1)
except Exception as e:
print(f"\n✗ Error: {str(e)}")
sys.exit(1)
if __name__ == "__main__":
main()

243
skills/scientific-schematics/test_ai_generation.py Normal file
View File

@@ -0,0 +1,243 @@
#!/usr/bin/env python3
"""
Test script to verify AI generation implementation.
This script performs dry-run tests without making actual API calls.
It verifies:
1. Script structure and imports
2. Class initialization
3. Method signatures
4. Error handling
5. Command-line interface
Usage:
python test_ai_generation.py
"""
import sys
import os
from pathlib import Path
# Add scripts directory to path
scripts_dir = Path(__file__).parent / "scripts"
sys.path.insert(0, str(scripts_dir))
def test_imports():
"""Test that all required modules can be imported."""
print("Testing imports...")
try:
from generate_schematic_ai import ScientificSchematicGenerator
print("✓ generate_schematic_ai imports successfully")
return True
except ImportError as e:
print(f"✗ Import failed: {e}")
return False
def test_class_structure():
"""Test class initialization and structure."""
print("\nTesting class structure...")
try:
from generate_schematic_ai import ScientificSchematicGenerator
# Test initialization with dummy key
generator = ScientificSchematicGenerator(api_key="test_key", verbose=False)
print("✓ Class initializes successfully")
# Check required methods exist
required_methods = [
'generate_image',
'review_image',
'improve_prompt',
'generate_iterative'
]
for method in required_methods:
if not hasattr(generator, method):
print(f"✗ Missing method: {method}")
return False
print(f"✓ Method exists: {method}")
# Check attributes
if not hasattr(generator, 'api_key'):
print("✗ Missing attribute: api_key")
return False
print("✓ Attribute exists: api_key")
if not hasattr(generator, 'image_model'):
print("✗ Missing attribute: image_model")
return False
print(f"✓ Image model: {generator.image_model}")
if not hasattr(generator, 'review_model'):
print("✗ Missing attribute: review_model")
return False
print(f"✓ Review model: {generator.review_model}")
return True
except Exception as e:
print(f"✗ Class structure test failed: {e}")
return False
def test_error_handling():
"""Test error handling for missing API key."""
print("\nTesting error handling...")
try:
from generate_schematic_ai import ScientificSchematicGenerator
# Clear environment variable
old_key = os.environ.get("OPENROUTER_API_KEY")
if old_key:
del os.environ["OPENROUTER_API_KEY"]
# Try to initialize without key
try:
generator = ScientificSchematicGenerator()
print("✗ Should have raised ValueError for missing API key")
return False
except ValueError as e:
if "OPENROUTER_API_KEY" in str(e):
print("✓ Correctly raises ValueError for missing API key")
else:
print(f"✗ Wrong error message: {e}")
return False
# Restore environment variable
if old_key:
os.environ["OPENROUTER_API_KEY"] = old_key
return True
except Exception as e:
print(f"✗ Error handling test failed: {e}")
return False
def test_wrapper_script():
"""Test wrapper script structure."""
print("\nTesting wrapper script...")
try:
import generate_schematic
print("✓ generate_schematic imports successfully")
# Check main functions exist
if not hasattr(generate_schematic, 'main'):
print("✗ Missing function: main")
return False
print("✓ Function exists: main")
return True
except Exception as e:
print(f"✗ Wrapper script test failed: {e}")
return False
def test_prompt_engineering():
"""Test prompt construction."""
print("\nTesting prompt engineering...")
try:
from generate_schematic_ai import ScientificSchematicGenerator
generator = ScientificSchematicGenerator(api_key="test_key", verbose=False)
# Test improve_prompt method
original = "Create a flowchart"
critique = "Add more spacing between boxes"
improved = generator.improve_prompt(original, critique, 2)
if not improved:
print("✗ improve_prompt returned empty string")
return False
if original not in improved:
print("✗ Improved prompt doesn't include original")
return False
if critique not in improved:
print("✗ Improved prompt doesn't include critique")
return False
if "ITERATION 2" not in improved:
print("✗ Improved prompt doesn't include iteration number")
return False
print("✓ Prompt engineering works correctly")
print(f" Original length: {len(original)} chars")
print(f" Improved length: {len(improved)} chars")
return True
except Exception as e:
print(f"✗ Prompt engineering test failed: {e}")
return False
def test_file_paths():
"""Test that all required files exist."""
print("\nTesting file structure...")
base_dir = Path(__file__).parent
required_files = [
"scripts/generate_schematic_ai.py",
"scripts/generate_schematic.py",
"SKILL.md",
"README.md"
]
all_exist = True
for file_path in required_files:
full_path = base_dir / file_path
if full_path.exists():
print(f"✓ {file_path}")
else:
print(f"✗ Missing: {file_path}")
all_exist = False
return all_exist
def main():
"""Run all tests."""
print("="*60)
print("Scientific Schematics AI Generation - Verification Tests")
print("="*60)
tests = [
("File Structure", test_file_paths),
("Imports", test_imports),
("Class Structure", test_class_structure),
("Error Handling", test_error_handling),
("Wrapper Script", test_wrapper_script),
("Prompt Engineering", test_prompt_engineering),
]
results = []
for test_name, test_func in tests:
try:
result = test_func()
results.append((test_name, result))
except Exception as e:
print(f"\n✗ Test '{test_name}' crashed: {e}")
results.append((test_name, False))
# Summary
print("\n" + "="*60)
print("Test Summary")
print("="*60)
passed = sum(1 for _, result in results if result)
total = len(results)
for test_name, result in results:
status = "✓ PASS" if result else "✗ FAIL"
print(f"{status}: {test_name}")
print(f"\nTotal: {passed}/{total} tests passed")
if passed == total:
print("\n✓ All tests passed! Implementation verified.")
print("\nNext steps:")
print("1. Set OPENROUTER_API_KEY environment variable")
print("2. Test with actual API call:")
print(" python scripts/generate_schematic.py 'test diagram' -o test.png")
return 0
else:
print(f"\n✗ {total - passed} test(s) failed. Please review errors above.")
return 1
if __name__ == "__main__":
sys.exit(main())