promptkit/internal/domain/smoke_diagnostics.go

package domain

import (
	"time"

	"go.maximumdirect.net/promptkit/internal/jsonvalue"
)

// BackendSmokeTestConfig describes optional backend-owned diagnostic defaults.
type BackendSmokeTestConfig struct {
	DefaultProfile *string
	Reachability   *ReachabilityProbeConfig
	Authentication *AuthenticationProbeConfig
}

// ReachabilityProbeConfig describes an optional endpoint for reachability tests.
type ReachabilityProbeConfig struct {
	Endpoint *string
}

// AuthenticationProbeConfig describes an optional authentication diagnostic.
type AuthenticationProbeConfig struct {
	Kind     *string
	Endpoint *string
}

// SmokeTestKind identifies one built-in diagnostic operation.
type SmokeTestKind string

const (
	SmokeTestReachability     SmokeTestKind = "reachability"
	SmokeTestAuthentication   SmokeTestKind = "authentication"
	SmokeTestTextInference    SmokeTestKind = "text_inference"
	SmokeTestStructuredOutput SmokeTestKind = "structured_output"
)

// SmokeTestRequest selects one diagnostic and its execution target.
type SmokeTestRequest struct {
	Kind             SmokeTestKind
	BackendID        string
	PromptID         string
	ProfileID        string
	Execution        *ExecutionTargetOverride
	APIKey           string `json:"-" yaml:"-"`
	TransientRetries *int
}

// SmokeTestReport contains factual diagnostic results, not generated content.
type SmokeTestReport struct {
	Kind       SmokeTestKind
	Supported  bool
	Applicable *bool
	Completed  bool
	Reason     SmokeTestReason
	Target     SmokeTestTarget
	Facts      SmokeTestFacts
	Timing     SmokeTestTiming
	Attempts   []SmokeTestAttempt
	Usage      ObservedTokenUsage
	Failure    ExecutionFailureKind
}

// SmokeTestTarget identifies the selected diagnostic target and its settings.
type SmokeTestTarget struct {
	BackendID              string
	ProfileID              string
	PromptID               string
	DefaultSourceBackendID string
	SelectionSource        string
	Endpoint               string
	EffectiveSettings      ExecutionTarget
	SettingsPresence       ExecutionTargetPresence
}

// SmokeTestFacts contains optional factual observations from a diagnostic.
type SmokeTestFacts struct {
	CredentialsSupplied       *bool
	EndpointReachable         *bool
	CredentialsAccepted       *bool
	ResponseReceived          *bool
	GenerationCompleted       *bool
	TextReturned              *bool
	ExpectedTextMatched       *bool
	StructuredOutputRequested *bool
	ValidJSON                 *bool
	SchemaMatched             *bool
}

// SmokeTestTiming records elapsed diagnostic and phase durations.
type SmokeTestTiming struct {
	StartedAt          time.Time
	Duration           time.Duration
	CapacityWait       *time.Duration
	RequestDuration    *time.Duration
	RetryDelay         *time.Duration
	EvaluationDuration *time.Duration
}

// SmokeTestAttempt records one dispatched attempt or an interrupted acquisition.
type SmokeTestAttempt struct {
	Dispatched      bool
	InitialEndpoint string
	Endpoint        string
	HTTPStatus      *int
	Facts           SmokeTestFacts
	Timing          SmokeTestTiming
	Failure         ExecutionFailureKind
	Usage           ObservedTokenUsage
}

// SmokeTestReason identifies additional factual context for a diagnostic.
type SmokeTestReason string

const (
	SmokeTestReasonNone                                SmokeTestReason = ""
	SmokeTestReasonAuthenticationNotApplicable         SmokeTestReason = "authentication_not_applicable"
	SmokeTestReasonProbeNotConfigured                  SmokeTestReason = "probe_not_configured"
	SmokeTestReasonHTTPDiagnosticsUnavailable          SmokeTestReason = "http_diagnostics_unavailable"
	SmokeTestReasonRequiredCredentialMissing           SmokeTestReason = "required_credential_missing"
	SmokeTestReasonAuthenticationResponseUnrecognized  SmokeTestReason = "authentication_response_unrecognized"
	SmokeTestReasonAuthenticationResponseLimitExceeded SmokeTestReason = "authentication_response_limit_exceeded"
)

// CloneBackend returns a copy of a backend, including its mutable settings.
func CloneBackend(backend Backend) Backend {
	cloned := backend
	cloned.ExtraParams = jsonvalue.CloneTrusted(backend.ExtraParams).(map[string]any)
	cloned.SmokeTests = CloneBackendSmokeTestConfig(backend.SmokeTests)
	return cloned
}

// CloneBackendSmokeTestConfig returns an independent copy of optional metadata.
func CloneBackendSmokeTestConfig(config *BackendSmokeTestConfig) *BackendSmokeTestConfig {
	if config == nil {
		return nil
	}
	cloned := *config
	cloned.DefaultProfile = cloneString(config.DefaultProfile)
	if config.Reachability != nil {
		reachability := *config.Reachability
		reachability.Endpoint = cloneString(config.Reachability.Endpoint)
		cloned.Reachability = &reachability
	}
	if config.Authentication != nil {
		authentication := *config.Authentication
		authentication.Kind = cloneString(config.Authentication.Kind)
		authentication.Endpoint = cloneString(config.Authentication.Endpoint)
		cloned.Authentication = &authentication
	}
	return &cloned
}

func cloneString(value *string) *string {
	if value == nil {
		return nil
	}
	cloned := *value
	return &cloned
}