Document every exported symbol and how callers use the library.

Co-authored-by: Cursor <cursoragent@cursor.com>

client.go

@@ -13,37 +13,50 @@ import (
 	"strings"
 )
 
-// Adapter is which native protocol the Client speaks.
+// Adapter selects the wire protocol a Client speaks.
+// [AdapterOpenAI] uses POST /v1/chat/completions and GET /v1/models.
+// [AdapterOllama] uses POST /api/chat and GET /api/tags.
 type Adapter string
 
 const (
+	// AdapterOpenAI selects the OpenAI-compatible protocol.
 	AdapterOpenAI Adapter = "openai"
+	// AdapterOllama selects the Ollama native protocol.
 	AdapterOllama Adapter = "ollama"
 )
 
-// Role is a Message role.
+// Role is the speaker of one Message.
 type Role string
 
 const (
-	RoleSystem    Role = "system"
-	RoleUser      Role = "user"
+	// RoleSystem is a system instruction.
+	RoleSystem Role = "system"
+	// RoleUser is the caller's turn.
+	RoleUser Role = "user"
+	// RoleAssistant is a previous model turn.
 	RoleAssistant Role = "assistant"
 )
 
-// Message is one chat turn.
+// Message is one chat turn. Role and Content are sent unchanged.
 type Message struct {
 	Role    Role
 	Content string
 }
 
-// Options are Chat/Stream parameters. Temperature and MaxTokens are omitted when nil.
+// Options configures one Chat or Stream call.
+// Model is the server-side model name. The Client does not check that it is
+// set; the server rejects an empty model.
+// A nil Temperature or MaxTokens is left out of the request.
+// On [AdapterOllama], MaxTokens is sent as num_predict.
 type Options struct {
 	Model       string
 	Temperature *float64
 	MaxTokens   *int
 }
 
-// Client is a configured caller bound to one Adapter, base URL, and optional API key.
+// Client calls one Adapter at one base URL.
+// An empty API key sends no Authorization header.
+// A non-empty key is sent as a Bearer token on every request.
 type Client struct {
 	adapter Adapter
 	baseURL string
@@ -51,7 +64,10 @@ type Client struct {
 	http    *http.Client
 }
 
-// NewClient validates Adapter and base URL. apiKey may be empty.
+// NewClient checks adapter and baseURL.
+// It returns an error when adapter is not [AdapterOpenAI] or [AdapterOllama],
+// or when baseURL is empty or only whitespace.
+// A trailing slash on baseURL is removed. apiKey may be empty.
 func NewClient(adapter Adapter, baseURL, apiKey string) (*Client, error) {
 	switch adapter {
 	case AdapterOpenAI, AdapterOllama:
@@ -65,7 +81,10 @@ func NewClient(adapter Adapter, baseURL, apiKey string) (*Client, error) {
 	return &Client{adapter: adapter, baseURL: base, apiKey: apiKey, http: http.DefaultClient}, nil
 }
 
-// Chat returns the assistant text for messages.
+// Chat sends messages and returns the assistant text.
+// It returns an error when ctx is canceled, the HTTP status is not 2xx,
+// the body cannot be decoded, or an OpenAI response contains no choices.
+// An HTTP failure includes a short prefix of the response body.
 func (c *Client) Chat(ctx context.Context, messages []Message, opt Options) (string, error) {
 	switch c.adapter {
 	case AdapterOpenAI:
@@ -77,7 +96,13 @@ func (c *Client) Chat(ctx context.Context, messages []Message, opt Options) (str
 	}
 }
 
-// Stream yields assistant text chunks for the same Chat request.
+// Stream sends the same request as Chat with streaming enabled and calls
+// yield for each non-empty text chunk, in order.
+// It returns the error from yield.
+// It also returns an error when ctx is canceled, the HTTP status is not 2xx,
+// or a stream line cannot be decoded.
+// [AdapterOpenAI] ends the stream when a data line is the token DONE.
+// [AdapterOllama] reads one JSON object per line and yields message content.
 func (c *Client) Stream(ctx context.Context, messages []Message, opt Options, yield func(chunk string) error) error {
 	switch c.adapter {
 	case AdapterOpenAI:
@@ -89,7 +114,11 @@ func (c *Client) Stream(ctx context.Context, messages []Message, opt Options, yi
 	}
 }
 
-// ListModels returns server-side Model names.
+// ListModels returns model names reported by the server.
+// [AdapterOpenAI] reads data[].id from GET /v1/models.
+// [AdapterOllama] reads models[].name from GET /api/tags.
+// It returns an error when ctx is canceled, the HTTP status is not 2xx,
+// or the body cannot be decoded. Empty names are omitted.
 func (c *Client) ListModels(ctx context.Context) ([]string, error) {
 	switch c.adapter {
 	case AdapterOpenAI: