thulp_core/
lib.rs

1//! # thulp-core
2//!
3//! Core types, traits, and error definitions for the thulp execution context platform.
4//!
5//! This crate provides the foundational abstractions for defining, validating, and executing
6//! tools in AI agent environments. It includes type-safe parameter definitions, tool metadata,
7//! and extensible traits for implementing custom tool providers and transports.
8//!
9//! ## Core Types
10//!
11//! - [`ToolDefinition`]: Describes an available tool with its parameters and metadata
12//! - [`ToolCall`]: Represents a request to execute a specific tool with arguments
13//! - [`ToolResult`]: The result of a tool execution (success or failure)
14//! - [`Parameter`]: Defines a tool parameter with type information and validation rules
15//! - [`ParameterType`]: Strongly-typed parameter types (String, Integer, Number, Boolean, Array, Object)
16//!
17//! ## Traits
18//!
19//! - [`Tool`]: Trait for implementing executable tools
20//! - [`Transport`]: Trait for implementing tool transport layers (e.g., MCP, HTTP, gRPC)
21//!
22//! ## Features
23//!
24//! - **Type Safety**: Compile-time and runtime validation of tool parameters
25//! - **Builder Pattern**: Ergonomic API for constructing tool definitions
26//! - **JSON Serialization**: Full serde support for all types
27//! - **MCP Integration**: Parse MCP JSON Schema to Thulp parameter definitions
28//! - **Async Support**: Built on tokio for efficient async execution
29//!
30//! ## Quick Start
31//!
32//! ### Defining a Tool
33//!
34//! ```rust
35//! use thulp_core::{ToolDefinition, Parameter, ParameterType};
36//!
37//! let tool = ToolDefinition::builder("read_file")
38//!     .description("Read contents of a file")
39//!     .parameter(
40//!         Parameter::builder("path")
41//!             .param_type(ParameterType::String)
42//!             .required(true)
43//!             .description("Path to the file to read")
44//!             .build()
45//!     )
46//!     .parameter(
47//!         Parameter::builder("encoding")
48//!             .param_type(ParameterType::String)
49//!             .default(serde_json::Value::String("utf-8".to_string()))
50//!             .description("File encoding")
51//!             .build()
52//!     )
53//!     .build();
54//!
55//! assert_eq!(tool.name, "read_file");
56//! assert_eq!(tool.parameters.len(), 2);
57//! ```
58//!
59//! ### Validating Tool Arguments
60//!
61//! ```rust
62//! use thulp_core::{ToolDefinition, Parameter, ParameterType};
63//! use serde_json::json;
64//!
65//! let tool = ToolDefinition::builder("add")
66//!     .description("Add two numbers")
67//!     .parameter(
68//!         Parameter::builder("a")
69//!             .param_type(ParameterType::Number)
70//!             .required(true)
71//!             .build()
72//!     )
73//!     .parameter(
74//!         Parameter::builder("b")
75//!             .param_type(ParameterType::Number)
76//!             .required(true)
77//!             .build()
78//!     )
79//!     .build();
80//!
81//! // Valid arguments
82//! let args = json!({"a": 5.0, "b": 3.0});
83//! assert!(tool.validate_args(&args).is_ok());
84//!
85//! // Invalid - missing required parameter
86//! let args = json!({"a": 5.0});
87//! assert!(tool.validate_args(&args).is_err());
88//!
89//! // Invalid - wrong type
90//! let args = json!({"a": "not a number", "b": 3.0});
91//! assert!(tool.validate_args(&args).is_err());
92//! ```
93//!
94//! ### Creating Tool Calls
95//!
96//! ```rust
97//! use thulp_core::ToolCall;
98//! use serde_json::json;
99//!
100//! let call = ToolCall::builder("search")
101//!     .arg("query", json!("rust programming"))
102//!     .arg("max_results", json!(10))
103//!     .build();
104//!
105//! assert_eq!(call.tool, "search");
106//! ```
107//!
108//! ### Parsing MCP JSON Schema
109//!
110//! ```rust
111//! use thulp_core::ToolDefinition;
112//! use serde_json::json;
113//!
114//! let schema = json!({
115//!     "type": "object",
116//!     "properties": {
117//!         "name": {
118//!             "type": "string",
119//!             "description": "User name"
120//!         },
121//!         "age": {
122//!             "type": "integer",
123//!             "description": "User age"
124//!         }
125//!     },
126//!     "required": ["name"]
127//! });
128//!
129//! let params = ToolDefinition::parse_mcp_input_schema(&schema).unwrap();
130//! assert_eq!(params.len(), 2);
131//! assert!(params.iter().find(|p| p.name == "name").unwrap().required);
132//! assert!(!params.iter().find(|p| p.name == "age").unwrap().required);
133//! ```
134//!
135//! ## Error Handling
136//!
137//! All fallible operations return [`Result<T, Error>`](Result), where [`Error`] provides
138//! detailed error information:
139//!
140//! ```rust
141//! use thulp_core::{ToolDefinition, Error};
142//! use serde_json::json;
143//!
144//! let tool = ToolDefinition::builder("test")
145//!     .parameter(
146//!         thulp_core::Parameter::builder("required_param")
147//!             .param_type(thulp_core::ParameterType::String)
148//!             .required(true)
149//!             .build()
150//!     )
151//!     .build();
152//!
153//! match tool.validate_args(&json!({})) {
154//!     Ok(_) => println!("Valid!"),
155//!     Err(Error::MissingParameter(name)) => {
156//!         eprintln!("Missing required parameter: {}", name);
157//!     }
158//!     Err(e) => eprintln!("Other error: {}", e),
159//! }
160//! ```
161
162mod error;
163mod parameter;
164mod tool;
165mod traits;
166
167pub use error::{Error, Result};
168pub use parameter::{Parameter, ParameterBuilder, ParameterType};
169pub use tool::{ToolCall, ToolCallBuilder, ToolDefinition, ToolDefinitionBuilder, ToolResult};
170pub use traits::{Tool, Transport};
thulp_core/lib.rs

thulp_core/
lib.rs
