container-pool 0.1.0__py3-none-any.whl

container_pool/__init__.py

@@ -0,0 +1,51 @@
+"""
+container-pool: Provider-agnostic async container pool with expiry recovery.
+
+Quick start:
+    from container_pool import ContainerPool
+    from container_pool.backends.openai import OpenAIContainerBackend
+
+    backend = OpenAIContainerBackend(openai_client)
+    pool = ContainerPool(backend, max_pool_size=5, acquire_timeout=30.0, container_name="ci")
+
+    container = await pool.acquire()
+    try:
+        uploaded = await container.upload_file("/tmp/data.csv")
+        ...
+    finally:
+        await pool.release(container)
+
+    await pool.shutdown()
+"""
+
+from ._backend import BaseContainerBackend
+from ._container import Container
+from ._exceptions import (
+    ContainerCreationError,
+    ContainerExpiredError,
+    ContainerFileError,
+    ContainerPoolError,
+    ContainerPoolExhaustedError,
+)
+from ._pool import ContainerPool
+from ._tracker import RequestFileTracker
+from ._types import ContainerInfo, ContainerStatus, UploadedFile
+
+__all__ = [
+    # Core
+    "ContainerPool",
+    "Container",
+    "RequestFileTracker",
+    # ABC
+    "BaseContainerBackend",
+    # Types
+    "ContainerInfo",
+    "ContainerStatus",
+    "UploadedFile",
+    # Exceptions
+    "ContainerPoolError",
+    "ContainerPoolExhaustedError",
+    "ContainerExpiredError",
+    "ContainerCreationError",
+    "ContainerFileError",
+]

container_pool/_backend.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ._types import ContainerInfo, UploadedFile
+
+
+class BaseContainerBackend(ABC):
+    """
+    Abstract interface every backend must implement.
+
+    All methods are async. Implementations are responsible for:
+    - Translating vendor-specific errors into ContainerExpiredError /
+      ContainerCreationError / ContainerFileError.
+    - Never leaking vendor SDK types through return values.
+    - Best-effort operations (destroy, delete_file) should swallow 404 silently.
+    """
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    @abstractmethod
+    async def create_container(self, name: str) -> ContainerInfo:
+        """
+        Create and activate a new container.
+        Raises ContainerCreationError on failure (after any internal retry).
+        """
+
+    @abstractmethod
+    async def get_container(self, container_id: str) -> ContainerInfo:
+        """
+        Fetch the current status of an existing container.
+        Raises ContainerExpiredError if the container is gone or expired.
+        """
+
+    @abstractmethod
+    async def destroy_container(self, container_id: str) -> None:
+        """
+        Permanently destroy a container.
+        Best-effort: should swallow 404 silently.
+        """
+
+    # -------------------------------------------------------------------------
+    # File operations
+    # -------------------------------------------------------------------------
+
+    @abstractmethod
+    async def upload_file(self, container_id: str, local_path: str) -> UploadedFile:
+        """
+        Upload a local file into the container.
+        Returns an UploadedFile with container_id, file_id, container_path.
+        Raises ContainerFileError on failure.
+        """
+
+    @abstractmethod
+    async def download_file_content(self, container_id: str, file_id: str) -> bytes:
+        """
+        Download a file's raw bytes by file_id.
+        Raises ContainerFileError on failure.
+        """
+
+    @abstractmethod
+    async def download_file_to_disk(
+        self,
+        container_id: str,
+        file_id: str,
+        local_path: str,
+    ) -> int:
+        """
+        Download a file and write it to local_path.
+        Returns the number of bytes written.
+        Raises ContainerFileError on failure.
+        """
+
+    @abstractmethod
+    async def delete_file(self, container_id: str, file_id: str) -> None:
+        """
+        Delete a single file from the container.
+        Best-effort: should swallow 404 silently.
+        """
+
+    @abstractmethod
+    async def list_files(
+        self,
+        container_id: str,
+        path_prefix: str = "",
+    ) -> dict[str, str]:
+        """
+        List files inside the container whose path starts with path_prefix.
+        Returns {filename: file_id}.
+        """

