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.
- ruml_parser/__init__.py +183 -0
- ruml_parser/internal/__init__.py +2 -0
- ruml_parser/internal/extension.py +91 -0
- ruml_parser/internal/mapping.py +731 -0
- ruml_parser/internal/ruml/__init__.py +237 -0
- ruml_parser/internal/ruml/actions/__init__.py +2 -0
- ruml_parser/internal/ruml/actions/actions_capability_declaration.py +23 -0
- ruml_parser/internal/ruml/actions/actions_node_capability.py +40 -0
- ruml_parser/internal/ruml/ai_query/__init__.py +2 -0
- ruml_parser/internal/ruml/ai_query/ai_query_capability_declaration.py +25 -0
- ruml_parser/internal/ruml/ai_query/ai_query_node_capability.py +66 -0
- ruml_parser/internal/ruml/aliases.py +93 -0
- ruml_parser/internal/ruml/capability/__init__.py +2 -0
- ruml_parser/internal/ruml/capability/abstract_capability_declaration.py +23 -0
- ruml_parser/internal/ruml/capability/abstract_node_capability.py +14 -0
- ruml_parser/internal/ruml/capability/capability_declaration.py +52 -0
- ruml_parser/internal/ruml/capability/capability_declarations.py +199 -0
- ruml_parser/internal/ruml/capability/extension_node_capability.py +17 -0
- ruml_parser/internal/ruml/capability/node_capabilities.py +113 -0
- ruml_parser/internal/ruml/capability/other_node_capability.py +21 -0
- ruml_parser/internal/ruml/context/__init__.py +2 -0
- ruml_parser/internal/ruml/context/context.py +40 -0
- ruml_parser/internal/ruml/context/context_capability_declaration.py +25 -0
- ruml_parser/internal/ruml/context/context_refs_node_capability.py +17 -0
- ruml_parser/internal/ruml/datapoints/__init__.py +2 -0
- ruml_parser/internal/ruml/datapoints/datapoint.py +101 -0
- ruml_parser/internal/ruml/datapoints/datapoint_set.py +20 -0
- ruml_parser/internal/ruml/datapoints/datapoints_capability_declaration.py +29 -0
- ruml_parser/internal/ruml/datapoints/option.py +11 -0
- ruml_parser/internal/ruml/expression/__init__.py +2 -0
- ruml_parser/internal/ruml/expression/expression_capability_declaration.py +23 -0
- ruml_parser/internal/ruml/expression/expression_node_capability.py +20 -0
- ruml_parser/internal/ruml/metadata.py +83 -0
- ruml_parser/internal/ruml/nodes/__init__.py +2 -0
- ruml_parser/internal/ruml/nodes/abstract_node.py +29 -0
- ruml_parser/internal/ruml/nodes/branch_node.py +15 -0
- ruml_parser/internal/ruml/nodes/leaf_node.py +10 -0
- ruml_parser/internal/ruml/nodes/node.py +6 -0
- ruml_parser/internal/ruml/protocol/__init__.py +2 -0
- ruml_parser/internal/ruml/protocol/protocol_capability_declaration.py +29 -0
- ruml_parser/internal/ruml/query/__init__.py +2 -0
- ruml_parser/internal/ruml/query/query_capability_declaration.py +23 -0
- ruml_parser/internal/ruml/query/query_node_capability.py +17 -0
- ruml_parser/internal/ruml/ruml_document.py +45 -0
- ruml_parser/internal/ruml/text_reference/__init__.py +2 -0
- ruml_parser/internal/ruml/text_reference/text.py +69 -0
- ruml_parser/internal/ruml/text_reference/text_reference_capability_declaration.py +25 -0
- ruml_parser/internal/ruml/text_reference/text_refs_node_capability.py +32 -0
- ruml_parser/internal/ruml/tree/__init__.py +2 -0
- ruml_parser/internal/ruml/tree/tree_capability_declarations.py +30 -0
- ruml_parser/internal/validation/__init__.py +14 -0
- ruml_parser/internal/validation/capabilities.py +227 -0
- ruml_parser/internal/validation/contexts.py +51 -0
- ruml_parser/internal/validation/datapoint_sets.py +125 -0
- ruml_parser/internal/validation/modular.py +42 -0
- ruml_parser/internal/validation/recursion.py +197 -0
- ruml_parser/internal/validation/root.py +36 -0
- ruml_parser/internal/validation/texts.py +50 -0
- ruml_parser/model/__init__.py +2 -0
- ruml_parser/model/ruml.py +1156 -0
- ruml_parser/model/ruml_result.py +430 -0
- ruml_parser/node_result_status.py +19 -0
- ruml_parser/pydantic.py +96 -0
- ruml_parser/ruml_parser.py +75 -0
- ruml_parser/schema_files.py +23 -0
- ruml_parser/schema_validation.py +354 -0
- ruml_parser/structural_error.py +36 -0
- ruml_parser/text.py +220 -0
- ruml_parser-1.0.0.dist-info/METADATA +119 -0
- ruml_parser-1.0.0.dist-info/RECORD +72 -0
- ruml_parser-1.0.0.dist-info/WHEEL +4 -0
- 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
|