tokitai-core 0.5.0

//! # Tokitai Core
//!
//! Core types and traits for the Tokitai AI tool integration library. All
//! tool information is generated at compile time, so the core has zero
//! runtime dependencies and is `no_std`-compatible (with the `serde`
//! feature disabled).
//!
//! See [`ToolDefinition`], [`ToolProvider`], and the [`tokitai`](https://crates.io/crates/tokitai)
//! crate for the high-level overview.
//!
//! # Example
//!
//! ```rust
//! use tokitai_core::{ToolDefinition, ParamType};
//!
//! 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!(ParamType::from_rust_type("i32"), Some(ParamType::Integer));
//! assert_eq!(ParamType::from_rust_type("Vec<i32>"), Some(ParamType::Array));
//! ```
//!
//! # Features
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `serde` (default) | Enable `serde`/`serde_json` integration |
//!
//! For `no_std` usage, depend on the crate with `default-features = false`.
//!
//! # License
//!
//! Dual-licensed under either of:
//!
//! - Apache License, Version 2.0
//! - MIT License
//!
//! at your option.

#![cfg_attr(not(feature = "serde"), no_std)]
#![deny(missing_docs)]
#![allow(dead_code)]

#[cfg(feature = "serde")]
extern crate serde;

#[cfg(feature = "serde")]
extern crate alloc;

#[cfg(feature = "serde")]
pub use serde_types::*;

#[cfg(feature = "serde")]
pub use config::{ToolConfig, ToolConfigRegistry, GLOBAL_CONFIG_REGISTRY};

/// A tool that an AI system can invoke.
///
/// Normally generated by the `#[tool]` macro; rarely created by hand.
///
/// # Example
///
/// ```rust
/// use tokitai_core::ToolDefinition;
///
/// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
/// assert_eq!(tool.name, "add");
/// ```
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ToolDefinition {
    /// Tool name used for identification during AI calls
    #[cfg(feature = "serde")]
    pub name: alloc::string::String,
    #[cfg(not(feature = "serde"))]
    pub name: &'static str,
    /// Tool description helping AI understand its purpose
    #[cfg(feature = "serde")]
    pub description: alloc::string::String,
    #[cfg(not(feature = "serde"))]
    pub description: &'static str,
    /// Input parameter JSON Schema (compile-time generated string)
    #[cfg(feature = "serde")]
    pub input_schema: alloc::string::String,
    #[cfg(not(feature = "serde"))]
    pub input_schema: &'static str,
    /// Tool version (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub version: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub version: Option<&'static str>,
    /// Version since when the tool is deprecated (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub deprecated_since: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub deprecated_since: Option<&'static str>,
    /// Version when the tool will be removed (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub remove_in: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub remove_in: Option<&'static str>,
    /// Tool that replaces this deprecated tool (optional)
    #[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
    #[cfg(feature = "serde")]
    pub replaced_by: Option<alloc::string::String>,
    #[cfg(not(feature = "serde"))]
    pub replaced_by: Option<&'static str>,
}

/// Compile-time storage for tool definition data, used by the
/// `#[tool]` macro and converted to a `ToolDefinition` at zero cost
/// via [`ToolDefinition::from_const`].
#[doc(hidden)]
pub struct ToolDefinitionConst {
    pub name: &'static str,
    pub description: &'static str,
    pub input_schema: &'static str,
}

impl ToolDefinition {
    /// Build a tool definition from compile-time constants. Optimized for the
    /// `#[tool]` macro: no allocation, just `'static` -> owned-string copies.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolDefinition, ToolDefinitionConst};
    ///
    /// const TOOL_DATA: ToolDefinitionConst = ToolDefinitionConst {
    ///     name: "get_weather",
    ///     description: "Get weather information for a specified city",
    ///     input_schema: r#"{"type":"object"}"#,
    /// };
    ///
    /// let tool = ToolDefinition::from_const(TOOL_DATA);
    /// ```
    #[inline(always)]
    pub fn from_const(data: ToolDefinitionConst) -> Self {
        Self {
            #[cfg(feature = "serde")]
            name: data.name.into(),
            #[cfg(not(feature = "serde"))]
            name: data.name,
            #[cfg(feature = "serde")]
            description: data.description.into(),
            #[cfg(not(feature = "serde"))]
            description: data.description,
            #[cfg(feature = "serde")]
            input_schema: data.input_schema.into(),
            #[cfg(not(feature = "serde"))]
            input_schema: data.input_schema,
            version: None,
            deprecated_since: None,
            remove_in: None,
            replaced_by: None,
        }
    }

