protocolith 0.6.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. protocolith/__init__.py +38 -0
  2. protocolith/baseline_groups.py +294 -0
  3. protocolith/baselines.py +288 -0
  4. protocolith/card_svg_render.py +281 -0
  5. protocolith/card_svg_styles.py +178 -0
  6. protocolith/cli.py +796 -0
  7. protocolith/core/__init__.py +63 -0
  8. protocolith/core/_lock_posix.py +29 -0
  9. protocolith/core/_lock_windows.py +29 -0
  10. protocolith/core/atlas.py +406 -0
  11. protocolith/core/atlas_assets/atlas.css +86 -0
  12. protocolith/core/atlas_assets/atlas.html +84 -0
  13. protocolith/core/atlas_assets/atlas.js +370 -0
  14. protocolith/core/atlas_i18n/en.json +61 -0
  15. protocolith/core/canonical.py +124 -0
  16. protocolith/core/capture.py +68 -0
  17. protocolith/core/clock.py +25 -0
  18. protocolith/core/commands.py +356 -0
  19. protocolith/core/errors.py +116 -0
  20. protocolith/core/issue.py +98 -0
  21. protocolith/core/ledger.py +75 -0
  22. protocolith/core/mcp.py +371 -0
  23. protocolith/core/ops.py +183 -0
  24. protocolith/core/rules.py +352 -0
  25. protocolith/core/schema.py +137 -0
  26. protocolith/core/store.py +101 -0
  27. protocolith/core/views.py +136 -0
  28. protocolith/doctor.py +135 -0
  29. protocolith/evidence_card.py +354 -0
  30. protocolith/family_ledger.py +489 -0
  31. protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
  32. protocolith/inspect.py +48 -0
  33. protocolith/nasa_power.py +266 -0
  34. protocolith/nasa_power_fetch.py +64 -0
  35. protocolith/nasa_power_parser.py +133 -0
  36. protocolith/nasa_power_prereg_runner.py +383 -0
  37. protocolith/noaa_coops_fetch.py +188 -0
  38. protocolith/noaa_coops_parser.py +120 -0
  39. protocolith/noaa_coops_prereg_runner.py +341 -0
  40. protocolith/public_ai_protocol.py +176 -0
  41. protocolith/py.typed +0 -0
  42. protocolith/registry.py +139 -0
  43. protocolith/registry_view.py +302 -0
  44. protocolith/rerun_report.py +111 -0
  45. protocolith/run_root.py +243 -0
  46. protocolith/scaffold.py +565 -0
  47. protocolith/source_probe.py +230 -0
  48. protocolith/svg_a11y.py +100 -0
  49. protocolith/tree_overlay.py +343 -0
  50. protocolith/verify_packs.py +251 -0
  51. protocolith/workflows.py +233 -0
  52. protocolith-0.6.0.dist-info/METADATA +283 -0
  53. protocolith-0.6.0.dist-info/RECORD +57 -0
  54. protocolith-0.6.0.dist-info/WHEEL +4 -0
  55. protocolith-0.6.0.dist-info/entry_points.txt +3 -0
  56. protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
  57. protocolith-0.6.0.dist-info/licenses/NOTICE +13 -0
