Metadata-Version: 2.4
Name: tidydisk
Version: 0.1.0
Summary: Safety-first media/personal-data consolidation engine with an agent layer designed for local models
Author: Surakshith Sampath
License-Expression: AGPL-3.0-or-later
Project-URL: Repository, https://github.com/msampath/tidydisk
Project-URL: Issues, https://github.com/msampath/tidydisk/issues
Project-URL: Changelog, https://github.com/msampath/tidydisk/blob/master/CHANGELOG.md
Keywords: media-library,deduplication,file-organization,agent,llm,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: ruff<0.16,>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Provides-Extra: enrich
Requires-Dist: mutagen>=1.47; extra == "enrich"
Requires-Dist: Pillow>=10; extra == "enrich"
Requires-Dist: thefuzz>=0.22; extra == "enrich"
Dynamic: license-file

# tidydisk: consolidate and organize a hoard of scattered files

[![ci](https://github.com/msampath/tidydisk/actions/workflows/ci.yml/badge.svg)](https://github.com/msampath/tidydisk/actions/workflows/ci.yml)
[![license: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
[![python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)

Pull years of scattered files (old drives, phone backups, NAS dumps, recovery-tool
output) into one organized, deduplicated library. Media lands in a Jellyfin/Plex-ready
layout; an agent layer sorts whatever your rules can't, using a local model so filenames
never leave your machine.

`tidydisk` fingerprints everything you point it at, drops exact duplicates and junk, and
files what's left where it belongs. It moves and stages files, never deletes them.

> Status: v0.1.0 (on PyPI: `pip install tidydisk`). The engine, the agent layer, content-derived
> organization, in-place library repair, the guided 2-pass web UI, opt-in enrichment
> connectors, and undo/dispose/doctor are all in. See [docs/roadmap.md](docs/roadmap.md)
> for what's deferred.

## Quickstart

The 2-pass cleanup (the front door): Pass 1 analyzes everything read-only into one
sealed proposal; Pass 2 is a single review-and-execute in a localhost web UI.

```mermaid
flowchart LR
    A[tidydisk pilot] -->|analyzes, read-only| B[sealed proposal.json]
    B --> C[tidydisk serve]
    C -->|review clusters, approve/reject| D{Execute}
    D -->|typed confirmation| E[library on disk]
```

```console
$ tidydisk pilot                       # Pass 1: analyze everything -> proposal.json
$ tidydisk serve                       # Pass 2: review clusters -> approve -> Execute
```

Headless Pass 2: `tidydisk pilot --execute --proposal <proposal.json> --approve-all`.

Install from PyPI (zero runtime deps: stdlib only):

```console
$ pip install tidydisk
```

Or the granular CLI:

```console
$ tidydisk init                        # writes an annotated tidydisk.toml
$ tidydisk check                       # validates config + root reachability
$ tidydisk scan library                # fingerprint your library into the index
$ tidydisk scan old-drive              # fingerprint a source
$ tidydisk verdicts old-drive          # ORGANIZED / JUNK / UNIQUE / REVIEW
$ tidydisk plan organize old-drive     # uniques -> library
$ tidydisk apply ".tidydisk/plans/plan-organize-old-drive-ab12cd34.jsonl" --execute
$ tidydisk plan dedup old-drive        # duplicates + junk -> staging (same-drive, reversible)
$ tidydisk apply ".tidydisk/plans/plan-dedup-old-drive-9f00aa11.jsonl" --execute
$ tidydisk verify library
$ tidydisk plan reorganize --under Video/old-drive --exif   # repair flat dumps in place
```

Agent layer (local model via Ollama, or any OpenAI-compatible endpoint):

```console
$ tidydisk agent triage old-drive     # LLM recommends dispositions for the REVIEW pile
$ tidydisk agent classify old-drive   # labels the tail your rules didn't cover
$ tidydisk agent eval                 # measures the configured chain on the golden sets
```

A fully-annotated example config is browsable at
[examples/tidydisk.toml](examples/tidydisk.toml).

One small kernel owns every filesystem mutation and there is no delete API anywhere in
the codebase (AST-enforced in CI): staging is reversible, and disposal only ever
happens through `tidydisk dispose`, gated behind a typed confirmation.

See [docs/formats.md](docs/formats.md) for the plan/summary JSON schemas and exit codes.

## License

AGPL-3.0-or-later. See [LICENSE](LICENSE).
