mini-oss-osdk 0.1.0a3__tar.gz

mini_oss_osdk-0.1.0a3/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026 ITEM. All rights reserved.
+
+This software and its associated documentation are proprietary to ITEM.
+No permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, sell, or create derivative works from this software except as
+expressly authorized under a separate written agreement with ITEM.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL ITEM
+BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE
+SOFTWARE.

mini_oss_osdk-0.1.0a3/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests/fixtures *.json *.md

mini_oss_osdk-0.1.0a3/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: mini-oss-osdk
+Version: 0.1.0a3
+Summary: Async Python client and object facade for the ITEM Mini-OSS runtime
+License-Expression: LicenseRef-Proprietary
+Keywords: item,ontology,osdk,object-query
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# Mini-OSS Python OSDK
+
+Async Python builder/runtime for canonical Object Query, Operation polling and bounded Result Gateway access. `0.1.0a3` adds a unified high-level facade while retaining the low-level `ObjectEngineClient` and `ResultGatewayClient` APIs. Production and isolated Preview Staging API Key lanes have passed page, lookup iterator and high-level `get()` verification.
+
+The public PyPI release lane is being prepared as distribution `mini-oss-osdk` with import `mini_oss_osdk`, but it is not published yet. A package name remains unreserved until the first successful registry upload.
+
+## High-level object lookup
+
+```python
+from mini_oss_osdk import OSDKClient
+
+async with OSDKClient(
+    tenant_id="01jabcdefgh1",
+    object_engine_url="https://object-engine.example.com",
+    result_gateway_url="https://object-results.example.com",
+    api_key=tenant_api_key,
+) as client:
+    restaurant = await client.ontology.objects.object(
+        "01jabcdefgh2", "Restaurant"
+    ).get(
+        "restaurant-001",
+        select=("name", "city"),
+    )
+
+    if restaurant is not None:
+        print(restaurant.rid, restaurant.primary_key, restaurant["name"])
+```
+
+`get()` only orchestrates canonical lookup → execute → wait → bounded Result page. It never reads Dataset/Redash/Athena metadata or creates SQL. Generic runtime has no Catalog property list, so `select=()` requests identity only; callers list Property API names explicitly. A future generated ontology package may provide that static list.
+
+Both service endpoints are required. HTTPS is mandatory except loopback HTTP used by tests. A local wait timeout does not cancel the server Operation.
+
+Generated ontology-specific classes are not implemented.
+
+## Distribution verification
+
+```bash
+python -m unittest discover -s tests
+python -m ruff check src tests scripts
+python -m build
+python -m twine check dist/*
+python scripts/verify_distribution.py dist
+```
+
+Branch and `main` pipelines only test and build. A `v<version>` tag is the sole public PyPI upload authority, and the tag must exactly match wheel metadata before upload.
+
+## License
+
+Proprietary. Copyright (c) 2026 ITEM. All rights reserved. See [`LICENSE`](LICENSE); public package availability does not grant permission to use, modify, or redistribute the software.

mini_oss_osdk-0.1.0a3/README.md

@@ -0,0 +1,49 @@
+# Mini-OSS Python OSDK
+
+Async Python builder/runtime for canonical Object Query, Operation polling and bounded Result Gateway access. `0.1.0a3` adds a unified high-level facade while retaining the low-level `ObjectEngineClient` and `ResultGatewayClient` APIs. Production and isolated Preview Staging API Key lanes have passed page, lookup iterator and high-level `get()` verification.
+
+The public PyPI release lane is being prepared as distribution `mini-oss-osdk` with import `mini_oss_osdk`, but it is not published yet. A package name remains unreserved until the first successful registry upload.
+
+## High-level object lookup
+
+```python
+from mini_oss_osdk import OSDKClient
+
+async with OSDKClient(
+    tenant_id="01jabcdefgh1",
+    object_engine_url="https://object-engine.example.com",
+    result_gateway_url="https://object-results.example.com",
+    api_key=tenant_api_key,
+) as client:
+    restaurant = await client.ontology.objects.object(
+        "01jabcdefgh2", "Restaurant"
+    ).get(
+        "restaurant-001",
+        select=("name", "city"),
+    )
+
+    if restaurant is not None:
+        print(restaurant.rid, restaurant.primary_key, restaurant["name"])
+```
+
+`get()` only orchestrates canonical lookup → execute → wait → bounded Result page. It never reads Dataset/Redash/Athena metadata or creates SQL. Generic runtime has no Catalog property list, so `select=()` requests identity only; callers list Property API names explicitly. A future generated ontology package may provide that static list.
+
+Both service endpoints are required. HTTPS is mandatory except loopback HTTP used by tests. A local wait timeout does not cancel the server Operation.
+
+Generated ontology-specific classes are not implemented.
+
+## Distribution verification
+
+```bash
+python -m unittest discover -s tests
+python -m ruff check src tests scripts
+python -m build
+python -m twine check dist/*
+python scripts/verify_distribution.py dist
+```
+
+Branch and `main` pipelines only test and build. A `v<version>` tag is the sole public PyPI upload authority, and the tag must exactly match wheel metadata before upload.
+
+## License
+
+Proprietary. Copyright (c) 2026 ITEM. All rights reserved. See [`LICENSE`](LICENSE); public package availability does not grant permission to use, modify, or redistribute the software.

