ModelCalls

KIT · class · 运行时值

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.

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core/types、@jangts/agent-core/kits、@jangts/agent-core/kits/inference。

定义

class ModelCalls<Input, Output, Bindings>

泛型参数

类型参数	约束	默认类型
Input	—	unknown
Output	—	unknown
Bindings	readonly ModelBinding<any, any>[]	readonly ModelBinding<Input, Output>[]

构造函数

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

参数	类型	传递	说明
bindings	Bindings	必需	—

返回： ModelCalls<Input, Output, Bindings>。

实例属性

字段	类型	必需	说明
definitions	readonly Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>[]	必需	只读。Registered bindings in declaration order, with methods already bound to their owner.

成员目录

成员	用途
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.

成员详情

ids

实例方法。

Registered binding ids in declaration order.

ids(): readonly string[]

Registered binding ids in declaration order.

无调用参数。

返回： readonly string[]。

has

实例方法。

Whether a binding id is registered.

has(id: string): boolean

Whether a binding id is registered.

参数	类型	传递	说明
id	string	必需	—

返回： boolean。

get

实例方法。

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.

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["id"]	必需	只读。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"]	必需	只读。Non-blank implementation identity (provider plus model name) reported in diagnostics.
invoke	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["invoke"]	必需	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 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 synchronous assertion run after the call, before the result is reported.

require

实例方法。

Registered binding for id.

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

Registered binding for id.

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>。

返回值结构

字段	类型	必需	说明
id	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["id"]	必需	只读。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"]	必需	只读。Non-blank implementation identity (provider plus model name) reported in diagnostics.
invoke	Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>["invoke"]	必需	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 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 synchronous assertion run after the call, before the result is reported.

values

实例方法。

Iterate the registered bindings.

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

Iterate the registered bindings.

无调用参数。

返回： IterableIterator<Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>>。

entries

实例方法。

Iterate [id, binding] pairs.

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

Iterate [id, binding] pairs.

无调用参数。

返回： IterableIterator<[string, Readonly<Pick<Bindings[number], Extract<keyof Bindings[number], keyof ModelBinding<any, any>>>>]>。

identity

实例方法。

Implementation identity of one binding.

identity(id: string): string

Implementation identity of one binding.

参数	类型	传递	说明
id	string	必需	—

返回： string。

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.

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.

类型参数	约束	默认类型
Id	string	—

参数	类型	传递	说明
request	ModelInvocationRequest<InputFor<Bindings, Id>> & { readonly modelId: Id; }	必需	—
context	ModelInvocationContext	必需	—

request 的字段

字段	类型	必需	说明
modelId	Id	必需	只读。Registered binding id; unknown ids fail before any provider work happens.
input	InputFor<Bindings, Id>	必需	只读。Input handed to the binding unchanged; Core never clones App objects here.
timeoutMs	number	必需	只读。Per-call timeout in milliseconds, 1..2147483647 (the platform timer ceiling).

context 的字段

字段	类型	必需	说明
attemptBudget	Pick<AttemptBudget, "take"> | undefined	可省略	只读。Shared attempt budget; a refusal fails the call with BudgetError before invoking.
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

返回： Promise<ModelResult<OutputFor<Bindings, Id>>>。

等待后的值： ModelResult<OutputFor<Bindings, Id>>。

返回值结构

字段	类型	必需	说明
value	OutputFor<Bindings, Id>	必需	只读。见类型定义及调用场景。
invocation	Readonly<ModelCallRecord>	必需	只读。见类型定义及调用场景。

使用示例

• ModelCalls：外部推理绑定：为 embedding 等 App 自定义 I/O 绑定身份、校验、取消与统一调用回执。

先绑定一个离线演示向量算法

入门 · Node.js

算法只演示 I/O 绑定，不提供真实语言向量质量。

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);

在同一 invoke 上增加输入输出检查和取消

配置 · 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);

相关策略源码

• 绑定、校验、期限与真实回执

相关定义

• ModelBinding
• ModelCallRecord
• ModelInvocationContext
• ModelInvocationRequest
• ModelResult