    /// Create a new tool definition at runtime. Each argument can be any
    /// type that implements `Into<String>`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new(
    ///     "get_weather",
    ///     "Get weather information for a specified city",
    ///     r#"{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}"#
    /// );
    /// ```
    #[cfg(feature = "serde")]
    pub fn new(
        name: impl Into<alloc::string::String>,
        description: impl Into<alloc::string::String>,
        input_schema: impl Into<alloc::string::String>,
    ) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            input_schema: input_schema.into(),
            version: None,
            deprecated_since: None,
            remove_in: None,
            replaced_by: None,
        }
    }

    /// `no_std` constructor: all three strings must be `'static`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// assert_eq!(tool.name, "add");
    /// ```
    #[cfg(not(feature = "serde"))]
    pub fn new(name: &'static str, description: &'static str, input_schema: &'static str) -> Self {
        Self {
            name,
            description,
            input_schema,
            version: None,
            deprecated_since: None,
            remove_in: None,
            replaced_by: None,
        }
    }

    /// Set the tool version.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#)
    ///     .with_version("1.2.0");
    /// assert_eq!(tool.version.as_deref(), Some("1.2.0"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn with_version(mut self, version: impl Into<alloc::string::String>) -> Self {
        self.version = Some(version.into());
        self
    }

    /// `no_std` version setter: `version` must be `'static`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#)
    ///     .with_version("1.2.0");
    /// assert_eq!(tool.version, Some("1.2.0"));
    /// ```
    #[cfg(not(feature = "serde"))]
    pub fn with_version(mut self, version: &'static str) -> Self {
        self.version = Some(version);
        self
    }

    /// Mark the tool as deprecated.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("multiply", "Multiply two numbers", r#"{"type":"object"}"#)
    ///     .with_deprecated("0.5.0", "0.7.0", "add_repeated");
    /// assert_eq!(tool.deprecated_since.as_deref(), Some("0.5.0"));
    /// assert_eq!(tool.remove_in.as_deref(), Some("0.7.0"));
    /// assert_eq!(tool.replaced_by.as_deref(), Some("add_repeated"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn with_deprecated(
        mut self,
        deprecated_since: impl Into<alloc::string::String>,
        remove_in: impl Into<alloc::string::String>,
        replaced_by: impl Into<alloc::string::String>,
    ) -> Self {
        self.deprecated_since = Some(deprecated_since.into());
        self.remove_in = Some(remove_in.into());
        self.replaced_by = Some(replaced_by.into());
        self
    }

    /// `no_std` deprecation setter: all three strings must be `'static`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("multiply", "Multiply two numbers", r#"{"type":"object"}"#)
    ///     .with_deprecated("0.5.0", "0.7.0", "add_repeated");
    /// assert_eq!(tool.deprecated_since, Some("0.5.0"));
    /// assert_eq!(tool.remove_in, Some("0.7.0"));
    /// assert_eq!(tool.replaced_by, Some("add_repeated"));
    /// ```
    #[cfg(not(feature = "serde"))]
    pub fn with_deprecated(
        mut self,
        deprecated_since: &'static str,
        remove_in: &'static str,
        replaced_by: &'static str,
    ) -> Self {
        self.deprecated_since = Some(deprecated_since);
        self.remove_in = Some(remove_in);
        self.replaced_by = Some(replaced_by);
        self
    }

    /// Serialize this tool definition to a JSON string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// let json = tool.to_json().unwrap();
    /// assert!(json.contains(r#""name":"add""#));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if serialization fails.
    #[cfg(feature = "serde")]
    pub fn to_json(&self) -> Result<String, serde_json::Error> {
        serde_json::to_string(self)
    }

    /// Serialize this tool definition to a `serde_json::Value`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// let value = tool.to_value().unwrap();
    /// assert_eq!(value["name"], json!("add"));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if serialization fails.
    #[cfg(feature = "serde")]
    pub fn to_value(&self) -> Result<serde_json::Value, serde_json::Error> {
        serde_json::to_value(self)
    }

    /// Return the input schema pretty-printed as a JSON string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let pretty = tool.input_schema_pretty().unwrap();
    /// assert!(pretty.contains('\n'));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if `input_schema` is not valid JSON or
    /// if pretty-printing fails.
    #[cfg(feature = "serde")]
    pub fn input_schema_pretty(&self) -> Result<String, serde_json::Error> {
        let value: serde_json::Value = serde_json::from_str(&self.input_schema)?;
        serde_json::to_string_pretty(&value)
    }

    /// Parse the input schema into a `serde_json::Value`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new("add", "Add two numbers", r#"{"type":"object"}"#);
    /// let schema = tool.input_schema_value().unwrap();
    /// assert_eq!(schema, json!({"type": "object"}));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a `serde_json::Error` if `input_schema` is not valid JSON.
    #[cfg(feature = "serde")]
    pub fn input_schema_value(&self) -> Result<serde_json::Value, serde_json::Error> {
        serde_json::from_str(&self.input_schema)
    }

    /// Apply a list of runtime configuration items to this tool definition.
    ///
    /// Used by the configuration system to override compile-time defaults.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolDefinition, ToolConfig};
    ///
    /// let mut tool = ToolDefinition::new("test", "Original description", "{}");
    /// tool.apply_configs(&[
    ///     ToolConfig::Desc("Overridden description".to_string()),
    /// ]);
    /// assert_eq!(tool.description, "Overridden description");
    /// ```
    #[cfg(feature = "serde")]
    pub fn apply_configs(&mut self, configs: &[ToolConfig]) {
        for config in configs {
            match config {
                ToolConfig::Desc(desc) => {
                    self.description = desc.clone();
                }
                ToolConfig::Tags(tags) => {
                    // Add tags to the schema
                    if let Ok(mut schema) =
                        serde_json::from_str::<serde_json::Value>(&self.input_schema)
                    {
                        if let Some(obj) = schema.as_object_mut() {
                            obj.insert("tags".to_string(), serde_json::json!(tags));
                        }
                        self.input_schema = schema.to_string();
                    }
                }
                ToolConfig::ParamDesc { name, desc } => {
                    self.apply_param_desc(name, desc);
                }
                ToolConfig::ParamExample { name, example } => {
                    self.apply_param_example(name, example);
                }
                ToolConfig::ParamDefault { name, default } => {
                    self.apply_param_default(name, default);
                }
                ToolConfig::ParamRequired { name, required } => {
                    self.apply_param_required(name, *required);
                }
                ToolConfig::ParamMin { name, min } => {
                    self.apply_param_constraint(name, "minimum", serde_json::json!(min));
                }
                ToolConfig::ParamMax { name, max } => {
                    self.apply_param_constraint(name, "maximum", serde_json::json!(max));
                }
                ToolConfig::ParamMinLength { name, min_length } => {
                    self.apply_param_constraint(name, "minLength", serde_json::json!(min_length));
                }
                ToolConfig::ParamMaxLength { name, max_length } => {
                    self.apply_param_constraint(name, "maxLength", serde_json::json!(max_length));
                }
                ToolConfig::ParamPattern { name, pattern } => {
                    self.apply_param_constraint(name, "pattern", serde_json::json!(pattern));
                }
                ToolConfig::ParamMinItems { name, min_items } => {
                    self.apply_param_constraint(name, "minItems", serde_json::json!(min_items));
                }
                ToolConfig::ParamMaxItems { name, max_items } => {
                    self.apply_param_constraint(name, "maxItems", serde_json::json!(max_items));
                }
                ToolConfig::ParamMultipleOf { name, multiple_of } => {
                    self.apply_param_constraint(name, "multipleOf", serde_json::json!(multiple_of));
                }
            }
        }
    }

    /// Set the `description` field of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_desc(&mut self, name: &str, desc: &str) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert("description".to_string(), serde_json::json!(desc));
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Set the `example` field of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_example(&mut self, name: &str, example: &serde_json::Value) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert("example".to_string(), example.clone());
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Set the `default` field of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_default(&mut self, name: &str, default: &serde_json::Value) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert("default".to_string(), default.clone());
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Toggle the `required` flag of the named parameter in the JSON schema.
    #[cfg(feature = "serde")]
    fn apply_param_required(&mut self, name: &str, required: bool) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                // Update required array
                let required_arr = obj
                    .entry("required".to_string())
                    .or_insert_with(|| serde_json::json!([]))
                    .as_array_mut();

                if let Some(req_arr) = required_arr {
                    let name_json = serde_json::json!(name);
                    if required && !req_arr.contains(&name_json) {
                        req_arr.push(name_json);
                    } else if !required {
                        req_arr.retain(|v| v != &name_json);
                    }
                }

                // Also update parameter schema
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        // Note: individual param "required" is not standard JSON Schema
                        // but we can add it for documentation purposes
                        param.insert("required".to_string(), serde_json::json!(required));
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Insert a JSON-Schema constraint (e.g. `minimum`, `pattern`) for a
    /// parameter by name.
    #[cfg(feature = "serde")]
    fn apply_param_constraint(
        &mut self,
        name: &str,
        constraint_key: &str,
        value: serde_json::Value,
    ) {
        if let Ok(mut schema) = serde_json::from_str::<serde_json::Value>(&self.input_schema) {
            if let Some(obj) = schema.as_object_mut() {
                if let Some(props) = obj.get_mut("properties").and_then(|v| v.as_object_mut()) {
                    if let Some(param) = props.get_mut(name).and_then(|v| v.as_object_mut()) {
                        param.insert(constraint_key.to_string(), value);
                    }
                }
            }
            self.input_schema = schema.to_string();
        }
    }

    /// Convert this tool definition into the OpenAI function-calling format.
    ///
    /// Spec: <https://platform.openai.com/docs/guides/function-calling>
    ///
    /// Returns a JSON object of the form:
    /// ```json
    /// {
    ///   "type": "function",
    ///   "function": {
    ///     "name": "<tool name>",
    ///     "description": "<tool description>",
    ///     "parameters": { /* full JSON Schema */ }
    ///   }
    /// }
    /// ```
    ///
    /// If the stored `input_schema` is not valid JSON, the `parameters`
    /// field will be emitted as an empty object (`{}`) so the surrounding
    /// envelope remains a valid OpenAI tool descriptor.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let openai = tool.to_openai_function();
    /// assert_eq!(openai["type"], json!("function"));
    /// assert_eq!(openai["function"]["name"], json!("add"));
    /// ```
    #[cfg(feature = "serde")]
    pub fn to_openai_function(&self) -> serde_json::Value {
        let parameters = self.parse_input_schema_or_empty();
        serde_json::json!({
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": parameters,
            }
        })
    }

    /// Convert this tool definition into the Anthropic tool-use format.
    ///
    /// Spec: <https://docs.anthropic.com/en/docs/build-with-claude/tool-use>
    ///
    /// Returns a JSON object of the form:
    /// ```json
    /// {
    ///   "name": "<tool name>",
    ///   "description": "<tool description>",
    ///   "input_schema": { /* full JSON Schema */ }
    /// }
    /// ```
    ///
    /// If the stored `input_schema` is not valid JSON, the `input_schema`
    /// field will be emitted as an empty object (`{}`) so the surrounding
    /// envelope remains a valid Anthropic tool descriptor.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let anthropic = tool.to_anthropic_tool();
    /// assert_eq!(anthropic["name"], json!("add"));
    /// assert!(anthropic["input_schema"].is_object());
    /// ```
    #[cfg(feature = "serde")]
    pub fn to_anthropic_tool(&self) -> serde_json::Value {
        let input_schema = self.parse_input_schema_or_empty();
        serde_json::json!({
            "name": self.name,
            "description": self.description,
            "input_schema": input_schema,
        })
    }

    /// Convert this tool definition into the Model Context Protocol (MCP)
    /// tool definition format.
    ///
    /// Spec: <https://modelcontextprotocol.io/>
    ///
    /// Returns a JSON object of the form:
    /// ```json
    /// {
    ///   "name": "<tool name>",
    ///   "description": "<tool description>",
    ///   "inputSchema": { /* full JSON Schema */ }
    /// }
    /// ```
    ///
    /// If the stored `input_schema` is not valid JSON, the `inputSchema`
    /// field will be emitted as an empty object (`{}`) so the surrounding
    /// envelope remains a valid MCP tool descriptor.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ToolDefinition;
    /// use serde_json::json;
    ///
    /// let tool = ToolDefinition::new(
    ///     "add",
    ///     "Add two numbers",
    ///     r#"{"type":"object","properties":{"a":{"type":"integer"}}}"#,
    /// );
    /// let mcp = tool.to_mcp_tool();
    /// assert_eq!(mcp["name"], json!("add"));
    /// assert!(mcp["inputSchema"].is_object());
    /// ```
    #[cfg(feature = "serde")]
    pub fn to_mcp_tool(&self) -> serde_json::Value {
        let input_schema = self.parse_input_schema_or_empty();
        serde_json::json!({
            "name": self.name,
            "description": self.description,
            "inputSchema": input_schema,
        })
    }

    /// Parse `input_schema` into a `serde_json::Value`, falling back to an
    /// empty object on parse failure. Used by the multi-format exporters
    /// (`to_openai_function`, `to_anthropic_tool`, `to_mcp_tool`) so the
    /// outer envelope is always well-formed JSON regardless of the inner
    /// schema state.
    #[cfg(feature = "serde")]
    fn parse_input_schema_or_empty(&self) -> serde_json::Value {
        serde_json::from_str::<serde_json::Value>(&self.input_schema)
            .unwrap_or_else(|_| serde_json::json!({}))
    }
}

