ivcap_service 0.3.0__tar.gz

ivcap_service-0.3.0/AUTHORS.md

@@ -0,0 +1,5 @@
+# Initial version authors
+
+* Max Ott <max.ott@csiro.au>
+
+# Partial list of contributors

ivcap_service-0.3.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Commonwealth Scientific and Industrial Research Organisation (CSIRO) ABN 41 687 119 230
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ivcap_service-0.3.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.1
+Name: ivcap_service
+Version: 0.3.0
+Summary: SDK library for building services for the IVCAP platform
+Author: Max Ott
+Author-email: max.ott@csiro.au
+Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: cachetools (>=5.5.2,<6.0.0)
+Requires-Dist: opentelemetry-distro (>=0.51b0,<0.52)
+Requires-Dist: opentelemetry-exporter-otlp (>=1.30.0,<2.0.0)
+Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.51b0,<0.52)
+Requires-Dist: opentelemetry-instrumentation-httpx (>=0.51b0,<0.52)
+Requires-Dist: opentelemetry-instrumentation-requests (>=0.51b0,<0.52)
+Requires-Dist: uuid6 (==2024.7.10)
+Description-Content-Type: text/markdown
+
+# ivcap_ai_tool: A python library for building AI tools for the IVCAP platform
+
+<a href="https://scan.coverity.com/projects/ivcap-works-ivcap-ai-tool-sdk-python">
+  <img alt="Coverity Scan Build Status"
+       src="https://img.shields.io/coverity/scan/31491.svg"/>
+</a>
+
+A python library containing various helper and middleware functions
+to simplify developing AI tools to be deployed on IVCAP.
+
+> **Note:** A template git repositiory using this library can be found on github
+[ivcap-works/ivcap-python-ai-tool-template](https://github.com/ivcap-works/ivcap-python-ai-tool-template). You may clone that and start from there.
+
+## Content
+
+* [Register a Tool Function](#register)
+* [Start the Service](#start)
+* [JSON-RPC Middleware](#json-rpc)
+* [Try-Later Middleware](#try-later)
+
+### Register a Tool Function <a name="register"></a>
+
+```python
+class Request(BaseModel):
+    jschema: str = Field("urn:sd:schema:some_tool.request.1", alias="$schema")
+    ...
+
+class Result(BaseModel):
+    jschema: str = Field("urn:sd:schema:some_tool.1", alias="$schema")
+    ...
+
+def some_tool(req: Request) -> Result:
+    """
+    Here should go a quite extensive description of what the tool can be
+    used for so that an agent can work out if this tool is useful in
+    a specific context.
+
+    DO NOT ADD PARAMTER AND RETURN DECRIPTIONS -
+       DESCRIBE THEM IN THE `Request` MODEL
+    """
+    ...
+
+    return Result(...)
+
+add_tool_api_route(app, "/", some_tool, opts=ToolOptions(tags=["Great Tool"]))
+```
+
+### Start the Service <a name="start"></a>
+
+```python
+app = FastAPI(
+  ..
+)
+
+if __name__ == "__main__":
+    start_tool_server(app, some_tool)
+```
+
+### JSON-RPC Middleware <a name="json-rpc"></a>
+
+This middleware will convert any `POST /` with a payload
+following the [JSON-RPC](https://www.jsonrpc.org/specification)
+specification to an internal `POST /{method}` and will return
+the result formatted according to the JSON-RPC spec.
+
+```python
+from ivcap_fastapi import use_json_rpc_middleware
+
+app = FastAPI(
+  ..
+)
+
+use_json_rpc_middleware(app)
+```
+
+### Try-Later Middleware <a name="try-later"></a>
+
+This middleware is supporting the use case where the execution of a
+requested service is taking longer than the caller is willing to wait.
+A typical use case is where the service is itself outsourcing the execution
+to some other long-running service but may immediately receive a reference
+to the eventual result.
+
+In this case, raising a `TryLaterException` will return with a 204
+status code and additional information on how to later check back for the
+result.
+
+```python
+from ivcap_fastapi import TryLaterException, use_try_later_middleware
+use_try_later_middleware(app)
+
+@app.post("/big_job")
+def big_job(req: Request) -> Response:
+    jobID, expected_exec_time = scheduling_big_job(req)
+    raise TryLaterException(f"/big_job/jobs/{jobID}", expected_exec_time)
+
+@app.get("/big_job/jobs/{jobID}")
+def get_job(jobID: str) -> Response:
+    resp = find_result_for(job_id)
+    return resp
+```
+
+Specifically, raising `TryLaterException(location, delay)` will
+return an HTTP response with a 204 status code with the additional
+HTTP headers `Location` and `Retry-Later` set to `location` and
+`delay` respectively.
+

ivcap_service-0.3.0/README.md

@@ -0,0 +1,106 @@
+# ivcap_ai_tool: A python library for building AI tools for the IVCAP platform
+
+<a href="https://scan.coverity.com/projects/ivcap-works-ivcap-ai-tool-sdk-python">
+  <img alt="Coverity Scan Build Status"
+       src="https://img.shields.io/coverity/scan/31491.svg"/>
+</a>
+
+A python library containing various helper and middleware functions
+to simplify developing AI tools to be deployed on IVCAP.
+
+> **Note:** A template git repositiory using this library can be found on github
+[ivcap-works/ivcap-python-ai-tool-template](https://github.com/ivcap-works/ivcap-python-ai-tool-template). You may clone that and start from there.
+
+## Content
+
+* [Register a Tool Function](#register)
+* [Start the Service](#start)
+* [JSON-RPC Middleware](#json-rpc)
+* [Try-Later Middleware](#try-later)
+
+### Register a Tool Function <a name="register"></a>
+
+```python
+class Request(BaseModel):
+    jschema: str = Field("urn:sd:schema:some_tool.request.1", alias="$schema")
+    ...
+
+class Result(BaseModel):
+    jschema: str = Field("urn:sd:schema:some_tool.1", alias="$schema")
+    ...
+
+def some_tool(req: Request) -> Result:
+    """
+    Here should go a quite extensive description of what the tool can be
+    used for so that an agent can work out if this tool is useful in
+    a specific context.
+
+    DO NOT ADD PARAMTER AND RETURN DECRIPTIONS -
+       DESCRIBE THEM IN THE `Request` MODEL
+    """
+    ...
+
+    return Result(...)
+
+add_tool_api_route(app, "/", some_tool, opts=ToolOptions(tags=["Great Tool"]))
+```
+
+### Start the Service <a name="start"></a>
+
+```python
+app = FastAPI(
+  ..
+)
+
+if __name__ == "__main__":
+    start_tool_server(app, some_tool)
+```
+
+### JSON-RPC Middleware <a name="json-rpc"></a>
+
+This middleware will convert any `POST /` with a payload
+following the [JSON-RPC](https://www.jsonrpc.org/specification)
+specification to an internal `POST /{method}` and will return
+the result formatted according to the JSON-RPC spec.
+
+```python
+from ivcap_fastapi import use_json_rpc_middleware
+
+app = FastAPI(
+  ..
+)
+
+use_json_rpc_middleware(app)
+```
+
+### Try-Later Middleware <a name="try-later"></a>
+
+This middleware is supporting the use case where the execution of a
+requested service is taking longer than the caller is willing to wait.
+A typical use case is where the service is itself outsourcing the execution
+to some other long-running service but may immediately receive a reference
+to the eventual result.
+
+In this case, raising a `TryLaterException` will return with a 204
+status code and additional information on how to later check back for the
+result.
+
+```python
+from ivcap_fastapi import TryLaterException, use_try_later_middleware
+use_try_later_middleware(app)
+
+@app.post("/big_job")
+def big_job(req: Request) -> Response:
+    jobID, expected_exec_time = scheduling_big_job(req)
+    raise TryLaterException(f"/big_job/jobs/{jobID}", expected_exec_time)
+
+@app.get("/big_job/jobs/{jobID}")
+def get_job(jobID: str) -> Response:
+    resp = find_result_for(job_id)
+    return resp
+```
+
+Specifically, raising `TryLaterException(location, delay)` will
+return an HTTP response with a 204 status code with the additional
+HTTP headers `Location` and `Retry-Later` set to `location` and
+`delay` respectively.

ivcap_service-0.3.0/pyproject.toml

@@ -0,0 +1,47 @@
+[tool.poetry]
+name = "ivcap_service"
+version = "0.3.0"
+description = "SDK library for building services for the IVCAP platform"
+
+authors = ["Max Ott <max.ott@csiro.au>"]
+
+readme = "README.md"
+
+include = ["src/ivcap_service/py.typed"]
+
+[tool.poetry.dependencies]
+python = ">=3.8"
+uuid6 = "2024.7.10"
+cachetools = "^5.5.2"
+opentelemetry-distro = "^0.51b0"
+opentelemetry-exporter-otlp = "^1.30.0"
+opentelemetry-instrumentation-fastapi = "^0.51b0"
+opentelemetry-instrumentation-requests = "^0.51b0"
+opentelemetry-instrumentation-httpx = "^0.51b0"
+
+[tool.poetry.dev-dependencies]
+
+[tool.poetry.group.dev.dependencies]
+fastapi = { version = "^0.111.1", extras = ["standard"] }
+pytest = "^7.1.3"
+pytest-cov = "^4.1.0"
+Sphinx = "^5.2.3"
+# myst-nb = "^1.2.0"
+autoapi = "^2.0.1"
+sphinx-autoapi = "^2.0.0"
+sphinx-rtd-theme = "^1.0.0"
+licenseheaders = "^0.8.8"
+
+[tool.semantic_release]
+version_variable = "pyproject.toml:version" # version location
+branch = "main"                             # branch to make releases of
+build_command = "poetry build"              # build dists
+dist_path = "dist/"                         # where to put dists
+upload_to_release = true                    # auto-create GitHub release
+upload_to_pypi = false                      # don't auto-upload to PyPI
+remove_dist = false                         # don't remove dists
+patch_without_tag = true                    # patch release by default
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

ivcap_service-0.3.0/src/ivcap_service/__init__.py

@@ -0,0 +1,12 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+""" A library for building services for the IVCAP platform"""
+
+from .version import __version__
+from .logger import getLogger, logging_init
+from .service import start_batch_service
+from .service_definition import create_service_definition
+from .tool_definition import create_tool_definition, print_tool_definition

ivcap_service-0.3.0/src/ivcap_service/ivcap.py

@@ -0,0 +1,145 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+from dataclasses import Field, dataclass
+import json
+import os
+import traceback
+from typing import Any, Callable, Generic, List, Optional, TypeVar, Union, BinaryIO
+
+from time import sleep
+from urllib.parse import urlparse, urlunparse
+import httpx
+from pydantic import BaseModel, HttpUrl
+from ivcap_fastapi import getLogger
+
+from .types import BinaryResult, ExecutionError, IvcapResult
+
+logger = getLogger("ivcap")
+
+# Number of attempt to deliver job result before giving up
+MAX_DELIVER_RESULT_ATTEMPTS = 4
+
+
+def verify_result(result: any, job_id: str, logger) -> any:
+    if isinstance(result, ExecutionError):
+        return result
+    if isinstance(result, BaseModel):
+        try:
+            return IvcapResult(
+                content=result.model_dump_json(by_alias=True),
+                content_type="application/json",
+                raw=result,
+            )
+        except Exception as ex:
+            msg = f"{job_id}: cannot json serialise pydantic isntance - {str(ex)}"
+            logger.warning(msg)
+            return ExecutionError(
+                error=msg,
+                type=type(ex).__name__,
+                traceback=traceback.format_exc()
+            )
+    if isinstance(result, BinaryResult):
+        return IvcapResult(content=result.content, content_type=result.content_type)
+    if isinstance(result, str):
+        return IvcapResult(content=result, content_type="text/plain", raw=result)
+    if isinstance(result, bytes):
+        # If it's a byte array, return it as is
+        return IvcapResult(
+            content=result,
+            content_type="application/octet-stream",
+            raw=result,
+        )
+    if isinstance(result, BinaryIO):
+        # If it's a file handler, return it as is
+        return IvcapResult(
+            content=result,
+            content_type="application/octet-stream",
+            raw=result
+        )
+    # normal model which should be serialisable
+    try:
+        result = IvcapResult(
+            content=json.dumps(result),
+            content_type="application/json"
+        )
+    except Exception as ex:
+        msg = f"{job_id}: cannot json serialise result - {str(ex)}"
+        logger.warning(msg)
+        result = ExecutionError(
+            error=msg,
+            type=type(ex).__name__,
+        )
+
+def push_result(result: Union[IvcapResult, ExecutionError], job_id: str, authorization: Optional[str]=None):
+    """Actively push result to sidecar, fail quietly."""
+    ivcap_url = get_ivcap_url()
+    if ivcap_url is None:
+        logger.warning(f"{job_id}: no ivcap url found - cannot push result")
+        return
+    url = urlunparse(ivcap_url._replace(path=f"/results/{job_id}"))
+
+    content_type="text/plain"
+    content="SOMETHING WENT WRONG _ PLEASE REPORT THIS ERROR"
+    is_error = False
+    if not (isinstance(result, ExecutionError) or isinstance(result, IvcapResult)):
+        msg = f"{job_id}: expected 'IvcapResult' or 'ExecutionError' but got {type(result)}"
+        logger.warning(msg)
+        result = ExecutionError(
+            error=msg,
+            type='InternalError',
+        )
+
+    if isinstance(result, IvcapResult):
+        content = result.content
+        content_type = result.content_type
+    else:
+        is_error = True
+        if not isinstance(result, ExecutionError):
+            # this should never happen
+            logger.error(f"{job_id}: expected 'ExecutionError' but got {type(result)}")
+            result = ExecutionError(
+                error="please report unexpected internal error - expected 'ExecutionError' but got {type(result)}",
+                type="internal_error",
+            )
+        content = result.model_dump_json(by_alias=True)
+        content_type = "application/json"
+
+
+    wait_time = 1
+    attempt = 0
+    headers = {
+        "Content-Type": content_type,
+        "Is-Error": str(is_error),
+    }
+    if not (authorization == None or authorization == ""):
+        headers["Authorization"] = authorization
+
+    while attempt < MAX_DELIVER_RESULT_ATTEMPTS:
+        try:
+            response = httpx.post(
+                url=url,
+                headers=headers,
+                data=content,
+            )
+            response.raise_for_status()
+            return
+        except Exception as e:
+            attempt += 1
+            logger.info(f"{job_id}: attempt #{attempt} failed to push result - will try again in {wait_time} sec - {type(e)}: {e}")
+            sleep(wait_time)
+            wait_time *= 2
+
+    logger.warning(f"{job_id}: giving up pushing result after {attempt} attempts")
+
+
+def get_ivcap_url() -> HttpUrl:
+    """
+    Returns the sidecar URL from the request headers.
+    """
+    base = os.getenv("IVCAP_BASE_URL")
+    if base == "" or base is None:
+        return None
+    return urlparse(base)

ivcap_service-0.3.0/src/ivcap_service/logger.py

@@ -0,0 +1,27 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+import json
+import logging
+from logging.config import dictConfig
+import os
+
+LOGGING_CONFIG={}
+
+def getLogger(name: str) -> logging.Logger:
+    return logging.getLogger(name)
+
+def service_log_config():
+    return LOGGING_CONFIG
+
+def logging_init(cfg_path: str=None):
+    if not cfg_path:
+        script_dir = os.path.dirname(__file__)
+        cfg_path = os.path.join(script_dir, "logging.json")
+
+    with open(cfg_path, 'r') as file:
+        global LOGGING_CONFIG
+        LOGGING_CONFIG = json.load(file)
+        dictConfig(LOGGING_CONFIG)

ivcap_service-0.3.0/src/ivcap_service/logging.json

@@ -0,0 +1,46 @@
+{
+  "version": 1,
+  "formatters": {
+    "default": {
+      "format": "%(asctime)s %(levelname)s (%(name)s): %(message)s",
+      "datefmt": "%Y-%m-%dT%H:%M:%S%z"
+    },
+    "access": {
+      "()": "uvicorn.logging.AccessFormatter",
+      "fmt": "%(asctime)s %(levelname)s (access): \"%(request_line)s\" %(status_code)s",
+      "datefmt": "%Y-%m-%dT%H:%M:%S%z"
+    }
+  },
+  "handlers": {
+    "default": {
+      "class": "logging.StreamHandler",
+      "level": "DEBUG",
+      "formatter": "default",
+      "stream": "ext://sys.stderr"
+    },
+    "access": {
+      "formatter": "access",
+      "class": "logging.StreamHandler",
+      "stream": "ext://sys.stdout"
+    }
+  },
+  "root": {
+    "level": "INFO",
+    "handlers": [
+      "default"
+    ]
+  },
+  "loggers": {
+    "app": {
+      "level": "DEBUG"
+    },
+    "uvicorn.access": {
+      "handlers": [
+        "access"
+      ],
+      "level": "INFO",
+      "propagate": false
+    }
+  },
+  "disable_existing_loggers": false
+}

ivcap_service-0.3.0/src/ivcap_service/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561