gea-program 0.1.0__tar.gz → 0.2.0__tar.gz

{gea_program-0.1.0/gea_program.egg-info → gea_program-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.1.0
+Version: 0.2.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
@@ -22,6 +22,16 @@ Requires-Dist: PyQt6>=6.5; extra == "desktop"
 Requires-Dist: matplotlib>=3.7; extra == "desktop"
 Provides-Extra: modbus
 Requires-Dist: pymodbus>=3.0; extra == "modbus"
+Provides-Extra: opcua
+Requires-Dist: asyncua>=1.0; extra == "opcua"
+Provides-Extra: mqtt
+Requires-Dist: paho-mqtt>=2.0; extra == "mqtt"
+Provides-Extra: live
+Requires-Dist: asyncua>=1.0; extra == "live"
+Requires-Dist: paho-mqtt>=2.0; extra == "live"
+Requires-Dist: pymodbus>=3.0; extra == "live"
+Provides-Extra: xls
+Requires-Dist: xlrd>=2.0; extra == "xls"
 Dynamic: license-file
 
 # GEA-Program
@@ -59,6 +69,12 @@ reaches a client document. Nothing unmeasured is ever reported as met.
   rate-controlled replay, duplicate suppression, per-record latency.
 - **Configuration versioning, SBOM, monthly SLA, FAT/SAT**
   (`config_versioning.py`, `sbom.py`, `sla_report.py`, `fat_sat.py`).
+- **Live protocol ports** (`live_ports.py`, `opcua_port.py`, `mqtt_port.py`):
+  read-only OPC UA client (read and subscribe) and MQTT subscriber (plain
+  number, JSON and Sparkplug B payloads, Sparkplug decoded with no protobuf
+  library); every message becomes a measurement record with its source
+  timestamp, ingest timestamp and quality flag; every session can be recorded
+  and replayed offline. See *Live data* below.
 - **Dashboard** (`dashboard.py`): tiles, well ranking, alarm wall, drill-down to
   every report; light and dark; status is always an icon with a label.
 - **Survey track** (`earth_model.py`, `strata_join.py`, `inverse_engine.py`,
@@ -75,7 +91,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (157 checks)
+gea accept                     # the product gate (172 checks)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
 ```
@@ -83,28 +99,62 @@ gea gui                        # the desktop window (pip install "gea-program[de
 `gea` is the front door (`gea/cli.py`); every other subcommand passes through to
 `python -m gea`. PATH-proof form: `python -m gea.cli ...`. Open `dashboard/index.html`.
 
+## Live data
+
+The engine reads live data through two protocol ports. Both are **read-only**,
+both map only what the site declares (a tag map the client owns; an empty map
+is declined), and both write every received message to a JSON-lines recording
+that `--replay` turns back into records without a connection - which is how a
+site session is reproduced offline and how the mapping logic is tested.
+
+```
+pip install "gea-program[live]"                       # asyncua + paho-mqtt (or [opcua] / [mqtt] alone)
+gea opcua --write-example-config opcua.json           # edit: endpoint, security, credential env names, nodes
+gea opcua --config opcua.json --read-once --out opc   # one read of every mapped node
+gea opcua --config opcua.json --seconds 60 --record opc/session.jsonl --out opc --stream-csv opc/stream.csv
+gea mqtt  --write-example-config mqtt.json            # edit: broker, TLS, credential env names, topics
+gea mqtt  --config mqtt.json --seconds 60 --record mq/session.jsonl --out mq --stream-csv mq/stream.csv
+gea mqtt  --config mqtt.json --replay mq/session.jsonl --out mq_replay     # no broker needed
+gea ingest --file mq/stream.csv                       # the stream CSV feeds the historian port like any other
+```
+
+| port | transport | quality | timestamps |
+|---|---|---|---|
+| `opcua` | opc.tcp, read + subscribe; Basic256Sha256 SignAndEncrypt when a certificate and key are given | StatusCode severity bits: Good -> GOOD, Uncertain -> STALE, Bad -> GAP (value withheld); the rule names the code | source timestamp, else server timestamp, else arrival; ingest stamped at arrival |
+| `mqtt` | MQTT v5 / v3.1.1, TLS optional, QoS per topic; `+`/`#` wildcards | number: GOOD or GAP (unparseable, reason kept); JSON: value/time/quality paths and the list of good values; Sparkplug B: `is_null` -> GAP, `Quality` property != 192 -> STALE | JSON time path (ISO / epoch s / epoch ms), Sparkplug metric timestamp, else arrival |
+
+Credentials never sit in a config file: the file names the environment variables
+that hold them (`GEA_OPCUA_USER`, `GEA_MQTT_PASSWORD`, ...). Sparkplug B aliases
+are learned from any NBIRTH/DBIRTH on the matching edge node, so alias-only DDATA
+resolves. The example configs are in `docs/examples/`; the acceptance suite
+section AB covers the codec, the mappings, the quality rules, replay and the
+hand-off to the store-and-forward buffer, and runs a live in-process OPC UA
+loopback wherever `asyncua` is installed.
+
 ## Layout
 
 ```
 gea/            the package: engines, record layer, reports, monitor, dashboard, cli, shell, acceptance suite
 gea/catalog/    52 public archive entries, each with a provenance file
-docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports),
-                commercial/ (pilot proposal, bench readiness, renders), HISTORY.md (development history)
-tools/          import_from_star_magic.py (the importer), register_audit.py, native/ (cli.py, shell.py sources)
-tests/          pytest wrapper around the acceptance suite and the no-corpus check
+docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports), examples/ (port configs),
+                SESSION_LOG.md (the working record, session by session),
+                commercial/ (pilot proposal, bench readiness, commercial use), HISTORY.md (the ship-by-ship record)
+tools/          standalone_check.py (the self-contained guard: imports, text, metadata; run by ci and ship.ps1)
+CHANGELOG.md    per-release summary (a tag ships only with its section); SHIP_LOG.md is written by ship.ps1
+tests/          pytest wrapper around the acceptance suite and the standalone check
 ```
 
-## Where the code came from
+## Basis
 
-The package was imported from the `uqff_downhole_simulator` package of the
-Star-Magic-Program repository by `tools/import_from_star_magic.py`, which renames
-the modules, removes every dependency on that repository's physics corpus, puts
-the gravity kernel on standard constants (CODATA 2018 G, standard gravity, IUGG
-mean radius), keeps the rock inventory's seventeen published density anchors and
-Vp ranges without their decompositions, and drops the two modules that existed
-only to compose numbers from that corpus. `gea/IMPORT_RECORD.md` lists the
-source commit and every file's hash. `tools/register_audit.py` lists what
-remains of the source program's vocabulary in comments and docstrings.
+GEA-Program is a self-contained package: every module imports only the
+standard library, numpy, the declared optional extras and the package itself,
+and `tools/standalone_check.py` (run by CI and by `ship.ps1`) fails the build
+if that ever changes or if a tracked file names another program. The physics
+is on standard constants - CODATA 2018 G, standard gravity 9.80665 m/s2, the
+IUGG mean Earth radius - and the rock inventory carries seventeen published
+density anchors and Vp ranges with their citations (Telford, Geldart and
+Sheriff; Schon). Every catalogue entry under `gea/catalog/` has a provenance
+file naming its public source.
 
 Two statements the product carries on its own model cards: the gauge aging
 envelope's lower bound is an engineering model with no field validation on
@@ -117,7 +167,8 @@ ACCEPTABLE at the 95 % target. Both are printed, never claimed otherwise.
 `pyproject.toml` must equal `gea.__version__` (`-Bump x.y.z` sets both), the tag must
 not exist anywhere, every version in `SHIP_LOG.md` must have its tag, `python -m gea
 accept` must be green, `SHIP_MESSAGE.txt` must start with the tag; then commit, tag,
-push, and the remote tag must be seen before SHIPPED is printed. `-DryRun` runs every
+push, and the remote tag must be seen before SHIPPED is printed. `CHANGELOG.md` must carry a
+section headed by the tag, and `tools/standalone_check.py` must report no findings. `-DryRun` runs every
 check and changes nothing; `-NoPush` stops after the local tag.
 
 ## Publishing to PyPI

{gea_program-0.1.0 → gea_program-0.2.0}/README.md

@@ -33,6 +33,12 @@ reaches a client document. Nothing unmeasured is ever reported as met.
   rate-controlled replay, duplicate suppression, per-record latency.
 - **Configuration versioning, SBOM, monthly SLA, FAT/SAT**
   (`config_versioning.py`, `sbom.py`, `sla_report.py`, `fat_sat.py`).
+- **Live protocol ports** (`live_ports.py`, `opcua_port.py`, `mqtt_port.py`):
+  read-only OPC UA client (read and subscribe) and MQTT subscriber (plain
+  number, JSON and Sparkplug B payloads, Sparkplug decoded with no protobuf
+  library); every message becomes a measurement record with its source
+  timestamp, ingest timestamp and quality flag; every session can be recorded
+  and replayed offline. See *Live data* below.
 - **Dashboard** (`dashboard.py`): tiles, well ranking, alarm wall, drill-down to
   every report; light and dark; status is always an icon with a label.
 - **Survey track** (`earth_model.py`, `strata_join.py`, `inverse_engine.py`,
@@ -49,7 +55,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (157 checks)
+gea accept                     # the product gate (172 checks)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
 ```
@@ -57,28 +63,62 @@ gea gui                        # the desktop window (pip install "gea-program[de
 `gea` is the front door (`gea/cli.py`); every other subcommand passes through to
 `python -m gea`. PATH-proof form: `python -m gea.cli ...`. Open `dashboard/index.html`.
 
+## Live data
+
+The engine reads live data through two protocol ports. Both are **read-only**,
+both map only what the site declares (a tag map the client owns; an empty map
+is declined), and both write every received message to a JSON-lines recording
+that `--replay` turns back into records without a connection - which is how a
+site session is reproduced offline and how the mapping logic is tested.
+
+```
+pip install "gea-program[live]"                       # asyncua + paho-mqtt (or [opcua] / [mqtt] alone)
+gea opcua --write-example-config opcua.json           # edit: endpoint, security, credential env names, nodes
+gea opcua --config opcua.json --read-once --out opc   # one read of every mapped node
+gea opcua --config opcua.json --seconds 60 --record opc/session.jsonl --out opc --stream-csv opc/stream.csv
+gea mqtt  --write-example-config mqtt.json            # edit: broker, TLS, credential env names, topics
+gea mqtt  --config mqtt.json --seconds 60 --record mq/session.jsonl --out mq --stream-csv mq/stream.csv
+gea mqtt  --config mqtt.json --replay mq/session.jsonl --out mq_replay     # no broker needed
+gea ingest --file mq/stream.csv                       # the stream CSV feeds the historian port like any other
+```
+
+| port | transport | quality | timestamps |
+|---|---|---|---|
+| `opcua` | opc.tcp, read + subscribe; Basic256Sha256 SignAndEncrypt when a certificate and key are given | StatusCode severity bits: Good -> GOOD, Uncertain -> STALE, Bad -> GAP (value withheld); the rule names the code | source timestamp, else server timestamp, else arrival; ingest stamped at arrival |
+| `mqtt` | MQTT v5 / v3.1.1, TLS optional, QoS per topic; `+`/`#` wildcards | number: GOOD or GAP (unparseable, reason kept); JSON: value/time/quality paths and the list of good values; Sparkplug B: `is_null` -> GAP, `Quality` property != 192 -> STALE | JSON time path (ISO / epoch s / epoch ms), Sparkplug metric timestamp, else arrival |
+
+Credentials never sit in a config file: the file names the environment variables
+that hold them (`GEA_OPCUA_USER`, `GEA_MQTT_PASSWORD`, ...). Sparkplug B aliases
+are learned from any NBIRTH/DBIRTH on the matching edge node, so alias-only DDATA
+resolves. The example configs are in `docs/examples/`; the acceptance suite
+section AB covers the codec, the mappings, the quality rules, replay and the
+hand-off to the store-and-forward buffer, and runs a live in-process OPC UA
+loopback wherever `asyncua` is installed.
+
 ## Layout
 
 ```
 gea/            the package: engines, record layer, reports, monitor, dashboard, cli, shell, acceptance suite
 gea/catalog/    52 public archive entries, each with a provenance file
-docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports),
-                commercial/ (pilot proposal, bench readiness, renders), HISTORY.md (development history)
-tools/          import_from_star_magic.py (the importer), register_audit.py, native/ (cli.py, shell.py sources)
-tests/          pytest wrapper around the acceptance suite and the no-corpus check
+docs/           TESTER_GUIDE.md, REQUIREMENTS_MATRIX.md (the scope-of-work mirror that shaped the reports), examples/ (port configs),
+                SESSION_LOG.md (the working record, session by session),
+                commercial/ (pilot proposal, bench readiness, commercial use), HISTORY.md (the ship-by-ship record)
+tools/          standalone_check.py (the self-contained guard: imports, text, metadata; run by ci and ship.ps1)
+CHANGELOG.md    per-release summary (a tag ships only with its section); SHIP_LOG.md is written by ship.ps1
+tests/          pytest wrapper around the acceptance suite and the standalone check
 ```
 
-## Where the code came from
+## Basis
 
-The package was imported from the `uqff_downhole_simulator` package of the
-Star-Magic-Program repository by `tools/import_from_star_magic.py`, which renames
-the modules, removes every dependency on that repository's physics corpus, puts
-the gravity kernel on standard constants (CODATA 2018 G, standard gravity, IUGG
-mean radius), keeps the rock inventory's seventeen published density anchors and
-Vp ranges without their decompositions, and drops the two modules that existed
-only to compose numbers from that corpus. `gea/IMPORT_RECORD.md` lists the
-source commit and every file's hash. `tools/register_audit.py` lists what
-remains of the source program's vocabulary in comments and docstrings.
+GEA-Program is a self-contained package: every module imports only the
+standard library, numpy, the declared optional extras and the package itself,
+and `tools/standalone_check.py` (run by CI and by `ship.ps1`) fails the build
+if that ever changes or if a tracked file names another program. The physics
+is on standard constants - CODATA 2018 G, standard gravity 9.80665 m/s2, the
+IUGG mean Earth radius - and the rock inventory carries seventeen published
+density anchors and Vp ranges with their citations (Telford, Geldart and
+Sheriff; Schon). Every catalogue entry under `gea/catalog/` has a provenance
+file naming its public source.
 
 Two statements the product carries on its own model cards: the gauge aging
 envelope's lower bound is an engineering model with no field validation on
@@ -91,7 +131,8 @@ ACCEPTABLE at the 95 % target. Both are printed, never claimed otherwise.
 `pyproject.toml` must equal `gea.__version__` (`-Bump x.y.z` sets both), the tag must
 not exist anywhere, every version in `SHIP_LOG.md` must have its tag, `python -m gea
 accept` must be green, `SHIP_MESSAGE.txt` must start with the tag; then commit, tag,
-push, and the remote tag must be seen before SHIPPED is printed. `-DryRun` runs every
+push, and the remote tag must be seen before SHIPPED is printed. `CHANGELOG.md` must carry a
+section headed by the tag, and `tools/standalone_check.py` must report no findings. `-DryRun` runs every
 check and changes nothing; `-NoPush` stops after the local tag.
 
 ## Publishing to PyPI

{gea_program-0.1.0 → gea_program-0.2.0}/gea/BENCH_TEST_PROTOCOL.md

@@ -1,10 +1,9 @@
 # Bench-Test Protocol — Measuring the 1.0324 Suppression Ratio
 
-**Field-tier step 8 (independent evaluation, adopted 2026-08-27).**
 Status of the quantity under test: `canonical_suppression()` = **1.0324 at
 unity trims** is today a **DERIVED_HYBRID** composition — industry baseline
 drift (0.215 %FS/yr class) with HPHT stress dressing, divided by a
-locked-primitive GEA composition. It is **not** a measured constant, and the
+the program's suppression composition of three locked constants. It is **not** a measured constant, and the
 product labels it so everywhere it appears. This protocol is the experiment
 that would change — or refuse to change — that label.
 
@@ -77,7 +76,7 @@ product's own honesty rule.
 
 - **Confirmed:** `canonical_suppression()`'s label may move from
   DERIVED_HYBRID to MEASURED_ON_BENCH **with the test ID, dates, apparatus
-  and per-pair results attached**. The composition's primitives are then a
+  and per-pair results attached**. The composition's constants are then a
   measured-consistent model, not just a labeled one.
 - **Refuted:** the label stays DERIVED_HYBRID; the refutation (conditions,
   measured R, uncertainty) is recorded beside it. No silent retuning of

{gea_program-0.1.0 → gea_program-0.2.0}/gea/__init__.py

@@ -8,10 +8,10 @@ deep-well (TD ~20,300 ft) six-gauge quartz P/T string with GEA-stabilized
 drift, transient events, live animation (matplotlib / optional PyQt6), and
 CSV export.
 
-Provenance: ported 2026-08-22 (Daniel GO) from the 22Aug2026 Grok thread
-template (grok_cce7a73b); canonical primitives locked, template tuning knobs
-renamed to engineering trims per the knob ruling. See README.md and
-PAPER_2256.
+The program aging model composes a fixed drift-suppression factor from three
+locked engineering constants (K_MEX = 25/12, PHI_RES = 0.84, F_TRZ = 0.1); the
+user-facing settings are the two instrument trims (k_structural_trim,
+phi_coupling_trim), never the constants. See README.md.
 
 Quick use (headless):
     from gea import DownholeEngine, SimulatorConfig
@@ -97,6 +97,8 @@ from .modbus import (
     RegisterMap,
     load_register_map,
 )
+from .opcua_port import ASYNCUA_AVAILABLE, OpcUaTap          # registers the 'opcua' port at import
+from .mqtt_port import PAHO_AVAILABLE, MqttTap                # registers the 'mqtt' port at import
 from .well_assembler import (
     WellAssembly, WellComponent, assemble, assemble_ktb_hb, assemble_odp_504b,
     assemble_site_1027, assemble_u1324, BUILTIN_ASSEMBLIES,
@@ -125,7 +127,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "calculate_quartz_transducer_hpht_program", "canonical_suppression",
     "conventional_drift", "drift_comparison",

{gea_program-0.1.0 → gea_program-0.2.0}/gea/__main__.py

@@ -1,7 +1,7 @@
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at https://mozilla.org/MPL/2.0/.
-"""Headless CLI for the GEA Downhole Simulator (v1.6.0 extension).
+"""Headless CLI for the GEA Downhole Simulator.
 
     python -m gea run          --steps 200 --out run.csv
     python -m gea service-life --years 5 --out curves.csv
@@ -250,6 +250,18 @@ def main(argv=None) -> int:
     p_db.add_argument("--name", type=str, default="site")
     p_db.add_argument("--out", type=str, default="dashboard")
 
+    for name, helptxt in (("opcua", "OPC UA client port: read once or subscribe; record; replay a recording offline"),
+                          ("mqtt", "MQTT subscriber port (3.1.1/5.0; number | json | Sparkplug B): run; record; replay offline")):
+        p_lp = sub.add_parser(name, help=helptxt)
+        p_lp.add_argument("--config", type=str, default=None, help="site map JSON (client-owned)")
+        p_lp.add_argument("--write-example-config", type=str, default=None, help="write an example map here and exit")
+        p_lp.add_argument("--replay", type=str, default=None, help="recording (JSON lines) to replay instead of connecting")
+        p_lp.add_argument("--record", type=str, default=None, help="write every received message to this recording")
+        p_lp.add_argument("--seconds", type=float, default=10.0, help="subscribe/run duration")
+        p_lp.add_argument("--read-once", action="store_true", help="opcua: one Read of all nodes instead of a subscription")
+        p_lp.add_argument("--out", type=str, default=None, help="write the records CSV here")
+        p_lp.add_argument("--stream-csv", type=str, default=None, help="also write a historian-style CSV the other commands ingest")
+
     p_cs = sub.add_parser("case-study", help="depth sweep, write the one-page markdown case")
     _add_well_args(p_cs)
     p_cs.add_argument("--points", type=int, default=12)
@@ -339,7 +351,7 @@ def main(argv=None) -> int:
                 asm = maker()
             except Exception:
                 # operator-tier assemblies on machines without the private
-                # data: listed honestly, never crashing the listing (v1.77.0)
+                # data: listed plainly, never crashing the listing
                 print(f"{name}: OPERATOR-TIER assembly - private data not "
                       "present on this machine (tier is per-machine, never required)")
                 continue
@@ -372,6 +384,47 @@ def main(argv=None) -> int:
         rep = Reconciler(_build_config(a)).reconcile(stream, station_map=station_map)
         import json as _json
         print(_json.dumps(rep, indent=1))
+    elif a.cmd in ("opcua", "mqtt"):
+        import json as _json
+        from .live_ports import records_to_stream, summarize, write_records_csv
+        mod = __import__("gea.opcua_port" if a.cmd == "opcua" else "gea.mqtt_port", fromlist=["x"])
+        if a.write_example_config:
+            print("config:", mod.write_example_config(a.write_example_config))
+            return 0
+        if not a.config:
+            raise SystemExit(f"{a.cmd} needs --config (or --write-example-config to start one)")
+        try:
+            if a.replay:
+                recs = mod.replay(a.config, a.replay)
+                src = f"replay {a.replay}"
+            elif a.cmd == "opcua":
+                tap = mod.OpcUaTap(a.config, recording_path=a.record).connect()
+                try:
+                    recs = tap.read_once() if a.read_once else tap.subscribe(a.seconds)
+                finally:
+                    tap.close()
+                src = tap.cfg["endpoint"]
+            else:
+                tap = mod.MqttTap(a.config, recording_path=a.record)
+                recs = tap.run(a.seconds)
+                src = tap.cfg["broker"]["host"]
+        except (NotImplementedError, ConnectionError, ValueError) as e:
+            raise SystemExit(f"{a.cmd}: {e}")          # the reason, without a traceback
+        print(f"{a.cmd}: {src}")
+        print(_json.dumps(summarize(recs), indent=1))
+        if a.out:
+            print("  records:", write_records_csv(recs, a.out))
+        if a.stream_csv and recs:
+            st = records_to_stream(recs, name=a.cmd)
+            import csv as _csv
+            from datetime import datetime as _dt, timedelta as _td
+            t0 = _dt.fromisoformat(st.meta["start_time"])
+            with open(a.stream_csv, "w", newline="", encoding="utf-8") as f:
+                w = _csv.writer(f)
+                w.writerow(["timestamp"] + list(st.channels))
+                for i, t in enumerate(st.index):
+                    w.writerow([(t0 + _td(seconds=float(t))).isoformat()] + ["" if st.channels[c].values[i] != st.channels[c].values[i] else round(float(st.channels[c].values[i]), 4) for c in st.channels])
+            print("  stream:", a.stream_csv)
     elif a.cmd == "dashboard":
         from . import GAUGE_SPECS, load_gauge_spec_json, DEFAULT_TD_FT
         from .dashboard import orchestrate