Add lookup.key and lookup.semantic operations and runtime contracts

[mborodii-prog]

Description

Add explicit lookup.key and lookup.semantic operations to WranglesPY, with separate recipe contract definitions.

The existing public entry point is generic lookup; the saved model's variant determines whether execution uses key lookup or semantic search. Explicit operation names will make that distinction visible in Python calls, recipes, generated schemas, and downstream documentation.

This follows the discussion in Wrangles-Docs #34, which proposed implementing the lookup variants as callable operations, similar to the existing extract.ai and extract.custom distinction.

Desired Behavior

Expose these operations through Python, YAML recipes, and the Wrangles DataFrame accessor:

Operation	Saved model purpose	Stored model variant
lookup.key	lookup	key
lookup.semantic	lookup	embedding

• Reuse the existing lookup execution path and saved models.
• Keep generic lookup available for existing Python callers and recipes.
• Validate that an explicitly selected operation is compatible with the supplied model. Make handling of missing and unknown variants explicit.
• Use the existing execution model_id. A catalog ID must not be substituted for the selected saved-model ID.
• Preserve supported output selection and renaming, complete-record output, row order, and existing lookup modes.
• Define each operation's recipe contract through the existing schema-generation mechanism: required parameters, defaults, accepted input/output forms, mode constraints, and examples.
• Document how n affects return shapes and which recipe modes support it.

Semantic models continue to use stored variant=embedding. The new operation name is lookup.semantic.

Example current / desired

In these examples, KEY_MODEL_ID and SEMANTIC_MODEL_ID are existing saved-model IDs. Define them as recipe variables or replace the placeholders with actual IDs.

The example models expose their value under Column1, matching the manual Excel fixtures. Replace this with the actual stored field name when using another model, such as Output. The left side of an output mapping selects the model field; the right side names the result column.

Current generic key lookup:

wrangles:
  - lookup:
      input: SKU
      output:
        - Column1: Output
      model_id: ${KEY_MODEL_ID}

Desired explicit key lookup:

wrangles:
  - lookup.key:
      input: SKU
      output:
        - Column1: Output
      model_id: ${KEY_MODEL_ID}

For a model containing ABC-001 → Bolt and ABC-002 → Nut, the selected field should contain Bolt and Nut, with duplicate input rows and their order preserved.

Desired explicit semantic lookup:

wrangles:
  - lookup.semantic:
      input: Description
      output:
        - Column1: Output
        - Score: Score
      model_id: ${SEMANTIC_MODEL_ID}

For the test fixture, descriptions such as steel bolt and steel bolt eight millimetre should match the stored bolt description. The selected value and score should appear in separate columns.

Complete-record and multiple-match output should also remain available. For example:

wrangles:
  - lookup.semantic:
      input: Description
      output: "Match *"
      model_id: ${SEMANTIC_MODEL_ID}
      n: 3

With three available matches, Match 1, Match 2, and Match 3 should contain match dictionaries. The lookup backend remains responsible for ranking and scores.

Python usage:

import os
import wrangles

key_model_id = os.environ["KEY_MODEL_ID"]
semantic_model_id = os.environ["SEMANTIC_MODEL_ID"]

values = wrangles.lookup.key(
    ["ABC-001", "ABC-002"],
    model_id=key_model_id,
    columns="Column1",
)

matches = wrangles.lookup.semantic(
    ["steel bolt", "brass nut M8"],
    model_id=semantic_model_id,
    columns=["Column1", "Score"],
)

Acceptance criteria

• Both explicit names resolve and execute through Python, recipes, and the Wrangles DataFrame accessor.
• Each operation validates model purpose and the agreed variant rules, with useful errors for incompatible models.
• Existing generic lookup calls and saved recipes retain their behavior.
• Generated recipe schemas contain separate definitions for lookup, lookup.key, and lookup.semantic.
• Contract definitions match actual parameters, defaults, output forms, and supported mode combinations.
• Tests cover scalar/list inputs, selected fields and output renaming, complete records, duplicate rows, empty inputs, supported lookup modes, multiple matches, and invalid model variants.
• Regression tests compare legacy and explicit operations using the same model metadata and backend responses.
• Manual Excel checks cover key and semantic execution with the same input and model when comparing against legacy lookup; score differences and untested cases are recorded explicitly.
• Examples use actual saved-model field names and execution IDs, with known limitations documented.

Draft behavior to confirm during review

• The current draft requires exact stored variants: key for lookup.key and embedding for lookup.semantic. Missing/null, unknown, and literal semantic variants are rejected by the explicit names. Generic lookup retains its existing handling.
• The new recipe operations reject a non-null n with by_dataframe or by_matrix; multiple-match requests use by_row.

These are proposed contract choices for review, not changes to existing generic lookup behavior.

Scope

This issue covers the WranglesPY operations, recipe contract definitions, and their tests. Separate documentation pages and Registry integration should be coordinated with the Wrangles-Docs work.

It does not require new database tables, catalog allocation changes, model migrations, a new lookup API endpoint, or a new semantic scoring algorithm.