Replays prior turns from `chats/{session}.json` when a session is given,
then appends the new user message and saves the round trip.

Args:
    prompt: User message to send to the model.
    session: Optional session name. Loads and appends history to `chats/{session}.json`.
    model: Grok model id (default `grok-4.6`).
    system_prompt: Optional system instruction prepended to the conversation.
    agent_count: 4 or 16. Only valid with `grok-4.20-multi-agent` for multi-agent research.
    service_tier: `"default"` or `"priority"`. Priority is processed faster at a higher token price.
    show_usage: Append a token usage and cost footer to the reply (default False).

Returns:
    The assistant's reply text, plus a token usage and cost footer when `show_usage` is true.

Attaches the given `file_ids` to the user turn so Grok can read/quote their
contents. Optional `session` persists local chat history across calls.

Args:
    prompt: Question or instruction about the attached files.
    file_ids: IDs of files previously returned by `upload_file`.
    session: Optional session name for persistent history in `chats/{session}.json`.
    model: Grok model id (default `grok-4.6`).
    system_prompt: Optional system instruction prepended to the conversation.
    show_usage: Append a token usage and cost footer to the reply (default False).

Returns:
    Assistant reply, followed by a `**Sources:**` list when the model cites URLs.

Accepts local image paths and/or public URLs in the same call. Local images
are sent as base64 data URIs (JPG/JPEG/PNG only, max 20 MiB each).

Args:
    prompt: Question or instruction about the image(s).
    session: Optional session name for persistent history in `chats/{session}.json`.
    model: Vision-capable Grok model (default `grok-4.6`).
    image_paths: Local image file paths to analyze.
    image_urls: Public image URLs to analyze.
    detail: Image detail level. One of `"auto"`, `"low"`, or `"high"`.
    show_usage: Append a token usage and cost footer to the reply (default False).

Returns:
    The model's textual answer about the image(s).

Only removes the client-side JSON file. Server-side stored responses are untouched.

Args:
    session: Session name whose `chats/{session}.json` file should be deleted.

Returns:
    Confirmation string or a not-found message.

The agent iteratively writes and executes Python (with common scientific
libraries) to arrive at a numeric, data, or analysis answer.

Args:
    prompt: Task or question requiring computation.
    model: Grok model driving the agent (default `grok-4.6`).
    max_turns: Cap the number of reasoning/execution turns.
    show_usage: Append a token usage and cost footer to the answer (default False).

Returns:
    Markdown with the final answer followed by each code execution block's stdout.

Args:
    file_id: ID of the file to remove.

Returns:
    Confirmation string with the deleted file ID.

Args:
    response_id: ID of the stored response to remove.

Returns:
    Confirmation string with the deleted response ID.

Continues the source video seamlessly from its last frame. `duration` sets
the length of the extension only, not the total output. For example, a
10 second input plus `duration=5` yields a 15 second final video.

Args:
    prompt: What should happen in the extended segment.
    video_url: Public URL of the source video (.mp4, 2–15 s).
    model: Video model (default `grok-imagine-video`).
    duration: Length of the extension in seconds (2–10, default 6).
    show_usage: Append a token usage and cost footer to the result (default False).

Returns:
    Markdown block with the extended video URL and total duration.

Pass `image_paths` and/or `image_urls` to edit images or use them as
visual references. Multiple references are combined in a single call.

Args:
    prompt: Image description, or the edit instruction when references are provided.
    model: Image model (`grok-imagine-image` or `grok-imagine-image-pro`).
    image_paths: Local image files (JPG/PNG) used as edit sources or references.
    image_urls: Public image URLs used as edit sources or references.
    n: Number of images to generate (1–10).
    image_format: `"url"` (default) or `"base64"`. Base64 responses carry no URL,
        so they are always saved locally.
    aspect_ratio: Aspect ratio like `"16:9"`, `"1:1"`, or `"9:16"`.
    resolution: `"1k"` or `"2k"`.
    save: Write each image to `images/` and report the local path instead of the
        remote URL. Remote URLs are temporary, so save anything you want to keep.
    show_usage: Append a token usage and cost footer to the result (default False).

Returns:
    Markdown block listing each image as a saved local path when saving, otherwise
    as a temporary remote URL.

Text-to-video by default. Provide an image to animate (image-to-video), or
a source video to edit. Only one mode per call. Reference images can be
added to guide style and subjects. Generation polls synchronously (xAI's
default timeout is 10 minutes).

Args:
    prompt: Video description, or the edit instruction for video editing.
    model: Video model (default `grok-imagine-video`).
    image_path: Local image to use as the starting frame.
    image_url: Public image URL to use as the starting frame.
    video_path: Local video to edit (max 20 MB, .mp4, ≤ 8.7s).
    video_url: Public video URL to edit (.mp4, ≤ 8.7s).
    reference_image_paths: Local images used as style/subject references.
    reference_image_urls: Public image URLs used as style/subject references.
    duration: Video length in seconds (1–15, ignored when editing).
    aspect_ratio: Aspect ratio like `"16:9"` or `"9:16"` (ignored when editing).
    resolution: `"480p"` or `"720p"` (ignored when editing).
    show_usage: Append a token usage and cost footer to the result (default False).

Returns:
    Markdown block with the generated video URL and actual duration.

Args:
    session: Session name to load from `chats/{session}.json` (default `default`).

Returns:
    Formatted transcript with timestamps and roles, or a not-found message.

Args:
    file_id: ID returned by `upload_file`.

Returns:
    Markdown block with the file's ID, filename, size, and creation time.

Bytes are decoded as UTF-8 with replacement for invalid sequences. Output
is truncated to `max_bytes` to avoid overwhelming the response.

