Guides

Cost, semantic review, and confidence

Reduce semantic cost conservatively and write confidence guidance that matches each operator.

These are recommended design practices, not declaration requirements. You may intentionally send a complete input hand to a semantic task or use a different confidence rubric. Relifold still compiles the prompt so its confidence field, threshold, examples, and output shape agree.

Send only unresolved relationships to semantic judgment

Start with the operation that best expresses the desired result. Use SemCluster for semantic grouping and deduplication, SemTaxonomy or SemHierarchy for broader/narrower structure, and SemSort for semantic order. Then ask which parts of that task are already settled by exact evidence for its downstream goal.

Normal operators and deterministic candidate gates can reduce the hand before model judgment:

Normalize exact spelling, punctuation, identifiers, dates, or units with a deterministic Transform.
Pre-merge exact or conservatively normalized duplicates with Cluster.
Exclude impossible pairs using arithmetic, exact categories, time bounds, indexed token retrieval, or another high-precision predicate.
Partition independent domains before a semantic relationship task when the partition itself is exact.

Gates remove opportunities. A semantic gate should be conservative about exclusion. Measure how many rows or pairs remain, review counterexamples, and prefer false admissions over false exclusions when recall matters.

Three examples

News deduplication. Exact normalized duplicates can merge first. A conservative time or entity index can exclude obviously unrelated headline pairs. SemCluster then decides only the plausible same-event pairs.

Product taxonomy. A child cannot be broader than a candidate with a larger deterministic depth or incompatible catalog branch when those fields are authoritative. Use those facts to gate candidates; let SemTaxonomy decide semantic subsumption among the rest.

Matching before ranking. Deterministic budget, geography, or availability rules can exclude impossible X/Y matches before SemJoin. If the joined evidence is consumed only by SemSort, also ask whether some order relations are already exact before paying for semantic comparisons.

The Planner is a beta architecture assistant

The Planner can propose these reductions, estimate the largest affordable semantic hand, and explain the architecture in its planning rationale. Treat a generated regex, similarity threshold, or token rule as a research direction until representative evidence supports it. The DAG shape and budget frontier may still save substantial design time even when a researcher or coding agent later replaces the preliminary deterministic rule.

Confidence guidance is optional but useful

A semantic task always returns confidence because the runtime needs it. A raw prompt does not have to explain the scale: Relifold's prompt compiler adds an operator-specific Confidence section using the task's actual confidence_threshold. Writing your own section is useful when domain evidence deserves more precise calibration.

A good section defines four things: what one score certifies, what evidence weakens it, the exact accepted/unresolved threshold, and examples on both sides of that boundary. Confidence is local to the operator's smallest complete decision, not a general feeling about the topic.

Confidence
For each complete cluster group, score the weakest material merge or separation
assertion visible in that partition cell. Below 0.5 is unresolved; 0.5–0.74 is
borderline accepted; 0.75–0.89 is strong; 0.9–1.0 requires no material unresolved
contradiction. A singleton is not confident merely because it has one member.

Examples
- Same named incident, participants, place, and compatible timing: 0.93.
- Shared topic but unclear whether it is the same incident: 0.35.

Operator-specific score units

Operator	One confidence certifies
`SemCluster`	One group's complete equivalence decision in the visible hand.
`SemTaxonomy`	One value's complete immediate-parent assignment.
`SemHierarchy`	One value's single-parent or root decision.
`SemSort`	The complete order, limited by its weakest ordering boundary.
`SemJoin`	One X value's complete qualifying Y set.
`SemAssign`	One X value's complete labeled Y assignment.
`SemMatching`	One match or unmatched decision.
`SemRelate`	One endpoint-pair label decision.
`SemTransform`	One input row's complete produced-field object.
`SemFilter`	A kept-row decision and the batch decision for omitted rows.

Reasons

With include_reason=True, Relifold defaults to decisive visible evidence of at most ten words. You may explicitly request a longer visible reason. Length limits guide generation only: Relifold never truncates or normalizes a reason after it is returned, because doing so saves no spend and destroys existing evidence. With include_reason=False, reason instructions and fields are removed from the effective schema. Reasons are evidence summaries, not hidden chain-of-thought.

Next: choose an operator, or read how the Planner exposes task purpose, evidence, uncertainty, and cost.