promptkit/engine.go

package promptkit

import (
	"context"
	"errors"
	"fmt"
	"io/fs"
	"net/http"
	"os"
	"path/filepath"
	"strings"
	"time"

	artifactadapter "gitea.maximumdirect.net/eric/promptkit/internal/artifact"
	"gitea.maximumdirect.net/eric/promptkit/internal/defaults"
	"gitea.maximumdirect.net/eric/promptkit/internal/llm"
	"gitea.maximumdirect.net/eric/promptkit/internal/profile"
	"gitea.maximumdirect.net/eric/promptkit/internal/profile/builtin"
	"gitea.maximumdirect.net/eric/promptkit/internal/prompt"
	"gitea.maximumdirect.net/eric/promptkit/internal/promptdef"
	"gitea.maximumdirect.net/eric/promptkit/internal/usecase"
	"gitea.maximumdirect.net/eric/promptkit/internal/validate"
)

// ErrInvalidConfig indicates invalid public engine configuration.
var ErrInvalidConfig = errors.New("invalid engine configuration")

var (
	ErrInvalidRequest   = errors.New("invalid run request")
	ErrPromptNotFound   = errors.New("prompt not found")
	ErrProfileNotFound  = errors.New("profile not found")
	ErrProfileRequired  = errors.New("profile selection is required")
	ErrPromptLoad       = errors.New("failed to load prompt definition")
	ErrProfileLoad      = errors.New("failed to load execution profile")
	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
	ErrArtifactLoad     = errors.New("failed to load artifact")
	ErrPromptRender     = errors.New("failed to render prompt")
	ErrLLMGenerate      = errors.New("failed to generate output")
	ErrValidation       = errors.New("failed to validate output")
)

// Engine prepares and runs Promptkit prompt requests.
type Engine struct {
	runner *usecase.Runner
}

// Config configures a public Promptkit engine.
type Config struct {
	PromptDir  string
	ProfileDir string
	SchemaDir  string
	// Timeout is the transport-wide safety cap for the built-in LLM client
	// when HTTPClient is absent or has a non-positive timeout.
	Timeout time.Duration
	// HTTPClient is cloned for the built-in LLM client. Its positive Timeout
	// takes precedence over Config.Timeout as the transport-wide safety cap.
	HTTPClient *http.Client
}

// Option customizes engine construction.
type Option interface {
	apply(*engineOptions) error
}

type optionFunc func(*engineOptions) error

func (f optionFunc) apply(options *engineOptions) error {
	return f(options)
}

type engineOptions struct {
	llmClient       llm.Client
	artifactReader  artifactadapter.Reader
	promptDefs      promptdef.Repository
	profiles        profile.Repository
	memoryProfiles  profile.Repository
	validator       validate.Validator
	promptSource    bool
	profileSource   bool
	memorySource    bool
	validatorSource bool
	artifactSource  bool
}

// WithLLMClient injects a custom LLM client for execution.
func WithLLMClient(client LLMClient) Option {
	return optionFunc(func(options *engineOptions) error {
		if client == nil {
			return ErrInvalidConfig
		}
		options.llmClient = publicLLMClientAdapter{client: client}
		return nil
	})
}

// WithArtifactReader injects a reader for every input artifact reference.
func WithArtifactReader(reader ArtifactReader) Option {
	return optionFunc(func(options *engineOptions) error {
		if reader == nil {
			return ErrInvalidConfig
		}
		options.artifactReader = publicArtifactReaderAdapter{reader: reader}
		options.artifactSource = true
		return nil
	})
}

// WithPromptFS loads prompt definitions from fsys under root.
//
// The source uses the same strict prompt YAML rules as configured prompt
// directories, and prompt content_file paths resolve within this source.
func WithPromptFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		if fsys == nil {
			return ErrInvalidConfig
		}
		if strings.TrimSpace(root) == "" {
			return ErrInvalidConfig
		}
		options.promptDefs = promptdef.NewFSRepository(fsys, root)
		options.promptSource = true
		return nil
	})
}

// WithPromptFile loads prompt definitions from the single prompt file at path.
//
// Relative prompt content_file paths resolve from the file's directory.
func WithPromptFile(path string) Option {
	return optionFunc(func(options *engineOptions) error {
		fsys, root, err := fileSource(path)
		if err != nil {
			return err
		}
		options.promptDefs = promptdef.NewFSRepository(fsys, root)
		options.promptSource = true
		return nil
	})
}

// WithProfileFS loads execution profiles from fsys under root.
//
// Profiles from this source overlay built-in profiles. Profile YAML must use
// api_key_env for environment-based credentials; raw API keys are rejected.
func WithProfileFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		if fsys == nil {
			return ErrInvalidConfig
		}
		if strings.TrimSpace(root) == "" {
			return ErrInvalidConfig
		}
		options.profiles = profile.NewFSRepository(fsys, root)
		options.profileSource = true
		return nil
	})
}

