Thinking in skyl

1. There is a seam, and it is four methods#

Everything in skyl exists to serve one interface.

type Provider interface {
	Name() string
	Complete(ctx context.Context, req *Request) (*Response, error)
	Stream(ctx context.Context, req *Request) (Stream, error)
	Models(ctx context.Context) ([]ModelInfo, error)
}

type Provider interface {
	Name() string
	Complete(ctx context.Context, req *Request) (*Response, error)
	Stream(ctx context.Context, req *Request) (Stream, error)
	Models(ctx context.Context) ([]ModelInfo, error)
}

An adapter's whole job is translating a *Request into a vendor call, and the vendor's reply back into a *Response. That is all. It does not retry, it does not validate, it does not time out.

The interface is small on purpose. It is easy to implement — an adapter in your own repository is a first-class citizen — easy to fake in tests, and easy to wrap.

2. Everything cross-cutting lives in Client#

Client wraps a Provider and adds request validation, retry with jittered backoff, per-attempt timeouts, and hooks.

Keeping those in Client rather than in each adapter means retry logic is written and tested once, not once per vendor — and a new adapter, including one you write, gets production-grade behaviour for free.

// The provider knows how to talk to OpenAI. The client knows how to be
// reliable. Neither knows the other's job.
client := skyl.New(
	openai.New(key),
	skyl.WithMaxRetries(5),
	skyl.WithTimeout(90*time.Second),
)

// The provider knows how to talk to OpenAI. The client knows how to be
// reliable. Neither knows the other's job.
client := skyl.New(
	openai.New(key),
	skyl.WithMaxRetries(5),
	skyl.WithTimeout(90*time.Second),
)

If you want the raw provider without any of that, it is one call away:

raw := client.Provider() // no retry, no validation, no hooks

raw := client.Provider() // no retry, no validation, no hooks

3. A message is a list of parts#

The hardest design problem in a multi-provider library is representing a message, because vendors disagree. OpenAI historically used a flat content string; Anthropic uses typed content blocks; Gemini uses parts under contents and calls the assistant role model.

skyl models the superset:

type Message struct {
	Role  Role
	Parts []Part
}

type Message struct {
	Role  Role
	Parts []Part
}

Part is a closed interface — it has an unexported marker method, so only skyl can implement it. The four implementations are Text, Image, ToolCall and ToolResult.

Flattening to a simpler vendor shape is lossless for the common case and explicit where it is not: an adapter that cannot represent a part returns ErrUnsupported naming the part, rather than silently dropping it.

4. There is no system role#

req := &skyl.Request{
	System:   "You are a terse Go expert.",   // ← a field, not a message
	Messages: []skyl.Message{skyl.UserText("What is a nil map?")},
}

req := &skyl.Request{
	System:   "You are a terse Go expert.",   // ← a field, not a message
	Messages: []skyl.Message{skyl.UserText("What is a nil map?")},
}

The roles are user, assistant and tool. System prompts live on Request.System because providers place them in three different locations — a top-level parameter for Anthropic, a leading message for OpenAI, systemInstruction for Gemini. Making it a field means skyl can put it where each provider expects, instead of you knowing which.

5. The abstraction is always escapable#

Every abstraction over a fast-moving API is wrong somewhere. If skyl's Request cannot express what you need, skyl must not be the reason you cannot ship.

Two hatches, always present:

// Send something skyl does not model. Your values override anything skyl set.
req.ProviderOptions = map[string]any{"top_k": 40}

// Read something skyl does not model. Raw is ALWAYS populated.
var full map[string]any
json.Unmarshal(resp.Raw, &full)

// Send something skyl does not model. Your values override anything skyl set.
req.ProviderOptions = map[string]any{"top_k": 40}

// Read something skyl does not model. Raw is ALWAYS populated.
var full map[string]any
json.Unmarshal(resp.Raw, &full)

You should never have to fork skyl to use a provider feature. If you do, that is a bug worth reporting.

6. Model IDs are opaque strings#

skyl ships no model constants and validates nothing against a list.

A curated enum guarantees that sooner or later skyl rejects a model you are entitled to use, because it shipped last Tuesday and skyl has not cut a release. Pass-through is correct forever. The trade is that a typo costs you a round trip instead of a compile error.