gea-program 0.88.0__tar.gz → 0.90.0__tar.gz

{gea_program-0.88.0/gea_program.egg-info → gea_program-0.90.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.88.0
+Version: 0.90.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.88.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.90.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`.
@@ -1053,6 +1053,83 @@ 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`.
+
+### Benchmark
+
+The wells of a pad against one another, and each against the best the pad
+has done. Every well with a drilling record is measured the same way from
+its own record - the footage, the days from its first stand to its last,
+feet per day, the rate on bottom, rotary and sliding, the median connection
+weight to weight, the trip speeds - and ranked on each count. Then each
+well is set against the pad's best: the well it would have been had every
+stretch of hole been drilled at the rate of whichever well was fastest
+through that stretch (300 ft or more of it), and every connection made in
+the pad's best quarter. The gap is hours the pad has already shown can be
+saved, on some well in that stretch - not a forecast, and not a cause: the
+bit, the motor, the mud and the hole size are not in the record. The
+**Benchmark** tab, `gea benchmark`, `gea help benchmark`; an assistant
+reads it as the `benchmark` tool.
+
+### Public data: a real pad
+
+A pad anyone may check. The Utah FORGE project - the U.S. Department of
+Energy's geothermal field laboratory near Milford, Utah - publishes the
+rig recorders of five wells drilled through the same basin fill and
+granite between 2017 and 2023, under Creative Commons Attribution 4.0.
+`gea public-pad` turns those files into a site of its own, so the rig
+time, the roadmap, the drilling alerts and the benchmark run on real
+records before any client's. The program does not contain the files and
+does not fetch them: the site downloads them in a browser from the
+Geothermal Data Repository, names the folder, and the program checks each
+file against the size and the SHA-256 it had when this release was checked
+with it, converts the three layouts that are not the recorder's own
+export, attaches each well, and keeps on the record what was done to
+each - 16A(78)-32's bit depth is RECONSTRUCTED from the block and the
+slips and is marked so on every page. Every page and report of that site
+ends with the credit the licence asks for.
+
+What this release made of them, on the five files as published:
+
+| Well | Drilled, ft | Days | ft/day | On bottom, ft/h | Median connection, min |
+|---|---|---|---|---|---|
+| 58-32 (2017) | 6,288 | 43.5 | 145 | 15.9 | 14.4 |
+| 16A(78)-32 (2020) | 11,035 | 67.8 | 163 | 34.4 | 11.3 |
+| 56-32 (2021) | 9,232 | 19.0 | 487 | 46.6 | 7.5 |
+| 78B-32 (2021) | 9,372 | 29.1 | 322 | 84.7 | 7.7 |
+| 16B(78)-32 (2023) | 10,490 | 52.4 | 200 | 45.7 | 10.2 |
+
+Against the pad's best the five wells spent 812 of their 1,256 on-bottom
+hours beyond it. The roadmap's own check on them is split - running nearer
+the window was the faster half on two wells and the slower on two - which
+is the page saying, of wells drilled six years apart in three hole sizes,
+that one well's parameters are not the next well's roadmap. The drilling
+alerts, replayed, find 27 motor stalls on the three wells whose records
+can show one, three falls in off-bottom pressure on 78B-32 that no trip followed
+and one on 58-32 that a trip out of the hole followed within twelve hours.
+Data: Utah FORGE, Energy & Geoscience Institute at the University of Utah,
+funded by the U.S. Department of Energy; Geothermal Data Repository,
+gdr.openei.org; CC BY 4.0. The **Public data** tab, `gea public-pad`,
+`gea help public-data`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1717,7 +1794,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.88.0.exe` (for 0.88.0): the
+Every release also carries `GEA-Program-Setup-0.90.0.exe` (for 0.90.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
@@ -1736,7 +1813,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.90.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.88.0 → gea_program-0.90.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.88.0.exe`: GEA
+it installed, every release also carries `GEA-Reader-Setup-0.90.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`.
@@ -1014,6 +1014,83 @@ 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`.
+
+### Benchmark
+
+The wells of a pad against one another, and each against the best the pad
+has done. Every well with a drilling record is measured the same way from
+its own record - the footage, the days from its first stand to its last,
+feet per day, the rate on bottom, rotary and sliding, the median connection
+weight to weight, the trip speeds - and ranked on each count. Then each
+well is set against the pad's best: the well it would have been had every
+stretch of hole been drilled at the rate of whichever well was fastest
+through that stretch (300 ft or more of it), and every connection made in
+the pad's best quarter. The gap is hours the pad has already shown can be
+saved, on some well in that stretch - not a forecast, and not a cause: the
+bit, the motor, the mud and the hole size are not in the record. The
+**Benchmark** tab, `gea benchmark`, `gea help benchmark`; an assistant
+reads it as the `benchmark` tool.
+
+### Public data: a real pad
+
+A pad anyone may check. The Utah FORGE project - the U.S. Department of
+Energy's geothermal field laboratory near Milford, Utah - publishes the
+rig recorders of five wells drilled through the same basin fill and
+granite between 2017 and 2023, under Creative Commons Attribution 4.0.
+`gea public-pad` turns those files into a site of its own, so the rig
+time, the roadmap, the drilling alerts and the benchmark run on real
+records before any client's. The program does not contain the files and
+does not fetch them: the site downloads them in a browser from the
+Geothermal Data Repository, names the folder, and the program checks each
+file against the size and the SHA-256 it had when this release was checked
+with it, converts the three layouts that are not the recorder's own
+export, attaches each well, and keeps on the record what was done to
+each - 16A(78)-32's bit depth is RECONSTRUCTED from the block and the
+slips and is marked so on every page. Every page and report of that site
+ends with the credit the licence asks for.
+
+What this release made of them, on the five files as published:
+
+| Well | Drilled, ft | Days | ft/day | On bottom, ft/h | Median connection, min |
+|---|---|---|---|---|---|
+| 58-32 (2017) | 6,288 | 43.5 | 145 | 15.9 | 14.4 |
+| 16A(78)-32 (2020) | 11,035 | 67.8 | 163 | 34.4 | 11.3 |
+| 56-32 (2021) | 9,232 | 19.0 | 487 | 46.6 | 7.5 |
+| 78B-32 (2021) | 9,372 | 29.1 | 322 | 84.7 | 7.7 |
+| 16B(78)-32 (2023) | 10,490 | 52.4 | 200 | 45.7 | 10.2 |
+
+Against the pad's best the five wells spent 812 of their 1,256 on-bottom
+hours beyond it. The roadmap's own check on them is split - running nearer
+the window was the faster half on two wells and the slower on two - which
+is the page saying, of wells drilled six years apart in three hole sizes,
+that one well's parameters are not the next well's roadmap. The drilling
+alerts, replayed, find 27 motor stalls on the three wells whose records
+can show one, three falls in off-bottom pressure on 78B-32 that no trip followed
+and one on 58-32 that a trip out of the hole followed within twelve hours.
+Data: Utah FORGE, Energy & Geoscience Institute at the University of Utah,
+funded by the U.S. Department of Energy; Geothermal Data Repository,
+gdr.openei.org; CC BY 4.0. The **Public data** tab, `gea public-pad`,
+`gea help public-data`.
+
 ### Plan vs actual and the survey tools
 
 Each well against its directional plan: at every survey station, how far
@@ -1678,7 +1755,7 @@ attaches the zips to the GitHub release of that tag.
 
 ### The Windows installer
 
-Every release also carries `GEA-Program-Setup-0.88.0.exe` (for 0.88.0): the
+Every release also carries `GEA-Program-Setup-0.90.0.exe` (for 0.90.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
@@ -1697,7 +1774,7 @@ it, removes the program and leaves the workspace. Silent, for a site's
 software deployment:
 
 ```
-GEA-Program-Setup-0.88.0.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /WORKSPACE="C:\site" /SITENAME="Pad 3" /TASKS="desktopicon"
+GEA-Program-Setup-0.90.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.88.0 → gea_program-0.90.0}/gea/__init__.py

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

