serdes_ai_tools/
lib.rs

1//! # serdes-ai-tools
2//!
3//! Tool system for serdes-ai agents.
4//!
5//! This crate provides the infrastructure for defining, registering, and
6//! executing tools that agents can use during conversations.
7//!
8//! ## Core Concepts
9//!
10//! - **[`Tool`]**: Trait for callable tools with typed parameters
11//! - **[`ToolRegistry`]**: Manage and lookup registered tools
12//! - **[`ToolDefinition`]**: JSON Schema-based tool descriptions for LLMs
13//! - **[`RunContext`]**: Execution context with dependencies passed to tools
14//! - **[`ToolReturn`]**: Return values from tool execution
15//!
16//! ## Defining Tools
17//!
18//! Tools can be defined by implementing the [`Tool`] trait:
19//!
20//! ```rust
21//! use async_trait::async_trait;
22//! use serdes_ai_tools::{
23//!     SchemaBuilder, Tool, ToolDefinition,
24//!     RunContext, ToolResult, ToolReturn,
25//! };
26//!
27//! struct WeatherTool;
28//!
29//! #[async_trait]
30//! impl Tool for WeatherTool {
31//!     fn definition(&self) -> ToolDefinition {
32//!         ToolDefinition::new("get_weather", "Get current weather for a location")
33//!             .with_parameters(
34//!                 SchemaBuilder::new()
35//!                     .string("location", "City name", true)
36//!                     .build()
37//!                     .unwrap()
38//!             )
39//!     }
40//!
41//!     async fn call(
42//!         &self,
43//!         _ctx: &RunContext,
44//!         args: serde_json::Value,
45//!     ) -> ToolResult {
46//!         let location = args["location"].as_str().unwrap_or("Unknown");
47//!         Ok(ToolReturn::text(format!("Weather in {}: 72°F, sunny", location)))
48//!     }
49//! }
50//! ```
51//!
52//! ## Using the Registry
53//!
54//! ```rust
55//! use serdes_ai_tools::{ToolRegistry, Tool, RunContext};
56//!
57//! # struct WeatherTool;
58//! # use async_trait::async_trait;
59//! # use serdes_ai_tools::{SchemaBuilder, ToolDefinition, ToolResult, ToolReturn};
60//! # #[async_trait] impl Tool for WeatherTool {
61//! #     fn definition(&self) -> ToolDefinition {
62//! #         ToolDefinition::new("weather", "Get weather")
63//! #             .with_parameters(SchemaBuilder::new().build().unwrap())
64//! #     }
65//! #     async fn call(&self, _: &RunContext, _: serde_json::Value) -> ToolResult { Ok(ToolReturn::empty()) }
66//! # }
67//!
68//! let mut registry = ToolRegistry::new();
69//! registry.register(WeatherTool);
70//!
71//! // Get all definitions for the model
72//! let definitions = registry.definitions();
73//!
74//! // Check if a tool exists
75//! assert!(registry.contains("weather"));
76//! ```
77//!
78//! ## Builtin Tools
79//!
80//! The crate provides builtin tools for common operations:
81//!
82//! - [`builtin::WebSearchTool`]: Search the web for information
83//! - [`builtin::CodeExecutionTool`]: Execute code in a sandbox
84//! - [`builtin::FileSearchTool`]: Vector-based file search
85//!
86//! ## Common Tools (Third-Party Integrations)
87//!
88//! With the `common-tools` feature, additional third-party tool integrations are available:
89//!
90//! ```toml
91//! serdes-ai-tools = { version = "0.1", features = ["common-tools"] }
92//! ```
93//!
94//! - `common::DuckDuckGoTool`: Web search using DuckDuckGo (no API key required)
95//! - `common::TavilyTool`: AI-optimized search using Tavily's API
96
97#![warn(missing_docs)]
98#![deny(unsafe_code)]
99
100pub mod builtin;
101#[cfg(feature = "common-tools")]
102pub mod common;
103pub mod context;
104pub mod deferred;
105pub mod definition;
106pub mod errors;
107pub mod registry;
108pub mod return_types;
109pub mod schema;
110pub mod tool;
111
112// Re-export core types
113pub use context::RunContext;
114pub use deferred::{
115    DeferredToolCall, DeferredToolDecision, DeferredToolDecisions, DeferredToolRequests,
116    DeferredToolResult, DeferredToolResults, ToolApproved, ToolApprover, ToolDenied,
117};
118pub use definition::{ObjectJsonSchema, ToolDefinition};
119pub use errors::{ToolError, ToolErrorInfo};
120pub use registry::{ToolProvider, ToolRegistry};
121pub use return_types::{IntoToolReturn, SerializableToolResult, ToolResult, ToolReturn};
122pub use schema::{PropertySchema, SchemaBuilder};
123pub use tool::{BoxedTool, FunctionTool, SyncFunctionTool, Tool};
124
125// Delete old files if they exist
126#[allow(unused_imports)]
127mod _cleanup {
128    // This module exists only to document what was removed
129    // Old files: error.rs, result.rs were replaced with errors.rs, return_types.rs
130}
serdes_ai_tools/lib.rs

serdes_ai_tools/
lib.rs
