pdf-renamer-ai 0.1.0

Intelligently rename PDF files using local LLMs. Supports multiple languages, automatic translation, and meaningful name generation.
pdf-renamer-ai-0.1.0 is not a library.

PDF Renamer AI

Crates.io Documentation License Build Status

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