Plan of record: third-party API configuration and generated caller catalogs #1206

Purpose and ownership

This is the living plan of record for the third-party API configuration redesign. Keep this issue body current as design decisions are made in the ongoing task.

• docs/api_configuration.md is the authoritative description of the latest agreed system design, including behavior not yet implemented. It owns terminology, configuration structure, resolution rules, caller coverage, and worked examples.
• This issue owns decision history, unresolved questions, implementation gaps, candidate delivery slices, dependencies, and verification status. Once a decision is agreed, update the reference and this plan together.
• The documentation split and rename from docs/ai_configuration.md are saved in local commit 953382fc; the JSON Schema design update is saved in local commit c2b11098, both on codex/extract-ai-cleanup. These documentation checkpoints are not yet pushed. Do not infer deployed behavior from the design document.
• Design review is still in progress. Lock the design before choosing and implementing the first slice(s). The sequence below is a proposal, not a finalized PR split.

Outcome

Manage third-party API choices and defaults in one configuration, then generate consumer-oriented caller catalogs from it. Recipes are the primary use case; Python functions use the same resolution rules. Start with the configuration and catalog foundation, then apply it to inline and saved extraction through the shared runtime.

Scope includes AI providers, SerpAPI, and DeepL. An API can have no selectable model. A configuration entry does not by itself implement an adapter or establish live provider availability.

Agreed design decisions

Application delegation must preserve the resolved application policy: notes calling extraction and semantic-index construction calling embeddings must not be overwritten by primitive defaults. Separate nested recipe steps resolve their own operation while retaining origin.

Decisions still needed before implementation

• Complete the caller/operation/action matrix's actual selections and operational defaults, including Web. Reasoning none and one additional retry are already settled; caller timeout/concurrency differences are not.
• Finalize field shapes, model/API compatibility declarations, null/clear semantics, and treatment of defaults inapplicable to an alternative model. Place standard parameter schemas at the applicable API/model levels without introducing schema-override semantics. Distinguish partial defaults from complete invocation inputs when validating required fields.
• Agree unsupported explicit-setting behavior and extra-parameter routing. The current extraction behavior warns and omits unsupported tuning; do not accidentally turn this into rejection or an expensive provider fallback during migration.
• Define caller-context transport, initialization, validation, and behavior for missing/unknown callers across local, hosted, nested, concurrent, and asynchronous paths. Proposal for legacy requests: record unknown origin and preserve existing behavior during upgrade; do not infer XL from hosting or PY from implementation language.
• Define migration for existing semantic indexes without a complete persisted embedding contract; never substitute the latest default silently.
• Finalize public export fields, artifact/schema/file names, environment-scoped delivery, revision matching, and refresh/cache behavior. Renaming the guide does not automatically rename ai_defaults.yml, WRANGLES_AI_CONFIG, or public interfaces.
• Confirm save-time inheritance/clear behavior and treatment of existing saved values, independently from execution precedence.
• Agree the first slice(s), their workstream/branch scope, and required consumer adaptations before coding.

Implementation baseline and gaps

As checked on 2026-09-29, PR #1203 remains an open draft, targeting main, with remote head e2468eeeb981b406db206bb3f5722f4cdd54ff4f. It contains useful extraction/catalog work based on the earlier design; it is not the completed implementation of this redesign.

• #1200 supplied the earlier provider/model configuration foundation. The earlier role mechanism and extraction-first catalog are migration inputs, not the target contract.
• The earlier exporter reads packaged configuration only. Replacement catalogs and the new caller-oriented layout require implementation. The earlier catalog is unreleased and does not require an automatic compatibility alias or format-version increment.
• The current extraction compiler still favors a saved model over a conflicting call model. wrangles/extract.py currently fills a configured model before calling wrangles/ai_definition.py, so reversing an expression alone would incorrectly treat inherited defaults as explicit overrides.
• Current reasoning precedence already permits a call to override saved reasoning. Sol's model default and the unreleased generate.ai operation still set low; remove that operation override or change it so shared none survives.
• Cross-service caller propagation and the catalog-driven editors are incomplete. Keep the manual WranglesXL model-list patch independent.
• SerpAPI already forwards extras after adapter checks. Preserve AI Mode's fixed engine/output and rejected options; classic search currently differs between recipe and direct-function locale defaults, so any normalization needs review.
• DeepL's inspected service adapter forwards text and language settings, not arbitrary extra provider options. Its service path must be integrated; Python catalog metadata alone does not establish support.
• Existing semantic training and query sources use small/512. That source evidence does not prove every historical index has that contract.
• API-Core copies ordinary model-content query arguments into saved Settings. Carry caller context separately; coordinate its exact contract with the shared logging work.

The prior mixed design/implementation document remains available in Git history. Keep historical mechanics here only when needed to explain a migration action.

Tooling choice and implementation boundary

Use standard schemas for parameter descriptions and validation, with ordinary YAML data for configured values. Python jsonschema validates the configuration, embedded parameter schemas, and effective parameter objects; declare it as a runtime dependency when runtime callers use it. The shared Wrangles resolver still selects caller/operation/action and provider/API/model, applies defaults and saved/call precedence, preserves provenance, and enforces operation-specific behavior. Adapters construct requests and separate provider parameters from runtime/client controls, context, authentication, and structural fields.

Do not deep-merge schemas as if they were defaults. Provider/model constraints and applicable application restrictions must all hold; open kwargs cannot widen a known constraint. Keep editor-only restrictions out of execution schemas. Schema validation reports a violation; migration must preserve each operation's agreed error or warning/omission behavior. An empty enum is not the representation for an unsupported parameter; use a property schema of false when explicitly forbidding that parameter.

