bundle.pods
===========

.. py:module:: bundle.pods

.. autoapi-nested-parse::

   Bundle pods CLI package.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/bundle/pods/cli/index
   /autoapi/bundle/pods/manager/index


Classes
-------

.. autoapisummary::

   bundle.pods.PodManager
   bundle.pods.PodSpec


Package Contents
----------------

.. py:class:: PodManager(/, **data: Any)

   Bases: :py:obj:`bundle.core.entity.Entity`


   Manages discovery and orchestration of local AI pods.

   On construction the manager resolves the Docker Compose CLI, scans the
   ``pods_root`` directory for pod folders (each containing a
   ``docker-compose.yml``), and caches the resulting :class:`PodSpec` objects.

   All compose operations (build, run, down, status, logs) are async and
   delegate to :class:`~bundle.core.process.ProcessStream` for streamed output
   or :class:`~bundle.core.process.Process` for captured output.


   .. py:attribute:: pods_root
      :type:  pathlib.Path


   .. py:method:: create(pods_root: pathlib.Path | str | None = None) -> PodManager
      :classmethod:


      Factory that resolves the pods root and returns a ready-to-use manager.



   .. py:property:: specs
      :type: dict[str, PodSpec]



   .. py:method:: get(name: str) -> PodSpec

      Look up a pod by name (case-insensitive). Raises ``ClickException`` if not found.



   .. py:method:: pod_path(pod: PodSpec) -> pathlib.Path

      Resolve and validate the filesystem path for a pod.



   .. py:method:: running_containers() -> set[str]
      :async:


      Query Docker for currently running container names.



   .. py:method:: compose(pod: PodSpec, subcommand: str, stream: bool = False) -> bundle.core.process.ProcessResult
      :async:


      Execute a docker compose subcommand against a pod's compose file.



   .. py:method:: build(pod: PodSpec) -> bundle.core.process.ProcessResult | None
      :async:


      Build the pod's Docker image. Skips pods that use prebuilt images only.



   .. py:method:: run(pod: PodSpec) -> bundle.core.process.ProcessResult
      :async:


      Start a pod in detached mode (``up -d``).



   .. py:method:: down(pod: PodSpec) -> bundle.core.process.ProcessResult
      :async:


      Stop and remove a pod's containers and networks.



   .. py:method:: status(pod: PodSpec) -> bundle.core.process.ProcessResult
      :async:


      Return the ``docker compose ps`` output for a pod.



   .. py:method:: logs(pod: PodSpec, follow: bool = True, tail: int = 200) -> bundle.core.process.ProcessResult
      :async:


      Stream or show pod container logs.



.. py:class:: PodSpec(/, **data: Any)

   Bases: :py:obj:`bundle.core.data.Data`


   Declarative specification for a single pod.

   .. attribute:: name

      Pod identifier (e.g. "comfyui", "discord-bot").

   .. attribute:: folder

      Subdirectory name under the pods root.

   .. attribute:: service

      Docker Compose service name, if the compose file defines one matching the pod name.

   .. attribute:: buildable

      Whether the compose file contains a ``build:`` section.

   .. attribute:: containers

      Explicit ``container_name`` values parsed from the compose file.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: folder
      :type:  str


   .. py:attribute:: service
      :type:  str | None
      :value: None



   .. py:attribute:: buildable
      :type:  bool
      :value: True



   .. py:attribute:: containers
      :type:  list[str]
      :value: None