suggest_semantics

suggest_semantics(
    df,
    dict_df,
    sources=None,
    include_dwc=False,
    max_per_role=3,
    search_fn=find_terms,
    codes=None,
    table_meta=None,
    dataset_meta=None,
    llm_assess=False,
    llm_provider='openai',
    llm_model=None,
    llm_api_key=None,
    llm_base_url=None,
    llm_reasoning_effort=None,
    llm_top_n=5,
    llm_context_files=None,
    llm_context_text=None,
    llm_timeout_seconds=60,
    llm_request_fn=None,
)

Suggest semantic annotations for SDP metadata targets.

Candidate retrieval covers dictionary columns, controlled codes, table observation units, and dataset keywords. Measurement columns are expanded into variable, property, entity, unit, constraint, and statistical_modifier roles; the code-level method role survives for codes.csv term_iri targets.

Parameters

Name Type Description Default
df A DataFrame, a named mapping of DataFrames, or None when only supplied metadata targets are being reviewed. required
dict_df pd.DataFrame SDP column dictionary. required
sources Optional[Sequence[str]] Retrieval sources. None uses role-aware defaults; any explicit value is a strict allowlist for initial and retry retrieval. None
llm_assess bool Enable opt-in LLM assessment. Context alone never enables a provider request. False
llm_context_files Local context file paths. Parsed DataFrames or document objects are rejected. None

Returns

Name Type Description
pandas.DataFrame A normalized dictionary carrying semantic_suggestions in DataFrame.attrs and, when requested, the stable 30-column semantic_llm_assessments table. The dictionary also carries a semantic_targets attribute with the discovered search targets (one row per unfilled semantic field); :func:~metasalmonpy.term_requests.detect_semantic_term_gaps reads it to report targets whose retrieval returned zero candidates, which by construction have no suggestion rows at all.
Back to top