4.9 ruml:ai-query
4.9 Capability ruml:ai-query
Overview
| Property | Value |
|---|---|
| Capability ID | ruml:ai-query |
| Scope | Node-Level (capabilities field on the node) |
Default required | false |
| Role | decision |
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
| Field | Type | Description |
|---|---|---|
model | String | MUST 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.) |
prompt | String | MAY 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.). |
description | String | MAY 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.) |
inputs | Object | MAY 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.) |
config | Object | MAY 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
| Field | Type | Description |
|---|---|---|
context | Array[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). |
dataPoints | Array[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.) |
texts | Array[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
| Field | Type | Description |
|---|---|---|
deterministic | Boolean | MAY 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.) |
effort | String | MAY 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.). |
temperature | Number | MAY 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:queryandruml:ai-query(Rule CAP-33CAP-33 A parser MUST accept a leaf node that has bothruml:queryandruml:ai-query.) - When multiple
decisionCapabilities are present on the node,decisionModedetermines the combination logic (see Chapter 4.3) - The LLM MUST return a result of
true,false, orundefined - For
undefined(undecidable),ruml:actionswithonUndefinedSHOULD 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." } } }]| Field | Type | Description |
|---|---|---|
systemPrompt | String | MAY 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.). |