geomind-ai 1.0.0__tar.gz

geomind_ai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harsh Shinde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geomind_ai-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include geomind *.py

geomind_ai-1.0.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: geomind-ai
+Version: 1.0.0
+Summary: AI agent for geospatial analysis
+Author: Harsh Shinde
+License-Expression: MIT
+Project-URL: Homepage, https://harshshinde0.github.io/GeoMind/
+Project-URL: Repository, https://github.com/HarshShinde0/GeoMind
+Project-URL: Documentation, https://github.com/HarshShinde0/GeoMind#readme
+Project-URL: Issues, https://github.com/HarshShinde0/GeoMind/issues
+Keywords: geospatial,satellite-imagery,sentinel-2,ai-agent,remote-sensing,earth-observation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pystac-client>=0.8.0
+Requires-Dist: pystac>=1.10.0
+Requires-Dist: xarray>=2024.1.0
+Requires-Dist: zarr>=2.18.0
+Requires-Dist: dask>=2024.1.0
+Requires-Dist: geopy>=2.4.0
+Requires-Dist: fsspec>=2024.1.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: s3fs>=2024.1.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Set Up API Key
+
+Set your HuggingFace API key in the environment or update `config.py`:
+
+```python
+# In geomind/config.py
+HF_API_KEY = "your_huggingface_api_key"
+```
+
+Get a free API key from [HuggingFace](https://huggingface.co/settings/tokens).
+
+### 3. Run the Agent
+
+```bash
+python main.py
+```
+
+## Example Queries
+
+```
+
+💬 "Create an RGB composite for the most recent image of London"
+
+💬 "Calculate NDVI for Central Park, New York"
+
+💬 "What images are available for Tokyo with less than 10% cloud cover?"
+```
+
+## Approach
+
+### Traditional Approach
+```
+Full Scene Download → Local Storage → Process → Result
+     ~720 MB            Disk I/O      Slow      
+```
+
+### GeoMind Approach (Zarr + fsspec)
+```
+HTTP Range Request → Stream Chunks → Process in Memory → Result
+     ~1-5 MB           No disk          Fast           
+```

geomind_ai-1.0.0/README.md

@@ -0,0 +1,47 @@
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Set Up API Key
+
+Set your HuggingFace API key in the environment or update `config.py`:
+
+```python
+# In geomind/config.py
+HF_API_KEY = "your_huggingface_api_key"
+```
+
+Get a free API key from [HuggingFace](https://huggingface.co/settings/tokens).
+
+### 3. Run the Agent
+
+```bash
+python main.py
+```
+
+## Example Queries
+
+```
+
+💬 "Create an RGB composite for the most recent image of London"
+
+💬 "Calculate NDVI for Central Park, New York"
+
+💬 "What images are available for Tokyo with less than 10% cloud cover?"
+```
+
+## Approach
+
+### Traditional Approach
+```
+Full Scene Download → Local Storage → Process → Result
+     ~720 MB            Disk I/O      Slow      
+```
+
+### GeoMind Approach (Zarr + fsspec)
+```
+HTTP Range Request → Stream Chunks → Process in Memory → Result
+     ~1-5 MB           No disk          Fast           
+```

geomind_ai-1.0.0/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_ai-1.0.0/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()