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.
Files changed (132) hide show
  1. aelix_analytics/__init__.py +359 -0
  2. aelix_analytics/__main__.py +682 -0
  3. aelix_analytics/_install.py +27 -0
  4. aelix_analytics/_platform.py +1895 -0
  5. aelix_analytics/aelix-plugin.toml +35 -0
  6. aelix_analytics/asset_app.py +471 -0
  7. aelix_analytics/asset_contract.py +48 -0
  8. aelix_analytics/asset_policy.py +49 -0
  9. aelix_analytics/asset_suggestions.py +491 -0
  10. aelix_analytics/assets/i18n/en.json +1317 -0
  11. aelix_analytics/assets/i18n/ko.json +1236 -0
  12. aelix_analytics/assets/workspace-i18n.js +195 -0
  13. aelix_analytics/assets/workspace-state.js +64 -0
  14. aelix_analytics/assets/workspace.css +713 -0
  15. aelix_analytics/assets/workspace.js +584 -0
  16. aelix_analytics/brand.py +54 -0
  17. aelix_analytics/capture.py +757 -0
  18. aelix_analytics/checkpoints.py +335 -0
  19. aelix_analytics/cli.py +642 -0
  20. aelix_analytics/core.py +4467 -0
  21. aelix_analytics/data.py +349 -0
  22. aelix_analytics/demo.py +168 -0
  23. aelix_analytics/demo_scripts/01_monthly_revenue.py +26 -0
  24. aelix_analytics/demo_scripts/02_channel_mix.py +20 -0
  25. aelix_analytics/demo_scripts/03_region_growth.py +22 -0
  26. aelix_analytics/extension.py +3606 -0
  27. aelix_analytics/i18n.py +156 -0
  28. aelix_analytics/kit/aelix_analytics/__init__.py +359 -0
  29. aelix_analytics/kit/aelix_analytics/__main__.py +682 -0
  30. aelix_analytics/kit/aelix_analytics/_install.py +27 -0
  31. aelix_analytics/kit/aelix_analytics/_platform.py +1895 -0
  32. aelix_analytics/kit/aelix_analytics/aelix-plugin.toml +35 -0
  33. aelix_analytics/kit/aelix_analytics/asset_app.py +471 -0
  34. aelix_analytics/kit/aelix_analytics/asset_contract.py +48 -0
  35. aelix_analytics/kit/aelix_analytics/asset_policy.py +49 -0
  36. aelix_analytics/kit/aelix_analytics/asset_suggestions.py +491 -0
  37. aelix_analytics/kit/aelix_analytics/assets/i18n/en.json +1317 -0
  38. aelix_analytics/kit/aelix_analytics/assets/i18n/ko.json +1236 -0
  39. aelix_analytics/kit/aelix_analytics/assets/workspace-i18n.js +195 -0
  40. aelix_analytics/kit/aelix_analytics/assets/workspace-state.js +64 -0
  41. aelix_analytics/kit/aelix_analytics/assets/workspace.css +713 -0
  42. aelix_analytics/kit/aelix_analytics/assets/workspace.js +584 -0
  43. aelix_analytics/kit/aelix_analytics/brand.py +54 -0
  44. aelix_analytics/kit/aelix_analytics/capture.py +757 -0
  45. aelix_analytics/kit/aelix_analytics/checkpoints.py +335 -0
  46. aelix_analytics/kit/aelix_analytics/cli.py +642 -0
  47. aelix_analytics/kit/aelix_analytics/core.py +4467 -0
  48. aelix_analytics/kit/aelix_analytics/data.py +349 -0
  49. aelix_analytics/kit/aelix_analytics/demo.py +168 -0
  50. aelix_analytics/kit/aelix_analytics/demo_scripts/01_monthly_revenue.py +26 -0
  51. aelix_analytics/kit/aelix_analytics/demo_scripts/02_channel_mix.py +20 -0
  52. aelix_analytics/kit/aelix_analytics/demo_scripts/03_region_growth.py +22 -0
  53. aelix_analytics/kit/aelix_analytics/i18n.py +156 -0
  54. aelix_analytics/kit/aelix_analytics/migration.py +3213 -0
  55. aelix_analytics/kit/aelix_analytics/observed.py +1113 -0
  56. aelix_analytics/kit/aelix_analytics/publishing/__init__.py +1 -0
  57. aelix_analytics/kit/aelix_analytics/publishing/assets/publication.css +1 -0
  58. aelix_analytics/kit/aelix_analytics/publishing/assets/publication.js +8 -0
  59. aelix_analytics/kit/aelix_analytics/publishing/basis.py +115 -0
  60. aelix_analytics/kit/aelix_analytics/publishing/build.py +890 -0
  61. aelix_analytics/kit/aelix_analytics/publishing/checks.py +973 -0
  62. aelix_analytics/kit/aelix_analytics/publishing/extract.py +95 -0
  63. aelix_analytics/kit/aelix_analytics/publishing/field_policy.py +362 -0
  64. aelix_analytics/kit/aelix_analytics/publishing/inspections.py +812 -0
  65. aelix_analytics/kit/aelix_analytics/publishing/model.py +225 -0
  66. aelix_analytics/kit/aelix_analytics/publishing/package.py +426 -0
  67. aelix_analytics/kit/aelix_analytics/publishing/projection.py +469 -0
  68. aelix_analytics/kit/aelix_analytics/publishing/publish.py +1215 -0
  69. aelix_analytics/kit/aelix_analytics/publishing/render.py +585 -0
  70. aelix_analytics/kit/aelix_analytics/publishing/scope.py +393 -0
  71. aelix_analytics/kit/aelix_analytics/publishing/snapshot.py +357 -0
  72. aelix_analytics/kit/aelix_analytics/publishing/state.py +156 -0
  73. aelix_analytics/kit/aelix_analytics/publishing/target.py +383 -0
  74. aelix_analytics/kit/aelix_analytics/relations.py +5364 -0
  75. aelix_analytics/kit/aelix_analytics/report_app.py +397 -0
  76. aelix_analytics/kit/aelix_analytics/report_renderer.py +34 -0
  77. aelix_analytics/kit/aelix_analytics/report_renderers.py +147 -0
  78. aelix_analytics/kit/aelix_analytics/runner.py +1229 -0
  79. aelix_analytics/kit/aelix_analytics/template/CONTEXT.md +33 -0
  80. aelix_analytics/kit/aelix_analytics/template/gitattributes +7 -0
  81. aelix_analytics/kit/aelix_analytics/template/gitignore +16 -0
  82. aelix_analytics/kit/aelix_analytics/template/pyproject.toml +22 -0
  83. aelix_analytics/kit/aelix_analytics/tree_state.py +182 -0
  84. aelix_analytics/kit/aelix_analytics/workspace.py +2637 -0
  85. aelix_analytics/kit/aelix_analytics/workspace_map.py +720 -0
  86. aelix_analytics/kit/aelix_analytics/workspace_provenance.py +499 -0
  87. aelix_analytics/kit/aelix_analytics/workspace_relations.py +358 -0
  88. aelix_analytics/kit/aelix_analytics/workspace_reports.py +626 -0
  89. aelix_analytics/kit/aelix_analytics/workspace_versions.py +956 -0
  90. aelix_analytics/kit/aelix_analytics/writer.py +1840 -0
  91. aelix_analytics/migration.py +3213 -0
  92. aelix_analytics/observed.py +1113 -0
  93. aelix_analytics/publishing/__init__.py +1 -0
  94. aelix_analytics/publishing/assets/publication.css +1 -0
  95. aelix_analytics/publishing/assets/publication.js +8 -0
  96. aelix_analytics/publishing/basis.py +115 -0
  97. aelix_analytics/publishing/build.py +890 -0
  98. aelix_analytics/publishing/checks.py +973 -0
  99. aelix_analytics/publishing/extract.py +95 -0
  100. aelix_analytics/publishing/field_policy.py +362 -0
  101. aelix_analytics/publishing/inspections.py +812 -0
  102. aelix_analytics/publishing/model.py +225 -0
  103. aelix_analytics/publishing/package.py +426 -0
  104. aelix_analytics/publishing/projection.py +469 -0
  105. aelix_analytics/publishing/publish.py +1215 -0
  106. aelix_analytics/publishing/render.py +585 -0
  107. aelix_analytics/publishing/scope.py +393 -0
  108. aelix_analytics/publishing/snapshot.py +357 -0
  109. aelix_analytics/publishing/state.py +156 -0
  110. aelix_analytics/publishing/target.py +383 -0
  111. aelix_analytics/relations.py +5364 -0
  112. aelix_analytics/report_app.py +397 -0
  113. aelix_analytics/report_renderer.py +34 -0
  114. aelix_analytics/report_renderers.py +147 -0
  115. aelix_analytics/runner.py +1229 -0
  116. aelix_analytics/template/CONTEXT.md +33 -0
  117. aelix_analytics/template/gitattributes +7 -0
  118. aelix_analytics/template/gitignore +16 -0
  119. aelix_analytics/template/pyproject.toml +22 -0
  120. aelix_analytics/tree_state.py +182 -0
  121. aelix_analytics/workspace.py +2637 -0
  122. aelix_analytics/workspace_map.py +720 -0
  123. aelix_analytics/workspace_provenance.py +499 -0
  124. aelix_analytics/workspace_relations.py +358 -0
  125. aelix_analytics/workspace_reports.py +626 -0
  126. aelix_analytics/workspace_versions.py +956 -0
  127. aelix_analytics/writer.py +1840 -0
  128. aelix_analytics-0.32.1.dist-info/METADATA +288 -0
  129. aelix_analytics-0.32.1.dist-info/RECORD +132 -0
  130. aelix_analytics-0.32.1.dist-info/WHEEL +4 -0
  131. aelix_analytics-0.32.1.dist-info/entry_points.txt +5 -0
  132. 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())