liametahi 0.1.0__tar.gz

liametahi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_call:
+
+jobs:
+  gate:
+    # implementation-contracts.md §8: definition of done for every unit.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install Python (per pyproject requires-python)
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: ruff format --check
+        run: uv run ruff format --check .
+
+      - name: ruff check
+        run: uv run ruff check .
+
+      - name: mypy --strict (src)
+        run: uv run mypy --strict src/liametahi
+
+      - name: mypy --strict (tests)
+        run: uv run mypy --strict tests
+
+      - name: pytest (unit tier; integration skipped without Docker, live never runs)
+        run: uv run pytest -q

liametahi-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  gate:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: gate
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv build
+
+      - name: Smoke-test the built wheel
+        run: |
+          uv venv /tmp/liametahi-smoke
+          uv pip install --python /tmp/liametahi-smoke/bin/python dist/*.whl
+          /tmp/liametahi-smoke/bin/liametahi --help
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing automatic

liametahi-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Configuration holds literal mailbox and model credentials (spec §12) — never commit it.
+liametahi.yaml
+liametahi.yml
+*.local.yaml
+config.yaml
+
+# Local state and backups
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+backups/
+
+# Real mail is never a test dependency and is never committed (contracts
+# §6.2). Only the hand-written synthetic corpus is; captured corpora
+# under any other tests/corpus/<name>/ are git-ignored.
+*.eml
+tests/corpus/*/
+!tests/corpus/synthetic/
+!tests/corpus/synthetic/**
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+data/

liametahi-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

liametahi-0.1.0/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+Instructions for any agent (or human) working in this repository. Liametahi
+is a local, cron-friendly Python CLI that cleans up an IMAP mailbox, using a
+model only as a constrained classifier — never as the thing that decides or
+acts. If anything here conflicts with the documents it points to, those
+documents win; this file is a map and a set of reminders, not a new source of
+truth.
+
+## Where things live
+
+| Path | What it is | Authoritative for |
+| --- | --- | --- |
+| `README.md` | User-facing install/quickstart/CLI usage | End-user behavior and docs |
+| `docs/configuration.md` | Full `config.yaml` key reference: accounts, models, processors, tasks, rule conditions | Config file shape and defaults |
+| `docs/internals.md` | Expanded reasoning behind each safety-model bullet | Why the safety properties exist |
+| `docs/development.md` | Checks to run, test tiers, live-mailbox testing workflow | Dev workflow |
+| `dev-notes/specification.md` | Full product/behavior spec, numbered acceptance criteria (§14), resolved decisions (§15) | **What** the tool does and why — read this first for any behavior question |
+| `dev-notes/implementation-contracts.md` | Toolchain, SQLite DDL, module signatures, work-unit boundaries, test-gate commands | **Shape** of the implementation — read this first for any "how is this wired together" question |
+| `dev-notes/jev-provider-plan.md` | The `processors`/Jev redesign brief (chat + Jev classification unified, `task:<id>` routing) | Authoritative for that redesign's shape until folded fully into `specification.md` (in progress — §2/§3/§11/§13–§15 of the spec still describe the pre-redesign `llm:`/rule-id model) |
+| `dev-notes/jev-provider-design-history.md` | Alternatives considered and rejected during that redesign, with reasons | Background only — nothing here is current design |
+| `dev-notes/*.md` (others) | Historical/working notes | Background only |
+| `dev-notes/archive/*.md` | Fully superseded docs kept for history only (e.g. `mailbox-cleanup-cli.md`, superseded by `specification.md`) | Not current — do not read for behavior/shape questions |
+| `src/liametahi/` | The package (see module map below) | — |
+| `tests/` | Unit tests (default), integration tests (`-m integration`, needs Docker/Dovecot), live tests (`-m live`, opt-in, real mailbox, never in CI) | — |
+| `tools/` | `capture_corpus.py` (pull a real mailbox into a local synthetic corpus, read-only) and `dev_imap.py` (disposable local Dovecot for integration/live testing) | — |
+| `config.example.yaml` | Template a user copies to `~/.config/liametahi/config.yaml` or `./config.yaml` | Quickstart |
+
+When `dev-notes/specification.md` and `dev-notes/implementation-contracts.md`
+disagree: the specification wins on behavior, the contracts document wins on
+shape (stated explicitly at the top of the contracts file).
+
+## Module map (`src/liametahi/`)
+
+- `cli.py` — Typer CLI: argument parsing, config path resolution, exit codes,
+  printing. Delegates every decision of substance elsewhere.
+- `config.py` — Pydantic v2 models, YAML load-time validation, config file
+  ownership/permission checks, condition-tree (`when:`) grammar parsing.
+- `rules.py` / `policy.py` — condition tree types (including `processor:`
+  atoms and the `all`/`any`/`none`/`not` composition keywords) and
+  rule-matching ("winner takes all" by plain list order — rules have no id
+  or priority field; the first matching rule wins) semantics.
+- `imap_adapter.py` — IMAP protocol wrapper (fetch, claim, mutate).
+- `classifier/` — `anthropic.py`, `openai_compatible.py`, and `jev.py`
+  adapters behind a shared interface in `__init__.py`. A model only ever
+  answers a named **processor**'s declared question (`noul`/`choice`/
+  `score`) against its own closed vocabulary of options/levels — never
+  free-form, never widening what a rule may act on. See
+  `dev-notes/jev-provider-plan.md` for the full design.
+- `evaluate.py` / `execute.py` — the two run phases: evaluate (classify,
+  decide, cache) and execute (backup, mutate).
+- `runner.py` — orchestrates a full task run across both phases, locking,
+  and crash recovery.
+- `backup.py` — content-addressed `.eml` backup + restore.
+- `state.py` — SQLite schema/access (see contracts doc for DDL).
+- `locks.py` — per-task advisory locks (`--wait`, exit `5` on contention).
+- `report.py` — renders a stored run without touching the mailbox or model.
+- `progress.py`, `logging.py`, `prompt.py`, `domain.py` — progress UI,
+  redacting logger, LLM prompt construction, and core domain types.
+
+## Conventions (binding, not stylistic preference)
+
+- **`uv` for everything** — `uv add`, `uv run`, `uv sync`. Never `pip`.
+- **Full type annotations**; `mypy --strict` covers `src/liametahi` *and*
+  `tests` (test doubles implement the same protocols as real adapters, so a
+  drifted signature is caught there).
+- Full gate before calling anything done (`docs/development.md`):
+  ```sh
+  uv run ruff format --check .
+  uv run ruff check .
+  uv run mypy --strict src/liametahi tests
+  uv run pytest
+  ```
+- **Never commit real credentials, real email content, or a captured
+  corpus.** `config.yaml`, `liametahi.yaml`/`.yml`, `*.local.yaml`, `*.eml`,
+  and captured `tests/corpus/*/` (other than the hand-written
+  `tests/corpus/synthetic/`) are gitignored on purpose — don't work around it.
+- The config file is a secret (spec §12): wrong ownership is a hard failure
+  (exit 2); group/world-readable mode bits print a warning but still load.
+- Safety properties from the spec (`BODY.PEEK` everywhere, one remote
+  mutation per message, claim-before-mutate, protected senders/flags
+  re-checked immediately before mutation, verify-then-act, and `trash`
+  always requiring at least one deterministic — non-`processor:` —
+  condition) are non-negotiable — implement them exactly even where a
+  simpler shape would pass the tests. (Backup-before-trash is *not* in this
+  list: it's deliberately no longer required, per
+  `dev-notes/jev-provider-plan.md` §8 — `backup` is still available and
+  freely composable, just optional.) A model's output is untrusted,
+  attacker-influenced input: validate every processor answer against its
+  own declared options/levels, never let it widen what an action may do.
+
+## Specialized agents in this repo
+
+- `liametahi-impl` (`.claude/agents/liametahi-impl.md`) implements a work
+  unit against the spec and contracts docs.
+- `liametahi-verify` (`.claude/agents/liametahi-verify.md`) is a read-only
+  auditor that checks implemented code against those same docs.
+
+Both were written before `dev-notes/` was renamed from `notes/`; their
+"read these first" paths have been corrected to `dev-notes/specification.md`
+and `dev-notes/implementation-contracts.md`. If you add a new agent for this
+repo, point it at the `dev-notes/` paths directly.

liametahi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 4piu
+
+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.

liametahi-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: liametahi
+Version: 0.1.0
+Summary: A local, cron-friendly IMAP mailbox cleanup CLI using an LLM as a constrained classifier.
+Project-URL: Homepage, https://github.com/4piu/liametahi
+Project-URL: Repository, https://github.com/4piu/liametahi
+Project-URL: Issues, https://github.com/4piu/liametahi/issues
+Author: 4piu
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Requires-Dist: anthropic>=0.120.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: platformdirs>=4.11.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: typer>=0.27.0
+Description-Content-Type: text/markdown
+
+# Liametahi
+
+An AI-powered mailbox cleanup tool for IMAP. Point it at an inbox and it
+can:
+
+- Trash, move, label, or route mail using both plain conditions (sender,
+  age, size, headers) and an AI's answer to a question you write ("is this
+  spam?", "how urgent is this?")
+- Preview any run with `--dry-run`, back up before deleting, and restore
+  anytime
+- Run unattended on a schedule — locking, crash recovery, and a report of
+  every past run
+- Mix a fast/cheap model with a slower one, only escalating the mail the
+  first pass is unsure about
+
+```yaml
+processors:
+  vibe-check:
+    model: local
+    type: noul
+    instructions: A newsletter or digest with nothing time-sensitive left in it.
+
+tasks:
+  inbox-cleanup:
+    account: personal
+    source_mailboxes: [INBOX]
+    rules:
+      - when:
+          - older-than: 30d
+          - processor: "vibe-check.value >= 0.9"
+        actions: [backup, trash]
+```
+
+## Install
+
+Needs Python ≥ 3.14, [`uv`](https://docs.astral.sh/uv/), an IMAP account, and
+a model endpoint — an OpenAI-compatible chat API, Anthropic, or a
+Jev-compatible API.
+
+```sh
+uv tool install liametahi
+liametahi --help
+```
+
+Running from a source checkout instead? See
+[docs/development.md](docs/development.md).
+
+## Usage
+
+```
+liametahi config check [--connect]
+liametahi run TASK [--dry-run] [--fail-fast] [--reevaluate] [--wait SECONDS] [--format table|json] [--verbose]
+liametahi report [RUN_ID] [--list] [--task TASK] [--format table|json] [--verbose]
+liametahi restore BACKUP_ID --mailbox MAILBOX [--account NAME] [--dry-run]
+```
+
+`--config PATH` works on every subcommand. Run/backup ids are short strings
+(`4w8wbbs3fs`); type any unambiguous leading prefix (eg. `4w8b`).
+
+## Quickstart
+
+```sh
+curl -o config.yaml https://raw.githubusercontent.com/4piu/liametahi/master/config.example.yaml
+$EDITOR config.yaml    # at least an account and a model
+chmod 600 config.yaml
+
+liametahi config check --connect
+liametahi run inbox-classify --dry-run --verbose  # preview, no mutation
+liametahi run inbox-classify                      # for real
+liametahi report                                  # review the last run
+liametahi restore 4w8w --mailbox INBOX            # undo a trash
+```
+
+See [docs/configuration.md](docs/configuration.md) for every key and how
+conditions/rules compose. Config file location, first match wins:
+
+1. `--config PATH`
+2. `$LIAMETAHI_CONFIG`
+3. `$(pwd)/config.yaml`
+4. `~/.config/liametahi/config.yaml` (Linux); `~/Library/Application Support/liametahi` (macOS); `%LOCALAPPDATA%\liametahi` (Windows)
+
+## Documentation
+
+- [docs/configuration.md](docs/configuration.md) — full config key
+  reference: accounts, models, processors, tasks, rule conditions.
+- [docs/internals.md](docs/internals.md) — safety model, run phases,
+  decision cache, and the reasoning behind each guarantee.
+- [docs/development.md](docs/development.md) — test tiers, running the
+  suite, and live-mailbox testing.

liametahi-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Liametahi
+
+An AI-powered mailbox cleanup tool for IMAP. Point it at an inbox and it
+can:
+
+- Trash, move, label, or route mail using both plain conditions (sender,
+  age, size, headers) and an AI's answer to a question you write ("is this
+  spam?", "how urgent is this?")
+- Preview any run with `--dry-run`, back up before deleting, and restore
+  anytime
+- Run unattended on a schedule — locking, crash recovery, and a report of
+  every past run
+- Mix a fast/cheap model with a slower one, only escalating the mail the
+  first pass is unsure about
+
+```yaml
+processors:
+  vibe-check:
+    model: local
+    type: noul
+    instructions: A newsletter or digest with nothing time-sensitive left in it.
+
+tasks:
+  inbox-cleanup:
+    account: personal
+    source_mailboxes: [INBOX]
+    rules:
+      - when:
+          - older-than: 30d
+          - processor: "vibe-check.value >= 0.9"
+        actions: [backup, trash]
+```
+
+## Install
+
+Needs Python ≥ 3.14, [`uv`](https://docs.astral.sh/uv/), an IMAP account, and
+a model endpoint — an OpenAI-compatible chat API, Anthropic, or a
+Jev-compatible API.
+
+```sh
+uv tool install liametahi
+liametahi --help
+```
+
+Running from a source checkout instead? See
+[docs/development.md](docs/development.md).
+
+## Usage
+
+```
+liametahi config check [--connect]
+liametahi run TASK [--dry-run] [--fail-fast] [--reevaluate] [--wait SECONDS] [--format table|json] [--verbose]
+liametahi report [RUN_ID] [--list] [--task TASK] [--format table|json] [--verbose]
+liametahi restore BACKUP_ID --mailbox MAILBOX [--account NAME] [--dry-run]
+```
+
+`--config PATH` works on every subcommand. Run/backup ids are short strings
+(`4w8wbbs3fs`); type any unambiguous leading prefix (eg. `4w8b`).
+
+## Quickstart
+
+```sh
+curl -o config.yaml https://raw.githubusercontent.com/4piu/liametahi/master/config.example.yaml
+$EDITOR config.yaml    # at least an account and a model
+chmod 600 config.yaml
+
+liametahi config check --connect
+liametahi run inbox-classify --dry-run --verbose  # preview, no mutation
+liametahi run inbox-classify                      # for real
+liametahi report                                  # review the last run
+liametahi restore 4w8w --mailbox INBOX            # undo a trash
+```
+
+See [docs/configuration.md](docs/configuration.md) for every key and how
+conditions/rules compose. Config file location, first match wins:
+
+1. `--config PATH`
+2. `$LIAMETAHI_CONFIG`
+3. `$(pwd)/config.yaml`
+4. `~/.config/liametahi/config.yaml` (Linux); `~/Library/Application Support/liametahi` (macOS); `%LOCALAPPDATA%\liametahi` (Windows)
+
+## Documentation
+
+- [docs/configuration.md](docs/configuration.md) — full config key
+  reference: accounts, models, processors, tasks, rule conditions.
+- [docs/internals.md](docs/internals.md) — safety model, run phases,
+  decision cache, and the reasoning behind each guarantee.
+- [docs/development.md](docs/development.md) — test tiers, running the
+  suite, and live-mailbox testing.

liametahi-0.1.0/config.example.yaml

@@ -0,0 +1,85 @@
+# Every inbox message is screened by jev; confident spam is trashed, and
+# anything uncertain is handed off to a second task that asks a chat
+# model to look at the body before deciding.
+
+version: 1
+
+accounts:
+  personal:
+    host: imap.gmail.com
+    port: 993
+    username: you@gmail.com
+    password: "an app password, not your real one"
+    trash_mailbox: "[Gmail]/Trash"
+
+models:
+  jev-primary:
+    provider: jev
+    base_url: https://api.typesafe.ai/v1/systemone
+    api_key: "${TYPESAFE_API_KEY}"
+    model: jev-latest
+    mails_per_request: 1
+    max_concurrent_requests: 8
+
+  local:
+    provider: openai_compatible
+    base_url: http://127.0.0.1:8080/v1/chat/completions
+    model: qwen2.5-7b-instruct
+
+processors:
+  spam-category:
+    model: jev-primary
+    type: choice
+    instructions: "Is this email spam or a personal/legitimate message?"
+    criteria:
+      spam: "Unsolicited bulk mail, phishing, or scam content"
+      personal: "A legitimate message, whether personal or business"
+
+  spam-review:
+    model: local
+    type: noul
+    include_body: true
+    instructions: "Is this message spam: unsolicited bulk mail, phishing, or a scam?"
+    criteria:
+      "true": "This message is spam: unsolicited bulk mail, phishing, or a scam."
+      "false": "This message is a legitimate message that should be kept."
+
+tasks:
+  inbox-classify:
+    account: personal
+    source_mailboxes: [INBOX]
+    protect:
+      flags: ['\Flagged', '\Answered']
+      unread: true
+    rules:
+      # Confident spam: trash outright, no local backup.
+      - when:
+          - processor: "spam-category.value == spam"
+          - processor: "spam-category.confidence >= 0.85"
+          - in-mailbox: INBOX
+        actions: [trash]
+
+      # Not confident: hand off to inbox-review for a closer look.
+      - when:
+          - processor: "spam-category.confidence < 0.85"
+        actions: [task:inbox-review]
+
+      # Digests/newsletters, unless the subject flags them urgent.
+      - when:
+          - older-than: 30d
+          - any:
+              - list-id-contains: digest
+              - list-id-contains: newsletter
+          - not:
+              subject-contains: urgent
+        actions: [backup, trash]
+
+  # Reached only via inbox-classify's task: action above -- no mailbox
+  # of its own to scan.
+  inbox-review:
+    account: personal
+    rules:
+      - when:
+          - processor: "spam-review.value >= 0.9"
+          - in-mailbox: INBOX
+        actions: [backup, trash]