damien 0.4.1__py3-none-any.whl

damien/__init__.py

@@ -0,0 +1,42 @@
+"""Damien — a Gmail triage CLI that asks before it acts."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _installed
+
+try:
+    # Whatever was actually installed. It is the honest answer for a wheel install, but an
+    # *editable* install runs this source tree while carrying the metadata of whenever it was
+    # installed — so `source_version()` below exists to notice when the two disagree.
+    __version__ = _installed("damien")
+except PackageNotFoundError:                  # a checkout with no install around it
+    __version__ = "0.0.0+source"
+
+
+def source_version() -> str | None:
+    """The version this *source tree* declares, or None when there is no tree (a wheel).
+
+    `pyproject.toml` is the single source of truth for the version; the installed metadata is a
+    copy of it made at install time. A floor check that reads only the copy can stop a machine
+    that is in fact running newer code.
+    """
+    import tomllib
+    from pathlib import Path
+
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "pyproject.toml"
+        if candidate.is_file():
+            try:
+                return tomllib.loads(candidate.read_text()).get("project", {}).get("version")
+            except (OSError, tomllib.TOMLDecodeError):
+                return None
+    return None
+
+
+def version_note() -> str | None:
+    """A line for `damien version` when the metadata is stale, else None."""
+    declared = source_version()
+    if declared and declared != __version__:
+        return (f"  running from a source tree that declares {declared} — the installed "
+                f"metadata says {__version__} (refresh it: uv tool install --editable "
+                f"'.[pg,vectors]' --force)")
+    return None

damien/calibrate.py

@@ -0,0 +1,138 @@
+"""Calibration: the confidence at which *this* model, on *this* host, may act unattended.
+
+A decision model's confidence describes its answer, not its correctness, and two models
+(or one model on two hosts) do not mean the same thing by 0.9. So the threshold is measured
+against what this inbox already settled — a person's corrections and the rules' applied
+work — and stored per model@host. A model without a measurement does not act on its own.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .config import Settings
+from .decide import JudgementSpec, decide_message
+from .models import Action
+
+CALIBRATION_FILE = "calibration.json"
+
+# The pass ran jev-1.13 at 0.9 before calibration existed; keep that, on any host.
+BASELINE_MODEL = "typesafe/jev-1.13"
+BASELINE_ACT = 0.9
+
+
+def _path(settings: Settings) -> Path:
+    return Path(settings.root) / CALIBRATION_FILE
+
+
+def _entry_key(settings: Settings) -> str:
+    return f"{settings.model}@{settings.judge_host() or ''}"
+
+
+def _load(settings: Settings) -> dict[str, Any]:
+    try:
+        return json.loads(_path(settings).read_text())
+    except (OSError, ValueError):
+        return {}
+
+
+def act_threshold(settings: Settings) -> float | None:
+    """The calibrated threshold for the current model+host, the baseline's, or None (uncalibrated)."""
+    entry = _load(settings).get(_entry_key(settings))
+    if isinstance(entry, dict) and isinstance(entry.get("act"), (int, float)):
+        return float(entry["act"])
+    if settings.model == BASELINE_MODEL:
+        return BASELINE_ACT
+    return None
+
+
+def _truth(store) -> dict[str, tuple[str, str | None]]:
+    """message_id -> (action, label) that a person or a rule settled, newest person correction winning."""
+    truth: dict[str, tuple[str, str | None]] = {}
+    runs = store.conn.execute(
+        "SELECT id, plan_id FROM runs WHERE status IN ('ok', 'partial') ORDER BY started_at").fetchall()
+    for run in runs:
+        applied: set[str] = set()
+        for batch in store.conn.execute("SELECT * FROM run_batches WHERE run_id=?", (run["id"],)).fetchall():
+            if "state" in batch.keys() and batch["state"] not in (None, "done"):
+                continue
+            applied.update(json.loads(batch["ids"]))
+        if not applied:
+            continue
+        for item in store.conn.execute(
+                "SELECT message_id, action, label FROM plan_items WHERE plan_id=? AND source IN ('rule', 'person')",
+                (run["plan_id"],)).fetchall():
+            if item["message_id"] in applied:
+                truth[item["message_id"]] = (item["action"], item["label"])
+    for mid, row in store.latest_corrections().items():
+        truth[mid] = (row["action"], row.get("label"))
+    return truth
+
+
+MIN_ACTED = 30          # a bar set on a handful of answers is a guess, not a calibration
+
+
+def evaluate(*, store, settings: Settings, spec: JudgementSpec, judge, limit: int = 500,
+             max_wrong_rate: float = 0.02, min_acted: int = MIN_ACTED) -> dict:
+    """Re-judge settled messages (headers only, no rules) and find the lowest safe threshold.
+
+    The full decide_message runs, guardrail included, because that is what would act;
+    no confidence floor is applied, so every threshold can be read off one pass.
+
+    "Safe" means: at least `min_acted` messages would have been acted on at that bar, and
+    the wrong rate stays within `max_wrong_rate` there *and* at every higher bar with as
+    much evidence — so the chosen bar never sits below a worse one.
+    """
+    truth = _truth(store)
+    ids = list(truth)[-limit:] if limit else list(truth)
+    messages = [m.model_copy(update={"body": None}) for m in store.get_messages(ids)]
+    judged: list[tuple[float, bool]] = []          # (confidence, wrong) for every non-keep action
+    criteria = spec.criteria()
+    batch = max(1, settings.judge_batch)
+    for start in range(0, len(messages), batch):
+        chunk: Sequence = messages[start:start + batch]
+        verdicts = judge.judge(chunk, criteria, context=spec.context)
+        for message, verdict in zip(chunk, verdicts, strict=False):
+            if message.id in getattr(judge, "failed", ()):
+                continue
+            d = decide_message(message, rules=(), verdict=verdict, spec=spec, model=settings.model,
+                               protected_labels=settings.protect_labels)
+            if d.action is Action.keep:
+                continue
+            action, label = truth[message.id]
+            wrong = d.action.value != action or (d.action is Action.label and d.label != label)
+            judged.append((d.confidence or 0.0, wrong))
+
+    thresholds = []
+    for step in range(50, 100):
+        t = step / 100
+        acted = [w for c, w in judged if c >= t]
+        thresholds.append({"t": t, "acted": len(acted), "wrong": sum(acted)})
+    act = None
+    for row in reversed(thresholds):                 # from the strictest bar down
+        if row["acted"] < min_acted:
+            continue
+        if row["wrong"] / row["acted"] > max_wrong_rate:
+            break
+        act = row["t"]
+    return {"n": len(messages), "thresholds": thresholds, "act": act}
+
+
+def save(settings: Settings, result: dict) -> Path:
+    """Record the measurement for this model@host; a result with no safe threshold removes it."""
+    data = _load(settings)
+    key = _entry_key(settings)
+    act = result.get("act")
+    if act is None:
+        data.pop(key, None)
+    else:
+        row = next((r for r in result.get("thresholds", []) if r["t"] == act), {})
+        data[key] = {"act": act, "n": result.get("n", 0), "wrong": row.get("wrong", 0),
+                     "at": datetime.now(UTC).isoformat(timespec="seconds")}
+    path = _path(settings)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True))
+    return path

