README
U
Prism
U
PrismEvent
U
PrismFinishReason
U
PrismOptions
U
PrismThinking
U
PrismToolCall
U
PrismToolResult

#src/sdk — SDK 组合根（导航索引）

MoonBit 目录 = 包：本目录是一个包，不能再建子文件夹（子文件夹 = 子包，会破坏 inherent methods 与包环约束，见 docs/report/sdk-split-feasibility.md）。包内组织靠功能组分区注释 + 本导航文件。

#功能组文件地图

#1. facade（对外入口，先读这里）

文件	内容
prism.mbt	Prism 门面类型 + PrismOptions/ConversionMeta/DecodedResponse + SdkProviderEndpoint
context.mbt	Context/SdkMessage/SdkTool 构建 + context_to_lux_request

#2. registry+match（注册与路由）

文件	内容
registry.mbt	ProviderRegistration 定义 + providers_cache + 动态注册表（register/unregister/with_overrides，T6）
match.mbt	路由匹配（match_provider_name / match_by_model）——唯一路由入口（静态表优先，动态表兜底）

#3. pipeline（编码解码编排）

文件	内容
pipeline.mbt	Prism 门面内部方法（encode/decode 样板，从自身 provider 出发）
codec_pipeline.mbt	通用 decode→IR→encode 管线（任意 source→target，无状态）

#4. convert（跨协议中转）

文件	内容
convert.mbt	convert_request/response/stream 组合入口（场景 2）+ StreamConverter 增量会话（T5）+ 类型化入口（T7）

#5. hooks（IR 策略层，T4）

文件	内容
hooks.mbt	SdkRequestHook/SdkResponseHook/SdkStreamHook + convert_*_with_hooks + 内置钩子

#6. snapshot（会话快照，T8）

文件	内容
snapshot.mbt	ConversationStore + restore_request_from_snapshot + convert_request_with_store

#7. error + diagnostics（类型化错误与诊断运维，T7/T10）

文件	内容
error.mbt	PrismError（LucentErrorKind 上翻）+ 保守分类器 + is_retryable
diagnostics.mbt	DiagnosticPolicy + enforce_policy + DiagnosticCollector

#8. schema+event（元数据，零内部依赖）

文件	内容
schema.mbt	ProviderSchema/FieldConstraint
event.mbt	PrismToolCall/PrismToolResult/PrismThinking

#9. 测试

*_wbtest.mbt：白盒测试（留包内，MoonBit 约束）
test/：黑盒测试子包（cross_protocol / convert_matrix / sdk_test / context_toolcall / events_to_context / options_ext / hooks / stream_converter / snapshot_store / error_typed / diagnostics_policy 等）

#依赖方向（禁止反向）

facade (prism/context) ──► match ◄── pipeline
                              │
                         registry（providers_cache + dynamic_providers）
                              ▲
                         convert ◄─► codec_pipeline
                              ▲
        hooks / snapshot / error / diagnostics（只消费 IR 与注册表；
        禁止反向依赖 provider——单向依赖图护栏）

match.mbt 是唯一读取注册表的文件
schema.mbt / event.mbt 零内部依赖（只定义数据）
禁止 registry/match 反向引用 facade/convert
T5 起 sdk 直接依赖 internal（SseFrameSplitter；internal 是叶子包，不成环）

#约定

新增门面 API → prism.mbt；新增状态构建 → context.mbt
新增路由逻辑 → match.mbt；新增跨协议组合 → convert.mbt + codec_pipeline.mbt
遵循 docs/rules/naming-conventions.md

SdkRequestHook

source

type SdkRequestHook = (@morning-start/prism/lux.LucentRequest
LucentRequest, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentRequest
LucentRequest

SdkRequestHook — 请求 IR 钩子

入参：(IR, 诊断收集器)；返回变换后的 IR。钩子可向收集器 push ConversionDiagnostic，最终与 decode/encode 两阶段诊断合并返回。

SdkResponseHook

source

type SdkResponseHook = (@morning-start/prism/lux.LucentResponse
LucentResponse, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentResponse
LucentResponse

SdkResponseHook — 响应 IR 钩子（同上）

SdkStreamHook

source

type SdkStreamHook = (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent], Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]

SdkStreamHook — 流事件 IR 钩子（事件数组整体变换）

Context

source

pub struct Context {
  system_prompt : String?
  messages : Array[SdkMessage]
  tools : Array[SdkTool]?
}

Context — 对话上下文

Context::add_assistant

source

fn Context::add_assistant(self : Context, text : String) -> Context

添加助手消息

Context::add_assistant_turn

source

fn Context::add_assistant_turn(self : Context, text : String, tool_calls : Array[SdkToolCall]) -> Context

回填整个 assistant 回合（文本 + 任意数量工具调用合并为一条消息）

Agent 循环回填闭环用：Prism::events_to_context 内部调用。

Context::add_system

source

fn Context::add_system(self : Context, prompt : String) -> Context

设置系统指令

Context::add_tool_call

source

fn Context::add_tool_call(self : Context, id : String, name : String, arguments_json : String, content : String) -> Context

回填 assistant 工具调用回合（Agent 循环：模型要求调用工具后、注入 tool_result 之前，必须先补这一回合，否则第二轮请求会被 provider 拒绝——tool_result 必须紧跟含 tool_use 的 assistant 消息）

Context::add_tool_result

source

fn Context::add_tool_result(self : Context, tool_use_id : String, content : String, is_error : Bool) -> Context

注入工具执行结果（Agent 循环：执行工具后继续对话）

Context::add_tools

source

fn Context::add_tools(self : Context, tools : Array[SdkTool]) -> Context

添加工具

Context::add_user

source

fn Context::add_user(self : Context, text : String) -> Context

添加用户消息

Context::new

source

fn Context::new() -> Context

ConversationStore

source

pub struct ConversationStore {
  get : (String) -> @morning-start/prism/lux.ConversationSnapshot
ConversationSnapshot?
  put : (@morning-start/prism/lux.ConversationSnapshot
ConversationSnapshot) -> Unit
}

ConversationStore — 宿主注入的会话快照存储

get：按 response_id 取快照（无则 None） put：存快照（同 id 覆盖）

ConversationStore::new

source

fn ConversationStore::new(get : (String) -> @morning-start/prism/lux.ConversationSnapshot
ConversationSnapshot?, put : (@morning-start/prism/lux.ConversationSnapshot
ConversationSnapshot) -> Unit) -> ConversationStore

ConversionMeta

source

pub struct ConversionMeta {
  source_provider : String
  diagnostics : Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]
  provider_payload : Json?
  extra_fields : Map[String, Json]?
}

