gea-program 0.87.0__tar.gz → 0.89.0__tar.gz

{gea_program-0.87.0/gea_program.egg-info → gea_program-0.89.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.87.0
+Version: 0.89.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
@@ -847,7 +847,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.87.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.89.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -1022,6 +1022,57 @@ of review and the front. Run by a person, kept with the hash of its inputs,
 marked stale when they change. Every figure a SIMULATION. The
 **Calibration** tab, `gea calibrate`, `gea help calibration`.
 
+### Drilling roadmap
+
+What the fastest stands on the pad were drilled with, stretch by stretch.
+Every well's drilling record is cut into stands of 100 ft; each stand goes
+into the stretch of hole it was drilled in - 1,000 ft of true vertical
+depth down to the heel, 1,000 ft along the hole beyond it, named for the
+mapped formation where the workspace has the tops and the well its
+elevation. In each stretch the fastest quarter of the stands is found, and
+the window is what those stands ran: the weight on bit, the rotary speed,
+the flow, the differential pressure, beside the well that was fastest
+there and what every other well ran through the same rock. Then the
+roadmap checks itself: each well is set against the roadmap made from the
+others, the half of its stands nearer the window against the farther half,
+stretch by stretch - so the page says whether running nearer the window
+went with drilling faster, or did not, before anyone drills the next well
+from it. The **Roadmap** tab, `gea roadmap`, `gea help roadmap`.
+
+### Drilling alerts
+
+Three old driller's rules, written down so each is applied to every stand
+of every well the same way, and replayed over the whole of each record:
+the off-bottom pressure falling at a steady flow, connection after
+connection (a washout - or a pump, the mud or a nozzle; the trip finds
+which); the differential pressure spiking with the bit stopped (a motor
+stall); the pick-up and slack-off weight leaving their own trend (the hole
+getting tight). The page shows every reading, what each rule would have
+said and when, and what the rig did next - whether a trip out of the hole
+followed. The thresholds are settings, each changed with its source. On a
+record still being written an event raises an alert once. The **Drilling
+alerts** tab, `gea dysfunction`, `gea help dysfunction`.
+
+### Assistant access (MCP)
+
+The site, readable by an assistant. `gea mcp` is a Model Context Protocol
+server: a chat program that speaks MCP - Claude Desktop, or any other
+client - starts it as its own child process and is given the program's
+pages as tools: the site and its wells, the rig time, the roadmap, the
+drilling alerts, torque and drag, hydraulics, the fluid balance, the plume,
+the front and their calibration, frac hits, the alerts, the audit log, the
+help. Each tool returns what the program itself computes, with its own
+labels - SIMULATION where it is one, "nothing declared" where nothing is -
+so the assistant's account of the site is the program's. It is local: no
+port is opened, the conversation is the child process's standard input and
+output. It is read-only: no tool declares, attaches, removes, writes a
+report or changes a setting. It is logged: every call is a line in the
+workspace. And the site chooses which pages are offered, because what a
+tool returns goes to whoever runs the model behind the assistant. Both
+eras of the protocol are spoken: the stateless revision 2026-07-28 and the
+`initialize` handshake of 2025-11-25 and earlier. The **Assistant access**
+tab (one button adds it to Claude Desktop), `gea mcp`, `gea help mcp`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1686,7 +1737,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.87.0.exe` (for 0.87.0): the
+Every release also carries `GEA-Program-Setup-0.89.0.exe` (for 0.89.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1705,7 +1756,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.87.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.89.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.87.0 → gea_program-0.89.0}/README.md

@@ -808,7 +808,7 @@ unsigned, the key hand-overs - and shows the reports as they were signed. A
 reader made from the workspace knows the site's key fingerprints, so it
 says whether a dossier is the site's; it allows no network request, and it
 leaves the trusted time-stamp to `verify_dossier.py`. For a client who wants
-it installed, every release also carries `GEA-Reader-Setup-0.87.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.89.0.exe`: GEA
 Reader as a Windows program of its own - its own icon and taskbar button,
 Check with GEA Reader on a dossier's right-click menu, fingerprints the client
 saves kept on that computer, nothing of GEA-Program. `gea help reader`.
@@ -983,6 +983,57 @@ of review and the front. Run by a person, kept with the hash of its inputs,
 marked stale when they change. Every figure a SIMULATION. The
 **Calibration** tab, `gea calibrate`, `gea help calibration`.
 
+### Drilling roadmap
+
+What the fastest stands on the pad were drilled with, stretch by stretch.
+Every well's drilling record is cut into stands of 100 ft; each stand goes
+into the stretch of hole it was drilled in - 1,000 ft of true vertical
+depth down to the heel, 1,000 ft along the hole beyond it, named for the
+mapped formation where the workspace has the tops and the well its
+elevation. In each stretch the fastest quarter of the stands is found, and
+the window is what those stands ran: the weight on bit, the rotary speed,
+the flow, the differential pressure, beside the well that was fastest
+there and what every other well ran through the same rock. Then the
+roadmap checks itself: each well is set against the roadmap made from the
+others, the half of its stands nearer the window against the farther half,
+stretch by stretch - so the page says whether running nearer the window
+went with drilling faster, or did not, before anyone drills the next well
+from it. The **Roadmap** tab, `gea roadmap`, `gea help roadmap`.
+
+### Drilling alerts
+
+Three old driller's rules, written down so each is applied to every stand
+of every well the same way, and replayed over the whole of each record:
+the off-bottom pressure falling at a steady flow, connection after
+connection (a washout - or a pump, the mud or a nozzle; the trip finds
+which); the differential pressure spiking with the bit stopped (a motor
+stall); the pick-up and slack-off weight leaving their own trend (the hole
+getting tight). The page shows every reading, what each rule would have
+said and when, and what the rig did next - whether a trip out of the hole
+followed. The thresholds are settings, each changed with its source. On a
+record still being written an event raises an alert once. The **Drilling
+alerts** tab, `gea dysfunction`, `gea help dysfunction`.
+
+### Assistant access (MCP)
+
+The site, readable by an assistant. `gea mcp` is a Model Context Protocol
+server: a chat program that speaks MCP - Claude Desktop, or any other
+client - starts it as its own child process and is given the program's
+pages as tools: the site and its wells, the rig time, the roadmap, the
+drilling alerts, torque and drag, hydraulics, the fluid balance, the plume,
+the front and their calibration, frac hits, the alerts, the audit log, the
+help. Each tool returns what the program itself computes, with its own
+labels - SIMULATION where it is one, "nothing declared" where nothing is -
+so the assistant's account of the site is the program's. It is local: no
+port is opened, the conversation is the child process's standard input and
+output. It is read-only: no tool declares, attaches, removes, writes a
+report or changes a setting. It is logged: every call is a line in the
+workspace. And the site chooses which pages are offered, because what a
+tool returns goes to whoever runs the model behind the assistant. Both
+eras of the protocol are spoken: the stateless revision 2026-07-28 and the
+`initialize` handshake of 2025-11-25 and earlier. The **Assistant access**
+tab (one button adds it to Claude Desktop), `gea mcp`, `gea help mcp`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1647,7 +1698,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.87.0.exe` (for 0.87.0): the
+Every release also carries `GEA-Program-Setup-0.89.0.exe` (for 0.89.0): the
 same Windows kit installed like any Windows program, for the signed-in user
 alone and with no administrator rights (`%LOCALAPPDATA%\Programs\GEA-Program`).
 It asks for the site workspace (an existing one such as `C:\site` is used as
@@ -1666,7 +1717,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.87.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.89.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
 ```
 
 The setup is built by Inno Setup 6 from `tools/installer.iss` in the same

{gea_program-0.87.0 → gea_program-0.89.0}/gea/__init__.py

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

{gea_program-0.87.0 → gea_program-0.89.0}/gea/__main__.py

@@ -628,6 +628,24 @@ def main(argv=None) -> int:
     p_cb.add_argument("--write", action="store_true", help="write reports/calibration/calibration.json and .md from the kept result")
     p_cb.add_argument("--actor", type=str, default="cli")
     p_cb.add_argument("--json", action="store_true")
+    p_rm = sub.add_parser("roadmap", help="the drilling roadmap: for every stretch of hole, the weight on bit, rotary speed, flow and differential pressure the fastest quarter of the stands on the pad's wells were drilled with, which well was fastest there, and each well checked against the roadmap made from the others")
+    p_rm.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (three labelled wells through rock with a known best weight and speed)")
+    p_rm.add_argument("--well", type=str, default=None, help="the well the next stand is given for (default: the well whose record ends last)")
+    p_rm.add_argument("--write", action="store_true", help="write reports/roadmap/roadmap.json, .md and .csv")
+    p_rm.add_argument("--actor", type=str, default="cli")
+    p_rm.add_argument("--json", action="store_true")
+    p_dy = sub.add_parser("dysfunction", help="drilling alerts replayed over each well's record: the off-bottom pressure falling at a steady flow (a washout), the differential pressure spiking with the bit stopped (a motor stall), the pick-up weight leaving its own trend (the hole getting tight) - what each rule would have said, when, and whether a trip followed")
+    p_dy.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (a labelled record with a washout, three stalls and a tightening hole put in, and a sound one)")
+    p_dy.add_argument("--washout-fall", type=float, default=None, help="settings: the fall in off-bottom pressure that flags a reading, as a fraction (default 0.06)")
+    p_dy.add_argument("--washout-min-psi", type=float, default=None, help="settings: and the least fall in psi (default 100)")
+    p_dy.add_argument("--stall-rise", type=float, default=None, help="settings: the rise in differential pressure over its median that is a stall, as a fraction (default 0.6)")
+    p_dy.add_argument("--stall-min-psi", type=float, default=None, help="settings: and the least rise in psi (default 300)")
+    p_dy.add_argument("--drag-sigma", type=float, default=None, help="settings: how many scatters off its trend a pick-up or slack-off weight is flagged at (default 3)")
+    p_dy.add_argument("--drag-min-klbf", type=float, default=None, help="settings: and the least distance in klbf (default 10)")
+    p_dy.add_argument("--source", type=str, default="", help="who set a changed setting and on what grounds")
+    p_dy.add_argument("--write", action="store_true", help="write reports/dysfunction/drilling_alerts.json, .md and events.csv")
+    p_dy.add_argument("--actor", type=str, default="cli")
+    p_dy.add_argument("--json", action="store_true")
     p_os = sub.add_parser("seismicity", help="operations and seismicity: each well's drilling, completion and disposal windows against the earthquake catalogue around it - the events during and after each, the levels a regulator's protocol would reach, and the rate during operations against the rest of the record; the Mahoning Valley worked example")
     p_os.add_argument("--workspace", type=str, default=None)
     p_os.add_argument("--scene", type=str, default=None, choices=("workspace", "mahoning"), help="your wells (the default with --workspace) or the public worked example")
@@ -659,6 +677,21 @@ def main(argv=None) -> int:
     p_os.add_argument("--actor", type=str, default="cli")
     p_os.add_argument("--json", action="store_true")
 
+    p_mc = sub.add_parser("mcp", help="the site, readable by an assistant: a Model Context Protocol server on standard input and output - local (no port), read-only (every tool reads one of the program's pages, none changes anything), logged; with --workspace alone it serves until its input closes")
+    p_mc.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs (both eras of the protocol against a labelled site)")
+    p_mc.add_argument("--allow", type=str, default=None, help="serve only these tools this run, comma-separated (never more than the site offers)")
+    p_mc.add_argument("--status", action="store_true", help="print the tools offered, how to start the server and the last calls, and exit")
+    p_mc.add_argument("--config", action="store_true", help="print the entry an MCP client's configuration needs to start this site's server, and exit")
+    p_mc.add_argument("--call", type=str, default=None, help="call one tool and print its answer, as an assistant would get it")
+    p_mc.add_argument("--well", type=str, default=None, help="--call: the well, by name or id")
+    p_mc.add_argument("--topic", type=str, default=None, help="--call help: the topic")
+    p_mc.add_argument("--json", action="store_true", help="--call: the page as JSON instead of its text")
+    p_mc.add_argument("--offer", type=str, default=None, help="settings: the tools the site offers, comma-separated (all: every tool)")
+    p_mc.add_argument("--max-chars", type=int, default=None, help="settings: the most characters one answer carries (default 40000)")
+    p_mc.add_argument("--source", type=str, default="", help="settings: who decided, and on what grounds")
+    p_mc.add_argument("--add-to-claude-desktop", action="store_true", help="add this site's server to Claude Desktop's configuration on this computer, keeping every other entry and a dated copy of the file")
+    p_mc.add_argument("--remove-from-claude-desktop", action="store_true", help="take it out again")
+    p_mc.add_argument("--actor", type=str, default="cli")
     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")
@@ -2832,6 +2865,52 @@ def main(argv=None) -> int:
             raise SystemExit(f"calibrate: {e.args[0] if e.args else e}")
         print(_json.dumps(p, default=str) if a.json else _CB.text(p))
         return 0
+    elif a.cmd == "roadmap":
+        import json as _json
+        from . import roadmap as _RM
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            r = _RM.selftest()
+            print(_json.dumps(r, default=str) if a.json else "\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']}")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+            if a.write:
+                from . import __version__ as _ver88r
+                r = _RM.write_report(ws, _ver88r, a.actor)
+                print(f"written: {', '.join(r['files'])} under {r['folder']}")
+            p = _RM.page(ws, a.well)
+        except (_RM.RoadmapError, WorkspaceError, ValueError, OSError) as e:
+            raise SystemExit(f"roadmap: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _RM.text(p))
+        return 0
+    elif a.cmd == "dysfunction":
+        import json as _json
+        from . import dysfunction as _DY
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            r = _DY.selftest()
+            print(_json.dumps(r, default=str) if a.json else "\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']}")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+            kw_ = {"washout_fall": a.washout_fall, "washout_min_psi": a.washout_min_psi, "stall_rise": a.stall_rise, "stall_min_psi": a.stall_min_psi, "drag_sigma": a.drag_sigma, "drag_min_klbf": a.drag_min_klbf}
+            if any(v is not None for v in kw_.values()):
+                st_ = _DY.set_settings(ws, a.actor, a.source, **kw_)
+                print("settings: " + ", ".join(f"{k} {st_[k]:g}" for k in _DY.DEFAULTS))
+            if a.write:
+                from . import __version__ as _ver88d
+                r = _DY.write_report(ws, _ver88d, a.actor)
+                print(f"written: {', '.join(r['files'])} under {r['folder']}")
+            p = _DY.page(ws)
+        except (_DY.DysfunctionError, WorkspaceError, ValueError, OSError) as e:
+            raise SystemExit(f"dysfunction: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _DY.text(p))
+        return 0
     elif a.cmd == "seismicity":
         import json as _json
         from . import op_seismicity as _OS
@@ -3496,6 +3575,50 @@ 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 == "mcp":
+        import json as _json
+        from . import mcp_server as _MC
+        from .workspace import Workspace, WorkspaceError
+        allow_ = [t_.strip() for t_ in a.allow.split(",") if t_.strip()] if a.allow else None
+        if not a.workspace:
+            r = _MC.selftest()
+            print("\n".join(f"{'PASS' if c['pass'] else 'FAIL'}  {c['check']}: {c['value']}" for c in r["checks"]) + f"\n{'OK' if r['ok'] else 'FAILED'} - {r['label']}")
+            return 0 if r["ok"] else 1
+        try:
+            ws = Workspace(a.workspace)
+        except WorkspaceError as e:
+            print(f"mcp: {e}", file=sys.stderr)                 # the error stream: standard output is the protocol's
+            return 2
+        if not (a.status or a.config or a.call or a.offer or a.max_chars is not None or a.add_to_claude_desktop or a.remove_from_claude_desktop):
+            return _MC.serve(ws, allow=allow_)                  # the server: nothing but protocol messages on standard output
+        from .cli import _safe_stdout
+        _safe_stdout()
+        try:
+            if a.offer or a.max_chars is not None:
+                st_ = _MC.set_settings(ws, a.actor, (list(_MC.NAMES) if a.offer and a.offer.strip().lower() == "all" else a.offer), a.max_chars, a.source)
+                print(f"offered: {', '.join(_MC.offered(ws))}; an answer carries {st_['max_chars']:,} characters at most")
+            if a.add_to_claude_desktop or a.remove_from_claude_desktop:
+                r = _MC.install_claude_desktop(ws, a.actor, remove=a.remove_from_claude_desktop)
+                for d_ in r["done"]:
+                    print(f"{'taken out of' if r['removed'] else 'added to'} {d_['path']}" + (f" (as it was: {d_['backup']})" if d_["backup"] else "") + " - quit Claude Desktop and start it again")
+                for d_ in r["skipped"]:
+                    print(f"not changed: {d_['path']} - {d_['why']}")
+            if a.config:
+                print(_json.dumps(_MC.client_config(ws.path, allow_), indent=2))
+            if a.call:
+                if a.call not in _MC.offered(ws, allow_):
+                    raise SystemExit(f"mcp: no tool {a.call!r} is offered; offered: {', '.join(_MC.offered(ws, allow_))}")
+                args_ = {k: v for k, v in (("well", a.well), ("topic", a.topic)) if v is not None}
+                if a.json:
+                    args_["json"] = True
+                r = _MC.call_tool(ws, a.call, args_, _MC.settings(ws)["max_chars"])
+                print(r["text"])
+                return 1 if r["is_error"] else 0
+            if a.status:
+                print(_MC.text(_MC.page(ws)))
+        except (_MC.ToolError, WorkspaceError, OSError) as e:
+            raise SystemExit(f"mcp: {e.args[0] if e.args else e}")
+        return 0
     elif a.cmd == "alerts":
         import json as _json
         from . import alerts as _AL