Crate tokitai 

Tokitai

AI Tool Integration System with Compile-time Tool Definitions

Tokitai is a zero-runtime-dependency procedural macro library that transforms your Rust methods into AI-callable tools with a single #[tool] attribute. All tool definitions are generated at compile time, ensuring type errors are caught before runtime.

🎯 Key Features

• Zero Runtime Intrusion - The macro itself has no runtime dependencies
• Compile-time Type Safety - Tool definitions generated at compile time, parameter type errors exposed during compilation
• Single Attribute - Just #[tool], no need for multiple tags
• Optional Runtime - Control dependencies via features, supports async-free environments
• Vendor Neutral - Works with any AI/LLM provider (Ollama, OpenAI, Anthropic, etc.)

🚀 Quick Start

1. Add Dependencies

[dependencies]
tokitai = "0.3.3"

That’s it! All required dependencies (serde, serde_json, thiserror) are included automatically.

2. Define Your Tools

use tokitai::tool;

pub struct Calculator;

#[tool]
impl Calculator {
    /// Add two numbers together
    pub fn add(&self, a: i32, b: i32) -> i32 {
        a + b
    }

    /// Calculate SHA256 hash of a string
    pub fn sha256(&self, input: String) -> String {
        // Your implementation...
        format!("hash of {}", input)
    }
}

3. Get Tool Definitions (Send to AI)

// Compile-time generated tool definitions
let tools = Calculator::tool_definitions();

// Convert to JSON and send to AI
let tools_json = serde_json::to_string_pretty(tools)?;
println!("{}", tools_json);

Output:

[
  {
    "name": "add",
    "description": "Add two numbers together",
    "input_schema": "{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"integer\"},\"b\":{\"type\":\"integer\"}},\"required\":[\"a\",\"b\"]}"
  },
  {
    "name": "sha256",
    "description": "Calculate SHA256 hash of a string",
    "input_schema": "{\"type\":\"object\",\"properties\":{\"input\":{\"type\":\"string\"}},\"required\":[\"input\"]}"
  }
]

4. Handle AI Calls

use tokitai::json;

let calc = Calculator;

// AI decides to call a tool
let call_request = json!({
    "name": "add",
    "arguments": {"a": 10, "b": 20}
});

// Execute the tool
let result = calc.call_tool(
    call_request["name"].as_str().unwrap(),
    &call_request["arguments"]
)?;

println!("Result: {}", result);  // 30

📦 Crate Structure

Tokitai is organized as a workspace with three crates:

Crate	Description
tokitai	Main crate with runtime support (this crate)
tokitai-core	Core types and traits (zero dependencies)
tokitai-macros	Procedural macros (compile-time code generation)

🔧 How It Works

+---------------+    Tool Definitions    +---------------+
|  Your Code    | ----------------------> |  AI Service   |
|  #[tool]      |                         |  (Ollama,     |
+---------------+                         |   OpenAI,     |
      ^                                   |   etc.)       |
      | Execution Result                  +---------------+
      |                                         |
      |                                         | Call Request
      |                                         v
+---------------+                         +---------------+
|  Rust Method  | <------ call_tool ------ |  JSON Call    |
|  (Local)      |                         | {"name":..}   |
+---------------+                         +---------------+

1. Define Rust methods → Implement your business logic
2. Send to AI → AI knows what tools are available
3. Receive call request → AI returns “I want to call a tool”
4. Execute and return → Run Rust code locally

🛠️ Features

Feature	Description
default	Enables full runtime support
runtime	Basic runtime support (async, error handling)
mcp	MCP protocol support (requires runtime)

Minimal Dependencies (Compile-time Only)

If you only need compile-time tool definitions without runtime support:

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

Note: Runtime features (call_tool, etc.) require serde/serde_json which are included by default.

📚 API Overview

Re-exported Core Types

• ToolDefinition - Tool definition with name, description, and input schema
• ToolError - Tool invocation error type
• ToolErrorKind - Error classification
• ParamType - JSON Schema type enumeration
• ToolProvider - Trait for tool providers (auto-implemented by #[tool])
• json! - Macro for creating JSON values (from serde_json)
• Value, Map - JSON value types (from serde_json)

Runtime Types

• AiToolError - Enhanced error type for runtime

Macro

• tool - Attribute macro for marking tool implementations

📋 Type Mapping

Rust types are automatically mapped to JSON Schema types:

Rust Type	JSON Schema Type
String, &str	string
i8, i16, i32, i64, u8, u16, u32, u64	integer
f32, f64	number
bool	boolean
Vec<T>	array
Custom structs	object

📖 Examples

See the examples directory for more:

• basic_usage.rs - Basic usage example
• ollama_integration.rs - Ollama AI integration with SHA256 tool
• multi_tool_chat.rs - Multi-tool协作 chatbot

⚙️ 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-core - Core types and traits
• tokitai-macros - Procedural macros

Re-exports

pub use error::AiToolError;

Modules

error

Runtime error types

Macros

config

tokitai! Configuration Macro

json

Construct a serde_json::Value from a JSON literal.

Structs

Map

Represents a JSON key/value type.

ToolConfigRegistry

Runtime registry for tool configurations.

ToolDefinition

Tool Definition

ToolError

Tool Error

Enums

ParamType

Parameter Type

ToolConfig

Configuration item for tool customization.

ToolErrorKind

Error Kind

Value

Represents any valid JSON value.

Constants

VERSION

Library version

Statics

GLOBAL_CONFIG_REGISTRY

Global registry instance for tool configurations.

Traits

ToolCaller

Tool Caller Trait

ToolProvider

Compile-time Tool Registry Trait

Attribute Macros

param_tool

Parameter-level tool attributes (helper macro for #[tool])

tool

#[tool] Attribute Macro

tool_default

Parameter default attribute (used internally by #[tool] macro)

tool_desc

Parameter description attribute (used internally by #[tool] macro)

tool_example

Parameter example attribute (used internally by #[tool] macro)

tool_max

Parameter max attribute (used internally by #[tool] macro)

tool_max_items

Parameter max_items attribute (used internally by #[tool] macro)

tool_max_length

Parameter max_length attribute (used internally by #[tool] macro)

tool_min

Parameter min attribute (used internally by #[tool] macro)

tool_min_items

Parameter min_items attribute (used internally by #[tool] macro)

tool_min_length

Parameter min_length attribute (used internally by #[tool] macro)

tool_multiple_of

Parameter multiple_of attribute (used internally by #[tool] macro)

tool_pattern

Parameter pattern attribute (used internally by #[tool] macro)

tool_required

Parameter required attribute (used internally by #[tool] macro)

tool_transform

Parameter transformation attribute (used internally by #[tool] macro)

tool_type

#[tool_type] Attribute Macro

tool_validate

Parameter validation attribute (used internally by #[tool] macro)