ruml-parser 1.0.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 (72) hide show
  1. ruml_parser/__init__.py +183 -0
  2. ruml_parser/internal/__init__.py +2 -0
  3. ruml_parser/internal/extension.py +91 -0
  4. ruml_parser/internal/mapping.py +731 -0
  5. ruml_parser/internal/ruml/__init__.py +237 -0
  6. ruml_parser/internal/ruml/actions/__init__.py +2 -0
  7. ruml_parser/internal/ruml/actions/actions_capability_declaration.py +23 -0
  8. ruml_parser/internal/ruml/actions/actions_node_capability.py +40 -0
  9. ruml_parser/internal/ruml/ai_query/__init__.py +2 -0
  10. ruml_parser/internal/ruml/ai_query/ai_query_capability_declaration.py +25 -0
  11. ruml_parser/internal/ruml/ai_query/ai_query_node_capability.py +66 -0
  12. ruml_parser/internal/ruml/aliases.py +93 -0
  13. ruml_parser/internal/ruml/capability/__init__.py +2 -0
  14. ruml_parser/internal/ruml/capability/abstract_capability_declaration.py +23 -0
  15. ruml_parser/internal/ruml/capability/abstract_node_capability.py +14 -0
  16. ruml_parser/internal/ruml/capability/capability_declaration.py +52 -0
  17. ruml_parser/internal/ruml/capability/capability_declarations.py +199 -0
  18. ruml_parser/internal/ruml/capability/extension_node_capability.py +17 -0
  19. ruml_parser/internal/ruml/capability/node_capabilities.py +113 -0
  20. ruml_parser/internal/ruml/capability/other_node_capability.py +21 -0
  21. ruml_parser/internal/ruml/context/__init__.py +2 -0
  22. ruml_parser/internal/ruml/context/context.py +40 -0
  23. ruml_parser/internal/ruml/context/context_capability_declaration.py +25 -0
  24. ruml_parser/internal/ruml/context/context_refs_node_capability.py +17 -0
  25. ruml_parser/internal/ruml/datapoints/__init__.py +2 -0
  26. ruml_parser/internal/ruml/datapoints/datapoint.py +101 -0
  27. ruml_parser/internal/ruml/datapoints/datapoint_set.py +20 -0
  28. ruml_parser/internal/ruml/datapoints/datapoints_capability_declaration.py +29 -0
  29. ruml_parser/internal/ruml/datapoints/option.py +11 -0
  30. ruml_parser/internal/ruml/expression/__init__.py +2 -0
  31. ruml_parser/internal/ruml/expression/expression_capability_declaration.py +23 -0
  32. ruml_parser/internal/ruml/expression/expression_node_capability.py +20 -0
  33. ruml_parser/internal/ruml/metadata.py +83 -0
  34. ruml_parser/internal/ruml/nodes/__init__.py +2 -0
  35. ruml_parser/internal/ruml/nodes/abstract_node.py +29 -0
  36. ruml_parser/internal/ruml/nodes/branch_node.py +15 -0
  37. ruml_parser/internal/ruml/nodes/leaf_node.py +10 -0
  38. ruml_parser/internal/ruml/nodes/node.py +6 -0
  39. ruml_parser/internal/ruml/protocol/__init__.py +2 -0
  40. ruml_parser/internal/ruml/protocol/protocol_capability_declaration.py +29 -0
  41. ruml_parser/internal/ruml/query/__init__.py +2 -0
  42. ruml_parser/internal/ruml/query/query_capability_declaration.py +23 -0
  43. ruml_parser/internal/ruml/query/query_node_capability.py +17 -0
  44. ruml_parser/internal/ruml/ruml_document.py +45 -0
  45. ruml_parser/internal/ruml/text_reference/__init__.py +2 -0
  46. ruml_parser/internal/ruml/text_reference/text.py +69 -0
  47. ruml_parser/internal/ruml/text_reference/text_reference_capability_declaration.py +25 -0
  48. ruml_parser/internal/ruml/text_reference/text_refs_node_capability.py +32 -0
  49. ruml_parser/internal/ruml/tree/__init__.py +2 -0
  50. ruml_parser/internal/ruml/tree/tree_capability_declarations.py +30 -0
  51. ruml_parser/internal/validation/__init__.py +14 -0
  52. ruml_parser/internal/validation/capabilities.py +227 -0
  53. ruml_parser/internal/validation/contexts.py +51 -0
  54. ruml_parser/internal/validation/datapoint_sets.py +125 -0
  55. ruml_parser/internal/validation/modular.py +42 -0
  56. ruml_parser/internal/validation/recursion.py +197 -0
  57. ruml_parser/internal/validation/root.py +36 -0
  58. ruml_parser/internal/validation/texts.py +50 -0
  59. ruml_parser/model/__init__.py +2 -0
  60. ruml_parser/model/ruml.py +1156 -0
  61. ruml_parser/model/ruml_result.py +430 -0
  62. ruml_parser/node_result_status.py +19 -0
  63. ruml_parser/pydantic.py +96 -0
  64. ruml_parser/ruml_parser.py +75 -0
  65. ruml_parser/schema_files.py +23 -0
  66. ruml_parser/schema_validation.py +354 -0
  67. ruml_parser/structural_error.py +36 -0
  68. ruml_parser/text.py +220 -0
  69. ruml_parser-1.0.0.dist-info/METADATA +119 -0
  70. ruml_parser-1.0.0.dist-info/RECORD +72 -0
  71. ruml_parser-1.0.0.dist-info/WHEEL +4 -0
  72. ruml_parser-1.0.0.dist-info/licenses/LICENSE +73 -0
