sdk/README.md

Hanzo AI SDKs

The central repository and conformance specification for all Hanzo AI SDKs.

Hanzo provides two distinct, complementary tiers across every major programming language:

1. Full Cloud SDKs: Complete, typed projections of the entire Hanzo Cloud platform (over 2,400 operations covering models, agents, compute, storage, datastore, IAM, billing, chain, and networking).
2. AI & Agents Flagship SDKs: Ergonomic, hand-crafted libraries tailored specifically for foundation models, streaming inference, agent orchestration, tool calling, memory architectures, MCP (Model Context Protocol), and the Kai Agent Governance & Behavioral Policy Engine.
3. CLI & Developer Utilities: Unified terminal workflows via hanzoai/cli and hanzo.sh.

---

SDK Matrix

Language / Platform	Tier	Package	Installation	Repository	Docs
Python	Cloud & AI Flagship	hanzoai / hanzo	pip install hanzoai	hanzoai/python-sdk	Python Docs
TypeScript / Node	Cloud & AI Flagship	@hanzo/sdk / @hanzo/ai	npm install @hanzo/sdk	hanzo-js/sdk · hanzoai/js-sdk	TypeScript Docs
Go	Cloud & AI	github.com/hanzoai/go-sdk	go get github.com/hanzoai/go-sdk	hanzo-go/sdk	Go Docs
Rust	AI & Agents / Cloud	hanzo-client / hanzo	cargo add hanzo-client	hanzo-rs/sdk	Rust Docs
PHP	Cloud API	hanzoai/hanzoai	composer require hanzoai/hanzoai	hanzo-php/sdk · hanzoai/php-sdk	PHP Docs
Ruby	Cloud API	hanzoai	gem install hanzoai	hanzo-ruby/sdk · hanzoai/ruby-sdk	Ruby Docs
Dart / Flutter	Cloud & Mobile	hanzoai	dart pub add hanzoai	hanzo-dart/sdk · hanzoai/dart-sdk	Dart Docs
Java	Cloud (typed client)	ai.hanzo:hanzo-java-cloud	Gradle / Maven	hanzo-java/sdk · hanzoai/java-sdk	Java Docs
Kotlin	Cloud & Agents	ai.hanzo:hanzo-kotlin-cloud	Gradle / Maven	hanzo-kotlin/sdk	Kotlin Docs
Swift	Cloud & Async/Await	Hanzo	SwiftPM (tag v8.0.0)	hanzo-swift/sdk	Swift Docs
C++	Native Bindings	hanzo::hanzo	CMake FetchContent	hanzo-cpp/sdk	C++ Docs
C# / .NET	Cloud API	Hanzo.AI	dotnet add package Hanzo.AI	hanzoai/csharp-sdk	C# Docs
Web Fetch	Browser / Edge	@hanzo/sdk-fetch	npm install @hanzo/sdk-fetch	hanzo-js/sdk-fetch	Fetch Docs
Angular	Frontend Angular	@hanzo/sdk-angular	npm install @hanzo/sdk-angular	hanzo-js/sdk-angular	Angular Docs
Hanzo CLI	Terminal & Automation	hanzo	curl -fsSL https://hanzo.sh | sh	hanzoai/cli	CLI Docs

Ecosystem Organization Architecture

