Skip to content
RUMLRUML

Open Format for Digital Law

4.9 ruml:ai-query

4.9 Capability ruml:ai-query

Overview

PropertyValue
Capability IDruml:ai-query
ScopeNode-Level (capabilities field on the node)
Default requiredfalse
Roledecision

The ruml:ai-query Capability extends Leaf-Nodes with LLM-based evaluation. The tree structure of the Rulemap narrows the question to the point where the LLM answers a clearly defined check — the result MUST be true, false, or undefined. The evaluation is not deterministic to the same degree as a ruml:query expression, but through the narrowly scoped question and configurable parameters (e.g., temperature), a high degree of reproducibility can be achieved.

When a node contains both ruml:query and ruml:ai-query, the decisionMode field on the node determines how the results are combined (see Chapter 4.3). In the default mode fallback, ruml:ai-query is only executed when ruml:query returns undefined.

Data Structure on the Node

The payload of the ruml:ai-query entry in a node’s capabilities array has the following structure:

"payload": {
"model": "strong",
"prompt": "Prüfe anhand der bereitgestellten Unterlagen, ob eine Härtefallbegründung plausibel ist. Antworte ausschließlich mit true, false oder undefined.",
"description": "Prüft die Plausibilität der Härtefallbegründung",
"inputs": {
"context": [
{
"id": "ctx_guidelines",
"role": "reference"
},
{
"id": "ctx_gutachten",
"role": "subject"
}
],
"dataPoints": ["dp_hardship_reason", "dp_annual_income"],
"texts": ["text_bgb_823"]
},
"config": {
"deterministic": true,
"effort": "high",
"temperature": 0.1
}
}

Fields

FieldTypeDescription
modelStringMUST contain a symbolic reference to the AI model to use (Rule CAP-30CAP-30 A node's ruml:ai-query payload MUST have model; a parser MUST accept prompt, description, inputs and config in it.)
promptStringMAY specify the prompt text inline in the RUML file. If present, this prompt is used — otherwise the tool-configured prompt template of the model is used (Rule CAP-30CAP-30 A node's ruml:ai-query payload MUST have model; a parser MUST accept prompt, description, inputs and config in it.).
descriptionStringMAY describe the purpose of the AI query (Rule CAP-30CAP-30 A node's ruml:ai-query payload MUST have model; a parser MUST accept prompt, description, inputs and config in it.)
inputsObjectMAY define the input data for the LLM (Rule CAP-30CAP-30 A node's ruml:ai-query payload MUST have model; a parser MUST accept prompt, description, inputs and config in it.)
configObjectMAY contain configuration hints for execution (Rule CAP-30CAP-30 A node's ruml:ai-query payload MUST have model; a parser MUST accept prompt, description, inputs and config in it.)

inputs Object

FieldTypeDescription
contextArray[String | Object]MAY specify IDs from the ruml:context Capability. Every id MUST be a key of the data of ruml:context (Rule CTX-10CTX-10 Every id in the refs of a node's ruml:context entry, and every context id in inputs.context of a ruml:ai-query, MUST be a key of the data of ruml:context.). As String: shorthand form (implicitly role: "reference"). As Object: id (MUST) and role (MAY, "reference" or "subject", default: "reference") (Rule CAP-31CAP-31 A parser MUST accept context, dataPoints and texts in the inputs of a ruml:ai-query payload; an object entry of context MUST have id, and a parser MUST accept role (reference or subject) in it.). "subject" marks the document as the subject of examination for this query. Note: Context objects referenced with role: "subject" SHOULD have subject: true set in the context object itself (see Chapter 4.11).
dataPointsArray[String]MAY specify DataPoint IDs whose values are passed to the LLM (Rule CAP-31CAP-31 A parser MUST accept context, dataPoints and texts in the inputs of a ruml:ai-query payload; an object entry of context MUST have id, and a parser MUST accept role (reference or subject) in it.). Every id MUST be a key of the data of ruml:datapoints (Rule DP-18DP-18 Every DataPoint id that the expression of a ruml:query or of a ruml:expression reads, and every id in inputs.dataPoints of a ruml:ai-query, MUST be a key of the data of ruml:datapoints.)
textsArray[String]MAY specify IDs from the ruml:text-reference Capability (see Chapter 4.12) (Rule CAP-31CAP-31 A parser MUST accept context, dataPoints and texts in the inputs of a ruml:ai-query payload; an object entry of context MUST have id, and a parser MUST accept role (reference or subject) in it.). Every id MUST be a key of the data of ruml:text-reference (Rule TXT-19TXT-19 Every id of an anchor in the refs of a node's ruml:text-reference entry, and every id in inputs.texts of a ruml:ai-query, MUST be a key of the data of ruml:text-reference.)

config Object

FieldTypeDescription
deterministicBooleanMAY indicate whether the same model and inputs should yield a consistent result (Rule CAP-32CAP-32 A parser MUST accept deterministic (a Boolean), effort (low, medium or high) and temperature (a number from 0 to 1) in the config of a node's ruml:ai-query payload, and systemPrompt in the config of its root payload.)
effortStringMAY indicate how much effort the model should spend on the query ("low", "medium", "high"), e.g. as reasoning effort. Default: "medium" (Rule CAP-32CAP-32 A parser MUST accept deterministic (a Boolean), effort (low, medium or high) and temperature (a number from 0 to 1) in the config of a node's ruml:ai-query payload, and systemPrompt in the config of its root payload.).
temperatureNumberMAY specify the sampling temperature for the LLM (0.0-1.0) (Rule CAP-32CAP-32 A parser MUST accept deterministic (a Boolean), effort (low, medium or high) and temperature (a number from 0 to 1) in the config of a node's ruml:ai-query payload, and systemPrompt in the config of its root payload.).

AI Model

The model field references the AI model (LLM) or class of models to use for the evaluation. The allowed values and their meanings are tool-dependent and not part of this standard. The concrete model associated with a value, the API endpoint, and the prompt template are stored in the tool settings, NOT in the RUML file — unless the prompt field provides the prompt text directly inline. In that case, the inline prompt takes precedence over the tool-configured template.

Evaluation Rules

  • A node MAY define both ruml:query and ruml:ai-query (Rule CAP-33CAP-33 A parser MUST accept a leaf node that has both ruml:query and ruml:ai-query.)
  • When multiple decision Capabilities are present on the node, decisionMode determines the combination logic (see Chapter 4.3)
  • The LLM MUST return a result of true, false, or undefined
  • For undefined (undecidable), ruml:actions with onUndefined SHOULD be combined

Example — Complete Node

"3": {
"id": "6840b48d-117f-474e-ae4e-337b8e60537c",
"label": "Begründung plausibel",
"capabilities": [
{
"id": "ruml:ai-query",
"payload": {
"model": "strong",
"prompt": "Prüfe anhand der bereitgestellten Unterlagen, ob eine Härtefallbegründung plausibel ist. Antworte ausschließlich mit true, false oder undefined.",
"description": "Prüft die Plausibilität der Härtefallbegründung anhand der Richtlinien und Beispielfälle",
"inputs": {
"context": [
"ctx_guidelines",
"ctx_bsg_ruling",
"ctx_example_approved_medical",
"ctx_example_rejected_luxury"
],
"dataPoints": ["dp_hardship_reason", "dp_annual_income"]
},
"config": {
"deterministic": true,
"effort": "high",
"temperature": 0.1
}
}
},
{
"id": "ruml:actions",
"payload": {
"onUndefined": {
"operation": "requestDecision",
"ref": "manual_review_workflow",
"config": {
"recipient": "role:social-worker",
"deadline": "P5D",
"responseOptions": ["approve", "reject", "requestMoreInfo"]
}
}
}
}
]
}

Root-Level Declaration

To use ruml:ai-query in a RUML file, the Capability MUST be declared in the root capabilities array (Rule CAP-15CAP-15 The id of every entry of a node's capabilities MUST be declared in the root capabilities.). The optional config field MAY contain a global systemPrompt that is used for all AI query executions in this file:

"capabilities": [
{
"id": "ruml:ai-query",
"payload": {
"config": {
"systemPrompt": "Du bist ein rechtlicher Assistent. Analysiere die bereitgestellten Sachverhalte anhand der geltenden deutschen Rechtslage und antworte ausschließlich mit true, false oder undefined."
}
}
}
]
FieldTypeDescription
systemPromptStringMAY define a global system prompt that applies to all ruml:ai-query executions in this file. When a node additionally has a prompt field, the systemPrompt is passed as the system role and the node-specific prompt as the user role (Rule CAP-32CAP-32 A parser MUST accept deterministic (a Boolean), effort (low, medium or high) and temperature (a number from 0 to 1) in the config of a node's ruml:ai-query payload, and systemPrompt in the config of its root payload.).