Metadata-Version: 2.4
Name: local-file-organizer
Version: 2.0.0b1
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 :: 4 - Beta
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~=13.0
Requires-Dist: textual~=0.50
Requires-Dist: fastapi~=0.109
Requires-Dist: starlette~=1.3
Requires-Dist: aiofiles~=23.0
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.0.3; 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~=3.15; extra == "dev"
Requires-Dist: mypy<1.20,>=1.8; 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~=5.13; extra == "dev"
Requires-Dist: pre-commit~=3.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~=7.0; 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~=4.8; 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

# File Organizer v2.0

[![CI](https://github.com/curdriceaurora/Local-File-Organizer/actions/workflows/ci.yml/badge.svg)](https://github.com/curdriceaurora/Local-File-Organizer/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-user%20guide-blue)](docs/USER_GUIDE.md)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.0.0--beta.1-orange)](CHANGELOG.md)

> 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.

**840 tests** | **408 modules** | **39 file types**

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

## Contents

- [Features](#features)
- [How It Works](#how-it-works)
- [Quick Start](#quick-start)
- [Web UI](#web-ui)
- [Documentation](#documentation)
- [Optional Feature Packs](#optional-feature-packs)
- [Project Structure](#project-structure)
- [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

- **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**: GitHub Releases checks with verified downloads and rollback
- **Cross-Platform**: macOS (DMG), Windows (installer), Linux (AppImage) executables

## How It Works

```
 Source Directory          AI Analysis              Organized Output
┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  ./Downloads │     │  Content         │     │  ./Organized     │
│              │     │  Extraction      │     │                  │
│  report.pdf  │────>│  (text, vision,  │────>│  Work/           │
│  photo.jpg   │     │   audio, video)  │     │    Reports/      │
│  meeting.mp3 │     │                  │     │  Photos/         │
│  clip.mp4    │     │  AI Categorize   │     │    Vacation/     │
│  notes.txt   │     │  (Ollama/OpenAI/ │     │  Audio/          │
│              │     │   Claude)        │     │    Meetings/     │
└──────────────┘     └──────────────────┘     └──────────────────┘
                              │
                     ┌────────┴────────┐
                     │  Learn & Adapt  │
                     │  (patterns,     │
                     │   preferences,  │
                     │   rules)        │
                     └─────────────────┘
```

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

## Screenshots

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

## Quick Start (Essentials)

### With Ollama (local, default)

```bash
pip install -e .

# 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
```

### Prefer a browser?

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

Then visit `http://localhost:8000/ui/`.

### 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
```

## Web UI

Start the FastAPI server and open the UI:

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

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

## 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)

### 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 -e ".[parsers,web]"
pip install -e ".[cloud,claude]"
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.

## Project Structure

<details>
<summary>Click to expand</summary>

```
src/file_organizer/
├── api/              # FastAPI web backend
├── cli/              # CLI commands and entry points
├── client/           # HTTP client utilities
├── config/           # Configuration management
├── core/             # Organization engine and business logic
├── daemon/           # Background file watcher daemon
├── deploy/           # Deployment helpers
├── desktop/          # Native desktop app (pywebview)
├── events/           # Event system
├── history/          # Operation history and undo/redo
├── integrations/     # External service integrations
├── interfaces/       # Abstract interfaces and protocols
├── methodologies/    # PARA, Johnny Decimal implementations
├── models/           # Data models
├── optimization/     # Performance optimization
├── parallel/         # Parallel processing
├── pipeline/         # File processing pipeline
├── plugins/          # Plugin system (audio, video, archives, etc.)
├── review_regressions/ # Code quality detectors
├── services/         # Core services (analytics, dedup, text, etc.)
├── tui/              # Textual terminal UI (8 views)
├── undo/             # Undo/redo infrastructure
├── updater/          # Auto-update from GitHub Releases
├── utils/            # Shared utilities
├── watcher/          # File system watcher
└── web/              # HTMX web UI templates and assets
```

</details>

## Development

```bash
# Run tests
pytest

# Lint
ruff check src/
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, 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**: Beta 1 | **Version**: 2.0.0-beta.1 | **Last Updated**: 2026-07-04
