jXdZddlmZddlmZddlmZmZddlZddl m Z ddl m Z mZmZmZmZddlmZmZmZmZmZdd lmZmZmZdd lmZdd lmZddZ ddZ!eee"e"fZ#GddZ$dS)zEMain SandboxClient class for interacting with the sandbox server API.) annotations)Mapping)AnyOptionalN)utils)ResourceCreationErrorResourceNameConflictErrorResourceNotFoundErrorResourceTimeoutErrorSandboxAPIError)handle_client_http_errorhandle_sandbox_creation_error merge_headersvalidate_service_params validate_ttl)ResourceStatus ServiceURLSnapshot)Sandbox)RetryTransportreturnstrc^tjdd}|ddS)zGet the default sandbox API endpoint from environment. Derives the endpoint from LANGSMITH_ENDPOINT (or LANGCHAIN_ENDPOINT). ENDPOINTzhttps://api.smith.langchain.com)default/z /v2/sandboxes)ls_utils get_env_varrstrip)bases c/lsinfo/ai/hellotax_ai/base_platform/venv/lib/python3.11/site-packages/langsmith/sandbox/_client.py_get_default_api_endpointr""s5   4U V V VDkk# - - -- Optional[str]c*tjdS)z)Get the default API key from environment.API_KEY)rrr#r!_get_default_api_keyr(+s   * **r#c eZdZdZdddddddcdZdddZdedZdedZdfdZdgdZ dhd Z diddd!dddddddd" djd/Z diddd!d0dddddddd1 dkd4Z dd5dld6Z dd5dmd8Zddddd9dnd;Zdd5dod<Zdd5dpd>Zd?dd@dqdDZdEdFddGdrdIZdEddJdsdKZdd5dodLZdddddMddNdtdUZdMddJdudWZdd5dvdXZdddddYdwd^Zdd5dxd_Zd`daddGdydbZdS)z SandboxClientaClient for interacting with the Sandbox Server API. This client provides a simple interface for managing sandboxes and snapshots. Example: # Uses LANGSMITH_ENDPOINT and LANGSMITH_API_KEY from environment client = SandboxClient() # Or with explicit configuration client = SandboxClient( api_endpoint="https://api.smith.langchain.com/v2/sandboxes", api_key="your-api-key", ) # Create a sandbox from a snapshot and run commands with client.sandbox(snapshot_id="") as sandbox: result = sandbox.run("python --version") print(result.stdout) Ng$@) api_endpointtimeoutapi_key max_retriesheadersr,r$r-floatr.r/intr0Optional[RequestHeaders]c|p td|_|p t}||_i}|r||d<|rt ||}t |}tj||||_ dS)apInitialize the SandboxClient. Args: api_endpoint: Full URL of the sandbox API endpoint. If not provided, derived from LANGSMITH_ENDPOINT environment variable. timeout: Default HTTP timeout in seconds. api_key: API key for authentication. If not provided, uses LANGSMITH_API_KEY environment variable. max_retries: Maximum number of retries for transient errors (502, 503, 504), rate limits (429), and connection failures. Set to 0 to disable retries. Default: 3. rz X-Api-Key)r/) transportr-r0N) r"r _base_urlr(_api_keyrrhttpxClient_http) selfr,r-r.r/r0resolved_api_keyclient_headersr5s r!__init__zSandboxClient.__init__Hs*'E*C*E*EMMcRR"<&:&<&<( )+  ;*:N; '  D*>7CCN"{;;; \.    r#RequestHeadersrOptional[dict[str, str]]c>|dSt|jj|S)z8Merge default client headers with per-request overrides.N)rr:r0)r;r0s r!_request_headerszSandboxClient._request_headersjs! ?4TZ/999r#Nonec8|jdS)zClose the HTTP client.N)r:closer;s r!rEzSandboxClient.closeps r#cx |jjs|jdSdS#t$rYdSwxYw)z,Close the HTTP client on garbage collection.N)r: is_closedrE ExceptionrFs r!__del__zSandboxClient.__del__tsZ :' #   """"" # #    DD s %+ 99c|S)zEnter context manager.r'rFs r! __enter__zSandboxClient.__enter__|s r#exc_typeOptional[type]exc_valOptional[BaseException]exc_tb Optional[Any]c.|dS)zExit context manager.N)rE)r;rMrOrQs r!__exit__zSandboxClient.__exit__s r#rcd|jdS)zReturn a string representation of the instance. Returns: The string representation of the instance. zSandboxClient (API URL: ))r6rFs r!__repr__zSandboxClient.__repr__s <$.;;;;r# snapshot_namenamer- ttl_secondsidle_ttl_secondsvcpus mem_bytesfs_capacity_bytes proxy_configr0 snapshot_idrZr[r\ Optional[int]r]r^r_r`raOptional[dict[str, Any]]rc T|||||||||| | |  } d| _| S)a Create a sandbox and return a Sandbox instance. This is the primary method for creating sandboxes. Use it as a context manager for automatic cleanup: with client.sandbox(snapshot_id="") as sandbox: result = sandbox.run("echo hello") # Resolve by snapshot name instead of ID: with client.sandbox(snapshot_name="my-snap") as sandbox: result = sandbox.run("echo hello") The sandbox is automatically deleted when exiting the context manager. For sandboxes with manual lifecycle management, use create_sandbox(). Args: snapshot_id: Snapshot ID to boot from. Mutually exclusive with ``snapshot_name``; exactly one must be provided. snapshot_name: Snapshot name to boot from. Resolved server-side to a snapshot owned by the caller's tenant. Mutually exclusive with ``snapshot_id``; exactly one must be provided. name: Optional sandbox name (auto-generated if not provided). timeout: Timeout in seconds when waiting for ready. ttl_seconds: Maximum lifetime in seconds from creation. The sandbox will be automatically deleted after this duration. Must be a multiple of 60. 0 or None disables this TTL. idle_ttl_seconds: Idle timeout in seconds. The sandbox will be automatically deleted after this duration of inactivity. Must be a multiple of 60. ``0`` explicitly disables the idle timeout. When omitted (``None``), the server applies a default of ``600`` seconds (10 minutes). vcpus: Number of vCPUs. mem_bytes: Memory in bytes. fs_capacity_bytes: Root filesystem capacity in bytes. proxy_config: Per-sandbox proxy configuration forwarded to the server as-is. Shape matches the backend `proxy_config` field: ``{"rules": [...], "no_proxy": [...], "access_control": {"allow_list": [...]}}`` or ``{"access_control": {"deny_list": [...]}}``. Use ``access_control.allow_list`` to restrict outbound HTTPS to a set of host patterns (exact domains, globs like ``*.example.com``, IPs, CIDRs, or ``~regex``). Returns: Sandbox instance. Raises: ResourceTimeoutError: If timeout waiting for sandbox to be ready. ResourceCreationError: If sandbox creation fails. SandboxClientError: For other errors. ValueError: If TTL values are invalid, or if neither/both of ``snapshot_id`` and ``snapshot_name`` are provided. rYT)create_sandbox _auto_delete) r;rbrZr[r-r\r]r^r_r`rar0sbs r!sandboxzSandboxClient.sandboxsNH '#-/%!    r#T) rZr[r-wait_for_readyr\r]r^r_r`rar0rjboolc t|t|krtdt|dt|d|jd} d|i}|r||d<|r||d<|r||d<|r||d <|||d<|||d<|||d <| | |d <| | |d <| | |d<|r|dznd} |j| |||| }|tj | |dS#tj $r}t|d }~wwxYw)a Create a new Sandbox. The sandbox is NOT automatically deleted. Use delete_sandbox() for cleanup, or use sandbox() for automatic cleanup with a context manager. Args: snapshot_id: Snapshot ID to boot from. Mutually exclusive with ``snapshot_name``; exactly one must be provided. snapshot_name: Snapshot name to boot from. Resolved server-side to a snapshot owned by the caller's tenant. Mutually exclusive with ``snapshot_id``; exactly one must be provided. name: Optional sandbox name (auto-generated if not provided). timeout: Timeout in seconds when waiting for ready (only used when wait_for_ready=True). wait_for_ready: If True (default), block until sandbox is ready. If False, return immediately with status "provisioning". Use get_sandbox_status() or wait_for_sandbox() to poll for readiness. ttl_seconds: Maximum lifetime in seconds from creation. The sandbox will be automatically deleted after this duration. Must be a multiple of 60. 0 or None disables this TTL. idle_ttl_seconds: Idle timeout in seconds. The sandbox will be automatically deleted after this duration of inactivity. Must be a multiple of 60. ``0`` explicitly disables the idle timeout. When omitted (``None``), the server applies a default of ``600`` seconds (10 minutes). vcpus: Number of vCPUs. mem_bytes: Memory in bytes. fs_capacity_bytes: Root filesystem capacity in bytes. proxy_config: Per-sandbox proxy configuration forwarded to the server as-is. Shape matches the backend `proxy_config` field: ``{"rules": [...], "no_proxy": [...], "access_control": {"allow_list": [...]}}`` or ``{"access_control": {"deny_list": [...]}}``. Use ``access_control.allow_list`` to restrict outbound HTTPS to a set of host patterns (exact domains, globs like ``*.example.com``, IPs, CIDRs, or ``~regex``). Returns: Created Sandbox. When wait_for_ready=False, the sandbox will have status="provisioning" and cannot be used for operations until ready. Raises: ResourceTimeoutError: If timeout waiting for sandbox to be ready. ResourceCreationError: If sandbox creation fails. SandboxClientError: For other errors. ValueError: If TTL values are invalid, or if neither/both of ``snapshot_id`` and ``snapshot_name`` are provided. z7Exactly one of snapshot_id or snapshot_name must be setr\r]/boxesrjrbrZr-r[Nr^r_r`rarX)jsonr-r0Fclient auto_delete)rk ValueErrorrr6r:postrBraise_for_statusr from_dictrnr8HTTPStatusErrorr)r;rbrZr[r-rjr\r]r^r_r`rar0urlpayload http_timeoutresponsees r!rfzSandboxClient.create_sandboxs@   ] 3 3 3 3VWW W[-000%'9:::''' n#   1%0GM "  5'4GO $  )!(GI   #"GFO  "%0GM "  '*:G& '  $GG   #,GK  (+g|]}tj|dS)Fro)rru).0cr;s r! z0SandboxClient.list_sandboxes..s;!!DeDDDr# sandboxesrAPI endpoint not found: %. Check that api_endpoint is correct.N r6r:rrBrtrnr8rvrzrr r )r;r0rwrzdatar{s` r!list_sandboxeszSandboxClient.list_sandboxesus  ''' z~~c43H3H3Q3Q~RRH  % % ' ' '==??D+r22 $   z%,,%;s;;; %Q ' ' '  sA8BC4C  C)new_namer\r]r0rcJt|dt|d|jd|}i}|||d<|||d<|||d< |j||||}|t j||dS#tj $ra} | j j d krtd |d d | | j j dkrtd|dd | t| d} ~ wwxYw)aUpdate a sandbox's properties. Args: name: Current sandbox name. new_name: New display name. ttl_seconds: Maximum lifetime in seconds from creation. Must be a multiple of 60. 0 disables this TTL. idle_ttl_seconds: Idle timeout in seconds. Must be a multiple of 60. ``0`` disables this TTL. ``None`` leaves the existing value unchanged. Returns: Updated Sandbox. Raises: ResourceNotFoundError: If sandbox not found. ResourceNameConflictError: If new_name is already in use. SandboxClientError: For other errors. ValueError: If TTL values are invalid. r\r]r~Nr[rnr0FrorrrririzSandbox name 'z' already in use)rr6r:patchrBrtrrurnr8rvrzrr r r ) r;r[rr\r]r0rwrxrzr{s r!update_sandboxzSandboxClient.update_sandboxs: [-000%'9:::...."$  &GFO  "%0GM "  '*:G& ' z'''4+@+@+I+I(H  % % ' ' '$X]]__TuUUU U$   z%,,+1111z%,,/?X???"+ %Q ' ' '  sA,B22D"ADD"cJ|jd|} |j|||}|dS#t j$r@}|jjdkrtd|dd|t|Yd}~dSd}~wwxYw) zDelete a Sandbox. Args: name: Sandbox name. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. r~r|rrrrirN r6r:deleterBrtr8rvrzrr r rs r!delete_sandboxzSandboxClient.delete_sandboxs.... (z((d6K6KG6T6T(UUH  % % ' ' ' ' '$ ( ( (z%,,+1111 %Q ' ' ' ' ' ' ' ' '  (AAB""5BB"rc|jd|d} |j|||}|t j|S#tj $r;}|j j dkrtd|dd|t|d }~wwxYw) aGet the provisioning status of a sandbox. This is a lightweight endpoint designed for high-frequency polling during sandbox provisioning. It returns only the status fields without full sandbox data. Args: name: Sandbox name. Returns: ResourceStatus with status and status_message. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. r~z/statusr|rrrrirN)r6r:rrBrtrrurnr8rvrzrr r rs r!get_sandbox_statusz SandboxClient.get_sandbox_statuss&55555 z~~c43H3H3Q3Q~RRH  % % ' ' '!+HMMOO<< <$   z%,,+1111 %Q ' ' '   sA(A88C6B==CiXexpires_in_secondsr0portrrctjdd}d}dfd } j||}|t j||S#tj $r;} | j j d krtd d d | t| d} ~ wwxYw)aiGet an authenticated URL for a service running inside a sandbox. Returns a :class:`ServiceURL` whose properties auto-refresh the token transparently before it expires. The object also provides HTTP helper methods (``.get``, ``.post``, etc.) that inject the authentication header automatically. Args: name: Sandbox name. port: Port the service is listening on inside the sandbox. expires_in_seconds: Token TTL in seconds (1--86400, default 600). headers: Optional per-request header overrides. Returns: ServiceURL with auto-refreshing token and HTTP helpers. Raises: ResourceNotFoundError: If sandbox not found. ValueError: If port or expires_in_seconds is out of range. SandboxClientError: For other errors. r~z /service-url)rrrrc6S)Nr)service)rr0r[rr;sr! _refresherz)SandboxClient.service.._refresher"s*<<#5   r#r)rrrrrirN)rr)rr6r:rsrBrtrrurnr8rvrzrr r ) r;r[rrr0rwrxrrzr{s ````` r!rzSandboxClient.servicesG: &8999:::::7IJJ           z'4+@+@+I+I'H  % % ' ' '' JOOO O$   z%,,+1111 %Q ' ' '   sA+BC).6C$$C)xg?)r- poll_intervalr0rcddl}||z} |||}|jdkr|||S|jdkrt |jpdd ||z }|dkrtd |d |d d|j |t||)aPoll until a sandbox reaches "ready" or "failed" status. Uses the lightweight status endpoint for polling, then fetches the full sandbox data once ready. Args: name: Sandbox name. timeout: Maximum time to wait in seconds. poll_interval: Time between status checks in seconds. Returns: Sandbox in "ready" status. Raises: ResourceCreationError: If sandbox status becomes "failed". ResourceTimeoutError: If timeout expires while still "provisioning". ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. rNTr|readyfailedzSandbox provisioning failedrirr' not ready after sr last_status) time monotonicrstatusrrstatus_messager sleepmin) r;r[r-rr0rdeadliner remainings r!wait_for_sandboxzSandboxClient.wait_for_sandbox8s6  >>##g- 6,,T7,CCF}''''g'>>>}((+)J-J"+!4>>#3#33IA~~*BBBBBB"+ &  JJs=)44 5 5 5! 6r#r-r0cz|jd|d} |j|i||}|nQ#t j$r?}|jjdkrtd|dd|t|Yd }~nd }~wwxYw| ||| S) aStart a stopped sandbox and wait until ready. Args: name: Sandbox name. timeout: Timeout in seconds when waiting for ready. Returns: Sandbox in "ready" status. Raises: ResourceNotFoundError: If sandbox not found. ResourceCreationError: If sandbox fails during startup. ResourceTimeoutError: If sandbox doesn't become ready within timeout. SandboxClientError: For other errors. r~z/startrrrrrirNr) r6r:rsrBrtr8rvrzrr r r)r;r[r-r0rwrzr{s r! start_sandboxzSandboxClient.start_sandboxhs,44444 (z"d&;&;G&D&D'H  % % ' ' ' '$ ( ( (z%,,+1111 %Q ' ' ' ' ' ' ' '  ($$T7G$LLLsAAB"#5BB"cN|jd|d} |j|i||}|d S#t j$r@}|jjdkrtd|dd|t|Yd }~d Sd }~wwxYw) zStop a running sandbox (preserves sandbox files for later restart). Args: name: Sandbox name. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. r~z/stoprrrrrirN) r6r:rsrBrtr8rvrzrr r rs r! stop_sandboxzSandboxClient.stop_sandboxs33333 (z"d&;&;G&D&D'H  % % ' ' ' ' '$ ( ( (z%,,+1111 %Q ' ' ' ' ' ' ' ' '  (sAAB$$5BB$<) registry_id registry_urlregistry_usernameregistry_passwordr-r0 docker_imagerrrrrc|jd} |||d} ||| d<||| d<||| d<||| d< |j| | || } | t j| } n'#tj $r}t|d}~wwxYw| | j || S) alBuild a snapshot from a Docker image. Blocks until the snapshot is ready (polls with 2s interval). Args: name: Snapshot name. docker_image: Docker image to build from (e.g., "python:3.12-slim"). fs_capacity_bytes: Filesystem capacity in bytes. registry_id: Private registry ID (alternative to URL/credentials). registry_url: Registry URL for private images. registry_username: Registry username. registry_password: Registry password. timeout: Timeout in seconds when waiting for ready. Returns: Snapshot in "ready" status. Raises: ResourceTimeoutError: If snapshot doesn't become ready within timeout. ResourceCreationError: If snapshot build fails. SandboxClientError: For other errors. /snapshots)r[rr`Nrrrrrr) r6r:rsrBrtrrurnr8rvr wait_for_snapshotid)r;r[rr`rrrrr-r0rwrxrzsnapshotr{s r!create_snapshotzSandboxClient.create_snapshots$F+++(!2# #   "%0GM "  #&2GN #  (+>C 6CCc|jd|} |j|||}|t j|S#tj $r;}|j j dkrtd|dd|t|d}~wwxYw) zGet a snapshot by ID. Args: snapshot_id: Snapshot UUID. Returns: Snapshot. Raises: ResourceNotFoundError: If snapshot not found. SandboxClientError: For other errors. /snapshots/r|r Snapshot 'rrrN)r6r:rrBrtrrurnr8rvrzrr r r;rbr0rwrzr{s r! get_snapshotzSandboxClient.get_snapshots99K99 z~~c43H3H3Q3Q~RRH  % % ' ' '%hmmoo66 6$   z%,,+9999 %Q ' ' '   sA(A77C6B<<C) name_containslimitoffsetr0rrrlist[Snapshot]c|jd}i}|||d<|||d<|||d< |j||pd||}||}d|dgDS#t j$r9} | jj d krtd |d | t| d} ~ wwxYw) aVList snapshots. The backend always paginates this endpoint. When ``limit`` is omitted the server applies a default page size (currently 50), so a single call is not guaranteed to return every snapshot. To iterate through all results, repeat the call with increasing ``offset`` values (or an explicit ``limit``) until fewer than ``limit`` snapshots come back. Args: name_contains: Optional case-insensitive substring filter applied to snapshot names server-side. limit: Optional maximum number of snapshots to return for a single request. Must be between 1 and 500 (inclusive); the server rejects values outside that range. Defaults to 50 server-side when omitted. offset: Optional number of snapshots to skip before returning results. Must be ``>= 0``. Useful for paginating through large result sets in combination with ``limit``. Returns: A single page of Snapshots matching the provided filters. rNrrr)paramsr0c6g|]}tj|Sr')rru)rrs r!rz0SandboxClient.list_snapshots..ds#MMMaH&q))MMMr# snapshotsrrrr) r;rrrr0rwrrzrr{s r!list_snapshotszSandboxClient.list_snapshots4s7<+++!#  $&3F? #  #F7O  %F8  z~~~--g66&H  % % ' ' '==??DMM488K3L3LMMM M$   z%,,%;s;;; %Q ' ' '  sA9BC%,4C  C%cJ|jd|} |j|||}|dS#t j$r@}|jjdkrtd|dd|t|Yd}~dSd}~wwxYw) zDelete a snapshot. Args: snapshot_id: Snapshot UUID. Raises: ResourceNotFoundError: If snapshot not found. SandboxClientError: For other errors. rr|rrrrrNrrs r!delete_snapshotzSandboxClient.delete_snapshotns99K99 (z((d6K6KG6T6T(UUH  % % ' ' ' ' '$ ( ( (z%,,+9999 %Q ' ' ' ' ' ' ' ' '  (ri,g@cddl}||z} |||}|jdkr|S|jdkrt |jpdd ||z }|dkrt d |d |d d|j |t||)a&Poll until a snapshot reaches "ready" or "failed" status. Args: snapshot_id: Snapshot UUID. timeout: Maximum time to wait in seconds. poll_interval: Time between status checks in seconds. Returns: Snapshot in "ready" status. Raises: ResourceCreationError: If snapshot status becomes "failed". ResourceTimeoutError: If timeout expires. ResourceNotFoundError: If snapshot not found. SandboxClientError: For other errors. rNTr|rrzSnapshot build failedrrrrrr) rrrrrrr rr) r;rbr-rr0rrrrs r!rzSandboxClient.wait_for_snapshots0  >>##g- 6((g(FFH'))(**++F/F",!4>>#3#33IA~~*JJJJJJ", ( JJs=)44 5 5 5! 6r#) r,r$r-r1r.r$r/r2r0r3)r0r?rr@)rrC)rr*)rMrNrOrPrQrRrrCrr)N)rbr$rZr$r[r$r-r2r\rcr]rcr^rcr_rcr`rcrardr0r?rr)rbr$rZr$r[r$r-r2rjrkr\rcr]rcr^rcr_rcr`rcrardr0r?rr)r[rr0r?rr)r0r?rr) r[rrr$r\rcr]rcr0r?rr)r[rr0r?rrC)r[rr0r?rr) r[rrr2rr2r0r?rr) r[rr-r2rr1r0r?rr)r[rr-r2r0r?rr)r[rrrr`r2rr$rr$rr$rr$r-r2r0r?rr) rrr[rr-r2r0r?rr)rbrr0r?rr) rr$rrcrrcr0r?rr)rbrr0r?rrC) rbrr-r2rr1r0r?rr)__name__ __module__ __qualname____doc__r>rBrErJrLrTrWrirfrrrrrrrrrrrrrrrr'r#r!r*r*3s.'+!%,0       D:::: <<<<&*R(,"%)*.##'+/15"&RRRRRRl&*m(,"#%)*.##'+/15"&mmmmmm^CG:;?:#'%)*."&::::::xFJ((((((.7;L#&"& 555555v""& .6.6.6.6.6.6h"& $M$M$M$M$M$MLDH((((((D&*&*+/+/"&=U=U=U=U=U=UH"& ,U,U,U,U,U,U^>B@(,# $"& 888888v>B((((((8""& +6+6+6+6+6+6+6+6r#r*r)rr$)%r __future__rcollections.abcrtypingrrr8 langsmithrrlangsmith.sandbox._exceptionsrr r r r langsmith.sandbox._helpersr rrrrlangsmith.sandbox._modelsrrrlangsmith.sandbox._sandboxrlangsmith.sandbox._transportrr"r(rr?r*r'r#r!rsKK""""""###### '''''' /.....777777....++++ '#s(+,~ 6~ 6~ 6~ 6~ 6~ 6~ 6~ 6~ 6~ 6r#