impl core::fmt::Display for ToolDefinition {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{}: {}", self.name, self.description)
    }
}

/// JSON Schema type for a tool parameter.
///
/// # Example
///
/// ```rust
/// 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::Integer.as_str(), "integer");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(u8)]
pub enum ParamType {
    /// String type
    String = 0,
    /// Integer type
    Integer = 1,
    /// Number type (floating point)
    Number = 2,
    /// Boolean type
    Boolean = 3,
    /// Array type
    Array = 4,
    /// Object type
    Object = 5,
}

impl ParamType {
    /// Return the JSON-Schema keyword for this variant (e.g. `"string"`).
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::ParamType;
    ///
    /// assert_eq!(ParamType::String.as_str(), "string");
    /// assert_eq!(ParamType::Integer.as_str(), "integer");
    /// ```
    pub fn as_str(&self) -> &'static str {
        match self {
            ParamType::String => "string",
            ParamType::Integer => "integer",
            ParamType::Number => "number",
            ParamType::Boolean => "boolean",
            ParamType::Array => "array",
            ParamType::Object => "object",
        }
    }

    /// Best-effort mapping from a Rust type name to a JSON-Schema type.
    /// Returns `None` for `Option<T>` (use [`FromJsonValue`] for those).
    ///
    /// # Example
    ///
    /// ```rust
    /// 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));
    /// ```
    pub fn from_rust_type(type_name: &str) -> Option<Self> {
        match type_name {
            "String" | "str" => Some(ParamType::String),
            "i8" | "i16" | "i32" | "i64" | "i128" | "u8" | "u16" | "u32" | "u64" | "u128"
            | "usize" | "isize" => Some(ParamType::Integer),
            "f32" | "f64" => Some(ParamType::Number),
            "bool" => Some(ParamType::Boolean),
            _ => {
                if type_name.starts_with("Vec<") {
                    Some(ParamType::Array)
                } else if type_name.starts_with("Option<") {
                    None
                } else {
                    Some(ParamType::Object)
                }
            }
        }
    }
}

