Documentation
¶
Overview ¶
Package responses contains the side-effect-free Responses body planner and rewriter used by the request interceptor. It intentionally knows nothing about HTTP or the VLM client: discovery happens first, and Rewrite is called only after every image has a successful VLM result.
Index ¶
- Constants
- func Discover(body []byte, options ...Options) (*responsesPlan, error)
- func RenderGroupResult(group PromptGroup, text string) string
- func RenderResult(number int, result ImageResult) string
- type Adapter
- type Error
- type ErrorKind
- type Image
- type ImageCountDetails
- type ImageResult
- type LimitKind
- type Options
- type Plan
- type PromptGroup
- type Protocol
- type ToolContext
Constants ¶
const ( ErrorMalformedRequest ErrorKind = "malformed_request" ErrorUnsupportedImage ErrorKind = "unsupported_image_source" // ErrorUnsupportedImageSource is the descriptive alias used by callers // that prefer the full contract wording. ErrorUnsupportedImageSource ErrorKind = ErrorUnsupportedImage ErrorLimitsExceeded ErrorKind = "limits_exceeded" ErrorMissingResult ErrorKind = "missing_result" ErrorInvalidResult ErrorKind = "invalid_result" ErrorRewriteVerification ErrorKind = "rewrite_verification" LimitRequestBody LimitKind = "request_body" LimitImageReference LimitKind = "image_reference" LimitImageCount LimitKind = "image_count" LimitVLMResult LimitKind = "vlm_result" LimitReanalysisCount LimitKind = "reanalysis_count" )
Variables ¶
This section is empty.
Functions ¶
func Discover ¶
Discover parses a Responses request body and records every supported image in input[].content[] and function_call_output.output[]. The variadic form keeps the common Discover(body) call concise while allowing the interceptor to pass explicit limits.
func RenderGroupResult ¶
func RenderGroupResult(group PromptGroup, text string) string
func RenderResult ¶
func RenderResult(number int, result ImageResult) string
RenderResult applies the frozen replacement template. It is exported so the VLM owner can use the same rendering in tests without duplicating wording.
Types ¶
type Adapter ¶
type Adapter interface {
Protocol() Protocol
Discover(body []byte, options ...Options) (Plan, error)
}
Adapter discovers and rewrites one exact downstream wire protocol.
type Error ¶
type Error struct {
Kind ErrorKind
StatusCode int
Message string
Path string
Limit LimitKind
Actual int
Maximum int
ImageCount *ImageCountDetails
DebugImages []Image
}
Error is a typed planner error. StatusCode is the HTTP status that should be returned when the error is surfaced before an upstream request is made.
type ErrorKind ¶
type ErrorKind string
ErrorKind identifies the class of a request planning or rewrite failure. The kind is stable and may be used by the interceptor when constructing its public error response.
type Image ¶
type Image struct {
Number int `json:"number"`
Reference string `json:"reference"`
FocusHint string `json:"focus_hint"`
InputIndex int `json:"input_index"`
BlockIndex int `json:"block_index"`
Source string `json:"source"`
// contains filtered or unexported fields
}
Image describes one image discovered in a request. Number is stable and is one-based in original traversal order. Reference is safe to pass to the VLM client, while FocusHint contains nearby user text with the configured hard cap applied.
type ImageCountDetails ¶
type ImageCountDetails struct {
InputItems int `json:"input_items"`
ImageInputItems int `json:"image_input_items"`
ImageBlocks int `json:"image_blocks"`
UniqueImageReferences int `json:"unique_image_references"`
DuplicateImageBlocks int `json:"duplicate_image_blocks"`
LastImageItemIndex int `json:"last_image_item_index"`
LastImageItemBlocks int `json:"last_image_item_blocks"`
EarlierImageBlocks int `json:"earlier_image_blocks"`
ContentImages int `json:"content_images"`
FunctionOutputImages int `json:"function_output_images"`
}
ImageCountDetails is a content-free breakdown of image blocks across a multi-turn Responses input. References themselves are never stored here.
type ImageResult ¶
ImageResult is the structured output required to replace one image. Both fields are rendered into the frozen single-block template.
func ParseVLMText ¶
func ParseVLMText(text string) ImageResult
ParseVLMText converts a conventional Luna response into the structured result expected by Rewrite. It accepts the frozen headings, a JSON object with visible_text/visual_description keys, or plain text (plain text is treated as the visual description while explicitly recording that no text was detected).
type LimitKind ¶
type LimitKind string
LimitKind identifies the exact bounded resource that rejected a request. It is safe to expose to diagnostics because it never contains user input.
type Options ¶
type Options struct {
MaxImages int
MaxReferenceBytes int
MaxBodyBytes int
MaxFocusChars int
MaxResultChars int
AgentReanalysisEnabled bool
}
Options controls request discovery and rewrite safety limits. A zero value uses conservative defaults. MaxFocusChars is a character (rune) limit; byte limits are measured in bytes of the UTF-8 request/reference.
type Plan ¶
type Plan interface {
Protocol() Protocol
InputItemCount() int
ImageCountDetails() ImageCountDetails
Images() []Image
Groups() []PromptGroup
HasImages() bool
RewriteGroupsText([]string) ([]byte, error)
}
Plan is an immutable, protocol-specific image discovery result.
type PromptGroup ¶
type PromptGroup struct {
ID int `json:"id"`
InputIndex int `json:"input_index"`
Source string `json:"source"`
Prompt string `json:"prompt"`
Images []Image `json:"images"`
Tool *ToolContext `json:"tool,omitempty"`
AllowAgentReanalysis bool `json:"allow_agent_reanalysis,omitempty"`
// contains filtered or unexported fields
}
PromptGroup is the unit sent to the visual model. Images that belong to the same Responses content/output item stay together so the model can preserve comparisons and relationships expressed by one prompt.
type ToolContext ¶ added in v0.3.0
type ToolContext struct {
Name string `json:"name"`
CallID string `json:"call_id"`
Location string `json:"location"`
Focus string `json:"focus"`
Detail string `json:"detail"`
CacheMode string `json:"cache_mode"`
Tail bool `json:"tail"`
Active bool `json:"active"`
}
ToolContext is the protocol-neutral metadata for one active agent-requested image reanalysis. Image content remains owned by the protocol-native tool result and is never accepted from tool arguments.