comet-ml
diff --git a/‎README-ADMIN.md‎
Lines changed: 73 additions & 0 deletions b/‎README-ADMIN.md‎
Lines changed: 73 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 49 additions & 0 deletions b/‎README.md‎
Lines changed: 49 additions & 0 deletions
diff --git a/‎cometx/cli/admin.py‎
Lines changed: 93 additions & 0 deletions b/‎cometx/cli/admin.py‎
Lines changed: 93 additions & 0 deletions
@@ -122,3 +122,76 @@ When using the `--app` flag, an interactive web interface is launched where you
 - Select workspace and project from dropdowns
 - View statistics and charts interactively
 - Change time units and regenerate reports
+
+## growth-report
+
+Generate a cross-platform use-case growth & adoption report — Opik projects, EM projects,
+and MPM monitored models — as a single self-contained HTML page. This is distinct from
+`usage-report` (an experiment-count PDF): `growth-report` tracks *how many use cases exist
+and how fast they're being created*, per workspace/department, across all three products.
+
+### Basic Usage
+
+```shell
+cometx admin growth-report
+cometx admin growth-report my-workspace
+cometx admin growth-report my-workspace another-workspace
+```
+
+If no workspace is given, all workspaces visible to the current API key are used.
+
+### Options
+
+- **`WORKSPACE ...`**: Zero or more workspaces to include. If omitted, resolved via `get_workspaces()`.
+- **`--units {month,week,day,hour}`**: Chart bucket granularity (default: `month`). Charts always render **all-time** history at this granularity — this is a separate concept from `--window`, below.
+- **`--window WINDOW`**: Relative analysis window for the KPI numbers, e.g. `7d`, `14d`, `30d`, `90d`, `2w`, `6m`, `1y` (default: `7d`). Format is `\d+[dwmy]`: `d`=days, `w`=weeks (×7 days), `m`=months (approximated as 30 days), `y`=years (approximated as 365 days). The month/year approximation is intentional — the window is only used to compute an "installed base before window" cutoff, not calendar-exact arithmetic.
+- **`--platforms PLATFORMS`**: Comma-separated platforms to include (default: `em,opik,mpm`).
+- **`--output PATH`**: Output HTML file path (default: `growth_report.html`).
+- **`--limit N`**: Limit the number of workspaces processed — useful for a fast smoke-test run.
+- **`--no-open`**: Don't automatically open the generated HTML file after generation.
+
+### The two time concepts
+
+- **`--units`** is the *chart granularity*: every chart shows the complete all-time history bucketed at this resolution.
+- **`--window`** is the *KPI analysis window*: Total/New/% Growth numbers compare "in the last `--window`" against "before the window." On the charts, the window is drawn as a shaded band overlaid on the all-time series, rather than filtering the data.
+
+### Growth rates
+
+Growth and adoption rates are computed directly from use-case **creation timestamps**:
+`pct_growth = new_in_window / count_before_window`, where `count_before_window` is the
+number of use cases created before `window.start` and `new_in_window` is the number
+created inside `[window.start, window.end]`.
+
+### Examples
+
+```shell
+# Full cross-platform report for all workspaces, default 7-day window
+cometx admin growth-report
+
+# Just Opik + EM, 30-day window, for two workspaces
+cometx admin growth-report --platforms em,opik --window 30d my-workspace another-workspace
+
+# Fast smoke-test run against a single workspace, don't auto-open
+cometx admin growth-report --limit 1 --no-open --output growth.html my-workspace
+```
+
+### Output
+
+The growth report generates a single self-contained HTML file containing:
+
+- A **unified section** ("Use cases across all platforms") with department/use-case KPIs, a stacked created-per-period chart broken down by kind (Opik/EM/MPM), a use-cases-by-department chart, and a breakdown table.
+- Per-product **growth** sections (Opik / EM / MPM) with Total / New / % Growth KPIs, a new-use-cases bar chart, a cumulative area chart (both carrying the analysis window as a shaded band), and a breakdown table.
+- Per-product **adoption** sections with secondary usage metrics — Opik span counts, EM experiment counts, MPM prediction volume — each broken down by project.
+
+The breakdown tables follow one rule throughout: when more than one workspace is included,
+tables break down **by workspace/department**; when only a single workspace is included,
+tables break down **by individual use case** instead (a by-workspace table with one row
+would be uninformative).
+
+### Caveats
+
+- **EM "created" is a proxy.** The Comet API has no true EM project-creation timestamp, so an EM project's creation time is approximated as the earliest experiment start time in that project, falling back to the project's `lastUpdated` time if it has no experiments.
+- **Workspace/department "created" is also a proxy** — the earliest use-case creation timestamp seen in that workspace, across all platforms.
+- **The EM model-registry engagement panel is a snapshot**, not an over-time series ("Registered models" / "Model versions" per workspace) — it is kept in its own labeled panel and is **never** combined with MPM's monitored-model counts, even though both are "model" concepts.
+- **MPM requires provisioning.** If the account/workspace has no MPM model-monitoring provisioned, the MPM collector degrades gracefully — an empty MPM section and `collectors.mpm: false` in the underlying report data — rather than failing the whole report.
+- Opik and MPM collection require their optional SDKs (`opik`, `comet_mpm`). Install them with `pip install 'cometx[all]'` if not already available; any platform whose SDK can't be imported is silently dropped from `--platforms` (a note is printed to the console) so the report still succeeds with the remaining platforms.
@@ -578,6 +578,55 @@ cometx admin usage-report workspace --units day --no-open
 cometx admin usage-report --app
 ```
 
+#### growth-report
+
+Generate a cross-platform use-case growth & adoption report (Opik projects, EM projects,
+MPM monitored models) as a single self-contained HTML page. Distinct from `usage-report`
+(experiment-count PDF): `growth-report` tracks *how many use cases exist and how fast
+they're being created*, per workspace/department, across all three products.
+
+```
+cometx admin growth-report [WORKSPACE ...]
+```
+
+**Arguments:**
+* `WORKSPACE` (optional, zero or more) - Workspaces to include. If omitted, all workspaces visible to the current API key are used (via `get_workspaces()`).
+
+**Options:**
+* `--units {month,week,day,hour}` - Chart bucket granularity (default: month). Charts always render **all-time** history at this granularity; this is unrelated to `--window` below.
+* `--window WINDOW` - Relative analysis window for the KPIs, e.g. `7d`, `14d`, `30d`, `90d`, `2w`, `6m`, `1y` (default: `7d`). `d`=days, `w`=weeks (×7d), `m`=months (approximated as 30 days), `y`=years (approximated as 365 days) — the approximation is intentional, since the window only needs an "installed base before window" cutoff, not calendar-exact arithmetic.
+* `--platforms PLATFORMS` - Comma-separated list of platforms to include (default: `em,opik,mpm`). Any of `em`, `opik`, `mpm`.
+* `--output PATH` - Output HTML file path (default: `growth_report.html`).
+* `--limit N` - Limit the number of workspaces processed (useful for a fast smoke-test run).
+* `--no-open` - Don't automatically open the generated HTML file after generation.
+
+**Two time concepts:**
+* `--units` controls chart *granularity* — every chart shows the full all-time history bucketed at this resolution.
+* `--window` controls the *analysis window* used for the KPI numbers (Total / New / % growth) — it's drawn as a shaded band on top of the all-time charts rather than filtering them out.
+
+**Growth rates:** growth/adoption rates are computed from use-case **creation timestamps**
+(`--window` boundary vs. each event's `created` time), not from a separate "installed base"
+snapshot, so `pct_growth` is always `new_in_window / count_before_window`.
+
+**Caveats:**
+* **EM "created" is a proxy** — the Comet API has no true EM project-creation timestamp, so EM project creation is approximated as the earliest experiment start time in that project (falling back to the project's `lastUpdated` time if no experiments exist).
+* **Workspace/department "created" is also a proxy** — it's the earliest use-case creation timestamp seen in that workspace, across all platforms.
+* **MPM requires provisioning** — if the account/workspace has no MPM model-monitoring provisioned, the MPM collector degrades gracefully (an empty MPM section, `collectors.mpm: false`) instead of failing the whole report.
+
+Opik and MPM collection require their optional SDKs; install them with `pip install 'cometx[all]'` if they aren't already available. Platforms whose SDK can't be imported are silently dropped from `--platforms` (a note is printed) so the report still succeeds with the remaining platforms.
+
+**Examples:**
+```
+# Full cross-platform report for all workspaces, default 7-day window
+cometx admin growth-report
+
+# Just Opik + EM, 30-day window, monthly chart granularity, for two workspaces
+cometx admin growth-report --platforms em,opik --window 30d my-workspace another-workspace
+
+# Fast smoke-test run against a single workspace, don't auto-open
+cometx admin growth-report --limit 1 --no-open --output growth.html my-workspace
+```
+
 #### gpu-report
 
 Generate a GPU usage report for one or more workspaces/projects with detailed GPU metrics analysis.
 
@@ -154,6 +154,7 @@
 from comet_ml import API
 
 from .admin_gpu_report import main as gpu_report_main
+from .admin_growth_report import generate_growth_report
 from .admin_optimizer_report import generate_json_report
 from .admin_usage_report import generate_usage_report
 
@@ -461,6 +462,79 @@ def get_parser_arguments(parser):
         action="store_true",
     )
 
+    # growth-report subcommand
+    growth_report_description = """Generate a cross-platform use-case growth report for one or more workspaces.
+
+Arguments:
+    WORKSPACE (optional, one or more)
+        One or more workspaces to run the growth report for.
+        If not provided, all workspaces are included.
+
+Output:
+    Generates a self-contained HTML page containing cross-platform (Opik + EM + MPM)
+    use-case growth and rate charts, broken down by workspace/department.
+
+Examples:
+    cometx admin growth-report
+    cometx admin growth-report my-workspace
+    cometx admin growth-report workspace1 workspace2 --units week
+    cometx admin growth-report my-workspace --window 30d
+    cometx admin growth-report my-workspace --platforms em,opik
+    cometx admin growth-report my-workspace --output report.html --no-open
+"""
+    growth_parser = subparsers.add_parser(
+        "growth-report",
+        help="Generate a cross-platform use-case growth report for one or more workspaces",
+        description=growth_report_description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    # Add global arguments to subparser so they show in help
+    add_global_arguments(growth_parser)
+    growth_parser.add_argument(
+        "WORKSPACE",
+        nargs="*",
+        help="One or more workspaces to run the growth report for (empty = all)",
+        metavar="WORKSPACE",
+        type=str,
+    )
+    growth_parser.add_argument(
+        "--units",
+        help="Time unit for chart bucket granularity (default: month)",
+        choices=["month", "week", "day", "hour"],
+        default="month",
+        type=str,
+    )
+    growth_parser.add_argument(
+        "--window",
+        help="Relative analysis window for KPIs, e.g. 7d/14d/30d/90d (default: 7d)",
+        default="7d",
+        type=str,
+    )
+    growth_parser.add_argument(
+        "--platforms",
+        help="Comma-separated list of platforms to include (default: em,opik,mpm)",
+        default="em,opik,mpm",
+        type=str,
+    )
+    growth_parser.add_argument(
+        "--output",
+        help="Output HTML file path (default: growth_report.html)",
+        default="growth_report.html",
+        type=str,
+    )
+    growth_parser.add_argument(
+        "--limit",
+        help="Optional limit on the number of items collected per platform",
+        type=int,
+        default=None,
+    )
+    growth_parser.add_argument(
+        "--no-open",
+        help="Don't automatically open the generated HTML file",
+        default=False,
+        action="store_true",
+    )
+
 
 def admin(parsed_args, remaining=None):
     # Called via `cometx admin ...`
@@ -746,6 +820,25 @@ def admin(parsed_args, remaining=None):
 
                         traceback.print_exc()
                     return
+        elif parsed_args.ACTION == "growth-report":
+            try:
+                generate_growth_report(
+                    api,
+                    parsed_args.WORKSPACE,
+                    window=parsed_args.window,
+                    units=parsed_args.units,
+                    platforms=parsed_args.platforms,
+                    output=parsed_args.output,
+                    no_open=parsed_args.no_open,
+                    limit=parsed_args.limit,
+                )
+            except Exception as e:
+                print("ERROR: " + str(e))
+                if parsed_args.debug:
+                    import traceback
+
+                    traceback.print_exc()
+                return
 
     except KeyboardInterrupt:
         if parsed_args.debug: