ivcap-lambda 0.7.22__py3-none-any.whl

ivcap_lambda/logging.json

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "filters": {
+    "suppress_paths": {
+      "()": "ivcap_lambda.logger.SuppressPathsFilter",
+      "targets": [
+        "/_healtz"
+      ]
+    }
+  },
+  "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"
+    },
+    "renamed": {
+      "format": "%(asctime)s %(levelname)s (uvicorn): %(message)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",
+      "filters": [
+        "suppress_paths"
+      ]
+    },
+    "uvicorn_error": {
+      "class": "logging.StreamHandler",
+      "level": "DEBUG",
+      "formatter": "renamed",
+      "stream": "ext://sys.stderr"
+    }
+  },
+  "root": {
+    "level": "INFO",
+    "handlers": [
+      "default"
+    ]
+  },
+  "loggers": {
+    "app": {
+      "level": "DEBUG"
+    },
+    "event": {
+      "level": "DEBUG"
+    },
+    "uvicorn.access": {
+      "handlers": [
+        "access"
+      ],
+      "level": "INFO",
+      "propagate": false
+    },
+    "uvicorn.error": {
+      "handlers": [
+        "uvicorn_error"
+      ],
+      "level": "INFO",
+      "propagate": false
+    }
+  },
+  "disable_existing_loggers": false
+}

ivcap_lambda/mcp.py

