@openapi-flow/langchain 0.3.14 → 0.3.16

package/README.md

@@ -1,5 +1,19 @@
 # @openapi-flow/langchain
 
+Version **0.3.16** adds `planWorkflowConnectionGoals` and
+`planWorkflowConnectionStep`. Each makes one structured model call; the host owns
+looping, checkpointing and review. Native planning stages accept optional abort
+signals. See the [connection guide](https://github.com/carefreelife98/openapi-flow/blob/main/docs/incremental-connection-planning.md)
+and [release status and limitations](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.16.md).
+
+Version **0.3.15** adds `selectApiBindingSources`, `planApiCallBindings` and
+`planApiBindingsByCall` for scoped API binding work. The model no longer needs to
+regenerate a whole selected-call inventory in this path. Code checks complete
+coverage and cross-call cycles, and the host explicitly chooses concurrency and
+stores validated progress for resume. Existing `planApiBindings` stays compatible.
+See [scalable bindings](https://github.com/carefreelife98/openapi-flow/blob/main/docs/scalable-api-binding-planning.md)
+and the [release record](https://github.com/carefreelife98/openapi-flow/blob/main/docs/releases/0.3.15.md).
+
 Version **0.3.14** adds source-owned structured errors and preserves initial
 argument provenance failures across optional enum selection. Existing prompts,
 values, schemas and retry behavior are unchanged; the host still chooses the

package/dist/arguments/analyze-api-input-answers.js

@@ -1,25 +1,34 @@
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
-import { captureApiInputAnswerContext, createApiInputAnswerExtractionRecord, resolveApiInputAnswerInterpretations, describeApiInputEnumAnswerChoices, describeApiInputSources, resolveApiInputSourceSelections, } from '@openapi-flow/core';
+import { captureApiInputAnswerContext, createApiInputAnswerExtractionRecord, resolveApiInputAnswerInterpretations, describeApiInputEnumAnswerChoices, describeApiInputSources, resolveApiInputSourceSelections, runOpenApiFlowOperation, } from '@openapi-flow/core';
 import { createApiInputAnswerSourceSchema, apiInputAnswerExplanationOptionsSchema, } from '../schemas/api-input-answer-source-schema.js';
 import { apiInputAnswersPrompt } from '../prompts/api-input-answers-prompt.js';
 import { serializeStructuredOutputSchema } from '../schemas/serialize-structured-output-schema.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+import { invokeStructuredModel } from '../model/invoke-structured-model.js';
 export async function analyzeApiInputAnswers(input) {
-    const options = apiInputAnswerExplanationOptionsSchema.parse({
-        includeExplanations: input.includeExplanations,
-        selectOasEnums: input.selectOasEnums,
-    });
-    const snapshot = captureApiInputAnswerContext({
-        reply: input.reply,
-        requirements: input.requirements,
-        ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
-        ...(options.selectOasEnums === undefined
-            ? {}
-            : { selectOasEnums: options.selectOasEnums }),
+    const { options, snapshot } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'analyzeApiInputAnswers',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        const options = apiInputAnswerExplanationOptionsSchema.parse({
+            includeExplanations: input.includeExplanations,
+            selectOasEnums: input.selectOasEnums,
+        });
+        const snapshot = captureApiInputAnswerContext({
+            reply: input.reply,
+            requirements: input.requirements,
+            ...(input.purpose === undefined ? {} : { purpose: input.purpose }),
+            ...(options.selectOasEnums === undefined
+                ? {}
+                : { selectOasEnums: options.selectOasEnums }),
+        });
+        if (input.model !== undefined &&
+            (!input.model || typeof input.model.withStructuredOutput !== 'function'))
+            throw new Error('analyzeApiInputAnswers.model must support structured output when supplied');
+        return { options, snapshot };
     });
-    if (input.model !== undefined &&
-        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
-        throw new Error('analyzeApiInputAnswers.model must support structured output when supplied');
     if (!snapshot.requirements.length || snapshot.reply === '')
         return {
             status: snapshot.requirements.length
@@ -37,82 +46,107 @@ export async function analyzeApiInputAnswers(input) {
             sources: [],
             unansweredRequirementIds: snapshot.requirements.map((item) => item.id),
         };
-    if (!input.model)
-        throw new Error('analyzeApiInputAnswers.model is required for a nonempty reply with pending inputs');
-    const enumChoices = describeApiInputEnumAnswerChoices(snapshot);
-    const schema = createApiInputAnswerSourceSchema(snapshot.requirements, catalog, options.includeExplanations === true, enumChoices);
-    const output = await input.model
-        .withStructuredOutput(serializeStructuredOutputSchema(schema, 'draft-2020-12'), {
+    const { model, schema, wireSchema, enumChoices } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'analyzeApiInputAnswers',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        if (!input.model)
+            throw new Error('analyzeApiInputAnswers.model is required for a nonempty reply with pending inputs');
+        const enumChoices = describeApiInputEnumAnswerChoices(snapshot);
+        const schema = createApiInputAnswerSourceSchema(snapshot.requirements, catalog, options.includeExplanations === true, enumChoices);
+        return {
+            model: input.model,
+            schema,
+            enumChoices,
+            wireSchema: serializeStructuredOutputSchema(schema, 'draft-2020-12'),
+        };
+    });
+    const output = await invokeStructuredModel({
+        model,
+        schema: wireSchema,
+        operation: 'analyzeApiInputAnswers',
         name: 'extract_api_input_answers',
         method: 'functionCalling',
         strict: true,
-    })
-        .invoke([
-        new SystemMessage(apiInputAnswersPrompt),
-        new HumanMessage(JSON.stringify({
-            reply: snapshot.reply,
-            questions: snapshot.requirements,
-            ...(snapshot.purpose === undefined
-                ? {}
-                : { purpose: snapshot.purpose }),
-            sources: catalog,
-            ...(enumChoices.length ? { enumChoices } : {}),
-        })),
-    ]);
-    const parsed = parseStructuredOutput(schema, output, 'model clarification answer sources');
-    const selections = resolveApiInputSourceSelections({
-        ...snapshot,
-        selections: parsed.answers.flatMap(({ requirementId, source }) => source.kind === 'oas-enum' ? [] : [{ requirementId, source }]),
+        messages: [
+            new SystemMessage(apiInputAnswersPrompt),
+            new HumanMessage(JSON.stringify({
+                reply: snapshot.reply,
+                questions: snapshot.requirements,
+                ...(snapshot.purpose === undefined
+                    ? {}
+                    : { purpose: snapshot.purpose }),
+                sources: catalog,
+                ...(enumChoices.length ? { enumChoices } : {}),
+            })),
+        ],
     });
-    const enumSelections = parsed.answers.flatMap((answer) => {
-        if (answer.source.kind !== 'oas-enum')
-            return [];
-        if (typeof answer.reason !== 'string')
-            throw new Error(`Enum answer ${answer.requirementId} requires an explanation`);
-        const [intent] = resolveApiInputSourceSelections({
+    return runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'analyzeApiInputAnswers',
+        stage: 'contract-validation',
+        code: 'API_ARGUMENT_VALIDATION_FAILED',
+    }, () => {
+        const parsed = parseStructuredOutput(schema, output, 'model clarification answer sources');
+        const selections = resolveApiInputSourceSelections({
             ...snapshot,
-            selections: [
-                { requirementId: answer.requirementId, source: answer.source.intent },
-            ],
+            selections: parsed.answers.flatMap(({ requirementId, source }) => source.kind === 'oas-enum' ? [] : [{ requirementId, source }]),
         });
-        return [
-            {
-                requirementId: answer.requirementId,
-                candidateId: answer.source.candidateId,
-                intent: {
-                    sourceFormat: intent.sourceFormat,
-                    sourceText: intent.sourceText,
+        const enumSelections = parsed.answers.flatMap((answer) => {
+            if (answer.source.kind !== 'oas-enum')
+                return [];
+            if (typeof answer.reason !== 'string')
+                throw new Error(`Enum answer ${answer.requirementId} requires an explanation`);
+            const [intent] = resolveApiInputSourceSelections({
+                ...snapshot,
+                selections: [
+                    {
+                        requirementId: answer.requirementId,
+                        source: answer.source.intent,
+                    },
+                ],
+            });
+            return [
+                {
+                    requirementId: answer.requirementId,
+                    candidateId: answer.source.candidateId,
+                    intent: {
+                        sourceFormat: intent.sourceFormat,
+                        sourceText: intent.sourceText,
+                    },
+                    reason: answer.reason,
                 },
-                reason: answer.reason,
-            },
-        ];
-    });
-    const resolved = resolveApiInputAnswerInterpretations({
-        ...snapshot,
-        selections,
-        ...(enumSelections.length ? { enumSelections } : {}),
-    });
-    let extraction;
-    if (options.includeExplanations === true) {
-        if (typeof parsed.reason !== 'string')
-            throw new Error('model clarification answer sources require an explanation');
-        extraction = createApiInputAnswerExtractionRecord({
+            ];
+        });
+        const resolved = resolveApiInputAnswerInterpretations({
             ...snapshot,
-            decision: {
-                reason: parsed.reason,
-                answers: selections.map((selection) => {
-                    const source = parsed.answers.find((answer) => answer.requirementId === selection.requirementId);
-                    if (typeof source?.reason !== 'string')
-                        throw new Error(`model answer ${selection.requirementId} requires an explanation`);
-                    return { ...selection, reason: source.reason };
-                }),
-                ...(enumSelections.length ? { enumSelections } : {}),
-            },
+            selections,
+            ...(enumSelections.length ? { enumSelections } : {}),
         });
-    }
-    return {
-        status: 'extracted',
-        ...resolved,
-        ...(extraction === undefined ? {} : { extraction }),
-    };
+        let extraction;
+        if (options.includeExplanations === true) {
+            if (typeof parsed.reason !== 'string')
+                throw new Error('model clarification answer sources require an explanation');
+            extraction = createApiInputAnswerExtractionRecord({
+                ...snapshot,
+                decision: {
+                    reason: parsed.reason,
+                    answers: selections.map((selection) => {
+                        const source = parsed.answers.find((answer) => answer.requirementId === selection.requirementId);
+                        if (typeof source?.reason !== 'string')
+                            throw new Error(`model answer ${selection.requirementId} requires an explanation`);
+                        return { ...selection, reason: source.reason };
+                    }),
+                    ...(enumSelections.length ? { enumSelections } : {}),
+                },
+            });
+        }
+        return {
+            status: 'extracted',
+            ...resolved,
+            ...(extraction === undefined ? {} : { extraction }),
+        };
+    });
 }

package/dist/arguments/generate-api-arguments.js

@@ -1,23 +1,36 @@
 import { SystemMessage, HumanMessage } from '@langchain/core/messages';
-import { describeApiLiteralGeneration, createApiLiteralGenerationRecord, applyConfirmedApiInputs, createApiRequestSchema, inspectApiArgumentRequirements, resolveApiLiteralProposalSources, } from '@openapi-flow/core';
+import { describeApiLiteralGeneration, createApiLiteralGenerationRecord, applyConfirmedApiInputs, createApiRequestSchema, inspectApiArgumentRequirements, resolveApiLiteralProposalSources, runOpenApiFlowOperation, runOpenApiFlowAsyncOperation, } from '@openapi-flow/core';
 import { apiLiteralGenerationOptionsSchema, createApiLiteralGenerationOutputSchema, } from '../schemas/api-literal-generation-output-schema.js';
 import { apiArgumentsPrompt } from '../prompts/api-arguments-prompt.js';
 import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
 import { interpretApiArgumentEnums } from './interpret-api-argument-enums.js';
+import { invokeStructuredModel } from '../model/invoke-structured-model.js';
 export async function generateApiArguments(input) {
-    if (input.model !== undefined &&
-        (!input.model || typeof input.model.withStructuredOutput !== 'function'))
-        throw new Error('generateApiArguments.model must support structured output when supplied');
-    if (typeof input.callId !== 'string' || !input.callId.trim())
-        throw new Error('callId must be non-empty');
-    const options = apiLiteralGenerationOptionsSchema.parse({
-        includeExplanations: input.includeExplanations,
-        selectOasEnums: input.selectOasEnums,
-        trackRequestedInputs: input.trackRequestedInputs,
+    const { options, snapshot, contract, context, trackInputs, schema } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'generateApiArguments',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        if (input.model !== undefined &&
+            (!input.model ||
+                typeof input.model.withStructuredOutput !== 'function'))
+            throw new Error('generateApiArguments.model must support structured output when supplied');
+        if (typeof input.callId !== 'string' || !input.callId.trim())
+            throw new Error('callId must be non-empty');
+        const options = apiLiteralGenerationOptionsSchema.parse({
+            includeExplanations: input.includeExplanations,
+            selectOasEnums: input.selectOasEnums,
+            trackRequestedInputs: input.trackRequestedInputs,
+        });
+        const { input: snapshot, contract, context, } = describeApiLiteralGeneration(input);
+        const trackInputs = options.trackRequestedInputs === true ||
+            options.selectOasEnums === true;
+        const schema = createApiLiteralGenerationOutputSchema(contract, options.includeExplanations === true, trackInputs ? createApiRequestSchema(snapshot) : undefined);
+        if (contract.hasLiteralInputs && !input.model)
+            throw new Error('generateApiArguments.model must support structured output when literal inputs remain');
+        return { options, snapshot, contract, context, trackInputs, schema };
     });
-    const { input: snapshot, contract, context, } = describeApiLiteralGeneration(input);
-    const trackInputs = options.trackRequestedInputs === true || options.selectOasEnums === true;
-    const schema = createApiLiteralGenerationOutputSchema(contract, options.includeExplanations === true, trackInputs ? createApiRequestSchema(snapshot) : undefined);
     let proposed = {
         values: {},
         ...(trackInputs ? { requestedInputs: [], literalSources: [] } : {}),
@@ -26,78 +39,89 @@ export async function generateApiArguments(input) {
         const model = input.model;
         if (!model || typeof model.withStructuredOutput !== 'function')
             throw new Error('generateApiArguments.model must support structured output when literal inputs remain');
-        proposed = await model
-            .withStructuredOutput(schema, {
+        proposed = await invokeStructuredModel({
+            model,
+            schema,
+            operation: 'generateApiArguments',
             name: 'generate_api_arguments',
             method: 'functionCalling',
-        })
-            .invoke([
-            new SystemMessage(apiArgumentsPrompt),
-            new HumanMessage(JSON.stringify({
-                ...context,
-                ...(options.selectOasEnums === true
-                    ? { selectOasEnums: true }
-                    : {}),
-            })),
-        ]);
+            // Preserve the existing provider-default strictness of literal generation.
+            strict: undefined,
+            messages: [
+                new SystemMessage(apiArgumentsPrompt),
+                new HumanMessage(JSON.stringify({
+                    ...context,
+                    ...(options.selectOasEnums === true
+                        ? { selectOasEnums: true }
+                        : {}),
+                })),
+            ],
+        });
     }
-    const parsed = parseStructuredOutput(schema, proposed, `model arguments for ${snapshot.callId}`);
-    const values = applyConfirmedApiInputs({
-        ...snapshot,
-        values: parsed.values,
-    });
-    const requestedInputs = 'requestedInputs' in parsed ? parsed.requestedInputs : undefined;
-    const literalSources = 'literalSources' in parsed
-        ? resolveApiLiteralProposalSources({
-            callId: snapshot.callId,
+    return runOpenApiFlowAsyncOperation({
+        owner: 'langchain',
+        operation: 'generateApiArguments',
+        stage: 'contract-validation',
+        code: 'API_ARGUMENT_VALIDATION_FAILED',
+    }, async () => {
+        const parsed = parseStructuredOutput(schema, proposed, `model arguments for ${snapshot.callId}`);
+        const values = applyConfirmedApiInputs({
+            ...snapshot,
             values: parsed.values,
-            sources: parsed.literalSources.map((source) => ({
-                ...source,
-                messageId: 'scenario',
-            })),
-            messages: [{ id: 'scenario', text: snapshot.scenario }],
-        })
-        : undefined;
-    const inspection = inspectApiArgumentRequirements({
-        ...snapshot,
-        values,
-        requestedInputs,
-    });
-    const result = {
-        callId: snapshot.callId,
-        values,
-        bindings: structuredClone(snapshot.bindings),
-        unresolvedInputs: inspection.requirements.map((item) => item.targetPointer),
-        ...(literalSources === undefined ? {} : { literalSources }),
-        ...(requestedInputs === undefined ? {} : { requestedInputs }),
-        ...(snapshot.requestMediaType === undefined
-            ? {}
-            : { requestMediaType: snapshot.requestMediaType }),
-        ...(options.includeExplanations === true
-            ? {
-                literalGeneration: createApiLiteralGenerationRecord({
-                    ...snapshot,
-                    ...('explanation' in parsed
-                        ? {
-                            proposal: { values: parsed.values },
-                            reason: parsed.explanation.reason,
-                        }
-                        : {}),
-                }),
-            }
-            : {}),
-    };
-    if (options.selectOasEnums === true) {
-        if (literalSources === undefined)
-            throw new Error('generateApiArguments enum interpretation requires source-verified literalSources');
-        return interpretApiArgumentEnums({
+        });
+        const requestedInputs = 'requestedInputs' in parsed ? parsed.requestedInputs : undefined;
+        const literalSources = 'literalSources' in parsed
+            ? resolveApiLiteralProposalSources({
+                callId: snapshot.callId,
+                values: parsed.values,
+                sources: parsed.literalSources.map((source) => ({
+                    ...source,
+                    messageId: 'scenario',
+                })),
+                messages: [{ id: 'scenario', text: snapshot.scenario }],
+            })
+            : undefined;
+        const inspection = inspectApiArgumentRequirements({
             ...snapshot,
-            ...options,
-            arguments: result,
-            proposal: { values: parsed.values },
-            literalSources,
-            model: input.model,
+            values,
+            requestedInputs,
         });
-    }
-    return result;
+        const result = {
+            callId: snapshot.callId,
+            values,
+            bindings: structuredClone(snapshot.bindings),
+            unresolvedInputs: inspection.requirements.map((item) => item.targetPointer),
+            ...(literalSources === undefined ? {} : { literalSources }),
+            ...(requestedInputs === undefined ? {} : { requestedInputs }),
+            ...(snapshot.requestMediaType === undefined
+                ? {}
+                : { requestMediaType: snapshot.requestMediaType }),
+            ...(options.includeExplanations === true
+                ? {
+                    literalGeneration: createApiLiteralGenerationRecord({
+                        ...snapshot,
+                        ...('explanation' in parsed
+                            ? {
+                                proposal: { values: parsed.values },
+                                reason: parsed.explanation.reason,
+                            }
+                            : {}),
+                    }),
+                }
+                : {}),
+        };
+        if (options.selectOasEnums === true) {
+            if (literalSources === undefined)
+                throw new Error('generateApiArguments enum interpretation requires source-verified literalSources');
+            return interpretApiArgumentEnums({
+                ...snapshot,
+                ...options,
+                arguments: result,
+                proposal: { values: parsed.values },
+                literalSources,
+                model: input.model,
+            });
+        }
+        return result;
+    });
 }

package/dist/bindings/plan-api-bindings-by-call.d.ts

@@ -0,0 +1,4 @@
+import type { ApiBindingPlan } from '@openapi-flow/core';
+import type { PlanApiBindingsByCallInput } from '../types/api-call-binding-planning.js';
+/** Resource-bounded scheduling; each result can also be checkpointed by a host graph. */
+export declare function planApiBindingsByCall(input: PlanApiBindingsByCallInput): Promise<ApiBindingPlan>;

package/dist/bindings/plan-api-bindings-by-call.js

@@ -0,0 +1,77 @@
+import { describeApiBindingPlanning, validateApiCallBindingPlan, assembleApiBindingPlan, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { apiBindingCallExecutionSchema } from '../schemas/api-call-binding-plan-schema.js';
+import { selectApiBindingSources } from './select-api-binding-sources.js';
+import { planApiCallBindings } from './plan-api-call-bindings.js';
+/** Resource-bounded scheduling; each result can also be checkpointed by a host graph. */
+export async function planApiBindingsByCall(input) {
+    const { snapshot, concurrency, completed } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'planApiBindingsByCall',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        const { concurrency } = apiBindingCallExecutionSchema.parse(input);
+        if (input.onCallPlanned !== undefined &&
+            typeof input.onCallPlanned !== 'function')
+            throw new Error('onCallPlanned must be a function when supplied');
+        const snapshot = describeApiBindingPlanning(input).input;
+        const completed = input.completedCalls === undefined
+            ? []
+            : structuredClone(input.completedCalls);
+        if (!Array.isArray(completed))
+            throw new Error('completedCalls must be an array');
+        if (new Set(completed.map((item) => item.callId)).size !== completed.length)
+            throw new Error('completedCalls contains duplicate API call identities');
+        for (const result of completed)
+            validateApiCallBindingPlan({
+                ...snapshot,
+                callId: result.callId,
+                includeExplanations: input.includeExplanations,
+                result,
+            });
+        return { snapshot, concurrency, completed };
+    });
+    input.signal?.throwIfAborted();
+    const results = new Map(completed.map((result) => [result.callId, result]));
+    const pending = snapshot.materials.filter((material) => !results.has(material.callId));
+    let next = 0;
+    let failed = false;
+    let failure;
+    async function worker() {
+        while (!failed && next < pending.length) {
+            const material = pending[next++];
+            try {
+                input.signal?.throwIfAborted();
+                const callInput = {
+                    ...snapshot,
+                    callId: material.callId,
+                    includeExplanations: input.includeExplanations,
+                    model: input.model,
+                    signal: input.signal,
+                };
+                const sources = await selectApiBindingSources(callInput);
+                if (failed)
+                    return;
+                const result = await planApiCallBindings({ ...callInput, sources });
+                input.signal?.throwIfAborted();
+                if (input.onCallPlanned !== undefined)
+                    await input.onCallPlanned(structuredClone(result));
+                results.set(result.callId, result);
+            }
+            catch (error) {
+                if (!failed)
+                    failure = error;
+                failed = true;
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, () => worker()));
+    if (failed)
+        throw failure;
+    input.signal?.throwIfAborted();
+    return assembleApiBindingPlan({
+        ...snapshot,
+        results: [...results.values()],
+        includeExplanations: input.includeExplanations,
+    });
+}

package/dist/bindings/plan-api-bindings.js

@@ -26,6 +26,7 @@ export async function planApiBindings(input) {
         operation: 'planApiBindings',
         name: 'plan_api_bindings',
         method: 'functionCalling',
+        strict: true,
         messages: [
             new SystemMessage(apiBindingsPrompt),
             new HumanMessage(JSON.stringify(context)),

package/dist/bindings/plan-api-call-bindings.d.ts

@@ -0,0 +1,3 @@
+import type { ApiCallBindingPlan } from '@openapi-flow/core';
+import type { PlanApiCallBindingsInput } from '../types/api-call-binding-planning.js';
+export declare function planApiCallBindings(input: PlanApiCallBindingsInput): Promise<ApiCallBindingPlan>;

package/dist/bindings/plan-api-call-bindings.js

@@ -0,0 +1,82 @@
+import { isDeepStrictEqual } from 'node:util';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { describeApiCallBindingPlanning, resolveApiBindingSourceSelection, resolveApiCallBindingPlan, listApiResponsePointers, runOpenApiFlowOperation, } from '@openapi-flow/core';
+import { createApiCallBindingPlanSchema } from '../schemas/api-call-binding-plan-schema.js';
+import { apiCallBindingsPrompt } from '../prompts/api-call-bindings-prompt.js';
+import { invokeStructuredModel } from '../model/invoke-structured-model.js';
+import { parseStructuredOutput } from '../legacy/planning/parse-structured-output.js';
+export async function planApiCallBindings(input) {
+    const { description, sources } = runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'planApiCallBindings',
+        stage: 'input-validation',
+        code: 'PLANNING_INPUT_INVALID',
+    }, () => {
+        const description = describeApiCallBindingPlanning(input);
+        const sources = structuredClone(input.sources);
+        const expected = resolveApiBindingSourceSelection({
+            ...description.input,
+            proposal: {
+                sourceNodeIds: sources.sourceNodeIds,
+                gaps: sources.gaps,
+                ...(sources.reason === undefined ? {} : { reason: sources.reason }),
+            },
+        });
+        if (!isDeepStrictEqual(sources, expected))
+            throw new Error('binding source selection changed or belongs to another call or source snapshot');
+        return { description, sources };
+    });
+    input.signal?.throwIfAborted();
+    if (!sources.sourceNodeIds.length)
+        return resolveApiCallBindingPlan({
+            ...description.input,
+            sources,
+            proposal: {
+                bindings: [],
+                gaps: [],
+                ...(sources.reason === undefined ? {} : { reason: sources.reason }),
+            },
+        });
+    const selected = new Set(sources.sourceNodeIds);
+    const schema = createApiCallBindingPlanSchema(description, sources.sourceNodeIds);
+    const output = await invokeStructuredModel({
+        model: input.model,
+        schema,
+        operation: 'planApiCallBindings',
+        name: 'plan_api_call_bindings',
+        method: 'functionCalling',
+        strict: true,
+        signal: input.signal,
+        messages: [
+            new SystemMessage(apiCallBindingsPrompt),
+            new HumanMessage(JSON.stringify({
+                scenario: description.input.scenario,
+                target: description.target,
+                requestSchema: description.requestSchema,
+                apiSources: description.input.materials
+                    .filter((material) => selected.has(material.callId))
+                    .map((material) => ({
+                    nodeId: material.callId,
+                    key: material.operation.key,
+                    method: material.operation.method,
+                    path: material.operation.path,
+                    purpose: material.purpose,
+                    responses: material.operation.operation.responses,
+                    responsePointerCatalog: listApiResponsePointers(material.operation),
+                })),
+                nativeSources: description.input.nativeOutputs?.filter((source) => selected.has(source.nodeId)),
+            })),
+        ],
+    });
+    input.signal?.throwIfAborted();
+    return runOpenApiFlowOperation({
+        owner: 'langchain',
+        operation: 'planApiCallBindings',
+        stage: 'contract-validation',
+        code: 'API_BINDING_VALIDATION_FAILED',
+    }, () => resolveApiCallBindingPlan({
+        ...description.input,
+        sources,
+        proposal: parseStructuredOutput(schema, output, 'API call bindings'),
+    }));
+}

package/dist/bindings/select-api-binding-sources.d.ts

@@ -0,0 +1,3 @@
+import type { ApiBindingSourceSelection } from '@openapi-flow/core';
+import type { SelectApiBindingSourcesInput } from '../types/api-call-binding-planning.js';
+export declare function selectApiBindingSources(input: SelectApiBindingSourcesInput): Promise<ApiBindingSourceSelection>;