config

type ChipModelConfig struct {
	// ConfigKey is the unique identifier used in runtime configuration
	// This key maps to runtime images and deployment settings
	// Example: "ascend-910b", "ascend-310p"
	ConfigKey string `yaml:"config_key"`

	// ModelName is the human-readable chip model name
	// Example: "Ascend 910B", "Ascend 310P"
	ModelName string `yaml:"model_name"`

	// DeviceID is the PCIe device identifier (16-bit hex value)
	// Example: "0xd802" for Ascend 910B
	DeviceID string `yaml:"device_id"`

	// SubsystemDeviceID is the PCIe subsystem device identifier (16-bit hex value, optional)
	// DEPRECATED: Use Variants instead for chip sub-versions
	// When empty, matching is based on VendorID and DeviceID only
	SubsystemDeviceID string `yaml:"subsystem_device_id,omitempty"`

	// Variants defines a list of chip sub-versions with different subsystem_device_id
	// Used to distinguish between models like 910B1, 910B2, etc.
	// If hardware matches a variant, the variant's config_key is used
	// All variants share the same runtime_images from base model config
	// If no variant matches, the base model config is used as fallback
	Variants []ChipVariant `yaml:"variants,omitempty"`

	// Generation groups related chip models (optional)
	// Example: "Ascend 9xx", "Ascend 3xx"
	Generation string `yaml:"generation,omitempty"`

	// Capabilities lists supported features and precision modes
	// Example: ["int8", "fp16", "inference"]
	Capabilities []string `yaml:"capabilities,omitempty"`

	// ChipsPerDevice specifies how many AI chips are on each physical PCI device
	// Default: 1 (single-chip card)
	// Example: 2 for dual-chip cards like Ascend 910B Duo
	// This allows proper device enumeration where one PCI device contains multiple inference cores
	ChipsPerDevice int `yaml:"chips_per_device,omitempty"`

	// Topology defines the physical topology for this chip model
	// Used for topology-aware allocation specific to this chip type
	Topology *TopologyConfig `yaml:"topology,omitempty"`

	// RuntimeImages maps inference engines to their Docker images by architecture
	// Structure: engine_name -> architecture -> image_url
	// Example: {"vllm": {"arm64": "quay.io/...", "amd64": "..."}}
	// All variants of this chip model share the same runtime images
	RuntimeImages map[string]map[string]string `yaml:"runtime_images,omitempty"`

	// ExtSandboxes defines configuration-based sandboxes for this chip model (optional)
	// Contains both common configuration and engine-specific configs
	// Common fields (devices, volumes, runtime) are shared by all engines
	// Engine configs are merged with common settings
	ExtSandboxes *ExtSandboxesConfig `yaml:"ext_sandboxes,omitempty"`
}

type ChipModelInfo struct {
	VendorID     string
	DeviceID     string
	ModelName    string
	ConfigKey    string
	DeviceType   api.DeviceType
	Generation   string
	Capabilities []string
}

type ChipVariant struct {
	// SubsystemDeviceID is the PCIe subsystem device identifier (16-bit hex value)
	// Example: "0x0001" for 910B1, "0x0002" for 910B2
	SubsystemDeviceID string `yaml:"subsystem_device_id"`

	// VariantKey is the unique identifier for this variant
	// Example: "ascend-910b1", "ascend-910b2"
	VariantKey string `yaml:"variant_key"`

	// VariantName is the human-readable variant name
	// Example: "910B1", "910B2"
	VariantName string `yaml:"variant_name,omitempty"`
}

type ChipVendorConfig struct {
	// VendorName is the company/organization name
	// Example: "Huawei", "Baidu", "Cambricon"
	VendorName string `yaml:"vendor_name"`

	// VendorID is the PCIe vendor identifier (16-bit hex value)
	// Example: "0x19e5" for Huawei
	VendorID string `yaml:"vendor_id"`

	// ChipModels lists all chip models from this vendor
	ChipModels []ChipModelConfig `yaml:"chip_models"`
}

type Config struct {
	// Server holds the HTTP server configuration including host and port.
	Server ServerConfig `json:"server"`

	// Storage holds the storage configuration including directories for
	// data and configuration files.
	Storage StorageConfig `json:"storage"`

	// RuntimeParams holds runtime parameter templates loaded at startup.
	RuntimeParams *RuntimeParamsConfig `json:"-"`

	// BinaryVersion is the version of the xw binary (e.g., "v0.0.1").
	// Set from main.Version during initialization.
	// Used as the default config_version if not specified in server.conf.
	BinaryVersion string `json:"-"`
}

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

type DevicesConfig struct {
	// Version specifies the configuration schema version
	// Used for compatibility checking and migration
	Version string `yaml:"version"`

	// Vendors contains all supported chip vendors and their models
	// Each vendor's chip models can define their own topology configuration
	Vendors []ChipVendorConfig `yaml:"vendors"`
}

type ExtSandboxConfig struct {
	// DeviceEnv specifies the environment variable name for device visibility.
	// This variable will be automatically set to a comma-separated list of
	// device indices (e.g., "0,1,2") when the container is created.
	//
	// Common examples:
	//   - Ascend NPU: ASCEND_RT_VISIBLE_DEVICES
	//   - NVIDIA GPU: CUDA_VISIBLE_DEVICES
	//   - Kunlun XPU: XPU_VISIBLE_DEVICES
	//   - Cambricon MLU: MLU_VISIBLE_DEVICES
	DeviceEnv string `yaml:"device_env"`

	// Environment contains additional static environment variables to set
	// in the container. These are set as-is without any template processing.
	//
	// Example:
	//   environment:
	//     LOG_LEVEL: "3"
	//     WORKER_METHOD: spawn
	Environment map[string]string `yaml:"environment"`

	// Devices lists all device node paths that may need to be mounted.
	//
	// Device mounting behavior:
	//   - Paths ending with a digit (e.g., /dev/xpu0, /dev/xpu5):
	//     Mounted only when the corresponding device index is allocated.
	//   - Paths not ending with a digit (e.g., /dev/xpu_ctl):
	//     Mounted as shared devices for all containers.
	//
	// Example:
	//   devices:
	//     - /dev/xpu0          # Mounted only when device 0 is allocated
	//     - /dev/xpu1          # Mounted only when device 1 is allocated
	//     - /dev/xpu_ctl       # Always mounted (shared control device)
	Devices []string `yaml:"devices"`

	// Volumes defines host-to-container volume mounts in "host:container" format.
	// If no container path is specified (no colon), the same path is used for both.
	//
	// Example:
	//   volumes:
	//     - /usr/local/xpu:/usr/local/xpu
	//     - /root/.cache:/root/.cache
	Volumes []string `yaml:"volumes"`

	// Privileged indicates whether the container requires privileged mode.
	//
	// Privileged mode grants the container extended permissions, including
	// access to all devices and the ability to modify system settings.
	// While less secure, some accelerators require it for proper operation.
	Privileged bool `yaml:"privileged"`

	// Runtime specifies the Docker runtime to use (e.g., "runc", "nvidia").
	// Defaults to "runc" if not specified.
	Runtime string `yaml:"runtime"`

	// ShmSizeGB specifies the shared memory size in gigabytes.
	// If not specified or zero, defaults to 16GB.
	//
	// Shared memory is required for:
	//   - Inter-process communication in distributed inference
	//   - PyTorch DataLoader workers
	//   - Model tensor sharing
	ShmSizeGB int `yaml:"shm_size_gb,omitempty"`

	// Capabilities lists Linux capabilities required by the container.
	//
	// Common capabilities for AI accelerators:
	//   - SYS_ADMIN: System administration operations
	//   - SYS_RAWIO: Direct device I/O access
	//   - IPC_LOCK: Memory locking for device buffers
	//   - SYS_RESOURCE: Resource limit adjustments
	Capabilities []string `yaml:"capabilities"`
}

type ExtSandboxesConfig struct {
	// Common configuration shared by all engines
	Devices []string `yaml:"devices,omitempty"`
	Volumes []string `yaml:"volumes,omitempty"`
	Runtime string   `yaml:"runtime,omitempty"`

	// Engine-specific configurations
	// Populated during YAML unmarshaling with all non-common keys
	Engines map[string]*ExtSandboxConfig `yaml:"-"`
}

type ModelConfig struct {

	// ModelID is the unique identifier for this model
	// Convention: lowercase, hyphen-separated (e.g., "qwen2-7b")
	ModelID string `yaml:"model_id"`

	// SourceID is the model ID on the source platform
	// Examples: "qwen/Qwen2-7B" (ModelScope), "Qwen/Qwen2-7B" (HuggingFace)
	SourceID string `yaml:"source_id"`

	// Parameters is the model size in billions of parameters
	// Example: 7.0 for 7B model
	Parameters float64 `yaml:"parameters,omitempty"`

	// ContextLength is the maximum context window size in tokens
	ContextLength int `yaml:"context_length,omitempty"`

	// SupportedDevices maps device types to their supported engines
	// Key: device config_key (e.g., "ascend-910b")
	// Value: list of engines in priority order (e.g., ["vllm:docker", "mindie:docker"])
	// Example:
	//   ascend-910b:
	//     - vllm:docker
	//     - mindie:docker
	SupportedDevices map[string][]string `yaml:"supported_devices"`

	// Tag specifies the model variant (e.g., "main", "int8", "fp16")
	Tag string `yaml:"tag,omitempty"`

	// Capabilities lists the model's supported features
	// Common values: "completion", "vision", "tool_use", "function_calling"
	Capabilities []string `yaml:"capabilities,omitempty"`
}

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

