docs/TOOLS.md

Tools Documentation

Nexus Coder v0.2 có 18+ tools để tương tác với môi trường.

Safety Levels

Level	Icon	Description
SAFE	✓	Read-only, no side effects
MODERATE	⚠	Writes to local files
DANGEROUS	⚡	Executes commands, network ops
DESTRUCTIVE	💀	Can delete data, requires confirmation

Tools by Category

FILE Operations

• file_read (✓) - Đọc file text
• file_write (⚠) - Ghi file (overwrite/append)
• file_list (✓) - Liệt kê files với glob
• file_delete (💀) - Xóa file/thư mục

EXEC

• shell_exec (⚡) - Execute bash commands
• python_exec (⚡) - Execute Python code (sandboxed)
• git_ops (⚡) - Git commands

WEB

• http_request (⚠) - HTTP GET/POST/PUT/DELETE
• web_fetch (✓) - Fetch webpage, extract text
• web_search (✓) - Search web

CODE

• code_search (✓) - Regex search trong code
• code_lint (✓) - Lint code (ruff, flake8, pylint)
• code_format (⚠) - Format code (black, autopep8, isort)
• regex_search (✓) - Regex search trong files

MATH

• calculator (✓) - Safe math expression eval

PARSER

• json_parse (✓) - Parse JSON với query support
• yaml_parse (✓) - Parse YAML
• csv_parse (✓) - Parse CSV

SYSTEM

• datetime (✓) - DateTime operations + timezone

NETWORK

• dns_lookup (✓) - DNS lookup (A, AAAA, MX, NS, CNAME, TXT)
• ping (✓) - Ping host

CRYPTO

• hash (✓) - Compute hash (md5, sha1, sha256, sha512, blake2)
• encrypt (⚡) - AES-256-GCM encrypt/decrypt

FILE (Archive)

• archive (⚠) - ZIP/TAR create/extract/list

Usage

from nexus.tools import get_global_registry, ToolContext

registry = get_global_registry()

# List all tools
print(registry.list_tools())

# Execute tool
from nexus.tools.base import ToolContext
ctx = ToolContext(working_dir="/tmp")
result = registry.execute("file_read", {"path": "/etc/hostname"}, ctx)
print(result.output)

# Check safety
tool = registry.get("file_delete")
print(f"Safety: {tool.safety.value}")

Audit Log

All tool calls are logged to ./logs/tool_audit.jsonl:

{
  "timestamp": 1234567890.123,
  "tool": "file_write",
  "safety": "moderate",
  "args": {"path": "/tmp/test.txt", "content": "hello"},
  "working_dir": ".",
  "user_id": null,
  "success": true,
  "return_code": 0,
  "duration": 0.001
}

Safety Features

1. Confirmation required for DANGEROUS and DESTRUCTIVE tools
2. Dry-run mode to preview actions without executing
3. Pre-hooks for rate limiting, auth checks
4. Post-hooks for metrics, notifications
5. Audit log for compliance
6. Blocked commands for known dangerous patterns

Custom Tools

from nexus.tools.base import Tool, ToolResult, ToolContext, ToolCategory, ToolSafety

class MyTool(Tool):
    category = ToolCategory.FILE
    safety = ToolSafety.SAFE
    
    @property
    def name(self) -> str:
        return "my_tool"
    
    @property
    def description(self) -> str:
        return "My custom tool"
    
    @property
    def parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {"input": {"type": "string"}},
            "required": ["input"],
        }
    
    def execute(self, args, context):
        return ToolResult(
            success=True,
            output=f"Processed: {args['input']}",
        )

# Register
from nexus.tools import get_global_registry
get_global_registry().register(MyTool())

Tool Calling via Natural Language

Agent có thể detect tool calls từ natural language:

• "read file /etc/hostname" → file_read
• "run ls -la" → shell_exec
• "search for TODO in src/" → regex_search
• "fetch https://example.com" → web_fetch
• "git status" → git_ops

Hoặc JSON format:

{"tool": "file_read", "args": {"path": "/etc/hostname"}}

Or @-mention:

@file_read path=/etc/hostname