nabugate

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: MIT Imports: 8 Imported by: 0

README

nabugate-go

Official Go client for NabuGate, the organisation's OpenAI-compatible AI gateway. Projects call NabuGate with an alias such as nabu-fast; the gateway picks the provider, falls back on failure, holds the secrets and meters the cost.

go get github.com/nabuxai/nabugate-go

Use

client := nabugate.New(os.Getenv("NABUGATE_API_KEY"))

text, err := client.CompleteText(ctx, nabugate.ChatRequest{
    Model:    "nabu-fast",
    Messages: []nabugate.Message{nabugate.Text("user", "Summarise this quarter.")},
})

// Streaming
err = client.StreamText(ctx, nabugate.ChatRequest{
    Messages: []nabugate.Message{nabugate.Text("user", "Write a haiku.")},
}, func(delta string) error {
    fmt.Print(delta)
    return nil
})

// Embeddings — pin Dimensions whenever you store the vectors
vectors, err := client.Embeddings(ctx, nabugate.EmbeddingsRequest{
    Model: "write-embed", Input: []string{"a", "b"}, Dimensions: nabugate.Int(1536),
})

// Images, speech, catalogue
image, err := client.Images(ctx, nabugate.ImageRequest{Prompt: "a lighthouse at dusk"})
audio, err := client.Speech(ctx, nabugate.SpeechRequest{Input: "Welcome back."})
models, err := client.Models(ctx)

Sub-agents

A named assistant is called exactly like a model — set Model to its name.

Everything passes through

The gateway forwards request bodies to the provider untouched. ChatRequest names the common fields and carries an Extra map for everything else, so a new provider parameter needs no release of this package:

req := nabugate.ChatRequest{
    Messages: messages,
    Tools:    []any{tool},
    Extra: map[string]any{
        "response_format":   map[string]string{"type": "json_object"},
        "frequency_penalty": 0.5,
    },
}

Options

New takes WithBaseURL, WithDefaultModel, WithHTTPClient and WithHeader. There is no client-level timeout — streams are long-lived by design, so pass a deadline on the context when you want one.

Failures return *nabugate.Error carrying StatusCode and Body.

MIT licensed.

Documentation

Overview

Package nabugate is the official Go client for NabuGate, the OpenAI-compatible AI gateway.

The gateway passes request bodies through to the upstream provider untouched, so requests here carry an Extra map alongside the typed fields. Anything put in Extra reaches the provider as-is, which means a new provider parameter needs no release of this package.

Index

Constants

View Source 
const DefaultBaseURL = "https://gate.nabuxai.com/v1"

DefaultBaseURL is the hosted gateway.

Variables

This section is empty.

Functions

func Float 

func Float(v float64) *float64

Float is a helper for the optional float fields.

func Int 

func Int(v int) *int

Int is a helper for the optional int fields.

Types

type ChatRequest 

type ChatRequest struct {
	Model       string    `json:"model,omitempty"`
	Messages    []Message `json:"messages"`
	Temperature *float64  `json:"temperature,omitempty"`
	MaxTokens   *int      `json:"max_tokens,omitempty"`
	TopP        *float64  `json:"top_p,omitempty"`
	Stop        []string  `json:"stop,omitempty"`
	Seed        *int      `json:"seed,omitempty"`
	Tools       []any     `json:"tools,omitempty"`
	ToolChoice  any       `json:"tool_choice,omitempty"`
	// ConversationID asks the gateway to replay a stored conversation.
	ConversationID string `json:"conversation_id,omitempty"`

	// Extra carries any parameter this struct does not name. It is merged into
	// the request body, so response_format, penalties and provider-specific
	// flags all work without a change here.
	Extra map[string]any `json:"-"`
}

ChatRequest is a chat completion request.

type ChatResponse 

type ChatResponse struct {
	ID      string   `json:"id"`
	Model   string   `json:"model"`
	Choices []Choice `json:"choices"`
	Usage   Usage    `json:"usage"`
}

ChatResponse is a chat completion response.

func (*ChatResponse) Text 

func (r *ChatResponse) Text() string

Text returns the first choice's content when it is a plain string.

type Choice 

type Choice struct {
	Index        int     `json:"index"`
	Message      Message `json:"message"`
	FinishReason string  `json:"finish_reason"`
}

Choice is one completion alternative.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client talks to a NabuGate deployment.

func New 

func New(apiKey string, opts ...Option) *Client

New builds a client. The only required input is the gateway API key.

func (*Client) Chat 

func (c *Client) Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)

Chat performs a chat completion.

func (*Client) CompleteText 

func (c *Client) CompleteText(ctx context.Context, req ChatRequest) (string, error)

CompleteText performs a chat completion and returns only the text.

func (*Client) Embeddings 

func (c *Client) Embeddings(ctx context.Context, req EmbeddingsRequest) (*EmbeddingsResponse, error)

Embeddings creates embeddings.

func (*Client) Images 

func (c *Client) Images(ctx context.Context, req ImageRequest) (*ImageResponse, error)

Images generates images.

func (*Client) Models 

func (c *Client) Models(ctx context.Context) ([]Model, error)

Models lists every model, alias and agent this key may call.

func (*Client) Speech 

func (c *Client) Speech(ctx context.Context, req SpeechRequest) ([]byte, error)

Speech synthesises speech and returns the raw audio bytes.

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, req ChatRequest, onChunk func(StreamChunk) error) error

Stream performs a streaming chat completion, calling onChunk for each event. Returning an error from onChunk stops the stream and is returned to the caller.

func (*Client) StreamText 

func (c *Client) StreamText(ctx context.Context, req ChatRequest, onText func(string) error) error

StreamText is Stream reduced to text deltas.

func (*Client) Usage 

func (c *Client) Usage(ctx context.Context) (map[string]any, error)

Usage returns token and cost usage for this key.

type EmbeddingsRequest 

type EmbeddingsRequest struct {
	Model string `json:"model,omitempty"`
	// Input is a string or a []string.
	Input any `json:"input"`
	// Dimensions pins the vector width. Set it whenever the vectors are being
	// stored: a fixed-width column cannot accept whatever the provider defaults
	// to. Leave it nil for ad-hoc search, since providers without the field
	// reject it.
	Dimensions *int `json:"dimensions,omitempty"`
}

EmbeddingsRequest asks for vectors.

type EmbeddingsResponse 

type EmbeddingsResponse struct {
	Model string `json:"model"`
	Data  []struct {
		Index     int       `json:"index"`
		Embedding []float64 `json:"embedding"`
	} `json:"data"`
	Usage Usage `json:"usage"`
}

EmbeddingsResponse holds the vectors.

type Error 

type Error struct {
	StatusCode int
	Body       string
}

Error is a non-2xx response from the gateway.

func (*Error) Error 

func (e *Error) Error() string

type ImageRequest 

type ImageRequest struct {
	Model  string `json:"model,omitempty"`
	Prompt string `json:"prompt"`
	N      int    `json:"n,omitempty"`
	Size   string `json:"size,omitempty"`
}

ImageRequest asks for generated images.

type ImageResponse 

type ImageResponse struct {
	Created int64 `json:"created"`
	Data    []struct {
		B64JSON       string `json:"b64_json"`
		URL           string `json:"url"`
		RevisedPrompt string `json:"revised_prompt"`
	} `json:"data"`
}

ImageResponse holds the generated images, base64-encoded.

type Message 

type Message struct {
	Role       string `json:"role"`
	Content    any    `json:"content"`
	Name       string `json:"name,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty"`
	ToolCalls  []any  `json:"tool_calls,omitempty"`
}

Message is one chat message. Content is typed as any so multimodal parts and tool results pass through unchanged.

func Text 

func Text(role, content string) Message

Text builds a plain text message.

type Model 

type Model struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	OwnedBy string `json:"owned_by"`
}

Model describes an entry in the gateway catalogue.

type Option 

type Option func(*Client)

Option customises a Client.

func WithBaseURL 

func WithBaseURL(url string) Option

WithBaseURL points the client at a different gateway deployment.

func WithDefaultModel 

func WithDefaultModel(model string) Option

WithDefaultModel sets the alias or agent used when a request names none.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a pre-configured HTTP client (proxies, tracing).

func WithHeader 

func WithHeader(key, value string) Option

WithHeader adds a header to every request, e.g. a project identifier.

type SpeechRequest 

type SpeechRequest struct {
	Model          string  `json:"model,omitempty"`
	Input          string  `json:"input"`
	Voice          string  `json:"voice,omitempty"`
	ResponseFormat string  `json:"response_format,omitempty"`
	Speed          float64 `json:"speed,omitempty"`
}

SpeechRequest asks for synthesised speech.

type StreamChunk 

type StreamChunk struct {
	ID      string `json:"id"`
	Model   string `json:"model"`
	Choices []struct {
		Index int `json:"index"`
		Delta struct {
			Role      string `json:"role"`
			Content   string `json:"content"`
			ToolCalls []any  `json:"tool_calls"`
		} `json:"delta"`
		FinishReason *string `json:"finish_reason"`
	} `json:"choices"`
}

StreamChunk is one server-sent event from a streaming completion.

type Usage 

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

Usage reports token consumption.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.