[Feature]: Allow dstack offer to aggregate GPU information (#2992)

Author: peterschmidt85

docs/docs/guides/protips.md

@@ -427,6 +427,36 @@ Getting offers...
 
 </div>
 
+??? info "Grouping offers"
+    Use `--group-by` to aggregate offers. Accepted values: `gpu`, `backend`, `region`, and `count`.
+
+    <div class="termy">
+
+    ```shell
+    dstack offer --gpu b200 --group-by gpu,backend,region
+    Project      main
+    User         admin
+    Resources    cpu=2.. mem=8GB.. disk=100GB.. b200:1..
+    Spot policy  auto
+    Max price    -
+    Reservation  -
+    Group by     gpu, backend, region
+
+    #   GPU              SPOT             $/GPU       BACKEND  REGION
+    1   B200:180GB:1..8  spot, on-demand  3.59..5.99  runpod   EU-RO-1
+    2   B200:180GB:1..8  spot, on-demand  3.59..5.99  runpod   US-CA-2
+    3   B200:180GB:8     on-demand        4.99        lambda   us-east-1
+    4   B200:180GB:8     on-demand        5.5         nebius   us-central1
+    ```
+
+    </div>
+
+    When using `--group-by`, `gpu` must always be `included`.
+    The `region` value can only be used together with `backend`.
+
+The `offer` command allows you to filter and group offers with various [advanced options](../reference/cli/dstack/offer.md#usage).
+
+
 ## Metrics
 
 `dstack` tracks essential metrics accessible via the CLI and UI. To access advanced metrics like DCGM, configure the server to export metrics to Prometheus. See [Metrics](metrics.md) for details.

docs/docs/reference/cli/dstack/offer.md

@@ -1,8 +1,8 @@
 # dstack offer
 
-Displays available offers (hardware configurations) with the configured backends (or offers that match already provisioned fleets).
+Displays available offers (hardware configurations) from configured backends or from fleets you’ve already provisioned. Supports filtering and grouping.
 
-The output includes backend, region, instance type, resources, spot availability, and pricing details.
+The output shows backend, region, instance type, resources, spot availability, and pricing.
 
 ## Usage
 
@@ -19,7 +19,7 @@ $ dstack offer --help
 
 ## Examples
 
-### List GPU offers
+### Filtering offers
 
 The `--gpu` flag accepts the same specification format as the `gpu` property in [`dev environment`](../../../concepts/dev-environments.md), [`task`](../../../concepts/tasks.md), 
 [`service`](../../../concepts/services.md), and [`fleet`](../../../concepts/fleets.md) configurations.
@@ -71,6 +71,34 @@ Getting offers...
 
 </div>
 
+### Grouping offers
+
+Use `--group-by` to aggregate offers. Accepted values: `gpu`, `backend`, `region`, and `count`.
+
+<div class="termy">
+
+```shell
+dstack offer --gpu b200 --group-by gpu,backend,region
+ Project      main
+ User         admin
+ Resources    cpu=2.. mem=8GB.. disk=100GB.. b200:1..
+ Spot policy  auto
+ Max price    -
+ Reservation  -
+ Group by     gpu, backend, region
+
+ #   GPU              SPOT             $/GPU       BACKEND  REGION
+ 1   B200:180GB:1..8  spot, on-demand  3.59..5.99  runpod   EU-RO-1
+ 2   B200:180GB:1..8  spot, on-demand  3.59..5.99  runpod   US-CA-2
+ 3   B200:180GB:8     on-demand        4.99        lambda   us-east-1
+ 4   B200:180GB:8     on-demand        5.5         nebius   us-central1
+```
+
+</div>
+
+When using `--group-by`, `gpu` must always be `included`.
+The `region` value can only be used together with `backend`.
+
 ### JSON format
 
 Use `--json` to output offers in the JSON format.

src/dstack/_internal/cli/commands/offer.py

@@ -1,29 +1,20 @@
 import argparse
-import contextlib
-import json
 from pathlib import Path
+from typing import List
 
 from dstack._internal.cli.commands import APIBaseCommand
-from dstack._internal.cli.services.configurators.run import (
-    BaseRunConfigurator,
-)
+from dstack._internal.cli.services.configurators.run import BaseRunConfigurator
 from dstack._internal.cli.utils.common import console
-from dstack._internal.cli.utils.run import print_run_plan
-from dstack._internal.core.models.configurations import (
-    ApplyConfigurationType,
-    TaskConfiguration,
-)
+from dstack._internal.cli.utils.gpu import print_gpu_json, print_gpu_table
+from dstack._internal.cli.utils.run import print_offers_json, print_run_plan
+from dstack._internal.core.errors import CLIError
+from dstack._internal.core.models.configurations import ApplyConfigurationType, TaskConfiguration
 from dstack._internal.core.models.runs import RunSpec
+from dstack._internal.server.schemas.gpus import GpuGroup
 from dstack.api.utils import load_profile
 
 
 class OfferConfigurator(BaseRunConfigurator):
-    # TODO: The command currently uses `BaseRunConfigurator` to register arguments.
-    #   This includes --env, --retry-policy, and other arguments that are unnecessary for this command.
-    #   Eventually, we should introduce a base `OfferConfigurator` that doesn't include those arguments—
-    #   `BaseRunConfigurator` will inherit from `OfferConfigurator`.
-    #
-    #   Additionally, it should have its own type: `ApplyConfigurationType.OFFER`.
     TYPE = ApplyConfigurationType.TASK
 
     @classmethod
@@ -32,10 +23,18 @@ def register_args(
         parser: argparse.ArgumentParser,
     ):
         super().register_args(parser, default_max_offers=50)
+        parser.add_argument(
+            "--group-by",
+            action="append",
+            help=(
+                "Group results by fields ([code]gpu[/code], [code]backend[/code], [code]region[/code], [code]count[/code]). "
+                "Optional, but if used, must include [code]gpu[/code]. "
+                "The use of [code]region[/code] also requires [code]backend[/code]. "
+                "Can be repeated or comma-separated (e.g. [code]--group-by gpu,backend[/code])."
+            ),
+        )
 
 
-# TODO: Support aggregated offers
-# TODO: Add tests
 class OfferCommand(APIBaseCommand):
     NAME = "offer"
     DESCRIPTION = "List offers"
@@ -70,49 +69,58 @@ def _command(self, args: argparse.Namespace):
             ssh_key_pub="(dummy)",
             profile=profile,
         )
+
+        if args.group_by:
+            args.group_by = self._process_group_by_args(args.group_by)
+
+        if args.group_by and "gpu" not in args.group_by:
+            group_values = ", ".join(args.group_by)
+            raise CLIError(f"Cannot group by '{group_values}' without also grouping by 'gpu'")
+
         if args.format == "plain":
-            status = console.status("Getting offers...")
+            with console.status("Getting offers..."):
+                if args.group_by:
+                    gpus = self._list_gpus(args, run_spec)
+                    print_gpu_table(gpus, run_spec, args.group_by, self.api.project)
+                else:
+                    run_plan = self.api.client.runs.get_plan(
+                        self.api.project,
+                        run_spec,
+                        max_offers=args.max_offers,
+                    )
+                    print_run_plan(run_plan, include_run_properties=False)
         else:
-            status = contextlib.nullcontext()
-        with status:
-            run_plan = self.api.client.runs.get_plan(
-                self.api.project,
-                run_spec,
-                max_offers=args.max_offers,
-            )
-
-        job_plan = run_plan.job_plans[0]
-
-        if args.format == "json":
-            # FIXME: Should use effective_run_spec from run_plan,
-            # since the spec can be changed by the server and plugins
-            output = {
-                "project": run_plan.project_name,
-                "user": run_plan.user,
-                "resources": job_plan.job_spec.requirements.resources.dict(),
-                "max_price": (job_plan.job_spec.requirements.max_price),
-                "spot": run_spec.configuration.spot_policy,
-                "reservation": run_plan.run_spec.configuration.reservation,
-                "offers": [],
-                "total_offers": job_plan.total_offers,
-            }
-
-            for offer in job_plan.offers:
-                output["offers"].append(
-                    {
-                        "backend": (
-                            "ssh" if offer.backend.value == "remote" else offer.backend.value
-                        ),
-                        "region": offer.region,
-                        "instance_type": offer.instance.name,
-                        "resources": offer.instance.resources.dict(),
-                        "spot": offer.instance.resources.spot,
-                        "price": float(offer.price),
-                        "availability": offer.availability.value,
-                    }
+            if args.group_by:
+                gpus = self._list_gpus(args, run_spec)
+                print_gpu_json(gpus, run_spec, args.group_by, self.api.project)
+            else:
+                run_plan = self.api.client.runs.get_plan(
+                    self.api.project,
+                    run_spec,
+                    max_offers=args.max_offers,
                 )
+                print_offers_json(run_plan, run_spec)
 
-            print(json.dumps(output, indent=2))
-            return
-        else:
-            print_run_plan(run_plan, include_run_properties=False)
+    def _process_group_by_args(self, group_by_args: List[str]) -> List[str]:
+        valid_choices = {"gpu", "backend", "region", "count"}
+        processed = []
+
+        for arg in group_by_args:
+            values = [v.strip() for v in arg.split(",") if v.strip()]
+            for value in values:
+                if value in valid_choices:
+                    processed.append(value)
+                else:
+                    raise CLIError(
+                        f"Invalid group-by value: '{value}'. Valid choices are: {', '.join(sorted(valid_choices))}"
+                    )
+
+        return processed
+
+    def _list_gpus(self, args: List[str], run_spec: RunSpec) -> List[GpuGroup]:
+        group_by = [g for g in args.group_by if g != "gpu"] or None
+        return self.api.client.gpus.list_gpus(
+            self.api.project,
+            run_spec,
+            group_by=group_by,
+        )