Developer Guide¶

Heliokit components are ordinary Python distributions that register one or more entry points. The host discovers them at runtime and exposes them through the CLI and Python API.

Minimal component package¶

[project]
name = "heliokit-data-example"
version = "0.1.4"
requires-python = ">=3.10,<3.11"
dependencies = ["heliokit>=0.1.4"]

[project.entry-points."heliokit.data"]
example = "heliokit_data_example.component:get_component"

Component factory¶

from heliokit_base import BaseComponent, ComponentMetadata

class ExampleDataComponent(BaseComponent):
    metadata = ComponentMetadata(
        kind="data",
        operation="read",
        name="example",
        summary="Read an example data file.",
    )

    def run(self, **kwargs):
        return {"ok": True, "input": kwargs.get("input")}

def get_component():
    return ExampleDataComponent()

Entry point groups¶

heliokit.data
heliokit.filters
heliokit.tools
heliokit.models
heliokit.pipelines
heliokit.viz3d

Documentation policy¶

Every user-visible CLI or desktop-distribution change must update the documentation in the same change set. This includes command names, shortcut commands, arguments, argument formats, defaults, required fields, installation steps, runtime entry points, path resolution, output-location behavior, component availability, and demo-data examples.

Update the relevant source pages under cli/docs and rebuild the HTML site before delivery:

D:\dev\conda\envs\swimc\python.exe -m sphinx -b html .\cli\docs .\cli\docs\_build\html

Use these pages as the primary destinations:

Page	When to update
`reference.rst`	Parameters, required fields, formats, defaults, and command behavior.
`get-started.rst`	Installation, environment setup, command activation, and first-run flows.
`demo-data.rst`	Runnable examples, demo-data commands, and generated figures.
`desktop.rst`	Desktop installation, launch commands, packaging behavior, and workspace terminal behavior.
`README.md`	Repository-level quick-start commands and local development workflows.

Any change to CLI commands, shortcut names, installation extras, output-path rules, or the desktop workspace terminal runtime must update these documents in the same change and rebuild the HTML site. Users should never need to infer a new command shape from the source tree.

Runtime isolation¶

Desktop terminal commands must run through a child Heliokit CLI Python process. Source-tree desktop runs may discover a controlled heliokit environment, but packaged desktop runs must stay inside the packaged or advertised runtime and must not depend on a user-created Conda environment. Treat HELIOKIT_COMPILED_APP, SWIMC_COMPILED_APP, and sys.frozen as packaged runtime signals. If no packaged CLI runtime can import heliokit.cli, show an explicit error instead of falling back to user PATH or Conda state.

Visualization helpers must not force Matplotlib backend changes after matplotlib.pyplot has been imported. Use a file-rendering backend for --no-show commands and try an interactive backend only before importing pyplot. Backend selection inside terminal commands is subprocess-local and must not leak into the desktop Qt process.

Design rules¶

Keep component packages focused on one capability family. Prefer small runtime dependencies and lazy imports for heavy model or visualization stacks, so component discovery remains fast and does not load TensorFlow, Torch, VTK, or Qt until the user actually runs a command that needs them.

Do not modify the legacy desktop entry points when adding Heliokit components. The component layer should wrap existing capabilities without changing the original SWAS/SWVIZ application behavior.