Metadata-Version: 2.4
Name: local-file-organizer
Version: 2.1.1
Summary: AI-powered local file management with state-of-the-art models
Author-email: Local File Organizer Team <noreply@example.com>
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/curdriceaurora/Local-File-Organizer
Project-URL: Documentation, https://github.com/curdriceaurora/Local-File-Organizer#readme
Project-URL: Repository, https://github.com/curdriceaurora/Local-File-Organizer
Project-URL: Issues, https://github.com/curdriceaurora/Local-File-Organizer/issues
Project-URL: Changelog, https://github.com/curdriceaurora/Local-File-Organizer/releases
Keywords: file-management,ai,organization,local-llm,privacy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ollama>=0.1.0
Requires-Dist: Pillow~=12.0
Requires-Dist: snowballstemmer>=2.2
Requires-Dist: numpy<2.5,>=1.26.4
Requires-Dist: tqdm~=4.66
Requires-Dist: defusedxml>=0.7
Requires-Dist: typer[all]<0.26,>=0.12
Requires-Dist: rich~=15.0
Requires-Dist: textual~=0.50
Requires-Dist: fastapi~=0.109
Requires-Dist: starlette~=1.3
Requires-Dist: aiofiles~=25.1
Requires-Dist: jinja2~=3.1
Requires-Dist: markupsafe~=3.0
Requires-Dist: uvicorn[standard]~=0.27
Requires-Dist: websockets<17,>=12.0
Requires-Dist: httpx~=0.26
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: Pygments>=2.20.0
Requires-Dist: pyjwt~=2.8
Requires-Dist: bcrypt<6.0.0,>=4.0.0
Requires-Dist: pycryptodomex>=3.23.0
Requires-Dist: sqlalchemy~=2.0
Requires-Dist: alembic~=1.13
Requires-Dist: redis~=8.0
Requires-Dist: pyyaml~=6.0
Requires-Dist: platformdirs~=4.10
Requires-Dist: pydantic~=2.5
Requires-Dist: pydantic-settings~=2.1
Requires-Dist: email-validator~=2.1
Requires-Dist: python-dotenv~=1.0
Requires-Dist: click~=8.1
Requires-Dist: watchdog<7,>=3.0
Requires-Dist: psutil<8,>=5.9
Requires-Dist: loguru>=0.7.0
Provides-Extra: parsers
Requires-Dist: PyMuPDF~=1.23; extra == "parsers"
Requires-Dist: python-docx~=1.0; extra == "parsers"
Requires-Dist: openpyxl~=3.1; extra == "parsers"
Requires-Dist: python-pptx>=0.6.0; extra == "parsers"
Requires-Dist: ebooklib<1,>=0.20; extra == "parsers"
Requires-Dist: beautifulsoup4~=4.12; extra == "parsers"
Requires-Dist: lxml~=6.1; extra == "parsers"
Provides-Extra: web
Requires-Dist: fastapi~=0.109; extra == "web"
Requires-Dist: jinja2~=3.1; extra == "web"
Requires-Dist: uvicorn[standard]~=0.27; extra == "web"
Requires-Dist: websockets<17,>=12.0; extra == "web"
Requires-Dist: httpx~=0.26; extra == "web"
Requires-Dist: python-multipart>=0.0.9; extra == "web"
Requires-Dist: Pygments>=2.20.0; extra == "web"
Requires-Dist: pyjwt~=2.8; extra == "web"
Requires-Dist: bcrypt<6.0.0,>=4.0.0; extra == "web"
Requires-Dist: redis~=8.0; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest~=9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio~=1.4; extra == "dev"
Requires-Dist: pytest-cov<8,>=4.1; extra == "dev"
Requires-Dist: pytest-mock~=3.12; extra == "dev"
Requires-Dist: pytest-timeout<2.5.0,>=2.2.0; extra == "dev"
Requires-Dist: pytest-xdist~=3.5; extra == "dev"
Requires-Dist: pytest-randomly~=4.1; extra == "dev"
Requires-Dist: mypy<1.20,>=1.19; extra == "dev"
Requires-Dist: types-PyYAML~=6.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black<27.0,>=23.12; extra == "dev"
Requires-Dist: isort~=8.0; extra == "dev"
Requires-Dist: pre-commit~=4.6; extra == "dev"
Requires-Dist: codespell~=2.2; extra == "dev"
Requires-Dist: faker~=40.12; extra == "dev"
Requires-Dist: pytest-benchmark<6,>=4.0; extra == "dev"
Requires-Dist: interrogate~=1.5; extra == "dev"
Requires-Dist: pymarkdownlnt>=0.9.25; extra == "dev"
Requires-Dist: deptry>=0.16.0; extra == "dev"
Requires-Dist: diff-cover~=10.3; extra == "dev"
Requires-Dist: asgi-lifespan~=2.1; extra == "dev"
Requires-Dist: pytest-playwright>=0.5.0; extra == "dev"
Requires-Dist: axe-playwright-python>=0.1.7; extra == "dev"
Provides-Extra: cloud
Requires-Dist: openai~=2.44; extra == "cloud"
Provides-Extra: llama
Requires-Dist: llama-cpp-python>=0.2.0; extra == "llama"
Provides-Extra: mlx
Requires-Dist: mlx-lm>=0.0.19; platform_system == "Darwin" and extra == "mlx"
Provides-Extra: claude
Requires-Dist: anthropic>=0.20.0; extra == "claude"
Provides-Extra: gui
Requires-Dist: PyQt6~=6.6; extra == "gui"
Provides-Extra: desktop
Requires-Dist: pywebview>=4.4; extra == "desktop"
Requires-Dist: uvicorn[standard]~=0.27; extra == "desktop"
Provides-Extra: audio
Requires-Dist: faster-whisper~=1.0; extra == "audio"
Requires-Dist: torch~=2.1; extra == "audio"
Requires-Dist: mutagen~=1.47; extra == "audio"
Requires-Dist: tinytag<3.0,>=1.10; extra == "audio"
Requires-Dist: pydub>=0.25.0; extra == "audio"
Requires-Dist: audioop-lts; python_version >= "3.13" and extra == "audio"
Provides-Extra: video
Requires-Dist: opencv-python~=5.0; extra == "video"
Requires-Dist: scenedetect[opencv]>=0.6.0; extra == "video"
Provides-Extra: dedup
Requires-Dist: imagededup>=0.3.0; extra == "dedup"
Requires-Dist: scikit-learn~=1.4; extra == "dedup"
Requires-Dist: pypdf<7,>=4; extra == "dedup"
Requires-Dist: striprtf>=0.0.26; extra == "dedup"
Provides-Extra: archive
Requires-Dist: py7zr>=0.20.0; extra == "archive"
Requires-Dist: rarfile~=4.1; extra == "archive"
Provides-Extra: scientific
Requires-Dist: h5py~=3.10; extra == "scientific"
Requires-Dist: netCDF4~=1.6; extra == "scientific"
Requires-Dist: scipy~=1.11; extra == "scientific"
Provides-Extra: cad
Requires-Dist: ezdxf~=1.1; extra == "cad"
Provides-Extra: build
Requires-Dist: pyinstaller~=6.0; extra == "build"
Provides-Extra: docs
Requires-Dist: mkdocs~=1.5; extra == "docs"
Requires-Dist: mkdocs-material~=9.5; extra == "docs"
Requires-Dist: pymdown-extensions~=11.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Provides-Extra: search
Requires-Dist: rank-bm25>=0.2.0; extra == "search"
Requires-Dist: scikit-learn~=1.4; extra == "search"
Provides-Extra: all
Requires-Dist: local-file-organizer[archive,audio,build,cad,claude,cloud,dedup,dev,gui,llama,mlx,parsers,scientific,search,video,web]; extra == "all"
Dynamic: license-file