container_pool/_container.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import logging
+import os
+
+from ._backend import BaseContainerBackend
+from ._types import UploadedFile
+
+log = logging.getLogger(__name__)
+
+
+class Container:
+    """
+    A live handle to a single container slot.
+
+    Returned by ContainerPool.acquire(). Callers use this object to
+    upload/download files. They must call pool.release(container) when done.
+
+    Container does not manage expiry or recreation — that is the pool's job.
+    Container does not hold a reference to the pool.
+    """
+
+    def __init__(self, container_id: str, backend: BaseContainerBackend) -> None:
+        self.container_id = container_id
+        self._backend = backend
+
+    # -------------------------------------------------------------------------
+    # File operations — thin delegation to backend
+    # -------------------------------------------------------------------------
+
+    async def upload_file(self, local_path: str) -> UploadedFile:
+        return await self._backend.upload_file(self.container_id, local_path)
+
+    async def download_file_content(self, file_id: str) -> bytes:
+        return await self._backend.download_file_content(self.container_id, file_id)
+
+    async def download_file_to_disk(self, file_id: str, local_path: str) -> int:
+        return await self._backend.download_file_to_disk(
+            self.container_id, file_id, local_path
+        )
+
+    async def delete_file(self, file_id: str) -> None:
+        await self._backend.delete_file(self.container_id, file_id)
+
+    async def delete_files(self, file_ids: list[str]) -> None:
+        """Best-effort bulk delete. Logs and continues on individual failures."""
+        for fid in file_ids:
+            try:
+                await self._backend.delete_file(self.container_id, fid)
+            except Exception:
+                log.warning(
+                    "Failed to delete file %r from container %r",
+                    fid,
+                    self.container_id,
+                    exc_info=True,
+                )
+
+    async def list_output_files(self, path_prefix: str = "") -> dict[str, str]:
+        """List files in the container, optionally filtered by path prefix."""
+        return await self._backend.list_files(self.container_id, path_prefix)
+
+    async def download_files(
+        self,
+        file_ids: dict[str, str],
+        output_dir: str,
+    ) -> dict[str, str]:
+        """
+        Download multiple files to a local directory.
+
+        Args:
+            file_ids: {filename: file_id}
+            output_dir: Local directory to save files into
+
+        Returns:
+            {filename: local_path}
+        """
+        results: dict[str, str] = {}
+        for filename, file_id in file_ids.items():
+            local_path = os.path.join(output_dir, filename)
+            await self._backend.download_file_to_disk(
+                self.container_id, file_id, local_path
+            )
+            results[filename] = local_path
+        return results
+
+    def __repr__(self) -> str:
+        return f"Container(id={self.container_id!r})"

container_pool/_exceptions.py

@@ -0,0 +1,46 @@
+class ContainerPoolError(Exception):
+    """Base class for all container-pool errors."""
+
+
+class ContainerPoolExhaustedError(ContainerPoolError):
+    """
+    Raised by ContainerPool.acquire() when no container becomes
+    available within acquire_timeout seconds.
+    """
+
+    def __init__(self, timeout: float, pool_size: int) -> None:
+        self.timeout = timeout
+        self.pool_size = pool_size
+        super().__init__(
+            f"No container available after {timeout}s (pool_size={pool_size})"
+        )
+
+
+class ContainerExpiredError(ContainerPoolError):
+    """
+    Raised by a backend when it detects a container has expired
+    (404 or status=expired). The pool catches this and recreates.
+    Callers should never see this in normal flow.
+    """
+
+    def __init__(self, container_id: str) -> None:
+        self.container_id = container_id
+        super().__init__(f"Container {container_id!r} has expired or been deleted")
+
+
+class ContainerCreationError(ContainerPoolError):
+    """
+    Raised when all retries to create a new container have failed.
+    Wraps the last underlying exception.
+    """
+
+    def __init__(self, attempts: int, cause: BaseException) -> None:
+        self.attempts = attempts
+        self.cause = cause
+        super().__init__(
+            f"Container creation failed after {attempts} attempt(s): {cause}"
+        )
+
+
+class ContainerFileError(ContainerPoolError):
+    """Raised when a file upload, download, or delete operation fails."""

