Python node packs

A Git pack is a normal installable Python project with a static root microscope-node.toml. The companion reads it without importing modules or executing a build backend.

schema_version = 1
id = "my_lab.pathology"
name = "My lab's pathology nodes"
version = "1.0.0"
nodes = ["lab_nodes:TissueNode", "lab_nodes:NucleiNode"]
dependencies = ["numpy>=2,<3"]
# Optional static, portable composite definitions; these files are not imported.
workflows = ["workflows/tissue.json"]

id is the portable pack identity (recommended); otherwise identity is derived from its HTTPS repository URL/name. Nodes have globally unique stable IDs outside the reserved microscope.* namespace. Classes may declare legacy_ids for previously persisted node IDs; the engine resolves those aliases only when that pack is installed, while the viewer retains the original saved type and parameters. A pack may provide Python nodes, static workflows, or both. Workflow entries name repository-relative JSON files; paths cannot escape the checkout or use symlinks, and all composite JSON together is limited to 256 KiB. Definitions are read and validated during review without importing modules. Their internal graphs use explicit typed microscope.composite_input.<type> and microscope.composite_output.<type> boundary nodes. Manifest ≤64 KiB, at most 64 module:Class bindings and 32 workflow paths, with bounded name/version/dependency fields. Include ordinary pyproject.toml; static build requirements/dependencies/dynamic metadata are shown during review. Dynamic installation metadata cannot be guaranteed complete without executing it; the trust warning states that install/build/dependencies are arbitrary code execution.

In Workflow → Add Nodes from Git, paste an HTTPS URL. Review name/version, exact commit and declared dependencies; Trust and install this commit is explicit authorization. The managed virtualenv receives the pinned checkout and dependencies. Python catalogue discovery occurs only after trust, inside that interpreter. Static composites are exposed in the node library from their reviewed JSON definitions. Selecting one embeds its pinned definition into the portable workflow; the installed definition remains read-only, and Fork and Edit creates a local editable copy without changing the installed package. Reconnect/refresh exposes descriptors in the node library. Remove pack deletes its managed environment, never the user's developer project. Updates are explicit remove/review/install operations, not silent background changes. Opening a workflow only lists missing required packs and offers Review at its pinned commit; it never installs or executes anything.

For local source checkouts, create a separate interpreter per pack, install only that pack's runtime dependencies, then run microscope nodes register /path/to/checkout --python /path/to/pack-env/bin/python --trust. Local developer registration is explicit trust and records the chosen interpreter; it does not create a managed environment or copy/delete the checkout. The pack subprocess uses the framework SDK bootstrap but cannot import other pack environments' site-packages.

V1 Git installation supports credential-free HTTPS repositories. For private repositories, clone using your own normal tools and use trusted local developer registration; the companion does not collect Git credentials. Git cloning is HTTPS-only, disallows credentials in URLs, disables hooks/file protocol/global Git config, does not recurse submodules, has a 100 MiB repository limit, bounded process lifetime, no credential prompting, and exact commit checks. Review expires after 15 minutes; at most four pending reviews and 16 installed packs. Interrupted reviews are removed on restart. A reviewer cannot request a general shell command through the service.

Native/GPU environments

Managed packs each get a venv, including the official packs; trusted local developer registrations use the exact interpreter selected by the user. The companion-provided source and layer nodes remain in the core SDK. A persistent child interpreter is reused for each pack within a job. Cross-environment arrays use NPY with pickle disabled and bounded JSON; imports and objects do not leak across environments. This costs disk serialization at pack boundaries. Use a single pack for consecutive expensive nodes where practical.

Do not install every framework automatically. Install only the dependencies a reviewed pack requires. CPU/CUDA PyTorch and ONNX Runtime builds, GPU drivers and platform wheels remain researcher choices. Managed packs can describe package dependencies, but installing CUDA-specific wheels from alternative indexes is better done in a user-managed environment; no arbitrary installer-command endpoint is offered.

For an existing lab environment or editable project:

# In your chosen native environment, install SDK + your package explicitly.
/path/to/lab-venv/bin/python -m pip install -e /path/to/microscope-python
/path/to/lab-venv/bin/python -m pip install -e /path/to/lab-nodes
microscope nodes register /path/to/lab-nodes \
  --python /path/to/lab-venv/bin/python --trust

Use the same --root as microscope serve if configured. Restart/reconnect after CLI registration. --trust authorizes module import for discovery; registration does not install dependencies or modify the selected interpreter. Removal only unregisters developer environments.

See the installable example. Copy that directory to your own HTTPS Git repository to test the Git flow. The example threshold is research demonstration code, not a clinically validated model.