package model

import (
	"context"
	"errors"
)

// Errors returned by the model package. Each is wrapped with %w on the way out
// so callers can test for a category while keeping the underlying cause.
var (
	// ErrNoModel is returned when no model name can be resolved.
	ErrNoModel = errors.New("model: no model configured")
	// ErrNoSteps is returned when a fallback chain has no steps.
	ErrNoSteps = errors.New("model: empty fallback chain")
	// ErrUpstream is returned when the provider request fails (network, status,
	// decode) or every fallback step fails.
	ErrUpstream = errors.New("model: upstream request failed")
	// ErrBadRequest is returned when the request cannot be encoded for the wire.
	ErrBadRequest = errors.New("model: invalid request")
	// ErrStream is returned when a stream ends before completion.
	ErrStream = errors.New("model: stream closed before completion")
)

// Recorder receives a CallRecord after a successfully completed LLM call. It is
// invoked by adapters so the runtime (M9 monitor/frontend) can collect usage
// without coupling to a storage backend.
type Recorder func(CallRecord)

// Adapter abstracts a single LLM provider. Implementations are vendor-specific
// but speak the normalized Request/Response vocabulary; a fallback Chain or a
// Router can compose them without knowing which provider is behind each one.
type Adapter interface {
	// Name returns a stable identifier for the provider/adapter.
	Name() string
	// Chat performs a non-streaming completion and returns the full response.
	Chat(ctx context.Context, req Request, opts Options) (Response, error)
	// ChatStream streams structured events via onEvent and returns the aggregated
	// response (with usage when the provider reports it). onEvent may be nil to
	// discard events while still aggregating. Every provider-supported segment is
	// bracketed (text_start/delta/end, tool_call_start/delta/end), so the consumer
	// can render each independently; segments adapters cannot yet distinguish are
	// delivered as text_delta events.
	ChatStream(ctx context.Context, req Request, onEvent func(StreamEvent)) (Response, error)
}