Metadata-Version: 2.4
Name: fo-core
Version: 2.0.0b5
Summary: Streamlined CLI file organizer powered by local AI (Ollama)
Author-email: fo-core Team <noreply@example.com>
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/curdriceaurora/fo-core
Project-URL: Repository, https://github.com/curdriceaurora/fo-core
Project-URL: Issues, https://github.com/curdriceaurora/fo-core/issues
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: 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.2
Requires-Dist: PyMuPDF~=1.23
Requires-Dist: python-docx~=1.0
Requires-Dist: openpyxl~=3.1
Requires-Dist: python-pptx<2,>=0.6.0
Requires-Dist: ebooklib<1,>=0.20
Requires-Dist: beautifulsoup4~=4.12
Requires-Dist: lxml~=6.1
Requires-Dist: defusedxml<1,>=0.7.1
Requires-Dist: mutagen~=1.47
Requires-Dist: snowballstemmer>=2.2.0
Requires-Dist: striprtf<1,>=0.0.26
Requires-Dist: tinytag~=2.2
Requires-Dist: py7zr<2,>=0.20.0
Requires-Dist: pypdf~=6.10
Requires-Dist: rarfile~=4.1
Requires-Dist: typer[all]~=0.12
Requires-Dist: rich~=13.0
Requires-Dist: Pygments>=2.20.0
Requires-Dist: sqlalchemy~=2.0
Requires-Dist: alembic~=1.13
Requires-Dist: Mako>=1.3.11
Requires-Dist: pyyaml~=6.0
Requires-Dist: platformdirs~=4.9
Requires-Dist: pydantic~=2.5
Requires-Dist: pydantic-settings~=2.1
Requires-Dist: python-dotenv~=1.0
Requires-Dist: click~=8.1
Requires-Dist: watchdog~=3.0
Requires-Dist: psutil<7,>=6.1
Requires-Dist: loguru<1,>=0.7.0
Requires-Dist: httpx~=0.27
Provides-Extra: dev
Requires-Dist: pytest~=9.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Requires-Dist: pytest-cov~=4.1; extra == "dev"
Requires-Dist: pytest-mock~=3.12; extra == "dev"
Requires-Dist: pytest-timeout<2.4.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.2,~=1.8; extra == "dev"
Requires-Dist: types-PyYAML~=6.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black~=26.3; extra == "dev"
Requires-Dist: isort~=8.0; 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~=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"
Provides-Extra: cloud
Requires-Dist: openai~=2.31; extra == "cloud"
Provides-Extra: llama
Requires-Dist: llama-cpp-python>=0.2.0; extra == "llama"
Provides-Extra: mlx
Requires-Dist: mlx-lm<1,>=0.0.19; platform_system == "Darwin" and extra == "mlx"
Provides-Extra: claude
Requires-Dist: anthropic>=0.20.0; extra == "claude"
Provides-Extra: media
Requires-Dist: faster-whisper~=1.0; extra == "media"
Requires-Dist: torch~=2.1; extra == "media"
Requires-Dist: pydub<1,>=0.25.0; extra == "media"
Requires-Dist: opencv-python~=4.8; extra == "media"
Requires-Dist: scenedetect[opencv]<1,>=0.6.0; extra == "media"
Provides-Extra: dedup-text
Requires-Dist: numpy<3,>=1.24; extra == "dedup-text"
Requires-Dist: scikit-learn<1.9,>=1.4; extra == "dedup-text"
Provides-Extra: dedup-image
Requires-Dist: fo-core[dedup-text]; extra == "dedup-image"
Requires-Dist: imagededup<1,>=0.3.0; extra == "dedup-image"
Requires-Dist: torch~=2.1; extra == "dedup-image"
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~=10.21; 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: numpy<3,>=1.24; extra == "search"
Requires-Dist: rank-bm25>=0.2.0; extra == "search"
Requires-Dist: scikit-learn<1.9,>=1.4; extra == "search"
Provides-Extra: all
Requires-Dist: fo-core[build,cad,claude,cloud,dedup-image,dedup-text,dev,llama,media,mlx,scientific,search]; extra == "all"
Dynamic: license-file

# fo-core

> Local AI file organizer. Point it at a directory — it categorizes and moves your files using a model running on your own machine. **Local by default**: Ollama runs on-device, no API key required. Cloud providers are optional extras.

