smartfileman 0.1.3

CLI tool to organize files by extension, fuzzy filename similarity, and semantic grouping

fileman

smartfileman is a powerful command-line tool that intelligently organizes files in your directories using multiple strategies:

• 📁 Extension-based grouping - Organize files by type (Images, Documents, Videos, etc.)
• 🔍 Fuzzy filename clustering - Group similar filenames using intelligent string matching
• 🧠 Semantic clustering - Use AI embeddings (via Ollama) to group files by content meaning

Installation

From PyPI (Recommended)

pip install smartfileman

Local development install

pip install .

Then run:

fileman --help

Requirements

• Python 3.9, 3.10, 3.11, or 3.12
• For semantic mode: Ollama must be installed and running

Usage

Basic Usage

Organize files in a directory by extension:

fileman organize-files --dir /path/to/folder

Common Options

Option	Short	Description
--dir	-d	Source directory to organize (default: current directory)
--interactive	-i	Prompt for custom folder names
--raw	-R	Use fuzzy filename clustering
--semantic	-s	Use AI-powered semantic grouping
--preview	-p	Preview grouping without moving files
--recursive	-r	Organize files in subdirectories
--eliminate-duplicates	--ed	Remove duplicate files

Examples

Preview before organizing:

fileman organize-files --dir ~/Downloads --preview

Organize with fuzzy clustering:

fileman organize-files --dir ~/Documents --raw

AI-powered semantic organization:

fileman organize-files --dir ~/Projects --semantic

Interactive mode with custom folder names:

fileman organize-files --dir ~/Desktop --interactive

Semantic Mode

Semantic mode uses Ollama to generate embeddings from file content and cluster files by meaning. It automatically:

1. Checks for required models (embeddinggemma, llama3.2)
2. Prompts to download missing models
3. Extracts text from PDFs, DOCX, PPTX, TXT, MD, and more
4. Clusters files using K-Means on combined title + content embeddings

Installing Ollama

1. Download from ollama.ai
2. Install and start the Ollama service
3. Run fileman with --semantic flag - missing models will be auto-downloaded

Supported File Types

Category	Extensions
Images	jpg, png, webp
Videos	mp4, mkv
Audio	mp3, wav
Archives	tar, zip, xz
Documents	pdf, docx, pptx, md

Development

# Clone the repository
git clone https://github.com/yourusername/smartfileman.git
cd smartfileman

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

# Run the CLI
fileman --help

Publishing

# Build distribution
python -m build

# Upload to PyPI
twine upload dist/*

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open an issue or submit a PR.

Installation Scripts

Linux/macOS

curl -sSL https://raw.githubusercontent.com/DineshThumma9/filman/main/scripts/install.sh | bash

Windows (PowerShell)

iwr https://raw.githubusercontent.com/DineshThumma9/filman/main/scripts/install.ps1 -useb | iex

The installer will:

• Automatically find a compatible Python version (3.9-3.13 for full features)
• Install with semantic support if available
• Fall back to base installation on Python 3.14+

Manual Installation

# All Python versions (base features)
pip install smartfileman

# Python 3.9-3.13 (with semantic mode)
pip install smartfileman[semantic]

# Using specific Python version
python3.12 -m pip install smartfileman[semantic]