perf: load opencode.types on first use

Generated resources now name response types as strings, resolved by
type_adapter on first use, and import models only under TYPE_CHECKING.
opencode.types is a lazy package attribute. import opencode no longer
builds ~640 pydantic models (median ~400ms -> ~265ms locally; the model
build moves to the first request, ~130ms).

Author: shrijayan

codegen/render.py

@@ -348,14 +348,14 @@ def _render_method(operation: Operation, errors: dict[str, dict[str, Any]], *, i
         lines += [
             "        return self._client.page(",
             *request_options,
-            f"            response_type={_resource_type(operation.response_type or 'Any')},",
+            f"            response_type={_resource_type(operation.response_type or 'Any')!r},",
             "        )",
         ]
     elif operation.kind == "stream":
         lines += [
             f"        return {awaiting}self._client.stream(",
             *request_options,
-            f"            item_type={_resource_type(operation.response_type or 'Any')},",
+            f"            item_type={_resource_type(operation.response_type or 'Any')!r},",
             "        )",
         ]
     elif operation.kind == "void":
@@ -371,7 +371,7 @@ def _render_method(operation: Operation, errors: dict[str, dict[str, Any]], *, i
         lines += [
             f"        return cast({returns!r}, {awaiting}self._client.request(",
             *request_options,
-            f"            response_type={_resource_type(operation.response_type or 'Any')},",
+            f"            response_type={_resource_type(operation.response_type or 'Any')!r},",
             *(["            unwrap=True,"] if operation.unwrap else []),
             "        ))",
         ]
@@ -453,7 +453,7 @@ def render_resource_module(
         [*_resource_classes(resource, errors, is_async=False), *_resource_classes(resource, errors, is_async=True)]
     )
     uses = _names_in(source)
-    typing_names = sorted({"Any", "Literal", "cast"} & uses)
+    typing_names = sorted(({"Any", "Literal", "cast"} & uses) | ({"TYPE_CHECKING"} if type_names else set[str]()))
     abc_names = sorted({"Mapping", "Sequence"} & uses)
     runtime: list[str] = []
     if "encode_path_segment" in uses:
@@ -481,7 +481,18 @@ def render_resource_module(
         *(["from .._streaming import AsyncStream, Stream"] if any(op.kind == "stream" for op in operations) else []),
         "from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout"
         + (", OpenEnum" if "OpenEnum" in uses else ""),
-        *(["from ..types import (", *[f"    {name}," for name in type_names], ")"] if type_names else []),
+        # Models load on first use (see ``type_adapter``), so importing the client does not build them all.
+        *(
+            [
+                "",
+                "if TYPE_CHECKING:",
+                "    from ..types import (",
+                *[f"        {name}," for name in type_names],
+                "    )",
+            ]
+            if type_names
+            else []
+        ),
         "",
         f"__all__ = [{', '.join(repr(prefix + resource.class_name + 'Resource') for prefix in ('', 'Async'))}]\n\n",
         source,

src/opencode/__init__.py

@@ -14,7 +14,8 @@
 
 from __future__ import annotations
 
-from . import types
+from typing import TYPE_CHECKING, Any
+
 from ._client import AsyncOpencode, Opencode
 
 # <generated:error-imports>
@@ -108,6 +109,9 @@
     rpc_method,
 )
 
+if TYPE_CHECKING:
+    from . import types
+
 # <generated:api-version>
 API_VERSION = "2.1.2"
 """The OpenCode server version this client was generated from."""
@@ -206,3 +210,12 @@
     "WorktreeError",
     # </generated:error-exports>
 ]
+
+
+def __getattr__(name: str) -> Any:
+    # `opencode.types` builds several hundred models, so it is imported on first use rather than with the package.
+    if name == "types":
+        import importlib
+
+        return importlib.import_module(".types", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/opencode/_base_client.py

@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import base64
+import builtins
 import email.utils
 import functools
 import json
@@ -60,8 +61,18 @@ def _cached_adapter(tp: Any) -> pydantic.TypeAdapter[Any]:
     return pydantic.TypeAdapter(tp)
 
 
+@functools.cache
+def _resolve_type(expr: str) -> Any:
+    # Generated resources name their response types as strings, so `import opencode` does not build every model.
+    from . import types
+
+    return eval(expr, {**vars(types), "builtins": builtins})  # expressions come from the generator
+
+
 def type_adapter(tp: Any) -> pydantic.TypeAdapter[Any]:
-    """Returns a cached ``TypeAdapter`` for a response type."""
+    """Returns a cached ``TypeAdapter`` for a response type, or for a type expression over ``opencode.types``."""
+    if isinstance(tp, str):
+        tp = _resolve_type(tp)
     try:
         return _cached_adapter(tp)
     except TypeError:  # unhashable type expression

src/opencode/_events.py

@@ -31,15 +31,14 @@
 from typing_extensions import Self
 
 from ._exceptions import APIConnectionError, APIStatusError, OpencodeError
-from .types import ServerConnectedEvent
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
     from types import TracebackType
 
     from ._client import AsyncOpencode, Opencode
     from ._streaming import AsyncStream, Stream
-    from .types import Event
+    from .types import Event, ServerConnectedEvent
 
 __all__ = [
     "SUBSCRIBER_CAPACITY",
@@ -302,6 +301,8 @@ def _run(self, connection: _SyncConnection) -> None:
 
     def _read(self, connection: _SyncConnection) -> None:
         """Reads one connection until it ends, setting ``connection.delivered`` once an event arrives."""
+        from .types import ServerConnectedEvent
+
         stream = self._client.event.subscribe()
         with self._lock:
             connection.stream = stream
@@ -605,6 +606,8 @@ async def _run(self, connection: _AsyncConnection) -> None:
 
     async def _read(self, connection: _AsyncConnection) -> None:
         """Reads one connection until it ends, setting ``connection.delivered`` once an event arrives."""
+        from .types import ServerConnectedEvent
+
         stream: AsyncStream[Event] = await self._client.event.subscribe()
         try:
             stream.on_activity = connection.activity

src/opencode/_rpc.py

@@ -44,7 +44,6 @@ class Counter(RpcDefinition, id="counter"):
 from ._exceptions import OpencodeError, validation_summary
 from ._types import NOT_GIVEN, NotGiven
 from .resources.rpc import AsyncRpcResource, RpcResource
-from .types import RpcEvent
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -53,7 +52,7 @@ class Counter(RpcDefinition, id="counter"):
     from ._client import AsyncOpencode, Opencode
     from ._events import AsyncSubscription, Subscription
     from ._types import Headers, Timeout
-    from .types import Location
+    from .types import Location, RpcEvent
 
 __all__ = [
     "AsyncRpcClient",
@@ -327,11 +326,15 @@ def call(
 
     def events(self) -> Subscription[RpcEvent]:
         """Subscribes to every event of this RPC, as raw events, on the client's shared event stream."""
+        from .types import RpcEvent
+
         prefix = f"rpc.{self.definition.id}."
         return self._client.events.of_type(RpcEvent).where(lambda event: event.type.startswith(prefix))
 
     def subscribe(self, event: RpcEventDefinition[_T]) -> RpcEvents[_T]:
         """Subscribes to one event of this RPC, with validated data, on the client's shared event stream."""
+        from .types import RpcEvent
+
         _check_event(self.definition, event)
         wire = self.definition.event_type(event)
         return RpcEvents(self._client.events.of_type(RpcEvent).where(lambda raw: raw.type == wire), event)
@@ -396,11 +399,15 @@ async def call(
 
     def events(self) -> AsyncSubscription[RpcEvent]:
         """Subscribes to every event of this RPC, as raw events, on the client's shared event stream."""
+        from .types import RpcEvent
+
         prefix = f"rpc.{self.definition.id}."
         return self._client.events.of_type(RpcEvent).where(lambda event: event.type.startswith(prefix))
 
     def subscribe(self, event: RpcEventDefinition[_T]) -> AsyncRpcEvents[_T]:
         """Subscribes to one event of this RPC, with validated data, on the client's shared event stream."""
+        from .types import RpcEvent
+
         _check_event(self.definition, event)
         wire = self.definition.event_type(event)
         return AsyncRpcEvents(self._client.events.of_type(RpcEvent).where(lambda raw: raw.type == wire), event)

src/opencode/lib/_session.py

@@ -14,26 +14,22 @@
 
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, NotGiven, Timeout
-from ..types import (
-    AgentID,
-    ModelRef,
-    PromptInputFileAttachment,
-    SessionID,
-    SessionInfo,
-    SessionMessageAssistant,
-    SessionMessageAssistantText,
-    SessionMessageIdle,
-    SessionMessageInfo,
-    SessionMessageUser,
-    SessionStructuredError,
-    TokenUsageInfo,
-    TokenUsageInfoCache,
-)
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
     from ..resources.session import AsyncSessionResource, SessionResource
+    from ..types import (
+        AgentID,
+        ModelRef,
+        PromptInputFileAttachment,
+        SessionID,
+        SessionInfo,
+        SessionMessageAssistant,
+        SessionMessageInfo,
+        SessionStructuredError,
+        TokenUsageInfo,
+    )
 
 __all__ = ["AsyncSessionHelpers", "RunResult", "SessionHelpers"]
 
@@ -44,17 +40,21 @@ class RunResult:
 
     session: SessionInfo
     """The session as it was after the run. ``session.cost`` and ``session.tokens`` cover the whole session."""
-    messages: list[SessionMessageInfo] = field(default_factory=list[SessionMessageInfo])
+    messages: list[SessionMessageInfo] = field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
     """Messages this run added, oldest first, starting with the prompt."""
 
     @property
     def assistant_messages(self) -> list[SessionMessageAssistant]:
         """The assistant messages of this run, oldest first."""
+        from ..types import SessionMessageAssistant
+
         return [message for message in self.messages if isinstance(message, SessionMessageAssistant)]
 
     @property
     def text(self) -> str:
         """Text of the last assistant message, or ``""`` when the agent produced none."""
+        from ..types import SessionMessageAssistantText
+
         for message in reversed(self.assistant_messages):
             parts = [item.text for item in message.content if isinstance(item, SessionMessageAssistantText)]
             if parts:
@@ -64,6 +64,8 @@ def text(self) -> str:
     @property
     def outcome(self) -> str | None:
         """``succeeded``, ``failed`` or ``interrupted``, from the run's idle marker or the session."""
+        from ..types import SessionMessageIdle
+
         for message in reversed(self.messages):
             if isinstance(message, SessionMessageIdle):
                 return message.outcome
@@ -72,6 +74,8 @@ def outcome(self) -> str | None:
     @property
     def error(self) -> SessionStructuredError | None:
         """Why the run failed, from its idle marker or last assistant message, or ``None``."""
+        from ..types import SessionMessageAssistant, SessionMessageIdle
+
         for message in reversed(self.messages):
             if isinstance(message, (SessionMessageIdle, SessionMessageAssistant)) and message.error is not None:
                 return message.error
@@ -85,6 +89,8 @@ def cost(self) -> float:
     @property
     def tokens(self) -> TokenUsageInfo:
         """Token usage of this run, summed over its assistant messages."""
+        from ..types import TokenUsageInfo, TokenUsageInfoCache
+
         total = TokenUsageInfo(input=0, output=0, reasoning=0, cache=TokenUsageInfoCache(read=0, write=0))
         for message in self.assistant_messages:
             usage = message.tokens
@@ -99,6 +105,8 @@ def tokens(self) -> TokenUsageInfo:
 
 
 def _new_messages(newest_first: list[SessionMessageInfo], marker: str | None) -> list[SessionMessageInfo]:
+    from ..types import SessionMessageUser
+
     collected: list[SessionMessageInfo] = []
     for message in newest_first:
         if marker is not None and message.id == marker:

src/opencode/resources/agent.py

@@ -5,18 +5,20 @@
 
 from __future__ import annotations
 
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._qs import encode_path_segment
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    AgentGetResponse,
-    AgentID,
-    AgentListResponse,
-    Location,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        AgentGetResponse,
+        AgentID,
+        AgentListResponse,
+        Location,
+    )
 
 __all__ = ["AgentResource", "AsyncAgentResource"]
 
@@ -56,7 +58,7 @@ def list(
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentListResponse,
+                response_type="AgentListResponse",
             ),
         )
 
@@ -94,7 +96,7 @@ def get(
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentGetResponse,
+                response_type="AgentGetResponse",
             ),
         )
 
@@ -134,7 +136,7 @@ async def list(
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentListResponse,
+                response_type="AgentListResponse",
             ),
         )
 
@@ -172,6 +174,6 @@ async def get(
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=AgentGetResponse,
+                response_type="AgentGetResponse",
             ),
         )

src/opencode/resources/command.py

@@ -5,15 +5,17 @@
 
 from __future__ import annotations
 
-from typing import cast
+from typing import TYPE_CHECKING, cast
 
 from .._base_client import RequestOptions
 from .._resource import AsyncAPIResource, SyncAPIResource
 from .._types import NOT_GIVEN, Body, Headers, NotGiven, Query, Timeout
-from ..types import (
-    CommandListResponse,
-    Location,
-)
+
+if TYPE_CHECKING:
+    from ..types import (
+        CommandListResponse,
+        Location,
+    )
 
 __all__ = ["CommandResource", "AsyncCommandResource"]
 
@@ -53,7 +55,7 @@ def list(
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=CommandListResponse,
+                response_type="CommandListResponse",
             ),
         )
 
@@ -93,6 +95,6 @@ async def list(
                     extra_body=extra_body,
                     timeout=timeout,
                 ),
-                response_type=CommandListResponse,
+                response_type="CommandListResponse",
             ),
         )