zeroruntime 0.1.0__py3-none-any.whl

zeroruntime-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: zeroruntime
+Version: 0.1.0
+Summary: Build real-time voice agents in Python.
+Author: ZeroRuntime
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/ZeroRuntimeAI/zeroruntime-py
+Project-URL: Repository, https://github.com/ZeroRuntimeAI/zeroruntime-py
+Project-URL: Issues, https://github.com/ZeroRuntimeAI/zeroruntime-py/issues
+Keywords: voice,voice-agents,realtime,speech,stt,tts,llm,grpc
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio>=1.83.0
+Requires-Dist: protobuf<8.0,>=7.35.1
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: mcp>=1.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: grpcio-tools==1.83.0; extra == "dev"
+Dynamic: license-file
+
+# zeroruntime
+
+Build real-time voice agents in Python. You describe the agent — instructions,
+tools, and a pipeline of providers — and the runtime runs it.
+
+## Install
+
+```bash
+pip install zeroruntime
+```
+
+or pin the version:
+
+```bash
+pip install zeroruntime==0.1.0
+```
+
+Requires Python 3.10 or newer.
+
+Most providers need no extra: their credential is a string you set in the
+environment, so the base install is enough.
+
+## Quickstart
+
+```python
+import zrt
+from zrt import Agent, Pipeline, Room, function_tool
+from zrt.inference import TurnDetector
+from zrt.plugins import CartesiaTTS, DeepgramSTT, GoogleLLM, SileroVAD
+
+AGENT_ID = "cascade-basic-agent"
+
+
+class VoiceAgent(Agent):
+    def __init__(self) -> None:
+        super().__init__(
+            agent_id=AGENT_ID,
+            instructions="You are a helpful voice assistant.",
+            pipeline=Pipeline(
+                stt=DeepgramSTT(),
+                llm=GoogleLLM(),
+                tts=CartesiaTTS(),
+                vad=SileroVAD(),
+                turn_detector=TurnDetector(),
+            ),
+        )
+
+    async def on_enter(self) -> None:
+        await self.session.say("Hello, how can I help you today?")
+
+    @function_tool
+    async def get_weather(self, latitude: str, longitude: str) -> dict:
+        """Fetch the current weather for a location.
+
+        Args:
+            latitude: Latitude of the location. Estimate it; do not ask.
+            longitude: Longitude of the location. Estimate it; do not ask.
+        """
+        return {"latitude": latitude, "longitude": longitude, "temperature_c": 28}
+
+
+def invoke_agent() -> None:
+    zrt.invoke(AGENT_ID, room=Room(name="Cascade Agent", playground=True))
+
+
+if __name__ == "__main__":
+    zrt.serve(VoiceAgent, on_ready=invoke_agent)
+```
+
+Run it and the playground URL is printed once, on stdout. Open it to talk to
+the agent.
+
+## Credentials
+
+Set your runtime token in the environment before serving:
+
+```bash
+export ZERORUNTIME_AUTH_TOKEN="..."
+```
+
+Vendor keys go in the environment too, one per provider you use — each provider
+names the variable it reads when the key is missing.
+
+## Providers
+
+`zrt.plugins` calls the vendor directly with your key on your account.
+`zrt.inference` reaches a subset of the same providers through the runtime
+gateway instead. The names mirror each other, so swapping the import swaps who
+makes the call and who is billed:
+
+```python
+from zrt.plugins import DeepgramSTT    # your Deepgram account
+from zrt.inference import DeepgramSTT  # through the gateway
+```

zeroruntime-0.1.0.dist-info/RECORD

