feat(integration): USGS Earthquake Details Integration (#533)

integrations/community/usgs_eq_details/README.md

@@ -0,0 +1,54 @@
+# USGS Earthquake Details Agent
+If provided an earthquake ID, this agent will query the USGS API for the corresponding earthquake's details, formatting fields to provide users the details in a readble manner.
+
+## Overview
+
+The United States Geological Survey (USGS) assigns individual earthquakes IDs to uniquely identify between events. This being said, each earthquake, correspondingly, has unique details (ex. magnitude, latitude and longitude).
+<br><br>
+This DeltaV compatible agent takes a USGS-assigned earthquake id as an input and will return a formatted list of details pertaining to the earthquake.
+
+## Prerequisites
+
+To use this integration you'll need:
+- Access to the Agentverse
+- Access to DeltaV
+
+## Steps to Use the Integration
+To use this integ
+
+## Steps to run this Agent
+Want to run this agent yourself through the Agentverse? Follow these steps:
+
+### 1. Create this Agent in the **Agentverse**
+
+1. Login to [Agentverse](https://agentverse.ai) and create a `New Agent`.
+2. Select `Blank Agent` and assign a name to your agent (ex.
+USGS Earthquake Details Agent)
+3. Copy the content from `get_usgs_eq_details.py` into `agent.py`.
+5. Click on `Start` to start the agent; it's now running in the Agentverse!
+
+### 2. Register the Agent as a Function
+
+1. Once the agent is running, select `Deploy` and create a `New Function`.
+2. Provide a function title, like:
+```USGS Earthquake Details```
+3. Provide a function description for the AI Engine. For example:
+```
+"This function will provide formatted details given a USGS earthquake ID."
+```
+4. This function will be a primary function. The fields `Protocol` and `Data Model`
+ should automatically be filled out with `USGS Earthquake Protocol` and `USGS_ID` respectively.
+5. Provide an extended description for the AI Engine. For example:
+```
+If a USGS (United States Geological Survey) earthquake ID is provided, this function will provide earthquake details in a formatted manner to the user. This is MUST be a string and not a URL or webpage address.
+```
+
+### 3. Access the Service/Agent on DeltaV
+
+1. Login to [DeltaV](https://deltav.agentverse.ai/home). Assuming you have enough currency, you can query your newly created Agent and function.
+2. Find a USGS-assigned earthquake ID online. An example could be `ci38457511`, which is the earthquake ID for the popular Ridgequest Earthquake Sequence's main event.
+3. Type in a query related to getting earthquake data. For example:
+```
+Could you provide me the earthquake details for earthquake id ci38457511?
+```
+4. Using `Advanced Options`, choose `My Functions`. Then, start the conversation to get earthquake details.

integrations/community/usgs_eq_details/get_usgs_eq_details.py

@@ -0,0 +1,59 @@
+import requests
+from datetime import datetime
+
+from uagents import Context, Protocol, Model
+from ai_engine import UAgentResponse, UAgentResponseType
+
+class USGS_ID(Model):
+    id: str
+
+usgs_eq_protocol = Protocol("USGS Earthquake Protocol")
+
+def get_usgs_eq_details(usgs_id):
+    USGS_API_URL = f"https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&eventid={usgs_id}"
+
+    try:
+        response = requests.get(USGS_API_URL)
+        response.raise_for_status()  # http error check
+        data = response.json()
+
+        properties = data.get('properties', {})
+        geometry = data.get('geometry', {})
+        coordinates = geometry.get('coordinates', [])
+
+        # format time-related strings
+        time_ms = properties.get('time', 0)
+        updated_ms = properties.get('updated', 0)
+        time_str = datetime.utcfromtimestamp(time_ms / 1000).strftime('%Y-%m-%d %H:%M:%S UTC')
+        updated_str = datetime.utcfromtimestamp(updated_ms / 1000).strftime('%Y-%m-%d %H:%M:%S UTC')
+
+        details = (
+            f"Details for Earthquake {usgs_id}\n"
+            f"Title: {properties.get('title', 'N/A')}\n"
+            f"Magnitude: {properties.get('mag', 'N/A')}\n"
+            f"Location: {properties.get('place', 'N/A')}\n"
+            f"Time: {time_str}\n"
+            f"Updated: {updated_str}\n"
+            f"Alert Level: {properties.get('alert', 'N/A')}\n"
+            f"Felt Reports: {properties.get('felt', 'N/A')}\n"
+            f"Coordinates: {coordinates[1]}, {coordinates[0]} (Lat, Long)\n"
+            f"Depth: {coordinates[2]} km\n"
+            f"URL: {properties.get('url', 'N/A')}"
+        )
+
+        return details
+
+    except Exception as err:
+        print(f"An error occured: {err}")
+
+
+@usgs_eq_protocol.on_message(model=USGS_ID, replies={UAgentResponse})
+async def process_usgs_eq_details(ctx: Context, sender: str, msg: USGS_ID):
+    usgs_id = msg.id
+    ctx.logger.info("Grabbing USGS earthquake details for id: " + usgs_id)
+    usgs_eq_details = get_usgs_eq_details(usgs_id)
+    await ctx.send(
+        sender, UAgentResponse(message=usgs_eq_details, type=UAgentResponseType.FINAL)
+    )
+
+agent.include(usgs_eq_protocol, publish_manifest=True)

integrations/community/usgs_eq_details/project.json

@@ -0,0 +1,6 @@
+{
+  "title": "USGS Earthquake Details Integration",
+  "description": "Query the USGS public API for details on a specfic earthquake.",
+  "categories":   ["USGS", "Earthquake"],
+  "deltav": true
+}

integrations/community/usgs_eq_details/pyproject.toml

@@ -0,0 +1,15 @@
+[tool.poetry]
+name = "usgs-eq-details"
+version = "0.1.0"
+description = ""
+authors = ["Steven Le <[email protected]>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+requests = "^2.32.3"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"