Skip to content

Home

Jump to bottom
Bormotoon edited this page Mar 1, 2025 · 1 revision

Вот обновлённый мануал для Wiki вашего репозитория на GitHub с учётом ссылки https://github.com/Bormotoon/ollamaFS. Я также добавил несколько примеров использования, чтобы показать практическую пользу приложения. Мануал остаётся на английском языке, как это принято для GitHub Wiki.

Document Sorter with Ollama User Manual

Welcome to the user manual for Document Sorter with Ollama, a versatile tool for organizing files into categories using the Ollama AI model. This guide covers installation, configuration, and usage via both the graphical user interface (GUI) and command-line interface (CLI). It includes detailed steps, practical examples, and troubleshooting tips.

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Installation
  4. Running the Application
  5. Using the GUI
  6. Using the CLI
  7. Practical Examples
  8. Troubleshooting

Introduction

"Document Sorter with Ollama" is a Python application hosted at https://github.com/Bormotoon/ollamaFS, inspired by llama-fs. The original project faced challenges running on macOS and relied on costly APIs, prompting a reimagined version that leverages a local Ollama model for free, AI-powered file sorting. Enhanced with a Tkinter-based GUI, cloud storage support (Google Drive and Dropbox), and features like duplicate removal, this tool offers a practical solution for file organization.

Prerequisites

Before using the application, ensure you have:

  • Python 3.6+: Installed on your system (3.11 recommended for compatibility).
  • Ollama: Running locally at http://localhost:11434. Download and install from Ollama's official site.
  • Git: For cloning the repository.
  • Internet Access: For initial dependency installation and optional cloud integration.

For cloud features:

  • Google Drive: A credentials.json file from Google Cloud Console.
  • Dropbox: An access token from the Dropbox App Console.

Installation

  1. Clone the Repository:

    git clone https://github.com/Bormotoon/ollamaFS.git
cd ollamaFS

  2. Set Up a Virtual Environment (recommended):

    python -m venv venv
    • Activate it:
      • Windows: venv\Scripts\activate
      • Linux/Mac: source venv/bin/activate

  3. Install Dependencies:

    pip install -r requirements.txt

    This installs all required Python packages listed in requirements.txt.

  4. Verify Ollama:

    • Start Ollama (e.g., ollama serve in a terminal).
    • Test connectivity: Visit http://localhost:11434 in a browser to confirm it’s running.

  5. Optional Cloud Setup:

    • Google Drive:
      • Go to Google Cloud Console.
      • Create a project, enable the Drive API, and generate a service account key (credentials.json).
      • Place credentials.json in the project root.
    • Dropbox:
      • Visit Dropbox App Console.
      • Create an app, generate an access token, and note it for later use.

Running the Application

GUI Mode

Launch the application with:

python main.py

This opens the graphical interface for interactive use.

Command-Line Mode

Run with specific arguments:

python main.py --source /path/to/source --dest /path/to/dest

See Using the CLI for details.

Using the GUI

Main Interface Overview

Upon launching in GUI mode, you'll see:

  • Language Menu: Top-left, switch between English and Russian.
  • Ollama Status: Displays connection status (green for connected, red for disconnected).
  • Model Selection: Dropdown to choose an Ollama model.
  • Directory Selection: Fields for source and destination directories.
  • Categories: Tree view for managing categories, with an "Automatic Sorting" checkbox.
  • Duplicate Removal Options: Radio buttons for deduplication modes.
  • Log: Text area for operation logs.
  • Progress Bar: Shows sorting progress.
  • Buttons: "Start Sorting" and "Create Backup".

Selecting Directories

  1. Source Directory:
    • Click "Browse" next to "Source Directory" or drag-and-drop a folder.
    • This is where unsorted files reside (e.g., /home/user/downloads).
  2. Destination Directory:
    • Click "Browse" next to "Destination Directory".
    • This is where sorted files will be moved (e.g., /home/user/sorted).

Managing Categories

  • Automatic Sorting:
    • Enabled by default (checkbox checked).
    • Ollama generates categories based on file analysis (e.g., "Documents/Work", "Images").
    • Set "Max Subcategory Depth" (default 3) to control nesting (e.g., 2 limits to "Documents/Work").
    • Manual controls are disabled in this mode.
  • Manual Categories:
    • Uncheck "Automatic Sorting" to enable manual controls.
    • Add Category: Click "Add Category", enter a name (e.g., "Documents"), and press OK.
    • Add Subcategory: Select a category, click "Add Subcategory", enter a name (e.g., "Work"), and press OK.
    • Remove: Select a category/subcategory and click "Remove".
    • Example tree: "Documents" → "Work", "Personal".

