124 lines
2.4 KiB
Markdown
124 lines
2.4 KiB
Markdown
# PyNamer
|
|
|
|
PyNamer is a command-line tool that uses AI vision models to generate descriptive filenames for images. It analyzes the content of images and renames them with meaningful, descriptive filenames in snake_case format.
|
|
|
|
## Features
|
|
|
|
- Uses LiteLLM to integrate with various vision-capable LLMs (default: GPT-4 Vision)
|
|
- Configurable via YAML config file
|
|
- Supports multiple image formats (jpg, jpeg, png, gif, webp)
|
|
- Dry-run mode to preview changes without renaming files
|
|
- Handles filename collisions automatically
|
|
|
|
## Installation
|
|
|
|
### Option 1: Install from PyPI (recommended)
|
|
|
|
```bash
|
|
pip install pynamer
|
|
```
|
|
|
|
### Option 2: Install from source
|
|
|
|
1. Clone this repository
|
|
2. Install the package in development mode:
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### Set up your API key
|
|
|
|
You need to set up your API key for the vision model:
|
|
|
|
- Set the appropriate environment variable (e.g., `OPENAI_API_KEY`), or
|
|
- Create a custom config file with your API key
|
|
|
|
## Configuration
|
|
|
|
PyNamer uses the following configuration file locations (in order of precedence):
|
|
|
|
1. Custom config file specified with `-c` or `--config` option
|
|
2. User config file at `~/.config/pynamer.yaml` (created automatically on first run)
|
|
3. Default config file included with the package
|
|
|
|
You can customize the following settings:
|
|
|
|
- LLM provider and model
|
|
- API key and endpoint
|
|
- Supported image formats
|
|
- Prompt templates for filename generation
|
|
|
|
Example configuration file:
|
|
|
|
```yaml
|
|
llm:
|
|
provider: "openai"
|
|
model: "gpt-4-vision-preview"
|
|
api_key: "your-api-key-here"
|
|
max_tokens: 100
|
|
temperature: 0.7
|
|
```
|
|
|
|
## Usage
|
|
|
|
After installation, you can use PyNamer directly from the command line:
|
|
|
|
Basic usage:
|
|
|
|
```bash
|
|
pynamer path/to/image.jpg
|
|
```
|
|
|
|
Process multiple images:
|
|
|
|
```bash
|
|
pynamer image1.jpg image2.png image3.jpg
|
|
```
|
|
|
|
Use a different config file:
|
|
|
|
```bash
|
|
pynamer -c custom_config.yaml image.jpg
|
|
```
|
|
|
|
Preview changes without renaming (dry run):
|
|
|
|
```bash
|
|
pynamer -d image.jpg
|
|
```
|
|
|
|
Enable verbose logging:
|
|
|
|
```bash
|
|
pynamer -v image.jpg
|
|
```
|
|
|
|
## Example
|
|
|
|
Input: `IMG_20230615_123456.jpg` (a photo of a cat sleeping on a window sill)
|
|
|
|
Output: `orange_cat_sleeping_on_sunny_windowsill.jpg`
|
|
|
|
## Development
|
|
|
|
### Building the package
|
|
|
|
```bash
|
|
pip install build
|
|
python -m build
|
|
```
|
|
|
|
### Installing in development mode
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Python 3.7+
|
|
- LiteLLM
|
|
- PyYAML
|
|
- Access to a vision-capable LLM API (OpenAI, Anthropic, etc.)
|