ivcap-lambda 0.7.22__py3-none-any.whl

ivcap_lambda/utils.py

@@ -0,0 +1,100 @@
+#
+# 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 typing import Optional, Dict, Tuple
+
+def get_title_from_path(path: str) -> Tuple[str, str]:
+    """Extracts a title from a path string.
+
+    Args:
+        path: A string potentially formatted as a directory path (separated by '/').
+
+    Returns:
+        A tuple containing:
+        - The processed string with the first character in lowercase.
+        - The processed string with the first character in uppercase.
+    """
+    # Extract the last element of the path
+    last_element = path.split('/')[-1]
+
+    # Convert to singular form if plural
+    singular = last_element
+    if singular.endswith('ies'):
+        singular = singular[:-3] + 'y'
+    elif singular.endswith('es'):
+        singular = singular[:-2]
+    elif singular.endswith('ss'):
+        pass
+    elif singular.endswith('s'):
+        singular = singular[:-1]
+
+    # Replace underscores with spaces
+    singular = singular.replace('_', ' ')
+
+    # Create lowercase and uppercase versions
+    if singular:
+        lowercase = singular[0].lower() + singular[1:] if len(singular) > 1 else singular.lower()
+        uppercase = singular[0].upper() + singular[1:] if len(singular) > 1 else singular.upper()
+    else:
+        lowercase = ""
+        uppercase = ""
+
+    return (lowercase, uppercase)
+
+def find_first(iterable, condition):
+    """
+    Returns the first item in the iterable for which the condition is True.
+    If no such item is found, returns None.
+    """
+    for item in iterable:
+        if condition(item):
+            return item
+    return None
+
+from fastapi import Request
+from typing import Optional, Dict, Tuple
+
+
+def get_public_url_prefix(req: Request) -> str:
+    """Return the public url prefix for `req`.
+
+    First checks for a `Forwarded` http header and if
+    absent uses the request's `base_ur;` variable.
+
+    Args:
+        req (Request): A FastAPI request instance
+
+    Returns:
+        str: A url as string
+    """
+    fw = get_forwarded_header(req)
+    if fw != None:
+        prefix = f"{fw.get('proto', 'http')}:://{fw.get('for')}"
+    else:
+        prefix = str(req.base_url).rstrip("/")
+    return prefix
+
+
+def get_forwarded_header(request: Request) -> Optional[Dict[str, str]]:
+    """
+    Parses the "Forwarded" HTTP header according to RFC 7239.
+    Returns a dictionary containing the parsed header values, or None if the header is missing.
+    """
+    header_value = request.headers.get("Forwarded")
+    if not header_value:
+        return None
+
+    parsed_values: Dict[str, str] = {}
+    for element in header_value.split(";"):
+        parts = element.split("=", 1)
+        if len(parts) == 2:
+            key = parts[0].strip()
+            value = parts[1].strip()
+            # Remove quotes if present
+            if value.startswith('"') and value.endswith('"'):
+                value = value[1:-1]
+            parsed_values[key] = value
+
+    return parsed_values

ivcap_lambda/version.py

@@ -0,0 +1,22 @@
+#
+# 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.
+#
+
+__version__ = "???"
+try:  # Python > 3.8+
+    from importlib_metadata import version
+
+    __version__ = version("ivcap_lambda")
+except ImportError:
+    try:
+        import pkg_resources
+
+        __version__ = pkg_resources.get_distribution("ivcap_lambda").version
+    except Exception:
+        pass
+
+
+def get_version():
+    return __version__

ivcap_lambda-0.7.22.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: ivcap-lambda
+Version: 0.7.22
+Summary: Helper functions for building lambda-style services on the IVCAP platform
+License-File: AUTHORS.md
+License-File: LICENSE
+Author: Max Ott
+Author-email: max.ott@csiro.au
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: cachetools (>=5.5.2,<6.0.0)
+Requires-Dist: fastapi (>=0.121.2,<0.122.0)
+Requires-Dist: ivcap-service (>=0.6.21,<0.7.0)
+Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.57b0)
+Requires-Dist: uuid6 (==2024.7.10)
+Requires-Dist: uvicorn (>=0.38.0,<0.39.0)
+Description-Content-Type: text/markdown
+
+# ivcap-lambda: A python library for building lambda-style services on the IVCAP platform
+
+> **Package renamed:** `ivcap-ai-tool` has been renamed to `ivcap-lambda` to reflect that
+> the library is useful for any lambda-style IVCAP service, not just AI agent tools.
+> A [compatibility shim](./compat/) is published under the old name — existing apps
+> will continue to work but will see a `DeprecationWarning` prompting migration.
+
+<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_lambda-0.7.22.dist-info/RECORD

@@ -0,0 +1,18 @@
+ivcap_lambda/__init__.py,sha256=vQouZe1fq35W5UC2621EPOOni_xalbp9Zm6yxSDiPMI,777
+ivcap_lambda/builder.py,sha256=MEcVs4Ey-WC6yRMIIzi-Phww8je37ToacVtKjt4VvHk,10779
+ivcap_lambda/decorators.py,sha256=DgLOqKAYVh1QvJNDcsFqoIzXloagIflBeBO-WeNdy0U,2813
+ivcap_lambda/executor.py,sha256=RwpZq9-Sm2RBUXqnskQUr580KF4zt9r0Vcm60_mF3uY,11154
+ivcap_lambda/logger.py,sha256=yVioKPXVUIjJ5WzSA0_cZxr4jthM8K7edO3px29rnLA,1327
+ivcap_lambda/logging.json,sha256=EBreTGZe9l1OU_MylU4uigwA8Zs_RBPCr_UDWHCVAps,1642
+ivcap_lambda/mcp.py,sha256=WJgLLD3sWxd9vxhHnqPTf0zMENgNgaCCJEjDKZ162hU,8250
+ivcap_lambda/py.typed,sha256=8ZJUsxZiuOy1oJeVhsTWQhTG_6pTVHVXk5hJL79ebTk,25
+ivcap_lambda/secret.py,sha256=iLXhuA0rfXLIlahVp7htk9_MF5mpfccLa6gqCp-OAEs,1300
+ivcap_lambda/server.py,sha256=17TIO3k9ThTNwoXYbEXkWvTIkPvEdS5esExy4U4Qyd0,6629
+ivcap_lambda/service_definition.py,sha256=ueuvo4Q5TxmBao-zeNP8qfYuVJwdXPAuYaOPGd12DdI,1645
+ivcap_lambda/utils.py,sha256=PhUwlMDO8_IHIPonJo8ZKX9mJimrmRDluhfkDzGGCwY,3145
+ivcap_lambda/version.py,sha256=doCn_9Qf-MMhIb5a7LaVxn3YDfU0SVH2QebEUTYe8zg,610
+ivcap_lambda-0.7.22.dist-info/METADATA,sha256=3i1id6WPuwOaGuCEDz0-MJTIXit9frM2kfbr31UuVy8,4397
+ivcap_lambda-0.7.22.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+ivcap_lambda-0.7.22.dist-info/licenses/AUTHORS.md,sha256=s9xR4_HAHQgbNlj505LViebt5AtACQmhPf92aJvNYgg,88
+ivcap_lambda-0.7.22.dist-info/licenses/LICENSE,sha256=dsQrDPPwW7iJs9pxahgJKDW8RNPf5FyXG70MFUlxcuk,1587
+ivcap_lambda-0.7.22.dist-info/RECORD,,

ivcap_lambda-0.7.22.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ivcap_lambda-0.7.22.dist-info/licenses/AUTHORS.md

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

ivcap_lambda-0.7.22.dist-info/licenses/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.