requesthandling

type AnthropicContent struct {
	Raw        string
	Structured []AnthropicContentBlock
}

type AnthropicContentBlock struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
	// image source fields (base64 or URL)
	Source *AnthropicImageSource `json:"source,omitempty"`
}

type AnthropicImageSource struct {
	Type      string `json:"type"`
	MediaType string `json:"media_type,omitempty"`
	Data      string `json:"data,omitempty"`
	URL       string `json:"url,omitempty"`
}

type AnthropicMessage struct {
	Role    string           `json:"role"`
	Content AnthropicContent `json:"content"`
}

type AudioBlock struct {
	Data   string `json:"data,omitempty"`
	Format string `json:"format,omitempty"`
}

type ChatCompletionsRequest struct {
	/* parameters from the official OpenAI chat-completions API */
	Messages []Message `json:"messages,omitempty"`
	Tools    []any     `json:"tools,omitempty"`
	/* parameters from the HuggingFace transformers chat-templates API */
	Documents                 []any          `json:"documents,omitempty"`
	ChatTemplate              string         `json:"chat_template,omitempty"`
	ReturnAssistantTokensMask bool           `json:"return_assistant_tokens_mask,omitempty"`
	ContinueFinalMessage      bool           `json:"continue_final_message,omitempty"`
	AddGenerationPrompt       bool           `json:"add_generation_prompt,omitempty"`
	ChatTemplateKWArgs        map[string]any `json:"chat_template_kwargs,omitempty"`
	// CacheSalt is an optional request parameter to isolate prefix caches for security reasons.
	CacheSalt string `json:"cache_salt,omitempty"`
}

type Claims struct {
	Paths     []string         // path patterns this parser claims (e.g., "chat/completions")
	Protocols []v1.AppProtocol // protocols this parser supports (e.g., "h2c")
}

type CompletionsRequest struct {
	// Prompt is the prompt(s) sent in the request body; can be a string or an array of strings.
	Prompt Prompt `json:"prompt"`
	// CacheSalt is an optional request parameter to isolate prefix caches for security reasons.
	CacheSalt string `json:"cache_salt,omitempty"`
}

type Content struct {
	Raw        string
	Structured []ContentBlock
}

type ContentBlock struct {
	Type       string     `json:"type"`
	Text       string     `json:"text,omitempty"`
	ImageURL   ImageBlock `json:"image_url"`
	InputAudio AudioBlock `json:"input_audio"`
	VideoURL   VideoBlock `json:"video_url"`
}

type ConversationItem struct {
	// Type specifies the item type (message, file, etc.)
	Type string `json:"type,omitempty"`
	// Role specifies the role (user, assistant, system)
	Role string `json:"role,omitempty"`
	// Content contains the item content
	Content any `json:"content,omitempty"`
}

type ConversationsRequest struct {
	// Items is the array of conversation items (messages, files, etc.)
	Items []ConversationItem `json:"items,omitempty"`
	// Metadata provides additional context for the conversation
	Metadata map[string]any `json:"metadata,omitempty"`
	// CacheSalt isolates prefix caches for security
	CacheSalt string `json:"cache_salt,omitempty"`
}

type EmbeddingsInput struct {
	Raw      string
	Strings  []string
	TokenIDs []uint32
}

type EmbeddingsRequest struct {
	// Input is the text to embed (string or array of strings).
	Input EmbeddingsInput `json:"input,omitempty"`
	// CacheSalt is an optional request parameter to isolate prefix caches for security reasons.
	CacheSalt string `json:"cache_salt,omitempty"`
}

type GenerateRequest struct {
	// TokenIDs are the pre-tokenized input token IDs.
	TokenIDs []uint32 `json:"token_ids"`
	// Features carries multimodal metadata (per-modality content hashes and
	// placeholder ranges) parsed out of the wire `features` block. Populated
	// by UnmarshalJSON; not itself a JSON-tagged field.
	Features *tokenization.MultiModalFeatures `json:"-"`
	// CacheSalt is an optional request parameter to isolate prefix caches for security reasons.
	CacheSalt string `json:"cache_salt,omitempty"`
}

type ImageBlock struct {
	URL string `json:"url,omitempty"`
}

type InferenceRequestBody struct {
	// CompletionsRequest is the representation of the OpenAI /v1/completions request body.
	Completions *CompletionsRequest `json:"completions,omitempty"`
	// ChatCompletionsRequest is the representation of the OpenAI /v1/chat/completions request body.
	ChatCompletions *ChatCompletionsRequest `json:"chat_completions,omitempty"`
	// MessagesRequest is the representation of the Claude /v1/messages request body.
	Messages *MessagesRequest `json:"messages,omitempty"`
	// ResponsesRequest is the representation of the OpenAI /v1/responses request body.
	Responses *ResponsesRequest `json:"responses,omitempty"`
	// ConversationsRequest is the representation of the OpenAI /v1/conversations request body.
	Conversations *ConversationsRequest `json:"conversations,omitempty"`
	// EmbeddingsRequest is the representation of the OpenAI /v1/embeddings request body.
	Embeddings *EmbeddingsRequest `json:"embeddings,omitempty"`
	// GenerateRequest is the representation of the vLLM /inference/v1/generate request body.
	Generate *GenerateRequest `json:"generate,omitempty"`
	// Payload contains the unmarshaled request payload or raw bytes.
	// If the payload is unmarshaled, we can perform advanced processing (like prefix cache aware routing).
	// If it remains as raw bytes, such processing may not be supported.
	Payload RequestPayload `json:"-"`
	// TokenizedPrompt contains parser-derived tokenization results when available.
	// It is nil when the request was not already tokenized.
	TokenizedPrompt *TokenizedPrompt `json:"-"`

	// Stream indicates whether the request specifies a streaming response (e.g., via a stream field).
	// This typically implies the model server's response will be streamed.
	Stream bool `json:"-"`
}