Args:
    file_id: ID of the uploaded file.
    max_bytes: Maximum bytes to return (default 500 000).

Returns:
    File text, with a truncation note appended when the content exceeds `max_bytes`.

Enable any subset of tools and attach any mix of uploaded files and images.
The agent decides which tools to use per turn. Supports optional local
session history and multi-agent research via `agent_count`.

Args:
    prompt: Task or question for the agent.
    session: Optional session name for persistent history in `chats/{session}.json`.
    model: Grok model driving the agent (default `grok-4.6`).
    file_ids: IDs of previously uploaded files to attach as context.
    image_urls: Public image URLs to attach.
    image_paths: Local image files to attach (sent as base64 data URIs).
    use_web_search: Enable the agentic web search tool.
    use_x_search: Enable the agentic X (Twitter) search tool.
    use_code_execution: Enable the Python code execution tool.
    use_image_generation: Enable the server-side image generation tool, letting the agent
        create and edit images mid-conversation. Images are saved under `images/`.
    image_generation_action: Which image capabilities to expose: `"auto"` (default, generate
        and edit), `"generate"` (text-to-image only), or `"edit"` (editing only).
    allowed_domains: Web search allow-list (max 5, mutually exclusive with excluded).
    excluded_domains: Web search deny-list (max 5).
    allowed_x_handles: X search handle allow-list (max 10, mutually exclusive with excluded).
    excluded_x_handles: X search handle deny-list (max 10).
    from_date: X search inclusive start date as `DD-MM-YYYY`.
    to_date: X search inclusive end date as `DD-MM-YYYY`.
    enable_image_understanding: Let search tools analyze images they encounter.
    enable_video_understanding: Let X search analyze videos in posts.
    enable_image_search: Let web search find and return image results.
    include_inline_citations: Embed `[1]`-style citation markers into the answer.
    system_prompt: Optional system instruction prepended to the conversation.
    max_turns: Cap the agent's reasoning/tool turns.
    agent_count: 4 or 16. Only valid with `grok-4.20-multi-agent`.
    service_tier: `"default"` or `"priority"`. Priority is processed faster at a higher token price.
    show_usage: Append a token usage and cost footer to the answer (default False).

Returns:
    Markdown with the answer body, then a `**Generated Images:**` list of saved file paths
    when the agent produced images, then a `**Sources:**` list when citations exist.

Returns:
    Markdown list of session names with turn counts and last-message timestamps,
    or a placeholder message when no sessions exist.

Args:
    limit: Maximum number of files to return (default 100).
    order: `"asc"` or `"desc"` sort order (default `"desc"`).
    sort_by: Field to sort by, such as `"created_at"`.

Returns:
    Markdown list of files with ID, filename, and size, or a placeholder when empty.

Returns:
    Markdown sections for language models (input/output $/M tokens) and
    image generation models ($/image), each with the model's release date.

Args:
    response_id: ID returned by a prior `stateful_chat` call.

Returns:
    The stored assistant reply and its `**Response ID:**`, or a not-found message.

The xAI API stores every turn so the client only needs to send the latest
prompt plus `previous_response_id`. Omit `response_id` to start a new thread.

Args:
    prompt: User message to append.
    model: Grok model id (default `grok-4.6`).
    response_id: ID of the previous response to continue from (omit to start fresh).
    system_prompt: Optional system instruction. Applied only on the first turn.
    show_usage: Append a token usage and cost footer to the reply (default False).

Returns:
    Assistant reply followed by the new `**Response ID:**` to pass back next turn.

Supported types include PDFs and text documents (see xAI file docs). The
returned file ID can be passed to `chat_with_files` or `grok_agent`.

Args:
    file_path: Absolute or relative path to the local file.
    expires_after: Optional TTL in seconds. The file is deleted from xAI
        automatically once it expires (omit to keep the file indefinitely).

Returns:
    Markdown block with the assigned file ID, filename, and size.

Grok browses the web across multiple turns, optionally inspecting images on
pages, then synthesizes an answer with citations.

Args:
    prompt: Search query or research question.
    model: Grok model used to drive the agent (default `grok-4.6`).
    allowed_domains: Restrict search to these domains (max 5, mutually exclusive with excluded).
    excluded_domains: Exclude these domains from search (max 5).
    enable_image_understanding: Let the agent analyze images it encounters.
    enable_image_search: Let the agent search for and return image results.
    include_inline_citations: Embed `[1]`-style citation markers into the answer text.
    max_turns: Cap the agent's reasoning/tool turns.
    show_usage: Append a token usage and cost footer to the answer (default False).

Returns:
    Markdown with the answer body followed by a `**Sources:**` list of cited URLs.

Searches posts, threads, and users on X. Can filter by handle allow/deny
lists and a date range, and optionally analyze images/videos attached to posts.

Args:
    prompt: Search query or question about X content.
    model: Grok model driving the agent (default `grok-4.6`).
    allowed_x_handles: Restrict search to these handles (max 10, mutually exclusive with excluded).
    excluded_x_handles: Exclude these handles (max 10).
    from_date: Inclusive start date as `DD-MM-YYYY`.
    to_date: Inclusive end date as `DD-MM-YYYY`.
    enable_image_understanding: Let the agent analyze images in posts.
    enable_video_understanding: Let the agent analyze videos in posts (X Search only).
    include_inline_citations: Embed `[1]`-style citation markers into the answer.
    max_turns: Cap the agent's reasoning/tool turns.
    show_usage: Append a token usage and cost footer to the answer (default False).

Returns:
    Markdown with the answer body followed by a `**Sources:**` list of cited posts.