add nature agent stack

nature-agent-files/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      starter-dependencies:
+        patterns:
+          - '*'
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

nature-agent-files/.github/workflows/build.yml

@@ -0,0 +1,27 @@
+name: Build and test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm build
+      - run: pnpm build:starters
+      - run: pnpm --filter @code-for-the-planet/programearth-client test

nature-agent-files/.github/workflows/codeql.yml

@@ -0,0 +1,25 @@
+name: CodeQL
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '23 7 * * 3'
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: javascript-typescript
+          queries: security-extended
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4

nature-agent-files/.gitignore

@@ -0,0 +1,28 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.pnpm-store
+dist
+dist-ssr
+*.local
+.env
+agent/**/.env
+mcp/**/.env
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

nature-agent-files/README.md

@@ -0,0 +1,151 @@
+# Code for the Planet Map + Agent Starter
+
+A modern, interactive map dashboard for environmental hackathons, with an optional Strands Nature Agent, a framework-neutral ProgramEarth MCP server, grounding evaluations, and advanced deployment modules.
+
+![Map Web App Preview](./public/map-dashboard-preview.png)
+
+## Features
+
+- Interactive map visualization with Leaflet
+- Dark mode support
+- Layer controls for toggling map data
+- Custom UI components (Button, CheckBox)
+- Responsive layout and styling
+- Mock data for development and testing
+- Modular component structure
+- Optional map-side Nature Agent panel
+- AWS Strands reference runtime (server-side and swappable)
+- Shared ProgramEarth API client and MCP tools
+- Promptfoo grounding and agent-safety checks
+- CodeQL and Dependabot configuration
+- Optional Kepler and KubeStellar deployment modules
+
+## Prerequisites
+
+- Node.js (v22 or higher; the development container uses Node 24)
+- pnpm (v9 or higher)
+
+## Installation
+
+1. Clone the repository:
+   ```sh
+   git clone https://github.com/OpenSourceFellows/map_dashboard_hackathon.git
+   cd map_dashboard_hackathon
+   ```
+
+2. Install dependencies:
+   ```sh
+   pnpm install
+   ```
+
+3. Start the optional Nature Agent server (safe demo mode by default):
+
+   ```sh
+   pnpm dev:agent
+   ```
+
+See [START-HERE.md](START-HERE.md) for the participant path and live-data checklist.
+
+## Development
+
+Start the development server:
+
+```sh
+pnpm run dev
+```
+
+The app will be available at `http://localhost:5173` by default.
+
+Build for production:
+
+```sh
+pnpm run build
+```
+
+Preview production build:
+
+```sh
+pnpm run preview
+```
+
+Run linter:
+
+```sh
+pnpm run lint
+```
+
+Type-check all agent/data/MCP starters:
+
+```sh
+pnpm run build:starters
+```
+
+Run the ProgramEarth client tests:
+
+```sh
+pnpm --filter @code-for-the-planet/programearth-client test
+```
+
+## Project Structure
+
+```
+map-dashboard/
+├── public/           # Static assets
+├── src/              # Source code
+│   ├── components/   # UI and map components
+│   │   ├── Layout/   # Header and layout components
+│   │   ├── Map/      # Map-related components
+│   │   └── UI/       # Reusable UI components
+│   ├── data/         # Mock data
+│   ├── hooks/        # Custom React hooks
+│   ├── styles/       # CSS files
+│   ├── types/        # TypeScript types
+│   ├── utils/        # Utility functions
+│   ├── App.tsx       # Main app component
+│   └── main.tsx      # Entry point
+├── agent/            # Optional agent runtime implementations
+│   └── frameworks/
+│       └── strands/  # Strands reference agent + local HTTP endpoint
+├── packages/
+│   └── programearth-client/ # Shared server-side API adapter
+├── mcp/
+│   └── programearth/ # Framework-neutral ProgramEarth tools
+├── evals/            # Promptfoo grounding checks
+├── challenges/       # Challenge briefs and stack recipes
+├── deploy/           # Docker, Kubernetes, Kepler, KubeStellar
+├── package.json      # Project metadata and scripts
+├── vite.config.ts    # Vite configuration
+└── README.md         # Project documentation
+```
+
+## Tools & Libraries
+
+- [React](https://react.dev/) – UI library
+- [Vite](https://vitejs.dev/) – Fast build tool
+- [TypeScript](https://www.typescriptlang.org/) – Type safety
+- [Leaflet](https://leafletjs.com/) – Interactive maps
+- [React Leaflet](https://react-leaflet.js.org/) – React components for Leaflet
+- [ESLint](https://eslint.org/) – Linting
+- [Strands Agents](https://strandsagents.com/) – Reference agent runtime
+- [Model Context Protocol](https://modelcontextprotocol.io/) – Framework-neutral tool connectivity
+- [Promptfoo](https://www.promptfoo.dev/) – Agent evaluation and red teaming
+- [CodeQL](https://codeql.github.com/) – Static application security analysis
+
+## Custom Components
+
+- `Header` – App title and navigation
+- `MapContainer` – Interactive Leaflet map with markers and polygons
+- `LayerControls` – Toggle map layers and data types
+- `MapLegend` – Map legend display
+- `CheckBox` – UI checkbox component
+
+## Additional Documentation
+
+- [START-HERE.md](START-HERE.md) - participant entrypoint
+- [agent/frameworks/strands/README.md](agent/frameworks/strands/README.md) - Strands setup and API contract
+- [mcp/programearth/README.md](mcp/programearth/README.md) - ProgramEarth MCP server
+- [security/README.md](security/README.md) - application security vs. agent security
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
+- [LICENSE.md](LICENSE.md) - License information
+- [docs/MAINTAINER.md](docs/MAINTAINER.md) - Maintainer guide
+- [docs/QGIS_ATTRIBUTE_PRESERVATION.md](docs/QGIS_ATTRIBUTE_PRESERVATION.md) - QGIS data layer documentation

nature-agent-files/START-HERE.md

@@ -0,0 +1,43 @@
+# Code for the Planet starter
+
+This repository is a working map dashboard with an optional environmental-agent layer. You do not need every module to participate.
+
+## Fastest path
+
+Requirements: Node.js 22+ and pnpm 9+.
+
+```sh
+pnpm install
+pnpm dev:agent
+```
+
+In a second terminal:
+
+```sh
+pnpm dev
+```
+
+Open `http://localhost:5173/map` and select **Nature Agent**. The starter defaults to safe demo mode, so it works without cloud credentials or live ProgramEarth data.
+
+## Choose only what helps
+
+| Layer | Included V1 | When to use it |
+|---|---|---|
+| Interface | React + Leaflet map | Every team starts here |
+| Agent runtime | Strands reference implementation | Add tool-using environmental analysis |
+| Connect | ProgramEarth MCP server | Expose the same tools to any MCP-compatible framework |
+| Data | Shared ProgramEarth API adapter | Connect approved public or governed API access |
+| Agent evaluation | Promptfoo starter cases | Catch fabricated measurements and unsafe assumptions |
+| Application security | CodeQL + Dependabot | Scan code and dependencies in GitHub |
+| Efficient AI | Kepler module | Measure a Kubernetes workload's compute energy |
+| Multi-cluster | KubeStellar module | Place an advanced workload across prepared clusters |
+
+## Before connecting live data
+
+- Align the route names in `packages/programearth-client` with the published API contract.
+- Issue event-scoped, least-privilege credentials.
+- Define which layers are public, governed, or unavailable for the challenge.
+- Add evaluation cases for units, geography, timestamps, missing data, and consent boundaries.
+- Keep API and model credentials on the server; never expose them through `VITE_` variables.
+
+See `challenges/water-security/starter.yaml` for the first stack recipe.

nature-agent-files/agent/frameworks/strands/.env.example

@@ -0,0 +1,12 @@
+# Safe default: the HTTP endpoint works without model credentials or live field data.
+AGENT_MOCK_MODE=true
+AGENT_PORT=8787
+
+# To run the Strands/Bedrock implementation:
+# AGENT_MOCK_MODE=false
+# AWS_REGION=us-west-2
+# STRANDS_MODEL_ID=global.anthropic.claude-sonnet-4-6
+
+# ProgramEarth/AmplifyEarth API adapter (server-side only):
+# PROGRAMEARTH_API_BASE_URL=https://api.example.org
+# PROGRAMEARTH_API_KEY=

nature-agent-files/agent/frameworks/strands/README.md

@@ -0,0 +1,36 @@
+# Strands Nature Agent starter
+
+This is one reference implementation of the optional agent runtime. The map dashboard and ProgramEarth client do not depend on Strands, so teams can add another framework beside it.
+
+## Run locally
+
+From the repository root:
+
+```sh
+pnpm install
+pnpm dev:agent
+```
+
+The safe default is demo mode, which requires no cloud credentials and never invents field data. In a second terminal, run `pnpm dev`; Vite proxies `/api/agent` to the agent server on port 8787.
+
+To use Strands with Amazon Bedrock:
+
+1. Copy `.env.example` to `.env` and load it in your preferred environment runner.
+2. Set `AGENT_MOCK_MODE=false`.
+3. Configure AWS credentials with permission to invoke the selected Bedrock model.
+4. Configure the ProgramEarth API adapter.
+
+Do not put AWS or ProgramEarth credentials in browser-side `VITE_` variables.
+
+## Endpoint
+
+`POST /api/agent`
+
+```json
+{
+  "message": "What observations are available for this site?",
+  "context": { "siteId": "site-id-from-the-map" }
+}
+```
+
+The server creates an isolated agent for each request. It validates request size and leaves all data credentials server-side.

nature-agent-files/agent/frameworks/strands/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@code-for-the-planet/strands-agent",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@code-for-the-planet/programearth-client": "workspace:*",
+    "@strands-agents/sdk": "^1.17.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.23.13",
+    "typescript": "~5.8.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}