Initial add of ecommercie - order status goal and tools

tools/__init__.py

@@ -17,6 +17,9 @@ from .fin.check_account_valid import check_account_valid
 from .fin.get_account_balances import get_account_balance
 from .fin.move_money import move_money
 
+from .ecommerce.get_order_status import get_order_status
+from .ecommerce.track_package import track_package
+
 from .give_hint import give_hint
 from .guess_location import guess_location
 
@@ -54,6 +57,10 @@ def get_handler(tool_name: str):
         return get_account_balance    
     if tool_name == "FinMoveMoneyOrder":
         return move_money    
+    if tool_name == "GetOrderStatus":
+        return get_order_status
+    if tool_name == "TrackPackage":
+        return track_package   
     if tool_name == "GiveHint":
         return give_hint
     if tool_name == "GuessLocation":

tools/data/customer_order_data.json

@@ -0,0 +1,15 @@
+{ 
+    "orders": [
+        {
+            "id": "123",
+            "email": "matt.murdock@nelsonmurdock.com",
+            "status": "paid"
+        },
+        {
+            "id": "456",
+            "email": "foggy.nelson@nelsonmurdock.com",
+            "status": "shipped",
+            "tracking_id": "9434609206094724509058" 
+        }
+    ]
+}

tools/ecommerce/get_order_status.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+import json
+
+# this is made to demonstrate functionality but it could just as durably be an API call
+# called as part of a temporal activity with automatic retries
+def get_order_status(args: dict) -> dict:
+    
+    order_id = args.get("order_id")
+
+    file_path = Path(__file__).resolve().parent.parent / "data" / "customer_order_data.json"
+    if not file_path.exists():
+        return {"error": "Data file not found."}
+    
+    with open(file_path, "r") as file:
+        data = json.load(file)
+    order_list = data["orders"]
+
+    for order in order_list:
+        if order["id"] == order_id:
+            if order["status"] == "shipped":
+                return{"status": order["status"], "tracking_id": order["tracking_id"]}
+            else:
+                return{"status": order["status"]}
+        
+    return_msg = "Order " + order_id + " not found."
+    return {"error": return_msg}

tools/ecommerce/track_package.py

@@ -0,0 +1,104 @@
+import http
+import os
+import json
+
+def track_package_faked(args: dict) -> dict:
+    
+    tracking_id = args.get("tracking_id")
+ 
+    #return_msg = "Account not found with email address " + email + " or account ID: " + account_id
+    return {"tracking_info": "delivered, probably"}
+
+'''Format of response:
+{
+    "TrackingNumber": "",
+    "Delivered": false,
+    "Carrier": "USPS",
+    "ServiceType": "USPS Ground Advantage<SUP>&#153;</SUP>",
+    "PickupDate": "",
+    "ScheduledDeliveryDate": "April 14, 2025",
+    "ScheduledDeliveryDateInDateTimeFromat": "2025-04-14T00:00:00",
+    "StatusCode": "In Transit from Origin Processing",
+    "Status": "Departed Post Office",
+    "StatusSummary": "Your item has left our acceptance facility and is in transit to a sorting facility on April 10, 2025 at 7:06 am in IRON RIDGE, WI 53035.",
+    "Message": "",
+    "DeliveredDateTime": "",
+    "DeliveredDateTimeInDateTimeFormat": null,
+    "SignatureName": "",
+    "DestinationCity": "CITY",
+    "DestinationState": "ST",
+    "DestinationZip": "12345",
+    "DestinationCountry": null,
+    "EventDate": "2025-04-10T07:06:00",
+    "TrackingDetails": [
+        {
+            "EventDateTime": "April 10, 2025 7:06 am",
+            "Event": "Departed Post Office",
+            "EventAddress": "IRON RIDGE WI 53035",
+            "State": "WI",
+            "City": "IRON RIDGE",
+            "Zip": "53035",
+            "EventDateTimeInDateTimeFormat": "2025-04-10T07:06:00"
+        },
+        {
+            "EventDateTime": "April 9, 2025 11:29 am",
+            "Event": "USPS picked up item",
+            "EventAddress": "IRON RIDGE WI 53035",
+            "State": "WI",
+            "City": "IRON RIDGE",
+            "Zip": "53035",
+            "EventDateTimeInDateTimeFormat": "2025-04-09T11:29:00"
+        },
+        {
+            "EventDateTime": "April 7, 2025 6:29 am",
+            "Event": "Shipping Label Created, USPS Awaiting Item",
+            "EventAddress": "IRON RIDGE WI 53035",
+            "State": "WI",
+            "City": "IRON RIDGE",
+            "Zip": "53035",
+            "EventDateTimeInDateTimeFormat": "2025-04-07T06:29:00"
+        }
+    ]
+}
+'''
+def track_package(args: dict) -> dict:
+
+    tracking_id = args.get("tracking_id")
+
+    api_key = os.getenv("PACKAGE_RAPIDAPI_KEY")
+    api_host = os.getenv("PACKAGE_RAPIDAPI_HOST", "trackingpackage.p.rapidapi.com")
+
+    conn = http.client.HTTPSConnection(api_host)
+    headers = {
+        "x-rapidapi-key": api_key,
+        "x-rapidapi-host": api_host,
+        "Authorization": "Basic Ym9sZGNoYXQ6TGZYfm0zY2d1QzkuKz9SLw==",
+    }
+
+    path = f"/TrackingPackage?trackingNumber={tracking_id}"
+
+    conn.request("GET", path, headers=headers)
+    res = conn.getresponse()
+    data = res.read()
+    data_decoded = data.decode("utf-8")
+    conn.close()
+
+    try:
+        json_data = json.loads(data_decoded)
+    except json.JSONDecodeError:
+        return {"error": "Invalid JSON response"}
+
+    scheduled_delivery_date = json_data["ScheduledDeliveryDate"]
+    carrier = json_data["Carrier"]
+    status_summary = json_data["StatusSummary"]
+    tracking_link = ""
+    if carrier == "USPS":
+        tracking_link = f"https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1={tracking_id}"
+    #tracking_details = json_data.get("TrackingDetails", [])
+
+    return {
+        "scheduled_delivery_date": scheduled_delivery_date,
+        "carrier": carrier,
+        "status_summary": status_summary,
+        "tracking_link": tracking_link,
+    }