/// A single parameter definition for a tool.
///
/// # Example
///
/// ```rust
/// use tokitai_core::{ToolParameter, ParamType};
///
/// let param = ToolParameter::new(
///     "city",
///     ParamType::String,
///     "Name of the city",
///     true, // required
/// );
/// ```
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ToolParameter {
    /// Parameter name
    pub name: &'static str,
    /// Parameter type
    #[cfg_attr(feature = "serde", serde(rename = "type"))]
    pub param_type: ParamType,
    /// Parameter description
    pub description: &'static str,
    /// Whether the parameter is required
    pub required: bool,
}

impl ToolParameter {
    /// Build a parameter definition.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolParameter, ParamType};
    ///
    /// let param = ToolParameter::new("limit", ParamType::Integer, "Number of results to return", false);
    /// ```
    pub fn new(
        name: &'static str,
        param_type: ParamType,
        description: &'static str,
        required: bool,
    ) -> Self {
        Self {
            name,
            param_type,
            description,
            required,
        }
    }
}

/// Error returned by tool invocations.
///
/// # Example
///
/// ```rust
/// use tokitai_core::{ToolError, ToolErrorKind};
///
/// let error = ToolError::validation_error("Missing required parameter 'city'");
/// assert_eq!(error.kind, ToolErrorKind::ValidationError);
/// ```
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ToolError {
    /// Error type classification
    pub kind: ToolErrorKind,
    /// Error message
    #[cfg(feature = "serde")]
    pub message: crate::serde_types::String,
    #[cfg(not(feature = "serde"))]
    pub message: &'static str,
}

#[cfg(feature = "serde")]
impl std::error::Error for ToolError {}

#[cfg(feature = "serde")]
impl std::fmt::Display for ToolError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "ToolError: {:?} - {}", self.kind, self.message)
    }
}

#[cfg(not(feature = "serde"))]
impl ToolError {
    /// Create a new error with the given `kind` and `message`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::new(ToolErrorKind::ValidationError, "field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn new(kind: ToolErrorKind, message: &'static str) -> Self {
        Self { kind, message }
    }

    /// Shortcut to build a `ValidationError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::validation_error("field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn validation_error(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::ValidationError,
            message,
        }
    }

    /// Shortcut to build a `NotFound` variant with the given tool name.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::not_found("unknown_tool");
    /// assert_eq!(err.kind, ToolErrorKind::NotFound);
    /// assert_eq!(err.message, "unknown_tool");
    /// ```
    pub fn not_found(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::NotFound,
            message,
        }
    }

    /// Shortcut to build an `InternalError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::internal_error("downstream timed out");
    /// assert_eq!(err.kind, ToolErrorKind::InternalError);
    /// ```
    pub fn internal_error(message: &'static str) -> Self {
        Self {
            kind: ToolErrorKind::InternalError,
            message,
        }
    }
}

#[cfg(feature = "serde")]
impl ToolError {
    /// Create a new error with the given `kind` and `message`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::new(ToolErrorKind::ValidationError, "field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn new(kind: ToolErrorKind, message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind,
            message: message.into(),
        }
    }

    /// Shortcut to build a `ValidationError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::validation_error("field 'name' is required");
    /// assert_eq!(err.kind, ToolErrorKind::ValidationError);
    /// ```
    pub fn validation_error(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::ValidationError,
            message: message.into(),
        }
    }

    /// Shortcut to build a `NotFound` variant with the given tool name.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::not_found("unknown_tool");
    /// assert_eq!(err.kind, ToolErrorKind::NotFound);
    /// ```
    pub fn not_found(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::NotFound,
            message: message.into(),
        }
    }

    /// Shortcut to build an `InternalError` variant with the given message.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::{ToolError, ToolErrorKind};
    ///
    /// let err = ToolError::internal_error("downstream timed out");
    /// assert_eq!(err.kind, ToolErrorKind::InternalError);
    /// ```
    pub fn internal_error(message: impl Into<crate::serde_types::String>) -> Self {
        Self {
            kind: ToolErrorKind::InternalError,
            message: message.into(),
        }
    }
}

/// Classification of a [`ToolError`] for structured error handling.
///
/// # Example
///
/// ```rust
/// use tokitai_core::ToolErrorKind;
///
/// // The four classifications:
/// assert_ne!(ToolErrorKind::ValidationError, ToolErrorKind::NotFound);
/// assert_ne!(ToolErrorKind::InternalError, ToolErrorKind::TypeError);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(u8)]
pub enum ToolErrorKind {
    /// Validation error - parameter validation failed
    ValidationError = 0,
    /// Not found - requested tool does not exist
    NotFound = 1,
    /// Internal error - tool execution failed
    InternalError = 2,
    /// Type error - parameter type mismatch
    TypeError = 3,
}

