154 lines
4.8 KiB
Markdown
154 lines
4.8 KiB
Markdown
# zeroclaw-tools
|
|
|
|
Python companion package for [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw) — LangGraph-based tool calling for consistent LLM agent execution.
|
|
|
|
## Why This Package?
|
|
|
|
Some LLM providers (particularly GLM-5/Zhipu and similar models) have inconsistent tool calling behavior when using text-based tool invocation. This package provides a LangGraph-based approach that delivers:
|
|
|
|
- **Consistent tool calling** across all OpenAI-compatible providers
|
|
- **Automatic tool loop** — keeps calling tools until the task is complete
|
|
- **Easy extensibility** — add new tools with a simple `@tool` decorator
|
|
- **Framework agnostic** — works with any OpenAI-compatible API
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install zeroclaw-tools
|
|
```
|
|
|
|
With Discord integration:
|
|
|
|
```bash
|
|
pip install zeroclaw-tools[discord]
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Basic Agent
|
|
|
|
```python
|
|
import asyncio
|
|
from zeroclaw_tools import create_agent, shell, file_read, file_write
|
|
from langchain_core.messages import HumanMessage
|
|
|
|
async def main():
|
|
# Create agent with tools
|
|
agent = create_agent(
|
|
tools=[shell, file_read, file_write],
|
|
model="glm-5",
|
|
api_key="your-api-key",
|
|
base_url="https://api.z.ai/api/coding/paas/v4"
|
|
)
|
|
|
|
# Execute a task
|
|
result = await agent.ainvoke({
|
|
"messages": [HumanMessage(content="List files in /tmp directory")]
|
|
})
|
|
|
|
print(result["messages"][-1].content)
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
### CLI Usage
|
|
|
|
```bash
|
|
# Set environment variables
|
|
export API_KEY="your-api-key"
|
|
export API_BASE="https://api.z.ai/api/coding/paas/v4"
|
|
|
|
# Run the CLI
|
|
zeroclaw-tools "List files in the current directory"
|
|
|
|
# Interactive mode (no message required)
|
|
zeroclaw-tools -i
|
|
```
|
|
|
|
### Discord Bot
|
|
|
|
```python
|
|
import os
|
|
from zeroclaw_tools.integrations import DiscordBot
|
|
|
|
bot = DiscordBot(
|
|
token=os.environ["DISCORD_TOKEN"],
|
|
guild_id=123456789,
|
|
allowed_users=["123456789"]
|
|
)
|
|
|
|
bot.run()
|
|
```
|
|
|
|
## Available Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `shell` | Execute shell commands |
|
|
| `file_read` | Read file contents |
|
|
| `file_write` | Write content to files |
|
|
| `web_search` | Search the web (requires Brave API key) |
|
|
| `http_request` | Make HTTP requests |
|
|
| `memory_store` | Store data in memory |
|
|
| `memory_recall` | Recall stored data |
|
|
|
|
## Creating Custom Tools
|
|
|
|
```python
|
|
from zeroclaw_tools import tool
|
|
|
|
@tool
|
|
def my_custom_tool(query: str) -> str:
|
|
"""Description of what this tool does."""
|
|
# Your implementation here
|
|
return f"Result for: {query}"
|
|
|
|
# Use with agent
|
|
agent = create_agent(tools=[my_custom_tool])
|
|
```
|
|
|
|
## Provider Compatibility
|
|
|
|
Works with any OpenAI-compatible provider:
|
|
|
|
- **Z.AI / GLM-5** — `https://api.z.ai/api/coding/paas/v4`
|
|
- **OpenRouter** — `https://openrouter.ai/api/v1`
|
|
- **Groq** — `https://api.groq.com/openai/v1`
|
|
- **DeepSeek** — `https://api.deepseek.com`
|
|
- **Ollama** — `http://localhost:11434/v1`
|
|
- **And many more...**
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────┐
|
|
│ Your Application │
|
|
├─────────────────────────────────────────────┤
|
|
│ zeroclaw-tools Agent │
|
|
│ ┌─────────────────────────────────────┐ │
|
|
│ │ LangGraph StateGraph │ │
|
|
│ │ ┌───────────┐ ┌──────────┐ │ │
|
|
│ │ │ Agent │───▶│ Tools │ │ │
|
|
│ │ │ Node │◀───│ Node │ │ │
|
|
│ │ └───────────┘ └──────────┘ │ │
|
|
│ └─────────────────────────────────────┘ │
|
|
├─────────────────────────────────────────────┤
|
|
│ OpenAI-Compatible LLM Provider │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Comparison with Rust ZeroClaw
|
|
|
|
| Feature | Rust ZeroClaw | zeroclaw-tools |
|
|
|---------|---------------|----------------|
|
|
| **Binary size** | ~3.4 MB | Python package |
|
|
| **Memory** | <5 MB | ~50 MB |
|
|
| **Startup** | <10ms | ~500ms |
|
|
| **Tool consistency** | Model-dependent | LangGraph guarantees |
|
|
| **Extensibility** | Rust traits | Python decorators |
|
|
|
|
Use **Rust ZeroClaw** for production edge deployments. Use **zeroclaw-tools** when you need guaranteed tool calling consistency or Python ecosystem integration.
|
|
|
|
## License
|
|
|
|
MIT License — see [LICENSE](../LICENSE)
|