feat(rocpd): add AI-powered GPU trace analysis module (rocpd analyze)

.gitignore

@@ -1,2 +1,15 @@
 .cline_storage
 /projects/hip/_build
+
+# Claude Code session data
+.claude/
+**/.claude/
+
+# Python
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+
+# Analysis output generated during testing
+rocpd-output-data/

projects/rocprofiler-sdk/cmake/Modules/rocprofiler-sdk-utilities.cmake

@@ -56,6 +56,17 @@ function(rocprofiler_sdk_pc_sampling_disabled _VAR)
     set(CMAKE_MESSAGE_INDENT "[${PROJECT_NAME}]${ARG_PREFIX} ")
 
     rocprofiler_sdk_get_gfx_architectures(rocprofiler-sdk-tests-gfx-info ECHO)
+    # Guard against empty GPU list (e.g. build machine without GPUs)
+    list(LENGTH rocprofiler-sdk-tests-gfx-info _gfx_list_len)
+    if(_gfx_list_len EQUAL 0)
+        set(${_VAR}
+            TRUE
+            PARENT_SCOPE)
+        if(ARG_ECHO)
+            message(STATUS "PC Sampling is disabled (no GPUs detected)")
+        endif()
+        return()
+    endif()
     list(GET rocprofiler-sdk-tests-gfx-info 0 pc-sampling-gpu-0-gfx-info)
 
     if("${pc-sampling-gpu-0-gfx-info}" MATCHES "^gfx90a$"
@@ -88,6 +99,17 @@ function(rocprofiler_sdk_pc_sampling_stochastic_disabled _VAR)
     set(CMAKE_MESSAGE_INDENT "[${PROJECT_NAME}]${ARG_PREFIX} ")
 
     rocprofiler_sdk_get_gfx_architectures(rocprofiler-sdk-tests-gfx-info ECHO)
+    # Guard against empty GPU list (e.g. build machine without GPUs)
+    list(LENGTH rocprofiler-sdk-tests-gfx-info _gfx_list_len)
+    if(_gfx_list_len EQUAL 0)
+        set(${_VAR}
+            TRUE
+            PARENT_SCOPE)
+        if(ARG_ECHO)
+            message(STATUS "Stochastic PC Sampling is disabled (no GPUs detected)")
+        endif()
+        return()
+    endif()
     list(GET rocprofiler-sdk-tests-gfx-info 0 pc-sampling-gpu-0-gfx-info)
 
     if("${pc-sampling-gpu-0-gfx-info}" MATCHES "^gfx94[0-9]$"

projects/rocprofiler-sdk/source/bin/rocprofv3.py

@@ -1291,7 +1291,10 @@ def _write_env_value():
         args.output_format = ["rocpd"]
 
     update_env(
-        "ROCPROF_OUTPUT_FORMAT", ",".join(args.output_format), append=True, join_char=","
+        "ROCPROF_OUTPUT_FORMAT",
+        ",".join(args.output_format),
+        append=True,
+        join_char=",",
     )
 
     if args.kokkos_trace:

projects/rocprofiler-sdk/source/lib/python/rocpd/__main__.py

@@ -38,6 +38,7 @@ def main(argv=None, config=None):
 
     """
     import argparse
+    from . import analyze
     from . import csv
     from . import merge
     from . import otf2
@@ -123,6 +124,27 @@ def main(argv=None, config=None):
     Aggregate 2 databases and output all summary files to HTML, only include HIP and MARKER regions, include domain summary
     $ rocpd summary -i db{0,1}.db --region-categories HIP MARKERS --domain-summary --format html
 
+"""
+
+    analyze_examples = """
+
+Example usage:
+
+    Analyze performance of a single database
+    $ rocpd analyze -i db0.db
+
+    Analyze with output to file
+    $ rocpd analyze -i db0.db --format text -d ./output/ -o analysis
+
+    Analyze top 20 kernels instead of default 10
+    $ rocpd analyze -i db{0..3}.db --top-kernels 20
+
+    Analyze with a custom prompt (guides local analysis; enhances LLM output when --llm is used)
+    $ rocpd analyze -i db0.db --prompt "Why is my application slow?"
+
+    Analyze with LLM-enhanced explanation
+    $ rocpd analyze -i db0.db --llm anthropic
+
 """
     input_help_string = "Input path and filename to one or more database(s). Wildcards accepted, as well as .rpdb folders"
 
@@ -193,6 +215,14 @@ def add_required_args(_parser):
         epilog=summary_examples,
     )
 
+    analyzer = subparsers.add_parser(
+        "analyze",
+        description="Analyze GPU performance traces with AI-powered insights",
+        allow_abbrev=False,
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog=analyze_examples,
+    )
+
     def get_output_type(val):
         return val.lower().replace("perfetto", "pftrace")
 
@@ -213,6 +243,17 @@ def get_output_type(val):
     add_required_args(packager)
     add_required_args(query_reporter)
     add_required_args(generate_summary)
+    # analyze: -i is optional (not required when --source-dir is used for Tier 0)
+    _analyze_input_group = analyzer.add_argument_group("Required options")
+    _analyze_input_group.add_argument(
+        "-i",
+        "--input",
+        required=False,
+        default=None,
+        type=output_config.check_file_exists,
+        nargs="+",
+        help=input_help_string,
+    )
 
     # converter: add args from any sub-modules
     process_converter_args = []
@@ -243,6 +284,12 @@ def get_output_type(val):
     process_generate_summary_args.append(summary.add_args(generate_summary))
     process_generate_summary_args.append(time_window.add_args(generate_summary))
 
+    # analyze: subparser args
+    process_analyzer_args = []
+    process_analyzer_args.append(output_config.add_args(analyzer))
+    process_analyzer_args.append(analyze.add_args(analyzer))
+    process_analyzer_args.append(time_window.add_args(analyzer))
+
     # parse the command line arguments
     args = parser.parse_args(argv)
 
@@ -355,6 +402,43 @@ def get_output_type(val):
 
         summary.generate_all_summaries(input, **summary_args)
 
+    # if the user requested AI analysis, execute the analyzer
+    elif args.command == "analyze":
+        # Validate: at least one of -i, --source-dir, or --interactive must be provided
+        has_input = bool(getattr(args, "input", None))
+        has_source_dir = bool(getattr(args, "source_dir", None))
+        has_interactive = bool(getattr(args, "interactive", None))
+        if not has_input and not has_source_dir and not has_interactive:
+            analyzer.error(
+                "at least one of -i/--input, --source-dir, or --interactive is required.\n"
+                "  Use -i output.db for trace analysis (Tier 1/2).\n"
+                "  Use --source-dir ./src for source code analysis (Tier 0).\n"
+                '  Use --interactive "./my_app" for the 7-phase workflow.\n'
+                "  Use both -i and --source-dir for combined analysis."
+            )
+
+        # construct the rocpd import data object (None if source-only)
+        if has_input:
+            input = RocpdImportData(
+                args.input,
+                automerge_limit=getattr(
+                    args, "automerge_limit", package.IDEAL_NUMBER_OF_DATABASE_FILES
+                ),
+            )
+        else:
+            input = None
+
+        # analyzer subparser args
+        analyzer_args = {}
+        for pitr in process_analyzer_args:
+            analyzer_args.update(pitr(input, args))
+
+        # Pass source_dir if provided
+        if has_source_dir:
+            analyzer_args["source_dir"] = args.source_dir
+
+        analyze.execute(input, **analyzer_args)
+
     print("Done. Exiting...")