thulp-core 0.3.0

Core types and traits for thulp
Documentation

thulp-core

Core types, traits, and error definitions for the Thulp execution context platform.

Overview

This crate provides the foundational abstractions for defining, validating, and executing tools in AI agent environments. It includes type-safe parameter definitions, tool metadata, and extensible traits for implementing custom tool providers and transports.

Features

  • Type-Safe Parameters: Compile-time and runtime validation of tool parameters
  • Builder Pattern: Ergonomic API for constructing tool definitions
  • JSON Serialization: Full serde support for all types
  • MCP Integration: Parse MCP JSON Schema to Thulp parameter definitions
  • Async Support: Built on tokio for efficient async execution

Installation

Add to your Cargo.toml:

[dependencies]
thulp-core = "0.2"

Core Types

  • ToolDefinition: Describes an available tool with its parameters and metadata
  • ToolCall: Represents a request to execute a specific tool with arguments
  • ToolResult: The result of a tool execution (success or failure)
  • Parameter: Defines a tool parameter with type information and validation rules
  • ParameterType: Strongly-typed parameter types (String, Integer, Number, Boolean, Array, Object)

MCP Types

  • Resource: MCP resource definition with URI, name, and metadata
  • ResourceContents: Content of a read resource (text or blob)
  • Prompt: MCP prompt definition with arguments
  • PromptMessage: Message in a rendered prompt

Traits

  • Tool: Trait for implementing executable tools
  • Transport: Trait for implementing tool transport layers (MCP, HTTP, gRPC)

Usage

Defining a Tool

use thulp_core::{ToolDefinition, Parameter, ParameterType};

let tool = ToolDefinition::builder("read_file")
    .description("Read contents of a file")
    .parameter(
        Parameter::builder("path")
            .param_type(ParameterType::String)
            .required(true)
            .description("Path to the file to read")
            .build()
    )
    .parameter(
        Parameter::builder("encoding")
            .param_type(ParameterType::String)
            .default(serde_json::Value::String("utf-8".to_string()))
            .description("File encoding")
            .build()
    )
    .build();

assert_eq!(tool.name, "read_file");
assert_eq!(tool.parameters.len(), 2);

Validating Tool Arguments

use thulp_core::{ToolDefinition, Parameter, ParameterType};
use serde_json::json;

let tool = ToolDefinition::builder("add")
    .description("Add two numbers")
    .parameter(
        Parameter::builder("a")
            .param_type(ParameterType::Number)
            .required(true)
            .build()
    )
    .parameter(
        Parameter::builder("b")
            .param_type(ParameterType::Number)
            .required(true)
            .build()
    )
    .build();

// Valid arguments
let args = json!({"a": 5.0, "b": 3.0});
assert!(tool.validate_args(&args).is_ok());

// Invalid - missing required parameter
let args = json!({"a": 5.0});
assert!(tool.validate_args(&args).is_err());

Creating Tool Calls

use thulp_core::ToolCall;
use serde_json::json;

let call = ToolCall::builder("search")
    .arg("query", json!("rust programming"))
    .arg("max_results", json!(10))
    .build();

assert_eq!(call.tool, "search");

Parsing MCP JSON Schema

use thulp_core::ToolDefinition;
use serde_json::json;

let schema = json!({
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "User name"
        },
        "age": {
            "type": "integer",
            "description": "User age"
        }
    },
    "required": ["name"]
});

let params = ToolDefinition::parse_mcp_input_schema(&schema).unwrap();
assert_eq!(params.len(), 2);

Working with MCP Resources

use thulp_core::{Resource, ResourceContents};

let resource = Resource::builder("file:///docs/readme.md", "readme.md")
    .title("Project README")
    .mime_type("text/markdown")
    .description("Main project documentation")
    .build();

let contents = ResourceContents::text("file:///docs/readme.md", "# Project\n...");

Error Handling

All fallible operations return Result<T, Error>, where Error provides detailed error information:

use thulp_core::{ToolDefinition, Error, Parameter, ParameterType};
use serde_json::json;

let tool = ToolDefinition::builder("test")
    .parameter(
        Parameter::builder("required_param")
            .param_type(ParameterType::String)
            .required(true)
            .build()
    )
    .build();

match tool.validate_args(&json!({})) {
    Ok(_) => println!("Valid!"),
    Err(Error::MissingParameter(name)) => {
        eprintln!("Missing required parameter: {}", name);
    }
    Err(e) => eprintln!("Other error: {}", e),
}

Testing

cargo test -p thulp-core

Benchmarking

cargo bench -p thulp-core --bench tool_benchmarks

License

Licensed under either of:

at your option.