Merge branch 'feat/mongo-logger' into 'main'

stages:

  - test

  - build

  - publish

  PIP_DISABLE_PIP_VERSION_CHECK: "1"

  PYTHONUNBUFFERED: "1"

test:

  stage: test

  image: python:3.12

  script:

    - python -m pip install --upgrade pip uv

    - uv sync --group dev

    - uv run pytest tests/ -v

lint:

  stage: test

  image: python:3.12

  script:

    - python -m pip install --upgrade pip uv

    - uv sync --group dev

    - uv run ruff check regstar tests

build:

  stage: build

  image: python:3.12

  needs:

    - test

    - lint

  script:

    - python -m pip install --upgrade pip uv

    - uv build

publish:

  stage: publish

  image: python:3.12

  needs:

    - build

  rules:

    - if: $CI_COMMIT_TAG

  script:

PyTorch + Hydra utilities for running reproducible “strategy training” experiments on graphs (optionally distributed with Ray).

This repository currently provides:

This repository provides:

- A lightweight training loop ([regstar/trainer/trainer.py](regstar/trainer/trainer.py))

- Graph + augmented-graph helpers ([regstar/graph](regstar/graph))

- A `Strategy` module that maintains masked, normalized edge probabilities ([regstar/strategy.py](regstar/strategy.py))

- Experiment orchestration with pluggable loggers and metrics, with optional Ray execution ([regstar/launch/experiment](regstar/launch/experiment))

- MongoDB loggers for persisting runs and experiments ([regstar/io/mongo](regstar/io/mongo))

## Requirements

Run the Hydra-based training script with uv:

```bash

uv run -m regstar.train

uv run -m regstar.train --config-name=demo

```

Important: `regstar.train` expects a Hydra config at `regstar/conf/default.yaml`.

Important: `regstar.train` expects a Hydra config in `conf/`. The repository includes `conf/demo.yaml`; use `--config-name=demo` to run it.

To override config values with Hydra:

uv run -m regstar.train --config-name=demo

```

### Running with MongoDB logging

Use the `demo_mongo` config to persist runs and experiments to MongoDB:

```bash

# Start MongoDB (e.g. Docker: docker run -d -p 27017:27017 mongo:latest)

uv run -m regstar.train --config-name=demo_mongo

```

Override the connection if MongoDB runs elsewhere:

```bash

uv run -m regstar.train --config-name=demo_mongo mongo.connection.client.host=myhost mongo.connection.client.port=27017

```

For a connection URI (e.g. with auth):

```bash

uv run -m regstar.train --config-name=demo_mongo mongo.connection.client.host='mongodb://user:pass@host:27017'

```

## Testing

Run the test suite (uses [mongomock](https://mongomock.readthedocs.io/) for MongoDB tests):

```bash

uv sync --group dev

uv run pytest tests/ -v

```

## Publish to GitLab Package Registry

This section shows how to manually upload the package to the GitLab PyPI registry.

experiment:

  logger:

    _target_: regstar.launch.experiment.loggers.none.NoOpExperimentLogger

    _target_: regstar.io.loggers.none.NoOpExperimentLogger

  # Optional: aggregate key metrics over epochs

  metrics:

      steps: 50

      eval_every: 10

      logger:

        _target_: regstar.trainer.loggers.none.NoOpTrainLogger

        _target_: regstar.io.loggers.none.NoOpTrainLogger

      # Partial optimizer: returns Adam(params, lr=0.1) when called with params

      optimizer:

        _target_: torch.optim.Adam

# Demo config with MongoDB logging (requires a running MongoDB instance)

# @package _global_

#

# Override connection: mongo.connection.client.host=myhost mongo.connection.client.port=27017

# Or use URI: mongo.connection.client.host=mongodb://user:pass@host:27017 (pass as single host arg)

defaults:

  - demo

mongo:

  connection:

    _target_: regstar.io.mongo.connection.MongoConnection

    db_name: regstar

    client:

      _target_: pymongo.MongoClient

      host: localhost

      port: 27017

experiment:

  logger:

    _target_: regstar.io.mongo.experiment_logger.MongoExperimentLogger

    connection: ${mongo.connection}

  run:

    trainer:

      logger:

        _target_: regstar.io.mongo.train_logger.MongoTrainLogger

        connection: ${mongo.connection}

        flush_interval: 10

requires-python = ">=3.12"

dependencies = [

    "gitpython>=3.1.46",

    "pymongo>=4.0.0",

    "hydra-core>=1.3.2",

    "numpy>=2.4.0",

    "omegaconf>=2.3.0",

[dependency-groups]

dev = [

    "mongomock>=4.3.0",

    "pre-commit>=4.5.0",

    "pytest>=8.0.0",

    "ruff>=0.14.8",

    "twine>=6.2.0",

    "ty>=0.0.8",

]

[tool.pytest.ini_options]

testpaths = ["tests"]

pythonpath = ["."]

[build-system]

requires = ["hatchling"]

build-backend = "hatchling.build"