ivcap_service 0.6.8__tar.gz

ivcap_service-0.6.8/AUTHORS.md

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

ivcap_service-0.6.8/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.6.8/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.3
+Name: ivcap_service
+Version: 0.6.8
+Summary: SDK library for building services for the IVCAP platform
+Author: Max Ott
+Author-email: max.ott@csiro.au
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: cachetools (>=5.5.2,<6.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: ivcap-client (>=0.44.2,<0.45.0)
+Requires-Dist: opentelemetry-distro (>=0.51b0,<0.52)
+Requires-Dist: opentelemetry-exporter-otlp (>=1.30.0,<2.0.0)
+Requires-Dist: opentelemetry-instrumentation-httpx (>=0.51b0,<0.52)
+Requires-Dist: opentelemetry-instrumentation-requests (>=0.51b0,<0.52)
+Requires-Dist: pydantic (>=2.11.4,<3.0.0)
+Description-Content-Type: text/markdown
+
+# ivcap-service: A python library for building services for the IVCAP platform
+
+<a href="https://scan.coverity.com/projects/ivcap-service-sdk-python">
+  <img alt="Coverity Scan Build Status"
+       src="https://scan.coverity.com/projects/31773/badge.svg"/>
+</a>
+
+A python library containing various helper and environment functions
+to simplify developing services to be deployed on IVCAP.
+
+> **Note:** A template git repository 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.
+
+## Describe the service <a name="register"></a>
+
+```python
+logging_init()
+logger = getLogger("app")
+
+service = Service(
+    name="Some service",
+    contact={
+        "name": "Mary Doe",
+        "email": "mary.doe@acme.au",
+    },
+    license_info={
+        "name": "MIT",
+        "url": "https://opensource.org/license/MIT",
+    },
+)
+```
+
+
+```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_service(req: Request) -> Result:
+    """
+    Here should go a quite extensive description of what the service can be
+    used for so that an agent can work out if this service is useful in
+    a specific context.
+
+    DO NOT ADD PARAMTER AND RETURN DECRIPTIONS -
+       DESCRIBE THEM IN THE `Request` MODEL
+    """
+    ...
+
+    return Result(...)
+```
+
+## Start the Service <a name="start"></a>
+
+```python
+if __name__ == "__main__":
+    from ivcap_service import start_batch_service
+    some_service(service, consume_compute)
+```
+

ivcap_service-0.6.8/README.md

@@ -0,0 +1,63 @@
+# ivcap-service: A python library for building services for the IVCAP platform
+
+<a href="https://scan.coverity.com/projects/ivcap-service-sdk-python">
+  <img alt="Coverity Scan Build Status"
+       src="https://scan.coverity.com/projects/31773/badge.svg"/>
+</a>
+
+A python library containing various helper and environment functions
+to simplify developing services to be deployed on IVCAP.
+
+> **Note:** A template git repository 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.
+
+## Describe the service <a name="register"></a>
+
+```python
+logging_init()
+logger = getLogger("app")
+
+service = Service(
+    name="Some service",
+    contact={
+        "name": "Mary Doe",
+        "email": "mary.doe@acme.au",
+    },
+    license_info={
+        "name": "MIT",
+        "url": "https://opensource.org/license/MIT",
+    },
+)
+```
+
+
+```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_service(req: Request) -> Result:
+    """
+    Here should go a quite extensive description of what the service can be
+    used for so that an agent can work out if this service is useful in
+    a specific context.
+
+    DO NOT ADD PARAMTER AND RETURN DECRIPTIONS -
+       DESCRIBE THEM IN THE `Request` MODEL
+    """
+    ...
+
+    return Result(...)
+```
+
+## Start the Service <a name="start"></a>
+
+```python
+if __name__ == "__main__":
+    from ivcap_service import start_batch_service
+    some_service(service, consume_compute)
+```

ivcap_service-0.6.8/ivcap_service/__init__.py

@@ -0,0 +1,20 @@
+#
+# Copyright (c) 2025 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, service_log_config, set_service_log_config
+from .service import start_batch_service, Service
+from .service_definition import create_service_definition, find_resources_file, find_command, IMAGE_PLACEHOLDER, Resources, ServiceDefinition
+from .tool_definition import create_tool_definition, print_tool_definition, ToolDefinition
+from .utils import get_function_return_type, get_input_type
+from .ivcap import get_ivcap_url, verify_result, push_result, set_result_callback, OnResultF, SidecarReporter
+from .types import IvcapResult, BinaryResult, ExecutionError, JobContext
+from .context import otel_instrument, set_context
+from .events import (
+    EventReporter, set_event_reporter_factory, EventFactoryF, create_event_reporter,
+    BaseEvent, GenericEvent, GenericErrorEvent,
+)

ivcap_service-0.6.8/ivcap_service/context.py

@@ -0,0 +1,148 @@
+#
+# Copyright (c) 2025 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.
+#
+
+# Various "patches" to maiontain context between incoming requests
+# and calls to external services within a "session"
+#
+import functools
+from logging import Logger
+from ivcap_service import getLogger
+import os
+from typing import Any, Callable, Literal, Optional
+from httpx import URL as URLx
+from urllib.parse import urlparse
+
+from .types import JobContext
+
+ExecContextF = Callable[[], JobContext]
+
+def otel_instrument(
+    with_telemetry: Optional[Literal[True]],
+    extension: Optional[Callable[[str], None]],
+    logger: Logger,
+):
+    if with_telemetry == False:
+        return
+    endpoint = os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT')
+    if endpoint == None:
+        if with_telemetry == True:
+            logger.warning("requested --with-telemetry but exporter is not defined")
+        return
+
+    if os.environ.get("PYTHONPATH") == None:
+            os.environ["PYTHONPATH"] = ""
+    import opentelemetry.instrumentation.auto_instrumentation.sitecustomize # force internal settings
+    logger.info(f"instrumenting for endpoint {endpoint}")
+    if extension != None:
+        extension(endpoint)
+    # Also instrumemt
+    try:
+        from opentelemetry.instrumentation.requests import RequestsInstrumentor
+        RequestsInstrumentor().instrument()
+    except ImportError:
+        pass
+    try:
+        import httpx # checks if httpx library is even used by this tool
+        from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+        HTTPXClientInstrumentor().instrument()
+    except ImportError:
+        pass
+
+def extend_requests(context_f: ExecContextF):
+    from requests import Session, PreparedRequest
+
+    logger = getLogger("app.request")
+
+    # Save original function
+    wrapped_send = Session.send
+
+    @functools.wraps(wrapped_send)
+    def _send(
+        self: Session, request: PreparedRequest, **kwargs: Any
+    ):
+        ctxt = context_f()
+        logger.debug(f"{ctxt.job_id if ctxt else '???'}: Instrumenting 'requests' request to {request.url}")
+        _modify_request(request, ctxt, logger)
+        # Call original method
+        return wrapped_send(self, request, **kwargs)
+
+    # Apply wrapper
+    Session.send = _send
+
+def _modify_request(request, ctxt: JobContext, logger):
+    headers = request.headers
+    url = request.url
+    hostname = _get_hostname(url)
+    is_local_url = hostname.endswith(".local") or hostname.endswith(".minikube") or hostname.endswith(".ivcap.net")
+    if not is_local_url:
+        request.url = _wrap_proxy_url(url, headers)
+    job_id = ctxt.job_id if ctxt != None else None
+    if job_id != None: # OTEL messages won't have a jobID
+        headers["Ivcap-Job-Id"] = job_id
+    auth = ctxt.job_authorization if ctxt != None else None
+    if auth != None and is_local_url:
+        logger.debug(f"Adding 'Authorization' header")
+        headers["Authorization"] = auth
+
+def _get_hostname(url):
+    try:
+        if isinstance(url, URLx):
+            return url.host
+        if isinstance(url, str):
+            return urlparse(url).hostname
+    except Exception:
+        return ""
+
+ivcap_proxy_url = os.getenv('IVCAP_PROXY_URL')
+
+def _wrap_proxy_url(url, headers):
+    global ivcap_proxy_url
+    if ivcap_proxy_url == None:
+        return url
+
+    if isinstance(url, URLx):
+        # ensuring that any 'unset' query parameters are not included
+        # in the final URL
+        query_params = [(k, v) for k, v in url.params.items() if v is not None]
+        url2 = URLx(url).copy_with(params=query_params)
+        forward_url = str(url2)
+        proxy_url = URLx(ivcap_proxy_url)
+    if isinstance(url, str):
+        forward_url = url # urllib.parse.quote_plus(url)
+        proxy_url = ivcap_proxy_url
+    headers["Ivcap-Forward-Url"] = forward_url
+    return proxy_url
+
+def extend_httpx(context_f: ExecContextF):
+    try:
+        import httpx
+    except ImportError:
+        return
+
+    logger = getLogger("app.httpx")
+
+    # Save original function
+    wrapped_send = httpx.Client.send
+    def _send(self, request, **kwargs):
+        ctxt = context_f()
+        logger.debug(f"{ctxt.job_id if ctxt else '???'}: Instrumenting 'httpx' request to {request.url}")
+        _modify_request(request, ctxt, logger)
+        # Call original method
+        return wrapped_send(self, request, **kwargs)
+    # Apply wrapper
+    httpx.Client.send = _send
+
+    wrapped_asend = httpx.AsyncClient.send
+    def _asend(self, request, **kwargs):
+        ctxt = context_f()
+        logger.debug(f"{ctxt.job_id if ctxt else '???'}: Instrumenting 'httpx' async request to {request.url}")
+        _modify_request(request, ctxt, logger)
+        return wrapped_asend(self, request, **kwargs)
+    httpx.AsyncClient.send = _asend
+
+def set_context(context_f: ExecContextF):
+    extend_requests(context_f)
+    extend_httpx(context_f)

ivcap_service-0.6.8/ivcap_service/events.py

@@ -0,0 +1,163 @@
+#
+# Copyright (c) 2025 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 contextlib import contextmanager
+import traceback
+from typing import Any, Callable, ClassVar, Generator, Optional, Type
+from pydantic import BaseModel, Field
+import json
+
+from .logger import getLogger
+
+class BaseEvent(BaseModel):
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if 'SCHEMA' not in getattr(cls, '__annotations__', {}):
+            raise TypeError(f"{cls.__name__} must annotate SCHEMA as 'ClassVar[str]'")
+        if not hasattr(cls, 'SCHEMA'):
+            raise TypeError(f"{cls.__name__} must define a class constant 'SCHEMA'")
+
+    def model_dump(self, *args, **kwargs):
+        d = super().model_dump(*args, **kwargs)
+        d["$schema"] = self.__class__.SCHEMA
+        return d
+
+    def model_dump_json(self, *args, **kwargs):
+        # Only pass *args, **kwargs to model_dump, not to json.dumps
+        return json.dumps(self.model_dump(*args, **kwargs))
+
+class GenericEvent(BaseEvent):
+    SCHEMA: ClassVar[str] = "urn:ivcap:schema:service.event.generic.1"
+    name: str = Field(description="Name of event")
+    options: Optional[dict[str, Any]] = Field(None, description="Optional list of options")
+
+class GenericErrorEvent(BaseEvent):
+    SCHEMA: ClassVar[str]= "urn:ivcap:schema:service.event.error.1"
+    error: str = Field(description="Error description")
+    context: Optional[str] = Field(None, description="Optional description of context")
+    stacktrace:  Optional[list[str]] = Field(None, description="Optional stacktrace")
+
+
+class StepStartEvent(GenericEvent):
+    SCHEMA: ClassVar[str] = "urn:ivcap:schema:service.event.step.start.1"
+
+class StepInfoEvent(GenericEvent):
+    SCHEMA: ClassVar[str] = "urn:ivcap:schema:service.event.step.info.1"
+
+class StepErrorEvent(GenericErrorEvent):
+    SCHEMA: ClassVar[str] = "urn:ivcap:schema:service.event.step.error.1"
+
+class StepFinishEvent(GenericEvent):
+    SCHEMA: ClassVar[str] = "urn:ivcap:schema:service.event.step.finish.1"
+
+logger = getLogger("event")
+
+event_reporter_factory = None
+
+EventFactoryF = Callable[[str, Optional[str]], 'EventReporter']
+def set_event_reporter_factory(factory: EventFactoryF):
+    """
+    Set afactory function for creating specialised EventReporter instances.
+
+    Args:
+        factory (EventFactoryF): A factory function that takes a job ID and an optional job authorization token,
+        and returns an instance of EventReporter. If None, the default EventReporter will be used.
+    """
+    global event_reporter_factory
+    if factory is not None and not callable(factory):
+        raise ValueError("Factory must be a callable that returns an EventReporter instance.")
+    event_reporter_factory = factory
+
+def create_event_reporter(job_id: str, job_authorization: Optional[str] = None) -> 'EventReporter':
+    """
+    Create an EventReporter instance for the given job ID.
+
+
+    Args:
+        job_id (str): The unique identifier for the job.
+        job_authorization (Optional[str]): Optional authorization token for the job.
+
+    Returns:
+        EventReporter: An instance of EventReporter initialized with the job ID.
+    """
+    if event_reporter_factory is not None:
+        return event_reporter_factory(job_id, job_authorization)
+    return EventReporter(job_id, job_authorization)
+
+class EventContext:
+    def __init__(self,
+                 event_name:str,
+                 reporter:'EventReporter',
+                 finishEventClass: Optional[Type[BaseEvent]],
+                 errorEventClass: Optional[Type[GenericErrorEvent]]
+        ):
+        self._event_name = event_name
+        self._reporter = reporter
+        self._finishEventClass = finishEventClass
+        self._errorEventClass = errorEventClass
+        self._finished_sent = False
+
+    @property
+    def name(self):
+        return self._event_name
+
+    def finished(self, **kwargs):
+        if self._finishEventClass:
+            event = self._finishEventClass(name=self._event_name, **kwargs)
+        else:
+            event = GenericEvent(name=self._event_name, options=kwargs)
+        self._reporter.emit(event)
+        self._finished_sent = True
+
+    def info(self, event: BaseEvent | dict):
+        self._reporter.emit(event)
+
+    def error(self, err: Exception, context: Optional[str]=None):
+        evc = self._errorEventClass if self._errorEventClass is not None else GenericErrorEvent
+        stacktrace = traceback.format_tb(err.__traceback__)
+        if not context:
+            context = self._event_name
+        event = evc(error=str(err), stacktrace=stacktrace, context=context)
+        self._reporter.emit(event)
+
+EventCtxtGenerator = Generator[EventContext, None, None]
+
+class EventReporter:
+    def __init__(self, job_id: str, job_authorization: str):
+        self.job_id = job_id
+        self.job_authorization = job_authorization
+
+    def _send(self, event: BaseEvent):
+        logger.debug(f"{self.job_id}: {event.model_dump_json(exclude_none=True)}")
+
+    def emit(self, event: BaseEvent):
+        self._send(event)
+
+    def step_started(self, step_name: str, **kwargs):
+        self.emit(StepStartEvent(name=step_name, options=kwargs))
+
+    def step_finished(self, step_name: str, **kwargs):
+        self.emit(StepFinishEvent(name=step_name, options=kwargs))
+
+    def step(self, step_name, **kwargs):
+        self.step_started(step_name, options=kwargs)
+        return self._event_scope(step_name, StepFinishEvent(name=step_name), StepErrorEvent)
+
+    @contextmanager
+    def _event_scope(
+        self,
+        event_name: str,
+        defaultFinishEvent: Optional[BaseEvent] = None,
+        errorEventClass: Optional[Type[GenericErrorEvent]] = None,
+    ) -> EventCtxtGenerator:
+        fevc = defaultFinishEvent.__class__ if defaultFinishEvent else None
+        ctxt = EventContext(event_name, self, fevc, errorEventClass)
+        try:
+            yield ctxt
+        except Exception as e:
+            ctxt.error(e, event_name)
+            raise e
+        if not ctxt._finished_sent:
+            self.emit(defaultFinishEvent)