Semantic operators

SemRelate

Recover labeled relationships among values in one Space.

SemRelate is for relations that are neither equivalence groups nor a single order. Every emitted relationship uses one of the labels you declare. Facts use a canonical unordered endpoint pair. Symmetric labels work directly; an endpoint-sensitive vocabulary should declare separate labels such as left_supports_right and right_supports_left, where left and right refer to the returned canonical endpoints. Use SemHierarchy for a directed acyclic prerequisite or dependency structure, SemTaxonomy for containment, and SemSort for a total order.

from scratchpad.api import RelationLabel, SemRelate

SemRelate(
    name="map-claims",
    input_spaces=("claims",),
    output_space="claim-relations",
    primary_key="claim",
    labels=(
        RelationLabel("supports"),
        RelationLabel("contradicts"),
        RelationLabel("independent"),
    ),
    min_labels_per_pair=1,
    max_labels_per_pair=1,
    max_candidate_pairs=25_000,
    prompt=(
        "Label the relationship between claims using only the supplied labels. "
        "Do not treat shared subject matter as support."
    ),
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    batch_size=14,
)

Parameter	Default	Meaning
`input_spaces`	required	The Space or Spaces read by the task.
`output_space`	required	The Space that receives the task output.
`name`	generated	A stable task name used in reviews, sessions, and metrics.
`primary_key`	id	The semantically meaningful field that identifies a value for this task. Rows with the same primary key represent one task value and produce one task result. Use Union first when every source identity must remain attached.
`evidence`	none	Optional supporting fields shown to the semantic model. Do not repeat a primary-key field or include irrelevant metadata.
`prompt`	required	The criterion or transformation written in plain language.
`provider / model`	required	The model used for this task's data decisions.
`reasoning_effort`	low	OpenAI GPT-5-family reasoning effort. Use none for the lowest-latency, lowest-reasoning-cost path when the task contract is precise; increase it only after representative quality evidence justifies the added time and spend.
`include_reason`	true	Whether every model decision includes item-local visible evidence. The compiled prompt defaults to at most ten words; an explicit prompt request for longer visible reasoning is preserved. This is generation guidance; returned reasons are never truncated. Set false only for a validated task where result and confidence suffice.
`confidence_threshold`	operator default	Exact boundary between unresolved and accepted evidence. Relifold compiles this value and operator-specific confidence guidance into the effective judge prompt.
`function_parameters`	registered gate defaults	Typed values for a generated semantic pair predicate such as merge_only_if, ancestor_only_if, match_only_if, or relate_only_if. The predicate declares the schema and finite candidates; reviewed evidence can then support parameter advice. Closed library gates do not take these bindings.
`max_llm_calls`	unlimited	A hard task-level call ceiling. The task stops instead of silently exceeding it.
`max_cost_usd`	unlimited	A hard task-level model-cost ceiling. A session-level ceiling may be stricter.
`max_output_tokens`	2048	Maximum generated tokens per model request. Increase it when one legitimate batch cannot fit its structured result.

Parameter	Default	Meaning
`labels`	required	The complete allowed relationship vocabulary.
`min_labels_per_pair`	0	Minimum retained labels required for every admitted pair. Leave 0 for sparse relationship discovery. Use a positive value only with an exhaustive vocabulary that includes an explicit negative, independent, or insufficient-evidence label.
`max_labels_per_pair`	none	Maximum distinct labels retained on one unordered pair. Use 1 for mutually exclusive classification labels; leave unset when labels are independent attributes that may coexist.
`relate_only_if`	none	A deterministic two-row constraint returning one exact declared label, a complete possible-label iterable, or None. Exact facts freeze before closure; domains remove impossible judge labels.
`max_candidate_pairs`	none	Optional positive ceiling on the exact unresolved eligible unordered-pair hand. An oversized hand fails before the first judge call.
`closure_rules`	label defaults	Optional valid implications among labels.
`batch_size`	operator default	Values considered together.
`max_rounds`	operator default	Maximum iterative relation rounds.

Use relate_only_if when exact metadata can authoritatively label a pair or rule out some labels. Return one string from labels for an exact fact; return an iterable for the complete set of labels still possible; return None when the complete vocabulary remains possible. A singleton iterable becomes exact only when the task requires exactly one label. Relifold validates the constraint, freezes exact facts before closure, sends only possible labels to the judge, and rejects impossible judge or closure output. It never interprets a boolean as a label or guesses what absence means. The callable receives rows in canonical endpoint order.

Use min_labels_per_pair=1 together with max_labels_per_pair=1 only when every unresolved pair must receive exactly one label. The label vocabulary must then include the negative case explicitly. Without a minimum, an omitted pair is a valid sparse result meaning no declared relationship was supported; Relifold does not invent an independent label from absence.

With a positive minimum, every successfully evaluated unresolved pair is materialized with the required number of retained labels. If the model still omits a required label after retries, the judge failure remains visible as incomplete work; Relifold neither marks that pair evaluated nor fabricates its negative label.

Set max_candidate_pairs from an enforced input extent and your expected deterministic facts and closure. Relifold counts the exact unresolved hand after compatible prior evidence is restored. If the unresolved hand exceeds the ceiling, the task fails before any judge call and tells you the exact count. A dollar or call cap is not a substitute: those limits may stop after publishing only a partial relation hand.

The output describes known relationships. It need not materialize every possible pair. The session output display lets you select a node and inspect labeled relationships without requiring the entire result to fit on screen.