Semantic operators

SemTaxonomy

Recover a multi-parent broader and narrower taxonomy.

SemTaxonomy recovers broader and narrower relationships where a value may have more than one immediate parent.

SemTaxonomy(
    name="organize-product-categories",
    input_spaces=("categories",),
    output_space="category-taxonomy",
    primary_key="category_name",
    evidence=(("top_products", 5),),
    prompt=(
        "Place a category below another only when the parent is genuinely broader "
        "and every item in the child also belongs in the parent."
    ),
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    max_immediate_parents=2,
    max_depth=6,
    ancestor_only_if=lambda parent, child:
        parent["view_count"] >= child["view_count"],
)

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_parents`	unlimited	Optional parent-degree bound.
`max_immediate_children`	unlimited	Optional child-degree bound.
`max_depth`	unlimited	Maximum path depth.
`max_components`	unlimited	Maximum disconnected taxonomy components.
`ancestor_only_if`	none	A deterministic condition required before two values may form an ancestry pair.

Output

The output represents immediate and implied ancestry without forcing a single parent. Use ordinary Taxonomy when code can determine ancestry exactly.

Exact ancestry boundaries

When taxonomy relationships are valid only within an exact family, use ancestor_only_if=gates.equal("family"). The closed equality gate avoids unrelated cross-family model work and supports indexed candidate discovery. For overlapping deterministic candidate sets, use gates.share_any("ancestry_blocks"), optionally inside gates.both(...) with an oriented numeric rule. Relifold deduplicates pairs that share several keys, but it never judges a pair excluded by the authored blocks.

A rejected direction is a hard ancestry constraint. If an otherwise eligible arc would combine with established ancestry to imply a rejected path, Relifold skips that impossible orientation. Unlike a single-parent hierarchy, a multi-parent taxonomy does not propagate general independence across descendant subtrees because independent categories may share a descendant.

Cost estimate

version_forecast() returns the current full-execution cost estimate when compatible evidence is available. Otherwise it says that a complete run is required.