downstream

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 12 Imported by: 0

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

View Source
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

func Discover(body []byte, options ...Options) (*responsesPlan, error)

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.

func Match

func Match(sourceFormat, path string) (Adapter, bool)

Match returns the adapter for an exact host source-format and request-path pair. Near matches intentionally remain outside the plugin boundary.

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.

func (*Error) Error

func (e *Error) Error() string

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

type ImageResult struct {
	VisibleText       string
	VisualDescription string
}

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 Protocol

type Protocol string

Protocol identifies a supported downstream request protocol.

const (
	ProtocolResponses Protocol = "responses"
	ProtocolChat      Protocol = "chat"
	ProtocolClaude    Protocol = "claude"
)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL