scientific-writer 2.1.1__py3-none-any.whl → 2.2.2__py3-none-any.whl

scientific_writer/.claude/skills/markitdown/scripts/convert_with_ai.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Convert documents to Markdown with AI-enhanced image descriptions.
+
+This script demonstrates how to use MarkItDown with OpenRouter to generate
+detailed descriptions of images in documents (PowerPoint, PDFs with images, etc.)
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from markitdown import MarkItDown
+from openai import OpenAI
+
+
+# Predefined prompts for different use cases
+PROMPTS = {
+    'scientific': """
+Analyze this scientific image or diagram. Provide:
+1. Type of visualization (graph, chart, microscopy, diagram, etc.)
+2. Key data points, trends, or patterns
+3. Axes labels, legends, and scales
+4. Notable features or findings
+5. Scientific context and significance
+Be precise, technical, and detailed.
+    """.strip(),
+    
+    'presentation': """
+Describe this presentation slide image. Include:
+1. Main visual elements and their arrangement
+2. Key points or messages conveyed
+3. Data or information presented
+4. Visual hierarchy and emphasis
+Keep the description clear and informative.
+    """.strip(),
+    
+    'general': """
+Describe this image in detail. Include:
+1. Main subjects and objects
+2. Visual composition and layout
+3. Text content (if any)
+4. Notable details
+5. Overall context and purpose
+Be comprehensive and accurate.
+    """.strip(),
+    
+    'data_viz': """
+Analyze this data visualization. Provide:
+1. Type of chart/graph (bar, line, scatter, pie, etc.)
+2. Variables and axes
+3. Data ranges and scales
+4. Key patterns, trends, or outliers
+5. Statistical insights
+Focus on quantitative accuracy.
+    """.strip(),
+    
+    'medical': """
+Describe this medical image. Include:
+1. Type of medical imaging (X-ray, MRI, CT, microscopy, etc.)
+2. Anatomical structures visible
+3. Notable findings or abnormalities
+4. Image quality and contrast
+5. Clinical relevance
+Be professional and precise.
+    """.strip()
+}
+
+
+def convert_with_ai(
+    input_file: Path,
+    output_file: Path,
+    api_key: str,
+    model: str = "anthropic/claude-sonnet-4.5",
+    prompt_type: str = "general",
+    custom_prompt: str = None
+) -> bool:
+    """
+    Convert a file to Markdown with AI image descriptions.
+    
+    Args:
+        input_file: Path to input file
+        output_file: Path to output Markdown file
+        api_key: OpenRouter API key
+        model: Model name (default: anthropic/claude-sonnet-4.5)
+        prompt_type: Type of prompt to use
+        custom_prompt: Custom prompt (overrides prompt_type)
+        
+    Returns:
+        True if successful, False otherwise
+    """
+    try:
+        # Initialize OpenRouter client (OpenAI-compatible)
+        client = OpenAI(
+            api_key=api_key,
+            base_url="https://openrouter.ai/api/v1"
+        )
+        
+        # Select prompt
+        if custom_prompt:
+            prompt = custom_prompt
+        else:
+            prompt = PROMPTS.get(prompt_type, PROMPTS['general'])
+        
+        print(f"Using model: {model}")
+        print(f"Prompt type: {prompt_type if not custom_prompt else 'custom'}")
+        print(f"Converting: {input_file}")
+        
+        # Create MarkItDown with AI support
+        md = MarkItDown(
+            llm_client=client,
+            llm_model=model,
+            llm_prompt=prompt
+        )
+        
+        # Convert file
+        result = md.convert(str(input_file))
+        
+        # Create output with metadata
+        content = f"# {result.title or input_file.stem}\n\n"
+        content += f"**Source**: {input_file.name}\n"
+        content += f"**Format**: {input_file.suffix}\n"
+        content += f"**AI Model**: {model}\n"
+        content += f"**Prompt Type**: {prompt_type if not custom_prompt else 'custom'}\n\n"
+        content += "---\n\n"
+        content += result.text_content
+        
+        # Write output
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        output_file.write_text(content, encoding='utf-8')
+        
+        print(f"✓ Successfully converted to: {output_file}")
+        return True
+        
+    except Exception as e:
+        print(f"✗ Error: {str(e)}", file=sys.stderr)
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert documents to Markdown with AI-enhanced image descriptions",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=f"""
+Available prompt types:
+  scientific    - For scientific diagrams, graphs, and charts
+  presentation  - For presentation slides
+  general       - General-purpose image description
+  data_viz      - For data visualizations and charts
+  medical       - For medical imaging
+
+Examples:
+  # Convert a scientific paper
+  python convert_with_ai.py paper.pdf output.md --prompt-type scientific
+  
+  # Convert a presentation with custom model
+  python convert_with_ai.py slides.pptx slides.md --model anthropic/claude-sonnet-4.5 --prompt-type presentation
+  
+  # Use custom prompt with Claude Sonnet 4.5
+  python convert_with_ai.py diagram.png diagram.md --model anthropic/claude-sonnet-4.5 --custom-prompt "Describe this technical diagram"
+  
+  # Set API key via environment variable
+  export OPENROUTER_API_KEY="sk-or-v1-..."
+  python convert_with_ai.py image.jpg image.md
+
+Environment Variables:
+  OPENROUTER_API_KEY    OpenRouter API key (required if not passed via --api-key)
+
+Popular Models (use with --model):
+  anthropic/claude-sonnet-4.5 - Claude Sonnet 4.5 (recommended, vision support)
+  anthropic/claude-3.5-sonnet - Claude 3.5 Sonnet (vision support)
+  openai/gpt-4o              - GPT-4 Omni (vision support)
+  openai/gpt-4-vision        - GPT-4 Vision
+  google/gemini-pro-vision   - Gemini Pro Vision
+        """
+    )
+    
+    parser.add_argument('input', type=Path, help='Input file')
+    parser.add_argument('output', type=Path, help='Output Markdown file')
+    parser.add_argument(
+        '--api-key', '-k',
+        help='OpenRouter API key (or set OPENROUTER_API_KEY env var)'
+    )
+    parser.add_argument(
+        '--model', '-m',
+        default='anthropic/claude-sonnet-4.5',
+        help='Model to use via OpenRouter (default: anthropic/claude-sonnet-4.5)'
+    )
+    parser.add_argument(
+        '--prompt-type', '-t',
+        choices=list(PROMPTS.keys()),
+        default='general',
+        help='Type of prompt to use (default: general)'
+    )
+    parser.add_argument(
+        '--custom-prompt', '-p',
+        help='Custom prompt (overrides --prompt-type)'
+    )
+    parser.add_argument(
+        '--list-prompts', '-l',
+        action='store_true',
+        help='List available prompt types and exit'
+    )
+    
+    args = parser.parse_args()
+    
+    # List prompts and exit
+    if args.list_prompts:
+        print("Available prompt types:\n")
+        for name, prompt in PROMPTS.items():
+            print(f"[{name}]")
+            print(prompt)
+            print("\n" + "="*60 + "\n")
+        sys.exit(0)
+    
+    # Get API key
+    api_key = args.api_key or os.environ.get('OPENROUTER_API_KEY')
+    if not api_key:
+        print("Error: OpenRouter API key required. Set OPENROUTER_API_KEY environment variable or use --api-key")
+        print("Get your API key at: https://openrouter.ai/keys")
+        sys.exit(1)
+    
+    # Validate input file
+    if not args.input.exists():
+        print(f"Error: Input file '{args.input}' does not exist")
+        sys.exit(1)
+    
+    # Convert file
+    success = convert_with_ai(
+        input_file=args.input,
+        output_file=args.output,
+        api_key=api_key,
+        model=args.model,
+        prompt_type=args.prompt_type,
+        custom_prompt=args.custom_prompt
+    )
+    
+    sys.exit(0 if success else 1)
+
+
+if __name__ == '__main__':
+    main()
+

scientific_writer/.claude/skills/paper-2-web/SKILL.md

@@ -0,0 +1,455 @@
+---
+name: paper-2-web
+description: This skill should be used when converting academic papers into promotional and presentation formats including interactive websites (Paper2Web), presentation videos (Paper2Video), and conference posters (Paper2Poster). Use this skill for tasks involving paper dissemination, conference preparation, creating explorable academic homepages, generating video abstracts, or producing print-ready posters from LaTeX or PDF sources.
+---
+
+# Paper2All: Academic Paper Transformation Pipeline
+
+## Overview
+
+This skill enables the transformation of academic papers into multiple promotional and presentation formats using the Paper2All autonomous pipeline. The system converts research papers (LaTeX or PDF) into three primary outputs:
+
+1. **Paper2Web**: Interactive, explorable academic homepages with layout-aware design
+2. **Paper2Video**: Professional presentation videos with narration, slides, and optional talking-head
+3. **Paper2Poster**: Print-ready conference posters with professional layouts
+
+The pipeline uses LLM-powered content extraction, design generation, and iterative refinement to create high-quality outputs suitable for conferences, journals, preprint repositories, and academic promotion.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- **Creating conference materials**: Posters, presentation videos, and companion websites for academic conferences
+- **Promoting research**: Converting published papers or preprints into accessible, engaging web formats
+- **Preparing presentations**: Generating video abstracts or full presentation videos from paper content
+- **Disseminating findings**: Creating promotional materials for social media, lab websites, or institutional showcases
+- **Enhancing preprints**: Adding interactive homepages to bioRxiv, arXiv, or other preprint submissions
+- **Batch processing**: Generating promotional materials for multiple papers simultaneously
+
+**Trigger phrases**:
+- "Convert this paper to a website"
+- "Generate a conference poster from my LaTeX paper"
+- "Create a video presentation from this research"
+- "Make an interactive homepage for my paper"
+- "Transform my paper into promotional materials"
+- "Generate a poster and video for my conference talk"
+
+## Core Capabilities
+
+### 1. Paper2Web: Interactive Website Generation
+
+Converts papers into layout-aware, interactive academic homepages that go beyond simple HTML conversion.
+
+**Key Features**:
+- Responsive, multi-section layouts adapted to paper content
+- Interactive figures, tables, and citations
+- Mobile-friendly design with navigation
+- Automatic logo discovery (with Google Search API)
+- Aesthetic refinement and quality assessment
+
+**Best For**: Post-publication promotion, preprint enhancement, lab websites, permanent research showcases
+
+→ **See `references/paper2web.md` for detailed documentation**
+
+---
+
+### 2. Paper2Video: Presentation Video Generation
+
+Generates professional presentation videos with slides, narration, cursor movements, and optional talking-head video.
+
+**Key Features**:
+- Automated slide generation from paper structure
+- Natural-sounding speech synthesis
+- Synchronized cursor movements and highlights
+- Optional talking-head video using Hallo2 (requires GPU)
+- Multi-language support
+
+**Best For**: Video abstracts, conference presentations, online talks, course materials, YouTube promotion
+
+→ **See `references/paper2video.md` for detailed documentation**
+
+---
+
+### 3. Paper2Poster: Conference Poster Generation
+
+Creates print-ready academic posters with professional layouts and visual design.
+
+**Key Features**:
+- Custom poster dimensions (any size)
+- Professional design templates
+- Institution branding support
+- QR code generation for links
+- High-resolution output (300+ DPI)
+
+**Best For**: Conference poster sessions, symposiums, academic exhibitions, virtual conferences
+
+→ **See `references/paper2poster.md` for detailed documentation**
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+1. **Install Paper2All**:
+   ```bash
+   git clone https://github.com/YuhangChen1/Paper2All.git
+   cd Paper2All
+   conda create -n paper2all python=3.11
+   conda activate paper2all
+   pip install -r requirements.txt
+   ```
+
+2. **Configure API Keys** (create `.env` file):
+   ```
+   OPENAI_API_KEY=your_openai_api_key_here
+   # Optional: GOOGLE_API_KEY and GOOGLE_CSE_ID for logo search
+   ```
+
+3. **Install System Dependencies**:
+   - LibreOffice (document conversion)
+   - Poppler utilities (PDF processing)
+   - NVIDIA GPU with 48GB (optional, for talking-head videos)
+
+→ **See `references/installation.md` for complete installation guide**
+
+---
+
+### Basic Usage
+
+**Generate All Components** (website + poster + video):
+```bash
+python pipeline_all.py \
+  --input-dir "path/to/paper" \
+  --output-dir "path/to/output" \
+  --model-choice 1
+```
+
+**Generate Website Only**:
+```bash
+python pipeline_all.py \
+  --input-dir "path/to/paper" \
+  --output-dir "path/to/output" \
+  --model-choice 1 \
+  --generate-website
+```
+
+**Generate Poster with Custom Size**:
+```bash
+python pipeline_all.py \
+  --input-dir "path/to/paper" \
+  --output-dir "path/to/output" \
+  --model-choice 1 \
+  --generate-poster \
+  --poster-width-inches 60 \
+  --poster-height-inches 40
+```
+
+**Generate Video** (lightweight pipeline):
+```bash
+python pipeline_light.py \
+  --model_name_t gpt-4.1 \
+  --model_name_v gpt-4.1 \
+  --result_dir "path/to/output" \
+  --paper_latex_root "path/to/paper"
+```
+
+→ **See `references/usage_examples.md` for comprehensive workflow examples**
+
+---
+
+## Workflow Decision Tree
+
+Use this decision tree to determine which components to generate:
+
+```
+User needs promotional materials for paper?
+│
+├─ Need permanent online presence?
+│  └─→ Generate Paper2Web (interactive website)
+│
+├─ Need physical conference materials?
+│  ├─→ Poster session? → Generate Paper2Poster
+│  └─→ Oral presentation? → Generate Paper2Video
+│
+├─ Need video content?
+│  ├─→ Journal video abstract? → Generate Paper2Video (5-10 min)
+│  ├─→ Conference talk? → Generate Paper2Video (15-20 min)
+│  └─→ Social media? → Generate Paper2Video (1-3 min)
+│
+└─ Need complete package?
+   └─→ Generate all three components
+```
+
+## Input Requirements
+
+### Supported Input Formats
+
+**1. LaTeX Source** (Recommended):
+```
+paper_directory/
+├── main.tex              # Main paper file
+├── sections/             # Optional: split sections
+├── figures/              # All figure files
+├── tables/               # Table files
+└── bibliography.bib      # References
+```
+
+**2. PDF**:
+- High-quality PDF with embedded fonts
+- Selectable text (not scanned images)
+- High-resolution figures (300+ DPI preferred)
+
+### Input Organization
+
+**Single Paper**:
+```bash
+input/
+└── paper_name/
+    ├── main.tex (or paper.pdf)
+    ├── figures/
+    └── bibliography.bib
+```
+
+**Multiple Papers** (batch processing):
+```bash
+input/
+├── paper1/
+│   └── main.tex
+├── paper2/
+│   └── main.tex
+└── paper3/
+    └── main.tex
+```
+
+## Common Parameters
+
+### Model Selection
+- `--model-choice 1`: GPT-4 (best balance of quality and cost)
+- `--model-choice 2`: GPT-4.1 (latest features, higher cost)
+- `--model_name_t gpt-3.5-turbo`: Faster, lower cost (acceptable quality)
+
+### Component Selection
+- `--generate-website`: Enable website generation
+- `--generate-poster`: Enable poster generation
+- `--generate-video`: Enable video generation
+- `--enable-talking-head`: Add talking-head to video (requires GPU)
+
+### Customization
+- `--poster-width-inches [width]`: Custom poster width
+- `--poster-height-inches [height]`: Custom poster height
+- `--video-duration [seconds]`: Target video length
+- `--enable-logo-search`: Automatic institution logo discovery
+
+## Output Structure
+
+Generated outputs are organized by paper and component:
+
+```
+output/
+└── paper_name/
+    ├── website/
+    │   ├── index.html
+    │   ├── styles.css
+    │   └── assets/
+    ├── poster/
+    │   ├── poster_final.pdf
+    │   ├── poster_final.png
+    │   └── poster_source/
+    └── video/
+        ├── final_video.mp4
+        ├── slides/
+        ├── audio/
+        └── subtitles/
+```
+
+## Best Practices
+
+### Input Preparation
+1. **Use LaTeX when possible**: Provides best content extraction and structure
+2. **Organize files properly**: Keep all assets (figures, tables, bibliography) in paper directory
+3. **High-quality figures**: Use vector formats (PDF, SVG) or high-resolution rasters (300+ DPI)
+4. **Clean LaTeX**: Remove compilation artifacts, ensure source compiles successfully
+
+### Model Selection Strategy
+- **GPT-4**: Best for production-quality outputs, conferences, publications
+- **GPT-4.1**: Use when you need latest features or best possible quality
+- **GPT-3.5-turbo**: Use for quick drafts, testing, or simple papers
+
+### Component Priority
+For tight deadlines, generate in this order:
+1. **Website** (fastest, most versatile, ~15-30 min)
+2. **Poster** (moderate speed, for print deadlines, ~10-20 min)
+3. **Video** (slowest, can be generated later, ~20-60 min)
+
+### Quality Assurance
+Before finalizing outputs:
+1. **Website**: Test on multiple devices, verify all links work, check figure quality
+2. **Poster**: Print test page, verify text readability from 3-6 feet, check colors
+3. **Video**: Watch entire video, verify audio synchronization, test on different devices
+
+## Resource Requirements
+
+### Processing Time
+- **Website**: 15-30 minutes per paper
+- **Poster**: 10-20 minutes per paper
+- **Video (no talking-head)**: 20-60 minutes per paper
+- **Video (with talking-head)**: 60-120 minutes per paper
+
+### Computational Requirements
+- **CPU**: Multi-core processor for parallel processing
+- **RAM**: 16GB minimum, 32GB recommended for large papers
+- **GPU**: Optional for standard outputs, required for talking-head (NVIDIA A6000 48GB)
+- **Storage**: 1-5GB per paper depending on components and quality settings
+
+### API Costs (Approximate)
+- **Website**: $0.50-2.00 per paper (GPT-4)
+- **Poster**: $0.30-1.00 per paper (GPT-4)
+- **Video**: $1.00-3.00 per paper (GPT-4)
+- **Complete package**: $2.00-6.00 per paper (GPT-4)
+
+## Troubleshooting
+
+### Common Issues
+
+**LaTeX parsing errors**:
+- Ensure LaTeX source compiles successfully: `pdflatex main.tex`
+- Check all referenced files are present
+- Verify no custom packages prevent parsing
+
+**Poor figure quality**:
+- Use vector formats (PDF, SVG, EPS) instead of rasters
+- Ensure raster images are 300+ DPI
+- Check figures render correctly in compiled PDF
+
+**Video generation failures**:
+- Verify sufficient disk space (5GB+ recommended)
+- Check all dependencies installed (LibreOffice, Poppler)
+- Review error logs in output directory
+
+**Poster layout issues**:
+- Verify poster dimensions are reasonable (24"-72" range)
+- Check content length (very long papers may need manual curation)
+- Ensure figures have appropriate resolution for poster size
+
+**API errors**:
+- Verify API keys in `.env` file
+- Check API credit balance
+- Ensure no rate limiting (wait and retry)
+
+## Platform-Specific Features
+
+### Social Media Optimization
+
+The system auto-detects target platforms:
+
+**Twitter/X** (English, numeric folder names):
+```bash
+mkdir -p input/001_twitter/
+# Generates English promotional content
+```
+
+**Xiaohongshu/小红书** (Chinese, alphanumeric folder names):
+```bash
+mkdir -p input/xhs_paper/
+# Generates Chinese promotional content
+```
+
+### Conference-Specific Formatting
+
+Specify conference requirements:
+- Standard poster sizes (4'×3', 5'×4', A0, A1)
+- Video abstract length limits (typically 3-5 minutes)
+- Institution branding requirements
+- Color scheme preferences
+
+## Integration and Deployment
+
+### Website Deployment
+Deploy generated websites to:
+- **GitHub Pages**: Free hosting with custom domain
+- **Academic hosting**: University web servers
+- **Personal servers**: AWS, DigitalOcean, etc.
+- **Netlify/Vercel**: Modern hosting with CI/CD
+
+### Poster Printing
+Print-ready files work with:
+- Professional poster printing services
+- University print shops
+- Online services (e.g., Spoonflower, VistaPrint)
+- Large format printers (if available)
+
+### Video Distribution
+Share videos on:
+- **YouTube**: Public or unlisted for maximum reach
+- **Institutional repositories**: University video platforms
+- **Conference platforms**: Virtual conference systems
+- **Social media**: Twitter, LinkedIn, ResearchGate
+
+## Advanced Usage
+
+### Batch Processing
+Process multiple papers efficiently:
+```bash
+# Organize papers in batch directory
+for paper in paper1 paper2 paper3; do
+    python pipeline_all.py \
+      --input-dir input/$paper \
+      --output-dir output/$paper \
+      --model-choice 1 &
+done
+wait
+```
+
+### Custom Branding
+Apply institution or lab branding:
+- Provide logo files in paper directory
+- Specify color schemes in configuration
+- Use custom templates (advanced)
+- Match conference theme requirements
+
+### Multi-Language Support
+Generate content in different languages:
+- Specify target language in configuration
+- System translates content appropriately
+- Selects appropriate voice for video narration
+- Adapts design conventions to culture
+
+## References and Resources
+
+This skill includes comprehensive reference documentation:
+
+- **`references/installation.md`**: Complete installation and configuration guide
+- **`references/paper2web.md`**: Detailed Paper2Web documentation with all features
+- **`references/paper2video.md`**: Comprehensive Paper2Video guide including talking-head setup
+- **`references/paper2poster.md`**: Complete Paper2Poster documentation with design templates
+- **`references/usage_examples.md`**: Real-world examples and workflow patterns
+
+**External Resources**:
+- GitHub Repository: https://github.com/YuhangChen1/Paper2All
+- Curated Dataset: Available on Hugging Face (13 research categories)
+- Benchmark Suite: Reference websites and evaluation metrics
+
+## Evaluation and Quality Metrics
+
+The Paper2All system includes built-in quality assessment:
+
+### Content Quality
+- **Completeness**: Coverage of paper content
+- **Accuracy**: Faithful representation of findings
+- **Clarity**: Accessibility and understandability
+- **Informativeness**: Key information prominence
+
+### Design Quality
+- **Aesthetics**: Visual appeal and professionalism
+- **Layout**: Balance, hierarchy, and organization
+- **Readability**: Text legibility and figure clarity
+- **Consistency**: Uniform styling and branding
+
+### Technical Quality
+- **Performance**: Load times, responsiveness
+- **Compatibility**: Cross-browser, cross-device support
+- **Accessibility**: WCAG compliance, screen reader support
+- **Standards**: Valid HTML/CSS, print-ready PDFs
+
+All outputs undergo automated quality checks before generation completes.