research-copilot 0.2.17 → 0.2.21

package/lib/skills/builtin/scientific-schematics/references/QUICK_REFERENCE.md

@@ -1,182 +0,0 @@
-# Scientific Schematics - Quick Reference
-
-**How it works:** Describe your diagram → AI generates it via OpenRouter automatically
-
-Path convention: use `@skill/...` for skill files and `@ws/...` for workspace inputs/outputs in shell commands.
-
-## Setup (One-Time)
-
-Default image model: `google/gemini-3-pro-image-preview`. Normal skill usage does not require choosing a model.
-
-```bash
-# Required
-export OPENROUTER_API_KEY='your-openrouter-api-key'
-```
-
-## Basic Usage
-
-```bash
-# Describe your diagram, AI creates it
-python @skill/scripts/generate_schematic.py "your diagram description" -o @ws/output.png
-
-# That's it! Automatic:
-# - Iterative refinement (up to 2 rounds)
-# - Quality review and improvement
-# - Publication-ready output
-```
-
-## Common Examples
-
-### CONSORT Flowchart
-```bash
-python @skill/scripts/generate_schematic.py \
-  "CONSORT flow: screened n=500, excluded n=150, randomized n=350" \
-  -o @ws/consort.png
-```
-
-### Neural Network
-```bash
-python @skill/scripts/generate_schematic.py \
-  "Transformer architecture with encoder and decoder stacks" \
-  -o @ws/transformer.png
-```
-
-### Biological Pathway
-```bash
-python @skill/scripts/generate_schematic.py \
-  "MAPK pathway: EGFR → RAS → RAF → MEK → ERK" \
-  -o @ws/mapk.png
-```
-
-### Circuit Diagram
-```bash
-python @skill/scripts/generate_schematic.py \
-  "Op-amp circuit with 1kΩ resistor and 10µF capacitor" \
-  -o @ws/circuit.png
-```
-
-## Command Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `-o, --output` | Output file path | `-o @ws/figures/diagram.png` |
-| `--iterations N` | Number of refinements (1-2) | `--iterations 2` |
-| `-v, --verbose` | Show detailed output | `-v` |
-
-## 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 `@ws/diagram.png`, you get:
-- `@ws/diagram_v1.png` - First iteration
-- `@ws/diagram_v2.png` - Second iteration
-- `@ws/diagram.png` - Copy of final
-- `@ws/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..."
-    },
-  ],
-  "final_score": 8.5
-}
-```
-
-## Supported Automation Interface
-
-```bash
-python @skill/scripts/generate_schematic.py "diagram description" -o @ws/output.png --iterations 2
-```
-
-Use the CLI wrapper inside workflows. Do not rely on importing private
-skill modules directly from Python.
-
-## Troubleshooting
-
-### API Key Not Found
-```bash
-# Set your OpenRouter API key
-export OPENROUTER_API_KEY='your-api-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 2`
-
-## Testing
-
-```bash
-# Smoke test
-python @skill/scripts/generate_schematic.py "test diagram" -o @ws/test.png -v
-```
-
-## Cost
-
-Typical cost per diagram (max 2 iterations):
-- Simple (1 iteration): $0.05-0.15
-- Complex (2 iterations): $0.10-0.30
-
-## How It 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 @skill/scripts/generate_schematic.py --help
-
-# Verbose mode for debugging
-python @skill/scripts/generate_schematic.py "diagram" -o @ws/out.png -v
-```
-
-## Quick Start Checklist
-
-- [ ] Set `OPENROUTER_API_KEY`
-- [ ] Run `python @skill/scripts/generate_schematic.py "test diagram" -o @ws/test.png -v`
-- [ ] Review output files (test_v1.png, test_v2.png, review_log.json)
-- [ ] Read SKILL.md for detailed documentation
-- [ ] Check README.md for examples
-
-## Resources
-
-- Full documentation: `@skill/SKILL.md`
-- Detailed guide: `@skill/references/README.md`
-- Example script: `@skill/scripts/example_usage.sh`

package/lib/skills/builtin/scientific-schematics/references/README.md

@@ -1,292 +0,0 @@
-# Scientific Schematics - OpenRouter API
-
-**Generate any scientific diagram by describing it in natural language.**
-
-AI image models create publication-quality diagrams automatically via OpenRouter - no coding, no templates, no manual drawing required.
-
-## Quick Start
-
-Default image model: `google/gemini-3-pro-image-preview`. Normal skill usage does not require model selection.
-
-### Generate Any Diagram
-
-```bash
-# Set your OpenRouter API key
-export OPENROUTER_API_KEY='your-openrouter-api-key'
-
-# Generate any scientific diagram
-python @skill/scripts/generate_schematic.py "CONSORT participant flow diagram" -o @ws/figures/consort.png
-
-# Neural network architecture
-python @skill/scripts/generate_schematic.py "Transformer encoder-decoder architecture" -o @ws/figures/transformer.png
-
-# Biological pathway
-python @skill/scripts/generate_schematic.py "MAPK signaling pathway" -o @ws/figures/pathway.png
-```
-
-### Path Conventions
-
-- Shell commands in this document use scoped paths:
-  - `@skill/...` points to skill-owned files.
-  - `@ws/...` points to workspace files.
-- Python API examples and generated review logs use raw filesystem paths (often workspace-relative like `figures/...`).
-
-### What You Get
-
-- **Up to two iterations** (v1, v2) 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. **Decision**: If quality meets threshold → DONE; otherwise continue
-4. **Generation 2**: Improve based on critique
-5. **Review 2**: Second evaluation with specific feedback
-
-### 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
-
-```bash
-# Set OpenRouter API key
-export OPENROUTER_API_KEY='your-openrouter-api-key'
-
-# Install Python dependencies (if not already installed)
-pip install requests
-```
-
-## Usage Examples
-
-### Example 1: CONSORT Flowchart
-
-```bash
-python @skill/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 @ws/figures/consort.png
-```
-
-**Output:**
-- `@ws/figures/consort_v1.png` - Initial generation
-- `@ws/figures/consort_v2.png` - After review (if needed)
-- `@ws/figures/consort.png` - Copy of final version
-- `@ws/figures/consort_review_log.json` - Detailed review log
-
-### Example 2: Neural Network Architecture
-
-```bash
-python @skill/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 @ws/figures/transformer.png \
-  --iterations 2
-```
-
-### Example 3: Biological Pathway
-
-```bash
-python @skill/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 @ws/figures/mapk.png
-```
-
-### Example 4: System Architecture
-
-```bash
-python @skill/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 @ws/figures/iot_system.png
-```
-
-## Command-Line Options
-
-```bash
-python @skill/scripts/generate_schematic.py [OPTIONS] "description" -o @ws/output.png
-
-Options:
-  --iterations N          Number of AI refinement iterations (default: 2, max: 2)
-  --doc-type TYPE         Document type for quality threshold (journal, poster, etc.)
-  --image-model MODEL     Override image generation model
-  --review-model MODEL    Override review model
-  -v, --verbose          Verbose output
-  -h, --help             Show help message
-```
-
-## Supported Automation Interface
-
-Use the CLI wrapper as the supported interface:
-
-```bash
-python @skill/scripts/generate_schematic.py \
-  "CONSORT flowchart" \
-  -o @ws/figures/consort.png \
-  --iterations 2
-```
-
-This skill does not ship as an installable Python package, so avoid direct
-`import scripts.generate_schematic_ai` patterns.
-
-## Prompt Engineering Tips
-
-### Be Specific About Layout
-- "Flowchart with vertical flow, top to bottom"
-- "Architecture diagram with encoder on left, decoder on right"
-- Avoid: "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"
-
-### 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...",
-  "doc_type": "default",
-  "quality_threshold": 7.5,
-  "iterations": [
-    {
-      "iteration": 1,
-      "image_path": "figures/consort_v1.png",
-      "score": 7.0,
-      "critique": "Score: 7/10. Issues: font too small...",
-      "success": true
-    },
-    {
-      "iteration": 2,
-      "image_path": "figures/consort_v2.png",
-      "score": 8.5,
-      "critique": "Much improved. Publication ready."
-    }
-  ],
-  "final_image": "figures/consort_v2.png",
-  "final_score": 8.5,
-  "success": true,
-  "early_stop": true,
-  "early_stop_reason": "Quality score 8.5 meets threshold 7.5 for default"
-}
-```
-
-Note: in review log JSON, file paths are stored as raw workspace-relative paths (`figures/...`), not scoped command prefixes.
-
-## Why Use AI Image Generation
-
-**Simply describe what you want - AI 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 API key is set
-echo $OPENROUTER_API_KEY
-
-# Set it if missing
-export OPENROUTER_API_KEY='your-api-key'
-```
-
-### Import Errors
-
-```bash
-# Install requests library
-pip install requests
-```
-
-### Generation Fails
-
-```bash
-# Use verbose mode to see detailed errors
-python @skill/scripts/generate_schematic.py "diagram" -o @ws/out.png -v
-```
-
-### 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 2`
-
-## Testing
-
-Run a simple smoke test:
-
-```bash
-python @skill/scripts/generate_schematic.py "test diagram" -o @ws/test.png -v
-```
-
-## Cost Considerations
-
-Costs depend on the models used via OpenRouter. Typical costs per diagram:
-- Simple diagram (1 iteration): ~$0.05-0.15
-- Complex diagram (2 iterations): ~$0.10-0.30
-
-## 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 a verbose smoke test with `python @skill/scripts/generate_schematic.py "test diagram" -o @ws/test.png -v`
-3. Use verbose mode (-v) to see detailed errors
-4. Review the review_log.json for quality feedback
-
-## License
-
-Part of the scientific-schematics skill. See main repository for license information.

