Metadata-Version: 2.4
Name: groundtruth-ag
Version: 1.0.0
Summary: Python client for the BRD Groundtruth API — read your own farm data (fields, weather, irrigation scheduling, soil health, yield history, equipment, market prices)
Author: Bishop Research and Development
License: MIT
Project-URL: Homepage, https://developer.bishopresearch.com
Project-URL: Documentation, https://developer.bishopresearch.com
Project-URL: Repository, https://bishopresearch.com
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: respx>=0.20; extra == "test"

# groundtruth-ag

Python client for the [BRD Groundtruth API](https://developer.bishopresearch.com) — read your own farm data (fields, weather, irrigation scheduling, soil health, yield history, equipment, market prices) from your own scripts.

This is a read-only v1: nothing here creates or modifies data in your account.

## Install

```bash
pip install groundtruth-ag
```

## Quickstart

Generate a personal API key at **bishopresearch.com → Dashboard → Settings → API Keys**, then:

```python
from groundtruth_ag import Client

client = Client(api_key="brd_live_...")
# or: export BRD_API_KEY=brd_live_... and just call Client()

for field in client.fields.list():
    forecast = client.fields.weather(field["id"])
    schedule = client.fields.irrigation(field["id"], days=7)
    print(field["name"], schedule["schedule"])
```

## Resources

| Call | Endpoint |
|---|---|
| `client.me()` | `GET /me` — the account this key belongs to |
| `client.fields.list()` | `GET /fields` |
| `client.fields.get(field_id)` | `GET /fields/{id}` |
| `client.fields.weather(field_id)` | `GET /fields/{id}/weather` |
| `client.fields.irrigation(field_id, days=7)` | `GET /fields/{id}/irrigation` |
| `client.soil_health.summary()` | `GET /soil-health` |
| `client.yield_history.list()` | `GET /yield-history` |
| `client.equipment.list()` | `GET /equipment` |
| `client.market.prices()` | `GET /market/prices` |

Full request/response shapes: https://developer.bishopresearch.com and the interactive reference at https://bishopresearch.com/api/v1/docs.

## Errors

Every non-2xx response raises a typed exception, all subclasses of `BRDAPIError`:

```python
from groundtruth_ag import Client, NotFoundError, RateLimitError, AuthenticationError

client = Client()
try:
    client.fields.get(999999)
except NotFoundError:
    print("no such field")
```

| Exception | HTTP status |
|---|---|
| `AuthenticationError` | 401 — missing, invalid, or revoked key |
| `NotFoundError` | 404 |
| `ValidationError` | 422 |
| `RateLimitError` | 429 — 60 requests/minute per key |
| `ServerError` | 5xx |
| `ConnectionError` | request never got a response (network/timeout) |

429s and 5xx responses are retried automatically (2 retries, exponential backoff) before an exception is raised — `RateLimitError`/`ServerError` mean retries were already exhausted.

## Context manager

```python
with Client(api_key="brd_live_...") as client:
    print(client.me())
# connection closed automatically
```

## Development

```bash
pip install -e ".[test]"
pytest
```

## Design notes

- Built on `httpx`. A sync client only for now; an `AsyncClient` mirroring the same resource classes on `httpx.AsyncClient` is a natural follow-on once there's demand, not built speculatively here.
- Auth is a bearer token (`Authorization: Bearer <key>`) whether it's a personal API key today or an OAuth access token in the future — the transport layer doesn't care which, so a future OAuth flow wouldn't require a breaking change to this library's public API.
- No pagination: every v1 resource returns a small, complete list (a farm's fields, not millions of rows), so none was added.
