hanzoai/python-sdk
2
0
Fork 0
mirror of https://github.com/hanzoai/python-sdk.git synced 2026-10-23 20:23:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

pypi: one canonical hanzo, and superseded packages that say where the real one is

Browse Source 
Three published packages declared a console script named `hanzo`, competing with
the native CLI and with each other. Measured on a clean venv at hanzo==0.4.3:
`hanzo --help` printed hanzo-cli's program, not the one pkg/hanzo/README.md
documents. Renamed to `hanzo-py` and `hanzo-cli` — script named after its
distribution. Nothing is yanked; both packages still install and run.

- pkg/hanzo 0.4.4 — summary and README now say the CLI is a native binary
  (curl -fsSL https://hanzo.sh | sh). Dropped the invented command tour
  (`hanzo chat --model gpt-4`, `hanzo node start`, `hanzo router start` on
  localhost:4000): none of those verbs exist in the program this package
  installs. Kept the three library entry points, each import-checked.
- pkg/hanzo-cli 0.2.4 — `hanzo login` replaced with the native `hanzo auth login`
  plus its own `hanzo-cli login`. Verified `hanzo iam users list` and
  `hanzo kms secrets list` against the shipped v1.9.18 binary.
- pkg/hanzo-node 0.1.1 — states the two meanings of the name: the `hanzo-node`
  COMMAND is a symlink to the Hanzo CLI; this package fetches a different binary
  from hanzoai/node, which is private, so the download 404s for the public.
  Documentation URL moved off docs.hanzo.ai/node (404) to hanzo.sh.
- root README (published as `hanzoai`) — `pip install hanzo` no longer advertised
  as the CLI; model ids zen-coder -> zen5-coder (zen-coder is not in the catalog);
  "2452 operations, 1798 schemas" dropped for the spec URL, since the live
  surface is 1058 paths / 1465 operations / 1139 schemas.

Co-authored-by: Hanzo Dev <[email protected]>
This commit is contained in:
zeekay
2026-08-01 13:35:20 -07:00
co-authored by Hanzo Dev
parent 816d29f069
commit c698ae5951
8 changed files with 140 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LLM.md
+25 -1
View File
@@ -12,11 +12,35 @@ OUT, never duplicate. Full spec: `~/work/hanzo/SDK-ARCHITECTURE.md`.
## Install / run
```bash
pip install hanzo # CLI + agents + MCP + client
pip install hanzoai # typed cloud client
pip install hanzo # agents + MCP + orchestration helpers
uv sync --all-packages # dev: whole workspace
uv run pytest tests/ -v # tests
```
## Console-script law — only the native binary is called `hanzo`
The `hanzo` command is the Rust CLI (`curl -fsSL https://hanzo.sh | sh`). No
package in this workspace may declare a `hanzo` console script.
Both `hanzo` and `hanzo-cli` used to, and `hanzo` depends on `hanzo-cli`, so
`pip install hanzo` installed two distributions fighting over one name — whichever
landed last won. Measured on a clean venv at 0.4.3: `hanzo --help` printed
*hanzo-cli's* program (bot/deploy/iam/k8s/kms/login/logout/paas/s3/whoami), not
the one `pkg/hanzo/README.md` documented. And if the native CLI was already on
PATH, `hanzo login` meant one of three different things depending on install
order — the real CLI reads a bare `hanzo login` as an AI task, since the verb
there is `hanzo auth login`.
Now: `hanzo` ships `hanzo-py`, `hanzo-cli` ships `hanzo-cli`. Script named after
its distribution, one canonical `hanzo`.
`hanzo-node` on PyPI is also **not** the `hanzo-node` command. That command is a
symlink to the Hanzo CLI, installed by hanzo.sh. The PyPI package fetches a
different Rust binary from `hanzoai/node` — a private repo, so its release assets
404 for anyone outside the org. Both READMEs say so rather than implying one
product.
## Brand rules (hard — enforce in all docs)
- Never "LLM gateway"; never position against LiteLLM. Hanzo is a full AI SDK / AI
cloud, not a proxy.
README.md
+23 -19
View File
@@ -17,14 +17,16 @@ compute, and a batteries-included CLI. If you build AI in Python, start here.
## Install
```bash
pip install hanzo # flagship: CLI + agents + MCP + client
pip install hanzoai # the typed cloud API client
pip install hanzo # orchestration helpers, agents, MCP
pip install "hanzo[all]" # everything, including optional extras
```
Or install exactly what you need:
The `hanzo` **command** is not a Python package — it is a native binary:
```bash
pip install hanzoai # just the typed cloud API client
pip install "hanzo[all]" # everything, including optional extras
curl -fsSL https://hanzo.sh | sh
hanzo auth login
```
## Quickstart
@@ -39,7 +41,7 @@ with ApiClient(config) as client:
ai = AiOpenAICompatibleApi(client)
resp = ai.ai_create_chat_completion(
AiChatCompletionRequest(
model="zen-coder",
model="zen5-coder",
messages=[AiChatMessage(role="user", content="Ship it.")],
)
)
@@ -72,8 +74,8 @@ export HANZO_API_KEY=hk-...
uv run python -m examples.hello
```
They import from **`hanzoai.cloud`** — the client generated from the Hanzo
OpenAPI surface (2452 operations, 1798 schemas), which is where new work goes.
They import from **`hanzoai.cloud`** — the client generated from
`https://api.hanzo.ai/v1/openapi.json`, which is where new work goes.
`examples/client.py` is the single place a base URL or an env var is resolved.
CI imports all six on every push, which is what keeps them from rotting into
pseudocode.
@@ -85,7 +87,7 @@ The workspace splits cleanly by concern. The headline packages:
| Package | Purpose |
|---------|---------|
| `hanzoai` | Typed cloud API client (generated from the Hanzo OpenAPI surface). |
| `hanzo` | The `hanzo` CLI + runtime that ties everything together. |
| `hanzo` | Orchestration helpers and the older Python CLI (console script `hanzo-py`). |
| `hanzo-mcp` | Model Context Protocol server — discovers tools via entry points. |
| `hanzo-agents` / `hanzo-agent` | Agent framework — build and orchestrate agents and swarms. |
| `hanzo-network` | Distributed AI compute and node orchestration. |
@@ -96,7 +98,7 @@ The workspace splits cleanly by concern. The headline packages:
python-sdk/
└── pkg/
├── hanzoai/ # typed cloud client (OpenAPI-generated)
├── hanzo/ # CLI + runtime meta package
├── hanzo/ # orchestration helpers + legacy Python CLI
├── hanzo-mcp/ # MCP server (entry-point tool discovery)
├── hanzo-agents/ # agent framework
├── hanzo-network/ # distributed compute
@@ -106,19 +108,21 @@ python-sdk/
## CLI
`pip install hanzo` gives you the `hanzo` command:
The Hanzo CLI is a native binary, not a Python package:
```bash
hanzo chat # chat with the Zen models
hanzo node # start / manage a local compute node
hanzo mcp # run the MCP server for your editor or agent
hanzo agent # build and run agents
hanzo run # run a workflow
hanzo cloud # manage cloud resources
hanzo search # AI-powered search
curl -fsSL https://hanzo.sh | sh
hanzo auth login
hanzo models list
hanzo "fix the failing test"
```
Run `hanzo --help` for the full command tree.
It carries one command group per Hanzo Cloud product, generated from the same
contract this SDK is generated from. `hanzo --help` prints the tree.
`pip install hanzo` still ships the older Python CLI as **`hanzo-py`**. It is
named that way on purpose: two programs called `hanzo` on one PATH is how
`hanzo login` came to mean different things to different people.
## Model Context Protocol (`hanzo-mcp`)
@@ -141,7 +145,7 @@ from hanzo_agents import Agent, Swarm
agent = Agent(
name="researcher",
model="zen-coder",
model="zen5-coder",
instructions="You are a research assistant.",
)
pkg/hanzo-cli/README.md
+24 -11
View File
@@ -1,19 +1,32 @@
# hanzo-cli
Unified CLI for the Hanzo platform — IAM, KMS, and PaaS management.
A Python CLI for Hanzo IAM, KMS, PaaS and S3. It predates the native Hanzo CLI
and is kept for the scripts that already depend on it.
## Install
## Use the native CLI instead
```bash
curl -fsSL https://hanzo.sh | sh
hanzo auth login
hanzo iam users list
hanzo kms secrets list
```
One binary, one command group per Hanzo Cloud product, generated from the same
contract the API and SDKs serve.
## If you still need this one
```bash
pip install hanzo-cli
hanzo-cli login
hanzo-cli whoami
hanzo-cli iam users
hanzo-cli kms list
hanzo-cli paas deploy list
```
## Usage
```bash
hanzo login
hanzo whoami
hanzo iam users
hanzo kms list
hanzo paas deploy list
```
The console script is `hanzo-cli`, not `hanzo`. `hanzo` is the native CLI, where
the sign-in verb is `hanzo auth login` — a bare `hanzo login` there is read as an
AI task, not a command. Naming this program after its distribution keeps the two
from shadowing each other on PATH.
pkg/hanzo-cli/pyproject.toml
+3 -2
View File
@@ -1,7 +1,7 @@
[project]
name = "hanzo-cli"
version = "0.2.4"
description = "Hanzo unified CLI — IAM, KMS, PaaS, S3, Deploy"
description = "Python CLI for Hanzo IAM, KMS, PaaS and S3. Superseded by the native hanzo CLI — https://hanzo.sh"
readme = "README.md"
license = { text = "MIT" }
requires-python = ">=3.12"
@@ -36,8 +36,9 @@ dev = [
"ruff>=0.5.0",
]
# Named after the distribution, not `hanzo` — `hanzo` is the native Hanzo CLI.
[project.scripts]
hanzo = "hanzo_cli.cli:main"
hanzo-cli = "hanzo_cli.cli:main"
[project.urls]
Homepage = "https://hanzo.ai"
pkg/hanzo-node/README.md
+25 -37
View File
@@ -1,56 +1,44 @@
# hanzo-node
Cross-platform installer for the Hanzo AI node (Rust binary).
A Python installer that downloads a `hanzo-node` binary from `hanzoai/node`
release assets.
## Installation
## Read this first
Two different things are called `hanzo-node`, and this package is not the one
most people want.
**The `hanzo-node` command** is a second name for the Hanzo CLI — a symlink to
the same binary, which the Hanzo Cloud control binary resolves first when it
delegates a verb it does not serve itself. You get it from the CLI installer, and
because it is a symlink it can never drift out of step with `hanzo`:
```bash
# Install via uv
uv tool install hanzo-node
# Or via pip
pip install hanzo-node
curl -fsSL https://hanzo.sh | sh
hanzo-node --version # same build as `hanzo --version`
```
**This package** installs a separate Rust agent-node binary from the
`hanzoai/node` repository. That repository is private, so its release assets
return 404 to an unauthenticated download and `hanzo-node install` cannot
complete unless you already have access. Nothing here is being removed, but if
you landed on it looking for the `hanzo-node` command, use the installer above.
## Usage
```bash
# Install the node binary
hanzo-node install
pip install hanzo-node # or: uv tool install hanzo-node
# Check status
hanzo-node install # fetch the binary for your platform
hanzo-node status
# Upgrade to latest
hanzo-node upgrade
# Run the node (passes args to binary)
hanzo-node run --help
# Uninstall
hanzo-node run --help # pass through to the binary
hanzo-node uninstall
```
## How It Works
This Python package is a thin wrapper that:
1. Detects your platform (macOS/Linux/Windows, x64/arm64)
2. Downloads the appropriate Rust binary from GitHub releases
3. Installs it to `~/.local/bin` (or `%LOCALAPPDATA%\hanzo\bin` on Windows)
4. Provides a CLI to manage the installation
The actual `hanzo-node` is written in Rust for performance. This package just handles cross-platform distribution.
## Supported Platforms
- macOS (Apple Silicon / Intel)
- Linux (x64 / arm64)
- Windows (x64)
## Environment Variables
- `HANZO_INSTALL_DIR` - Override the installation directory (default: `~/.local/bin`)
It detects your platform (macOS/Linux/Windows, x64/arm64), downloads the matching
asset, and installs it to `~/.local/bin` — or `%LOCALAPPDATA%\hanzo\bin` on
Windows. `HANZO_INSTALL_DIR` overrides the destination.
## License
pkg/hanzo-node/pyproject.toml
+3 -3
View File
@@ -1,7 +1,7 @@
[project]
name = "hanzo-node"
version = "0.1.0"
description = "Hanzo Node - Cross-platform installer for the Hanzo AI node (Rust binary)"
version = "0.1.1"
description = "Legacy installer for a private hanzo-node build. `hanzo-node` now ships with the Hanzo CLI — https://hanzo.sh"
authors = [
{name = "Hanzo AI", email = "[email protected]"},
]
@@ -33,7 +33,7 @@ hanzo-node = "hanzo_node.cli:main"
[project.urls]
Homepage = "https://hanzo.ai"
Repository = "https://github.com/hanzoai/python-sdk"
Documentation = "https://docs.hanzo.ai/node"
Documentation = "https://hanzo.sh"
[build-system]
requires = ["hatchling"]
pkg/hanzo/README.md
+32 -169
View File
@@ -1,223 +1,86 @@
# Hanzo CLI and Orchestration Tools
# hanzo
[![PyPI](https://img.shields.io/pypi/v/hanzo.svg)](https://pypi.org/project/hanzo/)
[![Python Version](https://img.shields.io/pypi/pyversions/hanzo.svg)](https://pypi.org/project/hanzo/)
Core CLI and orchestration tools for the Hanzo AI platform.
Python orchestration helpers for Hanzo AI, and the older Python implementation of
the Hanzo CLI.
## Installation
## The `hanzo` command lives elsewhere now
The Hanzo CLI is a native binary. Install it with:
```bash
curl -fsSL https://hanzo.sh | sh
hanzo auth login
```
That gives you `hanzo` (and `hanzo-node`, a symlink to the same build) with one
command group per Hanzo Cloud product. This package's console script is
**`hanzo-py`** — deliberately not `hanzo`, so it cannot shadow the real CLI on
your PATH:
```bash
pip install hanzo
hanzo-py --help
```
## Features
Nothing here is being removed. If you have scripts on `hanzo-py`, they keep
working; new work should target the native CLI.
- **Interactive Chat**: Chat with AI models through CLI
- **Node Management**: Run local AI inference nodes
- **Router Control**: Manage LLM proxy router
- **REPL Interface**: Interactive Python REPL with AI
- **Batch Orchestration**: Orchestrate multiple AI tasks
- **Memory Management**: Persistent conversation memory
## What's still useful here
## Usage
### CLI Commands
```bash
# Interactive chat
hanzo chat
# Use specific model
hanzo chat --model gpt-4
# Use router (local proxy)
hanzo chat --router
# Use cloud API
hanzo chat --cloud
```
### Node Management
```bash
# Start local node
hanzo node start
# Check status
hanzo node status
# List available models
hanzo node models
# Load specific model
hanzo node load llama2:7b
# Stop node
hanzo node stop
```
### Router Management
```bash
# Start router proxy
hanzo router start
# Check router status
hanzo router status
# List available models
hanzo router models
# View configuration
hanzo router config
# Stop router
hanzo router stop
```
### Interactive REPL
```bash
# Start REPL
hanzo repl
# In REPL:
> /help # Show help
> /models # List models
> /model gpt-4 # Switch model
> /clear # Clear context
> What is Python? # Ask questions
```
## Python API
### Batch Orchestration
The Python library pieces, importable without touching the CLI:
```python
from hanzo.batch_orchestrator import BatchOrchestrator
orchestrator = BatchOrchestrator()
results = await orchestrator.run_batch([
"Summarize quantum computing",
"Explain machine learning",
"Define artificial intelligence"
"Summarize the incident report",
"Draft the follow-up email",
])
```
### Memory Management
```python
from hanzo.memory_manager import MemoryManager
memory = MemoryManager()
memory.add_to_context("user", "What is Python?")
memory.add_to_context("assistant", "Python is...")
memory.add_to_context("user", "What changed in the last deploy?")
context = memory.get_context()
```
### Fallback Handling
```python
from hanzo.fallback_handler import FallbackHandler
handler = FallbackHandler()
result = await handler.handle_with_fallback(
primary_fn=api_call,
fallback_fn=local_inference
fallback_fn=local_inference,
)
```
For the typed Hanzo Cloud API client, install [`hanzoai`](https://pypi.org/project/hanzoai/).
## Configuration
### Environment Variables
```bash
# API settings
HANZO_API_KEY=your-api-key
HANZO_API_KEY=hk-...
HANZO_BASE_URL=https://api.hanzo.ai
# Router settings
HANZO_ROUTER_URL=http://localhost:4000/v1
# Node settings
HANZO_NODE_URL=http://localhost:8000/v1
HANZO_NODE_WORKERS=4
# Model preferences
HANZO_DEFAULT_MODEL=gpt-4
HANZO_FALLBACK_MODEL=llama2:7b
```
### Configuration File
Create `~/.hanzo/config.yaml`:
```yaml
api:
key: your-api-key
base_url: https://api.hanzo.ai
router:
url: http://localhost:4000/v1
auto_start: true
node:
url: http://localhost:8000/v1
workers: 4
models:
- llama2:7b
- mistral:7b
models:
default: gpt-4
fallback: llama2:7b
```
## Architecture
### Components
- **CLI**: Command-line interface (`cli.py`)
- **Chat**: Interactive chat interface (`commands/chat.py`)
- **Node**: Local AI node management (`commands/node.py`)
- **Router**: LLM proxy management (`commands/router.py`)
- **REPL**: Interactive Python REPL (`interactive/repl.py`)
- **Orchestrator**: Batch task orchestration (`batch_orchestrator.py`)
- **Memory**: Conversation memory (`memory_manager.py`)
- **Fallback**: Resilient API handling (`fallback_handler.py`)
### Port Allocation
- **4000**: Router (LLM proxy)
- **8000**: Node (local AI)
- **9550-9553**: Desktop app integration
Model ids come from the cloud catalog, not from this file — `zen5`,
`zen5-coder`, `zen5-flash`, `zen5-mini`, `zen5-pro`, `enso`, `enso-flash`,
`enso-ultra`. Ask the cloud rather than hardcoding: `hanzo models list`.
## Development
### Setup
```bash
cd pkg/hanzo
uv sync --all-extras
```
### Testing
```bash
# Run tests
pytest tests/
# With coverage
pytest tests/ --cov=hanzo
```
### Building
```bash
uv build
```
## License
Apache License 2.0
Apache 2.0
pkg/hanzo/pyproject.toml
+5 -2
View File
@@ -1,7 +1,7 @@
[project]
name = "hanzo"
version = "0.4.4"
description = "Hanzo AI - Complete AI Infrastructure Platform with CLI, Router, MCP, and Agent Runtime"
description = "Python orchestration tools for Hanzo AI. The `hanzo` command itself is now a native binary — https://hanzo.sh"
authors = [
{name = "Hanzo AI", email = "[email protected]"},
]
@@ -30,8 +30,11 @@ classifiers = [
"Topic :: Scientific/Engineering :: Artificial Intelligence",
]
# The console script is `hanzo-py`, NOT `hanzo`. `hanzo` is the native Hanzo
# CLI (curl -fsSL https://hanzo.sh | sh). Two programs on PATH under one name
# is how `hanzo login` came to mean different things to different people.
[project.scripts]
hanzo = "hanzo.cli:main"
hanzo-py = "hanzo.cli:main"
[project.optional-dependencies]
all = [