inference

type Audio struct {
	URL    string
	Data   []byte
	Format string
}

type AudioChunk struct {
	Data       []byte
	Transcript string
}

type AudioOutput struct {
	Voice  string
	Format string
}

type Batch struct {
	// ID is the Starport batch identifier.
	ID string
	// Endpoint is the operation path every line calls.
	Endpoint string
	// InputFileID names the stored input file.
	InputFileID string
	// OutputFileID names the stored result file, or is empty while the batch
	// has not written one.
	OutputFileID string
	// ErrorFileID names the stored error file, or is empty when every line
	// succeeded or none has failed yet.
	ErrorFileID string
	// State is the canonical job state word.
	State string
	// Reason states why a failed or cancelled batch stopped. It is empty for
	// every other state.
	Reason string
	// TotalLines is how many request lines the input file holds, or zero
	// while the batch has not counted them.
	TotalLines int
	// CompletedLines is how many lines produced a result.
	CompletedLines int
	// FailedLines is how many lines produced an error-file entry.
	FailedLines int
	// CreatedUnix is when Starport recorded the batch.
	CreatedUnix int64
	// CompletedUnix is when the batch reached a terminal state, or zero while
	// it has not.
	CompletedUnix int64
}

type BatchCreateRequest struct {
	// InputFileID names the stored JSONL file the batch reads.
	InputFileID string
	// Endpoint is the one operation path every line in the batch calls, such
	// as "/v1/chat/completions".
	Endpoint string
	// CompletionWindow is the window the caller asked for. The gateway
	// validates and echoes it rather than scheduling by it, because a
	// self-hosted gateway starts the work at once.
	CompletionWindow string
}

type BatchLine struct {
	// CustomID is the caller's own name for the line. Every result carries it
	// back, because line order is the only other way to match a result to a
	// request.
	CustomID string
	// URL is the operation path the line calls. The codec has already checked
	// it against the batch endpoint.
	URL string
	// Body is the raw request body the line carries. The line runner decodes
	// it with the same codec the online route uses.
	Body []byte
}

type BatchLineResult struct {
	// CustomID is the caller's name for the line, copied from the request.
	CustomID string
	// StatusCode is the HTTP status the online route would have answered.
	StatusCode int
	// RequestID is the per-line request identifier, for support and for the
	// usage record that carries the same value.
	RequestID string
	// Body is the response body, or the error body for a failed line.
	Body []byte
}

type ChatRequest struct {
	Model          string
	FallbackModels []string
	Messages       []Message
	Sampling       Sampling
	Tools          []Tool
	ToolChoice     ToolChoice
	// ParallelToolCalls permits or forbids several tool calls in one
	// assistant turn. Nil leaves the provider default in place.
	ParallelToolCalls *bool
	Output            StructuredOutput
	Reasoning         Reasoning
	// OutputModalities names what the caller will accept back. Empty means
	// text, which is what every model served before this field existed.
	// A model that speaks its answer needs the caller to ask for audio, so
	// this is a request field and not a routing hint.
	//
	// The response cache derives its key by serializing this struct, so a
	// field added here changes the key of every request, including one that
	// never sets it. internal/response/cache owns that consequence and
	// answers for it by version, because a canonical type carries no
	// transport tag that could hide the field instead.
	OutputModalities []Modality
	// AudioOutput configures the spoken answer OutputModalities asks for.
	// Nil leaves the provider to choose, and a provider that requires a
	// voice refuses the turn itself rather than take a gateway default.
	AudioOutput   *AudioOutput
	Stream        bool
	StreamOptions StreamOptions
	User          string
	Extensions    map[string]json.RawMessage
	// DocumentParser names the extraction the caller asked for before a
	// model reads an attached document. The zero value asks for none.
	//
	// This field reaches the response cache key for the reason
	// OutputModalities above states: the key serializes this struct, and a
	// canonical type carries no transport tag that could hide a field. The
	// same bytes parsed by two engines are two different inputs, so the
	// key has to separate them. internal/response/cache answers for that by
	// version.
	DocumentParser DocumentParser
}

