Metadata-Version: 2.4
Name: local-file-organizer
Version: 2.2.0
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<18,>=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<18,>=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~=9.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~=3.6; 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,>=6.15.0; 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.2.0-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 Analysis**: Uses Qwen 2.5 3B (text) and Qwen 2.5-VL 7B (vision) with Ollama, OpenAI-compatible endpoints, or Anthropic Claude (see [`analysis.inspect`](docs/developer/capability-matrix.md#analysisinspect)).
- **Audio Transcription**: Uses faster-whisper to convert local speech to text (requires optional `[audio]` extra; see [`audio.transcribe`](docs/developer/capability-matrix.md#audiotranscribe)).
- **Video Analysis**: Finds scenes and gets keyframes from video files (requires optional `[video]` extra; see [`video.analyze`](docs/developer/capability-matrix.md#videoanalyze)).
- **Intelligence**: Learns patterns, tracks preferences, suggests actions, and adds tags automatically (see [`automation.suggestions`](docs/developer/capability-matrix.md#automationsuggestions) and [`automation.tags`](docs/developer/capability-matrix.md#automationtags)).

### Interfaces

- **Terminal UI**: Gives an 8-view Textual TUI (see [`interfaces.launch`](docs/developer/capability-matrix.md#interfaceslaunch)).
- **Web UI**: Browser interface powered by FastAPI and HTMX (see [`web-desktop` surface status](docs/developer/capability-matrix.md#summary-statistics)).
- **Desktop App**: Native OS window using pywebview (shares the [`web-desktop` surface adapter](docs/developer/capability-matrix.md#summary-statistics) in a single Python process).
- **Full CLI**: Includes commands to organize, set rules, suggest, find duplicates, run as a daemon, show analytics, update, and manage API keys (see [`cli` surface status](docs/developer/capability-matrix.md#summary-statistics)).
- **Copilot Chat**: Accepts natural language commands such as "organize ./Downloads" or "undo" (see [`copilot.chat`](docs/developer/capability-matrix.md#copilotchat)).

### Organization

- **Product Capability Matrix**: Built on [34 product capabilities](docs/developer/capability-matrix.md#summary-statistics) across [6 official surfaces](docs/developer/capability-matrix.md#summary-statistics), with automated cross-surface parity enforcement (conformance-verified for [`organization.execute`](docs/developer/capability-matrix.md#organizationexecute), [`organization.preview`](docs/developer/capability-matrix.md#organizationpreview), [`organization.scan`](docs/developer/capability-matrix.md#organizationscan), and [`methodology.configure`](docs/developer/capability-matrix.md#methodologyconfigure)).
- **Organization Rules**: Sorts files automatically with conditions and previews (see [`automation.rules`](docs/developer/capability-matrix.md#automationrules)).
- **PARA + Johnny Decimal**: Supports canonical organization methodologies (see [`methodology.configure`](docs/developer/capability-matrix.md#methodologyconfigure)).
- **Deduplication**: Finds duplicate files with hash and semantic checks (requires optional `[dedup]` extra; see [`deduplication.manage`](docs/developer/capability-matrix.md#deduplicationmanage)).
- **Undo/Redo**: Keeps operation history so you can undo changes safely (see [`history.manage`](docs/developer/capability-matrix.md#historymanage)).
- **Auto-Update**: Manages application updates safely across platforms (see [`updates.manage`](docs/developer/capability-matrix.md#updatesmanage)).
- **Cross-Platform**: Operates on macOS, Windows, and Linux (see [`cli` surface status](docs/developer/capability-matrix.md#summary-statistics)).

## 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.2.0 | **Last Updated**: 2026-07-20
