Update readme and cli experience, remove previous edits on existing examples

Author: quic-boyuc

backends/qualcomm/debugger/README.md

@@ -90,28 +90,38 @@ Note: Files ending with `.bin ` do not support graph visualization in qairt_visu
 For more details, visit the [QAIRT Visualizer](https://pypi.org/project/qairt-visualizer/).
 
 
-# Observatory 
+# Observatory
+
 A new, review-focused Observatory implementation is available under:
 
 `backends/qualcomm/debugger/observatory`
 
-Use observaotry.cli to invoke ordinary aot script. Use `--lens_recipe=accuracy` to enable accuracy Lenses.
+Use the Observatory CLI to wrap any Qualcomm AOT export script. Use `--lens_recipe=accuracy`
+to enable accuracy lenses.
 
 ```bash
- python -m executorch.backends.qualcomm.debugger.observatory.cli \
-        --output-html obs_report.html \
-        --lens_recipe=accuracy \
-        {original script and args}
+python -m executorch.backends.qualcomm.debugger.observatory \
+    --output-html obs_report.html \
+    --lens_recipe=accuracy \
+    {original script and args}
 ```
-For example
+
+For example:
 
 ```bash
-python -m executorch.backends.qualcomm.debugger.observatory.cli \
+python -m executorch.backends.qualcomm.debugger.observatory \
     --output-html obs_report.html \
     --lens_recipe=accuracy \
-    examples/qualcomm/oss_scripts/mobilevit_v2.py --backend htp --model SM8650 -d ./imagenet-mini-val/ -b build-android/ --compile_only
+    examples/qualcomm/oss_scripts/mobilevit_v2.py \
+    --backend htp --model SM8650 -d ./imagenet-mini-val/ -b build-android/ --compile_only
 ```
 
+> **Note**: Qualcomm example scripts (e.g. `oss_scripts/roberta.py`) use only absolute imports
+> and are run as plain scripts. The Observatory CLI auto-selects `runpy.run_path` for these since
+> their directories do not contain `__init__.py`.
+
+See `backends/qualcomm/debugger/observatory/README.md` for full documentation.
+
 # ExecuTorch QNN Intermediate Output Debugger
 
 ExecuTorch QNN Intermediate Output Debugger is a tool that helps users debug intermediate output accuracy by comparing CPU outputs with QNN outputs. This tool offers a variety of output formats and flexibility for users to define their own metrics when debugging.

backends/xnnpack/debugger/observatory/cli.py

@@ -25,7 +25,7 @@
 
 
 def main():
-    from devtools.observatory.cli import (
+    from executorch.devtools.observatory.cli import (
         make_collect_parser,
         make_visualize_parser,
         run_observatory,
@@ -49,8 +49,8 @@ def main():
     )
     args = parser.parse_args(sys.argv[1:])
 
-    from devtools.observatory.observatory import Observatory
-    from devtools.observatory.lenses.pipeline_graph_collector import (
+    from executorch.devtools.observatory.observatory import Observatory
+    from executorch.devtools.observatory.lenses.pipeline_graph_collector import (
         PipelineGraphCollectorLens,
     )
     from .lenses.xnnpack_patches import install_xnnpack_patches
@@ -60,11 +60,11 @@ def main():
     Observatory.register_lens(PipelineGraphCollectorLens)
 
     if args.lens_recipe == "accuracy":
-        from devtools.observatory.lenses.accuracy import AccuracyLens
+        from executorch.devtools.observatory.lenses.accuracy import AccuracyLens
 
         Observatory.register_lens(AccuracyLens)
 
-        from devtools.observatory.lenses.per_layer_accuracy import (
+        from executorch.devtools.observatory.lenses.per_layer_accuracy import (
             PerLayerAccuracyLens,
         )
 

devtools/fx_viewer/exporter.py

@@ -389,8 +389,9 @@ def _sweep_min_gap(nids):
             # Phase 1: chain detection (real + dummy members)
             chains = cls._detect_chains(el or [], nodes)
 
+            FAIR_RUNS=5
             # Phase 2: iterative spine cohesion + pure-A overlap fix
-            for i in range(cls._SPINE_COHESION_ITER + 2):
+            for i in range(cls._SPINE_COHESION_ITER + FAIR_RUNS):
 
                 # delta for each node
                 # We record the relative weight (chain length) and their base delta
@@ -399,7 +400,7 @@ def _sweep_min_gap(nids):
                     if not ch:
                         continue
                     mean_x = sum(x[v] for v in ch) / len(ch)
-                    # emphasize end point
+                    # emphasize end point (disable for last FAIR_RUNS iters)
                     if i < cls._SPINE_COHESION_ITER:
                         # we use common start and end node of chain to attract chain close together
                         mean_x = (mean_x + x[ch[0]] + x[ch[-1]]) / 3.0

devtools/observatory/README.md

@@ -59,6 +59,10 @@ python -m executorch.backends.xnnpack.debugger.observatory \
     --model_name=mv2 --delegate --quantize --output_dir /tmp/mv2
 ```
 
+> **XNNPack note**: `aot_compiler.py` uses relative imports so it must run as a Python module.
+> The CLI auto-detects this from `__init__.py` presence. You can also pass the dotted module
+> name directly: `examples.xnnpack.aot_compiler`
+
 This produces:
 - `/tmp/obs/report.html` (interactive report)
 - `/tmp/obs/report.json` (raw data, path auto-derived from HTML path)
@@ -232,7 +236,6 @@ return AnalysisResult(per_record_data={"step_1": record_analysis})
 | [USAGE.md](USAGE.md) | CLI usage guide, workflow examples, demo script modes |
 | [lenses/LENSES.md](lenses/LENSES.md) | Built-in lens details, accuracy lens internals, custom lens patterns |
 | [REFERENCE.md](REFERENCE.md) | Contract tables, API reference, JS callbacks, performance notes |
-| [lenses/DEBUG_HANDLE_SYNC_ANALYSIS.md](lenses/DEBUG_HANDLE_SYNC_ANALYSIS.md) | Technical analysis of debug_handle consistency across pipeline stages |
 
 ## Tests
 

devtools/observatory/USAGE.md

@@ -32,6 +32,11 @@ python -m executorch.backends.xnnpack.debugger.observatory \
     --model_name=mv2 --delegate --quantize --output_dir /tmp/mv2
 ```
 
+> **XNNPack note**: `examples/xnnpack/aot_compiler.py` uses relative imports (`from . import ...`).
+> The CLI auto-detects this: when a `.py` path is given and its directory contains `__init__.py`,
+> it runs via `runpy.run_module` instead of `runpy.run_path`. You can also pass a dotted module
+> name directly (e.g. `examples.xnnpack.aot_compiler`) to force module mode explicitly.
+
 ## 2. Convert JSON to HTML (Visualize Mode)
 
 Use the `visualize` subcommand to convert an existing JSON file to HTML without

devtools/observatory/cli.py

@@ -83,6 +83,41 @@ def run_visualize(input_json: str, output_html: str) -> None:
     )
 
 
+def _resolve_run_mode(script: str) -> tuple[str, str, str | None]:
+    """Return (mode, target, pkg_root).
+
+    mode='module': target is a dotted module name; pkg_root is prepended to sys.path.
+    mode='script':  target is an absolute file path; pkg_root is None.
+
+    Detection rules (in order):
+    1. No '.py' suffix and no path separator → explicit dotted module name → 'module'
+    2. File path whose directory has __init__.py → walk up to find package root → 'module'
+    3. Everything else → 'script'
+    """
+    if not script.endswith(".py") and os.sep not in script and "/" not in script:
+        return "module", script, None
+
+    abs_path = os.path.abspath(script)
+    script_dir = os.path.dirname(abs_path)
+
+    if not os.path.isfile(os.path.join(script_dir, "__init__.py")):
+        return "script", abs_path, None
+
+    parts = [os.path.splitext(os.path.basename(abs_path))[0]]
+    current = script_dir
+    while True:
+        parts.insert(0, os.path.basename(current))
+        parent = os.path.dirname(current)
+        if parent == current or not os.path.isfile(
+            os.path.join(parent, "__init__.py")
+        ):
+            pkg_root = parent
+            break
+        current = parent
+
+    return "module", ".".join(parts), pkg_root
+
+
 def run_observatory(
     script_path: str,
     script_argv: list[str],
@@ -102,14 +137,46 @@ def run_observatory(
             output_json = "observatory_report.json"
 
     title = f"Observatory: {os.path.basename(script_path)}"
+    mode, target, pkg_root = _resolve_run_mode(script_path)
 
     try:
         with Observatory.enable_context(config={}):
-            runpy.run_path(script_path, run_name="__main__")
+            if mode == "module":
+                if pkg_root is not None and pkg_root not in sys.path:
+                    sys.path.insert(0, pkg_root)
+                logging.info("[Observatory CLI] Running as module: %s", target)
+                runpy.run_module(target, run_name="__main__", alter_sys=True)
+            else:
+                logging.info("[Observatory CLI] Running as script: %s", target)
+                runpy.run_path(target, run_name="__main__")
     except SystemExit:
         pass
+    except ImportError as exc:
+        logging.error("[Observatory CLI] Import error in '%s': %s", script_path, exc)
+        if "relative import" in str(exc) or "attempted relative import" in str(exc):
+            logging.error(
+                "  Hint: this script uses relative imports and must run as a Python module.\n"
+                "  Option A — ensure the script's directory contains __init__.py so it is\n"
+                "             auto-detected as a package member.\n"
+                "  Option B — pass a dotted module name instead of a file path:\n"
+                "             python -m executorch.devtools.observatory"
+                " <package>.<subpackage>.<module> [args...]"
+            )
+        elif mode == "module":
+            logging.error(
+                "  Hint: module '%s' could not be imported.\n"
+                "  Ensure the package root '%s' is on PYTHONPATH or the package is installed.",
+                target,
+                pkg_root or "unknown",
+            )
     except Exception as exc:
-        logging.error("[Observatory CLI] Script raised: %s", exc)
+        logging.error(
+            "[Observatory CLI] '%s' raised: %s  (run mode: %s, target: %s)",
+            os.path.basename(script_path),
+            exc,
+            mode,
+            target,
+        )
     finally:
         os.makedirs(os.path.dirname(output_html) or ".", exist_ok=True)
         os.makedirs(os.path.dirname(output_json) or ".", exist_ok=True)