Documentation
¶
Overview ¶
Package llmcontract 是直接结构化返回的统一契约与执行层：静态 Contract 是结构的单一来源，Execute 统一完成能力选择、提示词准备、请求重试、 Schema/DTO 解码和反馈自愈。 协议在请求发出前确定；原生请求被拒或违约时原样暴露，禁止静默去掉 schema 重发。
Index ¶
- func Execute[T any](ctx context.Context, model llmretry.Generator, req Request[T]) (T, error)
- func ExtractJSONObject(raw string) string
- func Nullable(s map[string]any) map[string]any
- func PreparePrompt(base string, c Contract, res Resolution) (string, error)
- func ValidateJSON(schema map[string]any, raw []byte) error
- func ValidateStrictReady(s map[string]any) error
- type Contract
- type Correction
- type Failure
- type FailureKind
- type Hooks
- type Mode
- type ModelFacts
- type Request
- type Resolution
- type Source
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Execute ¶
Execute 统一完成协议选择、提示词准备、请求重试、停止原因分类、Schema/DTO 解码和业务反馈自愈。prompt 模式的格式/Schema 错误以及两种模式的业务错误会 持续反馈给模型，直到成功或 context 结束；原生契约违约会立即暴露。
func ExtractJSONObject ¶
ExtractJSONObject 返回文本中的第一个平衡 JSON 对象，字符串中的花括号不计入层级。
func Nullable ¶
Nullable 把一个 schema 的 type 扩展为可空联合(["<t>","null"]),用于 strict 模式下"全字段 required、可选语义用 null"的表达。返回拷贝,不修改传入 map。
func PreparePrompt ¶
func PreparePrompt(base string, c Contract, res Resolution) (string, error)
PreparePrompt 保持业务语义提示词只有一份：原生模式直接返回原文；prompt contract 模式从同一份 Schema 自动生成格式后缀。调用方不维护第二套模板，字段 变更也不会让提示词与 response_format 分叉。
func ValidateJSON ¶
ValidateJSON 校验原始 JSON 是否满足直接返回契约使用的 JSON Schema 子集。 该子集覆盖 object/array/string/integer/number/boolean/null、required、enum 和 additionalProperties。未声明 additionalProperties 时遵循 JSON Schema 默认语义， 不额外拒绝未知字段。
func ValidateStrictReady ¶
ValidateStrictReady 递归校验 schema 满足 OpenAI strict 子集的结构前提: 所有 object 的属性都必须列入 required(可选语义用 null 联合表达)。litellm 在请求期做同样校验并自动补 additionalProperties:false;契约测试用本函数 前置断言(RFC §11.1),不把结构问题留到运行时。
Types ¶
type Contract ¶
Contract 是一次直接结构化返回的静态契约,紧邻各边界 DTO 定义。
func (Contract) Fingerprint ¶
Fingerprint 返回 schema 规范化 JSON 的 sha256 前 12 位 hex,用于日志关联; encoding/json 对 map 键排序,同一契约天然稳定。
type Correction ¶
Correction 描述一次模型可修复的输出错误。Attempt 是刚失败的调用序号。
type Failure ¶
type Failure struct {
Kind FailureKind
Contract string
Raw string
Err error
}
Failure 保留失败类别和模型原始输出，供调用方决定日志、工件和 UI 表达。
type FailureKind ¶
type FailureKind string
FailureKind 区分不可由同一次结构化反馈修复的失败边界。
const ( FailureRequest FailureKind = "request" FailureProtocol FailureKind = "protocol" FailureLength FailureKind = "length" FailureSafety FailureKind = "safety" FailureContract FailureKind = "contract" )
type Hooks ¶
type Hooks struct {
Resolved func(Resolution)
RequestRetry func(llmretry.Event)
Correction func(Correction)
}
Hooks 只负责可观测性，不改变执行语义。
type ModelFacts ¶
type ModelFacts struct {
Capabilities llm.Capabilities
Info llm.ModelInfo
JSONSchemaOverride *bool
}
ModelFacts 是一次能力解析所需的同一时刻快照。热切换包装器实现该接口， 避免 Resolve 分别读取能力、配置覆盖和模型身份时混入两次切换之间的状态。
type Request ¶
type Request[T any] struct { Contract Contract SystemPrompt string Payload string Options []agentcore.CallOption Validate func(*T) error Agent string Hooks Hooks }
Request 定义一次直接结构化返回。Contract 是结构的单一来源，Validate 只处理 JSON Schema 无法表达的业务约束。
type Resolution ¶
type Resolution struct {
Mode Mode
Source Source
Strict bool // native 时是否携带 strict
Provider string
Model string
}
Resolution 是请求发出前确定的协议选择结果,供调用方分支与日志。
func Plan ¶
func Plan(model any, c Contract) ([]agentcore.CallOption, Resolution)
Plan 解析协议并在原生模式下生成调用选项;prompt contract 模式返回 nil opts。
func Resolve ¶
func Resolve(model any) Resolution
Resolve 每次调用现读当前模型事实(热切换后下一次调用即用新值): config 三态优先,其次 adapter 模型级能力,未知一律 prompt contract。
Source Files