text-to-cypher 0.2.0

#![recursion_limit = "256"]
#![doc(test(attr(recursion_limit = "256")))]
//! # text-to-cypher
//!
//! A library for translating natural language text to Cypher queries using AI models.
//!
//! This library provides both a programmatic API and a REST server for converting
//! natural language questions into Cypher queries for graph databases, with built-in
//! support for `FalkorDB`.
//!
//! ## Features
//!
//! - **Text to Cypher Translation**: Convert natural language queries to Cypher database queries using AI
//! - **Schema Discovery**: Automatically discover and analyze graph database schemas
//! - **UDF Context**: Optionally surface a `FalkorDB` instance's user-defined functions to the model
//! - **Query Validation**: Built-in validation system to catch syntax errors before execution
//! - **Self-Healing Queries**: Automatic retry with error feedback when queries fail
//! - **Flexible AI Integration**: Support for multiple AI providers through the genai crate
//!
//! ## Library Usage
//!
//! To use text-to-cypher as a library in your Rust application:
//!
//! ```toml
//! [dependencies]
//! text-to-cypher = { version = "0.1", default-features = false }
//! ```
//!
//! ### Basic Example
//!
//! ```rust,no_run
//! use text_to_cypher::{TextToCypherClient, ChatRequest, ChatMessage, ChatRole};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
//!     // Create a client
//!     let client = TextToCypherClient::new(
//!         "gpt-4o-mini",
//!         "your-api-key",
//!         "falkor://127.0.0.1:6379"
//!     );
//!
//!     // Create a chat request
//!     let request = ChatRequest {
//!         messages: vec![
//!             ChatMessage {
//!                 role: ChatRole::User,
//!                 content: "Find all actors who appeared in movies released after 2020".to_string(),
//!             }
//!         ]
//!     };
//!
//!     // Convert text to Cypher and execute
//!     let response = client.text_to_cypher("movies", request).await?;
//!     
//!     println!("Generated query: {}", response.cypher_query.unwrap());
//!     println!("Result: {}", response.cypher_result.unwrap());
//!     println!("Answer: {}", response.answer.unwrap());
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Generate Cypher Only (Without Execution)
//!
//! ```rust,no_run
//! use text_to_cypher::{TextToCypherClient, ChatRequest, ChatMessage, ChatRole};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
//!     let client = TextToCypherClient::new(
//!         "gpt-4o-mini",
//!         "your-api-key",
//!         "falkor://127.0.0.1:6379"
//!     );
//!
//!     let request = ChatRequest {
//!         messages: vec![
//!             ChatMessage {
//!                 role: ChatRole::User,
//!                 content: "Find all people with more than 5 friends".to_string(),
//!             }
//!         ]
//!     };
//!
//!     // Generate query only, don't execute
//!     let response = client.cypher_only("social", request).await?;
//!     println!("Query: {}", response.cypher_query.unwrap());
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Using Core Functions Directly
//!
//! For more control, you can use the core functions directly:
//!
//! ```rust,no_run
//! use text_to_cypher::{core, ChatRequest, ChatMessage, ChatRole};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
//!     // Discover schema
//!     let schema = core::discover_graph_schema(
//!         "falkor://127.0.0.1:6379",
//!         "movies"
//!     ).await?;
//!     
//!     // Create GenAI client
//!     let client = core::create_genai_client(Some("your-api-key"));
//!     
//!     // Generate query
//!     let chat_req = ChatRequest {
//!         messages: vec![
//!             ChatMessage {
//!                 role: ChatRole::User,
//!                 content: "Find all actors".to_string(),
//!             }
//!         ]
//!     };
//!     
//!     let query = core::generate_cypher_query(
//!         &chat_req,
//!         &schema,
//!         &client,
//!         "gpt-4o-mini"
//!     ).await?;
//!     
//!     // Execute query
//!     let result = core::execute_cypher_query(
//!         &query,
//!         "movies",
//!         "falkor://127.0.0.1:6379",
//!         true
//!     ).await?;
//!     
//!     println!("Result: {}", result);
//!     Ok(())
//! }
//! ```
//!
//! ## Server Mode
//!
//! To use the REST server, enable the `server` feature (enabled by default):
//!
//! ```toml
//! [dependencies]
//! text-to-cypher = "0.1"
//! ```
//!
//! Then run the binary:
//!
//! ```bash
//! cargo run
//! ```

