mirrorneuron-cli 1.0.0__py3-none-any.whl

mirrorneuron_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: mirrorneuron-cli
+Version: 1.0.0
+Summary: MirrorNeuron CLI
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mirrorneuron-python-sdk
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Dynamic: license-file
+
+# MirrorNeuron CLI
+
+The official Command Line Interface for managing the MirrorNeuron distributed runtime system.
+
+## Installation
+*Note: This tool is installed automatically and symlinked globally as `mn` by the MirrorNeuron `install.sh` script.*
+
+```bash
+pip install mirrorneuron-cli
+```
+
+## Commands
+Powered by Typer and Rich, this CLI provides elegant formatting for job lifecycle management:
+
+```bash
+mn nodes                 # View system summary and available executor pools
+mn submit ./flow.json    # Submit a new workflow manifest
+mn list                  # View all active and completed jobs
+mn status <job_id>       # Detailed execution state of a specific job
+mn monitor <job_id>      # Stream live execution events
+mn cancel <job_id>       # Gracefully terminate a workflow
+mn metrics               # Inspect runtime metrics summary
+mn dead-letters <job_id> # Inspect dead-letter events
+```
+
+## Blueprint Commands
+
+Blueprint execution and observability are grouped under `mn blueprint` so users have one CLI entry point:
+
+```bash
+mn blueprint list
+mn blueprint install
+mn blueprint update
+mn blueprint run <blueprint_id>
+mn blueprint run ./path/to/bundle_or_source_blueprint
+mn blueprint run <blueprint_id> --offline
+mn blueprint run <blueprint_id> --revision <git_sha_or_tag>
+mn blueprint monitor --follow
+mn blueprint tail <run_id>
+mn blueprint compare <run_a> <run_b>
+mn blueprint export <run_id> --format markdown
+mn blueprint export <run_id> --format html
+```
+
+`mn blueprint run` accepts either an installed blueprint ID or a local folder. If the local folder is already a bundle, the CLI submits it directly; if it is a Python source blueprint, the CLI generates a bundle under `~/.mn/generated_blueprint_bundles/<run_id>/` first. Catalog runs use the cached blueprint library by default so runs are not silently changed by a network pull. Use `mn blueprint update` or `mn blueprint run <id> --update` when you want to refresh the cache. Each blueprint submission pre-generates a shared `MN_RUN_ID`, injects `MN_BLUEPRINT_CONFIG_JSON` into runtime workers, and prints both the blueprint run ID and runtime job ID.
+
+Blueprint run artifacts are read from the shared run store at `~/.mn/runs/<run_id>/`.
+Use `--runs-root <path>` with `monitor`, `tail`, `compare`, or `export` when inspecting a custom run directory.
+When a blueprint registers a shared or custom web UI, `monitor` shows the local URL and `export --format html` creates a static report page.
+
+## Configuration
+
+All overrides use `MN_` env vars:
+
+- `MN_GRPC_TARGET`: core gRPC target.
+- `MN_GRPC_TIMEOUT_SECONDS`: RPC timeout; `0` or `none` disables it.
+- `MN_GRPC_AUTH_TOKEN`: optional bearer metadata for protected core gateways.
+- `MN_CLI_LOG_PATH`: error log path.
+- `MN_CLI_OUTPUT=plain`: disable Rich color output.

mirrorneuron_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+mirrorneuron_cli-1.0.0.dist-info/licenses/LICENSE,sha256=wdEmA-XJ6EaXHsjFyuRKhT-owNT5-ucLf6jbtOz0yOM,1072
+mn_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mn_cli/config.py,sha256=fJfjiM__uHGStgz7jsuSN52HK3LOv76omhwWmR74hEk,1343
+mn_cli/error_handler.py,sha256=2k1PLN777U8EY90BpM3N7XtO3osPbzPzmraclWYYgYI,2276
+mn_cli/logging_config.py,sha256=AXHLgpcJHPEGd-axGrtTt_bslRQwr6eQ8Dxvmp0jK_I,982
+mn_cli/main.py,sha256=jShrxF1wszLKhKND4y6O5y3iQ007CO05pzwYZGBxpTc,1100
+mn_cli/server_cmds.py,sha256=n4rctjJbx9ZvCNMpIHniXvsO2QhSRhZ_HZvM7phPDJE,12162
+mn_cli/shared.py,sha256=aK2_mDXezAZsCiyRskPxdXmxUcjubKB7yGUGNzu7ylo,420
+mn_cli/libs/__init__.py,sha256=1IXSLNPLt2HhYADcj4mt_jQBK0nd1tCwkIfIwB6ycYo,26
+mn_cli/libs/blueprint_cmds.py,sha256=l7OBr4rS6c5febGLbUscoqP9xyDTqvrEPI8kD3l2fSc,24481
+mn_cli/libs/job_cmds.py,sha256=cO4AoqTVRQNLzQGRCGZUBnUa_3ATT6g_8Lp9BKb-9qc,5447
+mn_cli/libs/run_cmds.py,sha256=AYaH7J1RYhDAEVDDld2LLg2OLjRjng7OtWyMSkd7hO0,30046
+mn_cli/libs/sys_cmds.py,sha256=LIeWoxUwZADMZfTnkrz1L5MIP3wugE_yiKjm9LRvKBU,1881
+mn_cli/libs/ui.py,sha256=3qyEx2d0JFidcvP1IRq246D8l5rBaXqrlkOFx9NHHh0,5824
+mirrorneuron_cli-1.0.0.dist-info/METADATA,sha256=njQm3tMNA6dtz5eN95G4_WZm7xgwq6zh3sfPLq4bv-Q,3162
+mirrorneuron_cli-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mirrorneuron_cli-1.0.0.dist-info/entry_points.txt,sha256=e7vGuYEi_HV-mIYTbRbhfTGQMn04y-ItDDAdCTMYHdQ,39
+mirrorneuron_cli-1.0.0.dist-info/top_level.txt,sha256=yE-PY4RVgDSFkh0okxYE9UHWVBU5xEsyL8G2ZA_xEAE,7
+mirrorneuron_cli-1.0.0.dist-info/RECORD,,

