Tokitai Core

Core types for Tokitai - Compile-time tool definitions with zero runtime dependencies

This crate provides the fundamental types and traits for the Tokitai AI tool integration system. All tool information is generated at compile time, ensuring zero runtime overhead and maximum type safety.

🎯 Key Features

• Zero Runtime Dependencies - Core types have minimal dependencies
• no_std Support - Works in embedded environments (when serde feature is disabled)
• Type Safety - Compile-time tool definitions prevent runtime errors
• Serde Integration - Optional serialization support via the serde feature

Core Types

• [ToolDefinition] - Tool definition containing name, description, and input schema
• [ToolParameter] - Parameter definition for tools
• [ParamType] - JSON Schema type enumeration
• [ToolError] - Error type for tool invocation failures
• [ToolErrorKind] - Classification of tool errors
• [ToolProvider] - Trait for tool providers (auto-implemented by #[tool] macro)

Usage Example

use tokitai_core::ToolDefinition;

// Create a tool definition
let tool = ToolDefinition::new(
    "add",
    "Add two numbers together",
    r#"{"type":"object","properties":{"a":{"type":"integer"},"b":{"type":"integer"}},"required":["a","b"]}"#
);

assert_eq!(tool.name, "add");
assert_eq!(tool.description, "Add two numbers together");

// With serde feature enabled, convert to JSON
#[cfg(feature = "serde")]
{
    let json = tool.to_json().unwrap();
    assert!(json.contains("\"name\":\"add\""));
}

No-Std Support

This crate supports no_std environments when the serde feature is disabled:

[dependencies]
tokitai-core = { version = "0.3", default-features = false }

Type Mapping

The [ParamType] enum maps Rust types to JSON Schema types:

use tokitai_core::ParamType;

assert_eq!(ParamType::from_rust_type("String"), Some(ParamType::String));
assert_eq!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
assert_eq!(ParamType::from_rust_type("f64"), Some(ParamType::Number));
assert_eq!(ParamType::from_rust_type("bool"), Some(ParamType::Boolean));
assert_eq!(ParamType::from_rust_type("Vec<i32>"), Some(ParamType::Array));

Error Handling

The [ToolError] type provides structured error handling for tool invocations:

use tokitai_core::{ToolError, ToolErrorKind};

// Create different error types
let validation_err = ToolError::validation_error("Missing required parameter 'city'");
assert_eq!(validation_err.kind, ToolErrorKind::ValidationError);

let not_found_err = ToolError::not_found("Tool 'unknown_tool' not found");
assert_eq!(not_found_err.kind, ToolErrorKind::NotFound);

let internal_err = ToolError::internal_error("Connection timeout");
assert_eq!(internal_err.kind, ToolErrorKind::InternalError);

Tool Provider Trait

The [ToolProvider] trait is automatically implemented by the #[tool] macro:

use tokitai_core::ToolProvider;

// After using #[tool] macro on your type:
// struct Calculator;
// #[tool] impl Calculator { ... }

// Get all tool definitions
// let tools = Calculator::tool_definitions();

// Get tool count
// let count = Calculator::tool_count();

// Find a specific tool
// let tool = Calculator::find_tool("add");

JSON Schema Macro

The json_schema! macro helps generate JSON Schema strings at compile time:

use tokitai_core::json_schema;

const SCHEMA: &str = json_schema!({
    "city": {
        type: String,
        description: "Name of the city",
        required: true,
    }
});

Features

Requirements

• Rust Version: 1.70+
• Edition: 2021

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Contributing

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

See Also

• tokitai - Main crate with runtime support
• tokitai-macros - Procedural macros