Samfinton/stg 1147 python sdk rename create() to start() (#295)

monadoid · web-flow · commit 74cb7fb1806d · 2026-01-16T11:21:56.000-07:00
* - Renamed session.create() helper to session.start() to remain in sync with docs

* lint fix
diff --git a/README.md b/README.md
@@ -160,7 +160,7 @@ async def main() -> None:
     client = AsyncStagehand()
 
     # Start a new browser session (returns a session helper bound to a session_id)
-    session = await client.sessions.create(model_name="openai/gpt-5-nano")
+    session = await client.sessions.start(model_name="openai/gpt-5-nano")
 
     print(f"Session started: {session.id}")
 
@@ -308,7 +308,7 @@ from stagehand import AsyncStagehand
 
 async def main() -> None:
     client = AsyncStagehand()
-    session = await client.sessions.create(model_name="openai/gpt-5-nano")
+    session = await client.sessions.start(model_name="openai/gpt-5-nano")
     response = await session.act(input="click the first link on the page")
     print(response.data)
 
@@ -335,7 +335,7 @@ from stagehand import AsyncStagehand, DefaultAioHttpClient
 
 async def main() -> None:
     async with AsyncStagehand(http_client=DefaultAioHttpClient()) as client:
-        session = await client.sessions.create(model_name="openai/gpt-5-nano")
+        session = await client.sessions.start(model_name="openai/gpt-5-nano")
         response = await session.act(input="click the first link on the page")
         print(response.data)
 
@@ -360,7 +360,7 @@ from stagehand import AsyncStagehand
 
 async def main() -> None:
     async with AsyncStagehand() as client:
-        session = await client.sessions.create(model_name="openai/gpt-5-nano")
+        session = await client.sessions.start(model_name="openai/gpt-5-nano")
 
         stream = await client.sessions.act(
             id=session.id,
diff --git a/examples/act_example.py b/examples/act_example.py
@@ -28,7 +28,7 @@ async def main() -> None:
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         # Start a new browser session
-        session = await client.sessions.create(
+        session = await client.sessions.start(
             model_name="openai/gpt-5-nano",
         )
 
diff --git a/examples/agent_execute.py b/examples/agent_execute.py
@@ -27,7 +27,7 @@ async def main() -> None:
     # with missing fields set to None).
     async with AsyncStagehand(_strict_response_validation=True) as client:
         try:
-            session = await client.sessions.create(model_name=model_name)
+            session = await client.sessions.start(model_name=model_name)
         except APIResponseValidationError as e:
             print("Session start response failed schema validation.")
             print(f"Base URL: {client.base_url!r}")
diff --git a/examples/byob_example.py b/examples/byob_example.py
@@ -36,7 +36,7 @@ async def main() -> None:
     ) as client, async_playwright() as playwright:
         browser = await playwright.chromium.launch(headless=True)
         page = await browser.new_page()
-        session = await client.sessions.create(model_name="openai/gpt-5-nano")
+        session = await client.sessions.start(model_name="openai/gpt-5-nano")
 
         try:
             target_url = "https://news.ycombinator.com"
diff --git a/examples/full_example.py b/examples/full_example.py
@@ -30,7 +30,7 @@ async def main() -> None:
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         # Start a new browser session (returns a session helper bound to a session_id)
-        session = await client.sessions.create(
+        session = await client.sessions.start(
             model_name="openai/gpt-5-nano",
         )
 
diff --git a/examples/logging_example.py b/examples/logging_example.py
@@ -21,7 +21,7 @@ async def main() -> None:
         model_api_key=os.environ.get("MODEL_API_KEY"),
     ) as client:
         # Start a new browser session with verbose logging enabled
-        session = await client.sessions.create(
+        session = await client.sessions.start(
             model_name="openai/gpt-5-nano",
             verbose=2,
         )
diff --git a/examples/playwright_page_example.py b/examples/playwright_page_example.py
@@ -55,7 +55,7 @@ def main() -> None:
         model_api_key=model_api_key,
     ) as client:
         print("⏳ Starting Stagehand session...")
-        session = client.sessions.create(
+        session = client.sessions.start(
             model_name="openai/gpt-5-nano",
             browser={"type": "browserbase"},
         )
@@ -115,4 +115,3 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
-
diff --git a/examples/pydoll_tab_example.py b/examples/pydoll_tab_example.py
@@ -120,7 +120,7 @@ async def main() -> None:
         model_api_key=model_api_key,
     ) as client:
         print("⏳ Starting Stagehand session...")
-        session = await client.sessions.create(
+        session = await client.sessions.start(
             model_name="openai/gpt-5-nano",
             browser={"type": "browserbase"},
         )
diff --git a/src/stagehand/_client.py b/src/stagehand/_client.py
@@ -51,8 +51,8 @@
 
 class Stagehand(SyncAPIClient):
     # client options
-    browserbase_api_key: str
-    browserbase_project_id: str
+    browserbase_api_key: str | None
+    browserbase_project_id: str | None
     model_api_key: str
 
     def __init__(
@@ -299,7 +299,7 @@ def copy(
         )
 
     # Alias for `copy` for nicer inline usage, e.g.
-    # client.with_options(timeout=10).foo.create(...)
+    # client.with_options(timeout=10).foo.start(...)
     with_options = copy
 
     @override
@@ -338,8 +338,8 @@ def _make_status_error(
 
 class AsyncStagehand(AsyncAPIClient):
     # client options
-    browserbase_api_key: str
-    browserbase_project_id: str
+    browserbase_api_key: str | None
+    browserbase_project_id: str | None
     model_api_key: str
 
     def __init__(
@@ -585,7 +585,7 @@ def copy(
         )
 
     # Alias for `copy` for nicer inline usage, e.g.
-    # client.with_options(timeout=10).foo.create(...)
+    # client.with_options(timeout=10).foo.start(...)
     with_options = copy
 
     @override
diff --git a/src/stagehand/resources/sessions.py b/src/stagehand/resources/sessions.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Dict, Union
 from datetime import datetime, timezone
 from typing_extensions import Literal, overload
 
@@ -30,6 +30,7 @@
     async_to_streamed_response_wrapper,
 )
 from .._streaming import Stream, AsyncStream
+from .._exceptions import StagehandError
 from .._base_client import make_request_options
 from ..types.stream_event import StreamEvent
 from ..types.session_act_response import SessionActResponse
@@ -39,7 +40,6 @@
 from ..types.session_extract_response import SessionExtractResponse
 from ..types.session_observe_response import SessionObserveResponse
 from ..types.session_navigate_response import SessionNavigateResponse
-from .._exceptions import StagehandError
 
 __all__ = ["SessionsResource", "AsyncSessionsResource"]
 
@@ -62,9 +62,7 @@ def _requires_browserbase_credentials(
     if not is_given(browser):
         return True
 
-    browser_type = None
-    if isinstance(browser, dict):
-        browser_type = browser.get("type")
+    browser_type = browser.get("type")
 
     return browser_type != "local"
 
diff --git a/src/stagehand/resources/sessions_helpers.py b/src/stagehand/resources/sessions_helpers.py
@@ -4,19 +4,68 @@
 
 from typing import Union
 from datetime import datetime
-from typing_extensions import Literal
+from typing_extensions import Literal, override
 
 import httpx
 
 from ..types import session_start_params
 from .._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
+from .._compat import cached_property
 from ..session import Session, AsyncSession
-from .sessions import SessionsResource, AsyncSessionsResource
+from .sessions import (
+    SessionsResource,
+    AsyncSessionsResource,
+    SessionsResourceWithRawResponse,
+    AsyncSessionsResourceWithRawResponse,
+    SessionsResourceWithStreamingResponse,
+    AsyncSessionsResourceWithStreamingResponse,
+)
+from .._response import (
+    to_raw_response_wrapper,
+    to_streamed_response_wrapper,
+    async_to_raw_response_wrapper,
+    async_to_streamed_response_wrapper,
+)
 from ..types.session_start_response import SessionStartResponse
 
 
+class SessionsResourceWithHelpersRawResponse(SessionsResourceWithRawResponse):
+    def __init__(self, sessions: SessionsResourceWithHelpers) -> None:  # type: ignore[name-defined]
+        super().__init__(sessions)
+        self.start = to_raw_response_wrapper(super(SessionsResourceWithHelpers, sessions).start)
+
+
+class SessionsResourceWithHelpersStreamingResponse(SessionsResourceWithStreamingResponse):
+    def __init__(self, sessions: SessionsResourceWithHelpers) -> None:  # type: ignore[name-defined]
+        super().__init__(sessions)
+        self.start = to_streamed_response_wrapper(super(SessionsResourceWithHelpers, sessions).start)
+
+
+class AsyncSessionsResourceWithHelpersRawResponse(AsyncSessionsResourceWithRawResponse):
+    def __init__(self, sessions: AsyncSessionsResourceWithHelpers) -> None:  # type: ignore[name-defined]
+        super().__init__(sessions)
+        self.start = async_to_raw_response_wrapper(super(AsyncSessionsResourceWithHelpers, sessions).start)
+
+
+class AsyncSessionsResourceWithHelpersStreamingResponse(AsyncSessionsResourceWithStreamingResponse):
+    def __init__(self, sessions: AsyncSessionsResourceWithHelpers) -> None:  # type: ignore[name-defined]
+        super().__init__(sessions)
+        self.start = async_to_streamed_response_wrapper(super(AsyncSessionsResourceWithHelpers, sessions).start)
+
+
 class SessionsResourceWithHelpers(SessionsResource):
-    def create(
+    @cached_property
+    @override
+    def with_raw_response(self) -> SessionsResourceWithHelpersRawResponse:
+        return SessionsResourceWithHelpersRawResponse(self)
+
+    @cached_property
+    @override
+    def with_streaming_response(self) -> SessionsResourceWithHelpersStreamingResponse:
+        return SessionsResourceWithHelpersStreamingResponse(self)
+
+    @override
+    def start(
         self,
         *,
         model_name: str,
@@ -37,7 +86,7 @@ def create(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Session:
-        start_response = self.start(
+        start_response = super().start(
             model_name=model_name,
             act_timeout_ms=act_timeout_ms,
             browser=browser,
@@ -60,7 +109,18 @@ def create(
 
 
 class AsyncSessionsResourceWithHelpers(AsyncSessionsResource):
-    async def create(
+    @cached_property
+    @override
+    def with_raw_response(self) -> AsyncSessionsResourceWithHelpersRawResponse:
+        return AsyncSessionsResourceWithHelpersRawResponse(self)
+
+    @cached_property
+    @override
+    def with_streaming_response(self) -> AsyncSessionsResourceWithHelpersStreamingResponse:
+        return AsyncSessionsResourceWithHelpersStreamingResponse(self)
+
+    @override
+    async def start(
         self,
         *,
         model_name: str,
@@ -81,7 +141,7 @@ async def create(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AsyncSession:
-        start_response: SessionStartResponse = await self.start(
+        start_response: SessionStartResponse = await super().start(
             model_name=model_name,
             act_timeout_ms=act_timeout_ms,
             browser=browser,
diff --git a/src/stagehand/session.py b/src/stagehand/session.py
diff --git a/tests/test_local_server.py b/tests/test_local_server.py
diff --git a/tests/test_session_page_param.py b/tests/test_session_page_param.py
diff --git a/tests/test_sessions_create_helper.py b/tests/test_sessions_create_helper.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ async def main() -> None:`
`28`	`28`	`model_api_key=os.environ.get("MODEL_API_KEY"),`
`29`	`29`	`) as client:`
`30`	`30`	`# Start a new browser session`
`31`		`- session = await client.sessions.create(`
	`31`	`+ session = await client.sessions.start(`
`32`	`32`	`model_name="openai/gpt-5-nano",`
`33`	`33`	`)`
`34`	`34`
Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,7 @@ async def main() -> None:`
`30`	`30`	`model_api_key=os.environ.get("MODEL_API_KEY"),`
`31`	`31`	`) as client:`
`32`	`32`	`# Start a new browser session (returns a session helper bound to a session_id)`
`33`		`- session = await client.sessions.create(`
	`33`	`+ session = await client.sessions.start(`
`34`	`34`	`model_name="openai/gpt-5-nano",`
`35`	`35`	`)`
`36`	`36`
Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@ async def main() -> None:`
`21`	`21`	`model_api_key=os.environ.get("MODEL_API_KEY"),`
`22`	`22`	`) as client:`
`23`	`23`	`# Start a new browser session with verbose logging enabled`
`24`		`- session = await client.sessions.create(`
	`24`	`+ session = await client.sessions.start(`
`25`	`25`	`model_name="openai/gpt-5-nano",`
`26`	`26`	`verbose=2,`
`27`	`27`	`)`
Original file line number	Diff line number	Diff line change
`@@ -120,7 +120,7 @@ async def main() -> None:`
`120`	`120`	`model_api_key=model_api_key,`
`121`	`121`	`) as client:`
`122`	`122`	`print("⏳ Starting Stagehand session...")`
`123`		`- session = await client.sessions.create(`
	`123`	`+ session = await client.sessions.start(`
`124`	`124`	`model_name="openai/gpt-5-nano",`
`125`	`125`	`browser={"type": "browserbase"},`
`126`	`126`	`)`