osva-sdk 1.0.0__py3-none-any.whl

osva/__init__.py

@@ -0,0 +1,6 @@
+"""Official OSVA SDK for Python."""
+
+from osva.client import OSVAClient
+from osva.errors import OSVAAPIError, OSVATransportError
+
+__all__ = ["OSVAClient", "OSVAAPIError", "OSVATransportError"]

osva/client.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from osva.http_client import HTTPClient
+from osva.resources.agents import AgentsResource
+from osva.resources.approvals import ApprovalsResource
+from osva.resources.artifacts import ArtifactsResource
+from osva.resources.office import (
+    AssignmentsResource,
+    GoalsResource,
+    OfficeWorkersResource,
+    RolesResource,
+    TeamsResource,
+)
+from osva.resources.runs import RunsResource
+from osva.resources.schedules import SchedulesResource
+from osva.resources.workflow_runs import WorkflowRunsResource
+from osva.resources.workflows import WorkflowsResource
+
+
+class OSVAClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout_seconds: float = 30.0,
+        client: HTTPClient | None = None,
+    ) -> None:
+        self._http = client or HTTPClient(
+            base_url,
+            api_key=api_key,
+            timeout_seconds=timeout_seconds,
+        )
+        self.agents = AgentsResource(self._http)
+        self.runs = RunsResource(self._http)
+        self.workflows = WorkflowsResource(self._http)
+        self.workflow_runs = WorkflowRunsResource(self._http)
+        self.approvals = ApprovalsResource(self._http)
+        self.schedules = SchedulesResource(self._http)
+        self.artifacts = ArtifactsResource(self._http)
+        self.office_workers = OfficeWorkersResource(self._http)
+        self.roles = RolesResource(self._http)
+        self.teams = TeamsResource(self._http)
+        self.goals = GoalsResource(self._http)
+        self.assignments = AssignmentsResource(self._http)

osva/errors.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class OSVAAPIError(Exception):
+    def __init__(self, status: int, body: dict[str, Any]) -> None:
+        domain = body.get("status", "error")
+        super().__init__(f"OSVA API request failed with HTTP {status} ({domain}).")
+        self.status = status
+        self.body = body
+
+
+class OSVATransportError(Exception):
+    pass

osva/http_client.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from osva.errors import OSVAAPIError, OSVATransportError
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str,
+        timeout_seconds: float = 30.0,
+        client: httpx.Client | None = None,
+    ) -> None:
+        normalized = base_url.strip().rstrip("/")
+        if not normalized:
+            raise ValueError("base_url must not be empty.")
+        trimmed_key = api_key.strip()
+        if not trimmed_key:
+            raise ValueError("api_key must not be empty.")
+        self._base_url = normalized
+        self._timeout = timeout_seconds
+        self._api_key = trimmed_key
+        self._client = client or httpx.Client(timeout=timeout_seconds)
+
+    def _auth_headers(self, headers: dict[str, str] | None = None) -> dict[str, str]:
+        merged = dict(headers or {})
+        merged.setdefault("authorization", f"Bearer {self._api_key}")
+        return merged
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: dict[str, str | None] | None = None,
+        body: Any | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        params = {key: value for key, value in (query or {}).items() if value is not None}
+        url = f"{self._base_url}{path if path.startswith('/') else f'/{path}'}"
+        request_headers = self._auth_headers(headers)
+        if body is not None:
+            request_headers = {**request_headers, "content-type": "application/json"}
+        try:
+            response = self._client.request(
+                method,
+                url,
+                params=params,
+                json=body,
+                headers=request_headers,
+            )
+        except httpx.HTTPError as error:
+            raise OSVATransportError("OSVA API transport failed.") from error
+
+        try:
+            payload = response.json()
+        except json.JSONDecodeError as error:
+            raise OSVATransportError("OSVA API returned a non-JSON response.") from error
+
+        if response.status_code >= 400:
+            if isinstance(payload, dict) and isinstance(payload.get("status"), str):
+                body_dict = payload
+            else:
+                body_dict = {"status": "error"}
+            raise OSVAAPIError(response.status_code, body_dict)
+
+        if not isinstance(payload, dict):
+            raise OSVATransportError("OSVA API returned an unexpected response shape.")
+        return payload
+
+    def upload_multipart(
+        self,
+        path: str,
+        *,
+        data: dict[str, str],
+        files: dict[str, tuple[str, bytes, str | None]],
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self._base_url}{path if path.startswith('/') else f'/{path}'}"
+        try:
+            response = self._client.post(
+                url,
+                data=data,
+                files=files,
+                headers=self._auth_headers(headers),
+            )
+        except httpx.HTTPError as error:
+            raise OSVATransportError("OSVA API transport failed.") from error
+
+        try:
+            payload = response.json()
+        except json.JSONDecodeError as error:
+            raise OSVATransportError("OSVA API returned a non-JSON response.") from error
+
+        if response.status_code >= 400:
+            if isinstance(payload, dict) and isinstance(payload.get("status"), str):
+                body_dict = payload
+            else:
+                body_dict = {"status": "error"}
+            raise OSVAAPIError(response.status_code, body_dict)
+
+        if not isinstance(payload, dict):
+            raise OSVATransportError("OSVA API returned an unexpected response shape.")
+        return payload
+
+    def download(
+        self,
+        path: str,
+        *,
+        query: dict[str, str | None] | None = None,
+    ) -> httpx.Response:
+        params = {key: value for key, value in (query or {}).items() if value is not None}
+        url = f"{self._base_url}{path if path.startswith('/') else f'/{path}'}"
+        try:
+            response = self._client.get(
+                url,
+                params=params,
+                headers=self._auth_headers(),
+            )
+        except httpx.HTTPError as error:
+            raise OSVATransportError("OSVA API transport failed.") from error
+
+        if response.status_code >= 400:
+            try:
+                payload = response.json()
+            except json.JSONDecodeError:
+                payload = {"status": "error"}
+            if isinstance(payload, dict) and isinstance(payload.get("status"), str):
+                body_dict = payload
+            else:
+                body_dict = {"status": "error"}
+            raise OSVAAPIError(response.status_code, body_dict)
+
+        return response

