texforge 0.1.3

TexForge - Forge perfect LaTeX papers with automated compilation, validation, and maintenance

TexForge - Forge Perfect LaTeX Papers

Automated LaTeX paper compilation, validation, and maintenance

⚠️ Note: This project is under active construction. Features and APIs may change.

Forge your research with precision and ease:

• Modern CLI Tool: Simple texforge command for all operations
• Smart Compilation: LaTeX to PDF with error detection and auto-cleanup
• Project Templates: Physical Review A/L, generic article templates
• Validation: Compilation, references, citations, TODOs
• Notifications: Slack, Telegram, Discord, ntfy.sh (no config file needed!)
• Python API: Use as a library in your own scripts

📑 Table of Contents

• Quick Start
• Features
• Installation
• Usage
• Configuration
• Use Cases
• Documentation
• Contributing
• Support & Troubleshooting
• License

🚀 Quick Start

# Clone and install
git clone https://github.com/Jue-Xu/LaTex-paper-automation.git
cd LaTex-paper-automation
pip install -e .

# Create a new paper project
texforge init quantum-dynamics --template pra

# Write your paper
cd projects/quantum-dynamics
mv template.tex main.tex
# ... edit main.tex, add references.bib ...

# Compile to PDF
texforge compile

# Send notification (no config needed!)
export SLACK_WEBHOOK="https://hooks.slack.com/services/..."
texforge notify --slack "Paper compiled successfully!"

That's it! You're ready to forge perfect LaTeX papers.

📋 Features

🔨 Core Tools

1. texforge prove - Rigorous theorem prover ⭐ NEW (Guide)

   • Reads theorems from your LaTeX files by label
   • Dual AI agents: Prover + Checker for verification
   • Specialized for quantum info, complexity theory, information theory
   • Writes verified proofs back to your .tex files automatically
   • Example: texforge prove --label thm:main

2. texforge brainstorm - AI-powered research planning (Guide)

   • 6 expert personas evaluate your research idea
   • 3-round discussion with synthesis and recommendations
   • Reads references from library/ folder
   • Generates manuscript outline and detailed logs

3. texforge compile - Smart LaTeX compilation

   • Auto-detects main.tex, handles bibliography
   • Smart error detection vs. warnings
   • Auto-cleanup of auxiliary files
   • Slack notifications with --notify flag

4. texforge init - Project scaffolding

   • Physical Review A/L templates (revtex4-2)
   • Generic article template
   • Complete project structure with content/ and library/ folders

5. texforge review - Peer review simulation (Guide)

   • 3 expert reviewers for APS journals (PRA, PRB, PRL, PRX, PRR)
   • Automated compliance checks
   • Decision: Accept, Minor/Major Revision, or Reject

6. texforge cover-letter - Submission letter generator (Guide)

   • Journal-specific professional cover letters
   • Pre-configured for PRL, Nature, Science, PRA, PRB, PRX
   • Outputs .txt and .md formats

7. texforge validate - Quality checks

   • Compilation, references, citations, TODOs

8. texforge maintain - Automated maintenance

   • Scheduled checks with Git integration

9. texforge notify - Multi-channel notifications

   • Slack, Telegram, Discord, ntfy.sh
   • Works without config files (env vars)

🎯 Key Benefits

• Zero Configuration Start: Send notifications using environment variables
• Smart Error Detection: Distinguishes LaTeX warnings from real errors
• Clean API: Use as CLI tool or Python library
• Professional Templates: Journal-ready LaTeX templates
• Git Integration: Auto-commit with detailed messages
• Flexible Notifications: Config file, environment vars, or direct credentials

💻 Usage

Command-Line Interface

# Research Planning
texforge brainstorm                          # Use project goals from README
texforge brainstorm --idea "..." --journal "PRL"

# Paper Development
texforge init my-paper --template pra        # Initialize project
texforge compile                             # Compile to PDF
texforge validate                            # Quality checks

