Documentation
¶
Overview ¶
Package gpt is the OpenAI provider for neui. Build one with New and hand it to neui.WithProvider or neui.OptionProvider:
p, err := gpt.New(gpt.Conf{Model: gpt.GPT56Luna}, gpt.WithReasoningEffort(gpt.EffortHigh))
if err != nil {
return err
}
neui.Enable(ctx, neui.OptionProvider(p))
The key is read from OPENAI_API_KEY unless WithAPIKey sets one. Model and settings are fixed per Provider, so the same model at two efforts is two Providers. It speaks the Responses API rather than Chat Completions, because only Responses carries reasoning across turns.
Index ¶
- Variables
- type APIError
- type CacheMode
- type CacheTTL
- type Conf
- type Effort
- type Option
- func WithAPIKey(key string) Option
- func WithBaseURL(base string) Option
- func WithHTTPClient(client *http.Client) Option
- func WithInclude(values ...string) Option
- func WithMaxTokens(n int) Option
- func WithMetadata(m map[string]string) Option
- func WithObfuscation(on bool) Option
- func WithOrganization(id string) Option
- func WithParallelToolCalls(ok bool) Option
- func WithProject(id string) Option
- func WithPromptCacheKey(key string) Option
- func WithPromptCacheOptions(mode CacheMode, ttl CacheTTL) Option
- func WithReasoningContext(context ReasoningContext) Option
- func WithReasoningEffort(effort Effort) Option
- func WithReasoningMode(mode ReasoningMode) Option
- func WithReasoningReplay(mode ReplayMode) Option
- func WithReasoningSummary(summary Summary) Option
- func WithServiceTier(tier ServiceTier) Option
- func WithStore(store bool) Option
- func WithStrictTools(strict bool) Option
- func WithTemperature(v float64) Option
- func WithTopP(v float64) Option
- func WithTransport(opt lib.Options) Option
- func WithVerbosity(verbosity Verbosity) Option
- type Provider
- type ReasoningContext
- type ReasoningMode
- type ReplayMode
- type ServiceTier
- type Summary
- type Verbosity
Constants ¶
This section is empty.
Variables ¶
var ( GPT56Sol = api.Model{Name: "gpt-5.6-sol", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: imageSide, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} GPT56Luna = api.Model{Name: "gpt-5.6-luna", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: imageSide, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} GPT6Astra = api.Model{Name: "gpt-6-astra", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: 65_535, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} GPT6Sol = api.Model{Name: "gpt-6-sol", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: imageSide, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} GPT6Luna = api.Model{Name: "gpt-6-luna", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: imageSide, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} GPT61Sol = api.Model{Name: "gpt-6.1-sol", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: imageSide, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} GPT61Terra = api.Model{Name: "gpt-6.1-terra", Context: 1_050_000, ImagePixels: imagePixels, ImageSide: imageSide, ImageBytes: imageBytes, ImagesPerRequest: 1500, RequestBytes: requestBytes} )
The current OpenAI models for Conf.Model, with their published limits (read 2026-11-06): a 1,050,000-token context window, of which at most 922,000 tokens are input; 1,500 images and 512 MB per request. The input_file parts of one request share a separate 50 MB, which api.Model has no field for. Images are sent at detail "high", which fits an image within 2,500 patches of 32x32 pixels and, on gpt-5.6, 2048 pixels a side; gpt-6-astra allows a side of 65,535. The other models publish no sizing of their own and are declared at the gpt-5.6 limits. No byte limit is published for an image in a message; an image in a tool result is a data URL of at most 20,971,520 characters, and ImageBytes is the raw size that encodes to it, so one value covers both places. Each takes at most 128,000 output tokens, which WithMaxTokens is checked against. For a gateway-prefixed id such as "openai/gpt-6-sol" or a newer model, declare your own api.Model.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
Status int // HTTP status; 0 when the failure arrived inside the stream
NoRetry bool // the response said x-should-retry: false; HTTP failures only
Type string // the service's error type, such as "invalid_request_error"
Code string // the service's error code, or the incomplete_details reason
Param string // the request parameter the error is about, if any
Message string // the service's message; a non-JSON body trimmed to 512 runes; or this adapter's description when the service gave none
RequestID string // the x-request-id header, which OpenAI support asks for; HTTP failures only
}
APIError describes a failed turn: an HTTP status before the stream started, an error or failed frame inside it, or a response the service ended as incomplete, filtered, refused or cancelled. It is the Err of an api.EventErr, or wrapped in it after a 413 measured against Model.RequestBytes; branch on EventErr.Code and get the details with errors.As, for logs and bug reports.
type CacheMode ¶
type CacheMode string
CacheMode is a prompt_cache_options.mode value for WithPromptCacheOptions. Any string passes through.
type CacheTTL ¶
type CacheTTL string
CacheTTL is a prompt_cache_options.ttl value for WithPromptCacheOptions. Any string passes through.
type Conf ¶
type Conf struct {
Model api.Model // the one model this provider streams with, spelled as it goes on the wire
}
Conf holds what every Provider needs. Without Model.Name New returns an error. Use one of the models in this package, such as GPT56Luna, or an api.Model of your own for a gateway or a newer id.
type Effort ¶
type Effort string
Effort is a reasoning.effort value for WithReasoningEffort. Any string passes through, so a value newer than these constants works too.
type Option ¶
Option configures a Provider in New. Every option has a working default.
func WithAPIKey ¶
WithAPIKey sets the key, and OPENAI_API_KEY is then not read. An empty key sends no Authorization header, for a gateway that authenticates some other way.
func WithBaseURL ¶
WithBaseURL points the adapter at something other than api.openai.com: a gateway, a proxy, or a test server. The path "/responses" is appended, so pass the part that ends in "/v1".
func WithHTTPClient ¶
WithHTTPClient supplies the client. Leave Timeout at zero: it bounds the whole exchange including the streamed body and will cut a healthy long turn.
func WithInclude ¶
WithInclude replaces the include list. Without it, or with a nil list as WithInclude() gives, known reasoning models (see New) are sent "reasoning.encrypted_content", which older models need for reasoning replay; keep it in a list of your own, and pass it for any other model that reasons. Leaving it out while store is off drops reasoning from replay.
func WithMaxTokens ¶
WithMaxTokens caps the response, reasoning included, so on a reasoning model a small cap can leave no room for the answer. Zero, the default, sends no cap. A negative value and values from 1 to 15, below the API minimum, are rejected, and so is a value over 128,000 when Conf.Model is one of the models declared in this package, which take no more.
func WithMetadata ¶
WithMetadata sends m as metadata on every turn. The service takes up to sixteen pairs; the count is not checked here. m is kept, not copied, so do not change it afterwards.
func WithObfuscation ¶
WithObfuscation sets whether the service adds its random padding field to delta events to even out packet sizes. Off by default; turning it on costs only bandwidth.
func WithOrganization ¶
WithOrganization sends the OpenAI-Organization header, for a key that belongs to several organizations.
func WithParallelToolCalls ¶
WithParallelToolCalls allows or forbids more than one tool call per turn. The service allows it unless told otherwise.
func WithProject ¶
WithProject sends the OpenAI-Project header, for a key that spans several projects.
func WithPromptCacheKey ¶
WithPromptCacheKey steers cache routing for requests sharing a long prefix. OpenAI's prompt-caching guide asks for about fifteen requests a minute per key across all prefixes; above that, requests overflow to other machines and miss the cache.
func WithPromptCacheOptions ¶
WithPromptCacheOptions sets prompt_cache_options. Use it only with gpt-5.6 and later; earlier models answer 400. Prefer CacheImplicit: CacheExplicit expects per-block cache breakpoints, which this provider does not place.
func WithReasoningContext ¶
func WithReasoningContext(context ReasoningContext) Option
WithReasoningContext sets reasoning.context: auto, current_turn or all_turns. all_turns only does anything if the earlier reasoning items are actually in the request, which here means WithReasoningReplay is not ReplayNever.
func WithReasoningEffort ¶
WithReasoningEffort sets reasoning.effort. Accepted values differ per model. When Conf.Model is one of the models declared in this package, the values its docs leave out are rejected: EffortMinimal on all of them, and EffortNone on gpt-6-astra and gpt-6.1-sol. For any other model nothing is checked, and an unsupported value fails the turn with a 400.
func WithReasoningMode ¶
func WithReasoningMode(mode ReasoningMode) Option
WithReasoningMode sets reasoning.mode, standard or pro, for the gpt-5.6 and gpt-6 families.
func WithReasoningReplay ¶
func WithReasoningReplay(mode ReplayMode) Option
WithReasoningReplay picks which reasoning items go back on later turns.
func WithReasoningSummary ¶
WithReasoningSummary asks for readable reasoning summaries, which arrive as EventSummary and fill ContentReasoning.Summary. Off by default, so Summary stays empty. Recent models require a verified organization and answer 400 otherwise.
func WithServiceTier ¶
func WithServiceTier(tier ServiceTier) Option
WithServiceTier sets service_tier. Under TierFlex a turn fails with CodeBusy when there is no spare capacity, the same as a rate limit; back off and retry.
func WithStore ¶
WithStore sets whether the service retains responses server-side. Off by default; this provider resends the whole thread each turn and needs nothing stored. With it on, reasoning items without encrypted content replay by id for as long as the service keeps the response.
func WithStrictTools ¶
WithStrictTools sets the strict flag on every tool. Unset, the service makes schemas strict where it can. True fails the turn with a 400 unless every object in each tool schema has additionalProperties:false and lists every property in required.
func WithTemperature ¶
WithTemperature sets the sampling temperature, 0 to 2. New refuses it on a known reasoning model (see New) unless the reasoning effort is EffortNone.
func WithTopP ¶
WithTopP sets nucleus sampling, 0 to 1. Like WithTemperature, New refuses it on a known reasoning model unless the reasoning effort is EffortNone.
func WithTransport ¶
WithTransport sets the stream limits documented on lib.Options: how long the connection may stay silent and how large one frame may grow. A zero field keeps lib's default. The idle limit cannot be turned off, only raised; a turn that crosses it fails with CodeNetwork.
func WithVerbosity ¶
WithVerbosity sets text.verbosity: low, medium or high.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is an api.Provider for one OpenAI model. It is safe for concurrent use by any number of sessions.
func New ¶
New builds a Provider. A nil option is skipped; an option with an invalid value, or one the declared model does not take, makes New return its error, as does an empty Conf.Model.Name. So do WithTemperature or WithTopP on a known reasoning model, one whose Name is exactly that of a model declared in this package, unless the reasoning effort is EffortNone. Any other id is unknown: New checks no combination for it and every option is sent as configured, so what the model refuses fails the turn. Without WithAPIKey, New reads the key from OPENAI_API_KEY once. If that is empty, it logs a warning and requests carry no Authorization header, which api.openai.com refuses with CodeAccess.
func (*Provider) Stream ¶
Stream sends one turn and streams its events as api.Provider describes; read until the channel closes or cancel ctx. A request that cannot be built, such as one with a tool that has no name, ends at once with CodeInvalid, and one larger than a nonzero Model.RequestBytes with CodeTooLarge. A failure the service reports arrives as an EventErr whose Err is or wraps an *APIError.
type ReasoningContext ¶
type ReasoningContext string
ReasoningContext is a reasoning.context value for WithReasoningContext. Any string passes through.
const ( // ContextAuto lets the service decide which earlier reasoning to use. ContextAuto ReasoningContext = "auto" // ContextCurrentTurn uses only the reasoning of the current turn. ContextCurrentTurn ReasoningContext = "current_turn" // ContextAllTurns uses the replayed reasoning of earlier turns too. ContextAllTurns ReasoningContext = "all_turns" )
ReasoningContext values.
type ReasoningMode ¶
type ReasoningMode string
ReasoningMode is a reasoning.mode value for WithReasoningMode. Any string passes through.
const ( ReasoningStandard ReasoningMode = "standard" ReasoningPro ReasoningMode = "pro" )
ReasoningMode values.
type ReplayMode ¶
type ReplayMode int
ReplayMode says which earlier reasoning items are sent back on later turns; set it with WithReasoningReplay. The default, ReplayToolTurns, suits every reasoning model the service documents.
const ( // ReplayToolTurns replays a reasoning item when a tool call follows it in // the same message, with any preamble or commentary messages in between; // the case the service requires. Default. ReplayToolTurns ReplayMode = iota // ReplayAlways replays every reasoning item that has an item after it in // the same message, including one before a text answer. If the service // rejects that pairing, every multi-turn conversation fails with a 400. ReplayAlways // ReplayNever sends no reasoning items back; tool calls and results still // travel. Use it for a model or gateway that rejects reasoning input // ("Reasoning input items can only be provided to a reasoning or computer // use model"). It costs quality on tool loops. ReplayNever )
type ServiceTier ¶
type ServiceTier string
ServiceTier is a service_tier value for WithServiceTier. Any string passes through.
const ( TierAuto ServiceTier = "auto" TierDefault ServiceTier = "default" TierFlex ServiceTier = "flex" TierScale ServiceTier = "scale" TierPriority ServiceTier = "priority" TierFast ServiceTier = "fast" TierUltrafast ServiceTier = "ultrafast" )
ServiceTier values. TierFlex is cheaper and slower; TierPriority is faster and costs more, and TierFast asks for the same processing, which the response reports as priority. TierUltrafast is access-controlled and, as of 2026-11-05, offered only on gpt-5.6-sol.