@@ -0,0 +1,87 @@
+zeroruntime-0.1.0.dist-info/licenses/LICENSE,sha256=NlSU1VZTHtB2VSpKBmJnuyhqTNAOw5GIn7JQffXhdls,2864
+zrt/__init__.py,sha256=2BO0XlhJgL-t4a_U2TJm_bNeiBG9uucUuybrHpN6wMM,2720
+zrt/_cli.py,sha256=WNAurySEUjnBYL4eP1_1yByOersAVXGlLE6JrueD5Os,5839
+zrt/_cli_download.py,sha256=2GmpmPmI57DWnT68HKIKsoTPqPWiPnSjFgHe4YAtfzg,6308
+zrt/_invoke.py,sha256=JDL508q0d43BVG8047iUdlJFGul-Ueq2iZ5RrKLmAis,8369
+zrt/_log_format.py,sha256=CjzS2Lty3aR-CdP8o4I319ZDqIZHWMNqlgzLePf0Ato,2215
+zrt/_mcp_client.py,sha256=r6UCT4vfxwdJAPPFshKevsVrJKpU8SxTb2qLkIuy1tE,8423
+zrt/_serve.py,sha256=ktZT9NhSqgwwedOgw5RmP4zEy9tDkDwBZlYxmiOeAHw,19882
+zrt/_spec.py,sha256=2IqEQgVuB-uO3PwHa3l5veSlYeDrR2RUAU4lwWc2n-U,7134
+zrt/_version.py,sha256=BqrlbKZZBAHhA1__5ZHwLPQaCkW7Pi_dgI-cgbAZm40,85
+zrt/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zrt/_client/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+zrt/_client/auth.py,sha256=Teb7z0H_Y5uphYod80vsYKngGRRCSi5AeJUCXRhN17o,3673
+zrt/_client/channel.py,sha256=DCyKjn7oPREhtYk0O2mTpxZdFKWmguOn9XQns28oUME,10857
+zrt/_client/credentials.py,sha256=32rENbbC3y7LgeRnbHQUB-rXt6ha0RDbC6uhKtNk2UE,2540
+zrt/_client/registry.py,sha256=tvekzgUS4mB1w-ptdbSxFJqxWrN8iKVNNlWENRWTrn8,17020
+zrt/_client/tool_bridge.py,sha256=l9I_KW6Q7ZvIwmo5jL2QATBBfN8dM1Jeg72rONopBMU,5877
+zrt/_client/translate.py,sha256=S_qMNCfepzWoFjNr-0qFdLrHAnizKGDpbZiPMWKdx8E,4841
+zrt/_plugins/__init__.py,sha256=vHlVoCywD6x-DVbsZ4ryFrhLt0quvz3o1j5zXW9Z7LM,773
+zrt/_plugins/_registry.py,sha256=CSSi_TfQJ9_hjxsSDbPFIP9sABrrtdG74H2t44_I0pI,6594
+zrt/_plugins/anam.py,sha256=EE6K7TU5XgSqGCXMLzwBTQcpb0UWtZSAVstsCMNLxvs,1719
+zrt/_plugins/anthropic.py,sha256=iwqqHZUosnJtbkUGos6o9gLunG5RzSwNtPkznaIRgYI,2250
+zrt/_plugins/assemblyai.py,sha256=NcQKNhXhP8X6nn6udmipBzuPzxL8RoYFgSiR5-fmuHQ,2300
+zrt/_plugins/aws.py,sha256=5rVkN5lUCyo1RxsdQJkp02Dvwz_NO4IAnf0UK5T-dGk,3695
+zrt/_plugins/azure.py,sha256=ulFSOVvkzu_cQrm_YsVkBHhxjmtSwgU2Jk3s5dVGWDE,3667
+zrt/_plugins/cambai.py,sha256=xtiz9eqCW7j5P7KBztVL_Dhcjlg6tWpm1oC9rjfg0A0,2269
+zrt/_plugins/cartesia.py,sha256=Iiz-PgZICgZB7Hz81LmehEVAXK8X1cCZoNYcEqnqnoU,2948
+zrt/_plugins/cerebras.py,sha256=BinlNjreMkt9Q2TacP6cuDkBNtTZ1d27iOz5Z_45vyc,2080
+zrt/_plugins/cometapi.py,sha256=SHx5ZAQa69bEnvx0Y93yphDkSUyJXbsWcqp4Iel_v5s,2785
+zrt/_plugins/deepgram.py,sha256=zzxeApMZlT6i2tb-FzFyue4xNYhL6bbn8_WVZYQLWzQ,4235
+zrt/_plugins/elevenlabs.py,sha256=rMI8yyUk-cpEBPG_HhPCoEPjpYvWdjC0udnUs9byNU0,3457
+zrt/_plugins/gladia.py,sha256=HVzOGp6WY_GiDKD-HmwMTizvxozI2h6W5lDhdv2BX2Y,2068
+zrt/_plugins/google.py,sha256=yEwQ8EKEwPYFONJ-yWVUfLxsd1VSkP0BA09Jrz3llrk,5763
+zrt/_plugins/groq.py,sha256=UHOdnfza_xgXPcnwEVCbb2NdznvdNkDdNdbf0W_DjbU,1884
+zrt/_plugins/humeai.py,sha256=S1Z5bpK2LVIWUDwTExP1fnbH4t1axMiFw2ZxKfzemeQ,1802
+zrt/_plugins/inworldai.py,sha256=S5LxU0MS2gKhmOkq3X0NXG8R9h4qDxuACStBOzMvMSM,2239
+zrt/_plugins/lmnt.py,sha256=xB0p2e8p-4irPLzEj9XzWEdxhQrAoy56R4G_vmC1Fno,2473
+zrt/_plugins/murfai.py,sha256=ztp_ZL9sogwxMHnuVLlj-O2nNGHXVFhKo46YXGJRkL4,2064
+zrt/_plugins/navana.py,sha256=j5H27Gyt7Oi_XIrCu1_3mEYSLLJNnOtNDxJc7QeTx8s,1785
+zrt/_plugins/neuphonic.py,sha256=S0uev7yGBltxVp-t-F-AYLirTN4VHGXtiwSR4Z49MmU,2012
+zrt/_plugins/nvidia.py,sha256=x53gmHC3BG2pxzNQlsYnHFzDjntyur70P96iI3wiX2o,2759
+zrt/_plugins/openai.py,sha256=gtkUIa-EJMd9ivKV-MxQxTOxeDFK2kvHY68H2QQrCMY,6070
+zrt/_plugins/papla.py,sha256=Y0P7fE9Y1BoY9nSXutmkIymrJRffqX6XizlWp6NsLnY,1652
+zrt/_plugins/resemble.py,sha256=nU8CKsNoWGles951wFEAKsRCQjY97CON3Ghy3iSDnms,1772
+zrt/_plugins/rime.py,sha256=Slg2j-tfXnfPxXalJV1_q9FUBv2xX-UkgnhPVIdsb5k,2294
+zrt/_plugins/rnnoise.py,sha256=3yaHOgtl5GNxwuwVaec5yD9uacBzLepG6GJU4uZ7uq4,1503
+zrt/_plugins/sarvamai.py,sha256=g98ZSBX6ccVZ-co-moGBBx8GccQxBDH2YvFfObCEP88,4402
+zrt/_plugins/silero.py,sha256=aUpiflKHNWMqtPycmJUWyQVuIVadym57fN5VSMlufXM,2786
+zrt/_plugins/simli.py,sha256=ZDWK3H7S0qa1UtP_Fgbaq4hTT7ho3EH_ZJ1F-ZqUyn0,1828
+zrt/_plugins/smallestai.py,sha256=qDN88qB9bgo5AncMf0-sdjXj_FqRX_Uvomcxk3XZ0D8,2546
+zrt/_plugins/speechify.py,sha256=bRQKW3iZCfPs4YbdzesYJKZmUTe1J2RgCOnYfmKG3YQ,2094
+zrt/_plugins/ultravox.py,sha256=HGMGf8ESUC854pGYqBuajf5xuu8ZwxvPJwfBjfluDOU,1846
+zrt/_plugins/xai.py,sha256=-Xn9yQ1HOq8ImrZTvrOl_6UkGsD8iSKVJNdfwWvgQRU,4083
+zrt/_wire/__init__.py,sha256=xrm3qpd7gQenvLVd_KxzUYRVKST45IjMwBdu7zmufoY,239
+zrt/_wire/zeroruntime_pb2.py,sha256=71qbTSBG2Mnh4JKeuSx1oWM7M_JTc45KO5EZuNxS8Cw,28567
+zrt/_wire/zeroruntime_pb2.pyi,sha256=E8NFtCnLBhwaHaCMBV5Lqa5lTSFeqJzEN5dzV-DA-8U,45958
+zrt/_wire/zeroruntime_pb2_grpc.py,sha256=Wot5iwhtZg0VQ6TV9ZaMVMxCxC314JwqKGFvrdn-B9k,12954
+zrt/core/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+zrt/core/_tasks.py,sha256=oxFC7TZNYRMUfsj7L2fjG-331xjNYcN2ndXvMnm4zyQ,1350
+zrt/core/agent.py,sha256=RVkEuPxCeoPCRomjAPKE7Q1jdV5P2rpbQxK8_DeN59Y,10062
+zrt/core/context.py,sha256=gnva28bJigvGICkxHVXbklcYXE-NSiX1eDvnJBm8qyk,425
+zrt/core/enums.py,sha256=QQVAY1nhCoCJTk3LUs-s8xDCBeCjYUbpDQR46E0i1r4,3087
+zrt/core/errors.py,sha256=PkgkZ-RDWx4BCkFvuY164OYqNTyLe5f8VEQNq7eUHoI,1106
+zrt/core/events.py,sha256=3ntUdiD8mOjvbctQD-ja61u82Xpt50hm-cy1jY76cHA,4743
+zrt/core/mcp.py,sha256=6F8LrkQCqWcKWcAPv-9XVXASmNDS4MA86Y2wmNNXMLA,2681
+zrt/core/pipeline.py,sha256=NjU37dg0ZamyJswNCG2sBLLq-3pnvCDAeSTBdsrnNzk,9513
+zrt/core/room.py,sha256=Y9cGiiIgf2gIf9n44ksgNbQY8hpVvFMx66Xzi2WspFU,13090
+zrt/core/session.py,sha256=X_A2Ijb-FsDfME8lPK5GxPO6JSyh6d0Q-y6j5eJKhpo,48499
+zrt/core/stt_stream.py,sha256=83mRto7dLCGwfQDNPiAifjcOw8-A-T6qYQf6NiHM6AI,2473
+zrt/core/tools.py,sha256=mMF6G3_7pW7JXFyoeprr0cUJJAeNOgLf-adcJNXSBW0,5506
+zrt/core/transfer.py,sha256=F89D42h0WWFamkZlX1_fL8VOJ0SEtLPP2r7wKeDsvLc,6371
+zrt/core/tuning.py,sha256=5q1CgOC0Vw5qlx0hHjCJyoYe1xrr05e485WGrzTSF2k,4883
+zrt/core/utterance.py,sha256=RxNvTiNEW5UvwxpsYA1LKYSF2xuzIMbCjrX6qX2L1NE,1317
+zrt/inference/__init__.py,sha256=vvlwOd1GfXoCd7yMEw01PtX-6lEDskeyABRM89GIb0w,3344
+zrt/inference/_registry.py,sha256=4V_teHpPReND-OIMv3ujUadQP44sfUj-dASC_FcuhM8,2235
+zrt/inference/denoise.py,sha256=sv72PhLdew7pPotwBdly8M1n05b2I8r_YrrCnnunIBI,1504
+zrt/inference/llm.py,sha256=ygGsrWgnMCEm0F8kvTahRwF7L0sPrsxUjO0L61xOiSY,1440
+zrt/inference/realtime.py,sha256=iXziXhy1aldORZBQn857_f8-OGqS8GVFbVLuyGxSNrs,591
+zrt/inference/stt.py,sha256=cYQmJX28hzz5KlNhA4Uawr2BZaR8laBbkfrdXSyHLKE,2401
+zrt/inference/tts.py,sha256=F_scA8nopZhu-I9HmVDswtw9BQ-CKSYfUwHCj2co5UA,1903
+zrt/inference/turn.py,sha256=HcaCSblSHgdWPNHdvu9YHhA8BT5I64hV5ixzT6hv1G4,1859
+zrt/plugins/__init__.py,sha256=aPLcE64cn2fWRjou659-P-Ab9jemS-VXkv3DM1TRIe0,6702
+zeroruntime-0.1.0.dist-info/METADATA,sha256=tTVBrVMk6Hm_6vWwblVrX_EVBmkFvVO4el8cWMV6zQM,3926
+zeroruntime-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+zeroruntime-0.1.0.dist-info/entry_points.txt,sha256=39I-K-0tUoRpYfUF8542UIJKC_NE9eLCyj2-J1ZQBnY,38
+zeroruntime-0.1.0.dist-info/top_level.txt,sha256=44yp2UXFleIaf-P1xQJl61ajDgHcl9dy15WQwYc8eCk,4
+zeroruntime-0.1.0.dist-info/RECORD,,