{gea_program-0.88.0 → gea_program-0.90.0}/gea/__main__.py

@@ -677,6 +677,34 @@ def main(argv=None) -> int:
     p_os.add_argument("--actor", type=str, default="cli")
     p_os.add_argument("--json", action="store_true")
 
+    p_bm = sub.add_parser("benchmark", help="the wells of a pad against one another: feet per day, on-bottom rate, connections and trips ranked, and each well against the pad's best - every stretch at the rate of the fastest well through it")
+    p_bm.add_argument("--workspace", type=str, default=None, help="the workspace folder; without one the self-test runs")
+    p_bm.add_argument("--write", action="store_true", help="write reports/benchmark/benchmark.json, .md, .csv and stretches.csv")
+    p_bm.add_argument("--actor", type=str, default="cli")
+    p_bm.add_argument("--json", action="store_true")
+    p_pp = sub.add_parser("public-pad", help="a real pad from public data: the Utah FORGE wells' published rig recorders (CC BY 4.0) made into a site of their own - the files to get and where, checked against their sizes and hashes, converted and attached; the program fetches nothing")
+    p_pp.add_argument("--folder", type=str, default=None, help="the folder the downloaded files are in; with nothing else, lists each file and whether it is there. Without a folder the self-test runs (stand-ins in each published layout)")
+    p_pp.add_argument("--verify", action="store_true", help="hash each file that is there against the SHA-256 this release was checked with")
+    p_pp.add_argument("--build", action="store_true", help="make the site at --site from the files in --folder, or add to it the wells it does not have yet")
+    p_pp.add_argument("--site", type=str, default=None, help="--build: the folder the site's workspace is made in")
+    p_pp.add_argument("--list", action="store_true", help="list the dataset's files, sizes, hashes and where each is published, and exit")
+    p_pp.add_argument("--actor", type=str, default="cli")
+    p_pp.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")
@@ -3560,6 +3588,102 @@ 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 == "benchmark":
+        import json as _json
+        from . import benchmark as _BM
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        if not a.workspace:
+            r = _BM.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)
+            if a.write:
+                from . import __version__ as _ver90b
+                r = _BM.write_report(ws, _ver90b, a.actor)
+                print(f"written: {', '.join(r['files'])} under {r['folder']}")
+            p = _BM.page(ws)
+        except (_BM.BenchmarkError, WorkspaceError, ValueError, OSError) as e:
+            raise SystemExit(f"benchmark: {e.args[0] if e.args else e}")
+        print(_json.dumps(p, default=str) if a.json else _BM.text(p))
+        return 0
+    elif a.cmd == "public-pad":
+        import json as _json
+        from . import public_pad as _PP
+        from .cli import _safe_stdout
+        _safe_stdout()
+        if not a.folder and not a.list:
+            r = _PP.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:
+            if a.build:
+                if not a.site:
+                    raise SystemExit("public-pad: --build needs --site, the folder the site is made in")
+                last_ = {"t": ""}
+
+                def say_(d_):
+                    t_ = f"{d_.get('well', '')} {d_.get('step', '')}".strip()
+                    if t_ != last_["t"] and d_.get("step") != "done":
+                        last_["t"] = t_
+                        print(f"  {d_.get('n', '')}/{d_.get('of', '')} {t_}", flush=True)
+                r = _PP.build(a.folder, a.site, a.actor, verify=True, progress=say_)
+                print(f"{r['name']} at {r['path']}: " + (f"added {', '.join(r['added'])}" if r["added"] else "nothing to add") + f"; it has {', '.join(r['wells'])}")
+                for e_ in r["record"]["wells"]:
+                    for n_ in e_["notes"]:
+                        print(f"  {e_['well']}: {n_}")
+                return 0
+            s_ = _PP.status(a.folder or "", verify=a.verify)
+        except (_PP.PublicPadError, OSError) as e:
+            raise SystemExit(f"public-pad: {e.args[0] if e.args else e}")
+        print(_json.dumps(s_, default=str) if a.json else _PP.text(s_))
+        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