type ChatResponse struct {
	ID                string
	CreatedUnix       int64
	Model             string
	ModelUsed         string
	Choices           []Choice
	Usage             Usage
	SystemFingerprint string
}

type Choice struct {
	Index        int
	Message      Message
	FinishReason string
	LogProbs     []LogProb
}

type ChoiceDelta struct {
	Index     int
	Role      Role
	Text      string
	Reasoning string
	// Audio carries one chunk of a spoken answer. OpenRouter serves audio
	// output through streaming alone, so a caller that never reads this
	// field never receives the answer at all.
	Audio *AudioChunk
	// Media carries generated parts that arrive whole rather than in
	// pieces. An image is the case that forces the field: a provider sends
	// the finished picture in one delta, so there is nothing to accumulate
	// and nothing Text could hold. Audio is the other case and keeps its
	// own field, because a spoken answer does arrive in pieces.
	Media        []ContentPart
	ToolCalls    []ToolCall
	LogProbs     []LogProb
	FinishReason string
}

type ContentKind string

type ContentPart struct {
	Kind         ContentKind
	Text         string
	Image        *Image
	Audio        *Audio
	Document     *Document
	Video        *Video
	CacheControl string
}

type Document struct {
	URL      string
	Data     []byte
	Format   string
	Filename string

	// FileID names a stored document this gateway holds for the requesting
	// account. It is the only document reference the gateway can resolve
	// without leaving the deployment, and the only one whose bytes cannot
	// change under a cached answer: a stored file is written once and
	// deleted, never rewritten, and its identifier is never reused.
	FileID string
}

type DocumentParser struct {
	Engine ParserEngine
}

type Embedding struct {
	Index  int
	Vector []float32
}

type EmbeddingInput struct {
	Texts    []string
	TokenIDs [][]int
}

type EmbeddingRequest struct {
	Model          string
	Input          EmbeddingInput
	EncodingFormat string
	Dimensions     *int
	User           string
}

type EmbeddingResponse struct {
	Model string
	Data  []Embedding
	Usage Usage
}

type GeneratedImage struct {
	B64JSON string
	URL     string
	// RevisedPrompt is the prompt the provider actually rendered, when it
	// rewrote the one the caller sent.
	RevisedPrompt string
}

type Image struct {
	URL    string
	Detail string
}

type ImagesRequest struct {
	Model          string
	Prompt         string
	N              int
	Size           string
	Quality        string
	Style          string
	ResponseFormat string
	User           string
	// Image is the picture an edit starts from. An empty value means the
	// request is a generation.
	Image UploadedFile
	// Mask names the region of Image an edit may replace. It is meaningless
	// without Image.
	Mask UploadedFile
}

type ImagesResponse struct {
	Model       string
	CreatedUnix int64
	Images      []GeneratedImage
	Usage       Usage
}

type LogProb struct {
	Token string
	Value float64
	Bytes []int
	Top   []TopLogProb
}

type MediaUnits struct {
	// Images, Audio, Documents, and Videos count the parts of each kind.
	Images    int
	Audio     int
	Documents int
	Videos    int

	// InlineBytes totals the decoded bytes the request carries itself. A
	// part that names a remote reference adds nothing, because the gateway
	// never fetched the bytes behind it.
	InlineBytes int64
}

type Message struct {
	Role       Role
	Content    []ContentPart
	Reasoning  string
	Name       string
	ToolCalls  []ToolCall
	ToolCallID string
}

type Modality string

type ModerationCategory struct {
	// Name is the category name exactly as the provider states it.
	Name string
	// Flagged is the provider's own threshold decision for this category.
	Flagged bool
	// Score is how strongly the input matches the category. Providers
	// normalize it to the unit interval, and the gateway does not rescale it.
	Score float64
}

type ModerationRequest struct {
	Model string
	// Inputs is the list of texts to classify, in the order the caller
	// supplied. A result answers the input at the same position, so the order
	// is part of the request's meaning rather than a presentation detail.
	Inputs []string
}

type ModerationResponse struct {
	// ID is the provider's identifier for this classification, kept so the
	// wire answer a caller reads matches the record the provider holds.
	ID    string
	Model string
	// Results holds one result per request input, at the same position.
	Results []ModerationResult
	Usage   Usage
}

