{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "# MAAP Python Library Function Guide (maap-py v5, OGC)\n",
    "\n",
    "This notebook provides comprehensive documentation and examples for functions related to algorithms and jobs following OGC"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "from maap.maap import MAAP\n",
    "import json\n",
    "import os\n",
    "import time\n",
    "\n",
    "maap = MAAP()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14",
   "metadata": {},
   "source": [
    "## Algorithm Management Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3ca914d-5bb3-48c5-bce8-672b41f9c934",
   "metadata": {},
   "source": [
    "### list_algorithms()\n",
    "\n",
    "List all available OGC processes/algorithms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Status Code: 200\n",
      "Found 3 algorithms\n",
      "1. ID: shah-sardem-sarsen, Title: shah-sardem-sarsen\n",
      "2. ID: sardem-sarsen1, Title: sardem-sarsen\n",
      "3. ID: mlucas-operawatermask1, Title: mlucas-operawatermask1\n"
     ]
    }
   ],
   "source": [
    "# List all algorithms\n",
    "response = maap.list_algorithms()\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    algorithms = response.json()\n",
    "    print(f\"Found {len(algorithms.get('processes', []))} algorithms\")\n",
    "    \n",
    "    # Display first few algorithms\n",
    "    for i, algo in enumerate(algorithms.get('processes', [])[:3]):\n",
    "        print(f\"{i+1}. ID: {algo.get('id')}, Title: {algo.get('title')}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16",
   "metadata": {},
   "source": [
    "### register_algorithm()\n",
    "\n",
    "Deploy a new OGC process from a CWL file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "17",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Registration Status: 202\n",
      "{\n",
      "    \"title\": \"sardem-sarsen-mlucas\",\n",
      "    \"description\": \"sardem-sarsen\",\n",
      "    \"keywords\": [\n",
      "        \"null\"\n",
      "    ],\n",
      "    \"metadata\": [],\n",
      "    \"id\": \"sardem-sarsen-mlucas\",\n",
      "    \"version\": \"nasa-ogc\",\n",
      "    \"jobControlOptions\": [],\n",
      "    \"deploymentJobID\": 4,\n",
      "    \"status\": \"accepted\",\n",
      "    \"created\": \"2025-10-06 22:19:02.338271\",\n",
      "    \"links\": [\n",
      "        {\n",
      "            \"href\": \"/ogc/deploymentJobs/4\",\n",
      "            \"rel\": \"monitor\",\n",
      "            \"type\": \"application/json\",\n",
      "            \"hreflang\": \"en\",\n",
      "            \"title\": \"Deploying process status link\"\n",
      "        }\n",
      "    ],\n",
      "    \"processPipelineLink\": {\n",
      "        \"href\": \"https://repo.dit.maap-project.org/root/deploy-ogc-hysds/-/pipelines/9901\",\n",
      "        \"rel\": \"monitor\",\n",
      "        \"type\": \"text/html\",\n",
      "        \"hreflang\": \"en\",\n",
      "        \"title\": \"Link to process pipeline\"\n",
      "    }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "# Register algorithm from CWL file URL\n",
    "# NOTE that you need to use the link with the raw version\n",
    "cwl_url = \"https://repo.dit.maap-project.org/root/ogc-application-packages/-/raw/main/mlucas/sardem-sarsen-mlucas/nasa-ogc/process.cwl?ref_type=heads\"\n",
    "\n",
    "response = maap.register_algorithm(execution_unit_href=cwl_url)\n",
    "print(f\"Registration Status: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 202:\n",
    "    result_register_algorithm = response.json()\n",
    "    print(json.dumps(result_register_algorithm, indent=4))\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "28",
   "metadata": {},
   "source": [
    "### get_deployment_status()\n",
    "\n",
    "Check the status of an algorithm deployment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Checking deployment status for deployment 4\n",
      "Status Code: 200\n",
      "Deployment Status is: running\n"
     ]
    }
   ],
   "source": [
    "# Check deployment status\n",
    "deployment_id = result_register_algorithm.get(\"deploymentJobID\")\n",
    "print(f\"Checking deployment status for deployment {deployment_id}\")\n",
    "\n",
    "response = maap.get_deployment_status(deployment_id)\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    deployment_info = response.json()\n",
    "    status = deployment_info[\"status\"]\n",
    "    print(f\"Deployment Status is: {status}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "24",
   "metadata": {},
   "source": [
    "### delete_algorithm()\n",
    "\n",
    "Delete an algorithm (must be original deployer)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "25",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Delete Status: 200\n",
      "Algorithm deleted successfully\n"
     ]
    }
   ],
   "source": [
    "# Delete algorithm\n",
    "# Change to be a process id for one of your processes \n",
    "process_id = 5\n",
    "\n",
    "response = maap.delete_algorithm(process_id)\n",
    "print(f\"Delete Status: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    print(\"Algorithm deleted successfully\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18",
   "metadata": {},
   "source": [
    "### register_algorithm_from_cwl_file()\n",
    "\n",
    "Register algorithm from a local CWL configuration file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "19",
   "metadata": {
    "scrolled": true,
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# This function has not been implemented yet "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20",
   "metadata": {},
   "source": [
    "### describe_algorithm()\n",
    "\n",
    "Get detailed information about a specific algorithm."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Status Code: 200\n",
      "Algorithm Title: shah-sardem-sarsen\n",
      "Description: This application is designed to process Synthetic Aperture Radar (SAR) data from Sentinel-1 GRD (Ground Range Detected) products using a Digital Elevation Model (DEM) obtained from Copernicus.\n",
      "Version: nasa-ogc\n"
     ]
    }
   ],
   "source": [
    "# Describe a specific algorithm\n",
    "process_id = 1\n",
    "\n",
    "response = maap.describe_algorithm(process_id)\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    algorithm_info = response.json()\n",
    "    print(f\"Algorithm Title: {algorithm_info.get('title')}\")\n",
    "    print(f\"Description: {algorithm_info.get('description')}\")\n",
    "    print(f\"Version: {algorithm_info.get('version')}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22",
   "metadata": {},
   "source": [
    "### update_algorithm()\n",
    "\n",
    "Update an existing algorithm (must be original deployer)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "23",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Update Status: 202\n",
      "Algorithm updated successfully\n"
     ]
    }
   ],
   "source": [
    "# Update existing algorithm\n",
    "process_id = 3\n",
    "# Provide a new_cwl_url with the same id/version of the process you are trying to alter  \n",
    "new_cwl_url = \"https://raw.githubusercontent.com/grallewellyn/cwl-files/refs/heads/main/cwl6.cwl\"\n",
    "\n",
    "response = maap.update_algorithm(process_id, new_cwl_url)\n",
    "print(f\"Update Status: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 202:\n",
    "    result = response.json()\n",
    "    print(f\"Algorithm updated successfully\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26",
   "metadata": {},
   "source": [
    "### get_algorithm_package()\n",
    "\n",
    "Get the formal package description for an algorithm."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Status Code: 200\n",
      "Package description: {\n",
      "  \"processDescription\": \"This application is designed to process Synthetic Aperture Radar (SAR) data from Sentinel-1 GRD (Ground Range Detected) products using a Digital Elevation Model (DEM) obtained from Copernicus.\",\n",
      "  \"executionUnit\": {\n",
      "    \"href\": \"https://repo.uat.maap-project.org/root/ogc-application-packages/-/raw/main/sshah/shah-sardem-sarsen/nasa-ogc/process.cwl\",\n",
      "    \"rel\": \"monitor-desc\",\n",
      "    \"type\": \"text/html\",\n",
      "    \"hreflang\": \"en\",\n",
      "    \"title\": \"Process Reference\"\n",
      "  }\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "# Get algorithm package\n",
    "process_id = 1\n",
    "\n",
    "response = maap.get_algorithm_package(process_id)\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    package_info = response.json()\n",
    "    print(f\"Package description: {json.dumps(package_info, indent=2)}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30",
   "metadata": {},
   "source": [
    "## Job Management Functions\n",
    "\n",
    "### submit_job()\n",
    "\n",
    "Execute an algorithm job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Submit a job\n",
    "process_id = 1\n",
    "inputs = {\n",
    "    \"bbox\": \"-118.06817 34.22169 -118.05801 34.22822\",\n",
    "    \"stac_catalog_folder\": \"https://cmr.earthdata.nasa.gov/stac/ASF/collections/SENTINEL-1A_DP_GRD_HIGH_1/items/S1A_IW_GRDH_1SDV_20250330T171421_20250330T171446_058537_073E4F_985B-GRD_HD\",\n",
    "    \"stac_asset_name\": \"edu/GRD_HD/SA/S1A_IW_GRDH_1SDV_20250330T171421_20250330T171446_058537_073E4F_985B\"\n",
    "  }\n",
    "queue = \"maap-dps-sandbox\"\n",
    "\n",
    "response = maap.submit_job(\n",
    "    process_id=process_id,\n",
    "    inputs=inputs,\n",
    "    queue=queue,\n",
    "    dedup=True,  # Optional: prevent duplicate jobs\n",
    "    tag=\"my-experiment-run1\"  # Optional: user-defined tag\n",
    ")\n",
    "\n",
    "print(f\"Job Submission Status: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 202:\n",
    "    job_info = response.json()\n",
    "    print(f\"Status: {job_info.get('status')}\")\n",
    "    job_id = job_info.get('id')\n",
    "    print(f\"Job ID: {job_info.get('id')}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32",
   "metadata": {},
   "source": [
    "### get_job_status()\n",
    "\n",
    "Check the status of a submitted job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "33",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Check job status\n",
    "print(f\"Checking job status for {job_id}\")\n",
    "\n",
    "response = maap.get_job_status(job_id)\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    job_status = response.json()\n",
    "    print(f\"Job Status: {json.dumps(job_status, indent=2)}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34",
   "metadata": {},
   "source": [
    "### get_job_result()\n",
    "\n",
    "Get results from a completed job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Get job results\n",
    "print(f\"Checking job results for {success_job_id}\")\n",
    "\n",
    "response = maap.get_job_result(success_job_id)\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    results = response.json()\n",
    "    print(f\"Job Results: {json.dumps(results, indent=2)}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36",
   "metadata": {},
   "source": [
    "### cancel_job()\n",
    "\n",
    "Cancel a running job or delete a queued job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Cancel job\n",
    "process_id = existing_process_id_dont_alter\n",
    "inputs = {\n",
    "    \"bbox\": \"-118.06817 34.22169 -118.05801 34.22822\",\n",
    "    \"stac_catalog_folder\": \"https://cmr.earthdata.nasa.gov/stac/ASF/collections/SENTINEL-1A_DP_GRD_HIGH_1/items/S1A_IW_GRDH_1SDV_20250330T171421_20250330T171446_058537_073E4F_985B-GRD_HD\",\n",
    "    \"stac_asset_name\": \"edu/GRD_HD/SA/S1A_IW_GRDH_1SDV_20250330T171421_20250330T171446_058537_073E4F_985B\"\n",
    "  }\n",
    "queue = \"maap-dps-sandbox\"\n",
    "response = maap.submit_job(\n",
    "    process_id=process_id,\n",
    "    inputs=inputs,\n",
    "    queue=queue,\n",
    "    dedup=False,  # Optional: prevent duplicate jobs\n",
    "    tag=\"my-experiment-run1\"  # Optional: user-defined tag\n",
    ")\n",
    "job_info = response.json()\n",
    "if response.status_code == 202:\n",
    "    job_id = job_info.get('id')\n",
    "\n",
    "print(f\"Waiting for job {job_id} to be accepted as its status so that it can be cancelled\")\n",
    "time.sleep(10)\n",
    "print(f\"Cancelling job with ID {job_id}\")\n",
    "\n",
    "# Cancel without waiting\n",
    "response = maap.cancel_job(job_id)\n",
    "\n",
    "print(f\"Cancel Status: {response.status_code}\")\n",
    "print(response.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38",
   "metadata": {},
   "source": [
    "### list_jobs()\n",
    "\n",
    "List jobs with various filtering options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "39",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# List all jobs (basic)\n",
    "jobs_response = maap.list_jobs()\n",
    "print(f\"Status Code: {jobs_response.status_code}\")\n",
    "\n",
    "if jobs_response.status_code == 200:\n",
    "    jobs = jobs_response.json()\n",
    "    print(f\"Found {len(jobs.get('jobs', []))} total user jobs\")\n",
    "\n",
    "# List jobs with filters\n",
    "filtered_jobs_response = maap.list_jobs(\n",
    "    process_id=1, \n",
    "    status=\"failed\", \n",
    "    limit=5,\n",
    "    page_size=10,\n",
    "    queue=\"maap-dps-sandbox\",\n",
    "    tag=\"testing\",\n",
    "    min_duration=60,  # minimum 60 seconds\n",
    "    max_duration=3600,  # maximum 1 hour\n",
    "    datetime=\"2023-01-01T00:00:00Z/2025-12-31T23:59:59Z\"\n",
    ")\n",
    "print(f\"Filtered jobs {json.dumps(filtered_jobs_response.json(), indent=2)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40",
   "metadata": {},
   "source": [
    "### get_job_metrics()\n",
    "\n",
    "Get performance metrics for a job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "41",
   "metadata": {
    "vscode": {
     "languageId": "r"
    }
   },
   "outputs": [],
   "source": [
    "# Get job metrics\n",
    "\n",
    "response = maap.get_job_metrics(success_job_id)\n",
    "print(f\"Status Code: {response.status_code}\")\n",
    "\n",
    "if response.status_code == 200:\n",
    "    metrics = response.json()\n",
    "    print(f\"Job Metrics: {json.dumps(metrics, indent=2)}\")\n",
    "else:\n",
    "    print(f\"Error: {response.text}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56",
   "metadata": {},
   "source": [
    "### Summary\n",
    "\n",
    "This notebook has covered the functions available in the MAAP Python library for algorithms and jobs:\n",
    "\n",
    "#### Algorithm Management\n",
    "- `list_algorithms()` - List available algorithms\n",
    "- `register_algorithm()` - Deploy new algorithms\n",
    "- `describe_algorithm()` - Get algorithm details\n",
    "- `update_algorithm()` - Update existing algorithms\n",
    "- `delete_algorithm()` - Delete algorithms\n",
    "- `get_algorithm_package()` - Get algorithm package info\n",
    "- `get_deployment_status()` - Check deployment status\n",
    "\n",
    "#### Job Management\n",
    "- `submit_job()` - Execute algorithm jobs\n",
    "- `get_job_status()` - Check job status\n",
    "- `get_job_result()` - Get job results\n",
    "- `cancel_job()` - Cancel running jobs\n",
    "- `list_jobs()` - List user jobs with filters\n",
    "- `get_job_metrics()` - Get job performance metrics\n",
    "\n",
    "Each function is designed to work with the MAAP platform's OGC-compliant API"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "R",
   "language": "R",
   "name": "ir"
  },
  "language_info": {
   "codemirror_mode": "r",
   "file_extension": ".r",
   "mimetype": "text/x-r-source",
   "name": "R",
   "pygments_lexer": "r",
   "version": "4.0.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}