@@ -0,0 +1,266 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+
3
+ """NASA POWER D-103 offline adapter/materializer.
4
+
5
+ The adapter implements only plumbing for the frozen D-103 pre-registration
6
+ charter. It can build deterministic mock daily solar-resource series for tests
7
+ or convert operator-supplied local NASA POWER JSON files into a generic OHLCV
8
+ CSV. It does not fetch network payloads and does not run the empirical gate.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import csv
14
+ import hashlib
15
+ import json
16
+ from dataclasses import dataclass
17
+ from datetime import date, timedelta
18
+ from pathlib import Path
19
+
20
+ import numpy as np
21
+ from numpy.typing import NDArray
22
+
23
+ from protocolith.nasa_power_parser import (
24
+ parse_nasa_power_daily_json,
25
+ )
26
+
27
+
28
+ NASA_POWER_DATASET_ID_PREFIX = "nasa_power"
29
+ NASA_POWER_MANIFEST_SCHEMA = "nasa_power_manifest_v1"
30
+ NASA_POWER_PARAMETERS: tuple[str, ...] = (
31
+ "ALLSKY_SFC_SW_DWN",
32
+ "T2M",
33
+ "WS10M",
34
+ "PRECTOTCORR",
35
+ )
36
+ NASA_POWER_CSV_COLUMNS: tuple[str, ...] = (
37
+ "time",
38
+ "open",
39
+ "high",
40
+ "low",
41
+ "close",
42
+ "volume",
43
+ )
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class NasaPowerPoint:
48
+ point_id: str
49
+ name: str
50
+ latitude: float
51
+ longitude: float
52
+ community: str = "RE"
53
+ time_standard: str = "UTC"
54
+
55
+
56
+ NASA_POWER_POINTS: dict[str, NasaPowerPoint] = {
57
+ "POWER_A": NasaPowerPoint("POWER_A", "Kyiv", 50.4501, 30.5234),
58
+ "POWER_B": NasaPowerPoint("POWER_B", "Lviv", 49.8397, 24.0297),
59
+ "POWER_C": NasaPowerPoint("POWER_C", "Odesa", 46.4825, 30.7233),
60
+ }
61
+
62
+
63
+ @dataclass(frozen=True)
64
+ class NasaPowerMockConfig:
65
+ point_id: str
66
+ start: date
67
+ end: date
68
+ seed: int | None = None
69
+ solar_noise_std: float = 0.35
70
+
71
+ def __post_init__(self) -> None:
72
+ normalize_point_id(self.point_id)
73
+ if self.start >= self.end:
74
+ raise ValueError("start must be strictly less than end")
75
+ if self.solar_noise_std < 0.0 or self.solar_noise_std > 20.0:
76
+ raise ValueError("solar_noise_std must be in [0,20]")
77
+
78
+
79
+ def normalize_point_id(point_id: str) -> str:
80
+ pid = str(point_id).strip().upper()
81
+ if pid not in NASA_POWER_POINTS:
82
+ known = ", ".join(sorted(NASA_POWER_POINTS))
83
+ raise ValueError(f"unknown NASA POWER point {point_id!r}; known: {known}")
84
+ return pid
85
+
86
+
87
+ def build_nasa_power_dataset_id(point_id: str, *, source_mode: str) -> str:
88
+ pid = normalize_point_id(point_id)
89
+ if source_mode == "mock":
90
+ return f"{NASA_POWER_DATASET_ID_PREFIX}_{pid.lower()}_mock"
91
+ if source_mode == "nasa_power_json_file":
92
+ return f"{NASA_POWER_DATASET_ID_PREFIX}_{pid.lower()}"
93
+ raise ValueError(f"unsupported source_mode {source_mode!r}")
94
+
95
+
96
+ def _seed_from_config(config: NasaPowerMockConfig) -> int:
97
+ if config.seed is not None:
98
+ return int(config.seed) & 0xFFFFFFFF
99
+ material = f"{config.point_id}|{config.start.isoformat()}|{config.end.isoformat()}"
100
+ return int.from_bytes(hashlib.sha256(material.encode("utf-8")).digest()[:4], "big")
101
+
102
+
103
+ def _date_range(start: date, end: date) -> list[date]:
104
+ days = int((end - start).days)
105
+ if days < 1:
106
+ raise ValueError("configured interval must contain at least one day")
107
+ return [start + timedelta(days=i) for i in range(days)]
108
+
109
+
110
+ def trailing_mean(values: NDArray[np.float64], *, window: int) -> NDArray[np.float64]:
111
+ if window < 1:
112
+ raise ValueError("window must be >= 1")
113
+ arr = np.asarray(values, dtype=np.float64)
114
+ out = np.empty_like(arr)
115
+ for idx in range(len(arr)):
116
+ start = max(0, idx - window + 1)
117
+ out[idx] = float(np.mean(arr[start : idx + 1]))
118
+ return out
119
+
120
+
121
+ def generate_nasa_power_mock_daily_series(
122
+ config: NasaPowerMockConfig,
123
+ ) -> tuple[list[date], dict[str, NDArray[np.float64]]]:
124
+ """Return deterministic daily parameter series for offline tests only."""
125
+
126
+ rng = np.random.default_rng(_seed_from_config(config))
127
+ days = _date_range(config.start, config.end)
128
+ n = len(days)
129
+ solar = np.empty(n, dtype=np.float64)
130
+ temp = np.empty(n, dtype=np.float64)
131
+ wind = np.empty(n, dtype=np.float64)
132
+ precip = np.empty(n, dtype=np.float64)
133
+ for idx, day in enumerate(days):
134
+ seasonal = np.sin(2 * np.pi * (day.timetuple().tm_yday - 80) / 365.25)
135
+ solar[idx] = max(0.0, 3.5 + 2.2 * seasonal)
136
+ temp[idx] = 9.0 + 14.0 * seasonal
137
+ wind[idx] = 4.0 + 0.8 * np.cos(2 * np.pi * idx / 9.0)
138
+ precip[idx] = max(0.0, 1.2 + 1.0 * np.sin(2 * np.pi * idx / 17.0))
139
+ solar += rng.normal(0.0, config.solar_noise_std, n)
140
+ temp += rng.normal(0.0, 1.5, n)
141
+ wind += rng.normal(0.0, 0.25, n)
142
+ precip += rng.normal(0.0, 0.5, n)
143
+ return days, {
144
+ "ALLSKY_SFC_SW_DWN": np.maximum(solar, 0.0),
145
+ "T2M": temp,
146
+ "WS10M": np.maximum(wind, 0.0),
147
+ "PRECTOTCORR": np.maximum(precip, 0.0),
148
+ }
149
+
150
+
151
+ def parse_nasa_power_json_file(
152
+ json_path: str | Path,
153
+ ) -> tuple[list[date], dict[str, NDArray[np.float64]], dict[str, object]]:
154
+ days, values, summary = parse_nasa_power_daily_json(
155
+ json_path,
156
+ parameters=NASA_POWER_PARAMETERS,
157
+ )
158
+ out_summary = {
159
+ "parameters": list(summary.parameters),
160
+ "rows": summary.rows,
161
+ "skipped": summary.skipped,
162
+ "first_date": summary.first_date.isoformat() if summary.first_date else None,
163
+ "last_date": summary.last_date.isoformat() if summary.last_date else None,
164
+ }
165
+ return days, values, out_summary
166
+
167
+
168
+ def solar_7d_mean_from_values(values: dict[str, NDArray[np.float64]]) -> NDArray[np.float64]:
169
+ if "ALLSKY_SFC_SW_DWN" not in values:
170
+ raise ValueError("missing ALLSKY_SFC_SW_DWN values")
171
+ return trailing_mean(values["ALLSKY_SFC_SW_DWN"], window=7)
172
+
173
+
174
+ def _iso_day(day: date) -> str:
175
+ return f"{day.isoformat()}T00:00:00+00:00"
176
+
177
+
178
+ def write_nasa_power_solar_ohlcv_csv(
179
+ days: list[date],
180
+ solar_7d_mean: NDArray[np.float64],
181
+ path: str | Path,
182
+ ) -> Path:
183
+ out_path = Path(path)
184
+ out_path.parent.mkdir(parents=True, exist_ok=True)
185
+ if len(days) != int(solar_7d_mean.shape[0]):
186
+ raise ValueError("days length must match solar_7d_mean length")
187
+ if len(days) == 0:
188
+ raise ValueError("cannot write an empty daily series")
189
+ with out_path.open("w", encoding="utf-8", newline="") as fh:
190
+ writer = csv.writer(fh)
191
+ writer.writerow(list(NASA_POWER_CSV_COLUMNS))
192
+ for day, value in zip(days, solar_7d_mean.tolist(), strict=True):
193
+ cell = f"{float(value):.6f}"
194
+ writer.writerow([_iso_day(day), cell, cell, cell, cell, "1"])
195
+ return out_path
196
+
197
+
198
+ def write_nasa_power_manifest(
199
+ csv_path: str | Path,
200
+ *,
201
+ dataset_id: str,
202
+ point_id: str,
203
+ source_mode: str,
204
+ start_date: date,
205
+ end_date: date,
206
+ rows: int,
207
+ repo_semver: str | None,
208
+ git_commit_short: str | None,
209
+ manifest_path: str | Path | None = None,
210
+ ) -> Path:
211
+ csv_path_obj = Path(csv_path)
212
+ if not csv_path_obj.is_file():
213
+ raise FileNotFoundError(f"csv not found: {csv_path_obj}")
214
+ pid = normalize_point_id(point_id)
215
+ if source_mode not in {"mock", "nasa_power_json_file"}:
216
+ raise ValueError(f"unsupported source_mode {source_mode!r}")
217
+ point = NASA_POWER_POINTS[pid]
218
+ manifest: dict[str, object] = {
219
+ "schema": NASA_POWER_MANIFEST_SCHEMA,
220
+ "dataset_id": dataset_id,
221
+ "point_id": pid,
222
+ "point_name": point.name,
223
+ "point_location_redacted": True,
224
+ "community": point.community,
225
+ "time_standard": point.time_standard,
226
+ "source_mode": source_mode,
227
+ "parameters": list(NASA_POWER_PARAMETERS),
228
+ "derived_series": "solar_7d_mean",
229
+ "start_date": start_date.isoformat(),
230
+ "end_date": end_date.isoformat(),
231
+ "rows": int(rows),
232
+ "generated_csv_committed": False,
233
+ "repo_semver": repo_semver,
234
+ "git_commit_short": git_commit_short,
235
+ "raw_payload_committed": False,
236
+ "honest_boundary": (
237
+ "mock mode is synthetic plumbing only; nasa_power_json_file mode only "
238
+ "materializes operator-supplied local official-source payloads and does "
239
+ "not establish a positive empirical claim"
240
+ ),
241
+ }
242
+ out_path = (
243
+ Path(manifest_path)
244
+ if manifest_path is not None
245
+ else csv_path_obj.with_suffix(csv_path_obj.suffix + ".manifest.json")
246
+ )
247
+ out_path.parent.mkdir(parents=True, exist_ok=True)
248
+ out_path.write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
249
+ return out_path
250
+
251
+
252
+ __all__ = [
253
+ "NASA_POWER_MANIFEST_SCHEMA",
254
+ "NASA_POWER_PARAMETERS",
255
+ "NASA_POWER_POINTS",
256
+ "NasaPowerMockConfig",
257
+ "NasaPowerPoint",
258
+ "build_nasa_power_dataset_id",
259
+ "generate_nasa_power_mock_daily_series",
260
+ "normalize_point_id",
261
+ "parse_nasa_power_json_file",
262
+ "solar_7d_mean_from_values",
263
+ "trailing_mean",
264
+ "write_nasa_power_manifest",
265
+ "write_nasa_power_solar_ohlcv_csv",
266
+ ]
@@ -0,0 +1,64 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Download frozen NASA POWER D-103 JSON payloads for operator reruns."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import urllib.parse
7
+ import urllib.request
8
+ from pathlib import Path
9
+ from collections.abc import Callable
10
+
11
+ from protocolith.nasa_power import NASA_POWER_PARAMETERS, NASA_POWER_POINTS, NasaPowerPoint
12
+
13
+
14
+ NASA_POWER_API_BASE = "https://power.larc.nasa.gov/api/temporal/daily/point"
15
+ NASA_POWER_D103_START = "20150101"
16
+ NASA_POWER_D103_END = "20241231"
17
+ DEFAULT_USER_AGENT = "Protocolith-nasa-fetch/0.1"
18
+
19
+
20
+ def build_nasa_power_point_url(point: NasaPowerPoint) -> str:
21
+ params = {
22
+ "parameters": ",".join(NASA_POWER_PARAMETERS),
23
+ "community": point.community,
24
+ "longitude": str(point.longitude),
25
+ "latitude": str(point.latitude),
26
+ "start": NASA_POWER_D103_START,
27
+ "end": NASA_POWER_D103_END,
28
+ "format": "JSON",
29
+ }
30
+ return f"{NASA_POWER_API_BASE}?{urllib.parse.urlencode(params)}"
31
+
32
+
33
+ def download_nasa_power_point(
34
+ point_id: str,
35
+ out_path: Path,
36
+ *,
37
+ opener: Callable[..., object] | None = None,
38
+ ) -> Path:
39
+ point = NASA_POWER_POINTS[point_id]
40
+ url = build_nasa_power_point_url(point)
41
+ out_path.parent.mkdir(parents=True, exist_ok=True)
42
+ request = urllib.request.Request(url, headers={"User-Agent": DEFAULT_USER_AGENT})
43
+ open_fn = opener or urllib.request.urlopen
44
+ with open_fn(request, timeout=120) as response:
45
+ payload = response.read()
46
+ out_path.write_bytes(payload)
47
+ return out_path
48
+
49
+
50
+ def download_nasa_power_d103_points(
51
+ raw_dir: Path,
52
+ *,
53
+ opener: Callable[..., object] | None = None,
54
+ ) -> list[Path]:
55
+ paths: list[Path] = []
56
+ for point_id in ("POWER_A", "POWER_B", "POWER_C"):
57
+ paths.append(
58
+ download_nasa_power_point(
59
+ point_id,
60
+ raw_dir / f"{point_id}.json",
61
+ opener=opener,
62
+ )
63
+ )
64
+ return paths
@@ -0,0 +1,133 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+
3
+ """Offline NASA POWER Daily JSON parser for the D-103 pre-registration path.
4
+
5
+ This module parses JSON files that the operator has already saved outside the
6
+ repository. It performs no network I/O and does not validate any empirical
7
+ claim. The supported shape matches the NASA POWER daily point JSON convention:
8
+ ``properties.parameter`` contains one object per parameter, keyed by YYYYMMDD.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ from dataclasses import dataclass
15
+ from datetime import date, datetime
16
+ from pathlib import Path
17
+
18
+ import numpy as np
19
+ from numpy.typing import NDArray
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class NasaPowerParseSummary:
24
+ """Summary of a local NASA POWER Daily JSON parse."""
25
+
26
+ parameters: tuple[str, ...]
27
+ rows: int
28
+ skipped: int
29
+ first_date: date | None
30
+ last_date: date | None
31
+
32
+
33
+ def _parse_date_key(raw: object) -> date | None:
34
+ text = str(raw).strip() if raw is not None else ""
35
+ if not text:
36
+ return None
37
+ for fmt in ("%Y%m%d", "%Y-%m-%d"):
38
+ try:
39
+ return datetime.strptime(text, fmt).date()
40
+ except ValueError:
41
+ continue
42
+ return None
43
+
44
+
45
+ def _parse_value(raw: object) -> float | None:
46
+ text = str(raw).strip() if raw is not None else ""
47
+ if not text:
48
+ return None
49
+ try:
50
+ value = float(text)
51
+ except ValueError:
52
+ return None
53
+ if not np.isfinite(value):
54
+ return None
55
+ if value <= -900.0:
56
+ return None
57
+ return value
58
+
59
+
60
+ def _parameter_payload(payload: dict[str, object]) -> dict[str, object]:
61
+ props = payload.get("properties")
62
+ if not isinstance(props, dict):
63
+ raise ValueError("NASA POWER JSON must contain object key 'properties'")
64
+ params = props.get("parameter")
65
+ if not isinstance(params, dict):
66
+ raise ValueError("NASA POWER JSON must contain object key 'properties.parameter'")
67
+ return params
68
+
69
+
70
+ def parse_nasa_power_daily_json(
71
+ path: str | Path,
72
+ *,
73
+ parameters: tuple[str, ...],
74
+ ) -> tuple[list[date], dict[str, NDArray[np.float64]], NasaPowerParseSummary]:
75
+ """Parse selected parameters from a local NASA POWER Daily JSON file."""
76
+
77
+ file_path = Path(path)
78
+ if not file_path.is_file():
79
+ raise FileNotFoundError(f"NASA POWER JSON not found: {file_path}")
80
+ if not parameters:
81
+ raise ValueError("parameters must not be empty")
82
+ payload = json.loads(file_path.read_text(encoding="utf-8"))
83
+ if not isinstance(payload, dict):
84
+ raise ValueError(f"NASA POWER JSON root must be an object: {file_path}")
85
+ params = _parameter_payload(payload)
86
+
87
+ missing = [param for param in parameters if param not in params]
88
+ if missing:
89
+ raise ValueError(f"NASA POWER JSON missing parameters: {', '.join(missing)}")
90
+
91
+ by_date: dict[date, dict[str, float]] = {}
92
+ skipped = 0
93
+ for param in parameters:
94
+ raw_series = params[param]
95
+ if not isinstance(raw_series, dict):
96
+ raise ValueError(f"NASA POWER parameter {param!r} must be an object")
97
+ for raw_key, raw_value in raw_series.items():
98
+ day = _parse_date_key(raw_key)
99
+ value = _parse_value(raw_value)
100
+ if day is None or value is None:
101
+ skipped += 1
102
+ continue
103
+ by_date.setdefault(day, {})[param] = value
104
+
105
+ rows: list[tuple[date, dict[str, float]]] = []
106
+ for day, values in by_date.items():
107
+ if all(param in values for param in parameters):
108
+ rows.append((day, values))
109
+ else:
110
+ skipped += 1
111
+ rows.sort(key=lambda row: row[0])
112
+ if not rows:
113
+ raise ValueError("NASA POWER JSON contained no complete usable daily rows")
114
+
115
+ days = [row[0] for row in rows]
116
+ values_by_param = {
117
+ param: np.asarray([row[1][param] for row in rows], dtype=np.float64)
118
+ for param in parameters
119
+ }
120
+ summary = NasaPowerParseSummary(
121
+ parameters=tuple(parameters),
122
+ rows=len(days),
123
+ skipped=int(skipped),
124
+ first_date=days[0],
125
+ last_date=days[-1],
126
+ )
127
+ return days, values_by_param, summary
128
+
129
+
130
+ __all__ = [
131
+ "NasaPowerParseSummary",
132
+ "parse_nasa_power_daily_json",
133
+ ]