Reference Renamer

CLI tool for standardizing academic article filenames using metadata extraction and verification.

Features

• Automatic Renaming: Renames academic articles to a standardized format (Author_Year_FiveWordTitle.ext)
• Multiple Format Support: Handles PDF, TXT, and other document formats
• Metadata Enrichment: Uses arXiv, Semantic Scholar, and LLM processing to verify and enrich document metadata
• Citation Management: Maintains a BibTeX database of processed articles
• Accessibility Focused: Clear output formats and screen reader support
• Detailed Logging: Tracks all file operations

Installation

System Dependencies

Required for PDF processing with OCR:

# Ubuntu/Debian
sudo apt-get install tesseract-ocr poppler-utils

# macOS
brew install tesseract poppler

# Windows
# Install Tesseract from: https://github.com/UB-Mannheim/tesseract/wiki
# Install Poppler from: https://github.com/oschwartz10612/poppler-windows/releases

Note: OCR is only used as a fallback when PDFs contain no extractable text. If you only process text-based PDFs, these dependencies are optional.

Python Installation

1. Clone the repository:

git clone https://github.com/lukeslp/reference-renamer.git
cd reference-renamer

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

3. Install dependencies:

pip install -r requirements.txt

Ollama (Optional)

Ollama provides local LLM processing for enhanced metadata extraction. It is optional - the tool works without it using arXiv and Semantic Scholar APIs.

If you want to use Ollama:

# Install Ollama from https://ollama.ai
ollama run drummer-knowledge

Without Ollama, the tool will:

• Skip LLM-based extraction
• Fall back to arXiv and Semantic Scholar for metadata
• Still function correctly for most academic papers

Usage

Basic Usage

# Process a single directory
reference-renamer /path/to/papers

# Process recursively with dry run
reference-renamer --recursive --dry-run /path/to/papers

# Generate citations only
reference-renamer --citations-only /path/to/papers

Configuration

Create a config.yaml file in your working directory:

processing:
  supported_extensions:
    - .pdf
    - .txt
  recursive: true
  max_title_words: 5

apis:
  semantic_scholar:
    enabled: true
    timeout: 30
  arxiv:
    enabled: true
    max_results: 3

logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Output

The tool generates:

1. Renamed files in the specified format
2. A CSV log of all operations (rename_log.csv)
3. A BibTeX database of citations (citations.bib)

Accessibility Features

• Screen reader-friendly output formats
• High contrast CLI interface
• Clear error messages and status updates
• Configurable output formats

Development

Setting up the Development Environment

1. Install development dependencies:

pip install -r requirements-dev.txt

2. Install pre-commit hooks:

pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=reference_renamer

# Run specific test file
pytest tests/test_file_processor.py

Code Style

This project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking

Run the full suite:

# Format code
black .
isort .

# Check types
mypy .

# Lint
flake8

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Please ensure your PR:

• Includes tests for new features
• Updates documentation as needed
• Follows the project's code style
• Includes a clear description of changes

License

This project is licensed under the MIT License. The full license text is included in the source distribution as the LICENSE file.

Acknowledgments

• Built with Python
• Uses Ollama for LLM processing
• Integrates with arXiv and Semantic Scholar

Support

For support, please:

1. Check the documentation in this README
2. Search existing issues
3. Create a new issue if needed

What's New

This refactor archives old helpers, adds example snippets, and includes new funding links.

Credits & Support

• Tip Jar
• Substack
• GitHub
• Bluesky
• LinkedIn