@@ -0,0 +1,731 @@
1
+ # SPDX-FileCopyrightText: 2026 Rulemapping Group GmbH
2
+ # SPDX-License-Identifier: Apache-2.0
3
+ """Mappers to convert schema-generated RUML models to our hand-written dataclasses.
4
+
5
+ The entry point is `to_internal` (which `RumlParser` and `ParsedRumlDocument` call);
6
+ the rest are the per-type mappers it is built from, named after the type they produce.
7
+
8
+ As the mapping functions access all fields of both sides (Pydantic + internal), this
9
+ module doubles as a kind of "sync check" between both when typechecked. See the
10
+ docstring of `ruml_parser.internal.ruml`.
11
+ """
12
+
13
+ from collections.abc import Callable, Iterable, Mapping
14
+ from functools import partial
15
+ from typing import Any
16
+
17
+ from pydantic import BaseModel, TypeAdapter, ValidationError
18
+
19
+ from ruml_parser.internal.extension import CapabilityExtension
20
+ from ruml_parser.internal.ruml import (
21
+ Action,
22
+ ActionsCapabilityDeclaration,
23
+ ActionsNodeCapability,
24
+ AiQueryCapabilityDeclaration,
25
+ AiQueryDeclarationConfig,
26
+ AiQueryNodeCapability,
27
+ AiQueryNodeConfig,
28
+ Author,
29
+ BranchNode,
30
+ CapabilityDeclarations,
31
+ CapabilityDeclarationWithData,
32
+ CapabilityId,
33
+ CapabilityPayload,
34
+ CapabilityRole,
35
+ Cardinality,
36
+ Context,
37
+ ContextCapabilityDeclaration,
38
+ ContextInput,
39
+ ContextRefsNodeCapability,
40
+ Datapoint,
41
+ DatapointId,
42
+ DatapointsCapabilityDeclaration,
43
+ DatapointSet,
44
+ DerivedFrom,
45
+ DraftCapabilityDeclaration,
46
+ ExpressionCapabilityDeclaration,
47
+ ExpressionNodeCapability,
48
+ ExtensionCapabilityDeclaration,
49
+ ExternalBinding,
50
+ InputBinding,
51
+ LeafNode,
52
+ Metadata,
53
+ Node,
54
+ NodeCapabilities,
55
+ NodeCapability,
56
+ Option,
57
+ OtherNodeCapability,
58
+ ProtocolCapabilityDeclaration,
59
+ ProtocolConfig,
60
+ QueryCapabilityDeclaration,
61
+ QueryInputs,
62
+ QueryNodeCapability,
63
+ RumlDocument,
64
+ Text,
65
+ TextAnchor,
66
+ TextReferenceCapabilityDeclaration,
67
+ TextRefsNodeCapability,
68
+ TextSource,
69
+ TreeIncludeCapabilityDeclaration,
70
+ TreeReferenceCapabilityDeclaration,
71
+ Validation,
72
+ )
73
+ from ruml_parser.internal.validation.capabilities import (
74
+ reject_duplicate_capability_ids,
75
+ reject_invalid_number_of_combiners_per_node,
76
+ reject_repeated_data_capabilities,
77
+ reject_undeclared_node_capabilities,
78
+ )
79
+ from ruml_parser.internal.validation.contexts import (
80
+ reject_undeclared_context_inputs,
81
+ )
82
+ from ruml_parser.internal.validation.datapoint_sets import (
83
+ reject_recursive_sets,
84
+ reject_undeclared_set_references,
85
+ )
86
+ from ruml_parser.internal.validation.modular import reject_unmarked_modular_nodes
87
+ from ruml_parser.internal.validation.recursion import reject_forbidden_recursion
88
+ from ruml_parser.internal.validation.root import reject_root_as_child
89
+ from ruml_parser.internal.validation.texts import reject_undeclared_text_inputs
90
+ from ruml_parser.model import ruml as model
91
+ from ruml_parser.model.ruml import NodeCapabilityEntry
92
+ from ruml_parser.schema_validation import json_pointer
93
+ from ruml_parser.structural_error import RumlStructuralError, StructuralViolation
94
+
95
+ DRAFT_CAPABILITY_ID_PREFIX = "ruml:draft/"
96
+ """Every draft capability id starts with this; no other kind of id does."""
97
+
98
+ type _CapabilityEntry = model.CapabilityEntry | model.NodeCapabilityEntry
99
+ """A capability entry of either level: `{id, payload}` (plus `required` at the root)."""
100
+
101
+ _ACTIONS_ADAPTER = TypeAdapter[model.Actions](model.Actions)
102
+ """Validates a node's `ruml:actions` payload; a union, so a `TypeAdapter` is needed."""
103
+
104
+
105
+ def to_internal(
106
+ document: model.RumlRulemappingLogicFormat,
107
+ extensions: Iterable[CapabilityExtension] = (),
108
+ ) -> RumlDocument:
109
+ """Translate a validated RUML document into the internal model.
110
+
111
+ The result also satisfies the spec's cross-object rules, which
112
+ `ruml_parser.internal.validation` checks once the mapping has built it.
113
+
114
+ Args:
115
+ document: The document to translate.
116
+ extensions: Models of draft or third-party capabilities the document may use
117
+ (see ``CapabilityExtension``); without one, a capability's entries keep
118
+ their free-form payloads.
119
+
120
+ Raises:
121
+ ValueError: If validating the document turned up problems with it. Such issues
122
+ are due to Structural (see ADR 0001) invariants that neither the schema nor
123
+ generated models can or should enforce, so we check them here instead.
124
+ """
125
+ extensions_by_id = {extension.id: extension for extension in extensions}
126
+ result = RumlDocument(
127
+ spec_version=document.field_specVersion,
128
+ metadata=_metadata(document.metadata),
129
+ capabilities=_capabilities(document.capabilities, extensions_by_id),
130
+ nodes={
131
+ lex_id: _node(node, extensions_by_id)
132
+ for lex_id, node in document.rulemap.nodes.items()
133
+ },
134
+ )
135
+
136
+ # Validations:
137
+ # This is the Structural category of the error-handling split in ADR 0001 (`docs/
138
+ # adr/0001-error-handling-layers.md`): every error decidable from the RUML document
139
+ # alone belongs here, and must reference a RUML spec error code rather than an
140
+ # invented message.
141
+ reject_duplicate_capability_ids(result)
142
+ reject_undeclared_node_capabilities(result)
143
+ reject_repeated_data_capabilities(result)
144
+ reject_undeclared_context_inputs(result)
145
+ reject_undeclared_text_inputs(result)
146
+ reject_undeclared_set_references(result)
147
+ reject_recursive_sets(result)
148
+ reject_root_as_child(result)
149
+ reject_unmarked_modular_nodes(result)
150
+ reject_forbidden_recursion(result)
151
+ reject_invalid_number_of_combiners_per_node(result)
152
+ for extension in extensions_by_id.values():
153
+ extension.validate(result)
154
+
155
+ return result
156
+
157
+
158
+ # --- Metadata ---------------------------------------------------------------------------
159
+
160
+
161
+ def _metadata(src: model.Metadata) -> Metadata:
162
+ return Metadata(
163
+ id=src.id,
164
+ title=src.title,
165
+ description=src.description,
166
+ version=src.version,
167
+ created=src.created,
168
+ modified=src.modified,
169
+ status=src.status,
170
+ comment=src.comment,
171
+ document_type=src.documentType,
172
+ authors=[_author(author) for author in src.authors or ()],
173
+ organization=src.organization,
174
+ jurisdiction=src.jurisdiction,
175
+ legal_domain=src.legalDomain,
176
+ tags=list(src.tags or ()),
177
+ derived_from=_map_if_not_none(_derived_from, src.derivedFrom),
178
+ language=src.language,
179
+ valid_from=src.validFrom,
180
+ valid_until=src.validUntil,
181
+ replaces=src.replaces,
182
+ replaced_by=src.replacedBy,
183
+ )
184
+
185
+
186
+ def _author(src: model.Author) -> Author:
187
+ return Author(name=src.name, email=src.email, organization=src.organization)
188
+
189
+
190
+ def _derived_from(src: model.DerivedFrom) -> DerivedFrom:
191
+ return DerivedFrom(
192
+ original_id=src.originalId,
193
+ original_hash=src.originalHash,
194
+ original_status=src.originalStatus,
195
+ derivation_type=src.derivationType,
196
+ derived_at=src.derivedAt,
197
+ derived_by=src.derivedBy,
198
+ )
199
+
200
+
201
+ # --- Root-level capabilities ----------------------------------------------------------
202
+
203
+
204
+ def _capabilities(
205
+ src: model.Capabilities | None,
206
+ extensions: Mapping[CapabilityId, CapabilityExtension],
207
+ ) -> CapabilityDeclarations:
208
+ datapoints: DatapointsCapabilityDeclaration | None = None
209
+ text_reference: TextReferenceCapabilityDeclaration | None = None
210
+ tree_reference: TreeReferenceCapabilityDeclaration | None = None
211
+ tree_include: TreeIncludeCapabilityDeclaration | None = None
212
+ context: ContextCapabilityDeclaration | None = None
213
+ query: QueryCapabilityDeclaration | None = None
214
+ ai_query: AiQueryCapabilityDeclaration | None = None
215
+ expression: ExpressionCapabilityDeclaration | None = None
216
+ actions: ActionsCapabilityDeclaration | None = None
217
+ protocol: ProtocolCapabilityDeclaration | None = None
218
+ draft: dict[str, DraftCapabilityDeclaration] = {}
219
+ third_party: dict[str, CapabilityDeclarationWithData] = {}
220
+ extended: dict[str, ExtensionCapabilityDeclaration] = {}
221
+ violations: list[StructuralViolation] = []
222
+ for index, entry in enumerate(src or ()):
223
+ required = _default_if_none(entry.required, False)
224
+ match capability_id := str(entry.id):
225
+ case model.OfficialCapabilityId.ruml_datapoints:
226
+ datapoints = _capability_datapoints(
227
+ required, _payload(model.DatapointsPayload, entry)
228
+ )
229
+ case model.OfficialCapabilityId.ruml_text_reference:
230
+ text_reference = _capability_text_reference(
231
+ required, _payload(model.TextReferencePayload, entry)
232
+ )
233
+ case model.OfficialCapabilityId.ruml_tree_reference:
234
+ tree_reference = TreeReferenceCapabilityDeclaration(required=required)
235
+ case model.OfficialCapabilityId.ruml_tree_include:
236
+ tree_include = TreeIncludeCapabilityDeclaration(required=required)
237
+ case model.OfficialCapabilityId.ruml_context:
238
+ context = _capability_context(
239
+ required, _payload(model.ContextPayload, entry)
240
+ )
241
+ case model.OfficialCapabilityId.ruml_query:
242
+ query = QueryCapabilityDeclaration(
243
+ required=required, config=_payload(model.PlainPayload, entry).config
244
+ )
245
+ case model.OfficialCapabilityId.ruml_ai_query:
246
+ ai_query = _capability_ai_query_root(
247
+ required, _payload(model.AiQueryPayload, entry)
248
+ )
249
+ case model.OfficialCapabilityId.ruml_expression:
250
+ expression = ExpressionCapabilityDeclaration(
251
+ required=required, config=_payload(model.PlainPayload, entry).config
252
+ )
253
+ case model.OfficialCapabilityId.ruml_actions:
254
+ actions = ActionsCapabilityDeclaration(
255
+ required=required, config=_payload(model.PlainPayload, entry).config
256
+ )
257
+ case model.OfficialCapabilityId.ruml_protocol:
258
+ protocol = _capability_protocol(
259
+ required, _payload(model.ProtocolPayload, entry)
260
+ )
261
+ case _:
262
+ # Every id the cases above do not catch is a non-official one.
263
+ if (role := entry.role) is None:
264
+ violations.append(_undeclared_role(index, capability_id))
265
+ elif capability_id in extensions:
266
+ parsing_function = partial(
267
+ extensions[capability_id].declaration, required=required
268
+ )
269
+ declaration = _parsed_payload(parsing_function, entry)
270
+ if declaration.role != role:
271
+ violations.append(
272
+ _mismatched_role(index, capability_id, role, declaration)
273
+ )
274
+ extended[capability_id] = declaration
275
+ elif capability_id.startswith(DRAFT_CAPABILITY_ID_PREFIX):
276
+ draft[capability_id] = _capability_draft(
277
+ capability_id,
278
+ required,
279
+ role,
280
+ _payload(model.PlainPayload, entry),
281
+ )
282
+ else:
283
+ # A vendor payload the spec leaves open — no model prescribes it.
284
+ third_party[capability_id] = _capability_with_data(
285
+ capability_id, required, role, entry.payload
286
+ )
287
+ if violations:
288
+ raise RumlStructuralError(violations)
289
+ return CapabilityDeclarations(
290
+ datapoints=datapoints,
291
+ text_reference=text_reference,
292
+ tree_reference=tree_reference,
293
+ tree_include=tree_include,
294
+ context=context,
295
+ query=query,
296
+ ai_query=ai_query,
297
+ expression=expression,
298
+ actions=actions,
299
+ protocol=protocol,
300
+ draft=draft,
301
+ third_party=third_party,
302
+ extensions=extended,
303
+ declaration_order=[str(entry.id) for entry in src or ()],
304
+ )
305
+
306
+
307
+ def _undeclared_role(index: int, capability_id: CapabilityId) -> StructuralViolation:
308
+ return StructuralViolation(
309
+ rule="CAP-03",
310
+ message=f"capability {capability_id!r} does not declare its role"
311
+ " (chapter 4.2: a non-official capability must)",
312
+ paths=[json_pointer(("capabilities", index))],
313
+ )
314
+
315
+
316
+ def _mismatched_role(
317
+ index: int,
318
+ capability_id: CapabilityId,
319
+ declared: CapabilityRole,
320
+ implementation: ExtensionCapabilityDeclaration,
321
+ ) -> StructuralViolation:
322
+ return StructuralViolation(
323
+ rule="CAP-04",
324
+ message=f"capability {capability_id!r} is declared with the role"
325
+ f" {declared.value!r}, but this parser implements it with the role"
326
+ f" {implementation.role.value!r}",
327
+ paths=[json_pointer(("capabilities", index, "role"))],
328
+ )
329
+
330
+
331
+ def _capability_draft(
332
+ id: CapabilityId,
333
+ required: bool,
334
+ role: CapabilityRole,
335
+ payload: model.PlainPayload,
336
+ ) -> DraftCapabilityDeclaration:
337
+ return DraftCapabilityDeclaration(
338
+ id=id, required=required, role=role, config=payload.config
339
+ )
340
+
341
+
342
+ def _capability_with_data(
343
+ id: CapabilityId,
344
+ required: bool,
345
+ role: CapabilityRole,
346
+ payload: Mapping[str, Any] | None,
347
+ ) -> CapabilityDeclarationWithData:
348
+ payload = payload or {}
349
+ data = payload.get("data")
350
+ config = payload.get("config")
351
+ return CapabilityDeclarationWithData(
352
+ id=id,
353
+ required=required,
354
+ role=role,
355
+ data=data if isinstance(data, Mapping) else {},
356
+ config=config if isinstance(config, Mapping) else None,
357
+ )
358
+
359
+
360
+ def _capability_datapoints(
361
+ required: bool, payload: model.DatapointsPayload
362
+ ) -> DatapointsCapabilityDeclaration:
363
+ return DatapointsCapabilityDeclaration(
364
+ required=required,
365
+ data=_datapoints(payload.data),
366
+ sets={key: _datapoint_set(set_) for key, set_ in (payload.sets or {}).items()},
367
+ )
368
+
369
+
370
+ def _datapoint_set(src: model.DatapointSet) -> DatapointSet:
371
+ return DatapointSet(
372
+ name=src.name, description=src.description, fields=_datapoints(src.fields)
373
+ )
374
+
375
+
376
+ def _datapoints(
377
+ src: Mapping[DatapointId, model.Datapoint] | None,
378
+ ) -> dict[DatapointId, Datapoint]:
379
+ return {key: _datapoint(datapoint) for key, datapoint in (src or {}).items()}
380
+
381
+
382
+ def _datapoint(src: model.Datapoint) -> Datapoint:
383
+ return Datapoint(
384
+ name=src.name,
385
+ type=src.type,
386
+ description=src.description,
387
+ unit=src.unit,
388
+ sensitive=_default_if_none(src.sensitive, False),
389
+ format=src.format,
390
+ options=[_option(option) for option in src.options or ()],
391
+ binding=_binding(src.binding),
392
+ validation=_map_if_not_none(_validation, src.validation),
393
+ set=src.set,
394
+ cardinality=_map_if_not_none(_cardinality, src.cardinality),
395
+ )
396
+
397
+
398
+ def _cardinality(src: model.Cardinality) -> Cardinality:
399
+ return Cardinality(min=src.min, max=src.max)
400
+
401
+
402
+ def _option(src: model.Option) -> Option:
403
+ return Option(value=src.value, label=src.label)
404
+
405
+
406
+ def _binding(src: model.Binding) -> InputBinding | ExternalBinding:
407
+ # The schema describes every binding kind (input, external, computed) with one
408
+ # object, so `model.Binding` carries the fields of all kinds; `type` says which
409
+ # kind a binding is, and thus which of its fields apply.
410
+ match src.type:
411
+ case model.Type1.external:
412
+ return ExternalBinding(
413
+ ref=_required_field(src.ref, "binding.ref"),
414
+ description=src.description,
415
+ source_type=src.sourceType,
416
+ fallback=_map_if_not_none(_input_binding, src.fallback),
417
+ )
418
+ case model.Type1.computed:
419
+ raise NotImplementedError(
420
+ "a computed datapoint binding is not supported yet"
421
+ )
422
+ case _:
423
+ return _input_binding(src)
424
+
425
+
426
+ def _required_field[T](value: T | None, field: str) -> T:
427
+ """Return a field the schema requires for this binding kind but types optional."""
428
+ if value is None:
429
+ raise ValueError(f"{field} is required for this binding kind")
430
+ return value
431
+
432
+
433
+ def _input_binding(src: model.Binding | model.Fallback) -> InputBinding:
434
+ return InputBinding(
435
+ hint=src.hint, placeholder=src.placeholder, default_value=src.defaultValue
436
+ )
437
+
438
+
439
+ def _validation(src: model.Validation) -> Validation:
440
+ return Validation(
441
+ required=src.required,
442
+ min=src.min,
443
+ max=src.max,
444
+ min_length=src.minLength,
445
+ max_length=src.maxLength,
446
+ pattern=src.pattern,
447
+ enum=None if src.enum is None else list(src.enum),
448
+ message=src.message,
449
+ )
450
+
451
+
452
+ def _capability_text_reference(
453
+ required: bool, payload: model.TextReferencePayload
454
+ ) -> TextReferenceCapabilityDeclaration:
455
+ return TextReferenceCapabilityDeclaration(
456
+ required=required,
457
+ data={key: _text(text) for key, text in (payload.data or {}).items()},
458
+ )
459
+
460
+
461
+ def _text(src: model.Text) -> Text:
462
+ return Text(
463
+ title=src.title,
464
+ uri=src.uri,
465
+ timestamp=src.timestamp,
466
+ status=src.status,
467
+ type=_default_if_none(src.type, model.Type2.embedded),
468
+ text=src.text,
469
+ content=_map_if_not_none(_text_content, src.content),
470
+ digest=src.digest,
471
+ source=_map_if_not_none(_text_source, src.source),
472
+ url=_map_if_not_none(str, src.url),
473
+ container_path=src.containerPath,
474
+ ref=src.ref,
475
+ version=src.version,
476
+ valid_from=src.validFrom,
477
+ valid_until=src.validUntil,
478
+ language=src.language,
479
+ is_referenced=_default_if_none(src.isReferenced, True),
480
+ )
481
+
482
+
483
+ def _text_content(src: model.RumlTextDocument) -> Mapping[str, Any]:
484
+ return src.model_dump(mode="json", exclude_none=True)
485
+
486
+
487
+ def _text_source(src: model.TextSource) -> TextSource:
488
+ return TextSource(uri=src.uri, digest=src.digest, terms=src.terms)
489
+
490
+
491
+ def _capability_context(
492
+ required: bool, payload: model.ContextPayload
493
+ ) -> ContextCapabilityDeclaration:
494
+ return ContextCapabilityDeclaration(
495
+ required=required,
496
+ data={key: _context(context) for key, context in (payload.data or {}).items()},
497
+ )
498
+
499
+
500
+ def _context(src: model.Context) -> Context:
501
+ return Context(
502
+ title=src.title,
503
+ category=src.category,
504
+ type=_default_if_none(src.type, model.Type4.embedded),
505
+ timestamp=src.timestamp,
506
+ subject=_default_if_none(src.subject, False),
507
+ metadata=src.metadata or {},
508
+ content=src.content,
509
+ source=src.source,
510
+ url=_map_if_not_none(str, src.url),
511
+ container_path=src.containerPath,
512
+ ref=src.ref,
513
+ hash=src.hash,
514
+ access_date=src.accessDate,
515
+ )
516
+
517
+
518
+ def _capability_ai_query_root(
519
+ required: bool, payload: model.AiQueryPayload
520
+ ) -> AiQueryCapabilityDeclaration:
521
+ return AiQueryCapabilityDeclaration(
522
+ required=required,
523
+ config=_map_if_not_none(_ai_query_root_config, payload.config),
524
+ )
525
+
526
+
527
+ def _ai_query_root_config(src: model.Config1) -> AiQueryDeclarationConfig:
528
+ return AiQueryDeclarationConfig(system_prompt=src.systemPrompt)
529
+
530
+
531
+ def _capability_protocol(
532
+ required: bool, payload: model.ProtocolPayload
533
+ ) -> ProtocolCapabilityDeclaration:
534
+ config = payload.config or model.Config2()
535
+ return ProtocolCapabilityDeclaration(
536
+ required=required, config=_protocol_config(config)
537
+ )
538
+
539
+
540
+ def _protocol_config(src: model.Config2) -> ProtocolConfig:
541
+ return ProtocolConfig(level=_default_if_none(src.level, model.Level.standard))
542
+
543
+
544
+ # --- Node-level capabilities ----------------------------------------------------------
545
+
546
+
547
+ def _node_capabilities(
548
+ src: model.NodeCapabilities | None,
549
+ extensions: Mapping[CapabilityId, CapabilityExtension],
550
+ ) -> NodeCapabilities:
551
+ return NodeCapabilities(
552
+ entries=[
553
+ _create_internal_capability_entry(entry, extensions) for entry in src or ()
554
+ ]
555
+ )
556
+
557
+
558
+ def _create_internal_capability_entry(
559
+ entry: NodeCapabilityEntry, extensions: Mapping[CapabilityId, CapabilityExtension]
560
+ ) -> NodeCapability:
561
+ match str(entry.id):
562
+ case model.OfficialCapabilityId.ruml_query:
563
+ return _capability_query(_payload(model.CapabilityQuery, entry))
564
+ case model.OfficialCapabilityId.ruml_actions:
565
+ return _actions(_parsed_payload(_ACTIONS_ADAPTER.validate_python, entry))
566
+ case model.OfficialCapabilityId.ruml_context:
567
+ return _context_refs(_payload(model.ContextRefs, entry))
568
+ case model.OfficialCapabilityId.ruml_ai_query:
569
+ return _capability_ai_query(_payload(model.CapabilityAiQueryNode, entry))
570
+ case model.OfficialCapabilityId.ruml_text_reference:
571
+ return _text_refs(_payload(model.TextRefs, entry))
572
+ case model.OfficialCapabilityId.ruml_expression:
573
+ return _capability_expression(_payload(model.CapabilityExpression, entry))
574
+ case capability_id if capability_id in extensions:
575
+ return _parsed_payload(extensions[capability_id].node, entry)
576
+ case capability_id:
577
+ return OtherNodeCapability(id=capability_id, payload=entry.payload)
578
+
579
+
580
+ def _capability_query(src: model.CapabilityQuery) -> QueryNodeCapability:
581
+ return QueryNodeCapability(expression=src.expression, description=src.description)
582
+
583
+
584
+ def _capability_expression(src: model.CapabilityExpression) -> ExpressionNodeCapability:
585
+ return ExpressionNodeCapability(
586
+ expression=src.expression, description=src.description
587
+ )
588
+
589
+
590
+ def _actions(
591
+ src: model.Actions1 | model.Actions2 | model.Actions3,
592
+ ) -> ActionsNodeCapability:
593
+ return ActionsNodeCapability(
594
+ description=src.description,
595
+ on_true=_map_if_not_none(_action, src.onTrue),
596
+ on_false=_map_if_not_none(_action, src.onFalse),
597
+ on_undefined=_map_if_not_none(_action, src.onUndefined),
598
+ )
599
+
600
+
601
+ def _action(src: model.Action) -> Action:
602
+ return Action(operation=src.operation, ref=src.ref, config=src.config)
603
+
604
+
605
+ def _context_refs(src: model.ContextRefs) -> ContextRefsNodeCapability:
606
+ return ContextRefsNodeCapability(refs=list(src.refs))
607
+
608
+
609
+ def _text_refs(src: model.TextRefs) -> TextRefsNodeCapability:
610
+ return TextRefsNodeCapability(refs=[_text_anchor(ref) for ref in src.refs])
611
+
612
+
613
+ def _text_anchor(src: model.TextAnchor) -> TextAnchor:
614
+ return TextAnchor(id=src.id, type=src.type, element=src.element)
615
+
616
+
617
+ def _capability_ai_query(
618
+ src: model.CapabilityAiQueryNode,
619
+ ) -> AiQueryNodeCapability:
620
+ return AiQueryNodeCapability(
621
+ model=src.model,
622
+ prompt=src.prompt,
623
+ description=src.description,
624
+ inputs=_query_inputs(src.inputs),
625
+ config=_map_if_not_none(_ai_query_config, src.config),
626
+ )
627
+
628
+
629
+ def _query_inputs(src: model.Inputs | None) -> QueryInputs:
630
+ if src is None:
631
+ return QueryInputs()
632
+ return QueryInputs(
633
+ context=[_context_input(context) for context in src.context or ()],
634
+ datapoints=list(src.dataPoints or ()),
635
+ texts=list(src.texts or ()),
636
+ )
637
+
638
+
639
+ def _context_input(src: str | model.Context1) -> ContextInput:
640
+ if isinstance(src, str):
641
+ return ContextInput(id=src)
642
+ return ContextInput(
643
+ id=src.id, role=_default_if_none(src.role, model.Role.reference)
644
+ )
645
+
646
+
647
+ def _ai_query_config(src: model.Config) -> AiQueryNodeConfig:
648
+ return AiQueryNodeConfig(
649
+ deterministic=src.deterministic,
650
+ effort=_default_if_none(src.effort, model.Effort.medium),
651
+ temperature=src.temperature,
652
+ )
653
+
654
+
655
+ # --- Rulemap ----------------------------------------------------------------------------
656
+
657
+
658
+ def _node(
659
+ src: model.Node, extensions: Mapping[CapabilityId, CapabilityExtension]
660
+ ) -> Node:
661
+ if src.children:
662
+ assert src.operator, ( # nosemgrep: gitlab.bandit.B101
663
+ "Branch node must have operator"
664
+ )
665
+ return BranchNode(
666
+ id=src.id,
667
+ operator=src.operator,
668
+ label=src.label,
669
+ alt_text=src.altText,
670
+ description=src.description,
671
+ children=list(src.children or ()),
672
+ capabilities=_node_capabilities(src.capabilities, extensions),
673
+ metadata=src.metadata or {},
674
+ decision_mode=src.decisionMode,
675
+ modular=src.modular,
676
+ )
677
+ return LeafNode(
678
+ id=src.id,
679
+ label=src.label,
680
+ alt_text=src.altText,
681
+ description=src.description,
682
+ capabilities=_node_capabilities(src.capabilities, extensions),
683
+ metadata=src.metadata or {},
684
+ decision_mode=src.decisionMode,
685
+ modular=src.modular,
686
+ )
687
+
688
+
689
+ # --- Helpers ----------------------------------------------------------------------------
690
+
691
+
692
+ def _map_if_not_none[S, T](mapper: Callable[[S], T], src: S | None) -> T | None:
693
+ """Map `src` using `mapper` if the former is not `None`, else return `None`."""
694
+ return None if src is None else mapper(src)
695
+
696
+
697
+ def _default_if_none[T](value: T | None, default: T) -> T:
698
+ """Return `value` if it's not `None`, otherwise return `default`.
699
+
700
+ This is useful to apply schema defaults the generated model only records as `None`.
701
+ """
702
+ return default if value is None else value
703
+
704
+
705
+ def _payload[M: BaseModel](kind: type[M], entry: _CapabilityEntry) -> M:
706
+ """Validate an entry's payload against the model its id prescribes.
707
+
708
+ The schema picks a payload's schema by the entry's id (`if`/`then` rules), which
709
+ the codegen cannot follow: the generated entry models type `payload` as a free-form
710
+ object. Validating it here yields the model the id prescribes, or rejects the
711
+ payload as the schema would have. An absent payload counts as an empty one, so a
712
+ bare declaration like `{"id": "ruml:query"}` maps to the model's defaults.
713
+ """
714
+ return _parsed_payload(TypeAdapter[M](kind).validate_python, entry)
715
+
716
+
717
+ def _parsed_payload[T](
718
+ parse: Callable[[CapabilityPayload], T], entry: _CapabilityEntry
719
+ ) -> T:
720
+ """Parse an entry's payload with ``parse``, like ``_payload`` does with a model.
721
+
722
+ This serves payloads not parsed into a single model: a union, or a payload an
723
+ extension parses.
724
+ """
725
+ try:
726
+ return parse(entry.payload or {})
727
+ except ValidationError as error:
728
+ raise ValueError(
729
+ f"capability '{entry.id}' does not have the shape its id prescribes: "
730
+ f"{error}"
731
+ ) from error