majordomo/majordomo.go

// Package majordomo is a clean-slate substrate for building LLM-backed
// agents: target-agnostic model access, a parseable model naming /
// failover / tiering system with health tracking, multimodality, tool calls
// and structured output, and agents composed from a model + system prompt +
// toolboxes + skills.
//
// The one-call entry point is Parse:
//
//	reg := majordomo.New()
//	m, err := reg.Parse("ollama-cloud/minimax-m3:cloud,anthropic/opus-4.8,thinking")
//	resp, err := m.Generate(ctx, majordomo.Request{
//	    Messages: []majordomo.Message{majordomo.UserText("hello")},
//	})
//
// A spec is a comma-separated failover chain. Each element is either a
// "provider/model" target (built-in, client-registered, or defined via an
// LLM_* env DSN) or a registered alias/tier, which expands inline. See
// Registry.Parse for the full grammar.
//
// The canonical types (Message, Request, Response, Tool, Capabilities, ...)
// are defined in the llm subpackage and re-exported here, so most consumers
// only ever import this package (plus agent and skill).
package majordomo

import (
	"encoding/json"
	"sync"

	"gitea.stevedudenhoeffer.com/steve/majordomo/audio"
	"gitea.stevedudenhoeffer.com/steve/majordomo/imagegen"
	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
)

// Re-exported canonical types. See the llm package for documentation.
type (
	Model        = llm.Model
	Provider     = llm.Provider
	Message      = llm.Message
	Role         = llm.Role
	Part         = llm.Part
	TextPart     = llm.TextPart
	ImagePart    = llm.ImagePart
	Request      = llm.Request
	Response     = llm.Response
	Option       = llm.Option
	ModelOption  = llm.ModelOption
	ModelConfig  = llm.ModelConfig
	Tool         = llm.Tool
	ToolCall     = llm.ToolCall
	ToolResult   = llm.ToolResult
	Toolbox      = llm.Toolbox
	Capabilities = llm.Capabilities
	Stream       = llm.Stream
	StreamEvent  = llm.StreamEvent
	Usage        = llm.Usage
	FinishReason = llm.FinishReason
	APIError     = llm.APIError
	ErrorClass   = llm.ErrorClass
)

// Re-exported canonical image-generation types. See the imagegen package for
// documentation. Image generation is a separate contract from llm (no chat
// messages, tools, or streaming); the first backend is provider/llamaswap.
type (
	ImageModel       = imagegen.Model
	ImageProvider    = imagegen.Provider
	ImageRequest     = imagegen.Request
	ImageResult      = imagegen.Result
	ImageOption      = imagegen.Option
	ImageModelOption = imagegen.ModelOption
	ImageEditor      = imagegen.Editor
	ImageEditRequest = imagegen.EditRequest
	ImageEditOption  = imagegen.EditOption
)

// Re-exported canonical speech types. See the audio package for
// documentation. Speech synthesis and transcription are separate contracts
// from llm, mirroring imagegen (ADR-0017); the first backend is
// provider/llamaswap.
type (
	SpeechModel           = audio.SpeechModel
	SpeechProvider        = audio.SpeechProvider
	SpeechRequest         = audio.SpeechRequest
	SpeechResult          = audio.SpeechResult
	SpeechOption          = audio.SpeechOption
	TranscriptionModel    = audio.TranscriptionModel
	TranscriptionProvider = audio.TranscriptionProvider
	TranscriptionRequest  = audio.TranscriptionRequest
	TranscriptionResult   = audio.TranscriptionResult
	TranscriptionOption   = audio.TranscriptionOption
)

// Re-exported role and finish-reason constants.
const (
	RoleSystem    = llm.RoleSystem
	RoleUser      = llm.RoleUser
	RoleAssistant = llm.RoleAssistant
	RoleTool      = llm.RoleTool

	FinishStop          = llm.FinishStop
	FinishLength        = llm.FinishLength
	FinishToolCalls     = llm.FinishToolCalls
	FinishContentFilter = llm.FinishContentFilter
	FinishOther         = llm.FinishOther

	ClassTransient = llm.ClassTransient
	ClassPermanent = llm.ClassPermanent
)

// ErrModelNotFound re-exports llm.ErrModelNotFound.
var ErrModelNotFound = llm.ErrModelNotFound

// ErrUnsupported re-exports llm.ErrUnsupported.
var ErrUnsupported = llm.ErrUnsupported

// Re-exported content and message constructors.
func Text(s string) Part                               { return llm.Text(s) }
func Image(mime string, data []byte) Part              { return llm.Image(mime, data) }
func SystemText(s string) Message                      { return llm.SystemText(s) }
func UserText(s string) Message                        { return llm.UserText(s) }
func UserParts(parts ...Part) Message                  { return llm.UserParts(parts...) }
func AssistantText(s string) Message                   { return llm.AssistantText(s) }
func ToolResultsMessage(results ...ToolResult) Message { return llm.ToolResultsMessage(results...) }
func NewToolbox(name string, tools ...Tool) *Toolbox   { return llm.NewToolbox(name, tools...) }

// Re-exported request options.
func WithSystem(s string) Option                            { return llm.WithSystem(s) }
func WithTools(tools ...Tool) Option                        { return llm.WithTools(tools...) }
func WithToolbox(b *Toolbox) Option                         { return llm.WithToolbox(b) }
func WithToolChoice(choice string) Option                   { return llm.WithToolChoice(choice) }
func WithSchema(schema json.RawMessage, name string) Option { return llm.WithSchema(schema, name) }
func WithTemperature(t float64) Option                      { return llm.WithTemperature(t) }
func WithTopP(p float64) Option                             { return llm.WithTopP(p) }
func WithMaxTokens(n int) Option                            { return llm.WithMaxTokens(n) }
func WithStopSequences(stops ...string) Option              { return llm.WithStopSequences(stops...) }
func WithReasoningEffort(level string) Option               { return llm.WithReasoningEffort(level) }
func WithPromptCaching() Option                             { return llm.WithPromptCaching() }

// WithModelCapabilities re-exports llm.WithCapabilities for Provider.Model
// calls made through this package.
func WithModelCapabilities(caps Capabilities) ModelOption { return llm.WithCapabilities(caps) }

// Re-exported image-generation request options (see the imagegen package).
func WithImageCount(n int) ImageOption   { return imagegen.WithN(n) }
func WithImageSize(s string) ImageOption { return imagegen.WithSize(s) }

// Classify re-exports llm.Classify.
func Classify(err error) ErrorClass { return llm.Classify(err) }

// defaultRegistry backs the package-level convenience functions.
var defaultRegistry = func() func() *Registry {
	var (
		once sync.Once
		reg  *Registry
	)
	return func() *Registry {
		once.Do(func() { reg = New() })
		return reg
	}
}()

// Default returns the lazily-initialized package-level Registry (built-in
// providers plus LLM_* env providers from the process environment).
func Default() *Registry { return defaultRegistry() }

// Parse resolves a spec using the Default registry.
func Parse(spec string) (Model, error) { return Default().Parse(spec) }

// MustParse is Parse that panics on error; for wiring code and examples.
func MustParse(spec string) Model {
	m, err := Parse(spec)
	if err != nil {
		panic(err)
	}
	return m
}

// RegisterProvider registers a provider in the Default registry.
func RegisterProvider(p Provider) { Default().RegisterProvider(p) }

// RegisterAlias registers an alias/tier in the Default registry.
func RegisterAlias(name, spec string) { Default().RegisterAlias(name, spec) }