mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
docs: improve DX with navigation and cross-references
- Update docs/mcp/tools/ placeholders with quick refs and links - Create docs/ref/tools/index.md with full package table - Create docs/ref/agent/index.md with topic links - Create docs/ref/mcp/index.md with tool categories - Create docs/tools/index.md as main entry point - Add consistent cross-references between sections
This commit is contained in:
+20
-2
@@ -1,2 +1,20 @@
|
||||
# agent
|
||||
Documentation coming soon.
|
||||
# Agent Tools
|
||||
|
||||
Multi-agent orchestration with CLI integration.
|
||||
|
||||
→ **Full documentation: [../../tools/agent.md](../../tools/agent.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```python
|
||||
# Run agent
|
||||
agent(action="run", name="claude", prompt="Explain this code")
|
||||
|
||||
# List available agents
|
||||
agent(action="list")
|
||||
|
||||
# Multi-agent consensus
|
||||
agent(action="consensus", prompt="Design an API", agents=["claude", "gemini"])
|
||||
```
|
||||
|
||||
Available agents: `claude`, `codex`, `gemini`, `grok`, `qwen`, `vibe`, `code`, `dev`
|
||||
|
||||
@@ -1,2 +1,26 @@
|
||||
# urowser
|
||||
Documentation coming soon.
|
||||
# Browser Tool
|
||||
|
||||
Complete Playwright automation with 70+ actions.
|
||||
|
||||
→ **Full documentation: [../../tools/browser.md](../../tools/browser.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```python
|
||||
# Navigate
|
||||
browser(action="navigate", url="https://example.com")
|
||||
|
||||
# Click element
|
||||
browser(action="click", selector="button.submit")
|
||||
|
||||
# Fill form
|
||||
browser(action="fill", selector="input[name=email]", text="[email protected]")
|
||||
|
||||
# Screenshot
|
||||
browser(action="screenshot", full_page=True)
|
||||
|
||||
# Device emulation
|
||||
browser(action="emulate", device="mobile")
|
||||
```
|
||||
|
||||
Supports: navigation, forms, mouse, touch, assertions, storage, network, and more.
|
||||
|
||||
@@ -1,2 +1,32 @@
|
||||
# filesystem
|
||||
Documentation coming soon.
|
||||
# Filesystem Tools
|
||||
|
||||
File operations with AST analysis.
|
||||
|
||||
→ **Full documentation: [../../tools/fs.md](../../tools/fs.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```python
|
||||
# Read file
|
||||
read(file_path="/path/to/file.py")
|
||||
|
||||
# Write file
|
||||
write(file_path="/path/to/file.py", content="...")
|
||||
|
||||
# Edit file
|
||||
edit(file_path="/path/to/file.py", old_string="old", new_string="new")
|
||||
|
||||
# Directory tree
|
||||
tree(path="/project", depth=3)
|
||||
|
||||
# Find files
|
||||
find(pattern="*.py", path="/src")
|
||||
|
||||
# Search content
|
||||
search(pattern="TODO", path=".")
|
||||
|
||||
# AST analysis
|
||||
ast(pattern="def test_", path="/tests")
|
||||
```
|
||||
|
||||
7 tools: `read`, `write`, `edit`, `tree`, `find`, `search`, `ast`
|
||||
|
||||
@@ -1,2 +1,23 @@
|
||||
# llm
|
||||
Documentation coming soon.
|
||||
# LLM Tools
|
||||
|
||||
Unified LLM interface via LiteLLM.
|
||||
|
||||
→ **Full documentation: [../../tools/llm-tools.md](../../tools/llm-tools.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```python
|
||||
# Call any LLM
|
||||
llm(model="gpt-4", prompt="Explain quantum computing")
|
||||
|
||||
# With system prompt
|
||||
llm(model="claude-3-5-sonnet", prompt="...", system="You are a helpful assistant")
|
||||
|
||||
# Multi-model consensus
|
||||
consensus(
|
||||
prompt="Best database for this use case?",
|
||||
models=["gpt-4", "claude-3-5-sonnet", "gemini-pro"]
|
||||
)
|
||||
```
|
||||
|
||||
Supports: OpenAI, Anthropic, Google, Together, Groq, Mistral, Ollama, and 100+ more.
|
||||
|
||||
+29
-2
@@ -1,2 +1,29 @@
|
||||
# lsp
|
||||
Documentation coming soon.
|
||||
# LSP Tool
|
||||
|
||||
Language Server Protocol for code intelligence.
|
||||
|
||||
→ **Full documentation: [../../tools/lsp.md](../../tools/lsp.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```python
|
||||
# Go to definition
|
||||
lsp(action="definition", file="main.py", line=10, character=15)
|
||||
|
||||
# Find references
|
||||
lsp(action="references", file="main.py", line=10, character=15)
|
||||
|
||||
# Hover information
|
||||
lsp(action="hover", file="main.py", line=10, character=15)
|
||||
|
||||
# Code completion
|
||||
lsp(action="completion", file="main.py", line=10, character=15)
|
||||
|
||||
# Rename symbol
|
||||
lsp(action="rename", file="main.py", line=10, character=15, new_name="newName")
|
||||
|
||||
# Get diagnostics
|
||||
lsp(action="diagnostics", file="main.py")
|
||||
```
|
||||
|
||||
Supported: Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Ruby, Lua
|
||||
|
||||
@@ -1,2 +1,29 @@
|
||||
# memory
|
||||
Documentation coming soon.
|
||||
# Memory Tools
|
||||
|
||||
Persistent memory and knowledge base management.
|
||||
|
||||
→ **Full documentation: [../../tools/memory.md](../../tools/memory.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```python
|
||||
# Recall memories
|
||||
recall_memories(queries=["project architecture"])
|
||||
|
||||
# Create memories
|
||||
create_memories(statements=["User prefers dark mode"])
|
||||
|
||||
# Store facts
|
||||
store_facts(facts=["API rate limit: 100/hour"], kb_name="api_docs")
|
||||
|
||||
# Recall facts
|
||||
recall_facts(queries=["rate limits"], kb_name="api_docs")
|
||||
|
||||
# Summarize to memory
|
||||
summarize_to_memory(content="...", topic="Architecture Decisions")
|
||||
|
||||
# Manage knowledge bases
|
||||
manage_knowledge_bases(action="create", kb_name="docs", description="Project docs")
|
||||
```
|
||||
|
||||
9 tools for memory and knowledge management.
|
||||
|
||||
@@ -1,2 +1,44 @@
|
||||
# reasoning
|
||||
Documentation coming soon.
|
||||
# Reasoning Tools
|
||||
|
||||
Structured thinking and critical analysis.
|
||||
|
||||
→ **Full documentation: [../../tools/reasoning.md](../../tools/reasoning.md)**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Think Tool
|
||||
|
||||
```python
|
||||
# Structured reasoning
|
||||
think(thought="""
|
||||
Analyzing the authentication architecture:
|
||||
1. Current: Session-based auth with cookies
|
||||
2. Problem: Mobile apps need token-based auth
|
||||
3. Options:
|
||||
- JWT tokens
|
||||
- OAuth 2.0
|
||||
- API keys
|
||||
4. Recommendation: JWT for stateless auth
|
||||
""")
|
||||
```
|
||||
|
||||
### Critic Tool
|
||||
|
||||
```python
|
||||
# Critical analysis
|
||||
critic(analysis="""
|
||||
Code Review Analysis:
|
||||
- Missing error handling for network failures
|
||||
- No input validation on user data
|
||||
- SQL injection vulnerability in query construction
|
||||
- N+1 database query problem in loop
|
||||
|
||||
Recommendations:
|
||||
1. Add try/catch with retry logic
|
||||
2. Validate all inputs at API boundary
|
||||
3. Use parameterized queries
|
||||
4. Batch database queries
|
||||
""")
|
||||
```
|
||||
|
||||
Use `think` for exploration, `critic` for quality assurance.
|
||||
|
||||
+45
-2
@@ -1,2 +1,45 @@
|
||||
# index
|
||||
Documentation coming soon.
|
||||
# Agent Reference
|
||||
|
||||
API reference for the hanzo-agent framework.
|
||||
|
||||
## Overview
|
||||
|
||||
hanzo-agent provides a multi-agent SDK with:
|
||||
|
||||
- OpenAI-compatible API
|
||||
- Multi-agent orchestration
|
||||
- Tool use and guardrails
|
||||
- Streaming and tracing
|
||||
|
||||
## Documentation
|
||||
|
||||
| Topic | Description |
|
||||
|-------|-------------|
|
||||
| [Getting Started](../../agent/index.md) | Introduction to agents |
|
||||
| [Running Agents](../../agent/running_agents.md) | How to run agents |
|
||||
| [Agent Config](../../agent/config.md) | Configuration options |
|
||||
| [Tools](../../agent/tools.md) | Tool integration |
|
||||
| [Guardrails](../../agent/guardrails.md) | Safety constraints |
|
||||
| [Multi-Agent](../../agent/multi_agent.md) | Orchestrating multiple agents |
|
||||
| [Handoffs](../../agent/handoffs.md) | Agent handoff patterns |
|
||||
| [Streaming](../../agent/streaming.md) | Streaming responses |
|
||||
| [Tracing](../../agent/tracing.md) | Debugging and tracing |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
from hanzo_agent import Agent, Runner
|
||||
|
||||
agent = Agent(
|
||||
name="assistant",
|
||||
instructions="You are a helpful assistant.",
|
||||
)
|
||||
|
||||
result = await Runner.run(agent, "Hello!")
|
||||
print(result.final_output)
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Agent Tools](../../tools/agent.md) - CLI agent integration
|
||||
- [Consensus Protocol](../../lib/consensus.md) - Multi-agent agreement
|
||||
|
||||
+65
-2
@@ -1,2 +1,65 @@
|
||||
# index
|
||||
Documentation coming soon.
|
||||
# MCP Reference
|
||||
|
||||
API reference for hanzo-mcp (Model Context Protocol).
|
||||
|
||||
## Overview
|
||||
|
||||
hanzo-mcp provides:
|
||||
|
||||
- 30+ tools for AI development
|
||||
- FastMCP-based server
|
||||
- Claude Code integration
|
||||
- Entry-point based tool discovery
|
||||
|
||||
## Documentation
|
||||
|
||||
| Topic | Description |
|
||||
|-------|-------------|
|
||||
| [Quickstart](../../mcp/quickstart.md) | Getting started |
|
||||
| [Configuration](../../mcp/configuration.md) | Server configuration |
|
||||
| [VS Code Setup](../../mcp/vscode.md) | IDE integration |
|
||||
| [Tool Parity](../../mcp/PARITY.md) | Feature comparison |
|
||||
|
||||
## Tool Categories
|
||||
|
||||
| Category | Docs |
|
||||
|----------|------|
|
||||
| [Shell](../../mcp/tools/shell.md) | Command execution |
|
||||
| [Filesystem](../../mcp/tools/filesystem.md) | File operations |
|
||||
| [Browser](../../mcp/tools/browser.md) | Web automation |
|
||||
| [Memory](../../mcp/tools/memory.md) | Persistent memory |
|
||||
| [Reasoning](../../mcp/tools/reasoning.md) | Thinking tools |
|
||||
| [Agent](../../mcp/tools/agent.md) | Multi-agent |
|
||||
| [LSP](../../mcp/tools/lsp.md) | Code intelligence |
|
||||
| [LLM](../../mcp/tools/llm-tools.md) | LLM interface |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install
|
||||
pip install hanzo-mcp[tools-all]
|
||||
|
||||
# Run server
|
||||
hanzo-mcp
|
||||
|
||||
# Or with specific tools
|
||||
hanzo-mcp --tools shell,browser,memory
|
||||
```
|
||||
|
||||
## Claude Code Integration
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"hanzo": {
|
||||
"command": "hanzo-mcp",
|
||||
"args": ["--stdio"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Tools Reference](../tools/index.md) - Full tool documentation
|
||||
- [Core Libraries](../../lib/index.md) - Supporting packages
|
||||
|
||||
+58
-2
@@ -1,2 +1,58 @@
|
||||
# index
|
||||
Documentation coming soon.
|
||||
# Tools Reference
|
||||
|
||||
Comprehensive API reference for all hanzo-tools-* packages.
|
||||
|
||||
## Tool Packages
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Core](../../tools/core.md) | Base classes | Foundation for tool development |
|
||||
| [Filesystem](../../tools/fs.md) | 7 | File operations and AST analysis |
|
||||
| [Shell](../../tools/shell.md) | 12 | Command execution and process management |
|
||||
| [Browser](../../tools/browser.md) | 1 (70+ actions) | Playwright automation |
|
||||
| [Memory](../../tools/memory.md) | 9 | Persistent memory and knowledge bases |
|
||||
| [Reasoning](../../tools/reasoning.md) | 2 | Structured thinking and analysis |
|
||||
| [Agent](../../tools/agent.md) | 3 | Multi-agent orchestration |
|
||||
| [LSP](../../tools/lsp.md) | 1 | Language server protocol |
|
||||
| [Refactor](../../tools/refactor.md) | 1 | Code refactoring with AST/LSP |
|
||||
| [LLM](../../tools/llm-tools.md) | 2 | Unified LLM interface |
|
||||
| [Database](../../tools/database.md) | 8 | SQL and graph databases |
|
||||
| [Vector](../../tools/vector.md) | 3 | Semantic search |
|
||||
| [Jupyter](../../tools/jupyter.md) | 1 | Notebook operations |
|
||||
| [Editor](../../tools/editor.md) | 3 | Neovim integration |
|
||||
| [Todo](../../tools/todo.md) | 1 | Task management |
|
||||
| [Computer](../../tools/computer.md) | 1 | Mac automation |
|
||||
| [Config](../../tools/config.md) | 2 | Configuration management |
|
||||
| [MCP](../../tools/mcp-tools.md) | 4 | MCP server management |
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
# All tools
|
||||
pip install hanzo-mcp[tools-all]
|
||||
|
||||
# Core + dev tools
|
||||
pip install hanzo-mcp[tools-dev]
|
||||
|
||||
# Specific packages
|
||||
pip install hanzo-tools-shell hanzo-tools-browser
|
||||
```
|
||||
|
||||
## Tool Discovery
|
||||
|
||||
Tools are discovered via entry points:
|
||||
|
||||
```python
|
||||
from importlib.metadata import entry_points
|
||||
|
||||
# Get all tool entry points
|
||||
eps = entry_points(group="hanzo.tools")
|
||||
for name, ep in eps.items():
|
||||
tools = ep.load()
|
||||
print(f"{name}: {len(tools)} tools")
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Configuration](../../mcp/configuration.md)
|
||||
- [MCP Quickstart](../../mcp/quickstart.md)
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
# Tools Overview
|
||||
|
||||
Complete documentation for all `hanzo-tools-*` packages.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# All tools (recommended)
|
||||
pip install hanzo-mcp[tools-all]
|
||||
|
||||
# Core development tools
|
||||
pip install hanzo-mcp[tools-dev]
|
||||
|
||||
# Individual packages
|
||||
pip install hanzo-tools-shell hanzo-tools-browser
|
||||
```
|
||||
|
||||
## Tool Categories
|
||||
|
||||
### Core Infrastructure
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Core](core.md) | Base classes | Foundation for tool development |
|
||||
| [Config](config.md) | 2 | Configuration and mode management |
|
||||
|
||||
### File & Code Operations
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Filesystem](fs.md) | 7 | read, write, edit, tree, find, search, ast |
|
||||
| [LSP](lsp.md) | 1 | Language server protocol (definition, references, hover) |
|
||||
| [Refactor](refactor.md) | 1 | Code refactoring (rename, extract, inline) |
|
||||
|
||||
### Shell & Execution
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Shell](shell.md) | 12 | cmd, ps, zsh, bash, fish, dash, npx, uvx, open, curl, jq, wget |
|
||||
| [Computer](computer.md) | 1 | Mac automation via pyautogui |
|
||||
|
||||
### AI & Agents
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Agent](agent.md) | 3 | Multi-agent orchestration (agent, iching, review) |
|
||||
| [LLM](llm-tools.md) | 2 | Unified LLM interface (llm, consensus) |
|
||||
| [Reasoning](reasoning.md) | 2 | Structured thinking (think, critic) |
|
||||
|
||||
### Data & Memory
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Memory](memory.md) | 9 | Persistent memory and knowledge bases |
|
||||
| [Database](database.md) | 8 | SQL and graph database operations |
|
||||
| [Vector](vector.md) | 3 | Semantic search with embeddings |
|
||||
|
||||
### Specialized
|
||||
|
||||
| Package | Tools | Description |
|
||||
|---------|-------|-------------|
|
||||
| [Browser](browser.md) | 1 | Playwright automation (70+ actions) |
|
||||
| [Jupyter](jupyter.md) | 1 | Notebook read/edit/execute |
|
||||
| [Editor](editor.md) | 3 | Neovim integration |
|
||||
| [Todo](todo.md) | 1 | Task management |
|
||||
| [MCP](mcp-tools.md) | 4 | MCP server management |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Most Used Tools
|
||||
|
||||
```python
|
||||
# File operations
|
||||
read(file_path="/path/to/file")
|
||||
write(file_path="/path/to/file", content="...")
|
||||
edit(file_path="/path/to/file", old_string="old", new_string="new")
|
||||
|
||||
# Command execution
|
||||
cmd("ls -la")
|
||||
cmd(["npm install", "npm build"], parallel=True)
|
||||
|
||||
# Search
|
||||
search(pattern="TODO", path=".")
|
||||
ast(pattern="def test_", path="/tests")
|
||||
|
||||
# Reasoning
|
||||
think(thought="Analyzing the problem...")
|
||||
critic(analysis="Code review findings...")
|
||||
|
||||
# Browser
|
||||
browser(action="navigate", url="https://example.com")
|
||||
browser(action="click", selector="button")
|
||||
```
|
||||
|
||||
### Tool Discovery
|
||||
|
||||
```python
|
||||
from importlib.metadata import entry_points
|
||||
|
||||
# Discover all available tools
|
||||
for ep in entry_points(group="hanzo.tools"):
|
||||
tools = ep.load()
|
||||
print(f"{ep.name}: {[t.name for t in tools]}")
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
All tools follow a consistent pattern:
|
||||
|
||||
```python
|
||||
from hanzo_tools.core import BaseTool, ToolContext
|
||||
|
||||
class MyTool(BaseTool):
|
||||
name = "my_tool"
|
||||
|
||||
@property
|
||||
def description(self) -> str:
|
||||
return "Tool description"
|
||||
|
||||
async def call(self, ctx: ToolContext, **params) -> str:
|
||||
# Implementation
|
||||
return result
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Core Libraries](../lib/index.md) - Supporting packages (async, consensus, network)
|
||||
- [MCP Reference](../ref/mcp/index.md) - Server documentation
|
||||
- [Agent Framework](../ref/agent/index.md) - Multi-agent SDK
|
||||
Reference in New Issue
Block a user