type ModelsConfig struct {
	// Version specifies the configuration schema version
	// Used for compatibility checking and migration
	Version string `yaml:"version"`

	// Models contains all available model configurations
	Models []ModelConfig `yaml:"models"`

	// ModelGroups provides logical grouping of related models (optional)
	// Example: {"qwen2": ["qwen2-0.5b", "qwen2-7b", "qwen2-72b"]}
	ModelGroups map[string][]string `yaml:"model_groups,omitempty"`
}

type Package struct {
	// Version is the package version (e.g., "v0.0.1")
	Version string `json:"version"`

	// Name is the human-readable package name
	Name string `json:"name"`

	// Description provides a brief description of this version
	Description string `json:"description"`

	// ReleaseDate is when this version was released (YYYY-MM-DD)
	ReleaseDate string `json:"release_date"`

	// DownloadURL is the URL to download the package tarball
	DownloadURL string `json:"download_url"`

	// SHA256 is the expected SHA256 checksum of the package
	SHA256 string `json:"sha256"`

	// MinXwVersion is the minimum xw binary version required
	MinXwVersion string `json:"min_xw_version"`
}

type PackageRegistry struct {
	// Schema is the JSON schema URL
	Schema string `json:"$schema,omitempty"`

	// Name is the registry name
	Name string `json:"name"`

	// Description describes the registry
	Description string `json:"description"`

	// UpdatedAt is when the registry was last updated
	UpdatedAt string `json:"updated_at"`

	// Packages is the list of available configuration packages
	Packages []Package `json:"packages"`
}

type RuntimeImagesConfig map[string]map[string]map[string]string

type RuntimeParamsConfig struct {
	// Version specifies the configuration schema version
	Version string `yaml:"version"`

	// Templates contains all parameter templates
	Templates []RuntimeParamsTemplate `yaml:"templates"`
}

type RuntimeParamsTemplate struct {
	// Name is the template identifier (chip_model_backend)
	Name string `yaml:"name"`

	// Params is a list of key=value parameters
	// Example: ["max_batch_size=128", "tensor_parallel=4"]
	Params []string `yaml:"params"`
}

type ServerConfig struct {
	// Name is the unique identifier for this server instance.
	Name string `json:"name"`

	// Registry is the configuration package registry URL.
	Registry string `json:"registry"`

	// Host is the server host address (e.g., "localhost", "0.0.0.0").
	// Using "localhost" restricts access to local clients only.
	// Using "0.0.0.0" allows access from any network interface.
	Host string `json:"host"`

	// Port is the TCP port number the server listens on.
	// Common values are 11581 (default) or other non-privileged ports.
	Port int `json:"port"`

	// Address is the computed full server address.
	// This field is not serialized and is computed from Host and Port.
	// Format: "http://host:port"
	Address string `json:"-"`
}

type ServerIdentity struct {
	// Name is the unique identifier for this server instance.
	// Generated randomly on first start if not present.
	Name string `json:"name"`

	// Registry is the URL to the configuration package registry.
	// This registry maintains available configuration versions.
	Registry string `json:"registry"`

	// ConfigVersion is the currently active configuration version.
	// Defaults to the binary version (main.Version) if not specified.
	// Format: vX.Y.Z (e.g., "v0.0.1")
	ConfigVersion string `json:"config_version"`
}

type StorageConfig struct {
	// ConfigDir is the absolute path to the configuration files directory.
	// Contains YAML configuration files like devices.yaml, models.yaml.
	// Example: "/home/user/.xw"
	ConfigDir string `json:"config_dir"`

	// DataDir is the absolute path to the main data directory.
	// Contains all runtime data including models and server state.
	// Example: "/home/user/.xw/data"
	DataDir string `json:"data_dir"`
}

type TopologyBox struct {
	// Devices is a list of logical chip indices in this box
	// Example: [0, 1, 2, 3] means logical chips 0-3 have high-speed interconnect
	// Note: Use logical chip indices, NOT physical device indices
	Devices []int `yaml:"devices"`
}

type TopologyConfig struct {
	// Boxes is a list of device groups with high-speed interconnection
	// Each box contains devices with zero intra-box distance
	// Inter-box distance equals |box_index_a - box_index_b|
	Boxes []TopologyBox `yaml:"boxes,omitempty"`
}

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