TidyDrop

An AI-powered Dropbox file organizer that uses semantic understanding to automatically categorize files into meaningful folders.

What It Does

Unlike traditional file organizers that rely on file extensions, TidyDrop uses Google Gemini to analyze filenames and intelligently classify files into categories like Finance, Health, Work, Education, and more.

Example:

• faktura_WA_10445_2026.pdf → Finance (recognized as invoice)
• English_File_3d_Advanced_SB.pdf → Education (recognized as study material)
• lab_results_march.pdf → Health (recognized as medical document)

Features

• Content-Aware Sorting - AI analyzes filenames for context, not just extensions
• Configurable Categories - Define your own categories in categories.json
• Dropbox Integration - Works directly with your Dropbox via API
• Rate Limit Handling - Built-in retry logic for API limits

Quick Start

1. Install dependencies

poetry install

2. Configure environment

Create a .env file:

ACCESS_TOKEN=<your_dropbox_access_token>
GEMINI_API_KEY=<your_gemini_api_key>
TARGET_FOLDER=/TestZone

Get your API keys:

• Dropbox: https://www.dropbox.com/developers/apps
• Gemini: https://aistudio.google.com/apikey

3. Customize categories (optional)

Edit categories.json to define your own categories:

{
  "categories": [
    {
      "name": "Finance",
      "description": "Invoices, receipts, bank statements, tax documents"
    },
    {
      "name": "Project X",
      "description": "All files related to Project X deliverables"
    }
  ],
  "default_category": "Other"
}

4. Run

poetry run python organizer.py

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Dropbox API    │────▶│  Gemini LLM     │────▶│  File Move      │
│  (list files)   │     │  (classify)     │     │  (organize)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Roadmap

Current (v0.2)

• Gemini-powered filename classification
• Configurable category definitions
• Retry logic for rate limits

Future Plans

• Content Analysis - Extract text snippets from PDFs/docs for deeper classification
• Local LLM Option - Support for Ollama/Llama to run entirely offline
• Learning Mode - Remember user corrections to improve future classifications
• Batch Processing - Classify multiple files in a single API call for efficiency
• Watch Mode - Continuously monitor folder for new files

Notes

• Keep your .env out of version control
• Free tier Gemini API has daily limits (~1500 requests/day)
• For production, use OAuth refresh tokens instead of long-lived access tokens

License

MIT