• Dedicated Language Orgs: Each major ecosystem has its own dedicated GitHub organization (hanzo-php, hanzo-ruby, hanzo-go, hanzo-js, hanzo-rs, hanzo-py, hanzo-swift, hanzo-kotlin, hanzo-cpp, hanzo-dart). Real code lives in hanzo-<lang>/sdk.
• Public Package Mirrors: The hanzoai/*-sdk repositories under hanzoai act as public mirrors and landing redirects.
• Go Import Resolution: The Go module import path is github.com/hanzoai/go-sdk while the repository sits at hanzo-go/sdk. Go modules resolve by module path, not repo URL.
• PHP Packagist: The PHP SDK is officially published on Packagist as hanzoai/hanzoai from hanzo-php/sdk.
• RubyGems: The Ruby SDK is published on RubyGems as hanzoai from hanzo-ruby/sdk.
• Dart Pub: Published on pub.dev as hanzoai from hanzo-dart/sdk.

---

Universal API Contract & Configuration

Every official Hanzo SDK speaks the same HTTP/REST and SSE wire protocols:

Environment Variables

Variable	Default Value	Description
HANZO_API_KEY	(Required)	Secret API key (sk-...) or frontend publishable key (pk-...).
HANZO_BASE_URL	https://api.hanzo.ai/v1	Root API gateway endpoint.
HANZO_ORG_ID	None	Optional tenant / organization identifier (X-Hanzo-Org header).
HANZO_MODEL	zen5	Default frontier model ID.
HANZO_TIMEOUT	60	HTTP request timeout in seconds.
HANZO_MAX_RETRIES	3	Maximum retry attempts for 429/5xx status codes with exponential backoff.

Model Catalog (Zero Credential Route)

The model catalog is identical for all callers and requires no authentication token:

curl https://catalog.hanzo.ai/v1/models
# or
curl https://api.hanzo.ai/v1/models

Recommended frontier models:

• zen5: Flagship frontier reasoning model.
• zen5-coder: Specialized high-efficiency coding and architecture model.
• enso: Lightweight, ultra-low latency model for high-frequency agent actions.
• zen-embed: 1536-dimensional dense vector embeddings.

Kai Agent Governance & Decision API

Kai provides explicit policy evaluation and behavioral consistency benchmarking for autonomous agents:

POST /v1/decisions
Content-Type: application/json
Authorization: Bearer sk-...

{
  "agent_id": "agent-support-01",
  "policy_id": "pol-financial-safety-v2",
  "action": {
    "type": "execute_transaction",
    "payload": { "amount": 25.00, "currency": "USD" }
  },
  "context": { "user_authenticated": true }
}

Verdict replies: ALLOW, DENY, or MODIFY with deterministic confidence scores and reasoning audits.

---

Conformance Specification & Test Harness

This repository holds the canonical OpenAPI 3.1 specification and automated test fixtures to ensure 100% cross-language behavioral compatibility:

• spec/openapi.json: Official OpenAPI 3.1 specification for /v1.
• conformance/fixtures/: Wire test vectors for authentication headers, unary chat completions, SSE streaming events, tool calling, embeddings, Kai decisions, and error envelopes.
• conformance/runner.py: Self-contained Python test harness and local mock server.

Running the Conformance Suite Locally

# Validate all fixtures, OpenAPI schema, and run wire tests against the mock gateway
python3 conformance/runner.py --validate-all

# Spin up a standalone local mock gateway on port 8080 for testing any language SDK
python3 conformance/runner.py --server --port 8080

---

Quickstart Examples

Python

from hanzoai import Hanzo

client = Hanzo()

# Chat Completion
response = client.chat.completions.create(
    model="zen5",
    messages=[{"role": "user", "content": "Hello Hanzo!"}]
)
print(response.choices[0].message.content)

TypeScript / JavaScript

import { Hanzo } from '@hanzo/ai';

const client = new Hanzo();

const response = await client.chat.completions.create({
  model: 'zen5',
  messages: [{ role: 'user', content: 'Hello Hanzo!' }],
});
console.log(response.choices[0].message.content);

Go

package main

import (
    "context"
    "fmt"
    "github.com/hanzoai/go-sdk"
)

func main() {
    client := hanzo.NewClient()
    resp, _ := client.Chat.CreateCompletion(context.Background(), hanzo.ChatCompletionRequest{
        Model: "zen5",
        Messages: []hanzo.ChatMessage{{Role: "user", Content: "Hello from Go!"}},
    })
    fmt.Println(resp.Choices[0].Message.Content)
}

PHP

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Hanzo\Client;

$client = new Client();
$reply = $client->chat->completions->create([
    'model' => 'zen5',
    'messages' => [['role' => 'user', 'content' => 'Hello from PHP!']]
]);
echo $reply['choices'][0]['message']['content'] . "\n";

Ruby

require 'hanzoai'

client = Hanzoai::Client.new
reply = client.chat.completions.create(
  model: 'zen5',
  messages: [{ role: 'user', content: 'Hello from Ruby!' }]
)
puts reply.choices.first.message.content

Rust

use hanzo_client::{Client, ChatMessage, Role};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env();
    let reply = client.chat().create_completion("zen5", vec![
        ChatMessage { role: Role::User, content: "Hello from Rust!".into() }
    ]).await?;
    println!("{}", reply.choices[0].message.content);
    Ok(())
}

(See examples/ for complete standalone scripts in Go, Rust, Python, PHP, Ruby, Dart, and cURL).

---

Documentation & Resources

• Official Documentation
• API Reference
• API Key Management
• Kai Decision Engine & Behavioral Governance

---

Company & Support

Hanzo AI is co-led by Co-CEOs Antje Worring and Zach Kelling.

• Corporate Address: 995 Market St, San Francisco, CA 94103
• Inquiries & Support: [email protected] · [email protected]

---

License

Licensed under the Apache License, Version 2.0 or the MIT License at your option.