feat: Sync mlia

.github/workflows/release.yml

@@ -9,6 +9,7 @@ on:
       - main
     tags:
       - "v*.*.*"
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -61,8 +62,16 @@ jobs:
 
   publish_release:
     name: Publish Release
+    if: >-
+      ${{
+        always() &&
+        needs.build_and_test_wheel.result == 'success' &&
+        (github.repository_owner != 'arm' || github.ref_type == 'tag')
+      }}
     needs: build_and_test_wheel
     runs-on: ${{ fromJson(vars.UBUNTU_RUNNER || '["ubuntu-24.04-arm"]') }}
+    env:
+      PUBLISH_PYPI_HOST: ${{ secrets.PUBLISH_PYPI_HOST || '' }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -71,8 +80,17 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
       - run: uv build
-      - run: uv publish dist/*
+      - if: ${{ env.PUBLISH_PYPI_HOST != '' }}
+        run: uv publish dist/*
         env:
-          UV_PUBLISH_URL: ${{ secrets.PUBLISH_PYPI_HOST }}
+          UV_PUBLISH_URL: ${{ env.PUBLISH_PYPI_HOST }}
           UV_PUBLISH_USERNAME: ${{ secrets.INTERNAL_PYPI_USERNAME || secrets.PUBLISH_PYPI_USERNAME }}
           UV_PUBLISH_PASSWORD: ${{ secrets.INTERNAL_PYPI_PASSWORD || secrets.PUBLISH_PYPI_PASSWORD }}
+
+  sync_to_public_repo:
+    needs: build_and_test_wheel
+    if: ${{ github.event.repository.private }}
+    uses: Arm-Debug/github-workflow-wizardry/.github/workflows/sync-to-public-repo.yml@main
+    with:
+      public_repo: arm/mlia
+    secrets: inherit

README.md

@@ -44,7 +44,10 @@ Use the core docs for:
 - shared CLI guidance: [docs/source/cli.md](docs/source/cli.md)
 - backend discovery and installation model: [docs/source/backends.md](docs/source/backends.md)
 - output structure and JSON results: [docs/source/metrics.md](docs/source/metrics.md)
-- architecture and repo boundaries: [docs/source/overview.md](docs/source/overview.md)
+- architecture and repo boundaries:
+  [docs/source/overview.md](docs/source/overview.md),
+  [docs/source/high_level_architecture.md](docs/source/high_level_architecture.md),
+  and [docs/source/execution_flow.md](docs/source/execution_flow.md)
 
 Target-specific, backend-specific, and converter-specific detail belongs in the
 plugin repo that owns that functionality.
@@ -153,9 +156,9 @@ If you need `torch.nn.Module` inputs, install the optional extra:
 pip install mlia[torch]
 ```
 
-The Python API follows the same plugin-based architecture as the CLI: the core package
-provides the entry points and shared output structure, while installed plugins
-extend what targets and backends are available.
+The Python API follows the same plugin-based architecture as the CLI: the core
+package provides the entry points and shared output structure, while installed
+plugins extend what targets and backends are available.
 
 ## Development
 

docs/README.md

@@ -11,7 +11,9 @@ This directory contains the MkDocs content for the `mlia` repository.
 
 - `source/index.md`: documentation landing page
 - `source/overview.md`: role of the core repo in the split MLIA ecosystem
+- `source/high_level_architecture.md`: core runtime layers and extension boundaries
 - `source/plugin_architecture.md`: how the core repo relates to plugin repos
+- `source/execution_flow.md`: shared `mlia check` command, API, data, and artifact flow
 - `source/cli.md`: command-line entry points and common workflows
 - `source/backends.md`: backend discovery, installation, and responsibility boundaries
 - `source/metrics.md`: output formats, schema shape, and metrics guidance

docs/source/execution_flow.md

@@ -0,0 +1,149 @@
+<!---
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0
+--->
+
+# End-to-end Execution Flow
+
+This page follows a typical `mlia check` run from the command line to final
+reports. Plugin-specific collectors, analyzers, converters, and backend tools may
+vary, but the core orchestration path is shared.
+
+Use this page for runtime ordering and failure handling. For the static module
+layout, see [High-level Architecture](high_level_architecture.md). For plugin
+discovery and extension points, see [Plugin Architecture](plugin_architecture.md).
+
+## Command flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI as mlia CLI
+    participant Commands as mlia.cli.commands
+    participant API as mlia.api
+    participant TargetReg as Target registry
+    participant BackendReg as Backend registry
+    participant BackendMgr as Backend manager
+    participant Advisor as Target advisor
+    participant Workflow as Workflow executor
+    participant Reports as Output handlers
+
+    User->>CLI: mlia check model --target-profile profile --performance
+    CLI->>CLI: Parse args and create ExecutionContext
+    CLI->>Commands: check(ctx, target_profile, model, flags, backends)
+    Commands->>API: get_advice(target_profile, model, category, context, backends)
+    API->>TargetReg: Resolve profile and target
+    TargetReg->>BackendReg: Ensure backend plugins loaded
+    TargetReg->>TargetReg: Ensure target plugins loaded
+    API->>API: Validate advice category and backend selection
+    API->>BackendMgr: ensure_backends_installed(validated_backends)
+    API->>TargetReg: Get target advisor factory
+    TargetReg-->>API: Advisor factory
+    API->>Advisor: Create advisor for target profile and model
+    API->>Advisor: run(context)
+    Advisor->>Workflow: Configure collectors/analyzers/producers/events
+    Workflow->>Workflow: Collect data
+    Workflow->>Workflow: Analyze data
+    Workflow->>Workflow: Detect patterns when configured
+    Workflow->>Reports: Produce advice and publish events
+    Reports-->>User: Console output, JSON output, files, logs
+```
+
+## Runtime responsibilities
+
+| Step | Core owner | What happens |
+| --- | --- | --- |
+| Parse command | `mlia.cli.main` | Builds an argument parser from core and CLI plugin commands. |
+| Build context | `mlia.cli.main.setup_context()` | Creates `ExecutionContext`, resolves output format, output directory, action resolver, and logging. |
+| Select advice category | `mlia.cli.commands.check()` | Converts `--compatibility` and `--performance` flags into an advice-category set. |
+| Validate target/profile | `mlia.cli.command_validators`, `mlia.target.registry` | Confirms the selected target profile supports the requested category. |
+| Validate backends | `mlia.api.get_advice()` | Resolves requested backends against the target and supported backend registry. |
+| Ensure backend installation | `mlia.backend.manager` | Checks or installs backends as required, subject to EULA and noninteractive settings. |
+| Create advisor | `mlia.api.get_advisor()` | Finds the target from the profile and calls the target's advisor factory. |
+| Run workflow | `mlia.core.advisor`, `mlia.core.workflow` | Executes collectors, analyzers, optional pattern analyzers, and advice producers. |
+| Produce output | `mlia.core.reporting`, event handlers, output schema helpers | Emits console output, logs, generated files, and JSON-compatible data when requested. |
+
+## Conceptual data flow
+
+```mermaid
+graph LR
+    model[Input model] --> command[mlia check]
+    profile[Target profile TOML] --> command
+    backendOptions[Backend options] --> command
+
+    command --> context[ExecutionContext]
+    context --> outputDir[Output directory]
+    context --> logs[logs/mlia.log]
+
+    model --> collectors[Data collectors]
+    profile --> advisor[Target advisor]
+    advisor --> collectors
+    collectors --> maybeConvert{Converter needed?}
+    maybeConvert -->|yes| converter[Converter plugin]
+    converter --> intermediate[Converted/intermediate artifact]
+    maybeConvert -->|no| backendInput[Backend input artifact]
+    intermediate --> backendInput
+    backendInput --> backend[Backend tool or service]
+    backend --> rawResults[Raw backend output]
+    rawResults --> analyzers[Data analyzers]
+    analyzers --> facts[Analyzed facts]
+    facts --> producers[Advice producers]
+    producers --> advice[Advice]
+    advice --> events[Events]
+    events --> handlers[Event handlers and reporters]
+    handlers --> reports[Reports and JSON output]
+    reports --> outputDir
+```
+
+The exact collector inputs, converted artifact names, backend outputs, and
+analyzer facts are plugin-owned. The core guarantees the shared execution
+context, workflow stages, event publishing, and output/reporting mechanisms.
+
+## Failure flow
+
+MLIA failures normally terminate the command and return a non-zero exit status.
+The CLI always reports the run output directory at the end of command execution.
+Unless `--output-dir` is set, logs and generated artifacts are written under
+`mlia-output` in the current working directory. The main log file is
+`mlia-output/logs/mlia.log`.
+
+In normal CLI output, handled errors are intentionally short:
+
+```text
+Execution finished with error: <message>
+Please check the log files in the mlia-output/logs for more details, or enable debug mode (--debug)
+This execution of MLIA used output directory: mlia-output
+```
+
+With `--debug`, MLIA prints debug logging to the console and records debug logs
+in `mlia-output/logs/mlia.log`. For unexpected exceptions, `--debug` also shows
+the Python traceback. Handled error categories, such as configuration errors,
+backend availability errors, and interrupted execution, are still displayed as
+concise messages.
+
+The CLI handles these categories specially:
+
+| Failure category | User-visible behavior |
+| --- | --- |
+| Configuration error | Prints the configuration error message directly. |
+| Backend unavailable | Prints `Error: Backend <name> is not available.` Some optional backends also include an installation hint, for example `mlia-backend install "<name>"`. |
+| Interrupted execution | Prints `Execution has been interrupted`. |
+| Internal error | Prints `Internal error: <message>`. |
+| Other exception | Prints `Execution finished with error: <message>`, points to the log directory, and shows a traceback when `--debug` is enabled. |
+
+Inside the workflow, exceptions from collection, analysis, pattern detection, or
+advice production are first published as an `ExecutionFailedEvent`. That event
+contains the original exception in its `err` field so event handlers can observe
+or transform the failure. The default workflow event handler re-raises that
+exception, so the CLI error handling described above still decides what the user
+sees.
+
+## API flow
+
+Python callers can use `mlia.api` directly instead of invoking the CLI. The API
+path still validates target profiles, backend selection, backend installation,
+and advisor creation. `run_advisor()` additionally supports returning a
+standardized JSON-compatible dictionary and optional schema validation modes.
+
+Use the CLI when you want the standard command-line user experience. Use the API
+when another Python tool needs to run MLIA and consume structured results.

docs/source/high_level_architecture.md

@@ -0,0 +1,83 @@
+<!---
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0
+--->
+
+# High-level Architecture
+
+MLIA is a Python application and library built around one core package and
+installable plugins. The core package owns the shared user experience and
+runtime contracts; plugins add target, backend, converter, or CLI functionality
+through Python entry points.
+
+Use this page for the static system shape. For plugin loading details, see
+[Plugin Architecture](plugin_architecture.md). For the step-by-step
+`mlia check` path, see [End-to-end Execution Flow](execution_flow.md).
+
+## System view
+
+```mermaid
+graph TD
+    user[User] --> mainCli[mlia]
+    user --> backendCli[mlia-backend]
+    user --> targetCli[mlia-target]
+    automation[Automation or Python caller] --> api[Python API]
+
+    mainCli --> checkCommand[mlia.cli.commands.check]
+    mainCli --> cliPlugins[CLI plugin commands]
+    checkCommand --> api
+
+    backendCli --> backendCommands[backend install/list/uninstall]
+    targetCli --> targetCommands[target list]
+
+    api --> context[ExecutionContext]
+    api --> targetRegistry[Target registry]
+    api --> backendRegistry[Backend registry]
+    api --> backendManager[Installation manager]
+    api --> advisorFactory[Target advisor factory]
+
+    targetRegistry --> targetPlugins[Target plugins]
+    backendRegistry --> backendPlugins[Backend plugins]
+    advisorFactory --> advisor[InferenceAdvisor]
+
+    advisor --> workflow[DefaultWorkflowExecutor]
+    workflow --> collectors[Data collectors]
+    workflow --> analyzers[Data analyzers]
+    workflow --> patterns[Pattern analyzers]
+    workflow --> producers[Advice producers]
+    workflow --> events[Event publisher and handlers]
+
+    collectors --> backends[Backend tools and services]
+    backendManager --> backends
+    backendCommands --> backendManager
+    targetCommands --> targetRegistry
+    producers --> advice[Advice]
+    advice --> events
+    events --> handlers[Event handlers and reporters]
+    handlers --> reports[Console, JSON, and output files]
+```
+
+## Main runtime layers
+
+| Layer | Core modules | Responsibility |
+| --- | --- | --- |
+| CLI | `mlia.cli.main`, `mlia.cli.commands`, `mlia.cli.options` | Parse `mlia`, `mlia-backend`, and `mlia-target` commands, create `ExecutionContext`, configure logging and output format, and call command functions. |
+| Public API | `mlia.api` | Validate inputs, resolve targets and backends, ensure required backends are installed, create advisors, optionally return standardized output. |
+| Registries | `mlia.target.registry`, `mlia.backend.registry`, `mlia.plugins.*` | Load plugin entry points once and expose registered target, backend, converter, and CLI capabilities. |
+| Backend management | `mlia.backend.manager`, `mlia.backend.install`, `mlia.backend.config` | Show backend status, install/uninstall backends, resolve dependencies, and provide backend configuration metadata. |
+| Execution context | `mlia.core.context` | Carry advice category, config parameters, output directory, action resolver, event publisher, handlers, and output format. |
+| Advisor/workflow | `mlia.core.advisor`, `mlia.core.workflow` | Build and run the target-specific workflow stages. |
+| Reporting/output | `mlia.core.reporting`, `mlia.core.reporters`, `mlia.core.output_schema`, `mlia.core.output_validation` | Produce human-readable and JSON-compatible results and validate standardized output. |
+
+## Ownership boundaries
+
+The core package should not need target-specific conditionals for every new
+hardware family or converter. Instead:
+
+- target plugins register target metadata and advisor factories
+- backend plugins register backend configuration and installation metadata
+- converter plugins register named converter callables
+- CLI plugins can append commands to the command list
+
+This keeps core orchestration stable while allowing target, backend, and
+converter packages to evolve independently.

docs/source/index.md

@@ -16,7 +16,9 @@ see the individual plugin repositories.
 ## Contents
 
 - [Overview](overview.md)
+- [High-level Architecture](high_level_architecture.md)
 - [Plugin Architecture](plugin_architecture.md)
+- [End-to-end Execution Flow](execution_flow.md)
 - [CLI](cli.md)
 - [API](api.md)
 - [Backends](backends.md)

docs/source/metrics.md

@@ -56,6 +56,40 @@ A simplified example:
 The exact contents of the output depend on the installed plugins, but the
 high-level structure stays stable.
 
+### Metric availability
+
+From schema version `1.1.0`, result metrics can be represented in two ways:
+
+- numeric metrics with `name`, `value`, and `unit`
+- unavailable metric entries with `name`, `unit`, `availability`, and `reason`
+
+For numeric metrics, omitted `availability` means that the value is available.
+Unavailable metric entries do not contain a placeholder `value`.
+
+This explicit availability marker is currently limited to the standardized
+performance fields added for this work: `accelerator_operator_percentage`,
+`inferences_per_second`, `cpu_utilization`, `target_utilization`,
+`peak_activation_memory`, and `average_memory`. It is not a complete availability
+map for every possible consumer field.
+
+Example metric entries:
+
+```json
+[
+  {
+    "name": "inferences_per_second",
+    "value": 4830.9,
+    "unit": "inferences/s"
+  },
+  {
+    "name": "cpu_utilization",
+    "unit": "%",
+    "availability": "unavailable",
+    "reason": "CPU utilization data is not available."
+  }
+]
+```
+
 ## How to read a result
 
 A recommended reading order is:

mkdocs.yml

@@ -25,14 +25,23 @@ markdown_extensions:
   - attr_list
   - def_list
   - footnotes
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
   - tables
   - toc:
       permalink: true
 
+extra_javascript:
+  - https://unpkg.com/mermaid@10.9.1/dist/mermaid.min.js
+
 nav:
   - Home: index.md
   - Overview: overview.md
+  - High-level Architecture: high_level_architecture.md
   - Plugin Architecture: plugin_architecture.md
+  - End-to-end Execution Flow: execution_flow.md
   - CLI: cli.md
   - API: api.md
   - Backends: backends.md

openspec/changes/add-standard-performance-metrics/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-13

openspec/changes/add-standard-performance-metrics/.openspec.yaml.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright 2026, Arm Limited and/or its affiliates.
+SPDX-License-Identifier: Apache-2.0