> For the complete documentation index, see [llms.txt](https://docs.layerlens.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.layerlens.ai/13.6-system-judges-implementation/faithfulness-implementation.md).

# Faithfulness implementation

The **Faithfulness** system judge scores whether every factual claim in a model's `OUTPUT` is supported by the supplied `CONTEXT`. It is the workhorse judge for any RAG-pattern application. This page is the full rubric behind the [System judges](/8.-evaluate-score-the-outputs/system-judges.md) catalog entry.

## Contract

|                   |                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| **Inputs**        | `{{output}}` (the model's answer), `{{context}}` (retrieved documents / source-of-truth)               |
| **Output**        | `score` ∈ `0.0–1.0` + `unsupported_claims`: a list of claims in the output not entailed by the context |
| **Default model** | Frontier Claude Opus-class (`model_id` on the judge record)                                            |
| **`is_system`**   | `true`                                                                                                 |

## Rubric

The judge decomposes the output into atomic factual claims and checks each for entailment against the context, then aggregates:

| Band               | Score      | Meaning                                                               |
| ------------------ | ---------- | --------------------------------------------------------------------- |
| Fully grounded     | `1.0`      | Every claim is directly supported by the context                      |
| Mostly grounded    | `0.7–0.99` | All material claims supported; only trivial/inferable detail unstated |
| Partially grounded | `0.4–0.69` | A material claim is unsupported but not contradicted                  |
| Weakly grounded    | `0.1–0.39` | Multiple material claims unsupported, or one contradicts the context  |
| Ungrounded         | `0.0`      | Core claim is fabricated or directly contradicts the context          |

Each unsupported claim is returned in `unsupported_claims` with the offending text, so a low score is actionable rather than opaque.

## Tuning notes

* **Penalize confident hallucinations hardest.** A fluent, authoritative claim with no support in context is the most dangerous failure and should land at the bottom of the scale.
* **Do not penalize appropriate refusal.** If the context is genuinely insufficient and the model *declines to answer* (or says it cannot find the information), that is faithful behavior — it should not score low. Faithfulness measures grounding of claims made, not willingness to answer. (Whether the refusal itself was appropriate is the [Refusal Quality](/8.-evaluate-score-the-outputs/system-judges.md) judge's job.)
* **Extraction vs. inference.** Reasonable inference that a domain reader would accept as entailed by the context is grounded; a leap that introduces new facts is not.
* **Pair with a deterministic check where possible.** Faithfulness is subjective grounding; for citation-backed outputs, pair it with the Citation Accuracy judge and the deterministic Citation Existence code grader.

## Running it

```python
from layerlens import Stratix
client = Stratix()

faithfulness = next(
    j for j in client.judges.get_many(type="system") if j.name == "Faithfulness"
)
result = client.trace_evaluations.create(trace_id=trace_id, judge_id=faithfulness.id)
print(result.score, result.details)  # score + unsupported_claims
```

From the dashboard: open a trace → trace-evaluation panel → add the **Faithfulness** system judge.

## Improving agreement

If out-of-the-box agreement with your reviewers isn't high enough, **clone** the judge and run [GEPA optimization](/9.-improve-tune-the-system/judge-optimization.md) against ≥ 30 labeled examples spanning the score bands, then validate on a held-out slice before deploying the optimized variant.

## Reference

* [System judge implementation reference](/13.6-system-judges-implementation/system.md)
* [System judges — catalog](/8.-evaluate-score-the-outputs/system-judges.md)
* [Judges — SDK reference](https://github.com/LayerLens/gitbook-full/blob/main/13-reference/sdk-python/judges.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.layerlens.ai/13.6-system-judges-implementation/faithfulness-implementation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.