Core concepts
← Spaces

Primary and supporting keys

Show each task the meaningful value it decides and only the evidence that can improve that decision.

A Space has no permanent primary or supporting key. Each operation declares its own view of the input rows, because two operations may legitimately reason about the same dataset at different semantic grains.

Primary key

primary_key identifies one distinct value for this operation. Choose the shortest human-recognizable field—or composite of fields—that expresses what the decision is about. For a product-category hierarchy, category_name is normally a better key than a category URL, hash, database sequence, full product list, or one incidental attribute value.

Rows with the same primary-key value represent the same task value and are evaluated once. That is useful when repeated source rows require the same semantic answer; it does not preserve every source occurrence. Consolidate required IDs or memberships deterministically before the semantic operation and attach the result back afterward.

Supporting keys

evidence declares optional supporting fields shown with the primary value. Include a field only when its contents can materially improve this semantic decision. Never repeat a field already used by the primary key. Leave evidence=() when no non-key field is a meaningful quality booster.

A supporting field must pass two tests: it adds non-redundant information that materially changes the semantic decision, and that contribution cannot be settled completely by arithmetic, exact comparison, or a deterministic gate. Failure of either test keeps it out of the paid prompt. A broad category label that merely repeats what a descriptive headline already says is not supporting evidence. It may still be valuable as a validated deterministic eligibility gate under a tight budget. Gate equality means “eligible to compare,” never “must match.” Redundant evidence is a planning defect, not harmless context.

Supporting evidence should be compact and task-relevant. For an encyclopedia-class hierarchy, article count is not semantic evidence, although it may enforce an exact eligibility rule that an ancestor cannot have fewer articles than its descendant. For housing matching, an applicant's short free-text preference may add meaning absent from an opaque applicant ID; exact budget, floor area, city, and postal-location constraints belong in deterministic eligibility instead. Do not ask the semantic model to recompute those comparisons.

Worked example

SemTaxonomy(
    name="arrange-product-categories",
    input_spaces=("categories",),
    output_space="category-taxonomy",
    primary_key="category_name",
    evidence=("representative_products", "representative_attributes"),
    prompt="Place categories according to what the products are used for.",
    # Enforce numeric or temporal constraints with a deterministic gate.
    ancestor_only_if=ancestor_has_more_views,
)

If no concise field expresses the semantic value, add a cheap deterministic transformation that creates one before the semantic operation. Do not replace meaningful content with an opaque ID; the purpose is to avoid repeatedly sending long bodies or lists while keeping the actual subject of the decision visible.

Two-sided operations

A two-sided operation applies one primary-key shape independently to both input roles. If the roles use different source column names, first copy their meaningful values to a shared alias. Keep role-specific context in evidence only when it changes the semantic judgment.

Checklist