type ModerationResult struct {
	// Flagged reports whether any category flagged the input.
	Flagged bool
	// Categories holds one verdict per category, in the order the provider
	// stated them.
	Categories []ModerationCategory
}

type OutputFormat string

type ParserEngine string

type Reasoning struct {
	Effort    ReasoningEffort
	MaxTokens *int
	Exclude   bool
}

type ReasoningEffort string

type RecognitionRequest struct {
	Model string
	// Document is the whole document rather than one page. Splitting a
	// container into single-page documents needs a writer this gateway does
	// not carry, and a provider that reads a document reads its pages in
	// order anyway.
	Document UploadedFile
	// Pages is how many pages the native read counted. It travels because a
	// recognizer cannot otherwise tell a document that ended from an answer
	// that was cut short, and those two have to reach the caller differently.
	Pages int
}

type RecognitionResponse struct {
	Model string
	// Pages holds one entry per page the provider read, in page order.
	Pages []RecognizedPage
	Usage Usage
}

type RecognizedPage struct {
	// Number is the page's one-based position in the document.
	Number int
	// Text is what the recognizer read on that page. It is empty for a page
	// that held nothing, which is a real answer rather than a failure.
	Text string
}

type RerankRequest struct {
	Model string
	// Query is the text every document is scored against.
	Query string
	// Documents is the list to rank, in the order the caller supplied. A
	// result names a position in this slice, so its order is part of the
	// request's meaning rather than a presentation detail.
	Documents []string
	// TopN is how many results the caller wants back. Nil asks for all of
	// them. It is a request for fewer results rather than a page: a provider
	// scores every document either way and bills for every document either
	// way.
	TopN *int
	// MaxTokensPerDocument caps how much of each document the provider reads.
	// Nil leaves the provider's own default in place. A provider that exceeds
	// its cap either truncates the document or splits it into chunks it bills
	// separately, so the cap is a cost control as well as a size control.
	MaxTokensPerDocument *int
}

type RerankResponse struct {
	Model string
	// Results holds the scored documents in relevance order, highest first.
	// It is shorter than the request when the caller asked for fewer.
	Results []RerankResult
	Usage   Usage
}

type RerankResult struct {
	// Index is the document's position in the request that produced it.
	Index int
	// RelevanceScore is how well that document answers the query. Providers
	// normalize it to the unit interval, and the gateway does not rescale it.
	RelevanceScore float64
}

type Role string

type Sampling struct {
	Temperature      *float32
	TopP             *float32
	CandidateCount   *int
	MaxTokens        *int
	Stop             []string
	PresencePenalty  *float32
	FrequencyPenalty *float32
	LogitBias        map[string]int
	Seed             *int
}

type SpeechRequest struct {
	Model string
	Input string
	Voice string
	// ResponseFormat names the container the caller wants, such as mp3 or
	// wav. A provider decides the default when the caller states none.
	ResponseFormat string
	// Speed multiplies the delivery rate. A nil value means the provider
	// default, which is not the same as 0.
	Speed *float64
}

type SpeechResponse struct {
	Model string
	Audio []byte
	// ContentType is the media type the provider stated for Audio. The
	// gateway repeats it rather than deriving one, because the provider
	// encoded the file.
	ContentType string
	Usage       Usage
}

type StreamEvent struct {
	Kind              StreamEventKind
	ID                string
	CreatedUnix       int64
	Model             string
	ModelUsed         string
	SystemFingerprint string
	Deltas            []ChoiceDelta
	Usage             *Usage
}

type StreamEventKind string

type StreamOptions struct {
	IncludeUsage bool
}

type StructuredOutput struct {
	Format      OutputFormat
	Name        string
	Description string
	Schema      json.RawMessage
	Strict      bool
}

type Tool struct {
	Name        string
	Description string
	Parameters  json.RawMessage
}

type ToolCall struct {
	ID        string
	Name      string
	Arguments string
}

type ToolChoice struct {
	Mode ToolChoiceMode
	Name string
}

type ToolChoiceMode string