// Core modules - always available
pub mod chat;
pub mod core;
pub mod error;
pub mod formatter;
pub mod models_catalog;
pub mod processor;
pub mod schema;
pub mod skills;
pub mod template;
pub mod udf;
pub mod usage;
pub mod validator;

// Re-export commonly used types for easier access
pub use chat::{ChatMessage, ChatRequest, ChatRole};
pub use error::ErrorResponse;
pub use genai::adapter::AdapterKind;
pub use processor::{
    TextToCypherRequest, TextToCypherResponse, process_text_to_cypher_with_context, process_text_to_cypher_with_skills,
};
pub use skills::{SkillCatalog, SkillProfile};
pub use udf::{UdfCatalog, UdfError, UdfFunction, UdfLibrary, UdfSource};
pub use usage::TokenUsage;
// Server-specific modules - only when server feature is enabled
#[cfg(feature = "server")]
pub mod mcp;

/// A high-level client for text-to-cypher operations.
///
/// This client provides a convenient interface for converting natural language
/// to Cypher queries and executing them against a `FalkorDB` instance.
///
/// # Example
///
/// ```no_run
/// use text_to_cypher::{TextToCypherClient, ChatRequest, ChatMessage, ChatRole};
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
///     let client = TextToCypherClient::new(
///         "gpt-4o-mini",
///         "your-api-key",
///         "falkor://127.0.0.1:6379"
///     );
///
///     let request = ChatRequest {
///         messages: vec![
///             ChatMessage {
///                 role: ChatRole::User,
///                 content: "Find all nodes".to_string(),
///             }
///         ]
///     };
///
///     let response = client.text_to_cypher("my_graph", request).await?;
///     Ok(())
/// }
/// ```
pub struct TextToCypherClient {
    model: String,
    api_key: String,
    falkordb_connection: String,
    llm_endpoint: Option<String>,
    skill_catalog: Option<SkillCatalog>,
    udf_source: UdfSource,
}

impl TextToCypherClient {
    /// Creates a new `TextToCypherClient`.
    ///
    /// The client includes the built-in, read-only `FalkorDB` Cypher skills by default, so generated
    /// queries account for `FalkorDB`-specific syntax without any extra setup. Use
    /// [`without_skills`](Self::without_skills) to disable them, or
    /// [`with_additional_skills`](Self::with_additional_skills) to extend them.
    ///
    /// # Arguments
    ///
    /// * `model` - The AI model to use (e.g., "gpt-4o-mini", "anthropic:claude-3")
    /// * `api_key` - API key for the AI service
    /// * `falkordb_connection` - `FalkorDB` connection string (e.g., `falkor://127.0.0.1:6379`)
    ///
    /// # Example
    ///
    /// ```no_run
    /// use text_to_cypher::TextToCypherClient;
    ///
    /// let client = TextToCypherClient::new(
    ///     "gpt-4o-mini",
    ///     "your-api-key",
    ///     "falkor://127.0.0.1:6379"
    /// );
    /// ```
    #[must_use]
    pub fn new(
        model: impl Into<String>,
        api_key: impl Into<String>,
        falkordb_connection: impl Into<String>,
    ) -> Self {
        Self {
            model: model.into(),
            api_key: api_key.into(),
            falkordb_connection: falkordb_connection.into(),
            llm_endpoint: None,
            skill_catalog: Some(SkillCatalog::builtin()),
            udf_source: UdfSource::Off,
        }
    }

    /// Sets a custom LLM provider endpoint/base URL.
    ///
    /// This is useful for OpenAI-compatible local providers such as LM Studio
    /// (for example, `http://localhost:1234/v1`).
    #[must_use]
    pub fn with_llm_endpoint(
        mut self,
        endpoint: impl Into<String>,
    ) -> Self {
        self.llm_endpoint = Some(endpoint.into());
        self
    }

