AnimeLibrarian

🎬 AI-powered video file organizer that makes your media library beautiful

Getting Started • Features • Documentation • Development

---

✨ Key Features

• 🤖 AI-Powered Naming: Intelligently renames files using LLM technology
• 📁 Smart Organization: Automatically moves files to appropriate directories
• 🎯 Media Player Compatible: Ensures compatibility with Infuse, Plex, and more
• 🔍 Preview Changes: Dry-run option to review changes before applying
• 🚀 Simple CLI: Plain-text output with readable tables and progress updates
• 📺 Universal Support: Works with anime, movies, TV shows, and more
• 🎨 Interactive UX: Confirmation prompts and concise status updates that work in any terminal

🚀 Quick Start

# Install AnimeLibrarian
pip install git+https://github.com/laipz8200/anime-librarian.git

# Set up your environment
cp .env.example .env
# Edit .env with your Dify API credentials

# Run with default settings
anime-librarian

# Or specify custom paths
anime-librarian --source ~/Downloads --target ~/Media

UNIX-Friendly Modes

# Preview only
anime-librarian --dry-run --format table

# Machine-readable output (newline-delimited JSON for streaming)
anime-librarian --dry-run --format json

📋 Prerequisites

• Dify account
• Language model access through Dify
• AnimeLibrarian workflow in your Dify account

🛠️ Installation

Using pip (for users)

# Install directly from GitHub
pip install git+https://github.com/laipz8200/anime-librarian.git

Using uv (recommended for development)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/laipz8200/anime-librarian.git
cd anime-librarian

# Install dependencies with uv
uv sync

Traditional pip setup

# Clone the repository
git clone https://github.com/laipz8200/anime-librarian.git
cd anime-librarian

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install .

📖 Documentation

Dify Workflow Setup

1. Sign up at Dify
2. Configure your language model
3. Import the workflow:
   • Use DSL import
   • Import Anime Librarian.yml from Dify DSL File
4. Create an API key
5. Copy API key and endpoint URL

Tip

Add a TMDB API key to enhance media identification accuracy!

Configuration

1. Copy and edit the environment file:

   cp .env.example .env

2. Update .env values per the comments

⚠️ Important: Create media category subdirectories in your ANIMELIBRARIAN_TARGET_PATH for optimal AI organization.

Advanced Usage

# Preview changes (dry run)
anime-librarian --dry-run

# View all options
anime-librarian --help

🔄 How It Works

1. 📂 Scans source directory for videos
2. 🗂️ Identifies existing media categories
3. 🤖 AI analyzes filenames via Dify (with progress indicator)
4. ✨ Generates standardized names
5. 📝 Shows proposed changes in a formatted table
6. ✅ Moves and renames with real-time progress bar

🎨 Enhanced User Experience

AnimeLibrarian now features a straightforward terminal interface:

• Clear Status Messages: Highlights successes, warnings, and errors with simple text cues
• Readable Tables: File moves displayed with plain ASCII tables and lists
• Progress Updates: Lightweight textual progress notifications keep you informed
• Smart Prompts: Interactive confirmation dialogs with sensible defaults
• Summary Panels: Operation summaries rendered in easy-to-scan text blocks
• Terminal Compatibility: Looks the same in basic terminals, CI logs, and remote shells

👩‍💻 Development

Setup Development Environment

# Install uv package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/laipz8200/anime-librarian.git
cd anime-librarian

# Install dependencies with uv
uv sync

# Install prek hooks (pre-commit alternative)
prek install

Development Workflow

# Run linting and formatting
make lint                 # Format code and fix issues
make format              # Just format code
make check               # Check code without fixes

# Run tests
make test                # Run all tests
make test-mock           # Run mock server tests only
pytest --cov             # Run with coverage report

# Clean up
make clean               # Remove generated files

Testing with Mock Server

The project includes a comprehensive mock Dify server for testing without API access:

# Run integration tests with mock server
uv run pytest tests/test_integration_with_mock_server.py -v

# Use mock server in your tests
from tests.fixtures.mock_server_fixtures import run_mock_server

with run_mock_server() as server_url:
    # Your test code here
    pass

See tests/README_MOCK_SERVER.md for detailed mock server documentation.

Quality Assurance

• Pre-commit Hooks: Automatic code quality checks

  • Linting (ruff)
  • Formatting (ruff)
  • Type checking (ty)

• CI/CD: GitHub Actions workflow

  • Code quality checks
  • Test suite execution (98+ tests)
  • Automated PR validation

• Make Commands: Quick development tasks

  make help     # Show all available commands
  make lint     # Run full linting
  make test     # Run all tests

🔍 Troubleshooting

Common solutions for:

• 🔑 API Issues: Verify Dify credentials in .env
• 📁 Access Errors: Check directory permissions
• 🤖 AI Problems: Validate Dify workflow setup
• 📂 Organization: Ensure target directories exist
• 🔍 Testing: Use --dry-run to preview changes
• 📝 Output: The tool now runs without generating log files

🤝 Contributing

Contributions are welcome! Feel free to:

• 🐛 Report bugs
• 💡 Suggest features
• 🔧 Submit pull requests