osva/resources/__init__.py

@@ -0,0 +1 @@
+"""Control-plane resource clients."""

osva/resources/agents.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class AgentsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/agents")
+
+    def get(self, agent_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/agents/{agent_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/agents", body=payload)
+
+    def create_version(self, agent_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/v1/agents/{agent_id}/versions",
+            body=payload,
+        )

osva/resources/approvals.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class ApprovalsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def get(self, approval_request_id: str) -> dict[str, Any]:
+        return self._client.request(
+            "GET",
+            f"/v1/approval-requests/{approval_request_id}",
+        )
+
+    def decide(self, approval_request_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/v1/approval-requests/{approval_request_id}/decision",
+            body=payload,
+        )

osva/resources/artifacts.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from osva.http_client import HTTPClient
+
+
+class ArtifactsResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def list(self, **query: str | None) -> dict[str, Any]:
+        return self._http.request("GET", "/v1/artifacts", query=query)
+
+    def get(self, artifact_id: str) -> dict[str, Any]:
+        return self._http.request("GET", f"/v1/artifacts/{artifact_id}")
+
+    def create(
+        self,
+        *,
+        name: str,
+        content: bytes,
+        media_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        expected_digest: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        data: dict[str, str] = {"name": name}
+        if media_type is not None:
+            data["mediaType"] = media_type
+        if metadata is not None:
+            data["metadata"] = __import__("json").dumps(metadata)
+        if expected_digest is not None:
+            data["expectedDigest"] = expected_digest
+        if idempotency_key is not None:
+            data["idempotencyKey"] = idempotency_key
+
+        files: dict[str, tuple[str, bytes, str | None]] = {
+            "file": (
+                name,
+                content,
+                media_type or "application/octet-stream",
+            )
+        }
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key is not None else None
+        return self._http.upload_multipart(
+            "/v1/artifacts",
+            data=data,
+            files=files,
+            headers=headers,
+        )
+
+    def download(self, artifact_id: str) -> httpx.Response:
+        return self._http.download(f"/v1/artifacts/{artifact_id}/content")

osva/resources/office.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class OfficeWorkersResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/office/workers")
+
+    def get(self, office_worker_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/office-workers/{office_worker_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/office-workers", body=payload)
+
+    def update(self, office_worker_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request(
+            "PATCH",
+            f"/v1/office-workers/{office_worker_id}",
+            body=payload,
+        )
+
+
+class RolesResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/office/roles")
+
+    def get(self, role_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/roles/{role_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/roles", body=payload)
+
+    def update(self, role_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("PATCH", f"/v1/roles/{role_id}", body=payload)
+
+
+class TeamsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/office/teams")
+
+    def get(self, team_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/teams/{team_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/teams", body=payload)
+
+    def update(self, team_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("PATCH", f"/v1/teams/{team_id}", body=payload)
+
+    def list_memberships(self, team_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/teams/{team_id}/memberships")
+
+    def add_membership(self, team_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/v1/teams/{team_id}/memberships",
+            body=payload,
+        )
+
+
+class GoalsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/office/goals")
+
+    def get(self, goal_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/goals/{goal_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/goals", body=payload)
+
+    def update(self, goal_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("PATCH", f"/v1/goals/{goal_id}", body=payload)
+
+
+class AssignmentsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/office/assignments")
+
+    def get(self, assignment_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/assignments/{assignment_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/assignments", body=payload)
+
+    def update(self, assignment_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request(
+            "PATCH",
+            f"/v1/assignments/{assignment_id}",
+            body=payload,
+        )
+
+    def launch(self, assignment_id: str) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/v1/assignments/{assignment_id}/launch",
+        )
+
+    def cancel(self, assignment_id: str) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/v1/assignments/{assignment_id}/cancel",
+        )

osva/resources/runs.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class RunsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self, **query: str | None) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/runs", query=query)
+
+    def get(self, run_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/runs/{run_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/runs", body=payload)

osva/resources/schedules.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class SchedulesResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self, **query: str | None) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/schedules", query=query)
+
+    def get(self, schedule_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/schedules/{schedule_id}")

osva/resources/workflow_runs.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class WorkflowRunsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/workflow-runs", body=payload)
+
+    def get(self, workflow_run_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/workflow-runs/{workflow_run_id}")

osva/resources/workflows.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from osva.http_client import HTTPClient
+
+
+class WorkflowsResource:
+    def __init__(self, client: HTTPClient) -> None:
+        self._client = client
+
+    def list(self) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/workflows")
+
+    def get(self, workflow_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/workflows/{workflow_id}")
+
+    def create(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/workflows", body=payload)
+
+    def create_version(self, workflow_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request(
+            "POST",
+            f"/v1/workflows/{workflow_id}/versions",
+            body=payload,
+        )

osva/runtime/__init__.py

@@ -0,0 +1,5 @@
+"""Runtime Protocol V1 helpers for REMOTE_HTTP agents."""
+
+from osva.runtime.runtime import Runtime
+
+__all__ = ["Runtime"]

osva/runtime/context.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from osva.runtime.credential import CapabilityCredential
+from osva.runtime.errors import RuntimeCapabilityError
+
+PROTOCOL_VERSION = "1"
+GENERATE_TEXT_PATH = "/v1/runtime/capabilities/models/generate-text"
+INVOKE_TOOL_PATH = "/v1/runtime/capabilities/tools/invoke"
+KNOWLEDGE_SEARCH_PATH = "/v1/runtime/capabilities/knowledge/search"
+ARTIFACT_GET_PATH = "/v1/runtime/capabilities/artifacts/get"
+ARTIFACT_CREATE_PATH = "/v1/runtime/capabilities/artifacts/create"
+ARTIFACT_CONTENT_PATH = "/v1/runtime/capabilities/artifacts/content"
+
+
+class ModelsCapability:
+    def __init__(
+        self,
+        *,
+        execution_id: str,
+        credential: CapabilityCredential,
+        client: httpx.AsyncClient,
+    ) -> None:
+        self._execution_id = execution_id
+        self._credential = credential
+        self._client = client
+
+    async def generate_text(
+        self,
+        *,
+        binding: str,
+        messages: list[dict[str, str]],
+        max_output_tokens: int | None = None,
+    ) -> dict[str, str]:
+        payload: dict[str, Any] = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "executionId": self._execution_id,
+            "bindingName": binding,
+            "input": {"messages": messages},
+        }
+        if max_output_tokens is not None:
+            payload["input"]["maxOutputTokens"] = max_output_tokens
+        response = await self._post(GENERATE_TEXT_PATH, payload)
+        if response.get("outcome") != "SUCCEEDED":
+            error = response.get("error", {})
+            raise RuntimeCapabilityError(str(error.get("message", "Model capability failed.")))
+        result = response.get("result")
+        if not isinstance(result, dict) or not isinstance(result.get("text"), str):
+            raise RuntimeCapabilityError("Invalid model capability response.")
+        return {"text": result["text"]}
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                f"{self._credential.endpoint}{path}",
+                json=payload,
+                headers={
+                    "authorization": self._credential.authorization_header(),
+                    "content-type": "application/json",
+                    "accept": "application/json",
+                },
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeCapabilityError("Capability transport failed.") from error
+        data = response.json()
+        if not isinstance(data, dict):
+            raise RuntimeCapabilityError("Capability response was not an object.")
+        if data.get("executionId") != self._execution_id:
+            raise RuntimeCapabilityError("Capability response executionId mismatch.")
+        return data
+
+
+class ToolsCapability:
+    def __init__(
+        self,
+        *,
+        execution_id: str,
+        credential: CapabilityCredential,
+        client: httpx.AsyncClient,
+    ) -> None:
+        self._execution_id = execution_id
+        self._credential = credential
+        self._client = client
+
+    async def invoke(
+        self,
+        *,
+        binding: str,
+        input: Any,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        payload: dict[str, Any] = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "executionId": self._execution_id,
+            "bindingName": binding,
+            "input": input,
+        }
+        if idempotency_key is not None:
+            payload["idempotencyKey"] = idempotency_key
+        response = await self._post(INVOKE_TOOL_PATH, payload)
+        if response.get("outcome") != "SUCCEEDED":
+            error = response.get("error", {})
+            raise RuntimeCapabilityError(str(error.get("message", "Tool capability failed.")))
+        return response.get("output")
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                f"{self._credential.endpoint}{path}",
+                json=payload,
+                headers={
+                    "authorization": self._credential.authorization_header(),
+                    "content-type": "application/json",
+                    "accept": "application/json",
+                },
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeCapabilityError("Capability transport failed.") from error
+        data = response.json()
+        if not isinstance(data, dict):
+            raise RuntimeCapabilityError("Capability response was not an object.")
+        if data.get("executionId") != self._execution_id:
+            raise RuntimeCapabilityError("Capability response executionId mismatch.")
+        return data
+
+
+class ArtifactsCapability:
+    def __init__(
+        self,
+        *,
+        execution_id: str,
+        credential: CapabilityCredential,
+        client: httpx.AsyncClient,
+    ) -> None:
+        self._execution_id = execution_id
+        self._credential = credential
+        self._client = client
+
+    async def get(self, *, artifact_id: str) -> dict[str, Any]:
+        payload = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "executionId": self._execution_id,
+            "artifactId": artifact_id,
+        }
+        response = await self._post_json(ARTIFACT_GET_PATH, payload)
+        if response.get("outcome") != "SUCCEEDED":
+            error = response.get("error", {})
+            raise RuntimeCapabilityError(str(error.get("message", "Artifact get failed.")))
+        artifact = response.get("artifact")
+        if not isinstance(artifact, dict):
+            raise RuntimeCapabilityError("Invalid artifact capability response.")
+        return artifact
+
+    async def create(
+        self,
+        *,
+        name: str,
+        content: bytes,
+        media_type: str | None = None,
+    ) -> dict[str, Any]:
+        files = {"file": (name, content, media_type or "application/octet-stream")}
+        data = {
+            "executionId": self._execution_id,
+            "name": name,
+        }
+        if media_type is not None:
+            data["mediaType"] = media_type
+        try:
+            response = await self._client.post(
+                f"{self._credential.endpoint}{ARTIFACT_CREATE_PATH}",
+                data=data,
+                files=files,
+                headers={
+                    "authorization": self._credential.authorization_header(),
+                    "accept": "application/json",
+                },
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeCapabilityError("Capability transport failed.") from error
+        body = response.json()
+        if not isinstance(body, dict):
+            raise RuntimeCapabilityError("Capability response was not an object.")
+        if body.get("outcome") != "SUCCEEDED":
+            capability_error = body.get("error", {})
+            if not isinstance(capability_error, dict):
+                capability_error = {}
+            raise RuntimeCapabilityError(
+                str(capability_error.get("message", "Artifact create failed."))
+            )
+        artifact = body.get("artifact")
+        if not isinstance(artifact, dict):
+            raise RuntimeCapabilityError("Invalid artifact capability response.")
+        return artifact
+
+    async def open(self, *, artifact_id: str) -> httpx.Response:
+        url = (
+            f"{self._credential.endpoint}{ARTIFACT_CONTENT_PATH}"
+            f"?executionId={self._execution_id}&artifactId={artifact_id}"
+        )
+        try:
+            return await self._client.get(
+                url,
+                headers={"authorization": self._credential.authorization_header()},
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeCapabilityError("Capability transport failed.") from error
+
+    async def _post_json(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                f"{self._credential.endpoint}{path}",
+                json=payload,
+                headers={
+                    "authorization": self._credential.authorization_header(),
+                    "content-type": "application/json",
+                    "accept": "application/json",
+                },
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeCapabilityError("Capability transport failed.") from error
+        data = response.json()
+        if not isinstance(data, dict):
+            raise RuntimeCapabilityError("Capability response was not an object.")
+        if data.get("executionId") != self._execution_id:
+            raise RuntimeCapabilityError("Capability response executionId mismatch.")
+        return data
+
+
+class KnowledgeCapability:
+    def __init__(
+        self,
+        *,
+        execution_id: str,
+        credential: CapabilityCredential,
+        client: httpx.AsyncClient,
+    ) -> None:
+        self._execution_id = execution_id
+        self._credential = credential
+        self._client = client
+
+    async def search(
+        self,
+        *,
+        binding: str,
+        query: str,
+        top_k: int | None = None,
+        filter: dict[str, object] | None = None,
+    ) -> list[dict[str, object]]:
+        payload: dict[str, Any] = {
+            "protocolVersion": PROTOCOL_VERSION,
+            "executionId": self._execution_id,
+            "bindingName": binding,
+            "query": query,
+        }
+        if top_k is not None:
+            payload["topK"] = top_k
+        if filter is not None:
+            payload["filter"] = filter
+        response = await self._post(KNOWLEDGE_SEARCH_PATH, payload)
+        if response.get("outcome") != "SUCCEEDED":
+            error = response.get("error", {})
+            raise RuntimeCapabilityError(
+                str(error.get("message", "Knowledge search failed.")),
+            )
+        hits = response.get("hits")
+        if not isinstance(hits, list):
+            raise RuntimeCapabilityError("Invalid knowledge capability response.")
+        return hits
+
+    async def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                f"{self._credential.endpoint}{path}",
+                json=payload,
+                headers={
+                    "authorization": self._credential.authorization_header(),
+                    "content-type": "application/json",
+                    "accept": "application/json",
+                },
+            )
+        except httpx.HTTPError as error:
+            raise RuntimeCapabilityError("Capability transport failed.") from error
+        data = response.json()
+        if not isinstance(data, dict):
+            raise RuntimeCapabilityError("Capability response was not an object.")
+        if data.get("executionId") != self._execution_id:
+            raise RuntimeCapabilityError("Capability response executionId mismatch.")
+        return data
+
+
+class RuntimeContext:
+    def __init__(
+        self,
+        *,
+        execution_id: str,
+        credential: CapabilityCredential,
+        client: httpx.AsyncClient,
+    ) -> None:
+        self.execution_id = execution_id
+        self.models = ModelsCapability(
+            execution_id=execution_id,
+            credential=credential,
+            client=client,
+        )
+        self.tools = ToolsCapability(
+            execution_id=execution_id,
+            credential=credential,
+            client=client,
+        )
+        self.artifacts = ArtifactsCapability(
+            execution_id=execution_id,
+            credential=credential,
+            client=client,
+        )
+        self.knowledge = KnowledgeCapability(
+            execution_id=execution_id,
+            credential=credential,
+            client=client,
+        )

osva/runtime/credential.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+
+class CapabilityCredential:
+    def __init__(self, endpoint: str, token: str) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self._token = token
+
+    def authorization_header(self) -> str:
+        return f"Bearer {self._token}"
+
+    def __repr__(self) -> str:
+        return f"CapabilityCredential({self.endpoint!r})"
+
+    def to_json(self) -> dict[str, str]:
+        return {"endpoint": self.endpoint, "token": "[REDACTED]"}

osva/runtime/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class RuntimeExecutionError(Exception):
+    def __init__(self, message: str, code: str = "AGENT_EXECUTION_FAILED") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class RuntimeCapabilityError(Exception):
+    pass
+
+
+class RuntimeProtocolError(Exception):
+    def __init__(self, message: str, code: str = "RUNTIME_PROTOCOL_FAILURE") -> None:
+        super().__init__(message)
+        self.code = code

osva/runtime/runtime.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import httpx
+
+from osva.runtime.context import RuntimeContext
+from osva.runtime.credential import CapabilityCredential
+from osva.runtime.errors import RuntimeExecutionError, RuntimeProtocolError
+
+PROTOCOL_VERSION = "1"
+MAX_BODY_BYTES = 1_048_576
+
+
+ExecuteFn = Callable[[Any, RuntimeContext], Awaitable[Any]]
+
+
+class Runtime:
+    def __init__(self) -> None:
+        self._execute_fn: ExecuteFn | None = None
+
+    def execute(self, fn: ExecuteFn) -> ExecuteFn:
+        self._execute_fn = fn
+        return fn
+
+    async def handle_execute_request(self, body: dict[str, Any]) -> dict[str, Any]:
+        if body.get("protocolVersion") != PROTOCOL_VERSION:
+            raise RuntimeProtocolError(
+                f"Unsupported protocol version: {body.get('protocolVersion')!r}."
+            )
+
+        required = ("executionId", "input", "capabilities")
+        if any(key not in body for key in required):
+            raise RuntimeProtocolError("Invalid Runtime Protocol V1 execute request.")
+
+        execution_id = str(body["executionId"])
+        capabilities = body["capabilities"]
+        if not isinstance(capabilities, dict):
+            raise RuntimeProtocolError("Invalid capability credential in execute request.")
+
+        endpoint = capabilities.get("endpoint")
+        token = capabilities.get("token")
+        if not isinstance(endpoint, str) or not isinstance(token, str):
+            raise RuntimeProtocolError("Invalid capability credential in execute request.")
+
+        if self._execute_fn is None:
+            raise RuntimeProtocolError("Runtime execute handler is not configured.")
+
+        credential = CapabilityCredential(endpoint, token)
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            context = RuntimeContext(
+                execution_id=execution_id,
+                credential=credential,
+                client=client,
+            )
+            try:
+                output = await self._execute_fn(body["input"], context)
+                return {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "executionId": execution_id,
+                    "outcome": "SUCCEEDED",
+                    "output": output,
+                }
+            except RuntimeExecutionError as error:
+                return {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "executionId": execution_id,
+                    "outcome": "FAILED",
+                    "error": {"code": error.code, "message": str(error)[:500]},
+                }
+            except Exception as error:  # noqa: BLE001
+                return {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "executionId": execution_id,
+                    "outcome": "FAILED",
+                    "error": {
+                        "code": "AGENT_EXECUTION_FAILED",
+                        "message": str(error)[:500] or "Agent execution failed.",
+                    },
+                }
+
+    def asgi_app(self, path: str = "/execute") -> Callable[..., Awaitable[None]]:
+        async def app(scope: dict[str, Any], receive: Any, send: Any) -> None:
+            if scope.get("type") != "http":
+                await send({"type": "http.response.start", "status": 400, "headers": []})
+                await send({"type": "http.response.body", "body": b""})
+                return
+
+            request_path = scope.get("path", "")
+            method = scope.get("method", "GET")
+            if method != "POST" or request_path != path:
+                await _send_json(send, 404, _protocol_failure("Not found."))
+                return
+
+            body_bytes = b""
+            while True:
+                message = await receive()
+                if message["type"] != "http.request":
+                    continue
+                body_bytes += message.get("body", b"")
+                if len(body_bytes) > MAX_BODY_BYTES:
+                    await _send_json(
+                        send, 413, _protocol_failure("Request body exceeds maximum size.")
+                    )
+                    return
+                if not message.get("more_body", False):
+                    break
+
+            try:
+                parsed = json.loads(body_bytes.decode("utf-8"))
+            except json.JSONDecodeError:
+                await _send_json(send, 400, _protocol_failure("Request body must be valid JSON."))
+                return
+
+            if not isinstance(parsed, dict):
+                await _send_json(
+                    send, 400, _protocol_failure("Request body must be a JSON object.")
+                )
+                return
+
+            try:
+                result = await self.handle_execute_request(parsed)
+            except RuntimeProtocolError as error:
+                await _send_json(
+                    send,
+                    400,
+                    {
+                        "protocolVersion": PROTOCOL_VERSION,
+                        "outcome": "FAILED",
+                        "error": {"code": error.code, "message": str(error)},
+                    },
+                )
+                return
+
+            await _send_json(send, 200, result)
+
+        return app
+
+
+async def _send_json(send: Any, status: int, payload: dict[str, Any]) -> None:
+    body = json.dumps(payload).encode("utf-8")
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", b"application/json; charset=utf-8"),
+                (b"content-length", str(len(body)).encode("ascii")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+
+
+def _protocol_failure(message: str) -> dict[str, Any]:
+    return {
+        "protocolVersion": PROTOCOL_VERSION,
+        "outcome": "FAILED",
+        "error": {"code": "RUNTIME_PROTOCOL_FAILURE", "message": message},
+    }

osva_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: osva-sdk
+Version: 1.0.0
+Summary: Official OSVA SDK for Python
+Project-URL: Homepage, https://github.com/Osva-AI/osva
+Project-URL: Repository, https://github.com/Osva-AI/osva
+Project-URL: Documentation, https://github.com/Osva-AI/osva/blob/main/docs/OSS-1.0-QUICKSTART.md
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# osva-sdk
+
+Official OSVA SDK for Python (>=3.11).
+
+The package is publish-ready but not yet published to PyPI.

osva_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+osva/__init__.py,sha256=Y--tLLPYcvM_on4Hd0CnE7QIJ8y8CfADsB4ZNAwHtnU,193
+osva/client.py,sha256=1A19cAVGzbSwlfjR76fRRBmD1Vs3pwwIy5HAcTWUZdM,1592
+osva/errors.py,sha256=Y307QGbAWJ-QWTFFprSC8KpzuV8IeXcs0Abz91EE9v0,390
+osva/http_client.py,sha256=9EfeANBEbMolSRuim2iqxgpGmIiGC9NL73fcGSdqix0,4880
+osva/resources/__init__.py,sha256=WLGHEK54aeJqjJToThn6fi-BJbdMShp9KcZGOpGTlNQ,38
+osva/resources/agents.py,sha256=8IIU8wGmAXsJSxVVzejGy_mr49k390Z8tSznCI_EC_c,791
+osva/resources/approvals.py,sha256=fOaCxCUkebX4GgmR6dALt_Fx91nwILstRS2bRErNv0o,653
+osva/resources/artifacts.py,sha256=zroDZiMdKQeLFfe9smLJsvWjUBu9lbURw1iPqgQLbIY,1775
+osva/resources/office.py,sha256=7bZ_phdZvrizwt54lRm5H7AEEG8Ox7Ke4witrdYcXqc,4190
+osva/resources/runs.py,sha256=3wtpvTzVrJuNklCcUxSHxiv-iEVgxM-V1dQOLJsPAcE,584
+osva/resources/schedules.py,sha256=sg9R4kVwvtjKSCssX7794LkUZiVcJ4fMOiCOLGcH_oQ,473
+osva/resources/workflow_runs.py,sha256=a7okJ9pGSZEZoN4dQyIYKuvLPkiwvznWVg2V8Qc-Lek,500
+osva/resources/workflows.py,sha256=-4BGIwCqwkvdoStWnq2Jv03Y3adNpHMhvZ5z7T8DqmI,818
+osva/runtime/__init__.py,sha256=6qBNiytFGTGoIbxkS4p-kSZl1x7WXiSjzEw9bJrgbJk,123
+osva/runtime/context.py,sha256=CTzLY7WhlX-UheZ-Q-psdUj7UItU3wYqy7FApjK7MIM,11878
+osva/runtime/credential.py,sha256=sRHfFxtGqYQgLKI6NM7T5MqD5fNme3t6sEuKzlIR9jA,478
+osva/runtime/errors.py,sha256=0W_k2PXZ4Ymb-pqEK0pe3C7XnwB2--hKoJ9zkkbaiBA,458
+osva/runtime/runtime.py,sha256=Xg0rwpza-63WPkQyf2O56bMgdw6Yji2aLoLi9fRNI94,6001
+osva_sdk-1.0.0.dist-info/METADATA,sha256=x8D-n-F7MC4E6_up5mqtSx8snnid5TVtQxpb3stWcY8,774
+osva_sdk-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+osva_sdk-1.0.0.dist-info/RECORD,,

osva_sdk-1.0.0.dist-info/WHEEL

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