Metadata-Version: 2.3
Name: fornax-cutouts
Version: 0.1.0
Summary: NASA Fornax Cutouts - Pluggable backend for Async FITS cutouts with FastAPI + Celery using the IVOA UWS standard
Author: MAST Developers
Author-email: MAST Developers <archive@stsci.edu>
License: BSD-3-Clause
Requires-Dist: astrocut>=1.2.0
Requires-Dist: celery>=5.5.0
Requires-Dist: click>=8.3.0
Requires-Dist: fastapi[standard-no-fastapi-cloud-cli]>=0.115.0
Requires-Dist: fastapi-utils>=0.8.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.6,<3
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: redis>=6.2
Requires-Dist: typing-inspect>=0.9.0
Requires-Dist: uvicorn[standard]>=0.37.0
Requires-Dist: vo-models>=0.5.0
Requires-Dist: duckdb>=1.4.1
Requires-Dist: pyarrow>=20.0.0
Requires-Dist: pandas>=2.3.3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Fornax Cutouts

Pluggable backend for async FITS image cutouts with [FastAPI](https://fastapi.tiangolo.com/) +
[Celery](https://docs.celeryq.dev/) + [Astrocut](https://github.com/spacetelescope/astrocut) using the
[IVOA UWS](https://www.ivoa.net/documents/UWS/) standard.

## Welcome

This repository is the codebase for a **generalized** astronomical image cutout service.
The goal is to make it easier for archives and mission teams to stand up their own cutout services for their holdings without reimplementing async job handling, worker dispatch, and a standards-based REST API.
You add mission-specific data sources and deploy to your own infrastructure.
The framework supplies the cutout pipeline, UWS-based API and job metadata management.
The library is meant to be used by archives and other teams to deploy and extend it for their own data.
For example, MAST's cutouts service is one such deployment.
Collaboration happens on GitHub: use [issues](https://github.com/nasa-fornax/fornax-cutouts/issues) to report problems or discuss changes that benefit others, and open pull requests to contribute improvements upstream.
See [Contributing](#contributing) to get started.

## Overview

Fornax Cutouts provides a framework for building astronomical image cutout services. Define mission-specific data
sources, register them with the cutout registry, and the framework handles job queuing, worker dispatch, result storage,
and REST API exposure automatically.

## Requirements

- **Python** 3.12+
- **Redis** 6.x or newer — used as the Celery broker/backend and for UWS job state.

Configure the broker/backend with the following `CUTOUTS__REDIS__*` settings for local development:

| Variable                  | Default     | Purpose                      |
| ------------------------- | ----------- | ---------------------------- |
| `CUTOUTS__REDIS__HOST`    | `localhost` | Redis hostname               |
| `CUTOUTS__REDIS__PORT`    | `6379`      | Redis port                   |
| `CUTOUTS__REDIS__TIMEOUT` | `15.0`      | Connection timeout (seconds) |

The API and workers must use the same Redis instance (and compatible TLS/cluster settings).
See the [configuration reference](https://nasa-fornax.github.io/fornax-cutouts/configuration)
for the full list of settings.

## Documentation

Full documentation is available at
**[nasa-fornax.github.io/fornax-cutouts](https://nasa-fornax.github.io/fornax-cutouts)**.

- [Getting Started](https://nasa-fornax.github.io/fornax-cutouts/getting-started)
- [Configuration](https://nasa-fornax.github.io/fornax-cutouts/configuration)
- [CLI Reference](https://nasa-fornax.github.io/fornax-cutouts/cli)
- [API Reference](https://nasa-fornax.github.io/fornax-cutouts/api)
- [Building a Source](https://nasa-fornax.github.io/fornax-cutouts/sources/building-a-source)
- [Auth Providers Overview](https://nasa-fornax.github.io/fornax-cutouts/auth/overview)
- [Building an Auth Provider](https://nasa-fornax.github.io/fornax-cutouts/auth/building-a-provider)
- [Contributing](https://nasa-fornax.github.io/fornax-cutouts/contributing)

## Use as a library

Install this package in your own service and point `CUTOUTS__SOURCE_PATH` at a directory of mission modules
that register sources with `cutout_registry`.

With **uv**, you can add an editable path dependency if developing this project side by side with your mission sources:

```toml
[tool.uv.sources]
fornax-cutouts = { path = "../fornax-cutouts", editable = true }  # Only include if developing with fornax-cutouts source code

[project]
dependencies = [
    "fornax-cutouts",
]
```

Then run `uv sync`. Implement mission sources as described in
[Building a Source](https://nasa-fornax.github.io/fornax-cutouts/sources/building-a-source).

## Quick Start

```bash
# Install
git clone https://github.com/nasa-fornax/fornax-cutouts
cd fornax-cutouts
uv sync

# Configure (minimum required)
export CUTOUTS__SOURCE_PATH=/path/to/your/sources
export CUTOUTS__REDIS__HOST=localhost

# Start Redis
docker run -d -p 6379:6379 valkey/valkey-bundle:9.1

# Start API
fornax-cutouts api

# Start worker (separate terminal)
fornax-cutouts worker
```

Visit `http://localhost:8000/docs` for the interactive API.

## Contributing

Pre-commit is configured to lint and format all code:

```bash
uv sync
pre-commit install
pre-commit run --all-files
```

Use [Conventional Commits](https://www.conventionalcommits.org/) in **pull request titles** (squash merges). That drives [Semantic Versioning](https://semver.org/) and the changelog via [semantic-release](https://github.com/semantic-release/semantic-release). See the [Contributing guide](https://nasa-fornax.github.io/fornax-cutouts/contributing) for types, scopes, and best practices.

## Architecture

### Cloud Infrastructure

```mermaid
architecture-beta
    service internet(internet)[Internet]

    group cloud(cloud)[Cloud IaC]
    group fornax(server)[Fornax Cutouts] in cloud

    service gateway(internet)[Gateway] in cloud
    service load_balancer(server)[Load Balancer] in cloud

    service api(server)[REST API] in fornax
    service worker(server)[Celery Workers] in fornax

    service redis(database)[Redis] in cloud
    service s3(disk)[Storage] in cloud

    internet:R -- L:gateway
    gateway:R -- L:load_balancer
    load_balancer:B -- T:api
    api:B -- T:worker

    junction j1 in cloud
    redis:B -- T:j1

    redis:R -- L:api
    j1:R -- L:worker

    s3:L -- R:worker
```

### User sequence

```mermaid
sequenceDiagram
    actor U as User
    participant R as REST API
    participant C as Cutouts
    participant RD as Redis

    U->>+R: Request cutout
    R->>RD: Add request to queue
    R->>-U: Request Ack + Job ID

    par For each cutout
        RD->>+C: Perform cutout
        C->>-RD: Write results
    end

    loop Poll job status for complete
        U->>+R: Request job status
        RD->>R: .
        R->>-U: .
    end

    U->>+R: Get cutout results
    R->>-U: .
```

## Issues

Report bugs and request features on [GitHub Issues](https://github.com/nasa-fornax/fornax-cutouts/issues).

## License

This project is licensed under the terms of the [BSD 3-Clause license](LICENSE).