// WithProfileFile loads execution profiles from the single profile file at path.
//
// The profile overlays built-in profiles. Profile YAML must use api_key_env for
// environment-based credentials; raw API keys are rejected.
func WithProfileFile(path string) Option {
	return optionFunc(func(options *engineOptions) error {
		fsys, root, err := fileSource(path)
		if err != nil {
			return err
		}
		options.profiles = profile.NewFSRepository(fsys, root)
		options.profileSource = true
		return nil
	})
}

// WithProfiles configures in-memory profiles that take precedence over
// configured profile files and built-in profiles.
func WithProfiles(profiles ...Profile) Option {
	return optionFunc(func(options *engineOptions) error {
		repo, err := newMemoryProfileRepository(profiles)
		if err != nil {
			return err
		}
		options.memoryProfiles = repo
		options.memorySource = true
		return nil
	})
}

// WithSchemaFS loads JSON Schema documents from fsys under root.
//
// Prompt schema_path values resolve within this source when schema validation
// or structured output is requested.
func WithSchemaFS(fsys fs.FS, root string) Option {
	return optionFunc(func(options *engineOptions) error {
		if fsys == nil {
			return ErrInvalidConfig
		}
		if strings.TrimSpace(root) == "" {
			return ErrInvalidConfig
		}
		options.validator = validate.NewFSValidator(fsys, root)
		options.validatorSource = true
		return nil
	})
}

// WithSchemaFile loads JSON Schema documents from the single schema file at path.
//
// Prompt schema_path values refer to the file's base name.
func WithSchemaFile(path string) Option {
	return optionFunc(func(options *engineOptions) error {
		fsys, root, err := fileSource(path)
		if err != nil {
			return err
		}
		options.validator = validate.NewFSValidator(fsys, root)
		options.validatorSource = true
		return nil
	})
}

// NewEngine constructs an Engine from configuration and options.
func NewEngine(cfg Config, opts ...Option) (*Engine, error) {
	var options engineOptions
	for _, opt := range opts {
		if opt == nil {
			continue
		}
		if err := opt.apply(&options); err != nil {
			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
		}
	}

	promptDefs := options.promptDefs
	if !options.promptSource {
		if strings.TrimSpace(cfg.PromptDir) == "" {
			return nil, fmt.Errorf("%w: prompt directory is required", ErrInvalidConfig)
		}
		promptDefs = promptdef.NewFilesystemRepository(cfg.PromptDir)
	}

	profiles := builtin.NewRepositoryWithDirectory(cfg.ProfileDir)
	if options.profileSource {
		profiles = builtin.NewRepositoryWithPrimary(options.profiles)
	}
	if options.memorySource {
		profiles = profile.NewOverlayRepository(options.memoryProfiles, profiles)
	}

	validator := options.validator
	if !options.validatorSource {
		schemaDir := cfg.SchemaDir
		if strings.TrimSpace(schemaDir) == "" {
			schemaDir = defaults.SchemaDirDefault
		}
		validator = validate.NewStandardValidator(schemaDir)
	}

	llmClient := options.llmClient
	if llmClient == nil {
		var err error
		llmClient, err = llm.NewOpenAICompatibleClient(llm.OpenAICompatibleConfig{
			Timeout:    cfg.Timeout,
			HTTPClient: cfg.HTTPClient,
		})
		if err != nil {
			return nil, fmt.Errorf("%w: %v", ErrInvalidConfig, err)
		}
	}

	artifacts := options.artifactReader
	if !options.artifactSource {
		artifacts = artifactadapter.NewCompositeReader()
	}

	return &Engine{
		runner: usecase.NewRunner(
			promptDefs,
			profiles,
			artifacts,
			prompt.NewGoRenderer(),
			llmClient,
			validator,
		),
	}, nil
}

func fileSource(name string) (fs.FS, string, error) {
	cleanName := strings.TrimSpace(name)
	if cleanName == "" {
		return nil, "", ErrInvalidConfig
	}
	dir := filepath.Dir(cleanName)
	base := filepath.Base(cleanName)
	if base == "." || base == string(filepath.Separator) || strings.TrimSpace(base) == "" {
		return nil, "", ErrInvalidConfig
	}
	info, err := os.Stat(cleanName)
	if err != nil {
		return nil, "", fmt.Errorf("%w: failed to access source file %q: %v", ErrInvalidConfig, cleanName, err)
	}
	if info.IsDir() {
		return nil, "", fmt.Errorf("%w: source path %q must be a file", ErrInvalidConfig, cleanName)
	}
	return os.DirFS(dir), filepath.ToSlash(base), nil
}

// Prepare resolves a prompt request without calling an LLM.
func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error) {
	if e == nil || e.runner == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	domainReq, err := toDomainRunRequest(req)
	if err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
	}

	prepared, err := e.runner.Prepare(ctx, domainReq)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return fromDomainPreparedRun(prepared), nil
}

// Run executes a prompt request and returns the generated artifact and metadata.
func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error) {
	if e == nil || e.runner == nil {
		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
	}

	domainReq, err := toDomainRunRequest(req)
	if err != nil {
		return nil, fmt.Errorf("%w: %v", ErrInvalidRequest, err)
	}

	result, err := e.runner.Run(ctx, domainReq)
	if err != nil {
		return nil, mapPublicError(err)
	}
	return fromDomainRunResult(result), nil
}