Semantic operators

SemAssign

Recover labeled semantic relationships between two Spaces.

SemAssign relates X values from the first Space to Y values from the second and labels every emitted relationship with one of the declared labels. The Y values are data; the labels describe how an X and Y are related. Earlier design discussions called this operation SemLabel; SemAssign is its sole public name, not a separate operator.

SemAssign(
    name="assign-control-families",
    input_spaces=("policy-clauses", "control-families"),
    output_space="control-assignments",
    primary_key="semantic_value",
    labels=("supports", "partially_supports"),
    prompt=(
        "Relate a policy clause to a control family only when the clause materially "
        "supports that family. Label the relationship using the supplied vocabulary."
    ),
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    max_assignments_per_x=3,
    max_candidate_pairs=10_000,
)

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 relationship-label vocabulary.
`x_batch_size / y_batch_size`	operator defaults	Batch dimensions.
`max_assignments_per_x`	unlimited	Maximum Y assignments emitted for each X.
`max_assignments_per_y`	unlimited	Maximum X assignments emitted for each Y.
`exact_x / exact_y`	operator defaults	Fill declared bounds from evaluated candidates only; never from failed or budget-skipped pairs.
`max_candidate_pairs`	unlimited	Fail before semantic calls when unresolved X/Y pairs exceed this work ceiling.

Output

For each X value, the output records matching Y values and their declared relationship labels. Use SemJoin when the relationship is unlabeled.

Maximum versus exact cardinality

A maximum is an upper bound. Exact mode additionally fills a deficit from the least-negative successfully evaluated candidates. It never fabricates an assignment from a failed, exhausted, or budget-skipped pair. If evaluation did not cover enough candidates, the declared count remains unmet; validate that cardinality before treating the output as complete. Leave exactness false whenever zero assignments is a valid answer or only positively supported relationships should be emitted.