From 4d279402c783d246f688d9dc0395268568be5dac Mon Sep 17 00:00:00 2001 From: Bregy Malpartida Date: Tue, 6 Oct 2026 12:29:20 -0500 Subject: [PATCH 1/2] docs: add an agent prompt before the uv install step Coding agents need a pasteable prompt that launches the published viewer without a checkout or Rust toolchain. --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.md b/README.md index 653e11c..790cd36 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,20 @@ groups, and explore neighborhoods with search, picking, and lasso selection. ## Try the viewer +### For agents + +Paste this prompt: + +```text +Install uv if `uv` is not on PATH: https://docs.astral.sh/uv/getting-started/installation/ + +Open Hyper's built-in coauthorship demo. Do not clone a repository or install Rust: + +uvx --python 3.12 --from hypergraph-viz-viewer hyper + +Needs a desktop session and working graphics drivers. Wheels: Linux x86_64 (glibc 2.28+), macOS arm64/x86_64 (11.0+), Windows x86_64. The window opens on the machine running the command. To open a HIF file, append its path. +``` + Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then open the built-in coauthorship demo: From f05dce934cc8f67bd389f9b27380100b0fd85d92 Mon Sep 17 00:00:00 2001 From: Bregy Malpartida Date: Tue, 6 Oct 2026 13:04:10 -0500 Subject: [PATCH 2/2] docs: move the agent prompt into AGENTS.md AGENTS.md is the conventional agent entry point and keeps the commands, platform matrix, and desktop-session constraint in one place. The README links to it from a collapsed block, matching the existing pip and from-source blocks, so the human quick start stays first. --- AGENTS.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 18 ++++++++++-------- 2 files changed, 65 insertions(+), 8 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9ff81d6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,55 @@ +# Agent guide + +Instructions for coding agents asked to run or integrate Hyper. Human readers +should start with [README.md](README.md). + +## Run the viewer + +Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) on PATH. +No repository checkout and no Rust toolchain: + +```sh +uvx --python 3.12 --from hypergraph-viz-viewer hyper +uvx --python 3.12 --from hypergraph-viz-viewer hyper dataset.hif.json +``` + +`--from` is required. `hypergraph-viz` supplies the Python API and ships no +executable; `hypergraph-viz-viewer` supplies the `hyper` command. + +Accepted inputs are [HIF](docs/HIF.md) and native `hypergraph.v1` JSON, detected +automatically. `--projection bipartite|clique|star` and `--watch` are available; +see the [viewer guide](docs/VIEWER.md). + +## Check before you run it + +- **The viewer opens a native window on the machine running the command.** It is + not a notebook widget, and a remote host or container cannot display on the + user's laptop. Without a desktop session and working graphics drivers, report + that constraint rather than retrying the launch. +- Prebuilt wheels cover Linux x86_64 (glibc 2.28+), macOS arm64/x86_64 (11.0+), + and Windows x86_64. Other platforms build from source and need Rust 1.89+. +- `hyper --help` and `hyper --version` parse arguments before opening a window, + so they are safe to run headless to confirm the install. + +## Use the Python API + +For interchange and validation, which need no desktop: + +```sh +uv add hypergraph-viz +``` + +Add the viewer only when a window is actually wanted, with +`uv add "hypergraph-viz[viewer]"`. The API alone has no Bevy dependency. See the +[Python and HIF guide](docs/HIF.md). + +## Work in this checkout + +```sh +cargo run --locked --release -- fixtures/sample.json # native viewer +cargo run --locked -p hyper-viz --example project_scene # headless, no window +``` + +The first release build can take several minutes. +[CONTRIBUTING.md](CONTRIBUTING.md) is authoritative for the test, clippy, fmt, +and Python checks a change must pass, and for what belongs in this repository. diff --git a/README.md b/README.md index 790cd36..b4588fa 100644 --- a/README.md +++ b/README.md @@ -16,19 +16,21 @@ groups, and explore neighborhoods with search, picking, and lasso selection. ## Try the viewer -### For agents +
+Ask a coding agent to run it -Paste this prompt: +Paste this prompt into an agent working on your machine: ```text -Install uv if `uv` is not on PATH: https://docs.astral.sh/uv/getting-started/installation/ - -Open Hyper's built-in coauthorship demo. Do not clone a repository or install Rust: +Read https://github.com/atomicstrata/hyper/blob/main/AGENTS.md and open Hyper's +built-in demo. Install uv first if it is not on PATH. Do not clone the +repository or install Rust. +``` -uvx --python 3.12 --from hypergraph-viz-viewer hyper +[AGENTS.md](AGENTS.md) carries the commands, the platform matrix, and the +desktop-session constraint, so the agent does not have to infer them. -Needs a desktop session and working graphics drivers. Wheels: Linux x86_64 (glibc 2.28+), macOS arm64/x86_64 (11.0+), Windows x86_64. The window opens on the machine running the command. To open a HIF file, append its path. -``` +
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then open the built-in coauthorship demo: