CLM Agents in NDP

AI-powered agents for querying and analyzing California Landscape Metrics (CLM) datasets using natural language. Built with Pydantic AI and FastMCP.

Overview

This repository provides a Jupyter notebooks demonstrating different capabilities for interacting with CLM datasets:

Features

• 🔍 Natural Language Search - Find datasets using plain English queries
• 💬 Conversational Interface - Maintains context across questions
• 📊 Statistical Analysis - Compute zonal statistics for California counties
• 🗺️ Interactive Maps - Visualize datasets with WMS layers
• 📈 Distribution Charts - Compare data distributions across regions
• 🔬 Threshold Analysis - Calculate areas above/below specified thresholds
• 📝 Observability - Optional Logfire integration for debugging

Prerequisites

• Python 3.10 or higher
• Jupyter Notebook or JupyterLab
• OpenAI API key (or NRP API key for Qwen3 model)

Installation

1. Clone the repository:

git clone https://github.com/national-data-platform/ndp_clm_agent_demo.git
cd ndp_clm_agent_demo

2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file with your API key:

# For OpenAI
OPENAI_API_KEY=your_openai_api_key

# Or for NRP (optional)
NRP_API_KEY=your_nrp_api_key

Quick Start

Open enhanced_clm_agent.ipynb for advanced capabilities including maps and visualizations.

Example questions:

• "What is the average carbon turnover time in Los Angeles?"
• "Show me a map of the annual burn probability dataset"
• "Compare the distribution of carbon turnover between San Diego and Orange county"
• "Which county has the highest mean carbon turnover time?"

Full-featured agent with advanced capabilities:

• Statistical analysis (mean, median, min, max, std)
• Threshold-based area calculations
• Interactive WMS map visualization
• Distribution charts and histograms
• Multi-county comparisons
• Ranking and filtering

Architecture

User Question
     ↓
ConversationalAgent (manages history)
     ↓
Pydantic AI Agent (processes with LLM)
     ↓
Tools (search_datasets, compute_stats, etc.)
     ↓
FastMCP Client → CLM-MCP Server
     ↓
GeoServer (WCS/WFS) → Datasets
     ↓
Response (with data/maps/charts)

Available Tools

The enhanced agent includes these tools:

• search_and_select_dataset - Find relevant datasets by topic
• get_county_statistics - Compute zonal statistics
• get_area_above_threshold - Calculate area above a threshold
• get_area_below_threshold - Calculate area below a threshold
• show_map - Display interactive WMS map
• get_value_distribution - Get data distribution for charts

Model Options

OpenAI GPT-4o-mini (Default)

• Fast and reliable
• 60 second default timeout
• Requires OpenAI API key

NRP Qwen3 (Alternative)

• Open-source model
• 180 second default timeout
• Requires NRP API key
• Set MODEL = "nrp" in the configuration cell

Example Queries

Basic Search

"Find datasets about carbon turnover"
"What datasets are available for burn probability?"

Statistical Analysis

"What is the average carbon turnover time in Los Angeles?"
"Find the maximum annual burn probability in San Diego county"
"Rank the top 5 counties by mean carbon turnover time"

Threshold Analysis

"What percentage of San Diego County has carbon turnover time above 100 years?"
"Show all counties where at least 30% of area has carbon turnover less than 20 years"

Visualization

"Show me a map of the carbon turnover dataset"
"Show the data distribution for San Diego and Los Angeles"
"Compare distributions between San Diego, Los Angeles, and Orange county"

Follow-up Questions

User: "What is the average carbon turnover in Los Angeles?"
Agent: [provides answer]
User: "How about San Diego?"
Agent: [understands context and provides San Diego statistics]

Configuration

The notebooks connect to:

• MCP Server: https://wenokn.fastmcp.app/mcp
• GeoServer: https://sparcal.sdsc.edu/geoserver

These are configured in the BASE_CONFIG dictionary and can be modified if needed.

Troubleshooting

Timeout Errors

• For complex queries, the agent may timeout
• Try breaking down the question into simpler parts
• Switch to OpenAI model if using NRP
• Increase timeout in conv_agent.ask(question, timeout=300)

Map Not Displaying

• Ensure the dataset has been selected via search first
• Check that WMS URLs are accessible
• Verify internet connection

Chart Not Showing

• Distribution charts require multiple data points
• Ensure you're querying counties that exist in the dataset
• Check that the distribution tool received data

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Pydantic AI
• Uses FastMCP for Model Context Protocol
• California Landscape Metrics data from SDSC
• Powered by OpenAI GPT-4o-mini or NRP Qwen3

Support

For issues or questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Review the example questions in each notebook

Citation

If you use this work in your research, please cite:

@software{clm_agents_ndp,
  title = {CLM Agents in NDP: AI-powered California Landscape Metrics Analysis},
  year = {2024},
  license = {MIT}
}