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,
    commons_gaps=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
commons_gaps Optional path to a scripts/okf-check.py --gaps JSON export from salmon-knowledge-commons. This concept evidence is exclusive with the SDP dictionary and suggestion inputs and does not use their filters. None

Returns

Name Type Description
pandas.DataFrame Stable structured gap rows with candidate evidence, detection basis, LLM rationale, proposed-term metadata, and escalation provenance. Commons input keeps those columns and appends source provenance and lifecycle fields; held rows remain visible but cannot be requested.
Back to top