ConversionMeta — 转换来源元信息（D8）

回答"这个 LUX 值是从哪个协议解码来的"，并附带转换损失诊断与厂商特有字段（provider_payload / extra_fields）。开发者可用 source_provider 做按需特判（if 分支），主路径代码仍只写一次。

ConversionMeta::new

source

fn ConversionMeta::new(source_provider : String, diagnostics : Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic], provider_payload : Json?, extra_fields : Map[String, Json]?) -> ConversionMeta

ConvertMetaResult

source

pub struct ConvertMetaResult {
  value : String
  meta : ConversionMeta
}

ConvertMetaResult — convert 结果：目标协议 JSON + 来源元信息（D8）

ConvertMetaResult::meta

source

fn ConvertMetaResult::meta(self : ConvertMetaResult) -> ConversionMeta

ConvertMetaResult::new

source

fn ConvertMetaResult::new(value : String, meta : ConversionMeta) -> ConvertMetaResult

ConvertMetaResult::value

source

fn ConvertMetaResult::value(self : ConvertMetaResult) -> String

DecodedResponse

source

pub struct DecodedResponse {
  text : String
  meta : ConversionMeta
}

DecodedResponse — 解码结果：主路径文本 + 溯源元信息

DecodedResponse::new

source

fn DecodedResponse::new(text : String, meta : ConversionMeta) -> DecodedResponse

DiagnosticCollector

source

pub struct DiagnosticCollector {
  all : Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]
}

DiagnosticCollector — 诊断聚合器（T10）

中间件运维视图：跨请求累积诊断，按 status/field 计数，取最重诊断，输出人类可读 summary。典型用法：

let collector = DiagnosticCollector::new()
collector.add_all(result.diagnostics())
// 周期性：
log(collector.summary())
collector.reset()

DiagnosticCollector::add_all

source

fn DiagnosticCollector::add_all(self : DiagnosticCollector, diagnostics : Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> Unit

追加一组诊断（如 ConversionResult.diagnostics()）

DiagnosticCollector::count_by_field

source

fn DiagnosticCollector::count_by_field(self : DiagnosticCollector, field : String) -> Int

按 field 计数（运维定位热点字段，如 options.previous_response_id）

DiagnosticCollector::count_by_status

source

fn DiagnosticCollector::count_by_status(self : DiagnosticCollector) -> DiagnosticCounts

按 status 计数

DiagnosticCollector::diagnostics

source

fn DiagnosticCollector::diagnostics(self : DiagnosticCollector) -> Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]

取全部诊断（上报/导出用）

DiagnosticCollector::enforce

source

fn DiagnosticCollector::enforce(self : DiagnosticCollector, policy : DiagnosticPolicy) -> Result[Unit, String]

对收集的诊断执行策略（周期巡检/熔断判定用）

DiagnosticCollector::new

source

fn DiagnosticCollector::new() -> DiagnosticCollector

DiagnosticCollector::push

source

fn DiagnosticCollector::push(self : DiagnosticCollector, diagnostic : @morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic) -> Unit

追加单条诊断

DiagnosticCollector::reset

source

fn DiagnosticCollector::reset(self : DiagnosticCollector) -> Unit

清空（周期快照后重置）

DiagnosticCollector::summary

source

fn DiagnosticCollector::summary(self : DiagnosticCollector) -> String

人类可读摘要（日志/监控用）

DiagnosticCollector::total

source

fn DiagnosticCollector::total(self : DiagnosticCollector) -> Int

诊断总数

DiagnosticCollector::worst_status

source

fn DiagnosticCollector::worst_status(self : DiagnosticCollector) -> @morning-start/prism/lux.ConversionStatus
ConversionStatus?

最重诊断的 status（空收集器返回 None）

DiagnosticCounts

source

