Metadata-Version: 2.1
Name: antares-devkit
Version: 0.8.1
Summary: Provides tools and utility methods to write and debug ANTARES filters with Python.
Keywords: antares,devkit,filter development
Author-Email: NSF NOIRLab ANTARES Team <antares@noirlab.edu>
Maintainer-Email: NSF NOIRLab ANTARES Team <antares@noirlab.edu>
License: Copyright (c) 2025 Association of Universities for Research in Astronomy, Inc. (AURA)
         All rights reserved.
         
         Unless otherwise stated, the copyright of this software is owned by AURA.
         Redistribution and use in source and binary forms, with or without modification,
         are permitted provided that the following conditions are met:
         
         1) Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.
         2) Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
         3) The names of AURA and its representatives may not be used to endorse or
           promote products derived from this software without specific prior written
           permission.
         
         THIS SOFTWARE IS PROVIDED BY AURA "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
         INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
         FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL AURA BE
         LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
         CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
         GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
         HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
         LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
         THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.9
Project-URL: Homepage, https://gitlab.com/nsf-noirlab/csdc/antares/devkit
Project-URL: Documentation, https://nsf-noirlab.gitlab.io/csdc/antares/devkit/
Project-URL: Bug Reports, https://gitlab.com/nsf-noirlab/csdc/antares/devkit/issues
Project-URL: Source, https://gitlab.com/nsf-noirlab/csdc/antares/devkit
Requires-Python: >=3.9
Requires-Dist: astropy>=5.1.1
Requires-Dist: numpy>=1.24.4
Requires-Dist: pandas>=1.5.1
Requires-Dist: pydantic>=2.10.5
Provides-Extra: filter-dependencies
Requires-Dist: scikit-learn<=0.25; extra == "filter-dependencies"
Requires-Dist: statsmodels>=0.12.2; extra == "filter-dependencies"
Requires-Dist: scipy>=1.13.1; extra == "filter-dependencies"
Requires-Dist: light-curve==0.7.2; extra == "filter-dependencies"
Requires-Dist: ssi-forest>=0.1.1; extra == "filter-dependencies"
Requires-Dist: slack-sdk>=3.39.0; extra == "filter-dependencies"
Requires-Dist: xgboost==2.1.4; extra == "filter-dependencies"
Provides-Extra: jupyter
Requires-Dist: matplotlib>=3.9.4; extra == "jupyter"
Description-Content-Type: text/markdown

# antares-devkit

Provides tools and utility methods to write and debug [ANTARES](http://antares.noirlab.edu) filters with Python.

ANTARES is an Alert Broker developed by the [NSF NOIRLab](http://noirlab.edu) for ZTF and
LSST.

If you want to write and submit a filter to ANTARES please follow the [steps to submit a filter](https://nsf-noirlab.gitlab.io/csdc/antares/devkit/learn/submit-a-filter/)
in our documentation. ***If you wrote a filter for antares and is not in the devkit repository, contact us and we'll send you your code from our backup.***

## Installation

The ANTARES DevKit supports Python version 3.9 and up and can be installed with pip:

```sh
pip install antares-devkit
```

## Basic Usage

The DevKit can be used in a local environment and also on NSF NOIRLab’s [Astro Data Lab](https://datalab.noirlab.edu/) Jupyter environment.

A basic example of creating and executing a filter is provided below.

Create a `HelloWorld` filter:

```python
from antares_devkit.models import BaseFilter


class HelloWorld(BaseFilter):
    OUTPUT_LOCUS_TAGS = [
        {"name": "hello_world", "description": "hello!"},
    ]

    def _run(self, locus):
        print("Hello Locus ", locus.locus_id)

```

Run the filter on a random ANTARES locus:

```python
from antares_client import search
from antares_devkit.models import DevKitLocus
from antares_devkit.utils import filter_report

# fetch a random locus from the antares database using the antares-client
client_locus = search.get_random_locus()
devkit_locus = DevKitLocus.model_validate(client_locus.to_devkit())

# execute the filter
HelloWorld().run(devkit_locus)
```

For more information and additional examples visit our [DevKit guide](https://nsf-noirlab.gitlab.io/csdc/antares/devkit/).

## Development

### How does this work?

This repository can be shipped as a python package on pip and also can be used in installations using the repository with tags.
Then the filter_runner docker image in the antares main repository is going to install all the filters and required packages,
then we use a gcp bucket to know which filters are enabled or disabled.

### How to test filters using Docker (Recommended)

```sh
docker build -t antares_devkit:3.9 -f test/Dockerfile .
docker run -v $(pwd)/antares_devkit:/usr/src/app/antares_devkit -v $(pwd)/test:/usr/src/app/test -it antares_devkit:3.9
uv run pytest test
```

### How to setup local environment (with conda)

```sh
conda create -n devkit python=3.9 -y
conda activate devkit
pip install uv
uv sync --all-groups --all-extras
```

### How to add a filter dependency

```sh
uv add "{package_name}" --optional filter-dependencies
```

or for jupyter lab libraries use:

```sh
uv add "{package_name}" --optional jupyter
```

### How to add a dev dependency

```sh
uv add "{package_name}" --group dev
```

or for docs libraries use:

```sh
uv add "{package_name}" --group docs
```

### How to run a jupyter notebook

```sh
uv run --with jupyter jupyter lab
```

### How to write documentation

Add md files and update `mkdocs.yml` to add them in the nav.

### How to update filters src

1. Execute `uv run python scripts/update_filters_src.py`
2. Paste the output in `mkdocs.yml` within the nav.Filters replacing the entire section.

### How to view the documentation locally

Install necessary dependencies:

```sh
uv sync --group docs
```

Serve the docs:

```sh
uv run mkdocs serve
```
