/explain

/explain translates causal reasoning chains (the evidence tree) into clear, natural language descriptions.

By providing a fact ID from your results, receive a detailed explanation of how the reasoning engine reaches its decision and display these to end-users, embed into reports or store for audit.

All features delivered by Rainbird Labs are beta. They may contain bugs, are subject to change and are not covered by our platform SLAs. Your feedback can help shape development.

Getting Started

/explain is in open beta and details can be accessed from our API documentation. From here you download the OpenAPI specification to import into Postman, for example.

1. From a result from the Core endpoints (/query or /response) or NL endpoints (/interact) you can obtain a FactID

"results": [
        {
            "subject": "Jeff",
            "object": "Repair",
            "certainty": 100,
            "factID": "WA:KF:3d48671baa046851f47d46e9776012692e7a99045c7573a238fafac8db6bea3c",
            "relationship": "can claim"
        }
    ]

1. Make a request to /explain with the session ID, fact ID and ISO 639 language code (Authentication uses your Rainbird account API key passed in the header as X-API-Key)

{
"language": "en",
"sessionID": "{SESSION_ID}",
"factID": "WA:KF:3d48671baa046851f47d46e9776012692e7a99045c7573a238fafac8db6bea3c"
}

1. Receive a natural language explanation of the evidence tree

{
    "explanation": "Jeff, the policyholder, is eligible to make a claim for repairs. This decision is based on several key pieces of evidence. Firstly, Jeff holds a Gold policy, which is crucial because this policy provides coverage for repairs. The Gold policy is specifically designed to insure mobile phones, which is the type of equipment involved in this situation.\n\nThe incident in question is water damage, which Jeff has unfortunately experienced. The Gold policy not only covers this type of loss but also considers repair claims as appropriate for such damage. Therefore, since Jeff's mobile phone suffered water damage, and his Gold policy covers this type of incident, he is entitled to claim for the necessary repairs.",
    "metadata": {
        "querySubmittedAt": "2025-01-23T13:22:00.656922848Z",
        "languageEngineResponseTime": 2480,
        "llmTokens": {
            "completionTokens": 134,
            "promptTokens": 686,
            "totalTokens": 820
        },
        "apiVersion": "",
        "endpoint": "explain",
        "sessionID": "{SESSION_ID}"
    }
}

A resultResponse can contain multiple results, each with its own fact ID. If this is the case, you must call the explain endpoint for each result as there will be different reasons for each result.

Best Practice

To optimise the accuracy of /explain, it is advised you review the understandability of the evidence tree, looking specifically at the language used.

Improvements could be made by adjusting relationship names to improve readability, or by using evidence text in the graph to provide more context.

Important Information

Data Security

/explain operates using third-party AI services (OpenAI). Please ensure shared information is suitable for external processing.

Any request made to /explain shares the complete chain of reasoning with the LLM to produce the explanation.

Accuracy

Whilst we continue to improve the precision of /explain, some responses may be inaccurate.