# TensorZero Python Client
**[Website](https://www.tensorzero.com/)** ·
**[Docs](https://www.tensorzero.com/docs)** ·
**[Twitter](https://www.x.com/tensorzero)** ·
**[Slack](https://www.tensorzero.com/slack)** ·
**[Discord](https://www.tensorzero.com/discord)**
**[Quick Start (5min)](https://www.tensorzero.com/docs/quickstart)** ·
**[Comprehensive Tutorial](https://www.tensorzero.com/docs/gateway/tutorial)** ·
**[Deployment Guide](https://www.tensorzero.com/docs/gateway/deployment)** ·
**[API Reference](https://www.tensorzero.com/docs/gateway/api-reference/inference)** ·
**[Configuration Reference](https://www.tensorzero.com/docs/gateway/configuration-reference)**
The `tensorzero` package provides a Python client for the TensorZero Gateway.
This client allows you to easily make inference requests and assign feedback to them via the gateway.
See our **[API Reference](https://www.tensorzero.com/docs/gateway/api-reference)** for more information.
## Installation
```bash
pip install tensorzero
```
## Basic Usage
### Initialization
The TensorZero client offers synchronous (`TensorZeroGateway`) and asynchronous (`AsyncTensorZeroGateway`) variants.
Additionally, the client can launch an embedded (in-memory) gateway (`build_embedded`) or connect to an external HTTP gateway (`build_http`) - both of these methods return a gateway instance.
By default, the asynchronous client returns a `Future` when you call `build_http` or `build_embedded`, so you must `await` it.
If you prefer to avoid the `await`, you can set `async_setup=False` to initialize the client in a blocking way.
#### Synchronous HTTP Gateway
```python
from tensorzero import TensorZeroGateway
with TensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
# ...
```
#### Asynchronous HTTP Gateway
```python
import asyncio
from tensorzero import AsyncTensorZeroGateway
async def run():
async with await AsyncTensorZeroGateway.build_http(
gateway_url="http://localhost:3000",
# async_setup=False # optional: skip the `await` and run `build_http` synchronously (blocking)
) as client:
# ...
if __name__ == "__main__":
asyncio.run(run())
```
#### Synchronous Embedded Gateway
```python
from tensorzero import TensorZeroGateway
with TensorZeroGateway.build_embedded(
config_file="/path/to/tensorzero.toml",
clickhouse_url="http://chuser:chpassword@localhost:8123/tensorzero"
) as client:
# ...
```
#### Asynchronous Embedded Gateway
```python
import asyncio
from tensorzero import AsyncTensorZeroGateway
async def run():
async with await AsyncTensorZeroGateway.build_embedded(
config_file="/path/to/tensorzero.toml",
clickhouse_url="http://chuser:chpassword@localhost:8123/tensorzero"
# async_setup=False # optional: skip the `await` and run `build_embedded` synchronously (blocking)
) as client:
# ...
if __name__ == "__main__":
asyncio.run(run())
```
### Inference
#### Non-Streaming Inference with Synchronous Client
```python
with TensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
response = client.inference(
model_name="openai::gpt-4o-mini",
input={
"messages": [
{"role": "user", "content": "What is the capital of Japan?"},
],
},
)
print(response)
```
#### Non-Streaming Inference with Asynchronous Client
```python
async with await AsyncTensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
response = await client.inference(
model_name="openai::gpt-4o-mini",
input={
"messages": [
{"role": "user", "content": "What is the capital of Japan?"},
],
},
)
print(response)
```
#### Streaming Inference with Synchronous Client
```python
with TensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
stream = client.inference(
model_name="openai::gpt-4o-mini",
input={
"messages": [
{"role": "user", "content": "What is the capital of Japan?"},
],
},
stream=True,
)
for chunk in stream:
print(chunk)
```
#### Streaming Inference with Asynchronous Client
```python
async with await AsyncTensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
stream = await client.inference(
model_name="openai::gpt-4o-mini",
input={
"messages": [{"role": "user", "content": "What is the capital of Japan?"}],
},
stream=True,
)
async for chunk in stream:
print(chunk)
```
### Feedback
#### Synchronous
```python
with TensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
response = client.feedback(
metric_name="thumbs_up",
inference_id="00000000-0000-0000-0000-000000000000",
value=True, # 👍
)
print(response)
```
#### Asynchronous
```python
async with await AsyncTensorZeroGateway.build_http(gateway_url="http://localhost:3000") as client:
response = await client.feedback(
metric_name="thumbs_up",
inference_id="00000000-0000-0000-0000-000000000000",
value=True, # 👍
)
print(response)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "tensorzero",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "artificial intelligence, ai, machine learning, ml, large language model, large language models, llm, llms, natural language processing, NLP, generative ai, genai",
"author": null,
"author_email": "Viraj Mehta <viraj@tensorzero.com>, Gabriel Bianconi <gabriel@tensorzero.com>, Aaron Hill <aaron@tensorzero.com>",
"download_url": "https://files.pythonhosted.org/packages/ed/dc/80467a188d2a71ac5f2484dc66bd1e367404e559592f713e97303cbb97bf/tensorzero-2025.9.1.tar.gz",
"platform": null,
"description": "# TensorZero Python Client\n\n**[Website](https://www.tensorzero.com/)** \u00b7\n**[Docs](https://www.tensorzero.com/docs)** \u00b7\n**[Twitter](https://www.x.com/tensorzero)** \u00b7\n**[Slack](https://www.tensorzero.com/slack)** \u00b7\n**[Discord](https://www.tensorzero.com/discord)**\n\n**[Quick Start (5min)](https://www.tensorzero.com/docs/quickstart)** \u00b7\n**[Comprehensive Tutorial](https://www.tensorzero.com/docs/gateway/tutorial)** \u00b7\n**[Deployment Guide](https://www.tensorzero.com/docs/gateway/deployment)** \u00b7\n**[API Reference](https://www.tensorzero.com/docs/gateway/api-reference/inference)** \u00b7\n**[Configuration Reference](https://www.tensorzero.com/docs/gateway/configuration-reference)**\n\nThe `tensorzero` package provides a Python client for the TensorZero Gateway.\nThis client allows you to easily make inference requests and assign feedback to them via the gateway.\n\nSee our **[API Reference](https://www.tensorzero.com/docs/gateway/api-reference)** for more information.\n\n## Installation\n\n```bash\npip install tensorzero\n```\n\n## Basic Usage\n\n### Initialization\n\nThe TensorZero client offers synchronous (`TensorZeroGateway`) and asynchronous (`AsyncTensorZeroGateway`) variants.\nAdditionally, the client can launch an embedded (in-memory) gateway (`build_embedded`) or connect to an external HTTP gateway (`build_http`) - both of these methods return a gateway instance.\n\nBy default, the asynchronous client returns a `Future` when you call `build_http` or `build_embedded`, so you must `await` it.\nIf you prefer to avoid the `await`, you can set `async_setup=False` to initialize the client in a blocking way.\n\n#### Synchronous HTTP Gateway\n\n```python\nfrom tensorzero import TensorZeroGateway\n\nwith TensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n # ...\n```\n\n#### Asynchronous HTTP Gateway\n\n```python\nimport asyncio\n\nfrom tensorzero import AsyncTensorZeroGateway\n\n\nasync def run():\n async with await AsyncTensorZeroGateway.build_http(\n gateway_url=\"http://localhost:3000\",\n # async_setup=False # optional: skip the `await` and run `build_http` synchronously (blocking)\n ) as client:\n # ...\n\n\nif __name__ == \"__main__\":\n asyncio.run(run())\n```\n\n#### Synchronous Embedded Gateway\n\n```python\nfrom tensorzero import TensorZeroGateway\n\nwith TensorZeroGateway.build_embedded(\n config_file=\"/path/to/tensorzero.toml\",\n clickhouse_url=\"http://chuser:chpassword@localhost:8123/tensorzero\"\n) as client:\n # ...\n```\n\n#### Asynchronous Embedded Gateway\n\n```python\nimport asyncio\n\nfrom tensorzero import AsyncTensorZeroGateway\n\n\nasync def run():\n async with await AsyncTensorZeroGateway.build_embedded(\n config_file=\"/path/to/tensorzero.toml\",\n clickhouse_url=\"http://chuser:chpassword@localhost:8123/tensorzero\"\n # async_setup=False # optional: skip the `await` and run `build_embedded` synchronously (blocking)\n ) as client:\n # ...\n\n\nif __name__ == \"__main__\":\n asyncio.run(run())\n```\n\n### Inference\n\n#### Non-Streaming Inference with Synchronous Client\n\n```python\nwith TensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n response = client.inference(\n model_name=\"openai::gpt-4o-mini\",\n input={\n \"messages\": [\n {\"role\": \"user\", \"content\": \"What is the capital of Japan?\"},\n ],\n },\n )\n\n print(response)\n```\n\n#### Non-Streaming Inference with Asynchronous Client\n\n```python\nasync with await AsyncTensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n response = await client.inference(\n model_name=\"openai::gpt-4o-mini\",\n input={\n \"messages\": [\n {\"role\": \"user\", \"content\": \"What is the capital of Japan?\"},\n ],\n },\n )\n\n print(response)\n```\n\n#### Streaming Inference with Synchronous Client\n\n```python\nwith TensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n stream = client.inference(\n model_name=\"openai::gpt-4o-mini\",\n input={\n \"messages\": [\n {\"role\": \"user\", \"content\": \"What is the capital of Japan?\"},\n ],\n },\n stream=True,\n )\n\n for chunk in stream:\n print(chunk)\n```\n\n#### Streaming Inference with Asynchronous Client\n\n```python\nasync with await AsyncTensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n stream = await client.inference(\n model_name=\"openai::gpt-4o-mini\",\n input={\n \"messages\": [{\"role\": \"user\", \"content\": \"What is the capital of Japan?\"}],\n },\n stream=True,\n )\n\n async for chunk in stream:\n print(chunk)\n```\n\n### Feedback\n\n#### Synchronous\n\n```python\nwith TensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n response = client.feedback(\n metric_name=\"thumbs_up\",\n inference_id=\"00000000-0000-0000-0000-000000000000\",\n value=True, # \ud83d\udc4d\n )\n\n print(response)\n```\n\n#### Asynchronous\n\n```python\nasync with await AsyncTensorZeroGateway.build_http(gateway_url=\"http://localhost:3000\") as client:\n response = await client.feedback(\n metric_name=\"thumbs_up\",\n inference_id=\"00000000-0000-0000-0000-000000000000\",\n value=True, # \ud83d\udc4d\n )\n\n print(response)\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "The Python client for TensorZero",
"version": "2025.9.1",
"project_urls": {
"Documentation": "https://tensorzero.com/docs/",
"Homepage": "https://tensorzero.com/",
"Issues": "https://github.com/tensorzero/tensorzero/issues",
"ReleaseNotes": "https://github.com/tensorzero/tensorzero/releases",
"Repository": "https://github.com/tensorzero/tensorzero"
},
"split_keywords": [
"artificial intelligence",
" ai",
" machine learning",
" ml",
" large language model",
" large language models",
" llm",
" llms",
" natural language processing",
" nlp",
" generative ai",
" genai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73399fef3d7f6984978ef4865ddef8c96b7a4258f876cf6bd18214129b5b1433",
"md5": "d97dfc8d19b911f0b89bf4035012f4fa",
"sha256": "079d8f285a032056f1e7a7bb0a94277af8c28862a29d07200996a10bac70d90f"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-macosx_10_12_x86_64.whl",
"has_sig": false,
"md5_digest": "d97dfc8d19b911f0b89bf4035012f4fa",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 20883260,
"upload_time": "2025-09-08T05:00:33",
"upload_time_iso_8601": "2025-09-08T05:00:33.337459Z",
"url": "https://files.pythonhosted.org/packages/73/39/9fef3d7f6984978ef4865ddef8c96b7a4258f876cf6bd18214129b5b1433/tensorzero-2025.9.1-cp39-abi3-macosx_10_12_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f74aff7db6289e1babdba5b449515fbae32ef2b2d029d79ef6b29cc3f17c14a7",
"md5": "7e16c59fdbbc51d842334224581f2889",
"sha256": "b5fb50c0be2cd1beede3bd314f51e215e609808966a0a2f0292a013b176cf2b5"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "7e16c59fdbbc51d842334224581f2889",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 20008310,
"upload_time": "2025-09-08T05:00:29",
"upload_time_iso_8601": "2025-09-08T05:00:29.988900Z",
"url": "https://files.pythonhosted.org/packages/f7/4a/ff7db6289e1babdba5b449515fbae32ef2b2d029d79ef6b29cc3f17c14a7/tensorzero-2025.9.1-cp39-abi3-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d3f4321254be8610b1c62c517625ceb0dafec16b33e58d5c89808b4ffda791de",
"md5": "d64ee2a77991e4b26ded0f36e981b8f5",
"sha256": "52625155047d480fcf6e945cb05e86f8d1e337ebfe65986712b6f9fe3c7aaa3b"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "d64ee2a77991e4b26ded0f36e981b8f5",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 21941496,
"upload_time": "2025-09-08T05:00:21",
"upload_time_iso_8601": "2025-09-08T05:00:21.812582Z",
"url": "https://files.pythonhosted.org/packages/d3/f4/321254be8610b1c62c517625ceb0dafec16b33e58d5c89808b4ffda791de/tensorzero-2025.9.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "74fa5ed7c809dd2f7185045e37b63344503de11747758b5fbf979ce8d196fc17",
"md5": "229114083b42979c131f22ef789489e0",
"sha256": "024dc1b829e3e396e17158ee5c047b3aacbaf5aeef36e5c4cfcdfe25c310a7bb"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "229114083b42979c131f22ef789489e0",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 22621613,
"upload_time": "2025-09-08T05:00:26",
"upload_time_iso_8601": "2025-09-08T05:00:26.282179Z",
"url": "https://files.pythonhosted.org/packages/74/fa/5ed7c809dd2f7185045e37b63344503de11747758b5fbf979ce8d196fc17/tensorzero-2025.9.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b3e9320f655a03c652f0793b02db34c145828d205335c87f14ff753bb06be5a7",
"md5": "9eea5515e900104df68e2476f5242af4",
"sha256": "b9b203597c8ed31bae7bf07c5efc26719df761390a04044c8cc0ef932dfd8aeb"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-musllinux_1_2_aarch64.whl",
"has_sig": false,
"md5_digest": "9eea5515e900104df68e2476f5242af4",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 21982269,
"upload_time": "2025-09-08T05:00:36",
"upload_time_iso_8601": "2025-09-08T05:00:36.578807Z",
"url": "https://files.pythonhosted.org/packages/b3/e9/320f655a03c652f0793b02db34c145828d205335c87f14ff753bb06be5a7/tensorzero-2025.9.1-cp39-abi3-musllinux_1_2_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b5e4c594231c313511cd59b147a54c9da9b5960fef85c9d0845e910ce31fa920",
"md5": "e9bb7832b7796391ef053c3ba2b608a8",
"sha256": "7ca85229129a8d2850a093c506be8dc7c206ff385b34b0aac9c562d286dcb7ca"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-musllinux_1_2_x86_64.whl",
"has_sig": false,
"md5_digest": "e9bb7832b7796391ef053c3ba2b608a8",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 22816236,
"upload_time": "2025-09-08T05:00:39",
"upload_time_iso_8601": "2025-09-08T05:00:39.997380Z",
"url": "https://files.pythonhosted.org/packages/b5/e4/c594231c313511cd59b147a54c9da9b5960fef85c9d0845e910ce31fa920/tensorzero-2025.9.1-cp39-abi3-musllinux_1_2_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e601f9e4ec4544e1af9b9f786bd08c0af5d07835af67654fe85c93dd02077b01",
"md5": "610a44e9cc236e2a1c5b0784a83041da",
"sha256": "fe82be97ea49da30bb36e5d98fe6491b012791f09a77bba4cdc7c9e7c6d30d53"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1-cp39-abi3-win_amd64.whl",
"has_sig": false,
"md5_digest": "610a44e9cc236e2a1c5b0784a83041da",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 19269347,
"upload_time": "2025-09-08T05:00:45",
"upload_time_iso_8601": "2025-09-08T05:00:45.507904Z",
"url": "https://files.pythonhosted.org/packages/e6/01/f9e4ec4544e1af9b9f786bd08c0af5d07835af67654fe85c93dd02077b01/tensorzero-2025.9.1-cp39-abi3-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eddc80467a188d2a71ac5f2484dc66bd1e367404e559592f713e97303cbb97bf",
"md5": "a40d5e82c854fd5400b964c6a5908f61",
"sha256": "a8c90559807e3357ed7731f6af5d88c22025dc7e54f28e856b256eb8b815f57e"
},
"downloads": -1,
"filename": "tensorzero-2025.9.1.tar.gz",
"has_sig": false,
"md5_digest": "a40d5e82c854fd5400b964c6a5908f61",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 1396725,
"upload_time": "2025-09-08T05:00:42",
"upload_time_iso_8601": "2025-09-08T05:00:42.558316Z",
"url": "https://files.pythonhosted.org/packages/ed/dc/80467a188d2a71ac5f2484dc66bd1e367404e559592f713e97303cbb97bf/tensorzero-2025.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 05:00:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tensorzero",
"github_project": "tensorzero",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "tensorzero"
}
JSON
