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
• 📁 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: qwen3:latest)
pdf-renamer --model command-r7b:latest /path/to/pdfs

# Available models:
# - command-r7b:latest (recommended - best results)
# - qwen3:latest (default)
# - deepseek-r1:latest
# - gemma3n:e4b
# - mistral-nemo:latest

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: qwen3: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

Before

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

After

egyptwar.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 can be 1-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
• Custom naming patterns
• Progress bar for large directories
• GUI version
• Integration with cloud storage services
• Batch undo functionality

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