detect_semantic_term_gaps

detect_semantic_term_gaps(
    dict_df=None,
    suggestions=None,
    include_target_scopes=('column', 'code', 'table', 'dataset'),
    include_dictionary_roles=None,
    min_score=None,
)

Detect structured ontology gaps from candidate and final LLM evidence.

When suggestions is omitted, the semantic_suggestions, semantic_llm_assessments, and semantic_targets attributes are read from dict_df; the last is how zero-candidate targets are detected. A target with no retrieval evidence at all — no suggestion row before min_score filtering, no assessment of any decision — is reported with gap_detection_basis = "no_candidates", distinguishing “nothing found” from “found and rejected” (llm_request_new_term). Explicit suggestions use only LLM fields embedded in that table and keep the historical row-in/row-out behaviour. Identical duplicate assessments are collapsed; conflicting proposed term fields raise an error.

Parameters

Name Type Description Default
dict_df Optional[pd.DataFrame] Dictionary carrying semantic result attributes. None
suggestions Optional[pd.DataFrame] Explicit semantic suggestion table. None
include_target_scopes Sequence[str] Target scopes to retain. ('column', 'code', 'table', 'dataset')
include_dictionary_roles Optional[Sequence[str]] Optional semantic-role filter. None
min_score Optional[float] Candidate score threshold. Final LLM request_new_term evidence is not removed by this threshold. None

Returns

Name Type Description
pandas.DataFrame Stable structured gap rows with candidate evidence, detection basis, LLM rationale, proposed-term metadata, and escalation provenance.
Back to top