@@ -0,0 +1,261 @@
+#
+# 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 asyncio
+from pydantic import BaseModel
+from typing import Dict, Any, Union
+import json
+from pydantic import BaseModel
+from typing import Any
+from typing import Dict, List, Optional, Union
+from typing_extensions import Literal
+import json
+from typing import Optional, Union
+from fastapi import FastAPI, Request, Response, status
+
+from ivcap_service import getLogger, IvcapResult, ExecutionError
+
+from .builder import ToolDescription, tools
+
+logger = getLogger("mcp")
+
+class Notification(BaseModel):
+    type: str = "notification"
+    message: str
+
+# {
+#   "jsonrpc": "2.0",
+#   "id": 5,
+#   "result": {
+#     "content": [
+#       {
+#         "type": "text",
+#         "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
+#       }
+#     ],
+#     "structuredContent": {
+#       "temperature": 22.5,
+#       "conditions": "Partly cloudy",
+#       "humidity": 65
+#     }
+#   }
+# }
+class Result(BaseModel):
+    type: str = "result"
+    data: Any
+
+class JsonRpcRequest(BaseModel):
+    """
+    Pydantic model for a JSON-RPC 2.0 request object.
+    """
+    jsonrpc: Literal["2.0"]
+    method: str
+    params: Optional[Union[Dict[str, Any], List[Any]]] = None
+    id: Union[int, str, None] = None
+
+
+class JsonRpcSuccessResponse(BaseModel):
+    """
+    Pydantic model for a JSON-RPC 2.0 success response.
+    """
+    jsonrpc: Literal["2.0"]
+    result: Any
+    id: Union[int, str, None]
+
+
+class JsonRpcErrorObject(BaseModel):
+    """
+    Pydantic model for the error object in a JSON-RPC 2.0 error response.
+    """
+    code: int
+    message: str
+    data: Optional[Any] = None
+
+
+class JsonRpcErrorResponse(BaseModel):
+    """
+    Pydantic model for a JSON-RPC 2.0 error response.
+    """
+    jsonrpc: Literal["2.0"]
+    error: JsonRpcErrorObject
+    id: Union[int, str, None]
+
+#JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse
+
+# === Tool Runner (non-streaming path) ===
+async def run_tool_once(req_id: str, tool_name: str, input: dict, httpReq: Request) -> Result:
+    tool = next((t for t in tools if t.name == tool_name), None)
+    if not tool:
+        return Result(type="error", data=f"Tool '{tool_name}' not found")
+
+    try:
+        input_model = tool.input[0]
+        if input_model:
+            # verify parameters
+            m = input_model(**input)
+        else:
+            m = input
+        queue = await tool.executor.execute(m, f"urn:mcp:{req_id}", httpReq, report_result=False)
+        result = await asyncio.wait_for(queue.get(), timeout=600)
+        queue.task_done()
+    except (asyncio.CancelledError, GeneratorExit):
+        # allow cooperative shutdown; propagate cancellation cleanly
+        raise
+    except Exception as e:
+        return Result(type="error", data=str(e))
+
+    if isinstance(result, IvcapResult):
+        if isinstance(result.raw, BaseModel):
+            try:
+                data = result.raw.model_dump()
+                return Result(type="result", data=data)
+            except Exception:
+                pass
+
+        try:
+            data = str(result.content)
+            return Result(type="result", data=data)
+        except Exception as ex:
+            result = ExecutionError(error=f"while converting result to string - {ex}", type="")
+
+    if not isinstance(result, ExecutionError):
+        # this should never happen
+        logger.error(f"expected 'ExecutionError' but got {type(result)}")
+        result = ExecutionError(
+            error="please report unexpected internal error - expected 'ExecutionError' but got {type(result)}",
+            type="internal_error",
+        )
+    return Result(type="error", data=str(result.error))
+
+async def handle_tools_call(req_id, params, req: JsonRpcRequest, httpReq: Request):
+    tool_name = params["name"]
+    tool_args = params.get("arguments", {})
+
+    message = await run_tool_once(req_id, tool_name, tool_args, httpReq)
+    mtype = message.type
+    if mtype == "error":
+        data = message.data or "???"
+        error = JsonRpcErrorObject(
+            code=1000,
+            message=str(data),
+            data=data
+        )
+        return JsonRpcErrorResponse(id=req_id, error=error, jsonrpc="2.0")
+
+    elif mtype == "notification":
+        # Not expected in non-streaming mode; treat as no-op
+        error = JsonRpcErrorObject(
+            code=1001,
+            message="Unexpected notification message type in non-streaming mode",
+        )
+        return JsonRpcErrorResponse(id=req_id, error=error, jsonrpc="2.0")
+
+    elif mtype == "result":
+        return _result_response(req_id, message)
+
+    else:
+        error = JsonRpcErrorObject(
+            code=1002,
+            message=f"Unknown message type `{mtype}' received from tool",
+        )
+        return JsonRpcErrorResponse(id=req_id, error=error, jsonrpc="2.0")
+
+def _result_response(req_id, message):
+        # If result is not a string, convert to string
+        data = message.data or ""
+        result = {}
+        if not isinstance(data, str):
+            text = json.dumps(data)
+            result["structuredContent"] = data
+        else:
+            text = data
+
+        result["content"] = [
+            {
+                "type": "text",
+                "text": text
+            }
+        ]
+        return JsonRpcSuccessResponse(id=req_id, result=result, jsonrpc="2.0")
+
+
+def register_mcp(app: FastAPI, path_prefix: str = "/mcp"):
+    """
+    Register the MCP JSON-RPC handler on the given FastAPI app and path_prefix.
+    This replaces the @app.post(...) decorator usage.
+    The worker_fn and executor parameters are accepted for API symmetry but are not
+    directly used by the MCP route.
+    """
+
+    async def handle_rpc(rpcReq: JsonRpcRequest, httpReq: Request) -> Union[JsonRpcSuccessResponse, JsonRpcErrorResponse, Response]:
+        method = rpcReq.method
+        req_id = rpcReq.id
+        params = rpcReq.params
+
+        if method == "tools/call":
+            return await handle_tools_call(req_id, params, rpcReq, httpReq)
+
+        elif method == "tools/list":
+            return await handle_tools_list(req_id)
+
+        elif method == "initialize":
+            return await handle_initialize(req_id, app)
+
+        elif method == "notifications/initialized":
+            return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+        return await handle_unknown_method(req_id)
+
+    app.add_api_route(
+        path_prefix,
+        handle_rpc,
+        methods=["POST"],
+        response_model=None,
+        response_model_exclude_none=True,
+        response_model_by_alias=True,
+    )
+    logger.info(f"Added MCP endpoint at '{path_prefix}'")
+
+
+async def handle_unknown_method(req_id):
+    return JsonRpcErrorResponse({
+        "jsonrpc": "2.0",
+        "id": req_id,
+        "error": JsonRpcErrorObject(code=-32601, message="Unknown method"),
+    })
+
+async def handle_tools_list(req_id) -> JsonRpcSuccessResponse:
+    def f(td: ToolDescription):
+        _, description = (td.worker_fn.__doc__.lstrip() + "\n").split("\n", 1)
+        input_type = td.input[0]
+        return {
+            "name": td.name,
+            "description": description.strip(),
+            "inputSchema": input_type.model_json_schema(),
+        }
+    tl = [f(t) for t in tools]
+    result = { "tools": tl, "isLast": True} # "nextCursor": None }
+    return JsonRpcSuccessResponse(id=req_id, result=result, jsonrpc="2.0")
+
+async def handle_initialize(req_id, app) -> JsonRpcSuccessResponse:
+    result = {
+        "protocolVersion": "2024-11-05",
+        "serverInfo": {
+            "name": f"MCP Server for {app.title}",
+            "version": app.version
+        },
+        "capabilities": {
+            "tools": {
+                "listChanged": False
+            },
+            # "resources": {},
+            # "prompts": {},
+            "toolProvider": {
+                "version": "1.0.0",
+                "toolInvocationModes": ["standard", "streaming"]
+            }
+        }
+    }
+    return JsonRpcSuccessResponse(id=req_id, result=result, jsonrpc="2.0")