pub struct DiagnosticCounts {
  exact : Int
  degraded : Int
  unsupported : Int
  invalid : Int
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

DiagnosticCounts — 按 status 的计数（ConversionStatus 无 Hash 实现，用专用结构体而非 Map；运维直接读字段）

DiagnosticCounts::default

source

fn DiagnosticCounts::default() -> DiagnosticCounts

DiagnosticCounts::equal

source

fn DiagnosticCounts::equal(DiagnosticCounts, DiagnosticCounts) -> Bool

explicit: Eq::equal kept as a regular method (implicit promotion is deprecated, E0079)

DiagnosticCounts::total

source

fn DiagnosticCounts::total(self : DiagnosticCounts) -> Int

计数总数

DiagnosticPolicy

source

pub(all) enum DiagnosticPolicy {
  ReportOnly
  FailOnUnsupported
  FailOnDegraded
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

DiagnosticPolicy — 诊断处置策略

DiagnosticPolicy::equal

source

fn DiagnosticPolicy::equal(DiagnosticPolicy, DiagnosticPolicy) -> Bool

explicit: Eq::equal kept as a regular method (implicit promotion is deprecated, E0079)

FieldConstraint

source

pub struct FieldConstraint {
  min_val : Double?
  max_val : Double?
  required : Bool
  allowed_values : Array[String]?
}

FieldConstraint — 单字段约束

FieldConstraint::new

source

fn FieldConstraint::new(min_val : Double?, max_val : Double?, required : Bool, allowed_values : Array[String]?) -> FieldConstraint

Prism

source

pub struct Prism {
  provider : String
}

Prism — 主实例

Prism::capability

source

fn Prism::capability(_self : Prism, provider_name : String) -> @morning-start/prism/lux.ProviderCapability
ProviderCapability?

查询指定 provider 的能力声明（基于注册表）

Prism::check_capability

source

fn Prism::check_capability(self : Prism, req : @morning-start/prism/lux.LucentRequest
LucentRequest) -> Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]

能力校验（capability 消费落地，iteration-008 架构审计方向 A）

将请求所需能力与 provider 的 ProviderCapability 声明对照，声明为 Absent 的能力若请求实际使用，产生 Unsupported 诊断—— 让能力声明从"死数据"变为运行时契约（呼应 AGENTS.md "Unsupported capabilities MUST fail explicitly"）。

检查项：

请求含 tools 但声明 tool_calling=Absent → Unsupported
请求启用 reasoning 但声明 reasoning=Absent → Unsupported
请求含 structured_output 但声明 structured_output=Absent → Unsupported

空数组表示请求能力全部被支持。

Prism::complete

source

fn Prism::complete(self : Prism, text : String, opts : PrismOptions, send : (String) -> Result[String, String]) -> Result[String, String]

L1 零配置：文本进、文本出（HTTP 由 Host 注入 send）

Prism::decode_response

source

fn Prism::decode_response(self : Prism, json_str : String) -> Result[String, String]

将提供商 JSON 响应解码为纯文本（L1：JSON 进，文本出）

Prism::decode_response_typed

source

fn Prism::decode_response_typed(self : Prism, json_str : String) -> Result[DecodedResponse, PrismError]

响应解码为 DecodedResponse（类型化错误版）

Prism::decode_response_with_diagnostics

source

fn Prism::decode_response_with_diagnostics(self : Prism, json_str : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentResponse
LucentResponse], String]

将提供商响应解码为完整 LucentResponse，并返回结构化校验诊断。

Prism::decode_response_with_meta

source

fn Prism::decode_response_with_meta(self : Prism, json_str : String) -> Result[DecodedResponse, String]

将提供商 JSON 响应解码为 DecodedResponse（文本 + 来源元信息）。

meta.source_provider 为运行时从注册表解析的规范 provider 名（精确匹配/别名/模型正则），开发者可据此做按需特判。

Prism::decode_sse

source

fn Prism::decode_sse(self : Prism, sse_str : String) -> Result[Array[PrismEvent], String]

将提供商 SSE 事件解码为 PrismEvent 数组

Prism::decode_sse_typed

source

fn Prism::decode_sse_typed(self : Prism, sse_str : String) -> Result[Array[PrismEvent], PrismError]

SSE 解码为事件数组（类型化错误版）

Prism::encode_request

source

fn Prism::encode_request(self : Prism, text : String, opts : PrismOptions) -> Result[String, String]

将文本请求编码为提供商 JSON（L1：文本进，JSON 出）

Prism::encode_request_typed

source

fn Prism::encode_request_typed(self : Prism, text : String, opts : PrismOptions) -> Result[String, PrismError]

文本请求编码（类型化错误版；成功路径与 encode_request 一致）

Prism::encode_request_with_diagnostics

source

fn Prism::encode_request_with_diagnostics(self : Prism, text : String, opts : PrismOptions) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

将文本请求编码为提供商 JSON，并返回结构化校验诊断。

Prism::encode_stream_request

source

fn Prism::encode_stream_request(self : Prism, text : String, opts : PrismOptions) -> Result[String, String]

将文本请求编码为流式提供商 JSON

Prism::endpoint

source

fn Prism::endpoint(_self : Prism, provider_name : String) -> SdkProviderEndpoint?

查询指定 provider 的部署态端点配置（基于注册表，含动态注册）

Prism::events_to_context

source

fn Prism::events_to_context(_self : Prism, ctx : Context, events : Array[PrismEvent]) -> Context

Agent 循环回填闭环：把流事件累积为 assistant 回合并追加到 Context

用法（与 add_tool_result 配对）：

let events = prism.stream(ctx, send)?
let ctx = prism.events_to_context(ctx, events)  // 回填 assistant 回合
// 执行工具…
let ctx = ctx.add_tool_result(id, result, false)  // 注入结果
// 第二轮请求（provider 不再拒绝 tool_result）

语义：TextDelta 合并为一个 Text 块；每个 ToolCall 事件产生一个 ToolUse 块（含累积后的完整 arguments_json）；Thinking 不回填（v1）。空回合（无文本无工具调用）不追加消息。

Prism::new

source

fn Prism::new() -> Prism

Prism::stream

source

fn Prism::stream(self : Prism, ctx : Context, send : (String) -> Result[String, String]) -> Result[Array[PrismEvent], String]

L2 Agent 循环：流式请求 + 5 事件解码（HTTP 由 Host 注入 send）

Prism::with_provider

source

fn Prism::with_provider(_self : Prism, name : String) -> Prism

