Getting data out of Rainbird after a decision has been made has sometimes proven challenging. Getting visibility of all the data that was available, or generated, when making a decision was even trickier. There were methods to do it, but they were unwieldy or required using a query that would be counted for billing purposes. To help address this, Rainbird has introduced the ability to get all facts from a session, accessible via the Rainbird API.

A quick overview of facts in Rainbird

Facts are central to decisions being provided by Rainbird.

When a session is started and a query is made, this is simply the requestor asking the engine to return a fact, or facts, about a subject (e.g. what is the level of risk providing a loan to client XYZ).

The engine will explore the facts it already has available to it and potentially generate new facts, using the logic encoded within the knowledge map, in order for it to eventually generate a fact(s) that answers the initial query (e.g. client XYZ has a risk category of low).

We tend to refer to this as the query result, answer or a decision. But technically it is also just a fact, the difference being it’s the one someone asked about.

When producing that fact, there will be many underlying facts, some of which you might want to reuse when compiling documentation or updating systems following the query result.

This updated API endpoint will make it easier to do this, with less impact on your query quota.

What does this API give me?

This will return all of the facts that exist within a session, without bias on whether they contributed a query result or were not required for decision-making.

As well as the fact itself (which is comprised of the subject, the relationship, the object and the certainty of the fact), it will also provide:

  1. The scope:
    1. Facts are grouped by their scope, which in most cases will be global or local
      1. Global -  refers to facts that are available to any session as they are hard-coded into the knowledge map.
      2. Local - refers to facts that have been generated within that session and will therefore be more specific to the query/queries run within that session.
      3. Context - In some cases there may be facts held in ‘context’. These are facts that were generated in a different session, but have been shared to provide context, because the map was configured to allow it and the appropriate key was provided between those sessions.
  2. The source:
    1. Facts are derived in different ways. How the fact was created is indicated by the source, which could be:
      1. knowledgemap - a fact hard-coded directly into the knowledge map.
      2. injection - a fact ‘injected’ into the session prior to a query being run.
      3. datasource - a fact generated by the knowledge map retrieving data from an external API.
      4. rule - a fact inferred by a rule.
      5. answer - a fact generated from a user answering a question.
      6. synthesis - a fact automatically generated by the engine, for optional conditions, where no other route to the goal exists.
  3. The factID:
    1. The factID for each fact is provided. This can be used to retrieve further evidence about how the fact was created. This would require usage of the /evidence endpoint. This is mostly applicable to facts derived by a rule, because it will detail the conditions of the rule and the underlying facts it used to satisfy the rule.

What can’t I see from this data?

  1. What fact(s) were returned as a query result.
    1. Whilst the fact will be present, and can be found using the subject and relationship of the query, this isn’t explicitly identified in the data.
  2. How facts contributed, or didn’t contribute, to a query result.
    1. This endpoint returns all facts, some of which may not have been applicable to decision-making. The /evidence endpoint provides the necessary information about how the facts are chained together to provide a query result.
  3. The questions and answers an end-user responded with.
    1. The /interactions endpoint is available where access to the questions asked, the answers given and the query result is required.

If you have any questions about this API or want more information about how to get data out of Rainbird, please contact us here or at