ivcap_lambda/py.typed

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

ivcap_lambda/secret.py

@@ -0,0 +1,44 @@
+#
+# 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.
+#
+
+"""
+DEPRECATED: ivcap_lambda.secret.SecretMgrClient
+
+The SecretMgrClient has moved to ivcap_service.secret.SecretMgrClient.
+This module keeps a backwards-compatible shim so existing imports like
+
+    from ivcap_lambda.secret import SecretMgrClient
+
+continue to work. Please migrate to:
+
+    from ivcap_service.secret import SecretMgrClient
+
+This shim will be removed in a future release.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+__all__ = ["SecretMgrClient"]
+
+from ivcap_service.secret import SecretMgrClient as _SecretMgrClient  # type: ignore
+
+
+class SecretMgrClient(_SecretMgrClient):
+    """Backward-compatibility shim for SecretMgrClient.
+
+    Deprecated: Use ivcap_service.secret.SecretMgrClient instead.
+    """
+
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "ivcap_lambda.secret.SecretMgrClient is deprecated; use "
+            "ivcap_service.secret.SecretMgrClient",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)

ivcap_lambda/server.py

@@ -0,0 +1,217 @@
+#
+# 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 argparse
+from logging import Logger
+from signal import SIGTERM, signal
+from typing import Any, Callable, Dict, Optional
+from fastapi import FastAPI, Request, Response
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+import uvicorn
+import os
+import sys
+
+from ivcap_service import (
+    Service,
+    service_log_config,
+    getLogger,
+    print_tool_definition,
+    otel_instrument,
+    set_context,
+    set_event_reporter_factory,
+    SidecarReporter,
+    get_version as get_service_version,
+)
+
+from .executor import Executor, get_job_context
+from .version import get_version
+from .utils import find_first
+
+# from .context import set_context, otel_instrument
+from .builder import tools
+
+# shutdown pod cracefully
+signal(SIGTERM, lambda _1, _2: sys.exit(0))
+
+_app = FastAPI(
+    docs_url="/api",
+)
+
+
+def get_fast_app() -> FastAPI:
+    """Get the FastAPI app instance.
+
+    Returns:
+        FastAPI: The FastAPI app instance.
+    """
+    return _app
+
+
+def start_tool_server(
+    service: Service,
+    *,
+    logger: Optional[Logger] = None,
+    custom_args: Optional[
+        Callable[[argparse.ArgumentParser], argparse.Namespace]
+    ] = None,
+    run_opts: Optional[Dict[str, Any]] = None,
+    with_telemetry: Optional[bool] = None,
+):
+    """A helper function to start a FastApi server
+
+    Args:
+        service (Service): service description
+        logger (Logger): _description_
+        custom_args (Optional[Callable[[argparse.ArgumentParser], argparse.Namespace]], optional): _description_. Defaults to None.
+        run_opts (Optional[Dict[str, Any]], optional): _description_. Defaults to None.
+        with_telemetry: (Optional[bool]): Instantiate or block use of OpenTelemetry tracing
+    """
+    if len(tools) == 0:
+        raise ValueError(
+            "No tools have been registered. Please register at least one tool using the ivcap_lambda decorator."
+        )
+
+    app = get_fast_app()
+    app.title = service.name
+    app.version = service.version or os.environ.get("VERSION", "???")
+    app.contact = dict(service.contact) if service.contact else None
+    app.license_info = dict(service.license) if service.license else None
+
+    title = service.name
+    if logger is None:
+        logger = getLogger("app")
+
+    tool_names = [tool.name for tool in tools]
+    parser = argparse.ArgumentParser(description=title)
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=os.environ.get("HOST", "0.0.0.0"),
+        help="Host address",
+    )
+    parser.add_argument(
+        "--port", type=int, default=os.environ.get("PORT", "8090"), help="Port number"
+    )
+    parser.add_argument(
+        "--with-telemetry", action="store_true", help="Initialise OpenTelemetry"
+    )
+    parser.add_argument("--with-mcp", action="store_true", help="Add an MCP endpoint")
+    parser.add_argument(
+        "--print-service-description",
+        type=str,
+        metavar="NAME",
+        nargs="?",
+        const=tool_names[0],
+        default=None,
+        help=f"Print service description to stdout [{','.join(tool_names)}]",
+    )
+    parser.add_argument(
+        "--print-tool-description",
+        type=str,
+        metavar="NAME",
+        nargs="?",
+        const=tool_names[0],
+        default=None,
+        help=f"Print tool description to stdout [{','.join(tool_names)}]",
+    )
+
+    if custom_args is not None:
+        args = custom_args(parser)
+    else:
+        args = parser.parse_args()
+
+    if args.print_tool_description:
+        tool = next((t for t in tools if t.name == args.print_tool_description), None)
+        if tool is None:
+            print(
+                f"Tool '{args.print_tool_description}' not found. Available tools: {', '.join(tool_names)}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        print_tool_definition(tool.worker_fn)
+        sys.exit(0)
+
+    if args.print_service_description:
+        from .service_definition import print_rest_service_definition
+
+        tool = next(
+            (t for t in tools if t.name == args.print_service_description), None
+        )
+        if tool is None:
+            print(
+                f"Tool '{args.print_service_description}' not found. Available tools: {', '.join(tool_names)}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        print_rest_service_definition(service, tool.worker_fn)
+        sys.exit(0)
+
+    logger.info(
+        f"{title} - {os.getenv('VERSION')} - v{get_version()}|v{get_service_version()}"
+    )
+
+    # Check for '_healtz' service
+    healtz = find_first(app.routes, lambda r: r.path == "/_healtz")
+    if healtz is None:
+
+        @app.get("/_healtz", tags=["System"])
+        def healtz():
+            return {"version": os.environ.get("VERSION", "???")}
+
+    if args.with_mcp:
+        from .mcp import register_mcp
+
+        register_mcp(app, "/mcp")
+
+    # print(f">>>> OTEL_EXPORTER_OTLP_ENDPOINT: {os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT')}")
+    set_event_reporter_factory(SidecarReporter)
+
+    def get_context():
+        jctxt = get_job_context()
+        if jctxt is None or jctxt.job_id is None:
+            logger.warning("missing job context in thread")
+            return None
+        return jctxt
+
+    set_context(get_context)
+
+    otel_instrument(
+        with_telemetry, lambda _: FastAPIInstrumentor.instrument_app(app), logger
+    )
+
+    async def _add_version(request: Request, call_next) -> Response:
+        from .version import __version__
+
+        resp = await call_next(request)
+        resp.headers["Ivcap-AI-Tool-Version"] = __version__
+        return resp
+
+    app.middleware("http")(_add_version)
+
+    if run_opts is None:
+        run_opts = {}
+
+    class Server(uvicorn.Server):
+        def handle_exit(self, sig: int, frame: any) -> None:
+            logger.info(
+                f"Received request for shutdown. Waiting for all running requests to finish first."
+            )
+            Executor.wait_for_exit_ready()
+            super().handle_exit(sig, frame)
+
+    server = Server(
+        config=uvicorn.Config(
+            app,
+            host=args.host,
+            port=args.port,
+            log_config=service_log_config(),
+            **run_opts,
+        )
+    )
+
+    # Start the server
+    server.run()
+
+    # uvicorn.run(app, host=args.host, port=args.port, log_config=service_log_config(), **run_opts)

ivcap_lambda/service_definition.py

@@ -0,0 +1,44 @@
+#
+# 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 os
+from typing import Callable, List, Any, Optional, Union
+from pydantic import BaseModel, Field
+
+from ivcap_service import Service, IMAGE_PLACEHOLDER, Resources, ServiceDefinition
+from ivcap_service import create_service_definition, find_resources_file, find_command
+
+REST_CONTROLLER_SCHEMA = "urn:ivcap:schema.service.rest.1"
+
+class RestController(BaseModel):
+    jschema: str = Field(default=REST_CONTROLLER_SCHEMA, alias="$schema")
+    image: str
+    command: Union[List[str], str]
+    resources: Resources = Field(default_factory=Resources)
+
+def print_rest_service_definition(
+    service_description: Service,
+    fn: Callable[..., Any],
+    service_id: Optional[str] = None,
+):
+    sd = create_rest_service_definition(
+        service_description,
+        fn,
+        service_id=service_id,
+    )
+    print(sd.model_dump_json(indent=2, by_alias=True, exclude_none=True))
+
+def create_rest_service_definition(
+    service_description: Service,
+    fn: Callable[..., Any],
+    service_id: Optional[str] = None,
+) -> ServiceDefinition:
+    # controller
+    image = os.getenv("DOCKER_IMG", IMAGE_PLACEHOLDER)
+
+    command = find_command()
+    resources = find_resources_file()
+    controller = RestController(image=image, command=command, resources=resources)
+    return create_service_definition(service_description, fn, REST_CONTROLLER_SCHEMA, controller, service_id)