# Theorem Proving (NEW!)
texforge prove --label thm:main              # Prove theorem from LaTeX
texforge prove --label lem:bound --file methods.tex

# Pre-Submission Review
texforge review --journal prl                # Get peer review feedback
texforge review --journal prl --strict       # Strict criteria

# Submission Preparation
texforge cover-letter prl                    # Generate cover letter
texforge cover-letter nature -i "Context"    # With additional info

# Notifications
export SLACK_WEBHOOK="https://..."
texforge notify --slack "Paper ready!"

# Help
texforge --help
texforge <command> --help

📚 Complete Documentation:

• CLI Guide - All commands and options
• Theorem Prover Guide - Rigorous proof generation ⭐ NEW
• Brainstorming Guide - Research planning workflow
• APS Review Guide - Peer review simulation
• Cover Letter Guide - Submission letters

Python API

Use TexForge as a library in your own scripts:

from texforge import PDFCompiler, PaperMaintenanceConfig, NotificationManager

# Compile a paper
config = PaperMaintenanceConfig.load("config.yaml")
compiler = PDFCompiler(config)
result = compiler.compile()

if result.success:
    print(f"✓ PDF generated: {result.pdf_path}")
else:
    print(f"✗ Compilation failed: {result.errors}")

# Send notification
notifier = NotificationManager(config)
notifier.send_notification(
    subject="Build Complete",
    body="PDF generated successfully",
    channels=["slack", "ntfy"]
)

Available Templates

• pra - Physical Review A (two-column, revtex4-2)
• prl - Physical Review Letters (two-column, revtex4-2)
• ns - Nature/Science journals (intro, setup, results, discussion, references, methods, appendix)
• tcs - Theoretical Computer Science (intro with Preliminaries/Previous Work/Contributions subsections)
• generic - Generic article (single-column, article class)

🔧 Installation

Requirements

• Python 3.8+ with pip
• LaTeX distribution (TeX Live, MiKTeX, etc.)
• Git (for project management)

Install TexForge

# Clone repository
git clone https://github.com/Jue-Xu/LaTex-paper-automation.git
cd LaTex-paper-automation

# Install in editable mode (recommended for development)
pip install -e .

# Or install from PyPI (when published)
pip install texforge

This installs:

• texforge command-line tool
• Python package for programmatic use
• All dependencies (requests, numpy, matplotlib, pyyaml)

Verify Installation

# Check version
texforge --version

# Get help
texforge --help

# Test compilation (requires LaTeX)
texforge init test-paper
cd projects/test-paper
mv template.tex main.tex
texforge compile

📖 Complete Workflow Example

From idea to submission in 6 steps:

