geomind-ai 1.0.0__py3-none-any.whl

geomind/__init__.py

@@ -0,0 +1,11 @@
+"""
+GeoMind - Geospatial AI Agent
+
+"""
+
+__version__ = "1.0.0"
+__author__ = "Harsh Shinde"
+
+from .agent import GeoMindAgent
+
+__all__ = ["GeoMindAgent"]

geomind/agent.py

@@ -0,0 +1,445 @@
+"""
+GeoMind Agent - Main agent class powered by OpenRouter.
+
+This module implements the AI agent that can understand natural language
+queries about satellite imagery and execute the appropriate tools.
+"""
+
+import json
+from typing import Optional
+from datetime import datetime
+
+from openai import OpenAI
+
+from .config import OPENROUTER_API_KEY, OPENROUTER_API_URL, OPENROUTER_MODEL
+from .tools import (
+    geocode_location,
+    get_bbox_from_location,
+    search_imagery,
+    get_item_details,
+    list_recent_imagery,
+    create_rgb_composite,
+    calculate_ndvi,
+    get_band_statistics,
+)
+
+
+# Map tool names to functions
+TOOL_FUNCTIONS = {
+    "geocode_location": geocode_location,
+    "get_bbox_from_location": get_bbox_from_location,
+    "search_imagery": search_imagery,
+    "list_recent_imagery": list_recent_imagery,
+    "get_item_details": get_item_details,
+    "create_rgb_composite": create_rgb_composite,
+    "calculate_ndvi": calculate_ndvi,
+    "get_band_statistics": get_band_statistics,
+}
+
+# Tool definitions for the LLM
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "geocode_location",
+            "description": "Convert a place name to geographic coordinates (latitude, longitude). Use this when you need to find coordinates for a location.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "place_name": {
+                        "type": "string",
+                        "description": "The name of the place to geocode (e.g., 'New York City', 'Paris, France')",
+                    }
+                },
+                "required": ["place_name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_bbox_from_location",
+            "description": "Get a bounding box for a location, suitable for searching satellite imagery.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "place_name": {
+                        "type": "string",
+                        "description": "The name of the place",
+                    },
+                    "buffer_km": {
+                        "type": "number",
+                        "description": "Buffer distance in kilometers (default: 10)",
+                    },
+                },
+                "required": ["place_name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "search_imagery",
+            "description": "Search for Sentinel-2 satellite imagery in the EOPF catalog. Returns available scenes.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "bbox": {
+                        "type": "array",
+                        "items": {"type": "number"},
+                        "description": "Bounding box as [min_lon, min_lat, max_lon, max_lat]",
+                    },
+                    "start_date": {
+                        "type": "string",
+                        "description": "Start date in YYYY-MM-DD format",
+                    },
+                    "end_date": {
+                        "type": "string",
+                        "description": "End date in YYYY-MM-DD format",
+                    },
+                    "max_cloud_cover": {
+                        "type": "number",
+                        "description": "Maximum cloud cover percentage (0-100)",
+                    },
+                    "max_items": {
+                        "type": "integer",
+                        "description": "Maximum number of results",
+                    },
+                },
+                "required": [],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_recent_imagery",
+            "description": "List recent Sentinel-2 imagery for a location. Combines geocoding and search.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location_name": {
+                        "type": "string",
+                        "description": "Name of the location to search",
+                    },
+                    "days": {
+                        "type": "integer",
+                        "description": "Number of days to look back (default: 7)",
+                    },
+                    "max_cloud_cover": {
+                        "type": "number",
+                        "description": "Maximum cloud cover percentage",
+                    },
+                    "max_items": {
+                        "type": "integer",
+                        "description": "Maximum number of results",
+                    },
+                },
+                "required": [],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_item_details",
+            "description": "Get detailed information about a specific Sentinel-2 scene by its ID.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "item_id": {"type": "string", "description": "The STAC item ID"}
+                },
+                "required": ["item_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "create_rgb_composite",
+            "description": "Create an RGB true-color composite image from Sentinel-2 data.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "zarr_url": {
+                        "type": "string",
+                        "description": "URL to the SR_10m Zarr asset from a STAC item",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Optional path to save the output image",
+                    },
+                    "subset_size": {
+                        "type": "integer",
+                        "description": "Size to subset the image (default: 1000 pixels)",
+                    },
+                },
+                "required": ["zarr_url"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "calculate_ndvi",
+            "description": "Calculate NDVI (vegetation index) from Sentinel-2 data.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "zarr_url": {
+                        "type": "string",
+                        "description": "URL to the SR_10m Zarr asset",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Optional path to save the NDVI image",
+                    },
+                    "subset_size": {
+                        "type": "integer",
+                        "description": "Size to subset the image",
+                    },
+                },
+                "required": ["zarr_url"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_band_statistics",
+            "description": "Get statistics (min, max, mean) for spectral bands.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "zarr_url": {
+                        "type": "string",
+                        "description": "URL to the Zarr asset",
+                    },
+                    "bands": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of band names to analyze",
+                    },
+                },
+                "required": ["zarr_url"],
+            },
+        },
+    },
+]
+
+
+class GeoMindAgent:
+    """
+    GeoMind - An AI agent for geospatial analysis with Sentinel-2 imagery.
+
+    Uses OpenRouter API for access to multiple AI models.
+    """
+
+    def __init__(self, model: Optional[str] = None, api_key: Optional[str] = None):
+        """
+        Initialize the GeoMind agent.
+
+        Args:
+            model: Model name (default: xiaomi/mimo-v2-flash:free)
+            api_key: OpenRouter API key. If not provided, looks for OPENROUTER_API_KEY env variable.
+        """
+        self.provider = "openrouter"
+        self.api_key = api_key or OPENROUTER_API_KEY
+        self.model_name = model or OPENROUTER_MODEL
+        self.base_url = OPENROUTER_API_URL
+
+        if not self.api_key:
+            raise ValueError(
+                "OpenRouter API key required.\n"
+                "You can provide it in three ways:\n"
+                "1. Pass it to the constructor: GeoMindAgent(api_key='your-key')\n"
+                "2. Set OPENROUTER_API_KEY environment variable\n"
+                "3. Create a .env file with OPENROUTER_API_KEY=your-key\n"
+                "\nGet your API key at: https://openrouter.ai/settings/keys"
+            )
+
+        print(f"🚀 GeoMind Agent initialized with {self.model_name} (OpenRouter)")
+        print(f"   API URL: {self.base_url}")
+
+        # Create OpenAI-compatible client
+        self.client = OpenAI(base_url=self.base_url, api_key=self.api_key)
+
+        # Chat history
+        self.history = []
+
+        # Add system message
+        self.system_prompt = self._get_system_prompt()
+
+    def _get_system_prompt(self) -> str:
+        """Get the system prompt for the agent."""
+        return f"""You are GeoMind, an expert AI assistant specialized in geospatial analysis
+and satellite imagery. You help users find, analyze, and visualize Sentinel-2 satellite data
+from the EOPF (ESA Earth Observation Processing Framework) catalog.
+
+Your capabilities include:
+1. **Search**: Find Sentinel-2 L2A imagery by location, date, and cloud cover
+2. **Geocoding**: Convert place names to coordinates for searching
+3. **Visualization**: Create RGB composites and NDVI maps from imagery
+4. **Analysis**: Calculate spectral indices and band statistics
+
+Key information:
+- Data source: EOPF STAC API (https://stac.core.eopf.eodc.eu)
+- Satellite: Sentinel-2 (L2A surface reflectance products)
+- Bands available: B01-B12 at 10m, 20m, or 60m resolution
+- Current date: {datetime.now().strftime('%Y-%m-%d')}
+
+When users ask for imagery:
+1. First use get_bbox_from_location or list_recent_imagery to search
+2. Present the results clearly with key metadata
+3. Offer to create visualizations if data is found
+
+Always explain what you're doing and interpret results in a helpful way."""
+
+    def _execute_function(self, name: str, args: dict) -> dict:
+        """Execute a function call and return the result."""
+        print(f"  🔧 Executing: {name}({args})")
+
+        if name not in TOOL_FUNCTIONS:
+            return {"error": f"Unknown function: {name}"}
+
+        try:
+            result = TOOL_FUNCTIONS[name](**args)
+            return result
+        except Exception as e:
+            return {"error": str(e)}
+
+    def chat(self, message: str, verbose: bool = True) -> str:
+        """
+        Send a message to the agent and get a response.
+        """
+        if verbose:
+            print(f"\n💬 User: {message}")
+            print("🤔 Processing...")
+
+        # Add user message to history
+        self.history.append({"role": "user", "content": message})
+
+        # Build messages with system prompt
+        messages = [{"role": "system", "content": self.system_prompt}] + self.history
+
+        max_iterations = 10
+        iteration = 0
+
+        while iteration < max_iterations:
+            iteration += 1
+
+            # Call the model
+            response = self.client.chat.completions.create(
+                model=self.model_name,
+                messages=messages,
+                tools=TOOLS,
+                tool_choice="auto",
+                max_tokens=4096,
+            )
+
+            assistant_message = response.choices[0].message
+
+            # Check if there are tool calls
+            if assistant_message.tool_calls:
+                # Add assistant message with tool calls to messages
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": assistant_message.content or "",
+                        "tool_calls": [
+                            {
+                                "id": tc.id,
+                                "type": "function",
+                                "function": {
+                                    "name": tc.function.name,
+                                    "arguments": tc.function.arguments,
+                                },
+                            }
+                            for tc in assistant_message.tool_calls
+                        ],
+                    }
+                )
+
+                # Execute each tool call
+                for tool_call in assistant_message.tool_calls:
+                    func_name = tool_call.function.name
+                    func_args = json.loads(tool_call.function.arguments)
+
+                    result = self._execute_function(func_name, func_args)
+
+                    # Add tool result to messages
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "content": json.dumps(result, default=str),
+                        }
+                    )
+            else:
+                # No tool calls, we have a final response
+                final_text = assistant_message.content or ""
+
+                # Add to history
+                self.history.append({"role": "assistant", "content": final_text})
+
+                if verbose:
+                    print(f"\n🌍 GeoMind: {final_text}")
+
+                return final_text
+
+        return "Max iterations reached."
+
+    def reset(self):
+        """Reset the chat session."""
+        self.history = []
+        print("🔄 Chat session reset")
+
+
+def main(model: Optional[str] = None):
+    """Main entry point for CLI usage."""
+    import sys
+
+    print("=" * 60)
+    print("🌍 GeoMind - Geospatial AI Agent")
+    print("=" * 60)
+    print("Powered by OpenRouter | Sentinel-2 Imagery")
+    print("Type 'quit' or 'exit' to end the session")
+    print("Type 'reset' to start a new conversation")
+    print("=" * 60)
+
+    try:
+        agent = GeoMindAgent(model=model)
+    except ValueError as e:
+        print(f"\n❌ Error: {e}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        print("\nPlease check your API key and internet connection.")
+        sys.exit(1)
+
+    while True:
+        try:
+            user_input = input("\n💬 You: ").strip()
+
+            if not user_input:
+                continue
+
+            if user_input.lower() in ["quit", "exit", "q"]:
+                print("\n👋 Goodbye!")
+                break
+
+            if user_input.lower() == "reset":
+                agent.reset()
+                continue
+
+            agent.chat(user_input)
+
+        except KeyboardInterrupt:
+            print("\n\n👋 Goodbye!")
+            break
+        except Exception as e:
+            print(f"\n❌ Error: {e}")
+
+
+if __name__ == "__main__":
+    main()

geomind/cli.py

@@ -0,0 +1,125 @@
+"""
+Command-line interface for GeoMind.
+"""
+
+import sys
+import argparse
+from typing import Optional
+
+from .agent import GeoMindAgent
+
+
+def main():
+    """Main CLI entry point for the geomind package."""
+    parser = argparse.ArgumentParser(
+        description="GeoMind - AI agent for geospatial analysis with Sentinel-2 imagery",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive mode
+  geomind
+
+  # Single query
+  geomind --query "Find recent imagery of Paris"
+
+  # With custom model
+  geomind --model "anthropic/claude-3.5-sonnet"
+
+  # With API key
+  geomind --api-key "your-openrouter-api-key"
+
+Environment Variables:
+  OPENROUTER_API_KEY    Your OpenRouter API key
+  OPENROUTER_MODEL      Model to use (default: xiaomi/mimo-v2-flash:free)
+  OPENROUTER_API_URL    API endpoint (default: https://openrouter.ai/api/v1)
+        """,
+    )
+
+    parser.add_argument(
+        "--query",
+        "-q",
+        type=str,
+        help="Single query to run (if not provided, starts interactive mode)",
+    )
+    parser.add_argument(
+        "--model",
+        "-m",
+        type=str,
+        help="Model name to use (e.g., 'anthropic/claude-3.5-sonnet')",
+    )
+    parser.add_argument(
+        "--api-key",
+        "-k",
+        type=str,
+        help="OpenRouter API key (or set OPENROUTER_API_KEY env variable)",
+    )
+    parser.add_argument(
+        "--version", "-v", action="store_true", help="Show version and exit"
+    )
+
+    args = parser.parse_args()
+
+    if args.version:
+        from . import __version__
+
+        print(f"GeoMind version {__version__}")
+        sys.exit(0)
+
+    # Start interactive or single-query mode
+    try:
+        if args.query:
+            # Single query mode
+            agent = GeoMindAgent(model=args.model, api_key=args.api_key)
+            agent.chat(args.query)
+        else:
+            # Interactive mode
+            run_interactive(model=args.model, api_key=args.api_key)
+    except ValueError as e:
+        print(f"\n❌ Error: {e}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print("\n\n👋 Goodbye!")
+        sys.exit(0)
+    except Exception as e:
+        print(f"\n❌ Unexpected error: {e}")
+        sys.exit(1)
+
+
+def run_interactive(model: Optional[str] = None, api_key: Optional[str] = None):
+    """Run interactive CLI mode."""
+    print("=" * 60)
+    print("🌍 GeoMind - Geospatial AI Agent")
+    print("=" * 60)
+    print("Powered by OpenRouter | Sentinel-2 Imagery")
+    print("Type 'quit' or 'exit' to end the session")
+    print("Type 'reset' to start a new conversation")
+    print("=" * 60)
+
+    agent = GeoMindAgent(model=model, api_key=api_key)
+
+    while True:
+        try:
+            user_input = input("\n💬 You: ").strip()
+
+            if not user_input:
+                continue
+
+            if user_input.lower() in ["quit", "exit", "q"]:
+                print("\n👋 Goodbye!")
+                break
+
+            if user_input.lower() == "reset":
+                agent.reset()
+                continue
+
+            agent.chat(user_input)
+
+        except KeyboardInterrupt:
+            print("\n\n👋 Goodbye!")
+            break
+        except Exception as e:
+            print(f"\n❌ Error: {e}")
+
+
+if __name__ == "__main__":
+    main()

geomind/config.py

@@ -0,0 +1,55 @@
+"""
+Configuration settings for GeoMind agent.
+"""
+
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# STAC API Configuration
+STAC_API_URL = "https://stac.core.eopf.eodc.eu"
+STAC_COLLECTION = "sentinel-2-l2a"
+
+# Sentinel-2 Band Configuration
+SENTINEL2_BANDS = {
+    "B01": {"name": "Coastal aerosol", "wavelength": 0.443, "resolution": 60},
+    "B02": {"name": "Blue", "wavelength": 0.490, "resolution": 10},
+    "B03": {"name": "Green", "wavelength": 0.560, "resolution": 10},
+    "B04": {"name": "Red", "wavelength": 0.665, "resolution": 10},
+    "B05": {"name": "Red Edge 1", "wavelength": 0.704, "resolution": 20},
+    "B06": {"name": "Red Edge 2", "wavelength": 0.740, "resolution": 20},
+    "B07": {"name": "Red Edge 3", "wavelength": 0.783, "resolution": 20},
+    "B08": {"name": "NIR", "wavelength": 0.842, "resolution": 10},
+    "B8A": {"name": "NIR Narrow", "wavelength": 0.865, "resolution": 20},
+    "B09": {"name": "Water Vapour", "wavelength": 0.945, "resolution": 60},
+    "B11": {"name": "SWIR 1", "wavelength": 1.610, "resolution": 20},
+    "B12": {"name": "SWIR 2", "wavelength": 2.190, "resolution": 20},
+}
+
+# Reflectance scale and offset (from STAC metadata)
+REFLECTANCE_SCALE = 0.0001
+REFLECTANCE_OFFSET = -0.1
+
+# RGB Band Mapping
+RGB_BANDS = {"red": "b04", "green": "b03", "blue": "b02"}
+
+# Default search parameters
+DEFAULT_MAX_CLOUD_COVER = 20  # percent
+DEFAULT_BUFFER_KM = 10  # km buffer around point for bbox
+DEFAULT_MAX_ITEMS = 10
+
+# Output directory for saved images
+OUTPUT_DIR = Path("outputs")
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+# Geocoding configuration
+GEOCODER_USER_AGENT = "geomind_agent_v0.1"
+
+# OpenRouter API Configuration
+# OpenRouter provides access to multiple AI models via API
+OPENROUTER_API_KEY = os.getenv("OPENROUTER_API_KEY")
+OPENROUTER_API_URL = os.getenv("OPENROUTER_API_URL", "https://openrouter.ai/api/v1")
+OPENROUTER_MODEL = os.getenv("OPENROUTER_MODEL", "xiaomi/mimo-v2-flash:free")

geomind/tools/__init__.py

@@ -0,0 +1,27 @@
+"""
+GeoMind Tools - Functions available to the AI agent.
+
+This module contains all the tools that the agent can call:
+- Geocoding: Convert place names to coordinates
+- STAC Search: Query the Sentinel-2 catalog
+- Processing: Load and process imagery data
+"""
+
+from .geocoding import geocode_location, get_bbox_from_location
+from .stac_search import search_imagery, get_item_details, list_recent_imagery
+from .processing import (
+    create_rgb_composite,
+    calculate_ndvi,
+    get_band_statistics,
+)
+
+__all__ = [
+    "geocode_location",
+    "get_bbox_from_location",
+    "search_imagery",
+    "get_item_details",
+    "list_recent_imagery",
+    "create_rgb_composite",
+    "calculate_ndvi",
+    "get_band_statistics",
+]