# Opensource Pestmodels

> Hierarchical pest and disease modeling framework for AgStack (Linux Foundation). 13 models, 19 crops, 54 threats. Python wheel + FastAPI + MCP server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-agstack-opensource-pestmodels`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agstack](https://agentstack.voostack.com/s/agstack)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [agstack](https://github.com/agstack)
- **Source:** https://github.com/agstack/opensource-pestmodels
- **Website:** https://agstack.org

## Install

```sh
agentstack add mcp-agstack-opensource-pestmodels
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AgStack Pest & Disease Models

**Hierarchical pest and disease modeling framework** for the [AgStack Foundation](https://agstack.org) (Linux Foundation).

[](LICENSE)
[](https://www.python.org/downloads/)

## Overview

`agstack-pnd` provides a composable, three-layer modeling framework for agricultural pest and disease risk assessment:

- **Layer 1 -- Weather/Accumulation**: Growing Degree Days, Chill Hours/Portions, Accumulated Precipitation
- **Layer 2 -- Agronomic/Derived**: Leaf Wetness Duration, VPD, Humidity Streaks, Phenological Gating
- **Layer 3 -- Disease/Pest Risk**: Fuzzy Mamdani risk engine, rule-based risk, UC IPM Powdery Mildew

Ships with **19 crops** and **54 crop-threat pairings** (21 diseases, 19 pests) from the OpenAgri catalog.

## Quick Start

```bash
# Install the core library
pip install agstack-pnd

# Install with server (FastAPI + MCP + PostgreSQL)
pip install "agstack-pnd[server]"

# Docker Compose (full service)
docker compose -f docker/compose.yaml up
```

## Three Ways to Use It

### 1. Python Library

```python
from agstack_pnd.models.disease.fuzzy_mamdani import FuzzyMamdaniRisk
from agstack_pnd.catalog.loader import get_threat

threat = get_threat("grape", "Botrytis cinerea")
model = FuzzyMamdaniRisk()
result = model.calculate(weather_data, threat=threat)

for score in result.daily_scores:
    print(f"{score.date}: {score.value:.0f}/100 ({score.risk_level.value})")
```

### 2. REST API

```bash
curl -X POST http://localhost:8000/api/v1/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "model_uuid": "a1b2c3d4-0004-4000-8000-000000000001",
    "latitude": 38.5, "longitude": -121.7,
    "crop": "grape",
    "threat_scientific_name": "Botrytis cinerea",
    "start_date": "2026-04-01",
    "end_date": "2026-05-01"
  }'
```

### 3. MCP Server (AI Agents)

The built-in [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server lets any AI agent -- Claude, GPT, Cursor, or custom LLMs -- discover and query pest/disease models programmatically.

**Start the server:**

```bash
pip install "agstack-pnd[server]"
uvicorn agstack_pnd.server.app:create_app --factory --port 8000
```

**Connect your AI agent** (Claude Desktop, Cursor, or any MCP client):

```json
{
  "mcpServers": {
    "agstack-pnd": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**Available MCP tools:**

| Tool | What it does |
|------|-------------|
| `list_pest_models` | Discover models by layer or crop |
| `get_model_info` | Get metadata, parameters, and citations for a model |
| `get_supported_crops_tool` | List all crops with available models |
| `get_threats_for_crop_tool` | List pests/diseases for a specific crop |
| `explain_threat` | Get biological parameters for a crop-threat pairing |

**Example agent conversation:**
> **User:** "What diseases should I watch for in my grape vineyard this June?"
>
> **Agent** calls `get_threats_for_crop_tool("grape")` then `explain_threat("grape", "Uncinula necator")` and responds:
>
> "Watch for powdery mildew -- it thrives in warm, dry weather (20-28C). Unusually, free water actually *inhibits* this fungus. Your dry June increases powdery mildew risk while reducing downy mildew risk."

See the full [MCP Server Guide](docs/mcp_server_guide.md) for Claude Desktop config, Cursor config, stdio transport, Python client, and all tool/resource documentation.

## Run it as part of the DPI

agstack-pnd can run as a first-class Digital Public Infrastructure service:
register a field to get a **GeoID**, let weather flow in from TerraPipe as
governed **BITEs**, run a forecast off those BITEs, and publish the risk back as
a BITE that others can join on the GeoID.

- Set `PND_WEATHER_PROVIDER=dpi` (or pass `"weather_provider": "dpi"` per request)
  to read weather BITEs from Pancake instead of calling a weather API directly.
- Pass an AR2 `field_grant` to authorize L1 geometry and grant-gated weather.
- Pass `"publish": true` to persist the result as a `pest_disease` BITE, and use
  `POST /api/v1/aggregate` for distinct-field, district-level roll-ups.

A one-command, local, reproducible walkthrough (docker-compose + an executable
notebook) lives in the [`dpi-demo/`](https://github.com/agstack/pancake/tree/main/dpi-demo)
directory of the Pancake repo. See [OpenScience DPI Fit](docs/openscience_dpi_fit.md)
for the design and [Publishing a Model](docs/publishing_a_model.md) to ship your own.

## Architecture

```
                    +-----------+     +-----------+     +-------------+
                    |  Python   |     | REST API  |     | MCP Server  |
                    |  Library  |     | (FastAPI) |     | (AI Agents) |
                    +-----+-----+     +-----+-----+     +------+------+
                          |                 |                    |
                          v                 v                    v
                    +----------------------------------------------+
                    |           agstack_pnd Core Library            |
                    |                                              |
                    |  Layer 3: Fuzzy Mamdani | Rule-Based | UCIPM |
                    |  Layer 2: Leaf Wetness | VPD | Phenology     |
                    |  Layer 1: GDD | Chill Hours | Precipitation  |
                    |  Foundation: BaseModel ABC | WeatherProvider |
                    +----+--------+--------+--------+--------------+
                         |        |        |        |
                         v        v        v        v
                      NOAA    GeoID    Threat    PostgreSQL
                      API    Registry  Catalog     (cache)
```

Input: GeoID (AgStack Asset Registry) or raw lat/lon + crop + date range.
Output: daily risk scores (0-100) with Low / Moderate / High / Critical classification.

## Documentation

- [User Manual](docs/user_manual.md) -- How to use the library, API, and MCP server
- [MCP Server Guide](docs/mcp_server_guide.md) -- Install and connect AI agents to pest/disease models
- [Executive Summary](docs/executive_summary.md) -- Vision, stakeholders, coverage
- [Architecture Design](docs/design_architecture.md) -- Technical architecture
- [OpenScience DPI Fit](docs/openscience_dpi_fit.md) -- How agstack-pnd fits the AgStack DPI as a GeoID-addressable OpenScience service
- [Publishing a Model](docs/publishing_a_model.md) -- Ship your pest/disease model as a pip wheel that the runtime auto-discovers (see [`examples/model-template/`](examples/model-template/))
- [OpenAgri Migration Guide](docs/openagri_migration.md) -- How OpenAgri's work evolves into this framework
- [Contributor Guide](docs/contributor_guide.md) -- How to add models and providers
- [Deployment Guide](docs/deployment_guide.md) -- Docker, environment variables
- [API Reference](https://agstack.github.io/opensource-pestmodels)

## Contributing and CI/CD Quality Gates

Every contribution goes through **four automated CI gates** and **human review** before it can be merged. No code reaches `master` without passing all of them.

### Automated Gates (GitHub Actions)

| Gate | What it checks | Why it matters |
|------|---------------|----------------|
| **1. Lint & Format** | `ruff check` + `ruff format` | Consistent code style across all contributors |
| **2. Type Check** | `mypy --strict` | Catches type errors before they become runtime bugs |
| **3. Tests** | `pytest` -- all unit and integration tests | Every model must produce correct, reproducible results |
| **4. Catalog & FATFD Integrity** | Threat catalog schema, model UUID uniqueness, FATFD validator | Biological parameters are valid; no duplicate model IDs; quality harness passes |

All four gates must pass before a PR can be merged. This is enforced through GitHub branch protection rules.

### Human Review (CODEOWNERS)

Different parts of the codebase have designated reviewers:

- **Threat catalog and disease models** -- Reviewed by [OpenAgri maintainers](docs/openagri_migration.md) who created the original biological parameters and fuzzy risk engine
- **Foundation, infrastructure, CI/CD** -- Reviewed by AgStack core maintainers
- **Documentation** -- Reviewed by both teams

See [CODEOWNERS](.github/CODEOWNERS) for the full mapping.

### How to Contribute

1. Fork the repo and create a branch
2. Make your changes (new model, threat definition, bug fix)
3. Ensure tests pass locally: `pytest tests/ -v`
4. Open a Pull Request -- CI gates run automatically
5. Address review feedback from the designated CODEOWNERS
6. Once all gates pass and reviewers approve, the PR is merged

See the full [Contributor Guide](docs/contributor_guide.md) for details on adding models, weather providers, and threat definitions.

### Release Process

Releases are triggered by git tags (`v*`). When a maintainer tags a release:
1. The wheel is built and published to **PyPI** (`pip install agstack-pnd`)
2. A Docker image is built and pushed to **GHCR** (`ghcr.io/agstack/opensource-pestmodels`)
3. Documentation is rebuilt and deployed to **GitHub Pages**

## Relationship to OpenAgri

This project is the **evolution** of the OpenAgri Pest and Disease Management service, not a replacement. The OpenAgri team's Fuzzy Mamdani risk engine, threat catalog (19 crops, 54 threats), and biological parameters form the scientific core of this framework. OpenAgri maintainers serve as domain reviewers for all contributions touching disease models and biological parameters.

See [OpenAgri Migration Guide](docs/openagri_migration.md) for the full story.

## License

Apache-2.0. See [LICENSE](LICENSE).

## Acknowledgments

This project builds on the pioneering work of:
- **[OpenAgri (Horizon Europe)](https://horizon-openagri.eu/)** -- Fuzzy Mamdani risk engine, 54 crop-threat definitions, leaf wetness estimation. Special thanks to Stefan Drobic (VizLore), Nikos Kalatzis (Green Supply Chain), and Agrobit S.r.l.
- **[agstack/pest-models](https://github.com/agstack/pest-models)** -- Original GDD, chill, leaf wetness, and powdery mildew models
- **[agstack/OpenAgri-PestAndDiseaseManagement](https://github.com/agstack/OpenAgri-PestAndDiseaseManagement)** -- FastAPI service architecture, GDD intervals, rule-based risk engine

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agstack](https://github.com/agstack)
- **Source:** [agstack/opensource-pestmodels](https://github.com/agstack/opensource-pestmodels)
- **License:** Apache-2.0
- **Homepage:** https://agstack.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agstack-opensource-pestmodels
- Seller: https://agentstack.voostack.com/s/agstack
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.