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 input decision unit. An existing unique ID is valid when evidence includes the meaningful content needed for the task. A natural content field or composite is also valid when it distinguishes the intended decision units. You do not need to replace a valid ID with a generated description.

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,
)

Keep identity separate from meaning: an ID alone cannot replace missing task evidence. For example, use article_id as the key and supply headline and any necessary article text as evidence. No extra consolidation or expansion is required merely because the key is an ID.

Two-sided operations

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

Checklist