AI Download Analyzer

AI Download Analyzer is a smart background utility for Windows that automatically sorts your downloaded files into organized, topic-based folders. It combines simple rule-based sorting for common file types with the power of the Anthropic API to classify ambiguous files based on their names.

It runs quietly in your system tray, watching your Downloads folder and keeping it tidy without any manual intervention.

Disclaimer

This project was built strictly for experimental purposes. The entire codebase is vibe-coded, meaning it may not fulfill standard production-level code quality, optimization, or architectural guidelines. Use at your own risk.

Key Features

• Automatic Sorting: Watches your Downloads folder and moves new files to categorized subfolders.
• Hybrid Classification:
  • Rule-Based: Instantly sorts common file types like music, images, and videos based on their extension.
  • AI-Powered: For ambiguous files (.pdf, .docx, .exe), it uses the Anthropic API (Claude Haiku) to determine a specific, descriptive category based on the filename (e.g., invoice_acme_corp_dec.pdf -> Invoices).
• Smart Category Management: Remembers and reuses AI-generated categories to ensure similar files are grouped consistently. It intelligently merges similar names (e.g., "Resume" and "Resumes") to avoid clutter.
• System Tray Integration: Runs as a lightweight background process with a tray icon for easy access to settings, logs, and sorted folders.
• Windows Autostart: Can be configured to launch automatically when you log in.
• First-Run Setup: A simple dialog prompts for your Anthropic API key on the first run, with no need to manually edit configuration files.
• Built-in Safety: Automatically isolates files that appear to contain credentials (apikey, password, etc.) into a dedicated Sensitive_Credentials folder.

How It Works

The sorting logic is applied with the following priority:

1. Sensitive File Check: Any file with a name containing keywords like accesskey, password, or secret_key is immediately moved to a Sensitive_Credentials folder. This check happens before any other logic to ensure security-related files are handled consistently and not sent to the API.

2. Rule-Based Sorting: If the file's extension (e.g., .mp3, .jpg, .zip) matches a predefined category in config.yaml, it's moved to the corresponding folder (e.g., Music, Images, Archives). This is fast and requires no API calls.

3. AI-Powered Classification: If the file extension is ambiguous (like .pdf, .docx, or .csv), the application asks the Anthropic API for a suitable category.

   • It provides the filename and a list of existing AI-created categories to encourage reuse.
   • The AI is instructed to create short, specific, topic-based folder names (e.g., Job_Applications, Course_Notes).
   • Vague, generic names like "Documents" or "Misc" are automatically rejected.
   • Before a new category is created, the system checks if it's highly similar to an existing one and merges them to prevent duplicates like "Invoice" and "Invoices".

4. Fallback: If a file doesn't match any rules and the AI cannot provide a valid category, it is moved to a fallback folder, typically named Other.

Installation & Usage (End-Users)

1. Download the DownloadsSorter.exe file from the latest release.
2. Double-click DownloadsSorter.exe to run it. No installation is required.
3. First-Run Setup: A window will appear asking for your Anthropic API key.
   • You can get a free key from the Anthropic Console.
   • Paste your key into the dialog and click "Save and continue".
   • If you skip this step, the application will only perform rule-based sorting for common file types.
4. The application will now run in the background. You will see a new icon in your Windows system tray (near the clock).
5. Right-click the tray icon for options:
   • Open sorted folder: Opens the Sorted subfolder within your Downloads directory.
   • Open watch folder: Opens your main Downloads folder.
   • View log: Opens the log file for troubleshooting.
   • Edit config.yaml: Opens the configuration file for advanced customization.
   • Start with Windows: Toggles whether the app starts automatically on login.
   • Quit: Stops the application.

For Developers

Prerequisites

• Python 3.x
• Git

Setup

1. Clone the repository:

   git clone https://github.com/cemtbi/ai-download-analyzer.git
   cd ai-download-analyzer

2. Install dependencies:

   pip install -r requirements.txt

3. Set up your API Key: The application requires an Anthropic API key. It looks for it in an environment variable named ANTHROPIC_API_KEY. On first run, the packaged app creates a .env file for you, but for development, you can create it manually.

   Create a file named .env in the root of the project directory with the following content:

   ANTHROPIC_API_KEY="your_anthropic_api_key_here"
   

Running

• For development (console output): This mode runs the watcher directly, logs to the console, and does not show a system tray icon. It's ideal for testing and debugging.

  python watcher.py

• To run the full tray application:

  python main.py

Building the Executable

A build.bat script is provided to package the application into a single .exe file for Windows using PyInstaller.

1. Ensure all dependencies are installed (pip install -r requirements.txt).
2. Run the build script from the command prompt:

   build.bat

3. The final distributable DownloadsSorter.exe will be located in the dist/ directory.

Configuration

The application is configured via a config.yaml file located in the user's app data directory (%LOCALAPPDATA%/DownloadsSorter/). This file is created automatically on the first run.

You can customize:

• watch_folder: The folder to monitor (defaults to your Windows Downloads folder).
• target_base: The root folder where categorized subfolders will be created.
• categories: The mapping of file extensions to rule-based categories.
• ambiguous_extensions: The list of extensions that should be classified by the AI.
• fallback_category: The folder for files that couldn't be categorized.

License

This project is licensed under the MIT License. See the LICENSE file for details.