python-sdk/docs/lib/repl.md

hanzo-repl

Interactive REPL (Read-Eval-Print Loop) for Hanzo AI.

Installation

pip install hanzo-repl

Overview

hanzo-repl provides an interactive command-line interface for AI agents with:

• Multiple Backends - IPython, Textual, and standard REPL
• Voice Mode - Speech-to-text input
• Command Palette - Quick access to commands
• Command Suggestions - Context-aware suggestions
• LLM Integration - Direct AI assistant access

Quick Start

# Start the REPL
hanzo-repl

# Or with Python
python -m hanzo_repl

Features

Standard REPL

from hanzo_repl import REPL

# Create and run REPL
repl = REPL()
repl.run()

IPython Backend

Enhanced REPL with IPython features:

from hanzo_repl import IPythonREPL

repl = IPythonREPL()
repl.run()

Features:

• Tab completion
• Syntax highlighting
• Magic commands
• History persistence

Textual Backend

Modern TUI (Text User Interface) REPL:

from hanzo_repl import TextualREPL

repl = TextualREPL()
repl.run()

Features:

• Rich UI components
• Multiple panes
• Mouse support
• Keyboard shortcuts

Voice Mode

Enable voice input:

from hanzo_repl import REPL, VoiceMode

repl = REPL()
voice = VoiceMode()

# Enable voice
repl.enable_voice(voice)

# Start listening
repl.run()

Voice Commands

Command	Action
"Hey Hanzo"	Activate voice input
"Stop"	Cancel current input
"Execute"	Run current command
"Clear"	Clear screen

Command Palette

Quick access to common commands:

from hanzo_repl import CommandPalette

palette = CommandPalette()

# Add custom commands
palette.add_command("build", "npm run build", category="dev")
palette.add_command("test", "pytest", category="dev")

# Open palette (Ctrl+Shift+P)
palette.show()

Default Commands

Category	Commands
File	Open, Save, Close
Edit	Cut, Copy, Paste, Undo
View	Zoom In, Zoom Out, Toggle Panel
Git	Status, Commit, Push, Pull
Run	Execute, Debug, Profile

Command Suggestions

Context-aware suggestions:

from hanzo_repl import CommandSuggestions

suggestions = CommandSuggestions()

# Get suggestions based on context
ctx = {"language": "python", "file": "main.py"}
sugg = suggestions.get(ctx)

# Returns relevant commands like:
# - python main.py
# - pytest
# - black main.py

LLM Integration

Direct AI assistant access:

from hanzo_repl import LLMClient

client = LLMClient()

# Ask the AI
response = await client.ask("How do I sort a list in Python?")
print(response)

# With context
response = await client.ask(
    "Explain this code",
    context=code_snippet,
)

Configuration

LLMClient(
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

CLI Options

# Choose backend
hanzo-repl --backend ipython
hanzo-repl --backend textual
hanzo-repl --backend standard

# Enable voice
hanzo-repl --voice

# Set LLM model
hanzo-repl --model claude-3

# Debug mode
hanzo-repl --debug

Keyboard Shortcuts

Navigation

Shortcut	Action
Ctrl+C	Cancel/interrupt
Ctrl+D	Exit REPL
Ctrl+L	Clear screen
Ctrl+R	Search history
Tab	Complete command

Editing

Shortcut	Action
Ctrl+A	Beginning of line
Ctrl+E	End of line
Ctrl+K	Kill to end of line
Ctrl+U	Kill to start of line
Ctrl+W	Delete word backward

Command Palette

Shortcut	Action
Ctrl+Shift+P	Open command palette
Ctrl+P	Quick open file
Ctrl+Shift+F	Search in files

Configuration

Config File

Create ~/.hanzo/repl.yaml:

backend: ipython
voice:
  enabled: true
  wake_word: "hey hanzo"
llm:
  model: claude-3
  temperature: 0.7
theme: dark
history:
  size: 10000
  file: ~/.hanzo/history

Environment Variables

Variable	Description
HANZO_REPL_BACKEND	Default backend
HANZO_REPL_VOICE	Enable voice (true/false)
HANZO_REPL_MODEL	LLM model
HANZO_REPL_THEME	Color theme

Custom Commands

Register custom commands:

from hanzo_repl import REPL, command

@command("hello")
def hello_command(args):
    """Say hello"""
    name = args.get("name", "World")
    print(f"Hello, {name}!")

repl = REPL()
repl.register_command(hello_command)
repl.run()

Plugins

Extend the REPL with plugins:

from hanzo_repl import Plugin, REPL

class MyPlugin(Plugin):
    name = "my-plugin"

    def on_load(self, repl):
        print("Plugin loaded!")

    def on_command(self, cmd):
        # Process commands
        pass

repl = REPL()
repl.load_plugin(MyPlugin())

API Reference

REPL Class

Method	Description
run()	Start the REPL
eval(code)	Evaluate code
register_command(cmd)	Add custom command
enable_voice(mode)	Enable voice input
load_plugin(plugin)	Load a plugin

LLMClient Class

Method	Description
ask(prompt, context)	Ask the AI
stream(prompt)	Stream response
set_model(model)	Change model

VoiceMode Class

Method	Description
start()	Start listening
stop()	Stop listening
set_wake_word(word)	Set activation word