aichivist 0.1.0__tar.gz

aichivist-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Luft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aichivist-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: aichivist
+Version: 0.1.0
+Summary: Clean up your files like an archivist: AI agents rename, sort and de-duplicate documents with plans you approve and full undo
+License: MIT
+Project-URL: Homepage, https://github.com/luftphilipp/aichivist
+Project-URL: Changelog, https://github.com/luftphilipp/aichivist/blob/main/CHANGELOG.md
+Keywords: archive,records-management,file-organizer,bagit,fixity,claude-code,ai-agent
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4; extra == "pdf"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; python_version >= "3.10" and extra == "mcp"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="extension/icon.png" width="96" alt="">
+
+# aichivist
+
+### Clean up your files – like an archivist.
+
+**Your AI renames, sorts and de-duplicates your documents.<br>You approve every step, and everything can be undone.**
+
+[![tests](https://github.com/luftphilipp/aichivist/actions/workflows/tests.yml/badge.svg)](https://github.com/luftphilipp/aichivist/actions/workflows/tests.yml)
+![Windows · macOS · Linux](https://img.shields.io/badge/Windows%20%C2%B7%20macOS%20%C2%B7%20Linux-lightgrey)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+[Get started](#get-started) · [Why not just ask an AI?](#why-not-just-ask-an-ai) · [What it can do](#what-it-can-do)
+
+</div>
+
+## Why not just ask an AI?
+
+Tell ChatGPT or Claude *"tidy up my documents"* and you usually get a quick job: folders by file type
+(`PDFs`, `Images`, `Misc`), the same cryptic names, duplicates left where they were – and sometimes a game or program
+that no longer starts because its files were moved. It happens all at once, with no plan to check and no way back.
+Next time, the AI invents a different system.
+
+![Asking an AI alone vs. an AI with aichivist](docs/plain-ai-vs-aichivist.svg)
+
+aichivist gives your AI what a professional archivist works with: **your own filing rules**, a **plan you approve**,
+**names read from the document itself**, **duplicates found by content**, **programs that keep working**, and a
+**record of every step** that can be undone. Tried in real use on 25,000 photos and 1,500 documents.
+
+## How it works
+
+![The AI reads, proposes a plan, you approve, everything is filed](docs/how-it-works.svg)
+
+- **Nothing happens without your OK.** You see the plan first and can change or strike any line.
+- **Nothing gets lost.** Every step is recorded and can be undone; duplicates go to the trash only after you agree.
+- **Your files stay yours.** Normal folders, your own cloud, no account, no server.
+- **Speaks your language.** Messages in English or German; rule templates in English, German, French, Italian and
+  Spanish.
+
+## What it can do
+
+![Reads scans, names in your style, finds duplicates, programs keep working, seals finished folders, retention periods, backup check, private stays private](docs/features.svg)
+
+## Get started
+
+**Claude Desktop** – the easiest way, no technical knowledge needed
+1. Download the `.mcpb` file from the [latest release](https://github.com/luftphilipp/aichivist/releases/latest)
+   (no Claude Desktop yet? [claude.ai/download](https://claude.ai/download)).
+2. Double-click it and choose the folders Claude may organize.
+3. Ask Claude: *"Tidy up my Downloads."*
+
+<details>
+<summary>Other ways: Claude Code, Codex/Gemini CLI/Cursor, or without AI</summary>
+
+**Claude Code** – type `/plugin marketplace add luftphilipp/aichivist`, then `/plugin install aichivist@aichivist`,
+then say *"Set up aichivist."* The setup installs the command-line tool if it is missing (it asks first).
+
+**Codex, Gemini CLI, Cursor** – `pipx install aichivist` (or `uv tool install aichivist`), then copy
+[`templates/AGENTS.md`](templates/AGENTS.md) to where your agent reads instructions.
+
+**Downloaded the ZIP?** Unpack it and double-click **`Start (Mac).command`** or **`Start (Windows).bat`**
+(Linux: `start.sh`). A simple menu opens – look at your Downloads, check your backups, and see which AI app on your
+computer can tidy up. No installation needed, only Python 3 (a new Mac offers to install it by itself).
+The first time, your computer warns because the file comes from the internet:
+- **Mac:** click *Done*, open *System Settings → Privacy & Security*, scroll down and click *Open Anyway* next to
+  "Start (Mac).command", then confirm.
+- **Windows:** click *More info → Run anyway*.
+
+</details>
+
+**Just curious?** See what's going on in your folders – no AI, nothing is changed:
+
+```bash
+pipx install aichivist
+aichivist survey ~/Downloads
+```
+
+It shows how many files you have, duplicates that waste space, files with meaningless names, folders that slow down
+your cloud, program folders to leave alone, and whether your hard drive is healthy. `aichivist storage storage.md`
+checks whether your backups are safe and what your storage costs per year (it shows the table format on first run).
+`aichivist catalog-page <folder> --open` turns your catalogs into a searchable page, `aichivist photos` sorts photos
+by year, and `aichivist watch ~/Downloads --install` reminds you once 25 files have piled up.
+
+<details>
+<summary>See it in action (terminal demo)</summary>
+
+![aichivist demo](docs/demo.svg)
+
+</details>
+
+## Built on real archive practice
+
+Archives have organized documents reliably for centuries. aichivist brings their rules to your computer:
+
+| In an archive | In aichivist |
+|---|---|
+| A **filing plan** says where everything belongs | Your rules say which documents go where – the AI follows them |
+| **Nothing is thrown away** without a decision | Duplicates and old files are only removed after your OK |
+| Every document is **described in a catalog** | Each folder gets a list of what is in it, so you find things later |
+| **Finished collections are sealed** | A completed folder (e.g. last year's taxes) is locked, checked and searchable |
+| Records are **kept for a set time**, then archived or destroyed | Old records come up when their time is over – you choose |
+| **Copies are kept in separate places** | It checks the 3-2-1 rule: 3 copies, 2 kinds of storage, 1 away from home |
+
+## Privacy
+
+aichivist itself works only on your computer. The AI that reads your documents (e.g. Claude) receives the content of
+the documents it reads – so you decide which folders it may open, and can exclude private ones completely.
+
+## How this was built
+
+aichivist was designed by **Philipp Luft**, a trained archivist and information professional (Fachmann Information &
+Dokumentation) studying Business AI, who brought the archival principles and the requirements. The code was written
+with **[Claude Code](https://claude.com/claude-code)** – every commit lists Claude as co-author.
+
+## More
+
+- [Details](docs/DETAILS.md) – all commands, setup for other apps, safety model, comparison with other tools
+- [Concept](docs/CONCEPT.md) – the archival principles behind it
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · MIT [license](LICENSE)

aichivist-0.1.0/README.md

@@ -0,0 +1,121 @@
+<div align="center">
+
+<img src="extension/icon.png" width="96" alt="">
+
+# aichivist
+
+### Clean up your files – like an archivist.
+
+**Your AI renames, sorts and de-duplicates your documents.<br>You approve every step, and everything can be undone.**
+
+[![tests](https://github.com/luftphilipp/aichivist/actions/workflows/tests.yml/badge.svg)](https://github.com/luftphilipp/aichivist/actions/workflows/tests.yml)
+![Windows · macOS · Linux](https://img.shields.io/badge/Windows%20%C2%B7%20macOS%20%C2%B7%20Linux-lightgrey)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+[Get started](#get-started) · [Why not just ask an AI?](#why-not-just-ask-an-ai) · [What it can do](#what-it-can-do)
+
+</div>
+
+## Why not just ask an AI?
+
+Tell ChatGPT or Claude *"tidy up my documents"* and you usually get a quick job: folders by file type
+(`PDFs`, `Images`, `Misc`), the same cryptic names, duplicates left where they were – and sometimes a game or program
+that no longer starts because its files were moved. It happens all at once, with no plan to check and no way back.
+Next time, the AI invents a different system.
+
+![Asking an AI alone vs. an AI with aichivist](docs/plain-ai-vs-aichivist.svg)
+
+aichivist gives your AI what a professional archivist works with: **your own filing rules**, a **plan you approve**,
+**names read from the document itself**, **duplicates found by content**, **programs that keep working**, and a
+**record of every step** that can be undone. Tried in real use on 25,000 photos and 1,500 documents.
+
+## How it works
+
+![The AI reads, proposes a plan, you approve, everything is filed](docs/how-it-works.svg)
+
+- **Nothing happens without your OK.** You see the plan first and can change or strike any line.
+- **Nothing gets lost.** Every step is recorded and can be undone; duplicates go to the trash only after you agree.
+- **Your files stay yours.** Normal folders, your own cloud, no account, no server.
+- **Speaks your language.** Messages in English or German; rule templates in English, German, French, Italian and
+  Spanish.
+
+## What it can do
+
+![Reads scans, names in your style, finds duplicates, programs keep working, seals finished folders, retention periods, backup check, private stays private](docs/features.svg)
+
+## Get started
+
+**Claude Desktop** – the easiest way, no technical knowledge needed
+1. Download the `.mcpb` file from the [latest release](https://github.com/luftphilipp/aichivist/releases/latest)
+   (no Claude Desktop yet? [claude.ai/download](https://claude.ai/download)).
+2. Double-click it and choose the folders Claude may organize.
+3. Ask Claude: *"Tidy up my Downloads."*
+
+<details>
+<summary>Other ways: Claude Code, Codex/Gemini CLI/Cursor, or without AI</summary>
+
+**Claude Code** – type `/plugin marketplace add luftphilipp/aichivist`, then `/plugin install aichivist@aichivist`,
+then say *"Set up aichivist."* The setup installs the command-line tool if it is missing (it asks first).
+
+**Codex, Gemini CLI, Cursor** – `pipx install aichivist` (or `uv tool install aichivist`), then copy
+[`templates/AGENTS.md`](templates/AGENTS.md) to where your agent reads instructions.
+
+**Downloaded the ZIP?** Unpack it and double-click **`Start (Mac).command`** or **`Start (Windows).bat`**
+(Linux: `start.sh`). A simple menu opens – look at your Downloads, check your backups, and see which AI app on your
+computer can tidy up. No installation needed, only Python 3 (a new Mac offers to install it by itself).
+The first time, your computer warns because the file comes from the internet:
+- **Mac:** click *Done*, open *System Settings → Privacy & Security*, scroll down and click *Open Anyway* next to
+  "Start (Mac).command", then confirm.
+- **Windows:** click *More info → Run anyway*.
+
+</details>
+
+**Just curious?** See what's going on in your folders – no AI, nothing is changed:
+
+```bash
+pipx install aichivist
+aichivist survey ~/Downloads
+```
+
+It shows how many files you have, duplicates that waste space, files with meaningless names, folders that slow down
+your cloud, program folders to leave alone, and whether your hard drive is healthy. `aichivist storage storage.md`
+checks whether your backups are safe and what your storage costs per year (it shows the table format on first run).
+`aichivist catalog-page <folder> --open` turns your catalogs into a searchable page, `aichivist photos` sorts photos
+by year, and `aichivist watch ~/Downloads --install` reminds you once 25 files have piled up.
+
+<details>
+<summary>See it in action (terminal demo)</summary>
+
+![aichivist demo](docs/demo.svg)
+
+</details>
+
+## Built on real archive practice
+
+Archives have organized documents reliably for centuries. aichivist brings their rules to your computer:
+
+| In an archive | In aichivist |
+|---|---|
+| A **filing plan** says where everything belongs | Your rules say which documents go where – the AI follows them |
+| **Nothing is thrown away** without a decision | Duplicates and old files are only removed after your OK |
+| Every document is **described in a catalog** | Each folder gets a list of what is in it, so you find things later |
+| **Finished collections are sealed** | A completed folder (e.g. last year's taxes) is locked, checked and searchable |
+| Records are **kept for a set time**, then archived or destroyed | Old records come up when their time is over – you choose |
+| **Copies are kept in separate places** | It checks the 3-2-1 rule: 3 copies, 2 kinds of storage, 1 away from home |
+
+## Privacy
+
+aichivist itself works only on your computer. The AI that reads your documents (e.g. Claude) receives the content of
+the documents it reads – so you decide which folders it may open, and can exclude private ones completely.
+
+## How this was built
+
+aichivist was designed by **Philipp Luft**, a trained archivist and information professional (Fachmann Information &
+Dokumentation) studying Business AI, who brought the archival principles and the requirements. The code was written
+with **[Claude Code](https://claude.com/claude-code)** – every commit lists Claude as co-author.
+
+## More
+
+- [Details](docs/DETAILS.md) – all commands, setup for other apps, safety model, comparison with other tools
+- [Concept](docs/CONCEPT.md) – the archival principles behind it
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · MIT [license](LICENSE)

aichivist-0.1.0/aichivist/__init__.py

@@ -0,0 +1,3 @@
+"""aichivist – archival-grade file operations for AI filing agents."""
+
+__version__ = "0.1.0"

aichivist-0.1.0/aichivist/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

aichivist-0.1.0/aichivist/agent_tools.py

@@ -0,0 +1,184 @@
+"""Tools for agents without file access of their own (e.g. Claude Desktop via MCP).
+
+Every path must lie inside the folders the person shared when starting the server (--root). Paths are resolved
+first, so `..` and symlinks cannot escape. Moving files is only possible through filing plans.
+"""
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from . import (
+    apps,
+    catalog,
+    config,
+    describe,
+    duplicates,
+    fulltext,
+    inventory,
+    lifecycle,
+    photos,
+    plan,
+    retention,
+    review,
+    similar,
+    storage,
+    structure,
+    style,
+    survey,
+)
+from .config import full_path
+from .fileops import FilingError
+
+PLAN_NAME = re.compile(r"^[\w .-]{1,60}$")
+DEFAULT_MAX_CHARS = 20_000
+LIST_LIMIT = 300
+
+
+class Workspace:
+    def __init__(self, roots: List, rules=None, exclude: Optional[List] = None):
+        self.roots = [full_path(r).resolve() for r in roots]
+        self.rules = full_path(rules) if rules else None
+        self.exclude = [full_path(e).resolve() for e in exclude or []]
+
+    def excluded(self, path: Path) -> bool:
+        return any(path == e or e in path.parents for e in self.exclude)
+
+    def check(self, path) -> Path:
+        resolved = full_path(path).resolve()
+        if not any(resolved == r or r in resolved.parents for r in self.roots):
+            raise FilingError(f"{path} is outside the folders shared with aichivist")
+        if self.excluded(resolved):
+            raise FilingError(f"{path} is in an excluded folder; aichivist does not open it")
+        return resolved
+
+    def _plan_file(self, name: str) -> Path:
+        if not PLAN_NAME.match(name):
+            raise FilingError("plan names may contain letters, digits, spaces, dots, dashes and underscores")
+        folder = config.home_dir() / "plans"
+        folder.mkdir(parents=True, exist_ok=True)
+        return folder / f"{name}.md"
+
+    # ---- reading -------------------------------------------------------------
+    def get_rules(self) -> Dict[str, Any]:
+        if not self.rules or not self.rules.exists():
+            return {"rules": None, "note": "No rules file configured – ask the person where things belong before "
+                                           "proposing a plan, and suggest writing rules (templates/RULES.md)."}
+        return {"rules": self.rules.read_text(encoding="utf-8"), "path": str(self.rules)}
+
+    def survey(self, paths: List[str], stale_years: int = 3) -> Dict[str, Any]:
+        report = survey.run([self.check(p) for p in paths], stale_years=stale_years, exclude=self.exclude)
+        return survey.as_dict(report)
+
+    def list_folder(self, path: str) -> Dict[str, Any]:
+        folder = self.check(path)
+        entries = [{"name": p.name, "kind": "folder" if p.is_dir() else "file",
+                    "size": p.stat().st_size if p.is_file() else None}
+                   for p in sorted(folder.iterdir()) if not p.name.startswith(".") and not self.excluded(p.resolve())]
+        return {"path": str(folder), "entries": entries[:LIST_LIMIT], "truncated": len(entries) > LIST_LIMIT}
+
+    def read_document(self, path: str, max_chars: int = DEFAULT_MAX_CHARS) -> Dict[str, Any]:
+        file = self.check(path)
+        if not file.is_file():
+            raise FilingError(f"not a file: {path}")
+        text, method = fulltext.extract(file)
+        return {"path": str(file), "method": method, "text": text[:max_chars], "characters": len(text),
+                "truncated": len(text) > max_chars}
+
+    def inventory(self, path: str) -> Dict[str, Any]:
+        folder = self.check(path)
+        changes = inventory.diff(folder)
+        by_hand = inventory.manual_moves(folder, changes)
+
+        def visible(rel: str) -> bool:
+            return not self.excluded((folder / rel.rstrip("/")).resolve())
+        return {"entries": [e for e in changes.entries if visible(e)], "first_run": changes.first_run,
+                "new": [e for e in changes.new if visible(e)],
+                "moved": [{"from": o, "to": n, "by_hand": (o, n) in by_hand} for o, n in changes.moved
+                          if visible(o) and visible(n)]}
+
+    def find_duplicates(self, paths: List[str], area: str) -> List[Dict[str, str]]:
+        found = duplicates.find([self.check(p) for p in paths], self.check(area))
+        return [{"source": str(d.source), "match": str(d.match)} for d in found
+                if not self.excluded(d.source.resolve()) and not self.excluded(d.match.resolve())]
+
+    def find_similar(self, paths: List[str], area: Optional[str] = None, threshold: float = 0.8) -> List[Dict]:
+        hits = similar.find([self.check(p) for p in paths], self.check(area) if area else None, threshold)
+        return [h._asdict() for h in hits]
+
+    def suggest_name(self, path: str) -> Dict[str, Any]:
+        return describe.suggest(self.check(path))
+
+    def naming_examples(self, area: str) -> Dict[str, Any]:
+        return style.examples(self.check(area))
+
+    def structure_advice(self, area: str) -> Dict[str, Any]:
+        report = structure.analyse(self.check(area))
+        return {"findings": [f._asdict() for f in report.findings], "summary": structure.render(report)}
+
+    def retention_due(self, area: str, years: float) -> List[Dict[str, Any]]:
+        return [d._asdict() for d in retention.due(self.check(area), years)]
+
+    # ---- filing plans --------------------------------------------------------
+    def plan_add(self, source: str, target: str, reason: str, plan_name: str = "current") -> Dict[str, str]:
+        checked_target = target if target == plan.TRASH else str(self.check(target))
+        return plan.add(self._plan_file(plan_name), self.check(source), checked_target, reason)._asdict()
+
+    def plan_show(self, plan_name: str = "current") -> Dict[str, Any]:
+        file = self._plan_file(plan_name)
+        rows = [r._asdict() for r in plan.read(file)] if file.exists() else []
+        return {"plan": str(file), "rows": rows}
+
+    def plan_check(self, plan_name: str = "current", create_folders: bool = False) -> Dict[str, Any]:
+        results = plan.check(self._plan_file(plan_name), create_folders)
+        return {"problems": [{"row": i, "source": r.source, "problem": p}
+                             for i, (r, p) in enumerate(results, 1) if p]}
+
+    def plan_approve(self, plan_name: str = "current", rows: Optional[List[int]] = None,
+                     leave_link: bool = False) -> Dict[str, int]:
+        return {"approved": plan.approve(self._plan_file(plan_name), rows, leave_link)}
+
+    def storage_check(self, table_file: str) -> Dict[str, Any]:
+        table = self.check(table_file)
+        if not table.exists():
+            return {"error": "table missing", "example": storage.EXAMPLE}
+        return storage.as_dict(storage.check(table))
+
+    def program_check(self, paths: List[str]) -> Dict[str, List[str]]:
+        ctx = apps.context()
+        return {p: apps.risks(self.check(p), ctx) for p in paths}
+
+    def plan_review(self, plan_name: str = "current") -> Dict[str, str]:
+        url = review.serve(self._plan_file(plan_name), open_browser=True, block=False)
+        return {"url": url, "note": "The person reviews the plan in the browser and approves rows there."}
+
+    def plan_apply(self, plan_name: str = "current", create_folders: bool = False) -> Dict[str, object]:
+        file = self._plan_file(plan_name)
+        for row in plan.read(file):  # a plan file could have been edited – re-check every approved row
+            if row.mark in ("x", "link"):
+                self.check(row.source)
+                if row.target != plan.TRASH:
+                    self.check(row.target)
+        return plan.apply(file, create_folders)._asdict()
+
+    def plan_photos(self, inbox: str, photos_root: str, plan_name: str = "current") -> Dict[str, Any]:
+        rows = photos.propose(self.check(inbox), self.check(photos_root), self._plan_file(plan_name))
+        return {"proposed": len(rows), "rows": [r._asdict() for r in rows]}
+
+    # ---- catalogs and collections ---------------------------------------------
+    def catalog_check(self, catalog_file: str, add_missing: bool = False, prefill: bool = True) -> Dict[str, Any]:
+        file = self.check(catalog_file)
+        added = catalog.add_missing(file, prefill=prefill) if add_missing else []
+        return {"added": added, **catalog.check(file)._asdict()}
+
+    def catalog_describe(self, catalog_file: str, file: str, content: str, search_terms: str,
+                         date: str) -> Dict[str, str]:
+        return {"row": catalog.describe(self.check(catalog_file), file, content, search_terms, date)}
+
+    def status(self, path: str) -> Dict[str, Any]:
+        return {k: str(v) if v is not None else None for k, v in lifecycle.status(self.check(path))._asdict().items()}
+
+    def verify(self, path: str) -> Dict[str, List[str]]:
+        return lifecycle.verify(self.check(path))
+
+    def search(self, path: str, query: str) -> List[Dict[str, Any]]:
+        return [h._asdict() for h in fulltext.search(self.check(path), query)]