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

[Fromsko]

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)

Import statement	Result
import trpc_agent_sdk	✅ OK (instant)
from trpc_agent_sdk.models import OpenAIModel	✅ OK (instant)
from trpc_agent_sdk.configs import RunConfig	✅ OK (instant)
from trpc_agent_sdk.context import InvocationContext	✅ OK (instant)
from trpc_agent_sdk.abc import AgentABC	✅ OK (instant)
from trpc_agent_sdk.code_executors import BaseCodeExecutor	❌ Hang / segfault
from trpc_agent_sdk.agents._base_agent import BaseAgent	❌ Hang / segfault
from trpc_agent_sdk.agents import LlmAgent	❌ Hang / segfault

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.

[Fromsko]

Update: while investigating the fix, I found a second root cause with the same symptom.

Second problem: import magic in _files.py

code_executors/utils/_files.py also imports python-magic at module top level (lines 20-24):

try:
    import magic
    HAS_MAGIC = True
except ImportError:
    HAS_MAGIC = False

On Windows, python-magic requires a native libmagic DLL. When the DLL is not found, import magic hangs during magic.loader initialization (it probes the filesystem for the library). The try/except ImportError doesn't help because the hang happens before any exception is raised.

This is in the same import chain:

agents → code_executors → code_executors.utils → _files.py → import magic

Fix

Both import docker and import magic need to be deferred to call-time. I've prepared a PR with lazy imports for both.