golato

README

[!WARNING] Golato is still being churned. The recipe is in progress, and nothing is promised yet.

golato

golato is a small, embeddable generation, embedding, and agent runtime library for Go.

Use its generation package for direct streamed generation, its embedding package for atomic vector requests, or its Agent runtime for tool-using workflows. The host application keeps ownership of persistence, tenancy, retrieval, and product policy.

Why golato?

See the project description.

Install

go get github.com/yongtenglei/golato@v0.2.0

Generation stream

apiKey := os.Getenv("OPENAI_API_KEY")
if apiKey == "" {
    return errors.New("OPENAI_API_KEY is required")
}
model := os.Getenv("OPENAI_MODEL")
if model == "" {
    return errors.New("OPENAI_MODEL is required")
}

generator, err := openai.NewGenerator(openai.GeneratorConfig{
    EndpointConfig: openai.EndpointConfig{
        APIKey:  apiKey,
        BaseURL: os.Getenv("OPENAI_BASE_URL"),
    },
    Provider: "openai",
})
if err != nil {
    return err
}

stream, err := generator.Stream(ctx, generation.Request{
    Model: model,
    Messages: []message.Message{
        message.NewUserMessage("What can you help me with?"),
    },
})
if err != nil {
    return err
}

var final message.AssistantMessage
for event := range stream.Events() {
    switch event := event.(type) {
    case generation.TextDeltaEvent:
        fmt.Fprint(os.Stderr, event.Delta)
    case generation.DoneEvent:
        final = event.Message
    case generation.ErrorEvent:
        return event.Err
    }
}
fmt.Fprintln(os.Stderr)
fmt.Println(final.Text())

Streamed deltas are provisional. generation.DoneEvent.Message is the authoritative terminal assistant message.

Embeddings

Embedding is independent of Agent. One Embed call submits its complete input batch through the configured HTTP client once; Golato does not split or retry the batch, and redirect behavior remains part of that client's policy. Successful response bodies are limited to 16 MiB and return raw float64 vectors in input order.

embedder, err := openai.NewEmbedder(openai.EndpointConfig{
    APIKey:  apiKey,
    BaseURL: os.Getenv("OPENAI_BASE_URL"),
})
if err != nil {
    return err
}

response, err := embedder.Embed(ctx, embedding.Request{
    Model:  os.Getenv("OPENAI_EMBEDDING_MODEL"),
    Inputs: []string{"first input", "second input"},
})
if err != nil {
    return err
}
fmt.Println(response.Vectors)

Agent

An Agent is immutable and can run concurrently. It adds an execution lifecycle and a tool loop on top of a Generator. Without tools, it runs as plain chat.

chatAgent, err := agent.New(agent.Config{
    Generator: generator,
    Model:     model,
})
if err != nil {
    return err
}

run, err := chatAgent.Start(ctx, agent.Input{
    Prompts: []message.UserMessage{
        message.NewUserMessage("What can you help me with?"),
    },
})
if err != nil {
    return err
}

result, err := run.Wait()
if err != nil {
    return err
}
fmt.Println(result.Final.Text())

See examples/basic for the complete tool-driven dessert conversation.

Configure the environment:

export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.example.com/v1 # optional
export OPENAI_MODEL=gpt-4o-mini

Run the example locally from the repository root:

go run ./examples/basic

Or run it directly from the v0.2.0 release:

go run github.com/yongtenglei/golato/examples/basic@v0.2.0

Compaction

Compaction is optional and stateless. It is useful for long-running conversations approaching a model's context window. Before a model call, it can summarize older complete turns while preserving recent ones. Golato returns the resulting context and compaction records to the host; it does not persist them.

Development

make test
make check

Install the worktree-friendly pre-push hook with make hooks.

License

Except for the Golato logo, this repository is licensed under the MIT License. The Golato logo is © 2026 liuzi. All rights reserved.