tools/goal_registry.py

@@ -95,6 +95,7 @@ goal_pirate_treasure = AgentGoal(
     ),
 )
 
+# ----- Travel Goals ---
 goal_match_train_invoice = AgentGoal(
     id = "goal_match_train_invoice",
     category_tag="travel-trains",
@@ -180,6 +181,7 @@ goal_event_flight_invoice = AgentGoal(
     ),
 )
 
+# ----- HR Goals ---
 # This goal uses the data/employee_pto_data.json file as dummy data.
 goal_hr_schedule_pto = AgentGoal(
     id = "goal_hr_schedule_pto",
@@ -268,6 +270,7 @@ goal_hr_check_paycheck_bank_integration_status = AgentGoal(
     ),
 )
 
+# ----- FinServ Goals ---
 # this tool checks account balances, and uses ./data/customer_account_data.json as dummy data
 goal_fin_check_account_balances = AgentGoal(
     id = "goal_fin_check_account_balances",
@@ -340,6 +343,41 @@ goal_fin_move_money = AgentGoal(
     ),
 )
 
+# ----- E-Commerce Goals ---
+#todo: add goal to list all orders for last X amount of time?
+#todo: add goal to reorder?
+# this tool checks account balances, and uses ./data/customer_account_data.json as dummy data
+goal_ecomm_order_status = AgentGoal(
+    id = "goal_ecomm_order_status",
+    category_tag="ecommerce",
+    agent_name="Check Order Status",
+    agent_friendly_description="Check the status of your order.",   
+    tools=[
+        tool_registry.ecomm_get_order_status,
+        tool_registry.ecomm_track_package,
+    ],
+    description="The user wants to learn the status of a specific order. If the status is 'shipped', they might want to get the package tracking information. To assist with that goal, help the user gather args for these tools in order: "
+    "1. GetOrderStatus: get the status of the order"
+    "2. TrackPackage: provide tracking information for the package. This tool is optional and should only be offered if the status is 'shipped' - otherwise, skip this tool and do not mention it to the user.",
+    starter_prompt=starter_prompt_generic,
+    example_conversation_history="\n ".join(
+        [
+            "user: I'd like to know the status of my order",
+            "agent: Sure! I can help you out with that. May I have your email address or order number?",
+            "user: email is bob.johnson@emailzzz.com ",
+            "user_confirmed_tool_run: <user clicks confirm on GetOrderStatus tool>",
+            "tool_result: { 'status': 'shipped', 'tracking_id': 'abc123' }",
+            "agent: Your order has been shipped. Would you like to see the tracking inforation?",
+            "user: Yes",
+            "user_confirmed_tool_run: <user clicks confirm on TrackPackage tool>",
+            "tool_result: { 'scheduled_delivery_date': 'April 30, 2025', 'carrier': 'USPS', 'status_summary': 'Your item has left our acceptance facility and is in transit to a sorting facility on April 10, 2025 at 7:06 am in IRON RIDGE, WI 53035.', 'tracking_link': 'https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=12345",
+            "agent: Your package is scheduled to be delivered on April 30, 2025 via USPS. Here is the most recent status from them regarding your package: \n"
+            "Your item has left our acceptance facility and is in transit to a sorting facility on April 10, 2025 at 7:06 am in IRON RIDGE, WI 53035. \n"
+            "You can find the full tracking details here: tracking_link !",
+        ]
+    ),
+)
+
 #Add the goals to a list for more generic processing, like listing available agents
 goal_list: List[AgentGoal] = []
 goal_list.append(goal_choose_agent_type)
@@ -351,6 +389,7 @@ goal_list.append(goal_hr_check_pto)
 goal_list.append(goal_hr_check_paycheck_bank_integration_status)
 goal_list.append(goal_fin_check_account_balances)
 goal_list.append(goal_fin_move_money)
+goal_list.append(goal_ecomm_order_status)
 
 
 

tools/tool_registry.py

@@ -317,3 +317,33 @@ financial_move_money = ToolDefinition(
         ),
     ],
 )
+
+# ----- ECommerce Use Case Tools -----
+ecomm_get_order_status = ToolDefinition(
+    name="GetOrderStatus",
+    description="Get status of order by order number.",
+    arguments=[
+        ToolArgument(
+            name="order_id",
+            type="string",
+            description="ID of order to determine status of",
+        ),
+    ],
+)
+
+ecomm_track_package = ToolDefinition(
+    name="TrackPackage",
+    description="Get tracking information for a package by shipping provider and tracking ID",
+    arguments=[
+        ToolArgument(
+            name="tracking_id",
+            type="string",
+            description="ID of package to track",
+        ),
+        ToolArgument(
+            name="userConfirmation",
+            type="string",
+            description="Indication of user's desire to get package tracking information",
+        ),
+    ],
+)