container_pool/_pool.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from ._backend import BaseContainerBackend
+from ._container import Container
+from ._exceptions import (
+    ContainerCreationError,
+    ContainerExpiredError,
+    ContainerPoolExhaustedError,
+)
+from ._retry import retry_with_backoff
+from ._types import ContainerStatus
+
+log = logging.getLogger(__name__)
+
+
+class ContainerPool:
+    """
+    Async FIFO pool of Container objects backed by any BaseContainerBackend.
+
+    Usage:
+        pool = ContainerPool(
+            backend,
+            max_pool_size=5,
+            acquire_timeout=30.0,
+            container_name="mypool",
+        )
+        container = await pool.acquire()
+        try:
+            ...
+        finally:
+            await pool.release(container)
+        await pool.shutdown()
+    """
+
+    def __init__(
+        self,
+        backend: BaseContainerBackend,
+        *,
+        max_pool_size: int,
+        acquire_timeout: float,
+        container_name: str,
+        creation_max_attempts: int = 3,
+        creation_base_delay: float = 1.0,
+    ) -> None:
+        if not (1 <= max_pool_size <= 50):
+            raise ValueError(f"max_pool_size must be 1-50, got {max_pool_size}")
+        if acquire_timeout <= 0:
+            raise ValueError("acquire_timeout must be positive")
+
+        self._backend = backend
+        self.max_pool_size = max_pool_size
+        self.acquire_timeout = acquire_timeout
+        self.container_name = container_name
+        self._creation_max_attempts = creation_max_attempts
+        self._creation_base_delay = creation_base_delay
+
+        self._queue: asyncio.Queue[Container] = asyncio.Queue()
+        # Total containers ever created = items in queue + items checked out.
+        # Only decremented on failed creation (rollback) — not on expiry/replace.
+        self._total: int = 0
+        self._lock = asyncio.Lock()  # guards the growth decision (_total += 1)
+        self._closed: bool = False
+
+    # -------------------------------------------------------------------------
+    # Public API
+    # -------------------------------------------------------------------------
+
+    async def acquire(self) -> Container:
+        """
+        Return a validated, live Container from the pool.
+
+        Flow:
+          1. Queue has an item (non-blocking)? → validate_or_recreate, return.
+          2. _total < max_pool_size? → create new container, return.
+          3. Otherwise: wait up to acquire_timeout for a release().
+             Raises ContainerPoolExhaustedError on timeout.
+        """
+        if self._closed:
+            raise RuntimeError("ContainerPool is shut down")
+
+        # Fast path: something already in the queue
+        try:
+            container = self._queue.get_nowait()
+            return await self._validate_or_recreate(container)
+        except asyncio.QueueEmpty:
+            pass
+
+        # Growth path: can we create a new one?
+        async with self._lock:
+            if self._total < self.max_pool_size:
+                self._total += 1
+                should_create = True
+            else:
+                should_create = False
+
+        if should_create:
+            try:
+                return await self._create_container_with_retry()
+            except Exception:
+                async with self._lock:
+                    self._total -= 1  # roll back — creation failed
+                raise
+
+        # Blocking path: wait for someone to release
+        try:
+            container = await asyncio.wait_for(
+                self._queue.get(),
+                timeout=self.acquire_timeout,
+            )
+        except asyncio.TimeoutError:
+            raise ContainerPoolExhaustedError(
+                timeout=self.acquire_timeout,
+                pool_size=self.max_pool_size,
+            )
+
+        return await self._validate_or_recreate(container)
+
+    async def release(self, container: Container) -> None:
+        """
+        Return a container to the pool.
+
+        No re-validation at release time — validation happens at the next
+        acquire(). This keeps release() fast (safe to call in finally blocks).
+
+        If the pool is already shut down, destroys the container instead
+        of queuing it.
+        """
+        if self._closed:
+            await self._safe_destroy(container)
+            return
+        await self._queue.put(container)
+
+    async def shutdown(self) -> None:
+        """
+        Mark pool as closed and destroy all containers currently in the queue.
+
+        Containers that are checked out at shutdown time will be destroyed
+        when release() is called on them. This method is idempotent.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        log.info("ContainerPool shutting down. Draining queue...")
+
+        destroyed = 0
+        while True:
+            try:
+                container = self._queue.get_nowait()
+                await self._safe_destroy(container)
+                destroyed += 1
+            except asyncio.QueueEmpty:
+                break
+
+        log.info("ContainerPool shutdown complete. Destroyed %d container(s).", destroyed)
+
+    # -------------------------------------------------------------------------
+    # Internal helpers
+    # -------------------------------------------------------------------------
+
+    async def _create_container_with_retry(self) -> Container:
+        info = await retry_with_backoff(
+            lambda: self._backend.create_container(self.container_name),
+            max_attempts=self._creation_max_attempts,
+            base_delay=self._creation_base_delay,
+            retryable=ContainerCreationError,
+        )
+        log.debug("Created container %r", info.container_id)
+        return Container(container_id=info.container_id, backend=self._backend)
+
+    async def _validate_or_recreate(self, container: Container) -> Container:
+        """
+        Confirm the container is alive. If expired or gone, replace it
+        with a freshly created one (total pool count stays the same: 1-for-1).
+        """
+        try:
+            info = await self._backend.get_container(container.container_id)
+            if info.status == ContainerStatus.ACTIVE:
+                return container
+            log.info(
+                "Container %r has status=%r, recreating.",
+                container.container_id,
+                info.status,
+            )
+        except ContainerExpiredError:
+            log.info(
+                "Container %r returned expired/404, recreating.",
+                container.container_id,
+            )
+        except Exception as exc:
+            log.warning(
+                "Unexpected error validating container %r (%s), recreating.",
+                container.container_id,
+                exc,
+            )
+
+        await self._safe_destroy(container)
+        info = await retry_with_backoff(
+            lambda: self._backend.create_container(self.container_name),
+            max_attempts=self._creation_max_attempts,
+            base_delay=self._creation_base_delay,
+            retryable=ContainerCreationError,
+        )
+        log.debug(
+            "Recreated: %r -> %r", container.container_id, info.container_id
+        )
+        return Container(container_id=info.container_id, backend=self._backend)
+
+    async def _safe_destroy(self, container: Container) -> None:
+        """Destroy a container, swallowing all errors."""
+        try:
+            await self._backend.destroy_container(container.container_id)
+        except Exception:
+            log.warning(
+                "Failed to destroy container %r during cleanup",
+                container.container_id,
+                exc_info=True,
+            )

container_pool/_retry.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+log = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+async def retry_with_backoff(
+    fn: Callable[[], Awaitable[T]],
+    *,
+    max_attempts: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+    jitter: bool = True,
+    retryable: type[BaseException] | tuple[type[BaseException], ...] = Exception,
+) -> T:
+    """
+    Call fn() up to max_attempts times with exponential backoff.
+
+    Delay schedule (before jitter): 1s, 2s, 4s, 8s... capped at max_delay.
+    Jitter is ±20% of the computed delay to avoid thundering herd.
+
+    Only retries on exceptions matching `retryable`.
+    Raises the last exception after all attempts are exhausted.
+    """
+    last_exc: BaseException | None = None
+
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return await fn()
+        except retryable as exc:
+            last_exc = exc
+            if attempt == max_attempts:
+                break
+            delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
+            if jitter:
+                delay *= random.uniform(0.8, 1.2)
+            log.warning(
+                "Attempt %d/%d failed (%s). Retrying in %.2fs.",
+                attempt,
+                max_attempts,
+                exc,
+                delay,
+            )
+            await asyncio.sleep(delay)
+
+    raise last_exc  # type: ignore[misc]

container_pool/_tracker.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import logging
+
+from ._container import Container
+from ._types import UploadedFile
+
+log = logging.getLogger(__name__)
+
+
+class RequestFileTracker:
+    """
+    Wraps a Container for the duration of a single request.
+
+    Tracks every file_id returned by upload_file(). Call cleanup() once the
+    request is complete to delete all tracked files. Keeps containers clean
+    between users without the caller needing to track individual file ids.
+
+    Usage:
+        container = await pool.acquire()
+        tracker = RequestFileTracker(container)
+        try:
+            uploaded = await tracker.upload_file("/tmp/input.csv")
+            # ... use container ...
+        finally:
+            await tracker.cleanup()
+            await pool.release(container)
+    """
+
+    def __init__(self, container: Container) -> None:
+        self._container = container
+        self._tracked_file_ids: list[str] = []
+
+    @property
+    def container(self) -> Container:
+        return self._container
+
+    async def upload_file(self, local_path: str) -> UploadedFile:
+        """Upload a file and automatically track its file_id for cleanup."""
+        result = await self._container.upload_file(local_path)
+        self._tracked_file_ids.append(result.file_id)
+        return result
+
+    async def cleanup(self) -> None:
+        """
+        Delete all tracked files. Best-effort: always clears the tracking
+        list even if some deletes fail. Errors are logged, not raised.
+        """
+        if not self._tracked_file_ids:
+            return
+
+        ids_to_delete = list(self._tracked_file_ids)
+        self._tracked_file_ids.clear()  # clear before deleting — safe on partial failure
+
+        await self._container.delete_files(ids_to_delete)
+        log.debug("RequestFileTracker cleaned up %d file(s).", len(ids_to_delete))

container_pool/_types.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class ContainerStatus(StrEnum):
+    ACTIVE = "active"
+    EXPIRED = "expired"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class ContainerInfo:
+    """
+    Vendor-neutral snapshot of a container's identity and status.
+    Backends return this; the pool never touches raw vendor objects.
+    """
+
+    container_id: str
+    status: ContainerStatus
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class UploadedFile:
+    """
+    Returned by backend.upload_file(). Carries all three identifiers
+    the caller needs: the container it belongs to, the remote file id,
+    and the path the runtime sees it at.
+    """
+
+    container_id: str
+    file_id: str
+    container_path: str

container_pool/backends/__init__.py

@@ -0,0 +1,4 @@
+# Backend implementations.
+# Import explicitly to avoid crashing when optional deps are not installed:
+#
+#   from container_pool.backends.openai import OpenAIContainerBackend

container_pool/backends/openai.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import os
+
+try:
+    import openai as _openai
+    from openai import AsyncOpenAI
+except ImportError as exc:
+    raise ImportError(
+        "The OpenAI backend requires the 'openai' package. "
+        "Install it with: pip install 'container-pool[openai]'"
+    ) from exc
+
+from .._backend import BaseContainerBackend
+from .._exceptions import (
+    ContainerCreationError,
+    ContainerExpiredError,
+    ContainerFileError,
+)
+from .._types import ContainerInfo, ContainerStatus, UploadedFile
+
+
+class OpenAIContainerBackend(BaseContainerBackend):
+    """
+    Concrete backend using the OpenAI Code Interpreter Container API.
+
+    Requires openai>=1.0.0 and an AsyncOpenAI client. Install the extra:
+        pip install 'container-pool[openai]'
+
+    All vendor-specific errors are translated into ContainerPoolError subclasses.
+    The pool and Container classes never see openai SDK types.
+    """
+
+    def __init__(self, client: AsyncOpenAI) -> None:
+        self._client = client
+
+    # -------------------------------------------------------------------------
+    # Lifecycle
+    # -------------------------------------------------------------------------
+
+    async def create_container(self, name: str) -> ContainerInfo:
+        try:
+            result = await self._client.containers.create(name=name)
+            return ContainerInfo(
+                container_id=result.id,
+                status=self._parse_status(result.status),
+            )
+        except _openai.APIError as exc:
+            raise ContainerCreationError(attempts=1, cause=exc) from exc
+
+    async def get_container(self, container_id: str) -> ContainerInfo:
+        try:
+            result = await self._client.containers.retrieve(container_id)
+            status = self._parse_status(result.status)
+            if status != ContainerStatus.ACTIVE:
+                raise ContainerExpiredError(container_id)
+            return ContainerInfo(container_id=result.id, status=status)
+        except _openai.NotFoundError as exc:
+            raise ContainerExpiredError(container_id) from exc
+        except ContainerExpiredError:
+            raise
+        except _openai.APIConnectionError as exc:
+            # Network error — treat as expired so the pool recreates
+            raise ContainerExpiredError(container_id) from exc
+        except _openai.APIError as exc:
+            raise ContainerExpiredError(container_id) from exc
+
+    async def destroy_container(self, container_id: str) -> None:
+        try:
+            await self._client.containers.delete(container_id)
+        except (_openai.NotFoundError, _openai.APIError):
+            pass  # best-effort
+
+    # -------------------------------------------------------------------------
+    # File operations
+    # -------------------------------------------------------------------------
+
+    async def upload_file(self, container_id: str, local_path: str) -> UploadedFile:
+        try:
+            with open(local_path, "rb") as f:
+                result = await self._client.containers.files.create(
+                    container_id=container_id,
+                    file=f,
+                )
+            return UploadedFile(
+                container_id=container_id,
+                file_id=result.id,
+                container_path=result.path,
+            )
+        except FileNotFoundError:
+            raise
+        except Exception as exc:
+            raise ContainerFileError(
+                f"Upload failed for {local_path!r}: {exc}"
+            ) from exc
+
+    async def download_file_content(self, container_id: str, file_id: str) -> bytes:
+        try:
+            response = await self._client.containers.files.content.retrieve(
+                file_id=file_id,
+                container_id=container_id,
+            )
+            return response.content
+        except Exception as exc:
+            raise ContainerFileError(
+                f"Download failed for file {file_id!r}: {exc}"
+            ) from exc
+
+    async def download_file_to_disk(
+        self,
+        container_id: str,
+        file_id: str,
+        local_path: str,
+    ) -> int:
+        content = await self.download_file_content(container_id, file_id)
+        os.makedirs(os.path.dirname(local_path) or ".", exist_ok=True)
+        with open(local_path, "wb") as f:
+            f.write(content)
+        return len(content)
+
+    async def delete_file(self, container_id: str, file_id: str) -> None:
+        try:
+            await self._client.containers.files.delete(
+                file_id=file_id,
+                container_id=container_id,
+            )
+        except (_openai.NotFoundError, _openai.APIError):
+            pass  # best-effort
+
+    async def list_files(
+        self,
+        container_id: str,
+        path_prefix: str = "",
+    ) -> dict[str, str]:
+        try:
+            response = await self._client.containers.files.list(
+                container_id=container_id
+            )
+            files: dict[str, str] = {}
+            for f in response.data:
+                if path_prefix and not f.path.startswith(path_prefix):
+                    continue
+                filename = os.path.basename(f.path)
+                files[filename] = f.id
+            return files
+        except Exception as exc:
+            raise ContainerFileError(f"list_files failed: {exc}") from exc
+
+    # -------------------------------------------------------------------------
+    # Helpers
+    # -------------------------------------------------------------------------
+
+    @staticmethod
+    def _parse_status(raw: str) -> ContainerStatus:
+        try:
+            return ContainerStatus(raw)
+        except ValueError:
+            return ContainerStatus.UNKNOWN

container_pool-0.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: container-pool
+Version: 0.1.0
+Summary: Provider-agnostic async container pool with expiry recovery and per-request file tracking
+Project-URL: Repository, https://github.com/aayushgzip/container-pool
+Project-URL: Issues, https://github.com/aayushgzip/container-pool/issues
+License: MIT License
+        
+        Copyright (c) 2026 aayushdwids
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: async,asyncio,code-interpreter,container,openai,pool
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# container-pool
+
+Production-grade async container pool for Python. Handles container lifecycle, reuse, concurrency, and automatic recovery from expiry — so you don't have to.
+
+Built for OpenAI's Code Interpreter, but designed to work with **any sandboxed container runtime** via a pluggable backend interface.
+
+## The Problem
+
+When running sandboxed containers behind a multi-user backend, you hit problems no provider solves for you:
+
+- **Containers expire silently** after 20 minutes of inactivity. Your next request fails with a 404.
+- **No built-in pooling.** Every request creates a new container (~2-3s overhead).
+- **No concurrency management.** Two users hitting your API simultaneously? You're on your own.
+- **File cleanup is your problem.** Leaked files accumulate and you eat the storage cost.
+
+`container-pool` is the infrastructure layer that handles all of this.
+
+## What This Does
+
+```
+Request A ──→ acquire() ──→ [Container 1] ──→ release() ──→ back to pool
+Request B ──→ acquire() ──→ [Container 2] ──→ release() ──→ back to pool
+Request C ──→ acquire() ──→ (pool full, blocks until release) ──→ ...
+```
+
+- **FIFO pool** with configurable size, blocking acquisition with timeout when exhausted
+- **Automatic expiry recovery** — detects expired containers (404, status=expired) and transparently recreates them
+- **Per-request file tracking** with cleanup, so containers stay clean between users
+- **Retry with exponential backoff** on container creation failures
+- **Graceful shutdown** that destroys all containers on exit
+- **Provider-agnostic** — implement `BaseContainerBackend` to support any runtime
+
+## Installation
+
+```bash
+pip install container-pool            # core only
+pip install "container-pool[openai]"  # with OpenAI backend
+```
+
+## Usage
+
+```python
+from openai import AsyncOpenAI
+from container_pool import ContainerPool, RequestFileTracker
+from container_pool.backends.openai import OpenAIContainerBackend
+
+client = AsyncOpenAI()
+backend = OpenAIContainerBackend(client)
+
+pool = ContainerPool(
+    backend,
+    max_pool_size=5,
+    acquire_timeout=30.0,
+    container_name="my-pool",
+)
+
+# Acquire, use, release
+container = await pool.acquire()
+try:
+    tracker = RequestFileTracker(container)
+    uploaded = await tracker.upload_file("/tmp/data.csv")
+    # ... run code interpreter with container.container_id ...
+    files = await container.list_output_files("/mnt/data/")
+    results = await container.download_files(files, "/tmp/output")
+finally:
+    await tracker.cleanup()        # delete uploaded files
+    await pool.release(container)  # return to pool
+
+# On app shutdown
+await pool.shutdown()
+```
+
+## Custom Backends
+
+Implement `BaseContainerBackend` to plug in any container runtime:
+
+```python
+from container_pool import BaseContainerBackend, ContainerInfo, UploadedFile
+
+class MyBackend(BaseContainerBackend):
+    async def create_container(self, name: str) -> ContainerInfo: ...
+    async def get_container(self, container_id: str) -> ContainerInfo: ...
+    async def destroy_container(self, container_id: str) -> None: ...
+    async def upload_file(self, container_id: str, local_path: str) -> UploadedFile: ...
+    async def download_file_content(self, container_id: str, file_id: str) -> bytes: ...
+    async def download_file_to_disk(self, container_id: str, file_id: str, local_path: str) -> int: ...
+    async def delete_file(self, container_id: str, file_id: str) -> None: ...
+    async def list_files(self, container_id: str, path_prefix: str = "") -> dict[str, str]: ...
+```
+
+## How It Works
+
+### Acquire Flow
+
+```
+acquire()
+  ├─ Queue has available container? → validate it's alive → return
+  ├─ Pool below max size? → create new container → return
+  └─ Pool exhausted? → block until someone calls release() (with timeout)
+```
+
+### Expiry Recovery
+
+`container-pool` handles silent expiry transparently — callers always get a live container:
+
+```
+validate_or_recreate(container)
+  ├─ active status → use it
+  ├─ expired status → recreate
+  ├─ 404 → recreate
+  └─ connection error → recreate
+```
+
+### Performance
+
+| Operation | Latency |
+|---|---|
+| Warm acquire | <100ms |
+| Cold acquire | ~2-3s (container creation) |
+| Pool exhausted | Blocks up to `acquire_timeout` |
+| Expiry recovery | ~2-3s (transparent recreation) |
+
+## Configuration
+
+| Parameter | Description |
+|---|---|
+| `max_pool_size` | Max containers in pool (1–50) |
+| `acquire_timeout` | Seconds to wait when pool is exhausted |
+| `container_name` | Name prefix for created containers |
+| `creation_max_attempts` | Retry attempts on creation failure (default: 3) |
+| `creation_base_delay` | Base delay for exponential backoff in seconds (default: 1.0) |
+
+## Roadmap
+
+### v1 (current)
+- [x] FIFO pool with `asyncio.Queue`
+- [x] Automatic expiry detection and recovery
+- [x] Per-request file tracking and cleanup
+- [x] Retry with exponential backoff
+- [x] Graceful shutdown
+- [x] Pluggable backend interface
+- [x] OpenAI Code Interpreter backend
+
+### v2
+- [ ] **Pool pre-warming** — create containers at startup to eliminate cold-start latency
+- [ ] **Background keep-alive** — periodic pings to prevent idle expiry
+- [ ] **Distributed state** — Redis/PostgreSQL backend for multi-node deployments
+- [ ] **Observability** — metrics for pool utilization, acquire wait times, expiry rate
+- [ ] **Pool strategies** — LRU, priority-based in addition to FIFO
+
+## Contributing
+
+Contributions welcome. Please open an issue first to discuss what you'd like to change.
+
+## Why This Exists
+
+Built after hitting every one of these problems while running Code Interpreter in a multi-user production backend. OpenAI's docs hand you a container ID and say good luck — this is the "good luck" part.
+
+— [@aayushgzip](https://github.com/aayushgzip)
+
+## License
+
+[MIT](LICENSE)

container_pool-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+container_pool/__init__.py,sha256=KaW0rh1XJ9lt1PYvrFtsNUc-LJnTK022ccU3m6J96VA,1311
+container_pool/_backend.py,sha256=PJPKk_tp9HRQ_J7LejH7VxAGk13fiDH5H9SQ6Trn3PI,2946
+container_pool/_container.py,sha256=03y3VC2OOknWmTpkgu-bjp3FpyEBZcuLlY4KfMMsWQg,3069
+container_pool/_exceptions.py,sha256=CMCcPTwC3NMrfmZLFDxvOsz8mBc4tEQkC9t3szlSdwk,1484
+container_pool/_pool.py,sha256=5yTkorgy1UpkFEJwE_mp3zQ6GFPiiHjwyJ9c8e2fmk4,7714
+container_pool/_retry.py,sha256=c6ScGsCP8KPI49NalUDIWbfKsfLjg92d3eW3GkufVuU,1508
+container_pool/_tracker.py,sha256=bzxzSr0Y9izCrbxaf3aRyC-T3LvZ0J3kXSYQs6qPwAk,1856
+container_pool/_types.py,sha256=0h2Czgk5eysLvdFSSGa6I2msejs28-GfC7u7q8MTzec,844
+container_pool/backends/__init__.py,sha256=Pv8ebNKK-lcPwymzyF5JKpvNJRYxgjEDDyfDL76-xaU,175
+container_pool/backends/openai.py,sha256=sZKjtZkFuAttQ9tA464stmfVhgbEi5I4PuHODoYJuj8,5734
+container_pool-0.1.0.dist-info/METADATA,sha256=fq23Vx8rkcerhltizaxMNODzPUdgkLNiKzP5OBO8cHk,8362
+container_pool-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+container_pool-0.1.0.dist-info/licenses/LICENSE,sha256=5E2CMJpaO4JdczEgKliBHB2aSxCnkvyB5NNEtX0TgXY,1068
+container_pool-0.1.0.dist-info/RECORD,,

container_pool-0.1.0.dist-info/WHEEL

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

container_pool-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aayushdwids
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.