mirrorneuron_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mirrorneuron_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mn = mn_cli.main:app

mirrorneuron_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MirrorNeuronLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mirrorneuron_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mn_cli

mn_cli/config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CliConfig:
+    grpc_target: str = "localhost:50051"
+    grpc_timeout_seconds: float | None = 10.0
+    grpc_auth_token: str = ""
+    log_path: Path = Path.home() / ".mn" / "logs" / "cli.log"
+    output_mode: str = "rich"
+
+    @classmethod
+    def from_env(cls) -> "CliConfig":
+        core_host = os.getenv("MN_CORE_HOST", "localhost")
+        return cls(
+            grpc_target=os.getenv(
+                "MN_GRPC_TARGET",
+                os.getenv("MN_CORE_GRPC_TARGET", f"{core_host}:50051"),
+            ),
+            grpc_timeout_seconds=_timeout(),
+            grpc_auth_token=os.getenv("MN_GRPC_AUTH_TOKEN", ""),
+            log_path=Path(
+                os.getenv(
+                    "MN_CLI_LOG_PATH",
+                    str(Path.home() / ".mn" / "logs" / "cli.log"),
+                )
+            ).expanduser(),
+            output_mode=os.getenv("MN_CLI_OUTPUT", "rich"),
+        )
+
+
+def _timeout() -> float | None:
+    value = os.getenv("MN_GRPC_TIMEOUT_SECONDS", "10")
+    if value.lower() in {"", "none", "0"}:
+        return None
+    try:
+        return float(value)
+    except ValueError as exc:
+        raise ValueError("MN_GRPC_TIMEOUT_SECONDS must be a number, 0, or none") from exc

mn_cli/error_handler.py

@@ -0,0 +1,51 @@
+import sys
+import grpc
+from rich.console import Console
+from mn_cli.config import CliConfig
+from mn_cli.logging_config import configure_logging
+
+log_file = CliConfig.from_env().log_path
+logger = configure_logging("mn-cli", log_file)
+
+CONTEXT_MESSAGES = {
+    "submit": "Error submitting job",
+    "status": "Error fetching job status",
+    "list_jobs": "Error listing jobs",
+    "clear": "Error clearing jobs",
+    "cancel": "Error cancelling job",
+    "pause": "Error pausing job",
+    "resume": "Error resuming job",
+    "nodes": "Error fetching nodes",
+    "metrics": "Error fetching metrics",
+    "dead_letters": "Error listing dead letters",
+    "run bundle": "Error running bundle",
+    "monitor stream": "Error fetching job",
+    "fetch results": "Error fetching results",
+    "validate": "Validation failed",
+    "leave": "Error removing node",
+}
+
+def handle_cli_error(e: Exception, console: Console, context: str = ""):
+    """Handle exceptions gracefully, log the full trace, and print a friendly message."""
+    logger.exception(f"Error during {context}")
+    
+    if isinstance(e, grpc.RpcError):
+        code = e.code()
+        details = e.details()
+        
+        if code == grpc.StatusCode.NOT_FOUND:
+            console.print(f"[red]Error: Cannot find the job by ID. ({details})[/red]")
+        elif code == grpc.StatusCode.INTERNAL and "not found" in str(details).lower():
+            console.print(f"[red]Error: Cannot find the job by ID. ({details})[/red]")
+        elif code == grpc.StatusCode.INTERNAL and "terminal state" in str(details).lower():
+            console.print(f"[red]Error: Job is already in a terminal state and cannot be modified.[/red]")
+        elif code == grpc.StatusCode.RESOURCE_EXHAUSTED:
+            console.print("[yellow]Runtime is under CPU/GPU/memory pressure and is not accepting new jobs.[/yellow]")
+            console.print(f"[dim]{details}[/dim]")
+        else:
+            console.print(f"[red]Communication Error: {details} (Code: {code.name})[/red]")
+            console.print(f"[dim]See {log_file} for full details.[/dim]")
+    else:
+        prefix = CONTEXT_MESSAGES.get(context, "Error")
+        console.print(f"[red]{prefix}: {str(e)}[/red]")
+        console.print(f"[dim]See {log_file} for full details.[/dim]")

mn_cli/libs/__init__.py

@@ -0,0 +1 @@
+# Initialization for libs