Item Sorter

Overview
Features
Prerequisites
Installation
Configuration
Usage
Running in Background (Production)
Contributing
License

Overview

Item Sorter monitors your Downloads folder and watches for new files. When a new file or files appears, it intelligently categorizes and organizes them into existing folders if it can find an appropriate one, or it creates a new folder if needed. It uses the ChatGPT API to determine the appropriate folders.

Files are managed in batches of up to 10, ensuring efficient processing and reduced API requests. Recent files are moved to a Recents folder, while older files are categorized and stored in sub folders under a folder called AI Library. Item Sorter ignores pre-existing and new folders and only operates in individual files.

Features

Real-time Folder Monitoring: Utilizes chokidar to watch for new files in the specified directory.
Batch Processing: Groups incoming files into batches of up to 10 for efficient API interactions.
Smart Categorization: Leverages ChatGPT to suggest suitable categories based on file names and existing folders.
Re-categorization: Allows re-categorizing files in existing folders for better organization.
Automated Organization: Moves recent files to a Recents folder and older files to categorized folders within an AI Library.
Customizable Paths: Allows users to specify a custom directory path via command-line arguments.
Scheduled Maintenance: Periodically checks and moves files older than three days from Recents to AI Library.
Error Handling & Logging: Comprehensive logging for monitoring and debugging purposes.

Prerequisites

Node.js (v14 or later)
npm (Node Package Manager)
OpenAI API Key: Required to interact with the ChatGPT API.

Installation

Clone the Repository

git clone https://github.com/marcus/Item-Sorter.git

Navigate to the Project Directory
```
cd Item-Sorter
```
Install Dependencies
```
npm install
```
Set Up Environment Variables

Create a .env file in the root directory and add your OpenAI API key:
```
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini-2024-07-18
```
Note: Ensure that the .env file is included in your .gitignore to prevent sensitive information from being exposed.

Configuration

Item Sorter can be customized using command-line arguments to specify the directory you want to monitor.

Default Directory: Downloads folder in the user's home directory.
Custom Directory: Use the --path argument to specify a different directory.
Re-categorization Mode: Use the --recategorize flag followed by folder names to re-categorize files.

Examples

# Use a custom directory
node index.js --path="/Users/marcus/Documents/My Downloads"

# Re-categorize a specific folder within AI Library
node index.js --recategorize "Business Reports"

# You can also use the full path
node index.js --recategorize "AI Library/Business Reports"

# Re-categorize multiple folders
node index.js --recategorize "Screenshots" "Misc"

Usage

Start the Application

node index.js

Or with a custom path:

node index.js --path="/path/to/your/custom/folder"

How It Works
- Monitoring: The application continuously watches the specified directory for new files.
- Batching: Files are grouped into batches of up to 10. If the batch size is reached or after a 3-second interval, the batch is processed.
- Categorization: The batch is sent to the ChatGPT API, which suggests appropriate folders for each file based on its name.
- Organization:
  - Recent Files: Files less than or equal to 72 hours old are moved to the Recents folder.
  - Older Files: Files older than 72 hours are moved to the AI Library under the suggested categories.
- Scheduled Maintenance: Every hour, the application checks the Recents folder and moves files older than three days to the AI Library.
- Re-categorization: When using the --recategorize flag, the app analyzes files in the specified folders and suggests better categorizations based on file names and existing folder structure.

Running in Background (Production)

For continuous operation, you can use PM2 (Process Manager 2) to run Item Sorter as a background service on macOS.

Installing PM2

Install PM2 globally
```
npm install -g pm2
```

Starting with PM2

Start the application with PM2

pm2 start index.js --name "item-sorter"

Or with a custom path:

pm2 start index.js --name "item-sorter" -- --path="/path/to/your/custom/folder"

Save the PM2 process list
```
pm2 save
```
Set PM2 to start on system boot
```
pm2 startup
```
Follow the instructions provided by PM2 to complete the startup configuration.

Managing the Background Process

View process status:
```
pm2 status
```
View detailed process information:
```
pm2 describe item-sorter
```
View logs:
```
pm2 logs item-sorter
```
Restart the process:
```
pm2 restart item-sorter
```
Stop the process:
```
pm2 stop item-sorter
```
Remove the process:
```
pm2 delete item-sorter
```
Monitor CPU and memory usage:
```
pm2 monit
```

Log Management

PM2 automatically manages logs for your application:

Error logs: ~/.pm2/logs/item-sorter-error.log
Output logs: ~/.pm2/logs/item-sorter-out.log

You can view the last 1000 lines of logs with:

pm2 logs item-sorter --lines 1000

Contributing

Contributions are welcome! Please follow these steps:

Fork the Repository
Create a New Branch
```
git checkout -b feature/YourFeatureName
```
Make Your Changes
Commit Your Changes
```
git commit -m "Add your message here"
```
Push to the Branch
```
git push origin feature/YourFeatureName
```
Open a Pull Request

Please ensure that your code adheres to the project's coding standards and that all tests pass.

License

This project is licensed under the MIT License.

marcus/item-sorter