zeroruntime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zeroruntime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zrt = zrt._cli:main

zeroruntime-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,54 @@
+Zeroruntime SDK — Proprietary License
+
+Copyright (c) 2026 Zujo Tech Pvt Ltd. All rights reserved.
+
+This software, including its source code, object code, and accompanying
+documentation (collectively, the "Software"), is the proprietary and
+confidential property of Zujo Tech Pvt Ltd ("Licensor"). The Software is
+licensed, not sold. No ownership rights are transferred to you. "Zero Runtime"
+and "ZRT" are products and services of Zujo Tech Pvt Ltd.
+
+1. License Grant. Subject to your continued compliance with this License (and
+   with any separate written agreement you have entered into with Licensor),
+   Licensor grants you a limited, non-exclusive, non-transferable, non-
+   sublicensable, revocable license to install and use the Software solely to
+   develop and operate applications that connect to and interoperate with the
+   Zero Runtime service.
+
+2. Restrictions. Except to the extent expressly permitted in Section 1, by a
+   separate written agreement with Licensor, or by applicable law that cannot
+   be contractually waived, you may NOT:
+     (a) copy, modify, adapt, translate, or create derivative works of the
+         Software;
+     (b) distribute, publish, sublicense, sell, rent, lease, lend, or
+         otherwise make the Software available to any third party;
+     (c) reverse engineer, decompile, or disassemble the Software, or attempt
+         to derive its source code where not provided;
+     (d) use the Software to build or operate a product or service that
+         competes with the Zero Runtime service; or
+     (e) remove, obscure, or alter any proprietary notices, labels, or marks
+         on or in the Software.
+
+3. Ownership. The Software is protected by copyright and other intellectual
+   property laws and treaties. Licensor and its licensors retain all right,
+   title, and interest in and to the Software, including all intellectual
+   property rights therein.
+
+4. Termination. This License is effective until terminated. It terminates
+   automatically, without notice, if you breach any of its terms. Upon
+   termination you must cease all use of the Software and destroy all copies
+   in your possession or control.
+
+5. No Warranty. THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT
+   WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NONINFRINGEMENT.
+
+6. Limitation of Liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT
+   SHALL LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS, DATA, OR USE,
+   ARISING OUT OF OR RELATED TO THIS LICENSE OR THE SOFTWARE, WHETHER IN
+   CONTRACT, TORT, OR OTHERWISE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+   DAMAGES.
+
+For licensing inquiries, contact: support@videosdk.live

