Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Auto-update documentation after merge [skip ci]

camel-docs-bot1821e4c7773a
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json
index 3cd9e15a8..86536d5d3 100644
--- a/docs/mintlify/docs.json
+++ b/docs/mintlify/docs.json
@@ -259,6 +259,7 @@
"reference/camel.configs.vllm_config",
"reference/camel.configs.volcano_config",
"reference/camel.configs.watsonx_config",
+ "reference/camel.configs.xai_config",
"reference/camel.configs.yi_config",
"reference/camel.configs.zhipuai_config"
]
@@ -359,6 +360,7 @@
"reference/camel.models.vllm_model",
"reference/camel.models.volcano_model",
"reference/camel.models.watsonx_model",
+ "reference/camel.models.xai_model",
"reference/camel.models.yi_model",
"reference/camel.models.zhipuai_model",
"reference/camel.models.reward.base_reward_model",
diff --git a/docs/mintlify/reference/camel.configs.xai_config.mdx b/docs/mintlify/reference/camel.configs.xai_config.mdx
new file mode 100644
index 000000000..3e4ac32fa
--- /dev/null
+++ b/docs/mintlify/reference/camel.configs.xai_config.mdx
@@ -0,0 +1,27 @@
+<a id="camel.configs.xai_config"></a>
+
+<a id="camel.configs.xai_config.XAIConfig"></a>
+
+## XAIConfig
+
+```python
+class XAIConfig(BaseConfig):
+```
+
+Defines the parameters for generating chat completions using the
+xAI native SDK (gRPC).
+
+**Parameters:**
+
+- **temperature** (float, optional): Sampling temperature to use, between :obj:`0` and :obj:`2`. Higher values make the output more random, while lower values make it more focused and deterministic. (default: :obj:`None`)
+- **top_p** (float, optional): An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So :obj:`0.1` means only the tokens comprising the top 10% probability mass are considered. (default: :obj:`None`)
+- **max_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. (default: :obj:`None`)
+- **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
+- **stream** (bool, optional): If True, partial message deltas will be sent as they become available. (default: :obj:`None`)
+- **response_format** (object, optional): An object specifying the format that the model must output. Setting to a Pydantic BaseModel enables JSON schema mode for structured outputs. (default: :obj:`None`)
+- **tool_choice** (Union[dict[str, str], str], optional): Controls which (if any) tool is called by the model. :obj:`"none"` means the model will not call any tool. :obj:`"auto"` means the model can pick between generating a message or calling one or more tools. :obj:`"required"` means the model must call one or more tools. (default: :obj:`None`)
+- **reasoning_effort** (str, optional): Controls the reasoning effort for reasoning models. Valid values: :obj:`"low"`, :obj:`"medium"`, :obj:`"high"`. (default: :obj:`None`)
+- **use_encrypted_content** (bool, optional): If True, encrypted reasoning traces will be returned and preserved across conversation turns. This is required for multi-turn reasoning with thinking models. (default: :obj:`None`)
+- **store_messages** (bool, optional): If True, request/response history is stored on xAI's servers for up to 30 days, enabling conversation chaining via previous_response_id. If False, history is managed locally. (default: :obj:`None`)
+- **frequency_penalty** (float, optional): Penalizes new tokens based on their existing frequency in the text so far. Values between :obj:`-2.0` and :obj:`2.0`. (default: :obj:`None`)
+- **presence_penalty** (float, optional): Penalizes new tokens based on whether they appear in the text so far. Values between :obj:`-2.0` and :obj:`2.0`. (default: :obj:`None`)
diff --git a/docs/mintlify/reference/camel.models.openai_compatible_model.mdx b/docs/mintlify/reference/camel.models.openai_compatible_model.mdx
index 6d54f2920..04cf2a4f3 100644
--- a/docs/mintlify/reference/camel.models.openai_compatible_model.mdx
+++ b/docs/mintlify/reference/camel.models.openai_compatible_model.mdx
@@ -20,7 +20,8 @@ Constructor for model backend supporting OpenAI compatibility.
- **timeout** (Optional[float], optional): The timeout value in seconds for API calls. If not provided, will fall back to the MODEL_TIMEOUT environment variable or default to 180 seconds. (default: :obj:`None`)
- **max_retries** (int, optional): Maximum number of retries for API calls. (default: :obj:`3`)
- **client** (Optional[Any], optional): A custom synchronous OpenAI-compatible client instance. If provided, this client will be used instead of creating a new one. Useful for RL frameworks like AReaL or rLLM that provide OpenAI-compatible clients (e.g., ArealOpenAI). The client should implement the OpenAI client interface with `.chat.completions.create()` and `.beta.chat. completions.parse()` methods. (default: :obj:`None`)
-- **async_client** (Optional[Any], optional): A custom asynchronous OpenAI-compatible client instance. If provided, this client will be used instead of creating a new one. The client should implement the AsyncOpenAI client interface. (default: :obj:`None`) **kwargs (Any): Additional arguments to pass to the OpenAI client initialization. These can include parameters like 'organization', 'default_headers', 'http_client', etc. Ignored if custom clients are provided.
+- **async_client** (Optional[Any], optional): A custom asynchronous OpenAI-compatible client instance. If provided, this client will be used instead of creating a new one. The client should implement the AsyncOpenAI client interface. (default: :obj:`None`)
+- **api_mode** (`Literal["chat_completions", "responses"], optional`): API mode to use. Supported values: `"chat_completions"` (default) and `"responses"`. **kwargs (Any): Additional arguments to pass to the OpenAI client initialization. These can include parameters like 'organization', 'default_headers', 'http_client', etc. Ignored if custom clients are provided.
<a id="camel.models.openai_compatible_model.OpenAICompatibleModel.__init__"></a>
@@ -38,6 +39,7 @@ def __init__(
max_retries: int = 3,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
+ api_mode: Literal['chat_completions', 'responses'] = 'chat_completions',
**kwargs: Any
):
```
@@ -111,6 +113,130 @@ def _request_stream_parse(
Request streaming structured output parsing.
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._normalize_tools_for_responses_api"></a>
+
+### _normalize_tools_for_responses_api
+
+```python
+def _normalize_tools_for_responses_api(tools: List[Dict[str, Any]]):
+```
+
+Convert chat-completions style function tools to Responses style.
+
+Input:
+`{"type":"function","function":{"name":"foo",...}}`
+Output:
+`{"type":"function","name":"foo",...}`
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._enforce_object_additional_properties_false"></a>
+
+### _enforce_object_additional_properties_false
+
+```python
+def _enforce_object_additional_properties_false(schema: Any):
+```
+
+Recursively enforce strict object schema for Responses API.
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._get_response_chain_session_key"></a>
+
+### _get_response_chain_session_key
+
+```python
+def _get_response_chain_session_key(self):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._clear_response_chain_state"></a>
+
+### _clear_response_chain_state
+
+```python
+def _clear_response_chain_state(self, session_key: str):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._responses_chain_enabled"></a>
+
+### _responses_chain_enabled
+
+```python
+def _responses_chain_enabled(request_config: Dict[str, Any]):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._prepare_responses_input_and_chain"></a>
+
+### _prepare_responses_input_and_chain
+
+```python
+def _prepare_responses_input_and_chain(self, messages: List[OpenAIMessage], chain_enabled: bool = True):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._convert_messages_to_responses_input"></a>
+
+### _convert_messages_to_responses_input
+
+```python
+def _convert_messages_to_responses_input(messages: List[OpenAIMessage]):
+```
+
+Convert chat-completions style messages to Responses input items.
+
+This specifically rewrites tool-calling history:
+- assistant message with `tool_calls` -> one or more `function_call`
+items (+ optional assistant message when content exists)
+- tool message -> `function_call_output` item
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._save_response_chain_state"></a>
+
+### _save_response_chain_state
+
+```python
+def _save_response_chain_state(
+ self,
+ session_key: str,
+ response_id: Optional[str],
+ message_count: int
+):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._prepare_responses_request_config"></a>
+
+### _prepare_responses_request_config
+
+```python
+def _prepare_responses_request_config(
+ self,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ response_format: Optional[Type[BaseModel]] = None,
+ stream: bool = False
+):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._request_responses"></a>
+
+### _request_responses
+
+```python
+def _request_responses(
+ self,
+ messages: List[OpenAIMessage],
+ response_format: Optional[Type[BaseModel]],
+ tools: Optional[List[Dict[str, Any]]] = None
+):
+```
+
+<a id="camel.models.openai_compatible_model.OpenAICompatibleModel._request_responses_stream"></a>
+
+### _request_responses_stream
+
+```python
+def _request_responses_stream(
+ self,
+ messages: List[OpenAIMessage],
+ response_format: Optional[Type[BaseModel]],
+ tools: Optional[List[Dict[str, Any]]] = None
+):
+```
+
<a id="camel.models.openai_compatible_model.OpenAICompatibleModel.token_counter"></a>
### token_counter
diff --git a/docs/mintlify/reference/camel.models.xai_model.mdx b/docs/mintlify/reference/camel.models.xai_model.mdx
new file mode 100644
index 000000000..33552e92f
--- /dev/null
+++ b/docs/mintlify/reference/camel.models.xai_model.mdx
@@ -0,0 +1,343 @@
+<a id="camel.models.xai_model"></a>
+
+<a id="camel.models.xai_model.XAIModel"></a>
+
+## XAIModel
+
+```python
+class XAIModel(BaseModelBackend):
+```
+
+xAI native SDK model backend using gRPC.
+
+This backend uses the `__INLINE_CODE_0__` package to communicate with xAI's API
+via gRPC, providing access to Grok models with native features like
+encrypted thinking content and server-side conversation storage.
+
+**Parameters:**
+
+- **model_type** (Union[ModelType, str]): Model for which a backend is created, one of the Grok series (e.g. `__INLINE_CODE_0__`).
+- **model_config_dict** (Optional[Dict[str, Any]], optional): A dictionary of configuration parameters. If :obj:`None`, :obj:`XAIConfig().as_dict()` will be used. (default: :obj:`None`)
+- **api_key** (Optional[str], optional): The API key for authenticating with the xAI service. Falls back to the `__INLINE_CODE_0____INLINE_CODE_1__None`)
+- **url** (Optional[str], optional): Not used for native SDK (gRPC), kept for interface compatibility. (default: :obj:`None`)
+- **token_counter** (Optional[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter( ModelType.GPT_4O_MINI)` will be used. (default: :obj:`None`)
+- **timeout** (Optional[float], optional): The timeout value in seconds for API calls. If not provided, will fall back to the MODEL_TIMEOUT environment variable or default to 180 seconds. (default: :obj:`None`)
+- **max_retries** (int, optional): Maximum number of retries for API calls. (default: :obj:`3`)
+
+<a id="camel.models.xai_model.XAIModel.__init__"></a>
+
+### __init__
+
+```python
+def __init__(
+ self,
+ model_type: Union[ModelType, str],
+ model_config_dict: Optional[Dict[str, Any]] = None,
+ api_key: Optional[str] = None,
+ url: Optional[str] = None,
+ token_counter: Optional[BaseTokenCounter] = None,
+ timeout: Optional[float] = None,
+ max_retries: int = 3,
+ **kwargs: Any
+):
+```
+
+<a id="camel.models.xai_model.XAIModel.client"></a>
+
+### client
+
+```python
+def client(self):
+```
+
+Lazy-initialize the synchronous xAI SDK client.
+
+<a id="camel.models.xai_model.XAIModel.async_client"></a>
+
+### async_client
+
+```python
+def async_client(self):
+```
+
+Lazy-initialize the asynchronous xAI SDK client.
+
+<a id="camel.models.xai_model.XAIModel.token_counter"></a>
+
+### token_counter
+
+```python
+def token_counter(self):
+```
+
+**Returns:**
+
+ OpenAITokenCounter: The token counter following the model's
+tokenization style.
+
+<a id="camel.models.xai_model.XAIModel.stream"></a>
+
+### stream
+
+```python
+def stream(self):
+```
+
+**Returns:**
+
+ bool: Whether the model is in stream mode.
+
+<a id="camel.models.xai_model.XAIModel._convert_openai_tool_to_xai"></a>
+
+### _convert_openai_tool_to_xai
+
+```python
+def _convert_openai_tool_to_xai(self, tool: Dict[str, Any]):
+```
+
+Convert an OpenAI-format tool dict to xAI SDK Tool proto.
+
+**Parameters:**
+
+- **tool**: OpenAI-format tool dict with `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2__` keys.
+
+**Returns:**
+
+ chat_pb2.Tool: The xAI SDK tool proto.
+
+<a id="camel.models.xai_model.XAIModel._convert_messages"></a>
+
+### _convert_messages
+
+```python
+def _convert_messages(self, messages: List[OpenAIMessage]):
+```
+
+Convert OpenAI-format messages to xAI SDK message objects.
+
+Handles system, user, assistant (with/without tool calls), and tool
+result messages. For assistant messages that carry reasoning or
+encrypted content (stored from a previous response), those fields are
+injected into the protobuf message so xAI can reconstruct the
+reasoning chain.
+
+**Parameters:**
+
+- **messages**: List of OpenAI-format message dicts.
+
+**Returns:**
+
+ List of `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2__`.
+
+<a id="camel.models.xai_model.XAIModel._map_finish_reason"></a>
+
+### _map_finish_reason
+
+```python
+def _map_finish_reason(xai_reason: str):
+```
+
+Map xAI finish reason enum name to OpenAI-style string.
+
+<a id="camel.models.xai_model.XAIModel._xai_response_to_chat_completion"></a>
+
+### _xai_response_to_chat_completion
+
+```python
+def _xai_response_to_chat_completion(self, response: 'XAIResponse'):
+```
+
+Convert an xAI SDK Response to an OpenAI ChatCompletion.
+
+Preserves reasoning_content and encrypted_content from the response
+for downstream consumers and for injection into future requests.
+
+**Parameters:**
+
+- **response**: The xAI SDK Response object.
+
+**Returns:**
+
+ ChatCompletion: The OpenAI-compatible completion object.
+
+<a id="camel.models.xai_model.XAIModel._make_chunk"></a>
+
+### _make_chunk
+
+```python
+def _make_chunk(
+ chunk_id: str,
+ model: str,
+ delta_content: Optional[str] = None,
+ delta_reasoning: Optional[str] = None,
+ delta_tool_calls: Optional[List[Any]] = None,
+ finish_reason: Optional[str] = None,
+ usage: Any = None
+):
+```
+
+Build a `__INLINE_CODE_0__` with proper pydantic objects.
+
+<a id="camel.models.xai_model.XAIModel._build_delta_tool_calls"></a>
+
+### _build_delta_tool_calls
+
+```python
+def _build_delta_tool_calls(self, tool_calls: Sequence):
+```
+
+Convert xAI tool calls to ChoiceDeltaToolCall objects.
+
+<a id="camel.models.xai_model.XAIModel._stream_to_chunks"></a>
+
+### _stream_to_chunks
+
+```python
+def _stream_to_chunks(self, stream_iter, total_messages: int = 0):
+```
+
+Convert xAI SDK stream iterator to ChatCompletionChunk generator.
+
+**Parameters:**
+
+- **stream_iter**: Iterator from `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2__` tuples.
+- **total_messages**: Total message count for chain state bookkeeping.
+- **Yields**:
+- **ChatCompletionChunk**: OpenAI-compatible streaming chunks.
+
+<a id="camel.models.xai_model.XAIModel._build_chat_kwargs"></a>
+
+### _build_chat_kwargs
+
+```python
+def _build_chat_kwargs(self, tools: Optional[List[Dict[str, Any]]] = None):
+```
+
+Build keyword arguments for `__INLINE_CODE_0__`.
+
+Translates the CAMEL model config dict into xAI SDK create
+parameters, and converts OpenAI-format tools to xAI Tool protos.
+
+**Parameters:**
+
+- **tools**: Optional list of OpenAI-format tool dicts.
+
+**Returns:**
+
+ Dict of keyword arguments for `__INLINE_CODE_0__`.
+
+<a id="camel.models.xai_model.XAIModel._compute_delta_messages"></a>
+
+### _compute_delta_messages
+
+```python
+def _compute_delta_messages(self, messages: List[OpenAIMessage]):
+```
+
+Compute the delta messages for conversation chaining.
+
+If we have a `__INLINE_CODE_0__` from the last turn, only the
+new messages since then need to be sent. If the conversation was
+truncated (memory reset / context-window management), fall back to
+sending the full history.
+
+**Parameters:**
+
+- **messages**: The full conversation history from ChatAgent.
+
+**Returns:**
+
+ The messages to actually send in this request.
+
+<a id="camel.models.xai_model.XAIModel._save_response_chain"></a>
+
+### _save_response_chain
+
+```python
+def _save_response_chain(self, response_id: Optional[str], total_messages: int):
+```
+
+Persist the chain state after a successful response.
+
+<a id="camel.models.xai_model.XAIModel._inject_encrypted_content"></a>
+
+### _inject_encrypted_content
+
+```python
+def _inject_encrypted_content(self, messages: List[OpenAIMessage]):
+```
+
+Inject stored encrypted/reasoning content into conversation
+history for multi-turn reasoning.
+
+When `__INLINE_CODE_0__` is enabled, the encrypted thinking
+traces from the previous response must be included in the assistant
+message of the conversation history so xAI can reconstruct the
+reasoning chain.
+
+**Parameters:**
+
+- **messages**: The original OpenAI-format messages.
+
+**Returns:**
+
+ Messages with encrypted content injected into the last assistant
+message.
+
+<a id="camel.models.xai_model.XAIModel._prepare_chat"></a>
+
+### _prepare_chat
+
+```python
+def _prepare_chat(
+ self,
+ messages: List[OpenAIMessage],
+ tools: Optional[List[Dict[str, Any]]] = None,
+ response_format: Optional[Type[BaseModel]] = None
+):
+```
+
+**Returns:**
+
+ (chat_kwargs, messages_to_send, total_message_count)
+
+<a id="camel.models.xai_model.XAIModel._handle_response"></a>
+
+### _handle_response
+
+```python
+def _handle_response(self, response: 'XAIResponse', total_messages: int):
+```
+
+Convert response and update chain state.
+
+<a id="camel.models.xai_model.XAIModel._run"></a>
+
+### _run
+
+```python
+def _run(
+ self,
+ messages: List[OpenAIMessage],
+ response_format: Optional[Type[BaseModel]] = None,
+ tools: Optional[List[Dict[str, Any]]] = None
+):
+```
+
+Runs inference using the xAI native SDK.
+
+Uses `__INLINE_CODE_0__` to chain conversations on xAI's
+server, sending only new (delta) messages instead of the full
+history on subsequent turns.
+
+**Parameters:**
+
+- **messages** (List[OpenAIMessage]): Message list with the chat history in OpenAI API format.
+- **response_format** (Optional[Type[BaseModel]]): The format of the response.
+- **tools** (Optional[List[Dict[str, Any]]]): The schema of the tools to use for the request.
+
+**Returns:**
+
+ Union[ChatCompletion, Stream[ChatCompletionChunk]]:
+`__INLINE_CODE_0__` in non-stream mode, or a
+`__INLINE_CODE_1__` generator in stream mode.