ogx-api 1.1.2__tar.gz → 1.2.0__tar.gz

{ogx_api-1.1.2 → ogx_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ogx-api
-Version: 1.1.2
+Version: 1.2.0
 Summary: API and Provider specifications for OGX - lightweight package with protocol definitions and provider specs
 Author-email: The OGX Contributors <contributors@ogx.dev>
 License: MIT
@@ -15,12 +15,12 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: openai>=2.41.0
+Requires-Dist: openai>=2.43.0
 Requires-Dist: fastapi<1.0,>=0.136.3
 Requires-Dist: pydantic>=2.11.9
 Requires-Dist: jsonschema>=4.26.0
-Requires-Dist: opentelemetry-sdk>=1.42.1
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.42.1
+Requires-Dist: opentelemetry-sdk>=1.43.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.43.0
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.42.1
 
 # ogx-api

{ogx_api-1.1.2 → ogx_api-1.2.0}/__init__.py

@@ -64,6 +64,7 @@ from .responses import (
     DeleteResponseRequest,
     ListResponseInputItemsRequest,
     ListResponsesRequest,
+    MemoryToolConfig,
     ResponseItemInclude,
     ResponseTruncation,
     ResponseStreamOptions,
@@ -130,6 +131,44 @@ from .connectors import (
     GetConnectorToolRequest,
     ListConnectorToolsRequest,
 )
+from .containers import (
+    Container,
+    ContainerCreateRequest,
+    ContainerDeleteResponse,
+    ContainerExpiresAfter,
+    ContainerFile,
+    ContainerFileDeleteResponse,
+    ContainerFileSource,
+    ContainerRuntime,
+    Containers,
+    ContainerStatus,
+    DeleteContainerFileRequest,
+    DeleteContainerRequest,
+    ExecuteShellRequest,
+    GetContainerFileContentRequest,
+    GetContainerFileRequest,
+    GetContainerRequest,
+    ListContainerFilesRequest,
+    ListContainerFilesResponse,
+    ListContainersRequest,
+    ListContainersResponse,
+    MountSkillsRequest,
+    NetworkCredential,
+    NetworkDomainCredential,
+    NetworkPolicy,
+    NetworkPolicyExtended,
+    NetworkPolicyMode,
+    ShellCallOutput,
+    ShellEnvironment,
+    ShellEnvironmentContainerAuto,
+    ShellEnvironmentContainerReference,
+    ShellEnvironmentLocal,
+    ShellOutcome,
+    ShellOutcomeFailure,
+    ShellOutcomeSuccess,
+    ShellOutcomeTimeout,
+    UploadContainerFileRequest,
+)
 from .conversations import (
     AddItemsRequest,
     Conversation,
@@ -550,6 +589,7 @@ __all__ = [
     "DeleteResponseRequest",
     "ListResponseInputItemsRequest",
     "ListResponsesRequest",
+    "MemoryToolConfig",
     "RetrieveResponseRequest",
     "AllowedToolsFilter",
     "Api",
@@ -587,6 +627,42 @@ __all__ = [
     "ConnectorInput",
     "Connectors",
     "ConnectorType",
+    "Container",
+    "ContainerCreateRequest",
+    "ContainerDeleteResponse",
+    "ContainerExpiresAfter",
+    "ContainerFile",
+    "ContainerFileDeleteResponse",
+    "ContainerFileSource",
+    "ContainerRuntime",
+    "Containers",
+    "ContainerStatus",
+    "DeleteContainerFileRequest",
+    "DeleteContainerRequest",
+    "ExecuteShellRequest",
+    "GetContainerFileContentRequest",
+    "GetContainerFileRequest",
+    "GetContainerRequest",
+    "ListContainerFilesRequest",
+    "ListContainerFilesResponse",
+    "ListContainersRequest",
+    "ListContainersResponse",
+    "MountSkillsRequest",
+    "NetworkCredential",
+    "NetworkDomainCredential",
+    "NetworkPolicy",
+    "NetworkPolicyExtended",
+    "NetworkPolicyMode",
+    "ShellCallOutput",
+    "ShellEnvironment",
+    "ShellEnvironmentContainerAuto",
+    "ShellEnvironmentContainerReference",
+    "ShellEnvironmentLocal",
+    "ShellOutcome",
+    "ShellOutcomeFailure",
+    "ShellOutcomeSuccess",
+    "ShellOutcomeTimeout",
+    "UploadContainerFileRequest",
     "AddItemsRequest",
     "Conversation",
     "ConversationDeletedResource",

ogx_api-1.2.0/containers/__init__.py

@@ -0,0 +1,92 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Containers API module.
+
+Provides CRUD over sandboxed execution environments used by the Responses
+``shell`` and ``code_interpreter`` tools. Protocol definitions are in
+``api.py``, Pydantic models in ``models.py``, and FastAPI routes in
+``fastapi_routes.py``.
+"""
+
+from . import fastapi_routes
+from .api import ContainerRuntime, Containers
+from .models import (
+    Container,
+    ContainerCreateRequest,
+    ContainerDeleteResponse,
+    ContainerExpiresAfter,
+    ContainerFile,
+    ContainerFileDeleteResponse,
+    ContainerFileSource,
+    ContainerStatus,
+    DeleteContainerFileRequest,
+    DeleteContainerRequest,
+    ExecuteShellRequest,
+    GetContainerFileContentRequest,
+    GetContainerFileRequest,
+    GetContainerRequest,
+    ListContainerFilesRequest,
+    ListContainerFilesResponse,
+    ListContainersRequest,
+    ListContainersResponse,
+    MountSkillsRequest,
+    NetworkCredential,
+    NetworkDomainCredential,
+    NetworkPolicy,
+    NetworkPolicyExtended,
+    NetworkPolicyMode,
+    ShellCallOutput,
+    ShellEnvironment,
+    ShellEnvironmentContainerAuto,
+    ShellEnvironmentContainerReference,
+    ShellEnvironmentLocal,
+    ShellOutcome,
+    ShellOutcomeFailure,
+    ShellOutcomeSuccess,
+    ShellOutcomeTimeout,
+    UploadContainerFileRequest,
+)
+
+__all__ = [
+    "Container",
+    "ContainerCreateRequest",
+    "ContainerDeleteResponse",
+    "ContainerExpiresAfter",
+    "ContainerFile",
+    "ContainerFileDeleteResponse",
+    "ContainerFileSource",
+    "ContainerRuntime",
+    "ContainerStatus",
+    "Containers",
+    "DeleteContainerFileRequest",
+    "DeleteContainerRequest",
+    "ExecuteShellRequest",
+    "GetContainerFileContentRequest",
+    "GetContainerFileRequest",
+    "GetContainerRequest",
+    "ListContainerFilesRequest",
+    "ListContainerFilesResponse",
+    "ListContainersRequest",
+    "ListContainersResponse",
+    "MountSkillsRequest",
+    "NetworkCredential",
+    "NetworkDomainCredential",
+    "NetworkPolicy",
+    "NetworkPolicyExtended",
+    "NetworkPolicyMode",
+    "ShellCallOutput",
+    "ShellEnvironment",
+    "ShellEnvironmentContainerAuto",
+    "ShellEnvironmentContainerReference",
+    "ShellEnvironmentLocal",
+    "ShellOutcome",
+    "ShellOutcomeFailure",
+    "ShellOutcomeSuccess",
+    "ShellOutcomeTimeout",
+    "UploadContainerFileRequest",
+    "fastapi_routes",
+]

ogx_api-1.2.0/containers/api.py

@@ -0,0 +1,206 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Containers API protocol definitions.
+
+This module contains two protocols:
+
+* ``Containers`` — the HTTP-facing CRUD API for sandboxed execution
+  environments.
+* ``ContainerRuntime`` — the internal provider protocol that backends
+  (Docker/Podman, Kubernetes, local) implement. The Containers provider
+  delegates to a ``ContainerRuntime`` for the actual lifecycle, file, and
+  shell-execution work.
+
+Pydantic models are defined in ``models.py`` and FastAPI routes in
+``fastapi_routes.py``.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from fastapi import Response, UploadFile
+
+from .models import (
+    Container,
+    ContainerCreateRequest,
+    ContainerDeleteResponse,
+    ContainerFile,
+    ContainerFileDeleteResponse,
+    DeleteContainerFileRequest,
+    DeleteContainerRequest,
+    ExecuteShellRequest,
+    GetContainerFileContentRequest,
+    GetContainerFileRequest,
+    GetContainerRequest,
+    ListContainerFilesRequest,
+    ListContainerFilesResponse,
+    ListContainersRequest,
+    ListContainersResponse,
+    MountSkillsRequest,
+    ShellCallOutput,
+    UploadContainerFileRequest,
+)
+
+
+@runtime_checkable
+class Containers(Protocol):
+    """HTTP API for managing sandboxed execution containers.
+
+    Implementations enforce policy layering (request-supplied
+    ``NetworkPolicyExtended`` cannot expand operator defaults) and then
+    delegate to a configured :class:`ContainerRuntime` for backend work.
+    """
+
+    async def create_container(
+        self,
+        request: ContainerCreateRequest,
+    ) -> Container: ...
+
+    async def list_containers(
+        self,
+        request: ListContainersRequest,
+    ) -> ListContainersResponse: ...
+
+    async def get_container(
+        self,
+        request: GetContainerRequest,
+    ) -> Container: ...
+
+    async def delete_container(
+        self,
+        request: DeleteContainerRequest,
+    ) -> ContainerDeleteResponse: ...
+
+    async def upload_container_file(
+        self,
+        request: UploadContainerFileRequest,
+        file: UploadFile,
+    ) -> ContainerFile: ...
+
+    async def list_container_files(
+        self,
+        request: ListContainerFilesRequest,
+    ) -> ListContainerFilesResponse: ...
+
+    async def get_container_file(
+        self,
+        request: GetContainerFileRequest,
+    ) -> ContainerFile: ...
+
+    async def get_container_file_content(
+        self,
+        request: GetContainerFileContentRequest,
+    ) -> Response: ...
+
+    async def delete_container_file(
+        self,
+        request: DeleteContainerFileRequest,
+    ) -> ContainerFileDeleteResponse: ...
+
+
+@runtime_checkable
+class ContainerRuntime(Protocol):
+    """Internal provider protocol for container backends.
+
+    A ``ContainerRuntime`` provider is the thin layer between the Containers
+    API and a concrete backend (Docker/Podman socket, Kubernetes API, local
+    process supervisor). The Responses ``shell`` tool also calls
+    ``execute_shell`` directly when running in ``container_auto`` /
+    ``container_reference`` modes.
+
+    This protocol is not exposed over HTTP.
+    """
+
+    # --- lifecycle -------------------------------------------------------
+
+    async def create_container(
+        self,
+        request: ContainerCreateRequest,
+    ) -> Container:
+        """Create and start a container. Raises if resource limits are exceeded."""
+        ...
+
+    async def get_container(self, request: GetContainerRequest) -> Container:
+        """Fetch the current state of a container, including ``last_active_at``."""
+        ...
+
+    async def list_containers(
+        self,
+        request: ListContainersRequest,
+    ) -> ListContainersResponse:
+        """List containers known to this runtime."""
+        ...
+
+    async def delete_container(self, request: DeleteContainerRequest) -> ContainerDeleteResponse:
+        """Stop and remove a container along with its filesystem."""
+        ...
+
+    # --- file management ------------------------------------------------
+
+    async def upload_file(
+        self,
+        request: UploadContainerFileRequest,
+        file: UploadFile,
+    ) -> ContainerFile:
+        """Copy an uploaded file into the container at the runtime-chosen path."""
+        ...
+
+    async def list_files(
+        self,
+        request: ListContainerFilesRequest,
+    ) -> ListContainerFilesResponse:
+        """List files tracked inside a container."""
+        ...
+
+    async def get_file(
+        self,
+        request: GetContainerFileRequest,
+    ) -> ContainerFile:
+        """Get metadata for a single file inside a container."""
+        ...
+
+    async def get_file_content(
+        self,
+        request: GetContainerFileContentRequest,
+    ) -> Response:
+        """Stream the bytes of a file inside a container."""
+        ...
+
+    async def delete_file(
+        self,
+        request: DeleteContainerFileRequest,
+    ) -> ContainerFileDeleteResponse:
+        """Remove a file from a container's filesystem."""
+        ...
+
+    # --- execution ------------------------------------------------------
+
+    async def execute_shell(
+        self,
+        request: ExecuteShellRequest,
+    ) -> ShellCallOutput:
+        """Run a shell command inside the container and capture its output.
+
+        ``request.command`` is passed as ``argv`` (no shell expansion) to keep
+        the interface uniform across backends. Implementations are expected to
+        update ``last_active_at`` on the container as a side effect.
+        """
+        ...
+
+    # --- skill mounting -------------------------------------------------
+
+    async def mount_skills(
+        self,
+        request: MountSkillsRequest,
+    ) -> None:
+        """Mount skill bundles into ``/mnt/skills/{skill_name}/`` inside the container.
+
+        Each entry of ``request.skill_bundles`` is ``(skill_name, zip_bytes)``
+        — the zip archive is extracted into the named directory. Calling this
+        method multiple times with overlapping names overwrites the previous
+        contents.
+        """
+        ...

ogx_api-1.2.0/containers/fastapi_routes.py

@@ -0,0 +1,205 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""FastAPI routes for the Containers API.
+
+Endpoints are mounted at ``/v1alpha/containers``. See
+:class:`ogx_api.containers.api.Containers` for the protocol implementations
+must satisfy.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, UploadFile
+from fastapi.param_functions import File
+from fastapi.responses import Response
+
+from ogx_api.common.upload_limits import (
+    DEFAULT_MAX_UPLOAD_SIZE_BYTES,
+    PreReadUploadFile,
+    read_upload_with_size_limit,
+)
+from ogx_api.router_utils import create_path_dependency, create_query_dependency, standard_responses
+from ogx_api.version import OGX_API_V1ALPHA
+
+from .api import Containers
+from .models import (
+    Container,
+    ContainerCreateRequest,
+    ContainerDeleteResponse,
+    ContainerFile,
+    ContainerFileDeleteResponse,
+    DeleteContainerFileRequest,
+    DeleteContainerRequest,
+    GetContainerFileContentRequest,
+    GetContainerFileRequest,
+    GetContainerRequest,
+    ListContainerFilesRequest,
+    ListContainerFilesResponse,
+    ListContainersRequest,
+    ListContainersResponse,
+    UploadContainerFileRequest,
+)
+
+get_list_containers_request = create_query_dependency(ListContainersRequest)
+get_container_request = create_path_dependency(GetContainerRequest)
+get_delete_container_request = create_path_dependency(DeleteContainerRequest)
+get_upload_container_file_request = create_path_dependency(UploadContainerFileRequest)
+
+
+# Multi-field path-parameter models cannot use create_path_dependency, which only
+# supports single-field models. The helpers below combine path (+ query) params
+# into the request model explicitly.
+
+
+def _list_container_files_request(
+    container_id: str,
+    after: str | None = None,
+    limit: int | None = 20,
+    order: str | None = "desc",
+) -> ListContainerFilesRequest:
+    return ListContainerFilesRequest.model_validate(
+        {"container_id": container_id, "after": after, "limit": limit, "order": order}
+    )
+
+
+def _get_container_file_request(container_id: str, file_id: str) -> GetContainerFileRequest:
+    return GetContainerFileRequest(container_id=container_id, file_id=file_id)
+
+
+def _get_container_file_content_request(container_id: str, file_id: str) -> GetContainerFileContentRequest:
+    return GetContainerFileContentRequest(container_id=container_id, file_id=file_id)
+
+
+def _delete_container_file_request(container_id: str, file_id: str) -> DeleteContainerFileRequest:
+    return DeleteContainerFileRequest(container_id=container_id, file_id=file_id)
+
+
+def create_router(impl: Containers, max_upload_size_bytes: int = DEFAULT_MAX_UPLOAD_SIZE_BYTES) -> APIRouter:
+    router = APIRouter(
+        prefix=f"/{OGX_API_V1ALPHA}",
+        tags=["Containers"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/containers",
+        response_model=Container,
+        summary="Create container",
+        description="Create a sandboxed container for shell/code execution.",
+        responses={200: {"description": "The created container."}},
+    )
+    async def create_container(request: ContainerCreateRequest) -> Container:
+        return await impl.create_container(request)
+
+    @router.get(
+        "/containers",
+        response_model=ListContainersResponse,
+        summary="List containers",
+        description="List containers.",
+        responses={200: {"description": "The list of containers."}},
+    )
+    async def list_containers(
+        request: Annotated[ListContainersRequest, Depends(get_list_containers_request)],
+    ) -> ListContainersResponse:
+        return await impl.list_containers(request)
+
+    @router.get(
+        "/containers/{container_id}",
+        response_model=Container,
+        summary="Get container",
+        description="Get a container by ID.",
+        responses={200: {"description": "The container."}},
+    )
+    async def get_container(
+        request: Annotated[GetContainerRequest, Depends(get_container_request)],
+    ) -> Container:
+        return await impl.get_container(request)
+
+    @router.delete(
+        "/containers/{container_id}",
+        response_model=ContainerDeleteResponse,
+        summary="Delete container",
+        description="Stop and remove a container.",
+        responses={200: {"description": "The container was deleted."}},
+    )
+    async def delete_container(
+        request: Annotated[DeleteContainerRequest, Depends(get_delete_container_request)],
+    ) -> ContainerDeleteResponse:
+        return await impl.delete_container(request)
+
+    @router.post(
+        "/containers/{container_id}/files",
+        response_model=ContainerFile,
+        summary="Upload container file",
+        description="Upload a file into a container's filesystem.",
+        responses={200: {"description": "The uploaded container file."}},
+    )
+    async def upload_container_file(
+        container_id: str,
+        file: Annotated[UploadFile, File(description="The file to upload into the container.")],
+    ) -> ContainerFile:
+        content = await read_upload_with_size_limit(file, max_upload_size_bytes)
+        safe_file = PreReadUploadFile(content, filename=file.filename, content_type=file.content_type)
+        return await impl.upload_container_file(
+            UploadContainerFileRequest(container_id=container_id),
+            safe_file,
+        )
+
+    @router.get(
+        "/containers/{container_id}/files",
+        response_model=ListContainerFilesResponse,
+        summary="List container files",
+        description="List files inside a container.",
+        responses={200: {"description": "The list of files."}},
+    )
+    async def list_container_files(
+        request: Annotated[ListContainerFilesRequest, Depends(_list_container_files_request)],
+    ) -> ListContainerFilesResponse:
+        return await impl.list_container_files(request)
+
+    @router.get(
+        "/containers/{container_id}/files/{file_id}",
+        response_model=ContainerFile,
+        summary="Get container file",
+        description="Get metadata for a file inside a container.",
+        responses={200: {"description": "The container file metadata."}},
+    )
+    async def get_container_file(
+        request: Annotated[GetContainerFileRequest, Depends(_get_container_file_request)],
+    ) -> ContainerFile:
+        return await impl.get_container_file(request)
+
+    @router.get(
+        "/containers/{container_id}/files/{file_id}/content",
+        status_code=200,
+        summary="Get container file content",
+        description="Download the contents of a file inside a container.",
+        responses={
+            200: {
+                "description": "The file content.",
+                "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}},
+            },
+        },
+    )
+    async def get_container_file_content(
+        request: Annotated[GetContainerFileContentRequest, Depends(_get_container_file_content_request)],
+    ) -> Response:
+        return await impl.get_container_file_content(request)
+
+    @router.delete(
+        "/containers/{container_id}/files/{file_id}",
+        response_model=ContainerFileDeleteResponse,
+        summary="Delete container file",
+        description="Remove a file from a container's filesystem.",
+        responses={200: {"description": "The file was deleted."}},
+    )
+    async def delete_container_file(
+        request: Annotated[DeleteContainerFileRequest, Depends(_delete_container_file_request)],
+    ) -> ContainerFileDeleteResponse:
+        return await impl.delete_container_file(request)
+
+    return router