Metadata-Version: 2.4
Name: agribackup
Version: 1.1.3
Summary: AgriBackup Enterprise EUDR API
Home-page: 
Author: AgriBackup Architecture Team
Author-email: AgriBackup Architecture Team <contact@agribackup.com>
License: Proprietary
Project-URL: Repository, https://github.com/GIT_USER_ID/GIT_REPO_ID
Keywords: OpenAPI,OpenAPI-Generator,AgriBackup Enterprise EUDR API
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author

# AgriBackup Python Library

[![PyPI version](https://img.shields.io/pypi/v/agribackup.svg)](https://pypi.org/project/agribackup/)

The AgriBackup Python library provides convenient access to the AgriBackup Enterprise API from applications written in Python. It handles cryptographic authentication, deterministic network routing, and executes the complete TRACES NT compliance lifecycle.

## Documentation

See the [AgriBackup Documentation](https://docs.agribackup.com) for Python.

## Installation

Install the package via pip:

```sh
pip install agribackup
```

## Usage
The package needs to be configured with your account's API key, which you can get at https://agribackup.com. The SDK automatically routes your requests to the correct environment (Sandbox or Production) based on your key's prefix.

With this decoupled architecture, the SDK cleanly separates the environment setup (Webhooks) from the actual physical compliance flow.

### Phase 1: Pre-assessment (The Sandbox Check)
**Action:** `client.risk_management.assess_coordinate_risk(...)`

**Purpose:** A rapid, synchronous Boolean check to verify if a coordinate is in a deforested zone before you spend capital or compute on heavy satellite ingestion.

```python
from agribackup.client import AgriBackupClient
from agribackup.models import CoordinateRiskRequest
from agribackup.exceptions import ApiException

def assess_coordinate_risk():
    client = AgriBackupClient(api_key="sk_test_YOUR_API_KEY")

    risk_check = client.risk_management.assess_coordinate_risk(
        coordinate_risk_request=CoordinateRiskRequest(latitude=-1.246807, longitude=36.743217)
    )
    
    if risk_check.deforestation_detected:
        print("Deforestation detected. Cannot proceed.")
    else:
        print(f"Coordinate is safe. Risk level: {risk_check.country_risk_level}")
        
    print(risk_check)

if __name__ == "__main__":
    assess_coordinate_risk()
```

### Phase 2: Event-Driven Infrastructure (One-Time Setup)
**Action:** `client.webhooks.register_webhook(...)`

**Purpose:** Establishes the enterprise routing for asynchronous fulfillment. You register your ERP endpoint to listen for `polygon.verified`, `batch.risk_assessed`, `shipment.linked`, and `dds.submitted`.

```python
# Register your webhook endpoint once during system startup
from agribackup.models import WebhookRegistrationRequest

request = WebhookRegistrationRequest(
    target_url="https://your-erp.internal.co/api/webhooks/agribackup",
    event_types=["batch.risk_assessed", "polygon.verified", "shipment.linked", "dds.generated", "dds.submitted"]
)
registration = client.webhooks.register_webhook(request)
print(f"Webhook Secret (Save securely!): {registration.signing_secret}")
```
#### Webhook Event Payloads
Every webhook shares a common envelope (`eventType`, `eventId`, `timestamp`, `attempt`, `nextRetry`, `data`). Below are the schemas for the inner `data` object for each event:

*   `polygon.verified`: `{ jobId, polygonsVerified, polygonsFailed, status, polygonIds }`
*   `batch.risk_assessed`: `{ batchId, batchCode, workflowId, riskScore, classification, status }`
*   `shipment.linked`: `{ batchId, shipmentReference, transactionHash }`
*   `dds.generated`: `{ jobId, batchId, ddsReference, status, error }`
*   `dds.submitted`: `{ batchId, ddsReference, status }`
*   `dds.validated`: `{ batchId, ddsReference, validationTimestamp, status }`
*   `dds.rejected`: `{ batchId, ddsReference, rejectionReason, status }`
*   `job.failed`: `{ jobId, jobType, errorCode, errorMessage }`
*   `report.ready`: `{ reportId, reportType, downloadUrl }`

**Verifying Incoming Webhooks**
Use your `signing_secret` to cryptographically verify that incoming webhooks originated from AgriBackup:
```python
import hmac
import hashlib

def verify_webhook(signature_header: str, raw_body_string: str, secret: str) -> bool:
    expected_hash = hmac.new(
        secret.encode('utf-8'),
        raw_body_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_hash, signature_header)
```

**Alternative: Manual Polling**
If you prefer not to use webhooks, or need to manually verify a job's status, you can retrieve the job state at any time:
```python
job_response = client.jobs.get_job_status("job-1234-uuid")
phase = job_response.phase

if phase == "COMPLETED":
    print(f"Job completed! Compliant units: {job_response.compliant_units}")
elif phase == "FAILED":
    print(f"Job failed. Errors: {job_response.errors}")
else:
    print(f"Job is still processing. Current phase: {phase}")
```

### Phase 3: The Complete EUDR Execution Lifecycle
This is the core operational loop where the decoupling shines.

1. **Ingest Polygons**: Call `client.polygons.ingest_polygons(...)`. (Async: wait for `polygon.verified` webhook).
2. **Register Batch**: Call `client.batches.register_batch(...)` using the verified polygon IDs. (Sync: returns batchId instantly).
3. **Attach Documentation**: Call `client.documents.upload(...)` or equivalent to bind legal EUDR documents to the batchId.
4. **Assess Batch Risk**: Call `client.batches.assess_risk(...)`. (Async: wait for `batch.risk_assessed` webhook).
5. **Link Logistics**: Call `client.logistics.link_batch_to_shipment(...)`. (Async: wait for `shipment.linked` webhook).
6. **Generate Declaration**: Call `client.declarations.generate_dds(...)`. (Async: wait for `dds.generated` webhook).
7. **Submit Declaration**: Call `client.declarations.submit_dds(...)`. (Async: wait for TRACES NT `dds.validated` webhook).

This SDK structure gives you absolute deterministic control over the state machine of your agricultural supply chain.

#### Complete Lifecycle Implementation Example
```python
from fastapi import FastAPI, Request, BackgroundTasks
from agribackup.client import AgriBackupClient
from agribackup.models import (
    CoordinateRiskRequest, PolygonIngestionRequest, BatchRegistrationRequest, 
    ShipmentLinkRequest, DdsGenerationRequest, GeoJsonFeature, GeoJsonGeometry, FeatureProperties
)
import uvicorn

app = FastAPI()
client = AgriBackupClient(api_key="sk_test_YOUR_API_KEY")

# ==========================================
# Webhook Listener (Handling Async Events)
# ==========================================
@app.post("/api/webhooks/agribackup")
async def handle_webhook(request: Request, background_tasks: BackgroundTasks):
    event = await request.json()
    event_type = event.get("eventType")
    data = event.get("data", {})
    
    if event_type == "polygon.verified":
        background_tasks.add_task(handle_polygon_verified, data)
    elif event_type == "batch.risk_assessed":
        background_tasks.add_task(handle_batch_risk_assessed, data)
    elif event_type == "shipment.linked":
        background_tasks.add_task(handle_shipment_linked, data)
    elif event_type == "dds.generated":
        background_tasks.add_task(handle_dds_generated, data)
    elif event_type == "dds.submitted":
        print(f"DDS Successfully Filed! Reference: {data.get('ddsReference')}")
        
    return {"status": "OK"}

# ==========================================
# The State Machine Workflow
# ==========================================

# Step 1: Ingest Polygons (Triggered manually or via ERP)
def start_compliance_flow():
    polygon_job = client.polygons.ingest_polygons(
        polygon_ingestion_request=PolygonIngestionRequest(
            features=[
                GeoJsonFeature(
                    type="Feature",
                    geometry=GeoJsonGeometry(type="Polygon", coordinates=[[[36.8, -1.2], [36.9, -1.2], [36.9, -1.3], [36.8, -1.3], [36.8, -1.2]]]),
                    properties=FeatureProperties(farmer_name="Global Coffee Farmer #1", farmer_id="TEST_FARMER_100", plot_name="Nyeri Hill Farm Block B", area=2.5, unit="HECTARES", commodity="Coffee")
                )
            ]
        )
    )
    print(f"Polygon ingestion started. Job ID: {polygon_job.job_id}")

# Step 2 & 3: Register Batch & Attach Documents (Fired by polygon.verified webhook)
def handle_polygon_verified(data):
    if data.get("status") != "COMPLETED":
        return
        
    batch = client.batches.register_batch(
        batch_registration_request=BatchRegistrationRequest(
            commodity="Coffee", country_code="KEN", hs_code="0901", quantity_kg=1500.0,
            polygon_ids=data.get("polygonIds", []), vendor_ids=["ERP-VEND-991"]
        )
    )
    
    # Step 4: Assess Batch Risk
    client.batches.assess_risk(batch_id=batch.batch_id)
    print(f"Batch risk assessment started for {batch.batch_id}")

# Step 5: Link Logistics (Fired by batch.risk_assessed webhook)
def handle_batch_risk_assessed(data):
    if data.get("status") != "COMPLETED" or data.get("classification") == "HIGH_RISK":
        return
        
    client.logistics.link_batch_to_shipment(
        shipment_link_request=ShipmentLinkRequest(
            batch_id=data.get("batchId"), shipment_id="SHP-123", bill_of_lading="BOL-99281744", vessel_name="Evergreen"
        )
    )
    print(f"Logistics linked for batch {data.get('batchId')}")

# Step 6: Generate Declaration (Fired by shipment.linked webhook)
def handle_shipment_linked(data):
    # Note: shipment.linked webhook firing indicates success. No status check required.
        
    dds = client.declarations.generate_dds(
        dds_generation_request=DdsGenerationRequest(
            batch_id=data.get("batchId"), legal_document_hashes=["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]
        )
    )
    print(f"DDS generation started for batch {data.get('batchId')}. Job ID: {dds.job_id}")
    # Awaits 'dds.generated' webhook...

# Step 7: Submit Declaration (Fired by dds.generated webhook)
def handle_dds_generated(data):
    if data.get("status") != "COMPLETED":
        return
        
    dds_ref = data.get("ddsReference")
    client.declarations.submit_dds(reference_id=dds_ref)
    print(f"DDS submitted to TRACES. Awaiting validation for {dds_ref}...")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

## Cryptographic Evidence
AgriBackup anchors all critical compliance states to the Hedera Hashgraph DLT. You can retrieve immutable, cryptographically verifiable proofs of your compliance events at any time.

```python
evidence = client.evidence.get_batch_ledger_evidence("batch-123")
print(evidence)
```

### Interpreting the Evidence
The returned evidence object contains a chronological history of the entity's lifecycle anchored on-chain. It includes an array of `state_proofs`, where each proof represents a distinct compliance event (like `CREATED` or `RISK_ASSESSED`). 

Key fields inside each state proof include:
* **`hedera_transaction_id`**: The exact identifier on the Hedera Consensus Service. You can search this ID on any public Hedera explorer (e.g., Hashscan) to independently verify the transaction.
* **`consensus_timestamp`**: The decentralized, network-agreed time the event was permanently recorded.
* **`operation_type`**: The specific state transition that occurred.
* **`merkle_proof`**: The cryptographic data required to perform offline verification, ensuring the state has not been tampered with since anchoring.

## Archiving Reports
AgriBackup supports asynchronous generation of bulk compliance archives. This compiles all XML payloads, Hedera state proofs, and legal document hashes into a single cryptographic ZIP artifact.

1. **Request the Archive**: Call `client.archival.trigger_archive_report` with a date range.
2. **Await the Webhook**: Wait for the `report.ready` webhook.
3. **Download**: Use the provided URL or SDK method to securely retrieve the artifact.

```python
from datetime import date
from agribackup.models import ArchiveReportRequest

# Step 1: Request Archive
report_req = client.archival.trigger_archive_report(
    archive_report_request=ArchiveReportRequest(
        start_date=date(2026, 1, 1),
        end_date=date(2026, 3, 31)
    )
)
print(f"Report job started: {report_req.report_id}")

# Step 2: Handle Webhook (fired by report.ready)
def handle_report_ready(data):
    if data.get("reportType") != "COMPLIANCE_ARCHIVE":
        return
    print(f"Report is ready to download at: {data.get('downloadUrl')}")
    
    # Optionally fetch it directly using the SDK:
    # zip_buffer = client.archival.download_archive_report(report_id=data.get("reportId"))
```

## Advanced Enterprise Configuration
### Overriding Network Routing & Proxies
The client can be initialized with several options to bypass default network behaviors. This is primarily used by enterprise architectures operating behind zero-trust firewalls or corporate VPC proxies.

```python
client = AgriBackupClient(
    api_key="sk_live_...",
    base_url="https://custom-proxy.internal.co" # Overrides automated prefix routing
)
```

### Manual Idempotency Control
AgriBackup strictly guarantees safety during distributed failures via Idempotency-Key tracking. The backend will automatically generate this key if absent, so standard integrations can safely ignore this parameter.

If your Tier-1 enterprise architecture strictly requires passing your own internal ERP database transaction IDs as idempotency keys, you can inject them securely using the client's default HTTP headers:

```python
# Set the Idempotency-Key globally for the transaction
client.api_client.default_headers["Idempotency-Key"] = "erp-tx-10928-abc"

polygon_job = client.polygons.ingest_polygons(
    polygon_ingestion_request=PolygonIngestionRequest(features=[...])
)
```

## Support
If you require integration support or dedicated VPC configurations, reach out to support@agribackup.com or visit https://docs.agribackup.com.
