improving docs

cm/cmind/repo/README.md

@@ -1,14 +1,15 @@
 # Internal Collective Mind repository
 
 [![CM artifact](https://img.shields.io/badge/Artifact-automated%20and%20reusable-blue)](https://github.com/mlcommons/ck/tree/master/cm)
+[![CMX repository](https://img.shields.io/badge/CMX-compatible-blue)](https://github.com/mlcommons/ck/tree/master/cm)
+[![CMX repository](https://img.shields.io/badge/Common%20Metadata%20eXchange-compatible-blue)](https://github.com/mlcommons/ck/tree/master/cm)
 [![CM repository](https://img.shields.io/badge/Collective%20Mind-compatible-blue)](https://github.com/mlcommons/ck/tree/master/cm)
 
-This internal repository contains CM-compatible artifacts and automations 
-that were moved to the CM core to ensure their stability 
-because they are frequently used by the community.
+This internal repository hosts CM and CMX-compatible artifacts and
+automations that have been integrated into the CMX core to ensure
+stability, as they are frequently used by the community.
 
-* Authors: Grigori Fursin
-* Contributors:
+* Author: Grigori Fursin
 
 * Copyright: https://github.com/mlcommons/ck/blob/master/COPYRIGHT.txt
 * License: https://github.com/mlcommons/ck/blob/master/LICENSE.md

cm/cmind/repo/cmr.yaml

@@ -1,3 +1,4 @@
 uid: "36b263b05174aef9"
 alias: internal
 desc: "internal CM repository"
+author: "Grigori Fursin"

cmx/TOC.md

@@ -2,9 +2,9 @@
 
 * [Installation (Linux, Windows, MacOS)](install.md)
 * [Understanding CMX](understanding-cmx.md)
-* [CMX commands to share and reuse artifacts with common metadata](commands.md)
-* [CMX automation commands for related artifacts](cmx-automations.md)
+* [CMX commands to share and reuse artifacts with common metadata](common-automation-actions.md)
+* [CMX automation actions for related artifacts](specific-automation-actions.md)
 * [Reusing CMX automations and artifacts for MLOps, DevOps and MLPerf](cmx4mlops.md)
-* [CMX Python API](https://cknowledge.org/docs/cmx)
-* [CMX internal architecture](architecture-4.0.0.png)
+* [Creating new artifacts and automations](cmx4mlops.md)
+* [Improving CMX framework](improving-cmx.md)
 * [Motivation](motivation.md)

cmx/commands.md → cmx/common-automation-actions.md

@@ -1,10 +1,9 @@
 [ [Back to documentation](README.md) ]
 
-# CMX commands
+# CMX commands (automation actions) applicable to all artifacts
 
 
-
-## Command Line
+## CMX command line
 
 ```bash
 $ cmx {action} {automation} [CMX options] [CMX automation action flags]
@@ -14,18 +13,21 @@ CMX options have format -key=value or -key (value=True)
 
 CMX automation flags have format --key=value or --key (value=True) 
 
-Common actions for all automations (`cmx -h`):
- * `find` automation (artifact)
+Common actions for all artifacts and automations (`cmx -h`):
+ * `find` automation (artifact) - find artifacts based on alias, UID and tags
  * `load` automation (artifact) - load metadata of a give artifact referenced either by alias or UID or alias,UID or --tags
  * `update` automation (artifact) - update metadata of a given artifact 
- * `add` automation (artifact)
- * `rm` automation (artifact)
- * `mv` automation (repo:)artifact new_repo:
- * `copy`automation (repo:)artifact (new repo:)new_artifact
- * `help` automation - print available actions for a given automation 
+ * `add` automation (artifact) - add new artifact
+ * `rm` automation (artifact) - remove artifact(s)
+ * `mv` automation (repo:)artifact (new_repo:)new_artifact - rename artifact or move to another CMX repository
+ * `copy`automation (repo:)artifact (new repo:)new_artifact - copy artifact to another repository with a new UID
+ * `help` automation - print available actions for a given automation
 
 You can add -h to above actions to see related flags for a given automation action
 
+*These actions are inherited by all CMX automations from this 
+ [CMX Automation Class](https://github.com/mlcommons/ck/blob/master/cm/cmind/automation.py).*
+
 ## Default automations
 
 When you install [CMX/CM](https://access.cknowledge.org/playground/?action=install), you have the following automations

cmx/improving-cmx.md

@@ -0,0 +1,8 @@
+[ [Back to documentation](README.md) ]
+
+# Improving CMX
+
+* [CMX GitHub repository (Python cmind package)](https://github.com/mlcommons/ck/tree/master/cm)
+* [CMX GitHub internal repo](https://github.com/mlcommons/ck/tree/master/cm/cmind/repo)
+* [CMX internal architecture - diagram](architecture-4.0.0.png)
+* [CMX internal classes and data structures](https://cknowledge.org/docs/cmx)

cmx/mlperf-inference/README.md

@@ -0,0 +1,11 @@
+# MLPerf automations
+
+[Common Metadata eXchange and Collective Mind frameworks](https://github.com/mlcommons/ck/tree/master/cm) 
+have helped [the community](https://github.com/mlcommons/ck/blob/master/CONTRIBUTORS.md) 
+learn how to modularize and automate MLPerf inference benchmarks
+through [unified MLOps and MLPerf automations with extensible metadata](https://access.cknowledge.org/playground/?action=scripts).
+
+Here, we maintain an archive of various unified CM and CMX commands for running different versions of MLPerf benchmarks.
+
+You can also check the [CM/CMX commands](https://github.com/aryatschand/MLPerf-Power-HPCA-2025/blob/main/measurement_tutorial.md) 
+to run experiments from the [HPCA'25 paper "MLPerf Power: Benchmarking the Energy Efficiency of Machine Learning Systems from Microwatts to Megawatts for Sustainable AI"](https://arxiv.org/abs/2410.12032).

cmx/understanding-cmx.md

@@ -11,7 +11,7 @@ This common metadata includes extensible tags, a user-friendly alias, and an aut
 enabling everyone to find and reuse both public and private artifacts in accordance with [FAIR principles](https://en.wikipedia.org/wiki/FAIR_data) 
 (findable, accessible, interoperable, and reusable).
 
-At the same time, CMX allows users to share and reuse common automations 
+CMX also allows users to add, share and reuse common automations 
 with a unified CLI and Python API, applying them to related artifacts
 based on their common metadata.
 
@@ -96,6 +96,7 @@ as follows:
 ```bash
 fursin@laptop:~$ pip install cmind
 fursin@laptop:~$ cmx pull repo mlcommons@ck --dir=cmx4mlops/cmx4mlops
+fursin@laptop:~$ cmx show repo
 fursin@laptop:~$ cmx find script
 
 /home/fursin/CM/repos/mlcommons@ck/cmx4mlops/cmx4mlops/repo/script/app-image-classification-torch-py
@@ -137,7 +138,7 @@ allowing you to reuse artifacts and automations across different projects.
 
 All CMX artifacts contain a minimal set of keys in their metadata files.
 
-For example, the CMX script artifact `app-image-classification-torch-py`, 
+For example, the CMX script artifact [`app-image-classification-torch-py`](https://github.com/mlcommons/ck/tree/master/cmx4mlops/cmx4mlops/repo/script/app-image-classification-torch-py), 
 which includes PyTorch code for classifying images using the reference ResNet50 model, 
 has the following `_cm.yaml` format:
 
@@ -195,10 +196,65 @@ for artifact in artifacts:
 
 ## Understanding CMX automations
 
+All CMX artifacts must be associated with a corresponding CMX automation 
+that defines common actions based on the artifact's metadata.
 
+When one creates a new type of artifact, CMX will automatically generate a related automation 
+that inherits [common actions](common-automation-actions.md) 
+to manage all types of artifacts, including  `find/search`, `add`, `delete/rm`, `move/mv`, `copy/cp`, `load`, and `update`.
 
+For example, the metadata of the CMX script artifact [`app-image-classification-torch-py`](https://github.com/mlcommons/ck/blob/master/cmx4mlops/cmx4mlops/repo/script/app-image-classification-torch-py/_cm.yaml#L4)
+specifies its associated CMX automation:
 
+```yaml
+automation_alias: script
+automation_uid: 5b4e0237da074764
+```
 
+This allows CMX to find a related automation and determine which common actions 
+can be applied to this artifact based on its metadata.
 
+If we run the command `cmx load script app-image-classification-torch-py`, CMX will:
+* *search* for existing `script` automation in all `automation` directories across all CMX repositories.
+* *Locate* it in [`automation/script`](https://github.com/mlcommons/ck/tree/master/cmx4mlops/cmx4mlops/repo/automation/script).
+* *Load* `modulex.py` (for CMX) or [`module.py`](https://github.com/mlcommons/ck/blob/master/cmx4mlops/cmx4mlops/repo/automation/script/module.py) (for CM)
+* *Invoke* the  `load` function in the CAutomation class (which inherits common actions 
+  for all artifacts from the [CMX Automation class](https://github.com/mlcommons/ck/blob/master/cm/cmind/automation.py)).
+* *Pass* a unified CM/CMX input dictionary `{'artifact':'app-image-classification-torch-py' ...}`
+
+The [common `load` function](https://github.com/mlcommons/ck/blob/master/cm/cmind/automation.py#L627) 
+will, in turn:
+* *Search* for this artifact in all CMX repositories
+* *Load* tha artifact's metadata from `_cm.yaml` and/or `_cm.json`
+* *Print* the metadata to the console as JSON
+
+If the same command is invoked through the CMX Python API, it will return metadata as a unified CMX dictionary:
+
+```bash
+
+$ python
+
+import cmind
+r = cmind.x({'action':'load', 'automation':'script', 'artifact':'app-image-classification-torch-py'})
+
+print (r)
+
+{'return': 0, 'path': '...', 'meta': {'alias': 'app-image-classification-torch-py', 'automation_alias': 'script', 
+ 'automation_uid': '5b4e0237da074764', 'category': 'Modular AI/ML application pipeline', ...
+```
 
-To be continued...
+We can also implement automation actions tailored specifically for this group of artifacts.
+For example, we have implemented the 'run' action for scripts, enabling the execution 
+of both native and Python scripts on any platform, regardless of the operating system, 
+in a unified, portable, and deterministic manner:
+
+If we now run the command `cmx run script app-image-classification-torch-py`, CMX will
+invoke the [`run`](https://github.com/mlcommons/ck/blob/master/cmx4mlops/cmx4mlops/repo/automation/script/module.py#L96) 
+function within the `script` automation and execute it based on the [metadata](https://github.com/mlcommons/ck/blob/master/cmx4mlops/cmx4mlops/repo/script/app-image-classification-torch-py/_cm.yaml)
+of the `app-image-classification-torch-py` artifact.
+
+This covers the core CM/CMX concepts, which facilitate collaborative and
+reproducible research, development, and experimentation. They help users
+progressively modularize, unify, and extend complex projects using common
+and interconnected metadata and reusable automation. For example, the community has successfully
+applied this approach to [modularize and automate MLPerf benchmarks](https://arxiv.org/abs/2406.16791).

cmx4mlops/README.md

@@ -64,5 +64,5 @@ Visit the [parent Collective Knowledge project](https://github.com/mlcommons/ck)
 
 ## Citing this project
 
-If you found the CM automations helpful, kindly reference this article:
+If you found the CM and CMX automations helpful, kindly reference this article:
 [ [ArXiv](https://arxiv.org/abs/2406.16791) ]