ModelCalls

KIT · class · Runtime value

Frozen catalog of model bindings plus a checked invocation entry point.

Registration happens once in the constructor; the catalog is never mutated afterwards, so a caller cannot swap a provider in the middle of a run.

Import

TypeScript

import { ModelCalls } from '@jangts/agent-core/kits/inference';

JavaScript

import { ModelCalls } from '@jangts/agent-core/kits/inference';

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/kits, @jangts/agent-core/kits/inference.

Definition

class ModelCalls<Input, Output, Bindings>

Type parameters

Type parameter	Constraint	Default type
Input	—	unknown
Output	—	unknown
Bindings	readonly ModelBinding<any, any>[]	readonly ModelBinding<Input, Output>[]

Constructor

new ModelCalls<Input = unknown, Output = unknown, const Bindings extends readonly ModelBinding<any, any>[] = readonly ModelBinding<Input, Output>[]>(bindings: Bindings): ModelCalls<Input, Output, Bindings>

Parameter	Type	Passing	Description
bindings	Bindings	Required	—

Returns: ModelCalls<Input, Output, Bindings>.

Instance properties

Field	Type	Required	Description
definitions	readonly Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>[]	Required	Read-only. Registered bindings in declaration order, with methods already bound to their owner.

Member index

Member	Purpose
ids	Registered binding ids in declaration order.
has	Whether a binding id is registered.
get	Registered binding for id, or undefined when it is absent.
require	Registered binding for id.
values	Iterate the registered bindings.
entries	Iterate [id, binding] pairs.
identity	Implementation identity of one binding.
invoke	Invoke one registered binding under the caller's signal, timeout and attempt budget. Order matters: the binding id is resolved, input is asserted, the budget take happens before the provider call, and the output assertion runs before a result is reported. Any failure emits a diagnostic and rethrows unchanged, so callers see the provider's own error.

Member details

ids

Instance method.

Registered binding ids in declaration order.

ids(): readonly string[]

Registered binding ids in declaration order.

No call parameters.

Returns: readonly string[].

has

Instance method.

Whether a binding id is registered.

has(id: string): boolean

Whether a binding id is registered.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

get

Instance method.

Registered binding for id, or undefined when it is absent.

get(id: string): RegisteredBinding<Bindings[number]> | undefined

Registered binding for id, or undefined when it is absent.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["id"]	Required	Read-only. Catalog key used in requests; must be unique within one ModelCalls instance.
identity	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["identity"]	Required	Read-only. Non-blank implementation identity (provider plus model name) reported in diagnostics.
invoke	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["invoke"]	Required	Performs the provider call. May be async; the Kit applies the caller's signal.
assertInput	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["assertInput"] | undefined	Optional	Optional synchronous assertion run before the budget is consumed or the call starts.
assertOutput	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["assertOutput"] | undefined	Optional	Optional synchronous assertion run after the call, before the result is reported.

require

Instance method.

Registered binding for id.

require(id: string): RegisteredBinding<Bindings[number]>

Registered binding for id.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>.

Return value structure

Field	Type	Required	Description
id	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["id"]	Required	Read-only. Catalog key used in requests; must be unique within one ModelCalls instance.
identity	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["identity"]	Required	Read-only. Non-blank implementation identity (provider plus model name) reported in diagnostics.
invoke	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["invoke"]	Required	Performs the provider call. May be async; the Kit applies the caller's signal.
assertInput	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["assertInput"] | undefined	Optional	Optional synchronous assertion run before the budget is consumed or the call starts.
assertOutput	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["assertOutput"] | undefined	Optional	Optional synchronous assertion run after the call, before the result is reported.

values

Instance method.

Iterate the registered bindings.

values(): IterableIterator<RegisteredBinding<Bindings[number]>>

Iterate the registered bindings.

No call parameters.

Returns: IterableIterator<Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>>.

entries

Instance method.

Iterate [id, binding] pairs.

entries(): IterableIterator<[string, RegisteredBinding<Bindings[number]>]>

Iterate [id, binding] pairs.

No call parameters.

Returns: IterableIterator<[string, Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>]>.

identity

Instance method.

Implementation identity of one binding.

identity(id: string): string

Implementation identity of one binding.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: string.

invoke

Instance method.

Invoke one registered binding under the caller's signal, timeout and attempt budget.

Order matters: the binding id is resolved, input is asserted, the budget take happens before the provider call, and the output assertion runs before a result is reported. Any failure emits a diagnostic and rethrows unchanged, so callers see the provider's own error.