设置 provider 名称

PrismError

source

pub struct PrismError {
  kind : @morning-start/prism/lux.LucentErrorKind
LucentErrorKind
  message : String
  provider : String?
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

PrismError — SDK 层类型化错误

kind 复用 IR 的 LucentErrorKind（RateLimit/Authentication/ ServerError/ContentFilter/InvalidRequest/Native），让重试与熔断策略按类型匹配而非字符串匹配。

PrismError::equal

source

fn PrismError::equal(PrismError, PrismError) -> Bool

explicit: Eq::equal kept as a regular method (implicit promotion is deprecated, E0079)

PrismError::from_string

source

fn PrismError::from_string(message : String) -> PrismError

从字符串错误分类（尽力而为的启发式，provider=None）

六函数契约固定返回 String（命名规则 §3.1），类型信息在该边界丢失；分类器按消息内容保守推断：

未命中任何模式 → Native("unclassified")（绝不误判为可重试）
宁可漏分类，不可错分类——错分类会导致错误的重试行为（如把鉴权失败当限流重试）

PrismError::is_retryable

source

fn PrismError::is_retryable(self : PrismError) -> Bool

是否可重试（限流与服务端错误）

PrismError::message

source

fn PrismError::message(self : PrismError) -> String

错误消息文本（兼容 String 错误时代的展示）

PrismError::new

source

fn PrismError::new(kind : @morning-start/prism/lux.LucentErrorKind
LucentErrorKind, message : String, provider : String?) -> PrismError

PrismError::with_provider

source

fn PrismError::with_provider(self : PrismError, provider : String?) -> PrismError

设置 provider 字段（builder）

PrismEvent

source

pub(all) enum PrismEvent {
  TextDelta(String)
  ToolCall(PrismToolCall)
  ToolResult(PrismToolResult)
  Thinking(PrismThinking)
  Finish(PrismFinishReason)
}

PrismEvent — 流事件枚举

PrismFinishReason

source

pub(all) enum PrismFinishReason {
  Stop
  Length
  ToolCalls
  ContentFilter
  Error
}

PrismFinishReason — 结束原因

PrismOptions

source

pub struct PrismOptions {
  model : String?
  temperature : Double?
  max_tokens : Int?
  store : Bool?
  extras : Map[String, Json]?
  tool_choice : @morning-start/prism/lux.LucentToolChoice
LucentToolChoice?
  reasoning_enabled : Bool?
  reasoning_effort : @morning-start/prism/lux.LucentReasoningEffort
LucentReasoningEffort?
  structured_output : @morning-start/prism/lux.LucentStructuredOutput
LucentStructuredOutput?
  parallel_tool_calls : Bool?
}

PrismOptions — SDK 请求选项

字段分两组：

基础五项（model/temperature/max_tokens/store/extras）：new() 位置参数
T3 扩展项（tool_choice/reasoning/structured_output/parallel_tool_calls）：全部可选，经 with_* builder 设置；缺省 None 时编码输出与扩展前逐字节一致（有回归门禁测试）。

PrismOptions::default

source

fn PrismOptions::default() -> PrismOptions

PrismOptions::new

source

fn PrismOptions::new(model : String?, temperature : Double?, max_tokens : Int?, store : Bool?, extras : Map[String, Json]?) -> PrismOptions

PrismOptions::with_parallel_tool_calls

source

fn PrismOptions::with_parallel_tool_calls(self : PrismOptions, enabled : Bool) -> PrismOptions

设置并行工具调用（经 extras 语义反传，见字段注释）

PrismOptions::with_reasoning

source

fn PrismOptions::with_reasoning(self : PrismOptions, enabled : Bool?, effort : @morning-start/prism/lux.LucentReasoningEffort
LucentReasoningEffort?) -> PrismOptions

设置推理配置（enabled=None 时仅设置 effort，隐含启用）

PrismOptions::with_structured_output

source

fn PrismOptions::with_structured_output(self : PrismOptions, output : @morning-start/prism/lux.LucentStructuredOutput
LucentStructuredOutput) -> PrismOptions

设置结构化输出

PrismOptions::with_tool_choice

source

fn PrismOptions::with_tool_choice(self : PrismOptions, choice : @morning-start/prism/lux.LucentToolChoice
LucentToolChoice) -> PrismOptions

设置工具选择（builder 风格，其余字段保留）

PrismThinking

source

pub struct PrismThinking {
  text : String
  signature : String?
  redacted : Bool
}

PrismThinking — 推理内容

PrismToolCall

source

pub struct PrismToolCall {
  id : String
  name : String
  arguments_json : String
}

PrismToolCall — 工具调用

PrismToolCall::new

source

fn PrismToolCall::new(id : String, name : String, arguments_json : String) -> PrismToolCall

构造器（SDK 消费者自建 mock transport / 回放事件流时需要）

PrismToolResult

source

pub struct PrismToolResult {
  tool_use_id : String
  content : String
  is_error : Bool
}

PrismToolResult — 工具结果

ProviderRegistration

source

pub struct ProviderRegistration {
  name : String
  aliases : Array[String]
  capability : @morning-start/prism/lux.ProviderCapability
ProviderCapability
  model_pattern : String
  schema : @morning-start/prism/provider/meta.ProviderSchema
ProviderSchema
  request_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentRequest
LucentRequest], String]
  request_encode : (@morning-start/prism/lux.LucentRequest
LucentRequest) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]
  response_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentResponse
LucentResponse], String]
  response_encode : (@morning-start/prism/lux.LucentResponse
LucentResponse) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]
  events_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]], String]
  events_encode : (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]
  events_encode_with_ctx : (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent], @morning-start/prism/lux.LucentConversationMeta
