awmine 0.2.0__py3-none-any.whl

awmine/__init__.py

@@ -0,0 +1,9 @@
+"""awmine -- mine agent transcripts for tool outcomes, lessons, procedures and cost.
+
+Aither World Mine: what your own sessions already taught you, extracted as
+rows other tools can learn from, with every string redacted before it lands.
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

awmine/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m awmine`` entry point."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

awmine/_doctor.py

@@ -0,0 +1,190 @@
+"""Stack-aware `doctor` for awmine.
+
+GENERATED BY gen_aw_doctor.py -- DO NOT EDIT.
+Regenerate it with the generator named above; a hand-edit here is reverted by
+the next run and fails the parity gate.
+
+Why a doctor exists at all: the aw* bricks are designed to COMPOSE, so the
+interesting failures live BETWEEN them. "awmine is installed" is not the useful
+fact -- "awmine is installed and the thing it pairs with is not" is. This reports
+the whole stack, not just itself.
+
+stdlib only, on purpose: a diagnostic that cannot run because a dependency is
+missing is worthless precisely when you need it.
+"""
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+
+#: Frozen from the Aither World registry at generation time. A shipped
+#: package cannot read the registry, and a doctor that guessed at the family
+#: would go stale in silence. Regenerate to update.
+SELF = 'awmine'
+FAMILY = ['awask', 'awavatar', 'awbac', 'awbrain', 'awbrowse', 'awclassify', 'awdecide', 'awdeck', 'awdelphi', 'awdit', 'awembed', 'awevolve', 'awfind', 'awflow', 'awfocus', 'awgit', 'awgraph', 'awgym', 'awiam', 'awkno', 'awm', 'awmail', 'awnboard', 'awnest', 'awnet', 'awnode', 'awpool', 'awpredict', 'awprism', 'awprove', 'awreason', 'awrecover', 'awrecurse', 'awrelay', 'awrena', 'awrepl', 'awreport', 'awresearch', 'awrise', 'awrouter', 'awrtifact', 'awrun', 'awscreen', 'awseal', 'awsettings', 'awshare', 'awsprite', 'awstorage', 'awswarm', 'awtax', 'awtoll', 'awtunnel', 'awvision', 'awvoice', 'awwall', 'gawbbonet']
+PAIRS_WITH = ['awdecide', 'awm', 'awrise', 'awtoll']
+
+#: This brick's OWN config, read out of its source at generation time.
+#: ENV_REQUIRED is `os.environ["X"]` -- absent, that is a KeyError the moment
+#: the line runs. ENV_OPTIONAL is `os.getenv("X")`, which returns None and lets
+#: the caller cope. Only this brick's namespace is listed: reporting the
+#: platform-wide vars it also touches would be noise, and a doctor that floods
+#: gets ignored.
+ENV_REQUIRED = []
+ENV_OPTIONAL = ['AWMINE_CODEX_BACKLOG', 'AWMINE_DENY', 'AWMINE_FLUSH_ROWS', 'AWMINE_OUT', 'AWMINE_PUBLISH_GATE', 'AWMINE_ROOTS', 'AWMINE_SELFTEST_BREAK', 'AWMINE_SHARE', 'AWMINE_SHARE_REPO', 'AWMINE_SUSPECTS_FATAL']
+
+
+def _installed(mod: str) -> "str | None":
+    """Version if importable, else None. Never raises -- a broken sibling must
+    not take the diagnostic down with it."""
+    try:
+        if importlib.util.find_spec(mod) is None:
+            return None
+    except (ImportError, ValueError):
+        return None
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+        try:
+            return version(mod)
+        except PackageNotFoundError:
+            return "installed"
+    except Exception:
+        return "installed"
+
+
+def report(out=None) -> int:
+    """Print the stack picture. 0 = this brick and its pairs are present."""
+    out = out or sys.stdout
+    print(f"{SELF} doctor", file=out)
+
+    mine = _installed(SELF)
+    print(f"  self       {SELF} {mine or 'NOT IMPORTABLE'}", file=out)
+    shim = shutil.which(SELF)
+    print(f"  command    {shim or 'not on PATH'}", file=out)
+
+    # The stack. Siblings this brick pairs with are called out separately,
+    # because a missing pair is a REASON, while a missing unrelated brick is
+    # just a fact about your machine.
+    missing_pairs, present = [], []
+    for name in FAMILY:
+        v = _installed(name)
+        if v:
+            present.append(name)
+        elif name in PAIRS_WITH:
+            missing_pairs.append(name)
+    print(f"  stack      {len(present)}/{len(FAMILY)} aw* packages installed",
+          file=out)
+    if present:
+        print(f"             {' '.join(sorted(present))}", file=out)
+
+    missing_req = [v for v in ENV_REQUIRED if not os.environ.get(v)]
+    if ENV_REQUIRED or ENV_OPTIONAL:
+        have = sum(1 for v in ENV_REQUIRED + ENV_OPTIONAL if os.environ.get(v))
+        total = len(ENV_REQUIRED) + len(ENV_OPTIONAL)
+        print(f"  config     {have}/{total} of this brick's own vars set", file=out)
+        if missing_req:
+            # Not a preference. os.environ[...] raises the moment it runs.
+            print(f"             MISSING REQUIRED: {' '.join(missing_req)}", file=out)
+
+    local = _local_checks()
+    for line in local:
+        print(f"  {line}", file=out)
+    problems, unjudged = _local_verdict()
+
+    if mine is None:
+        print(f"\nverdict: {SELF} itself is not importable. Reinstall it before "
+              f"anything else here means much.", file=out)
+        return 1
+    if missing_req:
+        print(f"\nverdict: {SELF} is missing required config "
+              f"({', '.join(missing_req)}). Those are read with os.environ[...], "
+              f"so the code path that needs them raises rather than degrades.",
+              file=out)
+        return 1
+    # A measured NO outranks a missing optional pair: awrise printed
+    # "nothing wakes run-due" and still exited 0 because the missing-pairs
+    # branch returned first (measured 2026-09-20).
+    if problems:
+        for p in problems:
+            print(f"\nverdict: {p}", file=out)
+        return 1
+    if unjudged:
+        for u in unjudged:
+            print(f"\nverdict: UNJUDGED -- could not judge: {u}", file=out)
+        return 2
+    if missing_pairs:
+        print(f"\nverdict: {SELF} works, but pairs with "
+              f"{', '.join(sorted(missing_pairs))} which "
+              f"{'is' if len(missing_pairs) == 1 else 'are'} not installed. "
+              f"That is a capability you are missing, not an error.", file=out)
+        return 0
+    print(f"\nverdict: {SELF} and everything it pairs with are present.", file=out)
+    return 0
+
+
+def _local_verdict() -> tuple:
+    """The brick's OWN verdict, folded into the exit code.
+
+    Without this the local lines are DECORATION. Measured 2026-09-20: awrise
+    printed "hostclock NOT INSTALLED -- nothing wakes run-due" and "last tick
+    never", then exited 0 -- teaching an operator that a doctor exit code
+    carries no information. A brick opts in with `_doctor_local_verdict()`
+    returning (problems, unjudged); a brick without one is unaffected.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+        problems, unjudged = mod._doctor_local_verdict()
+    except Exception:                              # noqa: BLE001
+        return [], []
+    return list(problems or []), list(unjudged or [])
+
+
+def _local_checks() -> "list[str]":
+    """Per-brick checks, if this package defines them.
+
+    Kept as a HOOK rather than generated guesses: the generator knows the family
+    from the registry, but it does not know what awmine needs at runtime, and a
+    doctor that invented config requirements would be confidently wrong. A
+    package supplies `_doctor_local()` returning display lines; absent, the
+    stack picture above still stands on its own.
+    """
+    try:
+        mod = importlib.import_module(f"{SELF}.doctor_local")
+    except Exception:
+        return []
+    try:
+        return list(mod._doctor_local())
+    except Exception as exc:                       # noqa: BLE001
+        return [f"local     checks raised {type(exc).__name__}: {exc}"]
+
+
+def main(argv: "list[str] | None" = None) -> int:
+    # --self-test delegates to a SIBLING module when one exists.
+    #
+    # This file is generated and a fresh run replaces it, so a self-test
+    # written HERE is deleted by the next regeneration. awdelphi learned that
+    # the expensive way: 125 lines exercising four real failure paths --
+    # convergence, roster anonymization, resume, gateway-down -- lived in this
+    # file and were destroyed by a routine regeneration, silently, leaving a
+    # --self-test flag that reported PASS while asserting nothing.
+    #
+    # So the seam is a separate module the generator never writes. A package
+    # with real machinery to prove puts it in _selftest.py; everything else
+    # keeps the honest answer below rather than a self-test that only ever
+    # passes.
+    argv = list(argv if argv is not None else __import__("sys").argv[1:])
+    if "--self-test" in argv:
+        try:
+            from . import _selftest as _st
+        except Exception:
+            print("no _selftest module: this doctor reports the stack, and has",
+                  "no machinery of its own to prove")
+            return 0
+        return int(_st.run())
+    return report()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())