/// Compile-time tool registry trait.
///
/// Auto-implemented by the `#[tool]` macro for any `impl` block it processes.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::ToolProvider;
/// // After `#[tool]` on a type:
/// // let tools = Calculator::tool_definitions();
/// // let count = Calculator::tool_count();
/// // let tool  = Calculator::find_tool("add");
/// ```
pub trait ToolProvider {
    /// All tool definitions produced by this provider.
    fn tool_definitions() -> &'static [ToolDefinition];

    /// Number of tools produced by this provider.
    fn tool_count() -> usize {
        Self::tool_definitions().len()
    }

    /// Look up a tool definition by its `name`.
    fn find_tool(name: &str) -> Option<&'static ToolDefinition> {
        Self::tool_definitions().iter().find(|t| t.name == name)
    }
}

/// Runtime tool invocation trait. Auto-implemented by the `#[tool]` macro.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{ToolProvider, ToolCaller};
/// use serde_json::json;
///
/// let calc = Calculator;
/// let result = calc.call_tool("add", &json!({"a": 10, "b": 20})).unwrap();
/// assert_eq!(result, json!(30));
/// ```
#[cfg(feature = "serde")]
pub trait ToolCaller {
    /// Invoke a tool by `name` with the given JSON `args`.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::ToolCaller;
    /// use serde_json::json;
    ///
    /// // After `#[tool]` has been applied to Calculator:
    /// // let result = calc.call_tool("add", &json!({"a": 1, "b": 2})).unwrap();
    /// // assert_eq!(result, json!(3));
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a [`ToolError`] of kind [`ToolErrorKind::NotFound`] if no tool
    /// with the given name is registered, or of kind [`ToolErrorKind::ValidationError`]
    /// / [`ToolErrorKind::InternalError`] if argument parsing or tool
    /// execution fails.
    fn call_tool(
        &self,
        name: &str,
        args: &crate::serde_types::Value,
    ) -> Result<crate::serde_types::Value, ToolError>;
}

/// # From Json Value Trait
///
/// Parses JSON values into Rust types. Implemented once per type and used by
/// the `#[tool]` macro to extract typed parameters from JSON arguments.
///
/// # Example
///
/// ```rust
/// use tokitai_core::FromJsonValue;
/// use serde_json::json;
///
/// let args = json!({"count": 42, "name": "test"});
/// let count = i64::from_json_value(&args, "count").unwrap();
/// let name = String::from_json_value(&args, "name").unwrap();
/// assert_eq!(count, 42);
/// assert_eq!(name, "test");
/// ```
#[cfg(feature = "serde")]
pub trait FromJsonValue: Sized {
    /// Extract a typed value for `key` from a JSON arguments object.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::FromJsonValue;
    /// use serde_json::json;
    ///
    /// let args = json!({"count": 42});
    /// let count = i64::from_json_value(&args, "count").unwrap();
    /// assert_eq!(count, 42);
    /// ```
    ///
    /// # Errors
    ///
    /// Returns a [`ToolError`] of kind [`ToolErrorKind::ValidationError`] when
    /// `key` is missing or its value does not match `Self`'s expected type.
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError>;

    /// Extract a typed value for `key`, or `None` if extraction fails.
    ///
    /// Equivalent to `Self::from_json_value(args, key).ok()`. Useful for
    /// optional parameters.
    ///
    /// # Example
    ///
    /// ```rust
    /// use tokitai_core::FromJsonValue;
    /// use serde_json::json;
    ///
    /// let args = json!({});
    /// let missing: Option<i64> = i64::from_json_value_opt(&args, "absent");
    /// assert_eq!(missing, None);
    ///
    /// let args = json!({"count": 7});
    /// let present = i64::from_json_value_opt(&args, "count");
    /// assert_eq!(present, Some(7));
    /// ```
    fn from_json_value_opt(args: &crate::serde_types::Value, key: &str) -> Option<Self> {
        Self::from_json_value(args, key).ok()
    }
}

// ============== Primitive type impls ==============

#[cfg(feature = "serde")]
impl FromJsonValue for i64 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_i64()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for i32 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_i64()
            .map(|v| v as i32)
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for u64 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_u64()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected unsigned integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for u32 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_u64()
            .map(|v| v as u32)
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected unsigned integer",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for f64 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_f64()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected number",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for f32 {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_f64()
            .map(|v| v as f32)
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected number",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for bool {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_bool()
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected boolean",
                    key
                ))
            })
    }
}

#[cfg(feature = "serde")]
impl FromJsonValue for String {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        args.get(key)
            .ok_or_else(|| {
                ToolError::validation_error(format!("Missing required parameter '{}'", key))
            })?
            .as_str()
            .map(|s| s.to_string())
            .ok_or_else(|| {
                ToolError::validation_error(format!(
                    "Parameter '{}' has wrong type, expected string",
                    key
                ))
            })
    }
}

// ============== &str zero-copy support ==============
// Special handling: needs a lifetime, so we expose a standalone function.

/// Borrow a string parameter without copying.
///
/// # Example
///
/// ```rust
/// use tokitai_core::from_json_value_str;
/// use serde_json::json;
///
/// let args = json!({"city": "Paris"});
/// let city: &str = from_json_value_str(&args, "city").unwrap();
/// assert_eq!(city, "Paris");
/// ```
///
/// # Errors
///
/// Returns a [`ToolError`] of kind [`ToolErrorKind::ValidationError`] when
/// `key` is missing or its value is not a string.
#[cfg(feature = "serde")]
#[inline(always)]
pub fn from_json_value_str<'a>(
    args: &'a crate::serde_types::Value,
    key: &str,
) -> Result<&'a str, ToolError> {
    args.get(key)
        .ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?
        .as_str()
        .ok_or_else(|| {
            ToolError::validation_error(format!("Parameter '{}' type error, expected string", key))
        })
}

// ============== Option impls ==============

#[cfg(feature = "serde")]
impl<T: FromJsonValue> FromJsonValue for Option<T> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        Ok(T::from_json_value_opt(args, key))
    }
}

// ============== Vec impls ==============

#[cfg(feature = "serde")]
impl<T: serde::de::DeserializeOwned> FromJsonValue for Vec<T> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        let value = args.get(key).ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?;
        serde_json::from_value(value.clone()).map_err(|e| {
            ToolError::validation_error(format!("Parameter '{}' has wrong type: {}", key, e))
        })
    }
}