damien/cli/__init__.py

@@ -0,0 +1,131 @@
+"""The CLI. One binary, complete operations, nothing running in the background.
+
+    damien login                                  sign in to Gmail once
+    damien doctor                                 check the install; names the fix
+    damien pass weekly|monthly [--dry-run]        one scheduled pass: build, approve, apply the certain
+    damien scan    --query 'in:inbox older_than:1y'
+    damien plan build --query ... [--limit N]      decide, write nothing
+    damien plan show  <id> [--sample 20]           read the plan before it happens
+    damien plan approve <id>                       mint the token (printed once)
+    damien plan apply <id> --token T --yes         do it, in bulk, journaled
+    damien run list | run undo <run-id> --yes
+    damien rules init | rules list
+    damien judge eval                             calibrate the model's act threshold
+    damien skill install --target openclaw         install the agent skill
+    damien correct <message-id> --action keep --note "that was a client"
+
+Everything prints plain text unless `--json` is given, and every command is safe
+to run twice. `plan build` never writes to Gmail; only `plan apply` does.
+"""
+
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+import typer
+
+from ..config import Settings, load_settings
+from ..gmail import Gmail
+from ..jev import FakeJudge, make_judge
+from ..plan import group_by_index
+from ..rules import default_rules, load_rules, save_rules, sender_key
+
+app = typer.Typer(add_completion=False, help="Damien — Gmail triage: rules first, a System One model for judgment, code for every write.")
+plan_app = typer.Typer(help="Build, review and apply a plan. Only `apply` writes.")
+run_app = typer.Typer(help="Runs that were applied, and how to take them back.")
+rules_app = typer.Typer(help="The deterministic rules.")
+judge_app = typer.Typer(help="The decision model: how far its confidence can be trusted.")
+skill_app = typer.Typer(help="The agent skill that teaches a host agent to run Damien.")
+app.add_typer(plan_app, name="plan")
+app.add_typer(run_app, name="run")
+app.add_typer(rules_app, name="rules")
+app.add_typer(judge_app, name="judge")
+app.add_typer(skill_app, name="skill")
+
+SEEDED = "damien-seed"
+SKILL_NAME = "damien-mail-triage"
+
+
+def _load() -> Settings:
+    return load_settings()
+
+
+def _rules(settings: Settings, path: Path | None, *, seed: bool = True) -> list:
+    """The rules in force. `seed=False` is for read-only callers (doctor): no file is written."""
+    target = path or settings.root / "rules.json"
+    rules = load_rules(target)
+    if not rules and not target.exists():
+        rules = default_rules()
+        if seed:
+            save_rules(target, rules)
+    return rules
+
+
+def _gmail(settings: Settings) -> Gmail:
+    return Gmail(settings)
+
+
+def _judge(settings: Settings, mode: str, spec, cache=None):
+    if mode == "none":
+        return None
+    if mode == "fake":
+        return FakeJudge()
+    return make_judge(settings, spec, cache=cache)
+
+
+def _fail(message: str, json_out: bool, code: int = 1):
+    """One way to refuse: plain red text, or `{"ok": false, "error": ...}` for an agent."""
+    if json_out:
+        typer.echo(json.dumps({"ok": False, "error": message}))
+    else:
+        typer.secho(message, fg="red" if code == 1 else "yellow")
+    raise typer.Exit(code)
+
+
+def _fingerprint(ids: list[str]) -> str:
+    """Six hex of the group's sorted ids: a digest number that names the wrong group is refused."""
+    return hashlib.sha256("\n".join(sorted(ids)).encode()).hexdigest()[:6]
+
+
+def _parse_group(raw: str) -> tuple[int, str | None]:
+    number, _, fp = raw.partition(":")
+    try:
+        return int(number), (fp.strip().lower() or None)
+    except ValueError:
+        raise typer.BadParameter(f"--group takes N or N:fp from `plan digest`, not {raw!r}") from None
+
+
+def _pick_group(plan, store, raw: str, similarity: float):
+    """The group a person read in the digest — refused when its fingerprint no longer matches."""
+    index, fp = _parse_group(raw)
+    found = group_by_index(plan, store, index, similarity=similarity)
+    if fp is not None and _fingerprint(found.message_ids) != fp:
+        raise ValueError(f"group {index} is no longer {index}:{fp} (it is {index}:{_fingerprint(found.message_ids)}) — "
+                         f"run `damien plan digest {plan.id}` again and pick from what it shows now")
+    return found
+
+
+def _corrected_against(store, messages, action: str, ids: set[str] | None = None) -> list[tuple[str, dict]]:
+    """Person corrections that a rule for these senders would contradict: (subject, correction)."""
+    keys = {sender_key(m.from_addr) for m in messages if m.from_addr}
+    latest = store.latest_corrections()
+    if not latest:
+        return []
+    by_id = {m.id: m for m in store.get_messages(list(latest))}
+    out = []
+    for mid, c in latest.items():
+        m = by_id.get(mid)
+        hit = (ids is not None and mid in ids) or (m is not None and sender_key(m.from_addr) in keys)
+        if hit and c["action"] != action:
+            out.append(((m.subject if m else "") or "", c))
+    return out
+
+
+def main() -> None:
+    app()
+
+
+from . import core, plans, rules_cmds, runs  # noqa: E402,F401

