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
-------------------------

.. code-block:: toml

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

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

Component factory
-----------------

.. code-block:: python

   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
------------------

.. code-block:: text

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

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.