Skip to content
goloopPublic

About

A vendor-independent interface for AI model clients – the foundation on which goloop's AI drivers are built

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

17 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

deps.dev License License Stay with Ukraine

ai

ai is a small, provider-agnostic interface for talking to large language model APIs, plus the shared request and response types every provider driver speaks. It is the core that goloop's provider packages (anthropic, openai, gemini, and so on) build on.

Like the standard library's database/sql with its drivers, or log/slog with its handlers, this package holds the common contract while a separate package per provider implements it. A driver depends only on ai, so the whole set stays free of third-party dependencies.

Installation

go get github.com/goloop/ai

The interface

type Client interface {
	Generate(ctx context.Context, req *Request) (*Response, error)
	Stream(ctx context.Context, req *Request) iter.Seq2[Chunk, error]
}

Types

  • Role and Message (a role plus a list of content Part values).
  • Part: Text, Image (multimodal), ToolUse, ToolResult (tool calling).
  • Tool and ToolChoice for function calling.
  • Request (model, system, messages, tools, sampling knobs).
  • Format for structured output: ask for JSON, or JSON matching a schema.
  • Hosted for work the provider runs itself, such as web search, with Citation for the sources it came back with and HostedReport for whether it ran at all.
  • Response with Text(), JSON(&v), ToolCalls() and Citations() helpers; Chunk for streaming.
  • Usage for token counts; APIError for normalized provider errors.

Using a provider

import (
	"github.com/goloop/ai"
	"github.com/goloop/anthropic"
)

c := anthropic.New(os.Getenv("ANTHROPIC_API_KEY"))
resp, err := c.Generate(ctx, &ai.Request{
	Model:    anthropic.ModelClaude37SonnetLatest,
	Messages: []ai.Message{ai.UserText("Hello!")},
})

Any provider client is an ai.Client, so code written against the interface works with all of them, which makes multi-provider setups straightforward.

Plumbing for drivers

Drivers reuse the shared configuration and transport:

  • Options and functional options (WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithHeader), built with NewOptions.
  • Options.Do - an HTTP request with retries on 429 and 5xx.
  • SSEEvents - an iterator over Server-Sent Events data payloads.

Endpoints providers do not share (embeddings, images, audio, files, batches) are not part of the interface; each driver exposes them as native methods.

Documentation

Full reference: DOC.md (Ukrainian: DOC.UK.md).

License

MIT - see LICENSE.

Release v1.2.2

Preserve empty SSE data, cap Retry-After before converting to a duration, and avoid unnecessary text allocations.

About

A vendor-independent interface for AI model clients – the foundation on which goloop's AI drivers are built

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages