@planqk/planqk-service-sdk 1.9.0 → 2.1.0

package/fern/openapi/openapi.yml

@@ -0,0 +1,342 @@
+openapi: 3.0.0
+info:
+  version: "1.0"
+  title: PLANQK Service API
+  description: |
+    API description for a managed PLANQK Service.
+paths:
+  /:
+    get:
+      tags:
+        - Service API
+      summary: Health checking endpoint
+      description: |
+        This method checks the health of the service.
+      operationId: healthCheck
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    description: Status of the service
+                    example: "Service is up and running"
+    post:
+      tags:
+        - Service API
+      summary: Asynchronous execution of the service
+      description: |
+        This method starts a service execution, which in turn is processed asynchronously by PLANQK. 
+        The location header of the response contains the URL which can be used to query the status and the result of the service execution.
+      operationId: execute
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties:
+                type: object
+              oneOf:
+                - required:
+                    - data
+                  properties:
+                    data:
+                      $ref: '#/components/schemas/InputData'
+                    params:
+                      $ref: '#/components/schemas/InputParams'
+                - required:
+                    - dataRef
+                  properties:
+                    dataRef:
+                      $ref: '#/components/schemas/InputDataRef'
+                    params:
+                      $ref: '#/components/schemas/InputParams'
+      responses:
+        "201":
+          description: Service execution successfully submitted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ServiceExecution"
+          headers:
+            Location:
+              description: URL to query the status and the result of a service execution
+              schema:
+                type: string
+        "400":
+          description: Invalid input
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        "500":
+          description: Internal server error
+  /{id}:
+    get:
+      tags:
+        - Service API
+      summary: Check the status of a service execution
+      description: |
+        This method checks the status of a service execution.
+      operationId: getStatus
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: The id of a service execution
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ServiceExecution"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        "500":
+          description: Internal server error
+  /{id}/result:
+    get:
+      tags:
+        - Service API
+      summary: Get the result of a service execution
+      description: |
+        This method retrieves the result of a service execution.
+      operationId: getResult
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: The id of a service execution
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties:
+                  type: string
+                properties:
+                  _links:
+                    type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/HALLink'
+                    additionalProperties:
+                      $ref: '#/components/schemas/HALLink'
+                  _embedded:
+                    type: object
+                    properties:
+                      status:
+                        $ref: '#/components/schemas/ServiceExecution'
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        "500":
+          description: Internal server error
+  /{id}/result/{file}:
+    get:
+      tags:
+        - Service API
+      summary: Download a result file of a service execution
+      description: |
+        This method downloads a result file of a service execution.
+      operationId: getResultFile
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: The id of a service execution
+          schema:
+            type: string
+        - in: path
+          name: file
+          required: true
+          description: The name of the result file
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        "500":
+          description: Internal server error
+  /{id}/log:
+    get:
+      tags:
+        - Service API
+      summary: Get the log output of a service execution
+      description: |
+        This method retrieves the log output of a service execution.
+      operationId: getLogs
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: The id of a service execution
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        "500":
+          description: Internal server error
+  /{id}/cancel:
+    put:
+      tags:
+        - Service API
+      summary: Cancel a service execution
+      description: |
+        This method cancels a service execution.
+      operationId: cancel
+      parameters:
+        - in: path
+          name: id
+          required: true
+          description: The id of a service execution
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ServiceExecution"
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not found
+        "500":
+          description: Internal server error
+components:
+  schemas:
+    InputData:
+      type: object
+      additionalProperties:
+        type: object
+    InputParams:
+      type: object
+      additionalProperties:
+        type: object
+    InputDataRef:
+      type: object
+      properties:
+        dataPoolId:
+          type: string
+          example: 87cb778e-ac43-11ec-b909-0242ac120002
+        dataSourceDescriptorId:
+          type: string
+          example: 87cb778e-ac43-11ec-b909-0242ac120002
+        fileId:
+          type: string
+          example: 87cb778e-ac43-11ec-b909-0242ac120002
+      required:
+        - dataPoolId
+        - dataSourceDescriptorId
+        - fileId
+    ServiceExecution:
+      type: object
+      properties:
+        id:
+          type: string
+          example: 87cb778e-ac43-11ec-b909-0242ac120002
+        status:
+          type: string
+          enum: [UNKNOWN, PENDING, RUNNING, SUCCEEDED, CANCELLED, FAILED]
+          example: SUCCEEDED
+        createdAt:
+          type: string
+          example: "2022-01-01 22:38:08"
+        startedAt:
+          type: string
+          example: "2022-01-01 22:39:08"
+        endedAt:
+          type: string
+          example: "2022-01-01 22:40:08"
+    # Representation of link as defined in HAL: https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-11
+    HALLink:
+      type: object
+      properties:
+        href:
+          type: string
+          description: The URL of the link
+        templated:
+          type: boolean
+          description: Whether the link is templated (optional)
+          default: false
+        type:
+          type: string
+          description: The media type of the link (optional)
+        deprecation:
+          type: string
+          description: A URL that provides further information about the deprecation of the link (optional)
+        name:
+          type: string
+          description: The name of the link (optional)
+        profile:
+          type: string
+          description: A URL that provides further information about the profile of the link (optional)
+        title:
+          type: string
+          description: The title of the link (optional)
+        hreflang:
+          type: string
+          description: The language of the link's target resource (optional)
+
+  securitySchemes:
+    oauthClientCredentials:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://gateway.platform.planqk.de/token
+          scopes: {}
+
+servers:
+  - url: https://gateway.platform.planqk.de
+
+security:
+  - oauthClientCredentials: []

package/notebooks/python-sdk.ipynb

@@ -0,0 +1,280 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Python SDK"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "jupyter": {
+     "is_executing": true
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from dotenv import load_dotenv\n",
+    "\n",
+    "# Make a copy of .env.example and rename it to .env, place it in the \n",
+    "# root directory, and fill in the values.\n",
+    "\n",
+    "load_dotenv(override=True)\n",
+    "\n",
+    "token_endpoint = os.getenv(\"TOKEN_ENDPOINT\", None)\n",
+    "service_endpoint = os.getenv(\"SERVICE_ENDPOINT\", None)\n",
+    "consumer_key = os.getenv(\"CONSUMER_KEY\", None)\n",
+    "consumer_secret = os.getenv(\"CONSUMER_SECRET\", None)\n",
+    "\n",
+    "print(f\"Token endpoint: {token_endpoint}\")\n",
+    "print(f\"Service endpoint: {service_endpoint}\")\n",
+    "print(f\"Consumer key: {consumer_key}\")\n",
+    "print(f\"Consumer secret: {consumer_secret}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Usage"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from planqk.service.client import PlanqkServiceClient\n",
+    "\n",
+    "# Create a client\n",
+    "client = PlanqkServiceClient(\n",
+    "    service_endpoint, consumer_key, consumer_secret, token_endpoint\n",
+    ")\n",
+    "\n",
+    "# Start a service execution\n",
+    "data = {\"n_coin_tosses\": 3}\n",
+    "service_execution = client.run(request={\"data\": data})\n",
+    "\n",
+    "# Wait for the service execution to finish (blocking)\n",
+    "service_execution.wait_for_final_state()\n",
+    "\n",
+    "status = service_execution.status\n",
+    "ended_at = service_execution.ended_at\n",
+    "print(f\"Service execution finished at '{ended_at}' with status '{status}'\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Service execution finished at '2025-03-14 06:35:36' with status 'SUCCEEDED'\n"
+     ]
+    }
+   ],
+   "source": [
+    "# You may perform other operations while waiting for the service execution to finish\n",
+    "while not service_execution.has_finished:\n",
+    "    print(\"Waiting for service execution to finish...\")\n",
+    "\n",
+    "# Alternatively, you may poll the service execution status\n",
+    "while service_execution.status not in [\"SUCCEEDED\", \"FAILED\", \"CANCELLED\"]:\n",
+    "    service_execution.refresh()\n",
+    "\n",
+    "status = service_execution.status\n",
+    "ended_at = service_execution.ended_at\n",
+    "print(f\"Service execution finished at '{ended_at}' with status '{status}'\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Service execution finished at '2025-03-14 06:35:36' with status 'SUCCEEDED'\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Use the client to retrieve a service execution by its id\n",
+    "service_execution = client.get_service_execution(\"0030737b-35cb-46a8-88c2-f59d4885484d\")\n",
+    "\n",
+    "status = service_execution.status\n",
+    "ended_at = service_execution.ended_at\n",
+    "print(f\"Service execution finished at '{ended_at}' with status '{status}'\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{'000': 10, '001': 7, '010': 18, '011': 14, '100': 16, '101': 7, '110': 14, '111': 14}\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Retrieve the result\n",
+    "result = service_execution.result()\n",
+    "\n",
+    "print(result.counts)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "...\n",
+      "PlanQK:Job:MultilineResult\n",
+      "2025-03-14 06:35:35.424 | DEBUG    | qsharp.telemetry:callHandlers:1706 - In on_exit handler\n",
+      "2025-03-14 06:35:35.424 | DEBUG    | qsharp.telemetry:callHandlers:1706 - Exiting telemetry thread\n",
+      "2025-03-14 06:35:35.424 | DEBUG    | qsharp.telemetry:callHandlers:1706 - Sending telemetry request: b'[{\"ver\": 1, \"name\": \"Microsoft.ApplicationInsights.Metric\", \"time\": \"2025-03-14T06:35:35.424270Z\", \"sampleRate\": 100.0, \"iKey\": \"95d25b22-8b6d-448e-9677-78ad4047a95a\", \"tags\": {\"ai.device.locale\": \"en_US\", \"ai.device.osVersion\": \"#1 SMP PREEMPT_DYNAMIC Thu Jan 16 17:10:14 UTC 2025\"}, \"data\": {\"baseType\": \"MetricData\", \"baseData\": {\"ver\": 2, \"metrics\": [{\"name\": \"qsharp.import\", \"value\": 1, \"count\": 1}], \"properties\": {\"qsharp.version\": \"1.13.2\"}}}}]'\n",
+      "2025-03-14 06:35:36.073 | DEBUG    | qsharp.telemetry:callHandlers:1706 - Telemetry response: 200\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Retrieve service execution logs\n",
+    "logs = service_execution.logs()\n",
+    "\n",
+    "print(\"...\")\n",
+    "for log in logs[-5:]:\n",
+    "    print(log)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "['hello.jpg', 'hello.txt', 'output.json']\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "\n",
+    "# List the result files\n",
+    "files = service_execution.result_files()\n",
+    "\n",
+    "# Download the result files\n",
+    "cwd = os.getcwd()\n",
+    "for file in files:\n",
+    "    service_execution.download_result_file(file, cwd)\n",
+    "\n",
+    "print(files)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Alternatively, you may access the raw byte stream\n",
+    "file_stream = service_execution.result_file_stream(\"output.json\")\n",
+    "\n",
+    "with open(\"output.json\", \"wb\") as f:\n",
+    "    for chunk in file_stream:\n",
+    "        f.write(chunk)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Use a Data Pool as Input Data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "from planqk.service.sdk.types.input_data_ref import InputDataRef\n",
+    "\n",
+    "# Create a client\n",
+    "client = PlanqkServiceClient(\n",
+    "    service_endpoint, consumer_key, consumer_secret, token_endpoint\n",
+    ")\n",
+    "\n",
+    "# Use the InputDataRef class to define a reference to a file in a data pool.\n",
+    "# Create a data pools, and upload a file called 'data.json'. Use the \"Copy File Reference\"\n",
+    "# button in the PLANQK Data Pool UI to copy the data pool id, data source descriptor id, and file id.\n",
+    "file_reference = {\n",
+    "    \"dataPoolId\": \"9b943af3-ca78-4d6e-87fd-33129f5330a2\",\n",
+    "    \"dataSourceDescriptorId\": \"a1e4f7ab-82d5-4158-98c3-3562635cedd2\",\n",
+    "    \"fileId\": \"f9b5c9a2-0101-46a8-9958-383670a2cef4\",\n",
+    "}\n",
+    "\n",
+    "data = InputDataRef.model_validate(\n",
+    "    {\n",
+    "        \"data_pool_id\": file_reference[\"dataPoolId\"],\n",
+    "        \"data_source_descriptor_id\": file_reference[\"dataSourceDescriptorId\"],\n",
+    "        \"file_id\": file_reference[\"fileId\"],\n",
+    "    }\n",
+    ")\n",
+    "params = {\"some_attribute\": True}\n",
+    "\n",
+    "# Start a service execution\n",
+    "service_execution = client.run({\"dataRef\": data, \"params\": params})\n",
+    "\n",
+    "# Wait for the service execution to finish (blocking)\n",
+    "service_execution.wait_for_final_state()\n",
+    "\n",
+    "status = service_execution.status\n",
+    "ended_at = service_execution.ended_at\n",
+    "print(f\"Service execution finished at '{ended_at}' with status '{status}'\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@planqk/planqk-service-sdk",
-  "version": "1.9.0",
-  "description": "Typescript SDK to execute PlanQK Managed Services.",
+  "version": "2.1.0",
+  "description": "SDK to interact with PLANQK Managed Services.",
   "author": "Kipu Quantum GmbH",
   "contributors": [
     "Wurster, Michael <michael.wurster@kipu-quantum.com>"
@@ -11,41 +11,40 @@
     "type": "git",
     "url": "git+https://gitlab.com/planqk-foss/planqk-service-sdk.git"
   },
-  "keywords": [
-    "planqk"
-  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "shx rm -rf dist && tsc -b",
-    "lint": "eslint . --ext .ts --config .eslintrc",
-    "test": "jest --coverage"
+    "lint": "eslint",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "form-data": "^4",
+    "form-data-encoder": "^4",
+    "formdata-node": "^6",
+    "js-base64": "^3",
+    "node-fetch": "^3",
+    "qs": "^6",
+    "readable-stream": "^4",
+    "simple-oauth2": "^5",
+    "url-join": "^5"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.11",
-    "@types/qs": "^6.9.10",
-    "@types/simple-oauth2": "^5.0.7",
-    "@types/url-join": "^4.0.3",
-    "dotenv": "^16.3.1",
-    "eslint": "^8.55.0",
-    "eslint-config-oclif": "^5.0.0",
-    "eslint-config-oclif-typescript": "^3.0.26",
-    "jest": "^29.7.0",
+    "@types/node": "^22",
+    "@types/node-fetch": "^2",
+    "@types/qs": "^6",
+    "@types/simple-oauth2": "^5",
+    "@types/url-join": "^4",
+    "dotenv": "^16",
+    "eslint": "^9",
     "shx": "^0.3.4",
-    "ts-jest": "^29.1.1",
-    "typescript": "^4.6.4"
-  },
-  "dependencies": {
-    "@ungap/url-search-params": "^0.2.2",
-    "axios": "^0.27.2",
-    "form-data": "^4.0.0",
-    "js-base64": "^3.7.5",
-    "qs": "^6.11.2",
-    "simple-oauth2": "^5.0.0",
-    "url-join": "^4.0.1"
+    "typescript": "^5",
+    "typescript-eslint": "^8",
+    "vitest": "^3"
   },
   "private": false,
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "readme": "./README-node.md"
 }

package/planqk/service/__init__.py

@@ -0,0 +1 @@
+from ._version import __version__