SemJoin

Recover many-to-many semantic matches between an X Space and one or more Y Spaces.

The first input Space supplies X values. Remaining input Spaces form the Y side. For each X, SemJoin emits the Y values that satisfy the prompt's relationship.

SemJoin(
    name="match-needs-to-products",
    input_spaces=("customer-needs", "products"),
    output_space="recommended-products",
    primary_key="name",
    prompt=(
        "Match a customer need to a product only when the product directly "
        "addresses the stated need. Do not infer a match from broad category alone."
    ),
    provider="openai",
    model="gpt-5",
    reasoning_effort="low",
    x_batch_size=8,
    y_batch_size=20,
    rho=0.20,
    max_matches_per_x=5,
    max_candidate_pairs=10_000,
    match_only_if=lambda need, product:
        need["market"] == product["market"],
)

Output shape

Each output row retains the X fields and adds matches. Every entry in matches is the complete matched Y row—not a wrapper containing a nested value. A deterministic Transform can project the chosen catalog fields:

Transform(
    name="project-selected-product",
    input_spaces=("recommended-products",),
    output_space="selected-products",
    primary_key="name",
    fn=lambda row: {
        "product_id": row["matches"][0]["product_id"],
        "product_name": row["matches"][0]["name"],
    },
)

Primary keys across both sides

The declared primary-key columns must exist on both X and Y because the same key shape identifies values independently on each side. When the two Spaces use different names for their central fields, first use deterministic transforms to copy them to a common alias, such as semantic_value. Keep role-specific descriptions as evidence; do not build a composite key from columns that exist on only one side.

Cost shape

A join considers an X-by-Y candidate rectangle. Reduce it before semantic work: filter ineligible rows, use category or time gates, and keep only fields needed for the match. Bounds such as max_matches_per_x describe the result you want; they are not substitutes for a good eligibility predicate. max_candidate_pairs is a final pre-run guard over the unresolved eligible hand after compatible prior evidence is restored; it fails rather than silently returning a partial relationship result.

A rejected match_only_if pair is pair-local. It does not imply that another X or Y cannot match the same endpoint. The separate cardinality bounds can retire remaining candidates only after an endpoint reaches its declared match capacity.

Maximum versus exact cardinality

max_matches_per_x=3 with exact_x=false emits zero through three supported matches. With exact_x=true, every X must emit exactly three matches; the operator fills any deficit from the least-negative evaluated candidates. Use exactness only when the business output requires that count for every X. If no match is valid, or the instruction says “at most” or “only supported matches,” leave exactness false. Failed, exhausted, and budget-skipped pairs are never converted into matches. If evaluation does not cover enough candidates, the declared exact count remains unmet and is visible in the task output and failed-call metrics; treat that as a failed business invariant rather than accepting a partial result.

SemJoin versus SemMatching

Use SemJoin when values may have many matches. Use SemMatching when the output itself must be one-to-one, optionally perfect.