mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
zeekay
241ca6dc59
README: PyPI serves 3.2.1 and this tree is 3.2.11, so the install line is the git one. Between the two the default version left the operation ids — 3.2.1 carries get_v1_keys/get_v1_tools (182 api modules, 2172 models) and this carries get_keys/get_tools — so `pip install hanzoai` above a `get_keys()` quickstart hands the reader a client that cannot run it. Counts are measured off the pinned document: 1814 paths, 2479 operations, 191 tags + default_api = 192 API classes over 2460 models, 2659 importable modules. Auth was wrong everywhere and it was the same root cause: the document declares no securityScheme, so every operation got an empty auth_settings and Configuration(access_token=…) is read by nothing. Serializing get_keys from such a Configuration produces a request with no Authorization header at all — the five flows have been calling anonymously and reading the refusal as a bad key. examples/client.py now passes the bearer through ApiClient's header_name/value pair, verified against a local server that echoes what it received, and a smoke test pins both halves so the day cloud emits the scheme, the test fails and the header moves back into Configuration. The examples gate resolved class names and stopped there, which is how `money` and `tools` once passed it while every call in them named a method that no longer existed. It now walks the syntax tree for attribute accesses on anything bound to a *Api and asks the class: ten names resolve, and a stale get_v1_tools fails in the same second the import passes. Deleted five example scripts that imported hanzoai.Hanzo, hanzoai.cluster, hanzoai.agents and hanzoai.completion — none of which exist — or were dict literals captioned "in practice this would be called through the MCP interface"; compileall passed all five, because syntax is not a claim. Deleted three docs that were fabrication rather than drift and that nothing rendered: FEATURES.md, QUICKSTART.md, GPT5_ORCHESTRATION.md. pkg/hanzo-agent said `pip install hanzoai` and `from hanzoai import Agent, Runner`; the client has no Agent. Its own `full` extra resolved to hanzoai[web3,tee,marketplace,cli], extras the client does not declare, so it installed the client and none of the extensions. pyproject said BSD-3-Clause while LICENSE is the Apache 2.0 text. test_smoke imported tracker_api and no /v1/tracker path is emitted any more, so the suite carried a failing test naming a module the client does not have; it reads analytics_api now, off the client.
162 lines
4.7 KiB
Markdown
162 lines
4.7 KiB
Markdown
# Hanzo Python SDK
|
|
|
|
A workspace of 65 packages. Two things live here that people usually arrive for:
|
|
the API client, and the MCP server.
|
|
|
|
## The API client (`hanzoai`)
|
|
|
|
Generated from the Hanzo API's own OpenAPI document — 1814 paths, 2479
|
|
operations, 192 API classes over 2460 models. It is documented in the
|
|
[repository README](https://github.com/hanzoai/python-sdk#readme), which carries
|
|
the install line, the quickstart and the five runnable flows in `examples/`.
|
|
|
|
```python
|
|
import os
|
|
from hanzoai.cloud import ApiClient, Configuration, KeysApi
|
|
|
|
client = ApiClient(
|
|
Configuration(host="https://api.hanzo.ai"),
|
|
"Authorization", f"Bearer {os.environ['HANZO_API_KEY']}",
|
|
)
|
|
|
|
with client as api:
|
|
for key in KeysApi(api).get_keys().keys or []:
|
|
print(key.prefix, key.type, key.created_at)
|
|
```
|
|
|
|
The rest of this site is the MCP server, the agent framework and the tool
|
|
packages.
|
|
|
|
## Installation
|
|
|
|
=== "MCP server"
|
|
```bash
|
|
pip install hanzo-mcp
|
|
```
|
|
|
|
=== "Agent SDK"
|
|
```bash
|
|
pip install hanzo-agent
|
|
```
|
|
|
|
=== "Using uv"
|
|
```bash
|
|
uv pip install hanzo-mcp
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Using with Claude Code
|
|
|
|
The easiest way to use Hanzo MCP is with Claude Code:
|
|
|
|
```bash
|
|
# Install globally
|
|
uvx hanzo-mcp
|
|
|
|
# Or run directly
|
|
uvx hanzo-mcp --transport stdio
|
|
```
|
|
|
|
### Agent SDK Example
|
|
|
|
```python
|
|
from agents import Agent, Runner
|
|
|
|
agent = Agent(
|
|
name="assistant",
|
|
instructions="You are a helpful assistant."
|
|
)
|
|
|
|
result = Runner.run_sync(agent, "Hello!")
|
|
print(result.final_output)
|
|
```
|
|
|
|
### MCP Tools Example
|
|
|
|
```python
|
|
from hanzo_mcp import create_mcp_server
|
|
|
|
# Create server with all tools
|
|
server = create_mcp_server()
|
|
server.run()
|
|
```
|
|
|
|
## Packages
|
|
|
|
| Package | Description | PyPI |
|
|
|---------|-------------|------|
|
|
| `hanzo-mcp` | MCP server with all tools | [](https://pypi.org/project/hanzo-mcp/) |
|
|
| `hanzo-agent` | Agent SDK | [](https://pypi.org/project/hanzo-agent/) |
|
|
| `hanzo-tools-shell` | Shell/command tools | [](https://pypi.org/project/hanzo-tools-shell/) |
|
|
| `hanzo-tools-fs` | File system tools | [](https://pypi.org/project/hanzo-tools-fs/) |
|
|
| `hanzo-tools-browser` | Browser automation | [](https://pypi.org/project/hanzo-tools-browser/) |
|
|
| `hanzo-tools-memory` | Memory/knowledge tools | [](https://pypi.org/project/hanzo-tools-memory/) |
|
|
|
|
## Features
|
|
|
|
### 30+ MCP Tools
|
|
|
|
- **File System**: `read`, `write`, `edit`, `tree`, `find`, `search`, `ast`
|
|
- **Shell**: `cmd`, `zsh`, `bash`, `ps`, `npx`, `uvx`, `open`
|
|
- **Browser**: Full Playwright automation with 70+ actions
|
|
- **Memory**: Unified memory tool with recall, create, update, delete
|
|
- **Reasoning**: `think`, `critic` for structured AI reasoning
|
|
- **LSP**: Go-to-definition, find references, rename, hover
|
|
- **Refactor**: Advanced code refactoring with AST support
|
|
- **Agent**: Run external AI agents (Claude, Gemini, Codex, etc.)
|
|
- **LLM**: Direct LLM access and multi-model consensus
|
|
|
|
### Auto-Backgrounding
|
|
|
|
Long-running commands automatically background after 30 seconds:
|
|
|
|
```python
|
|
# This will auto-background if it takes too long
|
|
cmd("npm install")
|
|
|
|
# Check status
|
|
ps() # List all background processes
|
|
ps(logs="cmd_xxx") # View output
|
|
ps(kill="cmd_xxx") # Stop process
|
|
```
|
|
|
|
### Multi-Backend Support
|
|
|
|
Use the MCP with any AI assistant:
|
|
|
|
- **Claude Code** - `uvx hanzo-mcp`
|
|
- **VS Code/Cursor** - Hanzo extension with auto-detection
|
|
- **Antigravity** - Full integration via Open VSX
|
|
- **Any MCP Client** - Standard MCP protocol
|
|
|
|
## Documentation
|
|
|
|
### Getting Started
|
|
|
|
- [Quickstart Guide](getting-started/quickstart.md)
|
|
- [MCP Quickstart](mcp/quickstart.md)
|
|
- [MCP Configuration](mcp/configuration.md)
|
|
|
|
### Reference
|
|
|
|
- [Tools Reference](tools/index.md) - All 30+ tool packages
|
|
- [Agent Reference](ref/agent/index.md) - Agent SDK documentation
|
|
- [MCP Reference](ref/mcp/index.md) - MCP server documentation
|
|
- [Core Libraries](lib/index.md) - Supporting packages (async, consensus, network)
|
|
|
|
### Tool Categories
|
|
|
|
- [Filesystem Tools](tools/fs.md) - File operations and AST analysis
|
|
- [Shell Tools](tools/shell.md) - Command execution and process management
|
|
- [Browser Tool](tools/browser.md) - Playwright automation
|
|
- [Memory Tools](tools/memory.md) - Persistent memory and knowledge bases
|
|
- [Reasoning Tools](tools/reasoning.md) - Structured thinking and analysis
|
|
|
|
## Links
|
|
|
|
- [GitHub Repository](https://github.com/hanzoai/python-sdk)
|
|
- [PyPI Package](https://pypi.org/project/hanzo-mcp/)
|
|
- [Discord Community](https://discord.gg/CJCyAsm9Vr)
|
|
- [Hanzo AI](https://hanzo.ai)
|