Development

Development

Set up and check changes

Install the locked development environment:

uv sync

Run the quality checks used by the repository:

uvx ruff check .
uvx ruff format --check .
uv build

There is currently no test suite. For behavior changes, also run a short, relevant experiment and inspect its log and MLflow metrics.

Project conventions

• Use Python 3.12 typing, four-space indentation, and a 100-character line limit.
• Use snake_case for modules, functions, config keys, and registry names, PascalCase for classes, and UPPER_CASE for registries and constants.
• Keep orchestration in app/, reusable construction and validation in core/, and domain code in its matching package.
• Prefer typed, validated dataclass configuration over unstructured parameter access inside components.
• Preserve seed handling, resolved configs, and checkpoint compatibility when changing experiment behavior.

Add a registered component

Environment backends, agents, policies, and network nodes share the same extension workflow:

1. define a class that inherits the matching base class
2. define its typed nested or module-level Config dataclass
3. validate values in Config.__post_init__ when needed
4. register the class with the matching decorator
5. add its module to the builder's module list so registration occurs
6. add a focused Hydra config when users need to select it
7. document its compatibility and behavior.

A minimal stateless network node looks like:

@register_node("example")
class ExampleNode(BaseNode):
    @dataclasses.dataclass(kw_only=True, slots=True)
    class Config(BaseNode.Config):
        scale: float = 1.0

    @property
    def output_shape(self) -> TensorShape:
        return self.input_shape

    def forward(self, inputs, state=None):
        return inputs * self._cfg.scale, None

Stateful nodes must also implement initial_state and reset_state. Their forward method must be deterministic for identical parameters, input, and state, and must not mutate the supplied state or module buffers.

Add configuration

Add reusable settings to the narrowest group under src/spiking_rl_lab/configs/. Do not grow the root config.yaml with component-specific parameters.

Add a file under configs/experiment/ when a complete training setup must be retained. Such a file should include the environment, agent and network, runner, and trainer values that affect results.

Verify composition before execution:

uv run spiking-rl-lab experiment=<name> --cfg job

Update documentation

The project wiki is maintained in a separate Git repository.

• Keep README.md as the short project entry point.
• Update the relevant wiki page when configuration, architecture, algorithms, commands, or supported components change.
• Keep Algorithms.md as an index and document each learning algorithm in Algorithms/<Algorithm>.md, including its objective and spiking-state behavior.
• Add a page only when the topic cannot fit clearly into an existing one.
• Link pages from _Sidebar.md and avoid copying the same reference material into several pages.