---
name: matched_context
lang: py
domain: core
version: "1.0.0"
algebraic: product
definition: |
  @dataclass
  class MatchedContext:
      uri: str
      context_type: ContextType
      level: int = 2
      abstract: str = ""
      overview: str | None = None
      category: str = ""
      score: float = 0.0
      match_reason: str = ""
      relations: list[RelatedContext] = field(default_factory=list)
description: "Contexto encontrado por el retriever con su score de relevancia, nivel de detalle, y contextos relacionados."
tags: [retrieval, context, rag, match, score, result]
uses_types: [context_type_py_core, related_context_py_core]
file_path: "python/types/core/matched_context.py"
---

## Notas

El campo `level` define cuanto contenido fue cargado: 0 solo tiene `abstract`, 1 tiene `abstract` + `overview`, 2 tiene el contenido completo. El retriever puede usar niveles bajos para hacer un primer filtrado barato y luego cargar el nivel 2 solo para los candidatos seleccionados.

`score` en rango 0.0-1.0 donde 1.0 es maxima relevancia. El umbral de inclusion depende de la estrategia del retriever (ver `ScoreDistribution` para calcular umbrales adaptativos).

`match_reason` es texto libre generado por el LLM o el retriever para explicar la decision. Util para debugging y para mostrar al usuario por que se incluyo este contexto.

`relations` permite construir grafos de conocimiento ligeros sin un graph DB completo — cada contexto conoce sus vecinos directos.
