write_semantic_review_packet

write_semantic_review_packet(
    x,
    context_files=None,
    context_text=None,
    top_n=5,
    sources=None,
    search_fn=find_terms,
    code_scope='factor',
    review_dir=None,
    overwrite=False,
    quiet=False,
)

Write a semantic review packet for a harness to judge.

Model judgement runs outside metasalmonpy (ruled 2026-09-25, hub Q67). This writes the deterministic file a harness reads: every semantic slot that still needs a decision, each slot’s ranked candidate shortlist with the evidence the package’s own validators read (label, IRI, source, ontology, native type, role hints, term type, resource kind, type IRIs, definition and scores), the measurement bundles with their current slots, the scored excerpts from your context documents, the review instructions, the decision vocabulary and the 30-column assessment schema. The harness answers in a CSV next to the packet, and :func:~metasalmonpy.ingest_semantic_assessments reads it back.

This never calls a model. For a package path it retrieves each slot’s shortlist again through search_fn, which is the only way it reaches the network; for in-memory input it makes no network call at all.

For a package path the packet holds exactly the queue :func:~metasalmonpy.review_semantics would show – slots in column_dictionary.csv, codes.csv or tables.csv whose IRI field is blank or REVIEW:-marked and that carry no recorded decision – plus the blank slots discovery recovers because retrieval found nothing for them at creation. For an in-memory dictionary it holds every target in the semantic_targets attribute, including targets with no candidates, with the first top_n candidates of each from semantic_suggestions.

The packet holds excerpts from your own context documents. It is written under review/, which no publication path reads, and it is never published. Recovering blank slots for a package path reads its data resources only when tables.csv names a plain relative path inside the package; any other row is skipped with a warning.

Parameters

Name Type Description Default
x A package directory written by :func:~metasalmonpy.create_sdp, or a dictionary carrying the semantic_targets and semantic_suggestions attributes :func:~metasalmonpy.suggest_semantics attaches (an artifact mapping is read through its dict). required
context_files Local file paths whose text is chunked and scored against each unit, under the same path-only contract as llm_context_files: a parsed object is refused. None
context_text Inline context text: a string or a sequence of strings. None
top_n int The shortlist shown per slot and, for a package path, the retrieval depth. Default 5. 5
sources Optional[Sequence[str]] Vocabulary sources. None searches each role’s defaults (:func:~metasalmonpy.sources_for_role); a list is a strict allowlist. None
search_fn Callable The search function, used only for a package path. Defaults to :func:~metasalmonpy.find_terms. find_terms
code_scope str Which codes.csv values get a slot when a blank slot is recovered by discovery for a package path: "factor" (the default, as create_sdp() seeds), "all" or "none". Nothing in a package records the scope it was created with, so the packet records the one used here, and a blank code-level slot outside it is reported in not_covered rather than silently dropped. 'factor'
review_dir Optional[Union[str, os.PathLike]] Where to write the packet. Defaults to review/ under the package directory; required for in-memory input. None
overwrite bool A review session that already holds answers or a record refuses to be overwritten unless this is True, in which case the session’s files are deleted first. False
quiet bool Suppress the summary. False

Returns

Name Type Description
dict path (the packet file), packet_id (the SHA-256 the ingester checks), pass (always 1 here), units and targets (counts), and not_covered: the blank code-level slots the chosen code_scope left out, one row each (empty for in-memory input).
Back to top