PDF Renamer AI

A Rust CLI tool that automatically renames PDF files with meaningful, concise names using local LLMs via Ollama. Perfect for organizing documents with non-English filenames or long, complex names.

Features

• 🌍 Multi-language Support: Automatically translates non-English filenames
• 🤖 Local LLM Integration: Uses Ollama for privacy-preserving AI processing
• 🚀 Automatic Setup: Installs Ollama and downloads models as needed
• 🎯 Smart Naming: Generates concise, meaningful 10-character names
• 📁 Batch Processing: Processes entire directories recursively
• 🔒 Safe Operations: Dry-run mode by default, duplicate handling
• ⚡ Fast & Efficient: Written in Rust for optimal performance

Quick Start

# Clone and build
git clone https://github.com/RustSandbox/pdf_renamer.git
cd pdf_renamer
cargo build --release

# Run the demo
./demo.sh

# Or use directly
./target/release/pdf-renamer /path/to/pdfs

Installation

Prerequisites

• Rust (1.70 or later)
• macOS or Linux (Windows support coming soon)
• Internet connection (for automatic Ollama setup and model downloads)

Install from crates.io (Recommended)

cargo install pdf-renamer-ai

This will install the pdf-renamer command globally.

Build from Source

git clone https://github.com/RustSandbox/pdf_renamer.git
cd pdf_renamer
cargo build --release

The binary will be available at target/release/pdf-renamer.

Install from Source

cargo install --path .

Usage

Basic Usage

# Dry run - see what would be renamed
pdf-renamer /path/to/pdf/folder

# Actually rename files
pdf-renamer --rename /path/to/pdf/folder

Using Different Models

# Use a specific model (default: command-r7b:latest)
pdf-renamer --model llama3.2:latest /path/to/pdfs

# Recommended models:
# - command-r7b:latest (default - best balance of speed and quality)
# - llama3.2:latest (excellent for complex names)
# - qwen2.5:latest (good multilingual support)
# - mistral-nemo:latest (fast and efficient)

Command Line Options

USAGE:
    pdf-renamer [OPTIONS] <FOLDER_PATH>

ARGS:
    <FOLDER_PATH>    Path to the folder containing PDF files

OPTIONS:
    -r, --rename         Actually rename the files (dry run by default)
    -m, --model <MODEL>  Ollama model to use [default: command-r7b:latest]
    -h, --help           Print help information

How It Works

1. Setup Phase:

   • Checks if Ollama is installed (installs if needed)
   • Ensures Ollama service is running
   • Downloads the specified model if not available

2. Processing Phase:

   • Scans the directory for PDF files
   • Sends each filename to the LLM for translation/summarization
   • Generates a meaningful 10-character alphanumeric name
   • Renames files (if --rename flag is used)

3. Safety Features:

   • Dry-run by default
   • Handles duplicates by appending numbers
   • Preserves original files on error

Examples

Real Example

Before:

مصر_من_ناصر_إلى_حرب_أكتوبر.pdf
أوراق_هنري_كورييل_والحركة_الشيوعية_المصرية.pdf
あらゆる現実主義者のための量子論.pdf
Introduction_to_Machine_Learning_2024_Edition.pdf

After:

egyptoctwa.pdf
egyptcommu.pdf
quantumphy.pdf
mlintro24.pdf

Automatic Ollama Setup

The tool automatically handles Ollama installation and configuration:

• ✅ Detects if Ollama is installed
• ✅ Installs Ollama if missing (macOS/Linux)
• ✅ Starts Ollama service if not running
• ✅ Downloads required models automatically
• ✅ Shows progress during model downloads

Development

Project Structure

pdf_renamer/
├── src/
│   ├── main.rs       # CLI and main logic
│   ├── ollama.rs     # Ollama API client
│   └── setup.rs      # Ollama setup automation
├── Cargo.toml
└── README.md

Running Tests

cargo test

Building for Release

cargo build --release

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under a custom license that requires attribution for commercial use - see the LICENSE file for details.

Key points:

• ✅ Free for personal and commercial use
• ✅ Can modify and distribute
• ⚠️ Commercial use requires attribution
• ✅ Non-commercial use doesn't require attribution (but it's appreciated)

Author

Created by Hamzeh Ghalebi (ghalebi@gmail.com)

Acknowledgments

• Ollama for providing local LLM capabilities
• The Rust community for excellent libraries and tools
• All contributors and users of this project

Troubleshooting

Ollama Installation Fails

• Ensure you have curl installed
• Check your internet connection
• Try installing Ollama manually from https://ollama.com

Model Download Issues

• Ensure you have sufficient disk space (models range from 4GB to 10GB)
• Check your internet connection
• Try pulling the model manually: ollama pull model-name

Permission Errors

• Ensure you have write permissions in the PDF directory
• Run with appropriate permissions if needed

Roadmap

• Windows support
• Configuration file support (.pdfrenamer.toml)
• Custom naming patterns and length
• Progress bar for large directories
• Multiple file format support (DOCX, EPUB)
• Parallel processing for faster batch operations
• Undo/restore functionality with history
• Web UI for remote management

Support

If you encounter any issues or have questions, please:

1. Check the Issues page
2. Create a new issue with details about your problem
3. Include your OS, Rust version, and any error messages