Feature/add a unified wrangles py cli for saved extract ai models and recipe execution

[mborodii-prog]

Summary

Adds a unified CLI for managing saved Extract-AI definitions and running recipes that use them, without writing custom Python or HTTP wrappers.

Builds on the shared authoring contract delivered by #1184 for #1182.

Related to #1183.

Changes

• Add wrangles model validate/create/update/inspect/export/verify.
• Add wrangles recipe run while preserving wrangles.recipe compatibility.
• Preserve custom functions, executable Python variables files, and dictionary selection.
• Fix numeric recipe --timeout parsing.
• Add reusable Python model-operation helpers without changing existing train.extract signatures or HTTP response return values.
• Preserve full definitions, including nested structures, additional columns, paired examples, Unicode, false, 0, and null.
• Preserve existing settings when omitted from updates and merge explicit overrides through the shared contract.
• Add bounded waiting, request timeouts, structured JSON output, stable exit codes, and field-level verification differences.
• Check known server-added settings against submission parameters.
• Include a Power Supply example with 23 attributes, three synthetic inputs, and an extraction recipe.

Example usage

Run from the repository root after installing the checkout in editable mode:

python -m pip install -e .

Model commands use existing Wrangles credentials through WRANGLES_USER and WRANGLES_PASSWORD. Extraction additionally requires OPENAI_API_KEY.

1. Validate and create a saved Extract-AI model

wrangles model validate examples/power-supply/definition.json --json
if ($LASTEXITCODE -ne 0) { throw "Validation failed" }

$name = "CLI Power Supply " + [guid]::NewGuid().ToString("N")

$created = wrangles model create `
    --type extract-ai `
    --file examples/power-supply/definition.json `
    --name $name `
    --verify `
    --wait-timeout 300 `
    --json | ConvertFrom-Json

$createExit = $LASTEXITCODE
$created | ConvertTo-Json -Depth 30

if ($createExit -ne 0) {
    throw "Retain the returned model ID and reconcile before retrying creation."
}

$modelId = $created.model_id

--verify implies waiting. Successful creation reports verification: passed and readiness: ready.

2. Inspect, export, and verify

wrangles model inspect $modelId --json

wrangles model export $modelId --output saved-power-supply.json --json
if ($LASTEXITCODE -ne 0) { throw "Export failed" }

wrangles model verify $modelId --file saved-power-supply.json --json

Standalone verification currently expects the complete saved definition, including server-added settings. Export provides that complete document.

3. Update the same model while preserving settings

$revision = Get-Content saved-power-supply.json -Raw | ConvertFrom-Json
$column = [Array]::IndexOf($revision.Columns, "Description")
if ($column -lt 0) { throw "Description column not found" }

$revision.Data[0][$column] += " Preserve the complete manufacturer name as printed."
$revision.PSObject.Properties.Remove("Settings")

$revision | ConvertTo-Json -Depth 100 |
    Set-Content revised-power-supply.json -Encoding utf8

wrangles model update $modelId `
    --file revised-power-supply.json `
    --verify `
    --wait-timeout 300 `
    --json

This replaces the schema table and preserves existing settings.

Successful readback reports verification: passed. Update readiness remains unconfirmed because the API does not establish a submission-to-version link.

4. Run extraction using the saved model

$env:POWER_SUPPLY_MODEL_ID = $modelId
$env:POWER_SUPPLY_INPUT = (Resolve-Path examples/power-supply/input.json).Path
$env:POWER_SUPPLY_OUTPUT = Join-Path $env:TEMP "power-supply-extracted.json"

wrangles recipe run examples/power-supply/recipe.wrgl.yml --timeout 120
if ($LASTEXITCODE -ne 0) { throw "Recipe failed" }

Get-Content -LiteralPath $env:POWER_SUPPLY_OUTPUT -Raw

The recipe uses the saved definition through:

wrangles:
  - extract.ai:
      input: description
      output: attributes
      output_format: dictionary
      model_id: ${POWER_SUPPLY_MODEL_ID}
      api_key: ${OPENAI_API_KEY}
      cache: false

Input and output destinations are explicitly defined in the example recipe. The legacy wrangles.recipe entry point remains supported.

Verification and failure behavior

• Submission acceptance, readiness, saved-content verification, and extraction accuracy are reported separately.
• Uncertain writes are not automatically retried. Known model IDs remain available in failure results.
• Waiting deadlines do not cancel server processing or roll back writes.
• Model commands emit one JSON object to stdout with --json; diagnostics go to stderr.
• Export writes the definition separately from command status.
• Standalone verification remains strict; aligning its server-field handling with the original-file workflow in Add a shared custom-model authoring SDK and unified WranglesPY CLI #1183 is outstanding.

Validation

• Focused CLI, helper, connector, compiler, and example regressions: 359 passed, 1 skipped.
• Manual live create --verify and update --verify passed on the same disposable model.
• Exported definitions passed local validation and standalone verification.
• Live recipe execution produced 3 records with 23 attributes each.
• One extraction discrepancy was observed: PS-002’s manufacturer was shortened to Énergie.
• The automated opt-in live test is implemented but has not yet been run against the service.
• CI and actual Excel UI interaction have not been verified in this work.

Scope and cleanup

This change does not add remote recipe execution, model deletion, permission management, or a new credential store. Excel UI automation and general extraction accuracy evaluation remain outside scope.

Disposable test models require manual cleanup using their recorded IDs. Reverting the code does not remove models already created through the API.