Metadata-Version: 2.5
Name: agnue-push
Version: 0.2.1
Summary: SDK and CLI for pushing data to the AgNUE platform
Project-URL: Homepage, https://agnue.com/
Project-URL: Source, https://github.com/teknologisk-institut/AgNUE/tree/main/sdk/python
Project-URL: Issues, https://github.com/teknologisk-institut/AgNUE/issues
Requires-Python: >=3.10
Requires-Dist: boto3>=1.34
Requires-Dist: httpx>=0.28
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: convert
Requires-Dist: polars>=1.0; extra == 'convert'
Description-Content-Type: text/markdown

# agnue-push

CLI and Python SDK for uploading sensor data to the [AgNUE](https://agnue.com/) platform.

**Step-by-step guide** (install, configure, first upload, scheduling with cron or Windows Task Scheduler, troubleshooting): [Automatic uploads with agnue-push](https://docs.nuedata.eu/docs/getting-started/agnue-push).

## Installation

```bash
pip install agnue-push
# with Parquet conversion before upload (smaller, faster transfers):
pip install 'agnue-push[convert]'
```

## Configuration

When your site is approved, you receive an `agnue.toml` file by email. Place it in the directory you run `agnue` from — the SDK reads `./agnue.toml`.

You can also configure via environment variables: `AGNUE_PLATFORM_URL`, `AGNUE_CLIENT_ID`, `AGNUE_CLIENT_SECRET`, and optionally `AGNUE_KEYCLOAK_URL` (defaults to `<platform origin>/realms/agnue`) and `AGNUE_S3_*`. Precedence: CLI flags / explicit args > env vars > `agnue.toml`.

## CLI

```bash
# Upload a single file
agnue upload data.csv --data-source DK-Foo-SOIL-001

# Upload a directory
agnue upload ./sensor-exports/ --data-source DK-Foo-SOIL-001

# Upload with glob, excluding backups
agnue upload "*.csv" --data-source DK-Foo-SOIL-001 --exclude "*_backup*"
```

The `--data-source` ID follows the format `CC-SSS-DOMAIN-SEQ` (e.g. `DK-Foo-SOIL-001`).

**Fallback behaviour:** if the platform API is unreachable after 3 attempts, files are uploaded directly to S3 only if the resolved S3 settings are complete (from the `[s3]` block, `AGNUE_S3_*` env vars or `--s3-*` flags), otherwise copied to a local `agnue-staging/` folder. In both cases `upload()` returns `None`.

## Python API

```python
from agnue_push import AgNUEClient

client = AgNUEClient.from_config()  # reads ./agnue.toml or env vars
# client = AgNUEClient.from_config("/path/to/agnue.toml")

# Upload a file — returns ingestion_id, or None after the direct-S3 or local-staging fallback
ingestion_id = client.upload("data.csv", data_source_id="DK-Foo-SOIL-001")

# Check an earlier S3 upload
exists = client.verify_upload("raw/DK-Foo/data.csv")

# List all uploads for this site
keys = client.list_uploads()
```

Pass explicit config instead of a file:

```python
client = AgNUEClient.from_config(
    platform_url="https://nuedata.eu",
    client_id="site-DK-Foo",
    client_secret="...",
)
```