// ============== Helper: parse any DeserializeOwned type ==============
// For unsupported custom types, users can deserialize manually inside their method.

/// Parse a `DeserializeOwned` value for `key`. Useful for custom types not
/// covered by the [`FromJsonValue`] blanket impls.
///
/// # Example
///
/// ```rust
/// use tokitai_core::from_json_value_generic;
/// use serde_json::json;
/// use serde::Deserialize;
///
/// #[derive(Deserialize, Debug, PartialEq)]
/// struct Point { x: i32, y: i32 }
///
/// let args = json!({"p": {"x": 1, "y": 2}});
/// let p: Point = from_json_value_generic(&args, "p").unwrap();
/// assert_eq!(p, Point { x: 1, y: 2 });
/// ```
///
/// # Errors
///
/// Returns a [`ToolError`] of kind [`ToolErrorKind::ValidationError`] when
/// `key` is missing or its value cannot be deserialized into `T`.
#[cfg(feature = "serde")]
#[inline(always)]
pub fn from_json_value_generic<T: serde::de::DeserializeOwned>(
    args: &crate::serde_types::Value,
    key: &str,
) -> Result<T, ToolError> {
    let value = args.get(key).ok_or_else(|| {
        ToolError::validation_error(format!("Missing required parameter '{}'", key))
    })?;
    serde_json::from_value(value.clone())
        .map_err(|e| ToolError::validation_error(format!("Parameter '{}' type error: {}", key, e)))
}

// ============== HashMap impls ==============
#[cfg(feature = "serde")]
impl<V: serde::de::DeserializeOwned> FromJsonValue for std::collections::HashMap<String, V> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        let value = args.get(key).ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?;
        serde_json::from_value(value.clone()).map_err(|e| {
            ToolError::validation_error(format!("Parameter '{}' type error: {}", key, e))
        })
    }
}

// ============== BTreeMap impls ==============
#[cfg(feature = "serde")]
impl<V: serde::de::DeserializeOwned> FromJsonValue for std::collections::BTreeMap<String, V> {
    #[inline(always)]
    fn from_json_value(args: &crate::serde_types::Value, key: &str) -> Result<Self, ToolError> {
        let value = args.get(key).ok_or_else(|| {
            ToolError::validation_error(format!("Missing required parameter '{}'", key))
        })?;
        serde_json::from_value(value.clone()).map_err(|e| {
            ToolError::validation_error(format!("Parameter '{}' type error: {}", key, e))
        })
    }
}

/// Runtime configuration types used to override compile-time tool metadata.
#[cfg(feature = "serde")]
pub mod config;

/// # Runtime-Agnostic Async Executor
///
/// Bridge for the `#[tool]` macro's sync-from-async path that decouples
/// Tokitai from Tokio. The macro's sync wrapper delegates to a registered
/// [`AsyncExecutor`]; install one with [`set_async_executor`] to use
/// `async-std`, `smol`, `embassy`, or any custom executor.
///
/// ## Default behaviour
///
/// 1. Custom executor registered via [`set_async_executor`] -> use it.
/// 2. Otherwise, if inside a Tokio runtime, use the active
///    `Handle::block_on` (preserves backward compatibility).
/// 3. Otherwise, return a [`ToolError`] with a descriptive English message.
///
/// ## No-`std` fallback
///
/// When the `serde` feature is disabled the crate is `no_std` and no
/// executor is reachable; [`block_on_async`] always returns a
/// `ToolError::InternalError` so the macro can still type-check.
///
/// [`block_on_async`]: crate::block_on_async
///
/// This trait is **object-safe** so the user-registered executor can be
/// stored as `&'static dyn AsyncExecutor`. The type-erased
/// [`AsyncExecutor::block_on_dyn`] takes a boxed future and returns a boxed
/// output; typed convenience is provided by [`AsyncExecutorExt`].
pub trait AsyncExecutor: Send + Sync {
    /// Object-safe entry point: drive a boxed future to completion on the
    /// current thread and return its output as a boxed `Any`. Most users
    /// implement [`AsyncExecutorExt::block_on`] and let the blanket impl
    /// derive this; override it directly only for full control.
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::AsyncExecutor;
    /// use core::future::Future;
    /// use core::pin::Pin;
    /// use core::any::Any;
    ///
    /// struct ThreadPoolExecutor;
    /// impl AsyncExecutor for ThreadPoolExecutor {
    ///     fn block_on_dyn(
    ///         &self,
    ///         future: Pin<Box<dyn Future<Output = ()> + Send>>,
    ///     ) -> Box<dyn Any + Send> {
    ///         // ... drive the future to completion ...
    ///         # Box::new(())
    ///     }
    /// }
    /// ```
    fn block_on_dyn(
        &self,
        future: core::pin::Pin<Box<dyn core::future::Future<Output = ()> + Send>>,
    ) -> Box<dyn core::any::Any + Send>;
}

/// Typed convenience wrapper around [`AsyncExecutor::block_on_dyn`].
/// Implemented for every `T: AsyncExecutor`; re-introduces the natural
/// `block_on<F: Future>(&self, F) -> F::Output` signature on top of the
/// type-erased entry point.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{AsyncExecutor, AsyncExecutorExt};
///
/// fn drive<E: AsyncExecutor>(exec: &E) -> String {
///     exec.block_on(async { String::from("typed output") })
/// }
/// ```
pub trait AsyncExecutorExt: AsyncExecutor {
    /// Drive a future to completion and return its output.
    ///
    /// The future must be `Send + 'static` (so it can cross the type-erasure
    /// boundary) and its output must be `Send + 'static` (so it can be
    /// downcast on the call site).
    ///
    /// # Example
    ///
    /// ```rust,ignore
    /// use tokitai_core::{AsyncExecutor, AsyncExecutorExt};
    ///
    /// fn run<E: AsyncExecutor>(exec: &E) -> i32 {
    ///     exec.block_on(async { 21 + 21 })
    /// }
    /// ```
    ///
    /// # Panics
    ///
    /// Panics if the internal output slot mutex is poisoned or if the
    /// underlying [`AsyncExecutor::block_on_dyn`] returns without driving the
    /// future to completion.
    fn block_on<F>(&self, future: F) -> F::Output
    where
        F: core::future::Future + Send + 'static,
        F::Output: Send + 'static,
    {
        use core::any::Any;
        use core::sync::atomic::{AtomicBool, Ordering};
        use std::sync::{Arc, Mutex};

        let slot: Arc<Mutex<Option<F::Output>>> = Arc::new(Mutex::new(None));
        let ran: Arc<AtomicBool> = Arc::new(AtomicBool::new(false));
        let slot_inner = slot.clone();
        let ran_inner = ran.clone();

        let wrapped = async move {
            let output = future.await;
            *slot_inner
                .lock()
                .expect("AsyncExecutor output slot poisoned") = Some(output);
            ran_inner.store(true, Ordering::Release);
        };

        let _: Box<dyn Any + Send> = self.block_on_dyn(Box::pin(wrapped));

        assert!(
            ran.load(Ordering::Acquire),
            "AsyncExecutor did not drive the future to completion"
        );

        let mut guard = slot.lock().expect("AsyncExecutor output slot poisoned");
        guard
            .take()
            .expect("future reported complete but produced no output")
    }
}