[![CI](https://github.com/curdriceaurora/fo-core/actions/workflows/ci.yml/badge.svg)](https://github.com/curdriceaurora/fo-core/actions/workflows/ci.yml)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-2.0.0--beta.1-blue)](CHANGELOG.md)

---

## Prerequisites

1. **Python 3.11 or later** — check with `python3 --version`
2. **Ollama** — install from [ollama.ai](https://ollama.ai), then start it:

   ```bash
   ollama serve
   ```

---

## Install

```bash
pip install fo-core
```

Then pull the default AI models (first-time only, ~4 GB total):

```bash
ollama pull qwen2.5:3b-instruct-q4_K_M
ollama pull qwen2.5vl:7b-q4_K_M
```

Verify optional deps for your files:

```bash
fo doctor ~/Downloads
```

---

## Quick Start

```bash
# Preview what would happen — no files are moved
fo organize ~/Downloads ~/Organized --dry-run

# Run it for real
fo organize ~/Downloads ~/Organized

# Changed your mind?
fo undo
```

---

## Commands

| Command | What it does |
|---------|--------------|
| `fo organize [SRC] [DEST]` | Organize files using AI categorization |
| `fo preview [SRC]` | Dry-run preview without moving files |
| `fo search [QUERY]` | Full-text search across files |
| `fo analyze [DIR]` | File statistics and analysis |
| `fo dedupe` | Find and remove duplicate files |
| `fo suggest` | AI-powered organization suggestions |
| `fo autotag` | Auto-tag files based on content |
| `fo copilot` | Natural-language assistant |
| `fo rules` | Manage organization rules (YAML) |
| `fo config show\|list\|edit` | View or update configuration |
| `fo doctor [DIR]` | Scan a directory and recommend optional deps |
| `fo daemon start\|stop` | Background file watcher |
| `fo undo / redo / history` | Operation history and rollback |
| `fo model` | Select or inspect AI models |
| `fo benchmark` | Performance benchmarks |
| `fo setup` | Interactive setup wizard |

Full flag documentation: [docs/cli-reference.md](docs/cli-reference.md)

---

## AI Providers

**Default**: Ollama — runs entirely on your machine, no API key needed.

Cloud providers are optional extras:

| Provider | Install | Works with |
|----------|---------|------------|
| OpenAI-compatible | `pip install "fo-core[cloud]"` | OpenAI, LM Studio, vLLM, Groq |
| Anthropic Claude | `pip install "fo-core[claude]"` | Claude text + vision models |
| llama.cpp | `pip install "fo-core[llama]"` | GGUF models — no Ollama required |
| MLX (Apple Silicon) | `pip install "fo-core[mlx]"` | MLX-optimized local models |

---

## Optional Feature Packs

Core file types (PDF, DOCX, XLSX, PPTX, EPUB, ZIP) work out of the box. RAR also works but requires a system-level `unrar` or `unar` binary. Install extras for additional capabilities:

| Pack | Install | Adds |
|------|---------|------|
| `media` | `pip install "fo-core[media]"` | Audio transcription (faster-whisper) + video scene detection. Use `fo organize --transcribe-audio` for content-aware audio categorization, or verify the install with `fo benchmark run --suite audio --transcribe-smoke`. |
| `dedup-text` | `pip install "fo-core[dedup-text]"` | TF-IDF/cosine text deduplication |
| `dedup-image` | `pip install "fo-core[dedup-image]"` | Image similarity deduplication |
| `scientific` | `pip install "fo-core[scientific]"` | HDF5, NetCDF, MATLAB formats |
| `cad` | `pip install "fo-core[cad]"` | DXF/DWG CAD files |
| `search` | `pip install "fo-core[search]"` | BM25 + vector search |
| `all` | `pip install "fo-core[all]"` | All of the above |

---

## Configuration

Config lives in `~/.config/fo/config.yaml`. Override the location with the `FO_CONFIG` environment variable.

```bash
fo config show                                           # view all settings
fo config edit --text-model qwen2.5:3b-instruct-q4_K_M  # change text model
fo config edit --device auto                             # change device
```

Full configuration reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md)

---

## Documentation

| Doc | Contents |
|-----|----------|
| [Getting Started](docs/getting-started.md) | Installation options, first run, platform notes |
| [CLI Reference](docs/cli-reference.md) | Every command and flag |
| [Configuration](docs/CONFIGURATION.md) | All config keys explained |
| [FAQ](docs/faq.md) | Common questions and troubleshooting |
| [Troubleshooting](docs/troubleshooting.md) | Diagnosing connection and model issues |

---

## Contributing / Development

See [DEVELOPER.md](DEVELOPER.md) for architecture, local setup, testing, and contribution guidelines.

---

## Releases

Currently `2.0.0-beta.1`. The acceptance criteria that were required for this
promotion and the contract with public pre-release testers are documented in
[docs/release/beta-criteria.md](docs/release/beta-criteria.md).

## License

MIT OR Apache-2.0
