Files
skills/public/python-sdk.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

452 lines
24 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>python-sdk</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/python-sdk">
<link rel="alternate" type="text/markdown" href="/python-sdk.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/python-sdk.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>python-sdk</h1><p class="lede">Hanzo Python SDK is a generated Python client library for the Hanzo AI API.</p><h1>Hanzo Python SDK - Generated API Client</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related Skills</strong>: <code>hanzo/hanzo-chat.md</code>, <code>hanzo/js-sdk.md</code>, <code>hanzo/go-sdk.md</code></p>
<h2>Overview</h2>
<p>Hanzo Python SDK is a <strong>generated Python client library</strong> for the Hanzo AI API. Provides full type safety, async support, streaming, auto-pagination, and auto-retry. Covers all 187 API endpoints across 51 resource namespaces — identical API surface to the JS and Go SDKs.</p>
<h3>Why Hanzo Python SDK?</h3>
<ul><li><strong>Full type safety</strong>: Generated from our OpenAPI spec</li><li><strong>OpenAI compatible</strong>: Same interface patterns, easy migration</li><li><strong>Async native</strong>: Both sync and async clients</li><li><strong>Streaming</strong>: First-class SSE streaming with iterators</li><li><strong>Auto-retry</strong>: Configurable retry with exponential backoff</li><li><strong>Pagination</strong>: Auto-pagination helpers for list endpoints</li></ul>
<h3>OSS Base</h3>
<p>Generated by <strong>openapi-generator</strong>. Repo: <code>hanzoai/python-sdk</code>.</p>
<h2>When to use</h2>
<ul><li>Python applications calling Hanzo API</li><li>FastAPI, Django, or Flask backends</li><li>ML/AI pipelines needing LLM access</li><li>Replacing OpenAI Python SDK with Hanzo</li><li>Jupyter notebooks and data science workflows</li></ul>
<h2>Hard requirements</h2>
<ol><li><strong>Python &gt;=3.12</strong></li><li><strong>HANZO_API_KEY</strong> for authentication</li></ol>
<h2>Quick reference</h2>
<p>| Item | Value | |------|-------| | Package | <code>hanzoai</code> (PyPI) | | Version | 2.2.0 | | Repo | <code>github.com/hanzoai/python-sdk</code> | | Generated by | openapi-generator | | License | BSD-3-Clause | | Python | &gt;=3.12 | | Base URL | <code>https://api.hanzo.ai</code> |</p>
<h2>Installation</h2>
<pre><code class="lang-bash"># pip
pip install hanzoai
# uv (preferred)
uv add hanzoai
# poetry
poetry add hanzoai</code></pre>
<h2>One-file quickstart</h2>
<h3>Chat Completion</h3>
<pre><code class="lang-python">from hanzoai import Hanzo
client = Hanzo(
api_key=&quot;your-api-key&quot;, # defaults to HANZO_API_KEY env var
)
response = client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Hello, Hanzo!&quot;}],
)
print(response.choices[0].message.content)</code></pre>
<h3>Streaming</h3>
<pre><code class="lang-python">stream = client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Write a poem about code&quot;}],
stream=True,
)
for chunk in stream:
content = chunk.choices[0].delta.content
if content:
print(content, end=&quot;&quot;)</code></pre>
<h3>Async Client</h3>
<pre><code class="lang-python">import asyncio
from hanzoai import AsyncHanzo
client = AsyncHanzo()
async def main():
response = await client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Hello!&quot;}],
)
print(response.choices[0].message.content)
asyncio.run(main())</code></pre>
<h3>Async Streaming</h3>
<pre><code class="lang-python">async def stream_response():
stream = await client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Write a story&quot;}],
stream=True,
)
async for chunk in stream:
content = chunk.choices[0].delta.content
if content:
print(content, end=&quot;&quot;)</code></pre>
<h3>Embeddings</h3>
<pre><code class="lang-python">embedding = client.embeddings.create(
model=&quot;zen-embedding&quot;,
input=&quot;Hello world&quot;,
)
print(len(embedding.data[0].embedding)) # dimension count</code></pre>
<h3>Function Calling / Tools</h3>
<pre><code class="lang-python">response = client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;What&#x27;s the weather in Tokyo?&quot;}],
tools=[{
&quot;type&quot;: &quot;function&quot;,
&quot;function&quot;: {
&quot;name&quot;: &quot;get_weather&quot;,
&quot;description&quot;: &quot;Get current weather for a location&quot;,
&quot;parameters&quot;: {
&quot;type&quot;: &quot;object&quot;,
&quot;properties&quot;: {
&quot;location&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;description&quot;: &quot;City name&quot;},
},
&quot;required&quot;: [&quot;location&quot;],
},
},
}],
)
tool_call = response.choices[0].message.tool_calls[0]
if tool_call:
print(tool_call.function.name) # &quot;get_weather&quot;
print(tool_call.function.arguments) # &#x27;{&quot;location&quot;:&quot;Tokyo&quot;}&#x27;</code></pre>
<h3>Vision (Multimodal)</h3>
<pre><code class="lang-python">response = client.chat.completions.create(
model=&quot;zen-vision&quot;,
messages=[{
&quot;role&quot;: &quot;user&quot;,
&quot;content&quot;: [
{&quot;type&quot;: &quot;text&quot;, &quot;text&quot;: &quot;What&#x27;s in this image?&quot;},
{&quot;type&quot;: &quot;image_url&quot;, &quot;image_url&quot;: {&quot;url&quot;: &quot;https://example.com/photo.jpg&quot;}},
],
}],
)</code></pre>
<h2>API Surface</h2>
<p>The SDK provides <strong>187 endpoints</strong> across <strong>51 resource namespaces</strong>, generated from our OpenAPI spec.</p>
<h3>Core Resources</h3>
<p>| Resource | Method | Description | |----------|--------|-------------| | <code>client.chat.completions.create()</code> | POST | Chat completion (streaming optional) | | <code>client.completions.create()</code> | POST | Text completion (legacy) | | <code>client.embeddings.create()</code> | POST | Generate embeddings | | <code>client.models.list()</code> | GET | List available models | | <code>client.models.retrieve(id)</code> | GET | Get model details |</p>
<h3>File Management</h3>
<p>| Method | Description | |--------|-------------| | <code>client.files.create()</code> | Upload a file | | <code>client.files.retrieve(id)</code> | Get file metadata | | <code>client.files.list()</code> | List uploaded files | | <code>client.files.delete(id)</code> | Delete a file | | <code>client.files.content(id)</code> | Get file content |</p>
<h3>Fine-Tuning</h3>
<p>| Method | Description | |--------|-------------| | <code>client.fine_tuning.jobs.create()</code> | Create fine-tuning job | | <code>client.fine_tuning.jobs.retrieve(id)</code> | Get job status | | <code>client.fine_tuning.jobs.list()</code> | List all jobs | | <code>client.fine_tuning.jobs.cancel(id)</code> | Cancel a job | | <code>client.fine_tuning.jobs.list_events(id)</code> | List job events |</p>
<h3>Images</h3>
<p>| Method | Description | |--------|-------------| | <code>client.images.generate()</code> | Generate images | | <code>client.images.edit()</code> | Edit images |</p>
<h3>Audio</h3>
<p>| Method | Description | |--------|-------------| | <code>client.audio.transcriptions.create()</code> | Speech-to-text | | <code>client.audio.translations.create()</code> | Audio translation | | <code>client.audio.speech.create()</code> | Text-to-speech |</p>
<h3>Additional Resource Namespaces</h3>
<p>The SDK also includes namespaces for: assistants, threads, runs, batches, vector stores, model management, key management, team management, organization, budget, guardrails, credentials, and more (51 total).</p>
<h2>Configuration</h2>
<pre><code class="lang-python">client = Hanzo(
api_key=&quot;your-key&quot;, # Required (or HANZO_API_KEY env)
base_url=&quot;https://api.hanzo.ai&quot;, # Default
timeout=60.0, # Request timeout (seconds)
max_retries=2, # Auto-retry count
default_headers={&quot;X-Custom&quot;: &quot;val&quot;}, # Extra headers
default_query={&quot;version&quot;: &quot;2&quot;}, # Extra query params
)</code></pre>
<h3>Environment Variables</h3>
<pre><code class="lang-bash">HANZO_API_KEY=your-api-key # Required
HANZO_BASE_URL=https://... # Override base URL
HANZO_LOG=debug # Enable debug logging</code></pre>
<h2>OpenAI Drop-In Replacement</h2>
<pre><code class="lang-python">from openai import OpenAI
client = OpenAI(
base_url=&quot;https://api.hanzo.ai/v1&quot;,
api_key=os.environ[&quot;HANZO_API_KEY&quot;],
)
# Everything works — same API shape
response = client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Hello&quot;}],
)</code></pre>
<h2>Framework Integration</h2>
<h3>FastAPI</h3>
<pre><code class="lang-python">from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from hanzoai import Hanzo
app = FastAPI()
client = Hanzo()
@app.post(&quot;/api/chat&quot;)
async def chat(messages: list[dict]):
stream = client.chat.completions.create(
model=&quot;zen-70b&quot;,
messages=messages,
stream=True,
)
async def generate():
for chunk in stream:
content = chunk.choices[0].delta.content
if content:
yield f&quot;data: {content}\n\n&quot;
return StreamingResponse(generate(), media_type=&quot;text/event-stream&quot;)</code></pre>
<h3>LangChain</h3>
<pre><code class="lang-python">from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url=&quot;https://api.hanzo.ai/v1&quot;,
api_key=os.environ[&quot;HANZO_API_KEY&quot;],
model=&quot;zen-70b&quot;,
)
response = llm.invoke(&quot;Hello, Hanzo!&quot;)</code></pre>
<h2>Error Handling</h2>
<pre><code class="lang-python">from hanzoai import Hanzo, APIError, RateLimitError, APIConnectionError
try:
response = client.chat.completions.create(...)
except RateLimitError as e:
print(f&quot;Rate limited, retry after: {e.response.headers.get(&#x27;retry-after&#x27;)}&quot;)
except APIError as e:
print(f&quot;API error: {e.status_code} {e.message}&quot;)
except APIConnectionError as e:
print(f&quot;Connection error: {e}&quot;)</code></pre>
<h2>Pagination</h2>
<pre><code class="lang-python"># Auto-pagination
for model in client.models.list():
print(model.id)
# Manual pagination
page = client.models.list()
print(page.data)
if page.has_next_page():
next_page = page.get_next_page()</code></pre>
<h2>Package Structure</h2>
<p>The SDK contains <strong>55 packages</strong> in the <code>pkg/</code> directory, organized by resource namespace:</p>
<pre><code>hanzoai/
├── __init__.py # Main client export
├── _client.py # Hanzo and AsyncHanzo clients
├── _streaming.py # Stream and AsyncStream
├── _response.py # Response types
├── types/ # All Pydantic response models
│ ├── chat/
│ ├── fine_tuning/
│ ├── audio/
│ └── ...
├── resources/ # Resource namespace implementations
│ ├── chat/
│ │ └── completions.py
│ ├── embeddings.py
│ ├── models.py
│ ├── files.py
│ └── ...
└── pkg/ # 55 sub-packages</code></pre>
<h2>Runtime Support</h2>
<p>| Runtime | Support | Notes | |---------|---------|-------| | CPython 3.12+ | Full | Primary target | | PyPy 3.12+ | Full | Compatible | | Jupyter | Full | Sync client in notebooks |</p>
<h2>Related Skills</h2>
<ul><li><code>hanzo/hanzo-chat.md</code> - API reference and model catalog</li><li><code>hanzo/js-sdk.md</code> - JavaScript equivalent</li><li><code>hanzo/go-sdk.md</code> - Go equivalent</li><li><code>hanzo/rust-sdk.md</code> - Rust equivalent (infrastructure SDK)</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2026-03-13 <strong>Category</strong>: Hanzo Ecosystem <strong>Related</strong>: sdk, python, client, api <strong>Prerequisites</strong>: Python &gt;=3.12</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/python-sdk.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>