    /// Replaces the skill catalog used for Cypher skill loading.
    ///
    /// This **replaces** the built-in `FalkorDB` skills that [`new`](Self::new) installs by default. To
    /// keep the built-in skills and add your own, use [`with_additional_skills`](Self::with_additional_skills).
    ///
    /// When set, the AI model can access specialized `FalkorDB` Cypher skills
    /// for better query generation. Providers that support tool calling load
    /// skills on-demand; others get skill content injected into the prompt.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use text_to_cypher::{TextToCypherClient, SkillCatalog};
    /// use std::path::Path;
    ///
    /// let catalog = SkillCatalog::from_directory(Path::new("./skills")).unwrap();
    /// let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379")
    ///     .with_skills(catalog);
    /// ```
    #[must_use]
    pub fn with_skills(
        mut self,
        catalog: SkillCatalog,
    ) -> Self {
        self.skill_catalog = Some(catalog);
        self
    }

    /// Adds `catalog` to the current skills (the built-in `FalkorDB` skills by default), with `catalog`
    /// overriding any skill that shares an ID.
    #[must_use]
    pub fn with_additional_skills(
        mut self,
        catalog: SkillCatalog,
    ) -> Self {
        self.skill_catalog = Some(match self.skill_catalog.take() {
            Some(existing) => existing.merged_with(catalog),
            None => catalog,
        });
        self
    }

    /// Disables all Cypher skills for this client, including the built-in `FalkorDB` skills.
    #[must_use]
    pub fn without_skills(mut self) -> Self {
        self.skill_catalog = None;
        self
    }

    /// Enables discovery of the connected instance's user-defined functions (UDFs).
    ///
    /// On each request the client runs `GRAPH.UDF LIST` and surfaces the available
    /// `library.function` call targets to the model so generated Cypher can use them. UDFs are
    /// **instance-global** (shared across every graph on the server). On a `FalkorDB` server that
    /// does not support UDFs this degrades to no UDF context rather than failing the request.
    ///
    /// UDF context is **off by default**; call this to opt in.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use text_to_cypher::TextToCypherClient;
    ///
    /// let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379")
    ///     .with_discovered_udfs();
    /// ```
    #[must_use]
    pub fn with_discovered_udfs(mut self) -> Self {
        self.udf_source = UdfSource::Discover;
        self
    }

    /// Supplies a caller-built UDF catalog to surface to the model.
    ///
    /// Use this to provide pre-fetched or cached UDF metadata — for example in `cypher_only` mode
    /// without a live database, or to avoid a `GRAPH.UDF LIST` call per request. A provided catalog
    /// is used as-is (no discovery is performed).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use text_to_cypher::{TextToCypherClient, UdfCatalog, UdfLibrary, UdfFunction};
    ///
    /// let catalog = UdfCatalog::from_libraries(vec![UdfLibrary {
    ///     name: "mylib".to_string(),
    ///     functions: vec![UdfFunction::new("Foo")],
    /// }]);
    /// let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379")
    ///     .with_udfs(catalog);
    /// ```
    #[must_use]
    pub fn with_udfs(
        mut self,
        catalog: UdfCatalog,
    ) -> Self {
        self.udf_source = UdfSource::Provided(catalog);
        self
    }

    /// Disables UDF context for this client (the default).
    #[must_use]
    pub fn without_udfs(mut self) -> Self {
        self.udf_source = UdfSource::Off;
        self
    }

