Tinfoil Python Client
A Python client for verifiably private AI inference with Tinfoil. It wraps the OpenAI Python client with the same API, and before sending any request it verifies the enclave's attestation and encrypts the request body to the attested key using EHBP, so only the verified enclave can read it.
For complete documentation, see the Python SDK documentation.
Installation
uv add tinfoil
# or
pip install tinfoil
Quick Start
import os
from tinfoil import TinfoilAI
client = TinfoilAI(api_key=os.environ["TINFOIL_API_KEY"])
# Enclave verification and encryption happen automatically.
chat_completion = client.chat.completions.create(
model="llama3-3-70b", # see https://docs.tinfoil.sh/models/catalog
messages=[{"role": "user", "content": "Hi"}],
)
print(chat_completion.choices[0].message.content)
Async and streaming
Use AsyncTinfoilAI and await each call; the API is otherwise identical.
import asyncio
import os
from tinfoil import AsyncTinfoilAI
client = AsyncTinfoilAI(api_key=os.environ["TINFOIL_API_KEY"])
async def main() -> None:
stream = await client.chat.completions.create(
model="llama3-3-70b",
messages=[{"role": "user", "content": "Say this is a test"}],
stream=True,
)
async for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content is not None:
print(chunk.choices[0].delta.content, end="", flush=True)
print()
asyncio.run(main())
Audio transcription
with open("audio.mp3", "rb") as audio_file:
transcription = client.audio.transcriptions.create(
file=audio_file,
model="whisper-large-v3-turbo",
)
print(transcription.text)
Verification document
document = client.get_verification_document()
print(document.release_tag) # None when verifying against a pinned measurement
print(document.release_digest)
print(document.code_fingerprint)
print(document.enclave_fingerprint)
print(document.verifier)
print(document.verified_at)
verified_at is recorded from the local clock after successful verification. It is not an attested timestamp or a freshness guarantee.
Prompt Cache Scoping
The router partitions prompt caches by API identity and a user_cache_secret that the SDK adds to eligible requests. By default it generates one and persists it at ~/.tinfoil/user_cache_secret, which is suitable for single-user applications. Multi-user services should scope each request to its end user:
# Pin a stable, opaque secret for this client (or set TINFOIL_USER_CACHE_SECRET).
client = TinfoilAI(api_key=api_key, user_cache_secret=secret)
# A per-request value wins over the client-level secret.
chat_completion = client.chat.completions.create(
model="llama3-3-70b",
messages=[{"role": "user", "content": "Hi"}],
extra_body={"user_cache_secret": per_user_secret},
)
AsyncTinfoilAI and NewSecureClient accept the same parameter. See Prompt caching for resolution order and guidance on choosing a scope.
Advanced Functionality
NewSecureClient makes verified GET and POST requests to any path on the enclave. Requests to other origins are rejected.
import os
from tinfoil import NewSecureClient
api_key = os.environ["TINFOIL_API_KEY"]
tfclient = NewSecureClient()
resp = tfclient.get(
f"https://{tfclient.enclave}/health",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
print(resp.status_code, resp.text)
API Documentation
This library is a drop-in replacement for the official OpenAI Python client. All methods and types are identical; see the OpenAI Python client documentation for API usage.
Development
Install uv, then:
uv sync
uv run pytest -m "not integration"
# Integration tests require TINFOIL_API_KEY
export TINFOIL_API_KEY="..."
uv run pytest -m integration
Reporting Vulnerabilities
Please report security vulnerabilities by either:
- Emailing security@tinfoil.sh
- Opening an issue on GitHub on this repository
We aim to respond to (legitimate) security reports within 24 hours.
Release files for tinfoil 0.15.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| tinfoil-0.15.0.tar.gz | 684.0 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tinfoil-0.15.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 785.3 kB
Release files / tinfoil-0.15.0.tar.gz
| Download URL | tinfoil-0.15.0.tar.gz |
|---|---|
| Size | 684.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6676e0014ef8a992b26d7f47d4e99f3a440ab6e38488d1f21f34b537d12869d8
|
|
BLAKE2b-256 checksum How to use checksums |
c6c18d836dbb734a353f144118e5cb4107b5c678681adbaea8f00b3f8ddcec22
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / tinfoil-0.15.0-py3-none-any.whl
| Download URL | tinfoil-0.15.0-py3-none-any.whl |
|---|---|
| Size | 101.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbc5012dd65ab5d2211b9f32a5bdb823550f0310ab79c4ab21175ab4dd4abccd
|
|
BLAKE2b-256 checksum How to use checksums |
76a87f11e490569624e27ef3b5bbf10802354efb1ab2f2448c3028a8a9eb375c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for tinfoil 0.15.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for tinfoil-0.15.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