zeroruntime-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zrt

zrt/__init__.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from ._version import __version__
+
+_LAZY: dict[str, tuple[str, str]] = {
+    "Agent": ("zrt.core.agent", "Agent"),
+    "AgentContext": ("zrt.core.context", "AgentContext"),
+    "BackgroundAudio": ("zrt.core.agent", "BackgroundAudio"),
+    "CallSummary": ("zrt.core.agent", "CallSummary"),
+    "Pipeline": ("zrt.core.pipeline", "Pipeline"),
+    "NO_CHANGE": ("zrt.core.pipeline", "NO_CHANGE"),
+    "EOUConfig": ("zrt.core.tuning", "EOUConfig"),
+    "InterruptConfig": ("zrt.core.tuning", "InterruptConfig"),
+    "function_tool": ("zrt.core.tools", "function_tool"),
+    "MCPServerStdio": ("zrt.core.mcp", "MCPServerStdio"),
+    "MCPServerHTTP": ("zrt.core.mcp", "MCPServerHTTP"),
+    "SIPDestination": ("zrt.core.transfer", "SIPDestination"),
+    "WarmTransferConfig": ("zrt.core.transfer", "WarmTransferConfig"),
+    "WarmTransferPhase": ("zrt.core.transfer", "WarmTransferPhase"),
+    "WarmTransferResult": ("zrt.core.transfer", "WarmTransferResult"),
+    "run_stt": ("zrt.core.stt_stream", "run_stt"),
+    "Room": ("zrt.core.room", "Room"),
+    "UNSET": ("zrt.core.room", "UNSET"),
+    "Sip": ("zrt.core.room", "Sip"),
+    "Observability": ("zrt.core.room", "Observability"),
+    "Exporter": ("zrt.core.room", "Exporter"),
+    "Session": ("zrt.core.session", "Session"),
+    "UtteranceHandle": ("zrt.core.utterance", "UtteranceHandle"),
+    "PronunciationRule": ("zrt.core.pipeline", "PronunciationRule"),
+    "ContextWindow": ("zrt.core.pipeline", "ContextWindow"),
+    "RoomMessage": ("zrt.core.session", "RoomMessage"),
+    "Participant": ("zrt.core.session", "Participant"),
+    "serve": ("zrt._serve", "serve"),
+    "invoke": ("zrt._invoke", "invoke"),
+    "ZeroRuntimeChannel": ("zrt._client.channel", "ZeroRuntimeChannel"),
+    "ZrtError": ("zrt.core.errors", "ZrtError"),
+    "SessionRejected": ("zrt.core.errors", "SessionRejected"),
+    "ProviderUnavailable": ("zrt.core.errors", "ProviderUnavailable"),
+    "ZeroRuntimeUnreachable": ("zrt.core.errors", "ZeroRuntimeUnreachable"),
+    "ToolTimeout": ("zrt.core.errors", "ToolTimeout"),
+    "AgentState": ("zrt.core.enums", "AgentState"),
+    "UserState": ("zrt.core.enums", "UserState"),
+    "PipelineMode": ("zrt.core.enums", "PipelineMode"),
+    "ChatRole": ("zrt.core.enums", "ChatRole"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module, attr = _LAZY[name]
+    except KeyError:
+        raise AttributeError(f"module 'zrt' has no attribute {name!r}") from None
+    value = getattr(importlib.import_module(module), attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(_LAZY)
+
+
+__all__ = [*sorted(_LAZY), "__version__"]

zrt/_cli.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import os
+import platform
+import sys
+import time
+from typing import Optional
+
+from ._version import __version__ as _PACKAGE_VERSION
+
+REQUIRED_CLI_VERSION = "latest"
+_LATEST_TTL_S = 24 * 60 * 60
+
+_ARCH = {
+    "x86_64": "x86_64",
+    "amd64": "x86_64",
+    "AMD64": "x86_64",
+    "arm64": "aarch64",
+    "aarch64": "aarch64",
+}
+
+
+def cli_version() -> str:
+    return os.environ.get("ZRT_CLI_VERSION", "").strip() or REQUIRED_CLI_VERSION
+
+
+def detect_target(
+    system: Optional[str] = None, machine: Optional[str] = None
+) -> str:
+    system = system or platform.system()
+    machine = machine or platform.machine()
+    arch = _ARCH.get(machine) or _ARCH.get(machine.lower())
+    if not arch:
+        raise RuntimeError(
+            f"The ZRT CLI is not available for this architecture: {machine}."
+        )
+    if system == "Darwin":
+        return f"{arch}-apple-darwin"
+    if system == "Linux":
+        return f"{arch}-unknown-linux-gnu"
+    if system == "Windows":
+        return f"{arch}-pc-windows-msvc"
+    raise RuntimeError(
+        f"The ZRT CLI is not available for this operating system: {system}."
+    )
+
+
+def cli_binary_name() -> str:
+    return "zrt.exe" if sys.platform.startswith("win") else "zrt"
+
+
+def zrt_home() -> str:
+    return os.environ.get("ZRT_HOME") or os.path.join(os.path.expanduser("~"), ".zrt")
+
+
+def cli_install_path(version: Optional[str] = None) -> str:
+    return os.path.join(
+        zrt_home(), "bin", version or cli_version(), cli_binary_name()
+    )
+
+
+def checksum_record_path(binary_path: str) -> str:
+    return binary_path + ".sha256"
+
+
+def package_record_path(binary_path: str) -> str:
+    """Which ``zrt`` release this cached CLI was fetched for."""
+    return binary_path + ".pkg"
+
+
+def cached_package_version(binary_path: str) -> str:
+    try:
+        with open(package_record_path(binary_path), "r", encoding="utf-8") as f:
+            return f.read().strip()
+    except OSError:
+        return ""
+
+
+def stamp_package_version(binary_path: str) -> None:
+    """Record the package this CLI belongs to, so the next upgrade invalidates it."""
+    try:
+        with open(package_record_path(binary_path), "w", encoding="utf-8") as f:
+            f.write(_PACKAGE_VERSION)
+    except OSError:
+        # A cache that cannot be stamped just re-checks the CDN next time, which
+        # is the safe direction to fail in.
+        pass
+
+
+def _is_exec(path: str) -> bool:
+    return bool(path) and os.path.isfile(path) and os.access(path, os.X_OK)
+
+
+def refresh_requested() -> bool:
+    """ZRT_CLI_REFRESH: fetch the CLI again, whatever the cache says."""
+    return os.environ.get("ZRT_CLI_REFRESH", "").lower() in ("1", "true", "yes")
+
+
+def _is_stale(binary_path: str, version: str) -> bool:
+    if refresh_requested():
+        return True
+
+    # A CLI cached for a different `zrt` release. The two ship as one product,
+    # so installing the package is exactly the moment its CLI has to be
+    # re-checked -- otherwise an upgrade keeps running the previous binary until
+    # the 24h TTL happens to expire, and a pinned version never re-checks at all.
+    #
+    # This is the whole reason the cache is keyed on the package rather than on
+    # time: a wheel install runs no code of ours, so there is no post-install
+    # hook to clear it from. The first `zrt` command after the upgrade is the
+    # earliest we can notice, and this is what makes it notice.
+    if cached_package_version(binary_path) != _PACKAGE_VERSION:
+        return True
+
+    if version != "latest":
+        return False
+    try:
+        age = time.time() - os.path.getmtime(checksum_record_path(binary_path))
+    except OSError:
+        return True
+    return age > _LATEST_TTL_S
+
+
+def _local_build_fallback() -> Optional[str]:
+    name = cli_binary_name()
+    rel_targets = (
+        os.path.join("zrt-cli", "target"),
+        os.path.join("zrt", "target"),
+        "target",
+    )
+    cur = os.path.abspath(os.getcwd())
+    while True:
+        for rel in rel_targets:
+            for profile in ("release", "debug"):
+                cand = os.path.join(cur, rel, profile, name)
+                if _is_exec(cand):
+                    return cand
+        parent = os.path.dirname(cur)
+        if parent == cur:
+            return None
+        cur = parent
+
+
+def resolve_cli_binary(version: Optional[str] = None) -> str:
+    version = version or cli_version()
+
+    override = os.environ.get("ZRT_CLI_BIN", "").strip()
+    if override:
+        if _is_exec(override):
+            return override
+        raise RuntimeError(
+            f"ZRT_CLI_BIN points at {override!r}, which is not an executable file."
+        )
+
+    local_build = _local_build_fallback()
+    if local_build:
+        return local_build
+
+    installed = cli_install_path(version)
+    if _is_exec(installed) and not _is_stale(installed, version):
+        return installed
+
+    from ._cli_download import download_cli
+
+    try:
+        download_cli(version, installed)
+    except Exception:
+        if _is_exec(installed) and not refresh_requested():
+            return installed
+        raise
+
+    if _is_exec(installed):
+        return installed
+    raise RuntimeError(
+        f"Could not resolve the ZRT CLI ({version}). Set ZRT_CLI_BIN to a built "
+        f"binary, or ensure network access to the CLI download CDN."
+    )
+
+
+def main() -> None:
+    """Entry point for the ``zrt`` command: resolve the CLI (downloading it on
+    first use) and run it, forwarding all arguments and the exit code."""
+    try:
+        binary = resolve_cli_binary()
+    except Exception as e:
+        print(f"zrt: {e}", file=sys.stderr)
+        raise SystemExit(1)
+    args = [binary, *sys.argv[1:]]
+    if os.name == "nt":
+        import subprocess
+
+        raise SystemExit(subprocess.run(args).returncode)
+    os.execv(binary, args)