LucentConversationMeta?) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]
  base_url : String?
  auth_header : String?
  api_version : String?
}

单个 Provider 注册条目

身份字段（name / aliases / model_pattern / capability）与 schema 全部来自 src/provider/<name>/meta.mbt，本类型只负责把元数据与六个 codec 函数绑在一起。新增 provider 时不要在 build_providers 里重复元数据字面量。

ProviderRegistration::from_metadata

source

fn ProviderRegistration::from_metadata(metadata : @morning-start/prism/provider/meta.ProviderMeta
ProviderMeta, request_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentRequest
LucentRequest], String], request_encode : (@morning-start/prism/lux.LucentRequest
LucentRequest) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], response_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentResponse
LucentResponse], String], response_encode : (@morning-start/prism/lux.LucentResponse
LucentResponse) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], events_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]], String], events_encode : (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], events_encode_with_ctx : (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent], @morning-start/prism/lux.LucentConversationMeta
LucentConversationMeta?) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], base_url : String?, auth_header : String?, api_version : String?) -> ProviderRegistration

从 provider 自有元数据构造注册项 —— registry 不再重复元数据字段。

ProviderRegistration::new

source

fn ProviderRegistration::new(name : String, aliases : Array[String], capability : @morning-start/prism/lux.ProviderCapability
ProviderCapability, model_pattern : String, schema : @morning-start/prism/provider/meta.ProviderSchema
ProviderSchema, request_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentRequest
LucentRequest], String], request_encode : (@morning-start/prism/lux.LucentRequest
LucentRequest) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], response_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[@morning-start/prism/lux.LucentResponse
LucentResponse], String], response_encode : (@morning-start/prism/lux.LucentResponse
LucentResponse) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], events_decode : (String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]], String], events_encode : (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], events_encode_with_ctx : (Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent], @morning-start/prism/lux.LucentConversationMeta
LucentConversationMeta?) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String], base_url : String?, auth_header : String?, api_version : String?) -> ProviderRegistration

ProviderRegistration::with_overrides

source

fn ProviderRegistration::with_overrides(self : ProviderRegistration, overrides : RegistrationOverrides) -> ProviderRegistration

薄注册工厂：复用基座 adapter + 覆盖部署态元数据（azure/vllm 场景）

六个 codec 函数与 capability/schema 原样继承（协议行为不变），只替换身份与端点字段——中间件为同一协议配多个部署端点时不重写转换逻辑。覆盖 name 时建议同步覆盖 model_pattern/aliases 避免与基座匹配冲突（静态表精确匹配优先，动态项不会遮蔽静态项）。

ProviderSchema

source

pub struct ProviderSchema {
  provider_name : String
  temperature : FieldConstraint
  top_p : FieldConstraint
  top_k : FieldConstraint
  max_output_tokens : FieldConstraint
  resp_min_choices : Int
  supports_tools : Bool
  supports_system_instruction : Bool
  supported_reasoning_efforts : Array[String]?
  extra_checks : Array[() -> Array[String]]?
}

ProviderSchema — 单个 Provider 的请求/响应字段约束集合

ProviderSchema::anthropic

source

fn ProviderSchema::anthropic() -> ProviderSchema

Anthropic Messages

ProviderSchema::azure

source

fn ProviderSchema::azure() -> ProviderSchema

Azure OpenAI

ProviderSchema::gemini

source

fn ProviderSchema::gemini() -> ProviderSchema

Google Gemini

ProviderSchema::openai

source

fn ProviderSchema::openai() -> ProviderSchema

OpenAI Chat Completions / Responses

ProviderSchema::validate_request

source

fn ProviderSchema::validate_request(self : ProviderSchema, req : @morning-start/prism/lux.LucentRequest
LucentRequest) -> Array[String]

校验请求是否符合 Provider 的字段约束返回校验错误列表，空列表表示校验通过

ProviderSchema::validate_response

source

fn ProviderSchema::validate_response(self : ProviderSchema, resp : @morning-start/prism/lux.LucentResponse
LucentResponse) -> Array[String]

校验响应是否符合 Provider 的字段约束返回校验错误列表，空列表表示校验通过

RegistrationOverrides

source

pub struct RegistrationOverrides {
  name : String?
  aliases : Array[String]?
  model_pattern : String?
  base_url : String?
  auth_header : String?
  api_version : String?
}

RegistrationOverrides — 薄注册覆盖项（T6，derive 工厂用）

全部可选：None 表示继承基座值。codecs/capability/schema 不可覆盖（协议能力属于基座 adapter；部署态只改身份与端点）。

RegistrationOverrides::default

source

fn RegistrationOverrides::default() -> RegistrationOverrides

SdkMessage

source

pub struct SdkMessage {
  role : String
  content : String
  tool_use_id : String?
  is_error : Bool?
  tool_calls : Array[SdkToolCall]
}

SdkMessage — SDK 层的消息表示

SdkMessage::assistant_turn

source

fn SdkMessage::assistant_turn(content : String, tool_calls : Array[SdkToolCall]) -> SdkMessage

构造 assistant 回合消息（文本 + 任意数量工具调用合并为一条消息）

回合级语义：一个 assistant 回合的文本与全部 tool_use 必须在同一条消息里，provider（Anthropic/OpenAI）才接受紧随其后的 tool_result。

SdkMessage::new

source

fn SdkMessage::new(role : String, content : String) -> SdkMessage

SdkMessage::tool_call

source

fn SdkMessage::tool_call(id : String, name : String, arguments_json : String, content : String) -> SdkMessage

构造 assistant 工具调用消息（Agent 循环第一轮回填用，单个调用）