    /// Converts natural language text to Cypher and executes the query.
    ///
    /// This is the main method for full text-to-cypher processing:
    /// 1. Discovers the graph schema
    /// 2. Generates a Cypher query using AI
    /// 3. Executes the query
    /// 4. Generates a natural language answer
    ///
    /// # Arguments
    ///
    /// * `graph_name` - Name of the graph to query
    /// * `request` - Chat request containing the user's question
    ///
    /// # Errors
    ///
    /// Returns an error if schema discovery, query generation, execution, or answer generation fails.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use text_to_cypher::{TextToCypherClient, ChatRequest, ChatMessage, ChatRole};
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// # let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379");
    /// let request = ChatRequest {
    ///     messages: vec![
    ///         ChatMessage {
    ///             role: ChatRole::User,
    ///             content: "Find all actors".to_string(),
    ///         }
    ///     ]
    /// };
    ///
    /// let response = client.text_to_cypher("movies", request).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn text_to_cypher(
        &self,
        graph_name: impl Into<String>,
        request: ChatRequest,
    ) -> Result<TextToCypherResponse, Box<dyn std::error::Error + Send + Sync>> {
        let req = TextToCypherRequest {
            graph_name: graph_name.into(),
            chat_request: request,
            model: Some(self.model.clone()),
            key: Some(self.api_key.clone()),
            falkordb_connection: Some(self.falkordb_connection.clone()),
            llm_endpoint: self.llm_endpoint.clone(),
            cypher_only: false,
        };

        let response = processor::process_text_to_cypher_with_context(
            req,
            Some(self.model.clone()),
            Some(self.api_key.clone()),
            self.falkordb_connection.clone(),
            self.skill_catalog.as_ref(),
            &self.udf_source,
        )
        .await;

        if response.is_error() {
            return Err(response.error.unwrap_or_else(|| "Unknown error".to_string()).into());
        }

        Ok(response)
    }

    /// Generates a Cypher query without executing it.
    ///
    /// Use this method when you only want to generate the query for inspection
    /// or manual execution.
    ///
    /// # Arguments
    ///
    /// * `graph_name` - Name of the graph to generate query for
    /// * `request` - Chat request containing the user's question
    ///
    /// # Errors
    ///
    /// Returns an error if schema discovery or query generation fails.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use text_to_cypher::{TextToCypherClient, ChatRequest, ChatMessage, ChatRole};
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// # let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379");
    /// let request = ChatRequest {
    ///     messages: vec![
    ///         ChatMessage {
    ///             role: ChatRole::User,
    ///             content: "Find all actors".to_string(),
    ///         }
    ///     ]
    /// };
    ///
    /// let response = client.cypher_only("movies", request).await?;
    /// println!("Generated query: {}", response.cypher_query.unwrap());
    /// # Ok(())
    /// # }
    /// ```
    pub async fn cypher_only(
        &self,
        graph_name: impl Into<String>,
        request: ChatRequest,
    ) -> Result<TextToCypherResponse, Box<dyn std::error::Error + Send + Sync>> {
        let req = TextToCypherRequest {
            graph_name: graph_name.into(),
            chat_request: request,
            model: Some(self.model.clone()),
            key: Some(self.api_key.clone()),
            falkordb_connection: Some(self.falkordb_connection.clone()),
            llm_endpoint: self.llm_endpoint.clone(),
            cypher_only: true,
        };

        let response = processor::process_text_to_cypher_with_context(
            req,
            Some(self.model.clone()),
            Some(self.api_key.clone()),
            self.falkordb_connection.clone(),
            self.skill_catalog.as_ref(),
            &self.udf_source,
        )
        .await;

        if response.is_error() {
            return Err(response.error.unwrap_or_else(|| "Unknown error".to_string()).into());
        }

        Ok(response)
    }

    /// Discovers and returns the schema of a graph.
    ///
    /// # Arguments
    ///
    /// * `graph_name` - Name of the graph to discover schema for
    ///
    /// # Errors
    ///
    /// Returns an error if schema discovery fails.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # use text_to_cypher::TextToCypherClient;
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// # let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379");
    /// let schema = client.discover_schema("movies").await?;
    /// println!("Schema: {}", schema);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn discover_schema(
        &self,
        graph_name: impl Into<String>,
    ) -> Result<String, Box<dyn std::error::Error + Send + Sync>> {
        core::discover_graph_schema(&self.falkordb_connection, &graph_name.into()).await
    }

    /// Lists all available model names for a specific AI provider
    ///
    /// # Arguments
    ///
    /// * `adapter_kind` - The AI provider to query
    ///
    /// # Returns
    ///
    /// A vector of model names supported by the adapter
    ///
    /// # Errors
    ///
    /// Returns an error if the model listing request fails
    ///
    /// # Example
    ///
    /// ```no_run
    /// use text_to_cypher::TextToCypherClient;
    /// use genai::adapter::AdapterKind;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let client = TextToCypherClient::new(
    ///     "gpt-4o-mini",
    ///     "your-api-key",
    ///     "falkor://127.0.0.1:6379"
    /// );
    ///
    /// let models = client.list_models(AdapterKind::OpenAI).await?;
    /// println!("Available OpenAI models: {:?}", models);
    /// # Ok(())
    /// # }
    /// ```
    pub async fn list_models(
        &self,
        adapter_kind: AdapterKind,
    ) -> Result<Vec<String>, Box<dyn std::error::Error + Send + Sync>> {
        let client = core::create_genai_client_with_endpoint(Some(&self.api_key), self.llm_endpoint.as_deref());
        core::list_adapter_models_with_endpoint(adapter_kind, &client, self.llm_endpoint.as_deref()).await
    }

    /// Lists all available models across all supported AI providers
    ///
    /// # Returns
    ///
    /// A hashmap mapping adapter kinds to their available model names
    ///
    /// # Errors
    ///
    /// Returns an error if the model listing fails
    ///
    /// # Note
    ///
    /// Each provider's live results are merged with a curated static catalog, so
    /// providers with a curated list still return models even when the configured API
    /// key does not match them. Providers without a curated list (e.g. Ollama) are only
    /// returned when reachable.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use text_to_cypher::TextToCypherClient;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    /// let client = TextToCypherClient::new(
    ///     "gpt-4o-mini",
    ///     "your-api-key",
    ///     "falkor://127.0.0.1:6379"
    /// );
    ///
    /// let all_models = client.list_all_models().await?;
    /// for (kind, models) in all_models {
    ///     println!("{kind}: {} models", models.len());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub async fn list_all_models(
        &self
    ) -> Result<std::collections::HashMap<AdapterKind, Vec<String>>, Box<dyn std::error::Error + Send + Sync>> {
        let client = core::create_genai_client_with_endpoint(Some(&self.api_key), self.llm_endpoint.as_deref());
        core::list_all_models_with_endpoint(&client, self.llm_endpoint.as_deref()).await
    }
}

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

    #[test]
    fn test_client_creation() {
        let client = TextToCypherClient::new("gpt-4o-mini", "test-api-key", "falkor://127.0.0.1:6379");

        assert_eq!(client.model, "gpt-4o-mini");
        assert_eq!(client.api_key, "test-api-key");
        assert_eq!(client.falkordb_connection, "falkor://127.0.0.1:6379");
        assert_eq!(client.llm_endpoint, None);
    }

    #[test]
    fn test_client_creation_with_string() {
        let client = TextToCypherClient::new(
            "anthropic:claude-3".to_string(),
            "key123".to_string(),
            "falkor://localhost:6379".to_string(),
        );

        assert_eq!(client.model, "anthropic:claude-3");
        assert_eq!(client.api_key, "key123");
        assert_eq!(client.falkordb_connection, "falkor://localhost:6379");
        assert_eq!(client.llm_endpoint, None);
        // new() installs the built-in FalkorDB skills by default
        assert!(client.skill_catalog.is_some());
    }

    #[test]
    fn test_client_with_llm_endpoint() {
        let client = TextToCypherClient::new("openai::local-model", "key", "falkor://localhost:6379")
            .with_llm_endpoint("http://localhost:1234/v1");

        assert_eq!(client.llm_endpoint, Some("http://localhost:1234/v1".to_string()));
    }

    #[test]
    fn test_client_with_skills() {
        let catalog = SkillCatalog::empty();
        let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://localhost:6379").with_skills(catalog);
        assert!(client.skill_catalog.is_some());
    }

    #[test]
    fn test_new_client_includes_builtin_skills() {
        let client = TextToCypherClient::new("gpt-4o-mini", "key", "falkor://127.0.0.1:6379");
        let catalog = client.skill_catalog.as_ref().expect("builtin skills by default");
        assert!(!catalog.is_empty());
        assert!(catalog.get_skill("falkordb-fulltext-search").is_some());
    }

    #[test]
    fn test_without_skills_clears_builtin() {
        let client = TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379").without_skills();
        assert!(client.skill_catalog.is_none());
    }

    #[test]
    fn test_with_skills_replaces_builtin() {
        let client = TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379").with_skills(SkillCatalog::empty());
        assert!(client.skill_catalog.as_ref().unwrap().is_empty());
    }

    #[test]
    fn test_new_client_has_udf_off_by_default() {
        let client = TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379");
        assert_eq!(client.udf_source, UdfSource::Off);
    }

    #[test]
    fn test_with_discovered_udfs_sets_discover() {
        let client = TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379").with_discovered_udfs();
        assert_eq!(client.udf_source, UdfSource::Discover);
    }

    #[test]
    fn test_with_udfs_sets_provided_catalog() {
        let catalog = UdfCatalog::from_libraries(vec![UdfLibrary {
            name: "mylib".to_string(),
            functions: vec![UdfFunction::new("Foo")],
        }]);
        let client = TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379").with_udfs(catalog.clone());
        assert_eq!(client.udf_source, UdfSource::Provided(catalog));
    }

    #[test]
    fn test_without_udfs_resets_to_off() {
        let client = TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379")
            .with_discovered_udfs()
            .without_udfs();
        assert_eq!(client.udf_source, UdfSource::Off);
    }

    #[test]
    fn test_with_additional_skills_keeps_builtin() {
        let client =
            TextToCypherClient::new("m", "k", "falkor://127.0.0.1:6379").with_additional_skills(SkillCatalog::empty());
        assert!(
            client
                .skill_catalog
                .as_ref()
                .unwrap()
                .get_skill("falkordb-fulltext-search")
                .is_some()
        );
    }

    #[test]
    fn test_chat_request_construction() {
        let request = ChatRequest {
            messages: vec![
                ChatMessage {
                    role: ChatRole::User,
                    content: "Hello".to_string(),
                },
                ChatMessage {
                    role: ChatRole::Assistant,
                    content: "Hi there".to_string(),
                },
            ],
        };

        assert_eq!(request.messages.len(), 2);
        assert_eq!(request.messages[0].role, ChatRole::User);
        assert_eq!(request.messages[1].role, ChatRole::Assistant);
    }

    #[test]
    fn test_chat_role_serialization() {
        let role = ChatRole::User;
        let json = serde_json::to_string(&role).unwrap();
        assert_eq!(json, r#""user""#);

        let role = ChatRole::Assistant;
        let json = serde_json::to_string(&role).unwrap();
        assert_eq!(json, r#""assistant""#);

        let role = ChatRole::System;
        let json = serde_json::to_string(&role).unwrap();
        assert_eq!(json, r#""system""#);
    }

    #[test]
    fn test_chat_message_serialization() {
        let message = ChatMessage {
            role: ChatRole::User,
            content: "Test message".to_string(),
        };

        let json = serde_json::to_string(&message).unwrap();
        let deserialized: ChatMessage = serde_json::from_str(&json).unwrap();

        assert_eq!(deserialized.role, ChatRole::User);
        assert_eq!(deserialized.content, "Test message");
    }

    #[test]
    fn test_chat_request_serialization() {
        let request = ChatRequest {
            messages: vec![ChatMessage {
                role: ChatRole::User,
                content: "Find all nodes".to_string(),
            }],
        };

        let json = serde_json::to_string(&request).unwrap();
        let deserialized: ChatRequest = serde_json::from_str(&json).unwrap();

        assert_eq!(deserialized.messages.len(), 1);
        assert_eq!(deserialized.messages[0].content, "Find all nodes");
    }

    #[test]
    fn test_error_response_structure() {
        let error = ErrorResponse {
            error: "Test error".to_string(),
            message: "Detailed message".to_string(),
            status_code: 500,
        };

        assert_eq!(error.error, "Test error");
        assert_eq!(error.message, "Detailed message");
        assert_eq!(error.status_code, 500);
    }

    #[test]
    fn test_chat_role_equality() {
        assert_eq!(ChatRole::User, ChatRole::User);
        assert_eq!(ChatRole::Assistant, ChatRole::Assistant);
        assert_eq!(ChatRole::System, ChatRole::System);
        assert_ne!(ChatRole::User, ChatRole::Assistant);
    }

    #[test]
    fn test_client_with_different_models() {
        let models = vec!["gpt-4o-mini", "gpt-4o", "anthropic:claude-3", "gemini:gemini-2.0-flash-exp"];

        for model in models {
            let client = TextToCypherClient::new(model, "key", "falkor://localhost:6379");
            assert_eq!(client.model, model);
        }
    }
}