mini_oss_osdk-0.1.0a3/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mini-oss-osdk"
+version = "0.1.0a3"
+requires-python = ">=3.9"
+description = "Async Python client and object facade for the ITEM Mini-OSS runtime"
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+keywords = ["item", "ontology", "osdk", "object-query"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mini_oss_osdk = ["py.typed"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]

mini_oss_osdk-0.1.0a3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mini_oss_osdk-0.1.0a3/src/mini_oss_osdk/__init__.py

@@ -0,0 +1,45 @@
+from .client import (
+    EngineApiError,
+    HttpxTransport,
+    ObjectEngineClient,
+    OperationWaitTimeout,
+    TransportResponse,
+)
+from .facade import (
+    ObjectTypeClient,
+    OntologyClient,
+    OntologyObject,
+    OntologyObjects,
+    OperationExecutionError,
+    OSDKClient,
+    OSDKInvariantError,
+)
+from .operation import Operation, OperationError, OperationStatus
+from .query import Field, Metric, ObjectSet, Query
+from .result import ResultApiError, ResultGatewayClient, ResultPage, ResultRef
+
+__all__ = [
+    "EngineApiError",
+    "Field",
+    "HttpxTransport",
+    "Metric",
+    "OSDKClient",
+    "OSDKInvariantError",
+    "ObjectEngineClient",
+    "ObjectTypeClient",
+    "OntologyClient",
+    "OntologyObject",
+    "OntologyObjects",
+    "ObjectSet",
+    "Operation",
+    "OperationError",
+    "OperationExecutionError",
+    "OperationStatus",
+    "OperationWaitTimeout",
+    "Query",
+    "ResultApiError",
+    "ResultGatewayClient",
+    "ResultPage",
+    "ResultRef",
+    "TransportResponse",
+]

mini_oss_osdk-0.1.0a3/src/mini_oss_osdk/client.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import time
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Mapping, Optional, Protocol, Union
+from urllib.parse import quote, urlsplit
+
+import httpx
+
+from .operation import Operation
+from .query import Query
+
+
+@dataclass(frozen=True)
+class TransportResponse:
+    status_code: int
+    body: Mapping[str, Any]
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+
+class AsyncTransport(Protocol):
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        json_body: Optional[Mapping[str, Any]] = None,
+    ) -> TransportResponse:
+        ...
+
+
+class HttpxTransport:
+    def __init__(self, client: Optional[httpx.AsyncClient] = None) -> None:
+        self._client = client or httpx.AsyncClient()
+        self._owns_client = client is None
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        json_body: Optional[Mapping[str, Any]] = None,
+    ) -> TransportResponse:
+        response = await self._client.request(
+            method,
+            url,
+            headers=dict(headers),
+            json=dict(json_body) if json_body is not None else None,
+        )
+        payload = response.json()
+        if not isinstance(payload, Mapping):
+            raise ValueError("Object Engine response must be a JSON object")
+        return TransportResponse(
+            status_code=response.status_code,
+            body=dict(payload),
+            headers=dict(response.headers),
+        )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+
+class EngineApiError(RuntimeError):
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        retryable: bool,
+        request_id: Optional[str],
+        details: Mapping[str, Any],
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.request_id = request_id
+        self.details = dict(details)
+
+
+class OperationWaitTimeout(TimeoutError):
+    def __init__(self, operation: Operation) -> None:
+        super().__init__(f"timed out waiting for Operation {operation.operation_id}")
+        self.operation = operation
+
+
+QueryInput = Union[Query, Mapping[str, Any]]
+Sleep = Callable[[float], Awaitable[None]]
+Clock = Callable[[], float]
+
+
+class ObjectEngineClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        transport: Optional[AsyncTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        self._base_url = validate_service_base_url(base_url)
+        self._api_key = api_key
+        self._transport = transport or HttpxTransport()
+
+    async def aclose(self) -> None:
+        close = getattr(self._transport, "aclose", None)
+        if close is not None:
+            await close()
+
+    async def execute(
+        self,
+        *,
+        tenant_id: str,
+        namespace_id: str,
+        query: QueryInput,
+        idempotency_key: str,
+    ) -> Operation:
+        if not idempotency_key:
+            raise ValueError("idempotency_key must not be empty")
+        response = await self._request(
+            "POST",
+            self._query_path(tenant_id, namespace_id, ":execute"),
+            json_body=_query_wire(query),
+            extra_headers={"Idempotency-Key": idempotency_key},
+        )
+        return Operation.from_wire(response.body)
+
+    async def get_operation(
+        self,
+        *,
+        tenant_id: str,
+        namespace_id: str,
+        operation_id: str,
+    ) -> Operation:
+        response = await self._request(
+            "GET",
+            self._operation_path(tenant_id, namespace_id, operation_id),
+        )
+        return Operation.from_wire(response.body)
+
+    async def cancel(
+        self,
+        *,
+        tenant_id: str,
+        namespace_id: str,
+        operation_id: str,
+    ) -> Operation:
+        response = await self._request(
+            "POST",
+            self._operation_path(tenant_id, namespace_id, operation_id) + ":cancel",
+        )
+        return Operation.from_wire(response.body)
+
+    async def wait(
+        self,
+        operation: Operation,
+        *,
+        timeout: Optional[float] = None,
+        sleep: Sleep = asyncio.sleep,
+        monotonic: Clock = time.monotonic,
+    ) -> Operation:
+        if operation.is_terminal:
+            return operation
+        deadline = monotonic() + timeout if timeout is not None else None
+        current = operation
+        while not current.is_terminal:
+            if deadline is not None and monotonic() >= deadline:
+                raise OperationWaitTimeout(current)
+            delay = (current.next_poll_after_ms or 1000) / 1000.0
+            if deadline is not None:
+                delay = min(delay, max(0.0, deadline - monotonic()))
+            await sleep(delay)
+            if deadline is not None and monotonic() >= deadline:
+                raise OperationWaitTimeout(current)
+            current = await self.get_operation(
+                tenant_id=current.tenant_id,
+                namespace_id=current.namespace_id,
+                operation_id=current.operation_id,
+            )
+        return current
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Mapping[str, Any]] = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ) -> TransportResponse:
+        headers = {
+            "Accept": "application/json",
+            "X-API-Key": self._api_key,
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+        response = await self._transport.request(
+            method,
+            self._base_url + path,
+            headers=headers,
+            json_body=json_body,
+        )
+        if response.status_code >= 400:
+            payload = response.body
+            raise EngineApiError(
+                status_code=response.status_code,
+                code=str(payload.get("code", "ENGINE_HTTP_ERROR")),
+                message=str(payload.get("message", "Object Engine request failed")),
+                retryable=bool(payload.get("retryable", False)),
+                request_id=(
+                    str(payload["requestId"])
+                    if payload.get("requestId") is not None
+                    else None
+                ),
+                details=(
+                    dict(payload["details"])
+                    if isinstance(payload.get("details"), Mapping)
+                    else {}
+                ),
+            )
+        return response
+
+    @staticmethod
+    def _query_path(tenant_id: str, namespace_id: str, action: str) -> str:
+        return (
+            f"/v1/tenants/{quote(tenant_id, safe='')}/namespaces/"
+            f"{quote(namespace_id, safe='')}/queries{action}"
+        )
+
+    @staticmethod
+    def _operation_path(tenant_id: str, namespace_id: str, operation_id: str) -> str:
+        return (
+            f"/v1/tenants/{quote(tenant_id, safe='')}/namespaces/"
+            f"{quote(namespace_id, safe='')}/operations/"
+            f"{quote(operation_id, safe='')}"
+        )
+
+
+def validate_service_base_url(base_url: str) -> str:
+    if not base_url:
+        raise ValueError("service base URL must not be empty")
+    parsed = urlsplit(base_url)
+    try:
+        parsed.port
+    except ValueError as error:
+        raise ValueError("service base URL has an invalid port") from error
+    if (
+        not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            "service base URL must be absolute and omit credentials, query and fragment"
+        )
+    if parsed.scheme != "https" and not (
+        parsed.scheme == "http" and _is_loopback_host(parsed.hostname)
+    ):
+        raise ValueError(
+            "service base URL must use HTTPS; HTTP is only allowed for loopback tests"
+        )
+    return base_url.rstrip("/")
+
+
+def _is_loopback_host(host: str) -> bool:
+    if host.lower() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _query_wire(query: QueryInput) -> Mapping[str, Any]:
+    if isinstance(query, Query):
+        return query.to_wire()
+    return dict(query)