Windows: top-level import docker in _container_cli.py causes hang/segfault when Docker is unavailable — LlmAgent import blocked #230

What version of tRPC-Agent-Python are you using?

trpc-agent-py 1.1.14

What operating system and Python version are you using?

• OS: Windows 11 (10.0.26100) x86_64
• Python: 3.12.13 (CPython, uv-managed)
• Docker SDK: docker-py 7.2.0 (installed as a dependency)
• Docker Desktop: Not installed (Docker daemon is not running)

What did you do?

Ran the minimal example from the README — importing LlmAgent and creating a simple agent:

from trpc_agent_sdk.agents import LlmAgent

Or simply:

python -c "from trpc_agent_sdk.agents import LlmAgent"

What did you expect to see?

The import should complete instantly (a few hundred ms at most), allowing the user to proceed with agent creation.

What did you see instead?

The process hangs indefinitely (or crashes with a segmentation fault / exit code 139), making the SDK completely unusable on Windows without Docker Desktop installed.

Root cause analysis

The import chain is:

trpc_agent_sdk.agents.__init__
  → trpc_agent_sdk.agents._base_agent
    → trpc_agent_sdk.code_executors
      → trpc_agent_sdk.code_executors.container
        → _container_cli.py  line 19: import docker

_container_cli.py performs import docker at module top level (lines 19–23):

import docker
from docker.models.containers import Container
from docker.utils.socket import consume_socket_output
from docker.utils.socket import demux_adaptor
from docker.utils.socket import frames_iter

This is pulled in transitively by every from trpc_agent_sdk.agents import ... — even when the user has no intention of using ContainerCodeExecutor. The docker SDK's initialization path on Windows (where it looks for the Docker named pipe npipe:////./pipe/docker_engine) causes the hang/crash when no Docker daemon exists.

Step-by-step isolation (via timeout probes)

Narrowed down to:

# This hangs on Windows without Docker:
from trpc_agent_sdk.code_executors.container._container_cli import ContainerClient

Workaround

Pre-importing docker before importing trpc_agent_sdk.agents appears to avoid the segfault in some cases:

import docker  # pre-load the SDK safely
from trpc_agent_sdk.agents import LlmAgent  # now works

But this is fragile and not a real fix.

Suggested fix

Move import docker (and the from docker.* imports) from module top-level into the methods/functions that actually use them (lazy import). This is the standard pattern for optional heavy dependencies:

# _container_cli.py — before (line 19):
import docker
from docker.models.containers import Container
# ...

# after — lazy import inside __init__ or _init_docker_client:
def _init_docker_client(self):
    import docker
    from docker.models.containers import Container
    # ...

This way, users who only use LlmAgent with UnsafeLocalCodeExecutor (or no code executor at all) won't be forced to load the Docker SDK.

This issue makes the SDK completely unusable on Windows without Docker Desktop, which is a very common development environment. It would be great to see this fixed.