# Local File Organizer

[![CI](https://github.com/curdriceaurora/Local-File-Organizer/actions/workflows/ci.yml/badge.svg?style=flat-square)](https://github.com/curdriceaurora/Local-File-Organizer/actions/workflows/ci.yml)
[![Version](https://img.shields.io/badge/version-2.1.1-blue?style=flat-square)](CHANGELOG.md)
[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)

This software uses AI to organize your local files. It operates locally with Ollama. It does not need a cloud connection. You can also connect it to an OpenAI-compatible endpoint or Anthropic Claude.

![TUI overview](docs/assets/tui-overview.svg)

## Contents

- [Features](#features)
- [How It Works](#how-it-works)
- [Interfaces](#interfaces-visuals)
- [Quick Start (Essentials)](#quick-start-essentials)
- [Documentation](#documentation)
- [Optional Feature Packs](#optional-feature-packs)
- [Development](#development)
- [Contributing](#contributing)
- [Configuration](#configuration)
- [License](#license)

## Features

### AI and Analysis

- **AI-Powered Organization**: Uses Qwen 2.5 3B (text) and Qwen 2.5-VL 7B (vision) with Ollama. It also supports OpenAI-compatible endpoints and Anthropic Claude.
- **Audio Transcription**: Uses faster-whisper to convert local speech to text. This uses the GPU.
- **Video Analysis**: Finds scenes and gets keyframes from video files.
- **Intelligence**: Learns patterns, tracks your preferences, suggests actions, and adds tags automatically.

### Interfaces

- **Terminal UI**: Gives you an 8-view Textual TUI (Files, Analytics, Audio, History, Copilot).
- **Web UI**: Shows a browser interface with FastAPI and HTMX.
- **Desktop App**: Shows a native OS window with pywebview. It uses a single Python process. It does not use Electron or Rust.
- **Full CLI**: Includes commands to organize, set rules, suggest, find duplicates, run as a daemon, show analytics, update, and manage API keys.
- **Copilot Chat**: Lets you use natural language to give commands. For example, type "organize ./Downloads" or "undo".

### Organization

- **Extensive Support**: Operates on 840 tests, 408 modules, and 39 file types.
- **Organization Rules**: Sorts files automatically with conditions and previews. It saves rules in YAML.
- **PARA + Johnny Decimal**: Includes these organizational methodologies.
- **Deduplication**: Finds duplicate files with hash and semantic checks.
- **Undo/Redo**: Keeps a full history of operations so you can undo them.
- **Auto-Update**: Updates Linux AppImage from GitHub Releases. Updates macOS and Windows with `pip` or `pipx`.
- **Cross-Platform**: Operates on macOS, Windows, and Linux.

## How It Works

```mermaid
flowchart LR
    subgraph Source["Source Directory"]
        direction TB
        A[report.pdf]
        B[photo.jpg]
        C[meeting.mp3]
        D[clip.mp4]
    end

    subgraph AI["AI Analysis"]
        direction TB
        E[Content Extraction]
        F[AI Categorize]
    end

    subgraph Output["Organized Output"]
        direction TB
        G[Work/Reports/]
        H[Photos/Vacation/]
        I[Audio/Meetings/]
    end

    Source --> E --> F --> Output
    F -.-> |Learn Patterns| F
```

1. **Scan** — The software reads files from a source directory. It gets text, metadata, and visual content. It supports more than 80 formats.
2. **Analyze** — The software sends the content to an AI model. The model categorizes and names the files.
3. **Organize** — The software moves or copies files into folders. It uses the AI-generated names.
4. **Learn** — The software tracks your patterns and preferences to make better suggestions in the future.

## Interfaces (Visuals)

### Terminal UI
![TUI demo](docs/assets/tui-demo.gif)

### Web UI (Preview)
To start the FastAPI server and open the UI, type this command:

```bash
file-organizer serve --reload
```

Then, go to `http://localhost:8000/ui/` in your browser.

## Quick Start (Essentials)

### With Ollama (local, default)

```bash
# Install from PyPI with pipx:
pipx install local-file-organizer
# or with pip:
pip install local-file-organizer

# 1) Set the default configuration
fo setup

# 2) Preview a folder before you change anything
fo preview ~/Downloads

# 3) Start the organization process
fo organize ~/Downloads ~/Organized

# 4) Undo the most recent organize run if necessary
fo undo
```

### Use cloud providers instead of the default local flow

Read the [AI Provider Setup guide](docs/setup/ai-providers.md) for OpenAI-compatible endpoints and Claude.

```bash
# OpenAI-compatible providers
export FO_PROVIDER=openai

# Anthropic Claude
export FO_PROVIDER=claude
```

## Documentation

### Essentials

- [Documentation Home](docs/index.md)
- [Getting Started](docs/getting-started.md)
- [CLI Reference](docs/cli-reference.md#core-first-run-commands)
- [User Guide Workflow Map](docs/USER_GUIDE.md#workflow-map-quick-paths)
- [Web UI Quick Start](docs/web-ui/getting-started.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Installation Guide](docs/admin/installation.md)

### Advanced / Admin / Developer

- [Full CLI Reference](docs/cli-reference.md)
- [Terminal UI Guide](docs/tui.md)
- [Desktop App Guide](docs/desktop-app.md)
- [AI Provider Setup](docs/setup/ai-providers.md)
- [Audio & Video Processing Guide](docs/setup/audio-video.md)
- [Configuration Guide](docs/CONFIGURATION.md)
- [API Reference](docs/api/index.md)
- [File Format Reference](docs/admin/file-format-reference.md)
- [Path Standardization & Migration](docs/config/path-standardization.md)
- [Johnny Decimal User Guide](docs/methodologies/johnny-decimal/user-guide.md)
- [Johnny Decimal Migration Guide](docs/methodologies/johnny-decimal/migration.md)

## Optional Feature Packs

Canonical extras matrix:

- [Dependencies & Optional Extras](docs/setup/dependencies.md#optional-extras-matrix)

Common installation commands:

```bash
pip install "local-file-organizer[parsers,web]"
pip install "local-file-organizer[cloud,claude]"
pip install "local-file-organizer[all]"
```

> **From source (development):** Download the repository and use an editable install (for example, `pip install -e ".[all]"`).

### Audio system dependencies

To get full audio format support, the `[audio]` pack uses **FFmpeg** (all platforms). It optionally uses **CUDA + cuDNN** (for NVIDIA GPU users).

**FFmpeg** — This is necessary for non-`.wav` formats (MP3, M4A, FLAC, OGG). It is optional if you only transcribe raw `.wav` files:

```bash
# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (winget)
winget install ffmpeg
```

**CUDA + cuDNN** — This is optional. It makes transcription much faster.

```bash
# Install CUDA Toolkit from https://developer.nvidia.com/cuda-downloads
# Install cuDNN from https://developer.nvidia.com/cudnn

# Verify the full transcription backend
python3 -c "from faster_whisper import WhisperModel; print('faster-whisper OK')"
python3 -c "import torch; print('CUDA:', torch.cuda.is_available())"
```

**Fallback behavior**: If you do not have FFmpeg, the software only transcribes `.wav` files. It organizes other formats by filename and metadata, but it does not analyze their content. If you do not have CUDA, the transcription uses the CPU. This is slower but it operates correctly.

Read the [Installation Guide](docs/admin/installation.md) to find troubleshooting steps and advanced configuration options.

## Development

```bash
# Start tests
pytest

# Find errors with ruff
ruff check src/
```

*(To see a full breakdown of the project structure, read [CONTRIBUTING.md](CONTRIBUTING.md))*

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) to learn about the development setup, coding standards, project structure, and how to submit your changes.

## Configuration

The software stores configuration files in these locations:
- **macOS**: `~/Library/Application Support/file-organizer/`
- **Linux**: `~/.config/file-organizer/` (or `$XDG_CONFIG_HOME/file-organizer/`)
- **Windows**: `%APPDATA%/file-organizer/`

Read the [Configuration Guide](docs/CONFIGURATION.md) for more data.

## License

This project uses the [MIT License](LICENSE).

---

**Status**: Stable | **Version**: 2.1.1 | **Last Updated**: 2026-07-20
