BPOS-MVP/api-report/apps/api/src/modules/llm/contract.d.ts

/**
 * module: llm —— 对外类型(编码规范 §10.1)。
 *
 * 两条缝之一(§7.3):`ModelGateway` 支持 record | replay | live 三模式 ——
 * **任何模型调用不经 ModelGateway,回放审就对它失明**(§12.5#10)。
 */
import type { LlmInstanceView, LlmProvider, TaskId } from '@contracts';
import type { ModelBinding, BindingViolation } from './internal/domain/model-binding.ts';
export type { LlmInstanceView, LlmProvider, ModelBinding, BindingViolation };
/** 一条缝的三个开关位 */
export declare const GATEWAY_MODES: readonly ["live", "record", "replay"];
export type GatewayMode = (typeof GATEWAY_MODES)[number];
export declare class ModelNotBoundError extends Error {
    readonly modelName: string;
    readonly violations: readonly BindingViolation[];
    constructor(modelName: string, violations: readonly BindingViolation[]);
}
export declare class ModelDisabledError extends Error {
    readonly modelName: string;
    constructor(modelName: string);
}
export declare class ReplayMissError extends Error {
    readonly key: string;
    constructor(key: string);
}
/** 模型调用的语义入参 —— 录制的就是它,不含任何凭证(ADR-009 #5) */
export type ModelCall = {
    /** 活动声明的自定义模型名(逻辑名) */
    readonly model: string;
    readonly system?: string;
    readonly prompt: string;
    readonly temperature?: number;
    readonly maxOutputTokens?: number;
    /**
     * 压推理:`off` 不许想、`low` 少想;缺省由着模型。
     * 只对画像里声明了 `reasoningControl` 的厂家生效 —— 没姿势的厂家如实忽略。
     * 规划型调用(loop 单拍)该关:隐藏思考按秒计,而它的判断本就交给了判定表与工具。
     */
    readonly reasoning?: 'off' | 'low';
    /** 出参 schema(JSON Schema);给定即要求结构化出参并校验 */
    readonly outputSchema?: Record<string, unknown>;
    /** 录制/回放的定位:任务 × 步序号(§7.3) */
    readonly taskId?: TaskId;
    readonly stepNo?: number;
    /** 归因用:调用点标签(flow 步名 / loop 回合 / 系统用途) */
    readonly label?: string;
};
export type ModelUsage = {
    readonly inputTokens: number;
    readonly outputTokens: number;
    readonly latencyMs: number;
};
export type ModelResult = {
    readonly text: string;
    /** outputSchema 给定时的解析结果 */
    readonly object?: unknown;
    readonly usage: ModelUsage;
    /**
     * 推理模型的思考正文 —— **过程,不是结论**。
     * 出参只认 `text` / `object`;这一段单独留着,供任务记忆归档与断点复盘,
     * 不参与 schema 校验、不进业务字段。
     */
    readonly reasoning?: string;
    /** 行为可归因:模型与版本记入留痕(OS 4.1) */
    readonly binding: {
        readonly name: string;
        readonly provider: LlmProvider;
        readonly model: string;
    };
    readonly mode: GatewayMode;
};
/** 解好的模型端点(四元 + 明文密钥)—— app 层装配专用,见 ModelGateway.resolve */
export type ResolvedEndpoint = {
    readonly provider: LlmProvider;
    readonly baseUrl: string;
    readonly model: string;
    readonly apiKey: string;
};
/**
 * 模型网关 —— 活动基座六件里的「LLM 调用」。
 * 活动只见自定义模型名;解析、凭证、录制回放全在此。
 */
export type ModelGateway = {
    readonly mode: GatewayMode;
    /**
     * 解绑定:名 → 四元(含当场解出的密钥)—— **只给 app 层装配用**:
     * Mastra Agent 那类需要真模型对象做 tool-calling 往返的场合,
     * `generate` 的 text-in/text-out 抽象承载不了。
     * 密钥与 endpoint 仍不入 domain、不入包、不入留痕明文(OS 7.3 凭证隔离)。
     */
    resolve(modelName: string): Promise<ResolvedEndpoint>;
    generate(call: ModelCall): Promise<ModelResult>;
    /** 换模式的网关 —— 回放审用 replay 模式重跑引擎(§7.3) */
    withMode(mode: GatewayMode): ModelGateway;
};
export type UpsertLlmInstance = {
    readonly id?: string | undefined;
    readonly name: string;
    readonly provider: LlmProvider;
    /** 留空 = 取该 provider 的默认端点 */
    readonly baseUrl: string;
    readonly model: string;
    /** 只写不读:留空表示保持原值 */
    readonly apiKey?: string | undefined;
    readonly systemUse: boolean;
    readonly enabled: boolean;
};
export type LlmService = {
    list(): Promise<LlmInstanceView[]>;
    upsert(input: UpsertLlmInstance): Promise<LlmInstanceView>;
    remove(id: string): Promise<void>;
    /** 连通性探针 —— 治理台「测试连接」 */
    probe(id: string): Promise<{
        ok: boolean;
        latencyMs?: number;
        error?: string;
    }>;
    /**
     * 草稿探针 —— **只测不存**:拿表单上正填的四元去试,一个字节都不落库。
     * 密钥现填就用现填的,留空则取该实例已存的密文(改端点不必重打钥匙)。
     */
    probeDraft(draft: {
        id?: string | undefined;
        name?: string | undefined;
        provider: LlmProvider;
        baseUrl: string;
        model: string;
        apiKey?: string | undefined;
    }): Promise<{
        ok: boolean;
        latencyMs?: number;
        error?: string;
    }>;
    /** 安装静态审:核对活动声明的模型名已绑定(AM 11.3) */
    assertNamesBound(names: readonly string[]): Promise<{
        ok: boolean;
        missing: string[];
    }>;
    /** 系统用途模型 —— 叙述性小结 / 汇报生成 / 蒸馏钩子 */
    systemUseBinding(): Promise<ModelBinding | undefined>;
};