# 1. Create project and add references
texforge init quantum-entanglement --template pra
cd quantum-entanglement
cp ~/papers/refs/*.pdf library/

# 2. Brainstorm and plan (→ manuscript_outline.md)
texforge brainstorm --journal "Physical Review A"

# 3. Write paper based on outline
mv template.tex main.tex
# ... edit sections using content/manuscript_outline.md as guide ...

# 4. Compile and validate
texforge compile
texforge validate

# 5. Get peer review and iterate
texforge review --journal pra
# ... address feedback, revise ...
texforge compile && texforge review --journal pra

# 6. Prepare submission
texforge cover-letter pra
# Ready: paper PDF + cover_letter.txt

See detailed guides for each step:

• Brainstorming Guide - Steps 2-3
• APS Review Guide - Step 5
• Cover Letter Guide - Step 6

Advanced Features

# Compile with custom configuration
texforge compile -c custom-config.yaml paper.tex

# Keep auxiliary files for debugging
texforge compile --no-clean

# Setup macros file
texforge compile --setup-macros

# Get macro suggestions
texforge compile --suggest-macros

# Multiple notification channels
texforge notify --subject "Build Complete" \
  --slack --telegram --ntfy \
  "All checks passed!"

⚙️ Configuration

TexForge uses YAML configuration files. Each project gets a .paper-config.yaml:

# Paper Settings
paper_directory: /path/to/paper
main_tex_file: main.tex
target_journal: Physical Review A

# Schedule
schedule:
  run_interval_hours: 6
  quiet_hours_start: "23:00"
  quiet_hours_end: "07:00"

# Checks to Run
checks:
  compile_check: true
  citation_check: true
  math_check: true
  consistency_check: false

# Git Integration
git:
  remote: "origin"
  branch: "main"
  commit_prefix: "paper: "
  auto_push: false

# Notifications (optional - can use env vars instead)
notifications:
  slack:
    enabled: true
    webhook_url: ""  # or use SLACK_WEBHOOK env var
  ntfy:
    enabled: true
    topic: "my-paper-updates"  # or use NTFY_TOPIC env var

Notification Setup

No config file needed! Use environment variables:

# Slack
export SLACK_WEBHOOK="https://hooks.slack.com/services/..."
texforge notify --slack "Message"

# ntfy.sh (recommended - no signup!)
export NTFY_TOPIC="my-paper-updates"
texforge notify --ntfy "Message"

# Telegram
export TELEGRAM_BOT_TOKEN="your-token"
export TELEGRAM_CHAT_ID="your-chat-id"
texforge notify --telegram "Message"

# Discord
export DISCORD_WEBHOOK="https://discord.com/api/webhooks/..."
texforge notify --discord "Message"

Or use direct credentials:

texforge notify --slack-webhook "https://..." "Message"
texforge notify --ntfy-topic "my-topic" "Message"

🎯 Use Cases

Research Paper Development

Write your paper in LaTeX with automatic compilation and quality checks:

texforge init research-paper --template pra
cd projects/research-paper
# ... edit main.tex ...
texforge compile && texforge notify --slack "Draft ready for review!"

Collaborative Writing

Integrate with Git hooks for automatic validation:

# .git/hooks/pre-commit
#!/bin/bash
texforge compile || exit 1
texforge validate || exit 1

Automated Paper Maintenance

Schedule regular checks with cron:

# Run every 6 hours
0 */6 * * * cd ~/papers/my-paper && texforge maintain -c .paper-config.yaml

CI/CD Integration

Use in GitHub Actions or other CI systems:

# .github/workflows/latex.yml
- name: Compile LaTeX
  run: |
    pip install texforge
    texforge compile main.tex

📚 Documentation

Agent Guides

• Brainstorming Guide - AI research planning

  • 6 expert personas including Dr. Literature
  • 3-round discussion process
  • Output files and iteration workflow

• APS Review Guide - Peer review simulation

  • 3 expert reviewers for APS journals
  • Compliance checks and decisions
  • Understanding feedback and iterating

• Cover Letter Guide - Submission letters

  • Journal-specific letter generation
  • Customization and best practices
  • Integration with submission workflow

General Guides

• CLI Guide - Complete command reference

  • All commands with examples
  • Configuration and troubleshooting

• Additional docs in docs/:

  • Notification setup
  • Deployment checklists
  • Contributing guidelines

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development setup:

git clone https://github.com/Jue-Xu/LaTex-paper-automation.git
cd LaTex-paper-automation
pip install -e ".[dev]"  # Install with dev dependencies

📞 Support

Need help?

• CLI_GUIDE.md - Complete troubleshooting section
• GitHub Issues - Report bugs or request features
• GitHub Discussions - Ask questions

Quick diagnostics:

# Check installation
texforge --version
pip list | grep texforge

# Test compilation
texforge init test && cd projects/test
mv template.tex main.tex
texforge compile

# Test notifications
export SLACK_WEBHOOK="your-webhook"
texforge notify --slack "Test message"

📝 License

GNU General Public License v3.0 - see LICENSE file for details.

🙏 Acknowledgments

Built with Claude Code by Anthropic. Inspired by the needs of researchers who want to focus on science, not LaTeX debugging.

---

TexForge - Forge Perfect LaTeX Papers

Made with precision for researchers worldwide