Semantic operators

SemHierarchy

Recover a single-parent forest from broader and narrower concepts.

SemHierarchy builds one or more trees. Every non-root value may have at most one immediate parent.

SemHierarchy(
    name="organize-support-topics",
    input_spaces=("support-topics",),
    output_space="support-hierarchy",
    primary_key="topic",
    prompt=(
        "Place a topic below another only when the parent is genuinely broader "
        "and includes every case represented by the child."
    ),
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    max_depth=5,
    rho=0.20,
)

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
`batch_size`	operator default	Values considered together in one request.
`rho`	0.0	Additional allowance for checking weak ancestry decisions.
`max_rounds`	operator default	Maximum iterative structure rounds.
`max_immediate_children`	unlimited	Optional child-degree bound.
`max_depth`	unlimited	Maximum root-to-leaf depth.
`max_components`	unlimited	Maximum number of disconnected trees.
`ancestor_only_if`	none	A deterministic condition required before two values may form an ancestry pair.

SemHierarchy or SemTaxonomy?

Use SemHierarchy when one immediate parent is part of the output contract. Use SemTaxonomy when multiple immediate parents are valid.

Exact ancestry boundaries

When ancestry is meaningful only inside an exact family, declare ancestor_only_if=gates.equal("family"). Relifold then considers only within-family pairs. Prefer this closed gate to an equivalent Python lambda so large inputs can use the indexed family boundary. If nodes carry a deterministic iterable of ancestry-candidate keys, gates.share_any("ancestry_blocks") provides an indexed overlapping boundary. A missing shared key excludes the pair completely, so the authored keys must cover every relationship the task is expected to recover. A rejected ancestry direction is also respected through implied paths. In a single-parent hierarchy, a pair rejected in both directions makes their established descendant branches independent without additional model calls.