Semantic operators

SemMatching

Recover a one-to-one semantic matching between two Spaces.

SemMatching chooses a one-to-one set of semantic relationships. A value on either side appears in at most one selected pair.

SemMatching(
    name="match-resumes-to-openings",
    input_spaces=("candidates", "openings"),
    output_space="placements",
    primary_key="semantic_value",
    prompt=(
        "Match candidates and openings by required experience and demonstrated skills. "
        "Do not match on broad occupational similarity alone."
    ),
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    x_batch_size=8,
    y_batch_size=16,
    max_candidate_pairs=10_000,
    perfect=False,
)

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
`x_batch_size`	operator default	Number of X values in one request.
`y_batch_size`	operator default	Number of Y candidates in one request.
`max_candidate_pairs`	unlimited	Fail before semantic calls when unresolved eligible X/Y pairs exceed this work ceiling.
`perfect`	operator default	Require every X and Y value to appear exactly once; the task fails instead of publishing a partial result when that contract is infeasible.
`match_only_if`	none	A deterministic eligibility gate applied before semantic comparison.

Output

A one-to-one set of selected X/Y pairs. Use SemJoin when either side may legitimately have several matches. A perfect matching is a strict output contract: unequal or otherwise unmatchable hands fail visibly instead of producing null matches under a successful session.