reference-renamer 0.1.0

A tool for standardizing academic article filenames

Reference Renamer

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

Features

• Intelligent Renaming: Automatically 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
• Comprehensive Logging: Detailed tracking of all file operations

Installation

1. Clone the repository:

git clone https://github.com/yourusername/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

4. Configure Ollama:

• Ensure Ollama is installed and running
• Load the required model:

ollama run drummer-knowledge

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 - see the LICENSE file for details.

Acknowledgments

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

Support

For support, please:

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

Roadmap

See our project board for planned features and enhancements.

What's New

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

Credits & Support

• Tip Jar
• Substack
• GitHub
• Bluesky
• LinkedIn