OpenAPI can supply provider HTTP contracts where suitable, but does not replace model-specific or Wrangles-specific policy. Review and version imported definitions rather than fetching them during execution. Postman can exercise those contracts and test scoped values; it does not become a runtime dependency. No additional hosted configuration platform is required for this design.

References: JSON Schema object rules, default annotations, Python jsonschema, OpenAPI parameters, and Postman collection design.

Candidate delivery sequence — decide after design lock

1. Configuration foundation: implement the source shape, standard JSON Schema definitions and jsonschema validation, and shared resolver, including caller-owned selections, model-less APIs, extensible parameters, and request-context inputs. Migrate custom supported-value/sentinel declarations to standard schema constructs. Migrate assignments/defaults and inspect helpers/tests that still select by role.
2. Generated caller catalog: derive packaged and replacement views, public parameter schemas, and resolved defaults from the same validated snapshots. Verify alternate-choice defaults, schema-reference bundling, public filtering, deterministic revision identity, and environment/publication boundaries. Decide whether this and the foundation form one PR or two.
3. Return to PR Unify saved extract.ai configuration and publish the packaged AI catalog #1203 for extraction: adapt/rebase its useful work onto the foundation; remove duplicate or superseded catalog changes. Integrate caller context and the new precedence for recipe and saved-model execution through the shared runtime. Update schemas, guides, tests, and the PR description to its final scope.
4. Consumer and adapter slices: agree separate work for the WranglesXL/Web editor consumers, semantic save/build/query paths, remaining API callers including SerpAPI/DeepL, and note generators. Their sequence remains open. generate.ai remains lower priority.

New implementation PRs target main. Development is a deployment environment, not an integration branch. Existing #1203 stays draft while design and sequencing are unresolved; this issue does not merge, deploy, or mark it ready.

Verification and delivery gates

• Resolution checks cover all callers, choices with/without models, defaults versus restrictions, missing selections, mapping/list merges, explicit false/0, model compatibility, kwargs, and complete replacements.
• Schema checks cover valid/invalid types and enum values, numeric bounds, required inputs, explicitly unsupported properties, extra kwargs, composed constraints, and preservation of editor-versus-execution scope. Verify schemas against Draft 2020-12 and ensure validation neither inserts defaults nor widens known constraints. Validate configured values without demanding inputs intentionally supplied at call time.
• Catalog checks prove resolver/export parity, stable provenance, no credentials/prompts/internal endpoints/unrestricted kwargs, and independent packaged/custom outputs. Apply the same public filtering to schema descriptions/examples/default annotations/references; consumers must not need private or live remote schema retrieval.
• Extraction checks cover Recipes and Python functions, saved/inline definitions, both supported APIs, explicit model and reasoning overrides, omitted arguments retaining saved settings, selected-model defaults, unchanged saved definitions, and deprecated execution warnings.
• Preserve saved aliases/normalization, explicit unlisted model IDs and dated snapshots, output/instruction/example composition, credential routing, endpoint overrides, cache contracts, and generate.ai recipe/function strictness unless separately reviewed.
• Reasoning defaults to none for Luna/Sol across caller cells and operation overrides. Retry means one additional attempt; timeout remains per attempt.
• Context checks cover nested/concurrent work, application delegation, retries, and asynchronous origin propagation without crossing runs.
• Semantic checks preserve provider/model/dimensions/tasks through index build and query; generic embeddings never silently inherit lookup-only 512 dimensions.
• Run focused credential-free checks using the repository's local test configuration. Record local/mock/static evidence separately from live save/build/execute, editor testing, GitHub CI, and deployment evidence.
• Publish the catalog only after its matching runtime deployment succeeds. Failed publication leaves the prior artifact available; recheck deployed revision before retrying an old publication. A merged Python PR alone does not establish availability in execute-recipes-dev.

Related work and boundaries

• WranglesPY #1217: extraction reasoning-default incident and isolated v1.20.4.1 patch. Coordinate its longer-term/current-main fix with this redesign; implementation is deferred for now. Preserve the agreed extraction default of none for current and future models and explicit reasoning overrides.
• WranglesXL #1259: catalog-driven saved-model editor.
• WranglesXL #1260: independent manual model-list update.
• API-Core #106: shared wrangle logging/request context coordination; align the caller contract rather than duplicate it.
• WranglesPY #1172: optional extraction tracing, not a prerequisite.
• WranglesPY #1192: explicit lookup entry points; this redesign does not depend on renaming lookup first.

LiteLLM/proxy adoption, automatic provider discovery, and a remote configuration compiler remain deferred. Preserve Chat Completions compatibility; retiring that API is separate work.

Decision log

• 2026-10-04: adopted JSON Schema Draft 2020-12 and Python jsonschema for parameter definitions/validation, replacing the proposed supported_values / all-allowed vocabulary. Keep explicit default resolution and application policy in Wrangles, generate public caller schemas/defaults from the same source, and use OpenAPI/Postman optionally for provider contracts and request testing. This updates the design; implementation slices remain unchosen.
• 2026-09-28: expanded the design to third-party APIs, added wranglesweb, standardized api and wrangle.execute, moved default selections into caller configuration, and required replacement catalogs plus extensible kwargs.
• 2026-09-29: confirmed explicit extraction call settings override saved settings; set shared Luna/Sol reasoning default to none; confirmed caller views are generated rather than hand-maintained in product code.
• 2026-09-29: separated the current design reference into docs/api_configuration.md and this living plan. Configuration → generated catalog → return to extraction PR Unify saved extract.ai configuration and publish the packaged AI catalog #1203 is the candidate sequence, pending design lock.

When a decision changes, update the agreed-decision/open-decision sections and the reference first, then add a concise dated log entry. Do not leave contradictory instructions in comments or copy a second implementation plan into the reference.