Zǻi8|dZddlmZddlmZmZddlZddlmZ ddl m Z m Z m Z mZmZmZmZddlmZmZmZmZmZddlmZmZmZmZmZdd lmZdd l m!Z!dd Z"dd Z#Gd dZ$y)zEMain SandboxClient class for interacting with the sandbox server API.) annotations)AnyOptionalN)utils)ResourceCreationErrorResourceInUseErrorResourceNameConflictErrorResourceNotFoundErrorResourceTimeoutErrorSandboxAPIErrorValidationError)handle_client_http_errorhandle_pool_errorhandle_sandbox_creation_errorhandle_volume_creation_errorparse_error_response)PoolResourceStatusSandboxTemplateVolumeVolumeMountSpec)Sandbox)RetryTransportcXtjdd}|jddS)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 W/opt/lhia/marcimex/agent/venv/lib/python3.12/site-packages/langsmith/sandbox/_client.py_get_default_api_endpointr#%s.    4U VDkk# } --c,tjdS)z)Get the default API key from environment.API_KEY)rrr$r"_get_default_api_keyr(.s    **r$ceZdZdZddddd d0dZd1dZd1dZd2d Z d3d Zd d  d4d Z d5dZ d6dZ d7dZ ddd d8dZ ddddd d9dZd:dZd;dZddZd?dZddd d@d Zd7d!Zddd" dAd#Zddd$d% dBd&ZdCd'ZdDd(ZdEd)Zd7d*ZdFd+Zd,d-d. dGd/Zy)H SandboxClientaClient for interacting with the Sandbox Server API. This client provides a simple interface for managing sandboxes and templates. 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 and run commands with client.sandbox(template_name="python-sandbox") as sandbox: result = sandbox.run("python --version") print(result.stdout) Ng$@) api_endpointtimeoutapi_key max_retriesc|xs tjd|_|xs t}||_i}|r||d<t |}t j||||_y)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-headersN) r#r _base_urlr(_api_keyrhttpxClient_http)selfr,r-r.r/resolved_api_keyr2r1s r"__init__zSandboxClient.__init__Hsf('E*C*EMMcR"<&:&<( "$ #3GK "{; \\IwPWX r$c8|jjy)zClose the HTTP client.N)r7closer8s r"r<zSandboxClient.closees r$c |jjs|jjyy#t$rYywxYw)z,Close the HTTP client on garbage collection.N)r7 is_closedr< Exceptionr=s r"__del__zSandboxClient.__del__is; ::''   "(   s04 AAc|S)zEnter context manager.r'r=s r" __enter__zSandboxClient.__enter__qs r$c$|jy)zExit context manager.N)r<)r8exc_typeexc_valexc_tbs r"__exit__zSandboxClient.__exit__us  r$<)r-c&|jd}||d|d} |jj|||dz}|jt j |j S#tj$r}t|d}~wwxYw)a6Create a new persistent volume. Creates a persistent storage volume that can be referenced in templates. Args: name: Volume name. size: Storage size (e.g., "1Gi", "10Gi"). timeout: Timeout in seconds when waiting for ready (min: 5, max: 300). Returns: Created Volume. Raises: VolumeProvisioningError: If volume provisioning fails. ResourceTimeoutError: If volume doesn't become ready within timeout. SandboxClientError: For other errors. /volumesT)namesizewait_for_readyr-jsonr-N) r3r7postraise_for_statusr from_dictrQr5HTTPStatusErrorr)r8rLrMr-urlpayloadresponsees r" create_volumezSandboxClient.create_volumes0 )"   zzs'B,OH  % % '##HMMO4 4$$  ( +  sAA,,B? B  Bcf|jd|} |jj|}|jt j |j S#tj$r<}|jjdk(rtd|dd|t|d}~wwxYw)zGet a volume by name. Args: name: Volume name. Returns: Volume. Raises: ResourceNotFoundError: If volume not found. SandboxClientError: For other errors. /volumes/Volume ' ' not foundvolume resource_typeN) r3r7getrSrrTrQr5rUrX status_coder rr8rLrVrXrYs r" get_volumezSandboxClient.get_volumes $0 zz~~c*H  % % '##HMMO4 4$$ zz%%,+tfK0 %Q '   A A!!B047B++B0c|jd} |jj|}|j|j }|jdgDcgc]}t j |c}Scc}w#tj$r:}|jjdk(rtd|d|t|d}~wwxYw)zIList all volumes. Returns: List of Volumes. rKvolumesr]API endpoint not found: %. Check that api_endpoint is correct.N) r3r7rcrSrQrrTr5rUrXrdr r)r8rVrXdatavrYs r" list_volumeszSandboxClient.list_volumess  ) zz~~c*H  % % '==?D15)R1HIAF$$Q'I II$$ zz%%,%.se4:; %Q '  *AB A?<B?BC5C  Cc|jd|} |jj|}|jy #tj $ru}|j jdk(rtd|dd||j jdk(rt|}t|dd|t|Yd }~y d }~wwxYw) aDelete a volume. Args: name: Volume name. Raises: ResourceNotFoundError: If volume not found. ResourceInUseError: If volume is referenced by templates. SandboxClientError: For other errors. r\r]r^r_r`ramessageN r3r7deleterSr5rUrXrdr rrrr8rLrVrXrYrls r" delete_volumezSandboxClient.delete_volumes $0 (zz((-H  % % '$$ (zz%%,+tfK0zz%%,+A.(iQWXX $Q ' ' (+?CA+CC)new_namerMc|jd|}i}|||d<|||d<|s|j|S |jj||}|j t j |jS#tj$r}|jjdk(rtd|dd ||jjd k(rt|}t|d d ||jjdk(rt|}t|d d |t!|d}~wwxYw)aUpdate a volume's name and/or size. You can update the display name, size, or both in a single request. Only storage size increases are allowed (storage backend limitation). Args: name: Current volume name. new_name: New display name (optional). size: New storage size (must be >= current size). Optional. Returns: Updated Volume. Raises: ResourceNotFoundError: If volume not found. VolumeResizeError: If storage decrease attempted. ResourceNameConflictError: If new_name is already in use. SandboxQuotaExceededError: If storage quota would be exceeded. SandboxClientError: For other errors. r\NrLrMrQr]r^r_r`rairr VolumeResize) error_typerq)r3rfr7patchrSrrTrQr5rUrXrdr rr r r) r8rLrxrMrVrWrXrYrls r" update_volumezSandboxClient.update_volumesI6 $0"$  &GFO  "GFO??4( ( zz'''':H  % % '##HMMO4 4$$ zz%%,+tfK0zz%%,+A.%d9o.QWXXzz%%,+A./O8 %Q '  sABD?B!D::D?500m512Mi)cpumemorystorage volume_mountsc|jd}||||dd}|r||dd<|r*|D cgc]} | j| jdc} |d< |jj ||} | j t j| jScc} w#tj$r} t| d } ~ wwxYw) aCreate a new SandboxTemplate. Only the container image, resource limits, and volume mounts can be configured. All other container details are handled by the server. Args: name: Template name. image: Container image (e.g., "python:3.12-slim"). cpu: CPU limit (e.g., "500m", "1", "2"). Default: "500m". memory: Memory limit (e.g., "256Mi", "1Gi"). Default: "512Mi". storage: Ephemeral storage limit (e.g., "1Gi"). Optional. volume_mounts: List of volumes to mount in the sandbox. Optional. Returns: Created SandboxTemplate. Raises: SandboxClientError: If creation fails. /templates)rr)rLimage resourcesrr) volume_name mount_pathrrzN) r3rrr7rRrSrrTrQr5rUr) r8rLrrrrrrVrWvmrXrYs r"create_templatezSandboxClient.create_template4s: + #  .5GK  + ((!#bmmL(GO $  zzs9H  % % '",,X]]_= =($$  $Q '  s B AB%%C 8 CC cf|jd|} |jj|}|jt j |j S#tj$r<}|jjdk(rtd|dd|t|d}~wwxYw)aGet a SandboxTemplate by name. Args: name: Template name. Returns: SandboxTemplate. Raises: ResourceNotFoundError: If template not found. SandboxClientError: For other errors. /templates/r] Template 'r_templateraN) r3r7rcrSrrTrQr5rUrXrdr rres r" get_templatezSandboxClient.get_templateks D62 zz~~c*H  % % '",,X]]_= =$$ zz%%,+ k2* %Q '   rgc|jd} |jj|}|j|j }|jdgDcgc]}t j |c}Scc}w#tj$r:}|jjdk(rtd|d|t|d}~wwxYw)z[List all SandboxTemplates. Returns: List of SandboxTemplates. r templatesr]rjrkN) r3r7rcrSrQrrTr5rUrXrdr r)r8rVrXrltrYs r"list_templateszSandboxClient.list_templatess  + zz~~c*H  % % '==?D:>((;PR:STQO--a0T TT$$ zz%%,%.se4:; %Q '  roc|jd|}d|i} |jj||}|jt j |j S#tj$rq}|jjdk(rtd|dd||jjd k(rt|}t|d d|t|d }~wwxYw) aUpdate a template's display name. Args: name: Current template name. new_name: New display name. Returns: Updated SandboxTemplate. Raises: ResourceNotFoundError: If template not found. ResourceNameConflictError: If new_name is already in use. SandboxClientError: For other errors. rrLrzr]rr_rrarqrrN)r3r7r}rSrrTrQr5rUrXrdr rr r)r8rLrxrVrWrXrYrls r"update_templatezSandboxClient.update_templates D628$ zz'''':H  % % '",,X]]_= =$$ zz%%,+ k2*zz%%,+A./O: %Q '  sAA''C+:A,C&&C+c|jd|} |jj|}|jy #tj $ru}|j jdk(rtd|dd||j jdk(rt|}t|dd|t|Yd }~y d }~wwxYw) a Delete a SandboxTemplate. Args: name: Template name. Raises: ResourceNotFoundError: If template not found. ResourceInUseError: If template is referenced by sandboxes or pools. SandboxClientError: For other errors. rr]rr_rrarqrrNrsrus r"delete_templatezSandboxClient.delete_templates D62 (zz((-H  % % '$$ (zz%%,+ k2*zz%%,+A.(O: %Q ' ' (rwrOc,|jd}|||d|d} |dz}|jj|||}|jt j |j S#tj$r} t| d} ~ wwxYw)aCreate a new Sandbox Pool. Pools pre-provision sandboxes from a template for faster startup. Args: name: Pool name (lowercase letters, numbers, hyphens; max 63 chars). template_name: Name of the SandboxTemplate to use (no volume mounts). replicas: Number of sandboxes to pre-provision (1-100). timeout: Timeout in seconds when waiting for ready (10-600). Returns: Created Pool. Raises: ResourceNotFoundError: If template not found. ValidationError: If template has volumes attached. ResourceAlreadyExistsError: If pool with this name already exists. ResourceTimeoutError: If pool doesn't reach ready state within timeout. SandboxQuotaExceededError: If organization quota is exceeded. SandboxClientError: For other errors. /poolsT)rL template_namereplicasrNr-rOrPN) r3r7rRrSrrTrQr5rUr) r8rLrrr-rVrW http_timeoutrXrYs r" create_poolzSandboxClient.create_pools: '* " #  "R>(--/2 2$$  a  sAA//B BBcf|jd|} |jj|}|jt j |j S#tj$r<}|jjdk(rtd|dd|t|d}~wwxYw)zGet a Pool by name. Args: name: Pool name. Returns: Pool. Raises: ResourceNotFoundError: If pool not found. SandboxClientError: For other errors. /pools/r]Pool 'r_poolraN) r3r7rcrSrrTrQr5rUrXrdr rres r"get_poolzSandboxClient.get_pools v. zz~~c*H  % % '>>(--/2 2$$ zz%%,+TF+.f %Q '   rgc|jd} |jj|}|j|j }|jdgDcgc]}t j |c}Scc}w#tj$r:}|jjdk(rtd|d|t|d}~wwxYw)zEList all Pools. Returns: List of Pools. rpoolsr]rjrkN) r3r7rcrSrQrrTr5rUrXrdr r)r8rVrXrlprYs r" list_poolszSandboxClient.list_pools*s  ' zz~~c*H  % % '==?D/3xx/DE!DNN1%E EE$$ zz%%,%.se4:; %Q '  ro)rxrc|jd|}i}|||d<|||d<|s|j|S |jj||}|j t j |jS#tj$rq}|jjdk(rtd|dd ||jjd k(rt|}t|d d |t|d}~wwxYw) aUpdate a Pool's name and/or replica count. You can update the display name, replica count, or both. The template reference cannot be changed after creation. Args: name: Current pool name. new_name: New display name (optional). replicas: New number of replicas (0-100). Set to 0 to pause. Returns: Updated Pool. Raises: ResourceNotFoundError: If pool not found. ValidationError: If template was deleted. ResourceNameConflictError: If new_name is already in use. SandboxQuotaExceededError: If quota exceeded when scaling up. SandboxClientError: For other errors. rNrLrrzr]rr_rrarqrr)r3rr7r}rSrrTrQr5rUrXrdr rr r) r8rLrxrrVrWrXrYrls r" update_poolzSandboxClient.update_pool@s6 v."$  &GFO  "*GJ ==& & zz'''':H  % % '>>(--/2 2$$ zz%%,+TF+.fzz%%,+A./O6 a  sABD A,DD c*|jd|} |jj|}|jy#tj $r@}|j jdk(rtd|dd|t|Yd}~yd}~wwxYw)zDelete a Pool. This will terminate all sandboxes in the pool. Args: name: Pool name. Raises: ResourceNotFoundError: If pool not found. SandboxClientError: For other errors. rr]rr_rraN r3r7rtrSr5rUrXrdr rres r" delete_poolzSandboxClient.delete_poolxs v. (zz((-H  % % '$$ (zz%%,+TF+.f %Q ' '  (+?B6B  B)rLr-c<|j|||}d|_|S)aCreate 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(template_name="my-template") 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: template_name: Name of the SandboxTemplate to use. name: Optional sandbox name (auto-generated if not provided). timeout: Timeout in seconds when waiting for ready. Returns: Sandbox instance. Raises: ResourceTimeoutError: If timeout waiting for sandbox to be ready. ResourceCreationError: If sandbox creation fails. SandboxClientError: For other errors. )rrLr-T)create_sandbox _auto_delete)r8rrLr-sbs r"sandboxzSandboxClient.sandboxs0> '!   r$T)rLr-rNcP|jd}||d}|r||d<|r||d<|r|dznd} |jj|||}|jt j |j |dS#tj$r} t| d } ~ wwxYw) a3Create 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: template_name: Name of the SandboxTemplate to use. 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. 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. /boxes)rrNr-rLrOrPFclient auto_deleteN) r3r7rRrSrrTrQr5rUr) r8rrLr-rNrVrWrrXrYs r"rzSandboxClient.create_sandboxs> '+,#  !(GI  "GFO)7" R  zzs,OH  % % '$$X]]_TuU U$$  )! ,  sABB% B  B%cl|jd|} |jj|}|jt j |j |dS#tj$r<}|jjdk(rtd|dd|t|d }~wwxYw) aFGet a Sandbox by name. The sandbox is NOT automatically deleted. Use delete_sandbox() for cleanup. Args: name: Sandbox name. Returns: Sandbox. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. /boxes/Frr] Sandbox 'r_rraN) r3r7rcrSrrTrQr5rUrXrdr rres r" get_sandboxzSandboxClient.get_sandboxs v. zz~~c*H  % % '$$X]]_TuU U$$ zz%%,+v[1 %Q '   sAA$$B377B..B3c|jd} |jj|}|j|j }|jdgDcgc]}t j ||dc}Scc}w#tj$r:}|jjdk(rtd|d|t|d}~wwxYw) zMList all Sandboxes. Returns: List of Sandboxes. r sandboxesFrr]rjrkN) r3r7rcrSrQrrTr5rUrXrdr r)r8rVrXrlcrYs r"list_sandboxeszSandboxClient.list_sandboxes s  ' zz~~c*H  % % '==?D+r2!!!DeD $$ zz%%,%.se4:; %Q '  s*AB B?BBC5CCc|jd|}d|i} |jj||}|jt j |j |dS#tj$rg}|jjdk(rtd|dd ||jjd k(rtd |d d |t|d}~wwxYw)ayUpdate a sandbox's display name. Args: name: Current sandbox name. new_name: New display name. Returns: Updated Sandbox. Raises: ResourceNotFoundError: If sandbox not found. ResourceNameConflictError: If new_name is already in use. SandboxClientError: For other errors. rrLrzFrr]rr_rrarqzSandbox name 'z' already in useN)r3r7r}rSrrTrQr5rUrXrdr r r)r8rLrxrVrWrXrYs r"update_sandboxzSandboxClient.update_sandbox%s v.8$ zz'''':H  % % '$$X]]_TuU U$$ zz%%,+v[1zz%%,/$XJ.>?"+ %Q '  sAA**C$=A"CC$c*|jd|} |jj|}|jy#tj $r@}|j jdk(rtd|dd|t|Yd}~yd}~wwxYw)zDelete a Sandbox. Args: name: Sandbox name. Raises: ResourceNotFoundError: If sandbox not found. SandboxClientError: For other errors. rr]rr_rraNrres r"delete_sandboxzSandboxClient.delete_sandboxHs v. (zz((-H  % % '$$ (zz%%,+v[1 %Q ' '  (rch|jd|d} |jj|}|jt j |j S#tj$r<}|jjdk(rtd|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. rz/statusr]rr_rraN) r3r7rcrSrrTrQr5rUrXrdr rres r"get_sandbox_statusz SandboxClient.get_sandbox_status^s" vW5 zz~~c*H  % % '!++HMMO< <$$ zz%%,+v[1 %Q '   sA A""B157B,,B1xg?)r- poll_intervalcddl}|j|z} |j|}|jdk(r|j |S|jdk(rt |j xsdd||jz }|dkrtd|d |d d|j |jt||) 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. rNreadyfailedzSandbox provisioning failedrrarz' not ready after s)rb last_status) time monotonicrstatusrrstatus_messager sleepmin)r8rLr-rrdeadliner remainings r"wait_for_sandboxzSandboxClient.wait_for_sandbox}s4 >>#g-,,T2F}}'''--}}(+))J-J"+!4>>#33IA~*v%7yB"+ &  JJs=)4 5!r$)r, Optional[str]r-floatr.rr/int)returnNone)rr*)rEzOptional[type]rFzOptional[BaseException]rGz Optional[Any]rr)rLstrrMrr-rrr)rLrrr)rz list[Volume])rLrrr)rLrrxrrMrrr)rLrrrrrrrrrrzOptional[list[VolumeMountSpec]]rr)rLrrr)rzlist[SandboxTemplate])rLrrxrrr) rLrrrrrr-rrr)rLrrr)rz list[Pool])rLrrxrrz Optional[int]rr)rrrLrr-rrr) rrrLrr-rrNboolrr)rLrrr)rz list[Sandbox])rLrrxrrr)rLrrr)rLrr-rrrrr) __name__ __module__ __qualname____doc__r:r<rArCrHrZrfrnrvr~rrrrrrrrrrrrrrrrrrr'r$r"r*r*3s.'+!% Y$Y Y  Y  Y: )   $ '''  '  'R6,(<#'" 88 8  8  8F!%9=555  5  5575 5n6,!F(L ... .  . .`64#'"& 66 6  6  6p(@# %% %  %  %V## 22 2  2  2 2h:2!F(,F" -6-6 -6  -6  -6r$r*)rr)rr)%r __future__rtypingrrr5 langsmithrrlangsmith.sandbox._exceptionsrrr r r r r langsmith.sandbox._helpersrrrrrlangsmith.sandbox._modelsrrrrrlangsmith.sandbox._sandboxrlangsmith.sandbox._transportrr#r(r*r'r$r"rsUK" '/7.+ w 6w 6r$