Document uv setup and desktop viewer quick start

README.md

@@ -29,26 +29,111 @@ the workload and rendering limits.
 Inputs include scientific **HIF**, native **`hypergraph.v1`** JSON, and supported
 legacy exports. The model is domain-agnostic: vertices, hyperedges, and memberships.
 
-## Python and scientific interoperability
+## Quick start: desktop viewer
 
-Install the **`hypergraph-viz`** Python distribution with **CPython 3.10+**:
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then open
+the built-in coauthorship demo with one command:
 
 ```bash
-python -m pip install hypergraph-viz
+uvx --python 3.12 --from hypergraph-viz-viewer hyper
 ```
 
-The import name is `hyper_viz`. Wheels cover Linux x86_64, macOS arm64/x86_64,
-and Windows x86_64; a compatible wheel requires no Rust compiler. Install the native desktop viewer through the optional extra:
+To open your own HIF or native Hyper JSON file:
 
 ```bash
+uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json --projection bipartite
+```
+
+No project, repository checkout, or Rust compiler is needed. `--from` selects
+**`hypergraph-viz-viewer`**, the package containing the **`hyper`** executable.
+See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/).
+
+Desktop wheels support Linux x86_64 (glibc 2.28+), macOS arm64/x86_64 (11.0+),
+and Windows x86_64. A desktop session and working graphics driver are required.
+The viewer opens on the machine running the command; it does not embed in a notebook.
+
+## Use Hyper from Python
+
+Create a project with Python 3.12 and install the API plus matching desktop viewer:
+
+```bash
+uv init --python 3.12 hyper-example
+cd hyper-example
+uv add "hypergraph-viz[viewer]"
+```
+
+In an existing uv project using Python 3.10+, run just the `uv add` command.
+uv manages `.venv` and `uv.lock` and can download Python 3.12 if needed.
+`uv run` uses the project environment without activation.
+See the [uv project guide](https://docs.astral.sh/uv/guides/projects/).
+
+Save this complete example as `explore.py`:
+
+```python
+import json
+import hyper_viz
+
+document = hyper_viz.HifDocument.from_json(json.dumps({
+    "network-type": "undirected",
+    "nodes": [{"node": "alice"}, {"node": "bob"}, {"node": "carol"}],
+    "edges": [{"edge": "team"}],
+    "incidences": [
+        {"node": "alice", "edge": "team"},
+        {"node": "bob", "edge": "team"},
+        {"node": "carol", "edge": "team"},
+    ],
+}))
+document.save("team.hif.json")
+
+viewer = hyper_viz.show(document, projection="bipartite")
+exit_code = viewer.wait()  # Or viewer.close() to terminate and clean up.
+```
+
+Run it:
+
+```bash
+uv run explore.py
+```
+
+For an existing dataset, replace the constructor with
+`document = hyper_viz.HifDocument.load("dataset.hif.json")`.
+You can also open the exported example directly with `uv run hyper team.hif.json`.
+
+| What you need | Package / command |
+|---|---|
+| Standalone desktop viewer | `uvx --python 3.12 --from hypergraph-viz-viewer hyper` |
+| Python API and desktop viewer | `uv add "hypergraph-viz[viewer]"` |
+| HIF validation and interchange only | `uv add hypergraph-viz` |
+| Python import | `import hyper_viz` |
+
+The API requires CPython 3.10+. `hypergraph-viz` has no executable of its own,
+so `uvx hypergraph-viz` cannot launch the viewer. For interchange alone, omit
+`show()` from your script; the core package has no Bevy dependency.
+
+<details>
+<summary>Install with pip instead</summary>
+
+Use a Python 3.10+ virtual environment. For example, with Python 3.12 installed:
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
 python -m pip install --upgrade "hypergraph-viz[viewer]"
+python explore.py
 ```
 
-Use `--upgrade` when the core package is already installed so pip selects the
-release that provides the viewer extra. The viewer needs a desktop session and
-graphics driver. Linux desktop wheels
-require glibc 2.28+; macOS targets 11.0+. Rust is needed only for source builds.
-For a Python development build from this checkout with **Rust 1.89+**:
+On Windows, create the environment with `py -3.12 -m venv .venv` and activate
+it in PowerShell with `.venv\Scripts\Activate.ps1`.
+For interchange alone, use `python -m pip install hypergraph-viz`.
+If pip reports no matching distribution, check `python --version`: upgrading
+pip does not upgrade Python, and Xcode's Python 3.9 is too old.
+
+</details>
+
+<details>
+<summary>Build the Python extension from this checkout</summary>
+
+Source builds require Rust 1.89+ and CPython 3.10+:
 
 ```bash
 python -m venv .venv
@@ -59,17 +144,10 @@ maturin develop --locked
 cd ../..
 ```
 
-```python
-import hyper_viz
-
-document = hyper_viz.HifDocument.load("dataset.hif.json")
-document.save("roundtrip.hif.json")
-print(document.to_json())
+This builds the core extension. Install the viewer extra separately if you want
+prebuilt desktop launching, or build the native viewer with Cargo.
 
-# Install hypergraph-viz[viewer] first.
-viewer = hyper_viz.show(document, projection="bipartite")
-exit_code = viewer.wait() # or viewer.close() to terminate
-```
+</details>
 
 Pass `executable="/path/to/hyper"` to select a viewer explicitly. Otherwise the
 launcher finds the matching companion package, then `hyper` on PATH. The launcher

crates/hyper-viz-python/README.md

@@ -7,10 +7,21 @@ The package includes generated extension type stubs, typed Python wrappers, and
 
 ## Installation
 
+With [uv](https://docs.astral.sh/uv/getting-started/installation/), create a project
+with a supported Python version and add the package:
+
 ```sh
-python -m pip install hypergraph-viz
+uv init --python 3.12 hyper-example
+cd hyper-example
+uv add hypergraph-viz
 ```
 
+uv manages `.venv` and `uv.lock`, and can download Python 3.12 if needed.
+Save your Python code as `explore.py` and run it with `uv run explore.py`.
+In an existing uv project, run only `uv add hypergraph-viz`.
+Alternatively, use `python -m pip install hypergraph-viz` in a Python 3.10+
+virtual environment. Upgrading pip does not upgrade Python.
+
 Requires standard CPython 3.10 or newer. Platform wheels cover Linux x86_64,
 macOS arm64/x86_64, and Windows x86_64; installing a compatible wheel requires
 no Rust compiler. Building from source requires Rust 1.89 or newer and maturin.
@@ -40,22 +51,44 @@ not preserved.
 
 ## Launch the native viewer
 
-Install the matching prebuilt desktop viewer with the optional extra:
+From your uv project, install the matching prebuilt desktop viewer:
 
 ```sh
-python -m pip install --upgrade "hypergraph-viz[viewer]"
+uv add "hypergraph-viz[viewer]"
+uv run hyper
 ```
 
+`uv run hyper` opens the built-in demo; use
+`uv run hyper dataset.hif.json --projection bipartite` for your own dataset.
+For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"`.
+
+To launch only the desktop viewer without creating a project:
+
+```sh
+uvx --python 3.12 --from hypergraph-viz-viewer hyper
+# Open your dataset:
+uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json
+```
+
+`--from` selects the distribution that supplies the `hyper` executable.
+`hypergraph-viz` supplies the Python API and has no executable of its own;
+use `uv add "hypergraph-viz[viewer]"` for Python integration in a project.
+See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/).
+
 Wheels cover Linux x86_64, macOS arm64/x86_64, and Windows x86_64. No Rust
 compiler or repository checkout is needed on these platforms. A desktop session
 and graphics driver are required. Linux viewer wheels require glibc 2.28+;
 macOS wheels target 11.0+. Notebook kernels on remote machines cannot open a
 window on your laptop; see the
 [notebook prototype roadmap](https://github.com/atomicstrata/hyper/blob/python-v0.1.2/docs/NOTEBOOK_ROADMAP.md).
 
-Then launch it from Python:
+Save the following as `explore.py` alongside `dataset.hif.json`, then run
+`uv run explore.py`:
 
 ```python
+import hyper_viz
+
+document = hyper_viz.HifDocument.load("dataset.hif.json")
 viewer = hyper_viz.show(document, projection="bipartite")
 exit_code = viewer.wait()
 # Or viewer.close() to terminate and clean up.

docs/DESKTOP_PACKAGE.md

@@ -1,12 +1,39 @@
 # Hyper desktop viewer
 
 Prebuilt native viewer for [hypergraph-viz](https://pypi.org/project/hypergraph-viz/).
-Install the Python API and matching viewer together:
+Launch the built-in demo with [uv](https://docs.astral.sh/uv/getting-started/installation/):
 
 ```sh
-python -m pip install --upgrade "hypergraph-viz[viewer]"
+uvx --python 3.12 --from hypergraph-viz-viewer hyper
 ```
 
+Open your own dataset:
+
+```sh
+uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json
+```
+
+`--from` selects this package, which supplies the `hyper` executable.
+See [uv's tool guide](https://docs.astral.sh/uv/guides/tools/).
+
+For Python integration, install the API and matching viewer in a project:
+
+```sh
+uv init --python 3.12 hyper-example
+cd hyper-example
+uv add "hypergraph-viz[viewer]"
+```
+
+In an existing uv project using Python 3.10+, run only `uv add`.
+Save the Python example below as `explore.py` alongside `dataset.hif.json`,
+then run `uv run explore.py`. No environment activation is needed.
+uv can download Python 3.12 when necessary.
+`hypergraph-viz` provides the Python API and has no executable of its own;
+`uvx hypergraph-viz` cannot launch the viewer.
+
+For pip, use `python -m pip install --upgrade "hypergraph-viz[viewer]"` in a
+Python 3.10+ virtual environment.
+
 ```python
 import hyper_viz