role 固定为 "assistant"；content 可携带同回合的文本（混合输出）。

SdkMessage::tool_result

source

fn SdkMessage::tool_result(tool_use_id : String, content : String, is_error : Bool) -> SdkMessage

构造工具结果消息（Agent 循环注入工具执行结果用）

SdkProviderEndpoint

source

pub struct SdkProviderEndpoint {
  base_url : String?
  auth_header : String?
  api_version : String?
}

SdkProviderEndpoint — 部署态端点配置投影（T6）

Extension 字段：全部可选。SDK 不发起 HTTP（宿主注入 send），端点配置供宿主路由/鉴权读取；None 表示该 provider 未声明。

SdkTool

source

pub struct SdkTool {
  name : String
  description : String
  parameters_json : String
}

SdkTool — SDK 层的工具定义

SdkTool::new

source

fn SdkTool::new(name : String, description : String, parameters_json : String) -> SdkTool

SdkToolCall

source

pub struct SdkToolCall {
  id : String
  name : String
  arguments_json : String
}

SdkToolCall — SDK 层的 assistant 工具调用回合

Agent 循环第二轮必需：模型发出 tool_call 后，transcript 中必须先有对应的 assistant tool_use 回合，provider（Anthropic/OpenAI 均硬校验）才接受紧随其后的 tool_result。

SdkToolCall::new

source

fn SdkToolCall::new(id : String, name : String, arguments_json : String) -> SdkToolCall

StreamConverter

source

pub struct StreamConverter {
  source : ProviderRegistration
  target : ProviderRegistration
  splitter : @morning-start/prism/internal.SseFrameSplitter
SseFrameSplitter
  stream_ctx : @morning-start/prism/lux.LucentConversationMeta
LucentConversationMeta?
  open_blocks : Array[Int]
  held_events : Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]
}

StreamConverter — 增量流转换会话

场景 2（中转中间件）逐帧转发：host 持有会话对象，把上游 SSE chunk 原样 feed 进来，立即取得目标协议 SSE 帧——TFTB 从"整条响应到达" 降到"首帧到达"。

帧边界由 @internal.SseFrameSplitter 处理（跨 chunk 半帧缓冲， CRLF/CR/LF 归一化，含 \r|\n 切分边界）。每帧独立完成 source decode → IR → target encode；跨帧上下文（会话 id/model）由本会话跟踪，经 events_encode_with_ctx 传给需要它的编码器（openai/responses），保证逐帧输出与整缓冲转换逐字节一致。

用法：

let conv = StreamConverter::new("openai", "messages")?
for chunk in upstream_chunks {
  let frames = conv.feed(chunk)?   // 立即转发给下游
  downstream.write(frames)
}
let tail = conv.finish()?          // 冲刷尾部半帧

StreamConverter::feed

source

fn StreamConverter::feed(self : StreamConverter, chunk : String) -> Result[Array[String], String]

喂入一个上游 chunk，返回目标协议 SSE 帧数组（可能为空：半帧缓冲中）

StreamConverter::finish

source

fn StreamConverter::finish(self : StreamConverter) -> Result[Array[String], String]

流结束：冲刷尾部半帧（无结束空行的流）并转换，发射保持的 Finish 帧

StreamConverter::new

source

fn StreamConverter::new(source : String, target : String) -> Result[StreamConverter, String]

创建增量转换会话（解析 source/target provider）

DEFAULT_MODEL

source

let DEFAULT_MODEL : String

SDK 默认模型名称（请求编码时的 fallback）

DEFAULT_PROVIDER

source

let DEFAULT_PROVIDER : String

SDK 默认 provider 名称（Prism::new() 使用）

all_providers

source

fn all_providers() -> Array[ProviderRegistration]

所有已注册的 Provider（静态表 + 动态表，动态在后）

新增 Provider 只需在 build_providers 中追加，或运行时 register_provider。注意：条目顺序影响匹配优先级（精确匹配优先于正则匹配；静态表整体优先于动态表）。

每次调用返回独立数组，调用方可安全修改；内部匹配路径直接读 providers_cache / dynamic_providers 避免重复构造。

context_to_lux_request

source

fn context_to_lux_request(ctx : Context, model : String, opts : PrismOptions) -> @morning-start/prism/lux.LucentRequest
LucentRequest

将 Context 转为 LucentRequest（SDK 内部使用）

convert_request

source

fn convert_request(source : String, json_str : String, target : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

请求：source 协议 JSON → target 协议 JSON（带诊断）

convert_request_typed

source

fn convert_request_typed(source : String, json_str : String, target : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], PrismError]

请求转换（类型化错误版）

convert_request_with_hooks

source

fn convert_request_with_hooks(source : String, json_str : String, target : String, hooks : Array[(@morning-start/prism/lux.LucentRequest
LucentRequest, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentRequest
LucentRequest]) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

convert_request_with_hooks — 请求转换 + IR 钩子链（场景 2 策略注入）

管线：source decode → hooks(IR) → target encode；诊断按 decode/hook/encode 三段合并。hooks 为空数组时与 convert_request 一致。

convert_request_with_store

source

fn convert_request_with_store(source : String, json_str : String, target : String, store : ConversationStore) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

convert_request_with_store — 请求转换 + 会话快照还原（T8）

管线：source decode →（previous_response_id 且无历史 → 快照还原） → target encode。诊断按 decode/encode 两段合并。无快照时显式 Err（与直接 convert_request 的拒绝语义一致）。

convert_response

source

fn convert_response(source : String, json_str : String, target : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

响应：source 协议 JSON → target 协议 JSON（带诊断）

convert_response_typed

source

fn convert_response_typed(source : String, json_str : String, target : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], PrismError]

响应转换（类型化错误版）

convert_response_with_hooks

source

fn convert_response_with_hooks(source : String, json_str : String, target : String, hooks : Array[(@morning-start/prism/lux.LucentResponse
LucentResponse, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentResponse
LucentResponse]) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

convert_response_with_hooks — 响应转换 + IR 钩子链

convert_response_with_meta

source

fn convert_response_with_meta(source : String, json_str : String, target : String) -> Result[ConvertMetaResult, String]

响应转换（带来源元信息）：source 协议 JSON → target 协议 JSON。

convert_stream

source

fn convert_stream(source : String, sse_str : String, target : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

流式：source 协议 SSE → target 协议 SSE（事件级转换，带诊断）

convert_stream_typed

source

fn convert_stream_typed(source : String, sse_str : String, target : String) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], PrismError]

流转换（类型化错误版）

convert_stream_with_hooks

source

fn convert_stream_with_hooks(source : String, sse_str : String, target : String, hooks : Array[(Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent], Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent]]) -> Result[@morning-start/prism/lux.ConversionResult
ConversionResult[String], String]

convert_stream_with_hooks — 流转换 + IR 钩子链（事件级）

钩子作用于整个事件数组（可做事件过滤/注入/重排）；空 hooks 时与 convert_stream 一致。

enforce_policy

source

fn[T] enforce_policy(value : T, diagnostics : Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic], policy : DiagnosticPolicy) -> Result[T, String]

对「值 + 诊断」执行策略（T10 一次性入口）

ReportOnly → 原样 Ok；FailOnUnsupported/FailOnDegraded → 存在达到阈值的诊断时返回 Err（消息含计数与首条诊断详情）。

get_schema

source

fn get_schema(provider : String) -> ProviderSchema?

根据 provider 名获取对应 schema（自动匹配主名、别名与模型名）

hook_append_instructions

source