impl<T: AsyncExecutor + ?Sized> AsyncExecutorExt for T {}

/// Process-wide slot that holds the user-registered [`AsyncExecutor`].
/// A `OnceLock<Box<dyn AsyncExecutor>>` is the portable, leak-free
/// storage: the box is leaked into the static slot, so the resulting
/// reference is `&'static`.
static ASYNC_EXECUTOR: std::sync::OnceLock<Box<dyn AsyncExecutor>> = std::sync::OnceLock::new();

/// Install a global [`AsyncExecutor`] used by every `#[tool]`-generated sync
/// wrapper. Call once at program startup, before any sync `call_tool` is
/// invoked on an `async` tool. The box is leaked: the executor lives for the
/// lifetime of the program. The first call wins; subsequent calls are
/// silently ignored (best-effort registration).
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{set_async_executor, AsyncExecutor, AsyncExecutorExt};
/// use core::future::Future;
/// use core::pin::Pin;
///
/// struct BlockingExecutor;
/// impl AsyncExecutor for BlockingExecutor {
///     fn block_on_dyn(
///         &self,
///         future: Pin<Box<dyn Future<Output = ()> + Send>>,
///     ) -> Box<dyn core::any::Any + Send> {
///         Box::new(futures::executor::block_on(future))
///     }
/// }
///
/// set_async_executor(Box::new(BlockingExecutor));
/// ```
pub fn set_async_executor<E: AsyncExecutor + 'static>(executor: Box<E>) {
    let trait_obj: Box<dyn AsyncExecutor> = executor;
    // `_ =` to ignore the `AlreadyInitialized` error; the registration
    // is best-effort. The first executor wins.
    let _ = ASYNC_EXECUTOR.set(trait_obj);
}

/// Return the currently registered [`AsyncExecutor`], or `None` if no
/// executor has been installed via [`set_async_executor`]. The returned
/// reference is `&'static` because the registered `Box<dyn AsyncExecutor>`
/// is held inside a `OnceLock` for the program's lifetime.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::current_async_executor;
///
/// // Initially no executor has been installed.
/// assert!(current_async_executor().is_none());
/// ```
pub fn current_async_executor() -> Option<&'static dyn AsyncExecutor> {
    ASYNC_EXECUTOR
        .get()
        .map(|b| b.as_ref() as &'static dyn AsyncExecutor)
}

/// Try to drive `future` to completion using the registered executor, the
/// current Tokio runtime (when available), or a clear English error.
///
/// This is the entry point used by the `#[tool]` macro. It is intentionally
/// panic-free and always returns a [`ToolError`] on failure so the macro
/// can propagate the error through `call_tool_sync` without `unwrap`.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::{block_on_async, set_async_executor, AsyncExecutor, AsyncExecutorExt};
/// use core::future::Future;
/// use core::pin::Pin;
/// use core::any::Any;
///
/// struct InlineExecutor;
/// impl AsyncExecutor for InlineExecutor {
///     fn block_on_dyn(
///         &self,
///         future: Pin<Box<dyn Future<Output = ()> + Send>>,
///     ) -> Box<dyn Any + Send> {
///         futures::executor::block_on(future);
///         Box::new(())
///     }
/// }
///
/// set_async_executor(Box::new(InlineExecutor));
/// let value: i32 = block_on_async(async { 21 + 21 }).unwrap();
/// assert_eq!(value, 42);
/// ```
///
/// # Errors
///
/// Returns a [`ToolError`] of kind [`ToolErrorKind::InternalError`] when no
/// executor is registered and no Tokio runtime is in scope. The `#[tool]`
/// macro also probes for a Tokio runtime and surfaces a richer message via
/// [`block_on_async_error_message`].
#[cfg(feature = "serde")]
pub fn block_on_async<F>(future: F) -> Result<F::Output, ToolError>
where
    F: core::future::Future + Send + 'static,
    F::Output: Send + 'static,
{
    if let Some(exec) = current_async_executor() {
        return Ok(exec.block_on(future));
    }

    // No executor was registered. The `#[tool]` macro's sync wrappers
    // additionally probe the current Tokio runtime as a final fallback;
    // here we only handle the user-registered executor path and return
    // a clear error so the macro can surface a helpful message.
    drop(future);
    Err(ToolError::internal_error(block_on_async_error_message()))
}

/// `no_std`/`no-serde` companion to [`block_on_async`]. Always returns an
/// error because no executor is reachable in a `no_std` build.
///
/// # Errors
///
/// Always returns `Err` with a static explanation string instructing the
/// caller to enable the `serde` feature and register an executor.
#[cfg(not(feature = "serde"))]
pub fn block_on_async<F>(_future: F) -> Result<F, &'static str> {
    Err(
        "no async runtime available in no_std build; enable the `serde` feature \
         and call `tokitai_core::set_async_executor(...)` to enable sync-from-async",
    )
}

/// Canonical English error message returned by the `#[tool]` macro when
/// it cannot find any executor to drive a sync-from-async call. The macro
/// embeds the return value of this function as the error string, so the
/// message is centralised here for consistency and future i18n.
///
/// # Example
///
/// ```rust
/// use tokitai_core::block_on_async_error_message;
///
/// let msg = block_on_async_error_message();
/// assert!(msg.contains("no async runtime"));
/// ```
pub const fn block_on_async_error_message() -> &'static str {
    "no async runtime registered; either call from within an async context, \
     run inside a tokio runtime, or call `tokitai_core::set_async_executor(...)` \
     before invoking"
}

