tokitai-core 0.4.0

Tokitai core types - Compile-time tool definitions with zero runtime dependencies
Documentation

Tokitai Core

Crates.io Documentation License

🎯 核心类型定义

Tokitai Core 提供了 Tokitai AI 工具集成系统的基础类型和 trait。所有工具信息在编译期生成，确保零运行时开销和最大的类型安全。

✨ 核心特性

  • 零运行时依赖 - 核心类型依赖最小化
  • 类型安全 - 编译期工具定义防止运行时错误
  • Serde 集成 - 通过 serde 特性提供可选的序列化支持

📦 核心类型

类型 说明
[ToolDefinition] 工具定义，包含名称、描述和输入 schema
[ToolParameter] 工具的参数定义
[ParamType] JSON Schema 类型枚举
[ToolError] 工具调用错误类型
[ToolErrorKind] 错误分类枚举
[ToolProvider] 工具提供者 trait（由 #[tool] 宏自动实现）

🚀 快速开始

添加依赖

[dependencies]
tokitai-core = "0.3"

基本使用

use tokitai_core::ToolDefinition;

// 创建工具定义
let tool = ToolDefinition::new(
    "add",
    "两个数相加",
    r#"{"type":"object","properties":{"a":{"type":"integer"},"b":{"type":"integer"}},"required":["a","b"]}"#
);

assert_eq!(tool.name, "add");
assert_eq!(tool.description, "两个数相加");

// 启用 serde 特性时，可转换为 JSON
#[cfg(feature = "serde")]
{
    let json = tool.to_json().unwrap();
    println!("{}", json);
}

📋 类型映射

[ParamType] 枚举将 Rust 类型映射到 JSON Schema 类型：

Rust 类型 JSON Schema 类型 ParamType 变体
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
自定义 struct 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));

🔧 错误处理

[ToolError] 类型为工具调用提供结构化错误处理：

use tokitai_core::{ToolError, ToolErrorKind};

// 创建不同类型的错误
let validation_err = ToolError::validation_error("缺少必需参数 'city'");
assert_eq!(validation_err.kind, ToolErrorKind::ValidationError);

let not_found_err = ToolError::not_found("工具 'unknown_tool' 未找到");
assert_eq!(not_found_err.kind, ToolErrorKind::NotFound);

let internal_err = ToolError::internal_error("连接超时");
assert_eq!(internal_err.kind, ToolErrorKind::InternalError);

错误类型

变体 值 说明
ToolErrorKind::ValidationError 0 参数验证失败
ToolErrorKind::NotFound 1 工具未找到
ToolErrorKind::InternalError 2 内部错误
ToolErrorKind::TypeError 3 类型错误

🏗️ ToolProvider Trait

[ToolProvider] trait 由 #[tool] 宏自动实现：

use tokitai_core::ToolProvider;

// 在你的类型上使用 #[tool] 宏后：
// struct Calculator;
// #[tool] impl Calculator { ... }

// 获取所有工具定义
let tools = Calculator::tool_definitions();

// 获取工具数量
let count = Calculator::tool_count();

// 查找特定工具
let tool = Calculator::find_tool("add");

📐 JSON Schema 宏

json_schema! 宏帮助在编译期生成 JSON Schema 字符串：

use tokitai_core::json_schema;

const SCHEMA: &str = json_schema!({
    "city": {
        type: String,
        description: "城市名称",
        required: true,
    }
});

🎛️ Features

Feature 说明
serde (默认启用) 启用 serde 序列化和 JSON 支持

⚙️ 要求

  • Rust 版本: 1.80+
  • Edition: 2021

📄 许可证

Licensed under either of:

at your option.

🤝 贡献

除非你明确声明其他许可，否则你为本 crate 提交的所有贡献都将按上述两种方式之一授权，无需额外条款或条件。

📦 相关 Crate

Crate Crates.io 说明
tokitai crates.io 主 crate，包含运行时支持
tokitai-macros crates.io 过程宏实现

📚 文档

Happy Coding! 🦀