damien/cli/core.py

@@ -0,0 +1,234 @@
+"""Top-level commands."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from damien import cli as c
+from damien.cli import app
+
+from .. import __version__, passes, version_note
+from ..config import write_env
+from ..doctor import checks as doctor_checks
+from ..gmail import GmailError
+from ..models import Action
+from ..plan import (
+    load_messages,
+)
+from ..profile import write_profile
+from ..rules import (
+    default_rules,
+    save_rules,
+)
+from ..store import open_store
+
+
+@app.command()
+def version() -> None:
+    """Print the version. A stale editable install is called out rather than hidden."""
+    typer.echo(f"damien {__version__}")
+    note = version_note()
+    if note:
+        typer.echo(note)
+
+@app.command()
+def login() -> None:
+    """Sign in to Gmail (installed-app OAuth; writes a token to ~/.damien)."""
+    settings = c._load()
+    gmail = c._gmail(settings)
+    try:
+        who = gmail.login()
+    except GmailError as exc:
+        typer.secho(f"login failed: {exc}", fg="red")
+        raise typer.Exit(1) from exc
+    typer.secho(f"signed in as {who or 'unknown'}", fg="green")
+    typer.echo(f"token stored at {settings.token_path}")
+
+@app.command()
+def status(json_out: bool = typer.Option(False, "--json", help="Machine-readable output.")) -> None:
+    """What is configured, what has been decided, what has been done."""
+    settings = c._load()
+    with open_store(settings) as store:
+        info = {
+            "config": settings.redacted(),
+            "store": store.summary(),
+            "rules_file": str(settings.root / "rules.json"),
+        }
+    if json_out:
+        typer.echo(json.dumps(info, indent=2, default=str))
+        return
+    typer.secho("damien", bold=True)
+    for key, value in info["config"].items():
+        typer.echo(f"  {key:<18} {value}")
+    typer.echo("  store")
+    for key, value in info["store"].items():
+        typer.echo(f"    {key:<14} {value}")
+
+@app.command()
+def init(force: bool = typer.Option(False, "--force", help="Overwrite what is already there.")) -> None:
+    """Set up this install: profile, rules and a config file. Safe to re-run.
+
+    Nothing here is required to run Damien on the defaults — but `profile.json` is where
+    you tell it whose inbox this is, which is the difference between a tool that files your
+    mail and one that files mail.
+    """
+    settings = c._load()
+    root = settings.root
+    root.mkdir(parents=True, exist_ok=True)
+
+    path, written = write_profile(root, force=force)
+    typer.secho(f"{'wrote' if written else 'kept '} {path}", fg="green" if written else "yellow")
+
+    rules_path = root / "rules.json"
+    if not rules_path.exists() or force:
+        save_rules(rules_path, default_rules())
+        typer.secho(f"wrote {rules_path}", fg="green")
+    else:
+        typer.secho(f"kept  {rules_path}", fg="yellow")
+
+    env_path, env_written = write_env(root, force=force)
+    typer.secho(f"{'wrote' if env_written else 'kept '} {env_path}", fg="green" if env_written else "yellow")
+
+    typer.echo()
+    typer.secho("next:", bold=True)
+    typer.echo(f"  1. edit {path} — describe whose inbox this is and what belongs in it")
+    typer.echo(f"  2. edit {env_path} — your account, and the judge you want (rules | openrouter | typesafe | local)")
+    typer.echo("  3. damien login                      # Gmail, read/write in one browser tab")
+    typer.echo("  4. damien plan build -q 'in:inbox' --limit 200 --show 20")
+    typer.echo("  5. read it, then: damien plan approve <plan_id>, and damien plan apply <plan_id> --token <t> --yes")
+    typer.echo("  6. calibrate the model once: damien judge eval   — then schedule damien pass weekly")
+
+@app.command()
+def doctor(json_out: bool = typer.Option(False, "--json", help="Machine-readable output.")) -> None:
+    """Check this install and name the fix for anything missing.
+
+    Changes nothing: it reads your config, profile, rules, credential and store, makes at
+    most one live Gmail call, and prints a fix beside each finding. Exits non-zero only when
+    something actually blocks you.
+    """
+    settings = c._load()
+    rows = doctor_checks(settings, rules=c._rules(settings, None, seed=False))
+    if json_out:
+        typer.echo(json.dumps({"checks": [r.__dict__ for r in rows],
+                               "ok": not any(r.blocking for r in rows)}, indent=2))
+    else:
+        colour = {"ok": "green", "warn": "yellow", "fail": "red"}
+        mark = {"ok": "ok  ", "warn": "warn", "fail": "FAIL"}
+        typer.secho("damien doctor", bold=True)
+        for r in rows:
+            typer.secho(f"  {mark[r.status]}  {r.name:<17} {r.detail}", fg=colour[r.status])
+        blocking = sum(1 for r in rows if r.blocking)
+        soft = sum(1 for r in rows if r.status == "warn")
+        typer.echo()
+        typer.echo(f"  {len(rows)} checks: {len(rows) - blocking - soft} ok · "
+                   f"{soft} to look at · {blocking} blocking")
+        if blocking:
+            typer.secho("  the fix for each line above is in docs/SETUP.md", dim=True)
+        else:
+            typer.secho("  ready: damien plan build -q 'in:inbox' --limit 200 --show 20", dim=True)
+    if any(r.blocking for r in rows):
+        raise typer.Exit(1)
+
+@app.command()
+def scan(
+    query: str = typer.Option("in:inbox", "--query", "-q", help="Gmail search query."),
+    limit: int | None = typer.Option(None, "--limit", "-n", help="Stop after this many messages."),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """List and cache headers for a query. Reads only; decides nothing."""
+    settings = c._load()
+    gmail = c._gmail(settings)
+    with open_store(settings) as store:
+        try:
+            ids = gmail.list_ids(query, limit=limit)
+            messages, _fetched = load_messages(store=store, gmail=gmail, ids=ids,
+                                               ttl_hours=settings.header_ttl_hours)
+        except GmailError as exc:
+            typer.secho(str(exc), fg="red")
+            raise typer.Exit(1) from exc
+        store.upsert_messages(messages)
+        cached = store.count_messages()
+    if json_out:
+        typer.echo(json.dumps({"query": query, "matched": len(ids), "cached": cached}, indent=2))
+        return
+    typer.secho(f"{len(ids)} message(s) matched {query!r}; {cached} cached in the store", fg="green")
+
+@app.command("pass")
+def pass_(
+    period: str = typer.Argument(..., help="weekly (the last 7 days) | monthly (the calendar month just gone)"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Build and report; write nothing to Gmail."),
+    limit: int | None = typer.Option(None, "--limit", "-n", help="Cap how much this pass looks at."),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """One scheduled pass: rules first, the model on what they left, applied only where certain.
+
+    It approves its own plan in-process, so a scheduler needs no human step. What it is
+    not sure of stays in the plan and is reported, never applied.
+    """
+    if period not in ("weekly", "monthly"):
+        c._fail(f"usage: damien pass weekly|monthly — not {period!r}", json_out, 2)
+    settings = c._load()
+    report = passes.run_pass(settings=settings, period=period, dry_run=dry_run, limit=limit,
+                             gmail=c._gmail(settings))
+    if json_out:
+        typer.echo(json.dumps(report, indent=2, default=str))
+    else:
+        for line in passes.render(report):
+            typer.echo(line)
+    if not report["ok"]:
+        raise typer.Exit(1)
+
+@app.command()
+def restore(
+    message_id: list[str] = typer.Argument(..., help="One or more message ids."),
+    note: str | None = typer.Option(None, "--note"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """Put a message back in the inbox, and record that you wanted it there.
+
+    The inverse of trashing one message — because a whole run is a blunt thing to undo
+    when the model got exactly one of three hundred wrong. Also records the correction,
+    so the next plan agrees with you.
+    """
+    settings = c._load()
+    gmail = c._gmail(settings)
+    try:
+        n = gmail.untrash(message_id)
+    except GmailError as exc:
+        c._fail(str(exc), json_out)
+    with open_store(settings) as store:
+        for mid in message_id:
+            store.correct(mid, Action.keep, note=note)
+        refreshed = gmail.fetch(message_id)
+        store.upsert_messages(refreshed)
+    if json_out:
+        typer.echo(json.dumps({"ok": True, "restored": n, "message_ids": message_id}))
+        return
+    typer.secho(f"restored {n} message(s) to the inbox", fg="green")
+    typer.secho("recorded as a correction, so the next plan keeps it", dim=True)
+
+@app.command()
+def correct(
+    message_id: str,
+    action: str = typer.Option(..., "--action", help="What it should have been: keep|archive|trash|label|mark_read"),
+    label: str | None = typer.Option(None, "--label", help="Required with --action label."),
+    note: str | None = typer.Option(None, "--note"),
+    json_out: bool = typer.Option(False, "--json"),
+) -> None:
+    """Record what a person decided about one message. This is the training signal."""
+    try:
+        parsed = Action(action)
+    except ValueError:
+        c._fail(f"unknown action: {action}", json_out, 2)
+    if parsed is Action.label and not (label or "").strip():
+        c._fail("--action label needs --label NAME: a label correction without a label cannot be applied", json_out, 2)
+    settings = c._load()
+    with open_store(settings) as store:
+        store.correct(message_id, parsed, label=label, note=note)
+    if json_out:
+        typer.echo(json.dumps({"ok": True, "message_id": message_id, "action": parsed.value, "label": label}))
+        return
+    typer.secho(f"recorded correction for {message_id}: {parsed.value}", fg="green")
+    typer.secho("it outranks a rule or a model on every later plan", dim=True)