fn hook_append_instructions(text : String) -> ((@morning-start/prism/lux.LucentRequest
LucentRequest, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentRequest
LucentRequest)

追加系统指令（prompt 注入/改写）

有意为之的策略操作，不产生诊断（非损失）。

hook_clamp_max_tokens

source

fn hook_clamp_max_tokens(limit : Int) -> ((@morning-start/prism/lux.LucentRequest
LucentRequest, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentRequest
LucentRequest)

钳制 max_output_tokens 上限（成本兜底）

实际压价时 push Degraded 诊断（值被改小才算损失）；原值小于等于 limit 时原样返回、无诊断。

hook_filter_tools

source

fn hook_filter_tools(allowed : Array[String]) -> ((@morning-start/prism/lux.LucentRequest
LucentRequest, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentRequest
LucentRequest)

工具白名单过滤（裁剪越权工具）

被裁掉的工具 push Degraded 诊断（数据不静默丢失）；全部保留时无诊断。allowed 为空数组 = 裁掉所有工具。

hook_set_model

source

fn hook_set_model(model : String) -> ((@morning-start/prism/lux.LucentRequest
LucentRequest, Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> @morning-start/prism/lux.LucentRequest
LucentRequest)

改写模型名（路由/降级：把请求打到指定后端模型）

有意为之的路由操作，不产生诊断；同名时无操作。

hook_stream_drop_after_error

source

fn hook_stream_drop_after_error() -> ((Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent], Array[@morning-start/prism/lux.ConversionDiagnostic
ConversionDiagnostic]) -> Array[@morning-start/prism/lux.LucentStreamEvent
LucentStreamEvent])

流钩子示例：丢弃 Error 事件后的所有事件（故障演练/熔断演示用）

保留错误事件本身（显式失败原则），只丢弃其后的噪音。

list_provider_names

source

fn list_provider_names() -> Array[String]

获取所有 Provider 的主名称列表（静态表 + 动态表，动态在后）

match_by_model

source

fn match_by_model(model_name : String) -> ProviderRegistration?

根据 model_name 匹配 Provider（通过 model_pattern 子串匹配）

返回最具体的匹配（pattern 中 * 越多越优先），或 None。静态表与动态表联合评分：特异性严格大于才替换（同分静态优先）。

match_provider_name

source

fn match_provider_name(provider_name : String) -> ProviderRegistration?

根据名称匹配 Provider

匹配策略：

静态表精确匹配 name / 别名
动态表（register_provider）精确匹配 name / 别名
均未命中时，把输入当作模型名走 match_by_model 回退

若只想按模型名匹配，直接调用 match_by_model。

previous_response_id_of

source

fn previous_response_id_of(req : @morning-start/prism/lux.LucentRequest
LucentRequest) -> String?

取请求的 previous_response_id（标准字段优先，extras 旧载荷回退）

register_provider

source

fn register_provider(reg : ProviderRegistration) -> Unit

注册单个 Provider（运行时显式动态注册）

用于中间件部署态：复用已有 adapter + 覆盖 model_pattern/endpoint （配合 ProviderRegistration::derive 薄注册工厂）。幂等：同名主名称重复注册会替换旧动态项。注意：动态项不会遮蔽静态表的精确/别名匹配（静态优先）。

restore_request_from_snapshot

source

fn restore_request_from_snapshot(req : @morning-start/prism/lux.LucentRequest
LucentRequest, snapshot : @morning-start/prism/lux.ConversationSnapshot
ConversationSnapshot) -> @morning-start/prism/lux.LucentRequest
LucentRequest

快照还原：快照历史 + 新请求项合并为完整对话

规则：

conversation：快照请求的会话项全部在前，新请求项追加在后
instructions / tools / tool_choice：新请求优先，缺失时继承快照
options / capabilities / reasoning / metadata / extra：取新请求
previous_response_id 保留：responses → responses 时后端仍持有状态（正确续接）；无状态目标端由编码器既有逻辑剔除并打诊断

store_snapshot_from_response

source

fn store_snapshot_from_response(store : ConversationStore, req : @morning-start/prism/lux.LucentRequest
LucentRequest, response : @morning-start/prism/lux.LucentResponse
LucentResponse) -> Unit

从「已解码请求 + 已解码响应」构造并存储快照（中间件转发成功后调用）

unregister_provider

source

fn unregister_provider(name : String) -> Bool

注销动态注册的 Provider（按主名称）

静态表项不受影响（尝试注销静态名返回 false）。返回是否实际移除了动态项。

Source Files

Install

Download zip

A unified LLM protocol middleware converting between OpenAI, Anthropic, Gemini and other provider formats via the Lucent IR neutral protocol

llmwasmprotocolmiddlewareadapter

morning-start

MIT

github.com/morning-start/prism

Updated last month

48 downloads

Site source Report issue Modules Skills CLI Build queue Statistics

#src/sdk — SDK 组合根（导航索引）

#功能组文件地图

#1. facade（对外入口，先读这里）

#2. registry+match（注册与路由）

#3. pipeline（编码解码编排）

#4. convert（跨协议中转）

#5. hooks（IR 策略层，T4）

#6. snapshot（会话快照，T8）

#7. error + diagnostics（类型化错误与诊断运维，T7/T10）

#8. schema+event（元数据，零内部依赖）

#9. 测试

#依赖方向（禁止反向）

#约定

#SdkRequestHook

#SdkResponseHook

#SdkStreamHook

#Context

#Context::add_assistant

#Context::add_assistant_turn

#Context::add_system

#Context::add_tool_call

#Context::add_tool_result

#Context::add_tools

#Context::add_user

#Context::new

#ConversationStore

#ConversationStore::new

#ConversionMeta

#ConversionMeta::new

#ConvertMetaResult

#ConvertMetaResult::meta

#ConvertMetaResult::new

#ConvertMetaResult::value

#DecodedResponse

#DecodedResponse::new

#DiagnosticCollector

#DiagnosticCollector::add_all

#DiagnosticCollector::count_by_field

#DiagnosticCollector::count_by_status

#DiagnosticCollector::diagnostics

#DiagnosticCollector::enforce

#DiagnosticCollector::new

#DiagnosticCollector::push

#DiagnosticCollector::reset

#DiagnosticCollector::summary

#DiagnosticCollector::total

#DiagnosticCollector::worst_status

#DiagnosticCounts

#DiagnosticCounts::default

#DiagnosticCounts::equal

#DiagnosticCounts::total

#DiagnosticPolicy

#DiagnosticPolicy::equal

#FieldConstraint

#FieldConstraint::new

#Prism

#Prism::capability

#Prism::check_capability

#Prism::complete

#Prism::decode_response

#Prism::decode_response_typed

#Prism::decode_response_with_diagnostics

#Prism::decode_response_with_meta

#Prism::decode_sse

#Prism::decode_sse_typed

#Prism::encode_request

#Prism::encode_request_typed

#Prism::encode_request_with_diagnostics

#Prism::encode_stream_request

#Prism::endpoint

#Prism::events_to_context

#Prism::new

#Prism::stream

#Prism::with_provider

#PrismError

#PrismError::equal

#PrismError::from_string

#PrismError::is_retryable

#PrismError::message

#PrismError::new

SdkRequestHook

SdkResponseHook

SdkStreamHook

Context

Context::add_assistant

Context::add_assistant_turn

Context::add_system

Context::add_tool_call

Context::add_tool_result

Context::add_tools

Context::add_user

Context::new

ConversationStore

ConversationStore::new

ConversionMeta

ConversionMeta::new

ConvertMetaResult

ConvertMetaResult::meta

ConvertMetaResult::new

ConvertMetaResult::value

DecodedResponse

DecodedResponse::new

DiagnosticCollector

DiagnosticCollector::add_all

DiagnosticCollector::count_by_field

DiagnosticCollector::count_by_status

DiagnosticCollector::diagnostics

DiagnosticCollector::enforce

DiagnosticCollector::new

DiagnosticCollector::push

DiagnosticCollector::reset

DiagnosticCollector::summary

DiagnosticCollector::total

DiagnosticCollector::worst_status

DiagnosticCounts

DiagnosticCounts::default

DiagnosticCounts::equal

DiagnosticCounts::total

DiagnosticPolicy

DiagnosticPolicy::equal

FieldConstraint

FieldConstraint::new

Prism

Prism::capability

Prism::check_capability

Prism::complete

Prism::decode_response

Prism::decode_response_typed

Prism::decode_response_with_diagnostics

Prism::decode_response_with_meta

Prism::decode_sse

Prism::decode_sse_typed

Prism::encode_request

Prism::encode_request_typed

Prism::encode_request_with_diagnostics

Prism::encode_stream_request

Prism::endpoint

Prism::events_to_context

Prism::new

Prism::stream

Prism::with_provider

PrismError

PrismError::equal

PrismError::from_string

PrismError::is_retryable

PrismError::message

PrismError::new

PrismError::with_provider

PrismEvent

PrismFinishReason

PrismOptions

PrismOptions::default

PrismOptions::new

PrismOptions::with_parallel_tool_calls

PrismOptions::with_reasoning

PrismOptions::with_structured_output

PrismOptions::with_tool_choice

PrismThinking

PrismToolCall

PrismToolCall::new