Duplicate Removal Options

  • No Deduplication: Default, keeps all files.
  • Normal: Removes exact duplicates (same MD5 hash), keeps the newest.
  • Hardcore: Removes files with same name and size (minor differences allowed), keeps the newest.
  • Select a mode before sorting.

Sorting Files

  1. Set source and destination directories.
  2. Choose automatic or manual categories.
  3. Select a duplicate removal mode.
  4. Click "Start Sorting".
    • Progress bar updates as files are processed.
    • Log shows actions (e.g., "Moved 'report.docx' to 'Documents/Work'").
    • Files move to dest_dir/category/subcategory/filename.

Cloud Integration

  • Google Drive:
    • Click "Connect Google Drive".
    • Requires credentials.json in the project root.
    • Files download to a temporary folder for sorting.
  • Dropbox:
    • Click "Connect Dropbox".
    • Enter your access token when prompted.
    • Specify a Dropbox folder in CLI mode or adjust code for GUI.

Creating Backups

  • Click "Create Backup" before sorting.
  • Choose a location and name for the ZIP file (e.g., backup.zip).
  • The source directory is archived for safety.

Exporting Logs

  • Click "Export Log" to save the log as a .txt file.
  • Useful for tracking actions or debugging.

Using the CLI

Basic Command

Sort with automatic categories:

python main.py --source /path/to/source --dest /path/to/dest

Specifying Categories

Use custom categories (disables automatic sorting):

python main.py --source /path/to/source --dest /path/to/dest --categories "Documents,Images,Documents/Work"
  • Categories are comma-separated; use "/" for subcategories.

Duplicate Removal

Enable deduplication:

python main.py --source /path/to/source --dest /path/to/dest --dedupe normal
  • Options: none, normal, hardcore.

Practical Examples

Example 1: Organizing a Messy Downloads Folder

  • Scenario: Your Downloads folder (/home/user/downloads) is cluttered with PDFs, images, and documents.
  • GUI Steps:
    1. Run python main.py.
    2. Drag /home/user/downloads to "Source Directory".
    3. Set "Destination Directory" to /home/user/sorted.
    4. Leave "Automatic Sorting" checked (depth 2).
    5. Select "Normal" deduplication.
    6. Click "Start Sorting".
  • Result: Files sorted into /home/user/sorted/Documents/Reports, /home/user/sorted/Images, etc., with duplicates removed.
  • Why Use It?: Quickly organizes a chaotic folder without manual effort.

Example 2: Sorting Project Files

  • Scenario: You have a project folder (/projects/myproject) with code, docs, and images.
  • CLI Command: 
    python main.py --source /projects/myproject --dest /projects/sorted --categories "Code,Docs,Images" --dedupe hardcore
  • Result: Files sorted into /projects/sorted/Code, /projects/sorted/Docs, etc., with older duplicates removed.
  • Why Use It?: Keeps project files structured for team collaboration or archiving.

Example 3: Cleaning Up Cloud Storage

  • Scenario: Your Dropbox folder (/Dropbox/Files) has redundant files.
  • GUI Steps:
    1. Run python main.py.
    2. Click "Connect Dropbox", enter your token.
    3. Set "Source Directory" to a local path (cloud files download temporarily).
    4. Set "Destination Directory" to /home/user/cleaned.
    5. Enable "Automatic Sorting" (depth 3).
    6. Select "Hardcore" deduplication.
    7. Click "Start Sorting".
  • Result: Files sorted into /home/user/cleaned/Documents/Work/Reports, etc., with duplicates cleaned.
  • Why Use It?: Tidies up cloud storage efficiently.

Troubleshooting

  • Ollama Not Connected:
    • Ensure Ollama is running (ollama serve).
    • Test http://localhost:11434 in a browser.
  • ModuleNotFoundError:
    • Run pip install -r requirements.txt in the virtual environment.
    • Activate environment: venv\Scripts\activate (Windows) or source venv/bin/activate (Linux/Mac).
  • Cloud Connection Fails:
    • Google Drive: Verify credentials.json is in the root and has correct permissions.
    • Dropbox: Check token validity.
  • Sorting Fails:
    • Confirm source/destination paths exist and are writable.
    • Check the log for error details.

This manual provides a comprehensive guide to using "Document Sorter with Ollama". For more details, refer to the README.md or submit an issue at https://github.com/Bormotoon/ollamaFS.

Clone this wiki locally