tro-utils 0.5.4__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.
@@ -0,0 +1,378 @@
1
+ """ArtifactArrangement and ArtifactLocation models.
2
+
3
+ An arrangement is a snapshot of file locations at a particular point in time,
4
+ linking each file path to a :class:`~tro_utils.models.artifact.ResearchArtifact`
5
+ stored in the :class:`~tro_utils.models.composition.ArtifactComposition`.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import json
12
+ import os
13
+ import pathlib
14
+ from dataclasses import dataclass, field
15
+ from typing import Any
16
+
17
+ from ._base import TROVModel, natural_id_key
18
+ from .artifact import ResearchArtifact
19
+ from .composition import ArtifactComposition
20
+
21
+
22
+ @dataclass
23
+ class ArtifactLocation(TROVModel):
24
+ """A single (path, artifact) binding within an arrangement."""
25
+
26
+ location_id: str
27
+ artifact_id: str
28
+ path: str
29
+
30
+ def to_jsonld(self) -> dict[str, Any]:
31
+ return {
32
+ "@id": self.location_id,
33
+ "@type": "trov:ArtifactLocation",
34
+ "trov:artifact": {"@id": self.artifact_id},
35
+ "trov:path": self.path,
36
+ }
37
+
38
+ @classmethod
39
+ def from_jsonld(cls, data: dict[str, Any]) -> "ArtifactLocation":
40
+ return cls(
41
+ location_id=data["@id"],
42
+ artifact_id=data["trov:artifact"]["@id"],
43
+ path=data["trov:path"],
44
+ )
45
+
46
+
47
+ @dataclass
48
+ class ArtifactArrangement(TROVModel):
49
+ """A snapshot of all artifact locations at a given point in time."""
50
+
51
+ arrangement_id: str
52
+ comment: str = ""
53
+ locations: list[ArtifactLocation] = field(default_factory=list)
54
+
55
+ # ------------------------------------------------------------------
56
+ # Convenience constructors
57
+ # ------------------------------------------------------------------
58
+
59
+ @classmethod
60
+ def from_directory(
61
+ cls,
62
+ directory: str | pathlib.Path,
63
+ composition: ArtifactComposition,
64
+ arrangement_id: str,
65
+ comment: str | None = None,
66
+ ignore_dirs: list[str] | None = None,
67
+ resolve_symlinks: bool = True,
68
+ ) -> "ArtifactArrangement":
69
+ """Scan *directory* and create an arrangement, updating *composition* in place.
70
+
71
+ New files are added to *composition*; existing files (by hash) are reused.
72
+
73
+ Args:
74
+ directory: Root directory to scan.
75
+ composition: The :class:`ArtifactComposition` to add new artifacts to.
76
+ arrangement_id: The ``@id`` for this arrangement (e.g. ``"arrangement/1"``).
77
+ comment: Human-readable description of this arrangement snapshot.
78
+ ignore_dirs: Directory names to skip (default: ``[".git"]``).
79
+ resolve_symlinks: Whether to follow symlinks when walking the tree.
80
+
81
+ Returns:
82
+ A new :class:`ArtifactArrangement`.
83
+ """
84
+ import magic # local import
85
+
86
+ if ignore_dirs is None:
87
+ ignore_dirs = [".git"]
88
+ if comment is None:
89
+ comment = f"Scanned {directory}"
90
+
91
+ directory = pathlib.Path(directory)
92
+ magic_wrapper = magic.Magic(mime=True, uncompress=False)
93
+
94
+ # Collect the file list first, then sort by relative path. os.walk
95
+ # yields entries in filesystem order, which differs between machines;
96
+ # since this order decides both artifact @id assignment below and the
97
+ # order of trov:hasArtifactLocation, scanning the same tree twice has
98
+ # to walk it in the same order to produce the same declaration.
99
+ discovered: list[pathlib.Path] = []
100
+ for root, dirs, files in os.walk(str(directory)):
101
+ dirs[:] = [d for d in dirs if d not in ignore_dirs]
102
+ for filename in files:
103
+ discovered.append(pathlib.Path(root) / filename)
104
+ discovered.sort(key=lambda p: p.relative_to(directory).as_posix())
105
+
106
+ # Collect sha256 for all files in the directory
107
+ file_hashes: dict[pathlib.Path, str] = {
108
+ filepath: cls._sha256_for_file(str(filepath), resolve_symlinks)
109
+ for filepath in discovered
110
+ }
111
+
112
+ # Add any new artifacts to the composition
113
+ for filepath, hash_str in file_hashes.items():
114
+ if composition.get_by_hash(hash_str) is None:
115
+ artifact_id = composition.next_artifact_id()
116
+ if filepath.is_symlink():
117
+ mime_type = "inode/symlink"
118
+ else:
119
+ mime_type = (
120
+ magic_wrapper.from_file(str(filepath))
121
+ or "application/octet-stream"
122
+ )
123
+ from .hash_value import HashValue
124
+
125
+ algorithm, value = hash_str.split(":", 1)
126
+ artifact = ResearchArtifact(
127
+ artifact_id=artifact_id,
128
+ hash=HashValue(algorithm=algorithm, value=value),
129
+ mime_type=mime_type,
130
+ )
131
+ composition.add_artifact(artifact)
132
+
133
+ # Build locations
134
+ locations: list[ArtifactLocation] = []
135
+ for i, (filepath, hash_str) in enumerate(file_hashes.items()):
136
+ artifact = composition.get_by_hash(hash_str)
137
+ assert artifact is not None # guaranteed by the loop above
138
+ rel_path = filepath.relative_to(directory).as_posix()
139
+ locations.append(
140
+ ArtifactLocation(
141
+ location_id=f"{arrangement_id}/location/{i}",
142
+ artifact_id=artifact.artifact_id,
143
+ path=rel_path,
144
+ )
145
+ )
146
+
147
+ return cls(
148
+ arrangement_id=arrangement_id,
149
+ comment=comment,
150
+ locations=locations,
151
+ )
152
+
153
+ # ------------------------------------------------------------------
154
+ # Helpers
155
+ # ------------------------------------------------------------------
156
+
157
+ @staticmethod
158
+ def _sha256_for_file(filepath: str, resolve_symlinks: bool = True) -> str:
159
+ """Return ``"sha256:<hex>"`` for *filepath*, or ``"none:"`` for symlinks/non-files."""
160
+ p = pathlib.Path(filepath)
161
+ if not p.is_file() or p.is_symlink():
162
+ return "none:"
163
+ sha256 = hashlib.sha256()
164
+ with open(filepath, "rb") as f:
165
+ for chunk in iter(lambda: f.read(4096), b""):
166
+ sha256.update(chunk)
167
+ return f"sha256:{sha256.hexdigest()}"
168
+
169
+ def to_path_hash_map(self, composition: ArtifactComposition) -> dict[str, str]:
170
+ """Return a ``{relative_path: "sha256:<hex>"}`` binding.
171
+
172
+ Requires the corresponding :class:`ArtifactComposition` to resolve
173
+ artifact IDs to hash strings.
174
+
175
+ Args:
176
+ composition: The composition that owns the artifacts referenced here.
177
+
178
+ Returns:
179
+ Dict mapping relative file path to hash string.
180
+ """
181
+ result: dict[str, str] = {}
182
+ for location in self.locations:
183
+ artifact = composition.get_by_id(location.artifact_id)
184
+ if artifact is not None:
185
+ result[location.path] = artifact.hash.to_string()
186
+ return result
187
+
188
+ # ------------------------------------------------------------------
189
+ # JSON-LD serialisation
190
+ # ------------------------------------------------------------------
191
+
192
+ def to_jsonld(self) -> dict[str, Any]:
193
+ return {
194
+ "@id": self.arrangement_id,
195
+ "@type": "trov:ArtifactArrangement",
196
+ "rdfs:comment": self.comment,
197
+ "trov:hasArtifactLocation": [
198
+ loc.to_jsonld() for loc in self._sorted_locations()
199
+ ],
200
+ }
201
+
202
+ def _sorted_locations(self) -> list[ArtifactLocation]:
203
+ """Return locations in a stable, machine-independent order.
204
+
205
+ Sorted by path so a declaration serialises identically wherever it was
206
+ produced; ``location_id`` breaks ties for the rare duplicate path.
207
+ """
208
+ return sorted(
209
+ self.locations, key=lambda loc: (loc.path, natural_id_key(loc.location_id))
210
+ )
211
+
212
+ @classmethod
213
+ def from_jsonld(cls, data: dict[str, Any]) -> "ArtifactArrangement":
214
+ """Deserialise from a JSON-LD arrangement dict.
215
+
216
+ Args:
217
+ data: Dict with ``@id``, ``rdfs:comment``, ``trov:hasArtifactLocation``.
218
+
219
+ Returns:
220
+ :class:`ArtifactArrangement` instance.
221
+ """
222
+ locations = [
223
+ ArtifactLocation.from_jsonld(loc)
224
+ for loc in data.get("trov:hasArtifactLocation", [])
225
+ ]
226
+ return cls(
227
+ arrangement_id=data["@id"],
228
+ comment=data.get("rdfs:comment", ""),
229
+ locations=locations,
230
+ )
231
+
232
+ # ------------------------------------------------------------------
233
+ # Snapshot serialisation / deserialisation
234
+ # ------------------------------------------------------------------
235
+
236
+ def to_snapshot(self, composition: ArtifactComposition) -> dict[str, Any]:
237
+ """Serialise this arrangement and its referenced artifacts as a standalone dict.
238
+
239
+ The returned structure is self-contained: it embeds the subset of
240
+ *composition* artifacts that are referenced by this arrangement so the
241
+ snapshot can be loaded into a different TRO without the original
242
+ composition.
243
+
244
+ Args:
245
+ composition: The composition that owns the artifacts referenced by
246
+ this arrangement.
247
+
248
+ Returns:
249
+ A JSON-serialisable dict.
250
+ """
251
+ artifact_ids = {loc.artifact_id for loc in self.locations}
252
+ artifacts = sorted(
253
+ (
254
+ a.to_jsonld()
255
+ for a in composition.artifacts
256
+ if a.artifact_id in artifact_ids
257
+ ),
258
+ key=lambda a: natural_id_key(a["@id"]),
259
+ )
260
+ return {
261
+ "@type": "trov:ArrangementSnapshot",
262
+ "rdfs:comment": self.comment,
263
+ "trov:hasArtifactLocation": [
264
+ loc.to_jsonld() for loc in self._sorted_locations()
265
+ ],
266
+ "trov:hasArtifact": artifacts,
267
+ }
268
+
269
+ def save_snapshot(
270
+ self, filepath: str | pathlib.Path, composition: ArtifactComposition
271
+ ) -> None:
272
+ """Write this arrangement as a standalone snapshot JSON-LD file.
273
+
274
+ Args:
275
+ filepath: Destination path (will be created/overwritten).
276
+ composition: The composition that owns the referenced artifacts.
277
+ """
278
+ with open(filepath, "w") as f:
279
+ json.dump(self.to_snapshot(composition), f, indent=2, sort_keys=True)
280
+
281
+ @classmethod
282
+ def from_snapshot(
283
+ cls,
284
+ data: dict[str, Any],
285
+ target_composition: ArtifactComposition,
286
+ arrangement_id: str,
287
+ comment: str | None = None,
288
+ ) -> "ArtifactArrangement":
289
+ """Merge snapshot data into *target_composition* and return a new arrangement.
290
+
291
+ Artifacts are matched by content hash so duplicates are never inserted.
292
+ Location IDs are rewritten to fit the new *arrangement_id*.
293
+
294
+ Args:
295
+ data: Dict previously produced by :meth:`to_snapshot`.
296
+ target_composition: The composition to merge artifacts into.
297
+ arrangement_id: The ``@id`` to assign to the new arrangement.
298
+ comment: Override the comment stored in *data* when provided.
299
+
300
+ Returns:
301
+ A new :class:`ArtifactArrangement` whose locations point to
302
+ artifacts in *target_composition*.
303
+ """
304
+ from .artifact import ResearchArtifact
305
+
306
+ # Build a local lookup: snapshot-local artifact @id to ResearchArtifact
307
+ snap_artifacts: dict[str, ResearchArtifact] = {
308
+ art_data["@id"]: ResearchArtifact.from_jsonld(art_data)
309
+ for art_data in data.get("trov:hasArtifact", [])
310
+ }
311
+
312
+ # Merge each snapshot artifact into the target composition, tracking
313
+ # IDs. Iterate in a fixed order: this decides the @id each artifact
314
+ # gets in the target composition.
315
+ id_remap: dict[str, str] = {} # snapshot_id to target composition id
316
+ for snap_id in sorted(snap_artifacts, key=natural_id_key):
317
+ artifact = snap_artifacts[snap_id]
318
+ hash_str = artifact.hash.to_string()
319
+ existing = target_composition.get_by_hash(hash_str)
320
+ if existing is not None:
321
+ id_remap[snap_id] = existing.artifact_id
322
+ else:
323
+ new_id = target_composition.next_artifact_id()
324
+ target_composition.add_artifact(
325
+ ResearchArtifact(
326
+ artifact_id=new_id,
327
+ hash=artifact.hash,
328
+ mime_type=artifact.mime_type,
329
+ )
330
+ )
331
+ id_remap[snap_id] = new_id
332
+
333
+ # Rebuild locations with remapped artifact IDs, in path order so the
334
+ # new location @ids do not depend on the snapshot's internal ordering.
335
+ locations: list[ArtifactLocation] = []
336
+ raw_locations = sorted(
337
+ data.get("trov:hasArtifactLocation", []),
338
+ key=lambda loc: (loc["trov:path"], natural_id_key(loc["@id"])),
339
+ )
340
+ for i, loc_data in enumerate(raw_locations):
341
+ snap_art_id = loc_data["trov:artifact"]["@id"]
342
+ locations.append(
343
+ ArtifactLocation(
344
+ location_id=f"{arrangement_id}/location/{i}",
345
+ artifact_id=id_remap[snap_art_id],
346
+ path=loc_data["trov:path"],
347
+ )
348
+ )
349
+
350
+ return cls(
351
+ arrangement_id=arrangement_id,
352
+ comment=comment if comment is not None else data.get("rdfs:comment", ""),
353
+ locations=locations,
354
+ )
355
+
356
+ @classmethod
357
+ def load_snapshot(
358
+ cls,
359
+ filepath: str | pathlib.Path,
360
+ target_composition: ArtifactComposition,
361
+ arrangement_id: str,
362
+ comment: str | None = None,
363
+ ) -> "ArtifactArrangement":
364
+ """Load a snapshot file and merge it into *target_composition*.
365
+
366
+ Args:
367
+ filepath: Path to a JSON-LD snapshot file previously saved with
368
+ :meth:`save_snapshot`.
369
+ target_composition: The composition to merge artifacts into.
370
+ arrangement_id: The ``@id`` to assign to the new arrangement.
371
+ comment: Override the comment stored in the file when provided.
372
+
373
+ Returns:
374
+ A new :class:`ArtifactArrangement`.
375
+ """
376
+ with open(filepath) as f:
377
+ data = json.load(f)
378
+ return cls.from_snapshot(data, target_composition, arrangement_id, comment)
@@ -0,0 +1,101 @@
1
+ """ResearchArtifact model.
2
+
3
+ Represents a single research artifact (file) tracked within a TRO
4
+ composition, including its content hash and MIME type.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import pathlib
11
+ from dataclasses import dataclass
12
+ from typing import Any
13
+
14
+ from ._base import TROVModel
15
+ from .hash_value import HashValue
16
+
17
+
18
+ @dataclass
19
+ class ResearchArtifact(TROVModel):
20
+ """A single research artifact stored in an :class:`ArtifactComposition`."""
21
+
22
+ artifact_id: str
23
+ hash: HashValue
24
+ mime_type: str
25
+
26
+ # ------------------------------------------------------------------
27
+ # Convenience constructors
28
+ # ------------------------------------------------------------------
29
+
30
+ @classmethod
31
+ def from_file(
32
+ cls, path: str | pathlib.Path, artifact_id: str
33
+ ) -> "ResearchArtifact":
34
+ """Create a ``ResearchArtifact`` by hashing a file on disk.
35
+
36
+ Args:
37
+ path: Absolute or relative path to the file.
38
+ artifact_id: The ``@id`` to assign (e.g. ``"composition/1/artifact/3"``).
39
+
40
+ Returns:
41
+ A new :class:`ResearchArtifact`.
42
+
43
+ Raises:
44
+ FileNotFoundError: If *path* does not point to an existing regular file.
45
+ """
46
+ import magic # local import — optional dep
47
+
48
+ p = pathlib.Path(path)
49
+ if not p.is_file():
50
+ raise FileNotFoundError(f"Not a regular file: {p}")
51
+
52
+ sha256 = hashlib.sha256()
53
+ with open(p, "rb") as f:
54
+ for chunk in iter(lambda: f.read(4096), b""):
55
+ sha256.update(chunk)
56
+
57
+ hash_value = HashValue(algorithm="sha256", value=sha256.hexdigest())
58
+
59
+ if p.is_symlink():
60
+ mime_type = "inode/symlink"
61
+ else:
62
+ magic_wrapper = magic.Magic(mime=True, uncompress=False)
63
+ mime_type = magic_wrapper.from_file(str(p)) or "application/octet-stream"
64
+
65
+ return cls(artifact_id=artifact_id, hash=hash_value, mime_type=mime_type)
66
+
67
+ # ------------------------------------------------------------------
68
+ # JSON-LD serialisation
69
+ # ------------------------------------------------------------------
70
+
71
+ def to_jsonld(self) -> dict[str, Any]:
72
+ return {
73
+ "@id": self.artifact_id,
74
+ "@type": "trov:ResearchArtifact",
75
+ "trov:hash": self.hash.to_jsonld(),
76
+ "trov:mimeType": self.mime_type,
77
+ }
78
+
79
+ @classmethod
80
+ def from_jsonld(cls, data: dict[str, Any]) -> "ResearchArtifact":
81
+ """Deserialise from a JSON-LD artifact dict.
82
+
83
+ Args:
84
+ data: Dict with ``@id``, ``trov:hash``/``trov:sha256``, ``trov:mimeType``.
85
+
86
+ Returns:
87
+ :class:`ResearchArtifact` instance.
88
+ """
89
+ # Support both new trov:hash and legacy trov:sha256
90
+ if "trov:hash" in data:
91
+ h = HashValue.from_jsonld(data["trov:hash"])
92
+ elif "trov:sha256" in data:
93
+ h = HashValue(algorithm="sha256", value=data["trov:sha256"])
94
+ else:
95
+ raise ValueError(f"Artifact has no recognisable hash field: {data!r}")
96
+
97
+ return cls(
98
+ artifact_id=data["@id"],
99
+ hash=h,
100
+ mime_type=data.get("trov:mimeType", "application/octet-stream"),
101
+ )
@@ -0,0 +1,51 @@
1
+ """TROAttribute model.
2
+
3
+ Represents a TRO-level attribute warranted by a performance attribute.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Any
10
+
11
+ from ._base import TROVModel
12
+
13
+
14
+ @dataclass
15
+ class TROAttribute(TROVModel):
16
+ """A TRO-level attribute (e.g. ``trov:IncludesAllInputData``).
17
+
18
+ TRO attributes are warranted by one or more
19
+ :class:`~tro_utils.models.performance.PerformanceAttribute` instances.
20
+ """
21
+
22
+ attribute_id: str
23
+ attribute_type: str
24
+ warranted_by_id: str
25
+
26
+ # ------------------------------------------------------------------
27
+ # JSON-LD serialisation
28
+ # ------------------------------------------------------------------
29
+
30
+ def to_jsonld(self) -> dict[str, Any]:
31
+ return {
32
+ "@id": self.attribute_id,
33
+ "@type": self.attribute_type,
34
+ "trov:warrantedBy": {"@id": self.warranted_by_id},
35
+ }
36
+
37
+ @classmethod
38
+ def from_jsonld(cls, data: dict[str, Any]) -> "TROAttribute":
39
+ """Deserialise from a JSON-LD TRO attribute dict.
40
+
41
+ Args:
42
+ data: Dict with ``@id``, ``@type``, ``trov:warrantedBy``.
43
+
44
+ Returns:
45
+ :class:`TROAttribute` instance.
46
+ """
47
+ return cls(
48
+ attribute_id=data["@id"],
49
+ attribute_type=data["@type"],
50
+ warranted_by_id=data["trov:warrantedBy"]["@id"],
51
+ )
@@ -0,0 +1,144 @@
1
+ """ArtifactComposition and CompositionFingerprint models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ from dataclasses import dataclass, field
7
+ from typing import Any
8
+
9
+ from ._base import TROVModel, natural_id_key
10
+ from .artifact import ResearchArtifact
11
+ from .hash_value import HashValue
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class CompositionFingerprint(TROVModel):
16
+ """SHA-256 fingerprint over the sorted artifact hashes in a composition."""
17
+
18
+ hash: HashValue
19
+
20
+ @classmethod
21
+ def compute(cls, artifacts: list[ResearchArtifact]) -> "CompositionFingerprint":
22
+ """Compute the fingerprint for a list of artifacts.
23
+
24
+ The fingerprint is sha256 of the sorted, concatenated artifact hash values,
25
+ matching the existing ``TRO.calculate_fingerprint`` logic.
26
+
27
+ Args:
28
+ artifacts: List of :class:`ResearchArtifact` to fingerprint.
29
+
30
+ Returns:
31
+ A new :class:`CompositionFingerprint`.
32
+ """
33
+ hash_values = sorted(a.hash.value for a in artifacts)
34
+ digest = hashlib.sha256("".join(hash_values).encode("utf-8")).hexdigest()
35
+ return cls(hash=HashValue(algorithm="sha256", value=digest))
36
+
37
+ # ------------------------------------------------------------------
38
+ # JSON-LD serialisation
39
+ # ------------------------------------------------------------------
40
+
41
+ def to_jsonld(self) -> dict[str, Any]:
42
+ return {
43
+ "@id": "fingerprint",
44
+ "@type": "trov:CompositionFingerprint",
45
+ "trov:hash": self.hash.to_jsonld(),
46
+ }
47
+
48
+ @classmethod
49
+ def from_jsonld(cls, data: dict[str, Any]) -> "CompositionFingerprint":
50
+ return cls(hash=HashValue.from_jsonld(data["trov:hash"]))
51
+
52
+
53
+ @dataclass
54
+ class ArtifactComposition(TROVModel):
55
+ """Registry of all unique :class:`ResearchArtifact` objects in a TRO."""
56
+
57
+ composition_id: str = "composition/1"
58
+ artifacts: list[ResearchArtifact] = field(default_factory=list)
59
+ fingerprint: CompositionFingerprint | None = None
60
+
61
+ # ------------------------------------------------------------------
62
+ # Mutation
63
+ # ------------------------------------------------------------------
64
+
65
+ def add_artifact(self, artifact: ResearchArtifact) -> None:
66
+ """Append *artifact* and recompute the fingerprint.
67
+
68
+ Args:
69
+ artifact: The artifact to add.
70
+ """
71
+ self.artifacts.append(artifact)
72
+ self._recompute_fingerprint()
73
+
74
+ def _recompute_fingerprint(self) -> None:
75
+ self.fingerprint = CompositionFingerprint.compute(self.artifacts)
76
+
77
+ # ------------------------------------------------------------------
78
+ # Lookup helpers
79
+ # ------------------------------------------------------------------
80
+
81
+ def get_by_hash(self, hash_str: str) -> ResearchArtifact | None:
82
+ """Return the artifact whose hash string matches *hash_str*, or ``None``.
83
+
84
+ Args:
85
+ hash_str: Hash string in ``"<algorithm>:<value>"`` form.
86
+ """
87
+ for artifact in self.artifacts:
88
+ if artifact.hash.to_string() == hash_str:
89
+ return artifact
90
+ return None
91
+
92
+ def get_by_id(self, artifact_id: str) -> ResearchArtifact | None:
93
+ """Return the artifact with the given ``@id``, or ``None``."""
94
+ for artifact in self.artifacts:
95
+ if artifact.artifact_id == artifact_id:
96
+ return artifact
97
+ return None
98
+
99
+ def next_artifact_id(self) -> str:
100
+ """Return the next sequential artifact ``@id``."""
101
+ return f"{self.composition_id}/artifact/{len(self.artifacts)}"
102
+
103
+ # ------------------------------------------------------------------
104
+ # JSON-LD serialisation
105
+ # ------------------------------------------------------------------
106
+
107
+ def to_jsonld(self) -> dict[str, Any]:
108
+ result: dict[str, Any] = {
109
+ "@id": self.composition_id,
110
+ "@type": "trov:ArtifactComposition",
111
+ "trov:hasArtifact": sorted(
112
+ [a.to_jsonld() for a in self.artifacts],
113
+ key=lambda x: natural_id_key(x["@id"]),
114
+ ),
115
+ }
116
+ if self.fingerprint:
117
+ result["trov:hasFingerprint"] = self.fingerprint.to_jsonld()
118
+ return result
119
+
120
+ @classmethod
121
+ def from_jsonld(cls, data: dict[str, Any]) -> "ArtifactComposition":
122
+ """Deserialise from a JSON-LD composition dict.
123
+
124
+ Args:
125
+ data: Dict with ``@id``, ``trov:hasArtifact`` list, and optional fingerprint.
126
+
127
+ Returns:
128
+ :class:`ArtifactComposition` instance.
129
+ """
130
+ artifacts = [
131
+ ResearchArtifact.from_jsonld(a) for a in data.get("trov:hasArtifact", [])
132
+ ]
133
+ fingerprint = None
134
+ if "trov:hasFingerprint" in data:
135
+ fingerprint = CompositionFingerprint.from_jsonld(
136
+ data["trov:hasFingerprint"]
137
+ )
138
+
139
+ obj = cls(
140
+ composition_id=data.get("@id", "composition/1"),
141
+ artifacts=artifacts,
142
+ fingerprint=fingerprint,
143
+ )
144
+ return obj