Add automated base image detection with hardware compatibility matrix

inference-spec/images/images.yaml

@@ -0,0 +1,203 @@
+# Image Compatibility Matrix for RamaLama
+#
+# This file defines the mapping between hardware configurations and container images.
+# Images are selected based on:
+#   - Architecture (x86_64, aarch64)
+#   - GPU type (cuda, hip, intel, asahi, cann, musa, vulkan, metal, none)
+#   - Driver version (with version constraints like >=12.4, <13.0)
+#   - Runtime (llama.cpp, vllm, mlx)
+#   - OS type (linux, darwin, windows)
+#
+# Version constraint syntax:
+#   >=12.4       - Greater than or equal to 12.4
+#   <13.0        - Less than 13.0
+#   ==12.4       - Exactly 12.4
+#   >=12.4,<13.0 - Range (AND logic)
+#   *            - Any version (default)
+
+schema_version: "1.0.0"
+default_image: "quay.io/ramalama/ramalama"
+
+images:
+  # =============================================================================
+  # CUDA (NVIDIA) Images
+  # =============================================================================
+
+  # CUDA for llama.cpp - supports CUDA 12.4+
+  - image: "quay.io/ramalama/cuda"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["cuda"]
+      driver_version: ">=12.4"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux"]
+    tags:
+      # CUDA 12.4-12.7 use the -12.4.1 suffix image
+      "12.4": "latest-12.4.1"
+      "12.5": "latest-12.4.1"
+      "12.6": "latest-12.4.1"
+      "12.7": "latest-12.4.1"
+      # CUDA 12.8+ use the standard image (no suffix needed)
+
+  # =============================================================================
+  # ROCm (AMD) Images
+  # =============================================================================
+
+  # ROCm for llama.cpp - x86_64 only (ROCm not available for ARM)
+  - image: "quay.io/ramalama/rocm"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["hip"]
+      driver_version: "*"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # Intel GPU Images
+  # =============================================================================
+
+  # Intel GPU for llama.cpp - supports Arc and integrated GPUs
+  - image: "quay.io/ramalama/intel-gpu"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["intel"]
+      driver_version: "*"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # Apple Silicon Images
+  # =============================================================================
+
+  # Asahi Linux (Apple Silicon on Linux)
+  - image: "quay.io/ramalama/asahi"
+    priority: 100
+    constraints:
+      architectures: ["aarch64"]
+      gpu_types: ["asahi"]
+      driver_version: "*"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # Ascend (Huawei) NPU Images
+  # =============================================================================
+
+  # CANN for Ascend NPU
+  - image: "quay.io/ramalama/cann"
+    priority: 100
+    constraints:
+      architectures: ["x86_64", "aarch64"]
+      gpu_types: ["cann"]
+      driver_version: "*"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # Mthreads (MUSA) Images
+  # =============================================================================
+
+  # MUSA for Mthreads GPUs
+  - image: "quay.io/ramalama/musa"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["musa"]
+      driver_version: "*"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # vLLM Runtime Images
+  # =============================================================================
+
+  # vLLM for CUDA GPUs
+  - image: "docker.io/vllm/vllm-openai"
+    priority: 50
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["cuda"]
+      driver_version: ">=12.0"
+      runtimes: ["vllm"]
+      os_types: ["linux"]
+
+  # vLLM for ROCm GPUs
+  - image: "docker.io/vllm/vllm-openai"
+    priority: 50
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["hip"]
+      driver_version: "*"
+      runtimes: ["vllm"]
+      os_types: ["linux"]
+
+  # vLLM fallback for other GPUs
+  - image: "docker.io/vllm/vllm-openai"
+    priority: 10
+    constraints:
+      architectures: ["x86_64", "aarch64"]
+      gpu_types: ["intel", "asahi", "cann", "musa", "none"]
+      driver_version: "*"
+      runtimes: ["vllm"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # RAG Images
+  # =============================================================================
+
+  # RAG with CUDA
+  - image: "quay.io/ramalama/cuda-rag"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["cuda"]
+      driver_version: ">=12.4"
+      runtimes: ["llama.cpp-rag"]
+      os_types: ["linux"]
+
+  # RAG with ROCm
+  - image: "quay.io/ramalama/rocm-rag"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["hip"]
+      driver_version: "*"
+      runtimes: ["llama.cpp-rag"]
+      os_types: ["linux"]
+
+  # RAG with Intel GPU
+  - image: "quay.io/ramalama/intel-gpu-rag"
+    priority: 100
+    constraints:
+      architectures: ["x86_64"]
+      gpu_types: ["intel"]
+      driver_version: "*"
+      runtimes: ["llama.cpp-rag"]
+      os_types: ["linux"]
+
+  # RAG fallback
+  - image: "quay.io/ramalama/ramalama-rag"
+    priority: 1
+    constraints:
+      architectures: ["x86_64", "aarch64"]
+      gpu_types: ["none", "vulkan", "asahi", "cann", "musa"]
+      driver_version: "*"
+      runtimes: ["llama.cpp-rag"]
+      os_types: ["linux"]
+
+  # =============================================================================
+  # Default CPU/Vulkan Fallback Images
+  # =============================================================================
+
+  # Default fallback for llama.cpp (CPU or Vulkan acceleration)
+  - image: "quay.io/ramalama/ramalama"
+    priority: 1
+    constraints:
+      architectures: ["x86_64", "aarch64"]
+      gpu_types: ["none", "vulkan"]
+      driver_version: "*"
+      runtimes: ["llama.cpp"]
+      os_types: ["linux", "darwin", "windows"]

inference-spec/images/schema.1-0-0.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RamaLama schema for image compatibility matrix",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+      "description": "Schema version in semver format"
+    },
+    "default_image": {
+      "type": "string",
+      "description": "Default image to use when no match is found"
+    },
+    "images": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["image", "constraints"],
+        "properties": {
+          "image": {
+            "type": "string",
+            "description": "Container image URL (e.g., quay.io/ramalama/cuda)"
+          },
+          "priority": {
+            "type": "integer",
+            "default": 0,
+            "description": "Priority for image selection. Higher priority images are preferred when multiple match."
+          },
+          "constraints": {
+            "type": "object",
+            "properties": {
+              "architectures": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["x86_64", "aarch64"]
+                },
+                "description": "Supported CPU architectures"
+              },
+              "gpu_types": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["cuda", "hip", "intel", "asahi", "cann", "musa", "vulkan", "metal", "none"]
+                },
+                "description": "Supported GPU types"
+              },
+              "driver_version": {
+                "type": "string",
+                "description": "Driver version constraint (e.g., '>=12.4', '<13.0', '>=12.4,<13.0', '*')"
+              },
+              "runtimes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Supported inference runtimes (e.g., 'llama.cpp', 'vllm', 'mlx')"
+              },
+              "os_types": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["linux", "darwin", "windows"]
+                },
+                "description": "Supported operating systems"
+              }
+            },
+            "additionalProperties": false
+          },
+          "tags": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Version-specific image tags. Keys are driver versions (e.g., '12.4'), values are tags."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["schema_version", "default_image", "images"],
+  "additionalProperties": false
+}