#[cfg(feature = "serde")]
mod executor_internal {
    use super::*;

    /// A no-op executor used as a placeholder. Registered executors must
    /// implement [`AsyncExecutor`]; this stub panics on use so an accidental
    /// `set_async_executor(Box::new(NullExecutor))` is loud rather than
    /// silently broken.
    pub struct NullExecutor;

    impl AsyncExecutor for NullExecutor {
        /// # Panics
        ///
        /// Always panics with a message instructing the caller to install
        /// a real executor via [`crate::set_async_executor`].
        fn block_on_dyn(
            &self,
            _future: core::pin::Pin<Box<dyn core::future::Future<Output = ()> + Send>>,
        ) -> Box<dyn core::any::Any + Send> {
            panic!(
                "NullExecutor::block_on_dyn invoked; \
                 install a real AsyncExecutor via set_async_executor(...)"
            )
        }
    }
}

#[cfg(feature = "serde")]
pub mod serde_types {
    //! Re-exports of `serde_json` and `alloc::string` types under a stable
    //! path. Available when the `serde` feature is enabled.

    pub use alloc::string::String;
    pub use serde_json::Value;
}

/// Compile-time helper for emitting JSON Schema strings without runtime
/// overhead.
///
/// # Example
///
/// ```rust,ignore
/// use tokitai_core::json_schema;
///
/// const SCHEMA: &str = json_schema!({
///     "city": {
///         type: String,
///         description: "Name of the city",
///         required: true,
///     }
/// });
/// ```
#[macro_export]
macro_rules! json_schema {
    (
        {
            $($param_name:literal: {
                type: $param_type:ident,
                description: $description:literal,
                required: $required:literal $(,)?
            }),*
            $(,)?
        }
    ) => {{
        const SCHEMA: &str = concat!(
            "{\"type\":\"object\",\"properties\":{",
            $({
                concat!(
                    "\"", $param_name, "\":",
                    "{\"type\":\"", $crate::ParamType::$param_type.as_str(), "\",\"description\":\"", $description, "\"}"
                )
            },)*
            "},\"required\":[",
            $({
                if $required { concat!("\"", $param_name, "\"") } else { "" }
            },)*
            "]}"
        );
        SCHEMA
    }};
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_param_type_from_rust_type() {
        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)
        );
    }

    #[test]
    fn test_tool_definition_const() {
        let tool = ToolDefinition::new("test", "A test tool", "{}");
        assert_eq!(tool.name, "test");
        assert_eq!(tool.description, "A test tool");
    }

    #[cfg(feature = "serde")]
    #[test]
    fn test_tool_definition_to_json() {
        let tool = ToolDefinition::new("test", "A test tool", r#"{"type":"object"}"#);
        let json = tool.to_json().unwrap();
        assert!(json.contains(r#""name":"test""#));
    }

    // -----------------------------------------------------------------
    // AsyncExecutor unit tests
    //
    // The three scenarios the executor must cover are exercised in a
    // single `#[test]` so the order is deterministic. Splitting them
    // into three `#[test]` functions would not be reliable here:
    // libtest runs tests in alphabetical order, and the global
    // `ASYNC_EXECUTOR` slot is a `OnceLock` that can only be populated
    // once per process. A fresh-process test for the "no executor"
    // case is provided separately in
    // `tests/async_executor_no_executor_test.rs`.
    // -----------------------------------------------------------------

    /// Minimal test executor that drives a boxed future to completion via
    /// `futures::executor::block_on`. The output of the wrapped future is
    /// not used here because the typed `AsyncExecutorExt::block_on` reads
    /// the output from a shared slot.
    #[cfg(feature = "serde")]
    struct TestExecutor;

    #[cfg(feature = "serde")]
    impl AsyncExecutor for TestExecutor {
        fn block_on_dyn(
            &self,
            future: core::pin::Pin<Box<dyn core::future::Future<Output = ()> + Send>>,
        ) -> Box<dyn core::any::Any + Send> {
            futures::executor::block_on(future);
            Box::new(())
        }
    }

    /// Single-threaded executor used by the async-executor tests. We use
    /// `futures::executor::block_on` (no Tokio) so the suite can run
    /// without a Tokio runtime.
    #[cfg(feature = "serde")]
    #[test]
    #[serial_test::serial]
    fn test_async_executor_lifecycle() {
        // Step 1: in a fresh process the `OnceLock` is empty, so a
        // call to `block_on_async` returns the standard English
        // error. (We use a best-effort assertion: if a prior test in
        // the same binary has already set the executor, skip this
        // sub-assertion; the dedicated
        // `async_executor_no_executor_test.rs` integration test
        // exercises this path in a fresh process.)
        if current_async_executor().is_none() {
            let result: Result<(), ToolError> = block_on_async(async {});
            let err = result
                .expect_err("block_on_async should error when no AsyncExecutor is registered");
            assert_eq!(err.kind, ToolErrorKind::InternalError);
            let expected = block_on_async_error_message();
            assert!(
                err.message.contains(expected) || err.message.contains("no async runtime"),
                "expected English error message, got: {:?}",
                err.message
            );
        }

        // Step 2: register a custom executor and verify
        // `current_async_executor` returns it.
        set_async_executor(Box::new(TestExecutor));
        let exec = current_async_executor().expect("executor should be registered");
        // Sanity check: it is a `&'static dyn AsyncExecutor`.
        let _static_ref: &'static dyn AsyncExecutor = exec;

        // Step 3: drive a future with a `String` output through the
        // typed `AsyncExecutorExt::block_on` wrapper.
        let string_result: String = exec.block_on(async { String::from("hello, executor") });
        assert_eq!(string_result, "hello, executor");

        // Step 4: drive a future with a non-`()` typed output
        // (`(i32, String)`) through the type-erased `block_on_dyn`
        // boundary and back. This is the
        // `test_async_executor_typed_output` scenario.
        let tuple_result: (i32, String) = exec.block_on(async { (42, String::from("typed")) });
        assert_eq!(tuple_result, (42, String::from("typed")));
    }
}