Groundedness

The Groundedness metric measures whether a model’s generated response remains faithful to the input context and avoids hallucinations or speculative reasoning. It helps evaluate factual consistency and traceability, especially when LLMs generate answers based on external sources, retrieved passages, or structured data.

This metric is critical in RAG (retrieval-augmented generation), enterprise QA systems, and any use case where factuality is a core requirement.

When to Use

Apply the Groundedness metric when a model is expected to remain tightly aligned with an authoritative context, such as:

• Knowledge-grounded agents that cite documents or structured data
• Enterprise chat assistants referencing product, support, or policy content
• Tool-using agents interpreting intermediate function/state output
• Factual creative assistants (e.g., educational, journalistic, research support)

Score

The API returns a score (float, 0.0 – 1.0) under the groundedness key.

• 1.0: Fully faithful to the context; no unsupported or fabricated claims.
• 0.7–0.99: Mostly accurate with minor factual ambiguity.
• 0.2–0.7: Some inaccuracies or invented facts present.
• 0.0–0.2: Severe hallucinations or clear contradiction with context.

A higher score is better. A lower score indicates factual inconsistency, hallucinations, or unsupported reasoning.

API Request & Response Example

Request

[
  {
    "context": "The Eiffel Tower is located in Paris, France.",
    "generated_text": "The Eiffel Tower is located in England.",
    "config": {
      "groundedness": {
        "detector_name": "default",
        "explain":true
      }
    }
  }
]

Response

[
    {
        "groundedness": {
            "instructions_list": [
                {
                    "explanation": "The response states 'The Eiffel Tower is located in England,' which directly contradicts the factual context ('Paris, France').",
                    "follow_probability": 0.0022,
                    "instruction": "Ensure that the response does not contain minor or major factual inaccuracies or completely made-up sentences when compared to the context.",
                    "label": false
                },
                {
                    "explanation": "It introduces an unsupported fact ('England') instead of inferring implicit information correctly.",
                    "follow_probability": 0.0421,
                    "instruction": "Ensure that the response correctly infers implicit information without introducing unsupported facts.",
                    "label": false
                },
                {
                    "explanation": "The response arbitrarily chooses 'England' without clarifying why, despite the clear context pointing to Paris.",
                    "follow_probability": 0.4073,
                    "instruction": "Ensure that the response does not arbitrarily choose between contradictory pieces of information without clarification.",
                    "label": false
                },
                {
                    "explanation": "It misinterprets the implicit location by fabricating 'England' instead of accurately reflecting the context.",
                    "follow_probability": 0.0331,
                    "instruction": "Ensure that the response does not misinterpret or fabricate implicit information.",
                    "label": false
                },
                {
                    "explanation": "The response states 'The Eiffel Tower is located in England,' which is incorrect and shows hallucination, violating the instruction.",
                    "follow_probability": 0.0675,
                    "instruction": "Ensure that the response does not include hallucinated content due to ambiguity.",
                    "label": false
                }
            ],
            "score": 0
        }
    }
]

Code Examples

Python (Sync)

# Synchronous example

import os
from aimon import Client
import json

# Initialize client
client = Client(auth_header=f"Bearer {os.environ['AIMON_API_KEY']}")

# Construct payload
payload = [{
    "generated_text": "The Eiffel Tower is in Berlin.",
    "context": ["The Eiffel Tower is located in Paris, France."],
    "config": {
        "groundedness": {
            "detector_name": "default",
            "explain": True
        }
    },
    "publish": False
}]

# Call sync detect
response = client.inference.detect(body=payload)

# Print result
print(json.dumps(response[0].groundedness, indent=2))

Python (Async)

# Aynchronous example

import os
import json
from aimon import AsyncClient

aimon_api_key = os.environ["AIMON_API_KEY"]

aimon_payload = {
    "generated_text": "The Earth is flat.",
    "context": ["Scientific consensus holds that the Earth is a sphere."],
    "config": {
        "groundedness": {
            "detector_name": "default",
            "explain": True
        }
    },
    "publish": True,
    "async_mode": True,
    "application_name": "async_metric_example",
    "model_name": "async_metric_example"
}

data_to_send = [aimon_payload]

async def call_aimon():
    async with AsyncClient(auth_header=f"Bearer {aimon_api_key}") as aimon:
        return await aimon.inference.detect(body=data_to_send)

resp = await call_aimon()
print(json.dumps(resp, indent=2))
print("View results at: https://www.app.aimon.ai/llmapps?source=sidebar&stage=production")

Python (Decorator)

import os
from aimon import Detect

detect = Detect(
    values_returned=["context", "generated_text"],
    config={"groundedness": {"detector_name": "default", "explain": True}},
    api_key=os.getenv("AIMON_API_KEY"),
    application_name="application_name",
    model_name="model_name"
)

@detect
def groundedness_test(context, generated_text):
    return context, generated_text

context, generated_text, aimon_result = groundedness_test(
    "The Eiffel Tower is located in Paris, France.",
    "The Eiffel Tower is located in England."
)
print(aimon_result)

TypeScript

import Client from "aimon";
import dotenv from "dotenv";

dotenv.config();

const aimon = new Client({
  authHeader: `Bearer ${process.env.AIMON_API_KEY}`,
});

const run = async () => {
  const response = await aimon.detect({
    context: "The Eiffel Tower is located in Paris.",
    generatedText: "The Eiffel Tower is located in London.",
    config: {
      groundedness: {
        detector_name: "default",
        explain: true,
      },
    },
  });

  console.log("AIMon response:", JSON.stringify(response, null, 2));
};

run();