type TopLogProb struct {
	Token string
	Value float64
	Bytes []int
}

type TranscriptionRequest struct {
	Model string
	File  UploadedFile
	// Language names the language spoken in File, when the caller knows it.
	Language string
	// Prompt supplies vocabulary or context that helps the decoder.
	Prompt string
	// ResponseFormat names the transcript format, such as json, text, srt,
	// or vtt.
	ResponseFormat string
	// Temperature controls decoder sampling. A nil value means the provider
	// default, which is not the same as 0.
	Temperature *float64
	// Translate asks for an English transcript of speech in another
	// language. It selects the translation operation, which a provider
	// exposes at its own path, so it is a routing fact and not a hint.
	Translate bool
}

type TranscriptionResponse struct {
	Model string
	Text  string
	// Language is the language the provider detected, when it reported one.
	Language string
	// Duration is the length of the audio in seconds, when the provider
	// reported it.
	Duration float64
	Usage    Usage
}

type UploadedFile struct {
	// Filename is the name the caller gave the upload. A provider reads the
	// extension to pick a decoder, so an empty name loses information the
	// caller supplied.
	Filename string
	// MediaType is the content type the caller stated, when it stated one.
	MediaType string
	// Bytes is the decoded payload.
	Bytes []byte
}

type Usage struct {
	InputTokens      int
	OutputTokens     int
	TotalTokens      int
	ReasoningTokens  int
	CacheReadTokens  int
	CacheWriteTokens int

	// AudioInputTokens and AudioOutputTokens count the audio a provider
	// metered at its own rate. Both are already inside InputTokens and
	// OutputTokens, the way CacheReadTokens is: a cost that adds them again
	// rather than reclassifying them bills the same audio twice.
	AudioInputTokens  int
	AudioOutputTokens int
	// GeneratedImages counts the pictures the answer carries. It is the one
	// output unit no token total can describe, because a provider prices a
	// generated image per image and reports no tokens for it.
	GeneratedImages int
	// SearchUnits counts the units a rerank provider that bills by search
	// billed. One unit covers one query against a fixed number of documents,
	// and a longer document counts as several. No token total converts into
	// it, and the offering's own basis says whether to read this field or the
	// token counts beside it.
	SearchUnits int

	// Estimated marks counts the gateway synthesized with a tokenizer
	// because the provider reported no usage. Estimated counts never
	// appear on the wire as provider-reported facts; accounting records
	// carry the flag so operators can tell estimates from measurements.
	Estimated bool
}

type Video struct {
	URL    string
	Data   []byte
	Format string
}

type VideoJob struct {
	// ID is the Starport job identifier, and the only identifier a caller ever
	// sees for this work.
	ID string
	// Model is the catalog model identifier the job runs.
	Model string
	// Provider names who is running the work. A chat answer already reports
	// this, so a job answer reports it too.
	Provider string
	// State is the canonical job state word.
	State string
	// Reason states why a failed job produced no asset. It is empty for every
	// other state.
	Reason string
	// CreatedUnix is when Starport recorded the job.
	CreatedUnix int64
	// CompletedUnix is when the job reached a terminal state, or zero while it
	// has not.
	CompletedUnix int64
	// ExpiresUnix is when the retention window on the stored asset ends. It is
	// zero when this gateway holds no bytes for the job, which covers every job
	// that has not finished and every finished one whose bytes already went.
	//
	// A caller reads it to tell a video it can still fetch from one it cannot.
	// Without it the only way to ask is to fetch and read the refusal, which
	// spends a request per job to learn that a list of jobs is unplayable.
	ExpiresUnix int64
}

type VideoJobRequest struct {
	// Model is the catalog model identifier the caller asked for.
	Model string
	// Prompt describes the video to generate.
	Prompt string
	// NegativePrompt describes what to keep out of the result.
	NegativePrompt string
	// Size is the requested frame size, such as "1280x720".
	Size string
	// Seconds is the requested duration. It is a string because the two
	// published surfaces both send it as one, and a number would force a
	// guess at the unit.
	Seconds string
	// Seed makes a generation repeatable. It is a pointer because zero is a
	// seed a caller may ask for.
	Seed *int64
}