gea-program 0.43.0__tar.gz → 0.45.0__tar.gz

{gea_program-0.43.0 → gea_program-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.43.0
+Version: 0.45.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -648,6 +648,35 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### The lateral, the printable reports, the daily summary and the key
+
+An earthquake near a well with a directional survey is measured from the
+nearest point of its lateral, not from the pad - with the measured depth
+there and the distance to the hypocentre - so a protocol radius is read
+against the well bore a regulator means. Every client report is also
+written as a PDF beside its HTML (the drawings redrawn, long tables
+continued across pages) and kept in report history. Each morning the
+program writes a one-page pad summary - what changed, what is due, what is
+still missing - and sends it through the notification rules (`gea
+pad-summary`). The dossier signing key can be retired and replaced: the old
+key signs the hand-over, earlier dossiers still check out, and later ones
+carry the rotation so a client can follow it (`gea dossier --rotate-key`).
+`gea help pad-summary`.
+
+### The earthquake watch and the alerts
+
+While a well operates, the program reads the USGS earthquake catalogue
+every few minutes from the site's machine - the real-time feed USGS asks
+automated programs to use, and the catalogue service for any gap - and
+raises an alert when an earthquake near the well reaches the chosen
+regulator's protocol level; a revision to a higher level is a new alert,
+and a watch that cannot reach the catalogue says so. The same alerts cover
+what nobody watches by hand: a component's service interval used up, a
+penetrator check outside its rating, a signed dossier the workspace no
+longer matches. Every alert is listed on the Alarms tab and sent through
+the notification rules (email or a webhook). `gea seismicity --watch-once`,
+`gea alerts`, `gea help alerts`.
+
 ### Report history and the signed dossier
 
 Every client report a workspace writes is kept, version by version, under

{gea_program-0.43.0 → gea_program-0.45.0}/README.md

@@ -609,6 +609,35 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### The lateral, the printable reports, the daily summary and the key
+
+An earthquake near a well with a directional survey is measured from the
+nearest point of its lateral, not from the pad - with the measured depth
+there and the distance to the hypocentre - so a protocol radius is read
+against the well bore a regulator means. Every client report is also
+written as a PDF beside its HTML (the drawings redrawn, long tables
+continued across pages) and kept in report history. Each morning the
+program writes a one-page pad summary - what changed, what is due, what is
+still missing - and sends it through the notification rules (`gea
+pad-summary`). The dossier signing key can be retired and replaced: the old
+key signs the hand-over, earlier dossiers still check out, and later ones
+carry the rotation so a client can follow it (`gea dossier --rotate-key`).
+`gea help pad-summary`.
+
+### The earthquake watch and the alerts
+
+While a well operates, the program reads the USGS earthquake catalogue
+every few minutes from the site's machine - the real-time feed USGS asks
+automated programs to use, and the catalogue service for any gap - and
+raises an alert when an earthquake near the well reaches the chosen
+regulator's protocol level; a revision to a higher level is a new alert,
+and a watch that cannot reach the catalogue says so. The same alerts cover
+what nobody watches by hand: a component's service interval used up, a
+penetrator check outside its rating, a signed dossier the workspace no
+longer matches. Every alert is listed on the Alarms tab and sent through
+the notification rules (email or a webhook). `gea seismicity --watch-once`,
+`gea alerts`, `gea help alerts`.
+
 ### Report history and the signed dossier
 
 Every client report a workspace writes is kept, version by version, under

{gea_program-0.43.0 → gea_program-0.45.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.43.0"
+__version__ = "0.45.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.43.0 → gea_program-0.45.0}/gea/__main__.py

@@ -563,9 +563,19 @@ def main(argv=None) -> int:
     p_os.add_argument("--kind", type=str, default=None, choices=("drilling", "completion", "disposal", "injection", "other"))
     p_os.add_argument("--remove-op", type=str, default=None)
     p_os.add_argument("--remove-catalog", type=str, default=None)
+    p_os.add_argument("--watch", type=str, default=None, choices=("on", "off"), help="turn the live earthquake watch on or off")
+    p_os.add_argument("--watch-every", type=float, default=None, help="the watch's interval in minutes (default 5)")
+    p_os.add_argument("--watch-mode", type=str, default=None, choices=("operations", "always"), help="poll only while an operation is under way (default), or always")
+    p_os.add_argument("--watch-once", action="store_true", help="poll the USGS catalogue now, from this machine, and say what came back")
     p_os.add_argument("--actor", type=str, default="cli")
     p_os.add_argument("--json", action="store_true")
 
+    p_al = sub.add_parser("alerts", help="the program's alerts: earthquakes near operating wells and the protocol levels they reach, the earthquake watch going quiet, components due for service, penetrator checks outside their ratings, dossiers the workspace no longer matches")
+    p_al.add_argument("--workspace", type=str, required=True)
+    p_al.add_argument("--check", action="store_true", help="check the motors, penetrators and dossiers now, sending what began or cleared through the notification rules")
+    p_al.add_argument("-n", type=int, default=30)
+    p_al.add_argument("--json", action="store_true")
+
     p_dz = sub.add_parser("dossier", help="the signed dossier: a well's (or the pad's) reports, declarations, audit log and source hashes in one zip, signed with the site's Ed25519 key, with a checker anyone can run without this program")
     p_dz.add_argument("--workspace", type=str, default=None)
     p_dz.add_argument("--well", type=str, default=None, help="a well; without it, the pad (every well and the site reports)")
@@ -574,9 +584,21 @@ def main(argv=None) -> int:
     p_dz.add_argument("--sources", type=str, default="", help="with --verify: a folder holding the source records to check against their hashes")
     p_dz.add_argument("--key", action="store_true", help="print this site's signing key fingerprint")
     p_dz.add_argument("--list", action="store_true", help="list the dossiers this site has signed")
+    p_dz.add_argument("--rotate-key", action="store_true", help="retire this site's signing key and start a new one, signed over by the old (give --reason)")
+    p_dz.add_argument("--reason", type=str, default="", help="with --rotate-key: why the key is retired")
+    p_dz.add_argument("--key-history", action="store_true", help="the site's keys, current and retired, and the rotations between them")
     p_dz.add_argument("--actor", type=str, default="cli")
     p_dz.add_argument("--json", action="store_true")
 
+    p_ps = sub.add_parser("pad-summary", help="the daily pad summary: what changed since the last one, what is due, what is still missing - one page, kept in report history; the service writes it each day and sends it through the notification rules")
+    p_ps.add_argument("--workspace", type=str, required=True)
+    p_ps.add_argument("--send", action="store_true", help="also hand it to the notification rules (the event pad.summary)")
+    p_ps.add_argument("--at", type=str, default=None, help="the daily time the service writes it, HH:MM UTC")
+    p_ps.add_argument("--on", action="store_true", help="the service writes it each day")
+    p_ps.add_argument("--off", action="store_true", help="the service does not")
+    p_ps.add_argument("--actor", type=str, default="cli")
+    p_ps.add_argument("--json", action="store_true")
+
     p_rh = sub.add_parser("reports-history", help="every version of every client report this workspace has written, kept under reports/history; --prune keeps the newest N")
     p_rh.add_argument("--workspace", type=str, required=True)
     p_rh.add_argument("--family", type=str, default=None, help="e.g. wells/Well-1/well_report or pad_report")
@@ -2225,6 +2247,26 @@ def main(argv=None) -> int:
                 return 0
             if a.remove_op:
                 _OS.remove_operation(ws, a.actor, a.remove_op); print(f"removed {a.remove_op}"); return 0
+            if a.watch or a.watch_every is not None or a.watch_mode or a.watch_once:
+                from . import seismic_watch as _SW
+                if ws is None:
+                    raise SystemExit("seismicity: the watch needs --workspace")
+                if a.watch or a.watch_every is not None or a.watch_mode:
+                    _SW.set_settings(ws, a.actor, None if a.watch is None else a.watch == "on", a.watch_mode, a.watch_every)
+                if a.watch_once:
+                    from .notify import Notifier
+                    n_ = Notifier(ws.path); n_.reload()
+                    r_ = _SW.poll(ws, n_, force=True)
+                    if r_.get("ok"):
+                        print(f"reached the catalogue ({r_['how']}): {r_['in_circle']} earthquake(s) in the watch circle, {r_['new']} new; {len(r_['alerts'])} alert(s)")
+                        for al_ in r_["alerts"]:
+                            print(f"  {al_['event']}: {al_.get('detail', '')}")
+                    else:
+                        print(f"did not reach the catalogue: {r_.get('error') or r_.get('why')}")
+                st_ = _SW.status(ws)
+                print(f"watch: {st_['state']} - every {st_['settings']['every_min']:g} min, {st_['settings']['mode']}; last good poll {st_['last_ok_utc'] or 'never'}"
+                      + (f"; last error {st_['last_error']}" if st_.get('last_error') else ""))
+                return 0 if (not a.watch_once or r_.get("ok")) else 1
             if a.remove_catalog:
                 _OS.remove_catalog(ws, a.actor, a.remove_catalog); print(f"removed {a.remove_catalog}"); return 0
             over = {k: v for k, v in (("protocol", a.protocol), ("radius_km", a.radius_km), ("screen_km", a.screen_km), ("post_days", a.post_days), ("mc", a.mc)) if v is not None}
@@ -2267,6 +2309,23 @@ def main(argv=None) -> int:
             k = _DZ.key_info(ws)
             print(f"Ed25519 {k['fingerprint']} (public key {k['public_key']}, made {k['created_utc']})" if k else "no signing key yet: the first dossier makes one")
             return 0
+        if a.rotate_key:
+            try:
+                r_ = _DZ.rotate_key(ws, a.actor, a.reason)
+            except ValueError as ex:
+                raise SystemExit(f"dossier: {ex}")
+            print(f"retired {r_['old']['fingerprint']}; the new key is {r_['new']['fingerprint']}")
+            print("  the rotation is signed by both keys and rides in every later dossier; give the new fingerprint to your clients")
+            return 0
+        if a.key_history:
+            h_ = _DZ.key_history(ws)
+            if a.json:
+                print(_json.dumps(h_, default=str)); return 0
+            for k in h_["keys"]:
+                print(f"{k['fingerprint']}  made {k.get('created_utc') or '?'}  " + (f"retired {k['retired_utc']} ({k.get('reason', '')}) -> {k.get('successor')}" if k.get("retired_utc") else "CURRENT"))
+            if not h_["keys"]:
+                print("no key history yet")
+            return 0
         if a.list:
             for e in reversed(_DZ.ledger(ws)):
                 print(f"{e['utc']}  {e['dossier_id']}  {e['display']:<24} {e['n_files']:>4} files  {e['path']}")
@@ -2279,6 +2338,36 @@ def main(argv=None) -> int:
         print(f"  {os.path.join(ws.reports_dir, e['path'])}")
         print(f"  key fingerprint {e['fingerprint']}")
         return 0
+    elif a.cmd == "pad-summary":
+        import json as _json
+        from . import pad_summary as _PS
+        from .cli import _safe_stdout
+        from .notify import Notifier
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"pad-summary: {e}")
+        if a.at or a.on or a.off:
+            try:
+                s_ = _PS.set_settings(ws, a.actor, enabled=(True if a.on else False if a.off else None), at=a.at)
+            except ValueError as e:
+                raise SystemExit(f"pad-summary: {e}")
+            print(f"daily pad summary {'on' if s_['enabled'] else 'off'} at {s_['at']} UTC, sent through the notification rules: {'yes' if s_['send'] else 'no'}")
+            return 0
+        n_ = None
+        if a.send:
+            n_ = Notifier(ws.path); n_.reload()
+        r = _PS.write(ws, __version__, a.actor, n_, send=bool(a.send))
+        if a.json:
+            print(_json.dumps(r, default=str)); return 0
+        print(f"wrote {r['report_id']} (since {r['since']}): {r['paths']['html']}")
+        if r['paths'].get('pdf'):
+            print(f"  printable: {r['paths']['pdf']}")
+        if a.send:
+            print(f"  sent: {', '.join(str(d['channel']) + (' ok' if d['ok'] else ' FAILED') for d in r['delivered']) or 'no notification rule for pad.summary'}")
+        return 0
     elif a.cmd == "reports-history":
         import json as _json
         from . import report_history as _RH
@@ -2306,6 +2395,30 @@ def main(argv=None) -> int:
             for v in f_["versions"][: (50 if a.family else 3)]:
                 print(f"      {v['utc']}  {v.get('report_id') or ''}  reports/{v['dir']}")
         return 0
+    elif a.cmd == "alerts":
+        import json as _json
+        from . import alerts as _AL
+        from .cli import _safe_stdout
+        from .notify import Notifier
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            raise SystemExit(f"alerts: {e}")
+        if a.check:
+            n_ = Notifier(ws.path); n_.reload()
+            r_ = _AL.check_conditions(ws, n_, force=True)
+            print(f"checked: {len(r_)} alert(s) raised or cleared")
+        rows = _AL.recent(ws, a.n)
+        if a.json:
+            print(_json.dumps(rows, default=str)); return 0
+        for r in rows:
+            sent = ", ".join(f"{d['channel']}{'' if d['ok'] else ' (failed)'}" for d in r.get("delivered") or []) or "no channel set up"
+            print(f"{r['utc']}  {r['event']:<20} {r.get('well') or '':<16} {r.get('detail', '')}  [{sent}]")
+        if not rows:
+            print("no alerts yet")
+        return 0
     elif a.cmd == "simulation":
         import json as _json
         from . import simulation as _SIM