ramalama/common.py

@@ -691,13 +691,26 @@ class AccelImageArgsOtherRuntimeRAG(Protocol):
 
 def accel_image(config: Config, images: RamalamaImageConfig | None = None, conf_key: str = "image") -> str:
     """
-    Selects and the appropriate image based on config, arguments, environment.
-    "images" is a mapping of environment variable names to image names. If not specified, the
-    mapping from default config will be used.
-    "conf_key" is the configuration key that holds the configured value of the selected image.
-    If not specified, it defaults to "image".
+    Selects the appropriate container image based on config, arguments, environment.
+
+    This function performs automatic hardware detection to select the best container image
+    for the current system. It considers CPU architecture, GPU type, and driver versions.
+
+    For the new compatibility matrix-based selection system, use:
+        from ramalama.image_selector import select_image
+        image = select_image(config, runtime="llama.cpp")
+
+    Args:
+        config: RamaLama configuration object
+        images: Optional mapping of environment variable names to image names.
+                If not specified, the mapping from default config will be used.
+        conf_key: Configuration key that holds the configured value of the selected image.
+                  Defaults to "image". Use "rag_image" for RAG operations.
+
+    Returns:
+        The fully qualified image name with tag (e.g., "quay.io/ramalama/cuda:0.17")
     """
-    # User provided an image via config
+    # User provided an image via config - honor explicit user choice
     if config.is_set(conf_key):
         return tagged_image(getattr(config, conf_key))
 

ramalama/config.py

@@ -123,6 +123,49 @@ def get_inference_schema_files() -> dict[str, Path]:
     return files
 
 
+def get_image_matrix_files() -> list[Path]:
+    """
+    Get paths to image compatibility matrix files.
+
+    Searches in order:
+    1. Development path (inference-spec/images/)
+    2. System config directories (/etc/ramalama/inference/images/)
+    3. User config directories (~/.config/ramalama/inference/images/)
+
+    Later paths take precedence over earlier ones.
+
+    Returns:
+        List of paths to images.yaml files that exist
+    """
+    files: list[Path] = []
+
+    for spec_dir in get_all_inference_spec_dirs("images"):
+        for file_extension in ["*.yaml", "*.yml"]:
+            for matrix_file in sorted(Path(spec_dir).glob(file_extension)):
+                if matrix_file.stem == "images":
+                    files.append(matrix_file)
+
+    return files
+
+
+def get_image_matrix_schema_files() -> dict[str, Path]:
+    """
+    Get paths to image matrix schema files.
+
+    Returns:
+        Dict mapping schema version to schema file path
+    """
+    files: dict[str, Path] = {}
+
+    for schema_dir in get_all_inference_spec_dirs("images"):
+        for spec_file in sorted(Path(schema_dir).glob("schema.*.json")):
+            file = Path(spec_file)
+            version = file.name.replace("schema.", "").replace(".json", "")
+            files[version] = file
+
+    return files
+
+
 def coerce_to_bool(value: Any) -> bool:
     if isinstance(value, bool):
         return value