Crate tokitai

Expand description

§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.6"

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":..}   |
+---------------+                         +---------------+

Define Rust methods → Implement your business logic
Send to AI → AI knows what tools are available
Receive call request → AI returns “I want to call a tool”
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.6", 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 collaborative 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§

call: T-016: call!(self.method(args) => result) declarative macro.
config: tokitai! Configuration Macro
json: Construct a serde_json::Value from a JSON literal.

Structs§

DynamicToolRegistry: T-010: concrete dynamic registry.
Map: Represents a JSON key/value type.
ToolConfigRegistry: Runtime registry for tool configurations.
ToolDefinition: A tool that an AI system can invoke.
ToolError: Error returned by tool invocations.

Enums§

ParamType: JSON Schema type for a tool parameter.
ToolConfig: Configuration item for tool customization.
ToolErrorKind: Classification of a ToolError for structured error handling.
Value: Represents any valid JSON value.

Constants§

TENANT_DENIED_KIND_HINT: T-010: per-tenant error variant for the case where a tool exists globally but is gated off for the caller. Distinct from ToolErrorKind::NotFound so callers can distinguish “I never registered this tool” from “you can’t use this tool” when debugging per-tenant allow-list misconfigurations.
VERSION: Version string of this tokitai crate, sourced from the package’s Cargo.toml at compile time. Useful for diagnostics and for emitting version-aware MCP responses.

Statics§

GLOBAL_CONFIG_REGISTRY: Global registry instance for tool configurations.

Traits§

DynamicToolProvider: T-010: trait for runtime-mutable tool registries.
ToolCaller: Runtime tool invocation trait. Auto-implemented by the #[tool] macro.
ToolProvider: Compile-time tool registry trait.

Functions§

clear_current_version: T-013: clear any previously-registered current version. After this call the macro stops gating remove_in until set_current_version is called again. Useful in tests that need to exercise the “no gating” path mid-suite.
current_version: T-013: return the currently registered program version, or None when set_current_version was never called.
is_tenant_denied: Helper to extract the per-tenant not_found reason from a ToolError. Returns true when the error is the per-tenant gating flavour (i.e. the message starts with "tool \X` is not enabled for tenant `Y`“`).
set_current_version: T-013: install a process-wide current version. The #[tool] macro’s sync wrapper compares this value against each tool’s remove_in field; when remove_in <= current the call returns ToolError::Removed and the user is directed to replaced_by.

Type Aliases§

DynamicHandler: T-010: trait for runtime-mutable tool registries.

Attribute Macros§

circuit_breaker: #[circuit_breaker(failure_threshold = N, reset_timeout = "30s")] decorator. Wraps a function body in a 3-state (closed / open / half-open) circuit breaker. See docs/reference/circuit-breaker.md.
compose: #[compose] Attribute Macro
param_tool: Parameter-level tool attributes (helper macro for #[tool])
rate_limit: #[rate_limit(rps = N, burst = N)] decorator. Wraps a function body in a token-bucket rate limiter. See docs/reference/rate-limit.md.
retry: #[retry(max = N, backoff = "...", jitter = bool, on = "...")] decorator. Wraps a Result-returning function body in a retry loop with backoff between attempts. See tokitai_macros module docs and docs/reference/retry.md.
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)

Crate tokitai

Crate tokitai Copy item path

§Tokitai

§Key Features

§Quick Start

§1. Add Dependencies

§2. Define Your Tools

§3. Get Tool Definitions (Send to AI)

§4. Handle AI Calls

§Crate Structure

§How It Works

§Features

§Minimal Dependencies (Compile-time Only)

§API Overview

§Re-exported Core Types

§Runtime Types

§Macro

§Type Mapping

§Examples

§Requirements

§License

§Contributing

§See Also

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Statics§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Crate tokitai