promptkit/resource_inspection.go

package promptkit

// ProfileInspection describes a resolved profile resource, before backend
// completion or request overrides. References are not resolved. APIKeyEnv is
// an environment-variable name, never a credential value. The result and its
// mutable values are caller-owned. Nil pointers denote absent fields; non-nil
// pointers preserve explicit zero values and empty collections. JSON and YAML
// use the indicated field names and omit absent optional fields.
type ProfileInspection struct {
	ProfileID       string          `json:"id" yaml:"id"`
	Backend         *string         `json:"backend,omitempty" yaml:"backend,omitempty"`
	Endpoint        *string         `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
	Model           *string         `json:"model,omitempty" yaml:"model,omitempty"`
	Temperature     *float64        `json:"temperature,omitempty" yaml:"temperature,omitempty"`
	TopP            *float64        `json:"top_p,omitempty" yaml:"top_p,omitempty"`
	MaxTokens       *int            `json:"max_tokens,omitempty" yaml:"max_tokens,omitempty"`
	TimeoutSeconds  *int            `json:"timeout_seconds,omitempty" yaml:"timeout_seconds,omitempty"`
	ServiceTier     *string         `json:"service_tier,omitempty" yaml:"service_tier,omitempty"`
	ReasoningEffort *string         `json:"reasoning_effort,omitempty" yaml:"reasoning_effort,omitempty"`
	APIKeyEnv       *string         `json:"api_key_env,omitempty" yaml:"api_key_env,omitempty"`
	APIKeyRequired  *bool           `json:"api_key_required,omitempty" yaml:"api_key_required,omitempty"`
	ExtraParams     *map[string]any `json:"extra_params,omitempty" yaml:"extra_params,omitempty"`
}

// BackendInspection describes a resolved backend resource, not runtime capacity
// or diagnostic destinations derived during execution. APIKeyEnv names an
// environment variable, not its value. The result and its mutable values are
// caller-owned. Nil pointers denote absent fields; non-nil pointers preserve
// explicit zero values and empty collections in JSON and YAML.
type BackendInspection struct {
	BackendID        string                  `json:"id" yaml:"id"`
	Endpoint         string                  `json:"endpoint" yaml:"endpoint"`
	APIKeyEnv        *string                 `json:"api_key_env,omitempty" yaml:"api_key_env,omitempty"`
	ConcurrencyLimit *int                    `json:"concurrency_limit,omitempty" yaml:"concurrency_limit,omitempty"`
	QueueCapacity    *int                    `json:"queue_capacity,omitempty" yaml:"queue_capacity,omitempty"`
	ExtraParams      *map[string]any         `json:"extra_params,omitempty" yaml:"extra_params,omitempty"`
	SmokeTests       *BackendSmokeTestConfig `json:"smoke_tests,omitempty" yaml:"smoke_tests,omitempty"`
}

// PromptInspection describes a resolved prompt resource. Messages contain
// captured inline or imported text, not rendered content. References are not
// resolved by inspection; PromptHash is opaque. The result and its mutable
// values are caller-owned. Nil pointers denote absent fields; non-nil pointers
// preserve explicit zero values and empty collections in JSON and YAML.
type PromptInspection struct {
	PromptID         string                    `json:"id" yaml:"id"`
	PromptHash       string                    `json:"prompt_hash" yaml:"prompt_hash"`
	DefaultProfileID *string                   `json:"default_profile,omitempty" yaml:"default_profile,omitempty"`
	Description      *string                   `json:"description,omitempty" yaml:"description,omitempty"`
	SessionID        *string                   `json:"session_id,omitempty" yaml:"session_id,omitempty"`
	Inputs           *[]PromptInputInspection  `json:"inputs,omitempty" yaml:"inputs,omitempty"`
	Messages         []PromptMessageInspection `json:"messages" yaml:"messages"`
	OutputContract   PromptOutputInspection    `json:"output" yaml:"output"`
}

// PromptInputInspection describes a declared input and its optional metadata.
type PromptInputInspection struct {
	Name        string  `json:"name" yaml:"name"`
	Required    *bool   `json:"required,omitempty" yaml:"required,omitempty"`
	ContentType *string `json:"content_type,omitempty" yaml:"content_type,omitempty"`
	Description *string `json:"description,omitempty" yaml:"description,omitempty"`
}

// PromptMessageInspection describes a captured, unrendered message.
type PromptMessageInspection struct {
	Role         string                        `json:"role" yaml:"role"`
	Content      string                        `json:"content" yaml:"content"`
	CacheControl *PromptCacheControlInspection `json:"cache_control,omitempty" yaml:"cache_control,omitempty"`
}

// PromptCacheControlInspection describes configured message cache metadata.
// A non-nil TTL preserves an explicitly empty value.
type PromptCacheControlInspection struct {
	Type CacheControlType `json:"type" yaml:"type"`
	TTL  *string          `json:"ttl,omitempty" yaml:"ttl,omitempty"`
}

// PromptOutputInspection describes a prompt's output contract. SchemaPath is
// a reference and is not loaded by inspection.
type PromptOutputInspection struct {
	Format         OutputFormat   `json:"format" yaml:"format"`
	ValidationMode ValidationMode `json:"validation_mode" yaml:"validation_mode"`
	SchemaPath     *string        `json:"schema_path,omitempty" yaml:"schema_path,omitempty"`
	RepairAttempts *int           `json:"repair_attempts,omitempty" yaml:"repair_attempts,omitempty"`
}