mirror of
https://github.com/hanzoai/stack.git
synced 2026-11-19 03:06:57 +00:00
18 KiB
18 KiB
hanzo-cli Package Design
The hanzo-cli package provides a unified command-line interface to the entire Hanzo AI ecosystem, exposing all SDK functionality through a single hanzo command.
Package Structure
pkg/hanzo-cli/
├── pyproject.toml
├── README.md
├── src/
│ └── hanzo_cli/
│ ├── __init__.py
│ ├── __main__.py # Entry point for python -m hanzo
│ ├── cli.py # Main CLI using Click/Typer
│ ├── commands/
│ │ ├── __init__.py
│ │ ├── agent.py # Agent management commands
│ │ ├── cluster.py # Cluster commands
│ │ ├── mcp.py # MCP server commands
│ │ ├── miner.py # Mining commands
│ │ ├── chat.py # Interactive chat
│ │ ├── tools.py # Tool execution
│ │ ├── network.py # Network commands
│ │ └── config.py # Configuration
│ ├── interactive/
│ │ ├── __init__.py
│ │ ├── repl.py # Interactive REPL
│ │ ├── chat.py # Chat interface
│ │ └── dashboard.py # TUI dashboard
│ └── utils/
│ ├── __init__.py
│ ├── output.py # Rich output formatting
│ ├── config.py # Config management
│ └── auth.py # Authentication
├── completions/
│ ├── hanzo.bash
│ ├── hanzo.zsh
│ └── hanzo.fish
└── tests/
└── test_cli.py
pyproject.toml Configuration
[project]
name = "hanzo-cli"
version = "1.0.0"
description = "Unified CLI for Hanzo AI"
dependencies = [
"hanzoai>=1.0.0",
"hanzo-cluster>=0.1.0",
"hanzo-miner>=0.1.0",
"hanzo-mcp>=0.1.0",
"hanzo-agents>=0.1.0",
"hanzo-network>=0.1.0",
"hanzo-a2a>=0.1.0",
"click>=8.0.0",
"rich>=13.0.0",
"typer>=0.9.0",
"prompt-toolkit>=3.0.0",
"httpx>=0.23.0",
"pydantic>=2.0.0",
]
[project.scripts]
hanzo = "hanzo_cli.cli:main"
[project.urls]
Homepage = "https://hanzo.ai"
Repository = "https://github.com/hanzoai/python-sdk"
Documentation = "https://docs.hanzo.ai/cli"
# Publish as both hanzo-cli and hanzo
[tool.hatch.build]
packages = ["src/hanzo_cli"]
[tool.hatch.build.targets.wheel]
packages = ["src/hanzo_cli"]
# Additional metadata for PyPI
[project.keywords]
keywords = ["ai", "cli", "hanzo", "agents", "llm", "mcp"]
[project.classifiers]
classifiers = [
"Development Status :: 5 - Production/Stable",
"Environment :: Console",
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
"Programming Language :: Python :: 3.8",
"Topic :: Software Development :: Libraries :: Python Modules",
]
Main CLI Structure (cli.py)
import click
import asyncio
from rich.console import Console
from rich.table import Table
from typing import Optional
import sys
from hanzo_cli.commands import agent, cluster, mcp, miner, chat, tools, network, config
from hanzo_cli.interactive import repl
from hanzo_cli.utils import output
console = Console()
@click.group(invoke_without_command=True)
@click.version_option(version="1.0.0", prog_name="hanzo")
@click.option('--verbose', '-v', is_flag=True, help='Verbose output')
@click.option('--json', is_flag=True, help='JSON output format')
@click.pass_context
def cli(ctx, verbose, json):
"""Hanzo AI - Unified CLI for local, private, and free AI.
Run without arguments to enter interactive mode.
"""
ctx.ensure_object(dict)
ctx.obj['verbose'] = verbose
ctx.obj['json'] = json
ctx.obj['console'] = console
if ctx.invoked_subcommand is None:
# No subcommand - enter interactive mode
console.print("[bold cyan]Welcome to Hanzo AI CLI[/bold cyan]")
console.print("Type 'help' for available commands or 'exit' to quit.\n")
asyncio.run(repl.start())
# Register command groups
cli.add_command(agent.agent_group)
cli.add_command(cluster.cluster_group)
cli.add_command(mcp.mcp_group)
cli.add_command(miner.miner_group)
cli.add_command(chat.chat_command)
cli.add_command(tools.tools_group)
cli.add_command(network.network_group)
cli.add_command(config.config_group)
# Quick aliases
@cli.command()
@click.argument('prompt', nargs=-1)
@click.option('--model', '-m', default='llama-3.2-3b', help='Model to use')
@click.option('--local/--cloud', default=True, help='Use local or cloud model')
def ask(prompt, model, local):
"""Quick question to AI (alias for 'hanzo chat --once')."""
prompt_text = ' '.join(prompt)
asyncio.run(chat.ask_once(prompt_text, model, local))
@cli.command()
def serve():
"""Start local AI cluster (alias for 'hanzo cluster start')."""
asyncio.run(cluster.start_cluster())
def main():
"""Main entry point."""
try:
cli()
except KeyboardInterrupt:
console.print("\n[yellow]Interrupted by user[/yellow]")
sys.exit(0)
except Exception as e:
console.print(f"[red]Error: {e}[/red]")
if ctx.obj.get('verbose'):
console.print_exception()
sys.exit(1)
if __name__ == '__main__':
main()
Command Examples
Agent Commands (commands/agent.py)
import click
from rich.table import Table
from hanzo_agents import create_agent, create_network
@click.group(name='agent')
def agent_group():
"""Manage AI agents."""
pass
@agent_group.command()
@click.option('--name', '-n', required=True, help='Agent name')
@click.option('--model', '-m', default='llama-3.2-3b', help='Model to use')
@click.option('--local/--cloud', default=True, help='Use local or cloud')
def create(name, model, local):
"""Create a new agent."""
agent = create_agent(
name=name,
model=model,
base_url="http://localhost:8000" if local else None
)
console.print(f"[green]Created agent: {name}[/green]")
@agent_group.command()
def list():
"""List available agents."""
# Would connect to agent registry
table = Table(title="Available Agents")
table.add_column("Name", style="cyan")
table.add_column("Model", style="green")
table.add_column("Status", style="yellow")
# Add agents to table
table.add_row("helper", "llama-3.2-3b", "active")
table.add_row("coder", "codellama-7b", "idle")
console.print(table)
@agent_group.command()
@click.argument('agents', nargs=-1, required=True)
@click.option('--task', '-t', required=True, help='Task to execute')
def run(agents, task):
"""Run a task with specified agents."""
# Create network and run task
network = create_network(agents=list(agents))
result = asyncio.run(network.run(task))
console.print(result)
Cluster Commands (commands/cluster.py)
@click.group(name='cluster')
def cluster_group():
"""Manage local AI cluster."""
pass
@cluster_group.command()
@click.option('--name', '-n', default='hanzo-local', help='Cluster name')
@click.option('--port', '-p', default=8000, help='API port')
@click.option('--models', '-m', multiple=True, help='Models to load')
async def start(name, port, models):
"""Start local AI cluster."""
from hanzo_cluster import start_local_cluster
with console.status("[bold green]Starting cluster..."):
cluster = await start_local_cluster(
name=name,
port=port,
models=list(models) if models else None
)
console.print(f"[green]✓[/green] Cluster started at http://localhost:{port}")
console.print("Press Ctrl+C to stop")
try:
await asyncio.Event().wait()
except KeyboardInterrupt:
await cluster.stop()
@cluster_group.command()
def status():
"""Show cluster status."""
# Check if cluster is running
import httpx
try:
response = httpx.get("http://localhost:8000/health")
if response.status_code == 200:
console.print("[green]✓[/green] Cluster is running")
# Show loaded models, memory usage, etc.
else:
console.print("[red]✗[/red] Cluster is not responding")
except:
console.print("[yellow]![/yellow] Cluster is not running")
Interactive Chat (commands/chat.py)
@click.command(name='chat')
@click.option('--model', '-m', default='llama-3.2-3b', help='Model to use')
@click.option('--local/--cloud', default=True, help='Use local or cloud')
@click.option('--once', is_flag=True, help='Single question mode')
@click.argument('prompt', nargs=-1)
async def chat_command(model, local, once, prompt):
"""Interactive AI chat."""
if once or prompt:
# Single question mode
await ask_once(' '.join(prompt), model, local)
else:
# Interactive chat
from hanzo_cli.interactive.chat import InteractiveChat
chat = InteractiveChat(model=model, local=local)
await chat.run()
async def ask_once(prompt: str, model: str, local: bool):
"""Ask a single question."""
from hanzoai import completion
if local:
# Use local cluster
response = await completion(
model=model,
messages=[{"role": "user", "content": prompt}],
base_url="http://localhost:8000"
)
else:
# Use cloud
response = completion(
model=f"anthropic/{model}" if "claude" in model else model,
messages=[{"role": "user", "content": prompt}]
)
console.print(response)
MCP Commands (commands/mcp.py)
@click.group(name='mcp')
def mcp_group():
"""Manage MCP servers and tools."""
pass
@mcp_group.command()
@click.option('--name', '-n', default='hanzo-mcp', help='Server name')
@click.option('--transport', '-t', type=click.Choice(['stdio', 'sse']), default='stdio')
@click.option('--allow-path', '-p', multiple=True, help='Allowed paths')
def serve(name, transport, allow_path):
"""Start MCP server."""
from hanzo_mcp import run_mcp_server
console.print(f"[cyan]Starting MCP server ({transport})...[/cyan]")
run_mcp_server(
name=name,
transport=transport,
allowed_paths=list(allow_path) or ['.']
)
@mcp_group.command()
def tools():
"""List available MCP tools."""
from hanzo_mcp import create_server
server = create_server()
tools = asyncio.run(server.mcp.list_tools())
table = Table(title="MCP Tools")
table.add_column("Name", style="cyan")
table.add_column("Description", style="white")
for tool in tools:
table.add_row(tool.name, tool.description)
console.print(table)
@mcp_group.command()
@click.argument('tool')
@click.option('--arg', '-a', multiple=True, help='Tool arguments (key=value)')
def run(tool, arg):
"""Run an MCP tool."""
# Parse arguments
args = {}
for a in arg:
key, value = a.split('=', 1)
args[key] = value
# Run tool
from hanzo_mcp import create_server
server = create_server()
result = asyncio.run(server.run_tool(tool, **args))
console.print(result)
Mining Commands (commands/miner.py)
@click.group(name='miner')
def miner_group():
"""Manage mining operations."""
pass
@miner_group.command()
@click.option('--wallet', '-w', required=True, help='Wallet address')
@click.option('--max-ram', type=int, help='Max RAM to use (GB)')
@click.option('--max-gpu', type=int, help='Max GPU memory (GB)')
async def start(wallet, max_ram, max_gpu):
"""Start mining."""
from hanzo_miner import join_mining_network
with console.status("[bold yellow]Joining mining network..."):
miner = await join_mining_network(
wallet_address=wallet,
max_ram=max_ram,
max_vram=max_gpu
)
console.print(f"[green]✓[/green] Mining started")
console.print(f"Wallet: {wallet}")
# Show mining stats periodically
while True:
await asyncio.sleep(60)
stats = miner.get_stats()
console.print(f"Compute: {stats['compute_contributed']}")
console.print(f"Rewards: {stats['rewards_earned']}")
@miner_group.command()
def stats():
"""Show mining statistics."""
# Connect to miner and show stats
pass
Interactive REPL (interactive/repl.py)
from prompt_toolkit import PromptSession
from prompt_toolkit.completion import WordCompleter
from prompt_toolkit.history import FileHistory
from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
import shlex
class HanzoREPL:
"""Interactive REPL for Hanzo CLI."""
def __init__(self):
self.commands = {
'help': self.help,
'exit': self.exit,
'agent': self.agent_commands,
'cluster': self.cluster_commands,
'chat': self.chat,
'tools': self.tools,
# ... more commands
}
self.completer = WordCompleter(
list(self.commands.keys()),
ignore_case=True
)
self.session = PromptSession(
history=FileHistory('.hanzo_history'),
auto_suggest=AutoSuggestFromHistory(),
completer=self.completer
)
async def run(self):
"""Run the REPL."""
console.print("[cyan]Hanzo Interactive Mode[/cyan]")
console.print("Type 'help' for commands, 'exit' to quit\n")
while True:
try:
# Get input
line = await self.session.prompt_async('hanzo> ')
if not line.strip():
continue
# Parse command
parts = shlex.split(line)
cmd = parts[0]
args = parts[1:]
# Execute command
if cmd in self.commands:
await self.commands[cmd](args)
else:
# Try to run as shell command
await self.shell_command(line)
except KeyboardInterrupt:
continue
except EOFError:
break
async def help(self, args):
"""Show help."""
console.print("""
Available commands:
agent - Manage agents
cluster - Manage local cluster
chat - Start chat session
tools - Run tools
miner - Mining operations
network - Network operations
config - Configuration
help - Show this help
exit - Exit REPL
""")
async def exit(self, args):
"""Exit REPL."""
console.print("[yellow]Goodbye![/yellow]")
raise EOFError
Dashboard TUI (interactive/dashboard.py)
from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Static, DataTable
from textual.containers import Container, Horizontal, Vertical
class HanzoDashboard(App):
"""TUI dashboard for Hanzo."""
CSS = """
.box {
border: solid green;
padding: 1;
margin: 1;
}
"""
def compose(self) -> ComposeResult:
yield Header()
yield Container(
Horizontal(
Vertical(
Static("Cluster Status", classes="box"),
Static("Models: llama-3.2-3b", classes="box"),
id="cluster"
),
Vertical(
Static("Active Agents", classes="box"),
DataTable(id="agents"),
id="agents-panel"
),
),
Horizontal(
Vertical(
Static("Mining Stats", classes="box"),
Static("Rate: 0 H/s", id="mining-rate"),
Static("Rewards: 0", id="rewards"),
id="mining"
),
Vertical(
Static("Recent Tasks", classes="box"),
DataTable(id="tasks"),
id="tasks-panel"
),
),
)
yield Footer()
def on_mount(self) -> None:
# Start updating stats
self.set_interval(1.0, self.update_stats)
async def update_stats(self) -> None:
# Update dashboard with latest stats
pass
Usage Examples
# Quick AI question
hanzo ask "What is the capital of France?"
# Start local cluster
hanzo serve
# Interactive chat
hanzo chat
# Chat with specific model
hanzo chat -m codellama-7b
# Create and run agent
hanzo agent create -n helper -m llama-3.2-3b
hanzo agent run helper -t "Write a Python hello world"
# Start mining
hanzo miner start -w 0x1234...
# Run MCP server
hanzo mcp serve --allow-path /workspace
# List MCP tools
hanzo mcp tools
# Run specific tool
hanzo mcp run search -a pattern=TODO -a path=.
# Interactive mode
hanzo
> chat
Starting chat session...
You: Hello!
AI: Hello! How can I help you today?
You: exit
> cluster status
✓ Cluster is running
> exit
Goodbye!
# Dashboard
hanzo dashboard
Shell Completions
The package includes shell completion scripts for bash, zsh, and fish that enable tab completion for all commands and options.
Configuration
Configuration stored in ~/.config/hanzo/config.yaml:
default_model: llama-3.2-3b
prefer_local: true
cluster:
port: 8000
models:
- llama-3.2-3b
- codellama-7b
mining:
wallet: "0x..."
max_ram: 16
max_gpu: 8
Benefits
- Unified Interface: Single CLI for entire Hanzo ecosystem
- Intuitive Commands: Logical command structure
- Interactive Mode: REPL for exploration
- Rich Output: Beautiful formatted output
- Shell Integration: Tab completion support
- Flexible: Use as one-off commands or interactive
- Discoverable: Built-in help and examples