aelix-analytics 0.32.1__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.
- aelix_analytics/__init__.py +359 -0
- aelix_analytics/__main__.py +682 -0
- aelix_analytics/_install.py +27 -0
- aelix_analytics/_platform.py +1895 -0
- aelix_analytics/aelix-plugin.toml +35 -0
- aelix_analytics/asset_app.py +471 -0
- aelix_analytics/asset_contract.py +48 -0
- aelix_analytics/asset_policy.py +49 -0
- aelix_analytics/asset_suggestions.py +491 -0
- aelix_analytics/assets/i18n/en.json +1317 -0
- aelix_analytics/assets/i18n/ko.json +1236 -0
- aelix_analytics/assets/workspace-i18n.js +195 -0
- aelix_analytics/assets/workspace-state.js +64 -0
- aelix_analytics/assets/workspace.css +713 -0
- aelix_analytics/assets/workspace.js +584 -0
- aelix_analytics/brand.py +54 -0
- aelix_analytics/capture.py +757 -0
- aelix_analytics/checkpoints.py +335 -0
- aelix_analytics/cli.py +642 -0
- aelix_analytics/core.py +4467 -0
- aelix_analytics/data.py +349 -0
- aelix_analytics/demo.py +168 -0
- aelix_analytics/demo_scripts/01_monthly_revenue.py +26 -0
- aelix_analytics/demo_scripts/02_channel_mix.py +20 -0
- aelix_analytics/demo_scripts/03_region_growth.py +22 -0
- aelix_analytics/extension.py +3606 -0
- aelix_analytics/i18n.py +156 -0
- aelix_analytics/kit/aelix_analytics/__init__.py +359 -0
- aelix_analytics/kit/aelix_analytics/__main__.py +682 -0
- aelix_analytics/kit/aelix_analytics/_install.py +27 -0
- aelix_analytics/kit/aelix_analytics/_platform.py +1895 -0
- aelix_analytics/kit/aelix_analytics/aelix-plugin.toml +35 -0
- aelix_analytics/kit/aelix_analytics/asset_app.py +471 -0
- aelix_analytics/kit/aelix_analytics/asset_contract.py +48 -0
- aelix_analytics/kit/aelix_analytics/asset_policy.py +49 -0
- aelix_analytics/kit/aelix_analytics/asset_suggestions.py +491 -0
- aelix_analytics/kit/aelix_analytics/assets/i18n/en.json +1317 -0
- aelix_analytics/kit/aelix_analytics/assets/i18n/ko.json +1236 -0
- aelix_analytics/kit/aelix_analytics/assets/workspace-i18n.js +195 -0
- aelix_analytics/kit/aelix_analytics/assets/workspace-state.js +64 -0
- aelix_analytics/kit/aelix_analytics/assets/workspace.css +713 -0
- aelix_analytics/kit/aelix_analytics/assets/workspace.js +584 -0
- aelix_analytics/kit/aelix_analytics/brand.py +54 -0
- aelix_analytics/kit/aelix_analytics/capture.py +757 -0
- aelix_analytics/kit/aelix_analytics/checkpoints.py +335 -0
- aelix_analytics/kit/aelix_analytics/cli.py +642 -0
- aelix_analytics/kit/aelix_analytics/core.py +4467 -0
- aelix_analytics/kit/aelix_analytics/data.py +349 -0
- aelix_analytics/kit/aelix_analytics/demo.py +168 -0
- aelix_analytics/kit/aelix_analytics/demo_scripts/01_monthly_revenue.py +26 -0
- aelix_analytics/kit/aelix_analytics/demo_scripts/02_channel_mix.py +20 -0
- aelix_analytics/kit/aelix_analytics/demo_scripts/03_region_growth.py +22 -0
- aelix_analytics/kit/aelix_analytics/i18n.py +156 -0
- aelix_analytics/kit/aelix_analytics/migration.py +3213 -0
- aelix_analytics/kit/aelix_analytics/observed.py +1113 -0
- aelix_analytics/kit/aelix_analytics/publishing/__init__.py +1 -0
- aelix_analytics/kit/aelix_analytics/publishing/assets/publication.css +1 -0
- aelix_analytics/kit/aelix_analytics/publishing/assets/publication.js +8 -0
- aelix_analytics/kit/aelix_analytics/publishing/basis.py +115 -0
- aelix_analytics/kit/aelix_analytics/publishing/build.py +890 -0
- aelix_analytics/kit/aelix_analytics/publishing/checks.py +973 -0
- aelix_analytics/kit/aelix_analytics/publishing/extract.py +95 -0
- aelix_analytics/kit/aelix_analytics/publishing/field_policy.py +362 -0
- aelix_analytics/kit/aelix_analytics/publishing/inspections.py +812 -0
- aelix_analytics/kit/aelix_analytics/publishing/model.py +225 -0
- aelix_analytics/kit/aelix_analytics/publishing/package.py +426 -0
- aelix_analytics/kit/aelix_analytics/publishing/projection.py +469 -0
- aelix_analytics/kit/aelix_analytics/publishing/publish.py +1215 -0
- aelix_analytics/kit/aelix_analytics/publishing/render.py +585 -0
- aelix_analytics/kit/aelix_analytics/publishing/scope.py +393 -0
- aelix_analytics/kit/aelix_analytics/publishing/snapshot.py +357 -0
- aelix_analytics/kit/aelix_analytics/publishing/state.py +156 -0
- aelix_analytics/kit/aelix_analytics/publishing/target.py +383 -0
- aelix_analytics/kit/aelix_analytics/relations.py +5364 -0
- aelix_analytics/kit/aelix_analytics/report_app.py +397 -0
- aelix_analytics/kit/aelix_analytics/report_renderer.py +34 -0
- aelix_analytics/kit/aelix_analytics/report_renderers.py +147 -0
- aelix_analytics/kit/aelix_analytics/runner.py +1229 -0
- aelix_analytics/kit/aelix_analytics/template/CONTEXT.md +33 -0
- aelix_analytics/kit/aelix_analytics/template/gitattributes +7 -0
- aelix_analytics/kit/aelix_analytics/template/gitignore +16 -0
- aelix_analytics/kit/aelix_analytics/template/pyproject.toml +22 -0
- aelix_analytics/kit/aelix_analytics/tree_state.py +182 -0
- aelix_analytics/kit/aelix_analytics/workspace.py +2637 -0
- aelix_analytics/kit/aelix_analytics/workspace_map.py +720 -0
- aelix_analytics/kit/aelix_analytics/workspace_provenance.py +499 -0
- aelix_analytics/kit/aelix_analytics/workspace_relations.py +358 -0
- aelix_analytics/kit/aelix_analytics/workspace_reports.py +626 -0
- aelix_analytics/kit/aelix_analytics/workspace_versions.py +956 -0
- aelix_analytics/kit/aelix_analytics/writer.py +1840 -0
- aelix_analytics/migration.py +3213 -0
- aelix_analytics/observed.py +1113 -0
- aelix_analytics/publishing/__init__.py +1 -0
- aelix_analytics/publishing/assets/publication.css +1 -0
- aelix_analytics/publishing/assets/publication.js +8 -0
- aelix_analytics/publishing/basis.py +115 -0
- aelix_analytics/publishing/build.py +890 -0
- aelix_analytics/publishing/checks.py +973 -0
- aelix_analytics/publishing/extract.py +95 -0
- aelix_analytics/publishing/field_policy.py +362 -0
- aelix_analytics/publishing/inspections.py +812 -0
- aelix_analytics/publishing/model.py +225 -0
- aelix_analytics/publishing/package.py +426 -0
- aelix_analytics/publishing/projection.py +469 -0
- aelix_analytics/publishing/publish.py +1215 -0
- aelix_analytics/publishing/render.py +585 -0
- aelix_analytics/publishing/scope.py +393 -0
- aelix_analytics/publishing/snapshot.py +357 -0
- aelix_analytics/publishing/state.py +156 -0
- aelix_analytics/publishing/target.py +383 -0
- aelix_analytics/relations.py +5364 -0
- aelix_analytics/report_app.py +397 -0
- aelix_analytics/report_renderer.py +34 -0
- aelix_analytics/report_renderers.py +147 -0
- aelix_analytics/runner.py +1229 -0
- aelix_analytics/template/CONTEXT.md +33 -0
- aelix_analytics/template/gitattributes +7 -0
- aelix_analytics/template/gitignore +16 -0
- aelix_analytics/template/pyproject.toml +22 -0
- aelix_analytics/tree_state.py +182 -0
- aelix_analytics/workspace.py +2637 -0
- aelix_analytics/workspace_map.py +720 -0
- aelix_analytics/workspace_provenance.py +499 -0
- aelix_analytics/workspace_relations.py +358 -0
- aelix_analytics/workspace_reports.py +626 -0
- aelix_analytics/workspace_versions.py +956 -0
- aelix_analytics/writer.py +1840 -0
- aelix_analytics-0.32.1.dist-info/METADATA +288 -0
- aelix_analytics-0.32.1.dist-info/RECORD +132 -0
- aelix_analytics-0.32.1.dist-info/WHEEL +4 -0
- aelix_analytics-0.32.1.dist-info/entry_points.txt +5 -0
- aelix_analytics-0.32.1.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
"""Aelix Analytics: the script API of a run, and the package everything else of it is in.
|
|
2
|
+
|
|
3
|
+
import aelix_analytics as analytics
|
|
4
|
+
|
|
5
|
+
sales = analytics.read("sales") # Polars DataFrame of data/imported/sales.parquet
|
|
6
|
+
monthly = analytics.sql("SELECT ... FROM sales").pl() # DuckDB over every dataset view
|
|
7
|
+
analytics.save(monthly, "monthly_sales") # data/derived/monthly_sales.parquet
|
|
8
|
+
analytics.visualize(fig, "monthly-trend", title="…", caption="…", data=monthly)
|
|
9
|
+
|
|
10
|
+
Inside a run every call is recorded. Plain `pl.read_parquet(...)`, DuckDB SQL over file literals,
|
|
11
|
+
`plt.show()` and plotly `fig.show()` are captured too; `analytics.visualize(..., data=df)` additionally
|
|
12
|
+
keeps a stable chart id, a caption and the exact plotted data. Outside a run the calls still work but
|
|
13
|
+
record nothing. Before kit 0.2.0 this API was the module `labkit` (`import labkit as lab`); before kit
|
|
14
|
+
0.3.0 `record` was `note` and `visualize` was `chart`. No alias is kept: the old names fail with the new
|
|
15
|
+
one in the error (ADR-0005 decision 9). A run records what each call did by the function's own name
|
|
16
|
+
(its `via`: analytics.read, analytics.scan, analytics.sql, analytics.save, analytics.visualize) since
|
|
17
|
+
the new record format (kit 0.8.0, Issue #13); a lab.run/1 record holds the older lab.* names.
|
|
18
|
+
|
|
19
|
+
A run gets this package from the entry point that started it: `analytics`, `bin/analytics` and the aelix
|
|
20
|
+
extension give the project's environment exactly one directory on PYTHONPATH — the runtime root, the
|
|
21
|
+
checkout's `src/` or an installation's `aelix_analytics/kit/` — and `python -m aelix_analytics` runs
|
|
22
|
+
the kit's command line from it (__main__). The installed distribution is this package too: the human
|
|
23
|
+
command line (`cli`), where its kit is (`_install`), the aelix extension (`extension`) and the
|
|
24
|
+
manifest, with a copy of the whole package as the runtime root under `kit/`. aelix imports this
|
|
25
|
+
package when it loads the extension, so at module level it imports the standard library only: the
|
|
26
|
+
SDK's functions import the kit's modules when they are called, and `__version__` reads `core` when it
|
|
27
|
+
is asked for (PEP 562). `__getattr__` imports nothing else: the functions' old names get an
|
|
28
|
+
AttributeError that says the new one, and any other name a plain one.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
import os
|
|
34
|
+
import sys
|
|
35
|
+
from pathlib import Path
|
|
36
|
+
from typing import TYPE_CHECKING
|
|
37
|
+
|
|
38
|
+
if TYPE_CHECKING:
|
|
39
|
+
from . import core
|
|
40
|
+
|
|
41
|
+
__all__ = ["assets", "checkpoint", "datasets", "path", "project", "read", "record", "register_asset", "review_assets",
|
|
42
|
+
"run_id", "save", "scan", "set_asset_mode", "sql", "status", "update_asset", "visualize",
|
|
43
|
+
"save_report", "reports", "update_report", "clean_report_prepared"]
|
|
44
|
+
|
|
45
|
+
# The script API's functions renamed in kit 0.3.0 (Issue #9), by their old names. The version is fixed:
|
|
46
|
+
# it names the boundary, core.NAMES_RENAMED_IN, which this module may not import at load.
|
|
47
|
+
_RENAMED = {"note": "record", "chart": "visualize"}
|
|
48
|
+
_RENAMED_IN = "0.3.0"
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def __getattr__(name: str):
|
|
52
|
+
# Called for a name this module does not have, `hasattr` and `from aelix_analytics import x` of a
|
|
53
|
+
# submodule included: only `__version__` imports anything.
|
|
54
|
+
if name == "__version__":
|
|
55
|
+
from .core import KIT_VERSION
|
|
56
|
+
|
|
57
|
+
return KIT_VERSION
|
|
58
|
+
if name in _RENAMED:
|
|
59
|
+
raise AttributeError(
|
|
60
|
+
f"{__name__}.{name} was renamed {__name__}.{_RENAMED[name]} in kit {_RENAMED_IN}; call "
|
|
61
|
+
f"{_RENAMED[name]}(...) with the same arguments. A run recorded by an earlier kit (its "
|
|
62
|
+
f"env.kit_version is below {_RENAMED_IN}) re-runs as it was only with that kit")
|
|
63
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
_CONNECTION = None
|
|
67
|
+
UNSET = object()
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def project() -> core.Project:
|
|
71
|
+
"""The run's project, or outside a run the nearest one at or above AELIX_ANALYTICS_PROJECT or the
|
|
72
|
+
working directory (a directory with an analytics.json or a lab.json). One with both markers is
|
|
73
|
+
refused (marker_conflict, an AnalyticsError): which format to read it as cannot be told. Each
|
|
74
|
+
write function judges the project again before it writes (core.admit, Issue #13)."""
|
|
75
|
+
from . import capture, core
|
|
76
|
+
|
|
77
|
+
if capture.ACTIVE is not None:
|
|
78
|
+
return capture.ACTIVE.project
|
|
79
|
+
if os.environ.get("LAB_PROJECT"):
|
|
80
|
+
# Outside a run; in one, the kit's command line has refused it already.
|
|
81
|
+
raise RuntimeError(core.renamed_env_message("LAB_PROJECT"))
|
|
82
|
+
root = core.find_project(os.environ.get("AELIX_ANALYTICS_PROJECT") or os.getcwd())
|
|
83
|
+
if root is None:
|
|
84
|
+
raise RuntimeError("not inside an analytics project (no analytics.json or lab.json in this "
|
|
85
|
+
"directory or above)")
|
|
86
|
+
core.readable(root, "read the project")
|
|
87
|
+
return core.Project(root)
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def run_id() -> str | None:
|
|
91
|
+
from . import capture
|
|
92
|
+
|
|
93
|
+
return capture.ACTIVE.run_id if capture.ACTIVE is not None else None
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def path(rel) -> Path:
|
|
97
|
+
"""Absolute path of a project-relative path."""
|
|
98
|
+
return project().path(rel)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def datasets() -> dict[str, Path]:
|
|
102
|
+
"""Dataset view name -> absolute Parquet path."""
|
|
103
|
+
from . import core
|
|
104
|
+
|
|
105
|
+
p = project()
|
|
106
|
+
return {name: p.path(rel) for name, rel in core.view_names(core.list_datasets(p)).items()}
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _dataset_path(dataset) -> Path:
|
|
110
|
+
text = os.fspath(dataset)
|
|
111
|
+
if text.endswith(".parquet") or "/" in text or os.sep in text:
|
|
112
|
+
return project().path(text)
|
|
113
|
+
known = datasets()
|
|
114
|
+
if text not in known:
|
|
115
|
+
raise KeyError(f"unknown dataset {text!r}; available: {', '.join(known) or 'none'}")
|
|
116
|
+
return known[text]
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _record(p: Path, via: str) -> None:
|
|
120
|
+
from . import capture
|
|
121
|
+
|
|
122
|
+
if capture.ACTIVE is not None:
|
|
123
|
+
capture.ACTIVE.record_read(str(p), via)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def read(dataset, **kwargs):
|
|
127
|
+
"""Polars DataFrame of a dataset name (see datasets()) or a Parquet path."""
|
|
128
|
+
import polars as pl
|
|
129
|
+
|
|
130
|
+
from . import capture
|
|
131
|
+
|
|
132
|
+
p = _dataset_path(dataset)
|
|
133
|
+
_record(p, capture.READ)
|
|
134
|
+
return pl.read_parquet(p, **kwargs)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def scan(dataset, **kwargs):
|
|
138
|
+
"""Polars LazyFrame of a dataset name or a Parquet path."""
|
|
139
|
+
import polars as pl
|
|
140
|
+
|
|
141
|
+
from . import capture
|
|
142
|
+
|
|
143
|
+
p = _dataset_path(dataset)
|
|
144
|
+
_record(p, capture.SCAN)
|
|
145
|
+
return pl.scan_parquet(p, **kwargs)
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def sql(query: str, **frames):
|
|
149
|
+
"""DuckDB relation for `query`. Every dataset is a view named after it; keyword arguments
|
|
150
|
+
register extra Polars/Arrow frames under their names. Call .pl() for a Polars DataFrame."""
|
|
151
|
+
import duckdb
|
|
152
|
+
|
|
153
|
+
from . import capture, data
|
|
154
|
+
|
|
155
|
+
global _CONNECTION
|
|
156
|
+
if _CONNECTION is None:
|
|
157
|
+
_CONNECTION = duckdb.connect()
|
|
158
|
+
p = project()
|
|
159
|
+
views = data.register_views(_CONNECTION, p)
|
|
160
|
+
for name, frame in frames.items():
|
|
161
|
+
_CONNECTION.register(name, frame)
|
|
162
|
+
if capture.ACTIVE is not None:
|
|
163
|
+
for name in data.referenced_views(query, views):
|
|
164
|
+
_record(p.path(views[name]), capture.SQL)
|
|
165
|
+
return _CONNECTION.sql(query)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def save(obj, name: str) -> Path:
|
|
169
|
+
"""Write a Polars/DuckDB/Arrow/pandas table to data/derived/<name>.parquet."""
|
|
170
|
+
from . import capture
|
|
171
|
+
|
|
172
|
+
if capture.ACTIVE is not None:
|
|
173
|
+
return capture.ACTIVE.save_dataset(obj, name)
|
|
174
|
+
return capture.save_dataset(project(), obj, name)
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def visualize(obj, id: str | None = None, *, title: str | None = None, caption: str | None = None,
|
|
178
|
+
data=None) -> dict:
|
|
179
|
+
"""Record a visualization — a chart: a matplotlib Figure/Axes, a plotly Figure, an object with
|
|
180
|
+
_repr_html_, or a path to an image/HTML file. `id` should be short ASCII (it names the chart
|
|
181
|
+
across versions); `data` is the table that was plotted and is saved next to the chart. Named
|
|
182
|
+
`chart` before kit 0.3.0; its record's `via` is "analytics.visualize" (a lab.run/1 record's
|
|
183
|
+
"lab.chart")."""
|
|
184
|
+
from . import capture, core
|
|
185
|
+
|
|
186
|
+
state = capture.ACTIVE
|
|
187
|
+
if state is None:
|
|
188
|
+
p = project()
|
|
189
|
+
core.admit(p, "visualize") # before .analytics/adhoc/ is made
|
|
190
|
+
stamp = core.now().strftime("%Y%m%d-%H%M%S")
|
|
191
|
+
run_dir = p.state_dir / "adhoc" / stamp
|
|
192
|
+
state = capture.RunState(p, f"adhoc-{stamp}", run_dir, Path(sys.argv[0]).resolve())
|
|
193
|
+
record = state.capture(obj, id, title=title, caption=caption, data=data)
|
|
194
|
+
print(f"aelix_analytics: not inside an analytics run; chart saved under {run_dir} but not "
|
|
195
|
+
"recorded", file=sys.stderr)
|
|
196
|
+
return record
|
|
197
|
+
return state.capture(obj, id, title=title, caption=caption, data=data)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def record(kind: str, text: str, *, refs=(), details=None) -> dict:
|
|
201
|
+
"""A journal entry with names/typed refs and optional structured details (ADR-0011). Outside a
|
|
202
|
+
run returns the written event and request ID; inside a run returns pending=True and the run ID,
|
|
203
|
+
retaining a private payload until finalization. Final write failures are finalize_errors, not
|
|
204
|
+
successful observations. An in-run metric_observation defaults to that run_id. Definition,
|
|
205
|
+
focus and observation use their details.contract tags; free Python still needs no registration.
|
|
206
|
+
Authorship follows the run or the outside-run SDK Origin. Whole text and line limits apply at
|
|
207
|
+
the call and final write; no truncation. A run's later captured inputs can enlarge an observation
|
|
208
|
+
line, so a pending reply is not a guarantee of final append. Refused before effects where the kit
|
|
209
|
+
may not write. `gap` names its replacement workflow_feedback in bad_kind; `resolve` needs an
|
|
210
|
+
explicit typed resolves ref. Named `note` before kit 0.3.0."""
|
|
211
|
+
from . import capture, core
|
|
212
|
+
|
|
213
|
+
if kind == "resolve" and not refs:
|
|
214
|
+
# Preserve the original two-argument SDK refusal. Typed refs make the new explicit path.
|
|
215
|
+
core.writer.check_kind(kind, tuple(k for k in core.RECORD_KINDS if k != "resolve"))
|
|
216
|
+
core.writer.check_kind(kind)
|
|
217
|
+
text = str(text)
|
|
218
|
+
state = capture.ACTIVE
|
|
219
|
+
if state is not None:
|
|
220
|
+
refs = [refs] if isinstance(refs, (str, dict)) else list(refs or ())
|
|
221
|
+
if kind == "checkpoint":
|
|
222
|
+
prepared = core.prepare_checkpoint(state.project, text, refs=refs, details=details,
|
|
223
|
+
origin=state.sdk_origin, pending_run=state.run_id)
|
|
224
|
+
text, refs, details = prepared["text"], prepared["refs"], prepared["details"]
|
|
225
|
+
else:
|
|
226
|
+
refs = [*refs, state.run_id]
|
|
227
|
+
if kind == "metric_observation" and isinstance(details, dict):
|
|
228
|
+
details = {**details, "run_id": details.get("run_id", state.run_id)}
|
|
229
|
+
if details["run_id"] != state.run_id:
|
|
230
|
+
raise core.AnalyticsError("metric_reference", "an in-run observation uses this run_id")
|
|
231
|
+
# Judged now as the run will write it — linked to the run, by the run's actor through the
|
|
232
|
+
# SDK — with the widest seq (SEQ_BOUND): a note refused for its text or its line is this
|
|
233
|
+
# call's exception, never a note the run loses when it finishes.
|
|
234
|
+
core.writer_for(state.project, state.sdk_origin).check(
|
|
235
|
+
kind, text, refs=refs, details=details, seq=core.writer.SEQ_BOUND, pending_run=state.run_id)
|
|
236
|
+
# Preserve a JSON snapshot, so mutating a caller's dictionary after acknowledgement does
|
|
237
|
+
# not change the queued record. Full final relationships are rechecked when the run ends.
|
|
238
|
+
import json
|
|
239
|
+
|
|
240
|
+
state.notes.append((kind, text, json.loads(json.dumps(refs)),
|
|
241
|
+
json.loads(json.dumps(details)) if details is not None else None))
|
|
242
|
+
return {"pending": True, "run_id": state.run_id}
|
|
243
|
+
else:
|
|
244
|
+
return core.record(project(), kind, text, refs=refs, details=details,
|
|
245
|
+
origin=_script_origin()).to_json()
|
|
246
|
+
|
|
247
|
+
|
|
248
|
+
def checkpoint(text=None, *, refs=(), as_of_seq=None, context_version=UNSET, from_seq=0, limit=8):
|
|
249
|
+
"""Explicit authored or model-free deterministic summary at an exact call-time basis."""
|
|
250
|
+
from . import capture, core
|
|
251
|
+
|
|
252
|
+
state = capture.ACTIVE
|
|
253
|
+
options = {"refs": refs, "as_of_seq": as_of_seq, "from_seq": from_seq, "limit": limit}
|
|
254
|
+
if context_version is not UNSET:
|
|
255
|
+
options["context_version"] = context_version
|
|
256
|
+
if state is not None:
|
|
257
|
+
prepared = core.prepare_checkpoint(state.project, text, origin=state.sdk_origin, pending_run=state.run_id, **options)
|
|
258
|
+
answer = record("checkpoint", prepared["text"], refs=prepared["refs"], details=prepared["details"])
|
|
259
|
+
answer["basis"] = {key: prepared["details"][key] for key in ("as_of_seq", "context_version", "journal_basis")}
|
|
260
|
+
return answer
|
|
261
|
+
return core.checkpoint(project(), text, origin=_script_origin(), **options)
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _script_origin():
|
|
266
|
+
"""Who a record the script API makes outside a run is by (design 4.2, OQ1): AELIX_ANALYTICS_ACTOR
|
|
267
|
+
as given (declared), else `human`, which the kit fills in (inferred); the means `sdk` and the
|
|
268
|
+
session AELIX_ANALYTICS_SESSION. A lab.event/1 record holds the actor `script` there, which a
|
|
269
|
+
reader reads as it is."""
|
|
270
|
+
from . import core
|
|
271
|
+
|
|
272
|
+
actor = os.environ.get("AELIX_ANALYTICS_ACTOR") or None
|
|
273
|
+
return core.Origin(actor or "human", "sdk", "declared" if actor else "inferred",
|
|
274
|
+
os.environ.get("AELIX_ANALYTICS_SESSION") or None)
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def assets(asset_id=None) -> dict:
|
|
278
|
+
"""Read analysis asset candidates and exact prior versions; no review, execution or registration."""
|
|
279
|
+
from . import core
|
|
280
|
+
|
|
281
|
+
return core.assets(project(), asset_id)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _asset_origin():
|
|
285
|
+
from . import capture
|
|
286
|
+
|
|
287
|
+
return capture.ACTIVE.sdk_origin if capture.ACTIVE is not None else _script_origin()
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def save_report(report_id, *, files, entry, title, previous_revision, request_id=None, based_on=None, metadata=None):
|
|
291
|
+
"""Register authored files as one immutable Report revision, without running generation code.
|
|
292
|
+
|
|
293
|
+
previous_revision is explicit (None for the first revision). Preserve request_id for retries.
|
|
294
|
+
Evidence is only the supplied based_on, never inferred from the current project.
|
|
295
|
+
"""
|
|
296
|
+
from . import core
|
|
297
|
+
|
|
298
|
+
return core.save_report(project(), report_id, files=files, entry=entry, title=title,
|
|
299
|
+
previous_revision=previous_revision, request_id=request_id,
|
|
300
|
+
based_on=based_on, metadata=metadata, origin=_asset_origin())
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
def reports(report_id=None, revision_id=None, **options):
|
|
304
|
+
"""Bounded Report metadata/history or one file's exact bytes, encoded as base64."""
|
|
305
|
+
from . import core
|
|
306
|
+
|
|
307
|
+
return core.reports(project(), report_id, revision_id, **options)
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def update_report(report_id, revision_id, *, expected, new, reason):
|
|
311
|
+
"""Withdraw or restore an exact completed revision, keeping its authored bytes immutable."""
|
|
312
|
+
from . import core
|
|
313
|
+
|
|
314
|
+
return core.update_report(project(), report_id, revision_id, expected=expected, new=new,
|
|
315
|
+
reason=reason, origin=_asset_origin())
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
def clean_report_prepared(report_id, revision_id):
|
|
319
|
+
"""Explicitly remove only the named prepared attempt after taking its lock."""
|
|
320
|
+
from . import core
|
|
321
|
+
|
|
322
|
+
return core.clean_report_prepared(project(), report_id, revision_id, origin=_asset_origin())
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def review_assets(asset_id=None) -> dict:
|
|
326
|
+
"""Explicit model-free review; returned candidates are recorded as requested suggestions."""
|
|
327
|
+
from . import core
|
|
328
|
+
|
|
329
|
+
return core.review_assets(project(), asset_id, origin=_asset_origin())
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
def update_asset(event_id: str, *, expected: str, new: str, text: str, details=None) -> dict:
|
|
333
|
+
"""Advance, defer/reject or annotate one candidate version, preserving checks and history."""
|
|
334
|
+
from . import core
|
|
335
|
+
|
|
336
|
+
return core.update_asset(project(), event_id, expected=expected, new=new, text=text,
|
|
337
|
+
details=details, origin=_asset_origin())
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
def register_asset(event_id: str, *, name: str) -> dict:
|
|
341
|
+
"""Explicitly copy a validated version into this project; never a global installation."""
|
|
342
|
+
from . import core
|
|
343
|
+
|
|
344
|
+
return core.register_asset(project(), event_id, name=name, origin=_asset_origin())
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def status(*, part=None, **options) -> dict:
|
|
348
|
+
"""The same overview/record/context/relation read as analytics status and analytics_status.
|
|
349
|
+
No model, host or analysis library is needed by core's retrieval implementation."""
|
|
350
|
+
from . import core
|
|
351
|
+
|
|
352
|
+
return core.status(project(), part=part, **options)
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def set_asset_mode(mode: str) -> dict:
|
|
356
|
+
"""Choose project-local on-demand or model-free automatic suggestions as a human."""
|
|
357
|
+
from . import core
|
|
358
|
+
|
|
359
|
+
return core.set_asset_mode(project(), mode, origin=_asset_origin())
|