invoke<const Id extends string>(request: ModelInvocationRequest<InputFor<Bindings, Id>> & { readonly modelId: Id; }, context: ModelInvocationContext): Promise<ModelResult<OutputFor<Bindings, Id>>>

Invoke one registered binding under the caller's signal, timeout and attempt budget.

Order matters: the binding id is resolved, input is asserted, the budget take happens before the provider call, and the output assertion runs before a result is reported. Any failure emits a diagnostic and rethrows unchanged, so callers see the provider's own error.

Type parameter	Constraint	Default type
Id	string	—

Parameter	Type	Passing	Description
request	ModelInvocationRequest<InputFor<Bindings, Id>> & { readonly modelId: Id; }	Required	—
context	ModelInvocationContext	Required	—

Fields of request

Field	Type	Required	Description
modelId	Id	Required	Read-only. Registered binding id; unknown ids fail before any provider work happens.
input	InputFor<Bindings, Id>	Required	Read-only. Input handed to the binding unchanged; Core never clones App objects here.
timeoutMs	number	Required	Read-only. Per-call timeout in milliseconds, 1..2147483647 (the platform timer ceiling).

Fields of context

Field	Type	Required	Description
attemptBudget	Pick<AttemptBudget, "take"> | undefined	Optional	Read-only. Shared attempt budget; a refusal fails the call with BudgetError before invoking.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: Promise<ModelResult<OutputFor<Bindings, Id>>>.

Awaited value: ModelResult<OutputFor<Bindings, Id>>.

Return value structure

Field	Type	Required	Description
value	OutputFor<Bindings, Id>	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ModelCallRecord>	Required	Read-only. See the type definition and usage context.

Examples

• ModelCalls: external inference bindings: Bind identity, validation, cancellation, and a unified invocation receipt for App-defined I/O such as embeddings.

First bind an offline demonstration vector algorithm

Beginner · Node.js

The algorithm only demonstrates I/O binding and does not provide real language embedding quality.

TypeScript

import { ModelCalls } from '@jangts/agent-core/kits/inference';
const models = new ModelCalls([
  { id: 'demo-vector', identity: 'length-direction-v1', invoke: (text: string) => [text.length, 1] },
] as const);
const result = await models.invoke({ modelId: 'demo-vector', input: 'Agent Core', timeoutMs: 1000 }, { signal: new AbortController().signal });
console.log(result.value, result.invocation.modelId);

JavaScript

import { ModelCalls } from '@jangts/agent-core/kits/inference';
const models = new ModelCalls([
    { id: 'demo-vector', identity: 'length-direction-v1', invoke: (text) => [text.length, 1] },
]);
const result = await models.invoke({ modelId: 'demo-vector', input: 'Agent Core', timeoutMs: 1000 }, { signal: new AbortController().signal });
console.log(result.value, result.invocation.modelId);

Add input and output checks plus cancellation to the same invoke

Configuration · Node.js

TypeScript

import { ModelCalls } from '@jangts/agent-core/kits/inference';
const models = new ModelCalls([
  { id: 'demo-vector', identity: 'length-direction-v1',
    assertInput(text: string) { if (!text.trim()) throw new Error('文本为空'); },
    invoke(text: string, context) { context.signal.throwIfAborted(); return [text.length, 1]; },
    assertOutput(vector: number[]) { if (vector.length !== 2 || vector.some(value => !Number.isFinite(value))) throw new Error('向量无效'); },
  },
] as const);
const controller = new AbortController();
const result = await models.invoke({ modelId: 'demo-vector', input: 'Agent Core', timeoutMs: 1000 }, { signal: controller.signal });
console.log(models.identity('demo-vector'), result.value);

JavaScript

import { ModelCalls } from '@jangts/agent-core/kits/inference';
const models = new ModelCalls([
    { id: 'demo-vector', identity: 'length-direction-v1',
        assertInput(text) { if (!text.trim())
            throw new Error('文本为空'); },
        invoke(text, context) { context.signal.throwIfAborted(); return [text.length, 1]; },
        assertOutput(vector) { if (vector.length !== 2 || vector.some(value => !Number.isFinite(value)))
            throw new Error('向量无效'); },
    },
]);
const controller = new AbortController();
const result = await models.invoke({ modelId: 'demo-vector', input: 'Agent Core', timeoutMs: 1000 }, { signal: controller.signal });
console.log(models.identity('demo-vector'), result.value);

Related policy source

• Bindings, validation, deadlines, and real receipts

Related definitions

• ModelBinding
• ModelCallRecord
• ModelInvocationContext
• ModelInvocationRequest
• ModelResult