Metadata-Version: 2.4
Name: local-file-organizer
Version: 2.0.2
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: 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.0.0-blue?style=flat-square)](CHANGELOG.md)
[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)

AI-powered local file management. Local-first by default (Ollama, no cloud required)—or connect any OpenAI-compatible endpoint or Anthropic Claude when you need it.

![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**: Qwen 2.5 3B (text) + Qwen 2.5-VL 7B (vision) via Ollama — or any OpenAI-compatible endpoint (OpenAI, LM Studio, vLLM) — or Anthropic Claude
- **Audio Transcription**: Local speech-to-text with faster-whisper (GPU-accelerated)
- **Video Analysis**: Scene detection and keyframe extraction
- **Intelligence**: Pattern learning, preference tracking, smart suggestions, auto-tagging

### Interfaces

- **Terminal UI**: 8-view Textual TUI (Files, Analytics, Audio, History, Copilot, and more)
- **Web UI**: Browser-based interface via FastAPI and HTMX
- **Desktop App**: Native OS window via pywebview — single Python process, no Electron, no Rust
- **Full CLI**: Organize, rules, suggest, dedupe, daemon, analytics, update, api-keys
- **Copilot Chat**: Natural-language assistant -- "organize ./Downloads", "find report.pdf", "undo"

### Organization

- **Extensive Support**: Handles 840 tests, 408 modules, and 39 distinct file types natively
- **Organization Rules**: Automated sorting with conditions, preview, and YAML persistence
- **PARA + Johnny Decimal**: Built-in organizational methodologies
- **Deduplication**: Hash and semantic duplicate detection
- **Undo/Redo**: Full operation history
- **Auto-Update**: Linux AppImage self-updates from GitHub Releases (verified downloads + rollback); macOS/Windows update via `pip`/`pipx`
- **Cross-Platform**: Runs on macOS, Windows, and Linux (verified in CI). Linux ships a standalone AppImage plus executables; install on macOS/Windows via `pip`/`pipx`

## 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** — Reads files from a source directory, extracting text, metadata, and visual content per file type (80+ formats supported)
2. **Analyze** — Sends extracted content to an AI model (Ollama, OpenAI, or Claude) for categorization and naming
3. **Organize** — Moves or copies files into a structured folder hierarchy with AI-generated names
4. **Learn** — Tracks your patterns and preferences over time for smarter future suggestions

## Interfaces (Visuals)

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

### Web UI (Preview)
Start the FastAPI server and open the UI:

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

Then visit `http://localhost:8000/ui/` for the HTMX interface.

## Quick Start (Essentials)

### With Ollama (local, default)

```bash
# Install from PyPI — pipx keeps it isolated and on your PATH:
pipx install local-file-organizer
# or: pip install local-file-organizer

# 1) Configure defaults
fo setup

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

# 3) Run organization
fo organize ~/Downloads ~/Organized

# 4) Roll back the most recent organize run if needed
fo undo
```

### Need cloud providers instead of the default local flow?

Use 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 dependencies and audio setup)

### 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 installs:

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

> **From source (development):** clone the repo and use an editable install
> instead, e.g. `pip install -e ".[all]"`.

### Audio system dependencies

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

**FFmpeg** — required for non-`.wav` formats (MP3, M4A, FLAC, OGG); optional if you only transcribe raw `.wav`:

```bash
# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (winget)
winget install ffmpeg
```

**CUDA + cuDNN** — optional, for significantly faster transcription (see [faster-whisper benchmarks](https://github.com/SYSTRAN/faster-whisper) for hardware-specific numbers):

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

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

**Fallback behavior**: without FFmpeg, only `.wav` files are transcribed; other formats are organized by filename/metadata but not content-analyzed. Without CUDA, transcription runs on CPU (slower but fully functional).

See the [Installation Guide](docs/admin/installation.md) for troubleshooting and advanced configuration.

## Development

```bash
# Run tests
pytest

# Lint
ruff check src/
```

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, project structure, and how to submit changes.

## Configuration

Configuration is stored in platform-appropriate locations using `platformdirs`:
- **macOS**: `~/Library/Application Support/file-organizer/`
- **Linux**: `~/.config/file-organizer/` (or `$XDG_CONFIG_HOME/file-organizer/`)
- **Windows**: `%APPDATA%/file-organizer/`

See [Configuration Guide](docs/CONFIGURATION.md) for details.

## License

This project is licensed under the [MIT License](LICENSE).

---

**Status**: Stable | **Version**: 2.0.0 | **Last Updated**: 2026-07-05
