Metadata-Version: 2.4
Name: cropl
Version: 0.1.2
Summary: Python SDK for cropl — crop yield prediction powered by satellite imagery and machine learning
Project-URL: Homepage, https://cropl.co
Project-URL: Documentation, https://cropl.co/docs
Project-URL: Repository, https://github.com/cropl/cropl-python
Project-URL: Issues, https://github.com/cropl/cropl-python/issues
Author-email: cropl <dev@cropl.co>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: actuarial,agriculture,crop-yield,farming,insurance,machine-learning,prediction,satellite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pandas>=1.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Description-Content-Type: text/markdown

# cropl

**Python SDK for cropl — crop yield prediction powered by satellite imagery and machine learning.**

Predict crop yields by providing location, crop, and planting information. Built for developers, actuaries, insurers, and government agencies who need programmatic access to yield forecasts.

> **Preview Release** — This is the demo/preview version of the cropl SDK. It uses a local prediction engine with realistic modeled outputs calibrated from a pilot across 847 fields in 28 states. Production API with real satellite data and live model inference is coming soon.

## Installation

```bash
pip install cropl
```

For DataFrame support:

```bash
pip install cropl[pandas]
```

## Quickstart

```python
import cropl

result = cropl.predict(
    location="Story County, IA",
    crop="corn",
    planting_date="2026-04-15",
)

print(f"Predicted yield: {result.yield_value} {result.yield_unit}")
print(f"Confidence: {result.confidence}%")
print(result.summary())
```

## API Reference

### `cropl.predict()`

Generate a single crop yield prediction.

```python
result = cropl.predict(
    # Required
    location="Story County, IA",  # County+state, zip code, or FIPS code
    crop="corn",                   # corn, soybeans, wheat, cotton, rice
    planting_date="2026-04-15",    # YYYY-MM-DD

    # Optional
    irrigation="rainfed",          # rainfed, center_pivot, drip, flood
    tillage="conventional",        # conventional, no_till, strip_till, reduced
    temp_adjustment=0,             # -10 to +10 (°F offset from historical avg)
    rain_adjustment=0,             # -50 to +50 (% offset from historical avg)
    field_acres=None,              # float — enables revenue estimate
)
```

**Returns:** `PredictionResult` with:

| Attribute | Type | Description |
|-----------|------|-------------|
| `yield_value` | `float` | Predicted yield (e.g., 191.3) |
| `yield_unit` | `str` | Unit — `bu/acre`, `lb/acre`, or `cwt/acre` |
| `confidence` | `float` | Confidence score (0–100) |
| `mape` | `float` | Model error rate for this crop/region |
| `location` | `str` | Resolved location name |
| `county` | `str` | County name |
| `state` | `str` | State abbreviation |
| `fips` | `str` | FIPS code |
| `crop` | `str` | Crop name |
| `planting_date` | `str` | Input planting date |
| `growth_projection` | `list[dict]` | Monthly yield progression |
| `ndvi_timeline` | `list[dict]` | Monthly NDVI values |
| `factors` | `list[dict]` | Contributing factors with impact scores |
| `revenue_estimate` | `float \| None` | Revenue estimate (if `field_acres` provided) |
| `price_per_unit` | `float` | Market price used for revenue calc |
| `timestamp` | `str` | ISO timestamp of prediction |

**Convenience methods:**

```python
result.to_dict()       # dict representation
result.to_json()       # JSON string
result.to_dataframe()  # pandas DataFrame (single row)
result.summary()       # formatted string for printing
```

### `cropl.predict_batch()`

Run multiple predictions at once.

```python
results = cropl.predict_batch([
    {"location": "Story County, IA", "crop": "corn", "planting_date": "2026-04-15"},
    {"location": "50011", "crop": "soybeans", "planting_date": "2026-05-20"},
    {"location": "20135", "crop": "wheat", "planting_date": "2026-09-10"},
])
# Returns: list[PredictionResult]
```

### `cropl.predict_dataframe()`

Run predictions from a pandas DataFrame.

```python
import pandas as pd

df = pd.DataFrame([
    {"location": "Story County, IA", "crop": "corn", "planting_date": "2026-04-15"},
    {"location": "50011", "crop": "soybeans", "planting_date": "2026-05-20"},
])
results_df = cropl.predict_dataframe(df)

# Custom column names
results_df = cropl.predict_dataframe(
    df,
    location_col="county",
    crop_col="crop",
    date_col="plant_date",
)
```

### `cropl.list_crops()`

List all supported crops with metadata.

```python
crops = cropl.list_crops()
# [
#     {"name": "corn", "yield_unit": "bu/acre", "base_yield": 187.3, "planting_season": "Apr-May"},
#     {"name": "soybeans", "yield_unit": "bu/acre", "base_yield": 51.2, "planting_season": "May-Jun"},
#     ...
# ]
```

### `cropl.model_accuracy()`

Get model accuracy metrics for a crop and region.

```python
acc = cropl.model_accuracy(crop="corn", region="corn_belt")
# {"mape": 8.1, "rmse": 18.4, "accuracy_pct": 92, "r_squared": 0.87, "sample_size": 312}
```

### `cropl.market_price()`

Get current market price for a crop.

```python
price = cropl.market_price(crop="corn")
# {"crop": "corn", "price": 4.53, "unit": "$/bu", "source": "USDA", "as_of": "2026-03-01"}
```

### `cropl.resolve_location()`

Resolve a location string to county, state, FIPS, and region.

```python
loc = cropl.resolve_location("50011")
# {"county": "Story County", "state": "IA", "fips": "19169", "region": "corn_belt"}
```

## Supported Crops

| Crop | Base Yield | Unit | Planting Season |
|------|-----------|------|-----------------|
| Corn | ~187 | bu/acre | Apr–May |
| Soybeans | ~51 | bu/acre | May–Jun |
| Wheat | ~52 | bu/acre | Sep–Oct |
| Cotton | ~884 | lb/acre | Apr–Jun |
| Rice | ~75 | cwt/acre | Mar–Apr |

## Location Formats

Three input formats are supported:

| Format | Example |
|--------|---------|
| County + State | `"Story County, IA"` or `"Story, Iowa"` |
| Zip Code | `"50011"` |
| FIPS Code | `"19169"` |

All formats resolve internally to county + state + FIPS code.

## Revenue Estimation

Pass `field_acres` to get a revenue estimate based on predicted yield and current market prices:

```python
result = cropl.predict(
    location="Story County, IA",
    crop="corn",
    planting_date="2026-04-15",
    field_acres=160,
)
print(f"Estimated revenue: ${result.revenue_estimate:,.2f}")
```

## Production API

This preview SDK uses a local prediction engine. The production version connects to cropl's API with real satellite imagery, weather data, and trained ML models.

When the production API is available:

```python
import cropl

# Switch to production API — same predict() interface
cropl.configure(api_key="your-api-key")

result = cropl.predict(
    location="Story County, IA",
    crop="corn",
    planting_date="2026-04-15",
)
```

Visit [cropl.co](https://cropl.co) to learn more.

## License

Copyright 2026 cropl. All rights reserved.
