machi 0.8.1

A Web3-native AI Agent Framework
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! Built-in tools for agents.
//!
//! This module provides a collection of commonly used tools that agents can use
//! out of the box. All tools implement the [`Tool`](crate::tool::Tool) trait
//! and can be added to an [`Agent`](crate::agent::Agent) via its builder API.
//!
//! # Tool Categories
//!
//! - **Filesystem**: [`ReadFileTool`], [`WriteFileTool`], [`EditFileTool`],
//!   [`ListDirTool`] — file I/O operations
//! - **Shell**: [`ExecTool`] — command-line execution with timeout support
//! - **Web**: [`WebSearchTool`] — web search with pluggable providers
//!   ([`TavilyProvider`], [`SearxngProvider`], [`BraveProvider`],
//!   [`DuckDuckGoProvider`], [`BingProvider`])
//!
//! # Examples
//!
//! ```rust
//! use machi::tools::{ReadFileTool, ExecTool, create_tool, fs_tools};
//!
//! // Create individual tools
//! let read = ReadFileTool::new();
//! let exec = ExecTool::new();
//!
//! // Create a tool by name
//! let tool = create_tool("read_file");
//! assert!(tool.is_some());
//!
//! // Get all filesystem tools at once
//! let tools = fs_tools();
//! assert_eq!(tools.len(), 4);
//! ```

mod fs;
mod shell;
mod web_search;

pub use fs::{
    EditFileArgs, EditFileTool, ListDirArgs, ListDirTool, ReadFileArgs, ReadFileTool,
    WriteFileArgs, WriteFileTool,
};
pub use shell::{ExecArgs, ExecResult, ExecTool};
pub use web_search::{
    BingProvider, BoxedSearchProvider, BraveProvider, DuckDuckGoProvider, SearchProvider,
    SearchResult, SearxngProvider, TavilyProvider, WebSearchArgs, WebSearchTool,
};

use crate::tool::BoxedTool;

/// Names of all built-in tools provided by this module.
pub const BUILTIN_TOOL_NAMES: &[&str] = &[
    "read_file",
    "write_file",
    "edit_file",
    "list_dir",
    "exec",
    "web_search",
];

/// Create a built-in tool by name.
///
/// Returns `None` if the name is not recognized.
///
/// # Supported names
///
/// | Name | Tool |
/// |------|------|
/// | `"read_file"` | [`ReadFileTool`] |
/// | `"write_file"` | [`WriteFileTool`] |
/// | `"edit_file"` | [`EditFileTool`] |
/// | `"list_dir"` | [`ListDirTool`] |
/// | `"exec"` | [`ExecTool`] |
///
/// **Note:** `"web_search"` is *not* included here because it requires a
/// [`SearchProvider`] configuration.  Use [`WebSearchTool::tavily`],
/// [`WebSearchTool::searxng`], or [`WebSearchTool::brave`] directly.
#[must_use]
pub fn create_tool(name: &str) -> Option<BoxedTool> {
    match name {
        "read_file" => Some(Box::new(ReadFileTool::new())),
        "write_file" => Some(Box::new(WriteFileTool::new())),
        "edit_file" => Some(Box::new(EditFileTool::new())),
        "list_dir" => Some(Box::new(ListDirTool::new())),
        "exec" => Some(Box::new(ExecTool::new())),
        _ => None,
    }
}

/// Create multiple built-in tools by name.
///
/// Unrecognized names are silently skipped.
#[must_use]
pub fn create_tools(names: &[&str]) -> Vec<BoxedTool> {
    names.iter().filter_map(|name| create_tool(name)).collect()
}

/// Check if a tool name corresponds to a known built-in tool.
#[must_use]
pub fn is_builtin_tool(name: &str) -> bool {
    BUILTIN_TOOL_NAMES.contains(&name)
}

/// Get the default filesystem tools.
///
/// Returns: [`ReadFileTool`], [`WriteFileTool`], [`EditFileTool`],
/// [`ListDirTool`].
#[must_use]
pub fn fs_tools() -> Vec<BoxedTool> {
    vec![
        Box::new(ReadFileTool::new()),
        Box::new(WriteFileTool::new()),
        Box::new(EditFileTool::new()),
        Box::new(ListDirTool::new()),
    ]
}

/// Get all built-in tools.
///
/// Returns every tool listed in [`BUILTIN_TOOL_NAMES`].
#[must_use]
pub fn all_tools() -> Vec<BoxedTool> {
    vec![
        Box::new(ReadFileTool::new()),
        Box::new(WriteFileTool::new()),
        Box::new(EditFileTool::new()),
        Box::new(ListDirTool::new()),
        Box::new(ExecTool::new()),
    ]
}