Metadata-Version: 2.4
Name: atlantes-cpd
Version: 1.2.0
Summary: Online changepoint detection for AIS tracks, served over gRPC
Author-email: Skylight Team <skylight@skylight.global>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/allenai/atlantes
Project-URL: Repository, https://github.com/allenai/atlantes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: scipy<2,>=1.12
Provides-Extra: serve
Requires-Dist: grpcio<2,>1.65.1; extra == "serve"
Requires-Dist: grpcio-health-checking<2,>=1; extra == "serve"
Requires-Dist: protobuf<5,>=4.25; extra == "serve"
Provides-Extra: validate
Requires-Dist: click<9,>=8.1; extra == "validate"
Requires-Dist: matplotlib<4,>=3.8; extra == "validate"
Requires-Dist: pandas<3,>=2.2; extra == "validate"
Provides-Extra: dev
Requires-Dist: atlantes-cpd[serve,validate]; extra == "dev"
Requires-Dist: pytest<9,>7; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Dynamic: license-file

# atlantes-cpd

Online changepoint detection for AIS tracks. A changepoint marks where a track
should be split into a new subpath, which lets downstream inference run only
when a vessel's behavior may have changed. The detector is served over gRPC as
`atlanteschangepoint.ChangepointService`.

The detector (`atlantes_cpd.changepoint_detector`) can also be called in-process: `pip install atlantes-cpd` installs only numpy and scipy. The gRPC service needs the `serve` extra (`pip install 'atlantes-cpd[serve]'`), and `validate.py` needs the `validate` extra.

This is a standalone package. It does not import `atlantes` and has its own
dependencies, tests, Dockerfile, and CI workflow (`.github/workflows/cpd.yml`).

## Develop

```
cd cpd
python -m venv venv
venv/bin/pip install -e '.[dev]'
venv/bin/pytest tests --ignore=tests/integration/serve
```

The detector integration tests read three AIS track CSVs from `tests/data/`
(or `$CPD_TEST_DATA_DIR`); they skip when the files are absent. The tracks are licensed and must not be committed; `tests/data/*.csv` is gitignored.

## Run the service

```
docker compose up --build
```

Configuration comes from environment variables:

| Variable      | Default   | Purpose                  |
|---------------|-----------|--------------------------|
| `CPD_ADDRESS` | `0.0.0.0` | Address the server binds |
| `CPD_PORT`    | `5206`    | Port the server binds    |

With the service running, `CPD_ADDRESS=127.0.0.1 venv/bin/pytest tests/integration/serve` exercises it end to end.

## Tuning

Detection thresholds live in `src/atlantes_cpd/constants.py`.

## Regenerating the gRPC code

See `src/atlantes_cpd/serve/README.md`.

## Release to PyPI

The package publishes to PyPI as `atlantes-cpd` through trusted publishing; no API token is involved.

The repo has a single version, in the `VERSION` file at the repo root. `cpd/VERSION` is a symlink to it, and `pyproject.toml` reads it. A `v<version>` tag releases the whole repo, and `atlantes-cpd` is one of the artifacts.

1. Set `VERSION` and merge it.
2. Create a GitHub release with the tag `v<version>` (for example `v1.1.0`) and publish it. Drafts and pre-releases don't trigger the workflow.
3. `.github/workflows/publish_cpd.yml` checks that the tag matches `VERSION`, builds the sdist and wheel, and uploads them from the `pypi` environment.
