mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
feat: Major README reorganization and version updates
- Reorganized main README to focus on complete AI SDK ecosystem - Created dedicated hanzoai package README for AI client library - Clear distinction between ecosystem (hanzo) and client library (hanzoai) - Updated package descriptions and usage examples - Bump versions: hanzoai 2.0.2→2.1.0, hanzo 0.2.14→0.3.0, hanzo-mcp 0.7.7→0.8.0 - Highlighted hanzo net command for local AI orchestration - Added comprehensive installation variants and architecture details
This commit is contained in:
@@ -1,37 +1,163 @@
|
||||
# Hanzo Python API library
|
||||
# Hanzo AI SDK - Complete AI Infrastructure Platform
|
||||
|
||||
[](https://pypi.org/project/hanzoai/)
|
||||
[](https://pypi.org/project/hanzo/)
|
||||
[](https://pypi.org/project/hanzoai/)
|
||||
[](https://pypi.org/project/hanzo-mcp/)
|
||||
|
||||
The Hanzo Python library provides convenient access to the Hanzo REST API from any Python 3.8+
|
||||
application. The library includes type definitions for all request params and response fields,
|
||||
and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
|
||||
The complete AI infrastructure platform with unified CLI, AI client library, MCP tools, agent networks, and local AI orchestration. Everything you need to build, deploy, and orchestrate AI applications.
|
||||
|
||||
## Documentation
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# Install the complete platform
|
||||
pip install hanzo[all]
|
||||
|
||||
# Or install specific components
|
||||
pip install hanzo # CLI + network tools
|
||||
pip install hanzoai # AI client library
|
||||
pip install hanzo-mcp # MCP server & tools
|
||||
```
|
||||
|
||||
Start your local AI network:
|
||||
```bash
|
||||
hanzo net # Start local AI orchestration
|
||||
```
|
||||
|
||||
## 📦 Package Ecosystem
|
||||
|
||||
### Core Packages
|
||||
|
||||
| Package | Description | Install |
|
||||
|---------|------------|---------|
|
||||
| **`hanzo`** | 🎯 **Main CLI & Network** | `pip install hanzo` |
|
||||
| | - Universal CLI interface | |
|
||||
| | - Local AI network orchestration (90% cost reduction) | |
|
||||
| | - Peer agent networks with MCP | |
|
||||
| | - Commands: `hanzo net`, `hanzo chat`, `hanzo mcp` | |
|
||||
| **`hanzoai`** | 🤖 **AI Client Library** | `pip install hanzoai` |
|
||||
| | - 100+ LLM providers (OpenAI-compatible interface) | |
|
||||
| | - Unified gateway and proxy | |
|
||||
| | - Cost tracking and rate limiting | |
|
||||
| **`hanzo-mcp`** | 🛠️ **MCP Server & 70+ Tools** | `pip install hanzo-mcp` |
|
||||
| | - Complete development environment | |
|
||||
| | - Interactive notebooks, REPL, debugging | |
|
||||
| | - Multi-agent workflows and orchestration | |
|
||||
| **`hanzo-network`** | 🌐 **Decentralized Compute** | `pip install hanzo-network` |
|
||||
| | - Distributed AI workload management | |
|
||||
| | - Peer-to-peer agent networks | |
|
||||
|
||||
### Extended Ecosystem
|
||||
|
||||
| Package | Description |
|
||||
|---------|------------|
|
||||
| **`hanzo-agents`** | Multi-agent workflows and orchestration |
|
||||
| **`hanzo-memory`** | Vector memory and knowledge management |
|
||||
| **`hanzo-repl`** | Interactive AI-powered REPL |
|
||||
| **`hanzo-aci`** | AI-powered development tools |
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Local AI Orchestration (Hanzo Zen)
|
||||
Cost-effective orchestration model that runs on laptops, mobile, or edge devices:
|
||||
- **90% cost reduction** vs pure API calls
|
||||
- **Mixture of Experts (MoE)** architecture
|
||||
- **Local orchestration loop** with intelligent routing
|
||||
- **API-based LLMs** only for complex tasks
|
||||
- **Full MCP tool support** and recursive agent calls
|
||||
|
||||
### Agent Networks
|
||||
Two deployment architectures:
|
||||
1. **Traditional Swarm**: Hierarchical with main orchestrator
|
||||
2. **Peer Networks**: All agents equal, connected via MCP
|
||||
- Every agent exposes MCP tools to others
|
||||
- Recursive calling (`chat_with_*`, `delegate_to_*`)
|
||||
- Local orchestration with Hanzo Zen
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
The REST API documentation can be found on [docs.hanzo.ai](https://docs.hanzo.ai). The full API of this library can be found in [api.md](api.md).
|
||||
|
||||
## Installation
|
||||
## 💡 Installation Variants
|
||||
|
||||
```sh
|
||||
# install from PyPI
|
||||
```bash
|
||||
# Complete ecosystem
|
||||
pip install hanzo[all]
|
||||
|
||||
# Just the CLI and network tools
|
||||
pip install hanzo
|
||||
|
||||
# AI client library (like openai package)
|
||||
pip install hanzoai
|
||||
|
||||
# MCP development environment
|
||||
pip install hanzo-mcp
|
||||
|
||||
# Specific combinations
|
||||
pip install hanzo[ai,mcp] # CLI + AI client + MCP tools
|
||||
pip install hanzo[agents] # CLI + agent runtime
|
||||
```
|
||||
|
||||
## Usage
|
||||
## 🎯 Usage Examples
|
||||
|
||||
The full API of this library can be found in [api.md](api.md).
|
||||
### Command Line Interface
|
||||
```bash
|
||||
# Start local AI network (90% cost savings)
|
||||
hanzo net
|
||||
|
||||
# Interactive AI chat
|
||||
hanzo chat
|
||||
|
||||
# Launch MCP server for Claude Desktop
|
||||
hanzo mcp
|
||||
|
||||
# Run agent workflows
|
||||
hanzo agent --config my-team.yaml
|
||||
|
||||
# Check network status
|
||||
hanzo status
|
||||
```
|
||||
|
||||
### Python SDK - AI Client (hanzoai)
|
||||
```python
|
||||
import os
|
||||
# Use like OpenAI but with 100+ providers
|
||||
from hanzoai import Hanzo
|
||||
|
||||
client = Hanzo(
|
||||
api_key=os.environ.get("HANZO_API_KEY"), # This is the default and can be omitted
|
||||
client = Hanzo(api_key="your-key")
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4", # or claude-3-5-sonnet, llama-3, etc.
|
||||
messages=[{"role": "user", "content": "Hello!"}]
|
||||
)
|
||||
|
||||
response = client.get_home()
|
||||
```
|
||||
|
||||
### Unified SDK - Everything Together
|
||||
```python
|
||||
import hanzo
|
||||
|
||||
# Use AI client
|
||||
client = hanzo.Client(api_key="your-key")
|
||||
|
||||
# Start agent network
|
||||
network = hanzo.Network()
|
||||
network.start_agents(["coder", "reviewer", "tester"])
|
||||
|
||||
# Use MCP tools
|
||||
from hanzo.mcp import search, edit, critic
|
||||
search("authentication bug")
|
||||
edit("fix auth issue")
|
||||
critic("review this change")
|
||||
```
|
||||
|
||||
### MCP Development Environment
|
||||
```bash
|
||||
# Install to Claude Desktop
|
||||
uvx hanzo-mcp
|
||||
|
||||
# Or run standalone
|
||||
hanzo-mcp --tools search,edit,notebook,agent
|
||||
```
|
||||
|
||||
The full API reference can be found in [api.md](api.md).
|
||||
|
||||
While you can provide an `api_key` keyword argument,
|
||||
we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
|
||||
to add `HANZO_API_KEY="sk-xxxxxxx` to your `.env` file
|
||||
|
||||
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "hanzo-mcp"
|
||||
version = "0.7.7"
|
||||
version = "0.8.0"
|
||||
description = "The Zen of Hanzo MCP: One server to rule them all. The ultimate MCP that orchestrates all others."
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.12"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "hanzo"
|
||||
version = "0.2.14"
|
||||
version = "0.3.0"
|
||||
description = "Hanzo AI - Complete AI Infrastructure Platform with CLI, Router, MCP, and Agent Runtime"
|
||||
authors = [
|
||||
{name = "Hanzo AI", email = "[email protected]"},
|
||||
|
||||
@@ -0,0 +1,260 @@
|
||||
# Hanzo AI Client Library
|
||||
|
||||
[](https://pypi.org/project/hanzoai/)
|
||||
|
||||
A unified AI client library providing access to 100+ LLM providers through a single OpenAI-compatible interface. Part of the [Hanzo AI SDK ecosystem](https://github.com/hanzoai/python-sdk).
|
||||
|
||||
## Features
|
||||
|
||||
- **100+ LLM Providers**: OpenAI, Anthropic, Google, AWS Bedrock, Azure, and more
|
||||
- **OpenAI-Compatible**: Drop-in replacement for `openai` package
|
||||
- **Unified Gateway**: Route requests through Hanzo LLM proxy for cost optimization
|
||||
- **Type Safety**: Full TypeScript-style type hints for all APIs
|
||||
- **Async Support**: Both sync and async clients
|
||||
- **Cost Tracking**: Built-in usage monitoring and rate limiting
|
||||
|
||||
## Installation
|
||||
|
||||
```sh
|
||||
pip install hanzoai
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
from hanzoai import Hanzo
|
||||
|
||||
# Initialize client (uses HANZO_API_KEY env var by default)
|
||||
client = Hanzo()
|
||||
|
||||
# Chat completions (OpenAI-compatible)
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4", # or any supported model
|
||||
messages=[
|
||||
{"role": "user", "content": "Hello, world!"}
|
||||
]
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
|
||||
## Supported Models
|
||||
|
||||
### OpenAI
|
||||
- `gpt-4`, `gpt-4-turbo`, `gpt-4o`
|
||||
- `gpt-3.5-turbo`
|
||||
|
||||
### Anthropic
|
||||
- `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-haiku`
|
||||
|
||||
### Google
|
||||
- `gemini-pro`, `gemini-1.5-pro`
|
||||
|
||||
### Open Source
|
||||
- `llama-3-70b`, `llama-3-8b`
|
||||
- `mixtral-8x7b`, `mixtral-8x22b`
|
||||
- `qwen-2-72b`
|
||||
|
||||
And 90+ more models from providers like AWS Bedrock, Azure, Together AI, Replicate, and others.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Chat
|
||||
```python
|
||||
from hanzoai import Hanzo
|
||||
|
||||
client = Hanzo(api_key="your-hanzo-api-key")
|
||||
|
||||
response = client.chat.completions.create(
|
||||
model="claude-3-5-sonnet",
|
||||
messages=[
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Explain quantum computing"}
|
||||
],
|
||||
max_tokens=1000,
|
||||
temperature=0.7
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
|
||||
### Streaming Responses
|
||||
```python
|
||||
stream = client.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=[{"role": "user", "content": "Write a story"}],
|
||||
stream=True
|
||||
)
|
||||
|
||||
for chunk in stream:
|
||||
if chunk.choices[0].delta.content is not None:
|
||||
print(chunk.choices[0].delta.content, end="")
|
||||
```
|
||||
|
||||
### Async Client
|
||||
```python
|
||||
import asyncio
|
||||
from hanzoai import AsyncHanzo
|
||||
|
||||
async def main():
|
||||
client = AsyncHanzo(api_key="your-api-key")
|
||||
|
||||
response = await client.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=[{"role": "user", "content": "Hello async world!"}]
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
### Multiple Providers
|
||||
```python
|
||||
# Route different models through the same interface
|
||||
responses = []
|
||||
|
||||
for model in ["gpt-4", "claude-3-5-sonnet", "llama-3-70b"]:
|
||||
response = client.chat.completions.create(
|
||||
model=model,
|
||||
messages=[{"role": "user", "content": "What is AI?"}],
|
||||
max_tokens=100
|
||||
)
|
||||
responses.append((model, response.choices[0].message.content))
|
||||
|
||||
for model, answer in responses:
|
||||
print(f"\n{model}:")
|
||||
print(answer)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
export HANZO_API_KEY="your-api-key"
|
||||
export HANZO_BASE_URL="https://api.hanzo.ai" # Optional, defaults to hanzo.ai
|
||||
```
|
||||
|
||||
### Client Configuration
|
||||
```python
|
||||
client = Hanzo(
|
||||
api_key="your-api-key",
|
||||
base_url="https://api.hanzo.ai", # Custom endpoint
|
||||
timeout=60.0, # Request timeout
|
||||
max_retries=3 # Retry failed requests
|
||||
)
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Cost Tracking
|
||||
```python
|
||||
# Get usage statistics
|
||||
usage = client.usage.get()
|
||||
print(f"Total tokens: {usage.total_tokens}")
|
||||
print(f"Total cost: ${usage.total_cost}")
|
||||
|
||||
# Set budget limits
|
||||
client.budget.create(
|
||||
limit=100.0, # $100 monthly limit
|
||||
period="monthly"
|
||||
)
|
||||
```
|
||||
|
||||
### Custom Headers
|
||||
```python
|
||||
client = Hanzo(
|
||||
default_headers={
|
||||
"User-Agent": "MyApp/1.0",
|
||||
"X-Custom-Header": "value"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```python
|
||||
from hanzoai import APIError, RateLimitError, AuthenticationError
|
||||
|
||||
try:
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4",
|
||||
messages=[{"role": "user", "content": "Hello!"}]
|
||||
)
|
||||
except AuthenticationError:
|
||||
print("Invalid API key")
|
||||
except RateLimitError:
|
||||
print("Rate limit exceeded")
|
||||
except APIError as e:
|
||||
print(f"API error: {e}")
|
||||
```
|
||||
|
||||
## Drop-in OpenAI Replacement
|
||||
|
||||
Replace `openai` imports with `hanzoai` for instant access to 100+ models:
|
||||
|
||||
```python
|
||||
# Before
|
||||
from openai import OpenAI
|
||||
client = OpenAI(api_key="...")
|
||||
|
||||
# After
|
||||
from hanzoai import Hanzo as OpenAI # Alias for compatibility
|
||||
client = OpenAI(api_key="...")
|
||||
|
||||
# Same interface, 100x more models!
|
||||
```
|
||||
|
||||
## Integration with Hanzo Ecosystem
|
||||
|
||||
This package integrates seamlessly with other Hanzo AI components:
|
||||
|
||||
```python
|
||||
# Use with Hanzo CLI
|
||||
import hanzo
|
||||
client = hanzo.Client() # Auto-configured from CLI
|
||||
|
||||
# Use with Hanzo MCP tools
|
||||
from hanzo.mcp import llm_tool
|
||||
llm_tool.set_client(client)
|
||||
|
||||
# Use with Hanzo Agents
|
||||
from hanzo.agents import Agent
|
||||
agent = Agent(llm_client=client)
|
||||
```
|
||||
|
||||
## API Compatibility
|
||||
|
||||
The `hanzoai` package implements the OpenAI API specification:
|
||||
- Chat Completions (`/v1/chat/completions`)
|
||||
- Embeddings (`/v1/embeddings`)
|
||||
- Images (`/v1/images/generations`)
|
||||
- Audio (`/v1/audio/transcriptions`, `/v1/audio/speech`)
|
||||
- Files (`/v1/files`)
|
||||
- Fine-tuning (`/v1/fine_tuning/jobs`)
|
||||
|
||||
Plus Hanzo-specific extensions:
|
||||
- Multi-provider routing
|
||||
- Cost optimization
|
||||
- Usage analytics
|
||||
- Model switching
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Full API Reference](api.md)** - Complete API documentation
|
||||
- **[Hanzo AI Docs](https://docs.hanzo.ai)** - Official documentation
|
||||
- **[Model Provider Guide](https://docs.hanzo.ai/providers)** - Supported models
|
||||
- **[Migration Guide](https://docs.hanzo.ai/migration)** - Migrate from OpenAI
|
||||
|
||||
## Related Packages
|
||||
|
||||
- **[hanzo](https://pypi.org/project/hanzo/)** - CLI and network tools
|
||||
- **[hanzo-mcp](https://pypi.org/project/hanzo-mcp/)** - MCP development environment
|
||||
- **[hanzo-agents](https://pypi.org/project/hanzo-agents/)** - Multi-agent workflows
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## License
|
||||
|
||||
Apache 2.0 - see [LICENSE](../../LICENSE) for details.
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "hanzoai"
|
||||
version = "2.0.2"
|
||||
version = "2.1.0"
|
||||
description = "The official Python library for the Hanzo API"
|
||||
dynamic = ["readme"]
|
||||
license = "BSD-3-Clause"
|
||||
|
||||
Reference in New Issue
Block a user