xai-grok 0.1.0

//! # xai-grok
//!
//! A high-level async client for the [xAI Grok API], built on top of the
//! [`stream-rs`](stream_rs) streaming toolkit.
//!
//! xAI exposes an **OpenAI-compatible** REST API at `https://api.x.ai/v1`, so
//! this crate speaks the `OpenAI` chat-completions wire format while using
//! `stream-rs` for the part most clients get wrong: byte-accurate Server-Sent
//! Events parsing of the streamed response. Chunk boundaries, multi-line
//! `data:` fields, partial UTF-8, and interleaved tool-call deltas are all
//! handled correctly regardless of how the bytes arrive off the socket.
//!
//! ## Capabilities
//!
//! * **Chat** — [`GrokClient::chat`] for a single buffered response.
//! * **Realtime streaming** — [`GrokClient::chat_stream`] yields a
//!   [`futures_core::Stream`] of parsed [`ChatChunk`]s; or use
//!   [`GrokClient::chat_stream_collect`] to fold deltas back into the final
//!   message with a live token callback.
//! * **Tool calling** — declare [`Tool`]s and read back [`ToolCall`]s.
//! * **Vision** — multimodal [`Content::Parts`] with image URLs / `data:` URIs.
//! * **Structured outputs** — [`ResponseFormat::json_schema`].
//!
//! > **Embeddings:** xAI does **not** currently expose a public
//! > `/v1/embeddings` REST endpoint (embeddings exist only server-side inside
//! > the Collections API), so this crate intentionally does not provide an
//! > embeddings method rather than inventing one.
//!
//! ## Quick start
//!
//! ```no_run
//! use xai_grok::{GrokClient, ChatRequest, Message};
//!
//! # async fn run() -> xai_grok::Result<()> {
//! let client = GrokClient::from_env()?; // reads XAI_API_KEY
//! let req = ChatRequest::new("grok-4.3", vec![
//!     Message::system("You are a concise assistant."),
//!     Message::user("Say hello in one word."),
//! ]);
//! let resp = client.chat(req).await?;
//! println!("{}", resp.content().unwrap_or_default());
//! # Ok(())
//! # }
//! ```
//!
//! [xAI Grok API]: https://docs.x.ai

#![warn(missing_docs)]

mod client;
mod error;
pub mod types;

pub use client::{ChatStream, GrokClient, GrokClientBuilder, DEFAULT_BASE_URL};
pub use error::{Error, Result};

// Re-export the most-used types at the crate root for ergonomics.
pub use types::{
    ChatChunk, ChatRequest, ChatResponse, Content, ContentPart, Delta, FunctionCall, FunctionDef,
    ImageUrl, Message, ResponseFormat, Role, Tool, ToolCall, ToolChoice, Usage,
};

// Re-export the underlying accumulator so callers can fold streamed deltas
// themselves if they don't use `chat_stream_collect`.
pub use stream_rs::accumulators::openai::OpenAiAccumulator;