package/lib/skills/builtin/scientific-schematics/scripts/example_usage.sh

@@ -1,85 +0,0 @@
-#!/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 is not set"
-    echo ""
-    echo "Set OPENROUTER_API_KEY='your-api-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 2
-
-echo ""
-echo "✓ Generated: figures/consort_example.png"
-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 ""

package/lib/skills/builtin/scientific-schematics/scripts/generate_schematic.py

@@ -1,141 +0,0 @@
-#!/usr/bin/env python3
-"""
-Scientific schematic generation using OpenRouter API.
-
-Generate any scientific diagram by describing it in natural language.
-AI handles everything automatically with smart iterative refinement.
-
-Smart iteration: Only regenerates if quality is below threshold for your document type.
-Quality review: Uses Gemini for professional scientific evaluation.
-
-Usage:
-    # Generate for journal paper (highest quality threshold)
-    python generate_schematic.py "CONSORT flowchart" -o flowchart.png --doc-type journal
-
-    # Generate for presentation (lower threshold, faster)
-    python generate_schematic.py "Transformer architecture" -o transformer.png --doc-type presentation
-
-    # Generate for poster
-    python generate_schematic.py "MAPK signaling pathway" -o pathway.png --doc-type poster
-"""
-
-import argparse
-import subprocess
-import sys
-from pathlib import Path
-
-
-def main():
-    """Command-line interface."""
-    parser = argparse.ArgumentParser(
-        description="Generate scientific schematics using AI with smart iterative refinement",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-How it works:
-  Simply describe your diagram in natural language.
-  AI generates it automatically via OpenRouter with:
-  - Smart iteration (only regenerates if quality is below threshold)
-  - Quality review by Gemini
-  - Document-type aware quality thresholds
-  - Publication-ready output
-
-Document Types (quality thresholds):
-  journal      8.5/10  - Nature, Science, peer-reviewed journals
-  conference   8.0/10  - Conference papers
-  thesis       8.0/10  - Dissertations, theses
-  grant        8.0/10  - Grant proposals
-  preprint     7.5/10  - arXiv, bioRxiv, etc.
-  report       7.5/10  - Technical reports
-  poster       7.0/10  - Academic posters
-  presentation 6.5/10  - Slides, talks
-  default      7.5/10  - General purpose
-
-Examples:
-  # Generate for journal paper (strict quality)
-  python generate_schematic.py "CONSORT participant flow" -o flowchart.png --doc-type journal
-
-  # Generate for poster (moderate quality)
-  python generate_schematic.py "Transformer architecture" -o arch.png --doc-type poster
-
-  # Generate for slides (faster, lower threshold)
-  python generate_schematic.py "System diagram" -o system.png --doc-type presentation
-
-  # Custom max iterations
-  python generate_schematic.py "Complex pathway" -o pathway.png --iterations 2
-
-  # Verbose output
-  python generate_schematic.py "Circuit diagram" -o circuit.png -v
-
-Environment Variables:
-  OPENROUTER_API_KEY  Required. Your OpenRouter API key.
-        """
-    )
-
-    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("--doc-type", default="default",
-                       choices=["journal", "conference", "poster", "presentation",
-                               "report", "grant", "thesis", "preprint", "default"],
-                       help="Document type for quality threshold (default: default)")
-    parser.add_argument("--iterations", type=int, default=2,
-                       help="Maximum refinement iterations (default: 2, max: 2)")
-    parser.add_argument("--api-key",
-                       help="OpenRouter API key (or use OPENROUTER_API_KEY)")
-    parser.add_argument("--image-model",
-                       help="Image generation model (default: google/gemini-3-pro-image-preview)")
-    parser.add_argument("--review-model",
-                       help="Review model (default: google/gemini-3-pro-preview)")
-    parser.add_argument("--timeout-seconds", type=int,
-                       help=argparse.SUPPRESS)
-    parser.add_argument("-v", "--verbose", action="store_true",
-                       help="Verbose output")
-
-    args = parser.parse_args()
-
-    # 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.doc_type != "default":
-        cmd.extend(["--doc-type", args.doc_type])
-
-    # Enforce max 2 iterations
-    iterations = min(args.iterations, 2)
-    if iterations != 2:
-        cmd.extend(["--iterations", str(iterations)])
-
-    if args.api_key:
-        cmd.extend(["--api-key", args.api_key])
-
-    if args.image_model:
-        cmd.extend(["--image-model", args.image_model])
-
-    if args.review_model:
-        cmd.extend(["--review-model", args.review_model])
-
-    if args.timeout_seconds:
-        cmd.extend(["--timeout-seconds", str(args.timeout_seconds)])
-
-    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()