type Message struct {
	// Role is the message Role, optional values are 'user', 'assistant', ...
	Role string `json:"role,omitempty"`
	// Content defines text of this message
	Content Content `json:"content"`
	// ToolCalls contains assistant tool calls for chat template rendering.
	ToolCalls []any `json:"tool_calls,omitempty"`
}

type MessagesRequest struct {
	// Messages is the array of conversation messages with alternating user/assistant roles.
	Messages []AnthropicMessage `json:"messages,omitempty"`
	// System is the system prompt. In the Anthropic API this is a top-level field,
	// not a message with role "system".
	System AnthropicContent `json:"system,omitempty"`
	// Tools field for tool use capabilities.
	Tools []any `json:"tools,omitempty"`
	// CacheSalt isolates prefix caches for security.
	CacheSalt string `json:"cache_salt,omitempty"`
}

type Modality string

type MultiModalFeature struct {
	// Modality identifies the type of content.
	Modality Modality
	// Hash is the content hash of the item, used for KV-cache reuse across requests.
	Hash string
	// Offset is the index of the first placeholder token for this item in TokenIDs.
	Offset int
	// Length is the number of placeholder tokens this item occupies in TokenIDs.
	Length int
}

type ParseResult struct {
	// Body contains the parsed inference request body.
	Body *InferenceRequestBody
	// SkipResponseProcessing indicates whether to skip EPP stream interception for this request.
	// When set to true, the request will still go through the scheduling director
	// (allowing routing decisions, profiles, and admission control to run),
	// but the EPP will stop intercepting the stream after the request phase completes
	// (e.g., response headers and body will not be processed).
	//
	// This allows fallback or non-standard requests to be routed using the configured
	// policies without paying the overhead of response-phase interception.
	SkipResponseProcessing bool
}

type ParsedResponse struct {
	// Usage is only populate when the raw response has usage.
	Usage *Usage
}

type Parser interface {
	fwkplugin.Plugin
	// ParseRequest parses the request body and headers and returns the parsed result.
	// There are three outcomes based on the return values:
	// 1. err != nil: The request is invalid or cannot be parsed. The framework will fail the request early.
	// 2. err == nil and result.SkipResponseProcessing == true: The request is valid but EPP should stop intercepting the stream
	//    after the request phase. The scheduling director will still route the request, but subsequent
	//    response interception phases will be skipped.
	// 3. err == nil and result.SkipResponseProcessing == false: The request is valid and will be processed by the scheduling framework.
	ParseRequest(ctx context.Context, body []byte, headers map[string]string) (*ParseResult, error)

	// ParseResponse parses the response payload.
	// For streaming responses , this method is invoked multiple times (once per chunk),
	// where 'endOfStream' is set to true only for the final chunk.
	// For non-streaming responses, this method is invoked exactly once with the full
	// buffered response body and 'endOfStream' set to true.
	ParseResponse(ctx context.Context, body []byte, headers map[string]string, endofStream bool) (*ParsedResponse, error)

	// Claims returns the paths and protocols claimed by this parser.
	Claims() Claims
}

type PayloadMap map[string]any

type PayloadProto struct {
	proto.Message
}

type Prompt struct {
	Raw      string
	Strings  []string
	TokenIDs []uint32
}

type PromptTokenDetails struct {
	CachedTokens int `json:"cached_tokens"`
}

type RawPayload []byte

type RequestPayload interface {
	IsParsed() bool
	// AsMap returns the parsed JSON map
	AsMap() (PayloadMap, bool)
	// contains filtered or unexported methods
}

type ResponsesRequest struct {
	// Input can be either a string or an array of conversation items
	Input any `json:"input,omitempty"`
	// Instructions provides optional system-level guidance
	Instructions any `json:"instructions,omitempty"`
	// Tools field for function calling capabilities
	Tools any `json:"tools,omitempty"`
	// CacheSalt isolates prefix caches for security
	CacheSalt string `json:"cache_salt,omitempty"`
}

type TokenizedPrompt struct {
	// PerPromptTokens holds the token IDs for each prompt in the request.
	// Single-prompt requests (chat, generate, single-string completions) use a
	// length-1 outer slice. Multi-string completions use one inner slice per
	// prompt string.
	PerPromptTokens [][]uint32
	// MultiModalFeatures holds one entry per multimodal item in prompt order.
	// Nil if the prompt contains no multimodal content. Offsets are relative
	// to PerPromptTokens[0] (always single-prompt when multimodal content is
	// present).
	MultiModalFeatures []MultiModalFeature
	// CacheSalt isolates prefix caches across requests. Populated by the token-producer.
	CacheSalt string
}

type Usage struct {
	PromptTokens       int                 `json:"prompt_tokens"`
	CompletionTokens   int                 `json:"completion_tokens"`
	TotalTokens        int                 `json:"total_tokens"`
	PromptTokenDetails *PromptTokenDetails `json:"prompt_tokens_details,omitempty"`
}

type VideoBlock struct {
	URL string `json:"url,omitempty"`
}