Metadata-Version: 2.4
Name: agtag-gateway
Version: 0.1.1
Summary: AgTag Gateway ingestion, BLE processing, and AGSEG binary data tools
Author: AgriGates Inc.
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: bleak>=0.21
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: zstandard>=0.22

# AgTag Gateway

Python tools for reading, validating, converting, and loading AgTag `.agseg` binary segment data into PostgreSQL.

> **AgriGates Inc.**
> This package is developed for AgriGates Inc. and is used to parse binary data generated by AgTag devices into a structured, tabular format for storage and analysis. The input files use `.agseg`, a custom binary segment format designed specifically for AgTag devices.

## Installation

```bash
pip install agtag-gateway
```

The package provides:

* `agseg-load` — load an AGSEG export bundle into PostgreSQL
* `agseg-dump` — inspect and verify `.agseg` files
* `agseg-to-csv` — convert `.agseg` files to AgriGates-standard CSV

## Load an AGSEG bundle into PostgreSQL

An AGSEG export bundle contains a `manifest.json`, metadata dump, and one or more `.agseg` segment files:

```text
agtag_e001_20260911T185552Z/
├── manifest.json
├── meta.dump
└── segments/
    ├── e001_00000000_20260904T171023Z.agseg
    ├── e001_00000001_20260904T171146Z.agseg
    └── e001_00000002_20260904T172910Z.agseg
```

Load the bundle with:

```bash
agseg-load /path/to/agtag_bundle \
  --dsn "host=127.0.0.1 dbname=agtag user=agrigates password=YOUR_PASSWORD"
```

The loader:

1. Verifies the bundle against `manifest.json`.
2. Creates the required sensor table if needed.
3. Restores bundle metadata.
4. Verifies the CRC of each AGSEG record.
5. Decodes the segment records.
6. Inserts the decoded sensor data into PostgreSQL.
7. Rebuilds the required views.

### Options

Use a specific timezone for legacy date/time columns:

```bash
agseg-load /path/to/bundle \
  --dsn "..." \
  --tz America/New_York
```

Set the `edge_id`:

```bash
agseg-load /path/to/bundle \
  --dsn "..." \
  --edge-id 1
```

Verify the bundle without inserting data:

```bash
agseg-load /path/to/bundle \
  --dsn "..." \
  --verify-only
```

Skip metadata restoration:

```bash
agseg-load /path/to/bundle \
  --dsn "..." \
  --skip-meta
```

## Store the original `.agseg` files in PostgreSQL

The package can optionally preserve the original binary `.agseg` files in PostgreSQL as `BYTEA`.

Use:

```bash
agseg-load /path/to/bundle \
  --dsn "host=127.0.0.1 dbname=agtag user=agrigates password=YOUR_PASSWORD" \
  --store-binary
```

With this option, the loader creates the following table when necessary:

```sql
CREATE TABLE IF NOT EXISTS agseg_files (
    id           BIGSERIAL PRIMARY KEY,
    filename     TEXT NOT NULL,
    sha256       TEXT NOT NULL UNIQUE,
    file_size    BIGINT NOT NULL,
    uploaded_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    content      BYTEA NOT NULL
);
```

Each `.agseg` file is stored as its original binary content.

The SHA-256 hash is used to prevent duplicate files from being inserted.

This gives you both:

```text
.agseg file
    │
    ├── original binary ──> agseg_files.content (BYTEA)
    │
    └── decoded records ──> sensor_data
```

## Inspect an AGSEG file

Display segment information:

```bash
agseg-dump info /path/to/file.agseg
```

Verify every record:

```bash
agseg-dump verify /path/to/file.agseg
```

Decode records:

```bash
agseg-dump dump /path/to/file.agseg
```

Decode using physical/scaled values:

```bash
agseg-dump dump /path/to/file.agseg --scaled
```

Verify an entire bundle:

```bash
agseg-dump bundle /path/to/bundle
```

## Convert AGSEG to CSV

```bash
agseg-to-csv /path/to/file.agseg -o /path/to/output
```

Multiple segments can be supplied:

```bash
agseg-to-csv \
  /path/to/segment1.agseg \
  /path/to/segment2.agseg \
  /path/to/segment3.agseg \
  -o /path/to/output
```

## AGSEG format

`.agseg` is a custom binary segment format designed for data generated by AgriGates AgTag devices. It contains compressed sensor records and is intended to provide an efficient representation of device data before conversion into structured tabular data.

The package includes the reference reader and validation tools. The detailed format specification is available in:

```text
docs/agtag_binary_segment_format_v1.md
```

## PostgreSQL

The package requires PostgreSQL for the database-loading functionality.

Python dependencies are installed automatically:

* `bleak`
* `psycopg2-binary`
* `zstandard`

You do not need to install these separately when installing the package:

```bash
pip install agtag-gateway
```

## License

MIT
