Metadata-Version: 2.4
Name: gamma-earth-s2dr
Version: 0.2.0
Summary: Python client for the Gamma Earth S2DR3 API: submit a job, follow its STAC collection, download the products.
Author: Gamma Earth
License: Apache-2.0
Project-URL: Repository, https://github.com/Gamma-Earth/gamma-earth-s2dr
Project-URL: Issues, https://github.com/Gamma-Earth/gamma-earth-s2dr/issues
Keywords: sentinel-2,super-resolution,remote-sensing,stac,gamma-earth
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.31
Requires-Dist: pystac>=1.10
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# gamma-earth-s2dr

Python client for the Gamma Earth S2DR3 hosted API. It submits a job, follows the job's STAC collection and downloads
the products. It is **not** the Colab SDK (`ge-sdk`, which runs the model on your own GPU): this talks to the hosted API
with your API key.

> Status: 0.2.0, used end to end against the public API (a job created, its eight files downloaded). Not yet published to PyPI.

```python
from gamma_earth_s2dr import Client

client = Client()                       # GE_API_KEY from the environment (or Client(api_key=...)); the API is https://api.gamma.earth
job = client.submit((30.906, 51.394, 30.936, 51.422), "2024-06-15")   # lon_min lat_min lon_max lat_max; spends credits
files = job.download("out/")            # waits for the product (minutes; the first job after a quiet spell is slower)
```

Step by step: `job.wait()` returns a `pystac.ItemCollection` (empty while the job runs); `client.download(collection, "out/",
assets=["tci"])` fetches chosen assets (names: `ms`, `tci`, `irp`, `ndvi`, and `*_10m` for the original-resolution files;
products made before the STAC release have no item file and are not listed by `search()` or in collections). To follow a job you already created: `client.job("<job id>")`.

`submit` spends credits and is **not** safe to retry: if it fails after the request was sent (a timeout, a lost answer) the
job may exist, so check your jobs before submitting again. `wait` rides out a few transient errors (network, 5xx, 429),
stops with `JobFailed` if the job failed, and says so if a job is `completed` but no product ever appears.

## Search (0.2)

```python
client = Client()
found = client.search(bbox=(30.9, 51.39, 30.94, 51.42), datetime=('2024-06-01', '2024-06-30'), max_clouds=20)
found.products      # your finished products (collection s2dr3)
found.scenes        # unprocessed Sentinel-2 scenes over that area, with a price shown
found.warnings

client.search(ids=['T36UUB-...'])            # by product id
client.search(tile='36UUB', max_items=200)   # follow the next pages (at most 20)

job = client.process(found.scenes[0])                       # NeedsConfirmation: shows the price, spends nothing
job = client.process(found.scenes[0], confirm=True, max_credits=10)
job.download('out/')                          # also writes out/collection.json
```
A product you already paid for is free to make again, and a search does not list scenes for an area and day you already
have a product for. If a job turns out to be a free repeat, `job.credits_note` says so.

`client.catalog()` gives the API as a pystac `Catalog` (browse the collection `s2dr3`); searching is `client.search()`, which
returns pystac Items. After a download, `pystac.ItemCollection.from_file('out/collection.json')`
works offline: it lists only the files you downloaded, by relative path, without the key or the API address.

Every job created through this package carries `"client": "gamma-earth-s2dr/<version>"`, so the API records it as
`S2DR3P` (P = Python package) in the usage report; plain API calls stay `S2DR3A`.

## Keys and safety

- The key goes only to your API host: in the URL path for the job API (that is how the job API works today), in the
  `X-API-Key` header for the STAC API. It is never sent to the signed download address, never printed, and is removed from
  every error message. A link in an API answer that is not on the API host is ignored.
- Downloads are written to `<name>.part` and renamed only when the size equals Content-Length and the file is a TIFF.
- The default API is `https://api.gamma.earth`; `GE_API_URL` or `Client(api_url=...)` replace it (for example a test API). The key is always required.

## License

Apache License 2.0, Copyright 2026 Gamma Earth (see `LICENSE` and `NOTICE`). The license covers this client only, not the
S2DR3 model, its wheel or the hosted API. Using the API needs an API key and credits.

## Develop

```
pip install -e ".[test]"
python -m pytest -q
```
