mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
zeekay
f6fef478ad
Both sub-packages claimed BSD-3-Clause while hanzoai/python-sdk's root LICENSE is Apache-2.0, and neither ships its own LICENSE file. BSD-3 is out of scope for hanzoai originals under HIP-0137. The gimp README's aside about hanzoai/gimp-mcp's licence is dropped rather than restated — that repo states its own.
217 lines
4.3 KiB
Markdown
217 lines
4.3 KiB
Markdown
# Hanzo Dev
|
|
|
|
Interactive dev environment for Hanzo AI - Like Claude Code in your terminal.
|
|
|
|
## Features
|
|
|
|
- 🎯 **Direct MCP Access**: All 70+ MCP tools available as Python functions
|
|
- 💬 **Integrated Chat**: Chat with AI that can use MCP tools
|
|
- 🔧 **IPython Magic**: Advanced features with tab completion and magic commands
|
|
- 🎨 **Beautiful TUI**: Textual-based terminal UI with syntax highlighting
|
|
- 🔄 **Live Editing**: Edit code and see results immediately
|
|
- 🎤 **Voice Mode**: Speak to AI and hear responses (optional)
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install
|
|
pip install hanzo-dev
|
|
|
|
# Start interactive dev environment (recommended)
|
|
hanzo-dev
|
|
|
|
# Start IPython mode (advanced)
|
|
hanzo-dev-ipython
|
|
|
|
# Start TUI mode (beautiful interface)
|
|
hanzo-dev-tui
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic CLI Usage
|
|
|
|
The REPL integrates seamlessly with the Hanzo CLI:
|
|
|
|
```bash
|
|
# Interactive chat mode
|
|
hanzo chat
|
|
|
|
# Quick questions
|
|
hanzo ask "What files are in the current directory?"
|
|
|
|
# With specific model
|
|
hanzo ask "Explain this code" --model claude-3-opus
|
|
```
|
|
|
|
### REPL Commands
|
|
|
|
```python
|
|
# Direct tool access
|
|
>>> read_file(file_path="README.md")
|
|
>>> write_file(file_path="test.py", content="print('Hello')")
|
|
>>> search(query="def main", path=".")
|
|
|
|
# Chat with AI
|
|
>>> chat("Create a Python script that fetches weather data")
|
|
|
|
# AI will use tools automatically
|
|
>>> chat("Find all TODO comments in the codebase and create a summary")
|
|
```
|
|
|
|
### IPython Magic Commands
|
|
|
|
```python
|
|
# Quick chat
|
|
%chat What is 2+2?
|
|
|
|
# Multi-line chat
|
|
%%ai
|
|
Help me refactor this function to be more efficient.
|
|
It should handle edge cases better.
|
|
|
|
# List tools
|
|
%tools
|
|
|
|
# Change model
|
|
%model claude-3.5-sonnet
|
|
|
|
# Execute tool
|
|
%tool read_file {"file_path": "config.json"}
|
|
```
|
|
|
|
### TUI Mode Features
|
|
|
|
- **Split panes**: Code editor, chat, and output
|
|
- **Syntax highlighting**: Full language support
|
|
- **Tool palette**: Visual tool selection
|
|
- **History**: Navigate previous commands
|
|
- **Themes**: Dark/light mode support
|
|
|
|
## Environment Setup
|
|
|
|
Set at least one LLM provider:
|
|
|
|
```bash
|
|
export ANTHROPIC_API_KEY=your-key # For Claude
|
|
export OPENAI_API_KEY=your-key # For GPT
|
|
export HANZO_API_KEY=your-key # For Hanzo AI
|
|
```
|
|
|
|
## Advanced Features
|
|
|
|
### Voice Mode
|
|
|
|
Install voice dependencies:
|
|
|
|
```bash
|
|
pip install hanzo-dev[voice]
|
|
```
|
|
|
|
Enable in REPL:
|
|
|
|
```python
|
|
>>> enable_voice()
|
|
>>> chat("Hello") # Speak your message
|
|
```
|
|
|
|
### Custom Tools
|
|
|
|
Create custom tools on the fly:
|
|
|
|
```python
|
|
@register_tool
|
|
def my_tool(param: str) -> str:
|
|
"""My custom tool."""
|
|
return f"Processed: {param}"
|
|
|
|
# Now available to AI
|
|
>>> chat("Use my_tool to process 'hello'")
|
|
```
|
|
|
|
### Scripting
|
|
|
|
Use the REPL in scripts:
|
|
|
|
```python
|
|
from hanzo_dev import create_repl
|
|
|
|
async def main():
|
|
repl = create_repl()
|
|
result = await repl.chat("Analyze the project structure")
|
|
print(result)
|
|
```
|
|
|
|
## Integration with Hanzo Ecosystem
|
|
|
|
### With Hanzo MCP
|
|
|
|
All MCP tools are automatically available:
|
|
|
|
- File operations
|
|
- Code search and analysis
|
|
- Process management
|
|
- Git operations
|
|
- And 60+ more tools
|
|
|
|
### With Hanzo Agents
|
|
|
|
Create and manage agents:
|
|
|
|
```python
|
|
>>> agent = create_agent("researcher")
|
|
>>> agent.run("Research best practices for API design")
|
|
```
|
|
|
|
### With Hanzo Network
|
|
|
|
Dispatch to agent networks:
|
|
|
|
```python
|
|
>>> network.dispatch("Solve this problem", agents=5)
|
|
```
|
|
|
|
## Tips
|
|
|
|
1. **Tab Completion**: Use Tab to explore available tools and parameters
|
|
2. **Help System**: Use `?` after any function for documentation
|
|
3. **History**: Use up/down arrows to navigate command history
|
|
4. **Shortcuts**: Ctrl+R for reverse search, Ctrl+L to clear screen
|
|
5. **Output**: Results are automatically pretty-printed with Rich
|
|
|
|
## Troubleshooting
|
|
|
|
### No LLM Response
|
|
|
|
Ensure you have set API keys:
|
|
|
|
```bash
|
|
echo $ANTHROPIC_API_KEY # Should show your key
|
|
```
|
|
|
|
### Tool Errors
|
|
|
|
Check tool permissions:
|
|
|
|
```python
|
|
>>> mcp.get_allowed_paths()
|
|
>>> mcp.add_allowed_path("/path/to/allow")
|
|
```
|
|
|
|
### Performance
|
|
|
|
For better performance:
|
|
|
|
```python
|
|
>>> set_model("gpt-3.5-turbo") # Faster model
|
|
>>> set_streaming(True) # Stream responses
|
|
```
|
|
|
|
## Contributing
|
|
|
|
The REPL is part of the Hanzo Python SDK. See the main repository for contribution guidelines.
|
|
|
|
## License
|
|
|
|
Apache-2.0 — see the repository root [LICENSE](../../LICENSE), consistent with
|
|
the rest of `hanzoai/python-sdk`. Estate-wide licensing standard: HIP-0137 (`hanzoai/hips`). |