pipeline

type Builder struct {
	// contains filtered or unexported fields
}

type Inspector interface {
	Stages() []Stage
}

type Middleware interface {
	// Name returns a unique identifier for this middleware.
	Name() string

	// Priority returns execution order among non-terminal middleware
	// (lower = earlier = further out). The terminal always runs last.
	// Built-in bands:
	//   0-19:    request id, tracing, usage (they wrap everything)
	//   20-99:   timeout, identity, access, quota, stream lifecycle
	//   100-199: guardrails
	//   200-299: transform, alias, cache
	//   300-399: retry; custom middleware here runs once per attempt
	Priority() int

	// Process handles the request. Call next(ctx) to continue.
	Process(ctx context.Context, req *Request, next NextFunc) (*Response, error)
}

type NextFunc func(ctx context.Context) (*Response, error)

type Refusal interface {
	error
	RefusalCode() string
	StatusCode() int
}

type RefusalError struct {
	Code         string
	Status       int
	Message      string
	Limit        string
	RetryAfter   time.Duration
	Unattributed bool
	Cause        error
}

type Request struct {
	Completion *provider.CompletionRequest
	Embedding  *provider.EmbeddingRequest
	Type       RequestType // "completion", "stream", "embedding"

	// Mutable state middleware can read/write.
	State map[string]any
}

type RequestType string

type Response struct {
	Completion *provider.CompletionResponse
	Stream     provider.Stream
	Embedding  *provider.EmbeddingResponse
}

type Service interface {
	// Execute processes a completion request through the full pipeline.
	Execute(ctx context.Context, req *provider.CompletionRequest) (*provider.CompletionResponse, error)

	// ExecuteStream processes a streaming request through the pipeline.
	ExecuteStream(ctx context.Context, req *provider.CompletionRequest) (provider.Stream, error)

	// ExecuteEmbedding processes an embedding request.
	ExecuteEmbedding(ctx context.Context, req *provider.EmbeddingRequest) (*provider.EmbeddingResponse, error)
}

type Stage struct {
	Name     string `json:"name"`
	Priority int    `json:"priority"`
	Terminal bool   `json:"terminal"`
}

type Terminal interface {
	Terminal()
}