Crate tokitai_core

Expand description

§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.4.0", default-features = false }

§Type Mapping

The ParamType enum maps Rust types to JSON Schema types:

Rust Type	JSON Schema Type	`ParamType` Variant
`String`, `&str`	`string`	`ParamType::String`
`i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`	`integer`	`ParamType::Integer`
`f32`, `f64`	`number`	`ParamType::Number`
`bool`	`boolean`	`ParamType::Boolean`
`Vec<T>`	`array`	`ParamType::Array`
Custom structs	`object`	`ParamType::Object`

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

Feature	Description
`serde` (default)	Enable serde serialization and JSON support

§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

Re-exports§

pub use config::ToolConfig;
pub use config::ToolConfigRegistry;
pub use config::GLOBAL_CONFIG_REGISTRY;
pub use serde_types::*;

Modules§

config: Tool configuration types for runtime customization. Tool configuration system for runtime tool definition customization.
serde_types: Serde type aliases

Macros§

assert_no_config_deadlock: Macro for compile-time deadlock detection.
json_schema: JSON Schema Macro (Compile-time)

Structs§

ToolDefinition: Tool Definition
ToolError: Tool Error
ToolParameter: Tool Parameter

Enums§

ParamType: Parameter Type
ToolErrorKind: Error Kind

Traits§

FromJsonValue: From Json Value Trait (P0 优化)
ToolCaller: Tool Caller Trait
ToolProvider: Compile-time Tool Registry Trait

Functions§

from_json_value_generic
from_json_value_str