fo-core 2.0.0b4

Streamlined CLI file organizer powered by local AI (Ollama)

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.

---

Prerequisites

1. Python 3.11 or later — check with python3 --version

2. Ollama — install from ollama.ai, then start it:

   ollama serve
   

---

Install

pip install fo-core

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

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

Verify optional deps for your files:

fo doctor ~/Downloads

---

Quick Start

# 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

---

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.

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

---

Documentation

Doc	Contents
Getting Started	Installation options, first run, platform notes
CLI Reference	Every command and flag
Configuration	All config keys explained
FAQ	Common questions and troubleshooting
Troubleshooting	Diagnosing connection and model issues

---

Contributing / Development

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

License

MIT OR Apache-2.0