`) for a message.
**Parameters:**
* **message** (Message): The message to convert to HTML.
**Returns:**
str: The HTML representation of the message.
## derive\_key
```python theme={"system"}
def derive_key(password: str, length: int):
```
Derive a fixed-length key from the password using SHA256.
## decrypt
```python theme={"system"}
def decrypt(ciphertext_b64: str, password: str):
```
Decrypt base64-encoded ciphertext with XOR.
## \_compute\_stat
```python theme={"system"}
def _compute_stat(values: list, stat: str):
```
## aggregate\_results
```python theme={"system"}
def aggregate_results(
single_eval_results: List[SingleEvalResult],
default_stats: Tuple[str, str] = ('mean', 'std'),
name2stats: Optional[Dict[str, Tuple[str]]] = None
):
```
Aggregate results from multiple evaluations into a single EvalResult.
**Parameters:**
* **single\_eval\_results** (List\[SingleEvalResult]): A list of `SingleEvalResult` objects.
* **default\_stats** (Tuple\[str, str]): A tuple of default statistics to compute. (default: :obj:`("mean", "std")`)
* **name2stats** (Optional\[Dict\[str, Tuple\[str]]]): A dictionary mapping metric names to statistics to compute. (default: :obj:`None`)
**Returns:**
EvalResult: An `EvalResult` object containing aggregated results.
## BrowseCompBenchmark
```python theme={"system"}
class BrowseCompBenchmark(BaseBenchmark):
```
BrowseComp Benchmark for evaluating browser-based comprehension tasks.
This benchmark evaluates the ability of language models to comprehend and
answer questions based on browser-based content, measuring accuracy and
performance.
### **init**
```python theme={"system"}
def __init__(
self,
save_to: str,
processes: int = 1,
num_examples: Optional[int] = None,
n_repeats: int = 1
):
```
Initialize the BrowseComp benchmark.
**Parameters:**
* **save\_to** (str): The file to save the results.
* **processes** (int, optional): The number of processes to use for parallel processing. (default: :obj:`1`)
* **num\_examples** (Optional\[int]): Number of examples to evaluate. If None, all examples are used. Controls the sample size for testing. (default: :obj:`None`)
* **n\_repeats** (int, optional): Number of times to repeat each example. Useful for evaluating consistency across multiple runs. (default: :obj:`1`)
### download
```python theme={"system"}
def download(self):
```
**Returns:**
self: The benchmark instance
### load
```python theme={"system"}
def load(self):
```
**Returns:**
self: The benchmark instance
### train
```python theme={"system"}
def train(self):
```
### run
```python theme={"system"}
def run(
self,
pipeline_template: Union[ChatAgent, RolePlaying, Workforce],
chat_turn_limit: int = 10,
roleplaying_summarizer: Optional[ChatAgent] = None,
task_json_formatter: Optional[ChatAgent] = None
):
```
Run the benchmark by processing each example in parallel.
This method applies the provided pipeline to each example in the
dataset using a process pool for parallel execution. It shows progress
using tqdm and stores the results in self.\_raw\_results.
**Parameters:**
* **pipeline\_template** (Union\[ChatAgent, RolePlaying, Workforce]): The template agent or framework to use for processing examples. Can be a ChatAgent, RolePlaying, or Workforce instance that will be cloned for each example.
* **chat\_turn\_limit** (int): Maximum number of conversation turns allowed when using RolePlaying pipeline. (default: :obj:`10`)
* **roleplaying\_summarizer** (Optional\[ChatAgent]): Optional ChatAgent to summarize RolePlaying conversations. If None and RolePlaying is used, a default summarizer will be created. (default: :obj:`None`)
* **task\_json\_formatter** (Optional\[ChatAgent]): Optional ChatAgent to format task JSON. If None and Workforce is used, a default formatter will be created. (default: :obj:`None`)
### make\_report
```python theme={"system"}
def make_report(self, eval_result: EvalResult):
```
Create a standalone HTML report from an EvalResult.
### validate
```python theme={"system"}
def validate(self, grader: Optional[ChatAgent] = None):
```
Validate the raw results using the GRADER\_TEMPLATE and ChatAgent.
This method evaluates the correctness of each response by
multi-threading. A dedicated chat agent is created in each thread.
The chat agent will compare raw result with the expected answer. The
grading results will be aggregated in a report.
**Parameters:**
* **grader**: The ChatAgent used for validation. If None, a default agent will be created in each thread. If provided, the provided agent will be used as a template and be cloned into new agents in each thread. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.benchmarks.gaia
## RetrieverProtocol
```python theme={"system"}
class RetrieverProtocol(Protocol):
```
Protocol for the retriever class. Any retriever class implementing
this protocol can be used in the benchmark class.
### retrieve
```python theme={"system"}
def retrieve(
self,
query: str,
contents: List[str],
**kwargs: Dict[str, Any]
):
```
Retrieve the relevant content for the query.
**Parameters:**
* **query** (str): The query to retrieve the content for.
* **contents** (List\[str]): The list of contents to search in. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
Dict\[str, Any]: The relevant content for the query.
### reset
```python theme={"system"}
def reset(self, **kwargs):
```
Reset the retriever.
Some benchmarks may require resetting the retriever
after each query.
**Returns:**
bool: True if the reset was successful, False otherwise.
## DefaultGAIARetriever
```python theme={"system"}
class DefaultGAIARetriever(AutoRetriever):
```
Default retriever for the GAIA benchmark.
This retriever uses AutoRetriever in camel to retrieve the content based on
the query.
### retrieve
```python theme={"system"}
def retrieve(
self,
query: str,
contents: List[str],
**kwargs: Any
):
```
Retrieve the content based on the query.
**Parameters:**
* **query** (str): The query to search for.
* **contents** (List\[str]): The list of contents to search from. \*\*kwargs (Any): The keyword arguments to pass to the retriever.
**Returns:**
Dict\[str, Any]: The retrieved content.
### reset
```python theme={"system"}
def reset(self, **kwargs: Any):
```
Reset the retriever.
**Returns:**
bool: Whether the reset was successful.
## GAIABenchmark
```python theme={"system"}
class GAIABenchmark(BaseBenchmark):
```
GAIA Benchmark adapted from ["GAIA: a benchmark for General AI
Assistants"](https://huggingface.co/datasets/gaia-benchmark/GAIA).
**Parameters:**
* **data\_dir** (str): The directory to save the data.
* **save\_to** (str): The file to save the results.
* **retriever** (Optional\[RetrieverProtocol]): The retriever to use. (default: :obj:`None`)
* **processes** (int, optional): The number of processes to use. (default: :obj:`1`)
### **init**
```python theme={"system"}
def __init__(
self,
data_dir: str,
save_to: str,
retriever: Optional[RetrieverProtocol] = None,
processes: int = 1
):
```
Initialize the GAIA benchmark.
**Parameters:**
* **data\_dir** (str): The directory to save the data.
* **save\_to** (str): The file to save the results.
* **retriever** (Optional\[RetrieverProtocol], optional): The retriever to use. (default: :obj:`None`)
* **processes** (int, optional): The number of processes to use for parallel processing. (default: :obj:`1`)
### download
```python theme={"system"}
def download(self):
```
Download the GAIA dataset.
### load
```python theme={"system"}
def load(self, force_download = False):
```
Load the GAIA dataset.
**Parameters:**
* **force\_download** (bool, optional): Whether to force download the data.
### train
```python theme={"system"}
def train(self):
```
Get the training set.
### run
```python theme={"system"}
def run(
self,
agent: ChatAgent,
on: Literal['train', 'valid', 'test'],
level: Union[int, List[int], Literal['all']],
randomize: bool = False,
subset: Optional[int] = None
):
```
Run the benchmark.
**Parameters:**
* **agent** (ChatAgent): The agent to run the benchmark.
* **on** (`Literal["valid", "test"]`): The set to run the benchmark.
* **level** (`Union[int, List[int], Literal["all"]]`): The level to run the benchmark.
* **randomize** (bool, optional): Whether to randomize the data. (default: :obj:`False`)
* **subset** (Optional\[int], optional): The subset of data to run. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: The results of the benchmark.
### \_prepare\_task
```python theme={"system"}
def _prepare_task(self, task: Dict[str, Any]):
```
Prepare the task by validating and enriching its data.
### \_create\_user\_message
```python theme={"system"}
def _create_user_message(self, task: Dict[str, Any]):
```
Create a user message from a task.
### \_process\_result
```python theme={"system"}
def _process_result(
self,
agent: ChatAgent,
task: Dict[str, Any],
result: Any,
file_obj: Any
):
```
Process and store the result of a task.
### \_handle\_error
```python theme={"system"}
def _handle_error(
self,
task: Dict[str, Any],
error: Exception,
file_obj: Any
):
```
Handle errors encountered during task processing.
### \_generate\_summary
```python theme={"system"}
def _generate_summary(self):
```
Generate and return a summary of the benchmark results.
### question\_scorer
```python theme={"system"}
def question_scorer(self, model_answer: str, ground_truth: str):
```
Scorer for the GAIA benchmark.
[https://huggingface.co/spaces/gaia-benchmark/leaderboard/blob/main/](https://huggingface.co/spaces/gaia-benchmark/leaderboard/blob/main/)
scorer.py
**Parameters:**
* **model\_answer** (str): The model answer.
* **ground\_truth** (str): The ground truth answer.
**Returns:**
bool: The score of the model
### normalize\_number\_str
```python theme={"system"}
def normalize_number_str(self, number_str: str):
```
### split\_string
```python theme={"system"}
def split_string(self, s: str, char_list: Optional[List[str]] = None):
```
Split a string based on a list of characters.
**Parameters:**
* **s** (str): The string to split.
* **char\_list** (Optional\[List\[str]], optional): T he list of characters to split on. (default: :obj:`None`)
### normalize\_str
```python theme={"system"}
def normalize_str(self, input_str, remove_punct = True):
```
Normalize a string.
**Parameters:**
* **input\_str**: The input string to normalize.
* **remove\_punct**: Whether to remove punctuation.
**Returns:**
str: The normalized string.
### get\_final\_answer
```python theme={"system"}
def get_final_answer(self, content: str):
```
Get the final answer from the content.
**Parameters:**
* **content** (str): The content to extract the final answer from.
**Returns:**
str: The final answer.
# null
Source: https://docs.camel-ai.org/reference/camel.benchmarks.mock_website.app
## setup\_logging
```python theme={"system"}
def setup_logging(application):
```
## check\_task\_completion
```python theme={"system"}
def check_task_completion(current_cart_raw, ground_truth_spec):
```
## home
```python theme={"system"}
def home():
```
## product\_detail
```python theme={"system"}
def product_detail(product_id):
```
## view\_cart
```python theme={"system"}
def view_cart():
```
## get\_products
```python theme={"system"}
def get_products():
```
## get\_cart\_api
```python theme={"system"}
def get_cart_api():
```
## add\_to\_cart\_api
```python theme={"system"}
def add_to_cart_api():
```
## update\_cart\_item\_api
```python theme={"system"}
def update_cart_item_api():
```
## remove\_from\_cart\_api
```python theme={"system"}
def remove_from_cart_api():
```
# null
Source: https://docs.camel-ai.org/reference/camel.benchmarks.mock_website.mock_web
## setup\_dispatcher\_logging
```python theme={"system"}
def setup_dispatcher_logging():
```
## download\_website\_assets
```python theme={"system"}
def download_website_assets(project_name: str):
```
## enqueue\_output
```python theme={"system"}
def enqueue_output(stream, queue):
```
## run\_project
```python theme={"system"}
def run_project(project_name: str, port: int):
```
## main
```python theme={"system"}
def main():
```
# null
Source: https://docs.camel-ai.org/reference/camel.benchmarks.nexus
## NexusSample
```python theme={"system"}
class NexusSample:
```
Nexus benchmark dataset sample.
## NexusBenchmark
```python theme={"system"}
class NexusBenchmark(BaseBenchmark):
```
Nexus Function Calling Benchmark adapted from `NexusRaven V2
Function Calling Benchmark`
`
`.
**Parameters:**
* **data\_dir** (str): The directory to save the data.
* **save\_to** (str): The file to save the results.
* **processes** (int, optional): The number of processes to use. (default: :obj:`1`)
### **init**
```python theme={"system"}
def __init__(
self,
data_dir: str,
save_to: str,
processes: int = 1
):
```
Initialize the Nexus Function Calling benchmark.
**Parameters:**
* **data\_dir** (str): The directory to save the data.
* **save\_to** (str): The file to save the results.
* **processes** (int, optional): The number of processes to use for parallel processing. (default: :obj:`1`)
### download
```python theme={"system"}
def download(self):
```
Download the Nexus Functional Calling Benchmark dataset.
### load
```python theme={"system"}
def load(self, dataset_name: str, force_download: bool = False):
```
Load the Nexus Benchmark dataset.
**Parameters:**
* **dataset\_name** (str): Name of the specific dataset to be loaded.
* **force\_download** (bool): Whether to force download the data.
### train
```python theme={"system"}
def train(self):
```
Get the training set.
### run
```python theme={"system"}
def run(
self,
agent: ChatAgent,
task: Literal['NVDLibrary', 'VirusTotal', 'OTX', 'PlacesAPI', 'ClimateAPI', 'VirusTotal-ParallelCalls', 'VirusTotal-NestedCalls', 'NVDLibrary-NestedCalls'],
randomize: bool = False,
subset: Optional[int] = None
):
```
Run the benchmark.
**Parameters:**
* **agent** (ChatAgent): The agent to run the benchmark. task (Literal\["NVDLibrary", "VirusTotal", "OTX", "PlacesAPI", "ClimateAPI", "VirusTotal-ParallelCalls", "VirusTotal-NestedCalls", "NVDLibrary-NestedCalls"]): The task to run the benchmark.
* **randomize** (bool, optional): Whether to randomize the data. (default: :obj:`False`)
* **subset** (Optional\[int], optional): The subset of data to run. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: The results of the benchmark.
## construct\_tool\_descriptions
```python theme={"system"}
def construct_tool_descriptions(dataset_name: str):
```
Construct tool descriptions from function definitions and
descriptions.
## construct\_prompt
```python theme={"system"}
def construct_prompt(input: str, tools: str):
```
Construct prompt from tools and input.
## parse\_function\_call
```python theme={"system"}
def parse_function_call(call: str):
```
Parse a function call string to extract the function name,
positional arguments, and keyword arguments, including
nested function calls.
**Parameters:**
* **call** (str): A string in the format `func(arg1, arg2, kwarg=value)`.
**Returns:**
tuple: (function\_name (str), positional\_args (list),
keyword\_args (dict)) or (None, None, None).
## compare\_function\_calls
```python theme={"system"}
def compare_function_calls(agent_call: str, ground_truth_call: str):
```
Compare the function name and arguments of
agent\_call and ground\_truth\_call.
**Parameters:**
* **agent\_call** (str): Function call by agent.
* **ground\_truth\_call** (str): Ground truth function call.
**Returns:**
* `True` if the function names and arguments match.
* `False` otherwise.
# null
Source: https://docs.camel-ai.org/reference/camel.benchmarks.ragbench
## RagasFields
```python theme={"system"}
class RagasFields:
```
Constants for RAGAS evaluation field names.
## annotate\_dataset
```python theme={"system"}
def annotate_dataset(
dataset: Dataset,
context_call: Optional[Callable[[Dict[str, Any]], List[str]]],
answer_call: Optional[Callable[[Dict[str, Any]], str]]
):
```
Annotate the dataset by adding context and answers using the provided
functions.
**Parameters:**
* **dataset** (Dataset): The input dataset to annotate.
* **context\_call** (Optional\[Callable\[\[Dict\[str, Any]], List\[str]]]): Function to generate context for each example.
* **answer\_call** (Optional\[Callable\[\[Dict\[str, Any]], str]]): Function to generate answer for each example.
**Returns:**
Dataset: The annotated dataset with added contexts and/or answers.
## rmse
```python theme={"system"}
def rmse(input_trues: Sequence[float], input_preds: Sequence[float]):
```
Calculate Root Mean Squared Error (RMSE).
**Parameters:**
* **input\_trues** (Sequence\[float]): Ground truth values.
* **input\_preds** (Sequence\[float]): Predicted values.
**Returns:**
Optional\[float]: RMSE value, or None if inputs have different lengths.
## auroc
```python theme={"system"}
def auroc(trues: Sequence[bool], preds: Sequence[float]):
```
Calculate Area Under Receiver Operating Characteristic Curve (AUROC).
**Parameters:**
* **trues** (Sequence\[bool]): Ground truth binary values.
* **preds** (Sequence\[float]): Predicted probability values.
**Returns:**
float: AUROC score.
## ragas\_calculate\_metrics
```python theme={"system"}
def ragas_calculate_metrics(
dataset: Dataset,
pred_context_relevance_field: Optional[str],
pred_faithfulness_field: Optional[str],
metrics_to_evaluate: Optional[List[str]] = None,
ground_truth_context_relevance_field: str = 'relevance_score',
ground_truth_faithfulness_field: str = 'adherence_score'
):
```
Calculate RAGAS evaluation metrics.
**Parameters:**
* **dataset** (Dataset): The dataset containing predictions and ground truth.
* **pred\_context\_relevance\_field** (Optional\[str]): Field name for predicted context relevance.
* **pred\_faithfulness\_field** (Optional\[str]): Field name for predicted faithfulness.
* **metrics\_to\_evaluate** (Optional\[List\[str]]): List of metrics to evaluate.
* **ground\_truth\_context\_relevance\_field** (str): Field name for ground truth relevance.
* **ground\_truth\_faithfulness\_field** (str): Field name for ground truth adherence.
**Returns:**
Dict\[str, Optional\[float]]: Dictionary of calculated metrics.
## ragas\_evaluate\_dataset
```python theme={"system"}
def ragas_evaluate_dataset(
dataset: Dataset,
contexts_field_name: Optional[str],
answer_field_name: Optional[str],
metrics_to_evaluate: Optional[List[str]] = None
):
```
Evaluate the dataset using RAGAS metrics.
**Parameters:**
* **dataset** (Dataset): Input dataset to evaluate.
* **contexts\_field\_name** (Optional\[str]): Field name containing contexts.
* **answer\_field\_name** (Optional\[str]): Field name containing answers.
* **metrics\_to\_evaluate** (Optional\[List\[str]]): List of metrics to evaluate.
**Returns:**
Dataset: Dataset with added evaluation metrics.
## RAGBenchBenchmark
```python theme={"system"}
class RAGBenchBenchmark(BaseBenchmark):
```
RAGBench Benchmark for evaluating RAG performance.
This benchmark uses the rungalileo/ragbench dataset to evaluate
retrieval-augmented generation (RAG) systems. It measures context
relevancy and faithfulness metrics as described in
[https://arxiv.org/abs/2407.11005](https://arxiv.org/abs/2407.11005).
**Parameters:**
* **processes** (int, optional): Number of processes for parallel processing.
* **subset** (str, optional): Dataset subset to use (e.g., "hotpotqa").
* **split** (str, optional): Dataset split to use (e.g., "test").
### **init**
```python theme={"system"}
def __init__(
self,
processes: int = 1,
subset: Literal['covidqa', 'cuad', 'delucionqa', 'emanual', 'expertqa', 'finqa', 'hagrid', 'hotpotqa', 'msmarco', 'pubmedqa', 'tatqa', 'techqa'] = 'hotpotqa',
split: Literal['train', 'test', 'validation'] = 'test'
):
```
### download
```python theme={"system"}
def download(self):
```
Download the RAGBench dataset.
### load
```python theme={"system"}
def load(self, force_download: bool = False):
```
Load the RAGBench dataset.
**Parameters:**
* **force\_download** (bool, optional): Whether to force download the data.
### run
```python theme={"system"}
def run(self, agent: ChatAgent, auto_retriever: AutoRetriever):
```
Run the benchmark evaluation.
**Parameters:**
* **agent** (ChatAgent): Chat agent for generating answers.
* **auto\_retriever** (AutoRetriever): Retriever for finding relevant contexts.
**Returns:**
Dict\[str, Optional\[float]]: Dictionary of evaluation metrics.
# null
Source: https://docs.camel-ai.org/reference/camel.bots.discord.discord_app
## DiscordApp
```python theme={"system"}
class DiscordApp:
```
A class representing a Discord app that uses the `discord.py` library
to interact with Discord servers.
This bot can respond to messages in specific channels and only reacts to
messages that mention the bot.
**Parameters:**
* **channel\_ids** (Optional\[List\[int]]): A list of allowed channel IDs. If provided, the bot will only respond to messages in these channels.
* **token** (Optional\[str]): The Discord bot token used for authentication.
### **init**
```python theme={"system"}
def __init__(
self,
channel_ids: Optional[List[int]] = None,
token: Optional[str] = None,
client_id: Optional[str] = None,
client_secret: Optional[str] = None,
redirect_uri: Optional[str] = None,
installation_store: Optional[DiscordBaseInstallationStore] = None,
intents: Optional[discord.Intents] = None
):
```
Initialize the DiscordApp instance by setting up the Discord client
and event handlers.
**Parameters:**
* **channel\_ids** (Optional\[List\[int]]): A list of allowed channel IDs. The bot will only respond to messages in these channels if provided. (default: :obj:`None`)
* **token** (Optional\[str]): The Discord bot token for authentication. If not provided, the token will be retrieved from the environment variable `DISCORD_TOKEN`. (default: :obj:`None`)
* **client\_id** (str, optional): The client ID for Discord OAuth. (default: :obj:`None`)
* **client\_secret** (Optional\[str]): The client secret for Discord OAuth. (default: :obj:`None`)
* **redirect\_uri** (str): The redirect URI for OAuth callbacks. (default: :obj:`None`)
* **installation\_store** (DiscordAsyncInstallationStore): The database stores all information of all installations. (default: :obj:`None`)
* **intents** (discord.Intents): The Discord intents of this app. (default: :obj:`None`)
### run
```python theme={"system"}
def run(self):
```
Start the Discord bot using its token.
This method starts the bot and logs into Discord synchronously using
the provided token. It blocks execution and keeps the bot running.
### client
```python theme={"system"}
def client(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.bots.discord.discord_installation
## DiscordInstallation
```python theme={"system"}
class DiscordInstallation:
```
Represents an installation of a Discord application in a
specific guild (server).
**Parameters:**
* **guild\_id** (str): The unique identifier for the Discord guild (server) where the application is installed.
* **access\_token** (str): The access token used to authenticate API requests for the installed application.
* **refresh\_token** (str): The token used to refresh the access token when it expires.
* **installed\_at** (datetime): The timestamp indicating when the application was installed in the guild.
* **token\_expires\_at** (Optional\[datetime]): The optional timestamp indicating when the access token will expire. Defaults to None if the token does not have an expiration time.
### **init**
```python theme={"system"}
def __init__(
self,
guild_id: str,
access_token: str,
refresh_token: str,
installed_at: datetime,
token_expires_at: Optional[datetime] = None
):
```
Initialize the DiscordInstallation.
**Parameters:**
* **guild\_id** (str): The unique identifier for the Discord guild (server) where the application is installed.
* **access\_token** (str): The access token used to authenticate API requests for the installed application.
* **refresh\_token** (str): The token used to refresh the access token when it expires.
* **installed\_at** (datetime): The timestamp indicating when the application was installed in the guild.
* **token\_expires\_at** (Optional\[datetime]): The optional timestamp indicating when the access token will expire. Defaults to None if the token does not have an expiration time. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.bots.discord.discord_store
## DiscordBaseInstallationStore
```python theme={"system"}
class DiscordBaseInstallationStore:
```
Abstract base class for managing Discord installations.
This class defines the interface for database operations related to storing
and retrieving Discord installation data. Subclasses must implement these
methods to handle database-specific logic.
## DiscordSQLiteInstallationStore
```python theme={"system"}
class DiscordSQLiteInstallationStore(DiscordBaseInstallationStore):
```
SQLite-based implementation for managing Discord installations.
This class provides methods for initializing the database, saving,
retrieving, and deleting installation records using SQLite.
**Parameters:**
* **database** (str): Path to the SQLite database file.
### **init**
```python theme={"system"}
def __init__(self, database: str):
```
Initializes the SQLite installation store.
**Parameters:**
* **database** (str): Path to the SQLite database file.
# null
Source: https://docs.camel-ai.org/reference/camel.bots.slack.models
## SlackAuthProfile
```python theme={"system"}
class SlackAuthProfile(BaseModel):
```
Represents the authorization profile within a Slack event.
Events will contain a single, compact authorizations field that shows one
installation of your app that the event is visible to.
In other words, lists of authorizations will be truncated to one element.
If there's more than one installing party that your app is keeping track
of, it's best not to rely on the single party listed in authorizations to
be any particular one.
To get a full list of who can see events, call the apps.event.
authorizations.list method after obtaining an app-level token. Read more on
the changes here; they have taken effect for existing apps as of
February 24, 2021.
References:
* [https://api.slack.com/apis/events-api#authorizations](https://api.slack.com/apis/events-api#authorizations)
* [https://api.slack.com/changelog/2020-09-15-events-api-truncate-authed-users#no\_context](https://api.slack.com/changelog/2020-09-15-events-api-truncate-authed-users#no_context)
## SlackEventProfile
```python theme={"system"}
class SlackEventProfile(BaseModel):
```
Represents the detailed profile of a Slack event, including user,
message, and context data.
## SlackEventBody
```python theme={"system"}
class SlackEventBody(BaseModel):
```
Represents the entire body of a Slack event, including the event
profile, authorization, and context.
## SlackAppMentionEventProfile
```python theme={"system"}
class SlackAppMentionEventProfile(SlackEventProfile):
```
Represents the detailed profile of a Slack event where the app was
mentioned in a message.
## SlackAppMentionEventBody
```python theme={"system"}
class SlackAppMentionEventBody(SlackEventBody):
```
Represents the entire body of a Slack event where the app was mentioned
in a message.
# null
Source: https://docs.camel-ai.org/reference/camel.bots.slack.slack_app
## SlackApp
```python theme={"system"}
class SlackApp:
```
Represents a Slack app that is powered by a Slack Bolt `AsyncApp`.
This class is responsible for initializing and managing the Slack
application by setting up event handlers, running the app server, and
handling events such as messages and mentions from Slack.
**Parameters:**
* **token** (Optional\[str]): Slack API token for authentication.
* **scopes** (Optional\[str]): Slack app scopes for permissions.
* **signing\_secret** (Optional\[str]): Signing secret for verifying Slack requests.
* **client\_id** (Optional\[str]): Slack app client ID.
* **client\_secret** (Optional\[str]): Slack app client secret.
* **redirect\_uri\_path** (str): The URI path for OAuth redirect, defaults to "/slack/oauth\_redirect".
* **installation\_store** (Optional\[AsyncInstallationStore]): The installation store for handling OAuth installations.
### **init**
```python theme={"system"}
def __init__(
self,
token: Optional[str] = None,
scopes: Optional[str] = None,
signing_secret: Optional[str] = None,
client_id: Optional[str] = None,
client_secret: Optional[str] = None,
redirect_uri_path: str = '/slack/oauth_redirect',
installation_store: Optional[AsyncInstallationStore] = None
):
```
Initializes the SlackApp instance by setting up the Slack Bolt app
and configuring event handlers and OAuth settings.
**Parameters:**
* **token** (Optional\[str]): The Slack API token.
* **scopes** (Optional\[str]): The scopes for Slack app permissions.
* **signing\_secret** (Optional\[str]): The signing secret for verifying requests.
* **client\_id** (Optional\[str]): The Slack app client ID.
* **client\_secret** (Optional\[str]): The Slack app client secret.
* **redirect\_uri\_path** (str): The URI path for handling OAuth redirects (default is "/slack/oauth\_redirect").
* **installation\_store** (Optional\[AsyncInstallationStore]): An optional installation store for OAuth installations.
### setup\_handlers
```python theme={"system"}
def setup_handlers(self):
```
Sets up the event handlers for Slack events, such as `app_mention`
and `message`.
This method registers the `app_mention` and `on_message` event handlers
with the Slack Bolt app to respond to Slack events.
### run
```python theme={"system"}
def run(
self,
port: int = 3000,
path: str = '/slack/events',
host: Optional[str] = None
):
```
Starts the Slack Bolt app server to listen for incoming Slack
events.
**Parameters:**
* **port** (int): The port on which the server should run (default is 3000).
* **path** (str): The endpoint path for receiving Slack events (default is "/slack/events").
* **host** (Optional\[str]): The hostname to bind the server (default is None).
### mention\_me
```python theme={"system"}
def mention_me(self, context: 'AsyncBoltContext', body: SlackEventBody):
```
Check if the bot is mentioned in the message.
**Parameters:**
* **context** (AsyncBoltContext): The Slack Bolt context for the event.
* **body** (SlackEventBody): The body of the Slack event.
**Returns:**
bool: True if the bot is mentioned in the message, False otherwise.
# null
Source: https://docs.camel-ai.org/reference/camel.bots.telegram_bot
## TelegramBot
```python theme={"system"}
class TelegramBot:
```
Represents a Telegram bot that is powered by an agent.
**Parameters:**
* **chat\_agent** (ChatAgent): Chat agent that will power the bot.
* **telegram\_token** (str, optional): The bot token.
### **init**
```python theme={"system"}
def __init__(
self,
chat_agent: ChatAgent,
telegram_token: Optional[str] = None
):
```
### run
```python theme={"system"}
def run(self):
```
Start the Telegram bot.
### on\_message
```python theme={"system"}
def on_message(self, message: 'Message'):
```
Handles incoming messages from the user.
**Parameters:**
* **message** (types.Message): The incoming message object.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.aihubmix_config
## AihubMixConfig
```python theme={"system"}
class AihubMixConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
AihubMix API.
**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:`0.8`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`1024`)
* **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:`1`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. (default: :obj:`0`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. (default: :obj:`0`)
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`False`)
* **web\_search\_options** (dict, optional): Search model's web search options, only supported by specific search models. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
* **parallel\_tool\_calls** (bool, optional): A parameter specifying whether the model should call tools in parallel or not. (default: :obj:`None`)
* **extra\_headers**: Optional\[Dict\[str, str]]: Extra headers to use for the model. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.aiml_config
## AIMLConfig
```python theme={"system"}
class AIMLConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
AIML API.
**Parameters:**
* **temperature** (float, optional): Determines the degree of randomness in the response. (default: :obj:`None`)
* **top\_p** (float, optional): The top\_p (nucleus) parameter is used to dynamically adjust the number of choices for each predicted token based on the cumulative probabilities. (default: :obj:`None`)
* **n** (int, optional): Number of generations to return. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output.
* **stream** (bool, optional): If set, tokens are returned as Server-Sent Events as they are made available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.amd_config
## AMDConfig
```python theme={"system"}
class AMDConfig(BaseConfig):
```
Configuration class for AMD API models.
This class defines the configuration parameters for AMD's language
models, including temperature, sampling parameters, and response format
settings.
**Parameters:**
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`None`)
* **temperature** (float, optional): Controls randomness in the response. Higher values make output more random, lower values make it more deterministic. Range: \[0.0, 2.0]. (default: :obj:`None`)
* **top\_p** (float, optional): Controls diversity via nucleus sampling.
* **Range**: \[0.0, 1.0]. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Penalizes new tokens based on whether they appear in the text so far. Range: \[-2.0, 2.0]. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Penalizes new tokens based on their frequency in the text so far. Range: \[-2.0, 2.0]. (default: :obj:`None`)
* **max\_tokens** (Union\[int, NotGiven], optional): Maximum number of tokens to generate. If not provided, model will use its default maximum. (default: :obj:`None`)
* **seed** (Optional\[int], optional): Random seed for deterministic sampling. (default: :obj:`None`)
* **tools** (Optional\[List\[Dict]], optional): List of tools available to the model. This includes tools such as a text editor, a calculator, or a search engine. (default: :obj:`None`)
* **tool\_choice** (Optional\[str], optional): Tool choice configuration. (default: :obj:`None`)
* **stop** (Optional\[List\[str]], optional): List of stop sequences. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.anthropic_config
## AnthropicConfig
```python theme={"system"}
class AnthropicConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Anthropic API.
See: [https://docs.anthropic.com/en/api/messages](https://docs.anthropic.com/en/api/messages)
**Parameters:**
* **max\_tokens** (int, optional): The maximum number of tokens to generate before stopping. Note that Anthropic models may stop before reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. (default: :obj:`None`)
* **stop\_sequences** (List\[str], optional): Custom text sequences that will cause the model to stop generating. The models will normally stop when they have naturally completed their turn. If the model encounters one of these custom sequences, the response will be terminated and the stop\_reason will be "stop\_sequence". (default: :obj:`None`)
* **temperature** (float, optional): Amount of randomness injected into the response. Defaults to 1. Ranges from 0 to 1. Use temp closer to 0 for analytical / multiple choice, and closer to 1 for creative and generative tasks. Note that even with temperature of 0.0, the results will not be fully deterministic. (default: :obj:`None`)
* **top\_p** (float, optional): Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. You should either alter `temperature` or `top_p`, but not both. (default: :obj:`None`)
* **top\_k** (int, optional): Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. (default: :obj:`None`)
* **stream** (bool, optional): Whether to incrementally stream the response using server-sent events. (default: :obj:`None`)
* **metadata** (dict, optional): An object describing metadata about the request. Can include user\_id as an external identifier for the user associated with the request. (default: :obj:`None`)
* **tool\_choice** (dict, optional): How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. (default: :obj:`None`)
* **cache\_control** (`Optional[Literal["5m", "1h"]], optional`): The cache control TTL for prompt caching. Use '5m' for 5-minute cache or '1h' for 1-hour cache. (default: :obj:`None`)
* **extra\_headers** (Optional\[dict], optional): Additional headers for the request. (default: :obj:`None`)
* **extra\_body** (dict, optional): Extra body parameters to be passed to the Anthropic API.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.atlascloud_config
## AtlasCloudConfig
```python theme={"system"}
class AtlasCloudConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
Reference: [https://www.atlascloud.ai/docs/en/createChatCompletion](https://www.atlascloud.ai/docs/en/createChatCompletion)
**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`)
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **repetition\_penalty** (float, optional): Penalty for repeated tokens to prevent redundancy. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.base_config
## BaseConfig
```python theme={"system"}
class BaseConfig(ABC, BaseModel):
```
Base configuration class for all models.
This class provides a common interface for all models, ensuring that all
models have a consistent set of attributes and methods.
### fields\_type\_checking
```python theme={"system"}
def fields_type_checking(cls, tools):
```
Validate the type of tools in the configuration.
This method ensures that the tools provided in the configuration are
instances of `FunctionTool`. If any tool is not an instance of
`FunctionTool`, it raises a ValueError.
### as\_dict
```python theme={"system"}
def as_dict(self):
```
**Returns:**
dict\[str, Any]: A dictionary representation of the current
configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.bedrock_config
## BedrockConfig
```python theme={"system"}
class BedrockConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
**Parameters:**
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **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`)
* **top\_k** (int, optional): The number of top tokens to consider.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
* **reasoning\_effort** (str, optional): A parameter specifying the level of reasoning used by certain model types. Valid values are :obj: `"low"`, :obj:`"medium"`, or :obj:`"high"`. If set, it is only applied to the model types that support it (e.g., :obj:`o1`, :obj:`o1mini`, :obj:`o1preview`, :obj:`o3mini`). If not provided or if the model type does not support it, this parameter is ignored. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.cerebras_config
## CerebrasConfig
```python theme={"system"}
class CerebrasConfig(BaseConfig):
```
Defines the parameters for generating chat completions using Cerebras
compatibility.
Reference: [https://inference-docs.cerebras.ai/resources/openai](https://inference-docs.cerebras.ai/resources/openai)
**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`)
* **response\_format** (object, optional): An object specifying the format that the model must output.Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. (default: :obj:`None`)
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
* **reasoning\_effort** (str, optional): A parameter specifying the level of reasoning used by certain model types. Valid values are :obj: `"low"`, :obj:`"medium"`, or :obj:`"high"`. If set, it is only applied to the model types that support it (e.g., :obj:`o1`, :obj:`o1mini`, :obj:`o1preview`, :obj:`o3mini`). If not provided or if the model type does not support it, this parameter is ignored. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.cohere_config
## CohereConfig
```python theme={"system"}
class CohereConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Cohere API.
**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`)
* **documents** (list, optional): A list of relevant documents that the model can cite to generate a more accurate reply. Each document is either a string or document object with content and metadata. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens the model will generate as part of the response. (default: :obj:`None`) stop\_sequences (List(str), optional): A list of up to 5 strings that the model will use to stop generation. If the model generates a string that matches any of the strings in the list, it will stop generating tokens and return the generated text up to that point not including the stop sequence. (default: :obj:`None`)
* **seed** (int, optional): If specified, the backend will make a best effort to sample tokens deterministically, such that repeated requests with the same seed and parameters should return the same result. However, determinism cannot be totally guaranteed. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Min value of `0.0`, max value of `1.0`. Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Min value of `0.0`, max value of `1.0`. Used to reduce repetitiveness of generated tokens. Similar to `frequency_penalty`, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies. (default: :obj:`None`)
* **k** (int, optional): Ensures only the top k most likely tokens are considered for generation at each step. Min value of `0`, max value of `500`. (default: :obj:`None`)
* **p** (float, optional): Ensures that only the most likely tokens, with total probability mass of `p`, are considered for generation at each step. If both k and p are enabled, `p` acts after `k`. Min value of `0.01`, max value of `0.99`. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.cometapi_config
## CometAPIConfig
```python theme={"system"}
class CometAPIConfig(BaseConfig):
```
Defines the parameters for generating chat completions using CometAPI's
OpenAI-compatible interface.
Reference: [https://api.cometapi.com/v1/](https://api.cometapi.com/v1/)
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help CometAPI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.crynux_config
## CrynuxConfig
```python theme={"system"}
class CrynuxConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.deepseek_config
## DeepSeekConfig
```python theme={"system"}
class DeepSeekConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
DeepSeek API.
**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): Controls the diversity and focus of the generated results. Higher values make the output more diverse, while lower values make it more focused. (default: :obj:`None`)
* **response\_format** (object, optional): Specifies the format of the returned content. The available values are `{"type": "text"}` or `{"type": "json_object"}`. Setting it to `{"type": "json_object"}` will output a standard JSON string. (default: :obj:`None`)
* **stream** (bool, optional): If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events (SSE) as they become available, with the stream terminated by a
* **data**: \[DONE] message. (default: :obj:`None`)
* **stop** (Union\[str, list\[str]], optional): Up to 16 sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens that can be generated in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. (default: :obj:`None`)
* **tool\_choice** (Union\[dict\[str, str], str], optional): Controls which (if any) tool is called by the model. "none" means the model will not call any tool and instead generates a message. "auto" means the model can pick between generating a message or calling one or more tools. "required" means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. "none" is the default when no tools are present. "auto" is the default if tools are present. (default: :obj:`None`)
* **logprobs** (bool, optional): Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message. (default: :obj:`None`)
* **top\_logprobs** (int, optional): An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used. (default: :obj:`None`)
* **include\_usage** (bool, optional): When streaming, specifies whether to include usage information in `stream_options`. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, include_usage: bool = True, **kwargs):
```
# null
Source: https://docs.camel-ai.org/reference/camel.configs.function_gemma_config
## FunctionGemmaConfig
```python theme={"system"}
class FunctionGemmaConfig(BaseConfig):
```
Defines the parameters for generating completions using FunctionGemma
via Ollama's native API.
FunctionGemma uses a custom chat template format for function calling
that differs from OpenAI's format. This config is used with Ollama's
/api/generate endpoint.
Reference: [https://github.com/ollama/ollama/blob/main/docs/api.md](https://github.com/ollama/ollama/blob/main/docs/api.md)
**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. (default: :obj:`0.95`)
* **top\_k** (int, optional): Limits the next token selection to the K most probable tokens. (default: :obj:`64`)
* **num\_predict** (int, optional): Maximum number of tokens to generate. (default: :obj:`None`)
* **stop** (list, optional): Sequences where the model will stop generating further tokens. (default: :obj:`None`)
* **seed** (int, optional): Random seed for reproducibility. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.gemini_config
## GeminiConfig
```python theme={"system"}
class GeminiConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Gemini API.
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.groq_config
## GroqConfig
```python theme={"system"}
class GroqConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
Reference: [https://console.groq.com/docs/openai](https://console.groq.com/docs/openai)
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.internlm_config
## InternLMConfig
```python theme={"system"}
class InternLMConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
InternLM API. You can refer to the following link for more details:
[https://internlm.intern-ai.org.cn/api/document](https://internlm.intern-ai.org.cn/api/document)
**Parameters:**
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`None`)
* **temperature** (float, optional): Controls the diversity and focus of the generated results. Lower values make the output more focused, while higher values make it more diverse. (default: :obj:`None`)
* **top\_p** (float, optional): Controls the diversity and focus of the generated results. Higher values make the output more diverse, while lower values make it more focused. (default: :obj:`None`)
* **max\_tokens** (int, optional): Allows the model to generate the maximum number of tokens. (default: :obj:`None`)
* **tools** (list, optional): Specifies an array of tools that the model can call. It can contain one or more tool objects. During a function call process, the model will select one tool from the array. (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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.litellm_config
## LiteLLMConfig
```python theme={"system"}
class LiteLLMConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
LiteLLM API.
**Parameters:**
* **timeout** (Optional\[Union\[float, str]], optional): Request timeout. (default: :obj:`None`)
* **temperature** (Optional\[float], optional): Temperature parameter for controlling randomness. (default: :obj:`None`)
* **top\_p** (Optional\[float], optional): Top-p parameter for nucleus sampling. (default: :obj:`None`)
* **n** (Optional\[int], optional): Number of completions to generate. (default: :obj:`None`)
* **stream** (Optional\[bool], optional): Whether to return a streaming response. (default: :obj:`None`)
* **stream\_options** (Optional\[dict], optional): Options for the streaming response. (default: :obj:`None`)
* **stop** (Optional\[Union\[str, List\[str]]], optional): Sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (Optional\[int], optional): Maximum number of tokens to generate. (default: :obj:`None`)
* **presence\_penalty** (Optional\[float], optional): Penalize new tokens based on their existence in the text so far. (default: :obj:`None`)
* **frequency\_penalty** (Optional\[float], optional): Penalize new tokens based on their frequency in the text so far. (default: :obj:`None`)
* **logit\_bias** (Optional\[dict], optional): Modify the probability of specific tokens appearing in the completion. (default: :obj:`None`)
* **user** (Optional\[str], optional): A unique identifier representing the end-user. (default: :obj:`None`)
* **response\_format** (Optional\[dict], optional): Response format parameters. (default: :obj:`None`)
* **seed** (Optional\[int], optional): Random seed. (default: :obj:`None`)
* **tools** (Optional\[List], optional): List of tools. (default: :obj:`None`)
* **tool\_choice** (Optional\[Union\[str, dict]], optional): Tool choice parameters. (default: :obj:`None`)
* **logprobs** (Optional\[bool], optional): Whether to return log probabilities of the output tokens. (default: :obj:`None`)
* **top\_logprobs** (Optional\[int], optional): Number of most likely tokens to return at each token position. (default: :obj:`None`)
* **deployment\_id** (Optional\[str], optional): Deployment ID. (default: :obj:`None`)
* **extra\_headers** (Optional\[dict], optional): Additional headers for the request. (default: :obj:`None`)
* **api\_version** (Optional\[str], optional): API version. (default: :obj:`None`)
* **mock\_response** (Optional\[str], optional): Mock completion response for testing or debugging. (default: :obj:`None`)
* **custom\_llm\_provider** (Optional\[str], optional): Non-OpenAI LLM provider. (default: :obj:`None`)
* **max\_retries** (Optional\[int], optional): Maximum number of retries. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.lmstudio_config
## LMStudioConfig
```python theme={"system"}
class LMStudioConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
**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`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.minimax_config
## MinimaxConfig
```python theme={"system"}
class MinimaxConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility with Minimax.
Reference: [https://api.minimax.chat/document/guides/chat-model](https://api.minimax.chat/document/guides/chat-model)
**Parameters:**
* **temperature** (float, optional): Sampling temperature to use, between :obj:`0.0` and :obj:`1.0`. Higher values make the output more random, while lower values make it more focused and deterministic. Recommended to use :obj:`1.0`. Values outside this range will return an error. (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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. Only supports value :obj:`1`. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length. (default: :obj:`None`)
* **stream** (bool, optional): If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a data: \[DONE] message. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help to monitor and detect abuse. (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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
**Note:**
Some OpenAI parameters such as presence\_penalty, frequency\_penalty,
and logit\_bias will be ignored by Minimax.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.mistral_config
## MistralConfig
```python theme={"system"}
class MistralConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Mistral API.
reference: [https://github.com/mistralai/client-python/blob/9d238f88c41689821d7b08570f13b43426f97fd6/src/mistralai/client.py#L195](https://github.com/mistralai/client-python/blob/9d238f88c41689821d7b08570f13b43426f97fd6/src/mistralai/client.py#L195)
\#TODO: Support stream mode
**Parameters:**
* **temperature** (Optional\[float], optional): temperature the temperature to use for sampling, e.g. 0.5. (default: :obj:`None`)
* **top\_p** (Optional\[float], optional): the cumulative probability of tokens to generate, e.g. 0.9. (default: :obj:`None`)
* **max\_tokens** (Optional\[int], optional): the maximum number of tokens to generate, e.g. 100. (default: :obj:`None`)
* **stop** (Optional\[Union\[str,list\[str]]]): Stop generation if this token is detected. Or if one of these tokens is detected when providing a string list. (default: :obj:`None`)
* **random\_seed** (Optional\[int], optional): the random seed to use for sampling, e.g. 42. (default: :obj:`None`)
* **safe\_prompt** (bool, optional): whether to use safe prompt, e.g. true. (default: :obj:`None`)
* **response\_format** (Union\[Dict\[str, str], ResponseFormat): format of the response.
* **tool\_choice** (str, optional): Controls which (if any) tool is called by the model. :obj:`"none"` means the model will not call any tool and instead generates a message. :obj:`"auto"` means the model can pick between generating a message or calling one or more tools. :obj:`"any"` means the model must call one or more tools. :obj:`"auto"` is the default value.
### fields\_type\_checking
```python theme={"system"}
def fields_type_checking(cls, response_format):
```
# null
Source: https://docs.camel-ai.org/reference/camel.configs.modelscope_config
## ModelScopeConfig
```python theme={"system"}
class ModelScopeConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
ModelScope API. You can refer to the following link for more details:
[https://www.modelscope.cn/docs/model-service/API-Inference/intro](https://www.modelscope.cn/docs/model-service/API-Inference/intro)
**Parameters:**
* **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 and instead generates a message. :obj:`"auto"` means the model can pick between generating a message or calling one or more tools. :obj:`"required"` or specifying a particular tool via `{"type": "function", "function": {"name": "some_function"}}` can be used to guide the model to use tools more strongly. (default: :obj:`None`)
* **max\_tokens** (int, optional): Specifies the maximum number of tokens the model can generate. This sets an upper limit, but does not guarantee that this number will always be reached. (default: :obj:`None`)
* **top\_p** (float, optional): Controls the randomness of the generated results. Lower values lead to less randomness, while higher values increase randomness. (default: :obj:`None`)
* **temperature** (float, optional): Controls the diversity and focus of the generated results. Lower values make the output more focused, while higher values make it more diverse. (default: :obj:`0.3`)
* **stream** (bool, optional): If True, enables streaming output. (default: :obj:`None`)
* **extra\_body** (dict, optional): Extra body parameters to be passed to the ModelScope API.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.moonshot_config
## MoonshotConfig
```python theme={"system"}
class MoonshotConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Moonshot API. You can refer to the following link for more details:
[https://platform.moonshot.cn/docs/api-reference](https://platform.moonshot.cn/docs/api-reference)
**Parameters:**
* **temperature** (float, optional): Controls randomness in the response. Lower values make the output more focused and deterministic. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate. (default: :obj:`None`)
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`False`)
* **tools** (list, optional): List of tools that the model can use for function calling. Each tool should be a dictionary containing type, function name, description, and parameters. (default: :obj:`None`)
* **top\_p** (float, optional): Controls diversity via nucleus sampling. (default: :obj:`None`)
* **n** (int, optional): How many chat completion choices to generate for each input message.(default: :obj:`None`)
* **presence\_penalty** (float, optional): Penalty for new tokens based on whether they appear in the text so far. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Penalty for new tokens based on their frequency in the text so far. (default: :obj:`None`)
* **stop** (Optional\[Union\[str, List\[str]]], optional): Up to 4 sequences where the API will stop generating further tokens. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.nebius_config
## NebiusConfig
```python theme={"system"}
class NebiusConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility with Nebius AI Studio.
Reference: [https://nebius.com/docs/ai-studio/api](https://nebius.com/docs/ai-studio/api)
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.netmind_config
## NetmindConfig
```python theme={"system"}
class NetmindConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
Reference: [https://netmind-power.gitbook.io/netmind-power-documentation/](https://netmind-power.gitbook.io/netmind-power-documentation/)
api/inference/chat
**Parameters:**
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **repetition\_penalty** (float, optional): Penalizes new tokens based on their appearance in the prompt and generated text. (default: :obj:`None`)
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`None`)
* **temperature** (float, optional): Controls randomness in the response. Higher values make output more random, lower values make it more deterministic. Range: \[0.0, 2.0]. (default: :obj:`None`)
* **top\_p** (float, optional): Controls diversity via nucleus sampling.
* **Range**: \[0.0, 1.0]. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **max\_tokens** (Union\[int, NotGiven], optional): Maximum number of tokens to generate. If not provided, model will use its default maximum. (default: :obj:`None`)
* **stop** (Optional\[List\[str]], optional): List of stop sequences. (default: :obj:`None`)
* **n** (Optional\[int], optional): Number of chat completion choices to generate for each input message. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.novita_config
## NovitaConfig
```python theme={"system"}
class NovitaConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.nvidia_config
## NvidiaConfig
```python theme={"system"}
class NvidiaConfig(BaseConfig):
```
Configuration class for NVIDIA API models.
This class defines the configuration parameters for NVIDIA's language
models, including temperature, sampling parameters, and response format
settings.
**Parameters:**
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`None`)
* **temperature** (float, optional): Controls randomness in the response. Higher values make output more random, lower values make it more deterministic. Range: \[0.0, 2.0]. (default: :obj:`None`)
* **top\_p** (float, optional): Controls diversity via nucleus sampling.
* **Range**: \[0.0, 1.0]. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Penalizes new tokens based on whether they appear in the text so far. Range: \[-2.0, 2.0]. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Penalizes new tokens based on their frequency in the text so far. Range: \[-2.0, 2.0]. (default: :obj:`None`)
* **max\_tokens** (Union\[int, NotGiven], optional): Maximum number of tokens to generate. If not provided, model will use its default maximum. (default: :obj:`None`)
* **seed** (Optional\[int], optional): Random seed for deterministic sampling. (default: :obj:`None`)
* **tools** (Optional\[List\[Dict]], optional): List of tools available to the model. This includes tools such as a text editor, a calculator, or a search engine. (default: :obj:`None`)
* **tool\_choice** (Optional\[str], optional): Tool choice configuration. (default: :obj:`None`)
* **stop** (Optional\[List\[str]], optional): List of stop sequences. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.ollama_config
## OllamaConfig
```python theme={"system"}
class OllamaConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility
Reference: [https://github.com/ollama/ollama/blob/main/docs/openai.md](https://github.com/ollama/ollama/blob/main/docs/openai.md)
**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`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.openai_config
## ChatGPTConfig
```python theme={"system"}
class ChatGPTConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
* **reasoning\_effort** (str, optional): A parameter specifying the level of reasoning used by certain model types. Valid values are :obj: `"low"`, :obj:`"medium"`, or :obj:`"high"`. If set, it is only applied to the model types that support it (e.g., :obj:`o1`, :obj:`o1mini`, :obj:`o1preview`, :obj:`o3mini`). If not provided or if the model type does not support it, this parameter is ignored. (default: :obj:`None`)
* **parallel\_tool\_calls** (bool, optional): A parameter specifying whether the model should call tools in parallel or not. (default: :obj:`None`)
* **prompt\_cache\_key** (str, optional): A key used by the OpenAI Prompt Caching system to identify and reuse cached prompt segments. (default: :obj:`None`)
* **extra\_headers**: Optional\[Dict\[str, str]]: Extra headers to use for the model. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.openrouter_config
## OpenRouterConfig
```python theme={"system"}
class OpenRouterConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
Reference: [https://openrouter.ai/docs/api-reference/parameters](https://openrouter.ai/docs/api-reference/parameters)
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. (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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.ppio_config
## PPIOConfig
```python theme={"system"}
class PPIOConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.qianfan_config
## QianfanConfig
```python theme={"system"}
class QianfanConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility.
Reference: [https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb)
**Parameters:**
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **repetition\_penalty** (float, optional): Penalizes new tokens based on their appearance in the prompt and generated text. (default: :obj:`None`)
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`None`)
* **temperature** (float, optional): Controls randomness in the response. Higher values make output more random, lower values make it more deterministic. Range: \[0.0, 2.0]. (default: :obj:`None`)
* **top\_p** (float, optional): Controls diversity via nucleus sampling.
* **Range**: \[0.0, 1.0]. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **max\_tokens** (Union\[int, NotGiven], optional): Maximum number of tokens to generate. If not provided, model will use its default maximum. (default: :obj:`None`)
* **stop** (Optional\[List\[str]], optional): List of stop sequences. (default: :obj:`None`)
* **n** (Optional\[int], optional): Number of chat completion choices to generate for each input message. (default: :obj:`None`)
* **tools** (List, optional): Specifies an array of tools that the model can call. It can contain one or more tool objects. During a function call process, the model will select one tool from the array. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.qwen_config
## QwenConfig
```python theme={"system"}
class QwenConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Qwen API. You can refer to the following link for more details:
[https://help.aliyun.com/zh/model-studio/developer-reference/use-qwen-by-calling-api](https://help.aliyun.com/zh/model-studio/developer-reference/use-qwen-by-calling-api)
**Parameters:**
* **stream** (bool, optional): Whether to stream the response. (default: :obj:`None`)
* **temperature** (float, optional): Controls the diversity and focus of the generated results. Lower values make the output more focused, while higher values make it more diverse. (default: :obj:`None`)
* **top\_p** (float, optional): Controls the diversity and focus of the generated results. Higher values make the output more diverse, while lower values make it more focused. (default: :obj:`0.9`)
* **presence\_penalty** (float, optional): Controls the repetition content in the generated results. Positive values reduce the repetition of content, while negative values increase it. (default: :obj:`None`)
* **response\_format** (Optional\[Dict\[str, str]], optional): Specifies the format of the returned content. The available values are `{"type": "text"}` or `{"type": "json_object"}`. Setting it to `{"type": "json_object"}` will output a standard JSON string. (default: :obj:`None`)
* **max\_tokens** (Optional\[int], optional): Allows the model to generate the maximum number of tokens. (default: :obj:`None`)
* **seed** (Optional\[int], optional): Sets the seed parameter to make the text generation process more deterministic, typically used to ensure that the results are consistent across model runs. By passing the same seed value (specified by you) in each model call while keeping other parameters unchanged, the model is likely to return the same result. (default: :obj:`None`)
* **stop** (Optional\[Union\[str, List]], optional): Using the stop parameter, the model will automatically stop generating text when it is about to include the specified string or token\_id. You can use the stop parameter to control the output of the model by passing sensitive words. (default: :obj:`None`)
* **tools** (List, optional): Specifies an array of tools that the model can call. It can contain one or more tool objects. During a function call process, the model will select one tool from the array. (default: :obj:`None`)
* **extra\_body** (Optional\[Dict\[str, Any]], optional): Additional parameters to be sent to the Qwen API. If you want to enable internet search, you can set this parameter to `{"enable_search": True}`. (default: :obj:`None`)
* **include\_usage** (bool, optional): When streaming, specifies whether to include usage information in `stream_options`. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.reka_config
## RekaConfig
```python theme={"system"}
class RekaConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Reka API.
Reference: [https://docs.reka.ai/api-reference/chat/create](https://docs.reka.ai/api-reference/chat/create)
**Parameters:**
* **temperature** (Optional\[float], optional): temperature the temperature to use for sampling, e.g. 0.5. (default: :obj:`None`)
* **top\_p** (Optional\[float], optional): the cumulative probability of tokens to generate, e.g. 0.9. (default: :obj:`None`)
* **top\_k** (Optional\[int], optional): Parameter which forces the model to only consider the tokens with the `top_k` highest probabilities at the next step. (default: :obj:`None`)
* **max\_tokens** (Optional\[int], optional): the maximum number of tokens to generate, e.g. 100. (default: :obj:`None`)
* **stop** (Optional\[Union\[str,list\[str]]]): Stop generation if this token is detected. Or if one of these tokens is detected when providing a string list. (default: :obj:`None`)
* **seed** (Optional\[int], optional): the random seed to use for sampling, e. g. 42. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **use\_search\_engine** (Optional\[bool]): Whether to consider using search engine to complete the request. Note that even if this is set to `True`, the model might decide to not use search. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.samba_config
## SambaVerseAPIConfig
```python theme={"system"}
class SambaVerseAPIConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
SambaVerse API.
**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`)
* **top\_k** (int, optional): Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. (default: :obj:`None`)
* **max\_tokens** (Optional\[int], optional): The maximum number of tokens to generate, e.g. 100. (default: :obj:`None`)
* **repetition\_penalty** (Optional\[float], optional): The parameter for repetition penalty. 1.0 means no penalty. (default: :obj:`None`)
* **stop** (Optional\[Union\[str,list\[str]]]): Stop generation if this token is detected. Or if one of these tokens is detected when providing a string list. (default: :obj:`None`)
* **stream** (Optional\[bool]): If True, partial message deltas will be sent as data-only server-sent events as they become available. Currently SambaVerse API doesn't support stream mode. (default: :obj:`None`)
## SambaCloudAPIConfig
```python theme={"system"}
class SambaCloudAPIConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
**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:`0.2`)
* **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:`1.0`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`1`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`False`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`0.0`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`0.0`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`{}`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`""`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.sglang_config
## SGLangConfig
```python theme={"system"}
class SGLangConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
Reference: [https://sgl-project.github.io/references/sampling\_params.html](https://sgl-project.github.io/references/sampling_params.html)
**Parameters:**
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **stream** (bool, optional): Whether to stream the generated output in chunks. If set to `True`, the response will be streamed as it is generated. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **tools** (list\[Dict\[str, Any]], optional): A list of tool definitions that the model can dynamically invoke. Each tool should be defined as a dictionary following OpenAI's function calling specification format. For more details, refer to the OpenAI documentation. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.siliconflow_config
## SiliconFlowConfig
```python theme={"system"}
class SiliconFlowConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
SiliconFlow API.
**Parameters:**
* **temperature** (float, optional): Determines the degree of randomness in the response. (default: :obj:`None`)
* **top\_p** (float, optional): The top\_p (nucleus) parameter is used to dynamically adjust the number of choices for each predicted token based on the cumulative probabilities. (default: :obj:`None`)
* **n** (int, optional): Number of generations to return. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. (default: :obj:`None`)
* **stream** (bool, optional): If set, tokens are returned as Server-Sent Events as they are made available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. (default: :obj:`None`)
### as\_dict
```python theme={"system"}
def as_dict(self):
```
**Returns:**
dict\[str, Any]: A dictionary representation of the current
configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.configs.togetherai_config
## TogetherAIConfig
```python theme={"system"}
class TogetherAIConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`{}`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.vllm_config
## VLLMConfig
```python theme={"system"}
class VLLMConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
OpenAI API.
Reference: [https://docs.vllm.ai/en/latest/serving/openai\_compatible\_server.html](https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html)
**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`)
* **n** (int, optional): How many chat completion choices to generate for each input message. (default: :obj:`None`)
* **response\_format** (object, optional): An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to `{"type": "json_object"}` enables JSON mode, which guarantees the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish\_reason="length", which indicates the generation exceeded max\_tokens or the conversation exceeded the max context length.
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. (default: :obj:`None`)
* **frequency\_penalty** (float, optional): Number between :obj:`-2.0` and :obj:`2.0`. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. (default: :obj:`None`)
* **logit\_bias** (dict, optional): Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from :obj:`-100` to :obj:`100`. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between:obj:` -1`
* **and**: obj:`1` should decrease or increase likelihood of selection; values like :obj:`-100` or :obj:`100` should result in a ban or exclusive selection of the relevant token. (default: :obj:`None`)
* **user** (str, optional): A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. (default: :obj:`None`)
* **logprobs**: Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `logits` of `message`. (default: :obj:`None`)
* **top\_logprobs**: An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used. (default: :obj:`None`)
* **extra\_body**: Add additional JSON properties to the request. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.watsonx_config
## WatsonXConfig
```python theme={"system"}
class WatsonXConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
IBM WatsonX API.
See: [https://ibm.github.io/watsonx-ai-python-sdk/fm\_schema.html](https://ibm.github.io/watsonx-ai-python-sdk/fm_schema.html)
**Parameters:**
* **frequency\_penalty** (float, optional): Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. (default: :obj:`None`)
* **logprobs** (bool, optional): Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message. (default: :obj:`None`)
* **top\_logprobs** (int, optional): An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. (default: :obj:`None`)
* **presence\_penalty** (float, optional): Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. (default: :obj:`None`)
* **temperature** (float, optional): What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top\_p but not both. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **time\_limit** (int, optional): The maximum amount of time in seconds that the API will spend generating a response. (default: :obj:`None`)
* **top\_p** (float, optional): Controls the randomness of the generated results. Lower values lead to less randomness, while higher values increase randomness. (default: :obj:`None`)
* **n** (int, optional): How many chat completion choices to generate for each input message. Note that you will be charged based on the total number of tokens generated. (default: :obj:`None`)
* **logit\_biaslogit\_bias** (Optional\[dict], optional): Modify probability of specific tokens appearing in the completion. (default: :obj:`None`)
* **seed** (int, optional): If specified, the system will make a best effort to sample deterministically, such that repeated requests with the same seed and parameters should return the same result. (default: :obj:`None`)
* **stop** (List\[str], optional): Up to 4 sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **tool\_choice\_options** (`Literal["none", "auto"], optional`): The options for the tool choice. (default: :obj:`"auto"`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.yi_config
## YiConfig
```python theme={"system"}
class YiConfig(BaseConfig):
```
Defines the parameters for generating chat completions using the
Yi API. You can refer to the following link for more details:
[https://platform.lingyiwanwu.com/docs/api-reference](https://platform.lingyiwanwu.com/docs/api-reference)
**Parameters:**
* **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 and instead generates a message. :obj:`"auto"` means the model can pick between generating a message or calling one or more tools. :obj:`"required"` or specifying a particular tool via `{"type": "function", "function": {"name": "some_function"}}` can be used to guide the model to use tools more strongly. (default: :obj:`None`)
* **max\_tokens** (int, optional): Specifies the maximum number of tokens the model can generate. This sets an upper limit, but does not guarantee that this number will always be reached. (default: :obj:`None`)
* **top\_p** (float, optional): Controls the randomness of the generated results. Lower values lead to less randomness, while higher values increase randomness. (default: :obj:`None`)
* **temperature** (float, optional): Controls the diversity and focus of the generated results. Lower values make the output more focused, while higher values make it more diverse. (default: :obj:`0.3`)
* **stream** (bool, optional): If True, enables streaming output. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.configs.zhipuai_config
## ZhipuAIConfig
```python theme={"system"}
class ZhipuAIConfig(BaseConfig):
```
Defines the parameters for generating chat completions using OpenAI
compatibility
Reference: [https://open.bigmodel.cn/dev/api#glm-4v](https://open.bigmodel.cn/dev/api#glm-4v)
**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`)
* **stream** (bool, optional): If True, partial message deltas will be sent as data-only server-sent events as they become available. (default: :obj:`None`)
* **stop** (str or list, optional): Up to :obj:`4` sequences where the API will stop generating further tokens. (default: :obj:`None`)
* **max\_tokens** (int, optional): The maximum number of tokens to generate in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. (default: :obj:`None`)
* **tools** (list\[FunctionTool], optional): A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
* **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 and instead generates a message. :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. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. :obj:`"none"` is the default when no tools are present. :obj:`"auto"` is the default if tools are present.
# null
Source: https://docs.camel-ai.org/reference/camel.data_collectors.alpaca_collector
## AlpacaDataCollector
```python theme={"system"}
class AlpacaDataCollector(BaseDataCollector):
```
### **init**
```python theme={"system"}
def __init__(self):
```
### record
```python theme={"system"}
def record(self, agent: Union[List[ChatAgent], ChatAgent]):
```
Inject an agent into the data collector.
**Parameters:**
* **agent** (Union\[List\[ChatAgent], ChatAgent]): The agent to inject.
### convert
```python theme={"system"}
def convert(self):
```
Convert the collected data into a dictionary.
### llm\_convert
```python theme={"system"}
def llm_convert(
self,
converter: Optional[OpenAISchemaConverter] = None,
prompt: Optional[str] = None
):
```
Convert collected data using an LLM schema converter.
**Parameters:**
* **converter** (Optional\[OpenAISchemaConverter], optional): The converter to use. (default: :obj:`OpenAISchemaConverter`)
* **prompt** (Optional\[str], optional): Prompt to guide the conversion. (default: :obj:`DEFAULT_CONVERTER_PROMPTS`)
**Returns:**
Dict\[str, str]: The converted data.
# null
Source: https://docs.camel-ai.org/reference/camel.data_collectors.base
## CollectorData
```python theme={"system"}
class CollectorData:
```
### **init**
```python theme={"system"}
def __init__(
self,
id: UUID,
name: str,
role: Literal['user', 'assistant', 'system', 'tool'],
message: Optional[str] = None,
function_call: Optional[Dict[str, Any]] = None
):
```
Create a data item store information about a message.
Used by the data collector.
**Parameters:**
* **id** (UUID): The id of the message.
* **name** (str): The name of the agent.
* **role** (`Literal["user", "assistant", "system", "function"]`): The role of the message.
* **message** (Optional\[str], optional): The message. (default: :obj:`None`)
* **function\_call** (Optional\[Dict\[str, Any]], optional): The function call. (default: :obj:`None`)
### from\_context
```python theme={"system"}
def from_context(name, context: Dict[str, Any]):
```
Create a data collector from a context.
**Parameters:**
* **name** (str): The name of the agent.
* **context** (Dict\[str, Any]): The context.
**Returns:**
CollectorData: The data collector.
## BaseDataCollector
```python theme={"system"}
class BaseDataCollector(ABC):
```
Base class for data collectors.
### **init**
```python theme={"system"}
def __init__(self):
```
Create a data collector.
### step
```python theme={"system"}
def step(
self,
role: Literal['user', 'assistant', 'system', 'tool'],
name: Optional[str] = None,
message: Optional[str] = None,
function_call: Optional[Dict[str, Any]] = None
):
```
Record a message.
**Parameters:**
* **role** (`Literal["user", "assistant", "system", "tool"]`): The role of the message.
* **name** (Optional\[str], optional): The name of the agent. (default: :obj:`None`)
* **message** (Optional\[str], optional): The message to record. (default: :obj:`None`)
* **function\_call** (Optional\[Dict\[str, Any]], optional): The function call to record. (default: :obj:`None`)
**Returns:**
Self: The data collector.
### record
```python theme={"system"}
def record(self, agent: Union[List[ChatAgent], ChatAgent]):
```
Record agents.
**Parameters:**
* **agent** (Union\[List\[ChatAgent], ChatAgent]): The agent(s) to inject.
### start
```python theme={"system"}
def start(self):
```
Start recording.
### stop
```python theme={"system"}
def stop(self):
```
Stop recording.
### recording
```python theme={"system"}
def recording(self):
```
Whether the collector is recording.
### reset
```python theme={"system"}
def reset(self, reset_agents: bool = True):
```
Reset the collector.
**Parameters:**
* **reset\_agents** (bool, optional): Whether to reset the agents. Defaults to True.
### convert
```python theme={"system"}
def convert(self):
```
Convert the collected data.
### llm\_convert
```python theme={"system"}
def llm_convert(self, converter: Any, prompt: Optional[str] = None):
```
Convert the collected data.
### get\_agent\_history
```python theme={"system"}
def get_agent_history(self, name: str):
```
Get the message history of an agent.
**Parameters:**
* **name** (str): The name of the agent.
**Returns:**
List\[CollectorData]: The message history of the agent
# null
Source: https://docs.camel-ai.org/reference/camel.data_collectors.sharegpt_collector
## ShareGPTDataCollector
```python theme={"system"}
class ShareGPTDataCollector(BaseDataCollector):
```
### **init**
```python theme={"system"}
def __init__(self):
```
### record
```python theme={"system"}
def record(self, agent: Union[List[ChatAgent], ChatAgent]):
```
Inject an agent into the data collector.
### convert
```python theme={"system"}
def convert(self):
```
Convert the collected data into a dictionary.
### llm\_convert
```python theme={"system"}
def llm_convert(
self,
converter: Optional[OpenAISchemaConverter] = None,
prompt: Optional[str] = None
):
```
Convert collected data using an LLM schema converter.
**Parameters:**
* **converter** (Optional\[OpenAISchemaConverter], optional): The converter to use. (default: :obj:`OpenAISchemaConverter`)
* **prompt** (Optional\[str], optional): Prompt to guide the conversion. (default: :obj:`DEFAULT_CONVERTER_PROMPTS`)
**Returns:**
Dict\[str, str]: The converted data.
### to\_sharegpt\_conversation
```python theme={"system"}
def to_sharegpt_conversation(data: Dict[str, Any]):
```
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.cot_datagen
## AgentResponse
```python theme={"system"}
class AgentResponse(BaseModel):
```
Model for structured agent responses.
A Pydantic model class that represents structured responses from agents,
including a similarity score that measures the quality of the response.
**Parameters:**
* **score** (float): A similarity score between 0 and 1 that compares the current answer to the correct answer. Must be within the range \[0, 1].
## VerificationResponse
```python theme={"system"}
class VerificationResponse(BaseModel):
```
Model for structured verification responses.
A Pydantic model class that represents verification results from agents,
indicating whether an answer is correct or not.
**Parameters:**
* **is\_correct** (bool): Boolean indicating if the answer is correct.
## CoTDataGenerator
```python theme={"system"}
class CoTDataGenerator:
```
Class for generating and managing data through chat agent interactions.
This module implements a sophisticated Chain of Thought data generation
system that combines several key algorithms to produce high-quality
reasoning paths. Methods implemented:
1. Monte Carlo Tree Search (MCTS)
2. Binary Search Error Detection
3. Dual-Agent Verification System
4. Solution Tree Management
**Parameters:**
* **chat\_agent** (Optional\[ChatAgent]): Optional single agent for both tasks (legacy mode). (default::obj:`None`)
* **generator\_agent** (Optional\[ChatAgent]): Optional specialized agent for answer generation. (default::obj:`None`)
* **verifier\_agent** (Optional\[ChatAgent]): Optional specialized agent for answer verification. (default::obj:`None`)
* **golden\_answers** (Dict\[str, str]): Dictionary containing pre-defined correct answers for validation and comparison. Required for answer verification.
* **search\_limit** (int): Maximum number of search iterations allowed. (default::obj:`100`)
### **init**
```python theme={"system"}
def __init__(self, chat_agent: Optional[ChatAgent] = None):
```
Initialize the CoTDataGenerator.
This constructor supports both single-agent and dual-agent modes:
1. Single-agent mode (legacy): Pass a single chat\_agent that will be
used for both generation and verification.
2. Dual-agent mode: Pass separate generator\_agent and verifier\_agent
for specialized tasks.
**Parameters:**
* **chat\_agent** (Optional\[ChatAgent]): Optional single agent for both tasks (legacy mode). (default::obj:`None`)
* **generator\_agent** (Optional\[ChatAgent]): Optional specialized agent for answer generation. (default::obj:`None`)
* **verifier\_agent** (Optional\[ChatAgent]): Optional specialized agent for answer verification. (default::obj:`None`)
* **golden\_answers** (Dict\[str, str]): Dictionary containing pre-defined correct answers for validation and comparison. Required for answer verification.
* **search\_limit** (int): Maximum number of search iterations allowed. (default::obj:`100`)
### get\_answer
```python theme={"system"}
def get_answer(self, question: str, context: str = ''):
```
Get an answer from the chat agent for a given question.
**Parameters:**
* **question** (str): The question to ask.
* **context** (str): Additional context for the question. (default::obj:`""`)
**Returns:**
str: The generated answer.
### verify\_answer
```python theme={"system"}
def verify_answer(self, question: str, answer: str):
```
Verify if a generated answer is semantically equivalent to
the golden answer for a given question.
**Parameters:**
* **question** (str): The question being answered.
* **answer** (str): The answer to verify.
**Returns:**
bool: True if the answer matches the golden answer based on
semantic equivalence (meaning the core content and meaning are
the same, even if the exact wording differs).
False in the following cases:
* If the provided question doesn't exist in the golden answers
* If the answer's meaning differs from the golden answer
### evaluate\_partial\_solution
```python theme={"system"}
def evaluate_partial_solution(self, question: str, partial_solution: str = ''):
```
Evaluate the quality of a partial solution against the
golden answer.
This function generates a similarity score between the given partial
solution and the correct answer (golden answer).
**Parameters:**
* **question** (str): The question being solved.
* **partial\_solution** (str): The partial solution generated so far. (default::obj:`""`)
**Returns:**
float: A similarity score between 0 and 1, indicating how close the
partial solution is to the golden answer.
### binary\_search\_error
```python theme={"system"}
def binary_search_error(self, question: str, solution: str):
```
Use binary search to locate the first error in the solution.
This method splits the solution into sentences using both English and
Chinese sentence delimiters and performs binary search to find the
first error.
**Parameters:**
* **question** (str): The question being solved.
* **solution** (str): The complete solution to analyze.
**Returns:**
int: The position of the first error found in the solution.
Returns -1. If no errors are found (all sentences are correct).
### solve
```python theme={"system"}
def solve(self, question: str):
```
Solve a question using a multi-step approach.
The solution process follows these steps:
1. Try to solve directly - if correct, return the solution.
2. If not correct, perform a search by iteratively generating
new solutions and evaluating their similarity scores to
find a good solution. The search process involves:
a. Generation: Generate new solution candidates using
the generator agent.
b. Evaluation: Score each solution candidate for similarity
to the golden answer.
c. Selection: Keep the best-scoring candidate found so far.
d. Early stopping: If a sufficiently high-scoring solution
is found (score > 0.9), stop early.
3. If the solution isn't perfect, use binary search to locate
errors.
4. Generate a new solution based on the correct part of the
initial solution.
**Parameters:**
* **question** (str): The question to solve.
**Returns:**
str: The best solution found.
### import\_qa\_from\_json
```python theme={"system"}
def import_qa_from_json(self, data: Union[str, Dict[str, str]]):
```
Import question and answer data from either a JSON file or a
dictionary.
**Parameters:**
* **data** (Union\[str, Dict\[str, str]]): Either a path to a JSON file containing QA pairs or a dictionary of question-answer pairs. If a string is provided, it's treated as a file path. The expected format is: `{"question1": "answer1", "question2": "answer2", ...}`
**Returns:**
bool: True if import was successful, False otherwise.
### export\_solutions
```python theme={"system"}
def export_solutions(self, filepath: str = 'solutions.json'):
```
Export the solution process and results to a JSON file.
Exports the solution tree, golden answers,
and export timestamp to a JSON file.
The exported data includes:
* solutions: The solution tree
with intermediate steps
* golden\_answers: The reference answers used for verification
* export\_time: ISO format timestamp of the export
**Parameters:**
* **filepath** (str, optional): Path where the JSON file will be saved. (default::obj:`'solutions.json'`)
**Returns:**
None: The method writes to a file and logs the result but does not
return any value.
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.evol_instruct.evol_instruct
## EvolInstructPipeline
```python theme={"system"}
class EvolInstructPipeline:
```
Pipeline for evolving prompts using the Evol-Instruct methodology.
Supports custom templates defining evolution strategies and methods. The
pipeline leverages language models to iteratively refine prompts through
specified evolution strategies.
**Parameters:**
* **templates** (Type\[EvolInstructTemplates]): Template class containing evolution strategy and method definitions. Must provide `EVOL_METHODS` and `STRATEGY` attributes. (default: :obj:`EvolInstructTemplates`)
* **agent** (Optional\[ChatAgent]): Chat agent instance for LLM interaction.
* **If**: obj:`None`, initializes with a default ChatAgent. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
templates: Type = EvolInstructTemplates,
agent: Optional[ChatAgent] = None
):
```
Initialize pipeline with templates and language model agent.
**Parameters:**
* **templates** (Type\[EvolInstructTemplates]): Template class containing evolution strategy configurations. (default: :obj:`EvolInstructTemplates`)
* **agent** (Optional\[ChatAgent]): Preconfigured chat agent instance. Creates a default ChatAgent if not provided. (default: :obj:`None`)
### \_resolve\_evolution\_method
```python theme={"system"}
def _resolve_evolution_method(self, method_key: str):
```
Resolve evolution method key to concrete implementation.
**Parameters:**
* **method\_key** (str): Input method identifier. Can be: - Direct method key from templates.EVOL\_METHODS - Strategy name from templates.STRATEGY keys
**Returns:**
str: Resolved method key from EVOL\_METHODS
### \_get\_evolution\_methods
```python theme={"system"}
def _get_evolution_methods(self, method: Union[str, List[str]], num_generations: int = 2):
```
Get list of evolution methods based on input specification.
**Parameters:**
* **method** (Union\[str, List\[str]]): Specification for method selection. Can be: - Strategy name for methods from that strategy - Specific method name - List of method specifications
* **num\_generations** (int): Number of methods to return.
**Returns:**
List\[str]: List of resolved method names
### \_generate\_single\_evolution
```python theme={"system"}
def _generate_single_evolution(
self,
prompt: str,
method: str,
return_method: bool = False
):
```
Generate a single evolved prompt from a seed prompt.
**Parameters:**
* **prompt** (str): The seed prompt to evolve.
* **method** (str): The evolution method key to use.
* **return\_method** (bool): If True, returns method along with prompt.
**Returns:**
Tuple\[str, str]: Evolved prompt and method
### \_generate\_multiple\_evolutions
```python theme={"system"}
def _generate_multiple_evolutions(
self,
prompt: str,
method: Union[str, List[str]],
num_generations: int = 2,
keep_original: bool = True,
num_threads: int = 10
):
```
Generate multiple evolved versions of a prompt.
**Parameters:**
* **prompt** (str): Seed prompt to evolve.
* **method** (Union\[str, List\[str]]): Evolution method specification.
* **num\_generations** (int): Candidates to generate per iteration.
* **keep\_original** (bool): Whether to keep the original prompt.
* **num\_threads** (int): Number of threads for parallel processing.
**Returns:**
List\[Tuple\[str, str]]: List of (evolved\_prompt, method) pairs
### \_generate\_iterative\_evolutions
```python theme={"system"}
def _generate_iterative_evolutions(
self,
prompt: str,
evolution_spec: Union[str, List[Union[str, List[str]]]],
num_generations: int = 2,
num_iterations: Optional[int] = None,
keep_original: bool = True,
scorer: Optional[BaseScorer] = None,
num_threads: int = 10
):
```
Generate iterative evolutions of a prompt with scoring.
**Parameters:**
* **prompt** (str): Seed prompt to evolve.
* **evolution\_spec** (Union\[str, List\[Union\[str, List\[str]]]]): Evolution method specification. If a list is provided and num\_iterations is None, then num\_iterations is set to the length of the list.
* **num\_generations** (int): Candidates to generate per iteration.
* **num\_iterations** (Optional\[int]): Number of evolution iterations. Defaults to the length of evolution\_spec.
* **keep\_original** (bool): Include original prompt in results.
* **scorer** (Optional\[BaseScorer]): Scoring model for candidate.
* **num\_threads** (int): Number of threads for parallel processing.
**Returns:**
Dict\[int, List\[Dict\[str, Any]]]: Evolution results per iteration,
where each candidate is represented as a dict with keys:
"instruction", "method", and "scores".
### generate
```python theme={"system"}
def generate(
self,
prompts: List[str],
evolution_spec: Union[str, List[Union[str, List[str]]]],
num_generations: int = 2,
num_iterations: Optional[int] = None,
keep_original: bool = True,
scorer: Optional[BaseScorer] = None,
num_chunks: int = 1,
retry_limit: int = 3,
retry_delay: float = 1.0,
num_threads: int = 10
):
```
Evolve a batch of prompts through iterative refinement.
**Parameters:**
* **prompts** (List\[str]): Seed prompts to evolve.
* **evolution\_spec** (Union\[str, List\[Union\[str, List\[str]]]]): Evolution method specification. If a list is provided and num\_iterations is None, then num\_iterations is set to the length of the list.
* **num\_generations** (int): Candidates to generate per iteration.
* **num\_iterations** (Optional\[int]): Number of evolution iterations. Defaults to the length of evolution\_spec.
* **keep\_original** (bool): Include original prompts in results.
* **scorer** (Optional\[BaseScorer]): Scoring model for candidate.
* **num\_chunks** (int): Number of parallel processing chunks.
* **retry\_limit** (int): Max retries for failed generations.
* **retry\_delay** (float): Delay between retries in seconds.
* **num\_threads** (int): Number of threads for parallel processing.
**Returns:**
List\[Dict\[int, List\[Dict\[str, Any]]]]: Evolution results.
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.evol_instruct.scorer
## BaseScorer
```python theme={"system"}
class BaseScorer(ABC):
```
### score
```python theme={"system"}
def score(self, reference_prompt: str, candidate_prompt: str):
```
Compare a candidate prompt against a reference prompt and
return a tuple of scores. The higher the score, the better.
For example, (diversity, difficulty, feasibility).
## MathScorer
```python theme={"system"}
class MathScorer(BaseScorer):
```
### **init**
```python theme={"system"}
def __init__(self, agent: Optional[ChatAgent] = None):
```
### score
```python theme={"system"}
def score(self, reference_problem: str, new_problem: str):
```
Evaluates the new math problem relative to the reference math
problem.
**Parameters:**
* **reference\_problem** (str): The reference math problem.
* **new\_problem** (str): The new or evolved math problem.
**Returns:**
Dict\[str, int]: A dictionary with scores for diversity, difficulty,
validity, and solvability.
## GeneralScorer
```python theme={"system"}
class GeneralScorer(BaseScorer):
```
### **init**
```python theme={"system"}
def __init__(self, agent: Optional[ChatAgent] = None):
```
### score
```python theme={"system"}
def score(self, reference_problem: str, new_problem: str):
```
Evaluates the new problem against the reference problem using
structured scoring.
**Parameters:**
* **reference\_problem** (str): The original problem.
* **new\_problem** (str): The evolved or new problem.
**Returns:**
Dict\[str, int]: A dictionary with scores for diversity, complexity,
and validity.
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.evol_instruct.templates
## BaseEvolInstructTemplates
```python theme={"system"}
class BaseEvolInstructTemplates(ABC):
```
Abstract base class for evolution instruction templates.
This class defines a required structure for prompt transformation templates
* `EVOL_METHODS`: A dictionary mapping method keys to their descriptions.
* `STRATEGY`: A dictionary defining strategies and associated methods.
Subclasses should define concrete templates for specific domains.
### EVOL\_METHODS
```python theme={"system"}
def EVOL_METHODS(self):
```
A dictionary mapping evolution method keys to their descriptions.
### STRATEGY
```python theme={"system"}
def STRATEGY(self):
```
A dictionary defining strategies and their corresponding methods.
## EvolInstructTemplates
```python theme={"system"}
class EvolInstructTemplates(BaseEvolInstructTemplates):
```
Contains templates for EvolInstruct prompt transformations.
References:
* WizardLM: Empowering Large Language Models to Follow Complex
Instructions
[https://arxiv.org/pdf/2304.12244](https://arxiv.org/pdf/2304.12244)
* eva: Evolving Alignment via Asymmetric Self-Play
[https://arxiv.org/abs/2411.00062](https://arxiv.org/abs/2411.00062)
## MathEvolInstructTemplates
```python theme={"system"}
class MathEvolInstructTemplates(BaseEvolInstructTemplates):
```
Contains templates for MathEvolInstruct prompt transformations.
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.self_improving_cot
## SelfImprovingCoTPipeline
```python theme={"system"}
class SelfImprovingCoTPipeline:
```
Pipeline for generating self-taught reasoning traces
using the self-improving methodology.
This implements the STaR paper's approach of:
1. Initial reasoning trace generation
2. Self-evaluation
3. Feedback-based improvement
4. Iterative refinement
### **init**
```python theme={"system"}
def __init__(
self,
reason_agent: ChatAgent,
problems: List[Dict],
max_iterations: int = 3,
score_threshold: Union[float, Dict[str, float]] = 0.7,
rejection_sampling_n: Optional[int] = None,
evaluate_agent: Optional[ChatAgent] = None,
reward_model: Optional[BaseRewardModel] = None,
output_path: Optional[str] = None,
few_shot_examples: Optional[str] = None,
batch_size: Optional[int] = None,
max_workers: Optional[int] = None,
solution_pattern: str = '\\\\boxed{(.*?)}',
trace_pattern: Optional[str] = None
):
```
Initialize the self-improving cot pipeline.
**Parameters:**
* **reason\_agent** (ChatAgent): The chat agent used for generating and improving reasoning traces.
* **problems** (List\[Dict]): List of problem dictionaries to process.
* **max\_iterations** (int, optional): Maximum number of improvement iterations. If set to `0`, the pipeline will generate an initial trace without any improvement iterations. (default: :obj:`3`)
* **score\_threshold** (Union\[float, Dict\[str, float]], optional): Quality threshold. Can be either a single float value applied to average score, or a dictionary mapping score dimensions to their thresholds. For example: `{"correctness": 0.8, "coherence": 0.7}`. If using reward model and threshold for a dimension is not specified, will use the default value 0.7. (default: :obj:`0.7`)
* **rejection\_sampling\_n** (int, optional): Specifies the number of samples to be drawn using the rejection sampling method, where samples are accepted or rejected based on a predefined condition to achieve a desired distribution. (default: :obj: `None`)
* **evaluate\_agent** (Optional\[ChatAgent]): The chat agent used for evaluating reasoning traces. (default: :obj:`None`)
* **reward\_model** (BaseRewardModel, optional): Model used to evaluate reasoning traces. If `None`, uses Agent self-evaluation. (default: :obj:`None`)
* **output\_path** (str, optional): Output path for saving traces. If `None`, results will only be returned without saving to file. (default: :obj:`None`)
* **few\_shot\_examples** (str, optional): Examples to use for few-shot generation. (default: :obj:`None`)
* **batch\_size** (int, optional): Batch size for parallel processing. (default: :obj:`None`)
* **max\_workers** (int, optional): Maximum number of worker threads. (default: :obj:`None`)
* **solution\_pattern** (str, optional): Regular expression pattern with one capture group to extract answers from solution text. (default: :obj:`r'\\boxed{(.*?)}'`)
* **trace\_pattern** (str, optional): Regular expression pattern with one capture group to extract answers from trace text. If `None`, uses the same pattern as solution\_pattern. (default: :obj:`None`)
### safe\_write\_json
```python theme={"system"}
def safe_write_json(self, file_path, data):
```
### clean\_json
```python theme={"system"}
def clean_json(self, data):
```
### \_check\_score\_threshold
```python theme={"system"}
def _check_score_threshold(self, scores: Dict[str, float]):
```
Check if scores meet the threshold requirements.
**Parameters:**
* **scores** (Dict\[str, float]): Dictionary of scores for different dimensions.
**Returns:**
bool: True if scores meet threshold requirements, False otherwise.
### \_generate\_feedback
```python theme={"system"}
def _generate_feedback(self, scores: Dict[str, float]):
```
Generate feedback based on which dimensions need improvement.
**Parameters:**
* **scores** (Dict\[str, float]): Dictionary of scores for different dimensions.
**Returns:**
str: Feedback message indicating which dimensions need improvement.
### generate\_reasoning\_trace
```python theme={"system"}
def generate_reasoning_trace(self, problem: str):
```
Generate initial reasoning trace for a given problem.
**Parameters:**
* **problem** (str): The problem text to generate reasoning for.
**Returns:**
str: Generated reasoning trace.
### evaluate\_trace
```python theme={"system"}
def evaluate_trace(
self,
problem: str,
trace: str,
solution: Optional[str] = None
):
```
Evaluate the quality of a reasoning trace.
**Parameters:**
* **problem** (str): The original problem text to evaluate against.
* **trace** (str): The reasoning trace to evaluate.
* **solution** (Optional\[str]): The solution to the problem, if provided. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: Evaluation results containing:
* scores: Dict of evaluation dimensions and their scores
* feedback: Detailed feedback for improvement
For Agent self-evaluation, the scores will include:
* correctness: Score for logical correctness
* clarity: Score for clarity of explanation
* completeness: Score for completeness of reasoning
For reward model evaluation, the scores will depend on
the model's evaluation dimensions.
### generate\_reasoning\_trace\_rejection
```python theme={"system"}
def generate_reasoning_trace_rejection(self, problem: str):
```
Generate multiple candidate reasoning traces for a problem and
select the best one based on evaluation.
**Parameters:**
* **problem** (str): The problem text for generating a reasoning trace.
**Returns:**
str: The best candidate trace that meets quality criteria, or the
first candidate if none qualify.
### improve\_trace
```python theme={"system"}
def improve_trace(
self,
problem: str,
trace: str,
feedback: str,
solution: Optional[str] = None
):
```
Generate improved reasoning trace based on feedback.
**Parameters:**
* **problem** (str): The original problem text.
* **trace** (str): The current reasoning trace.
* **feedback** (str): Feedback for improving the trace.
* **solution** (Optional\[str]): The solution to the problem, if provided. (default: :obj:`None`)
**Returns:**
str: Improved reasoning trace.
### validate\_problem\_format
```python theme={"system"}
def validate_problem_format(self, problem: Dict):
```
Validate that a problem dictionary has the required format.
**Parameters:**
* **problem** (Dict): Problem dictionary to validate.
### \_check\_boxed\_answers
```python theme={"system"}
def _check_boxed_answers(self, solution: str, trace: str):
```
Check if the answer in the trace matches the solution using the
configured patterns.
**Parameters:**
* **solution** (str): The problem solution string.
* **trace** (str): The reasoning trace string.
**Returns:**
bool: True if answers match, False otherwise
### process\_problem
```python theme={"system"}
def process_problem(self, problem: Dict, rationalization: bool = False):
```
Process a single problem through the self-improving cot pipeline.
**Parameters:**
* **problem** (Dict): Problem dictionary containing the problem text.
* **rationalization** (bool, optional): Whether to use rationalization. (default: :obj:`False`)
**Returns:**
ProblemResult: Results with final trace and history.
### generate
```python theme={"system"}
def generate(self, rationalization: bool = False):
```
Execute the self-improving cot pipeline on all problems.
Process problems and return results. If output\_path is specified,
also save results to file.
**Parameters:**
* **rationalization** (bool, optional): Whether to use rationalization. (default: :obj:`False`)
**Returns:**
List\[Dict\[str, Any]]: List of processed results
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.self_instruct.self_instruct
## SelfInstructPipeline
```python theme={"system"}
class SelfInstructPipeline:
```
A pipeline to generate and manage machine-generated instructions for
tasks, combining human and machine task samples.
**Parameters:**
* **agent** (ChatAgent): The agent used to interact and generate instructions.
* **seed** (str): The path to the human-written instructions.
* **num\_machine\_instructions** (int): Number of machine-generated instructions to generate. (default::obj:`5`)
* **data\_output\_path** (Optional\[str]): Path to save the generated data. (default::obj:`./data_output.json`)
* **human\_to\_machine\_ratio** (tuple): Ratio of human to machine tasks used for instruction generation. (default::obj:`(6, 2)`)
* **instruction\_filter** (InstructionFilter): A filter to validate generated instructions. (default::obj:`None`)
* **filter\_config** (Optional\[Dict\[str, Dict\[str, Any]]]): configuration for the filter functions registered in FILE\_REGISTRY. (default::obj:`None`)
* **stop\_on\_first\_failure** (bool): If True, stops checking filters after the first failure.
### **init**
```python theme={"system"}
def __init__(
self,
agent: ChatAgent,
seed: str,
num_machine_instructions: int = 5,
data_output_path: Optional[str] = './data_output.json',
human_to_machine_ratio: tuple = (6, 2),
instruction_filter: Optional[InstructionFilter] = None,
filter_config: Optional[Dict[str, Dict[str, Any]]] = None,
stop_on_first_failure: bool = False
):
```
### load\_seed
```python theme={"system"}
def load_seed(self, path: str):
```
Load seed tasks from a file. Defaults to a predefined seed file if
no path is provided.
**Parameters:**
* **path** (str): Path to the seed file.
### sample\_human\_tasks
```python theme={"system"}
def sample_human_tasks(self, count: int):
```
Sample a specified number of human tasks from the loaded seed.
**Parameters:**
* **count** (int): Number of human tasks to sample.
**Returns:**
List\[dict]: A list of sampled human tasks.
### sample\_machine\_tasks
```python theme={"system"}
def sample_machine_tasks(self, count: int):
```
Sample a specified number of machine tasks.
**Parameters:**
* **count** (int): Number of machine tasks to sample.
**Returns:**
List\[dict]: A list of sampled machine tasks, with placeholders if
insufficient tasks are available.
### generate\_machine\_instruction
```python theme={"system"}
def generate_machine_instruction(self):
```
**Returns:**
List: The prompt and a machine-generated instruction.
### identify\_instruction
```python theme={"system"}
def identify_instruction(self, instruction: str):
```
Determine if the given instruction is a classification task.
**Parameters:**
* **instruction** (str): The instruction to classify.
**Returns:**
bool: True if the instruction is a classification task,
otherwise False.
### generate\_machine\_instances
```python theme={"system"}
def generate_machine_instances(self):
```
Generate instances for each machine task based on its
classification status.
### generate\_machine\_instance
```python theme={"system"}
def generate_machine_instance(self, instruction: str, classification: bool):
```
Generate instances for a given instruction.
**Parameters:**
* **instruction** (str): The instruction to create instances for.
* **classification** (bool): Whether the instruction is a classification task.
**Returns:**
List\[dict]: A list of generated instances in input-output format.
### parse\_classification\_output
```python theme={"system"}
def parse_classification_output(self, generated_text: str):
```
Parse the generated text for classification tasks into input-output
pairs.
**Parameters:**
* **generated\_text** (str): The raw text generated by the agent for classification tasks.
**Returns:**
List\[Dict\[str, str]]: A list of dictionaries with 'input' and
'output' keys.
### parse\_non\_classification\_output
```python theme={"system"}
def parse_non_classification_output(self, generated_text: str):
```
Parse the generated text for non-classification tasks into
input-output pairs.
**Parameters:**
* **generated\_text** (str): The raw text generated by the agent for non-classification tasks.
**Returns:**
List\[Dict\[str, str]]: A list of dictionaries with 'input' and
'output' keys.
### construct\_data
```python theme={"system"}
def construct_data(self):
```
Save the machine-generated tasks to the specified output path
in JSON format.
### generate
```python theme={"system"}
def generate(self, timeout_minutes = 600):
```
Execute the entire pipeline to generate machine instructions
and instances.
**Parameters:**
* **timeout\_minutes** (int): Maximum time in minutes to run the generation process before timing out. (default: :obj:`600`)
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.source2synth.data_processor
## UserDataProcessor
```python theme={"system"}
class UserDataProcessor:
```
A processor for generating multi-hop question-answer pairs from user
data.
This class handles the processing of text data to generate multi-hop
question-answer pairs using either an AI model or rule-based approaches.
It manages the entire pipeline from text preprocessing to dataset curation.
**Parameters:**
* **config** (ProcessorConfig): Configuration for data processing parameters.
* **rng** (random.Random): Random number generator for reproducibility.
* **multi\_hop\_agent** (Optional\[MultiHopGeneratorAgent]): Agent for generating QA pairs.
### **init**
```python theme={"system"}
def __init__(self, config: Optional[ProcessorConfig] = None):
```
Initialize the UserDataProcessor.
**Parameters:**
* **config** (Optional\[ProcessorConfig], optional): Configuration for data processing. (default: :obj:`None`)
### process\_text
```python theme={"system"}
def process_text(self, text: str, source: str = 'user_input'):
```
Process a single text to generate multi-hop QA pairs.
**Parameters:**
* **text** (str): The input text to process.
* **source** (str, optional): Source identifier for the text. (default: :obj:`"user_input"`)
**Returns:**
List\[Dict\[str, Any]]: List of processed examples with QA pairs and
metadata.
### process\_batch
```python theme={"system"}
def process_batch(self, texts: List[str], sources: Optional[List[str]] = None):
```
Process multiple texts in batch to generate multi-hop QA pairs.
**Parameters:**
* **texts** (List\[str]): List of input texts to process.
* **sources** (Optional\[List\[str]], optional): List of source identifiers. (default: :obj:`None`)
**Returns:**
List\[Dict\[str, Any]]: List of processed examples with QA pairs and
metadata.
## ExampleConstructor
```python theme={"system"}
class ExampleConstructor:
```
Constructs training examples from raw text data.
This class handles the construction of training examples by preprocessing
text, extracting information pairs, and generating question-answer pairs.
**Parameters:**
* **config** (ProcessorConfig): Configuration for example construction.
* **multi\_hop\_agent** (Optional\[MultiHopGeneratorAgent]): Agent for QA generation.
### **init**
```python theme={"system"}
def __init__(
self,
config: ProcessorConfig,
multi_hop_agent: Optional[MultiHopGeneratorAgent] = None
):
```
Initialize the ExampleConstructor.
**Parameters:**
* **config** (ProcessorConfig): Configuration for example construction.
* **multi\_hop\_agent** (Optional\[MultiHopGeneratorAgent], optional): Agent for generating multi-hop QA pairs. (default: :obj:`None`)
### construct\_examples
```python theme={"system"}
def construct_examples(self, raw_data: List[Dict[str, Any]]):
```
Construct training examples from raw data.
**Parameters:**
* **raw\_data** (List\[Dict\[str, Any]]): List of raw data dictionaries containing text and metadata.
**Returns:**
List\[Dict\[str, Any]]: List of constructed examples with QA pairs
and metadata.
### \_preprocess\_text
```python theme={"system"}
def _preprocess_text(self, text: str):
```
Preprocess input text for example construction.
**Parameters:**
* **text** (str): Input text to preprocess.
**Returns:**
str: Preprocessed text, or empty string if text fails quality
checks.
### \_check\_text\_quality
```python theme={"system"}
def _check_text_quality(self, text: str):
```
Check the quality of input text.
**Parameters:**
* **text** (str): Text to check quality for.
**Returns:**
bool: True if text passes quality checks, False otherwise.
### \_extract\_info\_pairs
```python theme={"system"}
def _extract_info_pairs(self, text: str):
```
Extract information pairs and relationships from text.
**Parameters:**
* **text** (str): Input text to extract information from.
**Returns:**
List\[Dict\[str, Sequence\[str]]]: List of dictionaries containing
premise, intermediate, conclusion, and related contexts.
### \_generate\_qa\_pairs
```python theme={"system"}
def _generate_qa_pairs(self, info_pairs: List[Dict[str, Sequence[str]]]):
```
Generate multi-hop question-answer pairs from information pairs.
**Parameters:**
* **info\_pairs** (List\[Dict\[str, Sequence\[str]]]): List of information pairs extracted from text.
**Returns:**
List\[Dict\[str, str]]: List of generated QA pairs.
### \_calculate\_complexity
```python theme={"system"}
def _calculate_complexity(self, qa_pairs: List[Dict[str, Any]]):
```
Calculate the complexity score for a set of QA pairs.
**Parameters:**
* **qa\_pairs** (List\[Dict\[str, Any]]): List of QA pairs to calculate complexity for.
**Returns:**
float: Complexity score between 0.0 and 1.0.
## DataCurator
```python theme={"system"}
class DataCurator:
```
Manages and curates datasets of multi-hop question-answer pairs.
This class handles dataset management tasks including quality filtering,
complexity filtering, deduplication, and dataset sampling.
**Parameters:**
* **config** (ProcessorConfig): Configuration for data curation parameters.
* **rng** (random.Random): Random number generator for reproducible sampling.
### **init**
```python theme={"system"}
def __init__(self, config: ProcessorConfig, rng: random.Random):
```
Initialize the DataCurator.
**Parameters:**
* **config** (ProcessorConfig): Configuration for data curation.
* **rng** (random.Random): Random number generator for reproducibility.
### curate\_dataset
```python theme={"system"}
def curate_dataset(self, examples: List[Dict[str, Any]]):
```
Manage and curate a dataset through multiple filtering stages.
**Parameters:**
* **examples** (List\[Dict\[str, Any]]): List of examples to curate.
**Returns:**
List\[Dict\[str, Any]]: Curated dataset meeting quality criteria.
### \_quality\_filter
```python theme={"system"}
def _quality_filter(self, examples: List[Dict[str, Any]]):
```
Filter examples based on quality criteria.
**Parameters:**
* **examples** (List\[Dict\[str, Any]]): List of examples to filter.
**Returns:**
List\[Dict\[str, Any]]: Examples that pass quality checks.
### \_check\_qa\_quality
```python theme={"system"}
def _check_qa_quality(self, qa_pairs: List[Dict[str, str]]):
```
Check the quality of question-answer pairs.
**Parameters:**
* **qa\_pairs** (List\[Dict\[str, str]]): List of QA pairs to check.
**Returns:**
bool: True if QA pairs meet quality criteria, False otherwise.
### \_complexity\_filter
```python theme={"system"}
def _complexity_filter(self, examples: List[Dict[str, Any]]):
```
Filter examples based on complexity threshold.
Removes examples with complexity scores below the configured threshold.
**Parameters:**
* **examples** (List\[Dict\[str, Any]]): List of examples to filter.
**Returns:**
List\[Dict\[str, Any]]: Examples meeting complexity threshold.
### \_remove\_duplicates
```python theme={"system"}
def _remove_duplicates(self, examples: List[Dict[str, Any]]):
```
Remove duplicate examples from the dataset.
**Parameters:**
* **examples** (List\[Dict\[str, Any]]): List of examples to deduplicate.
**Returns:**
List\[Dict\[str, Any]]: Deduplicated examples.
### \_sample\_dataset
```python theme={"system"}
def _sample_dataset(self, examples: List[Dict[str, Any]]):
```
Sample examples to match target dataset size.
**Parameters:**
* **examples** (List\[Dict\[str, Any]]): List of examples to sample from.
**Returns:**
List\[Dict\[str, Any]]: Sampled dataset of target size or smaller.
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.source2synth.models
## ReasoningStep
```python theme={"system"}
class ReasoningStep(BaseModel):
```
A single step in a multi-hop reasoning process.
**Parameters:**
* **step** (str): The textual description of the reasoning step.
## MultiHopQA
```python theme={"system"}
class MultiHopQA(BaseModel):
```
A multi-hop question-answer pair with reasoning steps and supporting
facts.
**Parameters:**
* **question** (str): The question requiring multi-hop reasoning.
* **reasoning\_steps** (List\[ReasoningStep]): List of reasoning steps to answer.
* **answer** (str): The final answer to the question.
* **supporting\_facts** (List\[str]): List of facts supporting the reasoning.
* **type** (str): The type of question-answer pair.
## ContextPrompt
```python theme={"system"}
class ContextPrompt(BaseModel):
```
A context prompt for generating multi-hop question-answer pairs.
**Parameters:**
* **main\_context** (str): The primary context for generating QA pairs.
* **related\_contexts** (Optional\[List\[str]]): Additional related contexts.
# null
Source: https://docs.camel-ai.org/reference/camel.datagen.source2synth.user_data_processor_config
## ProcessorConfig
```python theme={"system"}
class ProcessorConfig(BaseModel):
```
Data processing configuration class
### **repr**
```python theme={"system"}
def __repr__(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.datahubs.base
## BaseDatasetManager
```python theme={"system"}
class BaseDatasetManager(ABC):
```
Abstract base class for dataset managers.
### create\_dataset
```python theme={"system"}
def create_dataset(self, name: str, **kwargs: Any):
```
Creates a new dataset.
**Parameters:**
* **name** (str): The name of the dataset.
* **kwargs** (Any): Additional keyword arguments.
**Returns:**
str: The URL of the created dataset.
### list\_datasets
```python theme={"system"}
def list_datasets(
self,
username: str,
limit: int = 100,
**kwargs: Any
):
```
Lists all datasets for the current user.
**Parameters:**
* **username** (str): The username of the user whose datasets to list.
* **limit** (int): The maximum number of datasets to list. (default::obj:`100`)
* **kwargs** (Any): Additional keyword arguments.
**Returns:**
List\[str]: A list of dataset ids.
### delete\_dataset
```python theme={"system"}
def delete_dataset(self, dataset_name: str, **kwargs: Any):
```
Deletes a dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset to delete.
* **kwargs** (Any): Additional keyword arguments.
### add\_records
```python theme={"system"}
def add_records(
self,
dataset_name: str,
records: List[Record],
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Adds records to a dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **records** (List\[Record]): A list of records to add to the dataset.
* **filepath** (str): The path to the file containing the records. (default::obj:`"records/records.json"`)
* **kwargs** (Any): Additional keyword arguments.
### update\_records
```python theme={"system"}
def update_records(
self,
dataset_name: str,
records: List[Record],
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Updates records in a dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **records** (List\[Record]): A list of records to update in the dataset.
* **filepath** (str): The path to the file containing the records. (default::obj:`"records/records.json"`)
* **kwargs** (Any): Additional keyword arguments.
### list\_records
```python theme={"system"}
def list_records(
self,
dataset_name: str,
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Lists records in a dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **filepath** (str): The path to the file containing the records. (default::obj:`"records/records.json"`)
* **kwargs** (Any): Additional keyword arguments.
### delete\_record
```python theme={"system"}
def delete_record(
self,
dataset_name: str,
record_id: str,
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Deletes a record from the dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **record\_id** (str): The ID of the record to delete.
* **filepath** (str): The path to the file containing the records. (default::obj:`"records/records.json"`)
* **kwargs** (Any): Additional keyword arguments.
# null
Source: https://docs.camel-ai.org/reference/camel.datahubs.huggingface
## HuggingFaceDatasetManager
```python theme={"system"}
class HuggingFaceDatasetManager(BaseDatasetManager):
```
A dataset manager for Hugging Face datasets. This class provides
methods to create, add, update, delete, and list records in a dataset on
the Hugging Face Hub.
**Parameters:**
* **token** (str): The Hugging Face API token. If not provided, the token will be read from the environment variable `HF_TOKEN`.
### **init**
```python theme={"system"}
def __init__(self, token: Optional[str] = None):
```
### create\_dataset\_card
```python theme={"system"}
def create_dataset_card(
self,
dataset_name: str,
description: str,
license: Optional[str] = None,
version: Optional[str] = None,
tags: Optional[List[str]] = None,
authors: Optional[List[str]] = None,
size_category: Optional[List[str]] = None,
language: Optional[List[str]] = None,
task_categories: Optional[List[str]] = None,
content: Optional[str] = None
):
```
Creates and uploads a dataset card to the Hugging Face Hub in YAML
format.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **description** (str): A description of the dataset.
* **license** (str): The license of the dataset. (default: :obj:`None`)
* **version** (str): The version of the dataset. (default: :obj:`None`)
* **tags** (list): A list of tags for the dataset.(default: :obj:`None`)
* **authors** (list): A list of authors of the dataset. (default: :obj:`None`)
* **size\_category** (list): A size category for the dataset. (default: :obj:`None`)
* **language** (list): A list of languages the dataset is in. (default: :obj:`None`)
* **task\_categories** (list): A list of task categories. (default: :obj:`None`)
* **content** (str): Custom markdown content that the user wants to add to the dataset card. (default: :obj:`None`)
### create\_dataset
```python theme={"system"}
def create_dataset(
self,
name: str,
private: bool = False,
**kwargs: Any
):
```
Creates a new dataset on the Hugging Face Hub.
**Parameters:**
* **name** (str): The name of the dataset.
* **private** (bool): Whether the dataset should be private. defaults to False.
* **kwargs** (Any): Additional keyword arguments.
**Returns:**
str: The URL of the created dataset.
### list\_datasets
```python theme={"system"}
def list_datasets(
self,
username: str,
limit: int = 100,
**kwargs: Any
):
```
Lists all datasets for the current user.
**Parameters:**
* **username** (str): The username of the user whose datasets to list.
* **limit** (int): The maximum number of datasets to list. (default: :obj:`100`)
* **kwargs** (Any): Additional keyword arguments.
**Returns:**
List\[str]: A list of dataset ids.
### delete\_dataset
```python theme={"system"}
def delete_dataset(self, dataset_name: str, **kwargs: Any):
```
Deletes a dataset from the Hugging Face Hub.
**Parameters:**
* **dataset\_name** (str): The name of the dataset to delete.
* **kwargs** (Any): Additional keyword arguments.
### add\_records
```python theme={"system"}
def add_records(
self,
dataset_name: str,
records: List[Record],
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Adds records to a dataset on the Hugging Face Hub.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **records** (List\[Record]): A list of records to add to the dataset.
* **filepath** (str): The path to the file containing the records.
* **kwargs** (Any): Additional keyword arguments.
### update\_records
```python theme={"system"}
def update_records(
self,
dataset_name: str,
records: List[Record],
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Updates records in a dataset on the Hugging Face Hub.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **records** (List\[Record]): A list of records to update in the dataset.
* **filepath** (str): The path to the file containing the records.
* **kwargs** (Any): Additional keyword arguments.
### delete\_record
```python theme={"system"}
def delete_record(
self,
dataset_name: str,
record_id: str,
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Deletes a record from the dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **record\_id** (str): The ID of the record to delete.
* **filepath** (str): The path to the file containing the records.
* **kwargs** (Any): Additional keyword arguments.
### list\_records
```python theme={"system"}
def list_records(
self,
dataset_name: str,
filepath: str = 'records/records.json',
**kwargs: Any
):
```
Lists all records in a dataset.
**Parameters:**
* **dataset\_name** (str): The name of the dataset.
* **filepath** (str): The path to the file containing the records.
* **kwargs** (Any): Additional keyword arguments.
**Returns:**
List\[Record]: A list of records in the dataset.
### \_download\_records
```python theme={"system"}
def _download_records(
self,
dataset_name: str,
filepath: str,
**kwargs: Any
):
```
### \_upload\_records
```python theme={"system"}
def _upload_records(
self,
records: List[Record],
dataset_name: str,
filepath: str,
**kwargs: Any
):
```
### \_upload\_file
```python theme={"system"}
def _upload_file(
self,
file_content: str,
dataset_name: str,
filepath: str,
file_type: str = 'json',
**kwargs: Any
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.datasets.base_generator
## BaseGenerator
```python theme={"system"}
class BaseGenerator(ABC, IterableDataset):
```
Abstract base class for data generators.
This class defines the interface for generating synthetic datapoints.
Concrete implementations should provide specific generation strategies.
### **init**
```python theme={"system"}
def __init__(
self,
seed: int = 42,
buffer: int = 20,
cache: Union[str, Path, None] = None,
data_path: Union[str, Path, None] = None,
**kwargs
):
```
Initialize the base generator.
**Parameters:**
* **seed** (int): Random seed for reproducibility. (default: :obj:`42`) (default: 42)
* **buffer** (int): Amount of DataPoints to be generated when the iterator runs out of DataPoints in data. (default: :obj:`20`)
* **cache** (Union\[str, Path, None]): Optional path to save generated datapoints during iteration. If None is provided, datapoints will be discarded every 100 generations.
* **data\_path** (Union\[str, Path, None]): Optional path to a JSONL file to initialize the dataset from. \*\*kwargs: Additional generator parameters.
### **aiter**
```python theme={"system"}
def __aiter__(self):
```
Async iterator that yields datapoints dynamically.
If a `data_path` was provided during initialization, those datapoints
are yielded first. When self.\_data is empty, 20 new datapoints
are generated. Every 100 yields, the batch is appended to the
JSONL file or discarded if `cache` is None.
Yields:
DataPoint: A single datapoint.
### **iter**
```python theme={"system"}
def __iter__(self):
```
Synchronous iterator for PyTorch IterableDataset compatibility.
If a `data_path` was provided during initialization, those datapoints
are yielded first. When self.\_data is empty, 20 new datapoints
are generated. Every 100 yields, the batch is appended to the
JSONL file or discarded if `cache` is None.
Yields:
DataPoint: A single datapoint.
### sample
```python theme={"system"}
def sample(self):
```
**Returns:**
DataPoint: The next DataPoint.
**Note:**
This method is intended for synchronous contexts.
Use 'async\_sample' in asynchronous contexts to
avoid blocking or runtime errors.
### save\_to\_jsonl
```python theme={"system"}
def save_to_jsonl(self, file_path: Union[str, Path]):
```
Saves the generated datapoints to a JSONL (JSON Lines) file.
Each datapoint is stored as a separate JSON object on a new line.
**Parameters:**
* **file\_path** (Union\[str, Path]): Path to save the JSONL file.
**Note:**
* Uses `self._data`, which contains the generated datapoints.
* Appends to the file if it already exists.
* Ensures compatibility with large datasets by using JSONL format.
### flush
```python theme={"system"}
def flush(self, file_path: Union[str, Path]):
```
Flush the current data to a JSONL file and clear the data.
**Parameters:**
* **file\_path** (Union\[str, Path]): Path to save the JSONL file.
**Note:**
* Uses `save_to_jsonl` to save `self._data`.
### \_init\_from\_jsonl
```python theme={"system"}
def _init_from_jsonl(self, file_path: Path):
```
Load and parse a dataset from a JSONL file.
**Parameters:**
* **file\_path** (Path): Path to the JSONL file.
**Returns:**
List\[Dict\[str, Any]]: A list of datapoint dictionaries.
# null
Source: https://docs.camel-ai.org/reference/camel.datasets.few_shot_generator
## FewShotGenerator
```python theme={"system"}
class FewShotGenerator(BaseGenerator):
```
A generator for creating synthetic datapoints using few-shot learning.
This class leverages a seed dataset, an agent, and a verifier to generate
new synthetic datapoints on demand through few-shot prompting.
### **init**
```python theme={"system"}
def __init__(
self,
seed_dataset: StaticDataset,
verifier: BaseVerifier,
model: BaseModelBackend,
seed: int = 42,
**kwargs
):
```
Initialize the few-shot generator.
**Parameters:**
* **seed\_dataset** (StaticDataset): Validated static dataset to use for examples.
* **verifier** (BaseVerifier): Verifier to validate generated content.
* **model** (BaseModelBackend): The underlying LLM that the generating agent will be initiated with.
* **seed** (int): Random seed for reproducibility. (default: :obj:`42`) \*\*kwargs: Additional generator parameters. (default: 42)
### \_validate\_seed\_dataset
```python theme={"system"}
def _validate_seed_dataset(self):
```
### \_construct\_prompt
```python theme={"system"}
def _construct_prompt(self, examples: List[DataPoint]):
```
Construct a prompt for generating new datapoints
using a fixed sample of examples from the seed dataset.
**Parameters:**
* **examples** (List\[DataPoint]): Examples to include in the prompt.
**Returns:**
str: Formatted prompt with examples.
# null
Source: https://docs.camel-ai.org/reference/camel.datasets.models
## DataPoint
```python theme={"system"}
class DataPoint(BaseModel):
```
A single data point in the dataset.
**Parameters:**
* **question** (str): The primary question or issue to be addressed.
* **final\_answer** (str): The final answer.
* **rationale** (Optional\[str]): Logical reasoning or explanation behind the answer. (default: :obj:`None`)
* **metadata** (Optional\[Dict\[str, Any]]): Additional metadata about the data point. (default: :obj:`None`)
### to\_dict
```python theme={"system"}
def to_dict(self):
```
**Returns:**
Dict\[str, Any]: Dictionary representation of the DataPoint.
### from\_dict
```python theme={"system"}
def from_dict(cls, data: Dict[str, Any]):
```
Create a DataPoint from a dictionary.
**Parameters:**
* **data** (Dict\[str, Any]): Dictionary containing DataPoint fields.
**Returns:**
DataPoint: New DataPoint instance.
# null
Source: https://docs.camel-ai.org/reference/camel.datasets.self_instruct_generator
## SelfInstructGenerator
```python theme={"system"}
class SelfInstructGenerator(BaseGenerator):
```
A generator for creating synthetic datapoints using self-instruct.
It utilizes both a human-provided dataset (seed\_dataset) and generated
machine instructions (machine\_instructions) to produce new, synthetic
datapoints that include a question, a computed rationale (code), and a
final answer (from a verifier).
### **init**
```python theme={"system"}
def __init__(
self,
seed_dataset: StaticDataset,
verifier: BaseVerifier,
instruction_agent: Optional[ChatAgent] = None,
rationale_agent: Optional[ChatAgent] = None,
seed: int = 42,
**kwargs
):
```
Initialize the self-instruct generator.
**Parameters:**
* **seed\_dataset** (StaticDataset): Dataset containing seed instructions.
* **verifier** (BaseVerifier): Verifier instance to validate generated solutions.
* **instruction\_agent** (Optional\[ChatAgent]): Agent for generating instructions. If not provided, a default agent will be created.
* **rationale\_agent** (Optional\[ChatAgent]): Agent for generating rationales. If not provided, a default agent will be created.
* **seed** (int): Random seed for reproducibility. (default: :obj:`42`) \*\*kwargs: Additional keyword arguments passed to the BaseGenerator. (default: 42)
### default\_instruction\_agent
```python theme={"system"}
def default_instruction_agent(self):
```
**Returns:**
ChatAgent: An agent with the default instruction prompt.
### default\_rationale\_agent
```python theme={"system"}
def default_rationale_agent(self):
```
**Returns:**
ChatAgent: An agent with the rationale prompt
### format\_support\_block
```python theme={"system"}
def format_support_block(dp: DataPoint):
```
Format a DataPoint into a few-shot example block.
**Parameters:**
* **dp** (DataPoint): A data point.
**Returns:**
str: A formatted string containing the question and its
corresponding code block in Markdown-style Python format.
### generate\_new\_instruction
```python theme={"system"}
def generate_new_instruction(
self,
agent: ChatAgent,
support_human_dps: list[DataPoint],
support_machine_dps: list[DataPoint]
):
```
Generate a new instruction using self-instruct prompting.
**Parameters:**
* **agent** (ChatAgent): The agent to use for generating the instruction.
* **support\_human\_dps** (list\[DataPoint]): List of human examples to sample.
* **support\_machine\_dps** (list\[DataPoint]): List of machine examples to sample.
**Returns:**
str: The newly generated question.
### generate\_rationale
```python theme={"system"}
def generate_rationale(
self,
question: str,
agent: Optional[ChatAgent] = None,
support_human_dps: Optional[list[DataPoint]] = None
):
```
Generate rationale code (solution) for the given question.
**Parameters:**
* **question** (str): The question to be solved.
* **agent** (Optional\[ChatAgent]): The agent to use for generating the rationale. If None is provided, the default rationale agent will be used. (default: :obj:`None`)
* **support\_human\_dps** (Optional\[list\[DataPoint]]): List of human examples to sample. (default: :obj:`None`)
**Returns:**
str: The generated code solution as a string.
## QuestionSchema
```python theme={"system"}
class QuestionSchema(BaseModel):
```
Schema for the generated question.
**Parameters:**
* **question** (str): The question generated by the model.
## RationaleSchema
```python theme={"system"}
class RationaleSchema(BaseModel):
```
Schema for the generated rationale code.
**Parameters:**
* **code** (str): The generated code without any formatting.
# null
Source: https://docs.camel-ai.org/reference/camel.datasets.static_dataset
## StaticDataset
```python theme={"system"}
class StaticDataset(Dataset):
```
A static dataset containing a list of datapoints.
Ensures that all items adhere to the DataPoint schema.
This dataset extends :obj:`Dataset` from PyTorch and should
be used when its size is fixed at runtime.
This class can initialize from Hugging Face Datasets,
PyTorch Datasets, JSON file paths, or lists of dictionaries,
converting them into a consistent internal format.
### **init**
```python theme={"system"}
def __init__(
self,
data: Union[HFDataset, Dataset, Path, List[Dict[str, Any]]],
seed: int = 42,
min_samples: int = 1,
strict: bool = False,
**kwargs
):
```
Initialize the static dataset and validate integrity.
**Parameters:**
* **data** (Union\[HFDataset, Dataset, Path, List\[Dict\[str, Any]]]): Input data, which can be one of the following: - A Hugging Face Dataset (:obj:`HFDataset`). - A PyTorch Dataset (:obj:`torch.utils.data.Dataset`). - A :obj:`Path` object representing a JSON or JSONL file. - A list of dictionaries with :obj:`DataPoint`-compatible fields.
* **seed** (int): Random seed for reproducibility. (default: :obj:`42`)
* **min\_samples** (int): Minimum required number of samples. (default: :obj:`1`)
* **strict** (bool): Whether to raise an error on invalid datapoints (:obj:`True`) or skip/filter them (:obj:`False`). (default: :obj:`False`) \*\*kwargs: Additional dataset parameters.
### \_init\_data
```python theme={"system"}
def _init_data(
self,
data: Union[HFDataset, Dataset, Path, List[Dict[str, Any]]]
):
```
Convert input data from various formats into a list of
:obj:`DataPoint` instances.
**Parameters:**
* **data** (Union\[HFDataset, Dataset, Path, List\[Dict\[str, Any]]]): Input dataset in one of the supported formats.
**Returns:**
List\[DataPoint]: A list of validated :obj:`DataPoint`
instances.
### **len**
```python theme={"system"}
def __len__(self):
```
Return the size of the dataset.
### **getitem**
```python theme={"system"}
def __getitem__(self, idx: Union[int, slice]):
```
Retrieve a datapoint or a batch of datapoints by index or slice.
**Parameters:**
* **idx** (Union\[int, slice]): Index or slice of the datapoint(s).
**Returns:**
List\[DataPoint]: A list of `DataPoint` objects.
### sample
```python theme={"system"}
def sample(self):
```
**Returns:**
DataPoint: A randomly sampled :obj:`DataPoint`.
### metadata
```python theme={"system"}
def metadata(self):
```
**Returns:**
Dict\[str, Any]: A copy of the dataset metadata dictionary.
### \_init\_from\_hf\_dataset
```python theme={"system"}
def _init_from_hf_dataset(self, data: HFDataset):
```
Convert a Hugging Face dataset into a list of dictionaries.
**Parameters:**
* **data** (HFDataset): A Hugging Face dataset.
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries representing
the dataset, where each dictionary corresponds to a datapoint.
### \_init\_from\_pytorch\_dataset
```python theme={"system"}
def _init_from_pytorch_dataset(self, data: Dataset):
```
Convert a PyTorch dataset into a list of dictionaries.
**Parameters:**
* **data** (Dataset): A PyTorch dataset.
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries representing
the dataset.
### \_init\_from\_json\_path
```python theme={"system"}
def _init_from_json_path(self, data: Path):
```
Load and parse a dataset from a JSON file.
**Parameters:**
* **data** (Path): Path to the JSON file.
**Returns:**
List\[Dict\[str, Any]]: A list of datapoint dictionaries.
### \_init\_from\_jsonl\_path
```python theme={"system"}
def _init_from_jsonl_path(self, data: Path):
```
Load and parse a dataset from a JSONL file.
**Parameters:**
* **data** (Path): Path to the JSONL file.
**Returns:**
List\[Dict\[str, Any]]: A list of datapoint dictionaries.
### \_init\_from\_list
```python theme={"system"}
def _init_from_list(self, data: List[Dict[str, Any]]):
```
Validate and convert a list of dictionaries into a dataset.
**Parameters:**
* **data** (List\[Dict\[str, Any]]): A list of dictionaries where each dictionary must be a valid :obj:`DataPoint`.
**Returns:**
List\[Dict\[str, Any]]: The validated list of dictionaries.
### save\_to\_json
```python theme={"system"}
def save_to_json(self, file_path: Union[str, Path]):
```
Save the dataset to a local JSON file.
**Parameters:**
* **file\_path** (Union\[str, Path]): Path to the output JSON file. If a string is provided, it will be converted to a Path object.
### save\_to\_huggingface
```python theme={"system"}
def save_to_huggingface(
self,
dataset_name: str,
token: Optional[str] = None,
filepath: str = 'records/records.json',
private: bool = False,
description: Optional[str] = None,
license: Optional[str] = None,
version: Optional[str] = None,
tags: Optional[List[str]] = None,
language: Optional[List[str]] = None,
task_categories: Optional[List[str]] = None,
authors: Optional[List[str]] = None,
**kwargs: Any
):
```
Save the dataset to the Hugging Face Hub using the project's
HuggingFaceDatasetManager.
**Parameters:**
* **dataset\_name** (str): The name of the dataset on Hugging Face Hub. Should be in the format 'username/dataset\_name' .
* **token** (Optional\[str]): The Hugging Face API token. If not provided, the token will be read from the environment variable `HF_TOKEN` (default: :obj:`None`)
* **filepath** (str): The path in the repository where the dataset will be saved. (default: :obj:`"records/records.json"`)
* **private** (bool): Whether the dataset should be private. (default: :obj:`False`)
* **description** (Optional\[str]): A description of the dataset. (default: :obj:`None`)
* **license** (Optional\[str]): The license of the dataset. (default: :obj:`None`)
* **version** (Optional\[str]): The version of the dataset. (default: :obj:`None`)
* **tags** (Optional\[List\[str]]): A list of tags for the dataset. (default: :obj:`None`)
* **language** (Optional\[List\[str]]): A list of languages the dataset is in. (default: :obj:`None`)
* **task\_categories** (Optional\[List\[str]]): A list of task categories. (default: :obj:`None`)
* **authors** (Optional\[List\[str]]): A list of authors of the dataset. (default: :obj:`None`) \*\*kwargs (Any): Additional keyword arguments to pass to the Hugging Face API.
**Returns:**
str: The URL of the dataset on the Hugging Face Hub.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.azure_embedding
## AzureEmbedding
```python theme={"system"}
class AzureEmbedding:
```
Provides text embedding functionalities using Azure's OpenAI models.
**Parameters:**
* **model\_type** (EmbeddingModelType, optional): The model type to be used for text embeddings. (default: :obj:`TEXT_EMBEDDING_3_SMALL`)
* **url** (Optional\[str], optional): The url to the Azure OpenAI service. (default: :obj:`None`)
* **api\_key** (str, optional): The API key for authenticating with the Azure OpenAI service. (default: :obj:`None`)
* **api\_version** (str, optional): The API version for Azure OpenAI service. (default: :obj:`None`)
* **dimensions** (Optional\[int], optional): The text embedding output dimensions. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: EmbeddingModelType = EmbeddingModelType.TEXT_EMBEDDING_3_SMALL,
url: Union[str, None] = None,
api_key: Union[str, None] = None,
api_version: Union[str, None] = None,
dimensions: Union[int, None] = None
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Embeds a list of texts using the Azure OpenAI model.
**Parameters:**
* **objs** (list\[str]): The list of texts to embed. \*\*kwargs (Any): Additional keyword arguments to pass to the API.
**Returns:**
list\[list\[float]]: The embeddings for the input texts.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.base
## BaseEmbedding
```python theme={"system"}
class BaseEmbedding(ABC):
```
Abstract base class for text embedding functionalities.
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[T], **kwargs: Any):
```
Generates embeddings for the given texts.
**Parameters:**
* **objs** (list\[T]): The objects for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[list\[float]]: A list that represents the
generated embedding as a list of floating-point numbers.
### embed
```python theme={"system"}
def embed(self, obj: T, **kwargs: Any):
```
Generates an embedding for the given text.
**Parameters:**
* **obj** (T): The object for which to generate the embedding. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[float]: A list of floating-point numbers representing the
generated embedding.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.gemini_embedding
## GeminiEmbedding
```python theme={"system"}
class GeminiEmbedding:
```
Provides text embedding functionalities using Google's Gemini models.
**Parameters:**
* **model\_type** (EmbeddingModelType, optional): The model type to be used for text embeddings. (default: :obj:`GEMINI_EMBEDDING_EXP`)
* **api\_key** (str, optional): The API key for authenticating with the Gemini service. (default: :obj:`None`)
* **dimensions** (int, optional): The text embedding output dimensions. (default: :obj:`None`)
* **task\_type** (GeminiEmbeddingTaskType, optional): The task type for which to optimize the embeddings. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: EmbeddingModelType = EmbeddingModelType.GEMINI_EMBEDDING_EXP,
api_key: Optional[str] = None,
dimensions: Optional[int] = None,
task_type: Optional[GeminiEmbeddingTaskType] = None
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Generates embeddings for the given texts.
**Parameters:**
* **objs** (list\[str]): The texts for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.jina_embedding
## JinaEmbedding
```python theme={"system"}
class JinaEmbedding:
```
Provides text and image embedding functionalities using Jina AI's API.
**Parameters:**
* **model\_type** (EmbeddingModelType, optional): The model to use for embeddings. (default: :obj:`JINA_EMBEDDINGS_V3`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with Jina AI. (default: :obj:`None`)
* **dimensions** (Optional\[int], optional): The dimension of the output embeddings. (default: :obj:`None`)
* **embedding\_type** (Optional\[str], optional): The type of embedding format to generate. Options: 'int8' (binary encoding with higher storage and transfer efficiency), 'uint8' (unsigned binary encoding with higher storage and transfer efficiency), 'base64' (base64 string encoding with higher transfer efficiency). (default: :obj:`None`)
* **task** (Optional\[str], optional): The type of task for text embeddings.
* **Options**: retrieval.query, retrieval.passage, text-matching, classification, separation. (default: :obj:`None`)
* **late\_chunking** (bool, optional): If true, concatenates all sentences in input and treats as a single input. (default: :obj:`False`)
* **normalized** (bool, optional): If true, embeddings are normalized to unit L2 norm. (default: :obj:`False`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: EmbeddingModelType = EmbeddingModelType.JINA_EMBEDDINGS_V3,
api_key: Optional[str] = None,
dimensions: Optional[int] = None,
embedding_type: Optional[str] = None,
task: Optional[str] = None,
late_chunking: bool = False,
normalized: bool = False
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[Union[str, Image.Image]], **kwargs: Any):
```
Generates embeddings for the given texts or images.
**Parameters:**
* **objs** (list\[Union\[str, Image.Image]]): The texts or images for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API. Not used in this implementation.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.mistral_embedding
## MistralEmbedding
```python theme={"system"}
class MistralEmbedding:
```
Provides text embedding functionalities using Mistral's models.
**Parameters:**
* **model\_type** (EmbeddingModelType, optional): The model type to be used for text embeddings. (default: :obj:`MISTRAL_EMBED`)
* **api\_key** (str, optional): The API key for authenticating with the Mistral service. (default: :obj:`None`)
* **dimensions** (int, optional): The text embedding output dimensions. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: EmbeddingModelType = EmbeddingModelType.MISTRAL_EMBED,
api_key: str | None = None,
dimensions: int | None = None
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Generates embeddings for the given texts.
**Parameters:**
* **objs** (list\[str]): The texts for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.openai_compatible_embedding
## OpenAICompatibleEmbedding
```python theme={"system"}
class OpenAICompatibleEmbedding:
```
Provides text embedding functionalities supporting OpenAI
compatibility.
**Parameters:**
* **model\_type** (str): The model type to be used for text embeddings.
* **api\_key** (str): The API key for authenticating with the model service.
* **url** (str): The url to the model service.
* **output\_dim** (Optional\[int]): The dimensionality of the embedding vectors. If None, it will be determined during the first embedding call.
### **init**
```python theme={"system"}
def __init__(
self,
model_type: str,
api_key: Optional[str] = None,
url: Optional[str] = None,
output_dim: Optional[int] = None
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Generates embeddings for the given texts.
**Parameters:**
* **objs** (list\[str]): The texts for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.openai_embedding
## OpenAIEmbedding
```python theme={"system"}
class OpenAIEmbedding:
```
Provides text embedding functionalities using OpenAI's models.
**Parameters:**
* **model\_type** (EmbeddingModelType): The model type to be used for text embeddings. (default: :obj:`TEXT_EMBEDDING_3_SMALL`)
* **url** (Optional\[str]): The url to the OpenAI service. (default: :obj:`None`)
* **api\_key** (Optional\[str]): The API key for authenticating with the OpenAI service. (default: :obj:`None`)
* **dimensions** (Union\[int, NotGiven]): The text embedding output dimensions. (default: :obj:`NOT_GIVEN`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: EmbeddingModelType = EmbeddingModelType.TEXT_EMBEDDING_3_SMALL,
url: Optional[str] = None,
api_key: Optional[str] = None,
dimensions: Union[int, NotGiven] = NOT_GIVEN
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Generates embeddings for the given texts.
**Parameters:**
* **objs** (list\[str]): The texts for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.sentence_transformers_embeddings
## SentenceTransformerEncoder
```python theme={"system"}
class SentenceTransformerEncoder:
```
This class provides functionalities to generate text
embeddings using `Sentence Transformers`.
References:
[https://www.sbert.net/](https://www.sbert.net/)
### **init**
```python theme={"system"}
def __init__(self, model_name: str = 'intfloat/e5-large-v2', **kwargs):
```
Initializes the: obj: `SentenceTransformerEmbedding` class
with the specified transformer model.
**Parameters:**
* **model\_name** (str, optional): The name of the model to use. (default: :obj:`intfloat/e5-large-v2`) \*\*kwargs (optional): Additional arguments of :class:`SentenceTransformer`, such as :obj:`prompts` etc.
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Generates embeddings for the given texts using the model.
**Parameters:**
* **objs** (list\[str]): The texts for which to generate the embeddings.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embeddings.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.together_embedding
## TogetherEmbedding
```python theme={"system"}
class TogetherEmbedding:
```
Provides text embedding functionalities using Together AI's models.
**Parameters:**
* **model\_type** (str, optional): The model name to be used for text embeddings. (default: :obj:`togethercomputer/m2-bert-80M-8k-retrieval`)
* **api\_key** (str, optional): The API key for authenticating with the Together service. (default: :obj:`None`)
* **dimensions** (int, optional): The text embedding output dimensions. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: str = 'togethercomputer/m2-bert-80M-8k-retrieval',
api_key: Optional[str] = None,
dimensions: Optional[int] = None
):
```
### embed\_list
```python theme={"system"}
def embed_list(self, objs: list[str], **kwargs: Any):
```
Generates embeddings for the given texts.
**Parameters:**
* **objs** (list\[str]): The texts for which to generate the embeddings. \*\*kwargs (Any): Extra kwargs passed to the embedding API.
**Returns:**
list\[list\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.embeddings.vlm_embedding
## VisionLanguageEmbedding
```python theme={"system"}
class VisionLanguageEmbedding:
```
Provides image embedding functionalities using multimodal model.
**Parameters:**
* **model\_name**: The model type to be used for generating embeddings. And the default value is: obj:`openai/clip-vit-base-patch32`.
### **init**
```python theme={"system"}
def __init__(self, model_name: str = 'openai/clip-vit-base-patch32'):
```
Initializes the: obj: `VisionLanguageEmbedding` class with a
specified model and return the dimension of embeddings.
**Parameters:**
* **model\_name** (str, optional): The version name of the model to use. (default: :obj:`openai/clip-vit-base-patch32`)
### embed\_list
```python theme={"system"}
def embed_list(self, objs: List[Union[Image.Image, str]], **kwargs: Any):
```
Generates embeddings for the given images or texts.
**Parameters:**
* **objs** (List\[Image.Image|str]): The list of images or texts for which to generate the embeddings.
* **image\_processor\_kwargs**: Extra kwargs passed to the image processor.
* **tokenizer\_kwargs**: Extra kwargs passed to the text tokenizer (processor).
* **model\_kwargs**: Extra kwargs passed to the main model.
**Returns:**
List\[List\[float]]: A list that represents the generated embedding
as a list of floating-point numbers.
### get\_output\_dim
```python theme={"system"}
def get_output_dim(self):
```
**Returns:**
int: The dimensionality of the embedding for the current model.
# null
Source: https://docs.camel-ai.org/reference/camel.environments.models
## Action
```python theme={"system"}
class Action(BaseModel):
```
Represents an action taken in an environment.
This class defines the input context, the LLM-generated output, and
metadata required for verification and tracking within an RL
framework.
**Parameters:**
* **llm\_response** (str): The response generated by the LLM.
* **metadata** (Dict\[str, Any]): Additional metadata such as model parameters, prompt details, or response confidence scores.
* **timestamp** (datetime): The timestamp when the action was generated (UTC).
## Observation
```python theme={"system"}
class Observation(BaseModel):
```
Environment observation.
**Parameters:**
* **question**: The question posed to the LLM.
* **context**: Additional context for the question.
* **metadata**: Optional metadata about the observation.
## StepResult
```python theme={"system"}
class StepResult(BaseModel):
```
Result of an environment step.
**Parameters:**
* **observation**: The next observation.
* **reward**: Dictionary of reward scores for different aspects.
* **done**: Whether the episode is complete.
* **info**: Additional information about the step.
### as\_tuple
```python theme={"system"}
def as_tuple(self):
```
Returns all fields of the model as a tuple, in declaration order
# null
Source: https://docs.camel-ai.org/reference/camel.environments.multi_step
## MultiStepEnv
```python theme={"system"}
class MultiStepEnv(ABC):
```
A multi-step environment for reinforcement learning with LLMs.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: BaseExtractor,
max_steps: Optional[int] = None,
**kwargs
):
```
Initialize the environment.
**Parameters:**
* **extractor**: Extractor to process LLM responses.
* **max\_steps**: Maximum steps per episode. \*\*kwargs: Additional environment parameters.
### \_get\_initial\_state
```python theme={"system"}
def _get_initial_state(self):
```
### \_get\_next\_observation
```python theme={"system"}
def _get_next_observation(self):
```
### \_get\_terminal\_observation
```python theme={"system"}
def _get_terminal_observation(self):
```
### is\_done
```python theme={"system"}
def is_done(self):
```
**Returns:**
bool: A boolean flag.
### \_is\_done
```python theme={"system"}
def _is_done(self):
```
### metadata
```python theme={"system"}
def metadata(self):
```
**Returns:**
Dict\[str, Any]: A copy of the environment's metadata.
### current\_step
```python theme={"system"}
def current_step(self):
```
**Returns:**
int: The number of the step we are currently in.
# null
Source: https://docs.camel-ai.org/reference/camel.environments.rlcards_env
## ActionExtractor
```python theme={"system"}
class ActionExtractor(BaseExtractorStrategy):
```
A strategy for extracting RLCard actions from text.
### **init**
```python theme={"system"}
def __init__(self, action_pattern: str = '\\s*(.+)'):
```
Initialize the action extractor with a regex pattern.
**Parameters:**
* **action\_pattern** (str): The regex pattern to extract actions. (default: :obj:`"\\s*(.+)"`).
## RLCardsEnv
```python theme={"system"}
class RLCardsEnv(MultiStepEnv):
```
A base environment for RLCard games.
This environment implements a wrapper around RLCard environments for
reinforcement learning with LLMs. It handles the conversion between
RLCard states and actions and the CAMEL environment interface.
### **init**
```python theme={"system"}
def __init__(
self,
game_name: str,
extractor: Optional[BaseExtractor] = None,
max_steps: Optional[int] = None,
num_players: int = 2,
**kwargs
):
```
Initialize the RLCard environment.
**Parameters:**
* **game\_name** (str): The name of the RLCard game to play.
* **extractor** (Optional\[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor with ActionExtractor will be used. (default: :obj:`None`)
* **max\_steps** (Optional\[int]): Maximum steps per episode. (default: :obj:`None`)
* **num\_players** (int): Number of players in the game. (default: :obj:`2`) \*\*kwargs: Additional environment parameters.
### \_get\_initial\_state
```python theme={"system"}
def _get_initial_state(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing the initial state with
game state, player info, and game status flags.
### \_get\_next\_observation
```python theme={"system"}
def _get_next_observation(self):
```
**Returns:**
Observation: An Observation object containing the game state
description.
### \_get\_terminal\_observation
```python theme={"system"}
def _get_terminal_observation(self):
```
**Returns:**
Observation: An Observation object containing the final game state
description.
### \_is\_done
```python theme={"system"}
def _is_done(self):
```
**Returns:**
bool: True if the game is over, False otherwise.
### \_convert\_to\_rlcard\_action
```python theme={"system"}
def _convert_to_rlcard_action(self, action_str: str):
```
Convert a string action to the format expected by RLCard.
This method must be implemented by subclasses to handle the specific
action format of each game.
**Parameters:**
* **action\_str** (str): The string representation of the action.
**Returns:**
Any: The action in the format expected by the RLCard environment.
### \_format\_state\_for\_observation
```python theme={"system"}
def _format_state_for_observation(self, state: Dict[str, Any]):
```
Format the RLCard state for human-readable observation.
This method must be implemented by subclasses to create a
human-readable representation of the game state.
**Parameters:**
* **state** (Dict\[str, Any]): The RLCard state dictionary.
**Returns:**
str: A human-readable representation of the state.
### \_format\_legal\_actions
```python theme={"system"}
def _format_legal_actions(self, legal_actions: List[Any]):
```
Format the legal actions for human-readable observation.
This method must be implemented by subclasses to create a
human-readable representation of the legal actions.
**Parameters:**
* **legal\_actions** (List\[Any]): The list of legal actions.
**Returns:**
str: A human-readable representation of the legal actions.
## BlackjackEnv
```python theme={"system"}
class BlackjackEnv(RLCardsEnv):
```
A Blackjack environment for reinforcement learning with LLMs.
This environment implements a standard Blackjack game where the LLM agent
plays against a dealer.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
max_steps: Optional[int] = None,
**kwargs
):
```
Initialize the Blackjack environment.
**Parameters:**
* **extractor** (Optional\[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor will be used. (default: :obj:`None`)
* **max\_steps** (Optional\[int]): Maximum steps per episode. (default: :obj:`None`) \*\*kwargs: Additional environment parameters.
### \_convert\_to\_rlcard\_action
```python theme={"system"}
def _convert_to_rlcard_action(self, action_str: str):
```
Convert a string action to the format expected by RLCard Blackjack.
**Parameters:**
* **action\_str** (str): The string representation of the action. Expected to be 'hit' or 'stand'.
**Returns:**
int: 0 for 'hit', 1 for 'stand'.
### \_format\_state\_for\_observation
```python theme={"system"}
def _format_state_for_observation(self, state: Dict[str, Any]):
```
Format the Blackjack state for human-readable observation.
**Parameters:**
* **state** (Dict\[str, Any]): The RLCard state dictionary.
**Returns:**
str: A human-readable representation of the state.
### \_format\_legal\_actions
```python theme={"system"}
def _format_legal_actions(self, legal_actions: List[int]):
```
Format the legal actions for Blackjack.
**Parameters:**
* **legal\_actions** (List\[int]): The list of legal actions.
**Returns:**
str: A human-readable representation of the legal actions.
### \_format\_cards
```python theme={"system"}
def _format_cards(self, cards: List[str]):
```
Format a list of cards for display.
**Parameters:**
* **cards** (List\[str]): List of card strings.
**Returns:**
str: Formatted card string.
### \_calculate\_hand\_value
```python theme={"system"}
def _calculate_hand_value(self, cards: List[str]):
```
Calculate the value of a hand in Blackjack.
**Parameters:**
* **cards** (List\[str]): List of card strings.
**Returns:**
int: The value of the hand.
## LeducHoldemEnv
```python theme={"system"}
class LeducHoldemEnv(RLCardsEnv):
```
A Leduc Hold'em environment for reinforcement learning with LLMs.
This environment implements a Leduc Hold'em poker game where the LLM agent
plays against one or more opponents.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
max_steps: Optional[int] = None,
num_players: int = 2,
**kwargs
):
```
Initialize the Leduc Hold'em environment.
**Parameters:**
* **extractor** (Optional\[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor will be used. (default: :obj:`None`)
* **max\_steps** (Optional\[int]): Maximum steps per episode. (default: :obj:`None`)
* **num\_players** (int): Number of players in the game. (default: :obj:`2`) \*\*kwargs: Additional environment parameters.
### \_convert\_to\_rlcard\_action
```python theme={"system"}
def _convert_to_rlcard_action(self, action_str: str):
```
Convert a string action to the format expected by RLCard
Leduc Hold'em.
**Parameters:**
* **action\_str** (str): The string representation of the action. Expected to be 'fold', 'check', 'call', or 'raise'.
**Returns:**
int: 0 for 'fold', 1 for 'check/call', 2 for 'raise'.
### \_format\_state\_for\_observation
```python theme={"system"}
def _format_state_for_observation(self, state: Dict[str, Any]):
```
Format the Leduc Hold'em state for human-readable observation.
**Parameters:**
* **state** (Dict\[str, Any]): The RLCard state dictionary.
**Returns:**
str: A human-readable representation of the state.
### \_format\_legal\_actions
```python theme={"system"}
def _format_legal_actions(self, legal_actions: List[int]):
```
Format the legal actions for Leduc Hold'em.
**Parameters:**
* **legal\_actions** (List\[int]): The list of legal actions.
**Returns:**
str: A human-readable representation of the legal actions.
## DoudizhuEnv
```python theme={"system"}
class DoudizhuEnv(RLCardsEnv):
```
A Doudizhu environment for reinforcement learning with LLMs.
This environment implements a standard Doudizhu game where the LLM agent
plays against two AI opponents.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
max_steps: Optional[int] = None,
**kwargs
):
```
Initialize the Doudizhu environment.
**Parameters:**
* **extractor** (Optional\[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor will be used. (default: :obj:`None`)
* **max\_steps** (Optional\[int]): Maximum steps per episode. (default: :obj:`None`) \*\*kwargs: Additional environment parameters.
### \_convert\_to\_rlcard\_action
```python theme={"system"}
def _convert_to_rlcard_action(self, action_str: str):
```
Convert a string action to the format expected by RLCard Doudizhu.
**Parameters:**
* **action\_str** (str): The string representation of the action. Expected to be a card combination or 'pass'.
**Returns:**
str: The action string in the format expected by RLCard.
### \_format\_state\_for\_observation
```python theme={"system"}
def _format_state_for_observation(self, state: Dict[str, Any]):
```
Format the Doudizhu state for human-readable observation.
**Parameters:**
* **state** (Dict\[str, Any]): The RLCard state dictionary.
**Returns:**
str: A human-readable representation of the state.
### \_format\_legal\_actions
```python theme={"system"}
def _format_legal_actions(self, legal_actions: List[str]):
```
Format the legal actions for Doudizhu.
**Parameters:**
* **legal\_actions** (List\[str]): The list of legal actions.
**Returns:**
str: A human-readable representation of the legal actions.
### \_format\_cards
```python theme={"system"}
def _format_cards(self, cards: List[str]):
```
Format a list of cards for display.
**Parameters:**
* **cards** (List\[str]): List of card strings.
**Returns:**
str: Formatted card string.
# null
Source: https://docs.camel-ai.org/reference/camel.environments.single_step
## SingleStepEnv
```python theme={"system"}
class SingleStepEnv:
```
A lightweight environment for single-step RL with LLMs as policy.
This environment models a single interaction between an LLM-based agent
and a problem drawn from a dataset—such as a question-answering or
math problem—where the agent produces one response and receives feedback.
Core Flow:
* A question is sampled from a (possibly infinitely long) dataset.
* The LLM generates a single-step response (the action).
* The response is verified against the ground truth.
* A reward is computed based on correctness and optional custom logic.
Key Features:
* Batched evaluation with per-sample state tracking.
* Async setup and teardown for verifiers and related resources.
* Supports deterministic sampling via local RNG (optional seed).
* Extensible reward computation via subclassing.
### **init**
```python theme={"system"}
def __init__(
self,
dataset: Union[StaticDataset, BaseGenerator],
verifier: BaseVerifier,
timeout: Optional[float] = 180.0,
**kwargs
):
```
Initialize the SingleStepEnv.
**Parameters:**
* **dataset** (Union\[StaticDataset, BaseGenerator]): Dataset to sample problems from.
* **verifier** (BaseVerifier): Verifier used to evaluate LLM responses against ground-truth answers.
* **timeout** (Optional\[float], optional): The execution timeout in seconds. (default: :obj:`180.0`) \*\*kwargs: Optional metadata or configuration values.
**Note:**
This class assumes all interactions are single-step: one question,
one LLM response, one reward.
### \_normalize\_actions
```python theme={"system"}
def _normalize_actions(self, action: Union[Action, List[Action], str, Dict[int, str]]):
```
Normalize the user-provided action(s) into a validated list
of `Action` objects.
This method handles flexibility in input format by converting
raw strings (only allowed when batch size is 1) and dictionaries,
ensuring all necessary structure and integrity checks on
actions (e.g., index bounds, duplicates).
**Parameters:**
* **action** (Union\[Action, List\[Action], str]): The raw input action(s) provided by the agent. Can be: - A single `Action` object. - A list of `Action` objects. - A raw string (if `batch_size == 1`), auto-wrapped in an `Action`. - A dict mapping int indices to str responses
**Returns:**
List\[Action]: A list of validated `Action` instances
ready for evaluation.
### \_batch\_done
```python theme={"system"}
def _batch_done(self):
```
**Returns:**
bool: True if all states are marked as done, False otherwise.
### \_batch\_started
```python theme={"system"}
def _batch_started(self):
```
**Returns:**
bool: True if at least one state is marked as done, False
otherwise.
### metadata
```python theme={"system"}
def metadata(self):
```
**Returns:**
Dict\[str, Any]: A copy of the environment's metadata.
# null
Source: https://docs.camel-ai.org/reference/camel.environments.tic_tac_toe
## MoveExtractor
```python theme={"system"}
class MoveExtractor(BaseExtractorStrategy):
```
A strategy for extracting Tic Tac Toe actions from text.
## Opponent
```python theme={"system"}
class Opponent:
```
AI opponent for the Tic Tac Toe game.
This class implements different playing strategies for the AI opponent,
including an optimal strategy using the minimax algorithm with alpha-beta
pruning, and a random strategy.
### **init**
```python theme={"system"}
def __init__(self, play_style: Literal['optimal', 'random'] = 'optimal'):
```
Initialize the opponent with a specific play style.
**Parameters:**
* **play\_style** (`Literal["optimal", "random"]`): The strategy to use, either "optimal" or "random". (default: :obj:`"optimal"`)
### select\_move
```python theme={"system"}
def select_move(self, board: List[str]):
```
Select a move based on the opponent's play style.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
**Returns:**
Optional\[int]: The index of the selected move, or None if no move
is available.
### get\_optimal\_move
```python theme={"system"}
def get_optimal_move(self, board: List[str]):
```
Get the optimal move using the minimax algorithm.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
**Returns:**
Optional\[int]: The index of the optimal move, or None if no move
is available.
### minimax
```python theme={"system"}
def minimax(
self,
board: List[str],
is_maximizing: bool,
depth: int = 0,
alpha: float = -math.inf,
beta: float = math.inf
):
```
Minimax algorithm with alpha-beta pruning for optimal move
selection.
Recursively evaluates all possible moves to find the best one.
Uses alpha-beta pruning to reduce the search space.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
* **is\_maximizing** (bool): True if maximizing player (O), False if minimizing (X).
* **depth** (int): Current depth in the search tree. (default: :obj:`0`) (default: 0)
* **alpha** (float): Alpha value for pruning. (default: :obj:`-math.inf`) (default: -math.inf)
* **beta** (float): Beta value for pruning. (default: :obj:`math.inf`) (default: math.inf)
**Returns:**
Tuple\[float, Optional\[int]]: A tuple containing:
* float: The score of the best move (1 for O win, -1 for X
win, 0 for draw)
* Optional\[int]: The index of the best move, or None if
terminal state
## TicTacToeEnv
```python theme={"system"}
class TicTacToeEnv(MultiStepEnv):
```
A Tic Tac Toe environment for reinforcement learning with LLMs.
This environment implements a standard Tic Tac Toe game where the LLM agent
plays as 'X' against an AI opponent that plays as 'O'. The opponent can use
either an optimal strategy (minimax with alpha-beta pruning) or a random
strategy.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
max_steps: Optional[int] = None,
play_style: Literal['optimal', 'random'] = 'optimal',
**kwargs
):
```
Initialize the Tic Tac Toe environment.
**Parameters:**
* **extractor** (Optional\[BaseExtractor]): Extractor to process LLM responses. If None, a default extractor with MoveExtractor will be used. (default: :obj:`None`)
* **max\_steps** (Optional\[int]): Maximum steps per episode. (default: :obj:`None`)
* **play\_style** (`Literal["optimal", "random"]`): The strategy for the opponent to use, either "optimal" or "random". (default: :obj:`"optimal"`) \*\*kwargs: Additional environment parameters.
### \_get\_initial\_state
```python theme={"system"}
def _get_initial_state(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing the initial state with an
empty board, game status flags, and move history.
### \_get\_next\_observation
```python theme={"system"}
def _get_next_observation(self):
```
**Returns:**
Observation: An Observation object containing the game state
description.
### \_get\_terminal\_observation
```python theme={"system"}
def _get_terminal_observation(self):
```
**Returns:**
Observation: An Observation object containing the final game state
description.
### evaluate\_position\_for\_x
```python theme={"system"}
def evaluate_position_for_x(
board: List[str],
is_x_turn: bool,
depth: int = 0,
max_depth: int = 10
):
```
Evaluate the current board position from X's perspective.
Uses minimax to determine the value of the position.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
* **is\_x\_turn** (bool): True if it's X's turn to move, False otherwise.
**Returns:**
float: A float value representing the position evaluation:
* 1.0 if X has a winning position
* 0.0 if O has a winning position
* 0.5 for a draw
* For ongoing positions, returns the expected outcome with
perfect play
### \_is\_done
```python theme={"system"}
def _is_done(self):
```
**Returns:**
True if the game is over, False otherwise.
### available\_moves
```python theme={"system"}
def available_moves(board: List[str]):
```
Get all available moves on the board.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
**Returns:**
List\[int]: A list of indices representing empty cells on the board.
### check\_winner
```python theme={"system"}
def check_winner(board: List[str]):
```
Check if there is a winner or a draw on the board.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
**Returns:**
Optional\[Literal\["X", "O", "draw"]]: "X" if X has won, "O" if O
has won, "draw" if the game is a draw, or None if the game is
still ongoing.
### render\_board
```python theme={"system"}
def render_board(self, board: List[str]):
```
Render the board as a string for display.
**Parameters:**
* **board** (List\[str]): The current game board as a list of strings.
**Returns:**
str: A formatted string representation of the board.
# null
Source: https://docs.camel-ai.org/reference/camel.extractors.base
## BaseExtractorStrategy
```python theme={"system"}
class BaseExtractorStrategy(ABC):
```
Abstract base class for extraction strategies.
## BaseExtractor
```python theme={"system"}
class BaseExtractor:
```
Base class for response extractors with a fixed strategy pipeline.
This extractor:
* Uses a **fixed multi-stage pipeline** of extraction strategies.
* Tries **each strategy in order** within a stage until one succeeds.
* Feeds the **output of one stage into the next** for processing.
* Supports **async execution** for efficient processing.
* Provides **batch processing and resource monitoring** options.
### **init**
```python theme={"system"}
def __init__(
self,
pipeline: List[List[BaseExtractorStrategy]],
cache_templates: bool = True,
max_cache_size: int = 1000,
extraction_timeout: float = 30.0,
batch_size: int = 10,
monitoring_interval: float = 5.0,
cpu_threshold: float = 80.0,
memory_threshold: float = 85.0,
**kwargs
):
```
Initialize the extractor with a multi-stage strategy pipeline.
**Parameters:**
* **pipeline** (List\[List\[BaseExtractorStrategy]]): A fixed list of lists where each list represents a stage containing extractor strategies executed in order.
* **cache\_templates** (bool): Whether to cache extraction templates. (default: :obj:`True`)
* **max\_cache\_size** (int): Maximum number of templates to cache. (default: :obj:`1000`)
* **extraction\_timeout** (float): Maximum time for extraction in seconds. (default: :obj:`30.0`)
* **batch\_size** (int): Size of batches for parallel extraction. (default: :obj:`10`)
* **monitoring\_interval** (float): Interval in seconds between resource checks. (default: :obj:`5.0`)
* **cpu\_threshold** (float): CPU usage percentage threshold for scaling down. (default: :obj:`80.0`)
* **memory\_threshold** (float): Memory usage percentage threshold for scaling down. (default: :obj:`85.0`) \*\*kwargs: Additional extractor parameters.
# null
Source: https://docs.camel-ai.org/reference/camel.extractors.python_strategies
## BoxedStrategy
```python theme={"system"}
class BoxedStrategy(BaseExtractorStrategy):
```
Extracts content from \boxed\{} and \boxed\{} environments.
## PythonListStrategy
```python theme={"system"}
class PythonListStrategy(BaseExtractorStrategy):
```
Extracts and normalizes Python lists.
## PythonDictStrategy
```python theme={"system"}
class PythonDictStrategy(BaseExtractorStrategy):
```
Extracts and normalizes Python dictionaries.
## PythonSetStrategy
```python theme={"system"}
class PythonSetStrategy(BaseExtractorStrategy):
```
Extracts and normalizes Python sets.
## PythonTupleStrategy
```python theme={"system"}
class PythonTupleStrategy(BaseExtractorStrategy):
```
Extracts and normalizes Python tuples.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.base
## BaseInterpreter
```python theme={"system"}
class BaseInterpreter(ABC):
```
An abstract base class for code interpreters.
### run
```python theme={"system"}
def run(self, code: str, code_type: str):
```
Executes the given code based on its type.
**Parameters:**
* **code** (str): The code to be executed.
* **code\_type** (str): The type of the code, which must be one of the types returned by `supported_code_types()`.
**Returns:**
str: The result of the code execution. If the execution fails, this
should include sufficient information to diagnose and correct
the issue.
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
Provides supported code types by the interpreter.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates action space for *python* interpreter
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Executes a command in the interpreter.
**Parameters:**
* **command** (str): The command to execute.
**Returns:**
Tuple\[str, str]: A tuple containing the stdout and stderr of the
command execution.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.docker_interpreter
## DockerInterpreter
```python theme={"system"}
class DockerInterpreter(BaseInterpreter):
```
A class for executing code files or code strings in a docker container.
This class handles the execution of code in different scripting languages
(currently Python and Bash) within a docker container, capturing their
stdout and stderr streams, and allowing user checking before executing code
strings.
**Parameters:**
* **require\_confirm** (bool, optional): If `True`, prompt user before running code strings for security. Defaults to `True`.
* **print\_stdout** (bool, optional): If `True`, print the standard output of the executed code. Defaults to `False`.
* **print\_stderr** (bool, optional): If `True`, print the standard error of the executed code. Defaults to `True`.
### **init**
```python theme={"system"}
def __init__(
self,
require_confirm: bool = True,
print_stdout: bool = False,
print_stderr: bool = True
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Destructor for the DockerInterpreter class.
This method ensures that the Docker container is removed when the
interpreter is deleted.
### \_initialize\_if\_needed
```python theme={"system"}
def _initialize_if_needed(self):
```
### \_create\_file\_in\_container
```python theme={"system"}
def _create_file_in_container(self, content: str):
```
### \_run\_file\_in\_container
```python theme={"system"}
def _run_file_in_container(self, file: Path, code_type: str):
```
### cleanup
```python theme={"system"}
def cleanup(self):
```
Explicitly stops and removes the Docker container.
This method should be called when you're done with the interpreter
to ensure proper cleanup of Docker resources.
### run
```python theme={"system"}
def run(self, code: str, code_type: str = 'python'):
```
Executes the given code in the container attached to the
interpreter, and captures the stdout and stderr streams.
**Parameters:**
* **code** (str): The code string to execute.
* **code\_type** (str): The type of code to execute (e.g., 'python', 'bash'). (default: obj:`python`)
**Returns:**
str: A string containing the captured stdout and stderr of the
executed code.
### \_check\_code\_type
```python theme={"system"}
def _check_code_type(self, code_type: str):
```
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
Provides supported code types by the interpreter.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates action space for *python* interpreter
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Executes a command in the Docker container and returns its output.
**Parameters:**
* **command** (str): The command to execute in the container.
**Returns:**
str: A string containing the captured stdout and stderr of the
executed command.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.e2b_interpreter
## E2BInterpreter
```python theme={"system"}
class E2BInterpreter(BaseInterpreter):
```
E2B Code Interpreter implementation.
**Parameters:**
* **require\_confirm** (bool, optional): If True, prompt user before running code strings for security. (default: :obj:`True`) Environment Variables:
* **E2B\_API\_KEY**: The API key for authenticating with the E2B service.
* **E2B\_DOMAIN**: The base URL for the E2B API. If not provided, will use the default E2B endpoint.
### **init**
```python theme={"system"}
def __init__(self, require_confirm: bool = True):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Destructor for the E2BInterpreter class.
This method ensures that the e2b sandbox is killed when the
interpreter is deleted.
### run
```python theme={"system"}
def run(self, code: str, code_type: str = 'python'):
```
Executes the given code in the e2b sandbox.
**Parameters:**
* **code** (str): The code string to execute.
* **code\_type** (str): The type of code to execute (e.g., 'python', 'bash'). (default: obj:`python`)
**Returns:**
str: The string representation of the output of the executed code.
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
Provides supported code types by the interpreter.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates action space for *python* interpreter
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Execute a command can be used to resolve the dependency of the
code.
**Parameters:**
* **command** (str): The command to execute.
**Returns:**
str: The output of the command.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.internal_python_interpreter
## InternalPythonInterpreter
```python theme={"system"}
class InternalPythonInterpreter(BaseInterpreter):
```
A customized python interpreter to control the execution of
LLM-generated codes. The interpreter makes sure the code can only execute
functions given in action space and import white list. It also supports
fuzzy variable matching to retrieve uncertain input variable name.
.. highlight:: none
This class is adapted from the hugging face implementation
\[python\_interpreter.py]\([https://github.com/huggingface/transformers/blob/8f](https://github.com/huggingface/transformers/blob/8f)
093fb799246f7dd9104ff44728da0c53a9f67a/src/transformers/tools/python\_interp
reter.py). The original license applies::
Copyright 2023 The HuggingFace Inc. team. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied. See the License for the specific language governing
permissions and limitations under the License.
We have modified the original code to suit our requirements. We have
encapsulated the original functions within a class and saved the
interpreter state after execution. We have added support for "import"
statements, "for" statements, and several binary and unary operators. We
have added import white list to keep `import` statement safe. Additionally,
we have modified the variable matching logic and introduced the
:obj:`fuzz_state` for fuzzy matching.
Modifications copyright (C) 2023 CAMEL-AI.org
**Parameters:**
* **action\_space** (Dict\[str, Any], optional): A dictionary that maps action names to their corresponding functions or objects. The interpreter can only execute functions that are either directly listed in this dictionary or are member functions of objects listed in this dictionary. The concept of :obj:`action_space` is derived from EmbodiedAgent, representing the actions that an agent is capable of performing. If `None`, set to empty dict. (default: :obj:`None`)
* **import\_white\_list** (List\[str], optional): A list that stores the Python modules or functions that can be imported in the code. All submodules and functions of the modules listed in this list are importable. Any other import statements will be rejected. The module and its submodule or function name are separated by a period (:obj:`.`). (default: :obj:`None`)
* **unsafe\_mode** (bool, optional): If `True`, the interpreter runs the code by `eval()` or `exec()` without any security check. (default: :obj:`False`)
* **raise\_error** (bool, optional): Raise error if the interpreter fails. (default: :obj:`False`)
* **allow\_builtins** (bool, optional): If `True`, safe built-in functions like print, len, str, etc. are added to the action space. (default: :obj:`True`)
### **init**
```python theme={"system"}
def __init__(
self,
action_space: Optional[Dict[str, Any]] = None,
import_white_list: Optional[List[str]] = None,
unsafe_mode: bool = False,
raise_error: bool = False,
allow_builtins: bool = True
):
```
### \_add\_safe\_builtins
```python theme={"system"}
def _add_safe_builtins(self):
```
Add safe built-in functions to the action space.
### run
```python theme={"system"}
def run(self, code: str, code_type: str = 'python'):
```
Executes the given code with specified code type in the
interpreter.
This method takes a string of code and its type, checks if the code
type is supported, and then executes the code. If `unsafe_mode` is
set to `False`, the code is executed in a controlled environment using
the `execute` method. If `unsafe_mode` is `True`, the code is executed
using `eval()` or `exec()` with the action space as the global context.
An `InterpreterError` is raised if the code type is unsupported or if
any runtime error occurs during execution.
**Parameters:**
* **code** (str): The python code to be executed.
* **code\_type** (str): The type of the code, which should be one of the supported code types (`python`, `py`, `python3`, `python2`). (default: obj:`python`)
**Returns:**
str: The string representation of the output of the executed code.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates action space for *python* interpreter.
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
Provides supported code types by the interpreter.
### execute
```python theme={"system"}
def execute(
self,
code: str,
state: Optional[Dict[str, Any]] = None,
fuzz_state: Optional[Dict[str, Any]] = None,
keep_state: bool = True
):
```
Execute the input python codes in a security environment.
**Parameters:**
* **code** (str): Generated python code to be executed.
* **state** (Optional\[Dict\[str, Any]], optional): External variables that may be used in the generated code. (default: :obj:`None`)
* **fuzz\_state** (Optional\[Dict\[str, Any]], optional): External variables that do not have certain variable names. The interpreter will use fuzzy matching to access these variables. For example, if :obj:`fuzz_state` has a variable :obj:`image`, the generated code can use :obj:`input_image` to access it. (default: :obj:`None`)
* **keep\_state** (bool, optional): If :obj:`True`, :obj:`state` and :obj:`fuzz_state` will be kept for later execution. Otherwise, they will be cleared. (default: :obj:`True`)
**Returns:**
Any: The value of the last statement (excluding "import") in the
code. For this interpreter, the value of an expression is its
value, the value of an "assign" statement is the assigned
value, and the value of an "if" and "for" block statement is
the value of the last statement in the block.
### clear\_state
```python theme={"system"}
def clear_state(self):
```
Initialize :obj:`state` and :obj:`fuzz_state`.
### \_execute\_ast
```python theme={"system"}
def _execute_ast(self, expression: ast.AST):
```
### \_execute\_assign
```python theme={"system"}
def _execute_assign(self, assign: ast.Assign):
```
### \_assign
```python theme={"system"}
def _assign(self, target: ast.expr, value: Any):
```
### \_execute\_call
```python theme={"system"}
def _execute_call(self, call: ast.Call):
```
### \_execute\_subscript
```python theme={"system"}
def _execute_subscript(self, subscript: ast.Subscript):
```
### \_execute\_name
```python theme={"system"}
def _execute_name(self, name: ast.Name):
```
### \_execute\_condition
```python theme={"system"}
def _execute_condition(self, condition: ast.Compare):
```
### \_execute\_if
```python theme={"system"}
def _execute_if(self, if_statement: ast.If):
```
### \_execute\_for
```python theme={"system"}
def _execute_for(self, for_statement: ast.For):
```
### \_execute\_import
```python theme={"system"}
def _execute_import(self, import_module: ast.Import):
```
### \_execute\_import\_from
```python theme={"system"}
def _execute_import_from(self, import_from: ast.ImportFrom):
```
### \_validate\_import
```python theme={"system"}
def _validate_import(self, full_name: str):
```
### \_execute\_binop
```python theme={"system"}
def _execute_binop(self, binop: ast.BinOp):
```
### \_execute\_unaryop
```python theme={"system"}
def _execute_unaryop(self, unaryop: ast.UnaryOp):
```
### \_get\_value\_from\_state
```python theme={"system"}
def _get_value_from_state(self, key: str):
```
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Execute a command in the internal python interpreter.
**Parameters:**
* **command** (str): The command to execute.
**Returns:**
tuple: A tuple containing the stdout and stderr of the command.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.ipython_interpreter
## JupyterKernelInterpreter
```python theme={"system"}
class JupyterKernelInterpreter(BaseInterpreter):
```
A class for executing code strings in a Jupyter Kernel.
**Parameters:**
* **require\_confirm** (bool, optional): If `True`, prompt user before running code strings for security. Defaults to `True`.
* **print\_stdout** (bool, optional): If `True`, print the standard output of the executed code. Defaults to `False`.
* **print\_stderr** (bool, optional): If `True`, print the standard error of the executed code. Defaults to `True`.
### **init**
```python theme={"system"}
def __init__(
self,
require_confirm: bool = True,
print_stdout: bool = False,
print_stderr: bool = True
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up the kernel and client.
### \_initialize\_if\_needed
```python theme={"system"}
def _initialize_if_needed(self):
```
Initialize the kernel manager and client if they are not already
initialized.
### \_clean\_ipython\_output
```python theme={"system"}
def _clean_ipython_output(output: str):
```
Remove ANSI escape sequences from the output.
### \_execute
```python theme={"system"}
def _execute(self, code: str, timeout: float):
```
Execute the code in the Jupyter kernel and return the result.
### run
```python theme={"system"}
def run(self, code: str, code_type: str = 'python'):
```
Executes the given code in the Jupyter kernel.
**Parameters:**
* **code** (str): The code string to execute.
* **code\_type** (str): The type of code to execute (e.g., 'python', 'bash'). (default: obj:`python`)
**Returns:**
str: A string containing the captured result of the
executed code.
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Executes a shell command in the Jupyter kernel.
**Parameters:**
* **command** (str): The shell command to execute.
**Returns:**
str: A string containing the captured result of the
executed command.
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
**Returns:**
List\[str]: Supported code types.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates the action space for the interpreter.
**Parameters:**
* **action\_space** (Dict\[str, Any]): A dictionary representing the new or updated action space.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.microsandbox_interpreter
## MicrosandboxInterpreter
```python theme={"system"}
class MicrosandboxInterpreter(BaseInterpreter):
```
Microsandbox Code Interpreter implementation.
This interpreter provides secure code execution using microsandbox,
a self-hosted platform for secure execution of untrusted user/AI code.
It supports Python code execution via PythonSandbox, JavaScript/Node.js
code execution via NodeSandbox, and shell commands via the command
interface.
**Parameters:**
* **require\_confirm** (bool, optional): If True, prompt user before running code strings for security. (default: :obj:`True`)
* **server\_url** (str, optional): URL of the microsandbox server. If not provided, will use MSB\_SERVER\_URL environment variable, then fall back to [http://127.0.0.1:5555](http://127.0.0.1:5555). (default: :obj:`None`)
* **api\_key** (str, optional): API key for microsandbox authentication. If not provided, will use MSB\_API\_KEY environment variable. (default: :obj:`None`)
* **namespace** (str, optional): Namespace for the sandbox. (default: :obj:`"default"`)
* **sandbox\_name** (str, optional): Name of the sandbox instance. If not provided, a random name will be generated by the SDK. (default: :obj:`None`)
* **timeout** (int, optional): Default timeout for code execution in seconds. (default: :obj:`30`) Environment Variables:
* **MSB\_SERVER\_URL**: URL of the microsandbox server.
* **MSB\_API\_KEY**: API key for microsandbox authentication.
**Note:**
The SDK handles parameter priority as: user parameter > environment
variable > default value.
### **init**
```python theme={"system"}
def __init__(
self,
require_confirm: bool = True,
server_url: Optional[str] = None,
api_key: Optional[str] = None,
namespace: str = 'default',
sandbox_name: Optional[str] = None,
timeout: int = 30
):
```
### run
```python theme={"system"}
def run(self, code: str, code_type: str = 'python'):
```
Executes the given code in the microsandbox.
**Parameters:**
* **code** (str): The code string to execute.
* **code\_type** (str): The type of code to execute. Supported types: 'python', 'javascript', 'bash'. (default: :obj:`python`)
**Returns:**
str: The string representation of the output of the executed code.
### \_confirm\_execution
```python theme={"system"}
def _confirm_execution(self, execution_type: str):
```
Prompt user for confirmation before executing code or commands.
**Parameters:**
* **execution\_type** (str): Type of execution ('code' or 'command').
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
Provides supported code types by the interpreter.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates action space for interpreter.
**Parameters:**
* **action\_space**: Action space dictionary (unused in microsandbox).
**Note:**
Microsandbox doesn't support action space updates as it runs
in isolated environments for each execution.
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Execute a shell command in the microsandbox.
This method is designed for package management and system
administration tasks. It executes shell commands directly
using the microsandbox command interface.
**Parameters:**
* **command** (str): The shell command to execute (e.g., "pip install numpy", "ls -la", "apt-get update").
**Returns:**
Union\[str, Tuple\[str, str]]: The output of the command.
### **del**
```python theme={"system"}
def __del__(self):
```
Destructor for the MicrosandboxInterpreter class.
Microsandbox uses context managers for resource management,
so no explicit cleanup is needed.
# null
Source: https://docs.camel-ai.org/reference/camel.interpreters.subprocess_interpreter
## SubprocessInterpreter
```python theme={"system"}
class SubprocessInterpreter(BaseInterpreter):
```
SubprocessInterpreter is a class for executing code files or code
strings in a subprocess.
This class handles the execution of code in different scripting languages
(currently Python and Bash) within a subprocess, capturing their
stdout and stderr streams, and allowing user checking before executing code
strings.
**Parameters:**
* **require\_confirm** (bool, optional): If True, prompt user before running code strings for security. (default: :obj:`True`)
* **print\_stdout** (bool, optional): If True, print the standard output of the executed code. (default: :obj:`False`)
* **print\_stderr** (bool, optional): If True, print the standard error of the executed code. (default: :obj:`True`)
* **execution\_timeout** (int, optional): Maximum time in seconds to wait for code execution to complete. (default: :obj:`60`)
### **init**
```python theme={"system"}
def __init__(
self,
require_confirm: bool = True,
print_stdout: bool = False,
print_stderr: bool = True,
execution_timeout: int = 60
):
```
### run\_file
```python theme={"system"}
def run_file(self, file: Path, code_type: str = 'python'):
```
Executes a code file in a subprocess and captures its output.
**Parameters:**
* **file** (Path): The path object of the file to run.
* **code\_type** (str): The type of code to execute (e.g., 'python', 'bash'). (default: obj:`python`)
**Returns:**
str: A string containing the captured stdout and stderr of the
executed code.
### run
```python theme={"system"}
def run(self, code: str, code_type: str):
```
Generates a temporary file with the given code, executes it, and
deletes the file afterward.
**Parameters:**
* **code** (str): The code string to execute.
* **code\_type** (str): The type of code to execute (e.g., 'python', 'bash').
**Returns:**
str: A string containing the captured stdout and stderr of the
executed code.
### \_create\_temp\_file
```python theme={"system"}
def _create_temp_file(self, code: str, extension: str):
```
Creates a temporary file with the given code and extension.
**Parameters:**
* **code** (str): The code to write to the temporary file.
* **extension** (str): The file extension to use.
**Returns:**
Path: The path to the created temporary file.
### \_check\_code\_type
```python theme={"system"}
def _check_code_type(self, code_type: str):
```
### supported\_code\_types
```python theme={"system"}
def supported_code_types(self):
```
Provides supported code types by the interpreter.
### update\_action\_space
```python theme={"system"}
def update_action_space(self, action_space: Dict[str, Any]):
```
Updates action space for *python* interpreter
### \_is\_command\_available
```python theme={"system"}
def _is_command_available(self, command: str):
```
Check if a command is available in the system PATH.
**Parameters:**
* **command** (str): The command to check.
**Returns:**
bool: True if the command is available, False otherwise.
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Executes a shell command in a subprocess and captures its output.
**Parameters:**
* **command** (str): The shell command to execute.
**Returns:**
tuple: A tuple containing the captured stdout and stderr of the
executed command.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.apify_reader
## Apify
```python theme={"system"}
class Apify:
```
Apify is a platform that allows you to automate any web workflow.
**Parameters:**
* **api\_key** (Optional\[str]): API key for authenticating with the Apify API.
### **init**
```python theme={"system"}
def __init__(self, api_key: Optional[str] = None):
```
### run\_actor
```python theme={"system"}
def run_actor(
self,
actor_id: str,
run_input: Optional[dict] = None,
content_type: Optional[str] = None,
build: Optional[str] = None,
max_items: Optional[int] = None,
memory_mbytes: Optional[int] = None,
timeout_secs: Optional[int] = None,
webhooks: Optional[list] = None,
wait_secs: Optional[int] = None
):
```
Run an actor on the Apify platform.
**Parameters:**
* **actor\_id** (str): The ID of the actor to run.
* **run\_input** (Optional\[dict]): The input data for the actor. Defaults to `None`.
* **content\_type** (str, optional): The content type of the input.
* **build** (str, optional): Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).
* **max\_items** (int, optional): Maximum number of results that will be returned by this run. If the Actor is charged per result, you will not be charged for more results than the given limit.
* **memory\_mbytes** (int, optional): Memory limit for the run, in megabytes. By default, the run uses a memory limit specified in the default run configuration for the Actor.
* **timeout\_secs** (int, optional): Optional timeout for the run, in seconds. By default, the run uses timeout specified in the default run configuration for the Actor.
* **webhooks** (list, optional): Optional webhooks ([https://docs.apify.com/webhooks](https://docs.apify.com/webhooks)) associated with the Actor run, which can be used to receive a notification, e.g. when the Actor finished or failed. If you already have a webhook set up for the Actor, you do not have to add it again here.
* **wait\_secs** (int, optional): The maximum number of seconds the server waits for finish. If not provided, waits indefinitely.
**Returns:**
Optional\[dict]: The output data from the actor if successful.
# please use the 'defaultDatasetId' to get the dataset
### get\_dataset\_client
```python theme={"system"}
def get_dataset_client(self, dataset_id: str):
```
Get a dataset client from the Apify platform.
**Parameters:**
* **dataset\_id** (str): The ID of the dataset to get the client for.
**Returns:**
DatasetClient: The dataset client.
### get\_dataset
```python theme={"system"}
def get_dataset(self, dataset_id: str):
```
Get a dataset from the Apify platform.
**Parameters:**
* **dataset\_id** (str): The ID of the dataset to get.
**Returns:**
dict: The dataset.
### update\_dataset
```python theme={"system"}
def update_dataset(self, dataset_id: str, name: str):
```
Update a dataset on the Apify platform.
**Parameters:**
* **dataset\_id** (str): The ID of the dataset to update.
* **name** (str): The new name for the dataset.
**Returns:**
dict: The updated dataset.
### get\_dataset\_items
```python theme={"system"}
def get_dataset_items(self, dataset_id: str):
```
Get items from a dataset on the Apify platform.
**Parameters:**
* **dataset\_id** (str): The ID of the dataset to get items from.
**Returns:**
list: The items in the dataset.
### get\_datasets
```python theme={"system"}
def get_datasets(
self,
unnamed: Optional[bool] = None,
limit: Optional[int] = None,
offset: Optional[int] = None,
desc: Optional[bool] = None
):
```
Get all named datasets from the Apify platform.
**Parameters:**
* **unnamed** (bool, optional): Whether to include unnamed key-value stores in the list
* **limit** (int, optional): How many key-value stores to retrieve
* **offset** (int, optional): What key-value store to include as first when retrieving the list
* **desc** (bool, optional): Whether to sort the key-value stores in descending order based on their modification date
**Returns:**
List\[dict]: The datasets.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.base_io
## create\_file
```python theme={"system"}
def create_file(file: BytesIO, filename: str):
```
Reads an uploaded file and returns a File object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the file.
* **filename** (str): The name of the file.
**Returns:**
File: A File object.
## create\_file\_from\_raw\_bytes
```python theme={"system"}
def create_file_from_raw_bytes(raw_bytes: bytes, filename: str):
```
Reads raw bytes and returns a File object.
**Parameters:**
* **raw\_bytes** (bytes): The raw bytes content of the file.
* **filename** (str): The name of the file.
**Returns:**
File: A File object.
## File
```python theme={"system"}
class File(ABC):
```
Represents an uploaded file comprised of Documents.
**Parameters:**
* **name** (str): The name of the file.
* **file\_id** (str): The unique identifier of the file.
* **metadata** (Dict\[str, Any], optional): Additional metadata associated with the file. Defaults to None.
* **docs** (List\[Dict\[str, Any]], optional): A list of documents contained within the file. Defaults to None.
* **raw\_bytes** (bytes, optional): The raw bytes content of the file. Defaults to b"".
### **init**
```python theme={"system"}
def __init__(
self,
name: str,
file_id: str,
metadata: Optional[Dict[str, Any]] = None,
docs: Optional[List[Dict[str, Any]]] = None,
raw_bytes: bytes = b''
):
```
### from\_bytes
```python theme={"system"}
def from_bytes(cls, file: BytesIO, filename: str):
```
Creates a File object from a BytesIO object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the file.
* **filename** (str): The name of the file.
**Returns:**
File: A File object.
### from\_raw\_bytes
```python theme={"system"}
def from_raw_bytes(cls, raw_bytes: bytes, filename: str):
```
Creates a File object from raw bytes.
**Parameters:**
* **raw\_bytes** (bytes): The raw bytes content of the file.
* **filename** (str): The name of the file.
**Returns:**
File: A File object.
### **repr**
```python theme={"system"}
def __repr__(self):
```
### **str**
```python theme={"system"}
def __str__(self):
```
### copy
```python theme={"system"}
def copy(self):
```
Create a deep copy of this File
## strip\_consecutive\_newlines
```python theme={"system"}
def strip_consecutive_newlines(text: str):
```
Strips consecutive newlines from a string.
**Parameters:**
* **text** (str): The string to strip.
**Returns:**
str: The string with consecutive newlines stripped.
## DocxFile
```python theme={"system"}
class DocxFile(File):
```
### from\_bytes
```python theme={"system"}
def from_bytes(cls, file: BytesIO, filename: str):
```
Creates a DocxFile object from a BytesIO object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the docx file.
* **filename** (str): The name of the file.
**Returns:**
DocxFile: A DocxFile object.
## PdfFile
```python theme={"system"}
class PdfFile(File):
```
### from\_bytes
```python theme={"system"}
def from_bytes(cls, file: BytesIO, filename: str):
```
Creates a PdfFile object from a BytesIO object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the pdf file.
* **filename** (str): The name of the file.
**Returns:**
PdfFile: A PdfFile object.
## TxtFile
```python theme={"system"}
class TxtFile(File):
```
### from\_bytes
```python theme={"system"}
def from_bytes(cls, file: BytesIO, filename: str):
```
Creates a TxtFile object from a BytesIO object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the txt file.
* **filename** (str): The name of the file.
**Returns:**
TxtFile: A TxtFile object.
## JsonFile
```python theme={"system"}
class JsonFile(File):
```
### from\_bytes
```python theme={"system"}
def from_bytes(cls, file: BytesIO, filename: str):
```
Creates a JsonFile object from a BytesIO object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the json file.
* **filename** (str): The name of the file.
**Returns:**
JsonFile: A JsonFile object.
## HtmlFile
```python theme={"system"}
class HtmlFile(File):
```
### from\_bytes
```python theme={"system"}
def from_bytes(cls, file: BytesIO, filename: str):
```
Creates a HtmlFile object from a BytesIO object.
**Parameters:**
* **file** (BytesIO): A BytesIO object representing the contents of the html file.
* **filename** (str): The name of the file.
**Returns:**
HtmlFile: A HtmlFile object.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.base_loader
## BaseLoader
```python theme={"system"}
class BaseLoader(ABC):
```
Abstract base class for all data loaders in CAMEL.
### \_load\_single
```python theme={"system"}
def _load_single(self, source: Union[str, Path]):
```
Load data from a single source.
**Parameters:**
* **source** (Union\[str, Path]): The data source to load from.
**Returns:**
Dict\[str, Any]: A dictionary containing the loaded data. It is
recommended that the dictionary includes a "content" key with
the primary data and optional metadata keys.
### load
```python theme={"system"}
def load(self, source: Union[str, Path, List[Union[str, Path]]]):
```
Load data from one or multiple sources.
**Parameters:**
* **source** (Union\[str, Path, List\[Union\[str, Path]]]): The data source (s) to load from. Can be: - A single path/URL (str or Path) - A list of paths/URLs
**Returns:**
Dict\[str, List\[Dict\[str, Any]]]: A dictionary with a single key
"contents" containing a list of loaded data. If a single source
is provided, the list will contain a single item.
### supported\_formats
```python theme={"system"}
def supported_formats(self):
```
**Returns:**
set\[str]: A set of strings representing the supported formats/
sources.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.chunkr_reader
## ChunkrReaderConfig
```python theme={"system"}
class ChunkrReaderConfig:
```
Defines the parameters for configuring the task.
**Parameters:**
* **chunk\_processing** (int, optional): The target chunk length. (default: :obj:`512`)
* **high\_resolution** (bool, optional): Whether to use high resolution OCR. (default: :obj:`True`)
* **ocr\_strategy** (str, optional): The OCR strategy. Defaults to 'Auto'. \*\*kwargs: Additional keyword arguments to pass to the Chunkr Configuration. This accepts all other Configuration parameters such as expires\_in, pipeline, segment\_processing, segmentation\_strategy, etc. (default: `'Auto'`)
* **See**: [https://github.com/lumina-ai-inc/chunkr/blob/main/core/src/](https://github.com/lumina-ai-inc/chunkr/blob/main/core/src/) models/task.rs#L749
### **init**
```python theme={"system"}
def __init__(
self,
chunk_processing: int = 512,
high_resolution: bool = True,
ocr_strategy: str = 'Auto',
**kwargs
):
```
## ChunkrReader
```python theme={"system"}
class ChunkrReader:
```
Chunkr Reader for processing documents and returning content
in various formats.
**Parameters:**
* **api\_key** (Optional\[str], optional): The API key for Chunkr API. If not provided, it will be retrieved from the environment variable `CHUNKR_API_KEY`. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Chunkr service. (default: :obj:`https://api.chunkr.ai/api/v1/task`) \*\*kwargs (Any): Additional keyword arguments for request headers.
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
url: Optional[str] = 'https://api.chunkr.ai/api/v1/task'
):
```
### \_pretty\_print\_response
```python theme={"system"}
def _pretty_print_response(self, response_json: dict):
```
Pretty prints the JSON response.
**Parameters:**
* **response\_json** (dict): The response JSON to pretty print.
**Returns:**
str: Formatted JSON as a string.
### \_to\_chunkr\_configuration
```python theme={"system"}
def _to_chunkr_configuration(self, chunkr_config: ChunkrReaderConfig):
```
Converts the ChunkrReaderConfig to Chunkr Configuration.
**Parameters:**
* **chunkr\_config** (ChunkrReaderConfig): The ChunkrReaderConfig to convert.
**Returns:**
Configuration: Chunkr SDK configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.crawl4ai_reader
## Crawl4AI
```python theme={"system"}
class Crawl4AI:
```
Class for converting websites into LLM-ready data.
This class uses asynchronous crawling with CSS selectors or LLM-based
extraction to convert entire websites into structured data.
References:
[https://docs.crawl4ai.com/](https://docs.crawl4ai.com/)
### **init**
```python theme={"system"}
def __init__(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.firecrawl_reader
## Firecrawl
```python theme={"system"}
class Firecrawl:
```
Firecrawl allows you to turn entire websites into LLM-ready markdown.
**Parameters:**
* **api\_key** (Optional\[str]): API key for authenticating with the Firecrawl API.
* **api\_url** (Optional\[str]): Base URL for the Firecrawl API.
* **References**:
* **https**: //docs.firecrawl.dev/introduction
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
api_url: Optional[str] = None
):
```
### crawl
```python theme={"system"}
def crawl(
self,
url: str,
params: Optional[Dict[str, Any]] = None,
**kwargs: Any
):
```
Crawl a URL and all accessible subpages. Customize the crawl by
setting different parameters, and receive the full response or a job
ID based on the specified options.
**Parameters:**
* **url** (str): The URL to crawl.
* **params** (Optional\[Dict\[str, Any]]): Additional parameters for the crawl request. Defaults to `None`. \*\*kwargs (Any): Additional keyword arguments, such as `poll_interval`, `idempotency_key`.
**Returns:**
Any: The crawl job ID or the crawl results if waiting until
completion.
### check\_crawl\_job
```python theme={"system"}
def check_crawl_job(self, job_id: str):
```
Check the status of a crawl job.
**Parameters:**
* **job\_id** (str): The ID of the crawl job.
**Returns:**
Dict: The response including status of the crawl job.
### scrape
```python theme={"system"}
def scrape(self, url: str, params: Optional[Dict[str, str]] = None):
```
To scrape a single URL. This function supports advanced scraping
by setting different parameters and returns the full scraped data as a
dictionary.
Reference: [https://docs.firecrawl.dev/advanced-scraping-guide](https://docs.firecrawl.dev/advanced-scraping-guide)
**Parameters:**
* **url** (str): The URL to read.
* **params** (Optional\[Dict\[str, str]]): Additional parameters for the scrape request.
**Returns:**
Dict\[str, str]: The scraped data.
### structured\_scrape
```python theme={"system"}
def structured_scrape(self, url: str, response_format: BaseModel):
```
Use LLM to extract structured data from given URL.
**Parameters:**
* **url** (str): The URL to read.
* **response\_format** (BaseModel): A pydantic model that includes value types and field descriptions used to generate a structured response by LLM. This schema helps in defining the expected output format.
**Returns:**
Dict: The content of the URL.
### map\_site
```python theme={"system"}
def map_site(self, url: str, params: Optional[Dict[str, Any]] = None):
```
Map a website to retrieve all accessible URLs.
**Parameters:**
* **url** (str): The URL of the site to map.
* **params** (Optional\[Dict\[str, Any]]): Additional parameters for the map request. Defaults to `None`.
**Returns:**
list: A list containing the URLs found on the site.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.jina_url_reader
## JinaURLReader
```python theme={"system"}
class JinaURLReader:
```
URL Reader provided by Jina AI. The output is cleaner and more
LLM-friendly than the URL Reader of UnstructuredIO. Can be configured to
replace the UnstructuredIO URL Reader in the pipeline.
**Parameters:**
* **api\_key** (Optional\[str], optional): The API key for Jina AI. If not provided, the reader will have a lower rate limit. Defaults to None.
* **return\_format** (ReturnFormat, optional): The level of detail of the returned content, which is optimized for LLMs. For now screenshots are not supported. Defaults to ReturnFormat.DEFAULT.
* **json\_response** (bool, optional): Whether to return the response in JSON format. Defaults to False.
* **timeout** (int, optional): The maximum time in seconds to wait for the page to be rendered. Defaults to 30. \*\*kwargs (Any): Additional keyword arguments, including proxies, cookies, etc. It should align with the HTTP Header field and value pairs listed in the reference.
* **References**:
* **https**: //jina.ai/reader
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
return_format: JinaReturnFormat = JinaReturnFormat.DEFAULT,
json_response: bool = False,
timeout: int = 30,
**kwargs: Any
):
```
### read\_content
```python theme={"system"}
def read_content(self, url: str):
```
Reads the content of a URL and returns it as a string with
given form.
**Parameters:**
* **url** (str): The URL to read.
**Returns:**
str: The content of the URL.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.markitdown
## MarkItDownLoader
```python theme={"system"}
class MarkItDownLoader:
```
MarkitDown convert various file types into Markdown format.
Supported Input Formats:
* PDF
* Microsoft Office documents:
* Word (.doc, .docx)
* Excel (.xls, .xlsx)
* PowerPoint (.ppt, .pptx)
* EPUB
* HTML
* Images (with EXIF metadata and OCR support)
* Audio files (with EXIF metadata and speech transcription)
* Text-based formats:
* CSV
* JSON
* XML
* ZIP archives (iterates over contents)
* YouTube URLs (via transcript extraction)
### **init**
```python theme={"system"}
def __init__(
self,
llm_client: Optional[object] = None,
llm_model: Optional[str] = None
):
```
Initializes the Converter.
**Parameters:**
* **llm\_client** (Optional\[object]): Optional client for LLM integration. (default: :obj:`None`)
* **llm\_model** (Optional\[str]): Optional model name for the LLM. (default: :obj:`None`)
### \_validate\_format
```python theme={"system"}
def _validate_format(self, file_path: str):
```
Validates if the file format is supported.
**Parameters:**
* **file\_path** (str): Path to the input file.
**Returns:**
bool: True if the format is supported, False otherwise.
### convert\_file
```python theme={"system"}
def convert_file(self, file_path: str):
```
Converts the given file to Markdown format.
**Parameters:**
* **file\_path** (str): Path to the input file.
**Returns:**
str: Converted Markdown text.
### convert\_files
```python theme={"system"}
def convert_files(
self,
file_paths: List[str],
parallel: bool = False,
skip_failed: bool = False
):
```
Converts multiple files to Markdown format.
**Parameters:**
* **file\_paths** (List\[str]): List of file paths to convert.
* **parallel** (bool): Whether to process files in parallel. (default: :obj:`False`)
* **skip\_failed** (bool): Whether to skip failed files instead of including error messages. (default: :obj:`False`)
**Returns:**
Dict\[str, str]: Dictionary mapping file paths to their
converted Markdown text.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.mineru_extractor
## MinerU
```python theme={"system"}
class MinerU:
```
Document extraction service supporting OCR, formula recognition
and tables.
**Parameters:**
* **api\_key** (str, optional): Authentication key for MinerU API service. If not provided, will use MINERU\_API\_KEY environment variable. (default: :obj:`None`)
* **api\_url** (str, optional): Base URL endpoint for the MinerU API service. (default: :obj:`"https://mineru.net/api/v4"`)
**Note:**
* Single file size limit: 200MB
* Page limit per file: 600 pages
* Daily high-priority parsing quota: 2000 pages
* Some URLs (GitHub, AWS) may timeout due to network restrictions
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
api_url: Optional[str] = 'https://mineru.net/api/v4',
is_ocr: bool = False,
enable_formula: bool = False,
enable_table: bool = True,
layout_model: str = 'doclayout_yolo',
language: str = 'en'
):
```
Initialize MinerU extractor.
**Parameters:**
* **api\_key** (str, optional): Authentication key for MinerU API service. If not provided, will use MINERU\_API\_KEY environment variable.
* **api\_url** (str, optional): Base URL endpoint for MinerU API service. (default: "[https://mineru.net/api/v4](https://mineru.net/api/v4)")
* **is\_ocr** (bool, optional): Enable optical character recognition. (default: :obj:`False`)
* **enable\_formula** (bool, optional): Enable formula recognition. (default: :obj:`False`)
* **enable\_table** (bool, optional): Enable table detection, extraction. (default: :obj:`True`)
* **layout\_model** (str, optional): Model for document layout detection. Options are 'doclayout\_yolo' or 'layoutlmv3'. (default: :obj:`"doclayout_yolo"`)
* **language** (str, optional): Primary language of the document. (default: :obj:`"en"`)
### extract\_url
```python theme={"system"}
def extract_url(self, url: str):
```
Extract content from a URL document.
**Parameters:**
* **url** (str): Document URL to extract content from.
**Returns:**
Dict: Task identifier for tracking extraction progress.
### batch\_extract\_urls
```python theme={"system"}
def batch_extract_urls(self, files: List[Dict[str, Union[str, bool]]]):
```
Extract content from multiple document URLs in batch.
**Parameters:**
* **files** (List\[Dict\[str, Union\[str, bool]]]): List of document configurations. Each document requires 'url' and optionally 'is\_ocr' and 'data\_id' parameters.
**Returns:**
str: Batch identifier for tracking extraction progress.
### get\_task\_status
```python theme={"system"}
def get_task_status(self, task_id: str):
```
Retrieve status of a single extraction task.
**Parameters:**
* **task\_id** (str): Unique identifier of the extraction task.
**Returns:**
Dict: Current task status and results if completed.
### get\_batch\_status
```python theme={"system"}
def get_batch_status(self, batch_id: str):
```
Retrieve status of a batch extraction task.
**Parameters:**
* **batch\_id** (str): Unique identifier of the batch extraction task.
**Returns:**
Dict: Current status and results for all documents in the batch.
### wait\_for\_completion
```python theme={"system"}
def wait_for_completion(
self,
task_id: str,
is_batch: bool = False,
timeout: float = 100,
check_interval: float = 5
):
```
Monitor task until completion or timeout.
**Parameters:**
* **task\_id** (str): Unique identifier of the task or batch.
* **is\_batch** (bool, optional): Indicates if task is a batch operation. (default: :obj:`False`)
* **timeout** (float, optional): Maximum wait time in seconds. (default: :obj:`100`)
* **check\_interval** (float, optional): Time between status checks in seconds. (default: :obj:`5`)
**Returns:**
Dict: Final task status and extraction results.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.mistral_reader
## MistralReader
```python theme={"system"}
class MistralReader:
```
Mistral Document Loader.
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
model: Optional[str] = 'mistral-ocr-latest'
):
```
Initialize the MistralReader.
**Parameters:**
* **api\_key** (Optional\[str]): The API key for the Mistral API. (default: :obj:`None`)
* **model** (Optional\[str]): The model to use for OCR. (default: :obj:`"mistral-ocr-latest"`)
### \_encode\_file
```python theme={"system"}
def _encode_file(self, file_path: str):
```
Encode the pdf to base64.
**Parameters:**
* **file\_path** (str): Path to the input file.
**Returns:**
str: base64 version of the file.
### extract\_text
```python theme={"system"}
def extract_text(
self,
file_path: str,
is_image: bool = False,
pages: Optional[List[int]] = None,
include_image_base64: Optional[bool] = None
):
```
Converts the given file to Markdown format.
**Parameters:**
* **file\_path** (str): Path to the input file or a remote URL.
* **is\_image** (bool): Whether the file or URL is an image. If True, uses image\_url type instead of document\_url. (default: :obj:`False`)
* **pages** (Optional\[List\[int]]): Specific pages user wants to process in various formats: single number, range, or list of both. Starts from 0. (default: :obj:`None`)
* **include\_image\_base64** (Optional\[bool]): Whether to include image URLs in response. (default: :obj:`None`)
**Returns:**
OCRResponse: page wise extractions.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.pandas_reader
## check\_suffix
```python theme={"system"}
def check_suffix(valid_suffixs: List[str]):
```
A decorator to check the file suffix of a given file path.
**Parameters:**
* **valid\_suffix** (str): The required file suffix.
**Returns:**
Callable: The decorator function.
## PandasReader
```python theme={"system"}
class PandasReader:
```
### **init**
```python theme={"system"}
def __init__(self, config: Optional[Dict[str, Any]] = None):
```
Initializes the PandasReader class.
**Parameters:**
* **config** (Optional\[Dict\[str, Any]], optional): The configuration dictionary that can include LLM API settings for LLM-based processing. If not provided, no LLM will be configured by default. You can customize the LLM configuration by providing a 'llm' key in the config dictionary. (default: :obj:`None`)
### load
```python theme={"system"}
def load(
self,
data: Union['DataFrame', str],
*args: Any,
**kwargs: Dict[str, Any]
):
```
Loads a file or DataFrame and returns a DataFrame or
SmartDataframe object.
If an LLM is configured in the config dictionary, a SmartDataframe
will be returned, otherwise a regular pandas DataFrame will be
returned.
**Parameters:**
* **data** (Union\[DataFrame, str]): The data to load. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
Union\[DataFrame, SmartDataframe]: The DataFrame or SmartDataframe
object.
### read\_csv
```python theme={"system"}
def read_csv(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a CSV file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the CSV file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_excel
```python theme={"system"}
def read_excel(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads an Excel file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the Excel file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_json
```python theme={"system"}
def read_json(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a JSON file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the JSON file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_parquet
```python theme={"system"}
def read_parquet(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a Parquet file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the Parquet file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_sql
```python theme={"system"}
def read_sql(self, *args: Any, **kwargs: Dict[str, Any]):
```
Reads a SQL file and returns a DataFrame.
**Returns:**
DataFrame: The DataFrame object.
### read\_table
```python theme={"system"}
def read_table(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a table and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the table. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_clipboard
```python theme={"system"}
def read_clipboard(self, *args: Any, **kwargs: Dict[str, Any]):
```
Reads a clipboard and returns a DataFrame.
**Returns:**
DataFrame: The DataFrame object.
### read\_html
```python theme={"system"}
def read_html(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads an HTML file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the HTML file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_feather
```python theme={"system"}
def read_feather(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a Feather file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the Feather file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_stata
```python theme={"system"}
def read_stata(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a Stata file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the Stata file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_sas
```python theme={"system"}
def read_sas(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a SAS file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the SAS file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_pickle
```python theme={"system"}
def read_pickle(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads a Pickle file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the Pickle file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_hdf
```python theme={"system"}
def read_hdf(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads an HDF file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the HDF file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
### read\_orc
```python theme={"system"}
def read_orc(
self,
file_path: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Reads an ORC file and returns a DataFrame.
**Parameters:**
* **file\_path** (str): The path to the ORC file. \*args (Any): Additional positional arguments. \*\*kwargs (Dict\[str, Any]): Additional keyword arguments.
**Returns:**
DataFrame: The DataFrame object.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.scrapegraph_reader
## ScrapeGraphAI
```python theme={"system"}
class ScrapeGraphAI:
```
ScrapeGraphAI allows you to perform AI-powered web scraping and
searching.
**Parameters:**
* **api\_key** (Optional\[str]): API key for authenticating with the ScrapeGraphAI API.
* **References**:
* **https**: //scrapegraph.ai/
### **init**
```python theme={"system"}
def __init__(self, api_key: Optional[str] = None):
```
### search
```python theme={"system"}
def search(self, user_prompt: str):
```
Perform an AI-powered web search using ScrapeGraphAI.
**Parameters:**
* **user\_prompt** (str): The search query or instructions.
**Returns:**
Dict\[str, Any]: The search results including answer and reference
URLs.
### scrape
```python theme={"system"}
def scrape(
self,
website_url: str,
user_prompt: str,
website_html: Optional[str] = None
):
```
Perform AI-powered web scraping using ScrapeGraphAI.
**Parameters:**
* **website\_url** (str): The URL to scrape.
* **user\_prompt** (str): Instructions for what data to extract.
* **website\_html** (Optional\[str]): Optional HTML content to use instead of fetching from the URL.
**Returns:**
Dict\[str, Any]: The scraped data including request ID and result.
### close
```python theme={"system"}
def close(self):
```
Close the ScrapeGraphAI client connection.
# null
Source: https://docs.camel-ai.org/reference/camel.loaders.unstructured_io
## UnstructuredIO
```python theme={"system"}
class UnstructuredIO:
```
A class to handle various functionalities provided by the
Unstructured library, including version checking, parsing, cleaning,
extracting, staging, chunking data, and integrating with cloud
services like S3 and Azure for data connection.
References:
[https://docs.unstructured.io/](https://docs.unstructured.io/)
### create\_element\_from\_text
```python theme={"system"}
def create_element_from_text(
text: str,
element_id: Optional[str] = None,
embeddings: Optional[List[float]] = None,
filename: Optional[str] = None,
file_directory: Optional[str] = None,
last_modified: Optional[str] = None,
filetype: Optional[str] = None,
parent_id: Optional[str] = None
):
```
Creates a Text element from a given text input, with optional
metadata and embeddings.
**Parameters:**
* **text** (str): The text content for the element.
* **element\_id** (Optional\[str], optional): Unique identifier for the element. (default: :obj:`None`)
* **embeddings** (List\[float], optional): A list of float numbers representing the text embeddings. (default: :obj:`None`)
* **filename** (Optional\[str], optional): The name of the file the element is associated with. (default: :obj:`None`)
* **file\_directory** (Optional\[str], optional): The directory path where the file is located. (default: :obj:`None`)
* **last\_modified** (Optional\[str], optional): The last modified date of the file. (default: :obj:`None`)
* **filetype** (Optional\[str], optional): The type of the file. (default: :obj:`None`)
* **parent\_id** (Optional\[str], optional): The identifier of the parent element. (default: :obj:`None`)
**Returns:**
Element: An instance of Text with the provided content and
metadata.
### parse\_file\_or\_url
```python theme={"system"}
def parse_file_or_url(input_path: str, **kwargs: Any):
```
Loads a file or a URL and parses its contents into elements.
**Parameters:**
* **input\_path** (str): Path to the file or URL to be parsed. \*\*kwargs: Extra kwargs passed to the partition function.
**Returns:**
Union\[List\[Element],None]: List of elements after parsing the file
or URL if success.
**Note:**
Supported file types:
"csv", "doc", "docx", "epub", "image", "md", "msg", "odt",
"org", "pdf", "ppt", "pptx", "rtf", "rst", "tsv", "xlsx".
References:
[https://unstructured-io.github.io/unstructured/](https://unstructured-io.github.io/unstructured/)
### parse\_bytes
```python theme={"system"}
def parse_bytes(file: IO[bytes], **kwargs: Any):
```
Parses a bytes stream and converts its contents into elements.
**Parameters:**
* **file** (IO\[bytes]): The file in bytes format to be parsed. \*\*kwargs: Extra kwargs passed to the partition function.
**Returns:**
Union\[List\[Element], None]: List of elements after parsing the file
if successful, otherwise `None`.
**Note:**
Supported file types:
"csv", "doc", "docx", "epub", "image", "md", "msg", "odt",
"org", "pdf", "ppt", "pptx", "rtf", "rst", "tsv", "xlsx".
References:
[https://docs.unstructured.io/open-source/core-functionality/partitioning](https://docs.unstructured.io/open-source/core-functionality/partitioning)
### clean\_text\_data
```python theme={"system"}
def clean_text_data(
text: str,
clean_options: Optional[List[Tuple[str, Dict[str, Any]]]] = None
):
```
Cleans text data using a variety of cleaning functions provided by
the `unstructured` library.
This function applies multiple text cleaning utilities by calling the
`unstructured` library's cleaning bricks for operations like
replacing Unicode quotes, removing extra whitespace, dashes, non-ascii
characters, and more.
If no cleaning options are provided, a default set of cleaning
operations is applied. These defaults including operations
"replace\_unicode\_quotes", "clean\_non\_ascii\_chars",
"group\_broken\_paragraphs", and "clean\_extra\_whitespace".
**Parameters:**
* **text** (str): The text to be cleaned.
* **clean\_options** (dict): A dictionary specifying which cleaning options to apply. The keys should match the names of the cleaning functions, and the values should be dictionaries containing the parameters for each function. Supported types: 'clean\_extra\_whitespace', 'clean\_bullets', 'clean\_ordered\_bullets', 'clean\_postfix', 'clean\_prefix', 'clean\_dashes', 'clean\_trailing\_punctuation', 'clean\_non\_ascii\_chars', 'group\_broken\_paragraphs', 'remove\_punctuation', 'replace\_unicode\_quotes', 'bytes\_string\_to\_string', 'translate\_text'.
**Returns:**
str: The cleaned text.
**Note:**
The 'options' dictionary keys must correspond to valid cleaning
brick names from the `unstructured` library.
Each brick's parameters must be provided in a nested dictionary
as the value for the key.
References:
[https://unstructured-io.github.io/unstructured/](https://unstructured-io.github.io/unstructured/)
### extract\_data\_from\_text
```python theme={"system"}
def extract_data_from_text(
text: str,
extract_type: Literal['extract_datetimetz', 'extract_email_address', 'extract_ip_address', 'extract_ip_address_name', 'extract_mapi_id', 'extract_ordered_bullets', 'extract_text_after', 'extract_text_before', 'extract_us_phone_number'],
**kwargs
):
```
Extracts various types of data from text using functions from
unstructured.cleaners.extract.
**Parameters:**
* **text** (str): Text to extract data from. extract\_type (Literal\['extract\_datetimetz', 'extract\_email\_address', 'extract\_ip\_address', 'extract\_ip\_address\_name', 'extract\_mapi\_id', 'extract\_ordered\_bullets', 'extract\_text\_after', 'extract\_text\_before', 'extract\_us\_phone\_number']): Type of data to extract. \*\*kwargs: Additional keyword arguments for specific extraction functions.
**Returns:**
Any: The extracted data, type depends on extract\_type.
References:
[https://unstructured-io.github.io/unstructured/](https://unstructured-io.github.io/unstructured/)
### stage\_elements
```python theme={"system"}
def stage_elements(
elements: List[Any],
stage_type: Literal['convert_to_csv', 'convert_to_dataframe', 'convert_to_dict', 'dict_to_elements', 'stage_csv_for_prodigy', 'stage_for_prodigy', 'stage_for_baseplate', 'stage_for_datasaur', 'stage_for_label_box', 'stage_for_label_studio', 'stage_for_weaviate'],
**kwargs
):
```
Stages elements for various platforms based on the
specified staging type.
This function applies multiple staging utilities to format data
for different NLP annotation and machine learning tools. It uses
the 'unstructured.staging' module's functions for operations like
converting to CSV, DataFrame, dictionary, or formatting for
specific platforms like Prodigy, etc.
**Parameters:**
* **elements** (List\[Any]): List of Element objects to be staged. stage\_type (Literal\['convert\_to\_csv', 'convert\_to\_dataframe', 'convert\_to\_dict', 'dict\_to\_elements', 'stage\_csv\_for\_prodigy', 'stage\_for\_prodigy', 'stage\_for\_baseplate', 'stage\_for\_datasaur', 'stage\_for\_label\_box', 'stage\_for\_label\_studio', 'stage\_for\_weaviate']): Type of staging to perform. \*\*kwargs: Additional keyword arguments specific to the staging type.
**Returns:**
Union\[str, List\[Dict], Any]: Staged data in the
format appropriate for the specified staging type.
### chunk\_elements
```python theme={"system"}
def chunk_elements(elements: List['Element'], chunk_type: str, **kwargs):
```
Chunks elements by titles.
**Parameters:**
* **elements** (List\[Element]): List of Element objects to be chunked.
* **chunk\_type** (str): Type chunk going to apply. Supported types: 'chunk\_by\_title'. \*\*kwargs: Additional keyword arguments for chunking.
**Returns:**
List\[Dict]: List of chunked sections.
References:
[https://unstructured-io.github.io/unstructured/](https://unstructured-io.github.io/unstructured/)
# null
Source: https://docs.camel-ai.org/reference/camel.memories.agent_memories
## ChatHistoryMemory
```python theme={"system"}
class ChatHistoryMemory(AgentMemory):
```
An agent memory wrapper of :obj:`ChatHistoryBlock`.
**Parameters:**
* **context\_creator** (BaseContextCreator): A model context creator.
* **storage** (BaseKeyValueStorage, optional): A storage backend for storing chat history. If `None`, an :obj:`InMemoryKeyValueStorage` will be used. (default: :obj:`None`)
* **window\_size** (int, optional): The number of recent chat messages to retrieve. If not provided, the entire chat history will be retrieved. (default: :obj:`None`)
* **agent\_id** (str, optional): The ID of the agent associated with the chat history.
### **init**
```python theme={"system"}
def __init__(
self,
context_creator: BaseContextCreator,
storage: Optional[BaseKeyValueStorage] = None,
window_size: Optional[int] = None,
agent_id: Optional[str] = None
):
```
### agent\_id
```python theme={"system"}
def agent_id(self):
```
### agent\_id
```python theme={"system"}
def agent_id(self, val: Optional[str]):
```
### retrieve
```python theme={"system"}
def retrieve(self):
```
### write\_records
```python theme={"system"}
def write_records(self, records: List[MemoryRecord]):
```
### get\_context\_creator
```python theme={"system"}
def get_context_creator(self):
```
### clear
```python theme={"system"}
def clear(self):
```
### clean\_tool\_calls
```python theme={"system"}
def clean_tool_calls(self):
```
Removes tool call messages from memory.
This method removes all FUNCTION/TOOL role messages and any ASSISTANT
messages that contain tool\_calls in their meta\_dict to save token
usage.
### pop\_records
```python theme={"system"}
def pop_records(self, count: int):
```
Removes the most recent records from chat history memory.
### remove\_records\_by\_indices
```python theme={"system"}
def remove_records_by_indices(self, indices: List[int]):
```
Removes records at specified indices from chat history memory.
## VectorDBMemory
```python theme={"system"}
class VectorDBMemory(AgentMemory):
```
An agent memory wrapper of :obj:`VectorDBBlock`. This memory queries
messages stored in the vector database. Notice that the most recent
messages will not be added to the context.
**Parameters:**
* **context\_creator** (BaseContextCreator): A model context creator.
* **storage** (BaseVectorStorage, optional): A vector storage storage. If `None`, an :obj:`QdrantStorage` will be used. (default: :obj:`None`)
* **retrieve\_limit** (int, optional): The maximum number of messages to be added into the context. (default: :obj:`3`)
* **agent\_id** (str, optional): The ID of the agent associated with the messages stored in the vector database.
### **init**
```python theme={"system"}
def __init__(
self,
context_creator: BaseContextCreator,
storage: Optional[BaseVectorStorage] = None,
retrieve_limit: int = 3,
agent_id: Optional[str] = None
):
```
### agent\_id
```python theme={"system"}
def agent_id(self):
```
### agent\_id
```python theme={"system"}
def agent_id(self, val: Optional[str]):
```
### retrieve
```python theme={"system"}
def retrieve(self):
```
### write\_records
```python theme={"system"}
def write_records(self, records: List[MemoryRecord]):
```
### get\_context\_creator
```python theme={"system"}
def get_context_creator(self):
```
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the vector database memory.
### pop\_records
```python theme={"system"}
def pop_records(self, count: int):
```
Rolling back is unsupported for vector database memory.
### remove\_records\_by\_indices
```python theme={"system"}
def remove_records_by_indices(self, indices: List[int]):
```
Removing by indices is unsupported for vector database memory.
## LongtermAgentMemory
```python theme={"system"}
class LongtermAgentMemory(AgentMemory):
```
An implementation of the :obj:`AgentMemory` abstract base class for
augmenting ChatHistoryMemory with VectorDBMemory.
**Parameters:**
* **context\_creator** (BaseContextCreator): A model context creator.
* **chat\_history\_block** (Optional\[ChatHistoryBlock], optional): A chat history block. If `None`, a :obj:`ChatHistoryBlock` will be used. (default: :obj:`None`)
* **vector\_db\_block** (Optional\[VectorDBBlock], optional): A vector database block. If `None`, a :obj:`VectorDBBlock` will be used. (default: :obj:`None`)
* **retrieve\_limit** (int, optional): The maximum number of messages to be added into the context. (default: :obj:`3`)
* **agent\_id** (str, optional): The ID of the agent associated with the chat history and the messages stored in the vector database.
### **init**
```python theme={"system"}
def __init__(
self,
context_creator: BaseContextCreator,
chat_history_block: Optional[ChatHistoryBlock] = None,
vector_db_block: Optional[VectorDBBlock] = None,
retrieve_limit: int = 3,
agent_id: Optional[str] = None
):
```
### agent\_id
```python theme={"system"}
def agent_id(self):
```
### agent\_id
```python theme={"system"}
def agent_id(self, val: Optional[str]):
```
### get\_context\_creator
```python theme={"system"}
def get_context_creator(self):
```
**Returns:**
BaseContextCreator: The context creator used by the memory.
### retrieve
```python theme={"system"}
def retrieve(self):
```
**Returns:**
List\[ContextRecord]: A list of context records retrieved from both
the chat history and the vector database.
### write\_records
```python theme={"system"}
def write_records(self, records: List[MemoryRecord]):
```
Converts the provided chat messages into vector representations and
writes them to the vector database.
**Parameters:**
* **records** (List\[MemoryRecord]): Messages to be added to the vector database.
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the memory.
### pop\_records
```python theme={"system"}
def pop_records(self, count: int):
```
Removes recent chat history records while leaving vector memory.
### remove\_records\_by\_indices
```python theme={"system"}
def remove_records_by_indices(self, indices: List[int]):
```
Removes records at specified indices from chat history.
# null
Source: https://docs.camel-ai.org/reference/camel.memories.base
## MemoryBlock
```python theme={"system"}
class MemoryBlock(ABC):
```
An abstract class serves as the fundamental component within the agent
memory system. This class is equipped with "write" and "clear" functions.
However, it intentionally does not define a retrieval interface, as the
structure of the data to be retrieved may vary in different types of
memory blocks.
### write\_records
```python theme={"system"}
def write_records(self, records: List[MemoryRecord]):
```
Writes records to the memory, appending them to existing ones.
**Parameters:**
* **records** (List\[MemoryRecord]): Records to be added to the memory.
### write\_record
```python theme={"system"}
def write_record(self, record: MemoryRecord):
```
Writes a record to the memory, appending it to existing ones.
**Parameters:**
* **record** (MemoryRecord): Record to be added to the memory.
### pop\_records
```python theme={"system"}
def pop_records(self, count: int):
```
Removes records from the memory and returns the removed records.
**Parameters:**
* **count** (int): Number of records to remove.
**Returns:**
List\[MemoryRecord]: The records that were removed from the memory
in their original order.
### remove\_records\_by\_indices
```python theme={"system"}
def remove_records_by_indices(self, indices: List[int]):
```
Removes records at specified indices from the memory.
**Parameters:**
* **indices** (List\[int]): List of indices to remove. Indices should be valid positions in the current record list.
**Returns:**
List\[MemoryRecord]: The removed records in their original order.
### clear
```python theme={"system"}
def clear(self):
```
Clears all messages from the memory.
## BaseContextCreator
```python theme={"system"}
class BaseContextCreator(ABC):
```
An abstract base class defining the interface for context creation
strategies.
This class provides a foundational structure for different strategies to
generate conversational context from a list of context records. The
primary goal is to create a context that is aligned with a specified token
count limit, allowing subclasses to define their specific approach.
Subclasses should implement the :obj:`token_counter`,:obj: `token_limit`,
and :obj:`create_context` methods to provide specific context creation
logic.
**Parameters:**
* **token\_counter** (BaseTokenCounter): A token counter instance responsible for counting tokens in a message.
* **token\_limit** (int): The maximum number of tokens allowed in the generated context.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
### token\_limit
```python theme={"system"}
def token_limit(self):
```
### create\_context
```python theme={"system"}
def create_context(self, records: List[ContextRecord]):
```
An abstract method to create conversational context from the chat
history.
Constructs the context from provided records. The specifics of how this
is done and how the token count is managed should be provided by
subclasses implementing this method. The output messages order
should keep same as the input order.
**Parameters:**
* **records** (List\[ContextRecord]): A list of context records from which to generate the context.
**Returns:**
Tuple\[List\[OpenAIMessage], int]: A tuple containing the constructed
context in OpenAIMessage format and the total token count.
## AgentMemory
```python theme={"system"}
class AgentMemory(MemoryBlock, ABC):
```
Represents a specialized form of `MemoryBlock`, uniquely designed for
direct integration with an agent. Two key abstract functions, "retrieve"
and "get\_context\_creator", are used for generating model context based on
the memory records stored within the AgentMemory.
### agent\_id
```python theme={"system"}
def agent_id(self):
```
### agent\_id
```python theme={"system"}
def agent_id(self, val: Optional[str]):
```
### retrieve
```python theme={"system"}
def retrieve(self):
```
**Returns:**
List\[ContextRecord]: A record list for creating model context.
### get\_context\_creator
```python theme={"system"}
def get_context_creator(self):
```
**Returns:**
BaseContextCreator: A model context creator.
### get\_context
```python theme={"system"}
def get_context(self):
```
**Returns:**
(List\[OpenAIMessage], int): A tuple containing the constructed
context in OpenAIMessage format and the total token count.
### clean\_tool\_calls
```python theme={"system"}
def clean_tool_calls(self):
```
Removes tool call messages from memory.
This is an optional method that can be overridden by subclasses
to implement cleaning of tool-related messages. By default, it
does nothing, maintaining backward compatibility.
### **repr**
```python theme={"system"}
def __repr__(self):
```
**Returns:**
str: A string in the format 'ClassName(agent\_id=``)'
if agent\_id exists, otherwise just 'ClassName()'.
# null
Source: https://docs.camel-ai.org/reference/camel.memories.blocks.chat_history_block
## ChatHistoryBlock
```python theme={"system"}
class ChatHistoryBlock(MemoryBlock):
```
An implementation of the :obj:`MemoryBlock` abstract base class for
maintaining a record of chat histories.
This memory block helps manage conversation histories with a key-value
storage backend, either provided by the user or using a default
in-memory storage. It offers a windowed approach to retrieving chat
histories, allowing users to specify how many recent messages they'd
like to fetch.
**Parameters:**
* **storage** (BaseKeyValueStorage, optional): A storage mechanism for storing chat history. If `None`, an :obj:`InMemoryKeyValueStorage` will be used. (default: :obj:`None`)
* **keep\_rate** (float, optional): In historical messages, the score of the last message is 1.0, and with each step taken backward, the score of the message is multiplied by the `keep_rate`. Higher `keep_rate` leads to high possibility to keep history messages during context creation. (default: :obj:`0.9`)
### **init**
```python theme={"system"}
def __init__(
self,
storage: Optional[BaseKeyValueStorage] = None,
keep_rate: float = 0.9
):
```
### retrieve
```python theme={"system"}
def retrieve(self, window_size: Optional[int] = None):
```
Retrieves records with a proper size for the agent from the memory
based on the window size or fetches the entire chat history if no
window size is specified.
**Parameters:**
* **window\_size** (int, optional): Specifies the number of recent chat messages to retrieve. If not provided, the entire chat history will be retrieved. (default: :obj:`None`)
**Returns:**
List\[ContextRecord]: A list of retrieved records.
### write\_records
```python theme={"system"}
def write_records(self, records: List[MemoryRecord]):
```
Writes memory records to the memory. Additionally, performs
validation checks on the messages.
**Parameters:**
* **records** (List\[MemoryRecord]): Memory records to be added to the memory.
### clear
```python theme={"system"}
def clear(self):
```
Clears all chat messages from the memory.
### pop\_records
```python theme={"system"}
def pop_records(self, count: int):
```
Removes the most recent records from the memory.
**Parameters:**
* **count** (int): Number of records to remove from the end of the conversation history. A value of 0 results in no changes.
**Returns:**
List\[MemoryRecord]: The removed records in chronological order.
### remove\_records\_by\_indices
```python theme={"system"}
def remove_records_by_indices(self, indices: List[int]):
```
Removes records at specified indices from the memory.
**Parameters:**
* **indices** (List\[int]): List of indices to remove. Indices are positions in the current record list (0-based). System/developer messages at index 0 are protected and will not be removed.
**Returns:**
List\[MemoryRecord]: The removed records in their original order.
# null
Source: https://docs.camel-ai.org/reference/camel.memories.blocks.vectordb_block
## VectorDBBlock
```python theme={"system"}
class VectorDBBlock(MemoryBlock):
```
An implementation of the :obj:`MemoryBlock` abstract base class for
maintaining and retrieving information using vector embeddings within a
vector database.
**Parameters:**
* **storage** (Optional\[BaseVectorStorage], optional): The storage mechanism for the vector database. Defaults to in-memory :obj:`Qdrant` if not provided. (default: :obj:`None`)
* **embedding** (Optional\[BaseEmbedding], optional): Embedding mechanism to convert chat messages into vector representations. Defaults to :obj:`OpenAiEmbedding` if not provided. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
storage: Optional[BaseVectorStorage] = None,
embedding: Optional[BaseEmbedding] = None
):
```
### retrieve
```python theme={"system"}
def retrieve(self, keyword: str, limit: int = 3):
```
Retrieves similar records from the vector database based on the
content of the keyword.
**Parameters:**
* **keyword** (str): This string will be converted into a vector representation to query the database.
* **limit** (int, optional): The maximum number of similar messages to retrieve. (default: :obj:`3`).
**Returns:**
List\[ContextRecord]: A list of memory records retrieved from the
vector database based on similarity to :obj:`current_state`.
### write\_records
```python theme={"system"}
def write_records(self, records: List[MemoryRecord]):
```
Converts the provided chat messages into vector representations and
writes them to the vector database.
**Parameters:**
* **records** (List\[MemoryRecord]): Memory records to be added to the memory.
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the vector database memory.
# null
Source: https://docs.camel-ai.org/reference/camel.memories.context_creators.score_based
## ScoreBasedContextCreator
```python theme={"system"}
class ScoreBasedContextCreator(BaseContextCreator):
```
A context creation strategy that orders records chronologically.
This class supports token count estimation to reduce expensive repeated
token counting. When a cached token count is available, it estimates
new message tokens using character-based approximation instead of
calling the token counter for every message.
**Parameters:**
* **token\_counter** (BaseTokenCounter): Token counter instance used to compute the combined token count of the returned messages.
* **token\_limit** (int): Retained for API compatibility. No longer used to filter records.
### **init**
```python theme={"system"}
def __init__(self, token_counter: BaseTokenCounter, token_limit: int):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
### token\_limit
```python theme={"system"}
def token_limit(self):
```
### set\_cached\_token\_count
```python theme={"system"}
def set_cached_token_count(self, token_count: int, message_count: int):
```
Set the cached token count from LLM response usage.
**Parameters:**
* **token\_count** (int): The total token count (prompt + completion) from LLM response usage.
* **message\_count** (int): The number of messages including the assistant response that will be added to memory.
### clear\_cache
```python theme={"system"}
def clear_cache(self):
```
Clear the cached token count.
### \_estimate\_message\_tokens
```python theme={"system"}
def _estimate_message_tokens(self, message: OpenAIMessage):
```
Estimate token count for a single message.
Uses \~2 chars/token as a conservative approximation to handle both
ASCII (\~4 chars/token) and CJK text (\~1-2 chars/token).
**Parameters:**
* **message**: The OpenAI message to estimate.
**Returns:**
Estimated token count (intentionally conservative).
### create\_context
```python theme={"system"}
def create_context(self, records: List[ContextRecord]):
```
Returns messages sorted by timestamp and their total token count.
# null
Source: https://docs.camel-ai.org/reference/camel.memories.records
## MemoryRecord
```python theme={"system"}
class MemoryRecord(BaseModel):
```
The basic message storing unit in the CAMEL memory system.
**Parameters:**
* **message** (BaseMessage): The main content of the record.
* **role\_at\_backend** (OpenAIBackendRole): An enumeration value representing the role this message played at the OpenAI backend. Note that this value is different from the :obj:`RoleType` used in the CAMEL role playing system.
* **uuid** (UUID, optional): A universally unique identifier for this record. This is used to uniquely identify this record in the memory system. If not given, it will be assigned with a random UUID.
* **extra\_info** (Dict\[str, str], optional): A dictionary of additional key-value pairs that provide more information. If not given, it will be an empty `Dict`.
* **timestamp** (float, optional): The timestamp when the record was created.
* **agent\_id** (str): The identifier of the agent associated with this memory.
### \_get\_constructor\_params
```python theme={"system"}
def _get_constructor_params(cls, message_cls):
```
Get constructor parameters for a message class with caching.
### from\_dict
```python theme={"system"}
def from_dict(cls, record_dict: Dict[str, Any]):
```
Reconstruct a :obj:`MemoryRecord` from the input dict.
**Parameters:**
* **record\_dict** (Dict\[str, Any]): A dict generated by :meth:`to_dict`.
### to\_dict
```python theme={"system"}
def to_dict(self):
```
Convert the :obj:`MemoryRecord` to a dict for serialization
purposes.
### to\_openai\_message
```python theme={"system"}
def to_openai_message(self):
```
Converts the record to an :obj:`OpenAIMessage` object.
## ContextRecord
```python theme={"system"}
class ContextRecord(BaseModel):
```
The result of memory retrieving.
# null
Source: https://docs.camel-ai.org/reference/camel.messages.base
## BaseMessage
```python theme={"system"}
class BaseMessage:
```
Base class for message objects used in CAMEL chat system.
**Parameters:**
* **role\_name** (str): The name of the user or assistant role.
* **role\_type** (RoleType): The type of role, either :obj:`RoleType. ASSISTANT` or :obj:`RoleType.USER`.
* **meta\_dict** (Optional\[Dict\[str, Any]]): Additional metadata dictionary for the message.
* **content** (str): The content of the message.
* **video\_bytes** (Optional\[bytes]): Optional bytes of a video associated with the message. (default: :obj:`None`)
* **image\_list** (Optional\[List\[Union\[Image.Image, str]]]): Optional list of PIL Image objects or image URLs (strings) associated with the message. (default: :obj:`None`)
* **image\_detail** (`Literal["auto", "low", "high"]`): Detail level of the images associated with the message. (default: :obj:`auto`)
* **video\_detail** (`Literal["auto", "low", "high"]`): Detail level of the videos associated with the message. (default: :obj:`auto`)
* **parsed** (Optional\[Union\[Type\[BaseModel], dict]]): Optional object which is parsed from the content. (default: :obj:`None`)
* **reasoning\_content** (Optional\[str]): Optional reasoning trace associated with the message. (default: :obj:`None`)
### make\_user\_message
```python theme={"system"}
def make_user_message(
cls,
role_name: str,
content: str,
meta_dict: Optional[Dict[str, str]] = None,
video_bytes: Optional[bytes] = None,
image_list: Optional[List[Union[Image.Image, str]]] = None,
image_detail: Union[OpenAIVisionDetailType, str] = OpenAIVisionDetailType.AUTO,
video_detail: Union[OpenAIVisionDetailType, str] = OpenAIVisionDetailType.LOW
):
```
Create a new user message.
**Parameters:**
* **role\_name** (str): The name of the user role.
* **content** (str): The content of the message.
* **meta\_dict** (Optional\[Dict\[str, str]]): Additional metadata dictionary for the message.
* **video\_bytes** (Optional\[bytes]): Optional bytes of a video associated with the message.
* **image\_list** (Optional\[List\[Union\[Image.Image, str]]]): Optional list of PIL Image objects or image URLs (strings) associated with the message.
* **image\_detail** (Union\[OpenAIVisionDetailType, str]): Detail level of the images associated with the message.
* **video\_detail** (Union\[OpenAIVisionDetailType, str]): Detail level of the videos associated with the message.
**Returns:**
BaseMessage: The new user message.
### make\_assistant\_message
```python theme={"system"}
def make_assistant_message(
cls,
role_name: str,
content: str,
meta_dict: Optional[Dict[str, str]] = None,
video_bytes: Optional[bytes] = None,
image_list: Optional[List[Union[Image.Image, str]]] = None,
image_detail: Union[OpenAIVisionDetailType, str] = OpenAIVisionDetailType.AUTO,
video_detail: Union[OpenAIVisionDetailType, str] = OpenAIVisionDetailType.LOW
):
```
Create a new assistant message.
**Parameters:**
* **role\_name** (str): The name of the assistant role.
* **content** (str): The content of the message.
* **meta\_dict** (Optional\[Dict\[str, str]]): Additional metadata dictionary for the message.
* **video\_bytes** (Optional\[bytes]): Optional bytes of a video associated with the message.
* **image\_list** (Optional\[List\[Union\[Image.Image, str]]]): Optional list of PIL Image objects or image URLs (strings) associated with the message.
* **image\_detail** (Union\[OpenAIVisionDetailType, str]): Detail level of the images associated with the message.
* **video\_detail** (Union\[OpenAIVisionDetailType, str]): Detail level of the videos associated with the message.
**Returns:**
BaseMessage: The new assistant message.
### make\_system\_message
```python theme={"system"}
def make_system_message(
cls,
content: str,
role_name: str = 'System',
meta_dict: Optional[Dict[str, str]] = None
):
```
Create a new system message.
**Parameters:**
* **content** (str): The content of the system message.
* **role\_name** (str): The name of the system role. (default: :obj:`"System"`)
* **meta\_dict** (Optional\[Dict\[str, str]]): Additional metadata dictionary for the message.
**Returns:**
BaseMessage: The new system message.
### create\_new\_instance
```python theme={"system"}
def create_new_instance(self, content: str):
```
Create a new instance of the :obj:`BaseMessage` with updated
content.
**Parameters:**
* **content** (str): The new content value.
**Returns:**
BaseMessage: The new instance of :obj:`BaseMessage`.
### **add**
```python theme={"system"}
def __add__(self, other: Any):
```
Addition operator override for :obj:`BaseMessage`.
**Parameters:**
* **other** (Any): The value to be added with.
**Returns:**
Union\[BaseMessage, Any]: The result of the addition.
### **mul**
```python theme={"system"}
def __mul__(self, other: Any):
```
Multiplication operator override for :obj:`BaseMessage`.
**Parameters:**
* **other** (Any): The value to be multiplied with.
**Returns:**
Union\[BaseMessage, Any]: The result of the multiplication.
### **len**
```python theme={"system"}
def __len__(self):
```
**Returns:**
int: The length of the content.
### **contains**
```python theme={"system"}
def __contains__(self, item: str):
```
Contains operator override for :obj:`BaseMessage`.
**Parameters:**
* **item** (str): The item to check for containment.
**Returns:**
bool: :obj:`True` if the item is contained in the content,
:obj:`False` otherwise.
### extract\_text\_and\_code\_prompts
```python theme={"system"}
def extract_text_and_code_prompts(self):
```
**Returns:**
Tuple\[List\[TextPrompt], List\[CodePrompt]]: A tuple containing a
list of text prompts and a list of code prompts extracted
from the content.
### from\_sharegpt
```python theme={"system"}
def from_sharegpt(
cls,
message: ShareGPTMessage,
function_format: Optional[FunctionCallFormatter[Any, Any]] = None,
role_mapping = None
):
```
Convert ShareGPT message to BaseMessage or FunctionCallingMessage.
Note tool calls and responses have an 'assistant' role in CAMEL
**Parameters:**
* **message** (ShareGPTMessage): ShareGPT message to convert.
* **function\_format** (FunctionCallFormatter, optional): Function call formatter to use. (default: :obj:`HermesFunctionFormatter()`.
* **role\_mapping** (Dict\[str, List\[str, RoleType]], optional): Role mapping to use. Defaults to a CAMEL specific mapping.
**Returns:**
BaseMessage: Converted message.
### to\_sharegpt
```python theme={"system"}
def to_sharegpt(self, function_format: Optional[FunctionCallFormatter] = None):
```
Convert BaseMessage to ShareGPT message
**Parameters:**
* **function\_format** (FunctionCallFormatter): Function call formatter to use. Defaults to Hermes.
### to\_openai\_message
```python theme={"system"}
def to_openai_message(self, role_at_backend: OpenAIBackendRole):
```
Converts the message to an :obj:`OpenAIMessage` object.
**Parameters:**
* **role\_at\_backend** (OpenAIBackendRole): The role of the message in OpenAI chat system.
**Returns:**
OpenAIMessage: The converted :obj:`OpenAIMessage` object.
### to\_openai\_system\_message
```python theme={"system"}
def to_openai_system_message(self):
```
**Returns:**
OpenAISystemMessage: The converted :obj:`OpenAISystemMessage`
object.
### to\_openai\_user\_message
```python theme={"system"}
def to_openai_user_message(self):
```
**Returns:**
OpenAIUserMessage: The converted :obj:`OpenAIUserMessage` object.
### to\_openai\_assistant\_message
```python theme={"system"}
def to_openai_assistant_message(self):
```
**Returns:**
OpenAIAssistantMessage: The converted :obj:`OpenAIAssistantMessage`
object.
### to\_dict
```python theme={"system"}
def to_dict(self):
```
**Returns:**
dict: The converted dictionary.
# null
Source: https://docs.camel-ai.org/reference/camel.messages.conversion.alpaca
## AlpacaItem
```python theme={"system"}
class AlpacaItem(BaseModel):
```
Represents an instruction-response item in the Alpaca format.
Appropripate for both cases where input field is empty, or populated.
Provides parsing from string format using the class method from\_string().
**Parameters:**
* **instruction** (str): The instruction/question/prompt
* **input** (str): Input context or examples (put empty string if none)
* **output** (str): The response/answer to the instruction
### no\_section\_markers
```python theme={"system"}
def no_section_markers(cls, value: str):
```
Ensures fields don't contain section markers like '###
Response:'
### from\_string
```python theme={"system"}
def from_string(cls, text: str):
```
Creates an AlpacaItem from a formatted string.
**Parameters:**
* **text**: String in either of these formats: With input: ### Instruction: \{instruction} ### Input: \{input} ### Response: \{response} Without input: ### Instruction: \{instruction} ### Response: \{response}
**Returns:**
AlpacaItem: Parsed instance
### to\_string
```python theme={"system"}
def to_string(self):
```
**Returns:**
str: Formatted string representation with sections markers
# null
Source: https://docs.camel-ai.org/reference/camel.messages.conversion.conversation_models
## ShareGPTMessage
```python theme={"system"}
class ShareGPTMessage(BaseModel):
```
A single message in ShareGPT format with enhanced validation
## ShareGPTConversation
```python theme={"system"}
class ShareGPTConversation(RootModel):
```
A full conversation in ShareGPT format with validation
### validate\_conversation\_flow
```python theme={"system"}
def validate_conversation_flow(self):
```
Validate the conversation follows logical message order
### model\_dump
```python theme={"system"}
def model_dump(self, **kwargs):
```
### **iter**
```python theme={"system"}
def __iter__(self):
```
## ToolCall
```python theme={"system"}
class ToolCall(BaseModel):
```
Represents a single tool/function call with validation
### validate\_arguments
```python theme={"system"}
def validate_arguments(cls, v: Dict[str, Any]):
```
Validate argument structure and content
## ToolResponse
```python theme={"system"}
class ToolResponse(BaseModel):
```
Represents a tool/function response with validation. This is a
base class and default implementation for tool responses, for the purpose
of converting between different formats.
### validate\_content
```python theme={"system"}
def validate_content(cls, v: Dict[str, Any]):
```
Validate response content structure
# null
Source: https://docs.camel-ai.org/reference/camel.messages.func_message
## FunctionCallingMessage
```python theme={"system"}
class FunctionCallingMessage(BaseMessage):
```
Class for message objects used specifically for
function-related messages.
**Parameters:**
* **func\_name** (Optional\[str]): The name of the function used. (default: :obj:`None`)
* **args** (Optional\[Dict]): The dictionary of arguments passed to the function. (default: :obj:`None`)
* **result** (Optional\[Any]): The result of function execution. (default: :obj:`None`)
* **tool\_call\_id** (Optional\[str]): The ID of the tool call, if available. (default: :obj:`None`)
* **mask\_output** (Optional\[bool]): Whether to return a sanitized placeholder instead of the raw tool output. (default: :obj:`False`)
* **extra\_content** (Optional\[Dict\[str, Any]]): Additional content associated with the tool call. (default: :obj:`None`)
### to\_openai\_message
```python theme={"system"}
def to_openai_message(self, role_at_backend: OpenAIBackendRole):
```
Converts the message to an :obj:`OpenAIMessage` object.
**Parameters:**
* **role\_at\_backend** (OpenAIBackendRole): The role of the message in OpenAI chat system.
**Returns:**
OpenAIMessage: The converted :obj:`OpenAIMessage` object.
### to\_sharegpt
```python theme={"system"}
def to_sharegpt(
self,
function_format: Optional[FunctionCallFormatter[ToolCall, ToolResponse]] = None
):
```
Convert FunctionCallingMessage to ShareGPT message.
### to\_openai\_assistant\_message
```python theme={"system"}
def to_openai_assistant_message(self):
```
**Returns:**
OpenAIAssistantMessage: The converted :obj:`OpenAIAssistantMessage`
object.
### to\_openai\_tool\_message
```python theme={"system"}
def to_openai_tool_message(self):
```
**Returns:**
OpenAIToolMessageParam: The converted
:obj:`OpenAIToolMessageParam` object with its role being
"tool".
### to\_dict
```python theme={"system"}
def to_dict(self):
```
**Returns:**
dict: The converted dictionary.
# null
Source: https://docs.camel-ai.org/reference/camel.models._utils
## try\_modify\_message\_with\_format
```python theme={"system"}
def try_modify_message_with_format(
message: OpenAIMessage,
response_format: Optional[Type[BaseModel]]
):
```
Modifies the content of the message to include the instruction of using
the response format.
The message will not be modified in the following cases:
* response\_format is None
* message content is not a string
* message role is assistant
**Parameters:**
* **response\_format** (Optional\[Type\[BaseModel]]): The Pydantic model class.
* **message** (OpenAIMessage): The message to be modified.
# null
Source: https://docs.camel-ai.org/reference/camel.models.aihubmix_model
## AihubMixModel
```python theme={"system"}
class AihubMixModel(OpenAICompatibleModel):
```
AihubMix API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into OpenAI client. If :obj:`None`, :obj:`{}` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with AihubMix service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The URL to AihubMix service. If not provided, :obj:`https://aihubmix.com/v1` will be used. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.aiml_model
## AIMLModel
```python theme={"system"}
class AIMLModel(OpenAICompatibleModel):
```
AIML API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into OpenAI client. If :obj:`None`, :obj:`AIMLConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the AIML service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The URL to the AIML service. If not provided, :obj:`https://api.aimlapi.com/v1` will be used. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.amd_model
## AMDModel
```python theme={"system"}
class AMDModel(OpenAICompatibleModel):
```
AMD API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of AMD series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`AMDConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the AMD service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the AMD service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter( ModelType.GPT_4)` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
### check\_model\_config
```python theme={"system"}
def check_model_config(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.anthropic_model
## strip\_trailing\_whitespace\_from\_messages
```python theme={"system"}
def strip_trailing_whitespace_from_messages(messages: List[OpenAIMessage]):
```
Strip trailing whitespace from all message contents in a list of
messages. This is necessary because the Anthropic API doesn't allow
trailing whitespace in message content.
**Parameters:**
* **messages** (List\[OpenAIMessage]): List of messages to process
**Returns:**
List\[OpenAIMessage]: The processed messages with trailing whitespace
removed
## AnthropicModel
```python theme={"system"}
class AnthropicModel(BaseModelBackend):
```
Anthropic API in a unified BaseModelBackend interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of CLAUDE\_\* series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into Anthropic API. If :obj:`None`, :obj:`AnthropicConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Anthropic service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Anthropic service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`AnthropicTokenCounter` 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`)
* **client** (Optional\[Any], optional): A custom synchronous Anthropic client instance. If provided, this client will be used instead of creating a new one. (default: :obj:`None`)
* **async\_client** (Optional\[Any], optional): A custom asynchronous Anthropic client instance. If provided, this client will be used instead of creating a new one. (default: :obj:`None`)
* **use\_beta\_for\_structured\_outputs** (bool, optional): Whether to use the beta API for structured outputs. (default: :obj:`False`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
use_beta_for_structured_outputs: bool = False,
**kwargs: Any
):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
AnthropicTokenCounter: The token counter following the model's
tokenization style.
### \_convert\_openai\_to\_anthropic\_messages
```python theme={"system"}
def _convert_openai_to_anthropic_messages(self, messages: List[OpenAIMessage]):
```
Convert OpenAI format messages to Anthropic format.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Messages in OpenAI format.
**Returns:**
tuple\[Optional\[str], List\[Dict\[str, Any]]]: A tuple containing
the system message (if any) and the list of messages in
Anthropic format.
### \_convert\_anthropic\_to\_openai\_response
```python theme={"system"}
def _convert_anthropic_to_openai_response(self, response: Any, model: str):
```
Convert Anthropic API response to OpenAI ChatCompletion format.
**Parameters:**
* **response**: The response object from Anthropic API.
* **model** (str): The model name.
**Returns:**
ChatCompletion: Response in OpenAI format.
### \_convert\_anthropic\_stream\_to\_openai\_chunk
```python theme={"system"}
def _convert_anthropic_stream_to_openai_chunk(
self,
chunk: Any,
model: str,
tool_call_index: Dict[str, int],
finish_reason_sent: bool = False
):
```
Convert Anthropic streaming chunk to OpenAI ChatCompletionChunk.
**Parameters:**
* **chunk**: The streaming chunk from Anthropic API.
* **model** (str): The model name.
* **tool\_call\_index** (Dict\[str, int]): A mutable dict tracking tool call indices by their IDs, used to maintain consistent indexing across streaming chunks.
**Returns:**
ChatCompletionChunk: Chunk in OpenAI format.
### \_convert\_openai\_tools\_to\_anthropic
```python theme={"system"}
def _convert_openai_tools_to_anthropic(self, tools: Optional[List[Dict[str, Any]]]):
```
Convert OpenAI tools format to Anthropic tools format.
**Parameters:**
* **tools** (Optional\[List\[Dict\[str, Any]]]): Tools in OpenAI format.
**Returns:**
Optional\[List\[Dict\[str, Any]]]: Tools in Anthropic format.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Anthropic chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
* **response\_format** (Optional\[Type\[BaseModel]]): The format of the response. (Not supported by Anthropic API directly)
* **tools** (Optional\[List\[Dict\[str, Any]]]): The schema of the tools to use for the request.
**Returns:**
Union\[ChatCompletion, Stream\[ChatCompletionChunk]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
### \_wrap\_anthropic\_stream
```python theme={"system"}
def _wrap_anthropic_stream(self, stream: Any, model: str):
```
Wrap Anthropic streaming response to OpenAI Stream format.
**Parameters:**
* **stream**: The streaming response from Anthropic API.
* **model** (str): The model name.
**Returns:**
Stream\[ChatCompletionChunk]: Stream in OpenAI format.
### \_wrap\_anthropic\_async\_stream
```python theme={"system"}
def _wrap_anthropic_async_stream(self, stream: Any, model: str):
```
Wrap Anthropic async streaming response to OpenAI AsyncStream.
**Parameters:**
* **stream**: The async streaming response from Anthropic API.
* **model** (str): The model name.
**Returns:**
AsyncStream\[ChatCompletionChunk]: AsyncStream in OpenAI format.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.atlascloud_model
## AtlasCloudModel
```python theme={"system"}
class AtlasCloudModel(OpenAICompatibleModel):
```
LLM API served by AtlasCloud in a unified OpenAICompatibleModel
interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`AtlasCloudConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the AtlasCloud service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the AtlasCloud service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.aws_bedrock_model
## AWSBedrockModel
```python theme={"system"}
class AWSBedrockModel(OpenAICompatibleModel):
```
AWS Bedrock API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Dict\[str, Any], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`BedrockConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (str, optional): The API key for authenticating with the AWS Bedrock service. (default: :obj:`None`)
* **url** (str, optional): The url to the AWS Bedrock service.
* **token\_counter** (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
* **References**:
* **https**: //docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.azure_openai_model
## AzureOpenAIModel
```python theme={"system"}
class AzureOpenAIModel(BaseModelBackend):
```
Azure OpenAI API in a unified BaseModelBackend interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, Should be the deployment name you chose when you deployed an azure model.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`ChatGPTConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the OpenAI service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the OpenAI service. (default: :obj:`None`)
* **api\_version** (Optional\[str], optional): The api version for the model. (default: :obj:`None`)
* **azure\_ad\_token** (Optional\[str], optional): Your Azure Active Directory token, [https://www.microsoft.com/en-us/security/business/](https://www.microsoft.com/en-us/security/business/) identity-access/microsoft-entra-id. (default: :obj:`None`)
* **azure\_ad\_token\_provider** (Optional\[AzureADTokenProvider], optional): A function that returns an Azure Active Directory token, will be invoked on every request. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` 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`)
* **client** (Optional\[Any], optional): A custom synchronous AzureOpenAI 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 Azure OpenAI-compatible clients. The client should implement the AzureOpenAI client interface with `.chat.completions.create()` and `.beta.chat.completions.parse()` methods. (default: :obj:`None`)
* **async\_client** (Optional\[Any], optional): A custom asynchronous AzureOpenAI client instance. If provided, this client will be used instead of creating a new one. The client should implement the AsyncAzureOpenAI client interface. (default: :obj:`None`)
* **azure\_deployment\_name** (Optional\[str], optional): **Deprecated**. Use `model_type` parameter instead. This parameter is kept for backward compatibility and will be removed in a future version. (default: :obj:`None`) \*\*kwargs (Any): Additional arguments to pass to the client initialization. Ignored if custom clients are provided.
* **References**:
* **https**: //learn.microsoft.com/en-us/azure/ai-services/openai/
### **init**
```python theme={"system"}
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,
timeout: Optional[float] = None,
token_counter: Optional[BaseTokenCounter] = None,
api_version: Optional[str] = None,
azure_ad_token_provider: Optional['AzureADTokenProvider'] = None,
azure_ad_token: Optional[str] = None,
max_retries: int = 3,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
azure_deployment_name: Optional[str] = None,
**kwargs: Any
):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Azure OpenAI chat completion.
**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]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
`ChatCompletionStreamManager[BaseModel]` for
structured output streaming.
### \_request\_chat\_completion
```python theme={"system"}
def _request_chat_completion(
self,
messages: List[OpenAIMessage],
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_request\_parse
```python theme={"system"}
def _request_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_request\_stream\_parse
```python theme={"system"}
def _request_stream_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
Request streaming structured output parsing.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.base_audio_model
## BaseAudioModel
```python theme={"system"}
class BaseAudioModel(ABC):
```
Base class for audio models providing Text-to-Speech (TTS) and
Speech-to-Text (STT) functionality.
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
url: Optional[str] = None,
timeout: Optional[float] = Constants.TIMEOUT_THRESHOLD
):
```
Initialize an instance of BaseAudioModel.
**Parameters:**
* **api\_key** (Optional\[str]): API key for the audio service. If not provided, will look for an environment variable specific to the implementation.
* **url** (Optional\[str]): Base URL for the audio API. If not provided, will use a default URL or look for an environment variable specific to the implementation.
* **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`)
### text\_to\_speech
```python theme={"system"}
def text_to_speech(self, input: str, **kwargs: Any):
```
Convert text to speech.
**Parameters:**
* **input** (str): The text to be converted to speech.
* **storage\_path** (str): The local path to store the generated speech file. \*\*kwargs (Any): Extra kwargs passed to the TTS API.
**Returns:**
Any: The response from the TTS API, which may vary by
implementation.
### speech\_to\_text
```python theme={"system"}
def speech_to_text(self, audio_file_path: str, **kwargs: Any):
```
Convert speech audio to text.
**Parameters:**
* **audio\_file\_path** (str): The audio file path to transcribe. \*\*kwargs (Any): Extra keyword arguments passed to the Speech-to-Text (STT) API.
**Returns:**
str: The transcribed text.
### \_ensure\_directory\_exists
```python theme={"system"}
def _ensure_directory_exists(self, file_path: str):
```
Ensure the directory for the given file path exists.
**Parameters:**
* **file\_path** (str): The file path for which to ensure the directory exists.
# null
Source: https://docs.camel-ai.org/reference/camel.models.base_model
## \_StreamLogger
```python theme={"system"}
class _StreamLogger:
```
Base for stream logging wrappers.
### **init**
```python theme={"system"}
def __init__(self, log_path: Optional[str], log_enabled: bool):
```
### \_collect
```python theme={"system"}
def _collect(self, chunk: ChatCompletionChunk):
```
### \_log
```python theme={"system"}
def _log(self):
```
## \_SyncStreamWrapper
```python theme={"system"}
class _SyncStreamWrapper(_StreamLogger):
```
Sync stream wrapper with logging.
### **init**
```python theme={"system"}
def __init__(
self,
stream: Union[Stream[ChatCompletionChunk], Generator[ChatCompletionChunk, None, None]],
log_path: Optional[str],
log_enabled: bool
):
```
### **iter**
```python theme={"system"}
def __iter__(self):
```
### **next**
```python theme={"system"}
def __next__(self):
```
### **enter**
```python theme={"system"}
def __enter__(self):
```
### **exit**
```python theme={"system"}
def __exit__(self, *_):
```
### **del**
```python theme={"system"}
def __del__(self):
```
## \_AsyncStreamWrapper
```python theme={"system"}
class _AsyncStreamWrapper(_StreamLogger):
```
Async stream wrapper with logging.
### **init**
```python theme={"system"}
def __init__(
self,
stream: Union[AsyncStream[ChatCompletionChunk], AsyncGenerator[ChatCompletionChunk, None]],
log_path: Optional[str],
log_enabled: bool
):
```
### **aiter**
```python theme={"system"}
def __aiter__(self):
```
### **del**
```python theme={"system"}
def __del__(self):
```
## ModelBackendMeta
```python theme={"system"}
class ModelBackendMeta(ABCMeta):
```
Metaclass that automatically preprocesses messages in run method.
Automatically wraps the run method of any class inheriting from
BaseModelBackend to preprocess messages (remove `` tags) before they
are sent to the model.
### **new**
```python theme={"system"}
def __new__(
mcs,
name,
bases,
namespace
):
```
Wraps run method with preprocessing if it exists in the class.
## BaseModelBackend
```python theme={"system"}
class BaseModelBackend(ABC):
```
Base class for different model backends.
It may be OpenAI API, a local LLM, a stub for unit tests, etc.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A config dictionary. (default: :obj:`{}`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` will be used. (default: :obj:`None`)
* **timeout** (Optional\[float], optional): The timeout value in seconds for API calls. (default: :obj:`None`)
* **max\_retries** (int, optional): Maximum number of retries for API calls. (default: :obj:`3`)
### **init**
```python theme={"system"}
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] = Constants.TIMEOUT_THRESHOLD,
max_retries: int = 3
):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_prepare\_request\_config
```python theme={"system"}
def _prepare_request_config(self, tools: Optional[List[Dict[str, Any]]] = None):
```
Prepare the request configuration dictionary.
Creates a deep copy of the model config and handles tool-related
parameters. If no tools are specified, removes parallel\_tool\_calls
as OpenAI API only allows it when tools are present.
**Parameters:**
* **tools** (Optional\[List\[Dict\[str, Any]]]): The tools to include in the request. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: The prepared request configuration.
### preprocess\_messages
```python theme={"system"}
def preprocess_messages(self, messages: List[OpenAIMessage]):
```
Preprocess messages before sending to model API.
Removes thinking content from assistant and user messages.
Automatically formats messages for parallel tool calls if tools are
detected.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Original messages.
**Returns:**
List\[OpenAIMessage]: Preprocessed messages
### \_log\_request
```python theme={"system"}
def _log_request(self, messages: List[OpenAIMessage]):
```
Log the request messages to a JSON file if logging is enabled.
**Parameters:**
* **messages** (List\[OpenAIMessage]): The messages to log.
**Returns:**
Optional\[str]: The path to the log file if logging is enabled,
None otherwise.
### \_log\_response
```python theme={"system"}
def _log_response(self, log_path: str, response: Any):
```
Log the response to the existing log file.
**Parameters:**
* **log\_path** (str): The path to the log file.
* **response** (Any): The response to log.
### \_log\_and\_trace
```python theme={"system"}
def _log_and_trace(self):
```
Update Langfuse trace with session metadata.
This method updates the current Langfuse trace with agent session
information and model metadata. Called at the start of \_run() and
\_arun() methods before API execution.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs the query to the backend model in a non-stream mode.
**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], Any]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode,
or `ChatCompletionStreamManager[BaseModel]` in the structured
stream mode.
### run
```python theme={"system"}
def run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs the query to the backend model.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
* **response\_format** (Optional\[Type\[BaseModel]]): The response format to use for the model. (default: :obj:`None`)
* **tools** (Optional\[List\[Tool]]): The schema of tools to use for the model for this request. Will override the tools specified in the model configuration (but not change the configuration). (default: :obj:`None`)
**Returns:**
Union\[ChatCompletion, Stream\[ChatCompletionChunk], Any]:
`ChatCompletion` in the non-stream mode,
`Stream[ChatCompletionChunk]` in the stream mode, or
`ChatCompletionStreamManager[BaseModel]` in the structured
stream mode.
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Count the number of tokens in the messages using the specific
tokenizer.
**Parameters:**
* **messages** (List\[Dict]): message list with the chat history in OpenAI API format.
**Returns:**
int: Number of tokens in the messages.
### \_to\_chat\_completion
```python theme={"system"}
def _to_chat_completion(self, response: ParsedChatCompletion):
```
### token\_limit
```python theme={"system"}
def token_limit(self):
```
**Returns:**
int: The maximum token limit for the given model.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.cerebras_model
## CerebrasModel
```python theme={"system"}
class CerebrasModel(OpenAICompatibleModel):
```
LLM API served by Cerebras in a unified
OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`CerebrasConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Cerebras service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the Cerebras service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.cohere_model
## CohereModel
```python theme={"system"}
class CohereModel(BaseModelBackend):
```
Cohere API in a unified BaseModelBackend interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of Cohere series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`cohere.ClientV2().chat()`. If :obj:`None`, :obj:`CohereConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Cohere service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Cohere service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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,
**kwargs: Any
):
```
### \_to\_openai\_response
```python theme={"system"}
def _to_openai_response(self, response: 'ChatResponse'):
```
### \_to\_cohere\_chatmessage
```python theme={"system"}
def _to_cohere_chatmessage(self, messages: List[OpenAIMessage]):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_prepare\_request
```python theme={"system"}
def _prepare_request(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Cohere chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
ChatCompletion.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.cometapi_model
## CometAPIModel
```python theme={"system"}
class CometAPIModel(OpenAICompatibleModel):
```
LLM API served by CometAPI in a unified OpenAICompatibleModel
interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`CometAPIConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the CometAPI service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the CometAPI service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.crynux_model
## CrynuxModel
```python theme={"system"}
class CrynuxModel(OpenAICompatibleModel):
```
Constructor for Crynux backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`CrynuxConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Crynux service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Crynux service. If not provided, "[https://bridge.crynux.ai/v1/llm](https://bridge.crynux.ai/v1/llm)" will be used. (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.
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.deepseek_model
## DeepSeekModel
```python theme={"system"}
class DeepSeekModel(OpenAICompatibleModel):
```
DeepSeek API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`DeepSeekConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the DeepSeek service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the DeepSeek service. (default: :obj:`https://api.deepseek.com`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
* **References**:
* **https**: //api-docs.deepseek.com/
### **init**
```python theme={"system"}
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
):
```
### \_prepare\_request
```python theme={"system"}
def _prepare_request(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of DeepSeek chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
Union\[ChatCompletion, Stream\[ChatCompletionChunk]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.fish_audio_model
## FishAudioModel
```python theme={"system"}
class FishAudioModel(BaseAudioModel):
```
Provides access to FishAudio's Text-to-Speech (TTS) and Speech\_to\_Text
(STT) models.
### **init**
```python theme={"system"}
def __init__(self, api_key: Optional[str] = None, url: Optional[str] = None):
```
Initialize an instance of FishAudioModel.
**Parameters:**
* **api\_key** (Optional\[str]): API key for FishAudio service. If not provided, the environment variable `FISHAUDIO_API_KEY` will be used.
* **url** (Optional\[str]): Base URL for FishAudio API. If not provided, the environment variable `FISHAUDIO_API_BASE_URL` will be used.
### text\_to\_speech
```python theme={"system"}
def text_to_speech(self, input: str, **kwargs: Any):
```
Convert text to speech and save the output to a file.
**Parameters:**
* **input** (str): The text to convert to speech.
* **storage\_path** (Optional\[str]): The file path where the resulting speech will be saved. (default: :obj:`None`)
* **reference\_id** (Optional\[str]): An optional reference ID to associate with the request. (default: :obj:`None`)
* **reference\_audio** (Optional\[str]): Path to an audio file for reference speech. (default: :obj:`None`)
* **reference\_audio\_text** (Optional\[str]): Text for the reference audio. (default: :obj:`None`) \*\*kwargs (Any): Additional parameters to pass to the TTS request.
### speech\_to\_text
```python theme={"system"}
def speech_to_text(
self,
audio_file_path: str,
language: Optional[str] = None,
ignore_timestamps: Optional[bool] = None,
**kwargs: Any
):
```
Convert speech to text from an audio file.
**Parameters:**
* **audio\_file\_path** (str): The path to the audio file to transcribe.
* **language** (Optional\[str]): The language of the audio. (default: :obj:`None`)
* **ignore\_timestamps** (Optional\[bool]): Whether to ignore timestamps. (default: :obj:`None`) \*\*kwargs (Any): Additional parameters to pass to the STT request.
**Returns:**
str: The transcribed text from the audio.
# null
Source: https://docs.camel-ai.org/reference/camel.models.function_gemma_model
## FunctionGemmaModel
```python theme={"system"}
class FunctionGemmaModel(BaseModelBackend):
```
FunctionGemma model backend for Ollama with custom tool calling format.
FunctionGemma is a specialized Gemma model fine-tuned for function calling.
It uses a custom chat template format that differs from OpenAI's format.
This backend handles conversion between CAMEL's OpenAI-style tool schemas
and FunctionGemma's native format.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created (e.g., "functiongemma").
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary of configuration options. If :obj:`None`, :obj:`FunctionGemmaConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): Not required for local Ollama. (default: :obj:`None`)
* **url** (Optional\[str], optional): The URL to the Ollama server. (default: :obj:`http://localhost:11434`)
* **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`)
### **init**
```python theme={"system"}
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
):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_escape\_string
```python theme={"system"}
def _escape_string(self, s: str):
```
Wrap string values in `` tags for FunctionGemma format.
**Parameters:**
* **s** (str): The string to escape.
**Returns:**
str: The escaped string.
### \_unescape\_string
```python theme={"system"}
def _unescape_string(self, s: str):
```
Remove `` tags from string values.
**Parameters:**
* **s** (str): The string to unescape.
**Returns:**
str: The unescaped string.
### \_type\_to\_function\_gemma
```python theme={"system"}
def _type_to_function_gemma(self, json_type: Union[str, List[str]]):
```
Convert JSON schema type to FunctionGemma type (uppercase).
**Parameters:**
* **json\_type** (Union\[str, List\[str]]): The JSON schema type. Can be a string like "string" or a list like \["string", "null"] for optional parameters.
**Returns:**
str: The FunctionGemma type.
### \_format\_parameter\_properties
```python theme={"system"}
def _format_parameter_properties(self, properties: Dict[str, Any], required: List[str]):
```
Format parameter properties for FunctionGemma declaration.
**Parameters:**
* **properties** (Dict\[str, Any]): The properties dictionary.
* **required** (List\[str]): List of required parameter names.
**Returns:**
str: Formatted properties string.
### \_convert\_tool\_to\_function\_gemma
```python theme={"system"}
def _convert_tool_to_function_gemma(self, tool: Dict[str, Any]):
```
Convert OpenAI tool schema to FunctionGemma declaration format.
**Parameters:**
* **tool** (Dict\[str, Any]): The OpenAI tool schema.
**Returns:**
str: The FunctionGemma declaration string.
### \_format\_developer\_turn
```python theme={"system"}
def _format_developer_turn(self, content: str, tools: Optional[List[Dict[str, Any]]] = None):
```
Format the developer/system turn with function declarations.
**Parameters:**
* **content** (str): The system message content.
* **tools** (Optional\[List\[Dict\[str, Any]]]): List of tool schemas.
**Returns:**
str: Formatted developer turn.
### \_format\_user\_turn
```python theme={"system"}
def _format_user_turn(self, content: str):
```
Format a user message turn.
**Parameters:**
* **content** (str): The user message content.
**Returns:**
str: Formatted user turn.
### \_format\_model\_turn
```python theme={"system"}
def _format_model_turn(self, message: OpenAIMessage):
```
Format an assistant/model message turn.
**Parameters:**
* **message** (OpenAIMessage): The assistant message.
**Returns:**
str: Formatted model turn.
### \_format\_tool\_response
```python theme={"system"}
def _format_tool_response(self, message: OpenAIMessage):
```
Format a tool response message.
**Parameters:**
* **message** (OpenAIMessage): The tool response message.
**Returns:**
str: Formatted tool response.
### \_format\_messages
```python theme={"system"}
def _format_messages(
self,
messages: List[OpenAIMessage],
tools: Optional[List[Dict[str, Any]]] = None
):
```
Format all messages into a FunctionGemma prompt string.
**Parameters:**
* **messages** (List\[OpenAIMessage]): List of messages in OpenAI format.
* **tools** (Optional\[List\[Dict\[str, Any]]]): List of tool schemas.
**Returns:**
str: Complete formatted prompt.
### \_extract\_function\_calls
```python theme={"system"}
def _extract_function_calls(self, text: str, tools: Optional[List[Dict[str, Any]]] = None):
```
Extract function calls from model output.
**Parameters:**
* **text** (str): The model output text.
* **tools** (Optional\[List\[Dict\[str, Any]]]): Available tools to infer function names when the model outputs malformed calls.
**Returns:**
Tuple\[str, List\[Dict\[str, Any]]]: Tuple of
(remaining\_content, list\_of\_tool\_calls).
### \_infer\_function\_name
```python theme={"system"}
def _infer_function_name(self, args_str: str, tools: Optional[List[Dict[str, Any]]]):
```
Infer the function name from available tools.
**Parameters:**
* **args\_str** (str): The arguments string from the model output.
* **tools** (Optional\[List\[Dict\[str, Any]]]): Available tools.
**Returns:**
Optional\[str]: The inferred function name, or None if not found.
### \_parse\_function\_args
```python theme={"system"}
def _parse_function_args(self, args_str: str):
```
Parse function arguments from FunctionGemma format.
**Parameters:**
* **args\_str** (str): The arguments string (e.g., "a:15,b:27").
**Returns:**
Dict\[str, Any]: Parsed arguments dictionary.
### \_parse\_value
```python theme={"system"}
def _parse_value(self, value: str):
```
Parse a value string to appropriate Python type.
**Parameters:**
* **value** (str): The value string.
**Returns:**
Any: Parsed value (int, float, bool, or str).
### \_to\_chat\_completion
```python theme={"system"}
def _to_chat_completion(
self,
response_text: str,
model: str,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Convert parsed response to OpenAI ChatCompletion format.
**Parameters:**
* **response\_text** (str): The model response text.
* **model** (str): The model name.
* **tools** (Optional\[List\[Dict\[str, Any]]]): Available tools for function name inference.
**Returns:**
ChatCompletion: OpenAI-compatible ChatCompletion object.
### \_call\_ollama\_generate
```python theme={"system"}
def _call_ollama_generate(self, prompt: str):
```
Call Ollama's /api/generate endpoint with raw prompt.
**Parameters:**
* **prompt** (str): The formatted prompt string.
**Returns:**
str: The model response text.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Run inference using FunctionGemma via Ollama.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
* **response\_format** (Optional\[Type\[BaseModel]]): Not supported for FunctionGemma. (default: :obj:`None`)
* **tools** (Optional\[List\[Dict\[str, Any]]]): The schema of the tools to use for the request.
**Returns:**
ChatCompletion: The model response in OpenAI ChatCompletion format.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Always False for FunctionGemma.
# null
Source: https://docs.camel-ai.org/reference/camel.models.gemini_model
## GeminiModel
```python theme={"system"}
class GeminiModel(OpenAICompatibleModel):
```
Gemini API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of Gemini series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`GeminiConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Gemini service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Gemini service. (default: :obj:`https://generativelanguage.googleapis.com/v1beta/ openai/`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
### \_process\_messages
```python theme={"system"}
def _process_messages(self, messages):
```
Process the messages for Gemini API to ensure no empty content,
which is not accepted by Gemini. Also preserves thought signatures
required for Gemini 3 Pro function calling.
This method also merges consecutive assistant messages with single
tool calls into a single assistant message with multiple tool calls,
as required by Gemini's OpenAI-compatible API for parallel function
calling.
### \_preserve\_thought\_signatures
```python theme={"system"}
def _preserve_thought_signatures(
self,
response: Union[ChatCompletion, Stream[ChatCompletionChunk], AsyncStream[ChatCompletionChunk]]
):
```
Preserve thought signatures from Gemini responses for future
requests.
According to the Gemini documentation, when a response contains tool
calls with thought signatures, these signatures must be preserved
exactly as received when the response is added to conversation history
for subsequent requests.
**Parameters:**
* **response**: The response from Gemini API
**Returns:**
The response with thought signatures properly preserved.
For streaming responses, returns generators that preserve
signatures.
### \_wrap\_stream\_with\_thought\_preservation
```python theme={"system"}
def _wrap_stream_with_thought_preservation(self, stream: Stream[ChatCompletionChunk]):
```
Wrap a streaming response to preserve thought signatures in tool
calls.
This method ensures that when Gemini streaming responses contain tool
calls with thought signatures, these are properly preserved in the
extra\_content field for future conversation context.
**Parameters:**
* **stream**: The original streaming response from Gemini
**Returns:**
A wrapped stream that preserves thought signatures
### \_wrap\_async\_stream\_with\_thought\_preservation
```python theme={"system"}
def _wrap_async_stream_with_thought_preservation(self, stream: AsyncStream[ChatCompletionChunk]):
```
Wrap an async streaming response to preserve thought signatures in
tool calls.
This method ensures that when Gemini async streaming responses contain
tool calls with thought signatures, these are properly preserved in
the extra\_content field for future conversation context.
**Parameters:**
* **stream**: The original async streaming response from Gemini
**Returns:**
A wrapped async stream that preserves thought signatures
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Gemini chat completion.
**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]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
### \_request\_chat\_completion
```python theme={"system"}
def _request_chat_completion(
self,
messages: List[OpenAIMessage],
tools: Optional[List[Dict[str, Any]]] = None
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.groq_model
## GroqModel
```python theme={"system"}
class GroqModel(OpenAICompatibleModel):
```
LLM API served by Groq in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`GroqConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Groq service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the Groq service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.internlm_model
## InternLMModel
```python theme={"system"}
class InternLMModel(OpenAICompatibleModel):
```
InternLM API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of InternLM series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`InternLMConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the InternLM service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the InternLM service. (default: :obj:`https://internlm-chat.intern-ai.org.cn/puyu/api/v1`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.litellm_model
## LiteLLMModel
```python theme={"system"}
class LiteLLMModel(BaseModelBackend):
```
Constructor for LiteLLM backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, such as GPT-3.5-turbo, Claude-2, etc.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`completion()`. If:obj:`None`, :obj:`LiteLLMConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`LiteLLMTokenCounter` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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,
**kwargs: Any
):
```
### \_convert\_response\_from\_litellm\_to\_openai
```python theme={"system"}
def _convert_response_from_litellm_to_openai(self, response):
```
Converts a response from the LiteLLM format to the OpenAI format.
**Parameters:**
* **response** (LiteLLMResponse): The response object from LiteLLM.
**Returns:**
ChatCompletion: The response object in OpenAI's format.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of LiteLLM chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI format.
**Returns:**
ChatCompletion
# null
Source: https://docs.camel-ai.org/reference/camel.models.lmstudio_model
## LMStudioModel
```python theme={"system"}
class LMStudioModel(OpenAICompatibleModel):
```
LLM served by LMStudio in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`LMStudioConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. LMStudio doesn't need API key, it would be ignored if set. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the LMStudio service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.minimax_model
## MinimaxModel
```python theme={"system"}
class MinimaxModel(OpenAICompatibleModel):
```
LLM API served by Minimax in a unified OpenAICompatibleModel
interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`MinimaxConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Minimax service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the Minimax M2 service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.mistral_model
## MistralModel
```python theme={"system"}
class MistralModel(BaseModelBackend):
```
Mistral API in a unified BaseModelBackend interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of MISTRAL\_\* series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`Mistral.chat.complete()`.
* **If**: obj:`None`, :obj:`MistralConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the mistral service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the mistral service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
### \_to\_openai\_response
```python theme={"system"}
def _to_openai_response(self, response: 'ChatCompletionResponse'):
```
### \_to\_mistral\_chatmessage
```python theme={"system"}
def _to_mistral_chatmessage(self, messages: List[OpenAIMessage]):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Mistral chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
* **response\_format** (Optional\[Type\[BaseModel]]): The format of the response for this query.
* **tools** (Optional\[List\[Dict\[str, Any]]]): The tools to use for this query.
**Returns:**
ChatCompletion: The response from the model.
### \_prepare\_request
```python theme={"system"}
def _prepare_request(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.model_factory
## ModelFactory
```python theme={"system"}
class ModelFactory:
```
### create
```python theme={"system"}
def create(
model_platform: Union[ModelPlatformType, str],
model_type: Union[ModelType, str, UnifiedModelType],
model_config_dict: Optional[Dict] = None,
token_counter: Optional[BaseTokenCounter] = None,
api_key: Optional[str] = None,
url: Optional[str] = None,
timeout: Optional[float] = None,
max_retries: int = 3,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
**kwargs
):
```
Creates an instance of `BaseModelBackend` of the specified type.
**Parameters:**
* **model\_platform** (Union\[ModelPlatformType, str]): Platform from which the model originates. Can be a string or ModelPlatformType enum.
* **model\_type** (Union\[ModelType, str, UnifiedModelType]): Model for which a backend is created. Can be a string, ModelType enum, or UnifiedModelType.
* **model\_config\_dict** (Optional\[Dict]): A dictionary that will be fed into the backend constructor. (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 if the model platform didn't provide official token counter. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service. (default: :obj:`None`)
* **timeout** (Optional\[float], optional): The timeout value in seconds for API calls. (default: :obj:`None`)
* **max\_retries** (int, optional): Maximum number of retries for API calls. (default: :obj:`3`)
* **client** (Optional\[Any], optional): A custom synchronous client instance. Supported by models that use OpenAI-compatible APIs . The client should implement the appropriate client interface for the platform. (default: :obj:`None`)
* **async\_client** (Optional\[Any], optional): A custom asynchronous client instance. Supported by models that use OpenAI-compatible APIs. The client should implement the appropriate async client interface for the platform. (default: :obj:`None`) \*\*kwargs: Additional model-specific parameters that will be passed to the model constructor. For example, Azure OpenAI models may require `api_version`, `azure_deployment_name`, `azure_ad_token_provider`, and `azure_ad_token`.
**Returns:**
BaseModelBackend: The initialized backend.
### \_\_parse\_model\_platform
```python theme={"system"}
def __parse_model_platform(cls, model_platform_str: str):
```
Parses a string and returns the corresponding ModelPlatformType
enum.
**Parameters:**
* **model\_platform\_str** (str): The platform name as a string. Can be in the form "ModelPlatformType.``" or simply "``".
**Returns:**
ModelPlatformType: The matching enum value.
### \_\_load\_yaml
```python theme={"system"}
def __load_yaml(cls, filepath: str):
```
### \_\_load\_json
```python theme={"system"}
def __load_json(cls, filepath: str):
```
Loads and parses a JSON file into a dictionary.
**Parameters:**
* **filepath** (str): Path to the JSON configuration file.
**Returns:**
Dict: The parsed JSON content as a dictionary.
### create\_from\_yaml
```python theme={"system"}
def create_from_yaml(cls, filepath: str):
```
Creates and returns a model base backend instance
from a YAML configuration file.
**Parameters:**
* **filepath** (str): Path to the YAML file containing model configuration.
**Returns:**
BaseModelBackend: An instance of the model backend based on the
configuration.
### create\_from\_json
```python theme={"system"}
def create_from_json(cls, filepath: str):
```
Creates and returns a base model backend instance
from a JSON configuration file.
**Parameters:**
* **filepath** (str): Path to the JSON file containing model configuration.
**Returns:**
BaseModelBackend: An instance of the model backend based on the
configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.models.model_manager
## ModelProcessingError
```python theme={"system"}
class ModelProcessingError(Exception):
```
Raised when an error occurs during model processing.
## ModelManager
```python theme={"system"}
class ModelManager:
```
ModelManager choosing a model from provided list.
Models are picked according to defined strategy.
**Parameters:**
* **models** (Union\[BaseModelBackend, List\[BaseModelBackend]]): model backend or list of model backends (e.g., model instances, APIs)
* **scheduling\_strategy** (str): name of function that defines how to select the next model. (default: :str:`round_robin`)
### **init**
```python theme={"system"}
def __init__(
self,
models: Union[BaseModelBackend, List[BaseModelBackend]],
scheduling_strategy: str = 'round_robin'
):
```
### model\_type
```python theme={"system"}
def model_type(self):
```
**Returns:**
Union\[ModelType, str]: Current model type.
### model\_config\_dict
```python theme={"system"}
def model_config_dict(self):
```
**Returns:**
Dict\[str, Any]: Config dictionary of the current model.
### model\_config\_dict
```python theme={"system"}
def model_config_dict(self, model_config_dict: Dict[str, Any]):
```
Set model\_config\_dict to the current model.
**Parameters:**
* **model\_config\_dict** (Dict\[str, Any]): Config dictionary to be set at current model.
### current\_model\_index
```python theme={"system"}
def current_model_index(self):
```
**Returns:**
int: index of current model in given list of models.
### num\_models
```python theme={"system"}
def num_models(self):
```
**Returns:**
int: The number of models available in the model manager.
### token\_limit
```python theme={"system"}
def token_limit(self):
```
**Returns:**
int: The maximum token limit for the given model.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### add\_strategy
```python theme={"system"}
def add_strategy(self, name: str, strategy_fn: Callable):
```
Add a scheduling strategy method provided by user in case when none
of existent strategies fits.
When custom strategy is provided, it will be set as
"self.scheduling\_strategy" attribute.
**Parameters:**
* **name** (str): The name of the strategy.
* **strategy\_fn** (Callable): The scheduling strategy function.
### round\_robin
```python theme={"system"}
def round_robin(self):
```
**Returns:**
BaseModelBackend for processing incoming messages.
### always\_first
```python theme={"system"}
def always_first(self):
```
**Returns:**
BaseModelBackend for processing incoming messages.
### random\_model
```python theme={"system"}
def random_model(self):
```
**Returns:**
BaseModelBackend for processing incoming messages.
### run
```python theme={"system"}
def run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Process a list of messages by selecting a model based on
the scheduling strategy.
Sends the entire list of messages to the selected model,
and returns a single response.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
Union\[ChatCompletion, Stream\[ChatCompletionChunk],
ChatCompletionStreamManager\[BaseModel]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode, or
`ChatCompletionStreamManager[BaseModel]` for
structured-output stream.
# null
Source: https://docs.camel-ai.org/reference/camel.models.modelscope_model
## ModelScopeModel
```python theme={"system"}
class ModelScopeModel(OpenAICompatibleModel):
```
ModelScope API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of ModelScope series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`ModelScopeConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The MODELSCOPE\_SDK\_TOKEN for authenticating with the ModelScope service. (default: :obj:`None`) refer to the following link for more details:
* **https**: //modelscope.cn/my/myaccesstoken
* **url** (Optional\[str], optional): The url to the ModelScope service. (default: :obj:`https://api-inference.modelscope.cn/v1/`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.moonshot_model
## MoonshotModel
```python theme={"system"}
class MoonshotModel(OpenAICompatibleModel):
```
Moonshot API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of Moonshot series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into :obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`MoonshotConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Moonshot service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Moonshot service. For Chinese users, use :obj:`https://api.moonshot.cn/v1`. For overseas users, the default endpoint will be used. (default: :obj:`https://api.moonshot.ai/v1`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter( ModelType.GPT_4)` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
### \_prepare\_request
```python theme={"system"}
def _prepare_request(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Prepare the request configuration for Moonshot API.
**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:**
Dict\[str, Any]: The prepared request configuration.
### \_clean\_tool\_schemas
```python theme={"system"}
def _clean_tool_schemas(self, tools: List[Dict[str, Any]]):
```
Clean tool schemas to remove null types for Moonshot compatibility.
Moonshot API doesn't accept `{"type": "null"}` in anyOf schemas.
This method removes null type definitions from parameters.
**Parameters:**
* **tools** (List\[Dict\[str, Any]]): Original tool schemas.
**Returns:**
List\[Dict\[str, Any]]: Cleaned tool schemas.
# null
Source: https://docs.camel-ai.org/reference/camel.models.nebius_model
## NebiusModel
```python theme={"system"}
class NebiusModel(OpenAICompatibleModel):
```
LLM API served by Nebius AI Studio in a unified OpenAICompatibleModel
interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`NebiusConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Nebius AI Studio service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the Nebius AI Studio service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.nemotron_model
## NemotronModel
```python theme={"system"}
class NemotronModel(OpenAICompatibleModel):
```
Nemotron model API backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Nvidia service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Nvidia service. (default: :obj:`https://integrate.api.nvidia.com/v1`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
**Note:**
Nemotron model doesn't support additional model config like OpenAI.
### **init**
```python theme={"system"}
def __init__(
self,
model_type: Union[ModelType, str],
api_key: Optional[str] = None,
url: Optional[str] = None,
timeout: Optional[float] = None,
max_retries: int = 3,
**kwargs: Any
):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.netmind_model
## NetmindModel
```python theme={"system"}
class NetmindModel(OpenAICompatibleModel):
```
Constructor for Netmind backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, supported model can be found here:
* **https**: //[www.netmind.ai/modelsLibrary?expandList=Chat](http://www.netmind.ai/modelsLibrary?expandList=Chat)
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`NetmindConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Netmind service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Netmind service. If not provided, "[https://api.netmind.ai/inference-api/openai/v1](https://api.netmind.ai/inference-api/openai/v1)" will be used.(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.
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.novita_model
## NovitaModel
```python theme={"system"}
class NovitaModel(OpenAICompatibleModel):
```
Constructor for Novita backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, supported model can be found here:
* **https**: //novita.ai/models?utm\_source=github\_owl\&utm\_campaign=github\_link
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`NovitaConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Novita service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Novita service. If not provided, "[https://api.novita.ai/v3/openai](https://api.novita.ai/v3/openai)" will be used. (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.
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.nvidia_model
## NvidiaModel
```python theme={"system"}
class NvidiaModel(OpenAICompatibleModel):
```
NVIDIA API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of NVIDIA series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`NvidiaConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the NVIDIA service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the NVIDIA service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter( ModelType.GPT_4)` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.ollama_model
## OllamaModel
```python theme={"system"}
class OllamaModel(OpenAICompatibleModel):
```
Ollama service interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`OllamaConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. Required for Ollama cloud services. If not provided, defaults to "Not\_Provided". (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
* **References**:
* **https**: //github.com/ollama/ollama/blob/main/docs/openai.md
### **init**
```python theme={"system"}
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
):
```
### \_start\_server
```python theme={"system"}
def _start_server(self):
```
Starts the Ollama server in a subprocess.
# null
Source: https://docs.camel-ai.org/reference/camel.models.openai_audio_models
## OpenAIAudioModels
```python theme={"system"}
class OpenAIAudioModels(BaseAudioModel):
```
Provides access to OpenAI's Text-to-Speech (TTS) and Speech\_to\_Text
(STT) models.
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
url: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initialize an instance of OpenAI.
### text\_to\_speech
```python theme={"system"}
def text_to_speech(self, input: str, **kwargs: Any):
```
Convert text to speech using OpenAI's TTS model. This method
converts the given input text to speech using the specified model and
voice.
**Parameters:**
* **input** (str): The text to be converted to speech.
* **model\_type** (AudioModelType, optional): The TTS model to use. Defaults to `AudioModelType.TTS_1`.
* **voice** (VoiceType, optional): The voice to be used for generating speech. Defaults to `VoiceType.ALLOY`.
* **storage\_path** (str, optional): The local path to store the generated speech file if provided, defaults to `None`. \*\*kwargs (Any): Extra kwargs passed to the TTS API.
**Returns:**
Union\[List\[\_legacy\_response.HttpxBinaryResponseContent],
\_legacy\_response.HttpxBinaryResponseContent]: List of response
content object from OpenAI if input characters more than 4096,
single response content if input characters less than 4096.
### \_split\_audio
```python theme={"system"}
def _split_audio(self, audio_file_path: str, chunk_size_mb: int = 24):
```
Split the audio file into smaller chunks. Since the Whisper API
only supports files that are less than 25 MB.
**Parameters:**
* **audio\_file\_path** (str): Path to the input audio file.
* **chunk\_size\_mb** (int, optional): Size of each chunk in megabytes. Defaults to `24`.
**Returns:**
list: List of paths to the split audio files.
### speech\_to\_text
```python theme={"system"}
def speech_to_text(
self,
audio_file_path: str,
translate_into_english: bool = False,
**kwargs: Any
):
```
Convert speech audio to text.
**Parameters:**
* **audio\_file\_path** (str): The audio file path, supporting one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
* **translate\_into\_english** (bool, optional): Whether to translate the speech into English. Defaults to `False`. \*\*kwargs (Any): Extra keyword arguments passed to the Speech-to-Text (STT) API.
**Returns:**
str: The output text.
### audio\_question\_answering
```python theme={"system"}
def audio_question_answering(
self,
audio_file_path: str,
question: str,
model: str = 'gpt-4o-mini-audio-preview',
**kwargs: Any
):
```
Answer a question directly using the audio content.
**Parameters:**
* **audio\_file\_path** (str): The path to the audio file.
* **question** (str): The question to ask about the audio content.
* **model** (str, optional): The model to use for audio question answering. (default: :obj:`"gpt-4o-mini-audio-preview"`) \*\*kwargs (Any): Extra keyword arguments passed to the chat completions API.
**Returns:**
str: The model's response to the question.
# null
Source: https://docs.camel-ai.org/reference/camel.models.openai_compatible_model
## OpenAICompatibleModel
```python theme={"system"}
class OpenAICompatibleModel(BaseModelBackend):
```
Constructor for model backend supporting OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`{}` will be used. (default: :obj:`None`)
* **api\_key** (str): The API key for authenticating with the model service.
* **url** (str): The url to the model service.
* **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`)
* **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.
### **init**
```python theme={"system"}
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,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
**kwargs: Any
):
```
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of OpenAI chat completion.
**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]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
`ChatCompletionStreamManager[BaseModel]` for
structured output streaming.
### \_request\_chat\_completion
```python theme={"system"}
def _request_chat_completion(
self,
messages: List[OpenAIMessage],
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_request\_parse
```python theme={"system"}
def _request_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_request\_stream\_parse
```python theme={"system"}
def _request_stream_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
Request streaming structured output parsing.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
OpenAITokenCounter: The token counter following the model's
tokenization style.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.openai_model
## OpenAIModel
```python theme={"system"}
class OpenAIModel(BaseModelBackend):
```
OpenAI API in a unified BaseModelBackend interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of GPT\_\* series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`ChatGPTConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the OpenAI service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the OpenAI service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` 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`)
* **client** (Optional\[Any], optional): A custom synchronous OpenAI 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. 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 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.
### **init**
```python theme={"system"}
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,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
**kwargs: Any
):
```
### \_sanitize\_config
```python theme={"system"}
def _sanitize_config(self, config_dict: Dict[str, Any]):
```
Sanitize the model configuration for O1 models.
### \_adapt\_messages\_for\_o1\_models
```python theme={"system"}
def _adapt_messages_for_o1_models(self, messages: List[OpenAIMessage]):
```
Adjust message roles to comply with O1 model requirements by
converting 'system' or 'developer' to 'user' role.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
processed\_messages (List\[OpenAIMessage]): Return a new list of
messages to avoid mutating input.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of OpenAI chat completion.
**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],
ChatCompletionStreamManager\[BaseModel]]:
`ChatCompletion` in the non-stream mode,
`Stream[ChatCompletionChunk]`in the stream mode,
or `ChatCompletionStreamManager[BaseModel]` for
structured output streaming.
### \_request\_chat\_completion
```python theme={"system"}
def _request_chat_completion(
self,
messages: List[OpenAIMessage],
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_request\_parse
```python theme={"system"}
def _request_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_request\_stream\_parse
```python theme={"system"}
def _request_stream_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
Request streaming structured output parsing.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.openrouter_model
## OpenRouterModel
```python theme={"system"}
class OpenRouterModel(OpenAICompatibleModel):
```
LLM API served by OpenRouter in a unified OpenAICompatibleModel
interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`.
* **If**: obj:`None`, :obj:`GroqConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the OpenRouter service. (default: :obj:`None`).
* **url** (Optional\[str], optional): The url to the OpenRouter service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.ppio_model
## PPIOModel
```python theme={"system"}
class PPIOModel(OpenAICompatibleModel):
```
Constructor for PPIO backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, supported model can be found here:
* **https**: //ppinfra.com/model-api/product/llm-api?utm\_source=github\_owl
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`PPIOConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the PPIO service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the PPIO service. If not provided, "[https://api.ppinfra.com/v3/openai](https://api.ppinfra.com/v3/openai)" will be used. (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.
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.qianfan_model
## QianfanModel
```python theme={"system"}
class QianfanModel(OpenAICompatibleModel):
```
Constructor for Qianfan backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, supported model can be found here:
* **https**: //cloud.baidu.com/doc/QIANFANWORKSHOP/s/Wm9cvy6rl
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`QianfanConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Qianfan service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Qianfan service. If not provided, "[https://qianfan.baidubce.com/v2/chat/completions](https://qianfan.baidubce.com/v2/chat/completions)" will be used.(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.
* **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** (Optional\[int], optional): Maximum number of retries for API calls. (default: :obj:`None`) \*\*kwargs: Additional model-specific parameters that will be passed to the model constructor.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.qwen_model
## QwenModel
```python theme={"system"}
class QwenModel(OpenAICompatibleModel):
```
Qwen API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of Qwen series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`QwenConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Qwen service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Qwen service. (default: :obj:`https://dashscope.aliyuncs.com/compatible-mode/v1`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.reka_model
## RekaModel
```python theme={"system"}
class RekaModel(BaseModelBackend):
```
Reka API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of REKA\_\* series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`Reka.chat.create()`. If :obj:`None`, :obj:`RekaConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Reka service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Reka service. (default: :obj:`None`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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,
**kwargs: Any
):
```
### \_convert\_reka\_to\_openai\_response
```python theme={"system"}
def _convert_reka_to_openai_response(self, response: 'ChatResponse'):
```
Converts a Reka `ChatResponse` to an OpenAI-style `ChatCompletion`
response.
**Parameters:**
* **response** (ChatResponse): The response object from the Reka API.
**Returns:**
ChatCompletion: An OpenAI-compatible chat completion response.
### \_convert\_openai\_to\_reka\_messages
```python theme={"system"}
def _convert_openai_to_reka_messages(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[str]] = None
):
```
Converts OpenAI API messages to Reka API messages.
**Parameters:**
* **messages** (List\[OpenAIMessage]): A list of messages in OpenAI format.
**Returns:**
List\[ChatMessage]: A list of messages converted to Reka's format.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Mistral chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
ChatCompletion.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.reward.base_reward_model
## BaseRewardModel
```python theme={"system"}
class BaseRewardModel(ABC):
```
Abstract base class for reward models. Reward models are used to
evaluate messages and return scores based on different criteria.
Subclasses should implement the 'evaluate' and 'get\_scores\_types' methods.
### **init**
```python theme={"system"}
def __init__(
self,
model_type: Union[ModelType, str],
api_key: Optional[str] = None,
url: Optional[str] = None
):
```
### evaluate
```python theme={"system"}
def evaluate(self, messages: List[Dict[str, str]]):
```
Evaluate the messages and return scores based on different
criteria.
**Parameters:**
* **messages** (List\[Dict\[str, str]]): A list of messages where each message is a dictionary with 'role' and 'content'.
**Returns:**
Dict\[str, float]: A dictionary mapping score types to their values.
### get\_scores\_types
```python theme={"system"}
def get_scores_types(self):
```
**Returns:**
List\[str]: A list of score types that the reward model can return.
# null
Source: https://docs.camel-ai.org/reference/camel.models.reward.evaluator
## Evaluator
```python theme={"system"}
class Evaluator:
```
Evaluator class to evaluate messages using a reward model and filter
data based on the scores.
**Parameters:**
* **reward\_model** (BaseRewardModel): A reward model to evaluate messages.
### **init**
```python theme={"system"}
def __init__(self, reward_model: BaseRewardModel):
```
### evaluate
```python theme={"system"}
def evaluate(self, messages: List[Dict[str, str]]):
```
Evaluate the messages using the reward model.
**Parameters:**
* **messages** (List\[Dict\[str, str]]): A list of messages where each message is a dictionary with 'role' and 'content'.
**Returns:**
Dict\[str, float]: A dictionary mapping score types to their values.
### filter\_data
```python theme={"system"}
def filter_data(
self,
messages: List[Dict[str, str]],
thresholds: Dict[str, float]
):
```
Filter messages based on the scores.
**Parameters:**
* **messages** (List\[Dict\[str, str]]): A list of messages where each message is a dictionary with 'role' and 'content'.
* **thresholds** (Dict\[str, float]): A dictionary mapping score types to their values.
**Returns:**
bool: A boolean indicating whether the messages pass the filter.
# null
Source: https://docs.camel-ai.org/reference/camel.models.reward.nemotron_model
## NemotronRewardModel
```python theme={"system"}
class NemotronRewardModel(BaseRewardModel):
```
Reward model based on the Nemotron model with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service.
**Note:**
The Nemotron model does not support model config.
### **init**
```python theme={"system"}
def __init__(
self,
model_type: Union[ModelType, str],
api_key: Optional[str] = None,
url: Optional[str] = None
):
```
### evaluate
```python theme={"system"}
def evaluate(self, messages: List[Dict[str, str]]):
```
Evaluate the messages using the Nemotron model.
**Parameters:**
* **messages** (List\[Dict\[str, str]]): A list of messages where each message is a dictionary format.
**Returns:**
Dict\[str, float]: A dictionary mapping score types to their
values.
### get\_scores\_types
```python theme={"system"}
def get_scores_types(self):
```
**Returns:**
List\[str]: A list of score types that the reward model can return.
### \_parse\_scores
```python theme={"system"}
def _parse_scores(self, response: ChatCompletion):
```
Parse the scores from the response.
**Parameters:**
* **response** (ChatCompletion): A ChatCompletion object with the scores.
**Returns:**
Dict\[str, float]: A dictionary mapping score types to their values.
# null
Source: https://docs.camel-ai.org/reference/camel.models.reward.skywork_model
## SkyworkRewardModel
```python theme={"system"}
class SkyworkRewardModel(BaseRewardModel):
```
Reward model based on the transformers, it will download the model
from huggingface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **api\_key** (Optional\[str], optional): Not used. (default: :obj:`None`)
* **url** (Optional\[str], optional): Not used. (default: :obj:`None`)
* **device\_map** (Optional\[str], optional): choose the device map. (default: :obj:`auto`)
* **attn\_implementation** (Optional\[str], optional): choose the attention implementation. (default: :obj:`flash_attention_2`)
* **offload\_folder** (Optional\[str], optional): choose the offload folder. (default: :obj:`offload`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: Union[ModelType, str],
api_key: Optional[str] = None,
url: Optional[str] = None,
device_map: Optional[str] = 'auto',
attn_implementation: Optional[str] = 'flash_attention_2',
offload_folder: Optional[str] = 'offload'
):
```
### evaluate
```python theme={"system"}
def evaluate(self, messages: List[Dict[str, str]]):
```
Evaluate the messages using the Skywork model.
**Parameters:**
* **messages** (List\[Dict\[str, str]]): A list of messages.
**Returns:**
ChatCompletion: A ChatCompletion object with the scores.
### get\_scores\_types
```python theme={"system"}
def get_scores_types(self):
```
**Returns:**
List\[str]: list of scores types
# null
Source: https://docs.camel-ai.org/reference/camel.models.samba_model
## SambaModel
```python theme={"system"}
class SambaModel(BaseModelBackend):
```
SambaNova service interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a SambaNova backend is created. Supported models via SambaNova Cloud: `https://community.sambanova.ai/t/supported-models/193`. Supported models via SambaVerse API is listed in `https://sambaverse.sambanova.ai/models`.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`SambaCloudAPIConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the SambaNova service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the SambaNova service. Current support SambaVerse API: :obj:`"https://sambaverse.sambanova.ai/api/predict"` and SambaNova Cloud: :obj:`"https://api.sambanova.ai/v1"` (default: :obj:`https://api. sambanova.ai/v1`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter( ModelType.GPT_4O_MINI)` will be used.
* **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. Only applicable when using SambaNova Cloud API. (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. Only applicable when using SambaNova Cloud API. (default: :obj:`None`) \*\*kwargs (Any): Additional arguments to pass to the client initialization. Ignored if custom clients are provided.
### **init**
```python theme={"system"}
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,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
**kwargs: Any
):
```
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs SambaNova's service.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
Union\[ChatCompletion, Stream\[ChatCompletionChunk]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
### \_run\_streaming
```python theme={"system"}
def _run_streaming(self, messages: List[OpenAIMessage]):
```
Handles streaming inference with SambaNova's API.
**Parameters:**
* **messages** (List\[OpenAIMessage]): A list of messages representing the chat history in OpenAI API format.
**Returns:**
Stream\[ChatCompletionChunk]: A generator yielding
`ChatCompletionChunk` objects as they are received from the
API.
### \_run\_non\_streaming
```python theme={"system"}
def _run_non_streaming(self, messages: List[OpenAIMessage]):
```
Handles non-streaming inference with SambaNova's API.
**Parameters:**
* **messages** (List\[OpenAIMessage]): A list of messages representing the message in OpenAI API format.
**Returns:**
ChatCompletion: A `ChatCompletion` object containing the complete
response from the API.
### \_sambaverse\_to\_openai\_response
```python theme={"system"}
def _sambaverse_to_openai_response(self, samba_response: Dict[str, Any]):
```
Converts SambaVerse API response into an OpenAI-compatible
response.
**Parameters:**
* **samba\_response** (Dict\[str, Any]): A dictionary representing responses from the SambaVerse API.
**Returns:**
ChatCompletion: A `ChatCompletion` object constructed from the
aggregated response data.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.sglang_model
## SGLangModel
```python theme={"system"}
class SGLangModel(BaseModelBackend):
```
SGLang service interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`SGLangConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. SGLang doesn't need API key, it would be ignored if set. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service. If not provided, :obj:`"http://127.0.0.1:30000/v1"` will be used. (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`)
* **client** (Optional\[Any], optional): A custom synchronous OpenAI-compatible client instance. If provided, this client will be used instead of creating a new one. Note: When using custom clients with SGLang, server auto-start features will be disabled. (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. (default: :obj:`None`) \*\*kwargs (Any): Additional arguments to pass to the client initialization. Ignored if custom clients are provided.
* **Reference**: [https://sgl-project.github.io/backend/openai\_api\_completions](https://sgl-project.github.io/backend/openai_api_completions). html
### **init**
```python theme={"system"}
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,
client: Optional[Any] = None,
async_client: Optional[Any] = None,
**kwargs: Any
):
```
### \_start\_server
```python theme={"system"}
def _start_server(self):
```
### \_ensure\_server\_running
```python theme={"system"}
def _ensure_server_running(self):
```
Ensures that the server is running. If not, starts the server.
### \_monitor\_inactivity
```python theme={"system"}
def _monitor_inactivity(self):
```
Monitor whether the server process has been inactive for over 10
minutes.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of OpenAI chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
Union\[ChatCompletion, Stream\[ChatCompletionChunk]]:
`ChatCompletion` in the non-stream mode, or
`Stream[ChatCompletionChunk]` in the stream mode.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
### **del**
```python theme={"system"}
def __del__(self):
```
Properly clean up resources when the model is destroyed.
### cleanup
```python theme={"system"}
def cleanup(self):
```
Terminate the server process and clean up resources.
## \_terminate\_process
```python theme={"system"}
def _terminate_process(process):
```
## \_kill\_process\_tree
```python theme={"system"}
def _kill_process_tree(
parent_pid,
include_parent: bool = True,
skip_pid: Optional[int] = None
):
```
Kill the process and all its child processes.
## \_execute\_shell\_command
```python theme={"system"}
def _execute_shell_command(command: str):
```
Execute a shell command and return the process handle
**Parameters:**
* **command**: Shell command as a string (can include \ line continuations)
**Returns:**
subprocess.Popen: Process handle
## \_wait\_for\_server
```python theme={"system"}
def _wait_for_server(base_url: str, timeout: Optional[float] = 30):
```
Wait for the server to be ready by polling the /v1/models endpoint.
**Parameters:**
* **base\_url** (str): The base URL of the server
* **timeout** (Optional\[float]): Maximum time to wait in seconds. (default: :obj:`30`)
# null
Source: https://docs.camel-ai.org/reference/camel.models.siliconflow_model
## SiliconFlowModel
```python theme={"system"}
class SiliconFlowModel(OpenAICompatibleModel):
```
SiliconFlow API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into OpenAI client. If :obj:`None`, :obj:`SiliconFlowConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the SiliconFlow service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The URL to the SiliconFlow service. If not provided, :obj:`https://api.siliconflow.cn/v1/` will be used. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.stub_model
## StubTokenCounter
```python theme={"system"}
class StubTokenCounter(BaseTokenCounter):
```
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Token counting for STUB models, directly returning a constant.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
int: A constant to act as the number of the tokens in the
messages.
### encode
```python theme={"system"}
def encode(self, text: str):
```
Encode text into token IDs for STUB models.
**Parameters:**
* **text** (str): The text to encode.
**Returns:**
List\[int]: List of token IDs.
### decode
```python theme={"system"}
def decode(self, token_ids: List[int]):
```
Decode token IDs back to text for STUB models.
**Parameters:**
* **token\_ids** (List\[int]): List of token IDs to decode.
**Returns:**
str: Decoded text.
## StubModel
```python theme={"system"}
class StubModel(BaseModelBackend):
```
A dummy model used for unit tests.
### **init**
```python theme={"system"}
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
):
```
All arguments are unused for the dummy model.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
**Returns:**
Dict\[str, Any]: Response in the OpenAI API format.
# null
Source: https://docs.camel-ai.org/reference/camel.models.togetherai_model
## TogetherAIModel
```python theme={"system"}
class TogetherAIModel(OpenAICompatibleModel):
```
Constructor for Together AI backend with OpenAI compatibility.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, supported model can be found here:
* **https**: //docs.together.ai/docs/chat-models
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`TogetherAIConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Together service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Together AI service. If not provided, "[https://api.together.xyz/v1](https://api.together.xyz/v1)" will be used. (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.
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.vllm_model
## VLLMModel
```python theme={"system"}
class VLLMModel(OpenAICompatibleModel):
```
vLLM service interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`VLLMConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the model service. vLLM doesn't need API key, it would be ignored if set. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the model service. If not provided, :obj:`"http://localhost:8000/v1"` will be used. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
* **References**:
* **https**: //docs.vllm.ai/en/latest/serving/openai\_compatible\_server.html
### **init**
```python theme={"system"}
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
):
```
### \_start\_server
```python theme={"system"}
def _start_server(self):
```
Starts the vllm server in a subprocess.
# null
Source: https://docs.camel-ai.org/reference/camel.models.volcano_model
## VolcanoModel
```python theme={"system"}
class VolcanoModel(OpenAICompatibleModel):
```
Volcano Engine API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into the API call. If :obj:`None`, :obj:`{}` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Volcano Engine service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Volcano Engine service. (default: :obj:`https://ark.cn-beijing.volces.com/api/v3`)
* **token\_counter** (Optional\[BaseTokenCounter], optional): Token counter to use for the model. If not provided, :obj:`OpenAITokenCounter` 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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
### \_inject\_reasoning\_content
```python theme={"system"}
def _inject_reasoning_content(self, messages: List[OpenAIMessage]):
```
Inject the last reasoning\_content into assistant messages.
For Volcano Engine's doubao-seed models with deep thinking enabled,
the reasoning\_content from the model response needs to be passed back
in subsequent requests for proper context management.
**Parameters:**
* **messages**: The original messages list.
**Returns:**
Messages with reasoning\_content added to the last assistant
message that has tool\_calls.
### \_extract\_reasoning\_content
```python theme={"system"}
def _extract_reasoning_content(self, response: ChatCompletion):
```
Extract reasoning\_content from the model response.
**Parameters:**
* **response**: The model response.
**Returns:**
The reasoning\_content if available, None otherwise.
### run
```python theme={"system"}
def run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of Volcano Engine chat completion.
Overrides the base run method to inject reasoning\_content from
previous responses into subsequent requests, as required by
Volcano Engine's doubao-seed models with deep thinking enabled.
**Parameters:**
* **messages**: Message list with the chat history in OpenAI API format.
* **response\_format**: The format of the response.
* **tools**: The schema of the tools to use for the request.
**Returns:**
ChatCompletion in the non-stream mode, or
Stream\[ChatCompletionChunk] in the stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.watsonx_model
## WatsonXModel
```python theme={"system"}
class WatsonXModel(BaseModelBackend):
```
WatsonX API in a unified BaseModelBackend interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model type for which a backend is created, one of WatsonX series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into :obj:`ModelInference.chat()`.
* **If**: obj:`None`, :obj:`WatsonXConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the WatsonX service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the WatsonX service. (default: :obj:`None`)
* **project\_id** (Optional\[str], optional): The project ID authenticating with the WatsonX service. (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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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,
project_id: Optional[str] = None,
token_counter: Optional[BaseTokenCounter] = None,
timeout: Optional[float] = None,
**kwargs: Any
):
```
### \_to\_openai\_response
```python theme={"system"}
def _to_openai_response(self, response: Dict[str, Any]):
```
Convert WatsonX response to OpenAI format.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
**Returns:**
BaseTokenCounter: The token counter following the model's
tokenization style.
### \_prepare\_request
```python theme={"system"}
def _prepare_request(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
### \_run
```python theme={"system"}
def _run(
self,
messages: List[OpenAIMessage],
response_format: Optional[Type[BaseModel]] = None,
tools: Optional[List[Dict[str, Any]]] = None
):
```
Runs inference of WatsonX chat completion.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
* **response\_format** (Optional\[Type\[BaseModel]], optional): The response format. (default: :obj:`None`)
* **tools** (Optional\[List\[Dict\[str, Any]]], optional): tools to use. (default: :obj:`None`)
**Returns:**
ChatCompletion.
### stream
```python theme={"system"}
def stream(self):
```
**Returns:**
bool: Whether the model is in stream mode.
# null
Source: https://docs.camel-ai.org/reference/camel.models.yi_model
## YiModel
```python theme={"system"}
class YiModel(OpenAICompatibleModel):
```
Yi API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of Yi series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`YiConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Yi service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the Yi service. (default: :obj:`https://api.lingyiwanwu.com/v1`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.models.zhipuai_model
## ZhipuAIModel
```python theme={"system"}
class ZhipuAIModel(OpenAICompatibleModel):
```
ZhipuAI API in a unified OpenAICompatibleModel interface.
**Parameters:**
* **model\_type** (Union\[ModelType, str]): Model for which a backend is created, one of GLM\_\* series.
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`ZhipuAIConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the ZhipuAI service. (default: :obj:`None`)
* **url** (Optional\[str], optional): The url to the ZhipuAI service. (default: :obj:`https://open.bigmodel.cn/api/paas/v4/`)
* **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`) \*\*kwargs (Any): Additional arguments to pass to the client initialization.
### **init**
```python theme={"system"}
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
):
```
### \_request\_parse
```python theme={"system"}
def _request_parse(
self,
messages: List[OpenAIMessage],
response_format: Type[BaseModel],
tools: Optional[List[Dict[str, Any]]] = None
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.parsers.mcp_tool_call_parser
Utility functions for parsing MCP tool calls from model output.
## extract\_tool\_calls\_from\_text
```python theme={"system"}
def extract_tool_calls_from_text(content: str):
```
Extract tool call dictionaries from raw text output.
## \_collect\_tool\_calls
```python theme={"system"}
def _collect_tool_calls(payload: Any, accumulator: List[Dict[str, Any]]):
```
Collect valid tool call dictionaries from parsed payloads.
## \_try\_parse\_json\_like
```python theme={"system"}
def _try_parse_json_like(snippet: str):
```
Parse a JSON or JSON-like snippet into Python data.
## \_find\_json\_candidate
```python theme={"system"}
def _find_json_candidate(content: str, start_idx: int):
```
Locate a balanced JSON-like segment starting at `__INLINE_CODE_0__`.
## \_truncate\_snippet
```python theme={"system"}
def _truncate_snippet(snippet: str, limit: int = 120):
```
Return a truncated representation suitable for logging.
# null
Source: https://docs.camel-ai.org/reference/camel.personas.persona
## Persona
```python theme={"system"}
class Persona(BaseModel):
```
A persona is a character in the society.
**Parameters:**
* **name** (Optional\[str]): Name of the persona.
* **description** (Optional\[str]): Description of the persona.
* **text\_to\_persona\_prompt** (Union\[TextPrompt, str]): The prompt to convert text into a persona.
* **persona\_to\_persona\_prompt** (Union\[TextPrompt, str]): Persona-to-Persona interaction prompt.
* **id** (uuid.UUID): The unique identifier for the persona, automatically generated.
* **\_id** (uuid.UUID): Internal unique identifier for the persona, generated lazily using `uuid.uuid4`.
* **model\_config** (ClassVar\[ConfigDict]): Configuration for the Pydantic model. Allows arbitrary types and includes custom JSON schema settings.
### id
```python theme={"system"}
def id(self):
```
### model\_json\_schema
```python theme={"system"}
def model_json_schema(cls):
```
### dict
```python theme={"system"}
def dict(self, *args, **kwargs):
```
### json
```python theme={"system"}
def json(self, *args, **kwargs):
```
# null
Source: https://docs.camel-ai.org/reference/camel.personas.persona_hub
## PersonaHub
```python theme={"system"}
class PersonaHub:
```
The PersonaHub adapted from ["Scaling Synthetic Data Creation with 1,
000,000,000 Personas"](https://github.com/tencent-ailab/persona-hub).
PersonaHub proposes a novel persona-driven data synthesis methodology
that leverages various perspectives within a large language model (LLM) to
create diverse synthetic data. By showcasing PersonaHub's use cases in
synthesizing high-quality mathematical and logical reasoning problems,
instructions (i.e., user prompts), knowledge-rich texts, game NPCs and
tools (functions) at scale, the authors demonstrate persona-driven data
synthesis is versatile, scalable, flexible, and easy to use, potentially
driving a paradigm shift in synthetic data creation and applications in
practice, which may have a profound impact on LLM research and development.
Please refer to the paper for more details: [https://arxiv.org/pdf/2406.20094](https://arxiv.org/pdf/2406.20094).
**Parameters:**
* **model** (BaseModelBackend, optional): The model to use for persona generation and manipulation. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, model: Optional[BaseModelBackend] = None):
```
### **setitem**
```python theme={"system"}
def __setitem__(self, persona: Persona):
```
Add a persona to the group.
**Parameters:**
* **persona** (Persona): The persona to add.
### **delitem**
```python theme={"system"}
def __delitem__(self, persona_id: uuid.UUID):
```
Remove a persona from the group by ID.
**Parameters:**
* **persona\_id** (uuid.UUID): The ID of the persona to remove.
### **getitem**
```python theme={"system"}
def __getitem__(self, persona_id: uuid.UUID):
```
Get a persona by ID.
**Parameters:**
* **persona\_id** (uuid.UUID): The ID of the persona to retrieve.
### text\_to\_persona
```python theme={"system"}
def text_to_persona(
self,
text: str,
action: Literal['read', 'write', 'like', 'dislike'] = 'read'
):
```
Infers a specific persona who is likely to \[read|write|like|dislike
|...] the given text.
**Parameters:**
* **text** (str): The input text for which to infer a persona.
* **action** (str): The action associated with the persona (default is "read").
**Returns:**
Persona: The inferred persona.
### persona\_to\_persona
```python theme={"system"}
def persona_to_persona(self, persona: Persona):
```
Derives additional personas based on interpersonal relationships
from this persona.
**Parameters:**
* **persona** (Persona): The persona from which to derive related personas.
**Returns:**
Dict\[uuid.UUID, Persona]: A dictionary of related personas.
### deduplicate
```python theme={"system"}
def deduplicate(
self,
embedding_model: Optional[BaseEmbedding] = None,
similarity_threshold: float = 0.85
):
```
Remove similar personas from the group.
**Parameters:**
* **embedding\_model** (BaseEmbedding): The embedding model for similarity compairsion. (default is `None`).
* **similarity\_threshold** (float): The similarity threshold for deduplication (default is `0.85`).
### \_get\_embedding
```python theme={"system"}
def _get_embedding(embedding_model: BaseEmbedding, description: Optional[str]):
```
Cache embeddings to reduce recomputation.
### \_cosine\_similarity
```python theme={"system"}
def _cosine_similarity(vec1: np.ndarray, vec2: np.ndarray):
```
Copmute the cosine similarity of two vectors.
**Parameters:**
* **vec1** (np.ndarray): Vector 1
* **vec2** (np.ndarray): Vector 2
### \_is\_similar
```python theme={"system"}
def _is_similar(
self,
persona1: Persona,
persona2: Persona,
similarity_threshold: float,
embedding_model: BaseEmbedding
):
```
Check if two personas are similar by consine similarity
of the embeddings of their descriptions.
**Parameters:**
* **persona1** (Persona1): A persona.
* **persona2** (Persona2): The other persona.
* **similarity\_threshold** (float): The threshold on consine similarity to determine whether the two personas are similar.
* **embedding\_model** (BaseEmbedding): The embedding model for similarity compairsion.
### **len**
```python theme={"system"}
def __len__(self):
```
### **iter**
```python theme={"system"}
def __iter__(self):
```
### get\_all\_personas
```python theme={"system"}
def get_all_personas(self):
```
Return a list of all personas.
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.ai_society
## AISocietyPromptTemplateDict
```python theme={"system"}
class AISocietyPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `AI Society`
task.
**Parameters:**
* **GENERATE\_ASSISTANTS** (TextPrompt): A prompt to list different roles that the AI assistant can play.
* **GENERATE\_USERS** (TextPrompt): A prompt to list common groups of internet users or occupations.
* **GENERATE\_TASKS** (TextPrompt): A prompt to list diverse tasks that the AI assistant can assist AI user with.
* **TASK\_SPECIFY\_PROMPT** (TextPrompt): A prompt to specify a task in more detail.
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant that outlines the rules of the conversation and provides instructions for completing tasks.
* **USER\_PROMPT** (TextPrompt): A system prompt for the AI user that outlines the rules of the conversation and provides instructions for giving instructions to the AI assistant.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.base
## return\_prompt\_wrapper
```python theme={"system"}
def return_prompt_wrapper(cls: Any, func: Callable):
```
Wrapper that converts the return value of a function to an input
class instance if it's a string.
**Parameters:**
* **cls** (Any): The class to convert to.
* **func** (Callable): The function to decorate.
**Returns:**
Callable\[..., Union\[Any, str]]: Decorated function that
returns the decorated class instance if the return value is a
string.
## wrap\_prompt\_functions
```python theme={"system"}
def wrap_prompt_functions(cls: T):
```
Decorator that wraps functions of a class inherited from :obj:`str`
with the :obj:`return_text_prompt` decorator.
**Parameters:**
* **cls** (type): The class to decorate.
**Returns:**
type: Decorated class with wrapped functions.
## TextPrompt
```python theme={"system"}
class TextPrompt(str):
```
A class that represents a text prompt. The :obj:`TextPrompt` class
extends the built-in :obj:`str` class to provide a property for retrieving
the set of keywords in the prompt.
**Parameters:**
* **key\_words** (set): A set of strings representing the keywords in the prompt.
### key\_words
```python theme={"system"}
def key_words(self):
```
Returns a set of strings representing the keywords in the prompt.
### format
```python theme={"system"}
def format(self, *args: Any, **kwargs: Any):
```
Overrides the built-in :obj:`str.format` method to allow for
default values in the format string. This is used to allow formatting
the partial string.
**Returns:**
TextPrompt: A new :obj:`TextPrompt` object with the format string
replaced with the formatted string.
## CodePrompt
```python theme={"system"}
class CodePrompt(TextPrompt):
```
A class that represents a code prompt. It extends the :obj:`TextPrompt`
class with a :obj:`code_type` property.
**Parameters:**
* **code\_type** (str, optional): The type of code. Defaults to None.
### **new**
```python theme={"system"}
def __new__(cls, *args: Any, **kwargs: Any):
```
Creates a new instance of the :obj:`CodePrompt` class.
**Returns:**
CodePrompt: The created :obj:`CodePrompt` instance.
### code\_type
```python theme={"system"}
def code_type(self):
```
**Returns:**
Optional\[str]: The type of code.
### set\_code\_type
```python theme={"system"}
def set_code_type(self, code_type: str):
```
Sets the type of code.
**Parameters:**
* **code\_type** (str): The type of code.
### execute
```python theme={"system"}
def execute(
self,
interpreter: Optional[BaseInterpreter] = None,
**kwargs: Any
):
```
Executes the code string using the provided interpreter.
This method runs a code string through either a specified interpreter
or a default one. It supports additional keyword arguments for
flexibility.
**Parameters:**
* **interpreter** (Optional\[BaseInterpreter]): The interpreter instance to use for execution. If `None`, a default interpreter is used. (default: :obj:`None`) \*\*kwargs: Additional keyword arguments passed to the interpreter to run the code.
**Returns:**
str: The result of the code execution. If the execution fails, this
should include sufficient information to diagnose and correct
the issue.
## TextPromptDict
```python theme={"system"}
class TextPromptDict:
```
A dictionary class that maps from key to :obj:`TextPrompt` object.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.code
## CodePromptTemplateDict
```python theme={"system"}
class CodePromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `Code` task.
**Parameters:**
* **GENERATE\_LANGUAGES** (TextPrompt): A prompt to list different computer programming languages.
* **GENERATE\_DOMAINS** (TextPrompt): A prompt to list common fields of study that programming could help with.
* **GENERATE\_TASKS** (TextPrompt): A prompt to list diverse tasks that the AI assistant can assist AI user with.
* **TASK\_SPECIFY\_PROMPT** (TextPrompt): A prompt to specify a task in more detail.
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant that outlines the rules of the conversation and provides instructions for completing tasks.
* **USER\_PROMPT** (TextPrompt): A system prompt for the AI user that outlines the rules of the conversation and provides instructions for giving instructions to the AI assistant.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.evaluation
## EvaluationPromptTemplateDict
```python theme={"system"}
class EvaluationPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `Evaluation`
task.
**Parameters:**
* **GENERATE\_QUESTIONS** (TextPrompt): A prompt to generate a set of questions to be used for evaluating emergence of knowledge based on a particular field of knowledge.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.generate_text_embedding_data
## GenerateTextEmbeddingDataPromptTemplateDict
```python theme={"system"}
class GenerateTextEmbeddingDataPromptTemplateDict(TextPromptDict):
```
A :obj:`TextPrompt` dictionary containing text embedding tasks
generation, query, positive and hard negative samples generation,
from the ["Improving Text Embeddings with Large Language Models"](https://arxiv.org/abs/2401.00368) paper.
**Parameters:**
* **GENERATE\_TASKS** (TextPrompt): A prompt to generate a list
* **of**: obj:`num_tasks` synthetic text\_embedding tasks.
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant to generate synthetic :obj:`user_query`, :obj:`positive document`,
* **and**: obj:`hard_negative_document` for a specific :obj:`task` with specified parameters including :obj:`query_type`, :obj:`query_length`, :obj:`clarity`, :obj:`num_words`, :obj:`language` and :obj:`difficulty`.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.image_craft
## ImageCraftPromptTemplateDict
```python theme={"system"}
class ImageCraftPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `ImageCraft`
task.
**Parameters:**
* **ASSISTANT\_PROMPT** (TextPrompt): A prompt for the AI assistant to create an original image based on the provided descriptive captions.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.misalignment
## MisalignmentPromptTemplateDict
```python theme={"system"}
class MisalignmentPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `Misalignment`
task.
**Parameters:**
* **DAN\_PROMPT** (TextPrompt): A prompt for jail breaking.
* **GENERATE\_TASKS** (TextPrompt): A prompt to list unique malicious that the AI assistant can assist AI user with.
* **TASK\_SPECIFY\_PROMPT** (TextPrompt): A prompt to specify a task in more detail.
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant that outlines the rules of the conversation and provides instructions for completing tasks.
* **USER\_PROMPT** (TextPrompt): A system prompt for the AI user that outlines the rules of the conversation and provides instructions for giving instructions to the AI assistant.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.persona_hub
## PersonaHubPrompt
```python theme={"system"}
class PersonaHubPrompt(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used for generating and
relating personas based on given text or existing personas.
This class inherits from TextPromptDict, allowing for easy access and
management of the prompts.
**Parameters:**
* **TEXT\_TO\_PERSONA** (TextPrompt): A prompt for inferring a persona from a given text. This prompt asks to identify who is likely to interact with the provided text in various ways (read, write, like, dislike). The response should follow a specific template format.
* **PERSONA\_TO\_PERSONA** (TextPrompt): A prompt for deriving related personas based on a given persona. This prompt asks to describe personas who might have a close relationship with the provided persona. The response should follow a specific template format, allowing for multiple related personas.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.prompt_templates
## PromptTemplateGenerator
```python theme={"system"}
class PromptTemplateGenerator:
```
A class for generating prompt templates for tasks.
**Parameters:**
* **task\_prompt\_template\_dict** (TaskPromptTemplateDict, optional): A dictionary of task prompt templates for each task type. If not provided, an empty dictionary is used as default.
### **init**
```python theme={"system"}
def __init__(
self,
task_prompt_template_dict: Optional[TaskPromptTemplateDict] = None
):
```
### get\_prompt\_from\_key
```python theme={"system"}
def get_prompt_from_key(self, task_type: TaskType, key: Any):
```
Generates a text prompt using the specified :obj:`task_type` and
:obj:`key`.
**Parameters:**
* **task\_type** (TaskType): The type of task.
* **key** (Any): The key used to generate the prompt.
**Returns:**
TextPrompt: The generated text prompt.
### get\_system\_prompt
```python theme={"system"}
def get_system_prompt(self, task_type: TaskType, role_type: RoleType):
```
Generates a text prompt for the system role, using the specified
:obj:`task_type` and :obj:`role_type`.
**Parameters:**
* **task\_type** (TaskType): The type of task.
* **role\_type** (RoleType): The type of role, either "USER" or "ASSISTANT".
**Returns:**
TextPrompt: The generated text prompt.
### get\_generate\_tasks\_prompt
```python theme={"system"}
def get_generate_tasks_prompt(self, task_type: TaskType):
```
Gets the prompt for generating tasks for a given task type.
**Parameters:**
* **task\_type** (TaskType): The type of the task.
**Returns:**
TextPrompt: The generated prompt for generating tasks.
### get\_task\_specify\_prompt
```python theme={"system"}
def get_task_specify_prompt(self, task_type: TaskType):
```
Gets the prompt for specifying a task for a given task type.
**Parameters:**
* **task\_type** (TaskType): The type of the task.
**Returns:**
TextPrompt: The generated prompt for specifying a task.
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.role_description_prompt_template
## RoleDescriptionPromptTemplateDict
```python theme={"system"}
class RoleDescriptionPromptTemplateDict(AISocietyPromptTemplateDict):
```
A dictionary containing :obj:`TextPrompt` used in the `role description`
task.
**Parameters:**
* **ROLE\_DESCRIPTION\_PROMPT** (TextPrompt): A default prompt to describe the role descriptions.
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant that outlines the rules of the conversation and provides instructions for completing tasks.
* **USER\_PROMPT** (TextPrompt): A system prompt for the AI user that outlines the rules of the conversation and provides instructions for giving instructions to the AI assistant.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.solution_extraction
## SolutionExtractionPromptTemplateDict
```python theme={"system"}
class SolutionExtractionPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `SolutionExtraction`
task.
**Parameters:**
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant that outlines the rules of the conversation and provides instructions for completing tasks.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.task_prompt_template
## TaskPromptTemplateDict
```python theme={"system"}
class TaskPromptTemplateDict:
```
A dictionary (:obj:`Dict[Any, TextPromptDict]`) of task prompt
templates keyed by task type. This dictionary is used to map from
a task type to its corresponding prompt template dictionary.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.translation
## TranslationPromptTemplateDict
```python theme={"system"}
class TranslationPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `Translation`
task.
**Parameters:**
* **ASSISTANT\_PROMPT** (TextPrompt): A system prompt for the AI assistant that outlines the rules of the conversation and provides instructions for completing tasks.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.prompts.video_description_prompt
## VideoDescriptionPromptTemplateDict
```python theme={"system"}
class VideoDescriptionPromptTemplateDict(TextPromptDict):
```
A dictionary containing :obj:`TextPrompt` used in the `VideoDescription`
task.
**Parameters:**
* **ASSISTANT\_PROMPT** (TextPrompt): A prompt for the AI assistant to provide a shot description of the content of the current video.
### **init**
```python theme={"system"}
def __init__(self, *args: Any, **kwargs: Any):
```
# null
Source: https://docs.camel-ai.org/reference/camel.responses.agent_responses
## ChatAgentResponse
```python theme={"system"}
class ChatAgentResponse(BaseModel):
```
Response of a ChatAgent.
**Parameters:**
* **msgs** (List\[BaseMessage]): A list of zero, one or several messages. If the list is empty, there is some error in message generation. If the list has one message, this is normal mode. If the list has several messages, this is the critic mode.
* **terminated** (bool): A boolean indicating whether the agent decided to terminate the chat session.
* **info** (Dict\[str, Any]): Extra information about the chat message.
### msg
```python theme={"system"}
def msg(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.auto_retriever
## AutoRetriever
```python theme={"system"}
class AutoRetriever:
```
Facilitates the automatic retrieval of information using a
query-based approach with pre-defined elements.
**Parameters:**
* **url\_and\_api\_key** (Optional\[Tuple\[str, str]]): URL and API key for accessing the vector storage remotely.
* **vector\_storage\_local\_path** (Optional\[str]): Local path for vector storage, if applicable.
* **storage\_type** (Optional\[StorageType]): The type of vector storage to use. Defaults to `StorageType.QDRANT`.
* **embedding\_model** (Optional\[BaseEmbedding]): Model used for embedding queries and documents. Defaults to `OpenAIEmbedding()`.
### **init**
```python theme={"system"}
def __init__(
self,
url_and_api_key: Optional[Tuple[str, str]] = None,
vector_storage_local_path: Optional[str] = None,
storage_type: Optional[StorageType] = None,
embedding_model: Optional[BaseEmbedding] = None
):
```
### \_initialize\_vector\_storage
```python theme={"system"}
def _initialize_vector_storage(self, collection_name: Optional[str] = None):
```
Sets up and returns a vector storage instance with specified
parameters.
**Parameters:**
* **collection\_name** (Optional\[str]): Name of the collection in the vector storage.
**Returns:**
BaseVectorStorage: Configured vector storage instance.
### \_collection\_name\_generator
```python theme={"system"}
def _collection_name_generator(self, content: Union[str, 'Element']):
```
Generates a valid collection name from a given file path or URL.
**Parameters:**
* **content** (Union\[str, Element]): Local file path, remote URL, string content or Element object.
**Returns:**
str: A sanitized, valid collection name suitable for use.
### run\_vector\_retriever
```python theme={"system"}
def run_vector_retriever(
self,
query: str,
contents: Union[str, List[str], 'Element', List['Element']],
top_k: int = Constants.DEFAULT_TOP_K_RESULTS,
similarity_threshold: float = Constants.DEFAULT_SIMILARITY_THRESHOLD,
return_detailed_info: bool = False,
max_characters: int = 500
):
```
Executes the automatic vector retriever process using vector
storage.
**Parameters:**
* **query** (str): Query string for information retriever.
* **contents** (Union\[str, List\[str], Element, List\[Element]]): Local file paths, remote URLs, string contents or Element objects.
* **top\_k** (int, optional): The number of top results to return during retrieve. Must be a positive integer. Defaults to `DEFAULT_TOP_K_RESULTS`.
* **similarity\_threshold** (float, optional): The similarity threshold for filtering results. Defaults to `DEFAULT_SIMILARITY_THRESHOLD`.
* **return\_detailed\_info** (bool, optional): Whether to return detailed information including similarity score, content path and metadata. Defaults to `False`.
* **max\_characters** (int): Max number of characters in each chunk. Defaults to `500`.
**Returns:**
dict\[str, Sequence\[Collection\[str]]]: By default, returns
only the text information. If `return_detailed_info` is
`True`, return detailed information including similarity
score, content path and metadata.
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.base
## \_query\_unimplemented
```python theme={"system"}
def _query_unimplemented(self, *input: Any):
```
Defines the query behavior performed at every call.
Query the results. Subclasses should implement this
method according to their specific needs.
It should be overridden by all subclasses.
.. note::
Although the recipe for forward pass needs to be defined within
this function, one should call the :class:`BaseRetriever` instance
afterwards instead of this since the former takes care of running the
registered hooks while the latter silently ignores them.
## \_process\_unimplemented
```python theme={"system"}
def _process_unimplemented(self, *input: Any):
```
Defines the process behavior performed at every call.
Processes content from a file or URL, divides it into chunks by
using `Unstructured IO`,then stored internally. This method must be
called before executing queries with the retriever.
Should be overridden by all subclasses.
.. note::
Although the recipe for forward pass needs to be defined within
this function, one should call the :class:`BaseRetriever` instance
afterwards instead of this since the former takes care of running the
registered hooks while the latter silently ignores them.
## BaseRetriever
```python theme={"system"}
class BaseRetriever(ABC):
```
Abstract base class for implementing various types of information
retrievers.
### **init**
```python theme={"system"}
def __init__(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.bm25_retriever
## BM25Retriever
```python theme={"system"}
class BM25Retriever(BaseRetriever):
```
An implementation of the `BaseRetriever` using the `BM25` model.
This class facilitates the retriever of relevant information using a
query-based approach, it ranks documents based on the occurrence and
frequency of the query terms.
**Parameters:**
* **bm25** (BM25Okapi): An instance of the BM25Okapi class used for calculating document scores.
* **content\_input\_path** (str): The path to the content that has been processed and stored.
* **unstructured\_modules** (UnstructuredIO): A module for parsing files and URLs and chunking content based on specified parameters.
* **References**:
* **https**: //github.com/dorianbrown/rank\_bm25
### **init**
```python theme={"system"}
def __init__(self):
```
Initializes the BM25Retriever.
### process
```python theme={"system"}
def process(
self,
content_input_path: str,
chunk_type: str = 'chunk_by_title',
**kwargs: Any
):
```
Processes content from a file or URL, divides it into chunks by
using `Unstructured IO`,then stored internally. This method must be
called before executing queries with the retriever.
**Parameters:**
* **content\_input\_path** (str): File path or URL of the content to be processed.
* **chunk\_type** (str): Type of chunking going to apply. Defaults to "chunk\_by\_title". \*\*kwargs (Any): Additional keyword arguments for content parsing.
### query
```python theme={"system"}
def query(self, query: str, top_k: int = DEFAULT_TOP_K_RESULTS):
```
Executes a query and compiles the results.
**Parameters:**
* **query** (str): Query string for information retriever.
* **top\_k** (int, optional): The number of top results to return during retriever. Must be a positive integer. Defaults to `DEFAULT_TOP_K_RESULTS`.
**Returns:**
List\[Dict\[str]]: Concatenated list of the query results.
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.cohere_rerank_retriever
## CohereRerankRetriever
```python theme={"system"}
class CohereRerankRetriever(BaseRetriever):
```
An implementation of the `BaseRetriever` using the `Cohere Re-ranking`
model.
**Parameters:**
* **model\_name** (str): The model name to use for re-ranking.
* **api\_key** (Optional\[str]): The API key for authenticating with the Cohere service.
* **References**:
* **https**: //txt.cohere.com/rerank/
### **init**
```python theme={"system"}
def __init__(
self,
model_name: str = 'rerank-multilingual-v2.0',
api_key: Optional[str] = None
):
```
Initializes an instance of the CohereRerankRetriever. This
constructor sets up a client for interacting with the Cohere API using
the specified model name and API key. If the API key is not provided,
it attempts to retrieve it from the COHERE\_API\_KEY environment
variable.
**Parameters:**
* **model\_name** (str): The name of the model to be used for re-ranking. Defaults to 'rerank-multilingual-v2.0'.
* **api\_key** (Optional\[str]): The API key for authenticating requests to the Cohere API. If not provided, the method will attempt to retrieve the key from the environment variable 'COHERE\_API\_KEY'.
### query
```python theme={"system"}
def query(
self,
query: str,
retrieved_result: List[Dict[str, Any]],
top_k: int = DEFAULT_TOP_K_RESULTS
):
```
Queries and compiles results using the Cohere re-ranking model.
**Parameters:**
* **query** (str): Query string for information retriever.
* **retrieved\_result** (List\[Dict\[str, Any]]): The content to be re-ranked, should be the output from `BaseRetriever` like `VectorRetriever`.
* **top\_k** (int, optional): The number of top results to return during retriever. Must be a positive integer. Defaults to `DEFAULT_TOP_K_RESULTS`.
**Returns:**
List\[Dict\[str, Any]]: Concatenated list of the query results.
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.hybrid_retrival
## HybridRetriever
```python theme={"system"}
class HybridRetriever(BaseRetriever):
```
### **init**
```python theme={"system"}
def __init__(
self,
embedding_model: Optional[BaseEmbedding] = None,
vector_storage: Optional[BaseVectorStorage] = None
):
```
Initializes the HybridRetriever with optional embedding model and
vector storage.
**Parameters:**
* **embedding\_model** (Optional\[BaseEmbedding]): An optional embedding model used by the VectorRetriever. Defaults to None.
* **vector\_storage** (Optional\[BaseVectorStorage]): An optional vector storage used by the VectorRetriever. Defaults to None.
### process
```python theme={"system"}
def process(self, content_input_path: str):
```
Processes the content input path for both vector and BM25
retrievers.
**Parameters:**
* **content\_input\_path** (str): File path or URL of the content to be processed.
### \_sort\_rrf\_scores
```python theme={"system"}
def _sort_rrf_scores(
self,
vector_retriever_results: List[Dict[str, Any]],
bm25_retriever_results: List[Dict[str, Any]],
top_k: int,
vector_weight: float,
bm25_weight: float,
rank_smoothing_factor: float
):
```
Sorts and combines results from vector and BM25 retrievers using
Reciprocal Rank Fusion (RRF).
**Parameters:**
* **vector\_retriever\_results**: A list of dictionaries containing the results from the vector retriever, where each dictionary contains a 'text' entry.
* **bm25\_retriever\_results**: A list of dictionaries containing the results from the BM25 retriever, where each dictionary contains a 'text' entry.
* **top\_k**: The number of top results to return after sorting by RRF score.
* **vector\_weight**: The weight to assign to the vector retriever results in the RRF calculation.
* **bm25\_weight**: The weight to assign to the BM25 retriever results in the RRF calculation.
* **rank\_smoothing\_factor**: A hyperparameter for the RRF calculation that helps smooth the rank positions.
**Returns:**
List\[Dict\[str, Union\[str, float]]]: A list of dictionaries
representing the sorted results. Each dictionary contains the
'text'from the retrieved items and their corresponding 'rrf\_score'.
### query
```python theme={"system"}
def query(
self,
query: str,
top_k: int = 20,
vector_weight: float = 0.8,
bm25_weight: float = 0.2,
rank_smoothing_factor: int = 60,
vector_retriever_top_k: int = 50,
vector_retriever_similarity_threshold: float = 0.5,
bm25_retriever_top_k: int = 50,
return_detailed_info: bool = False
):
```
Executes a hybrid retrieval query using both vector and BM25
retrievers.
**Parameters:**
* **query** (str): The search query.
* **top\_k** (int): Number of top results to return (default 20).
* **vector\_weight** (float): Weight for vector retriever results in RRF.
* **bm25\_weight** (float): Weight for BM25 retriever results in RRF.
* **rank\_smoothing\_factor** (int): RRF hyperparameter for rank smoothing.
* **vector\_retriever\_top\_k** (int): Top results from vector retriever.
* **vector\_retriever\_similarity\_threshold** (float): Similarity threshold for vector retriever.
* **bm25\_retriever\_top\_k** (int): Top results from BM25 retriever.
* **return\_detailed\_info** (bool): Return detailed info if True.
**Returns:**
Union\[
dict\[str, Sequence\[Collection\[str]]],
dict\[str, Sequence\[Union\[str, float]]]
]: By default, returns only the text information. If
`return_detailed_info` is `True`, return detailed information
including rrf scores.
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.jina_rerank_retriever
## JinaRerankRetriever
```python theme={"system"}
class JinaRerankRetriever(BaseRetriever):
```
An implementation of the `BaseRetriever` using the `Jina AI Reranker`
model.
This retriever uses Jina AI's reranking API to re-order retrieved documents
based on their relevance to the query. It supports multilingual retrieval
across 100+ languages.
**Parameters:**
* **model\_name** (Union\[JinaRerankerModelType, str]): The model name to use for re-ranking.
* **api\_key** (str, optional): The API key for authenticating with the Jina AI service.
* **References**:
* **https**: //jina.ai/reranker/
### **init**
```python theme={"system"}
def __init__(
self,
model_name: Union[JinaRerankerModelType, str] = JinaRerankerModelType.JINA_RERANKER_V2_BASE_MULTILINGUAL,
api_key: str | None = None
):
```
Initializes an instance of the JinaRerankRetriever. This
constructor sets up the API key for interacting with the Jina AI
Reranker API.
**Parameters:**
* **model\_name** (Union\[JinaRerankerModelType, str]): The name of the model to be used for re-ranking. Can be a JinaRerankerModelType enum value or a string. Defaults to `JinaRerankerModelType.JINA_RERANKER_V2_BASE_MULTILINGUAL`.
* **api\_key** (Optional\[str]): The API key for authenticating requests to the Jina AI API. If not provided, the method will attempt to retrieve the key from the environment variable 'JINA\_API\_KEY'.
### query
```python theme={"system"}
def query(
self,
query: str,
retrieved_result: list[dict[str, Any]],
top_k: int = DEFAULT_TOP_K_RESULTS
):
```
Queries and compiles results using the Jina AI re-ranking model.
**Parameters:**
* **query** (str): Query string for information retriever.
* **retrieved\_result** (List\[Dict\[str, Any]]): The content to be re-ranked, should be the output from `BaseRetriever` like `VectorRetriever`. Each dict should have a 'text' key containing the document text.
* **top\_k** (int, optional): The number of top results to return during retrieval. Must be a positive integer. Defaults to `DEFAULT_TOP_K_RESULTS`.
**Returns:**
List\[Dict\[str, Any]]: Concatenated list of the query results,
each containing the original data plus a 'similarity score'.
# null
Source: https://docs.camel-ai.org/reference/camel.retrievers.vector_retriever
## VectorRetriever
```python theme={"system"}
class VectorRetriever(BaseRetriever):
```
An implementation of the `BaseRetriever` by using vector storage and
embedding model.
This class facilitates the retriever of relevant information using a
query-based approach, backed by vector embeddings.
**Parameters:**
* **embedding\_model** (BaseEmbedding): Embedding model used to generate vector embeddings.
* **storage** (BaseVectorStorage): Vector storage to query.
* **unstructured\_modules** (UnstructuredIO): A module for parsing files and URLs and chunking content based on specified parameters.
### **init**
```python theme={"system"}
def __init__(
self,
embedding_model: Optional[BaseEmbedding] = None,
storage: Optional[BaseVectorStorage] = None
):
```
Initializes the retriever class with an optional embedding model.
**Parameters:**
* **embedding\_model** (Optional\[BaseEmbedding]): The embedding model instance. Defaults to `OpenAIEmbedding` if not provided.
* **storage** (BaseVectorStorage): Vector storage to query.
### process
```python theme={"system"}
def process(
self,
content: Union[str, 'Element', IO[bytes]],
chunk_type: str = 'chunk_by_title',
max_characters: int = 500,
embed_batch: int = 50,
should_chunk: bool = True,
extra_info: Optional[dict] = None,
metadata_filename: Optional[str] = None,
chunker: Optional[BaseChunker] = None,
**kwargs: Any
):
```
Processes content from local file path, remote URL, string
content, Element object, or a binary file object, divides it into
chunks by using `Unstructured IO`, and stores their embeddings in the
specified vector storage.
**Parameters:**
* **content** (Union\[str, Element, IO\[bytes]]): Local file path, remote URL, string content, Element object, or a binary file object.
* **chunk\_type** (str): Type of chunking going to apply. Defaults to "chunk\_by\_title".
* **max\_characters** (int): Max number of characters in each chunk. Defaults to `500`.
* **embed\_batch** (int): Size of batch for embeddings. Defaults to `50`. (default: 50)
* **should\_chunk** (bool): If True, divide the content into chunks, otherwise skip chunking. Defaults to True.
* **extra\_info** (Optional\[dict]): Extra information to be added to the payload. Defaults to None.
* **metadata\_filename** (Optional\[str]): The metadata filename to be used for storing metadata. Defaults to None. \*\*kwargs (Any): Additional keyword arguments for content parsing.
### query
```python theme={"system"}
def query(
self,
query: str,
top_k: int = Constants.DEFAULT_TOP_K_RESULTS,
similarity_threshold: float = Constants.DEFAULT_SIMILARITY_THRESHOLD
):
```
Executes a query in vector storage and compiles the retrieved
results into a dictionary.
**Parameters:**
* **query** (str): Query string for information retriever.
* **similarity\_threshold** (float, optional): The similarity threshold for filtering results. Defaults to `DEFAULT_SIMILARITY_THRESHOLD`.
* **top\_k** (int, optional): The number of top results to return during retriever. Must be a positive integer. Defaults to `DEFAULT_TOP_K_RESULTS`.
**Returns:**
List\[Dict\[str, Any]]: Concatenated list of the query results.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.base
## BaseRuntime
```python theme={"system"}
class BaseRuntime(ABC):
```
An abstract base class for all CAMEL runtimes.
### **init**
```python theme={"system"}
def __init__(self):
```
### add
```python theme={"system"}
def add(
self,
funcs: Union[FunctionTool, List[FunctionTool]],
*args: Any,
**kwargs: Any
):
```
Adds a new tool to the runtime.
### reset
```python theme={"system"}
def reset(self, *args: Any, **kwargs: Any):
```
Resets the runtime to its initial state.
### cleanup
```python theme={"system"}
def cleanup(self):
```
Releases resources (containers, processes, connections, etc.).
Public part of the runtime lifecycle API: callers may call
:meth:`cleanup` or use the runtime as a context manager
(`__INLINE_CODE_1__`) for deterministic teardown. Subclasses must
implement this method.
### stop
```python theme={"system"}
def stop(self):
```
**Returns:**
BaseRuntime: The current runtime (for chaining).
### **enter**
```python theme={"system"}
def __enter__(self):
```
Enter the context manager.
### **exit**
```python theme={"system"}
def __exit__(
self,
exc_type: type[BaseException] | None,
exc_val: BaseException | None,
exc_tb: Any | None
):
```
Exit the context manager; ensures cleanup is called.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Returns a list of all tools in the runtime.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.configs
## TaskConfig
```python theme={"system"}
class TaskConfig(BaseModel):
```
A configuration for a task to run a command inside the container.
Arttributes:
cmd (str or list): Command to be executed
stdout (bool): Attach to stdout. (default: :obj:`True`)
stderr (bool): Attach to stderr. (default: :obj:`True`)
stdin (bool): Attach to stdin. (default: :obj:`False`)
tty (bool): Allocate a pseudo-TTY. (default: :obj:`False`)
privileged (bool): Run as privileged. (default: :obj:`False`)
user (str): User to execute command as. (default: :obj:`""`)
detach (bool): If true, detach from the exec command.
(default: :obj:`False`)
stream (bool): Stream response data. (default: :obj:`False`)
socket (bool): Return the connection socket to allow custom
read/write operations. (default: :obj:`False`)
environment (dict or list): A dictionary or a list of strings in
the following format `__INLINE_CODE_9__` or
`__INLINE_CODE_10____INLINE_CODE_11__None`)
workdir (str): Path to working directory for this exec session.
(default: :obj:`None`)
demux (bool): Return stdout and stderr separately. (default: :obj:
`False`)
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.daytona_runtime
## DaytonaRuntime
```python theme={"system"}
class DaytonaRuntime(BaseRuntime):
```
A runtime that executes functions in a Daytona sandbox environment.
Requires the Daytona server to be running and an API key configured.
**Parameters:**
* **api\_key** (Optional\[str]): The Daytona API key for authentication. If not provided, it will try to use the DAYTONA\_API\_KEY environment variable. (default: :obj:`None`)
* **api\_url** (Optional\[str]): The URL of the Daytona server. If not provided, it will try to use the DAYTONA\_API\_URL environment variable. If none is provided, it will use "[http://localhost:8000](http://localhost:8000)". (default: :obj:`None`)
* **language** (`Optional[Literal["python", "typescript", "javascript"]]`): The programming language for the sandbox. (default: :obj:`"python"`)
* **image** (Optional\[str]): The Docker image to use for the sandbox. If not provided, a default image based on the language will be used. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
api_url: Optional[str] = None,
language: Optional[Literal['python', 'typescript', 'javascript']] = 'python',
image: Optional[str] = None
):
```
### build
```python theme={"system"}
def build(self):
```
**Returns:**
DaytonaRuntime: The current runtime.
### cleanup
```python theme={"system"}
def cleanup(self):
```
Release the Daytona sandbox (delete and remove reference).
### add
```python theme={"system"}
def add(
self,
funcs: Union[FunctionTool, List[FunctionTool]],
entrypoint: str,
arguments: Optional[Dict[str, Any]] = None
):
```
Add a function or list of functions to the runtime.
**Parameters:**
* **funcs** (Union\[FunctionTool, List\[FunctionTool]]): The function or list of functions to add.
* **entrypoint** (str): The entrypoint for the function.
* **arguments** (Optional\[Dict\[str, Any]]): The arguments for the function. (default: :obj:`None`)
**Returns:**
DaytonaRuntime: The current runtime.
### info
```python theme={"system"}
def info(self):
```
**Returns:**
str: Information about the sandbox.
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up the sandbox when the object is deleted.
### stop
```python theme={"system"}
def stop(self):
```
**Returns:**
DaytonaRuntime: The current runtime.
### reset
```python theme={"system"}
def reset(self):
```
**Returns:**
DaytonaRuntime: The current runtime.
### docs
```python theme={"system"}
def docs(self):
```
**Returns:**
str: The URL for the API documentation.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.docker_runtime
## DockerRuntime
```python theme={"system"}
class DockerRuntime(BaseRuntime):
```
A class representing a runtime environment using Docker.
This class automatically wraps functions to be executed
in a Docker container.
**Parameters:**
* **image** (str): The name of the Docker image to use for the runtime.
* **port** (int): The port number to use for the runtime API. (default: :obj: `8000`)
* **remove** (bool): Whether to remove the container after stopping it. ' (default: :obj:`True`)
* **kwargs** (dict): Additional keyword arguments to pass to the Docker client.
### **init**
```python theme={"system"}
def __init__(
self,
image: str,
port: int = 8000,
remove: bool = True,
**kwargs
):
```
### mount
```python theme={"system"}
def mount(self, path: str, mount_path: str):
```
Mount a local directory to the container.
**Parameters:**
* **path** (str): The local path to mount.
* **mount\_path** (str): The path to mount the local directory to in the container.
**Returns:**
DockerRuntime: The DockerRuntime instance.
### copy
```python theme={"system"}
def copy(self, source: str, dest: str):
```
Copy a file or directory to the container.
**Parameters:**
* **source** (str): The local path to the file.
* **dest** (str): The path to copy the file to in the container.
**Returns:**
DockerRuntime: The DockerRuntime instance.
### add\_task
```python theme={"system"}
def add_task(self, task: TaskConfig):
```
Add a task to run a command inside the container when building.
Similar to `docker exec`.
**Parameters:**
* **task** (TaskConfig): The configuration for the task.
**Returns:**
DockerRuntime: The DockerRuntime instance.
### exec\_run
```python theme={"system"}
def exec_run(self, task: TaskConfig):
```
Run a command inside this container. Similar to `docker exec`.
**Parameters:**
* **task** (TaskConfig): The configuration for the task.
**Returns:**
(ExecResult): A tuple of (exit\_code, output)
exit\_code: (int):
Exit code for the executed command or `None` if
either `stream` or `socket` is `True`.
output: (generator, bytes, or tuple):
If `stream=True`, a generator yielding response chunks.
If `socket=True`, a socket object for the connection.
If `demux=True`, a tuple of two bytes: stdout and stderr.
A bytestring containing response data otherwise.
### build
```python theme={"system"}
def build(self, time_out: int = 15):
```
Build the Docker container and start it.
**Parameters:**
* **time\_out** (int): The number of seconds to wait for the container to start. (default: :obj:`15`)
**Returns:**
DockerRuntime: The DockerRuntime instance.
### add
```python theme={"system"}
def add(
self,
funcs: Union[FunctionTool, List[FunctionTool]],
entrypoint: str,
redirect_stdout: bool = False,
arguments: Optional[Dict[str, Any]] = None
):
```
Add a function or list of functions to the runtime.
**Parameters:**
* **funcs** (Union\[FunctionTool, List\[FunctionTool]]): The function or list of functions to add.
* **entrypoint** (str): The entrypoint for the function.
* **redirect\_stdout** (bool): Whether to return the stdout of the function. (default: :obj:`False`)
* **arguments** (Optional\[Dict\[str, Any]]): The arguments for the function. (default: :obj:`None`)
**Returns:**
DockerRuntime: The DockerRuntime instance.
### reset
```python theme={"system"}
def reset(self):
```
**Returns:**
DockerRuntime: The DockerRuntime instance.
### cleanup
```python theme={"system"}
def cleanup(self):
```
Stop and optionally remove the Docker container.
Uses the instance's :attr:`remove` setting to decide whether to
remove the container after stopping. For a one-off override,
use :meth:`stop` with the `__INLINE_CODE_2__` argument.
### stop
```python theme={"system"}
def stop(self, remove: Optional[bool] = None):
```
Stop the Docker container and release resources.
**Parameters:**
* **remove** (Optional\[bool]): If set, overrides the instance's :attr:`remove` setting for this call only (e.g. `__INLINE_CODE_1____INLINE_CODE_2__None`)
**Returns:**
DockerRuntime: The DockerRuntime instance.
### ok
```python theme={"system"}
def ok(self):
```
**Returns:**
bool: Whether the API Server is running.
### wait
```python theme={"system"}
def wait(self, timeout: int = 10):
```
Wait for the API Server to be ready.
**Parameters:**
* **timeout** (int): The number of seconds to wait. (default: :obj:`10`) (default: 10)
**Returns:**
bool: Whether the API Server is ready.
### **enter**
```python theme={"system"}
def __enter__(self):
```
**Returns:**
DockerRuntime: The DockerRuntime instance.
### **exit**
```python theme={"system"}
def __exit__(
self,
exc_type,
exc_val,
exc_tb
):
```
Exit the context manager.
### docs
```python theme={"system"}
def docs(self):
```
**Returns:**
str: The URL for the API documentation.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.llm_guard_runtime
## LLMGuardRuntime
```python theme={"system"}
class LLMGuardRuntime(BaseRuntime):
```
A runtime that evaluates the risk level of functions using
a language model.
**Parameters:**
* **prompt** (str): The prompt to use for the language model. (default: :obj:`GUARDPROMPT`)
* **model** (BaseModelBackend): The language model to use. (default: :obj: `None`)
* **verbose** (bool): Whether to print verbose output. (default: :obj: `False`)
### **init**
```python theme={"system"}
def __init__(
self,
prompt: str = GUARDPROMPT,
model: Optional[BaseModelBackend] = None,
verbose: bool = False
):
```
### add
```python theme={"system"}
def add(
self,
funcs: Union[FunctionTool, List[FunctionTool]],
threshold: int = 2
):
```
Add a function or list of functions to the runtime.
**Parameters:**
* **funcs** (FunctionTool or List\[FunctionTool]): The function or list of functions to add.
* **threshold** (int): The risk threshold for functions. (default: :obj:`2`)
**Returns:**
LLMGuardRuntime: The current runtime.
### cleanup
```python theme={"system"}
def cleanup(self):
```
No-op; LLMGuardRuntime does not hold external resources.
### reset
```python theme={"system"}
def reset(self):
```
Resets the runtime to its initial state.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.remote_http_runtime
## RemoteHttpRuntime
```python theme={"system"}
class RemoteHttpRuntime(BaseRuntime):
```
A runtime that runs functions in a remote HTTP server.
You need to run the API server in the remote server first.
**Parameters:**
* **host** (str): The host of the remote server.
* **port** (int): The port of the remote server. (default: :obj:`8000`) (default: 8000)
* **python\_exec** (str): The python executable to run the API server. (default: :obj:`python3`)
### **init**
```python theme={"system"}
def __init__(
self,
host: str,
port: int = 8000,
python_exec: str = 'python3'
):
```
### build
```python theme={"system"}
def build(self):
```
**Returns:**
RemoteHttpRuntime: The current runtime.
### cleanup
```python theme={"system"}
def cleanup(self):
```
Stop and release the API server process.
### add
```python theme={"system"}
def add(
self,
funcs: Union[FunctionTool, List[FunctionTool]],
entrypoint: str,
redirect_stdout: bool = False,
arguments: Optional[Dict[str, Any]] = None
):
```
Add a function or list of functions to the runtime.
**Parameters:**
* **funcs** (Union\[FunctionTool, List\[FunctionTool]]): The function or list of functions to add.
* **entrypoint** (str): The entrypoint for the function.
* **redirect\_stdout** (bool): Whether to return the stdout of the function. (default: :obj:`False`)
* **arguments** (Optional\[Dict\[str, Any]]): The arguments for the function. (default: :obj:`None`)
**Returns:**
RemoteHttpRuntime: The current runtime.
### ok
```python theme={"system"}
def ok(self):
```
**Returns:**
bool: Whether the API Server is running.
### wait
```python theme={"system"}
def wait(self, timeout: int = 10):
```
Wait for the API Server to be ready.
**Parameters:**
* **timeout** (int): The number of seconds to wait. (default: :obj:`10`) (default: 10)
**Returns:**
bool: Whether the API Server is ready.
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up the API server when the object is deleted.
### stop
```python theme={"system"}
def stop(self):
```
**Returns:**
RemoteHttpRuntime: The current runtime.
### reset
```python theme={"system"}
def reset(self):
```
**Returns:**
RemoteHttpRuntime: The current runtime.
### docs
```python theme={"system"}
def docs(self):
```
**Returns:**
str: The URL for the API documentation.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.ubuntu_docker_runtime
## UbuntuDockerRuntime
```python theme={"system"}
class UbuntuDockerRuntime(DockerRuntime):
```
A specialized Docker runtime for Ubuntu-based environments.
This runtime includes specific configurations and setup for Ubuntu
containers, including proper Python path handling and environment setup.
It provides methods for executing Python files, managing the container
lifecycle, and handling file operations within the Ubuntu container.
**Parameters:**
* **python\_path** (str): Path to the Python interpreter in the container
* **docker\_config** (dict): Configuration dict for Docker container setup
### **init**
```python theme={"system"}
def __init__(
self,
image: str,
port: int = 0,
remove: bool = True,
python_path: str = '/usr/bin/python3',
**kwargs
):
```
Initialize the Ubuntu Docker Runtime.
**Parameters:**
* **image** (str): Docker image name to use
* **port** (int, optional): Port to expose. Defaults to 0 (random port) (default: 0 (random port)
* **remove** (bool, optional): Whether to remove container after use. Defaults to True
* **python\_path** (str, optional): Path to Python interpreter. Defaults to "/usr/bin/python3" \*\*kwargs: Additional arguments passed to DockerRuntime
### add
```python theme={"system"}
def add(
self,
funcs: Union[FunctionTool, List[FunctionTool]],
entrypoint: str,
redirect_stdout: bool = False,
arguments: Optional[dict] = None
):
```
Add functions to the runtime with Ubuntu-specific modifications.
**Returns:**
Self for method chaining
### \_setup\_default\_mounts
```python theme={"system"}
def _setup_default_mounts(self):
```
Setup default volume mounts for the container.
This method can be extended to add Ubuntu-specific volume mounts.
### build
```python theme={"system"}
def build(self, time_out: int = 15):
```
Build and initialize the Ubuntu container with proper setup.
**Parameters:**
* **time\_out** (int): Timeout in seconds for build operation
**Returns:**
Self for method chaining
### exec\_python\_file
```python theme={"system"}
def exec_python_file(
self,
local_file_path: str,
container_path: Optional[str] = None,
args: Optional[List[str]] = None,
env: Optional[dict] = None,
callback: Optional[Callable[[str], None]] = None
):
```
Execute a Python file inside the Docker container.
**Parameters:**
* **env**: Additional environment variables to set for the execution
* **callback**: Optional function to process each line of output If None, output is printed to stdout
### \_create\_archive\_from\_file
```python theme={"system"}
def _create_archive_from_file(self, file_path: Union[str, Path]):
```
Create a tar archive from a single file for docker.put\_archive().
**Parameters:**
* **file\_path**: Path to the file to archive
**Returns:**
bytes: The tar archive as bytes
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.utils.function_risk_toolkit
## FunctionRiskToolkit
```python theme={"system"}
class FunctionRiskToolkit(BaseToolkit):
```
A toolkit for assessing the risk associated with functions.
**Parameters:**
* **verbose** (Optional\[bool]): Whether to print verbose output. (default: :obj:`False`)
### **init**
```python theme={"system"}
def __init__(self, verbose: Optional[bool] = False):
```
### function\_risk
```python theme={"system"}
def function_risk(self, score: int, reason: str):
```
Provides an assessment of the potential risk associated
with a function.
**Parameters:**
* **score** (int): The risk level associated with the function, ranging from 1 to 3: - 1: No harm (e.g., simple math operations, content searches) - 2: Minimal harm (e.g., accessing user files) - 3: Risk present (e.g., deleting files, modifying the file system)
* **reason** (str): A brief explanation of the reasoning behind the assigned score, describing the specific aspects that contribute to the assessed risk.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.runtimes.utils.ignore_risk_toolkit
## IgnoreRiskToolkit
```python theme={"system"}
class IgnoreRiskToolkit(BaseToolkit):
```
A toolkit for ignoring risks associated with functions.
**Parameters:**
* **function\_names** (Optional\[List\[str]]): A list of function names to ignore risks for. (default: :obj:`None`)
* **verbose** (Optional\[bool]): Whether to print verbose output. (default: :obj:`False`)
### **init**
```python theme={"system"}
def __init__(
self,
function_name: Optional[List[str]] = None,
verbose: Optional[bool] = False
):
```
### add
```python theme={"system"}
def add(self, name: str):
```
Adds a function to the toolkit.
**Parameters:**
* **name** (str): The name of the function to add.
### ignore\_risk
```python theme={"system"}
def ignore_risk(self, name: str, reason: str):
```
Force ignores the risk associated with named function. This ONLY
ignores the RISK for the NEXT Function Call.
**Parameters:**
* **name** (str): The name of the function to ignore.
* **reason** (str): A brief explanation of the reasoning behind the decision to ignore the risk.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.schemas.base
## BaseConverter
```python theme={"system"}
class BaseConverter(ABC):
```
A base class for schema outputs that includes functionality
for managing the response format.
**Parameters:**
* **output\_schema** (Optional\[Type\[BaseModel]], optional): The expected format of the response. (default: :obj:`None`)
### convert
```python theme={"system"}
def convert(
self,
content: str,
*args: Any,
**kwargs: Dict[str, Any]
):
```
Structures the input text into the expected response format.
**Parameters:**
* **text** (str): The input text to be structured.
* **output\_schema** (Optional\[Type\[BaseModel]], optional): The expected format of the response. Defaults to None.
* **prompt** (Optional\[str], optional): The prompt to be used.
**Returns:**
Any: The converted response.
# null
Source: https://docs.camel-ai.org/reference/camel.schemas.openai_converter
## OpenAISchemaConverter
```python theme={"system"}
class OpenAISchemaConverter(BaseConverter):
```
OpenAISchemaConverter is a class that converts a string or a function
into a BaseModel schema.
**Parameters:**
* **model\_type** (ModelType, optional): The model type to be used. (default: ModelType.GPT\_4O\_MINI)
* **model\_config\_dict** (Optional\[Dict\[str, Any]], optional): A dictionary that will be fed into:obj:`openai.ChatCompletion.create()`. If :obj:`None`, :obj:`ChatGPTConfig().as_dict()` will be used. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for authenticating with the OpenAI service. (default: :obj:`None`)
* **output\_schema** (Optional\[Type\[BaseModel]], optional): The expected format of the response. (default: :obj:`None`)
* **prompt** (Optional\[str], optional): The prompt to be used. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
model_type: ModelType = ModelType.GPT_4O_MINI,
model_config_dict: Optional[Dict[str, Any]] = None,
api_key: Optional[str] = None
):
```
### convert
```python theme={"system"}
def convert(
self,
content: str,
output_schema: Union[Type[BaseModel], str, Callable],
prompt: Optional[str] = DEFAULT_CONVERTER_PROMPTS
):
```
Formats the input content into the expected BaseModel
**Parameters:**
* **content** (str): The content to be formatted.
* **output\_schema** (Union\[Type\[BaseModel], str, Callable]): The expected format of the response.
**Returns:**
BaseModel: The formatted response.
# null
Source: https://docs.camel-ai.org/reference/camel.schemas.outlines_converter
## OutlinesConverter
```python theme={"system"}
class OutlinesConverter(BaseConverter):
```
OutlinesConverter is a class that converts a string or a function
into a BaseModel schema.
**Parameters:**
* **model\_type** (str, optional): The model type to be used.
* **platform** (str, optional): The platform to be used. 1. transformers 2. mamba 3. vllm 4. llamacpp 5. mlx (default: "transformers") \*\*kwargs: The keyword arguments to be used. See the outlines documentation for more details. See
* **https**: //dottxt-ai.github.io/outlines/latest/reference/models/models/
### **init**
```python theme={"system"}
def __init__(
self,
model_type: str,
platform: Literal['vllm', 'transformers', 'mamba', 'llamacpp', 'mlx'] = 'transformers',
**kwargs: Any
):
```
### convert\_regex
```python theme={"system"}
def convert_regex(self, content: str, regex_pattern: str):
```
Convert the content to the specified regex pattern.
**Parameters:**
* **content** (str): The content to be converted.
* **regex\_pattern** (str): The regex pattern to be used.
**Returns:**
str: The converted content.
### convert\_json
```python theme={"system"}
def convert_json(self, content: str, output_schema: Union[str, Callable]):
```
Convert the content to the specified JSON schema given by
output\_schema.
**Parameters:**
* **content** (str): The content to be converted.
* **output\_schema** (Union\[str, Callable]): The expected format of the response.
**Returns:**
dict: The converted content in JSON format.
### convert\_pydantic
```python theme={"system"}
def convert_pydantic(self, content: str, output_schema: Type[BaseModel]):
```
Convert the content to the specified Pydantic schema.
**Parameters:**
* **content** (str): The content to be converted.
* **output\_schema** (Type\[BaseModel]): The expected format of the response.
**Returns:**
BaseModel: The converted content in pydantic model format.
### convert\_type
```python theme={"system"}
def convert_type(self, content: str, type_name: type):
```
Convert the content to the specified type.
The following types are currently available:
1. int
2. float
3. bool
4. datetime.date
5. datetime.time
6. datetime.datetime
7. custom types ([https://dottxt-ai.github.io/outlines/latest/reference/generation/types/](https://dottxt-ai.github.io/outlines/latest/reference/generation/types/))
**Parameters:**
* **content** (str): The content to be converted.
* **type\_name** (type): The type to be used.
**Returns:**
str: The converted content.
### convert\_choice
```python theme={"system"}
def convert_choice(self, content: str, choices: List[str]):
```
Convert the content to the specified choice.
**Parameters:**
* **content** (str): The content to be converted.
* **choices** (List\[str]): The choices to be used.
**Returns:**
str: The converted content.
### convert\_grammar
```python theme={"system"}
def convert_grammar(self, content: str, grammar: str):
```
Convert the content to the specified grammar.
**Parameters:**
* **content** (str): The content to be converted.
* **grammar** (str): The grammar to be used.
**Returns:**
str: The converted content.
### convert
```python theme={"system"}
def convert(
self,
content: str,
type: Literal['regex', 'json', 'type', 'choice', 'grammar'],
**kwargs
):
```
Formats the input content into the expected BaseModel.
**Parameters:**
* **type** (`Literal["regex", "json", "type", "choice", "grammar"]`): The type of conversion to perform. Options are: - "regex": Match the content against a regex pattern. - "pydantic": Convert the content into a pydantic model. - "json": Convert the content into a JSON based on a schema. - "type": Convert the content into a specified type. - "choice": Match the content against a list of valid choices. - "grammar": Convert the content using a specified grammar.
* **content** (str): The content to be formatted. \*\*kwargs: Additional keyword arguments specific to the conversion type. - For "regex":
* **regex\_pattern** (str): The regex pattern to use for matching. - For "pydantic":
* **output\_schema** (Type\[BaseModel]): The schema to validate and format the pydantic model. - For "json":
* **output\_schema** (Union\[str, Callable]): The schema to validate and format the JSON object. - For "type":
* **type\_name** (str): The target type name for the conversion. - For "choice":
* **choices** (List\[str]): A list of valid choices to match against. - For "grammar":
* **grammar** (str): The grammar definition to use for content conversion.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.babyagi_playing
## BabyAGI
```python theme={"system"}
class BabyAGI:
```
The BabyAGI Agent adapted from ["Task-driven Autonomous Agent"](https://github.com/yoheinakajima/babyagi).
**Parameters:**
* **assistant\_role\_name** (str): The name of the role played by the assistant.
* **user\_role\_name** (str): The name of the role played by the user.
* **task\_prompt** (str, optional): A prompt for the task to be performed. (default: :obj:`""`)
* **task\_type** (TaskType, optional): The type of task to perform. (default: :obj:`TaskType.AI_SOCIETY`)
* **max\_task\_history** (int): The maximum number of previous tasks information to include in the task agent. (default: :obj:10)
* **assistant\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the assistant agent. (default: :obj:`None`)
* **task\_specify\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task specify agent. (default: :obj:`None`)
* **task\_creation\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task creation agent. (default: :obj:`None`)
* **task\_prioritization\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task prioritization agent. (default: :obj:`None`)
* **sys\_msg\_generator\_kwargs** (Dict, optional): Additional arguments to pass to the system message generator. (default: :obj:`None`)
* **extend\_task\_specify\_meta\_dict** (Dict, optional): A dict to extend the task specify meta dict with. (default: :obj:`None`)
* **output\_language** (str, optional): The language to be output by the agents. (default: :obj:`None`)
* **message\_window\_size** (int, optional): The maximum number of previous messages to include in the context window. If `None`, no windowing is performed. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
assistant_role_name: str,
user_role_name: str,
task_prompt: str = '',
task_type: TaskType = TaskType.AI_SOCIETY,
max_task_history: int = 10,
assistant_agent_kwargs: Optional[Dict] = None,
task_specify_agent_kwargs: Optional[Dict] = None,
task_creation_agent_kwargs: Optional[Dict] = None,
task_prioritization_agent_kwargs: Optional[Dict] = None,
sys_msg_generator_kwargs: Optional[Dict] = None,
extend_task_specify_meta_dict: Optional[Dict] = None,
output_language: Optional[str] = None,
message_window_size: Optional[int] = None
):
```
### init\_specified\_task\_prompt
```python theme={"system"}
def init_specified_task_prompt(
self,
assistant_role_name: str,
user_role_name: str,
task_specify_agent_kwargs: Optional[Dict],
extend_task_specify_meta_dict: Optional[Dict],
output_language: Optional[str]
):
```
Use a task specify agent to generate a specified task prompt.
Generated specified task prompt will be used to replace original
task prompt. If there is no task specify agent, specified task
prompt will not be generated.
**Parameters:**
* **assistant\_role\_name** (str): The name of the role played by the assistant.
* **user\_role\_name** (str): The name of the role played by the user.
* **task\_specify\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task specify agent.
* **extend\_task\_specify\_meta\_dict** (Dict, optional): A dict to extend the task specify meta dict with.
* **output\_language** (str, optional): The language to be output by the agents.
### init\_agents
```python theme={"system"}
def init_agents(
self,
init_assistant_sys_msg: BaseMessage,
assistant_agent_kwargs: Optional[Dict],
task_creation_agent_kwargs: Optional[Dict],
task_prioritization_agent_kwargs: Optional[Dict],
output_language: Optional[str],
message_window_size: Optional[int] = None
):
```
Initialize assistant and user agents with their system messages.
**Parameters:**
* **init\_assistant\_sys\_msg** (BaseMessage): Assistant agent's initial system message.
* **assistant\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the assistant agent.
* **task\_creation\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task creation agent.
* **task\_prioritization\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task prioritization agent.
* **output\_language** (str, optional): The language to be output by the agents.
* **message\_window\_size** (int, optional): The maximum number of previous messages to include in the context window. If `None`, no windowing is performed. (default: :obj:`None`)
### step
```python theme={"system"}
def step(self):
```
**Returns:**
ChatAgentResponse: it contains the resulting assistant message,
whether the assistant agent terminated the conversation,
and any additional assistant information.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.role_playing
## RolePlaying
```python theme={"system"}
class RolePlaying:
```
Role playing between two agents.
**Parameters:**
* **assistant\_role\_name** (str): The name of the role played by the assistant.
* **user\_role\_name** (str): The name of the role played by the user.
* **critic\_role\_name** (str, optional): The name of the role played by the critic. Role name with :obj:`"human"` will set critic as a :obj:`Human` agent, else will create a :obj:`CriticAgent`. (default: :obj:`"critic"`)
* **task\_prompt** (str, optional): A prompt for the task to be performed. (default: :obj:`""`)
* **with\_task\_specify** (bool, optional): Whether to use a task specify agent. (default: :obj:`True`)
* **with\_task\_planner** (bool, optional): Whether to use a task planner agent. (default: :obj:`False`)
* **with\_critic\_in\_the\_loop** (bool, optional): Whether to include a critic in the loop. (default: :obj:`False`)
* **critic\_criteria** (str, optional): Critic criteria for the critic agent. If not specified, set the criteria to improve task performance.
* **model** (BaseModelBackend, optional): The model backend to use for generating responses. If specified, it will override the model in all agents if not specified in agent-specific kwargs. (default: :obj:`OpenAIModel` with `GPT_4O_MINI`)
* **task\_type** (TaskType, optional): The type of task to perform. (default: :obj:`TaskType.AI_SOCIETY`)
* **assistant\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the assistant agent. (default: :obj:`None`)
* **user\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the user agent. (default: :obj:`None`)
* **task\_specify\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task specify agent. (default: :obj:`None`)
* **task\_planner\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task planner agent. (default: :obj:`None`)
* **critic\_kwargs** (Dict, optional): Additional arguments to pass to the critic. (default: :obj:`None`)
* **sys\_msg\_generator\_kwargs** (Dict, optional): Additional arguments to pass to the system message generator. (default: :obj:`None`)
* **extend\_sys\_msg\_meta\_dicts** (List\[Dict], optional): A list of dicts to extend the system message meta dicts with. (default: :obj:`None`)
* **extend\_task\_specify\_meta\_dict** (Dict, optional): A dict to extend the task specify meta dict with. (default: :obj:`None`)
* **output\_language** (str, optional): The language to be output by the agents. (default: :obj:`None`)
* **stop\_event** (Optional\[threading.Event], optional): Event to signal termination of the agent's operation. When set, the agent will terminate its execution. (default: :obj:`None`)
* **assistant\_agent** (ChatAgent, optional): A pre-configured ChatAgent to use as the assistant. If provided, this will override the creation of a new assistant agent. (default: :obj:`None`)
* **user\_agent** (ChatAgent, optional): A pre-configured ChatAgent to use as the user. If provided, this will override the creation of a new user agent. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, assistant_role_name: str, user_role_name: str):
```
### \_init\_specified\_task\_prompt
```python theme={"system"}
def _init_specified_task_prompt(
self,
assistant_role_name: str,
user_role_name: str,
task_specify_agent_kwargs: Optional[Dict] = None,
extend_task_specify_meta_dict: Optional[Dict] = None,
output_language: Optional[str] = None
):
```
Use a task specify agent to generate a specified task prompt.
Generated specified task prompt will be used to replace original
task prompt. If there is no task specify agent, specified task
prompt will not be generated.
**Parameters:**
* **assistant\_role\_name** (str): The name of the role played by the assistant.
* **user\_role\_name** (str): The name of the role played by the user.
* **task\_specify\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task specify agent. (default: :obj:`None`)
* **extend\_task\_specify\_meta\_dict** (Dict, optional): A dict to extend the task specify meta dict with. (default: :obj:`None`)
* **output\_language** (str, optional): The language to be output by the agents. (default: :obj:`None`)
### \_init\_planned\_task\_prompt
```python theme={"system"}
def _init_planned_task_prompt(
self,
task_planner_agent_kwargs: Optional[Dict] = None,
output_language: Optional[str] = None
):
```
Use a task plan agent to append a planned task prompt to task
prompt. The planned task prompt is generated based on the task
prompt, which can be original task prompt or specified task prompt
if available. If there is no task plan agent, planned task prompt
will not be generated.
**Parameters:**
* **task\_planner\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the task planner agent. (default: :obj:`None`)
* **output\_language** (str, optional): The language to be output by the agents. (default: :obj:`None`)
### \_get\_sys\_message\_info
```python theme={"system"}
def _get_sys_message_info(
self,
assistant_role_name: str,
user_role_name: str,
sys_msg_generator: SystemMessageGenerator,
extend_sys_msg_meta_dicts: Optional[List[Dict]] = None
):
```
Get initial assistant and user system message with a list of
system message meta dicts.
**Parameters:**
* **assistant\_role\_name** (str): The name of the role played by the assistant.
* **user\_role\_name** (str): The name of the role played by the user.
* **sys\_msg\_generator** (SystemMessageGenerator): A system message generator for agents.
* **extend\_sys\_msg\_meta\_dicts** (List\[Dict], optional): A list of dicts to extend the system message meta dicts with. (default: :obj:`None`)
**Returns:**
Tuple\[BaseMessage, BaseMessage, List\[Dict]]: A tuple containing a
`BaseMessage` representing the assistant's initial system
message, a `BaseMessage` representing the user's initial system
message, and a list of system message meta dicts.
### \_init\_agents
```python theme={"system"}
def _init_agents(
self,
init_assistant_sys_msg: Optional[BaseMessage],
init_user_sys_msg: Optional[BaseMessage],
assistant_agent_kwargs: Optional[Dict] = None,
user_agent_kwargs: Optional[Dict] = None,
output_language: Optional[str] = None,
stop_event: Optional[threading.Event] = None,
assistant_agent: Optional[ChatAgent] = None,
user_agent: Optional[ChatAgent] = None
):
```
Initialize assistant and user agents with their system messages.
**Parameters:**
* **init\_assistant\_sys\_msg** (Optional\[BaseMessage]): Assistant agent's initial system message.
* **init\_user\_sys\_msg** (Optional\[BaseMessage]): User agent's initial system message.
* **assistant\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the assistant agent. (default: :obj:`None`)
* **user\_agent\_kwargs** (Dict, optional): Additional arguments to pass to the user agent. (default: :obj:`None`)
* **output\_language** (str, optional): The language to be output by the agents. (default: :obj:`None`)
* **stop\_event** (Optional\[threading.Event], optional): Event to signal termination of the agent's operation. When set, the agent will terminate its execution. (default: :obj:`None`)
* **assistant\_agent** (ChatAgent, optional): A pre-configured ChatAgent to use as the assistant. If provided, this will override the creation of a new assistant agent. (default: :obj:`None`)
* **user\_agent** (ChatAgent, optional): A pre-configured ChatAgent to use as the user. If provided, this will override the creation of a new user agent. (default: :obj:`None`)
### \_init\_critic
```python theme={"system"}
def _init_critic(
self,
sys_msg_generator: SystemMessageGenerator,
sys_msg_meta_dicts: List[Dict],
critic_role_name: str,
critic_criteria: Optional[str] = None,
critic_kwargs: Optional[Dict] = None
):
```
Initialize critic agent. If critic role name is :obj:`"human"`,
create a :obj:`Human` critic agent. Else, create a :obj:`CriticAgent`
critic agent with specified critic criteria. If the critic criteria
is not specified, set it to improve task performance.
**Parameters:**
* **sys\_msg\_generator** (SystemMessageGenerator): A system message generator for agents.
* **sys\_msg\_meta\_dicts** (list): A list of system message meta dicts.
* **critic\_role\_name** (str): The name of the role played by the critic.
* **critic\_criteria** (str, optional): Critic criteria for the critic agent. If not specified, set it to improve task performance. (default: :obj:`None`)
* **critic\_kwargs** (Dict, optional): Additional arguments to pass to the critic. (default: :obj:`None`)
### \_reduce\_message\_options
```python theme={"system"}
def _reduce_message_options(self, messages: Sequence[BaseMessage]):
```
Processes a sequence of chat messages, returning the processed
message. If multiple messages are provided and
`with_critic_in_the_loop` is `False`, raises a `ValueError`.
If no messages are provided, a `ValueError` will be raised.
**Parameters:**
* **messages** (Sequence\[BaseMessage]): A sequence of `BaseMessage` objects to process.
**Returns:**
BaseMessage: A single `BaseMessage` representing the processed
message.
### init\_chat
```python theme={"system"}
def init_chat(self, init_msg_content: Optional[str] = None):
```
Initializes the chat by resetting both of the assistant and user
agents. Returns an initial message for the role-playing session.
**Parameters:**
* **init\_msg\_content** (str, optional): A user-specified initial message. Will be sent to the role-playing session as the initial message. (default: :obj:`None`)
**Returns:**
BaseMessage: A single `BaseMessage` representing the initial
message.
### step
```python theme={"system"}
def step(self, assistant_msg: BaseMessage):
```
Advances the conversation by taking a message from the assistant,
processing it using the user agent, and then processing the resulting
message using the assistant agent. Returns a tuple containing the
resulting assistant message, whether the assistant agent terminated
the conversation, and any additional assistant information, as well as
a tuple containing the resulting user message, whether the user agent
terminated the conversation, and any additional user information.
**Parameters:**
* **assistant\_msg**: A `BaseMessage` representing the message from the assistant.
**Returns:**
Tuple\[ChatAgentResponse, ChatAgentResponse]: A tuple containing two
ChatAgentResponse: the first struct contains the resulting
assistant message, whether the assistant agent terminated the
conversation, and any additional assistant information; the
second struct contains the resulting user message, whether the
user agent terminated the conversation, and any additional user
information.
### clone
```python theme={"system"}
def clone(self, task_prompt: str, with_memory: bool = False):
```
Creates a new instance of RolePlaying with the same configuration.
**Parameters:**
* **task\_prompt** (str): The task prompt to be used by the new instance.
* **with\_memory** (bool, optional): Whether to copy the memory (conversation history) to the new instance. If True, the new instance will have the same conversation history. If False, the new instance will have a fresh memory. (default: :obj:`False`)
**Returns:**
RolePlaying: A new instance of RolePlaying with the same
configuration.
### \_is\_multi\_response
```python theme={"system"}
def _is_multi_response(self, agent: ChatAgent):
```
Checks if the given agent supports multi-response.
**Parameters:**
* **agent** (ChatAgent): The agent to check for multi-response support.
**Returns:**
bool: True if the agent supports multi-response, False otherwise.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.base
## BaseNode
```python theme={"system"}
class BaseNode(ABC):
```
Base class for all nodes in the workforce.
**Parameters:**
* **description** (str): Description of the node.
* **node\_id** (Optional\[str]): ID of the node. If not provided, it will be generated automatically. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, description: str, node_id: Optional[str] = None):
```
### reset
```python theme={"system"}
def reset(self, *args: Any, **kwargs: Any):
```
Resets the node to its initial state.
### set\_channel
```python theme={"system"}
def set_channel(self, channel: TaskChannel):
```
Sets the channel for the node.
### stop
```python theme={"system"}
def stop(self):
```
Stop the node.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.role_playing_worker
## RolePlayingWorker
```python theme={"system"}
class RolePlayingWorker(Worker):
```
A worker node that contains a role playing.
**Parameters:**
* **description** (str): Description of the node.
* **assistant\_role\_name** (str): The role name of the assistant agent.
* **user\_role\_name** (str): The role name of the user agent.
* **assistant\_agent\_kwargs** (Optional\[Dict]): The keyword arguments to initialize the assistant agent in the role playing, like the model name, etc. (default: :obj:`None`)
* **user\_agent\_kwargs** (Optional\[Dict]): The keyword arguments to initialize the user agent in the role playing, like the model name, etc. (default: :obj:`None`)
* **summarize\_agent\_kwargs** (Optional\[Dict]): The keyword arguments to initialize the summarize agent, like the model name, etc. (default: :obj:`None`)
* **chat\_turn\_limit** (int): The maximum number of chat turns in the role playing. (default: :obj:`20`)
* **use\_structured\_output\_handler** (bool, optional): Whether to use the structured output handler instead of native structured output. When enabled, the workforce will use prompts with structured output instructions and regex extraction to parse responses. This ensures compatibility with agents that don't reliably support native structured output. When disabled, the workforce uses the native response\_format parameter. (default: :obj:`True`)
### **init**
```python theme={"system"}
def __init__(
self,
description: str,
assistant_role_name: str,
user_role_name: str,
assistant_agent_kwargs: Optional[Dict] = None,
user_agent_kwargs: Optional[Dict] = None,
summarize_agent_kwargs: Optional[Dict] = None,
chat_turn_limit: int = 20,
use_structured_output_handler: bool = True
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.single_agent_worker
## AgentPool
```python theme={"system"}
class AgentPool:
```
A pool of agent instances for efficient reuse.
This pool manages a collection of pre-cloned agents with automatic
scaling and idle timeout cleanup.
**Parameters:**
* **base\_agent** (ChatAgent): The base agent to clone from.
* **initial\_size** (int): Initial number of agents in the pool. (default: :obj:`1`)
* **max\_size** (int): Maximum number of agents in the pool. (default: :obj:`10`)
* **auto\_scale** (bool): Whether to automatically scale the pool size. (default: :obj:`True`)
* **idle\_timeout** (float): Time in seconds after which idle agents are removed. (default: :obj:`180.0`)
* **cleanup\_interval** (float): Fixed interval in seconds between cleanup checks. (default: :obj:`60.0`)
### **init**
```python theme={"system"}
def __init__(
self,
base_agent: ChatAgent,
initial_size: int = 1,
max_size: int = 10,
auto_scale: bool = True,
idle_timeout: float = 180.0,
cleanup_interval: float = 60.0
):
```
### \_initialize\_pool
```python theme={"system"}
def _initialize_pool(self, size: int):
```
Initialize the pool with the specified number of agents.
### \_create\_fresh\_agent
```python theme={"system"}
def _create_fresh_agent(self):
```
Create a fresh agent instance.
### get\_stats
```python theme={"system"}
def get_stats(self):
```
Get pool statistics.
## SingleAgentWorker
```python theme={"system"}
class SingleAgentWorker(Worker):
```
A worker node that consists of a single agent.
**Parameters:**
* **description** (str): Description of the node.
* **worker** (ChatAgent): Worker of the node. A single agent.
* **use\_agent\_pool** (bool): Whether to use agent pool for efficiency. (default: :obj:`True`)
* **pool\_initial\_size** (int): Initial size of the agent pool. (default: :obj:`1`)
* **pool\_max\_size** (int): Maximum size of the agent pool. (default: :obj:`10`)
* **auto\_scale\_pool** (bool): Whether to auto-scale the agent pool. (default: :obj:`True`)
* **use\_structured\_output\_handler** (bool, optional): Whether to use the structured output handler instead of native structured output. When enabled, the workforce will use prompts with structured output instructions and regex extraction to parse responses. This ensures compatibility with agents that don't reliably support native structured output. When disabled, the workforce uses the native response\_format parameter. (default: :obj:`True`)
* **context\_utility** (ContextUtility, optional): Shared context utility instance for workflow management. If provided, all workflow operations will use this shared instance instead of creating a new one. This ensures multiple workers share the same session directory. (default: :obj:`None`)
* **enable\_workflow\_memory** (bool, optional): Whether to enable workflow memory accumulation during task execution. When enabled, conversations from all task executions are accumulated for potential workflow saving. Set to True if you plan to call save\_workflow\_memories(). (default: :obj:`False`)
### **init**
```python theme={"system"}
def __init__(
self,
description: str,
worker: ChatAgent,
use_agent_pool: bool = True,
pool_initial_size: int = 1,
pool_max_size: int = 10,
auto_scale_pool: bool = True,
use_structured_output_handler: bool = True,
context_utility: Optional[ContextUtility] = None,
enable_workflow_memory: bool = False
):
```
### reset
```python theme={"system"}
def reset(self):
```
Resets the worker to its initial state.
### \_get\_context\_utility
```python theme={"system"}
def _get_context_utility(self):
```
Get context utility with lazy initialization.
### \_get\_conversation\_accumulator
```python theme={"system"}
def _get_conversation_accumulator(self):
```
Get or create the conversation accumulator agent.
### \_get\_workflow\_manager
```python theme={"system"}
def _get_workflow_manager(self):
```
Get or create the workflow memory manager.
### get\_pool\_stats
```python theme={"system"}
def get_pool_stats(self):
```
Get agent pool statistics if pool is enabled.
### save\_workflow\_memories
```python theme={"system"}
def save_workflow_memories(self):
```
**Returns:**
Dict\[str, Any]: Result dictionary with keys:
* status (str): "success" or "error"
* summary (str): Generated workflow summary
* file\_path (str): Path to saved file
* worker\_description (str): Worker description used
See Also:
:meth:`save_workflow_memories_async`: Async version for better
performance in parallel workflows.
### load\_workflow\_memories
```python theme={"system"}
def load_workflow_memories(
self,
pattern: Optional[str] = None,
max_workflows: int = 3,
session_id: Optional[str] = None,
use_smart_selection: bool = True
):
```
Load workflow memories using intelligent agent-based selection.
This method uses the worker agent to intelligently select the most
relevant workflows based on metadata (title, description, tags)
rather than simple filename pattern matching.
Delegates to WorkflowMemoryManager for all workflow operations.
**Parameters:**
* **pattern** (Optional\[str]): Legacy parameter for backward compatibility. When use\_smart\_selection=False, uses this pattern for file matching. Ignored when smart selection is enabled.
* **max\_workflows** (int): Maximum number of workflow files to load. (default: :obj:`3`)
* **session\_id** (Optional\[str]): Specific workforce session ID to load from. If None, searches across all sessions. (default: :obj:`None`)
* **use\_smart\_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses metadata and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
**Returns:**
bool: True if workflow memories were successfully loaded, False
otherwise.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.structured_output_handler
## StructuredOutputHandler
```python theme={"system"}
class StructuredOutputHandler:
```
Handler for generating prompts and extracting structured output from
agent responses.
This handler provides functionality to:
* Generate prompts that guide agents to produce structured output
* Extract structured data from agent responses using regex patterns
* Provide fallback mechanisms when extraction fails
* Support the existing structured output schemas used in workforce.py
### generate\_structured\_prompt
```python theme={"system"}
def generate_structured_prompt(
base_prompt: str,
schema: Type[BaseModel],
examples: Optional[List[Dict[str, Any]]] = None,
additional_instructions: Optional[str] = None
):
```
Generate a prompt that guides agents to produce structured output.
**Parameters:**
* **base\_prompt** (str): The base prompt content.
* **schema** (Type\[BaseModel]): The Pydantic model schema for the expected output.
* **examples** (Optional\[List\[Dict\[str, Any]]]): Optional examples of valid output.
* **additional\_instructions** (Optional\[str]): Additional instructions for output formatting.
**Returns:**
str: The enhanced prompt with structured output instructions.
### extract\_json
```python theme={"system"}
def extract_json(text: str, schema: Optional[Type[BaseModel]] = None):
```
Extract JSON data from text using multiple patterns.
**Parameters:**
* **text** (str): The text containing JSON data.
* **schema** (Optional\[Type\[BaseModel]]): Optional schema for targeted extraction.
**Returns:**
Optional\[Dict\[str, Any]]: Extracted JSON data or None if extraction
fails.
### \_extract\_with\_schema\_patterns
```python theme={"system"}
def _extract_with_schema_patterns(text: str, schema: Type[BaseModel]):
```
Extract data using schema-specific patterns.
**Parameters:**
* **text** (str): The text to extract from.
* **schema** (Type\[BaseModel]): The schema to use for extraction.
**Returns:**
Optional\[Dict\[str, Any]]: Extracted data or None.
### parse\_structured\_response
```python theme={"system"}
def parse_structured_response(
response_text: str,
schema: Type[BaseModel],
fallback_values: Optional[Dict[str, Any]] = None
):
```
Parse agent response into structured data with fallback support.
**Parameters:**
* **response\_text** (str): The agent's response text.
* **schema** (Type\[BaseModel]): The expected schema.
* **fallback\_values** (Optional\[Dict\[str, Any]]): Fallback values to use if parsing fails.
**Returns:**
Union\[BaseModel, Dict\[str, Any]]: Parsed data as schema instance
or fallback dictionary.
### \_fix\_common\_issues
```python theme={"system"}
def _fix_common_issues(data: Dict[str, Any], schema: Type[BaseModel]):
```
Attempt to fix common validation issues in extracted data.
**Parameters:**
* **data** (Dict\[str, Any]): The extracted data.
* **schema** (Type\[BaseModel]): The target schema.
**Returns:**
Optional\[Dict\[str, Any]]: Fixed data or None if unfixable.
### \_create\_default\_instance
```python theme={"system"}
def _create_default_instance(schema: Type[BaseModel]):
```
Create a default instance of the schema with minimal required
fields.
**Parameters:**
* **schema** (Type\[BaseModel]): The schema to instantiate.
**Returns:**
BaseModel: Default instance of the schema.
### validate\_response
```python theme={"system"}
def validate_response(
response: Union[BaseModel, Dict[str, Any]],
schema: Type[BaseModel]
):
```
Validate that a response conforms to the expected schema.
**Parameters:**
* **response**: The response to validate.
* **schema** (Type\[BaseModel]): The expected schema.
**Returns:**
bool: True if valid, False otherwise.
### create\_fallback\_response
```python theme={"system"}
def create_fallback_response(
schema: Type[BaseModel],
error_message: str,
context: Optional[Dict[str, Any]] = None
):
```
Create a fallback response for a given schema with error context.
**Parameters:**
* **schema** (Type\[BaseModel]): The schema to create a response for.
* **error\_message** (str): The error message to include.
* **context** (Optional\[Dict\[str, Any]]): Additional context for the fallback.
**Returns:**
BaseModel: A valid instance of the schema with fallback values.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.task_channel
## PacketStatus
```python theme={"system"}
class PacketStatus(Enum):
```
The status of a packet. The packet can be in one of the following
states:
* `__INLINE_CODE_0__`: The packet has been sent to a worker.
* `__INLINE_CODE_1__`: The packet has been claimed by a worker and is being
processed.
* `__INLINE_CODE_2__`: The packet has been returned by the worker, meaning that
the status of the task inside has been updated.
* `__INLINE_CODE_3__`: The packet has been archived, meaning that the content of
the task inside will not be changed. The task is considered
as a dependency.
## Packet
```python theme={"system"}
class Packet:
```
The basic element inside the channel. A task is wrapped inside a
packet. The packet will contain the task, along with the task's assignee,
and the task's status.
**Parameters:**
* **task** (Task): The task that is wrapped inside the packet.
* **publisher\_id** (str): The ID of the workforce that published the task.
* **assignee\_id** (Optional\[str], optional): The ID of the workforce that is assigned to the task. Would be None if the task is a dependency. Defaults to None.
* **status** (PacketStatus): The status of the task.
### **init**
```python theme={"system"}
def __init__(
self,
task: Task,
publisher_id: str,
assignee_id: Optional[str] = None,
status: PacketStatus = PacketStatus.SENT
):
```
### **repr**
```python theme={"system"}
def __repr__(self):
```
## TaskChannel
```python theme={"system"}
class TaskChannel:
```
An internal class used by Workforce to manage tasks.
This implementation uses a hybrid data structure approach:
* Hash map (\_task\_dict) for O(1) task lookup by ID
* Status-based index (\_task\_by\_status) for efficient filtering by status
* Assignee/publisher queues for ordered task processing
### **init**
```python theme={"system"}
def __init__(self):
```
### \_update\_task\_status
```python theme={"system"}
def _update_task_status(self, task_id: str, new_status: PacketStatus):
```
Helper method to properly update task status in all indexes.
### \_cleanup\_task\_from\_indexes
```python theme={"system"}
def _cleanup_task_from_indexes(self, task_id: str):
```
Helper method to remove a task from all indexes.
**Parameters:**
* **task\_id** (str): The ID of the task to remove from indexes.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.utils
## is\_generic\_role\_name
```python theme={"system"}
def is_generic_role_name(role_name: str):
```
Check if a role name is generic and should trigger fallback logic.
Generic role names are common, non-specific identifiers that don't
provide meaningful information about an agent's actual purpose.
When a role name is generic, fallback logic should be used to find
a more specific identifier (e.g., from LLM-generated agent\_title
or description).
**Parameters:**
* **role\_name** (str): The role name to check (will be converted to lowercase for case-insensitive comparison).
**Returns:**
bool: True if the role name is generic, False otherwise.
## WorkflowMetadata
```python theme={"system"}
class WorkflowMetadata(BaseModel):
```
Pydantic model for workflow metadata tracking.
This model defines the formal schema for workflow metadata that tracks
versioning, timestamps, and contextual information about saved workflows.
Used to maintain workflow history and enable proper version management.
## WorkflowConfig
```python theme={"system"}
class WorkflowConfig(BaseModel):
```
Configuration for workflow memory management.
Centralizes all workflow-related configuration options to avoid scattered
settings across multiple files and methods.
## WorkerConf
```python theme={"system"}
class WorkerConf(BaseModel):
```
The configuration of a worker.
## TaskResult
```python theme={"system"}
class TaskResult(BaseModel):
```
The result of a task.
## QualityEvaluation
```python theme={"system"}
class QualityEvaluation(BaseModel):
```
Quality evaluation result for a completed task.
.. deprecated::
Use :class:`TaskAnalysisResult` instead. This class is kept for
backward compatibility.
## TaskAssignment
```python theme={"system"}
class TaskAssignment(BaseModel):
```
An individual task assignment within a batch.
### \_split\_and\_strip
```python theme={"system"}
def _split_and_strip(dep_str: str):
```
Utility to split a comma separated string and strip
whitespace.
### validate\_dependencies
```python theme={"system"}
def validate_dependencies(cls, v):
```
## TaskAssignResult
```python theme={"system"}
class TaskAssignResult(BaseModel):
```
The result of task assignment for both single and batch
assignments.
## RecoveryStrategy
```python theme={"system"}
class RecoveryStrategy(str, Enum):
```
Strategies for handling failed tasks.
### **str**
```python theme={"system"}
def __str__(self):
```
### **repr**
```python theme={"system"}
def __repr__(self):
```
## FailureHandlingConfig
```python theme={"system"}
class FailureHandlingConfig(BaseModel):
```
Configuration for failure handling behavior in Workforce.
This configuration allows users to customize how the Workforce handles
task failures. This config allows users to disable reassignment or other
recovery strategies as needed.
**Parameters:**
* **max\_retries** (int): Maximum number of retry attempts before giving up on a task. (default: :obj:`3`)
* **enabled\_strategies** (Optional\[List\[RecoveryStrategy]]): List of recovery strategies that are allowed to be used. Can be specified as RecoveryStrategy enums or strings (e.g., \["retry", "replan"]). If None, all strategies are enabled (with LLM analysis). If an empty list, no recovery strategies are applied and failed tasks are marked as failed immediately. If only \["retry"] is specified, simple retry is used without LLM analysis. (default: :obj:`None` - all strategies enabled)
* **halt\_on\_max\_retries** (bool): Whether to halt the entire workforce when a task exceeds max retries. If False, the task is marked as failed and the workflow continues (similar to PIPELINE mode behavior). (default: :obj:`True` for AUTO\_DECOMPOSE mode behavior)
### validate\_enabled\_strategies
```python theme={"system"}
def validate_enabled_strategies(cls, v):
```
Convert string list to RecoveryStrategy enum list.
## FailureContext
```python theme={"system"}
class FailureContext(BaseModel):
```
Context information about a task failure.
## TaskAnalysisResult
```python theme={"system"}
class TaskAnalysisResult(BaseModel):
```
Unified result for task failure analysis and quality evaluation.
This model combines both failure recovery decisions and quality evaluation
results into a single structure. For failure analysis, only the recovery
strategy and reasoning fields are populated. For quality evaluation, all
fields including quality\_score and issues are populated.
### is\_quality\_evaluation
```python theme={"system"}
def is_quality_evaluation(self):
```
**Returns:**
bool: True if this is a quality evaluation (has quality\_score),
False if this is a failure analysis.
### quality\_sufficient
```python theme={"system"}
def quality_sufficient(self):
```
**Returns:**
bool: True if quality is sufficient (score `>= 70` and no recovery
strategy recommended), False otherwise. Always False for
failure analysis results.
## PipelineTaskBuilder
```python theme={"system"}
class PipelineTaskBuilder:
```
Helper class for building pipeline tasks with dependencies.
### **init**
```python theme={"system"}
def __init__(self):
```
Initialize an empty pipeline task builder.
### add
```python theme={"system"}
def add(
self,
content: str,
task_id: Optional[str] = None,
dependencies: Optional[List[str]] = None,
additional_info: Optional[dict] = None,
auto_depend: bool = True
):
```
Add a task to the pipeline with support for chaining.
**Parameters:**
* **content** (str): The content/description of the task.
* **task\_id** (str, optional): Unique identifier for the task. If None, a unique ID will be generated. (default: :obj:`None`)
* **dependencies** (List\[str], optional): List of task IDs that this task depends on. If None and auto\_depend=True, will depend on the last added task. (default: :obj:`None`)
* **additional\_info** (dict, optional): Additional information for the task. (default: :obj:`None`)
* **auto\_depend** (bool, optional): If True and dependencies is None, automatically depend on the last added task. (default: :obj:`True`)
**Returns:**
PipelineTaskBuilder: Self for method chaining.
### add\_parallel\_tasks
```python theme={"system"}
def add_parallel_tasks(
self,
task_contents: List[str],
dependencies: Optional[List[str]] = None,
task_id_prefix: str = 'parallel',
auto_depend: bool = True
):
```
Add multiple parallel tasks that can execute simultaneously.
**Parameters:**
* **task\_contents** (List\[str]): List of task content strings.
* **dependencies** (List\[str], optional): Common dependencies for all parallel tasks. If None and auto\_depend=True, will depend on the last added task. (default: :obj:`None`)
* **task\_id\_prefix** (str, optional): Prefix for generated task IDs. (default: :obj:`"parallel"`)
* **auto\_depend** (bool, optional): If True and dependencies is None, automatically depend on the last added task. (default: :obj:`True`)
**Returns:**
PipelineTaskBuilder: Self for method chaining.
### add\_sync\_task
```python theme={"system"}
def add_sync_task(
self,
content: str,
wait_for: Optional[List[str]] = None,
task_id: Optional[str] = None
):
```
Add a synchronization task that waits for multiple tasks.
**Parameters:**
* **content** (str): Content of the synchronization task.
* **wait\_for** (List\[str], optional): List of task IDs to wait for. If None, will automatically wait for the last parallel tasks. (default: :obj:`None`)
* **task\_id** (str, optional): ID for the sync task. If None, a unique ID will be generated. (default: :obj:`None`)
**Returns:**
PipelineTaskBuilder: Self for method chaining.
### build
```python theme={"system"}
def build(self):
```
**Returns:**
List\[Task]: List of tasks with proper dependency relationships.
### clear
```python theme={"system"}
def clear(self):
```
Clear all tasks from the builder.
### fork
```python theme={"system"}
def fork(self, task_contents: List[str]):
```
Create parallel branches from the current task (alias for
add\_parallel\_tasks).
**Parameters:**
* **task\_contents** (List\[str]): List of task content strings for parallel execution.
**Returns:**
PipelineTaskBuilder: Self for method chaining.
### join
```python theme={"system"}
def join(self, content: str, task_id: Optional[str] = None):
```
Join parallel branches with a synchronization task (alias for
add\_sync\_task).
**Parameters:**
* **content** (str): Content of the join/sync task.
* **task\_id** (str, optional): ID for the sync task.
**Returns:**
PipelineTaskBuilder: Self for method chaining.
### \_validate\_dependencies
```python theme={"system"}
def _validate_dependencies(self):
```
### get\_task\_info
```python theme={"system"}
def get_task_info(self):
```
**Returns:**
dict: Dictionary containing task count and task details.
## check\_if\_running
```python theme={"system"}
def check_if_running(
running: bool,
max_retries: int = 3,
retry_delay: float = 1.0,
handle_exceptions: bool = False
):
```
Check if the workforce is (not) running, specified by the boolean
value. Provides fault tolerance through automatic retries and exception
handling.
**Parameters:**
* **running** (bool): Expected running state (True or False).
* **max\_retries** (int, optional): Maximum number of retry attempts if the operation fails. Set to 0 to disable retries. (default: :obj:`3`)
* **retry\_delay** (float, optional): Delay in seconds between retry attempts. (default: :obj:`1.0`)
* **handle\_exceptions** (bool, optional): If True, catch and log exceptions instead of propagating them. (default: :obj:`False`)
**Raises:**
* **RuntimeError**: If the workforce is not in the expected status and
* **Exception**: Any exception raised by the decorated function if
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.worker
## Worker
```python theme={"system"}
class Worker(BaseNode, ABC):
```
A worker node that works on tasks. It is the basic unit of task
processing in the workforce system.
**Parameters:**
* **description** (str): Description of the node.
* **node\_id** (Optional\[str]): ID of the node. If not provided, it will be generated automatically. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, description: str, node_id: Optional[str] = None):
```
### **repr**
```python theme={"system"}
def __repr__(self):
```
### \_get\_dep\_tasks\_info
```python theme={"system"}
def _get_dep_tasks_info(dependencies: List[Task]):
```
### set\_channel
```python theme={"system"}
def set_channel(self, channel: TaskChannel):
```
### stop
```python theme={"system"}
def stop(self):
```
Forcefully stop the worker.
Cancels all running tasks immediately and sets the stop flag.
The worker will exit after completing cancellation.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.workflow_memory_manager
## WorkflowSelectionMethod
```python theme={"system"}
class WorkflowSelectionMethod(Enum):
```
Enum representing the method used to select workflows.
**Parameters:**
* **AGENT\_SELECTED**: Agent-based intelligent selection using metadata.
* **ROLE\_NAME\_MATCH**: Pattern matching by role\_name.
* **MOST\_RECENT**: Fallback to most recent workflows.
* **ALL\_AVAILABLE**: Returned all workflows (fewer than max requested).
* **NONE**: No workflows available.
## WorkflowMemoryManager
```python theme={"system"}
class WorkflowMemoryManager:
```
Manages workflow memory operations for workforce workers.
This class encapsulates all workflow memory functionality including
intelligent loading, saving, and selection of workflows. It separates
workflow management concerns from the core worker task processing logic.
**Parameters:**
* **worker** (ChatAgent): The worker agent that will use workflows.
* **description** (str): Description of the worker's role.
* **context\_utility** (Optional\[ContextUtility]): Shared context utility for workflow operations. If None, creates a new instance.
* **role\_identifier** (Optional\[str]): Role identifier for organizing workflows by role. If provided, workflows will be stored in role-based folders. If None, uses default workforce context.
* **config** (Optional\[WorkflowConfig]): Configuration for workflow management. If None, uses default configuration.
### **init**
```python theme={"system"}
def __init__(
self,
worker: ChatAgent,
description: str,
context_utility: Optional[ContextUtility] = None,
role_identifier: Optional[str] = None,
config: Optional[WorkflowConfig] = None
):
```
### \_get\_context\_utility
```python theme={"system"}
def _get_context_utility(self):
```
Get context utility with lazy initialization.
Uses role-based context if role\_identifier is set, otherwise falls
back to default workforce shared context.
### \_extract\_existing\_workflow\_metadata
```python theme={"system"}
def _extract_existing_workflow_metadata(self, file_path: Path):
```
Extract metadata from an existing workflow file for versioning.
This method reads the metadata section from an existing workflow
markdown file to retrieve version number and creation timestamp,
enabling proper version tracking when updating workflows.
**Parameters:**
* **file\_path** (Path): Path to the existing workflow file.
**Returns:**
Optional\[WorkflowMetadata]: WorkflowMetadata instance if file
exists and metadata is successfully parsed, None otherwise.
### \_try\_role\_based\_loading
```python theme={"system"}
def _try_role_based_loading(
self,
role_name: str,
pattern: Optional[str],
max_files_to_load: int,
use_smart_selection: bool
):
```
Try loading workflows from role-based directory structure.
**Parameters:**
* **role\_name** (str): Role name to load workflows from.
* **pattern** (Optional\[str]): Custom search pattern for workflow files.
* **max\_files\_to\_load** (int): Maximum number of workflow files to load.
* **use\_smart\_selection** (bool): Whether to use agent-based selection.
**Returns:**
bool: True if workflows were successfully loaded, False otherwise.
### \_try\_session\_based\_loading
```python theme={"system"}
def _try_session_based_loading(
self,
session_id: str,
role_name: str,
pattern: Optional[str],
max_files_to_load: int,
use_smart_selection: bool
):
```
Try loading workflows from session-based directory (deprecated).
**Parameters:**
* **session\_id** (str): Workforce session ID to load from.
* **role\_name** (str): Role name (for deprecation warning).
* **pattern** (Optional\[str]): Custom search pattern for workflow files.
* **max\_files\_to\_load** (int): Maximum number of workflow files to load.
* **use\_smart\_selection** (bool): Whether to use agent-based selection.
**Returns:**
bool: True if workflows were successfully loaded, False otherwise.
### \_session\_based\_smart\_loading
```python theme={"system"}
def _session_based_smart_loading(self, session_id: str, max_files_to_load: int):
```
Load workflows from session using smart selection.
**Parameters:**
* **session\_id** (str): Session ID to load from.
* **max\_files\_to\_load** (int): Maximum number of files to load.
**Returns:**
bool: True if workflows were loaded, False otherwise.
### \_session\_based\_pattern\_loading
```python theme={"system"}
def _session_based_pattern_loading(
self,
pattern: Optional[str],
session_id: str,
max_files_to_load: int
):
```
Load workflows from session using pattern matching.
**Parameters:**
* **pattern** (Optional\[str]): Pattern for file matching.
* **session\_id** (str): Session ID to load from.
* **max\_files\_to\_load** (int): Maximum number of files to load.
**Returns:**
bool: True if workflows were loaded, False otherwise.
### load\_workflows
```python theme={"system"}
def load_workflows(
self,
pattern: Optional[str] = None,
max_files_to_load: Optional[int] = None,
session_id: Optional[str] = None,
use_smart_selection: bool = True
):
```
Load workflow memories using intelligent agent-based selection.
This method first tries to load workflows from the role-based folder
structure. If no workflows are found and session\_id is provided, falls
back to session-based loading (deprecated).
**Parameters:**
* **pattern** (Optional\[str]): Legacy parameter for backward compatibility. When use\_smart\_selection=False, uses this pattern for file matching. Ignored when smart selection is enabled.
* **max\_files\_to\_load** (Optional\[int]): Maximum number of workflow files to load. If None, uses config.default\_max\_files\_to\_load. (default: :obj:`None`)
* **session\_id** (Optional\[str]): Deprecated. Specific workforce session ID to load from using legacy session-based organization. (default: :obj:`None`)
* **use\_smart\_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses workflow information and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
**Returns:**
bool: True if workflow memories were successfully loaded, False
otherwise. Check logs for detailed error messages.
### load\_workflows\_by\_role
```python theme={"system"}
def load_workflows_by_role(
self,
role_name: Optional[str] = None,
pattern: Optional[str] = None,
max_files_to_load: Optional[int] = None,
use_smart_selection: bool = True
):
```
Load workflow memories from role-based directory structure.
This method loads workflows from the new role-based folder structure:
workforce\_workflows/\{role\_name}/\*.md
**Parameters:**
* **role\_name** (Optional\[str]): Role name to load workflows from. If None, uses the worker's role\_name or role\_identifier.
* **pattern** (Optional\[str]): Custom search pattern for workflow files. Ignored when use\_smart\_selection=True.
* **max\_files\_to\_load** (Optional\[int]): Maximum number of workflow files to load. If None, uses config.default\_max\_files\_to\_load. (default: :obj:`None`)
* **use\_smart\_selection** (bool): Whether to use agent-based intelligent workflow selection. When True, uses workflow information and LLM to select most relevant workflows. When False, falls back to pattern matching. (default: :obj:`True`)
**Returns:**
bool: True if workflow memories were successfully loaded, False
otherwise.
### save\_workflow
```python theme={"system"}
def save_workflow(self, conversation_accumulator: Optional[ChatAgent] = None):
```
Save the worker's current workflow memories using agent
summarization.
This method uses a two-pass approach: first generates the workflow
summary to determine operation\_mode (update vs create), then saves
to the appropriate file path based on that decision.
**Parameters:**
* **conversation\_accumulator** (Optional\[ChatAgent]): Optional accumulator agent with collected conversations. If provided, uses this instead of the main worker agent.
**Returns:**
Dict\[str, Any]: Result dictionary with keys:
* status (str): "success" or "error"
* summary (str): Generated workflow summary
* file\_path (str): Path to saved file
* worker\_description (str): Worker description used
### generate\_workflow\_summary
```python theme={"system"}
def generate_workflow_summary(self, conversation_accumulator: Optional[ChatAgent] = None):
```
Generate a workflow summary without saving to disk.
This method generates a workflow summary by calling a dedicated
summarizer agent. It does NOT save to disk - only generates the
summary content and structured output. Use this when you need to
inspect the summary (e.g., extract operation\_mode) before determining
where to save it.
**Parameters:**
* **conversation\_accumulator** (Optional\[ChatAgent]): Optional accumulator agent with collected conversations. If provided, uses this instead of the main worker agent.
**Returns:**
Dict\[str, Any]: Result dictionary with:
* structured\_summary: WorkflowSummary instance or None
* summary\_content: Raw text content
* status: "success" or error message
### save\_workflow\_content
```python theme={"system"}
def save_workflow_content(
self,
workflow_summary: 'WorkflowSummary',
context_utility: Optional[ContextUtility] = None,
conversation_accumulator: Optional[ChatAgent] = None
):
```
Save a pre-generated workflow summary to disk.
This method takes a pre-generated WorkflowSummary object and saves
it to disk using the provided context utility. It does NOT call the
LLM - just formats and saves the content. Use this for two-pass
workflows where the summary is generated first, then saved to a
location determined by the summary content.
**Parameters:**
* **workflow\_summary** (WorkflowSummary): Pre-generated workflow summary object containing task\_title, agent\_title, etc.
* **context\_utility** (Optional\[ContextUtility]): Context utility with correct working directory. If None, uses default.
* **conversation\_accumulator** (Optional\[ChatAgent]): An optional agent that holds accumulated conversation history. Used to get accurate message\_count metadata. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: Result dictionary with keys:
* status (str): "success" or "error"
* summary (str): Formatted workflow summary
* file\_path (str): Path to saved file
* worker\_description (str): Worker description used
### \_select\_relevant\_workflows
```python theme={"system"}
def _select_relevant_workflows(
self,
workflows_metadata: List[Dict[str, Any]],
max_files: int,
session_id: Optional[str] = None
):
```
Use worker agent to select most relevant workflows.
This method creates a prompt with all available workflow information
and uses the worker agent to intelligently select the most relevant
workflows based on the worker's role and description.
**Parameters:**
* **workflows\_metadata** (List\[Dict\[str, Any]]): List of workflow information dicts (contains title, description, tags, file\_path).
* **max\_files** (int): Maximum number of workflows to select.
* **session\_id** (Optional\[str]): Specific workforce session ID to search in for fallback pattern matching. If None, searches across all sessions. (default: :obj:`None`)
**Returns:**
tuple\[List\[str], WorkflowSelectionMethod]: Tuple of (selected
workflow file paths, selection method used).
### \_format\_workflows\_for\_selection
```python theme={"system"}
def _format_workflows_for_selection(self, workflows_metadata: List[Dict[str, Any]]):
```
Format workflow information into a readable prompt for selection.
**Parameters:**
* **workflows\_metadata** (List\[Dict\[str, Any]]): List of workflow information dicts (contains title, description, tags, file\_path).
**Returns:**
str: Formatted string presenting workflows for LLM selection.
### \_find\_workflow\_files
```python theme={"system"}
def _find_workflow_files(self, pattern: Optional[str], session_id: Optional[str] = None):
```
Find and return sorted workflow files matching the pattern.
.. note::
Session-based workflow search will be deprecated in a future
version. Consider using :meth:`_find_workflow_files_by_role` for
role-based organization instead.
**Parameters:**
* **pattern** (Optional\[str]): Custom search pattern for workflow files. If None, uses worker role\_name to generate pattern.
* **session\_id** (Optional\[str]): Specific session ID to search in. If None, searches across all sessions.
**Returns:**
List\[str]: Sorted list of workflow file paths (empty if
validation fails).
### \_find\_workflow\_files\_by\_role
```python theme={"system"}
def _find_workflow_files_by_role(
self,
role_name: Optional[str] = None,
pattern: Optional[str] = None
):
```
Find workflow files in role-based directory structure.
This method searches for workflows in the new role-based folder
structure: workforce\_workflows/\{role\_name}/\*.md
**Parameters:**
* **role\_name** (Optional\[str]): Role name to search for. If None, uses the worker's role\_name or role\_identifier.
* **pattern** (Optional\[str]): Custom search pattern for workflow files. If None, searches for all workflow files in the role directory.
**Returns:**
List\[str]: Sorted list of workflow file paths by modification time
(most recent first).
### \_collect\_workflow\_contents
```python theme={"system"}
def _collect_workflow_contents(self, workflow_files: List[str]):
```
Collect and load workflow file contents.
Also populates the \_loaded\_workflow\_paths mapping for use during
workflow save operations (to support update mode).
**Parameters:**
* **workflow\_files** (List\[str]): List of workflow file paths to load.
**Returns:**
List\[Dict\[str, str]]: List of dicts with 'filename' and
'content' keys.
### \_format\_workflow\_list
```python theme={"system"}
def _format_workflow_list(self, workflows_to_load: List[Dict[str, str]]):
```
Format a list of workflows into a readable string.
This is a helper method that formats workflow content without
adding outer headers/footers. Used by \_format\_workflows\_for\_context
and \_prepare\_workflow\_prompt.
**Parameters:**
* **workflows\_to\_load** (List\[Dict\[str, str]]): List of workflow dicts with 'filename' and 'content' keys.
**Returns:**
str: Formatted workflow list string.
### \_format\_workflows\_for\_context
```python theme={"system"}
def _format_workflows_for_context(self, workflows_to_load: List[Dict[str, str]]):
```
Format workflows into a context string for the agent.
**Parameters:**
* **workflows\_to\_load** (List\[Dict\[str, str]]): List of workflow dicts with 'filename' and 'content' keys.
**Returns:**
str: Formatted workflow context string with header and all
workflows.
### \_add\_workflows\_to\_system\_message
```python theme={"system"}
def _add_workflows_to_system_message(self, workflow_context: str):
```
Add workflow context to agent's system message.
**Parameters:**
* **workflow\_context** (str): The formatted workflow context to add.
**Returns:**
bool: True if successful, False otherwise.
### \_load\_workflow\_files
```python theme={"system"}
def _load_workflow_files(self, workflow_files: List[str], max_workflows: int):
```
Load workflow files and return count of successful loads.
Loads all workflows together with a single header to avoid repetition.
Clears and repopulates the \_loaded\_workflow\_paths mapping.
**Parameters:**
* **workflow\_files** (List\[str]): List of workflow file paths to load.
* **max\_workflows** (int): Maximum number of workflows to load.
**Returns:**
int: Number of successfully loaded workflow files.
### \_get\_sanitized\_role\_name
```python theme={"system"}
def _get_sanitized_role_name(self):
```
**Returns:**
str: Sanitized role name suitable for use in filenames.
### \_generate\_workflow\_filename
```python theme={"system"}
def _generate_workflow_filename(self):
```
**Returns:**
str: Sanitized filename without timestamp and without .md
extension. Format: \{role\_name}\{workflow\_filename\_suffix}
### \_prepare\_workflow\_prompt
```python theme={"system"}
def _prepare_workflow_prompt(self):
```
**Returns:**
str: Structured prompt for workflow summary.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.workforce
## WorkforceState
```python theme={"system"}
class WorkforceState(Enum):
```
Workforce execution state for human intervention support.
## WorkforceMode
```python theme={"system"}
class WorkforceMode(Enum):
```
Workforce execution mode for different task processing strategies.
## WorkforceSnapshot
```python theme={"system"}
class WorkforceSnapshot:
```
Snapshot of workforce state for resuming execution.
### **init**
```python theme={"system"}
def __init__(
self,
main_task: Optional[Task] = None,
pending_tasks: Optional[Deque[Task]] = None,
completed_tasks: Optional[List[Task]] = None,
task_dependencies: Optional[Dict[str, List[str]]] = None,
assignees: Optional[Dict[str, str]] = None,
current_task_index: int = 0,
description: str = ''
):
```
## Workforce
```python theme={"system"}
class Workforce(BaseNode):
```
A system where multiple worker nodes (agents) cooperate together
to solve tasks. It can assign tasks to worker nodes and also take
strategies such as create new worker, decompose tasks, etc. to handle
situations when the task fails.
The workforce uses three specialized ChatAgents internally:
* Coordinator Agent: Assigns tasks to workers based on their
capabilities
* Task Planner Agent: Decomposes complex tasks and composes results
* Dynamic Workers: Created at runtime when tasks fail repeatedly
**Parameters:**
* **description** (str): Description of the workforce.
* **children** (Optional\[List\[BaseNode]], optional): List of child nodes under this node. Each child node can be a worker node or another workforce node. (default: :obj:`None`)
* **coordinator\_agent** (Optional\[ChatAgent], optional): A custom coordinator agent instance for task assignment and worker creation. If provided, the workforce will create a new agent using this agent's model configuration but with the required system message and functionality. If None, a default agent will be created using DEFAULT model settings. (default: :obj:`None`)
* **task\_agent** (Optional\[ChatAgent], optional): A custom task planning agent instance for task decomposition and composition. If provided, the workforce will create a new agent using this agent's model configuration but with the required system message. If None, a default agent will be created using DEFAULT model settings. (default: :obj:`None`)
* **new\_worker\_agent** (Optional\[ChatAgent], optional): A template agent for workers created dynamically at runtime when existing workers cannot handle failed tasks. If None, workers will be created with default settings including SearchToolkit, CodeExecutionToolkit, and ThinkingToolkit. (default: :obj:`None`) default\_model (Optional\[Union\[BaseModelBackend, ModelManager]], optional): Model backend or manager to use when creating default coordinator, task, or dynamic worker agents. If None, agents will be created using ModelPlatformType.DEFAULT and ModelType.DEFAULT settings. (default: :obj:`None`)
* **graceful\_shutdown\_timeout** (float, optional): The timeout in seconds for graceful shutdown when a task fails 3 times. During this period, the workforce remains active for debugging. Set to 0 for immediate shutdown. (default: :obj:`15.0`)
* **task\_timeout\_seconds** (Optional\[float], optional): The timeout in seconds for waiting for tasks to be returned by workers. If None, uses the global TASK\_TIMEOUT\_SECONDS value (600.0 seconds). Increase this value for tasks that require more processing time. (default: :obj:`None`)
* **share\_memory** (bool, optional): Whether to enable shared memory across SingleAgentWorker instances in the workforce. When enabled, all SingleAgentWorker instances, coordinator agent, and task planning agent will share their complete conversation history and function-calling trajectory, providing better context for task handoffs and continuity. Note: Currently only supports SingleAgentWorker instances; RolePlayingWorker and nested Workforce instances do not participate in memory sharing. (default: :obj:`False`)
* **use\_structured\_output\_handler** (bool, optional): Whether to use the structured output handler instead of native structured output. When enabled, the workforce will use prompts with structured output instructions and regex extraction to parse responses. This ensures compatibility with agents that don't reliably support native structured output. When disabled, the workforce uses the native response\_format parameter. (default: :obj:`True`)
* **callbacks** (Optional\[List\[WorkforceCallback]], optional): A list of callback handlers to observe and record workforce lifecycle events and metrics (e.g., task creation/assignment/start/completion/ failure, worker creation/deletion, all-tasks-completed). All items must be instances of :class:`WorkforceCallback`, otherwise
* **a**: class:`ValueError` is raised. If none of the provided callbacks implement :class:`WorkforceMetrics`, a built-in :class:`WorkforceLogger` (implements both callback and metrics) is added automatically. If at least one provided callback
* **implements**: class:`WorkforceMetrics`, no default logger is added. (default: :obj:`None`)
* **mode** (WorkforceMode, optional): The execution mode for task processing. AUTO\_DECOMPOSE mode uses intelligent recovery strategies (decompose, replan, etc.) when tasks fail. PIPELINE mode uses simple retry logic and allows failed tasks to continue the workflow, passing error information to dependent tasks. (default: :obj:`WorkforceMode.AUTO_DECOMPOSE`)
* **failure\_handling\_config** (Optional\[Union\[FailureHandlingConfig, Dict]]): Configuration for customizing failure handling behavior. Can be a FailureHandlingConfig instance or a dict with the same fields. Allows fine-grained control over which recovery strategies are enabled, maximum retry attempts, and whether to halt on max retries. The `enabled_strategies` field accepts both enum values and string lists like `["retry", "replan"]`. If None, uses default configuration with all strategies enabled. (default: :obj:`None`)
**Note:**
When custom coordinator\_agent or task\_agent are provided, the workforce
will preserve the user's system message and append the required
workforce coordination or task planning instructions to it. This
ensures both the user's intent is preserved and proper workforce
functionality is maintained. All other agent configurations (model,
memory, tools, etc.) will also be preserved.
### **init**
```python theme={"system"}
def __init__(
self,
description: str,
children: Optional[List[BaseNode]] = None,
coordinator_agent: Optional[ChatAgent] = None,
task_agent: Optional[ChatAgent] = None,
new_worker_agent: Optional[ChatAgent] = None,
default_model: Optional[Union[BaseModelBackend, ModelManager]] = None,
graceful_shutdown_timeout: float = 15.0,
share_memory: bool = False,
use_structured_output_handler: bool = True,
task_timeout_seconds: Optional[float] = None,
mode: WorkforceMode = WorkforceMode.AUTO_DECOMPOSE,
callbacks: Optional[List[WorkforceCallback]] = None,
failure_handling_config: Optional[Union[FailureHandlingConfig, Dict[str, Any]]] = None
):
```
### \_initialize\_callbacks
```python theme={"system"}
def _initialize_callbacks(self, callbacks: Optional[List[WorkforceCallback]]):
```
Validate, register, and prime workforce callbacks.
### \_notify\_worker\_created
```python theme={"system"}
def _notify_worker_created(self, worker_node: BaseNode):
```
Emit a worker-created event to all registered callbacks.
### \_get\_or\_create\_shared\_context\_utility
```python theme={"system"}
def _get_or_create_shared_context_utility(self, session_id: Optional[str] = None):
```
Get or create the shared context utility for workflow management.
This method creates the context utility only when needed, avoiding
unnecessary session folder creation during initialization.
**Parameters:**
* **session\_id** (Optional\[str]): Custom session ID to use. If None, auto-generates a timestamped session ID. (default: :obj:`None`)
**Returns:**
ContextUtility: The shared context utility instance.
### \_get\_role\_identifier
```python theme={"system"}
def _get_role_identifier(
self,
worker: ChatAgent,
description: str,
workflow_summary: Optional['WorkflowSummary'] = None
):
```
Extract role identifier for organizing workflows.
Uses priority fallback: role\_name → agent\_title (from
WorkflowSummary) → sanitized description.
**Parameters:**
* **worker** (ChatAgent): The worker agent to extract role from.
* **description** (str): Worker description to use as fallback.
* **workflow\_summary** (Optional\[WorkflowSummary]): Optional WorkflowSummary object that may contain agent\_title field.
**Returns:**
str: Role identifier for organizing workflows.
### \_validate\_agent\_compatibility
```python theme={"system"}
def _validate_agent_compatibility(self, agent: ChatAgent, agent_context: str = 'agent'):
```
Validate that agent configuration is compatible with workforce
settings.
**Parameters:**
* **agent** (ChatAgent): The agent to validate.
* **agent\_context** (str): Context description for error messages.
### \_attach\_pause\_event\_to\_agent
```python theme={"system"}
def _attach_pause_event_to_agent(self, agent: ChatAgent):
```
Ensure the given ChatAgent shares this workforce's pause\_event.
If the agent already has a different pause\_event we overwrite it and
emit a debug log (it is unlikely an agent needs multiple independent
pause controls once managed by this workforce).
### \_ensure\_pause\_event\_in\_kwargs
```python theme={"system"}
def _ensure_pause_event_in_kwargs(self, kwargs: Optional[Dict]):
```
Insert pause\_event into kwargs dict for ChatAgent construction.
### **repr**
```python theme={"system"}
def __repr__(self):
```
### set\_mode
```python theme={"system"}
def set_mode(self, mode: WorkforceMode):
```
Set the execution mode of the workforce.
This allows switching between AUTO\_DECOMPOSE and PIPELINE modes.
Useful when you want to reuse the same workforce instance for
different task processing strategies.
**Parameters:**
* **mode** (WorkforceMode): The desired execution mode. - AUTO\_DECOMPOSE: Intelligent task decomposition with recovery - PIPELINE: Predefined task pipeline with simple retry logic
**Returns:**
Workforce: Self for method chaining.
### \_ensure\_pipeline\_builder
```python theme={"system"}
def _ensure_pipeline_builder(self):
```
**Returns:**
PipelineTaskBuilder: The initialized pipeline builder instance.
### pipeline\_add
```python theme={"system"}
def pipeline_add(
self,
content: Union[str, Task],
task_id: Optional[str] = None,
dependencies: Optional[List[str]] = None,
additional_info: Optional[Dict[str, Any]] = None,
auto_depend: bool = True
):
```
Add a task to the pipeline with support for chaining.
Accepts either a string for simple tasks or a Task object for
advanced usage with metadata, images, or custom configurations.
**Parameters:**
* **content** (Union\[str, Task]): The task content string or a Task object. If a Task object is provided, task\_id and additional\_info parameters are ignored.
* **task\_id** (str, optional): Unique identifier for the task. If None, a unique ID will be generated. Only used when content is a string. (default: :obj:`None`)
* **dependencies** (List\[str], optional): List of task IDs that this task depends on. If None and auto\_depend=True, will depend on the last added task. (default: :obj:`None`)
* **additional\_info** (Dict\[str, Any], optional): Additional information for the task. Only used when content is a string. (default: :obj:`None`)
* **auto\_depend** (bool, optional): If True and dependencies is None, automatically depend on the last added task. (default: :obj:`True`)
**Returns:**
Workforce: Self for method chaining.
### add\_parallel\_pipeline\_tasks
```python theme={"system"}
def add_parallel_pipeline_tasks(
self,
task_contents: Union[List[str], List[Task]],
dependencies: Optional[List[str]] = None,
task_id_prefix: str = 'parallel',
auto_depend: bool = True
):
```
Add multiple parallel tasks to the pipeline.
Accepts either a list of strings for simple tasks or a list of Task
objects for advanced usage with metadata, images, or custom
configurations.
**Parameters:**
* **task\_contents** (Union\[List\[str], List\[Task]]): List of task content strings or Task objects. If Task objects are provided, task\_id\_prefix is ignored.
* **dependencies** (List\[str], optional): Common dependencies for all parallel tasks. (default: :obj:`None`)
* **task\_id\_prefix** (str, optional): Prefix for generated task IDs. Only used when task\_contents contains strings. (default: :obj:`"parallel"`)
* **auto\_depend** (bool, optional): If True and dependencies is None, automatically depend on the last added task. (default: :obj:`True`)
**Returns:**
Workforce: Self for method chaining.
### add\_sync\_pipeline\_task
```python theme={"system"}
def add_sync_pipeline_task(
self,
content: Union[str, Task],
wait_for: Optional[List[str]] = None,
task_id: Optional[str] = None
):
```
Add a synchronization task that waits for multiple tasks.
Accepts either a string for simple tasks or a Task object for
advanced usage with metadata, images, or custom configurations.
**Parameters:**
* **content** (Union\[str, Task]): Content of the synchronization task or a Task object. If a Task object is provided, task\_id parameter is ignored.
* **wait\_for** (List\[str], optional): List of task IDs to wait for. If None, will automatically wait for the last parallel tasks. (default: :obj:`None`)
* **task\_id** (str, optional): ID for the sync task. Only used when content is a string. (default: :obj:`None`)
**Returns:**
Workforce: Self for method chaining.
### pipeline\_fork
```python theme={"system"}
def pipeline_fork(self, task_contents: Union[List[str], List[Task]]):
```
Create parallel branches from the current task.
Accepts either a list of strings for simple tasks or a list of Task
objects for advanced usage with metadata, images, or custom
configurations.
**Parameters:**
* **task\_contents** (Union\[List\[str], List\[Task]]): List of task content strings or Task objects for parallel execution.
**Returns:**
Workforce: Self for method chaining.
### pipeline\_join
```python theme={"system"}
def pipeline_join(self, content: Union[str, Task], task_id: Optional[str] = None):
```
Join parallel branches with a synchronization task.
Accepts either a string for simple tasks or a Task object for
advanced usage with metadata, images, or custom configurations.
**Parameters:**
* **content** (Union\[str, Task]): Content of the join/sync task or a Task object. If a Task object is provided, task\_id parameter is ignored.
* **task\_id** (str, optional): ID for the sync task. Only used when content is a string. (default: :obj:`None`)
**Returns:**
Workforce: Self for method chaining.
### pipeline\_build
```python theme={"system"}
def pipeline_build(self):
```
**Returns:**
Workforce: Self for method chaining.
### get\_pipeline\_builder
```python theme={"system"}
def get_pipeline_builder(self):
```
**Returns:**
PipelineTaskBuilder: The pipeline builder instance.
### set\_pipeline\_tasks
```python theme={"system"}
def set_pipeline_tasks(self, tasks: List[Task]):
```
Set predefined pipeline tasks for PIPELINE mode.
**Parameters:**
* **tasks** (List\[Task]): List of tasks with dependencies already set. The dependencies should be Task objects in the Task.dependencies attribute.
### \_collect\_shared\_memory
```python theme={"system"}
def _collect_shared_memory(self):
```
**Returns:**
Dict\[str, List]: A dictionary mapping agent types to their memory
records. Contains entries for 'coordinator', 'task\_agent',
and 'workers'.
### \_share\_memory\_with\_agents
```python theme={"system"}
def _share_memory_with_agents(self, shared_memory: Dict[str, List]):
```
Share collected memory with coordinator, task agent, and
SingleAgentWorker instances.
**Parameters:**
* **shared\_memory** (Dict\[str, List]): Memory records collected from all agents to be shared.
### \_sync\_shared\_memory
```python theme={"system"}
def _sync_shared_memory(self):
```
Synchronize memory across all agents by collecting and sharing.
### \_update\_dependencies\_for\_decomposition
```python theme={"system"}
def _update_dependencies_for_decomposition(self, original_task: Task, subtasks: List[Task]):
```
Update dependency tracking when a task is decomposed into subtasks.
Tasks that depended on the original task should now depend on all
subtasks. The last subtask inherits the original task's dependencies.
### \_increment\_in\_flight\_tasks
```python theme={"system"}
def _increment_in_flight_tasks(self, task_id: str):
```
Safely increment the in-flight tasks counter with logging.
### \_decrement\_in\_flight\_tasks
```python theme={"system"}
def _decrement_in_flight_tasks(self, task_id: str, context: str = ''):
```
Safely decrement the in-flight tasks counter with safety checks.
### \_cleanup\_task\_tracking
```python theme={"system"}
def _cleanup_task_tracking(self, task_id: str):
```
Clean up tracking data for a task to prevent memory leaks.
**Parameters:**
* **task\_id** (str): The ID of the task to clean up.
### \_decompose\_task
```python theme={"system"}
def _decompose_task(
self,
task: Task,
stream_callback: Optional[Callable[['ChatAgentResponse'], None]] = None
):
```
Decompose the task into subtasks. This method will also set the
relationship between the task and its subtasks.
**Parameters:**
* **task** (Task): The task to decompose.
* **stream\_callback** (Callable\[\[ChatAgentResponse], None], optional): A callback function that receives each chunk (ChatAgentResponse) during streaming decomposition.
**Returns:**
Union\[List\[Task], Generator\[List\[Task], None, None]]:
The subtasks or generator of subtasks. Returns empty list for
PIPELINE mode.
### \_get\_available\_strategies\_text
```python theme={"system"}
def _get_available_strategies_text(self):
```
**Returns:**
str: Formatted text describing available strategies for the prompt.
### \_analyze\_task
```python theme={"system"}
def _analyze_task(self, task: Task):
```
Unified task analysis for both failures and quality evaluation.
This method consolidates the logic for analyzing task failures and
evaluating task quality, using the unified TASK\_ANALYSIS\_PROMPT.
**Parameters:**
* **task** (Task): The task to analyze
* **for\_failure** (bool): True for failure analysis, False for quality evaluation
* **error\_message** (Optional\[str]): Error message, required when for\_failure=True
**Returns:**
TaskAnalysisResult: Unified analysis result with recovery strategy
and optional quality metrics
### pause
```python theme={"system"}
def pause(self):
```
Pause the workforce execution.
If the internal event-loop is already running we schedule the
asynchronous pause coroutine onto it. When the loop has not yet
been created (e.g. the caller presses the hot-key immediately after
workforce start-up) we fall back to a synchronous state change so
that no tasks will be scheduled until the loop is ready.
### resume
```python theme={"system"}
def resume(self):
```
Resume execution after a manual pause.
### stop\_gracefully
```python theme={"system"}
def stop_gracefully(self):
```
Request workforce to finish current in-flight work then halt.
Works both when the internal event-loop is alive and when it has not
yet been started. In the latter case we simply mark the stop flag so
that the loop (when it eventually starts) will exit immediately after
initialisation.
### stop\_immediately
```python theme={"system"}
def stop_immediately(self):
```
Force-stop without waiting for current tasks to finish.
**Note:**
Child nodes will receive stop signals but may still be cleaning up
when this method returns.
### skip\_gracefully
```python theme={"system"}
def skip_gracefully(self):
```
Request workforce to skip current pending tasks and move to next
main task from the queue. If no main tasks exist, acts like
stop\_gracefully.
This method clears the current pending subtasks and moves to the next
main task in the queue if available. Works both when the internal
event-loop is alive and when it has not yet been started.
### save\_snapshot
```python theme={"system"}
def save_snapshot(self, description: str = ''):
```
Save current state as a snapshot.
### list\_snapshots
```python theme={"system"}
def list_snapshots(self):
```
List all available snapshots.
### get\_pending\_tasks
```python theme={"system"}
def get_pending_tasks(self):
```
Get current pending tasks for human review.
### get\_completed\_tasks
```python theme={"system"}
def get_completed_tasks(self):
```
Get completed tasks.
### modify\_task\_content
```python theme={"system"}
def modify_task_content(self, task_id: str, new_content: str):
```
Modify the content of a pending task.
### get\_main\_task\_queue
```python theme={"system"}
def get_main_task_queue(self):
```
**Returns:**
List\[Task]: List of main tasks waiting to be decomposed
and executed.
### add\_task
```python theme={"system"}
def add_task(
self,
content: str,
task_id: Optional[str] = None,
additional_info: Optional[Dict[str, Any]] = None,
as_subtask: bool = False,
insert_position: int = -1
):
```
Add a new task to the workforce.
By default, this method adds a main task that will be decomposed into
subtasks. Set `as_subtask=True` to add a task directly to the pending
subtask queue without decomposition.
**Parameters:**
* **content** (str): The content of the task.
* **task\_id** (Optional\[str], optional): Optional ID for the task. If not provided, a unique ID will be generated.
* **additional\_info** (Optional\[Dict\[str, Any]], optional): Optional additional metadata for the task.
* **as\_subtask** (bool, optional): If True, adds the task directly to the pending subtask queue. If False, adds as a main task that will be decomposed. Defaults to False.
* **insert\_position** (int, optional): Position to insert the task in the pending queue. Only applies when as\_subtask=True. Defaults to -1 (append to end).
**Returns:**
Task: The created task object.
### add\_main\_task
```python theme={"system"}
def add_main_task(
self,
content: str,
task_id: Optional[str] = None,
additional_info: Optional[Dict[str, Any]] = None
):
```
Add a new main task that will be decomposed into subtasks.
This is an alias for :meth:`add_task` with `as_subtask=False`.
**Parameters:**
* **content** (str): The content of the main task.
* **task\_id** (Optional\[str], optional): Optional ID for the task.
* **additional\_info** (Optional\[Dict\[str, Any]], optional): Optional additional metadata.
**Returns:**
Task: The created main task object.
### add\_subtask
```python theme={"system"}
def add_subtask(
self,
content: str,
task_id: Optional[str] = None,
additional_info: Optional[Dict[str, Any]] = None,
insert_position: int = -1
):
```
Add a new subtask to the current pending queue.
This is an alias for :meth:`add_task` with `as_subtask=True`.
**Parameters:**
* **content** (str): The content of the subtask.
* **task\_id** (Optional\[str], optional): Optional ID for the task.
* **additional\_info** (Optional\[Dict\[str, Any]], optional): Optional additional metadata.
* **insert\_position** (int, optional): Position to insert the task. Defaults to -1 (append to end).
**Returns:**
Task: The created subtask object.
### remove\_task
```python theme={"system"}
def remove_task(self, task_id: str):
```
Remove a task from the pending queue or main task queue.
**Parameters:**
* **task\_id** (str): The ID of the task to remove.
**Returns:**
bool: True if task was found and removed, False otherwise.
### reorder\_tasks
```python theme={"system"}
def reorder_tasks(self, task_ids: List[str]):
```
Reorder pending tasks according to the provided task IDs list.
### resume\_from\_task
```python theme={"system"}
def resume_from_task(self, task_id: str):
```
Resume execution from a specific task.
### restore\_from\_snapshot
```python theme={"system"}
def restore_from_snapshot(self, snapshot_index: int):
```
Restore workforce state from a snapshot.
### get\_workforce\_status
```python theme={"system"}
def get_workforce_status(self):
```
Get current workforce status for human review.
### \_collect\_pipeline\_results
```python theme={"system"}
def _collect_pipeline_results(self):
```
Collect results from all completed pipeline tasks.
### \_all\_pipeline\_tasks\_successful
```python theme={"system"}
def _all_pipeline_tasks_successful(self):
```
**Returns:**
bool: True if all tasks completed successfully (DONE state),
False if any tasks failed or are still pending.
### process\_task
```python theme={"system"}
def process_task(self, task: Task):
```
Synchronous wrapper for process\_task that handles async operations
internally.
**Parameters:**
* **task** (Task): The task to be processed.
**Returns:**
Task: The updated task.
### \_process\_task\_with\_intervention
```python theme={"system"}
def _process_task_with_intervention(self, task: Task):
```
Process task with human intervention support. This creates and
manages its own event loop to allow for pausing/resuming functionality.
**Parameters:**
* **task** (Task): The task to be processed.
**Returns:**
Task: The updated task.
### continue\_from\_pause
```python theme={"system"}
def continue_from_pause(self):
```
**Returns:**
Optional\[Task]: The completed task if execution finishes, None if
still running/paused.
### \_start\_child\_node\_when\_paused
```python theme={"system"}
def _start_child_node_when_paused(self, start_coroutine: Coroutine):
```
Helper to start a child node when workforce is paused.
**Parameters:**
* **start\_coroutine**: The coroutine to start (e.g., worker\_node.start())
### add\_single\_agent\_worker
```python theme={"system"}
def add_single_agent_worker(
self,
description: str,
worker: ChatAgent,
pool_max_size: int = DEFAULT_WORKER_POOL_SIZE,
enable_workflow_memory: bool = False
):
```
Add a worker node to the workforce that uses a single agent.
Can be called when workforce is paused to dynamically add workers.
**Parameters:**
* **description** (str): Description of the worker node.
* **worker** (ChatAgent): The agent to be added.
* **pool\_max\_size** (int): Maximum size of the agent pool. (default: :obj:`10`)
* **enable\_workflow\_memory** (bool): Whether to enable workflow memory accumulation. Set to True if you plan to call save\_workflow\_memories(). (default: :obj:`False`)
**Returns:**
Workforce: The workforce node itself.
### add\_role\_playing\_worker
```python theme={"system"}
def add_role_playing_worker(
self,
description: str,
assistant_role_name: str,
user_role_name: str,
assistant_agent_kwargs: Optional[Dict] = None,
user_agent_kwargs: Optional[Dict] = None,
summarize_agent_kwargs: Optional[Dict] = None,
chat_turn_limit: int = 3
):
```
Add a worker node to the workforce that uses `RolePlaying` system.
Can be called when workforce is paused to dynamically add workers.
**Parameters:**
* **description** (str): Description of the node.
* **assistant\_role\_name** (str): The role name of the assistant agent.
* **user\_role\_name** (str): The role name of the user agent.
* **assistant\_agent\_kwargs** (Optional\[Dict]): The keyword arguments to initialize the assistant agent in the role playing, like the model name, etc. (default: :obj:`None`)
* **user\_agent\_kwargs** (Optional\[Dict]): The keyword arguments to initialize the user agent in the role playing, like the model name, etc. (default: :obj:`None`)
* **summarize\_agent\_kwargs** (Optional\[Dict]): The keyword arguments to initialize the summarize agent, like the model name, etc. (default: :obj:`None`)
* **chat\_turn\_limit** (int): The maximum number of chat turns in the role playing. (default: :obj:`3`)
**Returns:**
Workforce: The workforce node itself.
### add\_workforce
```python theme={"system"}
def add_workforce(self, workforce: Workforce):
```
Add a workforce node to the workforce.
Can be called when workforce is paused to dynamically add workers.
**Parameters:**
* **workforce** (Workforce): The workforce node to be added.
**Returns:**
Workforce: The workforce node itself.
### reset
```python theme={"system"}
def reset(self):
```
Reset the workforce and all the child nodes under it. Can only
be called when the workforce is not running.
### save\_workflow\_memories
```python theme={"system"}
def save_workflow_memories(self):
```
**Returns:**
Dict\[str, str]: Dictionary mapping worker node IDs to save results.
Values are either file paths (success) or error messages
(failure).
**Note:**
For better performance with multiple workers, use the async
version::
results = await workforce.save\_workflow\_memories\_async()
See Also:
:meth:`save_workflow_memories_async`: Async version with parallel
processing for significantly better performance.
### load\_workflow\_memories
```python theme={"system"}
def load_workflow_memories(
self,
session_id: Optional[str] = None,
worker_max_workflows: int = 3,
coordinator_max_workflows: int = 5,
task_agent_max_workflows: int = 3
):
```
Load workflow memories for all SingleAgentWorker instances in the
workforce.
This method iterates through all child workers and loads relevant
workflow files for SingleAgentWorker instances using their
load\_workflow\_memories()
method. Workers match files based on their description names.
**Parameters:**
* **session\_id** (Optional\[str]): Specific workforce session ID to load from. If None, searches across all sessions. (default: :obj:`None`)
* **worker\_max\_workflows** (int): Maximum number of workflow files to load per worker agent. (default: :obj:`3`)
* **coordinator\_max\_workflows** (int): Maximum number of workflow files to load for the coordinator agent. (default: :obj:`5`)
* **task\_agent\_max\_workflows** (int): Maximum number of workflow files to load for the task planning agent. (default: :obj:`3`)
**Returns:**
Dict\[str, bool]: Dictionary mapping worker node IDs to load
success status.
True indicates successful loading, False indicates failure.
### \_load\_management\_agent\_workflows
```python theme={"system"}
def _load_management_agent_workflows(
self,
coordinator_max_workflows: int,
task_agent_max_workflows: int,
session_id: Optional[str] = None
):
```
Load workflow summaries for coordinator and task planning agents.
This method loads aggregated workflow summaries to help:
* Coordinator agent: understand task assignment patterns and worker
capabilities
* Task agent: understand task decomposition patterns and
successful strategies
**Parameters:**
* **coordinator\_max\_workflows** (int): Maximum number of workflow files to load for the coordinator agent.
* **task\_agent\_max\_workflows** (int): Maximum number of workflow files to load for the task planning agent.
* **session\_id** (Optional\[str]): Specific session ID to load from. If None, searches across all sessions.
### set\_channel
```python theme={"system"}
def set_channel(self, channel: TaskChannel):
```
Set the channel for the node and all the child nodes under it.
### \_get\_child\_nodes\_info
```python theme={"system"}
def _get_child_nodes_info(self):
```
Get the information of all the child nodes under this node.
### \_get\_node\_info
```python theme={"system"}
def _get_node_info(self, node):
```
Get descriptive information for a specific node type.
### \_get\_single\_agent\_toolkit\_info
```python theme={"system"}
def _get_single_agent_toolkit_info(self, worker: 'SingleAgentWorker'):
```
Get formatted information for a SingleAgentWorker node.
### \_group\_tools\_by\_toolkit
```python theme={"system"}
def _group_tools_by_toolkit(self, tool_dict: dict):
```
Group tools by their parent toolkit class names.
### \_get\_valid\_worker\_ids
```python theme={"system"}
def _get_valid_worker_ids(self):
```
**Returns:**
set: Set of valid worker IDs that can be assigned tasks.
### \_call\_coordinator\_for\_assignment
```python theme={"system"}
def _call_coordinator_for_assignment(self, tasks: List[Task], invalid_ids: Optional[List[str]] = None):
```
Call coordinator agent to assign tasks with optional validation
feedback in the case of invalid worker IDs.
**Parameters:**
* **tasks** (List\[Task]): Tasks to assign.
* **invalid\_ids** (List\[str], optional): Invalid worker IDs from previous attempt (if any).
**Returns:**
TaskAssignResult: Assignment result from coordinator.
### \_validate\_assignments
```python theme={"system"}
def _validate_assignments(self, assignments: List[TaskAssignment], valid_ids: Set[str]):
```
Validate task assignments against valid worker IDs.
**Parameters:**
* **assignments** (List\[TaskAssignment]): Assignments to validate.
* **valid\_ids** (Set\[str]): Set of valid worker IDs.
**Returns:**
Tuple\[List\[TaskAssignment], List\[TaskAssignment]]:
(valid\_assignments, invalid\_assignments)
### \_update\_task\_dependencies\_from\_assignments
```python theme={"system"}
def _update_task_dependencies_from_assignments(self, assignments: List[TaskAssignment], tasks: List[Task]):
```
Update Task.dependencies with actual Task objects based on
assignments.
**Parameters:**
* **assignments** (List\[TaskAssignment]): The task assignments containing dependency IDs.
* **tasks** (List\[Task]): The tasks that were assigned.
### get\_workforce\_log\_tree
```python theme={"system"}
def get_workforce_log_tree(self):
```
Returns an ASCII tree representation of the task hierarchy and
worker status.
### get\_workforce\_kpis
```python theme={"system"}
def get_workforce_kpis(self):
```
Returns a dictionary of key performance indicators.
### dump\_workforce\_logs
```python theme={"system"}
def dump_workforce_logs(self, file_path: str):
```
Dumps all collected logs to a JSON file.
**Parameters:**
* **file\_path** (str): The path to the JSON file.
### \_submit\_coro\_to\_loop
```python theme={"system"}
def _submit_coro_to_loop(self, coro: 'Coroutine'):
```
Thread-safe submission of coroutine to the workforce loop.
### stop
```python theme={"system"}
def stop(self):
```
Forcefully stop the workforce and its children immediately.
This is now an immediate stop (was previously a graceful lifecycle
cleanup). It cancels child listeners, clears pending/in-flight tasks,
and sets state to STOPPED without waiting for active work to finish.
### clone
```python theme={"system"}
def clone(self, with_memory: bool = False):
```
Creates a new instance of Workforce with the same configuration.
**Parameters:**
* **with\_memory** (bool, optional): Whether to copy the memory (conversation history) to the new instance. If True, the new instance will have the same conversation history. If False, the new instance will have a fresh memory. (default: :obj:`False`)
**Returns:**
Workforce: A new instance of Workforce with the same configuration.
### to\_mcp
```python theme={"system"}
def to_mcp(
self,
name: str = 'CAMEL-Workforce',
description: str = 'A workforce system using the CAMEL AI framework for multi-agent collaboration.',
dependencies: Optional[List[str]] = None,
host: str = 'localhost',
port: int = 8001
):
```
Expose this Workforce as an MCP server.
**Parameters:**
* **name** (str): Name of the MCP server. (default: :obj:`CAMEL-Workforce`)
* **description** (str): Description of the workforce. If None, a generic description is used. (default: :obj:`A workforce system using the CAMEL AI framework for multi-agent collaboration.`)
* **dependencies** (Optional\[List\[str]]): Additional dependencies for the MCP server. (default: :obj:`None`)
* **host** (str): Host to bind to for HTTP transport. (default: :obj:`localhost`)
* **port** (int): Port to bind to for HTTP transport. (default: :obj:`8001`)
**Returns:**
FastMCP: An MCP server instance that can be run.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.workforce_callback
## WorkforceCallback
```python theme={"system"}
class WorkforceCallback(ABC):
```
Interface for recording workforce lifecycle events.
Implementations should persist or stream events as appropriate.
### \_get\_color\_message
```python theme={"system"}
def _get_color_message(self, event: LogEvent):
```
Gets a colored message for a log event.
### log\_message
```python theme={"system"}
def log_message(self, event: LogEvent):
```
### log\_task\_created
```python theme={"system"}
def log_task_created(self, event: TaskCreatedEvent):
```
### log\_task\_decomposed
```python theme={"system"}
def log_task_decomposed(self, event: TaskDecomposedEvent):
```
### log\_task\_assigned
```python theme={"system"}
def log_task_assigned(self, event: TaskAssignedEvent):
```
### log\_task\_started
```python theme={"system"}
def log_task_started(self, event: TaskStartedEvent):
```
### log\_task\_updated
```python theme={"system"}
def log_task_updated(self, event: TaskUpdatedEvent):
```
### log\_task\_completed
```python theme={"system"}
def log_task_completed(self, event: TaskCompletedEvent):
```
### log\_task\_failed
```python theme={"system"}
def log_task_failed(self, event: TaskFailedEvent):
```
### log\_worker\_created
```python theme={"system"}
def log_worker_created(self, event: WorkerCreatedEvent):
```
### log\_worker\_deleted
```python theme={"system"}
def log_worker_deleted(self, event: WorkerDeletedEvent):
```
### log\_all\_tasks\_completed
```python theme={"system"}
def log_all_tasks_completed(self, event: AllTasksCompletedEvent):
```
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.workforce_logger
## WorkforceLogger
```python theme={"system"}
class WorkforceLogger(WorkforceCallback, WorkforceMetrics):
```
Logs events and metrics for a Workforce instance.
### **init**
```python theme={"system"}
def __init__(self, workforce_id: str):
```
Initializes the WorkforceLogger.
**Parameters:**
* **workforce\_id** (str): The unique identifier for the workforce.
### log\_message
```python theme={"system"}
def log_message(self, event: LogEvent):
```
Logs a message to the console with color.
### \_log\_event
```python theme={"system"}
def _log_event(self, event_type: str, **kwargs: Any):
```
Internal method to create and store a log entry.
**Parameters:**
* **event\_type** (str): The type of event being logged. \*\*kwargs: Additional data associated with the event.
### log\_task\_created
```python theme={"system"}
def log_task_created(self, event: TaskCreatedEvent):
```
Logs the creation of a new task.
### log\_task\_decomposed
```python theme={"system"}
def log_task_decomposed(self, event: TaskDecomposedEvent):
```
Logs the decomposition of a task into subtasks.
### log\_task\_assigned
```python theme={"system"}
def log_task_assigned(self, event: TaskAssignedEvent):
```
Logs the assignment of a task to a worker.
### log\_task\_started
```python theme={"system"}
def log_task_started(self, event: TaskStartedEvent):
```
Logs when a worker starts processing a task.
### log\_task\_updated
```python theme={"system"}
def log_task_updated(self, event: TaskUpdatedEvent):
```
Logs updates made to a task.
### log\_task\_completed
```python theme={"system"}
def log_task_completed(self, event: TaskCompletedEvent):
```
Logs the successful completion of a task.
### log\_task\_failed
```python theme={"system"}
def log_task_failed(self, event: TaskFailedEvent):
```
Logs the failure of a task.
### log\_worker\_created
```python theme={"system"}
def log_worker_created(self, event: WorkerCreatedEvent):
```
Logs the creation of a new worker.
### log\_worker\_deleted
```python theme={"system"}
def log_worker_deleted(self, event: WorkerDeletedEvent):
```
Logs the deletion of a worker.
### log\_queue\_status
```python theme={"system"}
def log_queue_status(self, event: QueueStatusEvent):
```
Logs the status of a task queue.
### log\_all\_tasks\_completed
```python theme={"system"}
def log_all_tasks_completed(self, event: AllTasksCompletedEvent):
```
### reset\_task\_data
```python theme={"system"}
def reset_task_data(self):
```
Resets logs and data related to tasks, preserving worker
information.
### dump\_to\_json
```python theme={"system"}
def dump_to_json(self, file_path: str):
```
Dumps all log entries to a JSON file.
**Parameters:**
* **file\_path** (str): The path to the JSON file.
### \_get\_all\_tasks\_in\_hierarchy
```python theme={"system"}
def _get_all_tasks_in_hierarchy(self, task_id: str):
```
Recursively collect all tasks in the hierarchy starting from
task\_id.
### \_get\_task\_tree\_string
```python theme={"system"}
def _get_task_tree_string(
self,
task_id: str,
prefix: str = '',
is_last: bool = True
):
```
Generate a string representation of the task tree.
### get\_ascii\_tree\_representation
```python theme={"system"}
def get_ascii_tree_representation(self):
```
Generates an ASCII tree representation of the current task
hierarchy and worker status.
### get\_kpis
```python theme={"system"}
def get_kpis(self):
```
Calculates and returns key performance indicators from the logs.
# null
Source: https://docs.camel-ai.org/reference/camel.societies.workforce.workforce_metrics
## WorkforceMetrics
```python theme={"system"}
class WorkforceMetrics(ABC):
```
### reset\_task\_data
```python theme={"system"}
def reset_task_data(self):
```
### dump\_to\_json
```python theme={"system"}
def dump_to_json(self, file_path: str):
```
### get\_ascii\_tree\_representation
```python theme={"system"}
def get_ascii_tree_representation(self):
```
### get\_kpis
```python theme={"system"}
def get_kpis(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.storages.graph_storages.base
## BaseGraphStorage
```python theme={"system"}
class BaseGraphStorage(ABC):
```
An abstract base class for graph storage systems.
### get\_client
```python theme={"system"}
def get_client(self):
```
Get the underlying graph storage client.
### get\_schema
```python theme={"system"}
def get_schema(self):
```
Get the schema of the graph storage
### get\_structured\_schema
```python theme={"system"}
def get_structured_schema(self):
```
Get the structured schema of the graph storage
### refresh\_schema
```python theme={"system"}
def refresh_schema(self):
```
Refreshes the graph schema information.
### add\_triplet
```python theme={"system"}
def add_triplet(
self,
subj: str,
obj: str,
rel: str
):
```
Adds a relationship (triplet) between two entities in the database.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object.
### delete\_triplet
```python theme={"system"}
def delete_triplet(
self,
subj: str,
obj: str,
rel: str
):
```
Deletes a specific triplet from the graph, comprising a subject,
object and relationship.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object.
### query
```python theme={"system"}
def query(self, query: str, params: Optional[Dict[str, Any]] = None):
```
Query the graph store with statement and parameters.
**Parameters:**
* **query** (str): The query to be executed.
* **params** (Optional\[Dict\[str, Any]]): A dictionary of parameters to be used in the query. Defaults to `None`.
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, each
dictionary represents a row of results from the query.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.graph_storages.graph_element
## Node
```python theme={"system"}
class Node(BaseModel):
```
Represents a node in a graph with associated properties.
**Parameters:**
* **id** (Union\[str, int]): A unique identifier for the node.
* **type** (str): The type of the relationship.
* **properties** (dict): Additional properties and metadata associated with the node.
## Relationship
```python theme={"system"}
class Relationship(BaseModel):
```
Represents a directed relationship between two nodes in a graph.
**Parameters:**
* **subj** (Node): The subject/source node of the relationship.
* **obj** (Node): The object/target node of the relationship.
* **type** (str): The type of the relationship.
* **timestamp** (str, optional): The timestamp of the relationship.
* **properties** (dict): Additional properties associated with the relationship.
## GraphElement
```python theme={"system"}
class GraphElement(BaseModel):
```
A graph element with lists of nodes and relationships.
**Parameters:**
* **nodes** (List\[Node]): A list of nodes in the graph.
* **relationships** (List\[Relationship]): A list of relationships in the graph.
* **source** (Element): The element from which the graph information is derived.
### **post\_init**
```python theme={"system"}
def __post_init__(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.storages.graph_storages.nebula_graph
## NebulaGraph
```python theme={"system"}
class NebulaGraph(BaseGraphStorage):
```
### **init**
```python theme={"system"}
def __init__(
self,
host,
username,
password,
space,
port = 9669,
timeout = 10000
):
```
Initializes the NebulaGraph client.
**Parameters:**
* **host** (str): The host address of the NebulaGraph service.
* **username** (str): The username for authentication.
* **password** (str): The password for authentication.
* **space** (str): The graph space to use. If it doesn't exist, a new one will be created.
* **port** (int, optional): The port number for the connection. (default: :obj:`9669`)
* **timeout** (int, optional): The connection timeout in milliseconds. (default: :obj:`10000`)
### \_init\_connection\_pool
```python theme={"system"}
def _init_connection_pool(self):
```
**Returns:**
ConnectionPool: A connection pool instance.
### \_get\_session
```python theme={"system"}
def _get_session(self):
```
**Returns:**
Session: A session object connected to NebulaGraph.
### get\_client
```python theme={"system"}
def get_client(self):
```
Get the underlying graph storage client.
### query
```python theme={"system"}
def query(self, query: str):
```
Execute a query on the graph store.
**Parameters:**
* **query** (str): The Cypher-like query to be executed.
**Returns:**
ResultSet: The result set of the query execution.
### get\_relationship\_types
```python theme={"system"}
def get_relationship_types(self):
```
**Returns:**
List\[str]: A list of relationship (edge) type names.
### add\_graph\_elements
```python theme={"system"}
def add_graph_elements(self, graph_elements: List[GraphElement]):
```
Add graph elements (nodes and relationships) to the graph.
**Parameters:**
* **graph\_elements** (List\[GraphElement]): A list of graph elements containing nodes and relationships.
### ensure\_edge\_type\_exists
```python theme={"system"}
def ensure_edge_type_exists(self, edge_type: str, time_label: Optional[str] = None):
```
Ensures that a specified edge type exists in the NebulaGraph
database. If the edge type already exists, this method does nothing.
**Parameters:**
* **edge\_type** (str): The name of the edge type to be created.
* **time\_label** (str, optional): A specific timestamp to set as the default value for the time label property. If not provided, no timestamp will be added. (default: :obj:`None`)
### ensure\_tag\_exists
```python theme={"system"}
def ensure_tag_exists(self, tag_name: str, time_label: Optional[str] = None):
```
Ensures a tag is created in the NebulaGraph database. If the tag
already exists, it does nothing.
**Parameters:**
* **tag\_name** (str): The name of the tag to be created.
* **time\_label** (str, optional): A specific timestamp to set as the default value for the time label property. If not provided, no timestamp will be added. (default: :obj:`None`)
### add\_node
```python theme={"system"}
def add_node(
self,
node_id: str,
tag_name: str,
time_label: Optional[str] = None
):
```
Add a node with the specified tag and properties.
**Parameters:**
* **node\_id** (str): The ID of the node.
* **tag\_name** (str): The tag name of the node.
* **time\_label** (str, optional): A specific timestamp to set for the node's time label property. If not provided, no timestamp will be added. (default: :obj:`None`)
### \_extract\_nodes
```python theme={"system"}
def _extract_nodes(self, graph_elements: List[Any]):
```
Extracts unique nodes from graph elements.
**Parameters:**
* **graph\_elements** (List\[Any]): A list of graph elements containing nodes.
**Returns:**
List\[Dict]: A list of dictionaries representing nodes.
### \_extract\_relationships
```python theme={"system"}
def _extract_relationships(self, graph_elements: List[Any]):
```
Extracts relationships from graph elements.
**Parameters:**
* **graph\_elements** (List\[Any]): A list of graph elements containing relationships.
**Returns:**
List\[Dict]: A list of dictionaries representing relationships.
### refresh\_schema
```python theme={"system"}
def refresh_schema(self):
```
Refreshes the schema by fetching the latest schema details.
### get\_structured\_schema
```python theme={"system"}
def get_structured_schema(self):
```
**Returns:**
Dict\[str, Any]: A dictionary representing the structured schema.
### get\_schema
```python theme={"system"}
def get_schema(self):
```
**Returns:**
str: A string describing the schema.
### get\_indexes
```python theme={"system"}
def get_indexes(self):
```
**Returns:**
List\[str]: A list of tag index names.
### add\_triplet
```python theme={"system"}
def add_triplet(
self,
subj: str,
obj: str,
rel: str,
time_label: Optional[str] = None
):
```
Adds a relationship (triplet) between two entities in the Nebula
Graph database.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object.
* **time\_label** (str, optional): A specific timestamp to set for the time label property of the relationship. If not provided, no timestamp will be added. (default: :obj:`None`)
### delete\_triplet
```python theme={"system"}
def delete_triplet(
self,
subj: str,
obj: str,
rel: str
):
```
Deletes a specific triplet (relationship between two entities)
from the Nebula Graph database.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object.
### delete\_entity
```python theme={"system"}
def delete_entity(self, entity_id: str):
```
Deletes an entity (vertex) from the graph.
**Parameters:**
* **entity\_id** (str): The identifier of the entity to be deleted.
### \_check\_edges
```python theme={"system"}
def _check_edges(self, entity_id: str):
```
Checks if an entity has any remaining edges in the graph.
**Parameters:**
* **entity\_id** (str): The identifier of the entity.
**Returns:**
bool: :obj:`True` if the entity has edges, :obj:`False` otherwise.
### get\_node\_properties
```python theme={"system"}
def get_node_properties(self):
```
**Returns:**
Tuple\[List\[str], List\[Dict\[str, Any]]]: A tuple where the first
element is a list of node schema properties, and the second
element is a list of dictionaries representing node structures.
### get\_relationship\_properties
```python theme={"system"}
def get_relationship_properties(self):
```
**Returns:**
Tuple\[List\[str], List\[Dict\[str, Any]]]: A tuple where the first
element is a list of relationship schema properties, and the
second element is a list of dictionaries representing
relationship structures.
### \_validate\_time\_label
```python theme={"system"}
def _validate_time_label(self, time_label: str):
```
Validates the format of a time label string.
**Parameters:**
* **time\_label** (str): The time label string to validate. Should be in format 'YYYY-MM-DDThh:mm:ss'.
**Returns:**
str: The validated time label.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.graph_storages.neo4j_graph
## Neo4jGraph
```python theme={"system"}
class Neo4jGraph(BaseGraphStorage):
```
Provides a connection to a Neo4j database for various graph operations.
The detailed information about Neo4j is available at:
`Neo4j https://neo4j.com/docs/getting-started`
This module referred to the work of Langchian and Llamaindex.
**Parameters:**
* **url** (str): The URL of the Neo4j database server.
* **username** (str): The username for database authentication.
* **password** (str): The password for database authentication.
* **database** (str): The name of the database to connect to. Defaults to `neo4j`.
* **timeout** (Optional\[float]): The timeout for transactions in seconds. Useful for terminating long-running queries. Defaults to `None`.
* **truncate** (bool): A flag to indicate whether to remove lists with more than `LIST_LIMIT` elements from results. Defaults to `False`.
### **init**
```python theme={"system"}
def __init__(
self,
url: str,
username: str,
password: str,
database: str = 'neo4j',
timeout: Optional[float] = None,
truncate: bool = False
):
```
Create a new Neo4j graph instance.
### get\_client
```python theme={"system"}
def get_client(self):
```
Get the underlying graph storage client.
### get\_schema
```python theme={"system"}
def get_schema(self, refresh: bool = False):
```
Retrieve the schema of the Neo4jGraph store.
**Parameters:**
* **refresh** (bool): A flag indicating whether to forcibly refresh the schema from the Neo4jGraph store regardless of whether it is already cached. Defaults to `False`.
**Returns:**
str: The schema of the Neo4jGraph store.
### get\_structured\_schema
```python theme={"system"}
def get_structured_schema(self):
```
**Returns:**
Dict\[str, Any]: The structured schema of the graph.
### \_value\_truncate
```python theme={"system"}
def _value_truncate(self, raw_value: Any):
```
Truncates the input raw value by removing entries that is
dictionary or list with values resembling embeddings and containing
more than `LIST_LIMIT` elements. This method aims to reduce unnecessary
computational cost and noise in scenarios where such detailed data
structures are not needed. If the input value is not dictionary or
list then give the raw value back.
**Parameters:**
* **raw\_value** (Any): The raw value to be truncated.
**Returns:**
Any: The truncated value, with embedding-like
dictionaries and oversized lists handled.
### query
```python theme={"system"}
def query(self, query: str, params: Optional[Dict[str, Any]] = None):
```
Executes a Neo4j Cypher declarative query in a database.
**Parameters:**
* **query** (str): The Cypher query to be executed.
* **params** (Optional\[Dict\[str, Any]]): A dictionary of parameters to be used in the query. Defaults to `None`.
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, each
dictionary represents a row of results from the Cypher query.
### refresh\_schema
```python theme={"system"}
def refresh_schema(self):
```
Refreshes the Neo4j graph schema information by querying the
database for node properties, relationship properties, and
relationships.
### add\_triplet
```python theme={"system"}
def add_triplet(
self,
subj: str,
obj: str,
rel: str,
timestamp: Optional[str] = None
):
```
Adds a relationship (triplet) between two entities
in the database with a timestamp.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object.
* **timestamp** (Optional\[str]): The timestamp of the relationship. Defaults to None.
### \_delete\_rel
```python theme={"system"}
def _delete_rel(
self,
subj: str,
obj: str,
rel: str
):
```
Deletes a specific relationship between two nodes in the Neo4j
database.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object to delete.
### \_delete\_entity
```python theme={"system"}
def _delete_entity(self, entity: str):
```
Deletes an entity from the Neo4j database based on its unique
identifier.
**Parameters:**
* **entity** (str): The unique identifier of the entity to be deleted.
### \_check\_edges
```python theme={"system"}
def _check_edges(self, entity: str):
```
Checks if the given entity has any relationships in the graph
database.
**Parameters:**
* **entity** (str): The unique identifier of the entity to check.
**Returns:**
bool: True if the entity has at least one edge (relationship),
False otherwise.
### delete\_triplet
```python theme={"system"}
def delete_triplet(
self,
subj: str,
obj: str,
rel: str
):
```
Deletes a specific triplet from the graph, comprising a subject,
object and relationship.
**Parameters:**
* **subj** (str): The identifier for the subject entity.
* **obj** (str): The identifier for the object entity.
* **rel** (str): The relationship between the subject and object.
### \_get\_node\_import\_query
```python theme={"system"}
def _get_node_import_query(self, base_entity_label: bool, include_source: bool):
```
Constructs a Cypher query string for importing nodes into a Neo4j
database.
**Parameters:**
* **base\_entity\_label** (bool): Flag indicating whether to use a base entity label in the MERGE operation.
* **include\_source** (bool): Flag indicating whether to include source element information in the query.
**Returns:**
str: A Cypher query string tailored based on the provided flags.
### \_get\_rel\_import\_query
```python theme={"system"}
def _get_rel_import_query(self, base_entity_label: bool):
```
Constructs a Cypher query string for importing relationship into a
Neo4j database.
**Parameters:**
* **base\_entity\_label** (bool): Flag indicating whether to use a base entity label in the MERGE operation.
**Returns:**
str: A Cypher query string tailored based on the provided flags.
### add\_graph\_elements
```python theme={"system"}
def add_graph_elements(
self,
graph_elements: List[GraphElement],
include_source: bool = False,
base_entity_label: bool = False
):
```
Adds nodes and relationships from a list of GraphElement objects
to the graph storage.
**Parameters:**
* **graph\_elements** (List\[GraphElement]): A list of GraphElement objects that contain the nodes and relationships to be added to the graph. Each GraphElement should encapsulate the structure of part of the graph, including nodes, relationships, and the source element information.
* **include\_source** (bool, optional): If True, stores the source element and links it to nodes in the graph using the MENTIONS relationship. This is useful for tracing back the origin of data. Merges source elements based on the `id` property from the source element metadata if available; otherwise it calculates the MD5 hash of `page_content` for merging process. Defaults to `False`.
* **base\_entity\_label** (bool, optional): If True, each newly created node gets a secondary `BASE_ENTITY_LABEL` label, which is indexed and improves import speed and performance. Defaults to `False`.
### random\_walk\_with\_restarts
```python theme={"system"}
def random_walk_with_restarts(
self,
graph_name: str,
sampling_ratio: float,
start_node_ids: List[int],
restart_probability: float = 0.1,
node_label_stratification: bool = False,
relationship_weight_property: Optional[str] = None
):
```
Runs the Random Walk with Restarts (RWR) sampling algorithm.
**Parameters:**
* **graph\_name** (str): The name of the original graph in the graph catalog.
* **sampling\_ratio** (float): The fraction of nodes in the original graph to be sampled.
* **start\_node\_ids** (List\[int]): IDs of the initial set of nodes of the original graph from which the sampling random walks will start.
* **restart\_probability** (float, optional): The probability that a sampling random walk restarts from one of the start nodes. Defaults to `0.1`.
* **node\_label\_stratification** (bool, optional): If true, preserves the node label distribution of the original graph. Defaults to `False`.
* **relationship\_weight\_property** (Optional\[str], optional): Name of the relationship property to use as weights. If unspecified, the algorithm runs unweighted. Defaults to `None`.
**Returns:**
Dict\[str, Any]: A dictionary with the results of the RWR sampling.
### common\_neighbour\_aware\_random\_walk
```python theme={"system"}
def common_neighbour_aware_random_walk(
self,
graph_name: str,
sampling_ratio: float,
start_node_ids: List[int],
node_label_stratification: bool = False,
relationship_weight_property: Optional[str] = None
):
```
Runs the Common Neighbour Aware Random Walk (CNARW) sampling
algorithm.
**Parameters:**
* **graph\_name** (str): The name of the original graph in the graph catalog.
* **sampling\_ratio** (float): The fraction of nodes in the original graph to be sampled.
* **start\_node\_ids** (List\[int]): IDs of the initial set of nodes of the original graph from which the sampling random walks will start.
* **node\_label\_stratification** (bool, optional): If true, preserves the node label distribution of the original graph. Defaults to `False`.
* **relationship\_weight\_property** (Optional\[str], optional): Name of the relationship property to use as weights. If unspecified, the algorithm runs unweighted. Defaults to `None`.
**Returns:**
Dict\[str, Any]: A dictionary with the results of the CNARW
sampling.
### get\_triplet
```python theme={"system"}
def get_triplet(
self,
subj: Optional[str] = None,
obj: Optional[str] = None,
rel: Optional[str] = None
):
```
Query triplet information. If subj, obj, or rel is
not specified, returns all matching triplets.
**Parameters:**
* **subj** (Optional\[str]): The ID of the subject node. If None, matches any subject node. (default: :obj:`None`)
* **obj** (Optional\[str]): The ID of the object node. If None, matches any object node. (default: :obj:`None`)
* **rel** (Optional\[str]): The type of relationship. If None, matches any relationship type. (default: :obj:`None`)
**Returns:**
List\[Dict\[str, Any]]: A list of matching triplets,
each containing subj, obj, rel, and timestamp.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.key_value_storages.base
## BaseKeyValueStorage
```python theme={"system"}
class BaseKeyValueStorage(ABC):
```
An abstract base class for key-value storage systems. Provides a
consistent interface for saving, loading, and clearing data records without
any loss of information.
An abstract base class designed to serve as a foundation for various
key-value storage systems. The class primarily interacts through Python
dictionaries.
This class is meant to be inherited by multiple types of key-value storage
implementations, including, but not limited to, JSON file storage, NoSQL
databases like MongoDB and Redis, as well as in-memory Python dictionaries.
### save
```python theme={"system"}
def save(self, records: List[Dict[str, Any]]):
```
Saves a batch of records to the key-value storage system.
**Parameters:**
* **records** (List\[Dict\[str, Any]]): A list of dictionaries, where each dictionary represents a unique record to be stored.
### load
```python theme={"system"}
def load(self):
```
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, where each dictionary
represents a stored record.
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the key-value storage system.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.key_value_storages.in_memory
## InMemoryKeyValueStorage
```python theme={"system"}
class InMemoryKeyValueStorage(BaseKeyValueStorage):
```
A concrete implementation of the :obj:`BaseKeyValueStorage` using
in-memory list. Ideal for temporary storage purposes, as data will be lost
when the program ends.
### **init**
```python theme={"system"}
def __init__(self):
```
### save
```python theme={"system"}
def save(self, records: List[Dict[str, Any]]):
```
Saves a batch of records to the key-value storage system.
**Parameters:**
* **records** (List\[Dict\[str, Any]]): A list of dictionaries, where each dictionary represents a unique record to be stored.
### load
```python theme={"system"}
def load(self):
```
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, where each dictionary
represents a stored record.
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the key-value storage system.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.key_value_storages.json
## CamelJSONEncoder
```python theme={"system"}
class CamelJSONEncoder(JSONEncoder):
```
A custom JSON encoder for serializing CAMEL-specific types.
Handles serialization of:
* Enumerated types (RoleType, TaskType, ModelType, OpenAIBackendRole)
* Pydantic BaseModel objects (from structured outputs)
Ensures these types can be stored in and retrieved from JSON format.
### default
```python theme={"system"}
def default(self, obj):
```
## JsonStorage
```python theme={"system"}
class JsonStorage(BaseKeyValueStorage):
```
A concrete implementation of the :obj:`BaseKeyValueStorage` using JSON
files. Allows for persistent storage of records in a human-readable format.
**Parameters:**
* **path** (Path, optional): Path to the desired JSON file. If `None`, a default path `./chat_history.json` will be used. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, path: Optional[Path] = None):
```
### \_json\_object\_hook
```python theme={"system"}
def _json_object_hook(self, d):
```
### save
```python theme={"system"}
def save(self, records: List[Dict[str, Any]]):
```
Saves a batch of records to the key-value storage system.
**Parameters:**
* **records** (List\[Dict\[str, Any]]): A list of dictionaries, where each dictionary represents a unique record to be stored.
### load
```python theme={"system"}
def load(self):
```
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, where each dictionary
represents a stored record.
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the key-value storage system.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.key_value_storages.mem0_cloud
## Mem0Storage
```python theme={"system"}
class Mem0Storage(BaseKeyValueStorage):
```
A concrete implementation of the :obj:`BaseKeyValueStorage` using Mem0
as the backend. This storage system uses Mem0's text capabilities to store,
search, and manage text with context.
**Parameters:**
* **agent\_id** (str): Default agent ID to associate memories with.
* **api\_key** (str, optional): The API key for authentication. If not provided, will try to get from environment variable MEM0\_API\_KEY (default: :obj:`None`).
* **user\_id** (str, optional): Default user ID to associate memories with (default: :obj:`None`).
* **metadata** (Dict\[str, Any], optional): Default metadata to include with all memories (default: :obj:`None`).
* **References**:
* **https**: //docs.mem0.ai
### **init**
```python theme={"system"}
def __init__(
self,
agent_id: str,
api_key: Optional[str] = None,
user_id: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None
):
```
### \_prepare\_options
```python theme={"system"}
def _prepare_options(
self,
agent_id: Optional[str] = None,
user_id: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs: Any
):
```
Helper method to prepare options for Mem0 API calls.
**Parameters:**
* **agent\_id** (Optional\[str], optional): Agent ID to use (default: :obj:`None`).
* **user\_id** (Optional\[str], optional): User ID to use (default: :obj:`None`).
* **metadata** (Optional\[Dict\[str, Any]], optional): Additional metadata to include (default: :obj:`None`). \*\*kwargs (Any): Additional keyword arguments.
**Returns:**
Dict\[str, Any]: Prepared options dictionary for API calls.
### \_prepare\_messages
```python theme={"system"}
def _prepare_messages(self, records: List[Dict[str, Any]]):
```
Prepare messages from records for Mem0 API calls.
**Parameters:**
* **records** (List\[Dict\[str, Any]]): List of record dictionaries.
**Returns:**
List\[Dict\[str, Any]]: List of prepared message dictionaries.
### save
```python theme={"system"}
def save(self, records: List[Dict[str, Any]]):
```
Saves a batch of records to the Mem0 storage system.
**Parameters:**
* **records** (List\[Dict\[str, Any]]): A list of dictionaries, where each dictionary represents a unique record to be stored.
### load
```python theme={"system"}
def load(self):
```
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, where each dictionary
represents a stored record.
### clear
```python theme={"system"}
def clear(
self,
agent_id: Optional[str] = None,
user_id: Optional[str] = None
):
```
Removes all records from the Mem0 storage system.
**Parameters:**
* **agent\_id** (Optional\[str]): Specific agent ID to clear memories for.
* **user\_id** (Optional\[str]): Specific user ID to clear memories for.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.key_value_storages.redis
## RedisStorage
```python theme={"system"}
class RedisStorage(BaseKeyValueStorage):
```
A concrete implementation of the :obj:`BaseCacheStorage` using Redis as
the backend. This is suitable for distributed cache systems that require
persistence and high availability.
### **init**
```python theme={"system"}
def __init__(
self,
sid: str,
url: str = 'redis://localhost:6379',
loop: Optional[asyncio.AbstractEventLoop] = None,
**kwargs
):
```
Initializes the RedisStorage instance with the provided URL and
options.
**Parameters:**
* **sid** (str): The ID for the storage instance to identify the record space.
* **url** (str): The URL for connecting to the Redis server. \*\*kwargs: Additional keyword arguments for Redis client configuration.
### **enter**
```python theme={"system"}
def __enter__(self):
```
### **exit**
```python theme={"system"}
def __exit__(
self,
exc_type,
exc,
tb
):
```
### \_create\_client
```python theme={"system"}
def _create_client(self, **kwargs):
```
Creates the Redis client with the provided URL and options.
### client
```python theme={"system"}
def client(self):
```
**Returns:**
redis.asyncio.Redis: The Redis client instance.
### save
```python theme={"system"}
def save(
self,
records: List[Dict[str, Any]],
expire: Optional[int] = None
):
```
Saves a batch of records to the key-value storage system.
### load
```python theme={"system"}
def load(self):
```
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, where each dictionary
represents a stored record.
### clear
```python theme={"system"}
def clear(self):
```
Removes all records from the key-value storage system.
### \_run\_async
```python theme={"system"}
def _run_async(self, coro):
```
# null
Source: https://docs.camel-ai.org/reference/camel.storages.object_storages.amazon_s3
## AmazonS3Storage
```python theme={"system"}
class AmazonS3Storage(BaseObjectStorage):
```
A class to connect with AWS S3 object storage to put and get objects
from one S3 bucket. The class will first try to use the credentials passed
as arguments, if not provided, it will look for the environment variables
`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. If none of these are
provided, it will try to use the local credentials (will be created if
logged in with AWS CLI).
**Parameters:**
* **bucket\_name** (str): The name of the S3 bucket.
* **create\_if\_not\_exists** (bool, optional): Whether to create the bucket if it does not exist. Defaults to True.
* **access\_key\_id** (Optional\[str], optional): The AWS access key ID. Defaults to None.
* **secret\_access\_key** (Optional\[str], optional): The AWS secret access key. Defaults to None.
* **anonymous** (bool, optional): Whether to use anonymous access. Defaults to False.
* **References**:
* **https**: //aws.amazon.com/pm/serv-s3/
* **https**: //aws.amazon.com/cli/
### **init**
```python theme={"system"}
def __init__(
self,
bucket_name: str,
create_if_not_exists: bool = True,
access_key_id: Optional[str] = None,
secret_access_key: Optional[str] = None,
anonymous: bool = False
):
```
### \_prepare\_and\_check
```python theme={"system"}
def _prepare_and_check(self):
```
Check privileges and existence of the bucket.
### canonicalize\_path
```python theme={"system"}
def canonicalize_path(file_path: PurePath):
```
Canonicalize file path for Amazon S3.
**Parameters:**
* **file\_path** (PurePath): The path to be canonicalized.
**Returns:**
Tuple\[str, str]: The canonicalized file key and file name.
### \_put\_file
```python theme={"system"}
def _put_file(self, file_key: str, file: File):
```
Put a file to the Amazon S3 bucket.
**Parameters:**
* **file\_key** (str): The path to the object in the bucket.
* **file** (File): The file to be uploaded.
### \_get\_file
```python theme={"system"}
def _get_file(self, file_key: str, filename: str):
```
Get a file from the Amazon S3 bucket.
**Parameters:**
* **file\_key** (str): The path to the object in the bucket.
* **filename** (str): The name of the file.
**Returns:**
File: The object from the S3 bucket.
### \_upload\_file
```python theme={"system"}
def _upload_file(self, local_file_path: Path, remote_file_key: str):
```
Upload a local file to the Amazon S3 bucket.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be uploaded.
* **remote\_file\_key** (str): The path to the object in the bucket.
### \_download\_file
```python theme={"system"}
def _download_file(self, local_file_path: Path, remote_file_key: str):
```
Download a file from the Amazon S3 bucket to the local system.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be saved.
* **remote\_file\_key** (str): The key of the object in the bucket.
### \_object\_exists
```python theme={"system"}
def _object_exists(self, file_key: str):
```
Check if the object exists in the Amazon S3 bucket.
**Parameters:**
* **file\_key**: The key of the object in the bucket.
**Returns:**
bool: Whether the object exists in the bucket.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.object_storages.azure_blob
## AzureBlobStorage
```python theme={"system"}
class AzureBlobStorage(BaseObjectStorage):
```
A class to connect to Azure Blob Storage. It will connect to one
container in the storage account.
**Parameters:**
* **storage\_account\_name** (str): The name of the storage account.
* **container\_name** (str): The name of the container.
* **access\_key** (Optional\[str], optional): The access key of the storage account. Defaults to None.
* **References**:
* **https**: //azure.microsoft.com/en-us/products/storage/blobs
### **init**
```python theme={"system"}
def __init__(
self,
storage_account_name: str,
container_name: str,
create_if_not_exists: bool = True,
access_key: Optional[str] = None
):
```
### \_prepare\_and\_check
```python theme={"system"}
def _prepare_and_check(self):
```
Check privileges and existence of the container.
### canonicalize\_path
```python theme={"system"}
def canonicalize_path(file_path: PurePath):
```
Canonicalize file path for Azure Blob Storage.
**Parameters:**
* **file\_path** (PurePath): The path to be canonicalized.
**Returns:**
Tuple\[str, str]: The canonicalized file key and file name.
### \_put\_file
```python theme={"system"}
def _put_file(self, file_key: str, file: File):
```
Put a file to the Azure Blob Storage container.
**Parameters:**
* **file\_key** (str): The path to the object in the container.
* **file** (File): The file to be uploaded.
### \_get\_file
```python theme={"system"}
def _get_file(self, file_key: str, filename: str):
```
Get a file from the Azure Blob Storage container.
**Parameters:**
* **file\_key** (str): The path to the object in the container.
* **filename** (str): The name of the file.
**Returns:**
File: The object from the container.
### \_upload\_file
```python theme={"system"}
def _upload_file(self, local_file_path: Path, remote_file_key: str):
```
Upload a local file to the Azure Blob Storage container.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be uploaded.
* **remote\_file\_key** (str): The path to the object in the container.
### \_download\_file
```python theme={"system"}
def _download_file(self, local_file_path: Path, remote_file_key: str):
```
Download a file from the Azure Blob Storage container to the local
system.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be saved.
* **remote\_file\_key** (str): The key of the object in the container.
### \_object\_exists
```python theme={"system"}
def _object_exists(self, file_key: str):
```
Check if the object exists in the Azure Blob Storage container.
**Parameters:**
* **file\_key**: The key of the object in the container.
**Returns:**
bool: Whether the object exists in the container.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.object_storages.base
## BaseObjectStorage
```python theme={"system"}
class BaseObjectStorage(ABC):
```
### object\_exists
```python theme={"system"}
def object_exists(self, file_path: PurePath):
```
Check if the object exists in the storage.
**Parameters:**
* **file\_path** (PurePath): The path to the object in the storage.
**Returns:**
bool: True if the object exists, False otherwise.
### canonicalize\_path
```python theme={"system"}
def canonicalize_path(file_path: PurePath):
```
### put\_file
```python theme={"system"}
def put_file(self, file_path: PurePath, file: File):
```
Put a file to the object storage.
**Parameters:**
* **file\_path** (PurePath): The path to the object in the storage.
* **file** (File): The file to be put.
### get\_file
```python theme={"system"}
def get_file(self, file_path: PurePath):
```
Get a file from the object storage.
**Parameters:**
* **file\_path** (PurePath): The path to the object in the storage.
**Returns:**
File: The file object get from the storage.
### upload\_file
```python theme={"system"}
def upload_file(self, local_file_path: Path, remote_file_path: PurePath):
```
Upload a local file to the object storage.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be uploaded.
* **remote\_file\_path** (PurePath): The path to the object in storage.
### download\_file
```python theme={"system"}
def download_file(self, local_file_path: Path, remote_file_path: PurePath):
```
Download a file from the object storage to the local system.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be saved.
* **remote\_file\_path** (PurePath): The path to the object in storage.
### \_put\_file
```python theme={"system"}
def _put_file(self, file_key: str, file: File):
```
### \_get\_file
```python theme={"system"}
def _get_file(self, file_key: str, filename: str):
```
### \_object\_exists
```python theme={"system"}
def _object_exists(self, file_key: str):
```
### \_upload\_file
```python theme={"system"}
def _upload_file(self, local_file_path: Path, remote_file_key: str):
```
### \_download\_file
```python theme={"system"}
def _download_file(self, local_file_path: Path, remote_file_key: str):
```
# null
Source: https://docs.camel-ai.org/reference/camel.storages.object_storages.google_cloud
## GoogleCloudStorage
```python theme={"system"}
class GoogleCloudStorage(BaseObjectStorage):
```
A class to connect to Google Cloud Storage. It will connect to one
bucket in the storage account.
Note that Google Cloud Storage does not support api key authentication.
Therefore, before using this class, you need to log in with gcloud command
line tool and save the credentials first.
**Parameters:**
* **bucket\_name** (str): The name of the bucket.
* **create\_if\_not\_exists** (bool, optional): Whether to create the bucket if it does not exist. Defaults to True.
* **anonymous** (bool, optional): Whether to use anonymous access. Defaults to False.
* **References**:
* **https**: //cloud.google.com/storage
* **https**: //cloud.google.com/docs/authentication/api-keys
### **init**
```python theme={"system"}
def __init__(
self,
bucket_name: str,
create_if_not_exists: bool = True,
anonymous: bool = False
):
```
### canonicalize\_path
```python theme={"system"}
def canonicalize_path(file_path: PurePath):
```
Canonicalize the path for Google Cloud Storage.
**Parameters:**
* **file\_path** (PurePath): The path to be canonicalized.
**Returns:**
Tuple\[str, str]: The canonicalized file key and file name.
### \_prepare\_and\_check
```python theme={"system"}
def _prepare_and_check(self):
```
Check privileges and existence of the bucket.
### \_put\_file
```python theme={"system"}
def _put_file(self, file_key: str, file: File):
```
Put a file to the GCloud bucket.
**Parameters:**
* **file\_key** (str): The path to the object in the bucket.
* **file** (File): The file to be uploaded.
### \_get\_file
```python theme={"system"}
def _get_file(self, file_key: str, filename: str):
```
Get a file from the GCloud bucket.
**Parameters:**
* **file\_key** (str): The path to the object in the bucket.
* **filename** (str): The name of the file.
**Returns:**
File: The object from the S3 bucket.
### \_upload\_file
```python theme={"system"}
def _upload_file(self, local_file_path: Path, remote_file_key: str):
```
Upload a local file to the GCloud bucket.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be uploaded.
* **remote\_file\_key** (str): The path to the object in the bucket.
### \_download\_file
```python theme={"system"}
def _download_file(self, local_file_path: Path, remote_file_key: str):
```
Download a file from the GCloud bucket to the local system.
**Parameters:**
* **local\_file\_path** (Path): The path to the local file to be saved.
* **remote\_file\_key** (str): The key of the object in the bucket.
### \_object\_exists
```python theme={"system"}
def _object_exists(self, file_key: str):
```
Check if the object exists in the GCloud bucket.
**Parameters:**
* **file\_key**: The key of the object in the bucket.
**Returns:**
bool: Whether the object exists in the bucket.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.base
## VectorRecord
```python theme={"system"}
class VectorRecord(BaseModel):
```
Encapsulates information about a vector's unique identifier and its
payload, which is primarily used as a data transfer object when saving
to vector storage.
**Parameters:**
* **vector** (List\[float]): The numerical representation of the vector.
* **id** (str, optional): A unique identifier for the vector. If not provided, an random uuid will be assigned.
* **payload** (Optional\[Dict\[str, Any]], optional): Any additional metadata or information related to the vector. (default: :obj:`None`)
## VectorDBQuery
```python theme={"system"}
class VectorDBQuery(BaseModel):
```
Represents a query to a vector database.
**Parameters:**
* **query\_vector** (List\[float]): The numerical representation of the query vector.
* **top\_k** (int, optional): The number of top similar vectors to retrieve from the database. (default: :obj:`1`)
### **init**
```python theme={"system"}
def __init__(
self,
query_vector: List[float],
top_k: int,
**kwargs: Any
):
```
Pass in query\_vector and tok\_k as positional arg.
**Parameters:**
* **query\_vector** (List\[float]): The numerical representation of the query vector.
* **top\_k** (int, optional): The number of top similar vectors to retrieve from the database. (default: :obj:`1`)
## VectorDBQueryResult
```python theme={"system"}
class VectorDBQueryResult(BaseModel):
```
Encapsulates the result of a query against a vector database.
**Parameters:**
* **record** (VectorRecord): The target vector record.
* **similarity** (float): The similarity score between the query vector and the record.
### create
```python theme={"system"}
def create(
cls,
similarity: float,
vector: List[float],
id: str,
payload: Optional[Dict[str, Any]] = None
):
```
A class method to construct a `VectorDBQueryResult` instance.
## VectorDBStatus
```python theme={"system"}
class VectorDBStatus(BaseModel):
```
Vector database status.
**Parameters:**
* **vector\_dim** (int): The dimension of stored vectors.
* **vector\_count** (int): The number of stored vectors.
## BaseVectorStorage
```python theme={"system"}
class BaseVectorStorage(ABC):
```
An abstract base class for vector storage systems.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs: Any):
```
Saves a list of vector records to the storage.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to be saved. \*\*kwargs (Any): Additional keyword arguments.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Deletes a list of vectors identified by their IDs from the storage.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be deleted. \*\*kwargs (Any): Additional keyword arguments.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: The vector database status.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Searches for similar vectors in the storage based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve. \*\*kwargs (Any): Additional keyword arguments.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### clear
```python theme={"system"}
def clear(self):
```
Remove all vectors from the storage.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
Provides access to the underlying vector database client.
### get\_payloads\_by\_vector
```python theme={"system"}
def get_payloads_by_vector(self, vector: List[float], top_k: int):
```
Returns payloads of top k vector records that closest to the given
vector.
This function is a wrapper of `BaseVectorStorage.query`.
**Parameters:**
* **vector** (List\[float]): The search vector.
* **top\_k** (int): The number of top similar vectors.
**Returns:**
List\[List\[Dict\[str, Any]]]: A list of vector payloads retrieved
from the storage based on similarity to the query vector.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.chroma
## ChromaStorage
```python theme={"system"}
class ChromaStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` for interacting with
ChromaDB, a vector database for embeddings.
ChromaDB is an open-source AI-native vector database focused on developer
productivity and happiness. The detailed information about ChromaDB is
available at: `ChromaDB `\_
This class provides multiple ways to connect to ChromaDB instances:
* Ephemeral (in-memory for testing/prototyping)
* Persistent (local file storage)
* HTTP (remote ChromaDB server)
* Cloud (ChromaDB Cloud - future support)
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **collection\_name** (Optional\[str], optional): Name for the collection in ChromaDB. If not provided, auto-generated with timestamp. (default: :obj:`None`)
* **client\_type** (`Literal["ephemeral", "persistent", "http", "cloud"]`): Type of ChromaDB client to use. Supported types: 'ephemeral', 'persistent', 'http', 'cloud'. (default: :obj:`"ephemeral"`) # Persistent client parameters
* **path** (Optional\[str], optional): Path to directory for persistent storage. Only used when client\_type='persistent'. (default: :obj:`"./chroma"`) # HTTP client parameters
* **host** (str, optional): Host for remote ChromaDB server. (default: :obj:`"localhost"`)
* **port** (int, optional): Port for remote ChromaDB server. (default: :obj:`8000`)
* **ssl** (bool, optional): Whether to use SSL for HTTP connections. (default: :obj:`False`)
* **headers** (Optional\[Dict\[str, str]], optional): Additional headers for HTTP client requests. (default: :obj:`None`) # Cloud client parameters
* **api\_key** (Optional\[str], optional): API key for ChromaDB Cloud. (default: :obj:`None`)
* **cloud\_host** (str, optional): ChromaDB Cloud host. (default: :obj:`"api.trychroma.com"`)
* **cloud\_port** (int, optional): ChromaDB Cloud port. (default: :obj:`8000`)
* **enable\_ssl** (bool, optional): Whether to enable SSL for cloud connection.(default: :obj:`True`) # Common parameters for all client types
* **settings** (Optional\[Any], optional): ChromaDB settings object for advanced configuration. (default: :obj:`None`)
* **tenant** (Optional\[str], optional): Tenant name for multi-tenancy support. (default: :obj:`None`)
* **database** (Optional\[str], optional): Database name for multi-database support. (default: :obj:`None`)
* **distance** (VectorDistance, optional): The distance metric for vector comparison. (default: :obj:`VectorDistance.COSINE`)
* **delete\_collection\_on\_del** (bool, optional): Flag to determine if the collection should be deleted upon object destruction. (default: :obj:`False`)
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
collection_name: Optional[str] = None,
client_type: Literal['ephemeral', 'persistent', 'http', 'cloud'] = 'ephemeral',
path: Optional[str] = './chroma',
host: str = 'localhost',
port: int = 8000,
ssl: bool = False,
headers: Optional[Dict[str, str]] = None,
api_key: Optional[str] = None,
cloud_host: str = 'api.trychroma.com',
cloud_port: int = 8000,
enable_ssl: bool = True,
settings: Optional[Any] = None,
tenant: Optional[str] = None,
database: Optional[str] = None,
distance: VectorDistance = VectorDistance.COSINE,
delete_collection_on_del: bool = False,
**kwargs: Any
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Deletes the collection if :obj:`delete_collection_on_del` is set to
:obj:`True`.
### \_validate\_client\_type
```python theme={"system"}
def _validate_client_type(
self,
client_type: Literal['ephemeral', 'persistent', 'http', 'cloud']
):
```
Validates client type parameter.
**Parameters:**
* **client\_type** (`Literal["ephemeral", "persistent", "http", "cloud"]`): The client type to validate.
### \_validate\_client\_config
```python theme={"system"}
def _validate_client_config(self):
```
### \_get\_connection\_client
```python theme={"system"}
def _get_connection_client(self):
```
Get ChromaDB client based on client type and user settings.
### \_create\_ephemeral\_client
```python theme={"system"}
def _create_ephemeral_client(self, chromadb_module: Any):
```
Create an ephemeral ChromaDB client (in-memory).
### \_create\_persistent\_client
```python theme={"system"}
def _create_persistent_client(self, chromadb_module: Any):
```
Create a persistent ChromaDB client (local file storage).
### \_create\_http\_client
```python theme={"system"}
def _create_http_client(self, chromadb_module: Any):
```
Create an HTTP ChromaDB client (remote server).
### \_create\_cloud\_client
```python theme={"system"}
def _create_cloud_client(self, chromadb_module: Any):
```
Create a cloud ChromaDB client.
### \_get\_common\_client\_kwargs
```python theme={"system"}
def _get_common_client_kwargs(self):
```
Get common kwargs for all ChromaDB clients.
### \_generate\_collection\_name
```python theme={"system"}
def _generate_collection_name(self):
```
**Returns:**
str: Generated collection name based on current timestamp.
### \_get\_distance\_function
```python theme={"system"}
def _get_distance_function(self):
```
**Returns:**
str: ChromaDB distance function name.
References:
[https://docs.trychroma.com/docs/collections/configure](https://docs.trychroma.com/docs/collections/configure)
### \_get\_or\_create\_collection
```python theme={"system"}
def _get_or_create_collection(self):
```
**Returns:**
ChromaDB collection object.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs: Any):
```
Adds vector records to ChromaDB collection.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to be saved. \*\*kwargs (Any): Additional keyword arguments for ChromaDB add operation.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Deletes vectors by their IDs from ChromaDB collection.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be deleted. \*\*kwargs (Any): Additional keyword arguments for ChromaDB delete operation.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: The vector database status containing dimension
and count information.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Searches for similar vectors in ChromaDB based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve. \*\*kwargs (Any): Additional keyword arguments for ChromaDB query operation.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### \_distance\_to\_similarity
```python theme={"system"}
def _distance_to_similarity(self, distance: float):
```
Convert distance to similarity score based on distance metric.
**Parameters:**
* **distance** (float): Distance value from ChromaDB.
**Returns:**
float: Similarity score (higher means more similar).
### clear
```python theme={"system"}
def clear(self):
```
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
For ChromaDB, collections are automatically available when client
connects, so this method is a no-op.
### delete\_collection
```python theme={"system"}
def delete_collection(self):
```
### client
```python theme={"system"}
def client(self):
```
**Returns:**
chromadb.Client: The ChromaDB client instance.
### collection
```python theme={"system"}
def collection(self):
```
**Returns:**
ChromaDB collection instance.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.faiss
## FaissStorage
```python theme={"system"}
class FaissStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` using FAISS,
Facebook AI's Similarity Search library for efficient vector search.
The detailed information about FAISS is available at:
`FAISS `\_
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **index\_type** (str, optional): Type of FAISS index to create. Options include 'Flat', 'IVF', 'HNSW', etc. (default: :obj:`'Flat'`)
* **collection\_name** (Optional\[str], optional): Name for the collection. If not provided, set it to the current time with iso format. (default: :obj:`None`)
* **storage\_path** (Optional\[str], optional): Path to directory where the index will be stored. If None, index will only exist in memory. (default: :obj:`None`)
* **distance** (VectorDistance, optional): The distance metric for vector comparison (default: :obj:`VectorDistance.COSINE`)
* **nlist** (int, optional): Number of cluster centroids for IVF indexes. Only used if index\_type includes 'IVF'. (default: :obj:`100`)
* **m** (int, optional): HNSW parameter. Number of connections per node. Only used if index\_type includes 'HNSW'. (default: :obj:`16`) \*\*kwargs (Any): Additional keyword arguments.
**Note:**
* FAISS offers various index types optimized for different use cases:
* 'Flat': Exact search, but slowest for large datasets
* 'IVF': Inverted file index, good balance of speed and recall
* 'HNSW': Hierarchical Navigable Small World, fast with high recall
* 'PQ': Product Quantization for memory-efficient storage
* The choice of index should be based on your specific requirements
for search speed, memory usage, and accuracy.
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
index_type: str = 'Flat',
collection_name: Optional[str] = None,
storage_path: Optional[str] = None,
distance: VectorDistance = VectorDistance.COSINE,
nlist: int = 100,
m: int = 16,
**kwargs: Any
):
```
Initialize the FAISS vector storage.
**Parameters:**
* **vector\_dim**: Dimension of vectors to be stored
* **index\_type**: FAISS index type ('Flat', 'IVF', 'HNSW', etc.)
* **collection\_name**: Name of the collection (defaults to timestamp) (default: timestamp)
* **storage\_path**: Directory to save the index (None for in-memory only)
* **distance**: Vector distance metric
* **nlist**: Number of clusters for IVF indexes
* **m**: HNSW parameter for connections per node \*\*kwargs: Additional parameters
### \_generate\_collection\_name
```python theme={"system"}
def _generate_collection_name(self):
```
Generates a collection name if user doesn't provide
### \_get\_index\_path
```python theme={"system"}
def _get_index_path(self):
```
Returns the path to the index file
### \_get\_metadata\_path
```python theme={"system"}
def _get_metadata_path(self):
```
Returns the path to the metadata file
### \_create\_index
```python theme={"system"}
def _create_index(self):
```
**Returns:**
A FAISS index object configured according to the parameters.
### \_save\_to\_disk
```python theme={"system"}
def _save_to_disk(self):
```
Save the index and metadata to disk if storage\_path is provided.
### \_load\_from\_disk
```python theme={"system"}
def _load_from_disk(self):
```
Loads the index and metadata from disk if they exist.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs):
```
Adds a list of vectors to the index.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to be added. \*\*kwargs (Any): Additional keyword arguments.
### update\_payload
```python theme={"system"}
def update_payload(
self,
ids: List[str],
payload: Dict[str, Any],
**kwargs: Any
):
```
Updates the payload of the vectors identified by their IDs.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be updated.
* **payload** (Dict\[str, Any]): Payload to be updated for all specified IDs. \*\*kwargs (Any): Additional keyword arguments.
### delete\_collection
```python theme={"system"}
def delete_collection(self):
```
Deletes the entire collection (index and metadata).
### delete
```python theme={"system"}
def delete(
self,
ids: Optional[List[str]] = None,
payload_filter: Optional[Dict[str, Any]] = None,
**kwargs: Any
):
```
Deletes vectors from the index based on either IDs or payload
filters.
**Parameters:**
* **ids** (Optional\[List\[str]], optional): List of unique identifiers for the vectors to be deleted.
* **payload\_filter** (Optional\[Dict\[str, Any]], optional): A filter for the payload to delete points matching specific conditions. \*\*kwargs (Any): Additional keyword arguments.
**Note:**
* FAISS does not support efficient single vector removal for most
index types. This implementation recreates the index without the
deleted vectors, which can be inefficient for large datasets.
* If both `ids` and `payload_filter` are provided, both filters
will be applied (vectors matching either will be deleted).
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: Current status of the vector database.
### query
```python theme={"system"}
def query(
self,
query: VectorDBQuery,
filter_conditions: Optional[Dict[str, Any]] = None,
**kwargs: Any
):
```
Searches for similar vectors in the storage based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve.
* **filter\_conditions** (Optional\[Dict\[str, Any]], optional): A dictionary specifying conditions to filter the query results. \*\*kwargs (Any): Additional keyword arguments.
**Returns:**
List\[VectorDBQueryResult]: A list of query results ordered by
similarity.
### clear
```python theme={"system"}
def clear(self):
```
Remove all vectors from the storage.
### load
```python theme={"system"}
def load(self):
```
Load the index from disk if storage\_path is provided.
### client
```python theme={"system"}
def client(self):
```
Provides access to the underlying FAISS client.
### \_matches\_filter
```python theme={"system"}
def _matches_filter(self, vector_id: str, filter_conditions: Dict[str, Any]):
```
Checks if a vector's payload matches the filter conditions.
**Parameters:**
* **vector\_id** (str): ID of the vector to check.
* **filter\_conditions** (Dict\[str, Any]): Conditions to match against.
**Returns:**
bool: True if the payload matches all conditions, False otherwise.
### \_normalize\_vector
```python theme={"system"}
def _normalize_vector(self, vector: 'ndarray'):
```
Normalizes a vector to unit length for cosine similarity.
**Parameters:**
* **vector** (ndarray): Vector to normalize, either 1D or 2D array.
**Returns:**
ndarray: Normalized vector with the same shape as input.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.milvus
## MilvusStorage
```python theme={"system"}
class MilvusStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` for interacting with
Milvus, a cloud-native vector search engine.
The detailed information about Milvus is available at:
`Milvus `\_
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **url\_and\_api\_key** (Tuple\[str, str]): Tuple containing the URL and API key for connecting to a remote Milvus instance. URL maps to Milvus uri concept, typically "endpoint:port". API key maps to Milvus token concept, for self-hosted it's "username:pwd", for Zilliz Cloud (fully-managed Milvus) it's API Key.
* **collection\_name** (Optional\[str], optional): Name for the collection in the Milvus. If not provided, set it to the current time with iso format. (default: :obj:`None`) \*\*kwargs (Any): Additional keyword arguments for initializing `MilvusClient`.
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
url_and_api_key: Tuple[str, str],
collection_name: Optional[str] = None,
**kwargs: Any
):
```
### \_create\_client
```python theme={"system"}
def _create_client(self, url_and_api_key: Tuple[str, str], **kwargs: Any):
```
Initializes the Milvus client with the provided connection details.
**Parameters:**
* **url\_and\_api\_key** (Tuple\[str, str]): The URL and API key for the Milvus server. \*\*kwargs: Additional keyword arguments passed to the Milvus client.
### \_check\_and\_create\_collection
```python theme={"system"}
def _check_and_create_collection(self):
```
Checks if the specified collection exists in Milvus and creates it
if it doesn't, ensuring it matches the specified vector dimensionality.
### \_create\_collection
```python theme={"system"}
def _create_collection(self, collection_name: str, **kwargs: Any):
```
Creates a new collection in the database.
**Parameters:**
* **collection\_name** (str): Name of the collection to be created. \*\*kwargs (Any): Additional keyword arguments pass to create collection.
### \_delete\_collection
```python theme={"system"}
def _delete_collection(self, collection_name: str):
```
Deletes an existing collection from the database.
**Parameters:**
* **collection** (str): Name of the collection to be deleted.
### \_collection\_exists
```python theme={"system"}
def _collection_exists(self, collection_name: str):
```
Checks whether a collection with the specified name exists in the
database.
**Parameters:**
* **collection\_name** (str): The name of the collection to check.
**Returns:**
bool: True if the collection exists, False otherwise.
### \_generate\_collection\_name
```python theme={"system"}
def _generate_collection_name(self):
```
**Returns:**
str: A unique, valid collection name.
### \_get\_collection\_info
```python theme={"system"}
def _get_collection_info(self, collection_name: str):
```
Retrieves details of an existing collection.
**Parameters:**
* **collection\_name** (str): Name of the collection to be checked.
**Returns:**
Dict\[str, Any]: A dictionary containing details about the
collection.
### \_validate\_and\_convert\_vectors
```python theme={"system"}
def _validate_and_convert_vectors(self, records: List[VectorRecord]):
```
Validates and converts VectorRecord instances to the format
expected by Milvus.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to validate and convert.
**Returns:**
List\[dict]: A list of dictionaries formatted for Milvus insertion.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs):
```
Adds a list of vectors to the specified collection.
**Parameters:**
* **records** (List\[VectorRecord]): List of vectors to be added. \*\*kwargs (Any): Additional keyword arguments pass to insert.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Deletes a list of vectors identified by their IDs from the
storage. If unsure of ids you can first query the collection to grab
the corresponding data.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be deleted. \*\*kwargs (Any): Additional keyword arguments passed to delete.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: An object containing information about the
collection's status.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Searches for similar vectors in the storage based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve. \*\*kwargs (Any): Additional keyword arguments passed to search.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### clear
```python theme={"system"}
def clear(self):
```
Removes all vectors from the Milvus collection. This method
deletes the existing collection and then recreates it with the same
schema to effectively remove all stored vectors.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
**Returns:**
Any: The Milvus client instance.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.oceanbase
## OceanBaseStorage
```python theme={"system"}
class OceanBaseStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` for interacting with
OceanBase Vector Database.
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **table\_name** (str): Name for the table in OceanBase.
* **uri** (str): Connection URI for OceanBase (host:port). (default: :obj:`"127.0.0.1:2881"`)
* **user** (str): Username for connecting to OceanBase. (default: :obj:`"root@test"`)
* **password** (str): Password for the user. (default: :obj:`""`) (default: `""`)
* **db\_name** (str): Database name in OceanBase. (default: :obj:`"test"`)
* **distance** (`Literal["l2", "cosine"], optional`): The distance metric for vector comparison. Options: "l2", "cosine". (default: :obj:`"l2"`)
* **delete\_table\_on\_del** (bool, optional): Flag to determine if the table should be deleted upon object destruction. (default: :obj:`False`) \*\*kwargs (Any): Additional keyword arguments for initializing `ObVecClient`.
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
table_name: str,
uri: str = '127.0.0.1:2881',
user: str = 'root@test',
password: str = '',
db_name: str = 'test',
distance: Literal['l2', 'cosine'] = 'l2',
delete_table_on_del: bool = False,
**kwargs: Any
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Deletes the table if :obj:`delete_table_on_del` is set to
:obj:`True`.
### add
```python theme={"system"}
def add(
self,
records: List[VectorRecord],
batch_size: int = 100,
**kwargs: Any
):
```
Saves a list of vector records to the storage.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to be saved.
* **batch\_size** (int): Number of records to insert each batch. Larger batches are more efficient but use more memory. (default: :obj:`100`) \*\*kwargs (Any): Additional keyword arguments.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Deletes a list of vectors identified by their IDs from the storage.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be deleted. \*\*kwargs (Any): Additional keyword arguments.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: The vector database status.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Searches for similar vectors in the storage based on the
provided query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve. \*\*kwargs (Any): Additional keyword arguments.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### \_convert\_distance\_to\_similarity
```python theme={"system"}
def _convert_distance_to_similarity(self, distance: float):
```
Converts distance to similarity score based on distance metric.
### clear
```python theme={"system"}
def clear(self):
```
Remove all vectors from the storage.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
Provides access to underlying OceanBase vector database client.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.pgvector
## PgVectorStorage
```python theme={"system"}
class PgVectorStorage(BaseVectorStorage):
```
PgVectorStorage is an implementation of BaseVectorStorage for
PostgreSQL with pgvector extension.
This class provides methods to add, delete, query, and manage vector
records in a PostgreSQL database using the pgvector extension.
It supports different distance metrics for similarity search.
**Parameters:**
* **vector\_dim** (int): The dimension of the vectors to be stored.
* **conn\_info** (Dict\[str, Any]): Connection information for psycopg2.connect.
* **table\_name** (str, optional): Name of the table to store vectors. (default: :obj:`None`)
* **distance** (VectorDistance, optional): Distance metric for vector comparison. (default: :obj:`VectorDistance.COSINE`)
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
conn_info: Dict[str, Any],
table_name: Optional[str] = None,
distance: VectorDistance = VectorDistance.COSINE,
**kwargs: Any
):
```
Initialize PgVectorStorage.
**Parameters:**
* **vector\_dim** (int): The dimension of the vectors.
* **conn\_info** (Dict\[str, Any]): Connection info for psycopg2.connect.
* **table\_name** (str, optional): Table name. (default: :obj:`None`)
* **distance** (VectorDistance, optional): Distance metric. (default: :obj:`VectorDistance.COSINE`)
### \_ensure\_table
```python theme={"system"}
def _ensure_table(self):
```
Ensure the vector table exists in the database.
Creates the table if it does not exist.
### \_ensure\_index
```python theme={"system"}
def _ensure_index(self):
```
Ensure vector similarity search index exists for better
performance.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs: Any):
```
Add or update vector records in the database.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to add or update.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Delete vector records from the database by their IDs.
**Parameters:**
* **ids** (List\[str]): List of record IDs to delete.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Query the database for the most similar vectors to the given
query vector.
**Parameters:**
* **query** (VectorDBQuery): Query object containing the query vector and top\_k. \*\*kwargs (Any): Additional keyword arguments for the query.
**Returns:**
List\[VectorDBQueryResult]: List of query results sorted by
similarity.
### status
```python theme={"system"}
def status(self, **kwargs: Any):
```
Get the status of the vector database, including vector
dimension and count.
**Returns:**
VectorDBStatus: Status object with vector dimension and count.
### clear
```python theme={"system"}
def clear(self):
```
Remove all vectors from the storage by truncating the table.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service (no-op for pgvector).
This method is provided for interface compatibility.
### close
```python theme={"system"}
def close(self):
```
Close the database connection.
### **del**
```python theme={"system"}
def __del__(self):
```
Ensure connection is closed when object is destroyed.
### client
```python theme={"system"}
def client(self):
```
**Returns:**
Any: The underlying psycopg connection object.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.qdrant
## QdrantStorage
```python theme={"system"}
class QdrantStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` for interacting with
Qdrant, a vector search engine.
The detailed information about Qdrant is available at:
`Qdrant `\_
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **collection\_name** (Optional\[str], optional): Name for the collection in the Qdrant. If not provided, set it to the current time with iso format. (default: :obj:`None`)
* **url\_and\_api\_key** (Optional\[Tuple\[str, str]], optional): Tuple containing the URL and API key for connecting to a remote Qdrant instance. (default: :obj:`None`)
* **path** (Optional\[str], optional): Path to a directory for initializing a local Qdrant client. (default: :obj:`None`)
* **distance** (VectorDistance, optional): The distance metric for vector comparison (default: :obj:`VectorDistance.COSINE`)
* **delete\_collection\_on\_del** (bool, optional): Flag to determine if the collection should be deleted upon object destruction. (default: :obj:`False`) \*\*kwargs (Any): Additional keyword arguments for initializing `QdrantClient`.
**Note:**
* If `url_and_api_key` is provided, it takes priority and the client
will attempt to connect to the remote Qdrant instance using the URL
endpoint.
* If `url_and_api_key` is not provided and `path` is given, the client
will use the local path to initialize Qdrant.
* If neither `url_and_api_key` nor `path` is provided, the client will
be initialized with an in-memory storage (`":memory:"`).
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
collection_name: Optional[str] = None,
url_and_api_key: Optional[Tuple[str, str]] = None,
path: Optional[str] = None,
distance: VectorDistance = VectorDistance.COSINE,
delete_collection_on_del: bool = False,
**kwargs: Any
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Deletes the collection if :obj:`del_collection` is set to
:obj:`True`.
### \_create\_client
```python theme={"system"}
def _create_client(
self,
url_and_api_key: Optional[Tuple[str, str]],
path: Optional[str],
**kwargs: Any
):
```
### \_check\_and\_create\_collection
```python theme={"system"}
def _check_and_create_collection(self):
```
### \_create\_collection
```python theme={"system"}
def _create_collection(
self,
collection_name: str,
size: int,
distance: VectorDistance = VectorDistance.COSINE,
**kwargs: Any
):
```
Creates a new collection in the database.
**Parameters:**
* **collection\_name** (str): Name of the collection to be created.
* **size** (int): Dimensionality of vectors to be stored in this collection.
* **distance** (VectorDistance, optional): The distance metric to be used for vector similarity. (default: :obj:`VectorDistance.COSINE`) \*\*kwargs (Any): Additional keyword arguments.
### \_delete\_collection
```python theme={"system"}
def _delete_collection(self, collection_name: str, **kwargs: Any):
```
Deletes an existing collection from the database.
**Parameters:**
* **collection** (str): Name of the collection to be deleted. \*\*kwargs (Any): Additional keyword arguments.
### \_collection\_exists
```python theme={"system"}
def _collection_exists(self, collection_name: str):
```
Returns whether the collection exists in the database
### \_generate\_collection\_name
```python theme={"system"}
def _generate_collection_name(self):
```
Generates a collection name if user doesn't provide
### \_get\_collection\_info
```python theme={"system"}
def _get_collection_info(self, collection_name: str):
```
Retrieves details of an existing collection.
**Parameters:**
* **collection\_name** (str): Name of the collection to be checked.
**Returns:**
Dict\[str, Any]: A dictionary containing details about the
collection.
### close\_client
```python theme={"system"}
def close_client(self, **kwargs):
```
Closes the client connection to the Qdrant storage.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs):
```
Adds a list of vectors to the specified collection.
**Parameters:**
* **vectors** (List\[VectorRecord]): List of vectors to be added. \*\*kwargs (Any): Additional keyword arguments.
### update\_payload
```python theme={"system"}
def update_payload(
self,
ids: List[str],
payload: Dict[str, Any],
**kwargs: Any
):
```
Updates the payload of the vectors identified by their IDs.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be updated.
* **payload** (Dict\[str, Any]): List of payloads to be updated. \*\*kwargs (Any): Additional keyword arguments.
### delete\_collection
```python theme={"system"}
def delete_collection(self):
```
Deletes the entire collection in the Qdrant storage.
### delete
```python theme={"system"}
def delete(
self,
ids: Optional[List[str]] = None,
payload_filter: Optional[Dict[str, Any]] = None,
**kwargs: Any
):
```
Deletes points from the collection based on either IDs or payload
filters.
**Parameters:**
* **ids** (Optional\[List\[str]], optional): List of unique identifiers for the vectors to be deleted.
* **payload\_filter** (Optional\[Dict\[str, Any]], optional): A filter for the payload to delete points matching specific conditions. If `ids` is provided, `payload_filter` will be ignored unless both are combined explicitly. \*\*kwargs (Any): Additional keyword arguments pass to `QdrantClient. delete`.
**Note:**
* If `ids` is provided, the points with these IDs will be deleted
directly, and the `payload_filter` will be ignored.
* If `ids` is not provided but `payload_filter` is, then points
matching the `payload_filter` will be deleted.
### status
```python theme={"system"}
def status(self):
```
### query
```python theme={"system"}
def query(
self,
query: VectorDBQuery,
filter_conditions: Optional[Dict[str, Any]] = None,
**kwargs: Any
):
```
Searches for similar vectors in the storage based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve.
* **filter\_conditions** (Optional\[Dict\[str, Any]], optional): A dictionary specifying conditions to filter the query results. \*\*kwargs (Any): Additional keyword arguments.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### clear
```python theme={"system"}
def clear(self):
```
Remove all vectors from the storage.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
Provides access to the underlying vector database client.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.surreal
## SurrealStorage
```python theme={"system"}
class SurrealStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` using SurrealDB,
a scalable, distributed database with WebSocket support, for
efficient vector storage and similarity search.
SurrealDB official site and documentation can be found at:
`SurrealDB `\_
**Parameters:**
* **url** (str): WebSocket URL for connecting to SurrealDB (default: "ws\://localhost:8000/rpc").
* **table** (str): Name of the table used for storing vectors (default: "vector\_store").
* **vector\_dim** (int): Dimensionality of the stored vectors.
* **distance** (VectorDistance): Distance metric used for similarity comparisons (default: VectorDistance.COSINE).
* **namespace** (str): SurrealDB namespace to use (default: "default"). (default: `"default"`)
* **database** (str): SurrealDB database name (default: "demo"). (default: `"demo"`)
* **user** (str): Username for authentication (default: "root"). (default: `"root"`)
* **password** (str): Password for authentication (default: "root"). (default: `"root"`)
**Note:**
* SurrealDB supports flexible schema and powerful querying capabilities
via SQL-like syntax over WebSocket.
* This implementation manages connection setup and ensures the target
table exists.
* Suitable for applications requiring distributed vector storage and
search with real-time updates.
### **init**
```python theme={"system"}
def __init__(self):
```
Initialize SurrealStorage with connection settings and ensure
the target table exists.
**Parameters:**
* **url** (str): WebSocket URL for connecting to SurrealDB. (default: :obj:`"ws://localhost:8000/rpc"`)
* **table** (str): Name of the table used for vector storage. (default: :obj:`"vector_store"`)
* **vector\_dim** (int): Dimensionality of the stored vectors. (default: :obj:`786`)
* **distance** (VectorDistance): Distance metric for similarity searches. (default: :obj:`VectorDistance.COSINE`)
* **namespace** (str): SurrealDB namespace to use. (default: :obj:`"default"`)
* **database** (str): SurrealDB database name. (default: :obj:`"demo"`)
* **user** (str): Username for authentication. (default: :obj:`"root"`)
* **password** (str): Password for authentication. (default: :obj:`"root"`)
### \_table\_exists
```python theme={"system"}
def _table_exists(self):
```
**Returns:**
bool: True if the table exists, False otherwise.
### \_get\_table\_info
```python theme={"system"}
def _get_table_info(self):
```
**Returns:**
Dict\[str, int]: A dictionary with 'dim' and 'count' keys.
### \_create\_table
```python theme={"system"}
def _create_table(self):
```
Define and create the vector storage table with HNSW index.
Documentation: [https://surrealdb.com/docs/surrealdb/reference-guide/](https://surrealdb.com/docs/surrealdb/reference-guide/)
vector-search#vector-search-cheat-sheet
### \_drop\_table
```python theme={"system"}
def _drop_table(self):
```
Drop the vector storage table if it exists.
### \_check\_and\_create\_table
```python theme={"system"}
def _check_and_create_table(self):
```
Check if the table exists and matches the expected vector
dimension. If not, create a new table.
### \_validate\_and\_convert\_records
```python theme={"system"}
def _validate_and_convert_records(self, records: List[VectorRecord]):
```
Validate and convert VectorRecord instances into
SurrealDB-compatible dictionaries.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to insert.
**Returns:**
List\[Dict]: Transformed list of dicts ready for insertion.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Perform a top-k similarity search using the configured distance
metric.
**Parameters:**
* **query** (VectorDBQuery): Query containing the query vector and top\_k value.
**Returns:**
List\[VectorDBQueryResult]: Ranked list of matching records
with similarity scores.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs):
```
Insert validated vector records into the SurrealDB table.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to add.
### delete
```python theme={"system"}
def delete(
self,
ids: Optional[List[str]] = None,
if_all: bool = False,
**kwargs
):
```
Delete specific records by ID or clear the entire table.
**Parameters:**
* **ids** (Optional\[List\[str]]): List of record IDs to delete.
* **if\_all** (bool): Whether to delete all records in the table.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: Object containing vector table metadata.
### clear
```python theme={"system"}
def clear(self):
```
Reset the vector table by dropping and recreating it.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
Provides access to the underlying SurrealDB client.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.tidb
## EnumEncoder
```python theme={"system"}
class EnumEncoder(JSONEncoder):
```
### default
```python theme={"system"}
def default(self, obj):
```
## TiDBStorage
```python theme={"system"}
class TiDBStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` for interacting with TiDB.
The detailed information about TiDB is available at:
`TiDB Vector Search `\_
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **url\_and\_api\_key** (Optional\[Union\[Tuple\[str, str], str]]): A tuple containing the database url and API key for connecting to a TiDB cluster. The URL should be in the format: "mysql+pymysql://``:``@``:``/``". TiDB will not use the API Key, but retains the definition for interface compatible.
* **collection\_name** (Optional\[str]): Name of the collection. The collection name will be used as the table name in TiDB. If not provided, set it to the current time with iso format. \*\*kwargs (Any): Additional keyword arguments for initializing TiDB connection.
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
collection_name: Optional[str] = None,
url_and_api_key: Optional[Union[Tuple[str, str], str]] = None,
**kwargs: Any
):
```
### \_create\_client
```python theme={"system"}
def _create_client(self, database_url: Optional[str] = None, **kwargs: Any):
```
Initializes the TiDB client with the provided connection details.
**Parameters:**
* **database\_url** (Optional\[str]): The database connection string for the TiDB server. \*\*kwargs: Additional keyword arguments passed to the TiDB client.
### \_get\_table\_model
```python theme={"system"}
def _get_table_model(self, collection_name: str):
```
### \_open\_and\_create\_table
```python theme={"system"}
def _open_and_create_table(self):
```
Opens an existing table or creates a new table in TiDB.
### \_check\_table
```python theme={"system"}
def _check_table(self):
```
Ensuring the specified table matches the specified vector
dimensionality.
### \_generate\_table\_name
```python theme={"system"}
def _generate_table_name(self):
```
**Returns:**
str: A unique, valid table name.
### \_get\_table\_info
```python theme={"system"}
def _get_table_info(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing details about the
table.
### \_validate\_and\_convert\_vectors
```python theme={"system"}
def _validate_and_convert_vectors(self, records: List[VectorRecord]):
```
Validates and converts VectorRecord instances to VectorDBRecord
instances.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to validate and convert.
**Returns:**
List\[VectorDBRecord]: A list of VectorDBRecord instances.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs):
```
Adds a list of vectors to the specified table.
**Parameters:**
* **records** (List\[VectorRecord]): List of vectors to be added. \*\*kwargs (Any): Additional keyword arguments pass to insert.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Deletes a list of vectors identified by their IDs from the
storage.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be deleted. \*\*kwargs (Any): Additional keyword arguments passed to delete.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: An object containing information about the
table's status.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Searches for similar vectors in the storage based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve. \*\*kwargs (Any): Additional keyword arguments passed to search.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### clear
```python theme={"system"}
def clear(self):
```
Removes all vectors from the TiDB table. This method
deletes the existing table and then recreates it with the same
schema to effectively remove all stored vectors.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
**Returns:**
Any: The TiDB client instance.
# null
Source: https://docs.camel-ai.org/reference/camel.storages.vectordb_storages.weaviate
## WeaviateStorage
```python theme={"system"}
class WeaviateStorage(BaseVectorStorage):
```
An implementation of the `BaseVectorStorage` for interacting with
Weaviate, a cloud-native vector search engine.
This class provides multiple ways to connect to Weaviate instances:
* Weaviate Cloud (WCD)
* Local Docker/Kubernetes instances
* Embedded Weaviate
* Custom connection parameters
**Parameters:**
* **vector\_dim** (int): The dimension of storing vectors.
* **collection\_name** (Optional\[str], optional): Name for the collection in Weaviate. If not provided, generates a unique name based on current timestamp. (default: :obj:`None`)
* **connection\_type** (ConnectionType, optional): Type of connection to use. Supported types: 'local', 'cloud', 'embedded', 'custom'. (default: :obj:`"local"`) # Weaviate Cloud parameters
* **wcd\_cluster\_url** (Optional\[str], optional): Weaviate Cloud cluster URL. Required when connection\_type='cloud'.
* **wcd\_api\_key** (Optional\[str], optional): Weaviate Cloud API key. Required when connection\_type='cloud'. # Local instance parameters
* **local\_host** (str, optional): Local Weaviate host. (default: :obj:`"localhost"`)
* **local\_port** (int, optional): Local Weaviate HTTP port. (default: :obj:`8080`)
* **local\_grpc\_port** (int, optional): Local Weaviate gRPC port. (default: :obj:`50051`)
* **local\_auth\_credentials** (Optional\[Union\[str, Any]], optional): Authentication credentials for local instance. Can be an API key string or Auth object. (default: :obj:`None`) # Embedded Weaviate parameters
* **embedded\_hostname** (str, optional): Embedded instance hostname. (default: :obj:`"127.0.0.1"`)
* **embedded\_port** (int, optional): Embedded instance HTTP port. (default: :obj:`8079`)
* **embedded\_grpc\_port** (int, optional): Embedded instance gRPC port. (default: :obj:`50050`)
* **embedded\_version** (Optional\[str], optional): Weaviate version for embedded instance. If None, uses the default version. (default: :obj:`None`)
* **embedded\_persistence\_data\_path** (Optional\[str], optional): Directory for embedded database files. (default: :obj:`None`)
* **embedded\_binary\_path** (Optional\[str], optional): Directory for Weaviate binary. (default: :obj:`None`)
* **embedded\_environment\_variables** (Optional\[Dict\[str, str]], optional): Environment variables for embedded instance. (default: :obj:`None`) # Custom connection parameters
* **custom\_http\_host** (Optional\[str], optional): Custom HTTP host.
* **custom\_http\_port** (Optional\[int], optional): Custom HTTP port.
* **custom\_http\_secure** (Optional\[bool], optional): Use HTTPS.
* **custom\_grpc\_host** (Optional\[str], optional): Custom gRPC host.
* **custom\_grpc\_port** (Optional\[int], optional): Custom gRPC port.
* **custom\_grpc\_secure** (Optional\[bool], optional): Use secure gRPC.
* **custom\_auth\_credentials** (Optional\[Any], optional): Custom auth. # Vector index configuration parameters
* **vector\_index\_type** (VectorIndexType, optional): Vector index type. Supported types: 'hnsw', 'flat'. (default: :obj:`"hnsw"`)
* **distance\_metric** (DistanceMetric, optional): Distance metric for vector similarity. Supported metrics: 'cosine', 'dot', 'l2-squared', 'hamming', 'manhattan'. (default: :obj:`"cosine"`) # Common parameters for all connection types
* **headers** (Optional\[Dict\[str, str]], optional): Additional headers for third-party API keys (e.g., OpenAI, Cohere). (default: :obj:`None`)
* **additional\_config** (Optional\[Any], optional): Advanced configuration options like timeouts. (default: :obj:`None`)
* **skip\_init\_checks** (bool, optional): Skip initialization checks. (default: :obj:`False`)
**Note:**
This implementation supports synchronous operations only.
The client connection is automatically handled and closed when the
storage instance is destroyed.
### **init**
```python theme={"system"}
def __init__(
self,
vector_dim: int,
collection_name: Optional[str] = None,
connection_type: ConnectionType = 'local',
wcd_cluster_url: Optional[str] = None,
wcd_api_key: Optional[str] = None,
local_host: str = 'localhost',
local_port: int = 8080,
local_grpc_port: int = 50051,
local_auth_credentials: Optional[Union[str, Any]] = None,
embedded_hostname: str = '127.0.0.1',
embedded_port: int = 8079,
embedded_grpc_port: int = 50050,
embedded_version: Optional[str] = None,
embedded_persistence_data_path: Optional[str] = None,
embedded_binary_path: Optional[str] = None,
embedded_environment_variables: Optional[Dict[str, str]] = None,
custom_http_host: Optional[str] = None,
custom_http_port: Optional[int] = None,
custom_http_secure: Optional[bool] = None,
custom_grpc_host: Optional[str] = None,
custom_grpc_port: Optional[int] = None,
custom_grpc_secure: Optional[bool] = None,
custom_auth_credentials: Optional[Any] = None,
vector_index_type: VectorIndexType = 'hnsw',
distance_metric: DistanceMetric = 'cosine',
headers: Optional[Dict[str, str]] = None,
additional_config: Optional[Any] = None,
skip_init_checks: bool = False,
**kwargs: Any
):
```
### \_get\_connection\_client
```python theme={"system"}
def _get_connection_client(self):
```
Get Weaviate client based on connection type and user settings.
### \_create\_cloud\_client
```python theme={"system"}
def _create_cloud_client(self, weaviate_module: Any):
```
Create a Weaviate Cloud client.
### \_create\_local\_client
```python theme={"system"}
def _create_local_client(self, weaviate_module: Any):
```
Create a local Weaviate client.
### \_create\_embedded\_client
```python theme={"system"}
def _create_embedded_client(self, weaviate_module: Any):
```
Create an embedded Weaviate client.
### \_create\_custom\_client
```python theme={"system"}
def _create_custom_client(self, weaviate_module: Any):
```
Create a custom Weaviate client.
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up client connection.
### close
```python theme={"system"}
def close(self):
```
Explicitly close the client connection.
### \_generate\_collection\_name
```python theme={"system"}
def _generate_collection_name(self):
```
Generate a collection name if user doesn't provide one.
### \_check\_and\_create\_collection
```python theme={"system"}
def _check_and_create_collection(self, **kwargs: Any):
```
Check if collection exists and create if it doesn't.
### \_collection\_exists
```python theme={"system"}
def _collection_exists(self, collection_name: str):
```
Check if the collection exists.
### \_get\_vector\_index\_config
```python theme={"system"}
def _get_vector_index_config(self, **kwargs: Any):
```
Get vector index configuration based on user settings.
### \_create\_collection
```python theme={"system"}
def _create_collection(self, **kwargs: Any):
```
Create a new collection in Weaviate.
### add
```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs: Any):
```
Saves a list of vector records to the storage.
**Parameters:**
* **records** (List\[VectorRecord]): List of vector records to be saved. \*\*kwargs (Any): Additional keyword arguments.
### delete
```python theme={"system"}
def delete(self, ids: List[str], **kwargs: Any):
```
Deletes a list of vectors identified by their IDs from the storage.
**Parameters:**
* **ids** (List\[str]): List of unique identifiers for the vectors to be deleted. \*\*kwargs (Any): Additional keyword arguments.
### \_calculate\_similarity\_from\_distance
```python theme={"system"}
def _calculate_similarity_from_distance(self, distance: Optional[float]):
```
Calculate similarity score based on distance metric.
**Parameters:**
* **distance** (Optional\[float]): The distance value from Weaviate.
**Returns:**
float: Normalized similarity score between 0 and 1.
### status
```python theme={"system"}
def status(self):
```
**Returns:**
VectorDBStatus: The vector database status.
### query
```python theme={"system"}
def query(self, query: VectorDBQuery, **kwargs: Any):
```
Searches for similar vectors in the storage based on the provided
query.
**Parameters:**
* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve. \*\*kwargs (Any): Additional keyword arguments.
**Returns:**
List\[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
### clear
```python theme={"system"}
def clear(self):
```
Remove all vectors from the storage.
### load
```python theme={"system"}
def load(self):
```
Load the collection hosted on cloud service.
### client
```python theme={"system"}
def client(self):
```
Provides access to the underlying vector database client.
# null
Source: https://docs.camel-ai.org/reference/camel.tasks.task
## TaskValidationMode
```python theme={"system"}
class TaskValidationMode(Enum):
```
Validation modes for different use cases.
## validate\_task\_content
```python theme={"system"}
def validate_task_content(
content: str,
task_id: str = 'unknown',
min_length: int = 1,
mode: TaskValidationMode = TaskValidationMode.INPUT,
check_failure_patterns: bool = True
):
```
Unified validation for task content and results to avoid silent
failures. Performs comprehensive checks to ensure content meets quality
standards.
**Parameters:**
* **content** (str): The task content or result to validate.
* **task\_id** (str): Task ID for logging purposes. (default: :obj:`"unknown"`)
* **min\_length** (int): Minimum content length after stripping whitespace. (default: :obj:`1`)
* **mode** (TaskValidationMode): Validation mode - INPUT for task content, OUTPUT for task results. (default: :obj:`TaskValidationMode.INPUT`)
* **check\_failure\_patterns** (bool): Whether to check for failure indicators in the content. Only effective in OUTPUT mode. (default: :obj:`True`)
**Returns:**
bool: True if content passes validation, False otherwise.
## is\_task\_result\_insufficient
```python theme={"system"}
def is_task_result_insufficient(task: 'Task'):
```
Check if a task result is insufficient and should be treated as failed.
This is a convenience wrapper around validate\_task\_content for backward
compatibility and semantic clarity when checking task results.
**Parameters:**
* **task** (Task): The task to check.
**Returns:**
bool: True if the result is insufficient, False otherwise.
## parse\_response
```python theme={"system"}
def parse_response(response: str, task_id: Optional[str] = None):
```
Parse Tasks from a response.
**Parameters:**
* **response** (str): The model response.
* **task\_id** (str, optional): a parent task id, the default value is "0"
**Returns:**
List\[Task]: A list of tasks which is :obj:`Task` instance.
## TaskState
```python theme={"system"}
class TaskState(str, Enum):
```
### states
```python theme={"system"}
def states(cls):
```
## Task
```python theme={"system"}
class Task(BaseModel):
```
Task is specific assignment that can be passed to a agent.
**Parameters:**
* **content** (str): string content for task.
* **id** (str): An unique string identifier for the task. This should ideally be provided by the provider/model which created the task. (default: :obj:`uuid.uuid4()`)
* **state** (TaskState): The state which should be OPEN, RUNNING, DONE or DELETED. (default: :obj:`TaskState.FAILED`)
* **type** (Optional\[str]): task type. (default: :obj:`None`)
* **parent** (Optional\[Task]): The parent task, None for root task. (default: :obj:`None`)
* **subtasks** (List\[Task]): The childrent sub-tasks for the task. (default: :obj:`[]`)
* **result** (Optional\[str]): The answer for the task. (default: :obj:`""`)
* **failure\_count** (int): The failure count for the task. (default: :obj:`0`)
* **assigned\_worker\_id** (Optional\[str]): The ID of the worker assigned to this task. (default: :obj:`None`)
* **dependencies** (List\[Task]): The dependencies for the task. (default: :obj:`[]`)
* **additional\_info** (Optional\[Dict\[str, Any]]): Additional information for the task. (default: :obj:`None`)
* **image\_list** (Optional\[List\[Union\[Image.Image, str]]]): Optional list of PIL Image objects or image URLs (strings) associated with the task. (default: :obj:`None`)
* **image\_detail** (`Literal["auto", "low", "high"]`): Detail level of the images associated with the task. (default: :obj:`auto`)
* **video\_bytes** (Optional\[bytes]): Optional bytes of a video associated with the task. (default: :obj:`None`)
* **video\_detail** (`Literal["auto", "low", "high"]`): Detail level of the videos associated with the task. (default: :obj:`auto`)
### **repr**
```python theme={"system"}
def __repr__(self):
```
Return a string representation of the task.
### from\_message
```python theme={"system"}
def from_message(cls, message: BaseMessage):
```
Create a task from a message.
**Parameters:**
* **message** (BaseMessage): The message to the task.
**Returns:**
Task
### to\_message
```python theme={"system"}
def to_message():
```
Convert a Task to a Message.
### reset
```python theme={"system"}
def reset(self):
```
Reset Task to initial state.
### update\_result
```python theme={"system"}
def update_result(self, result: str):
```
Set task result and mark the task as DONE.
**Parameters:**
* **result** (str): The task result.
### set\_id
```python theme={"system"}
def set_id(self, id: str):
```
Set the id of the task.
**Parameters:**
* **id** (str): The id of the task.
### set\_state
```python theme={"system"}
def set_state(self, state: TaskState):
```
Recursively set the state of the task and its subtasks.
**Parameters:**
* **state** (TaskState): The giving state.
### add\_subtask
```python theme={"system"}
def add_subtask(self, task: 'Task'):
```
Add a subtask to the current task.
**Parameters:**
* **task** (Task): The subtask to be added.
### remove\_subtask
```python theme={"system"}
def remove_subtask(self, id: str):
```
Remove a subtask from the current task.
**Parameters:**
* **id** (str): The id of the subtask to be removed.
### get\_running\_task
```python theme={"system"}
def get_running_task(self):
```
Get RUNNING task.
### to\_string
```python theme={"system"}
def to_string(self, indent: str = '', state: bool = False):
```
Convert task to a string.
**Parameters:**
* **indent** (str): The ident for hierarchical tasks.
* **state** (bool): Include or not task state.
**Returns:**
str: The printable task string.
### get\_result
```python theme={"system"}
def get_result(self, indent: str = ''):
```
Get task result to a string.
**Parameters:**
* **indent** (str): The ident for hierarchical tasks.
**Returns:**
str: The printable task string.
### decompose
```python theme={"system"}
def decompose(
self,
agent: 'ChatAgent',
prompt: Optional[str] = None,
task_parser: Callable[[str, str], List['Task']] = parse_response,
stream_callback: Optional[Callable[['ChatAgentResponse'], None]] = None
):
```
Decompose a task to a list of sub-tasks. Automatically detects
streaming or non-streaming based on agent configuration.
**Parameters:**
* **agent** (ChatAgent): An agent that used to decompose the task.
* **prompt** (str, optional): A prompt to decompose the task. If not provided, the default prompt will be used.
* **task\_parser** (Callable\[\[str, str], List\[Task]], optional): A function to extract Task from response. If not provided, the default parse\_response will be used.
* **stream\_callback** (Callable\[\[ChatAgentResponse], None], optional): A callback function that receives each chunk (ChatAgentResponse) during streaming. This allows tracking the decomposition progress in real-time.
**Returns:**
Union\[List\[Task], Generator\[List\[Task], None, None]]: If agent is
configured for streaming, returns a generator that yields lists
of new tasks as they are parsed. Otherwise returns a list of
all tasks.
### \_decompose\_streaming
```python theme={"system"}
def _decompose_streaming(
self,
response: Iterable,
task_parser: Callable[[str, str], List['Task']],
stream_callback: Optional[Callable[['ChatAgentResponse'], None]] = None
):
```
Handle streaming response for task decomposition.
**Parameters:**
* **response**: Streaming response from agent
* **task\_parser**: Function to parse tasks from response
* **stream\_callback** (Callable\[\[ChatAgentResponse], None], optional): A callback function that receives each chunk (ChatAgentResponse) during streaming.
* **Yields**: List\[Task]: New tasks as they are parsed from streaming response
### \_decompose\_non\_streaming
```python theme={"system"}
def _decompose_non_streaming(self, response, task_parser: Callable[[str, str], List['Task']]):
```
Handle non-streaming response for task decomposition.
**Parameters:**
* **response**: Regular response from agent
* **task\_parser**: Function to parse tasks from response
**Returns:**
List\[Task]: All parsed tasks
### \_parse\_partial\_tasks
```python theme={"system"}
def _parse_partial_tasks(self, response: str):
```
Parse tasks from potentially incomplete response.
**Parameters:**
* **response**: Partial response content
**Returns:**
List\[Task]: Tasks parsed from complete ```` blocks
### compose
```python theme={"system"}
def compose(
self,
agent: 'ChatAgent',
template: TextPrompt = TASK_COMPOSE_PROMPT,
result_parser: Optional[Callable[[str], str]] = None
):
```
compose task result by the sub-tasks.
**Parameters:**
* **agent** (ChatAgent): An agent that used to compose the task result.
* **template** (TextPrompt, optional): The prompt template to compose task. If not provided, the default template will be used.
* **result\_parser** (Callable\[\[str, str], List\[Task]], optional): A function to extract Task from response.
### get\_depth
```python theme={"system"}
def get_depth(self):
```
Get current task depth.
## TaskManager
```python theme={"system"}
class TaskManager:
```
TaskManager is used to manage tasks.
**Parameters:**
* **task** (Task): The root Task.
### **init**
```python theme={"system"}
def __init__(self, task: Task):
```
### gen\_task\_id
```python theme={"system"}
def gen_task_id(self):
```
Generate a new task id.
### exist
```python theme={"system"}
def exist(self, task_id: str):
```
Check if a task with the given id exists.
### current\_task
```python theme={"system"}
def current_task(self):
```
Get the current task.
### topological\_sort
```python theme={"system"}
def topological_sort(tasks: List[Task]):
```
Sort a list of tasks by topological way.
**Parameters:**
* **tasks** (List\[Task]): The giving list of tasks.
**Returns:**
The sorted list of tasks.
### set\_tasks\_dependence
```python theme={"system"}
def set_tasks_dependence(
root: Task,
others: List[Task],
type: Literal['serial', 'parallel'] = 'parallel'
):
```
Set relationship between root task and other tasks.
Two relationships are currently supported: serial and parallel.
`serial` : root -> other1 -> other2
`parallel`: root -> other1
-> other2
**Parameters:**
* **root** (Task): A root task.
* **others** (List\[Task]): A list of tasks.
### add\_tasks
```python theme={"system"}
def add_tasks(self, tasks: Union[Task, List[Task]]):
```
self.tasks and self.task\_map will be updated by the input tasks.
### evolve
```python theme={"system"}
def evolve(
self,
task: Task,
agent: 'ChatAgent',
template: Optional[TextPrompt] = None,
task_parser: Optional[Callable[[str, str], List[Task]]] = None
):
```
Evolve a task to a new task.
Evolve is only used for data generation.
**Parameters:**
* **task** (Task): A given task.
* **agent** (ChatAgent): An agent that used to evolve the task.
* **template** (TextPrompt, optional): A prompt template to evolve task. If not provided, the default template will be used.
* **task\_parser** (Callable, optional): A function to extract Task from response. If not provided, the default parser will be used.
**Returns:**
Task: The created :obj:`Task` instance or None.
# null
Source: https://docs.camel-ai.org/reference/camel.terminators.base
## BaseTerminator
```python theme={"system"}
class BaseTerminator(ABC):
```
Base class for terminators.
### **init**
```python theme={"system"}
def __init__(self, *args, **kwargs):
```
### is\_terminated
```python theme={"system"}
def is_terminated(self, *args, **kwargs):
```
### reset
```python theme={"system"}
def reset(self):
```
## ResponseTerminator
```python theme={"system"}
class ResponseTerminator(BaseTerminator):
```
A terminator that terminates the conversation based on the response.
### is\_terminated
```python theme={"system"}
def is_terminated(self, messages: List[BaseMessage]):
```
### reset
```python theme={"system"}
def reset(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.terminators.response_terminator
## ResponseWordsTerminator
```python theme={"system"}
class ResponseWordsTerminator(ResponseTerminator):
```
Terminate agent when some words reached to occurrence
limit by any message of the response.
**Parameters:**
* **words\_dict** (dict): Dictionary of words and its occurrence threshold.
* **case\_sensitive** (bool): Whether count the words as case-sensitive. (default: :obj:`False`)
* **mode** (TerminationMode): Whether terminate agent if any or all pre-set words reached the threshold. (default: :obj:`TerminationMode.ANY`)
### **init**
```python theme={"system"}
def __init__(
self,
words_dict: Dict[str, int],
case_sensitive: bool = False,
mode: TerminationMode = TerminationMode.ANY
):
```
### \_validate
```python theme={"system"}
def _validate(self):
```
### is\_terminated
```python theme={"system"}
def is_terminated(self, messages: List[BaseMessage]):
```
Whether terminate the agent by checking the occurrence
of specified words reached to preset thresholds.
**Parameters:**
* **messages** (list): List of :obj:`BaseMessage` from a response.
**Returns:**
tuple: A tuple containing whether the agent should be
terminated and a string of termination reason.
### reset
```python theme={"system"}
def reset(self):
```
Reset the terminator.
# null
Source: https://docs.camel-ai.org/reference/camel.terminators.token_limit_terminator
## TokenLimitTerminator
```python theme={"system"}
class TokenLimitTerminator(BaseTerminator):
```
Terminate agent if number of tokens reached to token limit threshold.
**Parameters:**
* **token\_limit** (int): Token limit threshold.
### **init**
```python theme={"system"}
def __init__(self, token_limit: int):
```
### \_validate
```python theme={"system"}
def _validate(self):
```
### is\_terminated
```python theme={"system"}
def is_terminated(self, num_tokens: int):
```
Whether terminate the agent by checking number of
used tokens reached to token limit.
**Parameters:**
* **num\_tokens** (int): Number of tokens.
**Returns:**
tuple: A tuple containing whether the agent should be
terminated and a string of termination reason.
### reset
```python theme={"system"}
def reset(self):
```
Reset the terminator.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.aci_toolkit
## ACIToolkit
```python theme={"system"}
class ACIToolkit(BaseToolkit):
```
A toolkit for interacting with the ACI API.
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
base_url: Optional[str] = None,
linked_account_owner_id: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initialize the ACI toolkit.
**Parameters:**
* **api\_key** (Optional\[str]): The API key for authentication. (default: :obj:`None`)
* **base\_url** (Optional\[str]): The base URL for the ACI API. (default: :obj:`None`)
* **linked\_account\_owner\_id** (Optional\[str]): ID of the owner of the linked account, e.g., "johndoe" (default: :obj:`None`)
* **timeout** (Optional\[float]): Request timeout. (default: :obj:`None`)
### search\_tool
```python theme={"system"}
def search_tool(
self,
intent: Optional[str] = None,
allowed_app_only: bool = True,
include_functions: bool = False,
categories: Optional[List[str]] = None,
limit: Optional[int] = 10,
offset: Optional[int] = 0
):
```
Search for apps based on intent.
**Parameters:**
* **intent** (Optional\[str]): Search results will be sorted by relevance to this intent. (default: :obj:`None`)
* **allowed\_app\_only** (bool): If true, only return apps that are allowed by the agent/accessor, identified by the api key. (default: :obj:`True`)
* **include\_functions** (bool): If true, include functions (name and description) in the search results. (default: :obj:`False`)
* **categories** (Optional\[List\[str]]): List of categories to filter the search results. Defaults to an empty list. (default: :obj:`None`)
* **limit** (Optional\[int]): Maximum number of results to return. (default: :obj:`10`)
* **offset** (Optional\[int]): Offset for pagination. (default: :obj:`0`)
**Returns:**
Optional\[List\[AppBasic]]: List of matching apps if successful,
error message otherwise.
### list\_configured\_apps
```python theme={"system"}
def list_configured_apps(
self,
app_names: Optional[List[str]] = None,
limit: Optional[int] = 10,
offset: Optional[int] = 0
):
```
List all configured apps.
**Parameters:**
* **app\_names** (Optional\[List\[str]]): List of app names to filter the results. (default: :obj:`None`)
* **limit** (Optional\[int]): Maximum number of results to return. (default: :obj:`10`)
* **offset** (Optional\[int]): Offset for pagination. (default: :obj:`0`) (default: 0)
**Returns:**
Union\[List\[AppConfiguration], str]: List of configured apps if
successful, error message otherwise.
### configure\_app
```python theme={"system"}
def configure_app(self, app_name: str):
```
Configure an app with specified authentication type.
**Parameters:**
* **app\_name** (str): Name of the app to configure.
**Returns:**
Union\[Dict, str]: Configuration result or error message.
### get\_app\_configuration
```python theme={"system"}
def get_app_configuration(self, app_name: str):
```
Get app configuration by app name.
**Parameters:**
* **app\_name** (str): Name of the app to get configuration for.
**Returns:**
Union\[AppConfiguration, str]: App configuration if successful,
error message otherwise.
### delete\_app
```python theme={"system"}
def delete_app(self, app_name: str):
```
Delete an app configuration.
**Parameters:**
* **app\_name** (str): Name of the app to delete.
**Returns:**
Optional\[str]: None if successful, error message otherwise.
### link\_account
```python theme={"system"}
def link_account(self, app_name: str):
```
Link an account to a configured app.
**Parameters:**
* **app\_name** (str): Name of the app to link the account to.
**Returns:**
Union\[LinkedAccount, str]: LinkedAccount object if successful,
error message otherwise.
### get\_app\_details
```python theme={"system"}
def get_app_details(self, app_name: str):
```
Get details of an app.
**Parameters:**
* **app\_name** (str): Name of the app to get details for.
**Returns:**
AppDetails: App details.
### get\_linked\_accounts
```python theme={"system"}
def get_linked_accounts(self, app_name: str):
```
List all linked accounts for a specific app.
**Parameters:**
* **app\_name** (str): Name of the app to get linked accounts for.
**Returns:**
Union\[List\[LinkedAccount], str]: List of linked accounts if
successful, error message otherwise.
### enable\_linked\_account
```python theme={"system"}
def enable_linked_account(self, linked_account_id: str):
```
Enable a linked account.
**Parameters:**
* **linked\_account\_id** (str): ID of the linked account to enable.
**Returns:**
Union\[LinkedAccount, str]: Linked account if successful, error
message otherwise.
### disable\_linked\_account
```python theme={"system"}
def disable_linked_account(self, linked_account_id: str):
```
Disable a linked account.
**Parameters:**
* **linked\_account\_id** (str): ID of the linked account to disable.
**Returns:**
Union\[LinkedAccount, str]: The updated linked account if
successful, error message otherwise.
### delete\_linked\_account
```python theme={"system"}
def delete_linked_account(self, linked_account_id: str):
```
Delete a linked account.
**Parameters:**
* **linked\_account\_id** (str): ID of the linked account to delete.
**Returns:**
str: Success message if successful, error message otherwise.
### function\_definition
```python theme={"system"}
def function_definition(self, func_name: str):
```
Get the function definition for an app.
**Parameters:**
* **app\_name** (str): Name of the app to get function definition for
**Returns:**
Dict: Function definition dictionary.
### search\_function
```python theme={"system"}
def search_function(
self,
app_names: Optional[List[str]] = None,
intent: Optional[str] = None,
allowed_apps_only: bool = True,
limit: Optional[int] = 10,
offset: Optional[int] = 0
):
```
Search for functions based on intent.
**Parameters:**
* **app\_names** (Optional\[List\[str]]): List of app names to filter the search results. (default: :obj:`None`)
* **intent** (Optional\[str]): The search query/intent. (default: :obj:`None`)
* **allowed\_apps\_only** (bool): If true, only return functions from allowed apps. (default: :obj:`True`)
* **limit** (Optional\[int]): Maximum number of results to return. (default: :obj:`10`)
* **offset** (Optional\[int]): Offset for pagination. (default: :obj:`0`)
**Returns:**
List\[Dict]: List of matching functions
### execute\_function
```python theme={"system"}
def execute_function(
self,
function_name: str,
function_arguments: Dict,
linked_account_owner_id: str,
allowed_apps_only: bool = False
):
```
Execute a function call.
**Parameters:**
* **function\_name** (str): Name of the function to execute.
* **function\_arguments** (Dict): Arguments to pass to the function.
* **linked\_account\_owner\_id** (str): To specify the end-user (account owner) on behalf of whom you want to execute functions You need to first link corresponding account with the same owner id in the ACI dashboard ([https://platform.aci.dev](https://platform.aci.dev)).
* **allowed\_apps\_only** (bool): If true, only returns functions/apps that are allowed to be used by the agent/accessor, identified by the api key. (default: :obj:`False`)
**Returns:**
Dict: Result of the function execution
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of FunctionTool objects representing
available functions
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.artifact_toolkit
## ArtifactToolkit
```python theme={"system"}
class ArtifactToolkit(BaseToolkit):
```
A toolkit for creating and managing artifacts like HTML, SVG, charts, and diagrams.
This toolkit enables agents to generate visual content that can be previewed
in the CAMEL web application, similar to Claude's artifact system.
Supported artifact types:
* HTML documents
* SVG graphics
* Mermaid flowcharts and diagrams
* Code snippets (with syntax highlighting)
* Markdown documents
* LaTeX math expressions
### \_generate\_artifact\_id
```python theme={"system"}
def _generate_artifact_id(self, artifact_type: str):
```
Generate a unique artifact ID with microsecond precision.
### create\_html\_artifact
```python theme={"system"}
def create_html_artifact(
self,
content: str,
title: str = 'HTML Artifact',
include_css: bool = True,
css_styles: Optional[str] = None
):
```
Create an HTML artifact that can be rendered in the web interface.
**Parameters:**
* **content** (str): The HTML content to be displayed.
* **title** (str, optional): Title for the artifact. Defaults to "HTML Artifact". (default: `"HTML Artifact"`)
* **include\_css** (bool, optional): Whether to include basic CSS styling. Defaults to True. (default: True)
* **css\_styles** (str, optional): Additional CSS styles to include.
**Returns:**
Dict\[str, Any]: A dictionary containing the artifact data with metadata.
### \_wrap\_html\_content
```python theme={"system"}
def _wrap_html_content(
self,
content: str,
title: str,
include_css: bool,
css_styles: Optional[str]
):
```
Wrap content in a complete HTML document with optional styling.
### \_create\_html\_document
```python theme={"system"}
def _create_html_document(
self,
title: str,
body_content: str,
head_content: str = '',
body_class: str = ''
):
```
Create a complete HTML document with consistent structure.
### \_get\_base\_styles
```python theme={"system"}
def _get_base_styles(self):
```
Get base CSS styles used across all artifacts.
### create\_svg\_artifact
```python theme={"system"}
def create_svg_artifact(
self,
svg_content: str,
title: str = 'SVG Graphic',
width: Optional[int] = None,
height: Optional[int] = None
):
```
Create an SVG artifact for vector graphics.
**Parameters:**
* **svg\_content** (str): The SVG content (can be just the inner elements or complete SVG).
* **title** (str, optional): Title for the artifact. Defaults to "SVG Graphic". (default: `"SVG Graphic"`)
* **width** (int, optional): Width of the SVG. If not provided, uses SVG's viewBox or defaults.
* **height** (int, optional): Height of the SVG. If not provided, uses SVG's viewBox or defaults.
**Returns:**
Dict\[str, Any]: A dictionary containing the SVG artifact data.
### create\_mermaid\_flowchart
```python theme={"system"}
def create_mermaid_flowchart(
self,
flowchart_definition: str,
title: str = 'Flowchart',
direction: str = 'TD'
):
```
Create a Mermaid flowchart artifact.
**Parameters:**
* **flowchart\_definition** (str): The Mermaid flowchart definition.
* **title** (str, optional): Title for the flowchart. Defaults to "Flowchart". (default: `"Flowchart"`)
* **direction** (str, optional): Flow direction (TD, LR, BT, RL). Defaults to "TD". (default: `"TD"`)
**Returns:**
Dict\[str, Any]: A dictionary containing the Mermaid flowchart data.
### create\_code\_artifact
```python theme={"system"}
def create_code_artifact(
self,
code: str,
language: str = 'python',
title: str = 'Code Snippet',
show_line_numbers: bool = True,
theme: str = 'github'
):
```
Create a code artifact with syntax highlighting.
**Parameters:**
* **code** (str): The source code content.
* **language** (str, optional): Programming language for syntax highlighting. Defaults to "python". (default: `"python"`)
* **title** (str, optional): Title for the code artifact. Defaults to "Code Snippet". (default: `"Code Snippet"`)
* **show\_line\_numbers** (bool, optional): Whether to show line numbers. Defaults to True. (default: True)
* **theme** (str, optional): Syntax highlighting theme. Defaults to "github". (default: `"github"`)
**Returns:**
Dict\[str, Any]: A dictionary containing the code artifact data.
### create\_markdown\_artifact
```python theme={"system"}
def create_markdown_artifact(
self,
markdown_content: str,
title: str = 'Document',
include_toc: bool = False,
theme: str = 'github'
):
```
Create a Markdown document artifact with rendering.
**Parameters:**
* **markdown\_content** (str): The Markdown content.
* **title** (str, optional): Title for the document. Defaults to "Document". (default: `"Document"`)
* **include\_toc** (bool, optional): Whether to include a table of contents. Defaults to False. (default: False)
* **theme** (str, optional): Styling theme for the document. Defaults to "github". (default: `"github"`)
**Returns:**
Dict\[str, Any]: A dictionary containing the Markdown artifact data.
### create\_latex\_math
```python theme={"system"}
def create_latex_math(
self,
latex_expression: str,
title: str = 'Mathematical Expression',
display_mode: str = 'block',
show_source: bool = False
):
```
Create a LaTeX mathematical expression artifact.
**Parameters:**
* **latex\_expression** (str): The LaTeX mathematical expression.
* **title** (str, optional): Title for the math artifact. Defaults to "Mathematical Expression". (default: `"Mathematical Expression"`)
* **display\_mode** (str, optional): Display mode - "block" for centered equations, "inline" for text-style. Defaults to "block". (default: `"block"`)
* **show\_source** (bool, optional): Whether to show the LaTeX source code. Defaults to False. (default: False)
**Returns:**
Dict\[str, Any]: A dictionary containing the LaTeX math artifact data.
### get\_artifact\_info
```python theme={"system"}
def get_artifact_info(self, artifact: Dict[str, Any]):
```
Get formatted information about an artifact.
**Parameters:**
* **artifact** (Dict\[str, Any]): The artifact dictionary.
**Returns:**
str: Formatted information about the artifact.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.arxiv_toolkit
## ArxivToolkit
```python theme={"system"}
class ArxivToolkit(BaseToolkit):
```
A toolkit for interacting with the arXiv API to search and download
academic papers.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the ArxivToolkit and sets up the arXiv client.
### \_get\_search\_results
```python theme={"system"}
def _get_search_results(
self,
query: str,
paper_ids: Optional[List[str]] = None,
max_results: Optional[int] = 5
):
```
Retrieves search results from the arXiv API based on the provided
query and optional paper IDs.
**Parameters:**
* **query** (str): The search query string used to search for papers on arXiv.
* **paper\_ids** (List\[str], optional): A list of specific arXiv paper IDs to search for. (default: :obj:`None`)
* **max\_results** (int, optional): The maximum number of search results to retrieve. (default: :obj:`5`)
**Returns:**
Generator: A generator that yields results from the arXiv search
query, which includes metadata about each paper matching the
query.
### search\_papers
```python theme={"system"}
def search_papers(
self,
query: str,
paper_ids: Optional[List[str]] = None,
max_results: Optional[int] = 5
):
```
Searches for academic papers on arXiv using a query string and
optional paper IDs.
**Parameters:**
* **query** (str): The search query string.
* **paper\_ids** (List\[str], optional): A list of specific arXiv paper IDs to search for. (default: :obj:`None`)
* **max\_results** (int, optional): The maximum number of search results to return. (default: :obj:`5`)
**Returns:**
List\[Dict\[str, str]]: A list of dictionaries, each containing
information about a paper, including title, published date,
authors, entry ID, summary, and extracted text from the paper.
### download\_papers
```python theme={"system"}
def download_papers(
self,
query: str,
paper_ids: Optional[List[str]] = None,
max_results: Optional[int] = 5,
output_dir: Optional[str] = './'
):
```
Downloads PDFs of academic papers from arXiv based on the provided
query.
**Parameters:**
* **query** (str): The search query string.
* **paper\_ids** (List\[str], optional): A list of specific arXiv paper IDs to download. (default: :obj:`None`)
* **max\_results** (int, optional): The maximum number of search results to download. (default: :obj:`5`)
* **output\_dir** (str, optional): The directory to save the downloaded PDFs. Defaults to the current directory.
**Returns:**
str: Status message indicating success or failure.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.ask_news_toolkit
## \_process\_response
```python theme={"system"}
def _process_response(response, return_type: str):
```
Process the response based on the specified return type.
This helper method processes the API response and returns the content
in the specified format, which could be a string, a dictionary, or
both.
**Parameters:**
* **response**: The response object returned by the API call.
* **return\_type** (str): Specifies the format of the return value. It can be "string" to return the response as a string, "dicts" to return it as a dictionary, or "both" to return both formats as a tuple.
**Returns:**
Union\[str, dict, Tuple\[str, dict]]: The processed response,
formatted according to the return\_type argument. If "string",
returns the response as a string. If "dicts", returns the
response as a dictionary. If "both", returns a tuple
containing both formats.
**Raises:**
* **ValueError**: If the return\_type provided is invalid.
## AskNewsToolkit
```python theme={"system"}
class AskNewsToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with the AskNews API.
This class provides methods for fetching news, stories, and other content
based on user queries using the AskNews API.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the AskNewsToolkit with API clients.The API keys and
credentials are retrieved from environment variables.
### get\_news
```python theme={"system"}
def get_news(
self,
query: str,
n_articles: int = 10,
return_type: Literal['string', 'dicts', 'both'] = 'string',
method: Literal['nl', 'kw'] = 'kw'
):
```
Fetch news or stories based on a user query.
**Parameters:**
* **query** (str): The search query for fetching relevant news.
* **n\_articles** (int): Number of articles to include in the response. (default: :obj:`10`)
* **return\_type** (`Literal["string", "dicts", "both"]`): The format of the return value. (default: :obj:`"string"`)
* **method** (`Literal["nl", "kw"]`): The search method, either "nl" for natural language or "kw" for keyword search. (default: :obj:`"kw"`)
**Returns:**
Union\[str, dict, Tuple\[str, dict]]: A string, dictionary,
or both containing the news or story content, or error message
if the process fails.
### get\_stories
```python theme={"system"}
def get_stories(
self,
query: str,
categories: List[Literal['Politics', 'Economy', 'Finance', 'Science', 'Technology', 'Sports', 'Climate', 'Environment', 'Culture', 'Entertainment', 'Business', 'Health', 'International']],
reddit: int = 3,
expand_updates: bool = True,
max_updates: int = 2,
max_articles: int = 10
):
```
Fetch stories based on the provided parameters.
**Parameters:**
* **query** (str): The search query for fetching relevant stories.
* **categories** (list): The categories to filter stories by.
* **reddit** (int): Number of Reddit threads to include. (default: :obj:`3`)
* **expand\_updates** (bool): Whether to include detailed updates. (default: :obj:`True`)
* **max\_updates** (int): Maximum number of recent updates per story. (default: :obj:`2`)
* **max\_articles** (int): Maximum number of articles associated with each update. (default: :obj:`10`)
**Returns:**
Union\[dict, str]: A dictionary containing the stories and their
associated data, or error message if the process fails.
### get\_web\_search
```python theme={"system"}
def get_web_search(
self,
queries: List[str],
return_type: Literal['string', 'dicts', 'both'] = 'string'
):
```
Perform a live web search based on the given queries.
**Parameters:**
* **queries** (List\[str]): A list of search queries.
* **return\_type** (`Literal["string", "dicts", "both"]`): The format of the return value. (default: :obj:`"string"`)
**Returns:**
Union\[str, dict, Tuple\[str, dict]]: A string,
dictionary, or both containing the search results, or
error message if the process fails.
### search\_reddit
```python theme={"system"}
def search_reddit(
self,
keywords: List[str],
n_threads: int = 5,
return_type: Literal['string', 'dicts', 'both'] = 'string',
method: Literal['nl', 'kw'] = 'kw'
):
```
Search Reddit based on the provided keywords.
**Parameters:**
* **keywords** (List\[str]): The keywords to search for on Reddit.
* **n\_threads** (int): Number of Reddit threads to summarize and return. (default: :obj:`5`)
* **return\_type** (`Literal["string", "dicts", "both"]`): The format of the return value. (default: :obj:`"string"`)
* **method** (`Literal["nl", "kw"]`): The search method, either "nl" for natural language or "kw" for keyword search. (default: :obj:`"kw"`)
**Returns:**
Union\[str, dict, Tuple\[str, dict]]: The Reddit search
results as a string, dictionary, or both, or error message if
the process fails.
### query\_finance
```python theme={"system"}
def query_finance(
self,
asset: Literal['bitcoin', 'ethereum', 'cardano', 'uniswap', 'ripple', 'solana', 'polkadot', 'polygon', 'chainlink', 'tether', 'dogecoin', 'monero', 'tron', 'binance', 'aave', 'tesla', 'microsoft', 'amazon'],
metric: Literal['news_positive', 'news_negative', 'news_total', 'news_positive_weighted', 'news_negative_weighted', 'news_total_weighted'] = 'news_positive',
return_type: Literal['list', 'string'] = 'string',
date_from: Optional[datetime] = None,
date_to: Optional[datetime] = None
):
```
Fetch asset sentiment data for a given asset, metric, and date
range.
**Parameters:**
* **asset** (Literal): The asset for which to fetch sentiment data.
* **metric** (Literal): The sentiment metric to analyze.
* **return\_type** (`Literal["list", "string"]`): The format of the return value. (default: :obj:`"string"`)
* **date\_from** (datetime, optional): The start date and time for the data in ISO 8601 format.
* **date\_to** (datetime, optional): The end date and time for the data in ISO 8601 format.
**Returns:**
Union\[list, str]: A list of dictionaries containing the datetime
and value or a string describing all datetime and value pairs
for providing quantified time-series data for news sentiment
on topics of interest, or an error message if the process
fails.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
## AsyncAskNewsToolkit
```python theme={"system"}
class AsyncAskNewsToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with the AskNews API
asynchronously.
This class provides methods for fetching news, stories, and other
content based on user queries using the AskNews API.
### **init**
```python theme={"system"}
def __init__(self):
```
Initialize the AsyncAskNewsToolkit with API clients.The API keys
and credentials are retrieved from environment variables.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.async_browser_toolkit
## extract\_function\_name
```python theme={"system"}
def extract_function_name(s: str):
```
Extract the pure function name from a string (without parameters or
parentheses)
**Parameters:**
* **s** (str): Input string, e.g., `1.`**`click_id(14)`**, `scroll_up()`, `\'visit_page(url)\'`, etc.
**Returns:**
str: Pure function name (e.g., `click_id`, `scroll_up`, `visit_page`)
## AsyncBaseBrowser
```python theme={"system"}
class AsyncBaseBrowser:
```
### **init**
```python theme={"system"}
def __init__(
self,
headless = True,
cache_dir: Optional[str] = None,
channel: Literal['chrome', 'msedge', 'chromium'] = 'chromium',
cookie_json_path: Optional[str] = None,
user_data_dir: Optional[str] = None
):
```
Initialize the asynchronous browser core.
**Parameters:**
* **headless** (bool): Whether to run the browser in headless mode.
* **cache\_dir** (Union\[str, None]): The directory to store cache files.
* **channel** (`Literal["chrome", "msedge", "chromium"]`): The browser channel to use. Must be one of "chrome", "msedge", or "chromium".
* **cookie\_json\_path** (Optional\[str]): Path to a JSON file containing authentication cookies and browser storage state. If provided and the file exists, the browser will load this state to maintain authenticated sessions. This is primarily used when `user_data_dir` is not set.
* **user\_data\_dir** (Optional\[str]): The directory to store user data for persistent context. If None, a fresh browser instance is used without saving data. (default: :obj:`None`)
**Returns:**
None
### init
```python theme={"system"}
def init(self):
```
Initialize the browser asynchronously.
### clean\_cache
```python theme={"system"}
def clean_cache(self):
```
Delete the cache directory and its contents.
### wait\_for\_load
```python theme={"system"}
def wait_for_load(self, timeout: int = 20):
```
Wait for a certain amount of time for the page to load.
**Parameters:**
* **timeout** (int): Timeout in seconds.
### click\_blank\_area
```python theme={"system"}
def click_blank_area(self):
```
Click a blank area of the page to unfocus the current element.
### visit\_page
```python theme={"system"}
def visit_page(self, url: str):
```
Visit a page with the given URL.
### ask\_question\_about\_video
```python theme={"system"}
def ask_question_about_video(self, question: str):
```
Ask a question about the video on the current page,
such as YouTube video.
**Parameters:**
* **question** (str): The question to ask.
**Returns:**
str: The answer to the question.
### get\_screenshot
```python theme={"system"}
def get_screenshot(self, save_image: bool = False):
```
Get a screenshot of the current page.
**Parameters:**
* **save\_image** (bool): Whether to save the image to the cache directory.
**Returns:**
Tuple\[Image.Image, str]: A tuple containing the screenshot
image and the path to the image file if saved, otherwise
:obj:`None`.
### capture\_full\_page\_screenshots
```python theme={"system"}
def capture_full_page_screenshots(self, scroll_ratio: float = 0.8):
```
Capture full page screenshots by scrolling the page with
a buffer zone.
**Parameters:**
* **scroll\_ratio** (float): The ratio of viewport height to scroll each step (default: 0.8).
**Returns:**
List\[str]: A list of paths to the captured screenshots.
### get\_visual\_viewport
```python theme={"system"}
def get_visual_viewport(self):
```
Get the visual viewport of the current page.
### get\_interactive\_elements
```python theme={"system"}
def get_interactive_elements(self):
```
**Returns:**
Dict\[str, InteractiveRegion]: A dictionary of interactive elements.
### get\_som\_screenshot
```python theme={"system"}
def get_som_screenshot(self, save_image: bool = False):
```
Get a screenshot of the current viewport with interactive elements
marked.
**Parameters:**
* **save\_image** (bool): Whether to save the image to the cache directory.
**Returns:**
Tuple\[Image.Image, str]: A tuple containing the screenshot image
and the path to the image file.
### scroll\_up
```python theme={"system"}
def scroll_up(self):
```
Scroll up the page.
### scroll\_down
```python theme={"system"}
def scroll_down(self):
```
Scroll down the page.
### get\_url
```python theme={"system"}
def get_url(self):
```
Get the URL of the current page.
### click\_id
```python theme={"system"}
def click_id(self, identifier: Union[str, int]):
```
Click an element with the given identifier.
### extract\_url\_content
```python theme={"system"}
def extract_url_content(self):
```
Extract the content of the current page.
### download\_file\_id
```python theme={"system"}
def download_file_id(self, identifier: Union[str, int]):
```
Download a file with the given identifier.
### fill\_input\_id
```python theme={"system"}
def fill_input_id(self, identifier: Union[str, int], text: str):
```
Fill an input field with the given text, and then press Enter.
### scroll\_to\_bottom
```python theme={"system"}
def scroll_to_bottom(self):
```
Scroll to the bottom of the page.
### scroll\_to\_top
```python theme={"system"}
def scroll_to_top(self):
```
Scroll to the top of the page.
### hover\_id
```python theme={"system"}
def hover_id(self, identifier: Union[str, int]):
```
Hover over an element with the given identifier.
### find\_text\_on\_page
```python theme={"system"}
def find_text_on_page(self, search_text: str):
```
Find the next given text on the page, and scroll the page to
the targeted text. It is equivalent to pressing Ctrl + F and
searching for the text.
**Parameters:**
* **search\_text** (str): The text to search for.
**Returns:**
str: The result of the action.
### back
```python theme={"system"}
def back(self):
```
Navigate back to the previous page.
### close
```python theme={"system"}
def close(self):
```
Close the browser.
### show\_interactive\_elements
```python theme={"system"}
def show_interactive_elements(self):
```
Show simple interactive elements on the current page.
### get\_webpage\_content
```python theme={"system"}
def get_webpage_content(self):
```
Extract the content of the current page.
### \_ensure\_browser\_installed
```python theme={"system"}
def _ensure_browser_installed(self):
```
Ensure the browser is installed.
## AsyncBrowserToolkit
```python theme={"system"}
class AsyncBrowserToolkit(BaseToolkit):
```
An asynchronous class for browsing the web and interacting
with web pages.
This class provides methods for browsing the web and interacting with web
pages.
### **init**
```python theme={"system"}
def __init__(
self,
headless: bool = False,
cache_dir: Optional[str] = None,
channel: Literal['chrome', 'msedge', 'chromium'] = 'chromium',
history_window: int = 5,
web_agent_model: Optional[BaseModelBackend] = None,
planning_agent_model: Optional[BaseModelBackend] = None,
output_language: str = 'en',
cookie_json_path: Optional[str] = None,
user_data_dir: Optional[str] = None
):
```
Initialize the BrowserToolkit instance.
**Parameters:**
* **headless** (bool): Whether to run the browser in headless mode.
* **cache\_dir** (Union\[str, None]): The directory to store cache files.
* **channel** (`Literal["chrome", "msedge", "chromium"]`): The browser channel to use. Must be one of "chrome", "msedge", or "chromium".
* **history\_window** (int): The window size for storing the history of actions.
* **web\_agent\_model** (Optional\[BaseModelBackend]): The model backend for the web agent.
* **planning\_agent\_model** (Optional\[BaseModelBackend]): The model backend for the planning agent.
* **output\_language** (str): The language to use for output. (default: :obj:`"en`")
* **cookie\_json\_path** (Optional\[str]): Path to a JSON file containing authentication cookies and browser storage state. If provided and the file exists, the browser will load this state to maintain authenticated sessions without requiring manual login. (default: :obj:`None`)
* **user\_data\_dir** (Optional\[str]): The directory to store user data for persistent context. (default: :obj:`"user_data_dir/"`)
### \_reset
```python theme={"system"}
def _reset(self):
```
### \_initialize\_agent
```python theme={"system"}
def _initialize_agent(self):
```
Initialize the planning and web agents.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.audio_analysis_toolkit
## download\_file
```python theme={"system"}
def download_file(url: str, cache_dir: str):
```
Download a file from a URL to a local cache directory.
**Parameters:**
* **url** (str): The URL of the file to download.
* **cache\_dir** (str): The directory to save the downloaded file.
**Returns:**
str: The path to the downloaded file.
**Raises:**
* **Exception**: If the download fails.
## AudioAnalysisToolkit
```python theme={"system"}
class AudioAnalysisToolkit(BaseToolkit):
```
### **init**
```python theme={"system"}
def __init__(
self,
cache_dir: Optional[str] = None,
transcribe_model: Optional[BaseAudioModel] = None,
audio_reasoning_model: Optional[BaseModelBackend] = None,
timeout: Optional[float] = None
):
```
A toolkit for audio processing and analysis. This class provides
methods for processing, transcribing, and extracting information from
audio data, including direct question answering about audio content.
**Parameters:**
* **cache\_dir** (Optional\[str]): Directory path for caching downloaded audio files. If not provided, 'tmp/' will be used. (default: :obj:`None`)
* **transcribe\_model** (Optional\[BaseAudioModel]): Model used for audio transcription. If not provided, OpenAIAudioModels will be used. (default: :obj:`None`)
* **audio\_reasoning\_model** (Optional\[BaseModelBackend]): Model used for audio reasoning and question answering. If not provided, uses the default model from ChatAgent. (default: :obj:`None`)
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### audio2text
```python theme={"system"}
def audio2text(self, audio_path: str):
```
Transcribe audio to text.
**Parameters:**
* **audio\_path** (str): The path to the audio file or URL.
**Returns:**
str: The transcribed text.
### ask\_question\_about\_audio
```python theme={"system"}
def ask_question_about_audio(self, audio_path: str, question: str):
```
Ask any question about the audio and get the answer using
multimodal model.
**Parameters:**
* **audio\_path** (str): The path to the audio file.
* **question** (str): The question to ask about the audio.
**Returns:**
str: The answer to the question.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.base
## manual\_timeout
```python theme={"system"}
def manual_timeout(func: F):
```
Decorator to mark a function as having manual timeout handling.
Use this decorator on toolkit methods that manage their own timeout logic
internally but don't have a `timeout` parameter in their signature.
This prevents the automatic `with_timeout` wrapper from being applied
by `BaseToolkit`.
**Parameters:**
* **func** (F): The function to mark as having manual timeout handling.
**Returns:**
F: The same function with `_manual_timeout` attribute set to True.
## BaseToolkit
```python theme={"system"}
class BaseToolkit:
```
Base class for toolkits.
**Parameters:**
* **timeout** (Optional\[float]): The timeout for the toolkit.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = Constants.TIMEOUT_THRESHOLD):
```
### **init\_subclass**
```python theme={"system"}
def __init_subclass__(cls, **kwargs):
```
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
### run\_mcp\_server
```python theme={"system"}
def run_mcp_server(self, mode: Literal['stdio', 'sse', 'streamable-http']):
```
Run the MCP server in the specified mode.
**Parameters:**
* **mode** (`Literal["stdio", "sse", "streamable-http"]`): The mode to run the MCP server in.
## RegisteredAgentToolkit
```python theme={"system"}
class RegisteredAgentToolkit:
```
Mixin class for toolkits that need to register a ChatAgent.
This mixin provides a standard interface for toolkits that require
a reference to a ChatAgent instance. The ChatAgent will check if a
toolkit has this mixin and automatically register itself.
### **init**
```python theme={"system"}
def __init__(self):
```
### agent
```python theme={"system"}
def agent(self):
```
**Returns:**
Optional\[ChatAgent]: The registered agent, or None if not
registered.
**Note:**
If None is returned, it means the toolkit has not been registered
with a ChatAgent yet. Make sure to pass this toolkit to a ChatAgent
via the toolkits parameter during initialization.
### register\_agent
```python theme={"system"}
def register_agent(self, agent: 'ChatAgent'):
```
Register a ChatAgent with this toolkit.
This method allows registering an agent after initialization. The
ChatAgent will automatically call this method if the toolkit to
register inherits from RegisteredAgentToolkit.
**Parameters:**
* **agent** (ChatAgent): The ChatAgent instance to register.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.bohrium_toolkit
## BohriumToolkit
```python theme={"system"}
class BohriumToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with Bohrium services.
**Parameters:**
* **timeout** (Optional\[float], optional): The timeout for BohriumToolkit. (default: :obj:`None`)
* **api\_key** (Optional\[str], optional): The API key for Bohrium client. (default: :obj:`None`)
* **project\_id** (Optional\[int], optional): The project ID for Bohrium client. (default: :obj:`None`)
* **yaml\_path** (Optional\[str], optional): The path to the YAML file containing the job parameters. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
api_key: Optional[str] = None,
project_id: Optional[int] = None,
yaml_path: Optional[str] = None,
_test_mode: bool = False
):
```
### \_custom\_insert
```python theme={"system"}
def _custom_insert(self, data):
```
refactor insert method, ensure return jobId information
### submit\_job
```python theme={"system"}
def submit_job(
self,
job_name: str = 'bohr-job',
machine_type: str = 'c2_m4_cpu',
cmd: str = 'mpirun -n 2 lmp_mpi -i in.shear',
image_address: str = 'registry.dp.tech/dptech/lammps:29Sep2021'
):
```
Submit a job to Bohrium.
**Parameters:**
* **job\_name** (str): The name of the job. It will be updated when yaml file is provided. The yaml file might be set when initialize BohriumToolkit. (default: :obj:`bohr-job`)
* **machine\_type** (str): The type of machine to use. It will be updated when yaml file is provided. The yaml file might be set when initialize BohriumToolkit. (default: :obj:`c2_m4_cpu`)
* **cmd** (str): The command to run. It will be updated when yaml file is provided. The yaml file might be set when initialize (default: :obj:`mpirun -n 2 lmp_mpi -i in.shear`)
* **image\_address** (str): The address of the image to use. It will be updated when yaml file is provided. The yaml file might be set when initialize BohriumToolkit. (default: :obj:`registry.dp.tech/dptech/lammps:29Sep2021`)
**Returns:**
Dict\[str, Any]: The result of the job submission.
### get\_job\_details
```python theme={"system"}
def get_job_details(self, job_id: int):
```
Get details for a specific job.
**Parameters:**
* **job\_id** (int): The ID of the job.
**Returns:**
Dict\[str, Any]: The job details.
### terminate\_job
```python theme={"system"}
def terminate_job(self, job_id: int):
```
Terminate a running job.
**Parameters:**
* **job\_id** (int): The ID of the job to terminate.
**Returns:**
Dict\[str, Any]: The result of the termination request.
### kill\_job
```python theme={"system"}
def kill_job(self, job_id: int):
```
Kill a running job.
**Parameters:**
* **job\_id** (int): The ID of the job to kill.
**Returns:**
Dict\[str, Any]: The result of the kill request.
### get\_job\_logs
```python theme={"system"}
def get_job_logs(
self,
job_id: int,
log_file: str = 'STDOUTERR',
page: int = -1,
page_size: int = 8192
):
```
Get logs for a specific job.
**Parameters:**
* **job\_id** (int): The ID of the job.
* **log\_file** (str, optional): The log file to get. (default: :obj:`STDOUTERR`)
* **page** (int, optional): The page number. (default: :obj:`-1`)
* **page\_size** (int, optional): The page size. (default: :obj:`8192`)
**Returns:**
str: The log contents.
### create\_job\_group
```python theme={"system"}
def create_job_group(self, project_id: int, job_group_name: str):
```
Create a job group.
**Parameters:**
* **project\_id** (int): The ID of the project.
* **job\_group\_name** (str): The name of the job group.
**Returns:**
Dict\[str, Any]: The result of the job group creation.
### download\_job\_results
```python theme={"system"}
def download_job_results(self, job_id: int, save_path: str):
```
Download the results of a job.
**Parameters:**
* **job\_id** (int): The ID of the job.
* **save\_path** (str): The path to save the results to.
**Returns:**
Dict\[str, Any]: The result of the download request.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.browser_toolkit
## \_get\_str
```python theme={"system"}
def _get_str(d: Any, k: str):
```
Safely retrieve a string value from a dictionary.
## \_get\_number
```python theme={"system"}
def _get_number(d: Any, k: str):
```
Safely retrieve a number (int or float) from a dictionary
## \_get\_bool
```python theme={"system"}
def _get_bool(d: Any, k: str):
```
Safely retrieve a boolean value from a dictionary.
## BaseBrowser
```python theme={"system"}
class BaseBrowser:
```
### **init**
```python theme={"system"}
def __init__(
self,
headless = True,
cache_dir: Optional[str] = None,
channel: Literal['chrome', 'msedge', 'chromium'] = 'chromium',
cookie_json_path: Optional[str] = None,
user_data_dir: Optional[str] = None
):
```
Initialize the WebBrowser instance.
**Parameters:**
* **headless** (bool): Whether to run the browser in headless mode.
* **cache\_dir** (Union\[str, None]): The directory to store cache files.
* **channel** (`Literal["chrome", "msedge", "chromium"]`): The browser channel to use. Must be one of "chrome", "msedge", or "chromium".
* **cookie\_json\_path** (Optional\[str]): Path to a JSON file containing authentication cookies and browser storage state. If provided and the file exists, the browser will load this state to maintain authenticated sessions. This is primarily used when `user_data_dir` is not set.
* **user\_data\_dir** (Optional\[str]): The directory to store user data for persistent context. If None, a fresh browser instance is used without saving data. (default: :obj:`None`)
**Returns:**
None
### init
```python theme={"system"}
def init(self):
```
Initialize the browser.
### clean\_cache
```python theme={"system"}
def clean_cache(self):
```
Delete the cache directory and its contents.
### \_wait\_for\_load
```python theme={"system"}
def _wait_for_load(self, timeout: int = 20):
```
Wait for a certain amount of time for the page to load.
### click\_blank\_area
```python theme={"system"}
def click_blank_area(self):
```
Click a blank area of the page to unfocus the current element.
### visit\_page
```python theme={"system"}
def visit_page(self, url: str):
```
Visit a page with the given URL.
### ask\_question\_about\_video
```python theme={"system"}
def ask_question_about_video(self, question: str):
```
Ask a question about the video on the current page,
such as YouTube video.
**Parameters:**
* **question** (str): The question to ask.
**Returns:**
str: The answer to the question.
### get\_screenshot
```python theme={"system"}
def get_screenshot(self, save_image: bool = False):
```
Get a screenshot of the current page.
**Parameters:**
* **save\_image** (bool): Whether to save the image to the cache directory.
**Returns:**
Tuple\[Image.Image, str]: A tuple containing the screenshot
image and the path to the image file if saved, otherwise
:obj:`None`.
### capture\_full\_page\_screenshots
```python theme={"system"}
def capture_full_page_screenshots(self, scroll_ratio: float = 0.8):
```
Capture full page screenshots by scrolling the page with a buffer
zone.
**Parameters:**
* **scroll\_ratio** (float): The ratio of viewport height to scroll each step. (default: :obj:`0.8`)
**Returns:**
List\[str]: A list of paths to the screenshot files.
### get\_visual\_viewport
```python theme={"system"}
def get_visual_viewport(self):
```
**Returns:**
VisualViewport: The visual viewport of the current page.
### get\_interactive\_elements
```python theme={"system"}
def get_interactive_elements(self):
```
**Returns:**
Dict\[str, InteractiveRegion]: A dictionary of interactive elements.
### get\_som\_screenshot
```python theme={"system"}
def get_som_screenshot(self, save_image: bool = False):
```
Get a screenshot of the current viewport with interactive elements
marked.
**Parameters:**
* **save\_image** (bool): Whether to save the image to the cache directory.
**Returns:**
Tuple\[Image.Image, Union\[str, None]]: A tuple containing the
screenshot image
and an optional path to the image file if saved, otherwise
:obj:`None`.
### scroll\_up
```python theme={"system"}
def scroll_up(self):
```
Scroll up the page.
### scroll\_down
```python theme={"system"}
def scroll_down(self):
```
Scroll down the page.
### get\_url
```python theme={"system"}
def get_url(self):
```
Get the URL of the current page.
### click\_id
```python theme={"system"}
def click_id(self, identifier: Union[str, int]):
```
Click an element with the given identifier.
### extract\_url\_content
```python theme={"system"}
def extract_url_content(self):
```
Extract the content of the current page.
### download\_file\_id
```python theme={"system"}
def download_file_id(self, identifier: Union[str, int]):
```
Download a file with the given selector.
**Parameters:**
* **identifier** (str): The identifier of the file to download.
**Returns:**
str: The result of the action.
### fill\_input\_id
```python theme={"system"}
def fill_input_id(self, identifier: Union[str, int], text: str):
```
Fill an input field with the given text, and then press Enter.
**Parameters:**
* **identifier** (str): The identifier of the input field.
* **text** (str): The text to fill.
**Returns:**
str: The result of the action.
### scroll\_to\_bottom
```python theme={"system"}
def scroll_to_bottom(self):
```
### scroll\_to\_top
```python theme={"system"}
def scroll_to_top(self):
```
### hover\_id
```python theme={"system"}
def hover_id(self, identifier: Union[str, int]):
```
Hover over an element with the given identifier.
**Parameters:**
* **identifier** (str): The identifier of the element to hover over.
**Returns:**
str: The result of the action.
### find\_text\_on\_page
```python theme={"system"}
def find_text_on_page(self, search_text: str):
```
Find the next given text on the page, and scroll the page to the
targeted text. It is equivalent to pressing Ctrl + F and searching for
the text.
### back
```python theme={"system"}
def back(self):
```
Navigate back to the previous page.
### close
```python theme={"system"}
def close(self):
```
### show\_interactive\_elements
```python theme={"system"}
def show_interactive_elements(self):
```
Show simple interactive elements on the current page.
### get\_webpage\_content
```python theme={"system"}
def get_webpage_content(self):
```
### \_ensure\_browser\_installed
```python theme={"system"}
def _ensure_browser_installed(self):
```
Ensure the browser is installed.
## BrowserToolkit
```python theme={"system"}
class BrowserToolkit(BaseToolkit):
```
A class for browsing the web and interacting with web pages.
This class provides methods for browsing the web and interacting with web
pages.
### **init**
```python theme={"system"}
def __init__(
self,
headless: bool = False,
cache_dir: Optional[str] = None,
channel: Literal['chrome', 'msedge', 'chromium'] = 'chromium',
history_window: int = 5,
web_agent_model: Optional[BaseModelBackend] = None,
planning_agent_model: Optional[BaseModelBackend] = None,
output_language: str = 'en',
cookie_json_path: Optional[str] = None,
user_data_dir: Optional[str] = None
):
```
Initialize the BrowserToolkit instance.
**Parameters:**
* **headless** (bool): Whether to run the browser in headless mode. When running inside a CAMEL runtime container, this is automatically set to True since containers typically don't have a display.
* **cache\_dir** (Union\[str, None]): The directory to store cache files.
* **channel** (`Literal["chrome", "msedge", "chromium"]`): The browser channel to use. Must be one of "chrome", "msedge", or "chromium".
* **history\_window** (int): The window size for storing the history of actions.
* **web\_agent\_model** (Optional\[BaseModelBackend]): The model backend for the web agent.
* **planning\_agent\_model** (Optional\[BaseModelBackend]): The model backend for the planning agent.
* **output\_language** (str): The language to use for output. (default: :obj:`"en`")
* **cookie\_json\_path** (Optional\[str]): Path to a JSON file containing authentication cookies and browser storage state. If provided and the file exists, the browser will load this state to maintain authenticated sessions without requiring manual login. (default: :obj:`None`)
* **user\_data\_dir** (Optional\[str]): The directory to store user data for persistent context. If None, a fresh browser instance is used without saving data. (default: :obj:`None`)
### \_reset
```python theme={"system"}
def _reset(self):
```
### \_initialize\_agent
```python theme={"system"}
def _initialize_agent(
self,
web_agent_model_backend: Optional[BaseModelBackend],
planning_agent_model_backend: Optional[BaseModelBackend]
):
```
Initialize the agent.
### \_observe
```python theme={"system"}
def _observe(self, task_prompt: str, detailed_plan: Optional[str] = None):
```
Let agent observe the current environment, and get the next
action.
### \_act
```python theme={"system"}
def _act(self, action_code: str):
```
Let agent act based on the given action code.
**Parameters:**
* **action\_code** (str): The action code to act.
**Returns:**
Tuple\[bool, str]: A tuple containing a boolean indicating whether
the action was successful, and the information to be returned.
### \_get\_final\_answer
```python theme={"system"}
def _get_final_answer(self, task_prompt: str):
```
Get the final answer based on the task prompt and current
browser state.
It is used when the agent thinks that the task can be completed
without any further action, and answer can be directly found in the
current viewport.
### \_task\_planning
```python theme={"system"}
def _task_planning(self, task_prompt: str, start_url: str):
```
Plan the task based on the given task prompt.
### \_task\_replanning
```python theme={"system"}
def _task_replanning(self, task_prompt: str, detailed_plan: str):
```
Replan the task based on the given task prompt.
**Parameters:**
* **task\_prompt** (str): The original task prompt.
* **detailed\_plan** (str): The detailed plan to replan.
**Returns:**
Tuple\[bool, str]: A tuple containing a boolean indicating
whether the task needs to be replanned, and the replanned schema.
### browse\_url
```python theme={"system"}
def browse_url(
self,
task_prompt: str,
start_url: str,
round_limit: int = 12
):
```
A powerful toolkit which can simulate the browser interaction to
solve the task which needs multi-step actions.
**Parameters:**
* **task\_prompt** (str): The task prompt to solve.
* **start\_url** (str): The start URL to visit.
* **round\_limit** (int): The round limit to solve the task. (default: :obj:`12`).
**Returns:**
str: The simulation result to the task.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.browser_toolkit_commons
## \_get\_str
```python theme={"system"}
def _get_str(d: Any, k: str):
```
Safely retrieve a string value from a dictionary.
## \_get\_number
```python theme={"system"}
def _get_number(d: Any, k: str):
```
Safely retrieve a number (int or float) from a dictionary
## \_get\_bool
```python theme={"system"}
def _get_bool(d: Any, k: str):
```
Safely retrieve a boolean value from a dictionary.
## \_parse\_json\_output
```python theme={"system"}
def _parse_json_output(text: str, logger: Any):
```
Extract JSON output from a string.
## \_reload\_image
```python theme={"system"}
def _reload_image(image: Image.Image):
```
## dom\_rectangle\_from\_dict
```python theme={"system"}
def dom_rectangle_from_dict(rect: Dict[str, Any]):
```
Create a DOMRectangle object from a dictionary.
## interactive\_region\_from\_dict
```python theme={"system"}
def interactive_region_from_dict(region: Dict[str, Any]):
```
Create an :class:`InteractiveRegion` object from a dictionary.
## visual\_viewport\_from\_dict
```python theme={"system"}
def visual_viewport_from_dict(viewport: Dict[str, Any]):
```
Create a :class:`VisualViewport` object from a dictionary.
## add\_set\_of\_mark
```python theme={"system"}
def add_set_of_mark(
screenshot: Union[bytes, Image.Image, io.BufferedIOBase],
ROIs: Dict[str, InteractiveRegion]
):
```
## \_add\_set\_of\_mark
```python theme={"system"}
def _add_set_of_mark(screenshot: Image.Image, ROIs: Dict[str, InteractiveRegion]):
```
Add a set of marks to the screenshot.
**Parameters:**
* **screenshot** (Image.Image): The screenshot to add marks to.
* **ROIs** (Dict\[str, InteractiveRegion]): The regions to add marks to.
**Returns:**
Tuple\[Image.Image, List\[str], List\[str], List\[str]]: A tuple
containing the screenshot with marked ROIs, ROIs fully within the
images, ROIs located above the visible area, and ROIs located below
the visible area.
## \_draw\_roi
```python theme={"system"}
def _draw_roi(
draw: ImageDraw.ImageDraw,
idx: int,
font: Union[ImageFont.FreeTypeFont, ImageFont.ImageFont],
rect: DOMRectangle
):
```
Draw a ROI on the image.
**Parameters:**
* **draw** (ImageDraw\.ImageDraw): The draw object.
* **idx** (int): The index of the ROI.
* **font** (ImageFont.FreeTypeFont | ImageFont.ImageFont): The font.
* **rect** (DOMRectangle): The DOM rectangle.
## \_get\_text\_color
```python theme={"system"}
def _get_text_color(bg_color: Tuple[int, int, int, int]):
```
Determine the ideal text color (black or white) for contrast.
**Parameters:**
* **bg\_color**: The background color (R, G, B, A).
**Returns:**
A tuple representing black or white color for text.
## \_get\_random\_color
```python theme={"system"}
def _get_random_color(identifier: int):
```
Generate a consistent random RGBA color based on the identifier.
**Parameters:**
* **identifier**: The ID used as a seed to ensure color consistency.
**Returns:**
A tuple representing (R, G, B, A) values.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.code_execution
## CodeExecutionToolkit
```python theme={"system"}
class CodeExecutionToolkit(BaseToolkit):
```
A toolkit for code execution.
**Parameters:**
* **sandbox** (str): The environment type used to execute code. (default: `subprocess`)
* **verbose** (bool): Whether to print the output of the code execution. (default: :obj:`False`)
* **unsafe\_mode** (bool): If `True`, the interpreter runs the code by `eval()` without any security check. (default: :obj:`False`)
* **import\_white\_list** (Optional\[List\[str]]): A list of allowed imports. (default: :obj:`None`)
* **require\_confirm** (bool): Whether to require confirmation before executing code. (default: :obj:`False`)
* **timeout** (Optional\[float]): General timeout for toolkit operations. (default: :obj:`None`)
* **microsandbox\_config** (Optional\[dict]): Configuration for microsandbox interpreter. Available keys: 'server\_url', 'api\_key', 'namespace', 'sandbox\_name', 'timeout'. If None, uses default configuration. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
sandbox: Literal['internal_python', 'jupyter', 'docker', 'subprocess', 'e2b', 'microsandbox'] = 'subprocess',
verbose: bool = False,
unsafe_mode: bool = False,
import_white_list: Optional[List[str]] = None,
require_confirm: bool = False,
timeout: Optional[float] = None,
microsandbox_config: Optional[dict] = None
):
```
### execute\_code
```python theme={"system"}
def execute_code(self, code: str, code_type: str = 'python'):
```
Execute a given code snippet.
**Parameters:**
* **code** (str): The input code to the Code Interpreter tool call.
* **code\_type** (str): The type of the code to be executed (e.g. node.js, python, etc). (default: obj:`python`)
**Returns:**
str: The text output from the Code Interpreter tool call.
### execute\_command
```python theme={"system"}
def execute_command(self, command: str):
```
Execute a command can be used to resolve the dependency of the
code. Useful if there's dependency issues when you try to execute code.
**Parameters:**
* **command** (str): The command to execute.
**Returns:**
Union\[str, tuple\[str, str]]: The output of the command.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.context_summarizer_toolkit
## ContextSummarizerToolkit
```python theme={"system"}
class ContextSummarizerToolkit(BaseToolkit):
```
A toolkit that provides intelligent context summarization and
management for agents.
This toolkit enables agents to compress conversation context through
intelligent summarization, save conversation history to markdown files,
and search through past conversations. It handles all context management
needs in a single toolkit.
Key features:
* Intelligent context compression with over-compression prevention
* Markdown file storage with session management
* Simple text-based search through conversation history
* Configurable summarization prompts
* Context loading and saving capabilities
### **init**
```python theme={"system"}
def __init__(
self,
agent: 'ChatAgent',
working_directory: Optional[str] = None,
timeout: Optional[float] = None,
summary_prompt_template: Optional[str] = None
):
```
Initialize the ContextSummarizerToolkit.
**Parameters:**
* **agent** (ChatAgent): The agent that is using the toolkit. This is required to access the agent's memory.
* **working\_directory** (str, optional): The directory path where notes will be stored. If not provided, a default directory will be used.
* **timeout** (Optional\[float]): The timeout for the toolkit.
* **summary\_prompt\_template** (Optional\[str]): Custom prompt template for summarization. If None, a default task-focused template is used. Users can customize this for different use cases.
### \_setup\_storage
```python theme={"system"}
def _setup_storage(self, working_directory: Optional[str]):
```
Initialize storage paths and create session-specific directories
using ContextUtility for file management.
### \_summarize\_messages
```python theme={"system"}
def _summarize_messages(self, memory_records: List['MemoryRecord']):
```
Generate a summary of the conversation context.
**Parameters:**
* **memory\_records** (`List["MemoryRecord"]`): A list of memory records to summarize.
**Returns:**
str: The summary of the conversation context.
### \_save\_summary
```python theme={"system"}
def _save_summary(self, summary: str):
```
Persist conversation summary to markdown file with metadata
including timestamp and session information.
**Parameters:**
* **summary** (str): The summary text to save.
**Returns:**
str: "success" or error message starting with "Error:".
### \_save\_history
```python theme={"system"}
def _save_history(self, memory_records: List['MemoryRecord']):
```
Export complete conversation transcript as formatted markdown
with message roles, agent IDs, and content structure preserved.
**Parameters:**
* **memory\_records** (`List["MemoryRecord"]`): The list of memory records to save.
**Returns:**
str: "success" or error message starting with "Error:".
### \_compress\_and\_save
```python theme={"system"}
def _compress_and_save(self, memory_records: List['MemoryRecord']):
```
Complete compression pipeline: summarize and save both history and
summary.
**Parameters:**
* **memory\_records** (`List["MemoryRecord"]`): The memory records to compress and save.
**Returns:**
str: The generated summary text.
### \_load\_summary
```python theme={"system"}
def _load_summary(self):
```
**Returns:**
str: The summary content, or empty string if not found.
### \_load\_history
```python theme={"system"}
def _load_history(self):
```
**Returns:**
str: The history content, or empty string if not found.
### \_format\_conversation
```python theme={"system"}
def _format_conversation(self, memory_records: List['MemoryRecord']):
```
Convert memory records into human-readable conversation format
with role names and message content for summarization processing.
**Parameters:**
* **memory\_records** (`List["MemoryRecord"]`): A list of memory records to format.
**Returns:**
str: The formatted conversation.
### \_create\_summary\_prompt
```python theme={"system"}
def _create_summary_prompt(self, conversation_text: str):
```
Construct detailed summarization prompt with instructions
for extracting key information, goals, and progress from conversation.
**Parameters:**
* **conversation\_text** (str): The formatted conversation to summarize.
**Returns:**
str: The complete prompt for summarization.
### summarize\_full\_conversation\_history
```python theme={"system"}
def summarize_full_conversation_history(self):
```
**Returns:**
str: Success message with brief summary, or error message.
### \_refresh\_context\_with\_summary
```python theme={"system"}
def _refresh_context_with_summary(self, summary: str):
```
Empty the agent's memory and replace it with a summary
of the conversation history.
**Parameters:**
* **summary** (str): The summary of the conversation history.
**Returns:**
bool: True if the context was refreshed successfully, False
otherwise.
### get\_conversation\_memory\_info
```python theme={"system"}
def get_conversation_memory_info(self):
```
**Returns:**
str: Information about current memory and saved files.
### search\_full\_conversation\_history
```python theme={"system"}
def search_full_conversation_history(self, keywords: List[str], top_k: int = 4):
```
Search the conversation history using keyword matching. This is
used when information is missing from the summary and the current
conversation, and can potentially be found in the full conversation
history before it was summarized.
Searches through the current session's history.md file to find the
top messages that contain the most keywords.
**Parameters:**
* **keywords** (List\[str]): List of keywords to search for. The keywords must be explicitly related to the information the user is looking for, and not general terms that might be found about any topic. For example, if the user is searching for the price of the flight to "Paris" which was discussed previously, the keywords should be \["Paris", "price", "flight", "\$", "costs"].
* **top\_k** (int): The number of results to return (default 4).
**Returns:**
str: The search results or error message.
### should\_compress\_context
```python theme={"system"}
def should_compress_context(self, message_limit: int = 40, token_limit: Optional[int] = None):
```
Check if context should be compressed based on limits.
**Parameters:**
* **message\_limit** (int): Maximum number of messages before compression.
* **token\_limit** (Optional\[int]): Maximum number of tokens before compression.
**Returns:**
bool: True if context should be compressed.
### reset
```python theme={"system"}
def reset(self):
```
Clear all compression state including stored summaries,
compressed message tracking, and compression counters.
### get\_current\_summary
```python theme={"system"}
def get_current_summary(self):
```
**Returns:**
Optional\[str]: The current summary, or None if no summary exists.
### set\_summary
```python theme={"system"}
def set_summary(self, summary: str):
```
Override the current in-memory summary with provided content
without affecting saved files or compression tracking.
**Parameters:**
* **summary** (str): The summary to store.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: The list of tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.craw4ai_toolkit
## Crawl4AIToolkit
```python theme={"system"}
class Crawl4AIToolkit(BaseToolkit):
```
A class representing a toolkit for Crawl4AI.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.dalle_toolkit
## OpenAIImageToolkit
```python theme={"system"}
class OpenAIImageToolkit(BaseToolkit):
```
A class representing a toolkit for image generation using OpenAI's
DALL-E model.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes a new instance of the OpenAIImageToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### base64\_to\_image
```python theme={"system"}
def base64_to_image(self, base64_string: str):
```
Converts a base64 encoded string into a PIL Image object.
**Parameters:**
* **base64\_string** (str): The base64 encoded string of the image.
**Returns:**
Optional\[Image.Image]: The PIL Image object or None if conversion
fails.
### image\_path\_to\_base64
```python theme={"system"}
def image_path_to_base64(self, image_path: str):
```
Converts the file path of an image to a Base64 encoded string.
**Parameters:**
* **image\_path** (str): The path to the image file.
**Returns:**
str: A Base64 encoded string representing the content of the image
file.
### image\_to\_base64
```python theme={"system"}
def image_to_base64(self, image: Image.Image):
```
Converts an image into a base64-encoded string.
This function takes an image object as input, encodes the image into a
PNG format base64 string, and returns it.
If the encoding process encounters an error, it prints the error
message and returns None.
**Parameters:**
* **image**: The image object to be encoded, supports any image format that can be saved in PNG format.
**Returns:**
str: A base64-encoded string of the image.
### get\_dalle\_img
```python theme={"system"}
def get_dalle_img(self, prompt: str, image_dir: str = 'img'):
```
Generate an image using OpenAI's DALL-E model.
The generated image is saved to the specified directory.
**Parameters:**
* **prompt** (str): The text prompt based on which the image is generated.
* **image\_dir** (str): The directory to save the generated image. Defaults to 'img'.
**Returns:**
str: The path to the saved image.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.dappier_toolkit
## DappierToolkit
```python theme={"system"}
class DappierToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with the Dappier API.
This class provides methods for searching real time data and fetching
ai recommendations across key verticals like News, Finance, Stock Market,
Sports, Weather and more.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the DappierTookit with API clients.The API keys and
credentials are retrieved from environment variables.
### search\_real\_time\_data
```python theme={"system"}
def search_real_time_data(
self,
query: str,
ai_model_id: str = 'am_01j06ytn18ejftedz6dyhz2b15'
):
```
Search real-time data using an AI model.
This function accesses real-time information using the specified
AI model based on the given query. Depending on the AI model ID,
the data retrieved can vary between general web search results or
financial news and stock prices.
Supported AI Models:
* `am_01j06ytn18ejftedz6dyhz2b15`:
Access real-time Google web search results, including the latest
news, weather updates, travel details, deals, and more.
* `am_01j749h8pbf7ns8r1bq9s2evrh`:
Access real-time financial news, stock prices, and trades from
polygon.io, with AI-powered insights and up-to-the-minute updates.
**Parameters:**
* **query** (str): The user-provided query. Examples include: - "How is the weather today in Austin, TX?" - "What is the latest news for Meta?" - "What is the stock price for AAPL?"
* **ai\_model\_id** (str, optional): The AI model ID to use for the query. The AI model ID always starts with the prefix "am\_". (default: `am_01j06ytn18ejftedz6dyhz2b15`)
**Returns:**
str: The search result corresponding to the provided query and
AI model ID. This may include real time search data,
depending on the selected AI model.
**Note:**
Multiple AI model IDs are available, which can be found at:
[https://marketplace.dappier.com/marketplace](https://marketplace.dappier.com/marketplace)
### get\_ai\_recommendations
```python theme={"system"}
def get_ai_recommendations(
self,
query: str,
data_model_id: str = 'dm_01j0pb465keqmatq9k83dthx34',
similarity_top_k: int = 9,
ref: Optional[str] = None,
num_articles_ref: int = 0,
search_algorithm: Literal['most_recent', 'semantic', 'most_recent_semantic', 'trending'] = 'most_recent'
):
```
Retrieve AI-powered recommendations based on the provided query
and data model.
This function fetches real-time AI-generated recommendations using the
specified data model and search algorithm. The results include
personalized content based on the query and, optionally, relevance
to a specific reference domain.
Supported Data Models:
* `dm_01j0pb465keqmatq9k83dthx34`:
Real-time news, updates, and personalized content from top sports
sources such as Sportsnaut, Forever Blueshirts, Minnesota Sports
Fan, LAFB Network, Bounding Into Sports, and Ringside Intel.
* `dm_01j0q82s4bfjmsqkhs3ywm3x6y`:
Real-time updates, analysis, and personalized content from top
sources like The Mix, Snipdaily, Nerdable, and Familyproof.
**Parameters:**
* **query** (str): The user query for retrieving recommendations.
* **data\_model\_id** (str, optional): The data model ID to use for recommendations. Data model IDs always start with the prefix "dm\_". (default: :obj:`dm_01j0pb465keqmatq9k83dthx34`)
* **similarity\_top\_k** (int, optional): The number of top documents to retrieve based on similarity. (default: :obj:`9`)
* **ref** (Optional\[str], optional): The site domain where AI recommendations should be displayed. (default: :obj:`None`)
* **num\_articles\_ref** (int, optional): The minimum number of articles to return from the specified reference domain (`ref`). The remaining articles will come from other sites in the RAG model. (default: :obj:`0`) search\_algorithm (Literal\[ "most\_recent", "semantic", "most\_recent\_semantic", "trending", ], optional): The search algorithm to use for retrieving articles. (default: :obj:`most_recent`)
**Returns:**
List\[Dict\[str, str]]: A list of recommended articles or content
based on the specified parameters, query, and data model.
**Note:**
Multiple data model IDs are available and can be found at:
[https://marketplace.dappier.com/marketplace](https://marketplace.dappier.com/marketplace)
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.data_commons_toolkit
## DataCommonsToolkit
```python theme={"system"}
class DataCommonsToolkit(BaseToolkit):
```
A class representing a toolkit for Data Commons.
This class provides methods for querying and retrieving data from the
Data Commons knowledge graph. It includes functionality for:
* Executing SPARQL queries
* Retrieving triples associated with nodes
* Fetching statistical time series data
* Analyzing property labels and values
* Retrieving places within a given place type
* Obtaining statistical values for specific variables and locations
All the data are grabbed from the knowledge graph of Data Commons.
Refer to [https://datacommons.org/browser/](https://datacommons.org/browser/) for more details.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the DataCommonsToolkit.
**Parameters:**
* **timeout** (Optional\[float], optional): Maximum time in seconds to wait for API calls to complete. If None, will wait indefinitely. (default: :obj:`None`)
### get\_triples\_outgoing
```python theme={"system"}
def get_triples_outgoing(self, dcids: Union[str, List[str]]):
```
Retrieve triples associated with nodes for outgoing relationships.
**Parameters:**
* **dcids** (Union\[str, List\[str]]): A single DCID or a list of DCIDs to query.
**Returns:**
Optional\[Dict\[str, List\[tuple]]]: A dictionary where keys are
DCIDs and values are lists of associated triples if success,
(default: :obj:`None`) otherwise.
### get\_triples\_incoming
```python theme={"system"}
def get_triples_incoming(self, dcids: Union[str, List[str]]):
```
Retrieve triples associated with nodes for incoming relationships.
**Parameters:**
* **dcids** (Union\[str, List\[str]]): A single DCID or a list of DCIDs to query.
**Returns:**
Optional\[Dict\[str, List\[tuple]]]: A dictionary where keys are
DCIDs and values are lists of associated triples if success,
(default: :obj:`None`) otherwise.
### get\_stat
```python theme={"system"}
def get_stat(
self,
date: str,
entity_dcids: Union[str, List[str]],
variable_dcids: Union[str, List[str]]
):
```
Retrieve statistical time series for a place.
**Parameters:**
* **date** (str): The date option for the observations. Use 'all' for all dates, 'latest' for the most recent data, or provide a date as a string (e.g., "2026").
* **entity\_dcids** (Union\[str, List\[str]]): Entity IDs to filter the data.
* **variable\_dcids** (Union\[str, List\[str]]): The variable(s) to fetch observations for. This can be a single variable ID or a list of IDs.
**Returns:**
Optional\[Dict\[str, Any]]: A dictionary containing the statistical
time series data if success, (default: :obj:`None`) otherwise.
### get\_property\_labels
```python theme={"system"}
def get_property_labels(self, dcids: Union[str, List[str]], out: bool = True):
```
Retrieves and analyzes property labels for given DCIDs.
**Parameters:**
* **dcids** (Union\[str, List\[str]]): A single DCID or a list of DCIDs to query.
* **out** (bool): Whether to fetch outgoing properties (default: :obj:`True`)
**Returns:**
Optional\[Dict\[str, List\[str]]]: Analysis results for each DCID if
success, (default: :obj:`None`) otherwise.
### get\_property\_values
```python theme={"system"}
def get_property_values(
self,
dcids: Union[str, List[str]],
properties: Union[str, List[str]],
constraints: Optional[str] = None,
out: Optional[bool] = True
):
```
Retrieves and analyzes property values for given DCIDs.
**Parameters:**
* **dcids** (Union\[str, List\[str]]): A single DCID or a list of DCIDs to query.
* **properties** (Union\[str, List\[str]]): The property or properties to analyze.
* **constraints** (Optional\[str]): Additional constraints for the query. (default: :obj:`None`)
* **out** (bool, optional): Whether to fetch outgoing properties. (default: :obj:`True`)
**Returns:**
Optional\[Dict\[str, Any]]: Analysis results for each DCID if
success, (default: :obj:`None`) otherwise.
### get\_places\_in
```python theme={"system"}
def get_places_in(
self,
place_dcids: Union[str, List[str]],
children_type: Optional[str] = None
):
```
Retrieves places within a given place type.
**Parameters:**
* **place\_dcids** (Union\[str, List\[str]]): A single DCID or a list of DCIDs to query.
* **children\_type** (Optional\[str]): The type of the child entities to fetch. If None, fetches all child types. (default: :obj:`None`)
**Returns:**
Optional\[Dict\[str, Any]]: Analysis results for each DCID if
success, (default: :obj:`None`) otherwise.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.dingtalk
## \_get\_dingtalk\_access\_token
```python theme={"system"}
def _get_dingtalk_access_token():
```
**Returns:**
str: Access token for API requests.
## \_make\_dingtalk\_request
```python theme={"system"}
def _make_dingtalk_request(method: Literal['GET', 'POST'], endpoint: str, **kwargs):
```
Makes authenticated request to Dingtalk API.
**Parameters:**
* **method** (`Literal["GET", "POST"]`): HTTP method to use.
* **endpoint** (str): API endpoint path. \*\*kwargs: Additional arguments passed to requests.
**Returns:**
Dict\[str, Any]: API response data.
**Raises:**
* **Exception**: If API request fails or returns error.
## \_generate\_signature
```python theme={"system"}
def _generate_signature(secret: str, timestamp: str):
```
Generates signature for Dingtalk webhook.
**Parameters:**
* **secret** (str): Webhook secret.
* **timestamp** (str): Current timestamp.
**Returns:**
str: Generated signature.
## DingtalkToolkit
```python theme={"system"}
class DingtalkToolkit(BaseToolkit):
```
A toolkit for Dingtalk operations.
This toolkit provides methods to interact with the Dingtalk API,
allowing users to send messages, manage users, departments, and handle
webhook operations.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the DingtalkToolkit.
**Parameters:**
* **timeout** (Optional\[float]): Timeout for API requests in seconds.
### \_initialize\_token\_safely
```python theme={"system"}
def _initialize_token_safely(self):
```
Safely initializes access token during toolkit setup.
This method attempts to get an access token during initialization
but doesn't raise exceptions if it fails, allowing the toolkit
to be instantiated even if credentials are temporarily invalid.
### dingtalk\_send\_text\_message
```python theme={"system"}
def dingtalk_send_text_message(self, userid: str, content: str):
```
Sends a text message to a Dingtalk user.
**Parameters:**
* **userid** (str): The user's userid.
* **content** (str): Message content.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/send-single-chat-message](https://open.dingtalk.com/document/orgapp-server/send-single-chat-message)
### dingtalk\_send\_markdown\_message
```python theme={"system"}
def dingtalk_send_markdown_message(
self,
userid: str,
title: str,
markdown_content: str
):
```
Sends a markdown message to a Dingtalk user.
**Parameters:**
* **userid** (str): The user's userid.
* **title** (str): Message title.
* **markdown\_content** (str): Markdown formatted content.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/send-single-chat-message](https://open.dingtalk.com/document/orgapp-server/send-single-chat-message)
### dingtalk\_get\_user\_info
```python theme={"system"}
def dingtalk_get_user_info(self, userid: str):
```
Retrieves Dingtalk user information.
**Parameters:**
* **userid** (str): The user's userid.
**Returns:**
Dict\[str, Any]: User information or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/query-user-details](https://open.dingtalk.com/document/orgapp-server/query-user-details)
### dingtalk\_get\_department\_list
```python theme={"system"}
def dingtalk_get_department_list(self, dept_id: Optional[int] = None):
```
Retrieves list of departments.
**Parameters:**
* **dept\_id** (Optional\[int]): Department ID. If None, gets root departments.
**Returns:**
Dict\[str, Any]: Department list or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/obtain-the-department-list-v2](https://open.dingtalk.com/document/orgapp-server/obtain-the-department-list-v2)
### dingtalk\_get\_department\_users
```python theme={"system"}
def dingtalk_get_department_users(
self,
dept_id: int,
offset: int = 0,
size: int = 100
):
```
Retrieves users in a department.
**Parameters:**
* **dept\_id** (int): Department ID.
* **offset** (int): Offset for pagination (default: 0). (default: 0)
* **size** (int): Number of users to retrieve (default: 100, max: 100). (default: 100, max: 100)
**Returns:**
Dict\[str, Any]: Users list or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/queries-the-complete-information-of-a-department-user](https://open.dingtalk.com/document/orgapp-server/queries-the-complete-information-of-a-department-user)
### dingtalk\_search\_users\_by\_name
```python theme={"system"}
def dingtalk_search_users_by_name(self, name: str):
```
Searches for users by name.
**Parameters:**
* **name** (str): User name to search for.
**Returns:**
Dict\[str, Any]: Search results or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/query-users](https://open.dingtalk.com/document/orgapp-server/query-users)
### dingtalk\_send\_webhook\_message
```python theme={"system"}
def dingtalk_send_webhook_message(
self,
content: str,
msgtype: Literal['text', 'markdown', 'link', 'actionCard'] = 'text',
title: Optional[str] = None,
webhook_url: Optional[str] = None,
webhook_secret: Optional[str] = None
):
```
Sends a message via Dingtalk webhook.
**Parameters:**
* **content** (str): Message content.
* **msgtype** (Literal): Message type (text, markdown, link, actionCard).
* **title** (Optional\[str]): Message title (required for markdown).
* **webhook\_url** (Optional\[str]): Webhook URL. If None, uses env var.
* **webhook\_secret** (Optional\[str]): Webhook secret. If None, uses env var.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/robots/custom-robot-access](https://open.dingtalk.com/document/robots/custom-robot-access)
### dingtalk\_create\_group
```python theme={"system"}
def dingtalk_create_group(
self,
name: str,
owner: str,
useridlist: List[str]
):
```
Creates a Dingtalk group.
**Parameters:**
* **name** (str): Group name.
* **owner** (str): Group owner's userid.
* **useridlist** (List\[str]): List of user IDs to add to the group.
**Returns:**
Dict\[str, Any]: Group creation result with chatid or error.
References:
[https://open.dingtalk.com/document/orgapp-server/create-group-session](https://open.dingtalk.com/document/orgapp-server/create-group-session)
### dingtalk\_send\_group\_message
```python theme={"system"}
def dingtalk_send_group_message(
self,
chatid: str,
content: str,
msgtype: Literal['text', 'markdown'] = 'text'
):
```
Sends a message to a Dingtalk group.
**Parameters:**
* **chatid** (str): Group chat ID.
* **content** (str): Message content.
* **msgtype** (`Literal["text", "markdown"]`): Message type.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/send-group-messages](https://open.dingtalk.com/document/orgapp-server/send-group-messages)
### dingtalk\_send\_link\_message
```python theme={"system"}
def dingtalk_send_link_message(
self,
userid: str,
title: str,
text: str,
message_url: str,
pic_url: Optional[str] = None
):
```
Sends a link message to a Dingtalk user.
**Parameters:**
* **userid** (str): The user's userid.
* **title** (str): Link title.
* **text** (str): Link description text.
* **message\_url** (str): URL to link to.
* **pic\_url** (Optional\[str]): Picture URL for the link.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/send-single-chat-message](https://open.dingtalk.com/document/orgapp-server/send-single-chat-message)
### dingtalk\_send\_action\_card\_message
```python theme={"system"}
def dingtalk_send_action_card_message(
self,
userid: str,
title: str,
text: str,
single_title: str,
single_url: str
):
```
Sends an action card message to a Dingtalk user.
**Parameters:**
* **userid** (str): The user's userid.
* **title** (str): Card title.
* **text** (str): Card content text.
* **single\_title** (str): Action button title.
* **single\_url** (str): Action button URL.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/send-single-chat-message](https://open.dingtalk.com/document/orgapp-server/send-single-chat-message)
### dingtalk\_get\_user\_by\_mobile
```python theme={"system"}
def dingtalk_get_user_by_mobile(self, mobile: str):
```
Gets user information by mobile number.
**Parameters:**
* **mobile** (str): User's mobile number. Should be a valid Chinese mobile number format (11 digits starting with 1).
**Returns:**
Dict\[str, Any]: User information or error information.
### dingtalk\_get\_user\_by\_unionid
```python theme={"system"}
def dingtalk_get_user_by_unionid(self, unionid: str):
```
Gets user information by unionid.
**Parameters:**
* **unionid** (str): User's unique identifier across all DingTalk organizations. This is a global identifier that remains consistent even if the user belongs to multiple DingTalk organizations, unlike userid which is organization-specific.
**Returns:**
Dict\[str, Any]: User information or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/query-a-user-by-the-union-id](https://open.dingtalk.com/document/orgapp-server/query-a-user-by-the-union-id)
### dingtalk\_get\_department\_detail
```python theme={"system"}
def dingtalk_get_department_detail(self, dept_id: int):
```
Gets detailed information about a department.
**Parameters:**
* **dept\_id** (int): Department ID.
**Returns:**
Dict\[str, Any]: Department details or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/query-department-details0-v2](https://open.dingtalk.com/document/orgapp-server/query-department-details0-v2)
### dingtalk\_send\_oa\_message
```python theme={"system"}
def dingtalk_send_oa_message(
self,
userid: str,
message_url: str,
head_bgcolor: str,
head_text: str,
body_title: str,
body_content: str
):
```
Sends an OA (Office Automation) message to a Dingtalk user.
**Parameters:**
* **userid** (str): The user's userid.
* **message\_url** (str): URL for the message action.
* **head\_bgcolor** (str): Header background color (hex format).
* **head\_text** (str): Header text.
* **body\_title** (str): Body title.
* **body\_content** (str): Body content.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/send-single-chat-message](https://open.dingtalk.com/document/orgapp-server/send-single-chat-message)
### dingtalk\_get\_group\_info
```python theme={"system"}
def dingtalk_get_group_info(self, chatid: str):
```
Gets information about a group chat.
**Parameters:**
* **chatid** (str): Group chat ID.
**Returns:**
Dict\[str, Any]: Group information or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/query-group-session-information](https://open.dingtalk.com/document/orgapp-server/query-group-session-information)
### dingtalk\_update\_group
```python theme={"system"}
def dingtalk_update_group(
self,
chatid: str,
name: Optional[str] = None,
owner: Optional[str] = None,
add_useridlist: Optional[List[str]] = None,
del_useridlist: Optional[List[str]] = None
):
```
Updates a Dingtalk group configuration.
**Parameters:**
* **chatid** (str): Group chat ID.
* **name** (Optional\[str]): New group name.
* **owner** (Optional\[str]): New group owner userid.
* **add\_useridlist** (Optional\[List\[str]]): List of user IDs to add.
**Returns:**
Dict\[str, Any]: Update result or error information.
References:
[https://open.dingtalk.com/document/orgapp-server/modify-group-session](https://open.dingtalk.com/document/orgapp-server/modify-group-session)
### dingtalk\_send\_work\_notification
```python theme={"system"}
def dingtalk_send_work_notification(
self,
userid_list: List[str],
msg_content: str,
msg_type: Literal['text', 'markdown'] = 'text'
):
```
Sends work notification to multiple users.
**Parameters:**
* **userid\_list** (List\[str]): List of user IDs to send to.
**Returns:**
str: Success or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/asynchronous-sending-of-enterprise-session-messages](https://open.dingtalk.com/document/orgapp-server/asynchronous-sending-of-enterprise-session-messages)
### dingtalk\_get\_userid\_by\_phone
```python theme={"system"}
def dingtalk_get_userid_by_phone(self, phone_number: str):
```
Gets user ID by phone number for LLM agents.
**Parameters:**
* **phone\_number** (str): User's phone number.
**Returns:**
str: User ID or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/query-user-details](https://open.dingtalk.com/document/orgapp-server/query-user-details)
### dingtalk\_get\_userid\_by\_name
```python theme={"system"}
def dingtalk_get_userid_by_name(self, user_name: str):
```
Gets user ID by user name for LLM agents.
**Parameters:**
* **user\_name** (str): User's display name.
**Returns:**
str: User ID or error message.
References:
[https://open.dingtalk.com/document/orgapp-server/query-users](https://open.dingtalk.com/document/orgapp-server/query-users)
### dingtalk\_get\_department\_id\_by\_name
```python theme={"system"}
def dingtalk_get_department_id_by_name(self, department_name: str):
```
Gets department ID by department name for LLM agents.
**Parameters:**
* **department\_name** (str): Department name to search for.
**Returns:**
str: Department ID or error message.
### dingtalk\_get\_chatid\_by\_group\_name
```python theme={"system"}
def dingtalk_get_chatid_by_group_name(self, group_name: str):
```
Gets chat ID by group name for LLM agents.
**Parameters:**
* **group\_name** (str): Group name to search for.
**Returns:**
str: Guidance message for obtaining chat ID.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Returns toolkit functions as tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.earth_science_toolkit
## EarthScienceToolkit
```python theme={"system"}
class EarthScienceToolkit(BaseToolkit):
```
A class representing a toolkit for earth observation science.
This class provides 104 basic methods for earth observation solutions:
Index (12), Inversion (18), Perception (15), Analysis (10), Statistics
(49).
### calculate\_ndvi
```python theme={"system"}
def calculate_ndvi(
self,
input_nir_path,
input_red_path,
output_path
):
```
Calculate NDVI from NIR and Red band rasters.
**Parameters:**
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **input\_red\_path** (str): Path to Red band raster file.
* **output\_path** (str): Relative output path, e.g. "question17/ndvi\_2022-01-16.tif"
**Returns:**
str: Path to the saved NDVI file.
### calculate\_batch\_ndvi
```python theme={"system"}
def calculate_batch_ndvi(
self,
input_nir_paths: list[str],
input_red_paths: list[str],
output_paths: list[str]
):
```
Batch-calculate NDVI from multiple pairs of NIR/Red rasters.
**Parameters:**
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **input\_red\_paths** (list\[str]): Paths to Red band rasters.
* **output\_paths** (list\[str]): Relative output paths.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_ndwi
```python theme={"system"}
def calculate_ndwi(
self,
input_nir_path,
input_swir_path,
output_path
):
```
Calculate NDWI from NIR and SWIR band rasters.
**Parameters:**
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **input\_swir\_path** (str): Path to Short-Wave Infrared (SWIR) raster.
* **output\_path** (str): Relative output path, e.g. "question17/ndwi\_2022-01-16.tif"
**Returns:**
str: Path to the saved NDWI file.
### calculate\_batch\_ndwi
```python theme={"system"}
def calculate_batch_ndwi(
self,
input_nir_paths: list[str],
input_swir_paths: list[str],
output_paths: list[str]
):
```
Batch-calculate NDWI from multiple pairs of NIR/SWIR rasters.
**Parameters:**
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **input\_swir\_paths** (list\[str]): Paths to SWIR band rasters.
* **output\_paths** (list\[str]): Relative output paths.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_ndbi
```python theme={"system"}
def calculate_ndbi(
self,
input_swir_path,
input_nir_path,
output_path
):
```
Calculate NDBI from SWIR and NIR band rasters.
**Parameters:**
* **input\_swir\_path** (str): Path to Short-Wave Infrared (SWIR) raster.
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **output\_path** (str): Relative output path, e.g. "question17/ndbi\_2022-01-16.tif"
**Returns:**
str: Path to the saved NDBI file.
### calculate\_batch\_ndbi
```python theme={"system"}
def calculate_batch_ndbi(
self,
input_swir_paths: list[str],
input_nir_paths: list[str],
output_paths: list[str]
):
```
Batch-calculate NDBI from multiple pairs of SWIR/NIR rasters.
**Parameters:**
* **input\_swir\_paths** (list\[str]): Paths to SWIR band rasters.
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **output\_paths** (list\[str]): Relative output paths.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_evi
```python theme={"system"}
def calculate_evi(
self,
input_nir_path,
input_red_path,
input_blue_path,
output_path,
G: float = 2.5,
C1: float = 6,
C2: float = 7.5,
L: float = 1
):
```
Calculate EVI from NIR, Red, and Blue band rasters.
**Parameters:**
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **input\_red\_path** (str): Path to Red band raster file.
* **input\_blue\_path** (str): Path to Blue band raster file.
* **output\_path** (str): Relative output path, e.g. "question17/evi\_2022-01-16.tif"
* **G** (float, optional): Gain factor. Defaults to 2.5. (default: 2)
* **C1** (float, optional): Coefficient 1. Defaults to 6. (default: 6)
* **C2** (float, optional): Coefficient 2. Defaults to 7.5. (default: 7)
* **L** (float, optional): Adjustment factor. Defaults to 1. (default: 1)
### calculate\_batch\_evi
```python theme={"system"}
def calculate_batch_evi(
self,
input_nir_paths: list[str],
input_red_paths: list[str],
input_blue_paths: list[str],
output_paths: list[str],
G: float = 2.5,
C1: float = 6,
C2: float = 7.5,
L: float = 1
):
```
Batch-calculate EVI from multiple sets of NIR/Red/Blue rasters.
**Parameters:**
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **input\_red\_paths** (list\[str]): Paths to Red band rasters.
* **input\_blue\_paths** (list\[str]): Paths to Blue band rasters.
* **output\_paths** (list\[str]): Relative output paths. G, C1, C2, L (float, optional): EVI coefficients.
**Returns:**
list\[str]: Result messages from each `calculate_evi` call.
### calculate\_nbr
```python theme={"system"}
def calculate_nbr(
self,
input_nir_path,
input_swir_path,
output_path
):
```
Calculate NBR from NIR and SWIR band rasters.
**Parameters:**
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **input\_swir\_path** (str): Path to Short-Wave Infrared (SWIR) raster.
* **output\_path** (str): Relative output path, e.g. "question17/nbr\_2022-01-16.tif"
**Returns:**
str: Path to the saved NBR file.
### calculate\_batch\_nbr
```python theme={"system"}
def calculate_batch_nbr(
self,
input_nir_paths: list[str],
input_swir_paths: list[str],
output_paths: list[str]
):
```
Batch-calculate NBR from multiple pairs of NIR/SWIR rasters.
**Parameters:**
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **input\_swir\_paths** (list\[str]): Paths to SWIR band rasters.
* **output\_paths** (list\[str]): Relative output paths.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_fvc
```python theme={"system"}
def calculate_fvc(
self,
input_nir_path,
input_red_path,
output_path,
ndvi_min = 0.1,
ndvi_max = 0.9
):
```
Calculate FVC from NIR and Red band rasters.
**Parameters:**
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **input\_red\_path** (str): Path to Red band raster file.
* **output\_path** (str): Relative output path.
* **ndvi\_min** (float): Min NDVI for non-vegetated areas (default: 0.1). (default: 0.1)
* **ndvi\_max** (float): Max NDVI for fully vegetated areas (default: 0. 9).
**Returns:**
str: Path to the saved FVC raster file.
### calculate\_batch\_fvc
```python theme={"system"}
def calculate_batch_fvc(
self,
input_nir_paths: list[str],
input_red_paths: list[str],
output_paths: list[str],
ndvi_min: float = 0.1,
ndvi_max: float = 0.9
):
```
Batch-calculate FVC from multiple pairs of NIR/Red rasters.
**Parameters:**
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **input\_red\_paths** (list\[str]): Paths to Red band rasters.
* **output\_paths** (list\[str]): Relative output paths.
* **ndvi\_min** (float, optional): Min NDVI for non-vegetated areas.
* **ndvi\_max** (float, optional): Max NDVI for fully vegetated areas.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_wri
```python theme={"system"}
def calculate_wri(
self,
input_green_path,
input_red_path,
input_nir_path,
input_swir_path,
output_path
):
```
Calculate WRI from Green, Red, NIR, and SWIR band rasters.
**Parameters:**
* **input\_green\_path** (str): Path to Green band raster file.
* **input\_red\_path** (str): Path to Red band raster file.
* **input\_nir\_path** (str): Path to Near-Infrared (NIR) band raster.
* **input\_swir\_path** (str): Path to Short-Wave Infrared (SWIR) raster.
* **output\_path** (str): Relative output path.
**Returns:**
str: Path to the saved WRI raster file.
### calculate\_batch\_wri
```python theme={"system"}
def calculate_batch_wri(
self,
input_green_paths: list[str],
input_red_paths: list[str],
input_nir_paths: list[str],
input_swir_paths: list[str],
output_paths: list[str]
):
```
Batch-calculate WRI from multiple raster sets.
**Parameters:**
* **input\_green\_paths** (list\[str]): Paths to Green band rasters.
* **input\_red\_paths** (list\[str]): Paths to Red band rasters.
* **input\_nir\_paths** (list\[str]): Paths to NIR band rasters.
* **input\_swir\_paths** (list\[str]): Paths to SWIR band rasters.
* **output\_paths** (list\[str]): Relative output paths.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_ndti
```python theme={"system"}
def calculate_ndti(
self,
input_red_path,
input_green_path,
output_path
):
```
Calculate NDTI from Red and Green band rasters.
**Parameters:**
* **input\_red\_path** (str): Path to Red band raster file.
* **input\_green\_path** (str): Path to Green band raster file.
* **output\_path** (str): Relative output path.
**Returns:**
str: Path to the saved NDTI file.
### calculate\_batch\_ndti
```python theme={"system"}
def calculate_batch_ndti(
self,
input_red_paths: list[str],
input_green_paths: list[str],
output_paths: list[str]
):
```
Batch-calculate NDTI from multiple pairs of Red/Green rasters.
**Parameters:**
* **input\_red\_paths** (list\[str]): Paths to Red band rasters.
* **input\_green\_paths** (list\[str]): Paths to Green band rasters.
* **output\_paths** (list\[str]): Relative output paths (e.g., "question17/ndti\_2022-01-16.tif").
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_frp
```python theme={"system"}
def calculate_frp(
self,
input_frp_path,
output_path,
fire_threshold = 0
):
```
Calculate Fire Radiative Power (FRP) statistics from input raster
files and save the result to a specified output path.
**Parameters:**
* **input\_frp\_path** (str): Path to the FRP raster file.
* **output\_path** (str): relative path for the output raster file, e.g. "question17/frp\_2022-01-16.tif"
* **fire\_threshold** (float): Minimum FRP value to be considered as fire (default: 0).
**Returns:**
str: Path to the saved fire mask file.
### calculate\_batch\_frp
```python theme={"system"}
def calculate_batch_frp(
self,
input_frp_paths: list[str],
output_paths: list[str],
fire_threshold: float = 0
):
```
Batch-calculate FRP fire masks from multiple raster files.
**Parameters:**
* **input\_frp\_paths** (list\[str]): Paths to FRP raster files.
* **output\_paths** (list\[str]): Relative output paths (e.g., "question17/frp\_2022-01-16.tif").
* **fire\_threshold** (float, optional): Minimum FRP value to be considered as fire. Defaults to 0.
**Returns:**
list\[str]: A list of result messages (e.g., saved file paths).
### calculate\_ndsi
```python theme={"system"}
def calculate_ndsi(
self,
input_green_path: str,
input_swir_path: str,
output_path: str
):
```
Calculate the Normalized Difference Snow Index (NDSI) from input
raster files and save the result to a specified output path.
NDSI = (Green - SWIR) / (Green + SWIR)
**Parameters:**
* **input\_green\_path** (str): Path to the Green band raster file.
* **input\_swir\_path** (str): Path to the SWIR band raster file.
* **output\_path** (str): relative path for the output raster file, e.g. "question17/ndsi\_2022-01-16.tif"
**Returns:**
str: Path to the output NDSI raster file.
### calculate\_batch\_ndsi
```python theme={"system"}
def calculate_batch_ndsi(
self,
green_file_list: list[str],
swir_file_list: list[str],
output_path_list: list[str]
):
```
Calculate NDSI for multiple pairs of Green and SWIR band images.
**Parameters:**
* **green\_file\_list** (list\[str]): List of paths to Green band raster files.
* **swir\_file\_list** (list\[str]): List of paths to SWIR band raster files.
* **output\_path\_list** (list\[str]): relative path for the output raster file, e.g. \["question17/ndsi\_2022-01-16.tif", "question17/ ndsi\_2022-01-16.tif"]
**Returns:**
list\[str]: List of paths to the output NDSI raster files.
### calc\_extreme\_snow\_loss\_percentage\_from\_binary\_map
```python theme={"system"}
def calc_extreme_snow_loss_percentage_from_binary_map(self, binary_map_path: str):
```
Calculate the percentage of extreme snow and ice loss areas from a
binary map.
**Parameters:**
* **binary\_map\_path** (str): Path to the binary raster image where pixels with value 1.0 represent extreme snow/ice loss areas.
**Returns:**
float:
The percentage of extreme snow/ice loss pixels relative to all
valid pixels
(range: 0.0-1.0).
### compute\_tvdi
```python theme={"system"}
def compute_tvdi(
self,
ndvi_path: str,
lst_path: str,
output_path: str
):
```
Description:
Compute the Temperature Vegetation Dryness Index (TVDI) based on
NDVI and LST raster data.
TVDI quantifies soil moisture conditions by analyzing the
relationship between NDVI and LST
through a trapezoidal space approach. The function fits linear
regressions for LST maxima
and minima per NDVI bin and normalizes per-pixel LST values
accordingly.
**Parameters:**
* **ndvi\_path** (str): Path to the NDVI GeoTIFF file (e.g., MODIS NDVI scaled by 0.0001).
* **lst\_path** (str): Path to the LST GeoTIFF file (e.g., MODIS LST scaled by 0.02).
* **output\_path** (str): Relative path to save the computed TVDI raster (e.g., "question17/tvdi\_2022-01-16.tif").
**Returns:**
str: Path to the saved TVDI GeoTIFF file.
### band\_ratio
```python theme={"system"}
def band_ratio(
self,
sur_refl_b02_path: str,
sur_refl_b05_path: str,
sur_refl_b17_path: str,
sur_refl_b18_path: str,
sur_refl_b19_path: str,
output_path: str
):
```
Description:
Compute a Precipitable Water Vapor (PWV) image from MODIS surface
reflectance bands
using the band ratio method.
This method interpolates atmospheric window reflectance between 0.
865 µm and 1.240 µm,
computes transmittance in water vapor absorption bands (0.905, 0.
936, 0.940 µm),
and derives PWV in centimeters.
The output GeoTIFF contains four bands:
1. PWV
2. T17 (transmittance at 0.905 µm)
3. T18 (transmittance at 0.936 µm)
4. T19 (transmittance at 0.940 µm)
**Parameters:**
* **sur\_refl\_b02\_path** (str): Path to MODIS surface reflectance band sur\_refl\_b02 (0.865 µm) GeoTIFF.
* **sur\_refl\_b05\_path** (str): Path to MODIS surface reflectance band sur\_refl\_b05 (1.240 µm) GeoTIFF.
* **sur\_refl\_b17\_path** (str): Path to MODIS surface reflectance band sur\_refl\_b17 (0.905 µm) GeoTIFF.
* **sur\_refl\_b18\_path** (str): Path to MODIS surface reflectance band sur\_refl\_b18 (0.936 µm) GeoTIFF.
* **sur\_refl\_b19\_path** (str): Path to MODIS surface reflectance band sur\_refl\_b19 (0.940 µm) GeoTIFF.
* **output\_path** (str): Relative output path for the PWV GeoTIFF, e.g. "question17/pwv\_2022-01-16.tif".
**Returns:**
str: Full path to the saved PWV GeoTIFF.
### lst\_single\_channel
```python theme={"system"}
def lst_single_channel(
self,
bt_path: str,
red_path: str,
nir_path: str,
output_path: str
):
```
Description:
Estimate Land Surface Temperature (LST) using the Single-Channel
method.
This approach calculates LST from thermal brightness temperature
and adjusts
for surface emissivity estimated using NDVI derived from RED and
NIR bands.
It is suitable for single thermal band sensors such as Landsat 8
TIRS.
**Parameters:**
* **bt\_path** (str): Path to the Brightness Temperature GeoTIFF (Kelvin).
* **red\_path** (str): Path to the RED band GeoTIFF (e.g., Landsat 8 Band 4).
* **nir\_path** (str): Path to the NIR band GeoTIFF (e.g., Landsat 8 Band 5).
* **output\_path** (str): Relative path for the output LST GeoTIFF, e.g. "question17/lst\_2022-01-16.tif".
**Returns:**
str: Full path to the saved LST GeoTIFF.
### lst\_multi\_channel
```python theme={"system"}
def lst_multi_channel(
self,
band31_path: str,
band32_path: str,
output_path: str
):
```
Description:
Estimate Land Surface Temperature (LST) using the multi-channel
algorithm.
This method combines two thermal infrared bands (typically at \~11
μm and \~12 μm)
to reduce atmospheric effects and improve LST estimation accuracy.
**Parameters:**
* **band31\_path** (str): Path to local GeoTIFF file for thermal band 31 (\~11 μm).
* **band32\_path** (str): Path to local GeoTIFF file for thermal band 32 (\~12 μm).
* **output\_path** (str): Relative path for the output LST GeoTIFF, e.g. "question17/lst\_2022-01-16.tif".
**Returns:**
str: Full path to the saved LST GeoTIFF.
### split\_window
```python theme={"system"}
def split_window(
self,
band31_path: str,
band32_path: str,
emissivity31_path: str,
emissivity32_path: str,
parameter: str,
output_path: str
):
```
Description:
Estimate **Land Surface Temperature (LST)** or **Precipitable
Water Vapor (PWV)**
using the split-window algorithm.
The method leverages two thermal infrared bands (\~11 μm and \~12 μm)
and emissivity data to correct atmospheric effects and retrieve
accurate surface or atmospheric Args.
Only one parameter is computed based on the user-selected
`parameter`.
**Parameters:**
* **band31\_path** (str): Path to thermal band 31 GeoTIFF (\~11 μm).
* **band32\_path** (str): Path to thermal band 32 GeoTIFF (\~12 μm).
* **emissivity31\_path** (str): Path to emissivity band 31 GeoTIFF.
* **emissivity32\_path** (str): Path to emissivity band 32 GeoTIFF.
* **parameter** (str): Specify either `"LST"` for Land Surface Temperature or `"PWV"` for Precipitable Water Vapor.
* **output\_path** (str): Relative path for the output raster file, e.g. `"question17/lst_2022-01-16.tif"`.
**Returns:**
str: Full path to the saved GeoTIFF containing the selected
parameter.
### temperature\_emissivity\_separation
```python theme={"system"}
def temperature_emissivity_separation(
self,
tir_band_paths: list[str],
representative_band_index: int,
output_path: str
):
```
Description:
Estimate Land Surface Temperature (LST) using the Temperature
Emissivity Separation (TES)
algorithm with empirical emissivity estimation. Outputs a
multi-band raster containing LST,
emissivity, and emissivity variation (Δε).
**Parameters:**
* **tir\_band\_paths** (list\[str]): List of paths to Thermal Infrared (TIR) GeoTIFFs (e.g., ASTER Bands 10-14).
* **representative\_band\_index** (int): Index of the TIR band used as the reference brightness temperature (e.g., 3 for Band 13).
* **output\_path** (str): Relative path for saving the output raster file (e.g., "question17/lst\_2022-01-16.tif").
**Returns:**
str: Path to the saved GeoTIFF file containing:
* Band 1: LST (K)
* Band 2: Emissivity (ε)
* Band 3: Emissivity variation (Δε)
### modis\_day\_night\_lst
```python theme={"system"}
def modis_day_night_lst(
self,
BT_day_path: str,
BT_night_path: str,
Emis_day_path: str,
Emis_night_path: str,
output_path: str
):
```
Description:
Estimate Land Surface Temperature (LST) from MODIS Day and Night
brightness temperatures
using a single-channel correction algorithm. Performs resampling,
scaling, and filtering
of emissivity and brightness temperature bands to output a
six-band GeoTIFF.
**Parameters:**
* **BT\_day\_path** (str): Path to local MODIS Brightness Temperature Day GeoTIFF.
* **BT\_night\_path** (str): Path to local MODIS Brightness Temperature Night GeoTIFF.
* **Emis\_day\_path** (str): Path to MODIS Emissivity Day GeoTIFF (scaled by 0.002, offset by 0.49).
* **Emis\_night\_path** (str): Path to MODIS Emissivity Night GeoTIFF (scaled by 0.002, offset by 0.49).
* **output\_path** (str): Relative path for saving the output raster file (e.g., "question17/lst\_2022-01-16.tif").
**Returns:**
str: Path to the exported GeoTIFF with six bands:
* Band 1: LST (Day)
* Band 2: LST (Night)
* Band 3: BT (Day)
* Band 4: BT (Night)
* Band 5: Emissivity (Day)
* Band 6: Emissivity (Night)
### ttm\_lst
```python theme={"system"}
def ttm_lst(
self,
tir_band_paths: list[str],
output_path: str,
wavelengths: list[float] | None = None
):
```
Estimate LST and emissivity using Three-Temperature Method.
Reads three thermal infrared (TIR) bands, performs filtering,
applies empirical atmospheric correction, and outputs a
three-band GeoTIFF with LST and emissivity estimates.
**Parameters:**
* **tir\_band\_paths** (list\[str]): Paths to three TIR band GeoTIFFs (e.g., ASTER B10, B11, B12).
* **output\_path** (str): Relative path to save the output raster.
* **wavelengths** (list\[float], optional): Central wavelengths (μm) for each band. Defaults to \[8.3, 8.65, 9.1].
**Returns:**
str: Path to exported GeoTIFF with LST (K) and emissivity bands.
### calculate\_mean\_lst\_by\_ndvi
```python theme={"system"}
def calculate_mean_lst_by_ndvi(
self,
red_paths: str | list[str],
nir_paths: str | list[str],
lst_paths: str | list[str],
ndvi_threshold: float,
mode: str = 'above'
):
```
Calculate the average Land Surface Temperature (LST) across multiple
images where NDVI is either above or below a given threshold.
**Parameters:**
* **red\_paths** (str or list): Path(s) to red band image(s).
* **nir\_paths** (str or list): Path(s) to near-infrared (NIR) image(s).
* **lst\_paths** (str or list): Path(s) to land surface temperature (LST) image(s).
* **ndvi\_threshold** (float): Threshold value for NDVI.
* **mode** (str): 'above' for NDVI >= threshold, 'below' for NDVI \< threshold.
**Returns:**
float: Mean of LST values over selected NDVI regions across all
image sets. Returns np.nan if no valid pixels found.
### calculate\_max\_lst\_by\_ndvi
```python theme={"system"}
def calculate_max_lst_by_ndvi(
self,
red_path: str,
nir_path: str,
lst_path: str,
ndvi_threshold: float,
mode: str = 'above'
):
```
Calculate the maximum Land Surface Temperature (LST) in areas where
NDVI is above or below a given threshold.
**Parameters:**
* **red\_path** (str): Path to the red band image.
* **nir\_path** (str): Path to the near-infrared (NIR) band image.
* **lst\_path** (str): Path to the land surface temperature (LST) image.
* **ndvi\_threshold** (float): Threshold value for NDVI.
* **mode** (str): 'above' to select NDVI >= threshold, 'below' for NDVI \< threshold. Default is 'above'.
**Returns:**
float: Maximum LST value over the selected NDVI region. Returns np.
nan if no valid data.
### calculate\_ATI
```python theme={"system"}
def calculate_ATI(
self,
day_temp_path: str,
night_temp_path: str,
albedo_path: str,
output_path: str
):
```
Description:
Estimate Apparent Thermal Inertia (ATI) using the Thermal Inertia
Method.
ATI is computed as (1 - Albedo) / (Daytime BT - Nighttime BT) and
serves as a proxy for
land surface heat retention and thermal stability over diurnal
cycles.
The function aligns all raster layers to the daytime brightness
temperature raster's resolution and extent before calculation.
**Parameters:**
* **day\_temp\_path** (str): Path to the daytime brightness temperature (BT) GeoTIFF.
* **night\_temp\_path** (str): Path to the nighttime brightness temperature (BT) GeoTIFF.
* **albedo\_path** (str): Path to the surface albedo GeoTIFF.
* **output\_path** (str): Relative path to save the ATI raster, e.g. "question17/thermal\_inertia\_2022-01-16.tif".
**Returns:**
str: Path to the saved Apparent Thermal Inertia GeoTIFF file.
### dual\_polarization\_differential
```python theme={"system"}
def dual_polarization_differential(
self,
pol1_path: str,
pol2_path: str,
parameter: str,
output_path: str,
a: float = 0.3,
b: float = 0.1,
input_unit: str = 'dB'
):
```
Dual-Polarization Differential Method (DPDM) for microwave remote
sensing parameter inversion.
Supports soil moisture and vegetation index estimation with improved
data handling and flexible Args.
**Parameters:**
* **pol1\_path** (str): File path for the first polarization band GeoTIFF (e.g., VV).
* **pol2\_path** (str): File path for the second polarization band GeoTIFF (e.g., VH).
* **parameter** (str): Parameter to invert, options: "soil\_moisture" or "vegetation\_index".
* **output\_path** (str): relative path for the output raster file, e.g. "question17/thermal\_inertia\_2022-01-16.tif"
* **a** (float, optional): Linear coefficient for soil moisture model. Default is 0.3.
* **b** (float, optional): Intercept for soil moisture model. Default is 0.1.
* **input\_unit** (str, optional): Unit of input data, either "dB" or "linear". Default is "dB".
**Returns:**
str: Path to the exported parameter GeoTIFF.
### dual\_frequency\_diff
```python theme={"system"}
def dual_frequency_diff(
self,
band1_path: str,
band2_path: str,
parameter: str,
alpha: float,
beta: float,
output_path: str
):
```
Dual-frequency Differential Method (DDM) for parameter inversion.
Uses local raster data for parameter inversion via empirical linear
models:
* Soil Moisture (SM): param = alpha\*(band1 - band2) + beta
* Vegetation Index (VI): param = alpha\*(band1 - band2) + beta
* Leaf Area Index (LAI): param = alpha\*(band1 - band2) + beta
**Parameters:**
* **band1\_path** (str): File path for frequency 1 polarization band GeoTIFF.
* **band2\_path** (str): File path for frequency 2 polarization band GeoTIFF.
* **parameter** (str): Parameter to invert. Options: 'SM', 'VI', 'LAI'. Default is 'SM'.
* **alpha** (float, optional): Slope coefficient to override default.
* **beta** (float, optional): Intercept coefficient to override default.
* **output\_path** (str): Relative path for the output raster file, e.g. "question17/thermal\_inertia\_2022-01-16.tif"
**Returns:**
str: Path to the saved combined output GeoTIFF (difference and
parameter).
### multi\_freq\_bt
```python theme={"system"}
def multi_freq_bt(
self,
bt_paths: list[str],
diff_pairs: list[list[int]],
parameter: str,
output_path: str
):
```
Multi-frequency Brightness Temperature Method for inversion.
Uses local raster data for parameter inversion.
**Parameters:**
* **bt\_paths** (list\[str]): List of local file paths for brightness temperature GeoTIFF bands (e.g., \["BT\_10GHz.tif", "BT\_19GHz.tif", "BT\_37GHz.tif"]).
* **diff\_pairs** (list\[list\[int]]): List of index pairs from bt\_paths for difference calculation (e.g., \[\[0,1],\[1,2]]).
* **parameter** (str): Parameter to invert. Options: 'SM', 'VWC', 'LAI'.
* **output\_path** (str): Relative path for the output raster file, e.g. "question17/thermal\_inertia\_2022-01-16.tif"
**Returns:**
str: Path to the saved inverted parameter GeoTIFF.
### chang\_single\_param\_inversion
```python theme={"system"}
def chang_single_param_inversion(
self,
bt_paths: list[str],
diff_pairs: list[list[int]],
parameter: str,
output_path: str
):
```
Chang algorithm for single parameter inversion.
Uses multi-frequency dual-polarized microwave brightness temperatures
from local raster files.
**Parameters:**
* **bt\_paths** (list\[str]): List of local GeoTIFF file paths for brightness temperature bands (e.g., \["BT\_10V.tif", "BT\_10H.tif", "BT\_19V.tif", "BT\_19H.tif"]).
* **diff\_pairs** (list\[list\[int]]): List of index pairs for brightness temperature differences.
* **parameter** (str): Parameter to invert (e.g., "SM", "VWC").
* **output\_path** (str): Relative path for the output raster file, e.g. "question17/thermal\_inertia\_2022-01-16.tif"
**Returns:**
str: File path to saved GeoTIFF with inverted parameter band.
### nasa\_team\_sea\_ice\_concentration
```python theme={"system"}
def nasa_team_sea_ice_concentration(
self,
bt_paths: dict,
output_path: str,
nd_ice: float = 50.0,
nd_water: float = 0.0,
s1_ice: float = 20.0,
s1_water: float = 0.0
):
```
Estimate Sea Ice Concentration using NASA Team Algorithm.
Uses local passive microwave brightness temperature GeoTIFF files.
**Parameters:**
* **bt\_paths** (dict): Dictionary of local GeoTIFF file paths for required brightness temperature bands, e.g., `{"19V": "BT_19V.tif", "19H": "BT_19H.tif", "37V": "BT_37V.tif", "37H": "BT_37H.tif"}`
* **nd\_ice** (float): ND value for ice reference. Default 50.0.
* **nd\_water** (float): ND value for water reference. Default 0.0.
* **s1\_ice** (float): S1 value for ice reference. Default 20.0.
* **s1\_water** (float): S1 value for water reference. Default 0.0.
* **output\_path** (str): Relative path for the output raster file, e.g. "question17/thermal\_inertia\_2022-01-16.tif"
**Returns:**
str: Path to saved GeoTIFF with sea ice concentration band.
### dual\_polarization\_ratio
```python theme={"system"}
def dual_polarization_ratio(
self,
bt_paths: dict,
parameter: str,
output_path: str,
coeffs: dict | None = None
):
```
Estimate VWC or SM using Dual-Polarization Ratio Method (PRM).
Uses local passive microwave brightness temperature GeoTIFF files.
The polarization ratio is computed as: (V - H) / (V + H), where V
and H are brightness temperatures of vertical and horizontal
polarizations.
Empirical models:
* VWC = a\_vwc \* PR + b\_vwc
* SM = a\_sm \* PR + b\_sm
**Parameters:**
* **bt\_paths** (dict): Dictionary of local GeoTIFF file paths for vertical and horizontal polarization bands, e.g. `{"V": "BT_V.tif", "H": "BT_H.tif"}`
* **parameter** (str): Parameter to invert, either "VWC" or "SM".
* **output\_path** (str): Relative path for the output raster file, e.g. "question17/thermal\_inertia\_2022-01-16.tif"
* **coeffs** (dict, optional): Empirical coefficients `{"VWC": {"a":float, "b":float}, "SM": {...}}`.
**Returns:**
str: File path of the saved GeoTIFF containing the inverted
parameter and PR band.
### calculate\_water\_turbidity\_ntu
```python theme={"system"}
def calculate_water_turbidity_ntu(
self,
input_red_path: str,
output_path: str,
method: str = 'linear',
a: float = 1.0,
b: float = 0.0,
n: float = 1.0
):
```
Calculate water turbidity in NTU from red band raster file.
NTU = Nephelometric Turbidity Units. Saves result to output path.
**Parameters:**
* **input\_red\_path** (str): Path to the Red band raster file.
* **output\_path** (str): Relative path for the output raster file, e.g. "benchmark/data/question17/turbidity\_2022-01-16.tif"
* **method** (str): Calculation method - "linear" (a*Red+b), "power" (a*Red^n+b), or "log" (a\*log(Red)+b).
* **a** (float): Coefficient parameter, default 1.0.
* **b** (float): Offset parameter, default 0.0.
* **n** (float): Power parameter for power method, default 1.0.
**Returns:**
str: Path to the output NTU raster file.
### threshold\_segmentation
```python theme={"system"}
def threshold_segmentation(
self,
input_image_path: str,
threshold: float | int,
output_path: str
):
```
Perform threshold-based segmentation on a single-band raster image.
Reads a raster image, converts it to a binary mask by applying a fixed
threshold, and writes the resulting binary image to a new file. Pixel
values greater than threshold are set to 255 (white), and values less
than or equal to threshold are set to 0 (black).
**Parameters:**
* **input\_image\_path** (str): Path to the input raster image file (e.g., TIFF, PNG, JPG).
* **threshold** (float or int): Pixel intensity threshold used to generate the binary mask.
* **output\_path** (str): Relative output path (under TEMP\_DIR) where the result will be saved, e.g., "question17/threshold\_segmentation\_2022-01-16.tif".
**Returns:**
str: Message indicating the file path where the result is saved.
### bbox\_expansion
```python theme={"system"}
def bbox_expansion(
self,
bboxes: list[list[float]],
radius: float,
gsd: float
):
```
Expand bounding boxes by a given radius.
**Parameters:**
* **bboxes** (list\[list\[float]]): List of bounding boxes, each represented as \[x1, y1, x2, y2].
* **radius** (float): Expansion radius in the same unit as the GSD.
* **gsd** (float): Ground Sampling Distance in the same unit as radius.
**Returns:**
list\[list\[float]]: List of expanded bounding boxes, each
represented as \[x1, y1, x2, y2].
### count\_above\_threshold
```python theme={"system"}
def count_above_threshold(self, file_path: str, threshold: float):
```
Count pixels in an image whose values exceed the threshold.
**Parameters:**
* **file\_path** (str): Path to the input image (GeoTIFF or raster format).
* **threshold** (float): Threshold value for hotspot detection.
**Returns:**
count (int):
Number of pixels with values greater than the threshold.
### count\_skeleton\_contours
```python theme={"system"}
def count_skeleton_contours(self, image_path: str):
```
Count external contours in a skeletonized binary image.
Reads a binary image, applies erosion and skeletonization, then
counts the number of external contours.
**Parameters:**
* **image\_path** (str): Path to the input binary (black and white) image.
**Returns:**
count (int):
Number of external contours detected after skeletonization.
### bboxes2centroids
```python theme={"system"}
def bboxes2centroids(self, bboxes: list[list[float]]):
```
Convert bounding boxes to centroid coordinates.
Converts from \[x\_min, y\_min, x\_max, y\_max] format to (x, y) centroids.
**Parameters:**
* **bboxes** (list\[list\[float]]): A list of bounding boxes, each defined as \[x\_min, y\_min, x\_max, y\_max].
**Returns:**
centroids (list\[tuple\[float, float]]):
A list of centroid coordinates, each in (x, y) format.
### centroid\_distance\_extremes
```python theme={"system"}
def centroid_distance_extremes(self, centroids: list[tuple[float, float]]):
```
Find closest and farthest centroid pairs.
Computes pairwise distances between centroids and returns both the
closest and farthest pairs with their indices and distances.
**Parameters:**
* **centroids** (list\[tuple\[float, float]] or np.ndarray): A list or NumPy array of centroid coordinates in (x, y) format.
**Returns:**
result (dict):
A dictionary containing:
* 'min': (index1, index2, distance)
Indices of the closest centroid pair and their distance.
* 'max': (index1, index2, distance)
Indices of the farthest centroid pair and their distance.
### calculate\_bbox\_area
```python theme={"system"}
def calculate_bbox_area(self, bboxes: list[list[float]], gsd: float | None = None):
```
Calculate the total area of bounding boxes in \[x, y, w, h] format.
**Parameters:**
* **bboxes** (list\[list\[float]]): A list of bounding boxes, each defined as \[x, y, w, h] where x,y is top-left corner and w,h are width and height.
* **gsd** (float, optional): Ground sample distance (meters per pixel). If provided, result is in m². If None, result is in pixel². Default = None.
**Returns:**
total\_area (float): The total area of all bounding boxes, in m²
if gsd is provided, otherwise in pixel².
### compute\_linear\_trend
```python theme={"system"}
def compute_linear_trend(self, y: list, x: list | None = None):
```
Compute linear trend (slope and intercept) of a time series.
Fits a line of the form y = a \* x + b using least squares method.
**Parameters:**
* **y** (list): The dependent variable (time series data).
* **x** (list): The independent variable (time indices). If not provided, uses np.arange(len(y)) as default.
**Returns:**
tuple: (slope, intercept) where:
* slope (float): The coefficient a representing the trend.
> 0: upward, \< 0: downward, \~0: no trend.
* intercept (float): The y-intercept b of the fitted line.
### mann\_kendall\_test
```python theme={"system"}
def mann_kendall_test(self, x: list):
```
Description:
Conduct the Mann-Kendall trend test on a time series to assess
whether a statistically significant monotonic trend exists.
The test is non-parametric and does not assume normality.
Handles tied ranks with variance correction.
**Parameters:**
* **x** (list\[float]): The input time series data as a list of floats or ints. Any missing values (NaN) should be removed beforehand.
**Returns:**
trend (str):
Type of detected trend:
* "increasing" if a significant upward trend is found
* "decreasing" if a significant downward trend is found
* "no trend" if no significant trend is detected
p\_value (float):
Two-tailed p-value of the test.
z (float):
Standard normal test statistic.
tau (float):
Kendall's Tau statistic (measure of rank correlation,
range -1 to 1).
### sens\_slope
```python theme={"system"}
def sens_slope(self, x: list):
```
Description:
Compute Sen's Slope estimator for a univariate time series.
This robust non-parametric method calculates the median of
all pairwise slopes between observations, providing an estimate
of the overall monotonic trend magnitude.
**Parameters:**
* **x** (list\[float]): The input time series data as a list of floats or ints. Must have at least two data points.
**Returns:**
slope (float):
The Sen's Slope estimate (median of all pairwise slopes).
slopes (list\[float]):
List of all pairwise slopes, which can be used for
further distributional or variability analysis.
### stl\_decompose
```python theme={"system"}
def stl_decompose(
self,
x: list,
period: int,
robust: bool = True
):
```
Apply STL decomposition to a univariate time series.
Decomposes input data into three additive components: trend,
seasonal, and residual using LOESS.
**Parameters:**
* **x** (list\[float]): Input time series values.
* **period** (int): Number of observations in one seasonal cycle.
**Returns:**
dict: Dictionary with keys "trend", "seasonal", "resid", each
containing list\[float] of component values.
### detect\_change\_points
```python theme={"system"}
def detect_change_points(
self,
signal: list[float],
model: str = 'l2',
penalty: float = 10
):
```
Description:
Detect change points in a one-dimensional time series using the
PELT algorithm from the ruptures library. This identifies indices
where the statistical structure of the signal changes.
**Parameters:**
* **signal** (list\[float]): Input time series data.
* **model** (`str, default="l2"`): Segmentation cost model to use. - "l1": robust to outliers (absolute loss) - "l2": mean shift model (squared loss, default) - "rbf": kernel-based model for nonlinear changes - others supported by ruptures
* **penalty** (float, default=10): Penalty value controlling sensitivity. Higher values detect fewer change points (more conservative).
**Returns:**
change\_points (list\[int]):
List of indices marking change points in the series.
The final index of the signal is always included.
### autocorrelation\_function
```python theme={"system"}
def autocorrelation_function(self, x: list, nlags: int = 20):
```
Compute the Autocorrelation Function (ACF) of a time series.
The ACF describes correlation between the series and its lagged values,
commonly used to detect seasonality or serial dependence.
**Parameters:**
* **x** (list\[float]): Input time series data.
* **nlags** (int, default=20): Number of lags to compute.
**Returns:**
acf (list\[float]): Autocorrelation values for lags 0 to nlags.
acf\[0] = 1.0 (self-correlation), acf\[k] = correlation at lag k.
### detect\_seasonality\_acf
```python theme={"system"}
def detect_seasonality_acf(self, values: list, min_acf: float = 0.3):
```
Detect dominant seasonality in a time series using ACF.
A peak in the ACF beyond lag=1 indicates potential periodicity.
**Parameters:**
* **values** (list\[float]): Input time series data.
* **min\_acf** (float, default=0.3): ACF threshold to consider significant.
**Returns:**
result (int | str): Dominant period (lag) if detected, or
"Data is not cyclical" if no significant seasonality found.
### getis\_ord\_gi\_star
```python theme={"system"}
def getis_ord_gi_star(
self,
image_path: str,
weight_matrix: list,
output_path: str
):
```
Compute Getis-Ord Gi\* statistic for local spatial autocorrelation.
Positive Gi\* values indicate hot spots (clusters of high values),
negative values indicate cold spots (clusters of low values).
**Parameters:**
* **image\_path** (str): Path to input single-band raster (GeoTIFF).
* **weight\_matrix** (list\[list\[float]]): 2D spatial weight kernel (e.g., 3x3 or 5x5). Sum of weights must not be zero.
* **output\_path** (str): Relative path to save the Gi\* result GeoTIFF.
**Returns:**
str: Path to saved GeoTIFF with Gi\* statistics (float32 raster).
Preserves georeference and projection from input if available.
### analyze\_hotspot\_direction
```python theme={"system"}
def analyze_hotspot_direction(self, hotspot_map_path: str):
```
Analyze dominant direction of hotspot concentration.
Computes the relative location of hotspot pixels (value=1) with
respect to raster center and determines which cardinal direction
contains the majority of hotspots.
**Parameters:**
* **hotspot\_map\_path** (str): Path to binary hotspot map GeoTIFF. Hotspot pixels should be value=1; others are ignored.
**Returns:**
str: "north", "south", "east", "west" for dominant direction,
or "no hotspots found" if no hotspot pixels exist.
### count\_spikes\_from\_values
```python theme={"system"}
def count_spikes_from_values(
self,
values: list[float],
spike_threshold: float = 0.1,
verbose: bool = True
):
```
Count the number of upward spikes in a sequence of numerical values.
A spike is defined as a positive difference between consecutive valid
values greater than the given threshold.
**Parameters:**
* **values** (list of float): Input sequence of values (can include None or NaN).
* **spike\_threshold** (float): Minimum positive change required to count as a spike.
* **verbose** (bool): If True, logger.infos details for each detected spike.
**Returns:**
int:
Number of detected upward spikes.
### coefficient\_of\_variation
```python theme={"system"}
def coefficient_of_variation(self, x: list, ddof: int = 1):
```
Description:
Compute the Coefficient of Variation (CV) for a dataset.
CV is defined as the ratio of the standard deviation to the mean:
CV = std(x) / mean(x)
**Parameters:**
* **x** (list\[float]): Input dataset values (numeric).
* **ddof** (int, default=1): Delta Degrees of Freedom for standard deviation calculation: - ddof=0 → population standard deviation - ddof=1 → sample standard deviation (default)
**Returns:**
cv (float):
The computed Coefficient of Variation.
Returns NaN if mean(x) == 0 to avoid division by zero.
### skewness
```python theme={"system"}
def skewness(self, x: list, bias: bool = True):
```
Compute skewness of a dataset (distribution asymmetry).
Positive skew = longer right tail, negative = longer left tail,
zero = approximately symmetric.
**Parameters:**
* **x** (list\[float]): Input dataset values (numeric).
* **bias** (bool, default=True): If False, applies bias correction (Fisher-Pearson method) for unbiased estimator.
**Returns:**
skew (float): Skewness value. Returns 0.0 if no variation.
### kurtosis
```python theme={"system"}
def kurtosis(
self,
x: list,
bias: bool = True,
fisher: bool = True
):
```
Compute kurtosis of a dataset (tailedness measure).
Positive kurtosis = heavier tails than normal, negative = lighter.
Zero kurtosis = similar tails to normal (when fisher=True).
**Parameters:**
* **x** (list\[float]): Input dataset values (numeric).
* **bias** (bool, default=True): If False, applies bias correction.
* **fisher** (bool, default=True): If True, returns "excess kurtosis" (normal=0). If False, returns regular kurtosis (normal=3).
**Returns:**
kurt (float): Kurtosis value. Returns 0.0 if no variation.
### calc\_single\_image\_mean
```python theme={"system"}
def calc_single_image_mean(self, file_path: str, uint8: bool = False):
```
Compute mean value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
mean (float): Mean pixel value
### calc\_batch\_image\_mean
```python theme={"system"}
def calc_batch_image_mean(self, file_list: list[str], uint8: bool = False):
```
Compute mean value of an batch of images.
**Returns:**
mean (list(float)): Mean pixel value
### calc\_single\_image\_std
```python theme={"system"}
def calc_single_image_std(self, file_path: str, uint8: bool = False):
```
Compute standard deviation value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
std (float): Standard deviation
### calc\_batch\_image\_std
```python theme={"system"}
def calc_batch_image_std(self, file_list: list[str], uint8: bool = False):
```
Compute standard deviation for a batch of images.
**Parameters:**
* **file\_list** (list\[str]): List of input image file paths.
* **uint8** (bool, optional): Whether to convert to uint8 first. Default = False.
**Returns:**
list\[float]: Standard deviation values, one per input image.
### calc\_single\_image\_median
```python theme={"system"}
def calc_single_image_median(self, file_path: str, uint8: bool = False):
```
Compute median value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
median (float): Median pixel value
### calc\_batch\_image\_median
```python theme={"system"}
def calc_batch_image_median(self, file_list: list[str], uint8: bool = False):
```
Compute median pixel value for a batch of images.
**Parameters:**
* **file\_list** (list\[str]): List of input image file paths.
* **uint8** (bool, optional): Whether to convert to uint8 first. Default = False.
**Returns:**
list\[float]: Median pixel values, one per input image.
### calc\_single\_image\_min
```python theme={"system"}
def calc_single_image_min(self, file_path: str, uint8: bool = False):
```
Compute min value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
min (float): Minimum pixel value
### calc\_batch\_image\_min
```python theme={"system"}
def calc_batch_image_min(self, file_list: list[str], uint8: bool = False):
```
Compute minimum pixel value for a batch of images.
**Parameters:**
* **file\_list** (list\[str]): List of input image file paths.
* **uint8** (bool, optional): Whether to convert to uint8 first. Default = False.
**Returns:**
list\[float]: Minimum pixel values, one per input image.
### calc\_single\_image\_max
```python theme={"system"}
def calc_single_image_max(self, file_path: str, uint8: bool = False):
```
Compute max value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
max (float): Maximum pixel value
### calc\_batch\_image\_max
```python theme={"system"}
def calc_batch_image_max(self, file_list: list[str], uint8: bool = False):
```
Compute maximum pixel value for a batch of images.
**Parameters:**
* **file\_list** (list\[str]): List of input image file paths.
* **uint8** (bool, optional): Whether to convert to uint8 first. Default = False.
**Returns:**
list\[float]: Maximum pixel values, one per input image.
### calc\_single\_image\_skewness
```python theme={"system"}
def calc_single_image_skewness(self, file_path: str, uint8: bool = False):
```
Compute skewness value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
skewness: Skewness of pixel value distribution
### calc\_batch\_image\_skewness
```python theme={"system"}
def calc_batch_image_skewness(self, file_list: list[str], uint8: bool = False):
```
Compute skewness of pixel distributions for a batch of images.
Positive skew = longer right tail, negative = longer left tail,
zero = symmetric distribution.
**Parameters:**
* **file\_list** (list\[str]): List of input image file paths.
* **uint8** (bool, optional): Whether to convert to uint8 first. Default = False.
**Returns:**
list\[float]: Skewness values, one per input image.
### calc\_single\_image\_kurtosis
```python theme={"system"}
def calc_single_image_kurtosis(self, file_path: str, uint8: bool = False):
```
Compute kurtosis value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
**Returns:**
kurtosis: Kurtosis of pixel value distribution (excess kurtosis)
### calc\_batch\_image\_kurtosis
```python theme={"system"}
def calc_batch_image_kurtosis(self, file_list: list[str], uint8: bool = False):
```
Compute kurtosis of pixel distributions for a batch of images.
Kurtosis measures "tailedness" relative to normal distribution.
Normal = 3, higher = heavier tails, lower = lighter tails.
**Parameters:**
* **file\_list** (list\[str]): List of input image file paths.
* **uint8** (bool, optional): Whether to convert to uint8 first. Default = False.
**Returns:**
list\[float]: Kurtosis values, one per input image.
### calc\_single\_image\_sum
```python theme={"system"}
def calc_single_image_sum(self, file_path: str, uint8: bool = False):
```
Compute sum value of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
* **uint8** (bool): Whether to use uint8 format.
**Returns:**
sum (float): Sum pixel value
### calc\_batch\_image\_sum
```python theme={"system"}
def calc_batch_image_sum(self, file_list: list[str], uint8: bool = False):
```
Description:
Compute the sum of pixel values for a batch of images.
**Returns:**
* sum (list\[float]): List of pixel sum values, one for each image.
### calc\_single\_image\_hotspot\_percentage
```python theme={"system"}
def calc_single_image_hotspot_percentage(
self,
file_path: str,
threshold: float,
uint8: bool = False
):
```
Compute hotspot percentage of an image.
**Parameters:**
* **file\_path** (str): Path to input image.
* **threshold** (float): Threshold value for hotspot detection.
* **uint8** (bool): Whether to use uint8 format.
**Returns:**
percentage (float): Hotspot area percentage (0.0 to 1.0).
### calc\_batch\_image\_hotspot\_percentage
```python theme={"system"}
def calc_batch_image_hotspot_percentage(
self,
file_list: list[str],
threshold: float,
uint8: bool = False
):
```
Description:
Compute the hotspot percentage (fraction of pixels above a threshold)
for a batch of images.
**Returns:**
* percentage (list\[float]): List of hotspot area percentages (0.0-1.0),
one for each input image.
### calc\_single\_image\_hotspot\_tif
```python theme={"system"}
def calc_single_image_hotspot_tif(
self,
file_path: str,
threshold: float,
output_path: str,
uint8: bool = False
):
```
Create a binary map highlighting areas below the threshold and save
as GeoTIFF.
**Parameters:**
* **file\_path** (str): Path to input image.
* **threshold** (float): Threshold value for detection.
* **uint8** (bool): Whether to use uint8 format.
* **output\_path** (str, optional): relative path for the output raster file, e.g. "question17/hotspot\_2022-01-16.tif"
**Returns:**
str: Path to the saved GeoTIFF image containing the binary map.
### calc\_batch\_image\_hotspot\_tif
```python theme={"system"}
def calc_batch_image_hotspot_tif(
self,
file_list: list[str],
threshold: float,
output_path_list: list[str],
uint8: bool = False
):
```
Description:
Create binary hotspot maps for a batch of images, where pixels below
a specified threshold are set to 1 (hotspot) and others set to 0.
The output is saved as GeoTIFF files, preserving georeference metadata
from the input images.
**Returns:**
* list\[str]: Paths to the saved GeoTIFF images containing the binary
hotspot maps.
### difference
```python theme={"system"}
def difference(self, a: float, b: float):
```
Description:
Compute the absolute difference between two numbers.
**Returns:**
* diff (float): The absolute difference |a - b|.
### division
```python theme={"system"}
def division(self, a: float, b: float):
```
Description:
Perform division between two numbers.
**Returns:**
* result (float): The result of b ÷ a. Returns +inf if a = 0.
### percentage\_change
```python theme={"system"}
def percentage_change(self, a: float, b: float):
```
Description:
Calculate the percentage change between two numbers, useful for
comparing relative growth or decline.
**Returns:**
* percent (float): The percentage change, computed as
((b - a) / a) \* 100. Positive values indicate increase,
negative values indicate decrease. Returns +inf if a = 0.
### kelvin\_to\_celsius
```python theme={"system"}
def kelvin_to_celsius(self, kelvin: float):
```
Description:
Convert temperature from Kelvin to Celsius.
**Returns:**
* celsius (float): Temperature in Celsius, computed as
(Kelvin - 273.15).
### celsius\_to\_kelvin
```python theme={"system"}
def celsius_to_kelvin(self, celsius: float):
```
Description:
Convert temperature from Celsius to Kelvin.
**Parameters:**
* **celsius** (float): Temperature in Celsius.
**Returns:**
kelvin (float):
Temperature in Kelvin, computed as:
Kelvin = Celsius + 273.15
### max\_value\_and\_index
```python theme={"system"}
def max_value_and_index(self, x: list):
```
Description:
Find the maximum value in a list and return both the maximum value
and its index.
**Returns:**
* result (tuple\[float, int]): A tuple containing:
- max\_value (float): The maximum value in the list.
- max\_index (int): The index of the maximum value.
### min\_value\_and\_index
```python theme={"system"}
def min_value_and_index(self, x: list):
```
Description:
Find the minimum value in a list and return both the minimum value
and its index.
**Returns:**
* result (tuple\[float, int]): A tuple containing:
- min\_value (float): The minimum value in the list.
- min\_index (int): The index of the minimum value.
### multiply
```python theme={"system"}
def multiply(self, a: float | int, b: float | int):
```
Description:
Multiply two numbers and return their product.
**Parameters:**
* **a** (float or int): First number.
* **b** (float or int): Second number.
**Returns:**
result (float or int):
The product of a and b.
### ceil\_number
```python theme={"system"}
def ceil_number(self, n: float):
```
Description:
Return the ceiling (rounded up integer) of a given number.
**Parameters:**
* **n** (float): A numeric value.
**Returns:**
result (int):
The smallest integer greater than or equal to n.
### get\_list\_object\_via\_indexes
```python theme={"system"}
def get_list_object_via_indexes(self, input_list: list, indexes: list[int]):
```
Description:
Retrieve elements from a list using a list or tuple of indices.
**Parameters:**
* **input\_list** (list): The source list from which elements will be extracted.
* **indexes** (list\[int]): A sequence of indices specifying the positions of elements to retrieve.
**Returns:**
result (list):
A list of elements corresponding to the provided indices.
### mean
```python theme={"system"}
def mean(self, x: list):
```
Description:
Compute the arithmetic mean (average) of a dataset.
**Parameters:**
* **x** (list\[float]): Input data array.
**Returns:**
mean\_value (float):
The arithmetic mean of the input values.
### calculate\_threshold\_ratio
```python theme={"system"}
def calculate_threshold_ratio(
self,
image_paths: str | list[str],
threshold: float = 0.75,
band_index: int = 0
):
```
Description:
Calculate the average percentage of pixels above a given threshold
for one or more images and a specified band.
**Parameters:**
* **image\_paths** (str or list\[str]): Path or list of image file paths.
* **threshold** (float, optional): Threshold value. Default = 0.75.
* **band\_index** (int, optional): Band index to use (0-based). Default = 0 (first band).
**Returns:**
percentage (float):
Average percentage of pixels above the threshold across all
images.
### calc\_single\_image\_fire\_pixels
```python theme={"system"}
def calc_single_image_fire_pixels(self, file_path: str, fire_threshold: float = 0):
```
Compute the number of fire pixels (MaxFRP > threshold) in an image.
**Parameters:**
* **file\_path** (str): Path to input image.
* **fire\_threshold** (float): Minimum FRP value to be considered as fire (default: 0).
**Returns:**
fire\_pixels (int): Number of fire pixels
### calc\_batch\_fire\_pixels
```python theme={"system"}
def calc_batch_fire_pixels(self, file_list: list[str], fire_threshold: float = 0):
```
Description:
Compute the number of fire pixels (FRP > threshold) for a batch of
images.
**Parameters:**
* **file\_list** (list\[str]): Paths to input images.
* **fire\_threshold** (float, optional): Minimum FRP value to be considered as fire. Default = 0.
**Returns:**
fire\_pixels (list\[int]):
A list of fire pixel counts, one per input image.
### create\_fire\_increase\_map
```python theme={"system"}
def create_fire_increase_map(
self,
change_image_path: str,
output_path: str,
threshold: float = 20.0
):
```
Description:
Create a binary map highlighting areas where fire increase exceeds
a specified threshold.
**Parameters:**
* **change\_image\_path** (str): Path to the fire change image.
* **output\_path** (str): Relative path for the output raster file (e.g., "question17/hotspot\_2022-01-16.tif").
* **threshold** (float, optional): Threshold value in MW. Default = 20.0.
**Returns:**
result (str):
Path to the saved GeoTIFF fire increase map.
### identify\_fire\_prone\_areas
```python theme={"system"}
def identify_fire_prone_areas(
self,
file_path: str,
output_path: str,
threshold_percentile: float = 75,
uint8: bool = False
):
```
Description:
Identify fire-prone areas from a hotspot map based on a given
percentile threshold.
**Parameters:**
* **file\_path** (str): Path to the input hotspot map file.
* **output\_path** (str): Relative path for the output raster file (e.g., "question17/hotspot\_2022-01-16.tif").
* **threshold\_percentile** (float, optional): Percentile threshold for identifying fire-prone areas. Default = 75.
* **uint8** (bool, optional): Whether to use uint8 format when reading the input. Default = False.
**Returns:**
result (tuple\[str, float]):
A tuple containing:
* Path to the saved GeoTIFF file with fire-prone areas.
* Threshold value used for classification.
### get\_percentile\_value\_from\_image
```python theme={"system"}
def get_percentile_value_from_image(self, image_path: str, percentile: int | float):
```
Description:
Calculate the N-th percentile value of pixel values in a raster
image, and return it as a native Python type matching the image's
data type.
**Parameters:**
* **image\_path** (str): Path to the input raster (.tif) file.
* **percentile** (int or float): Percentile to calculate (range 1-100).
**Returns:**
value (int or float):
The pixel value corresponding to the specified percentile,
cast to the appropriate native Python type (int for integer
rasters, float for floating-point rasters).
### image\_division\_mean
```python theme={"system"}
def image_division_mean(
self,
image_path1: str,
image_path2: str | None = None,
band1: int | None = 1,
band2: int | None = 2
):
```
Description:
Calculate the mean of pixel-wise division between two images
or between two bands of the same image.
**Parameters:**
* **image\_path1** (str): Path to the first image (or the only image if comparing two bands).
* **image\_path2** (str, optional): Path to the second image. If None, band1 and band2 of image\_path1 will be used.
* **band1** (int, optional): Band index for numerator when using a multi-band image. Default = 1.
* **band2** (int, optional): Band index for denominator when using a multi-band image. Default = 2.
**Returns:**
result (float):
The mean of the valid pixel-wise division results.
### calculate\_intersection\_percentage
```python theme={"system"}
def calculate_intersection_percentage(
self,
path1: str,
threshold1: float,
path2: str,
threshold2: float
):
```
Description:
Calculate the percentage of pixels that simultaneously satisfy
threshold conditions in two raster images.
**Parameters:**
* **path1** (str): Path to the first raster image (e.g., NDVI).
* **threshold1** (float): Threshold value for the first image (e.g., NDVI > 0.3).
* **path2** (str): Path to the second raster image (e.g., TVDI).
* **threshold2** (float): Threshold value for the second image (e.g., TVDI > 0.7).
**Returns:**
percentage (float):
Percentage of pixels that satisfy both conditions
over the total valid pixels.
### calc\_batch\_image\_mean\_mean
```python theme={"system"}
def calc_batch_image_mean_mean(self, file_list: list[str], uint8: bool = False):
```
Description:
Compute the average of mean pixel values across a batch of images.
**Parameters:**
* **file\_list** (list\[str]): List of image file paths.
* **uint8** (bool, optional): Whether to convert images to uint8 format (0-255). Default = False.
**Returns:**
mean\_of\_means (float):
The average of the mean pixel values across all images.
### calc\_batch\_image\_mean\_max
```python theme={"system"}
def calc_batch_image_mean_max(self, file_list: list[str], uint8: bool = False):
```
Description:
Compute the mean pixel values of a batch of images and return the
maximum mean.
**Parameters:**
* **file\_list** (list\[str]): Paths to input images.
* **uint8** (bool, optional): Whether to treat image as uint8 (0-255 normalization). Default = False.
**Returns:**
max\_mean (float):
The maximum mean pixel value among all images.
### calc\_batch\_image\_mean\_max\_min
```python theme={"system"}
def calc_batch_image_mean_max_min(self, file_list: list[str], uint8: bool = False):
```
Description:
Compute the batch-wise statistics across multiple images,
including:
* Mean of mean values
* Maximum of maximum values
* Minimum of minimum values
**Parameters:**
* **file\_list** (list\[str]): List of image file paths.
* **uint8** (bool, optional): Whether to convert the data to uint8 range (0-255). Default = False.
**Returns:**
result (tuple\[float, float, float]):
A tuple containing:
(mean of means, max of maxs, min of mins)
### calc\_batch\_image\_mean\_threshold
```python theme={"system"}
def calc_batch_image_mean_threshold(
self,
file_list: list[str],
threshold: float,
above: bool = True,
uint8: bool = False,
band_index: int = 0,
return_type: str = 'ratio'
):
```
Description:
Calculate the percentage or count of images whose mean pixel values
(in a specified band) are above or below a given threshold.
**Parameters:**
* **file\_list** (list\[str]): List of image file paths.
* **threshold** (float): Threshold value for comparison.
* **above** (bool, optional): If True, count images with mean > threshold; if False, mean \< threshold. Default = True.
* **uint8** (bool, optional): If True, rescale image data to 0-255 range. Default = False.
* **band\_index** (int, optional): Index of the band to read (0-based). Default = 0.
* **return\_type** (str, optional): - "ratio": return percentage (float, 0-100). - "count": return number of images (int). Default = "ratio".
**Returns:**
float | int:
Percentage (0-100) or count of images satisfying the condition.
### calculate\_multi\_band\_threshold\_ratio
```python theme={"system"}
def calculate_multi_band_threshold_ratio(self, image_path: str, band_conditions: list):
```
Description:
Calculate the percentage of pixels that simultaneously satisfy
multiple band threshold conditions.
**Parameters:**
* **image\_path** (str): Path to the multi-band image file.
* **band\_conditions** (list\[tuple\[int, float, str]]): A list of conditions in the form (band\_index, threshold\_value, compare\_type): - band\_index (int): Zero-based band index. - threshold\_value (float): Threshold to apply. - compare\_type (str): "above" or "below".
**Returns:**
float:
Percentage of pixels satisfying all conditions (intersection).
### count\_pixels\_satisfying\_conditions
```python theme={"system"}
def count_pixels_satisfying_conditions(self, image_path: str, band_conditions: list):
```
Description:
Count the number of pixels that simultaneously satisfy multiple
band threshold conditions.
**Parameters:**
* **image\_path** (str): Path to the multi-band image file.
* **band\_conditions** (list\[tuple\[int, float, str]]): A list of conditions in the form (band\_index, threshold\_value, compare\_type): - band\_index (int): Zero-based band index. - threshold\_value (float): Threshold to apply. - compare\_type (str): "above" or "below".
**Returns:**
int:
Number of pixels satisfying all threshold conditions
(intersection).
### count\_images\_exceeding\_threshold\_ratio
```python theme={"system"}
def count_images_exceeding_threshold_ratio(
self,
image_paths: str | list[str],
value_threshold: float = 0.7,
ratio_threshold: float = 20.0,
mode: str = 'above',
verbose: bool = True
):
```
Count how many images have a percentage of pixels above or below a
threshold that exceeds a specified ratio.
**Parameters:**
* **image\_paths** (str or list): Path(s) to image file(s).
* **value\_threshold** (float): Pixel value threshold (e.g., NDVI > 0.7).
* **ratio\_threshold** (float): Percentage threshold for comparison (e.g., 20.0 means 20%).
* **mode** (str): - 'above': pixels > value\_threshold - 'below': pixels \< value\_threshold Default is 'above'.
* **verbose** (bool): If True, logger.infos detailed ratio results per image.
**Returns:**
int: Number of images whose pixel ratio exceeds the
ratio\_threshold.
### average\_ratio\_exceeding\_threshold
```python theme={"system"}
def average_ratio_exceeding_threshold(
self,
image_paths: str | list[str],
value_threshold: float = 0.7,
ratio_threshold: float = 20.0,
mode: str = 'above',
verbose: bool = True
):
```
Calculate the average percentage of pixels exceeding a value threshold,
considering only images where the ratio is greater than a specified
ratio threshold.
**Parameters:**
* **image\_paths** (str or list): Path(s) to image file(s).
* **value\_threshold** (float): Pixel value threshold (e.g., NDVI > 0.7).
* **ratio\_threshold** (float): Minimum percentage threshold for inclusion (e.g., 20.0 means 20%).
* **mode** (str): - 'above': pixels > value\_threshold - 'below': pixels \< value\_threshold Default is 'above'.
* **verbose** (bool): If True, logger.infos detailed ratio results per image.
**Returns:**
float:
Average percentage of qualifying images.
Returns 0.0 if no image meets the criteria.
### count\_images\_exceeding\_mean\_multiplier
```python theme={"system"}
def count_images_exceeding_mean_multiplier(
self,
image_paths: str | list[str],
mean_multiplier: float = 1.1,
mode: str = 'above',
verbose: bool = True
):
```
Count how many images have a mean pixel value above or below
a multiple of the overall mean pixel value across all images.
**Parameters:**
* **image\_paths** (str or list): Path(s) to image file(s).
* **mean\_multiplier** (float): Multiplier applied to the overall mean (e.g., 1.1 means 110%).
* **mode** (str): - 'above': count images with mean > mean\_multiplier \* overall\_mean - 'below': count images with mean \< mean\_multiplier \* overall\_mean Default is 'above'.
* **verbose** (bool): If True, logger.infos detailed mean and threshold comparisons per image.
**Returns:**
int:
Number of images satisfying the condition.
### calculate\_band\_mean\_by\_condition
```python theme={"system"}
def calculate_band_mean_by_condition(
self,
image_path: str,
condition_band_index: int,
condition_threshold: float,
condition_mode: str = 'above',
target_band_index: int = 0
):
```
Calculate the mean value of a target band over pixels where a
condition band satisfies a threshold.
**Parameters:**
* **image\_path** (str): Path to the multi-band raster image.
* **condition\_band\_index** (int): Zero-based index of the band used for thresholding.
* **condition\_threshold** (float): Threshold value to apply on the condition band.
* **condition\_mode** (`str, default='above'`): - 'above': select pixels where condition\_band >= threshold - 'below': select pixels where condition\_band \< threshold
* **target\_band\_index** (int, default=0): Zero-based index of the band for which the mean is calculated.
**Returns:**
float:
Mean value of the target band over selected pixels.
### calc\_threshold\_value\_mean
```python theme={"system"}
def calc_threshold_value_mean(
self,
path1: str | list[str],
path2: str | list[str],
threshold: float = 300.0
):
```
Calculate the mean value of corresponding raster pixels in path2
where the raster values in path1 exceed the given threshold.
**Parameters:**
* **path1** (Path or List\[Path]): Path(s) to the first set of raster files (e.g., LST).
* **path2** (Path or List\[Path]): Path(s) to the second set of raster files (e.g., TVDI).
* **threshold** (float): Threshold for values in path1 (e.g., LST in Kelvin).
**Returns:**
float: Mean value of path2 pixels that meet the threshold
condition in path1. Returns np.nan if no valid data is found.
### calculate\_tif\_average
```python theme={"system"}
def calculate_tif_average(
self,
file_list: list[str],
output_path: str,
uint8: bool = False
):
```
Calculate average of multiple tif files and save result to same
directory.
**Parameters:**
* **file\_list** (list\[str]): List of tif file paths.
* **output\_path** (str): relative path for the output raster file, e.g. "benchmark/data/question17/avg\_result.tif"
* **uint8** (bool): Convert to uint8 format, default False.
**Returns:**
output\_path (str): Full path of output file.
### calculate\_tif\_difference
```python theme={"system"}
def calculate_tif_difference(
self,
image_a_path: str,
image_b_path: str,
output_path: str,
uint8: bool = False
):
```
Calculate difference between two tif files (image\_b - image\_a) and
save result.
**Parameters:**
* **image\_a\_path** (str): Path to first image (will be subtracted from).
* **image\_b\_path** (str): Path to second image (will subtract from).
* **output\_path** (str): relative path for the output raster file, e.g. "question17/difference\_result.tif"
* **uint8** (bool): Convert to uint8 format, default False.
**Returns:**
output\_path (str): Full path of output file.
### subtract
```python theme={"system"}
def subtract(
self,
img1_path: str,
img2_path: str,
output_path: str
):
```
Subtract two images and save result.
**Parameters:**
* **img1\_path** (str): Path to first image.
* **img2\_path** (str): Path to second image.
* **output\_path** (str): relative path for the output raster file, e.g. "question17/difference\_result.tif"
**Returns:**
str: Path to output file.
### calculate\_area
```python theme={"system"}
def calculate_area(self, input_image_path: str, gsd: float | None):
```
Description:
This function calculates the area of non-zero pixels in the input
image and returns the result.
**Parameters:**
* **input\_image\_path** (str): Path to the input image file (TIFF, PNG, JPG, etc.).
* **gsd** (float): Ground sample distance in meters per pixel, if None, the function will return the number of non-zero pixels.
**Returns:**
area (int): The area of non-zero pixels in the input image.
### grayscale\_to\_colormap
```python theme={"system"}
def grayscale_to_colormap(
self,
image_path: str,
save_name: str,
cmap_name: str = 'viridis',
preserve_geo: bool = False
):
```
Apply a colormap to a grayscale image and save as a color image.
**Parameters:**
* **image\_path** (str): Path to input grayscale image (e.g. .tif).
* **save\_name** (str): Filename for save color image (.png, .jpg, or .tif).
* **cmap\_name** (str): Name of a matplotlib colormap, e.g. 'viridis', 'RdBu', etc.
* **preserve\_geo** (bool): If True, preserves georeferencing.
### get\_filelist
```python theme={"system"}
def get_filelist(self, dir_path: str):
```
Returns a list of files in the specified directory.
**Parameters:**
* **dir\_path** (str): Path to the directory.
**Returns:**
list: List of file names in the directory.
### radiometric\_correction\_sr
```python theme={"system"}
def radiometric_correction_sr(self, input_band_path: str, output_path: str):
```
Apply Landsat 8 surface reflectance (SR\_B\*) radiometric correction.
**Parameters:**
* **input\_band\_path** (str): Path to the input reflectance band file.
* **output\_path** (str): relative path for the output raster file, e.g. "question17/radiometric\_correction\_2022-01-16.tif"
**Returns:**
str: Path to the saved corrected reflectance file.
### apply\_cloud\_mask
```python theme={"system"}
def apply_cloud_mask(
self,
sr_band_path: str,
qa_pixel_path: str,
output_path: str
):
```
Apply cloud/shadow mask to a single Landsat 8 surface reflectance band
using QA\_PIXEL band.
**Parameters:**
* **sr\_band\_path** (str): Path to surface reflectance band (e.g., SR\_B3 or SR\_B5).
* **qa\_pixel\_path** (str): Path to QA\_PIXEL band.
* **output\_path** (str): relative path for the output raster file, e.g. "question17/cloud\_mask\_2022-01-16.tif"
**Returns:**
str: Path to the saved masked raster file.
### read\_image
```python theme={"system"}
def read_image(self, file_path: str):
```
### read\_image\_uint8
```python theme={"system"}
def read_image_uint8(self, file_path: str):
```
### get\_geotransform
```python theme={"system"}
def get_geotransform(self, file_path):
```
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.edgeone_pages_mcp_toolkit
## EdgeOnePagesMCPToolkit
```python theme={"system"}
class EdgeOnePagesMCPToolkit(MCPToolkit):
```
EdgeOnePagesMCPToolkit provides an interface for interacting with
EdgeOne pages using the EdgeOne Pages MCP server.
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the EdgeOnePagesMCPToolkit.
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.excel_toolkit
## ExcelToolkit
```python theme={"system"}
class ExcelToolkit(BaseToolkit):
```
A class representing a toolkit for extract detailed cell information
from an Excel file.
This class provides methods extracting detailed content from Excel files
(including .xls, .xlsx,.csv), and converting the data into
Markdown formatted table.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
working_directory: Optional[str] = None
):
```
Initializes a new instance of the ExcelToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
* **working\_directory** (str, optional): The default directory for output files. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.
### \_validate\_file\_path
```python theme={"system"}
def _validate_file_path(self, file_path: str):
```
Validate file path for security.
**Parameters:**
* **file\_path** (str): The file path to validate.
**Returns:**
bool: True if path is safe, False otherwise.
### \_convert\_to\_markdown
```python theme={"system"}
def _convert_to_markdown(self, df: 'DataFrame'):
```
Convert DataFrame to Markdown format table.
**Parameters:**
* **df** (DataFrame): DataFrame containing the Excel data.
**Returns:**
str: Markdown formatted table.
### extract\_excel\_content
```python theme={"system"}
def extract_excel_content(self, document_path: str):
```
Extract and analyze the full content of an Excel file (.xlsx/.xls/.
csv).
Use this tool to read and understand the structure and content of
Excel files. This is typically the first step when working with
existing Excel files.
**Parameters:**
* **document\_path** (str): The file path to the Excel file.
**Returns:**
str: A comprehensive report containing:
* Sheet names and their content in markdown table format
* Detailed cell information including values, colors, and
positions
* Formatted data that's easy to understand and analyze
### \_save\_workbook
```python theme={"system"}
def _save_workbook(self, file_path: str):
```
Save the current workbook to file.
**Parameters:**
* **file\_path** (str): The path to save the workbook.
**Returns:**
str: Success or error message.
### save\_workbook
```python theme={"system"}
def save_workbook(self, filename: str):
```
Save the current in-memory workbook to a file.
**Parameters:**
* **filename** (str): The filename to save the workbook. Must end with .xlsx extension. The file will be saved in self. working\_directory.
**Returns:**
str: Success message or error details.
### create\_workbook
```python theme={"system"}
def create_workbook(
self,
filename: Optional[str] = None,
sheet_name: Optional[str] = None,
data: Optional[List[List[Union[str, int, float, None]]]] = None
):
```
Create a new Excel workbook from scratch.
Use this when you need to create a new Excel file. This sets up the
toolkit to work with the new file and optionally adds initial data.
**Parameters:**
* **filename** (Optional\[str]): The filename for the workbook. Must end with .xlsx extension. The file will be saved in self.working\_directory. (default: :obj:`None`)
* **sheet\_name** (Optional\[str]): Name for the first sheet. If None, creates "Sheet1". (default: :obj:`None`)
* **data** (Optional\[List\[List\[Union\[str, int, float, None]]]]): Initial data as rows. Each inner list is one row. (default: :obj:`None`)
**Returns:**
str: Success confirmation message or error details
### delete\_workbook
```python theme={"system"}
def delete_workbook(self, filename: str):
```
Delete a spreadsheet file from the working directory.
**Parameters:**
* **filename** (str): The filename to delete. Must end with .xlsx extension. The file will be deleted from self. working\_directory.
**Returns:**
str: Success message or error details.
### create\_sheet
```python theme={"system"}
def create_sheet(
self,
sheet_name: str,
data: Optional[List[List[Union[str, int, float, None]]]] = None
):
```
Create a new sheet with the given sheet name and data.
**Parameters:**
* **sheet\_name** (str): The name of the sheet to create.
* **data** (Optional\[List\[List\[Union\[str, int, float, None]]]]): The data to write to the sheet.
**Returns:**
str: Success message.
### delete\_sheet
```python theme={"system"}
def delete_sheet(self, sheet_name: str):
```
Delete a sheet from the workbook.
**Parameters:**
* **sheet\_name** (str): The name of the sheet to delete.
**Returns:**
str: Success message.
### clear\_sheet
```python theme={"system"}
def clear_sheet(self, sheet_name: str):
```
Clear all data from a sheet.
**Parameters:**
* **sheet\_name** (str): The name of the sheet to clear.
**Returns:**
str: Success message.
### delete\_rows
```python theme={"system"}
def delete_rows(
self,
sheet_name: str,
start_row: int,
end_row: Optional[int] = None
):
```
Delete rows from a sheet.
Use this to remove unwanted rows. You can delete single rows or ranges.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to modify.
* **start\_row** (int): Starting row number to delete (1-based, where 1 is first row).
* **end\_row** (Optional\[int]): Ending row number to delete (1-based). If None, deletes only start\_row. (default: :obj:`None`)
**Returns:**
str: Success confirmation message or error details
### delete\_columns
```python theme={"system"}
def delete_columns(
self,
sheet_name: str,
start_col: int,
end_col: Optional[int] = None
):
```
Delete columns from a sheet.
Use this to remove unwanted columns. You can delete single columns or
ranges.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to modify.
* **start\_col** (int): Starting column number to delete (1-based, where 1 is column A).
* **end\_col** (Optional\[int]): Ending column number to delete (1-based). If None, deletes only start\_col. (default: :obj:`None`)
**Returns:**
str: Success confirmation message or error details
### get\_cell\_value
```python theme={"system"}
def get_cell_value(self, sheet_name: str, cell_reference: str):
```
Get the value from a specific cell.
Use this to read a single cell's value. Useful for checking specific
data points or getting values for calculations.
**Parameters:**
* **sheet\_name** (str): Name of the sheet containing the cell.
* **cell\_reference** (str): Excel-style cell reference (column letter + row number).
**Returns:**
Union\[str, int, float, None]: The cell's value or error message
Returns None for empty cells.
### set\_cell\_value
```python theme={"system"}
def set_cell_value(
self,
sheet_name: str,
cell_reference: str,
value: Union[str, int, float, None]
):
```
Set the value of a specific cell.
Use this to update individual cells with new values. Useful for
corrections, calculations, or updating specific data points.
**Parameters:**
* **sheet\_name** (str): Name of the sheet containing the cell.
* **cell\_reference** (str): Excel-style cell reference (column letter + row number).
* **value** (Union\[str, int, float, None]): New value for the cell. (default: :obj:`None`)
**Returns:**
str: Success confirmation message or error details.
### get\_column\_data
```python theme={"system"}
def get_column_data(self, sheet_name: str, column: Union[int, str]):
```
Get all data from a specific column.
Use this to extract all values from a column for analysis or
processing.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to read from.
* **column** (Union\[int, str]): Column identifier - either number (1-based) or letter.
**Returns:**
Union\[List\[Union\[str, int, float, None]], str]:
List of all non-empty values in the column or error message
### find\_cells
```python theme={"system"}
def find_cells(
self,
sheet_name: str,
search_value: Union[str, int, float],
search_column: Optional[Union[int, str]] = None
):
```
Find cells containing a specific value.
Use this to locate where specific data appears in the sheet.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to search in.
* **search\_value** (Union\[str, int, float]): Value to search for.
* **search\_column** (Optional\[Union\[int, str]]): Limit search to specific column. If None, searches entire sheet. (default: :obj:`None`)
**Returns:**
Union\[List\[str], str]: List of cell references (like "A5", "B12")
where the value was found, or error message.
### get\_range\_values
```python theme={"system"}
def get_range_values(self, sheet_name: str, cell_range: str):
```
Get values from a specific range of cells.
Use this to read a rectangular block of cells at once.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to read from.
* **cell\_range** (str): Range in Excel format (start:end).
**Returns:**
Union\[List\[List\[Union\[str, int, float, None]]], str]:
2D list where each inner list is a row of cell values, or
error message.
### set\_range\_values
```python theme={"system"}
def set_range_values(
self,
sheet_name: str,
cell_range: str,
values: List[List[Union[str, int, float, None]]]
):
```
Set values for a specific range of cells.
Use this to update multiple cells at once with a 2D array of data.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to modify.
* **cell\_range** (str): Range in Excel format to update.
* **values** (List\[List\[Union\[str, int, float, None]]]): 2D array of values. Each inner list represents a row.
**Returns:**
str: Success confirmation message or error details.
### export\_sheet\_to\_csv
```python theme={"system"}
def export_sheet_to_csv(self, sheet_name: str, csv_filename: str):
```
Export a specific sheet to CSV format.
Use this to convert Excel sheets to CSV files for compatibility or
data exchange.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to export.
* **csv\_filename** (str): Filename for the CSV file. Must end with .csv extension. The file will be saved in self.working\_directory.
**Returns:**
str: Success confirmation message or error details.
### get\_rows
```python theme={"system"}
def get_rows(
self,
sheet_name: str,
start_row: Optional[int] = None,
end_row: Optional[int] = None
):
```
Retrieve rows of data from a sheet.
Use this to read data from a sheet. You can get all rows or specify a
range. Returns actual data as lists, making it easy to process
programmatically.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to read from.
* **start\_row** (Optional\[int]): First row to read (1-based). If None, starts from row 1. (default: :obj:`None`)
* **end\_row** (Optional\[int]): Last row to read (1-based). If None, reads to the end. (default: :obj:`None`)
**Returns:**
Union\[List\[List\[Union\[str, int, float, None]]], str]:
List of rows (each row is a list of cell values) or error
message.
### append\_row
```python theme={"system"}
def append_row(
self,
sheet_name: str,
row_data: List[Union[str, int, float, None]]
):
```
Add a single row to the end of a sheet.
Use this to add one row of data to the end of existing content.
For multiple rows, use multiple calls to this function.
**Parameters:**
* **sheet\_name** (str): Name of the target sheet.
* **row\_data** (List\[Union\[str, int, float, None]]): Single row of data to add.
**Returns:**
str: Success confirmation message or error details.
### update\_row
```python theme={"system"}
def update_row(
self,
sheet_name: str,
row_number: int,
row_data: List[Union[str, int, float, None]]
):
```
Update a specific row in the sheet.
Use this to replace all data in a specific row with new values.
**Parameters:**
* **sheet\_name** (str): Name of the sheet to modify.
* **row\_number** (int): The row number to update (1-based, where 1 is first row).
* **row\_data** (List\[Union\[str, int, float, None]]): New data for the entire row.
**Returns:**
str: Success confirmation message or error details.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.file_toolkit
## FileToolkit
```python theme={"system"}
class FileToolkit(BaseToolkit):
```
A comprehensive toolkit for file operations including reading,
writing, and editing files.
This class provides cross-platform (macOS, Linux, Windows) support for:
* Reading various file formats (text, JSON, YAML, PDF, DOCX)
* Writing to multiple formats (Markdown, DOCX, PDF, plaintext, JSON,
YAML, CSV, HTML)
* Editing and modifying existing files with content replacement
* Automatic backup creation before modifications
* Custom encoding and enhanced formatting options
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
timeout: Optional[float] = None,
default_encoding: str = 'utf-8',
backup_enabled: bool = True
):
```
Initialize the FileWriteToolkit.
**Parameters:**
* **working\_directory** (str, optional): The default directory for output files. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.
* **timeout** (Optional\[float]): The timeout for the toolkit. (default: :obj:`None`)
* **default\_encoding** (str): Default character encoding for text operations. (default: :obj:`utf-8`)
* **backup\_enabled** (bool): Whether to create backups of existing files before overwriting. (default: :obj:`True`)
### \_resolve\_filepath
```python theme={"system"}
def _resolve_filepath(self, file_path: str):
```
Convert the given string path to a Path object.
If the provided path is not absolute, it is made relative to the
default output directory. The filename part is sanitized to replace
spaces and special characters with underscores, ensuring safe usage
in downstream processing.
**Parameters:**
* **file\_path** (str): The file path to resolve.
**Returns:**
Path: A fully resolved (absolute) and sanitized Path object.
### \_sanitize\_filename
```python theme={"system"}
def _sanitize_filename(self, filename: str):
```
Sanitize a filename by replacing any character that is not
alphanumeric, a dot (.), hyphen (-), or underscore (*) with an
underscore (*).
**Parameters:**
* **filename** (str): The original filename which may contain spaces or special characters.
**Returns:**
str: The sanitized filename with disallowed characters replaced by
underscores.
### \_write\_text\_file
```python theme={"system"}
def _write_text_file(
self,
file_path: Path,
content: str,
encoding: str = 'utf-8'
):
```
Write text content to a plaintext file.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The text content to write.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### \_create\_backup
```python theme={"system"}
def _create_backup(self, file_path: Path):
```
Create a backup of the file if it exists and backup is enabled.
**Parameters:**
* **file\_path** (Path): The file path to backup.
**Returns:**
Optional\[Path]: Path to the backup file if created, None otherwise.
### \_write\_docx\_file
```python theme={"system"}
def _write_docx_file(self, file_path: Path, content: str):
```
Write text content to a DOCX file with default formatting.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The text content to write.
### \_write\_pdf\_file
```python theme={"system"}
def _write_pdf_file(
self,
file_path: Path,
title: str,
content: Union[str, List[List[str]]],
use_latex: bool = False
):
```
Write text content to a PDF file with LaTeX and table support.
**Parameters:**
* **file\_path** (Path): The target file path.
* **title** (str): The document title.
* **content** (Union\[str, List\[List\[str]]]): The content to write. Can
* **be**: - String: Supports Markdown-style tables and LaTeX math expressions - List\[List\[str]]: Table data as list of rows for direct table rendering
* **use\_latex** (bool): Whether to use LaTeX for math rendering. (default: :obj:`False`)
### \_process\_text\_content
```python theme={"system"}
def _process_text_content(
self,
story,
content: str,
heading_style,
body_style
):
```
Process text content and add to story.
**Parameters:**
* **story**: The reportlab story list to append to
* **content** (str): The text content to process
* **heading\_style**: Style for headings
* **body\_style**: Style for body text
### \_find\_table\_line\_ranges
```python theme={"system"}
def _find_table_line_ranges(self, lines: List[str]):
```
Find line ranges that contain markdown tables.
**Parameters:**
* **lines** (List\[str]): List of lines to analyze.
**Returns:**
List\[Tuple\[int, int]]: List of (start\_line, end\_line) tuples
for table ranges.
### \_register\_chinese\_font
```python theme={"system"}
def _register_chinese_font(self):
```
**Returns:**
str: The font name to use for Chinese text.
### \_parse\_markdown\_table
```python theme={"system"}
def _parse_markdown_table(self, lines: List[str]):
```
Parse markdown-style tables from a list of lines.
**Parameters:**
* **lines** (List\[str]): List of text lines that may contain tables.
**Returns:**
List\[List\[List\[str]]]: List of tables, where each table is a list
of rows, and each row is a list of cells.
### \_is\_table\_row
```python theme={"system"}
def _is_table_row(self, line: str):
```
Check if a line appears to be a table row.
**Parameters:**
* **line** (str): The line to check.
**Returns:**
bool: True if the line looks like a table row.
### \_is\_table\_separator
```python theme={"system"}
def _is_table_separator(self, line: str):
```
Check if a line is a table separator (e.g., |---|---|).
**Parameters:**
* **line** (str): The line to check.
**Returns:**
bool: True if the line is a table separator.
### \_parse\_table\_row
```python theme={"system"}
def _parse_table_row(self, line: str):
```
Parse a single table row into cells.
**Parameters:**
* **line** (str): The table row line.
**Returns:**
List\[str]: List of cell contents.
### \_create\_pdf\_table
```python theme={"system"}
def _create_pdf_table(self, table_data: List[List[str]]):
```
Create a formatted table for PDF.
**Parameters:**
* **table\_data** (List\[List\[str]]): Table data as list of rows.
**Returns:**
Table: A formatted reportlab Table object.
### \_convert\_markdown\_to\_html
```python theme={"system"}
def _convert_markdown_to_html(self, text: str):
```
Convert basic markdown formatting to HTML for PDF rendering.
**Parameters:**
* **text** (str): Text with markdown formatting.
**Returns:**
str: Text with HTML formatting.
### \_ensure\_html\_utf8\_meta
```python theme={"system"}
def _ensure_html_utf8_meta(self, content: str):
```
Ensure HTML content has UTF-8 meta tag.
**Parameters:**
* **content** (str): The HTML content.
**Returns:**
str: HTML content with UTF-8 meta tag.
### \_write\_csv\_file
```python theme={"system"}
def _write_csv_file(
self,
file_path: Path,
content: Union[str, List[List]],
encoding: str = 'utf-8-sig'
):
```
Write CSV content to a file.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (Union\[str, List\[List]]): The CSV content as a string or list of lists.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8-sig`)
### \_write\_json\_file
```python theme={"system"}
def _write_json_file(
self,
file_path: Path,
content: str,
encoding: str = 'utf-8'
):
```
Write JSON content to a file.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The JSON content as a string.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### \_write\_simple\_text\_file
```python theme={"system"}
def _write_simple_text_file(
self,
file_path: Path,
content: str,
encoding: str = 'utf-8'
):
```
Write text content to a file (used for HTML, Markdown, YAML, etc.).
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The content to write.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### write\_to\_file
```python theme={"system"}
def write_to_file(
self,
title: str,
content: Union[str, List[List[str]]],
filename: str,
encoding: Optional[str] = None,
use_latex: bool = False
):
```
Write the given content to a file.
If the file exists, it will be overwritten. Supports multiple formats:
Markdown (.md, .markdown, default), Plaintext (.txt), CSV (.csv),
DOC/DOCX (.doc, .docx), PDF (.pdf), JSON (.json), YAML (.yml, .yaml),
and HTML (.html, .htm).
**Parameters:**
* **title** (str): The title of the document.
* **content** (Union\[str, List\[List\[str]]]): The content to write to the file. Content format varies by file type: - Text formats (txt, md, html, yaml): string - CSV: string or list of lists - JSON: string or serializable object
* **filename** (str): The name or path of the file. If a relative path is supplied, it is resolved to self.working\_directory.
* **encoding** (Optional\[str]): The character encoding to use. (default: :obj: `None`)
* **use\_latex** (bool): Whether to use LaTeX for math rendering. (default: :obj:`False`)
**Returns:**
str: A message indicating success or error details.
### read\_file
```python theme={"system"}
def read_file(self, file_paths: Union[str, List[str]]):
```
Read and return content of one or more files using MarkItDown
for better format support.
This method uses MarkItDownLoader to convert various file formats
to Markdown. It supports a wide range of formats including:
* PDF (.pdf)
* Microsoft Office: Word (.doc, .docx), Excel (.xls, .xlsx),
PowerPoint (.ppt, .pptx)
* EPUB (.epub)
* HTML (.html, .htm)
* Images (.jpg, .jpeg, .png) for OCR
* Audio (.mp3, .wav) for transcription
* Text-based formats (.csv, .json, .xml, .txt, .md)
* ZIP archives (.zip)
**Parameters:**
* **file\_paths** (Union\[str, List\[str]]): A single file path or a list of file paths to read. Paths can be relative or absolute. If relative, they will be resolved relative to the working directory.
**Returns:**
Union\[str, Dict\[str, str]]:
* If a single file path is provided: Returns the content as
a string.
* If multiple file paths are provided: Returns a dictionary
where keys are file paths and values are the corresponding
content in Markdown format.
If conversion fails, returns an error message.
### edit\_file
```python theme={"system"}
def edit_file(
self,
file_path: str,
old_content: str,
new_content: str
):
```
Edit a file by replacing specified content.
This method performs simple text replacement in files. It reads
the file, replaces all occurrences of old\_content with new\_content,
and writes the result back.
**Parameters:**
* **file\_path** (str): The path to the file to edit. Can be relative or absolute. If relative, it will be resolved relative to the working directory.
* **old\_content** (str): The exact text to find and replace.
* **new\_content** (str): The text to replace old\_content with.
**Returns:**
str: A success message if the edit was successful, or an
error message if the content wasn't found or an error occurred.
### search\_files
```python theme={"system"}
def search_files(
self,
pattern: str,
file_types: Optional[List[str]] = None,
file_pattern: Optional[str] = None,
path: Optional[str] = None
):
```
Search for a text pattern in files with specified extensions or
file patterns.
This method searches for a text pattern (case-insensitive substring
match) in files matching either the specified file types or a file
pattern. It returns structured results showing which files contain
the pattern, along with line numbers and matching content.
**Parameters:**
* **pattern** (str): The text pattern to search for (case-insensitive string match).
* **file\_types** (Optional\[List\[str]]): List of file extensions to search (e.g., \["md", "txt", "py"]). Do not include the dot. If not provided and file\_pattern is also not provided, defaults to \["md"] (markdown files). Ignored if file\_pattern is provided. (default: :obj:`None`)
* **file\_pattern** (Optional\[str]): Glob pattern for matching files (e.g., "**workflow\.md", "test**.py"). If provided, this overrides file\_types. (default: :obj:`None`)
* **path** (Optional\[str]): Directory to search in. If not provided, uses the working\_directory. Can be relative or absolute. (default: :obj:`None`)
**Returns:**
str: JSON-formatted string containing search results with the
structure:
`\{
"pattern": "search_pattern",
"searched_path": "/absolute/path",
"file_types": ["md", "txt"],
"file_pattern": "*_workflow.md",
"matches": [
\{
"file": "relative/path/to/file.md",
"line": 42,
"content": "matching line content"
\},
...
],
"total_matches": 10,
"files_searched": 5
\}`
If an error occurs, returns a JSON string with an "error" key.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the available functions in this toolkit.
## FileWriteToolkit
```python theme={"system"}
class FileWriteToolkit(FileToolkit):
```
Deprecated: Use FileToolkit instead.
This class is maintained for backward compatibility only.
Please use FileToolkit for new code.
### **init**
```python theme={"system"}
def __init__(self, *args, **kwargs):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.file_write_toolkit
## FileWriteToolkit
```python theme={"system"}
class FileWriteToolkit(BaseToolkit):
```
A toolkit for creating, writing, and modifying text in files.
This class provides cross-platform (macOS, Linux, Windows) support for
writing to various file formats (Markdown, DOCX, PDF, and plaintext),
replacing text in existing files, automatic filename uniquification to
prevent overwrites, custom encoding and enhanced formatting options for
specialized formats.
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
timeout: Optional[float] = None,
default_encoding: str = 'utf-8',
backup_enabled: bool = True
):
```
Initialize the FileWriteToolkit.
**Parameters:**
* **working\_directory** (str, optional): The default directory for output files. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.
* **timeout** (Optional\[float]): The timeout for the toolkit. (default: :obj:`None`)
* **default\_encoding** (str): Default character encoding for text operations. (default: :obj:`utf-8`)
* **backup\_enabled** (bool): Whether to create backups of existing files before overwriting. (default: :obj:`True`)
### \_resolve\_filepath
```python theme={"system"}
def _resolve_filepath(self, file_path: str):
```
Convert the given string path to a Path object.
If the provided path is not absolute, it is made relative to the
default output directory. The filename part is sanitized to replace
spaces and special characters with underscores, ensuring safe usage
in downstream processing.
**Parameters:**
* **file\_path** (str): The file path to resolve.
**Returns:**
Path: A fully resolved (absolute) and sanitized Path object.
### \_sanitize\_filename
```python theme={"system"}
def _sanitize_filename(self, filename: str):
```
Sanitize a filename by replacing any character that is not
alphanumeric, a dot (.), hyphen (-), or underscore (*) with an
underscore (*).
**Parameters:**
* **filename** (str): The original filename which may contain spaces or special characters.
**Returns:**
str: The sanitized filename with disallowed characters replaced by
underscores.
### \_write\_text\_file
```python theme={"system"}
def _write_text_file(
self,
file_path: Path,
content: str,
encoding: str = 'utf-8'
):
```
Write text content to a plaintext file.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The text content to write.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### \_generate\_unique\_filename
```python theme={"system"}
def _generate_unique_filename(self, file_path: Path):
```
Generate a unique filename if the target file already exists.
**Parameters:**
* **file\_path** (Path): The original file path.
**Returns:**
Path: A unique file path that doesn't exist yet.
### \_write\_docx\_file
```python theme={"system"}
def _write_docx_file(self, file_path: Path, content: str):
```
Write text content to a DOCX file with default formatting.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The text content to write.
### \_write\_pdf\_file
```python theme={"system"}
def _write_pdf_file(
self,
file_path: Path,
title: str,
content: Union[str, List[List[str]]],
use_latex: bool = False
):
```
Write text content to a PDF file with LaTeX and table support.
**Parameters:**
* **file\_path** (Path): The target file path.
* **title** (str): The document title.
* **content** (Union\[str, List\[List\[str]]]): The content to write. Can
* **be**: - String: Supports Markdown-style tables and LaTeX math expressions - List\[List\[str]]: Table data as list of rows for direct table rendering
* **use\_latex** (bool): Whether to use LaTeX for math rendering. (default: :obj:`False`)
### \_process\_text\_content
```python theme={"system"}
def _process_text_content(
self,
story,
content: str,
heading_style,
body_style
):
```
Process text content and add to story.
**Parameters:**
* **story**: The reportlab story list to append to
* **content** (str): The text content to process
* **heading\_style**: Style for headings
* **body\_style**: Style for body text
### \_find\_table\_line\_ranges
```python theme={"system"}
def _find_table_line_ranges(self, lines: List[str]):
```
Find line ranges that contain markdown tables.
**Parameters:**
* **lines** (List\[str]): List of lines to analyze.
**Returns:**
List\[Tuple\[int, int]]: List of (start\_line, end\_line) tuples
for table ranges.
### \_register\_chinese\_font
```python theme={"system"}
def _register_chinese_font(self):
```
**Returns:**
str: The font name to use for Chinese text.
### \_parse\_markdown\_table
```python theme={"system"}
def _parse_markdown_table(self, lines: List[str]):
```
Parse markdown-style tables from a list of lines.
**Parameters:**
* **lines** (List\[str]): List of text lines that may contain tables.
**Returns:**
List\[List\[List\[str]]]: List of tables, where each table is a list
of rows, and each row is a list of cells.
### \_is\_table\_row
```python theme={"system"}
def _is_table_row(self, line: str):
```
Check if a line appears to be a table row.
**Parameters:**
* **line** (str): The line to check.
**Returns:**
bool: True if the line looks like a table row.
### \_is\_table\_separator
```python theme={"system"}
def _is_table_separator(self, line: str):
```
Check if a line is a table separator (e.g., |---|---|).
**Parameters:**
* **line** (str): The line to check.
**Returns:**
bool: True if the line is a table separator.
### \_parse\_table\_row
```python theme={"system"}
def _parse_table_row(self, line: str):
```
Parse a single table row into cells.
**Parameters:**
* **line** (str): The table row line.
**Returns:**
List\[str]: List of cell contents.
### \_create\_pdf\_table
```python theme={"system"}
def _create_pdf_table(self, table_data: List[List[str]]):
```
Create a formatted table for PDF.
**Parameters:**
* **table\_data** (List\[List\[str]]): Table data as list of rows.
**Returns:**
Table: A formatted reportlab Table object.
### \_convert\_markdown\_to\_html
```python theme={"system"}
def _convert_markdown_to_html(self, text: str):
```
Convert basic markdown formatting to HTML for PDF rendering.
**Parameters:**
* **text** (str): Text with markdown formatting.
**Returns:**
str: Text with HTML formatting.
### \_ensure\_html\_utf8\_meta
```python theme={"system"}
def _ensure_html_utf8_meta(self, content: str):
```
Ensure HTML content has UTF-8 meta tag.
**Parameters:**
* **content** (str): The HTML content.
**Returns:**
str: HTML content with UTF-8 meta tag.
### \_write\_csv\_file
```python theme={"system"}
def _write_csv_file(
self,
file_path: Path,
content: Union[str, List[List]],
encoding: str = 'utf-8'
):
```
Write CSV content to a file.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (Union\[str, List\[List]]): The CSV content as a string or list of lists.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### \_write\_json\_file
```python theme={"system"}
def _write_json_file(
self,
file_path: Path,
content: str,
encoding: str = 'utf-8'
):
```
Write JSON content to a file.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The JSON content as a string.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### \_write\_simple\_text\_file
```python theme={"system"}
def _write_simple_text_file(
self,
file_path: Path,
content: str,
encoding: str = 'utf-8'
):
```
Write text content to a file (used for HTML, Markdown, YAML, etc.).
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (str): The content to write.
* **encoding** (str): Character encoding to use. (default: :obj:`utf-8`) (default: utf-8)
### write\_to\_file
```python theme={"system"}
def write_to_file(
self,
title: str,
content: Union[str, List[List[str]]],
filename: str,
encoding: Optional[str] = None,
use_latex: bool = False
):
```
Write the given content to a file.
If the file exists, it will be overwritten. Supports multiple formats:
Markdown (.md, .markdown, default), Plaintext (.txt), CSV (.csv),
DOC/DOCX (.doc, .docx), PDF (.pdf), JSON (.json), YAML (.yml, .yaml),
and HTML (.html, .htm).
**Parameters:**
* **title** (str): The title of the document.
* **content** (Union\[str, List\[List\[str]]]): The content to write to the file. Content format varies by file type: - Text formats (txt, md, html, yaml): string - CSV: string or list of lists - JSON: string or serializable object
* **filename** (str): The name or path of the file. If a relative path is supplied, it is resolved to self.working\_directory.
* **encoding** (Optional\[str]): The character encoding to use. (default: :obj: `None`)
* **use\_latex** (bool): Whether to use LaTeX for math rendering. (default: :obj:`False`)
**Returns:**
str: A message indicating success or error details.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the available functions in this toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.function_tool
## \_remove\_a\_key
```python theme={"system"}
def _remove_a_key(d: Dict, remove_key: Any):
```
Remove a key from a dictionary recursively.
## \_remove\_title\_recursively
```python theme={"system"}
def _remove_title_recursively(data, parent_key = None):
```
Recursively removes the 'title' key from all levels of a nested
dictionary, except when 'title' is an argument name in the schema.
## get\_openai\_function\_schema
```python theme={"system"}
def get_openai_function_schema(func: Callable):
```
Generates a schema dict for an OpenAI function based on its signature.
This function is deprecated and will be replaced by
:obj:`get_openai_tool_schema()` in future versions. It parses the
function's parameters and docstring to construct a JSON schema-like
dictionary.
**Parameters:**
* **func** (Callable): The OpenAI function to generate the schema for.
**Returns:**
Dict\[str, Any]: A dictionary representing the JSON schema of the
function, including its name, description, and parameter
specifications.
## get\_openai\_tool\_schema
```python theme={"system"}
def get_openai_tool_schema(func: Callable):
```
Generates an OpenAI JSON schema from a given Python function.
This function creates a schema compatible with OpenAI's API specifications,
based on the provided Python function. It processes the function's
parameters, types, and docstrings, and constructs a schema accordingly.
**Parameters:**
* **func** (Callable): The Python function to be converted into an OpenAI JSON schema.
**Returns:**
Dict\[str, Any]: A dictionary representing the OpenAI JSON schema of
the provided function.
See Also:
[OpenAI API Reference](https://platform.openai.com/docs/api-reference/assistants/object)
## sanitize\_and\_enforce\_required
```python theme={"system"}
def sanitize_and_enforce_required(parameters_dict):
```
Cleans and updates the function schema to conform with OpenAI's
requirements:
* Removes invalid 'default' fields from the parameters schema.
* Ensures all fields are marked as required or have null type for optional
fields.
* Recursively adds additionalProperties: false to all nested objects.
**Parameters:**
* **parameters\_dict** (dict): The dictionary representing the function schema.
**Returns:**
dict: The updated dictionary with invalid defaults removed and all
fields properly configured for strict mode.
## generate\_docstring
```python theme={"system"}
def generate_docstring(code: str, model: Optional[BaseModelBackend] = None):
```
Generates a docstring for a given function code using LLM.
This function leverages a language model to generate a
PEP 8/PEP 257-compliant docstring for a provided Python function.
If no model is supplied, a default gpt-4o-mini is used.
**Parameters:**
* **code** (str): The source code of the function.
* **model** (Optional\[BaseModelBackend]): An optional language model backend instance. If not provided, a default gpt-4o-mini is used.
**Returns:**
str: The generated docstring.
## FunctionTool
```python theme={"system"}
class FunctionTool:
```
An abstraction of a function that OpenAI chat models can call. See
[https://platform.openai.com/docs/api-reference/chat/create](https://platform.openai.com/docs/api-reference/chat/create).
By default, the tool schema will be parsed from the func, or you can
provide a user-defined tool schema to override.
**Parameters:**
* **func** (Callable): The function to call. The tool schema is parsed from the function signature and docstring by default.
* **openai\_tool\_schema** (Optional\[Dict\[str, Any]], optional): A user-defined OpenAI tool schema to override the default result. (default: :obj:`None`)
* **synthesize\_schema** (Optional\[bool], optional): Whether to enable the use of a schema assistant model to automatically synthesize the schema if validation fails or no valid schema is provided. (default: :obj:`False`)
* **synthesize\_schema\_model** (Optional\[BaseModelBackend], optional): An assistant model (e.g., an LLM model) used to synthesize the schema if `synthesize_schema` is enabled and no valid schema is provided. (default: :obj:`None`)
* **synthesize\_schema\_max\_retries** (int, optional): The maximum number of attempts to retry schema synthesis using the schema assistant model if the previous attempts fail. (default: 2)
* **synthesize\_output** (Optional\[bool], optional): Flag for enabling synthesis output mode, where output is synthesized based on the function's execution. (default: :obj:`False`)
* **synthesize\_output\_model** (Optional\[BaseModelBackend], optional): Model used for output synthesis in synthesis mode. (default: :obj:`None`)
* **synthesize\_output\_format** (Optional\[Type\[BaseModel]], optional): Format for the response when synthesizing output. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
func: Callable,
openai_tool_schema: Optional[Dict[str, Any]] = None,
synthesize_schema: Optional[bool] = False,
synthesize_schema_model: Optional[BaseModelBackend] = None,
synthesize_schema_max_retries: int = 2,
synthesize_output: Optional[bool] = False,
synthesize_output_model: Optional[BaseModelBackend] = None,
synthesize_output_format: Optional[Type[BaseModel]] = None
):
```
### **call**
```python theme={"system"}
def __call__(self, *args: Any, **kwargs: Any):
```
### \_run\_async\_in\_persistent\_loop
```python theme={"system"}
def _run_async_in_persistent_loop(coro):
```
Run coroutine in persistent loop to preserve httpx connections.
### is\_async
```python theme={"system"}
def is_async(self):
```
### validate\_openai\_tool\_schema
```python theme={"system"}
def validate_openai_tool_schema(openai_tool_schema: Dict[str, Any]):
```
Validates the OpenAI tool schema against
:obj:`ToolAssistantToolsFunction`.
This function checks if the provided :obj:`openai_tool_schema` adheres
to the specifications required by OpenAI's
:obj:`ToolAssistantToolsFunction`. It ensures that the function
description and parameters are correctly formatted according to JSON
Schema specifications.
**Parameters:**
* **openai\_tool\_schema** (Dict\[str, Any]): The OpenAI tool schema to validate.
### get\_openai\_tool\_schema
```python theme={"system"}
def get_openai_tool_schema(self):
```
**Returns:**
Dict\[str, Any]: The OpenAI tool schema for this function.
### set\_openai\_tool\_schema
```python theme={"system"}
def set_openai_tool_schema(self, schema: Dict[str, Any]):
```
Sets the OpenAI tool schema for this function.
Allows setting a custom OpenAI tool schema for this function.
**Parameters:**
* **schema** (Dict\[str, Any]): The OpenAI tool schema to set.
### get\_openai\_function\_schema
```python theme={"system"}
def get_openai_function_schema(self):
```
**Returns:**
Dict\[str, Any]: The schema of the function within the OpenAI tool
schema.
### set\_openai\_function\_schema
```python theme={"system"}
def set_openai_function_schema(self, openai_function_schema: Dict[str, Any]):
```
Sets the schema of the function within the OpenAI tool schema.
**Parameters:**
* **openai\_function\_schema** (Dict\[str, Any]): The function schema to set within the OpenAI tool schema.
### get\_function\_name
```python theme={"system"}
def get_function_name(self):
```
**Returns:**
str: The name of the function.
### set\_function\_name
```python theme={"system"}
def set_function_name(self, name: str):
```
Sets the name of the function in the OpenAI tool schema.
**Parameters:**
* **name** (str): The name of the function to set.
### get\_function\_description
```python theme={"system"}
def get_function_description(self):
```
**Returns:**
str: The description of the function.
### set\_function\_description
```python theme={"system"}
def set_function_description(self, description: str):
```
Sets the description of the function in the OpenAI tool schema.
**Parameters:**
* **description** (str): The description for the function.
### get\_parameter\_description
```python theme={"system"}
def get_parameter_description(self, param_name: str):
```
Gets the description of a specific parameter from the function
schema.
**Parameters:**
* **param\_name** (str): The name of the parameter to get the description.
**Returns:**
str: The description of the specified parameter.
### set\_parameter\_description
```python theme={"system"}
def set_parameter_description(self, param_name: str, description: str):
```
Sets the description for a specific parameter in the function
schema.
**Parameters:**
* **param\_name** (str): The name of the parameter to set the description for.
* **description** (str): The description for the parameter.
### get\_parameter
```python theme={"system"}
def get_parameter(self, param_name: str):
```
Gets the schema for a specific parameter from the function schema.
**Parameters:**
* **param\_name** (str): The name of the parameter to get the schema.
**Returns:**
Dict\[str, Any]: The schema of the specified parameter.
### set\_parameter
```python theme={"system"}
def set_parameter(self, param_name: str, value: Dict[str, Any]):
```
Sets the schema for a specific parameter in the function schema.
**Parameters:**
* **param\_name** (str): The name of the parameter to set the schema for.
* **value** (Dict\[str, Any]): The schema to set for the parameter.
### synthesize\_openai\_tool\_schema
```python theme={"system"}
def synthesize_openai_tool_schema(self, max_retries: Optional[int] = None):
```
Synthesizes an OpenAI tool schema for the specified function.
This method uses a language model (LLM) to synthesize the OpenAI tool
schema for the specified function by first generating a docstring and
then creating a schema based on the function's source code. The
schema synthesis and validation process is retried up to
`max_retries` times in case of failure.
**Parameters:**
* **max\_retries** (Optional\[int], optional): The maximum number of retries for schema synthesis and validation if the process fails. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: The synthesis OpenAI tool schema for the function.
### synthesize\_execution\_output
```python theme={"system"}
def synthesize_execution_output(
self,
args: Optional[tuple[Any, ...]] = None,
kwargs: Optional[Dict[str, Any]] = None
):
```
Synthesizes the output of the function based on the provided
positional arguments and keyword arguments.
**Parameters:**
* **args** (Optional\[tuple]): Positional arguments to pass to the function during synthesis. (default: :obj:`None`)
* **kwargs** (Optional\[Dict\[str, Any]]): Keyword arguments to pass to the function during synthesis. (default: :obj:`None`)
**Returns:**
Any: Synthesized output from the function execution. If no
synthesis model is provided, a warning is logged.
### parameters
```python theme={"system"}
def parameters(self):
```
**Returns:**
Dict\[str, Any]: the dictionary containing information of
parameters of this function.
### parameters
```python theme={"system"}
def parameters(self, value: Dict[str, Any]):
```
Setter method for the property :obj:`parameters`. It will
firstly check if the input parameters schema is valid. If invalid,
the method will raise :obj:`jsonschema.exceptions.SchemaError`.
**Parameters:**
* **value** (Dict\[str, Any]): the new dictionary value for the function's parameters.
## tool
```python theme={"system"}
def tool(func: Optional[Callable] = None):
```
A decorator that converts a Python function into a FunctionTool
instance.
This decorator can be used with or without parentheses:
* @tool - without parentheses, uses default settings
* @tool() - with parentheses, uses default settings
* @tool(synthesize\_output=True) - with custom settings
**Parameters:**
* **func** (Optional\[Callable], optional): The function to be decorated. This is automatically passed when using @tool without parentheses. (default: :obj:`None`)
* **openai\_tool\_schema** (Optional\[Dict\[str, Any]], optional): A user-defined OpenAI tool schema to override the default result. (default: :obj:`None`)
* **synthesize\_schema** (bool, optional): Whether to enable schema synthesis. (default: :obj:`False`)
* **synthesize\_schema\_model** (Optional\[BaseModelBackend], optional): Model to use for schema synthesis. (default: :obj:`None`)
* **synthesize\_schema\_max\_retries** (int, optional): Maximum number of retries for schema synthesis. (default: :obj:`2`)
* **synthesize\_output** (bool, optional): Whether to enable output synthesis. (default: :obj:`False`)
* **synthesize\_output\_model** (Optional\[BaseModelBackend], optional): Model to use for output synthesis. (default: :obj:`None`)
* **synthesize\_output\_format** (Optional\[Type\[BaseModel]], optional): Format for synthesized output. (default: :obj:`None`)
**Returns:**
Callable\[\[Callable], FunctionTool]: A decorator function that converts
the decorated function into a FunctionTool instance.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.github_toolkit
## GithubToolkit
```python theme={"system"}
class GithubToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with GitHub
repositories.
This class provides methods for retrieving open issues, retrieving
specific issues, and creating pull requests in a GitHub repository.
**Parameters:**
* **access\_token** (str, optional): The access token to authenticate with GitHub. If not provided, it will be obtained using the `get_github_access_token` method.
### **init**
```python theme={"system"}
def __init__(
self,
access_token: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initializes a new instance of the GitHubToolkit class.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **access\_token** (str, optional): The access token to authenticate with GitHub. If not provided, it will be obtained using the `get_github_access_token` method.
### get\_github\_access\_token
```python theme={"system"}
def get_github_access_token(self):
```
**Returns:**
str: A string containing the GitHub access token.
### github\_create\_pull\_request
```python theme={"system"}
def github_create_pull_request(
self,
repo_name: str,
file_path: str,
new_content: str,
pr_title: str,
body: str,
branch_name: str
):
```
Creates a pull request.
This function creates a pull request in specified repository, which
updates a file in the specific path with new content. The pull request
description contains information about the issue title and number.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **file\_path** (str): The path of the file to be updated in the repository.
* **new\_content** (str): The specified new content of the specified file.
* **pr\_title** (str): The title of the issue that is solved by this pull request.
* **body** (str): The commit message for the pull request.
* **branch\_name** (str): The name of the branch to create and submit the pull request from.
**Returns:**
str: A formatted report of whether the pull request was created
successfully or not.
### github\_get\_issue\_list
```python theme={"system"}
def github_get_issue_list(
self,
repo_name: str,
state: Literal['open', 'closed', 'all'] = 'all'
):
```
Retrieves all issues from the GitHub repository.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **state** (`Literal["open", "closed", "all"]`): The state of pull requests to retrieve. (default: :obj:`all`) Options are: - "open": Retrieve only open pull requests. - "closed": Retrieve only closed pull requests. - "all": Retrieve all pull requests, regardless of state.
**Returns:**
List\[Dict\[str, object]]: A list of dictionaries where each
dictionary contains the issue number and title.
### github\_get\_issue\_content
```python theme={"system"}
def github_get_issue_content(self, repo_name: str, issue_number: int):
```
Retrieves the content of a specific issue by its number.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **issue\_number** (int): The number of the issue to retrieve.
**Returns:**
str: issues content details.
### github\_get\_pull\_request\_list
```python theme={"system"}
def github_get_pull_request_list(
self,
repo_name: str,
state: Literal['open', 'closed', 'all'] = 'all'
):
```
Retrieves all pull requests from the GitHub repository.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **state** (`Literal["open", "closed", "all"]`): The state of pull requests to retrieve. (default: :obj:`all`) Options are: - "open": Retrieve only open pull requests. - "closed": Retrieve only closed pull requests. - "all": Retrieve all pull requests, regardless of state.
**Returns:**
list: A list of dictionaries where each dictionary contains the
pull request number and title.
### github\_get\_pull\_request\_code
```python theme={"system"}
def github_get_pull_request_code(self, repo_name: str, pr_number: int):
```
Retrieves the code changes of a specific pull request.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **pr\_number** (int): The number of the pull request to retrieve.
**Returns:**
List\[Dict\[str, str]]: A list of dictionaries where each dictionary
contains the file name and the corresponding code changes
(patch).
### github\_get\_pull\_request\_comments
```python theme={"system"}
def github_get_pull_request_comments(self, repo_name: str, pr_number: int):
```
Retrieves the comments from a specific pull request.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **pr\_number** (int): The number of the pull request to retrieve.
**Returns:**
List\[Dict\[str, str]]: A list of dictionaries where each dictionary
contains the user ID and the comment body.
### github\_get\_all\_file\_paths
```python theme={"system"}
def github_get_all_file_paths(self, repo_name: str, path: str = ''):
```
Recursively retrieves all file paths in the GitHub repository.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **path** (str): The repository path to start the traversal from. empty string means starts from the root directory. (default: :obj:`""`)
**Returns:**
List\[str]: A list of file paths within the specified directory
structure.
### github\_retrieve\_file\_content
```python theme={"system"}
def github_retrieve_file_content(self, repo_name: str, file_path: str):
```
Retrieves the content of a file from the GitHub repository.
**Parameters:**
* **repo\_name** (str): The name of the GitHub repository.
* **file\_path** (str): The path of the file to retrieve.
**Returns:**
str: The decoded content of the file.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
### create\_pull\_request
```python theme={"system"}
def create_pull_request(self, *args, **kwargs):
```
Deprecated: Use github\_create\_pull\_request instead.
### get\_issue\_list
```python theme={"system"}
def get_issue_list(self, *args, **kwargs):
```
Deprecated: Use github\_get\_issue\_list instead.
### get\_issue\_content
```python theme={"system"}
def get_issue_content(self, *args, **kwargs):
```
Deprecated: Use github\_get\_issue\_content instead.
### get\_pull\_request\_list
```python theme={"system"}
def get_pull_request_list(self, *args, **kwargs):
```
Deprecated: Use github\_get\_pull\_request\_list instead.
### get\_pull\_request\_code
```python theme={"system"}
def get_pull_request_code(self, *args, **kwargs):
```
Deprecated: Use github\_get\_pull\_request\_code instead.
### get\_pull\_request\_comments
```python theme={"system"}
def get_pull_request_comments(self, *args, **kwargs):
```
Deprecated: Use github\_get\_pull\_request\_comments instead.
### get\_all\_file\_paths
```python theme={"system"}
def get_all_file_paths(self, *args, **kwargs):
```
Deprecated: Use github\_get\_all\_file\_paths instead.
### retrieve\_file\_content
```python theme={"system"}
def retrieve_file_content(self, *args, **kwargs):
```
Deprecated: Use github\_retrieve\_file\_content instead.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.gmail_toolkit
## GmailToolkit
```python theme={"system"}
class GmailToolkit(BaseToolkit):
```
A comprehensive toolkit for Gmail operations.
This class provides methods for Gmail operations including sending emails,
managing drafts, fetching messages, managing labels, and handling contacts.
API keys can be accessed in google cloud console ([https://console.cloud.google.com/](https://console.cloud.google.com/))
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes a new instance of the GmailToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### people\_service
```python theme={"system"}
def people_service(self):
```
Lazily initialize and return the Google People service.
### people\_service
```python theme={"system"}
def people_service(self, service: Any):
```
Allow overriding/injecting the People service (e.g., in tests).
### gmail\_send\_email
```python theme={"system"}
def gmail_send_email(
self,
to: Union[str, List[str]],
subject: str,
body: str,
cc: Optional[Union[str, List[str]]] = None,
bcc: Optional[Union[str, List[str]]] = None,
attachments: Optional[List[str]] = None,
is_html: bool = False
):
```
Send an email through Gmail.
**Parameters:**
* **to** (Union\[str, List\[str]]): Recipient email address(es).
* **subject** (str): Email subject.
* **body** (str): Email body content.
* **cc** (Optional\[Union\[str, List\[str]]]): CC recipient email address(es).
* **bcc** (Optional\[Union\[str, List\[str]]]): BCC recipient email address(es).
* **attachments** (Optional\[List\[str]]): List of file paths to attach.
* **is\_html** (bool): Whether the body is HTML format. Set to True when sending formatted emails with HTML tags (e.g., bold, links, images). Use False (default) for plain text emails.
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_reply\_to\_email
```python theme={"system"}
def gmail_reply_to_email(
self,
message_id: str,
reply_body: str,
reply_all: bool = False,
is_html: bool = False
):
```
Reply to an email message.
**Parameters:**
* **message\_id** (str): The unique identifier of the message to reply to. To get a message ID, first use fetch\_emails() to list messages, or use the 'message\_id' returned from send\_email() or create\_email\_draft().
* **reply\_body** (str): The reply message body.
* **reply\_all** (bool): Whether to reply to all recipients.
* **is\_html** (bool): Whether the body is HTML format. Set to True when sending formatted emails with HTML tags (e.g., bold, links, images). Use False (default) for plain text emails.
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_forward\_email
```python theme={"system"}
def gmail_forward_email(
self,
message_id: str,
to: Union[str, List[str]],
forward_body: Optional[str] = None,
cc: Optional[Union[str, List[str]]] = None,
bcc: Optional[Union[str, List[str]]] = None,
include_attachments: bool = True
):
```
Forward an email message.
**Parameters:**
* **message\_id** (str): The unique identifier of the message to forward. To get a message ID, first use fetch\_emails() to list messages, or use the 'message\_id' returned from send\_email() or create\_email\_draft().
* **to** (Union\[str, List\[str]]): Recipient email address(es).
* **forward\_body** (Optional\[str]): Additional message to include at the top of the forwarded email, before the original message content. If not provided, only the original message will be forwarded.
* **cc** (Optional\[Union\[str, List\[str]]]): CC recipient email address(es).
* **bcc** (Optional\[Union\[str, List\[str]]]): BCC recipient email address(es).
* **include\_attachments** (bool): Whether to include original attachments. Defaults to True. Only includes real attachments, not inline images.
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation, including the number of attachments forwarded.
### gmail\_create\_draft
```python theme={"system"}
def gmail_create_draft(
self,
to: Union[str, List[str]],
subject: str,
body: str,
cc: Optional[Union[str, List[str]]] = None,
bcc: Optional[Union[str, List[str]]] = None,
attachments: Optional[List[str]] = None,
is_html: bool = False
):
```
Create an email draft.
**Parameters:**
* **to** (Union\[str, List\[str]]): Recipient email address(es).
* **subject** (str): Email subject.
* **body** (str): Email body content.
* **cc** (Optional\[Union\[str, List\[str]]]): CC recipient email address(es).
* **bcc** (Optional\[Union\[str, List\[str]]]): BCC recipient email address(es).
* **attachments** (Optional\[List\[str]]): List of file paths to attach.
* **is\_html** (bool): Whether the body is HTML format. Set to True when sending formatted emails with HTML tags (e.g., bold, links, images). Use False (default) for plain text emails.
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_send\_draft
```python theme={"system"}
def gmail_send_draft(self, draft_id: str):
```
Send a draft email.
**Parameters:**
* **draft\_id** (str): The unique identifier of the draft to send. To get a draft ID, first use list\_drafts() to list drafts, or use the 'draft\_id' returned from create\_email\_draft().
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_fetch\_emails
```python theme={"system"}
def gmail_fetch_emails(
self,
query: str = '',
max_results: int = 10,
include_spam_trash: bool = False,
label_ids: Optional[List[str]] = None,
page_token: Optional[str] = None
):
```
Fetch emails with filters and pagination.
**Parameters:**
* **query** (str): Gmail search query string. Use Gmail's search syntax: - 'from:[example@domain.com](mailto:example@domain.com)' - emails from specific sender - 'subject:meeting' - emails with specific subject text - 'has:attachment' - emails with attachments - 'is:unread' - unread emails - 'in:sent' - emails in sent folder - 'after:2024/01/01 before:2024/12/31' - date range
**Returns:**
Dict\[str, Any]: A dictionary containing the fetched emails.
### gmail\_fetch\_thread\_by\_id
```python theme={"system"}
def gmail_fetch_thread_by_id(self, thread_id: str):
```
Fetch a thread by ID.
**Parameters:**
* **thread\_id** (str): The unique identifier of the thread to fetch. To get a thread ID, first use list\_threads() to list threads, or use the 'thread\_id' returned from send\_email() or reply\_to\_email().
**Returns:**
Dict\[str, Any]: A dictionary containing the thread details.
### gmail\_modify\_email\_labels
```python theme={"system"}
def gmail_modify_email_labels(
self,
message_id: str,
add_labels: Optional[List[str]] = None,
remove_labels: Optional[List[str]] = None
):
```
Modify labels on an email message.
**Parameters:**
* **message\_id** (str): The unique identifier of the message to modify. To get a message ID, first use fetch\_emails() to list messages, or use the 'message\_id' returned from send\_email() or create\_email\_draft().
* **add\_labels** (Optional\[List\[str]]): List of label IDs to add to the message. Label IDs can be: - System labels: 'INBOX', 'STARRED', 'IMPORTANT', 'UNREAD', etc. - Custom label IDs: Retrieved from list\_gmail\_labels() method.
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_move\_to\_trash
```python theme={"system"}
def gmail_move_to_trash(self, message_id: str):
```
Move a message to trash.
**Parameters:**
* **message\_id** (str): The unique identifier of the message to move to trash. To get a message ID, first use fetch\_emails() to list messages, or use the 'message\_id' returned from send\_email() or create\_email\_draft().
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_get\_attachment
```python theme={"system"}
def gmail_get_attachment(
self,
message_id: str,
attachment_id: str,
save_path: Optional[str] = None
):
```
Get an attachment from a message.
**Parameters:**
* **message\_id** (str): The unique identifier of the message containing the attachment. To get a message ID, first use fetch\_emails() to list messages, or use the 'message\_id' returned from send\_email() or create\_email\_draft().
* **attachment\_id** (str): The unique identifier of the attachment to download. To get an attachment ID, first use fetch\_emails() to get message details, then look for 'attachment\_id' in the 'attachments' list of each message.
* **save\_path** (Optional\[str]): Local file path where the attachment should be saved. If provided, the attachment will be saved to this location and the response will include a success message. If not provided, the attachment data will be returned as base64-encoded content in the response.
**Returns:**
Dict\[str, Any]: A dictionary containing the attachment data or
save result.
### gmail\_list\_threads
```python theme={"system"}
def gmail_list_threads(
self,
query: str = '',
max_results: int = 10,
include_spam_trash: bool = False,
label_ids: Optional[List[str]] = None,
page_token: Optional[str] = None
):
```
List email threads.
**Parameters:**
* **query** (str): Gmail search query string. Use Gmail's search syntax: - 'from:[example@domain.com](mailto:example@domain.com)' - threads from specific sender - 'subject:meeting' - threads with specific subject text - 'has:attachment' - threads with attachments - 'is:unread' - unread threads - 'in:sent' - threads in sent folder - 'after:2024/01/01 before:2024/12/31' - date range
**Returns:**
Dict\[str, Any]: A dictionary containing the thread list.
### gmail\_list\_drafts
```python theme={"system"}
def gmail_list_drafts(self, max_results: int = 10, page_token: Optional[str] = None):
```
List email drafts.
**Parameters:**
* **max\_results** (int): Maximum number of drafts to fetch.
* **page\_token** (Optional\[str]): Pagination token from a previous response. If provided, fetches the next page of results.
**Returns:**
Dict\[str, Any]: A dictionary containing the draft list.
### gmail\_list\_labels
```python theme={"system"}
def gmail_list_labels(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing the label list.
### gmail\_create\_label
```python theme={"system"}
def gmail_create_label(
self,
name: str,
label_list_visibility: Literal['labelShow', 'labelHide'] = 'labelShow',
message_list_visibility: Literal['show', 'hide'] = 'show'
):
```
Create a new Gmail label.
**Parameters:**
* **name** (str): The name of the label to create.
* **label\_list\_visibility** (str): How the label appears in Gmail's label list. - 'labelShow': Label is visible in the label list sidebar (default) - 'labelHide': Label is hidden from the label list sidebar
* **message\_list\_visibility** (str): How the label appears in message lists. - 'show': Label is visible on messages in inbox/lists (default) - 'hide': Label is hidden from message displays
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_delete\_label
```python theme={"system"}
def gmail_delete_label(self, label_id: str):
```
Delete a Gmail label.
**Parameters:**
* **label\_id** (str): The unique identifier of the user-created label to delete. To get a label ID, first use list\_gmail\_labels() to list all labels. Note: System labels (e.g., 'INBOX', 'SENT', 'DRAFT', 'SPAM', 'TRASH', 'UNREAD', 'STARRED', 'IMPORTANT', 'CATEGORY\_PERSONAL', etc.) cannot be deleted.
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_modify\_thread\_labels
```python theme={"system"}
def gmail_modify_thread_labels(
self,
thread_id: str,
add_labels: Optional[List[str]] = None,
remove_labels: Optional[List[str]] = None
):
```
Modify labels on a thread.
**Parameters:**
* **thread\_id** (str): The unique identifier of the thread to modify. To get a thread ID, first use list\_threads() to list threads, or use the 'thread\_id' returned from send\_email() or reply\_to\_email().
* **add\_labels** (Optional\[List\[str]]): List of label IDs to add to all messages in the thread. Label IDs can be: - System labels: 'INBOX', 'STARRED', 'IMPORTANT', 'UNREAD', etc. - Custom label IDs: Retrieved from list\_gmail\_labels().
**Returns:**
Dict\[str, Any]: A dictionary containing the result of the
operation.
### gmail\_get\_profile
```python theme={"system"}
def gmail_get_profile(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing the profile information.
### gmail\_get\_contacts
```python theme={"system"}
def gmail_get_contacts(self, max_results: int = 100, page_token: Optional[str] = None):
```
List connections from Google People API.
**Parameters:**
* **max\_results** (int): Maximum number of contacts to fetch.
* **page\_token** (Optional\[str]): Pagination token from a previous response. If provided, fetches the next page of results.
**Returns:**
Dict\[str, Any]: A dictionary containing the contacts.
### gmail\_search\_people
```python theme={"system"}
def gmail_search_people(self, query: str, max_results: int = 10):
```
Search for people in contacts.
**Parameters:**
* **query** (str): Search query for people in contacts. Can search by: - Name: 'John Smith' or partial names like 'John' - Email: '[john@example.com](mailto:john@example.com)' - Organization: 'Google' or 'Acme Corp' - Phone number: '+1234567890'
**Returns:**
Dict\[str, Any]: A dictionary containing the search results.
### \_get\_gmail\_service
```python theme={"system"}
def _get_gmail_service(self):
```
Get Gmail service object.
### \_get\_people\_service
```python theme={"system"}
def _get_people_service(self):
```
Get People service object.
### \_authenticate
```python theme={"system"}
def _authenticate(self):
```
Authenticate with Google APIs using OAuth2.
Automatically saves and loads credentials from
\~/.camel/gmail\_token.json to avoid repeated
browser logins.
### \_create\_message
```python theme={"system"}
def _create_message(
self,
to_list: List[str],
subject: str,
body: str,
cc_list: Optional[List[str]] = None,
bcc_list: Optional[List[str]] = None,
attachments: Optional[List[str]] = None,
is_html: bool = False,
in_reply_to: Optional[str] = None,
references: Optional[List[str]] = None
):
```
Create a message object for sending.
### \_get\_message\_details
```python theme={"system"}
def _get_message_details(self, message_id: str):
```
Get detailed information about a message.
### \_get\_header\_value
```python theme={"system"}
def _get_header_value(self, headers: List[Dict[str, str]], name: str):
```
Get header value by name.
### \_extract\_message\_body
```python theme={"system"}
def _extract_message_body(self, message: Dict[str, Any]):
```
Extract message body from message payload.
Recursively traverses the entire message tree and collects all text
content from text/plain and text/html parts. Special handling for
multipart/alternative containers: recursively searches for one format
(preferring plain text) to avoid duplication when both formats contain
the same content. All other text parts are collected to ensure no
information is lost.
**Parameters:**
* **message** (Dict\[str, Any]): The Gmail message dictionary containing the payload to extract text from.
**Returns:**
str: The extracted message body text with multiple parts separated
by double newlines, or an empty string if no text content is
found.
### \_extract\_attachments
```python theme={"system"}
def _extract_attachments(self, message: Dict[str, Any], include_inline: bool = False):
```
Extract attachment information from message payload.
Recursively traverses the message tree to find all attachments
and extracts their metadata. Distinguishes between regular attachments
and inline images embedded in HTML content.
**Parameters:**
* **message** (Dict\[str, Any]): The Gmail message dictionary containing the payload to extract attachments from.
**Returns:**
List\[Dict\[str, Any]]: List of attachment dictionaries, each
containing:
* attachment\_id: Gmail's unique identifier for the attachment
* filename: Name of the attached file
* mime\_type: MIME type of the attachment
* size: Size of the attachment in bytes
* is\_inline: Whether this is an inline image (embedded in HTML)
### \_is\_valid\_email
```python theme={"system"}
def _is_valid_email(self, email: str):
```
Validate email address format.
Supports both formats:
* Plain email: [john@example.com](mailto:john@example.com)
* Named email: John Doe ``
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.google_calendar_toolkit
## GoogleCalendarToolkit
```python theme={"system"}
class GoogleCalendarToolkit(BaseToolkit):
```
A class representing a toolkit for Google Calendar operations.
This class provides methods for creating events, retrieving events,
updating events, and deleting events from a Google Calendar.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes a new instance of the GoogleCalendarToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
**Note:**
Before using this toolkit, make sure to:
1. Set the required environment variables: GOOGLE\_CLIENT\_ID and
GOOGLE\_CLIENT\_SECRET
2. Configure the redirect URI in Google Cloud Console to
[http://localhost/](http://localhost/)
### create\_event
```python theme={"system"}
def create_event(
self,
event_title: str,
start_time: str,
end_time: str,
description: str = '',
location: str = '',
attendees_email: Optional[List[str]] = None,
timezone: str = 'UTC'
):
```
Creates an event in the user's primary Google Calendar.
**Parameters:**
* **event\_title** (str): Title of the event.
* **start\_time** (str): Start time in ISO format (YYYY-MM-DDTHH:MM:SS).
* **end\_time** (str): End time in ISO format (YYYY-MM-DDTHH:MM:SS).
* **description** (str, optional): Description of the event.
* **location** (str, optional): Location of the event.
* **attendees\_email** (List\[str], optional): List of email addresses. (default: :obj:`None`)
* **timezone** (str, optional): Timezone for the event. (default: :obj:`UTC`)
**Returns:**
dict: A dictionary containing details of the created event.
### get\_events
```python theme={"system"}
def get_events(self, max_results: int = 10, time_min: Optional[str] = None):
```
Retrieves upcoming events from the user's primary Google Calendar.
**Parameters:**
* **max\_results** (int, optional): Maximum number of events to retrieve. (default: :obj:`10`)
* **time\_min** (str, optional): The minimum time to fetch events from. If not provided, defaults to the current time. (default: :obj:`None`)
**Returns:**
Union\[List\[Dict\[str, Any]], Dict\[str, Any]]: A list of
dictionaries, each containing details of an event, or a
dictionary with an error message.
### update\_event
```python theme={"system"}
def update_event(
self,
event_id: str,
event_title: Optional[str] = None,
start_time: Optional[str] = None,
end_time: Optional[str] = None,
description: Optional[str] = None,
location: Optional[str] = None,
attendees_email: Optional[List[str]] = None
):
```
Updates an existing event in the user's primary Google Calendar.
**Parameters:**
* **event\_id** (str): The ID of the event to update.
* **event\_title** (Optional\[str]): New title of the event. (default: :obj:`None`)
* **start\_time** (Optional\[str]): New start time in ISO format (YYYY-MM-DDTHH:MM:SSZ). (default: :obj:`None`)
* **end\_time** (Optional\[str]): New end time in ISO format (YYYY-MM-DDTHH:MM:SSZ). (default: :obj:`None`)
* **description** (Optional\[str]): New description of the event. (default: :obj:`None`)
* **location** (Optional\[str]): New location of the event. (default: :obj:`None`)
* **attendees\_email** (Optional\[List\[str]]): List of email addresses. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: A dictionary containing details of the updated
event.
### delete\_event
```python theme={"system"}
def delete_event(self, event_id: str):
```
Deletes an event from the user's primary Google Calendar.
**Parameters:**
* **event\_id** (str): The ID of the event to delete.
**Returns:**
str: A message indicating the result of the deletion.
### get\_calendar\_details
```python theme={"system"}
def get_calendar_details(self):
```
**Returns:**
dict: A dictionary containing details about the calendar.
### \_get\_calendar\_service
```python theme={"system"}
def _get_calendar_service(self):
```
**Returns:**
Resource: A Google Calendar API service object.
### \_authenticate
```python theme={"system"}
def _authenticate(self):
```
**Returns:**
Credentials: A Google OAuth2 credentials object.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.google_drive_mcp_toolkit
## GoogleDriveMCPToolkit
```python theme={"system"}
class GoogleDriveMCPToolkit(MCPToolkit):
```
GoogleDriveMCPToolkit provides an interface for interacting with
Google Drive using the Google Drive MCP server.
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
credentials_path: Optional[str] = None
):
```
Initializes the GoogleDriveMCPToolkit.
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
* **credentials\_path** (Optional\[str]): Path to the Google Drive credentials file. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.google_maps_toolkit
## handle\_googlemaps\_exceptions
```python theme={"system"}
def handle_googlemaps_exceptions(func: Callable[..., Any]):
```
Decorator to catch and handle exceptions raised by Google Maps API
calls.
**Parameters:**
* **func** (Callable): The function to be wrapped by the decorator.
**Returns:**
Callable: A wrapper function that calls the wrapped function and
handles exceptions.
## \_format\_offset\_to\_natural\_language
```python theme={"system"}
def _format_offset_to_natural_language(offset: int):
```
Converts a time offset in seconds to a more natural language
description using hours as the unit, with decimal places to represent
minutes and seconds.
**Parameters:**
* **offset** (int): The time offset in seconds. Can be positive, negative, or zero.
**Returns:**
str: A string representing the offset in hours, such as
"+2.50 hours" or "-3.75 hours".
## GoogleMapsToolkit
```python theme={"system"}
class GoogleMapsToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with GoogleMaps API.
This class provides methods for validating addresses, retrieving elevation,
and fetching timezone information using the Google Maps API.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
### get\_address\_description
```python theme={"system"}
def get_address_description(
self,
address: Union[str, List[str]],
region_code: Optional[str] = None,
locality: Optional[str] = None
):
```
Validates an address via Google Maps API, returns a descriptive
summary. Validates an address using Google Maps API, returning a
summary that includes information on address completion, formatted
address, location coordinates, and metadata types that are true for
the given address.
**Parameters:**
* **address** (Union\[str, List\[str]]): The address or components to validate. Can be a single string or a list representing different parts.
* **region\_code** (str, optional): Country code for regional restriction, helps narrow down results. (default: :obj:`None`)
* **locality** (str, optional): Restricts validation to a specific locality, e.g., "Mountain View". (default: :obj:`None`)
**Returns:**
str: Summary of the address validation results, including
information on address completion, formatted address,
geographical coordinates (latitude and longitude), and metadata
types true for the address.
### get\_elevation
```python theme={"system"}
def get_elevation(self, lat: float, lng: float):
```
Retrieves elevation data for a given latitude and longitude.
Uses the Google Maps API to fetch elevation data for the specified
latitude and longitude. It handles exceptions gracefully and returns a
description of the elevation, including its value in meters and the
data resolution.
**Parameters:**
* **lat** (float): The latitude of the location to query.
* **lng** (float): The longitude of the location to query.
**Returns:**
str: A description of the elevation at the specified location(s),
including the elevation in meters and the data resolution. If
elevation data is not available, a message indicating this is
returned.
### get\_timezone
```python theme={"system"}
def get_timezone(self, lat: float, lng: float):
```
Retrieves timezone information for a given latitude and longitude.
This function uses the Google Maps Timezone API to fetch timezone
data for the specified latitude and longitude. It returns a natural
language description of the timezone, including the timezone ID, name,
standard time offset, daylight saving time offset, and the total
offset from Coordinated Universal Time (UTC).
**Parameters:**
* **lat** (float): The latitude of the location to query.
* **lng** (float): The longitude of the location to query.
**Returns:**
str: A descriptive string of the timezone information,
including the timezone ID and name, standard time offset,
daylight saving time offset, and total offset from UTC.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.google_scholar_toolkit
## GoogleScholarToolkit
```python theme={"system"}
class GoogleScholarToolkit(BaseToolkit):
```
A toolkit for retrieving information about authors and their
publications from Google Scholar.
**Parameters:**
* **author\_identifier** (Union\[str, None]): The author's Google Scholar URL or name of the author to search for.
* **is\_author\_name** (bool): Flag to indicate if the identifier is a name. (default: :obj:`False`)
* **scholarly** (module): The scholarly module for querying Google Scholar.
* **author** (Optional\[Dict\[str, Any]]): Cached author details, allowing manual assignment if desired.
### **init**
```python theme={"system"}
def __init__(
self,
author_identifier: str,
is_author_name: bool = False,
use_free_proxies: bool = False,
proxy_http: Optional[str] = None,
proxy_https: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initializes the GoogleScholarToolkit with the author's identifier.
**Parameters:**
* **author\_identifier** (str): The author's Google Scholar URL or name of the author to search for.
* **is\_author\_name** (bool): Flag to indicate if the identifier is a name. (default: :obj:`False`)
* **use\_free\_proxies** (bool): Whether to use Free Proxies. (default: :obj:`False`)
* **proxy\_http** (Optional\[str]): Proxy http address pass to pg. SingleProxy. (default: :obj:`None`)
* **proxy\_https** (Optional\[str]): Proxy https address pass to pg. SingleProxy. (default: :obj:`None`)
### author
```python theme={"system"}
def author(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing author details. If no data
is available, returns an empty dictionary.
### author
```python theme={"system"}
def author(self, value: Optional[Dict[str, Any]]):
```
Sets or overrides the cached author information.
**Parameters:**
* **value** (Optional\[Dict\[str, Any]]): A dictionary containing author details to cache or `None` to clear the cached data.
### \_extract\_author\_id
```python theme={"system"}
def _extract_author_id(self):
```
**Returns:**
Optional\[str]: The extracted author ID, or None if not found.
### get\_author\_detailed\_info
```python theme={"system"}
def get_author_detailed_info(self):
```
**Returns:**
dict: A dictionary containing detailed information about the
author.
### get\_author\_publications
```python theme={"system"}
def get_author_publications(self):
```
**Returns:**
List\[str]: A list of publication titles authored by the author.
### get\_publication\_by\_title
```python theme={"system"}
def get_publication_by_title(self, publication_title: str):
```
Retrieves detailed information about a specific publication by its
title. Note that this method cannot retrieve the full content of the
paper.
**Parameters:**
* **publication\_title** (str): The title of the publication to search for.
**Returns:**
Optional\[dict]: A dictionary containing detailed information about
the publication if found; otherwise, `None`.
### get\_full\_paper\_content\_by\_link
```python theme={"system"}
def get_full_paper_content_by_link(self, pdf_url: str):
```
Retrieves the full paper content from a given PDF URL using the
arxiv2text tool.
**Parameters:**
* **pdf\_url** (str): The URL of the PDF file.
**Returns:**
Optional\[str]: The full text extracted from the PDF, or `None` if
an error occurs.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.human_toolkit
## HumanToolkit
```python theme={"system"}
class HumanToolkit(BaseToolkit):
```
A class representing a toolkit for human interaction.
**Note:**
This toolkit should be called to send a tidy message to the user to
keep them informed.
### ask\_human\_via\_console
```python theme={"system"}
def ask_human_via_console(self, question: str):
```
Use this tool to ask a question to the user when you are stuck,
need clarification, or require a decision to be made. This is a
two-way communication channel that will wait for the user's response.
You should use it to:
* Clarify ambiguous instructions or requirements.
* Request missing information that you cannot find (e.g., login
credentials, file paths).
* Ask for a decision when there are multiple viable options.
* Seek help when you encounter an error you cannot resolve on your own.
**Parameters:**
* **question** (str): The question to ask the user.
**Returns:**
str: The user's response to the question.
### send\_message\_to\_user
```python theme={"system"}
def send_message_to_user(self, message: str):
```
Use this tool to send a tidy message to the user in one short
sentence.
This one-way tool keeps the user informed about your progress,
decisions, or actions. It does not require a response.
You should use it to:
* Announce what you are about to do (e.g., "I will now search for
papers on GUI Agents.").
* Report the result of an action (e.g., "I have found 15 relevant
papers.").
* State a decision (e.g., "I will now analyze the top 10 papers.").
* Give a status update during a long-running task.
**Parameters:**
* **message** (str): The tidy and informative message for the user.
**Returns:**
str: Confirmation that the message was successfully sent.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.actions
## ActionExecutor
```python theme={"system"}
class ActionExecutor:
```
Executes high-level actions (click, type …) on a Playwright Page.
### **init**
```python theme={"system"}
def __init__(
self,
page: 'Page',
session: Optional[Any] = None,
default_timeout: Optional[int] = None,
short_timeout: Optional[int] = None,
max_scroll_amount: Optional[int] = None
):
```
### should\_update\_snapshot
```python theme={"system"}
def should_update_snapshot(action: Dict[str, Any]):
```
Determine if an action requires a snapshot update.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.agent
## PlaywrightLLMAgent
```python theme={"system"}
class PlaywrightLLMAgent:
```
High-level orchestration: snapshot ↔ LLM ↔ action executor.
### **init**
```python theme={"system"}
def __init__(self):
```
### \_get\_chat\_agent
```python theme={"system"}
def _get_chat_agent(self):
```
Get or create the ChatAgent instance.
### \_safe\_parse\_json
```python theme={"system"}
def _safe_parse_json(self, content: str):
```
Safely parse JSON from LLM response with multiple fallback
strategies.
### \_get\_fallback\_response
```python theme={"system"}
def _get_fallback_response(self, error_msg: str):
```
Generate a fallback response structure.
### \_llm\_call
```python theme={"system"}
def _llm_call(
self,
prompt: str,
snapshot: str,
is_initial: bool,
history: Optional[List[Dict[str, Any]]] = None
):
```
Call the LLM (via CAMEL ChatAgent) to get plan & next action.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.browser_session
## TabIdGenerator
```python theme={"system"}
class TabIdGenerator:
```
Monotonically increasing tab ID generator.
## HybridBrowserSession
```python theme={"system"}
class HybridBrowserSession:
```
Lightweight wrapper around Playwright for
browsing with multi-tab support.
It provides multiple *Page* instances plus helper utilities (snapshot &
executor). Multiple toolkits or agents can reuse this class without
duplicating Playwright setup code.
This class is a singleton per event-loop and session-id combination.
### **new**
```python theme={"system"}
def __new__(cls):
```
### **init**
```python theme={"system"}
def __init__(self):
```
### \_load\_stealth\_script
```python theme={"system"}
def _load_stealth_script(self):
```
Load the stealth JavaScript script from file.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.config_loader
## BrowserConfig
```python theme={"system"}
class BrowserConfig:
```
Browser configuration settings.
## ToolkitConfig
```python theme={"system"}
class ToolkitConfig:
```
Toolkit-specific configuration.
## ConfigLoader
```python theme={"system"}
class ConfigLoader:
```
Configuration loader for HybridBrowserToolkit.
### **init**
```python theme={"system"}
def __init__(
self,
browser_config: Optional[BrowserConfig] = None,
toolkit_config: Optional[ToolkitConfig] = None
):
```
### from\_kwargs
```python theme={"system"}
def from_kwargs(cls, **kwargs):
```
Create ConfigLoader from keyword arguments.
### get\_browser\_config
```python theme={"system"}
def get_browser_config(self):
```
Get browser configuration.
### get\_toolkit\_config
```python theme={"system"}
def get_toolkit_config(self):
```
Get toolkit configuration.
### to\_ws\_config
```python theme={"system"}
def to_ws_config(self):
```
Convert to WebSocket wrapper configuration format.
### get\_timeout\_config
```python theme={"system"}
def get_timeout_config(self):
```
Get all timeout configurations.
### update\_browser\_config
```python theme={"system"}
def update_browser_config(self, **kwargs):
```
Update browser configuration.
### update\_toolkit\_config
```python theme={"system"}
def update_toolkit_config(self, **kwargs):
```
Update toolkit configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.hybrid_browser_toolkit
## HybridBrowserToolkit
```python theme={"system"}
class HybridBrowserToolkit(BaseToolkit):
```
A hybrid browser toolkit that can switch between TypeScript and Python
implementations.
This wrapper allows users to choose between:
* 'typescript': WebSocket-based implementation using TypeScript/Node.js
* 'python': Pure Python implementation using Playwright directly
**Parameters:**
* **mode** (`Literal["typescript", "python"]`): Implementation mode. - 'typescript': Uses WebSocket-based TypeScript implementation - 'python': Uses pure Python Playwright implementation. Defaults to "typescript".
* **headless** (bool): Whether to run browser in headless mode. Defaults to True.
* **user\_data\_dir** (Optional\[str]): Directory for user data persistence. Defaults to None.
* **stealth** (bool): Whether to enable stealth mode. Defaults to False.
* **cache\_dir** (str): Directory for caching. Defaults to "tmp/". (default: `"tmp/"`)
* **enabled\_tools** (Optional\[List\[str]]): List of enabled tools. Defaults to None.
* **browser\_log\_to\_file** (bool): Whether to log browser actions to file. Defaults to False.
* **log\_dir** (Optional\[str]): Custom directory path for log files. If None, defaults to "browser\_log". Defaults to None.
* **session\_id** (Optional\[str]): Session identifier. Defaults to None.
* **default\_start\_url** (str): Default URL to start with. Defaults to "[https://google.com/](https://google.com/)".
* **default\_timeout** (Optional\[int]): Default timeout in milliseconds. Defaults to None.
* **short\_timeout** (Optional\[int]): Short timeout in milliseconds. Defaults to None.
* **navigation\_timeout** (Optional\[int]): Navigation timeout in milliseconds. Defaults to None.
* **network\_idle\_timeout** (Optional\[int]): Network idle timeout in milliseconds. Defaults to None.
* **screenshot\_timeout** (Optional\[int]): Screenshot timeout in milliseconds. Defaults to None.
* **page\_stability\_timeout** (Optional\[int]): Page stability timeout in milliseconds. Defaults to None.
* **dom\_content\_loaded\_timeout** (Optional\[int]): DOM content loaded timeout in milliseconds. Defaults to None.
* **viewport\_limit** (bool): Whether to filter page snapshot elements to only those visible in the current viewport. Defaults to False.
* **connect\_over\_cdp** (bool): Whether to connect to an existing browser via Chrome DevTools Protocol. Defaults to False. (Only supported in TypeScript mode)
* **cdp\_url** (Optional\[str]): WebSocket endpoint URL for CDP connection. Required when connect\_over\_cdp is True. Defaults to None. (Only supported in TypeScript mode)
* **cdp\_keep\_current\_page** (bool): When True and using CDP mode, won't create new pages but use the existing one. Defaults to False. (Only supported in TypeScript mode)
* **full\_visual\_mode** (bool): When True, browser actions like click, browser\_open, visit\_page, etc. will return 'full visual mode' as snapshot instead of actual page content. The browser\_get\_page\_snapshot method will still return the actual snapshot. Defaults to False. \*\*kwargs: Additional keyword arguments passed to the implementation.
### **new**
```python theme={"system"}
def __new__(cls, **kwargs: Any):
```
Create a HybridBrowserToolkit instance with the specified mode.
**Parameters:**
* **mode** (`Literal["typescript", "python"]`): Implementation mode. - 'typescript': Uses WebSocket-based TypeScript implementation - 'python': Uses pure Python Playwright implementation Defaults to "typescript".
* **headless** (bool): Whether to run browser in headless mode. Defaults to True.
* **user\_data\_dir** (Optional\[str]): Directory for user data persistence. Defaults to None.
* **stealth** (bool): Whether to enable stealth mode. Defaults to False.
* **cache\_dir** (str): Directory for caching. Defaults to "tmp/". (default: `"tmp/"`)
* **enabled\_tools** (Optional\[List\[str]]): List of enabled tools. Defaults to None.
* **browser\_log\_to\_file** (bool): Whether to log browser actions to file. Defaults to False.
* **log\_dir** (Optional\[str]): Custom directory path for log files. If None, defaults to "browser\_log". Defaults to None.
* **session\_id** (Optional\[str]): Session identifier. Defaults to None.
* **default\_start\_url** (str): Default URL to start with. Defaults to "[https://google.com/](https://google.com/)".
* **default\_timeout** (Optional\[int]): Default timeout in milliseconds. Defaults to None.
* **short\_timeout** (Optional\[int]): Short timeout in milliseconds. Defaults to None.
* **navigation\_timeout** (Optional\[int]): Navigation timeout in milliseconds. Defaults to None.
* **network\_idle\_timeout** (Optional\[int]): Network idle timeout in milliseconds. Defaults to None.
* **screenshot\_timeout** (Optional\[int]): Screenshot timeout in milliseconds. Defaults to None.
* **page\_stability\_timeout** (Optional\[int]): Page stability timeout in milliseconds. Defaults to None.
* **dom\_content\_loaded\_timeout** (Optional\[int]): DOM content loaded timeout in milliseconds. Defaults to None.
* **viewport\_limit** (bool): Whether to filter page snapshot elements to only those visible in the current viewport. Defaults to False.
* **connect\_over\_cdp** (bool): Whether to connect to an existing browser via Chrome DevTools Protocol. Defaults to False. (Only supported in TypeScript mode)
* **cdp\_url** (Optional\[str]): WebSocket endpoint URL for CDP connection. Required when connect\_over\_cdp is True. Defaults to None. (Only supported in TypeScript mode)
* **cdp\_keep\_current\_page** (bool): When True and using CDP mode, won't create new pages but use the existing one. Defaults to False. (Only supported in TypeScript mode)
* **full\_visual\_mode** (bool): When True, browser actions like click, browser\_open, visit\_page, etc. will return 'full visual mode' as snapshot instead of actual page content. The browser\_get\_page\_snapshot method will still return the actual snapshot. Defaults to False. \*\*kwargs: Additional keyword arguments passed to the implementation.
**Returns:**
HybridBrowserToolkit instance of the specified implementation.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.hybrid_browser_toolkit_ts
## \_add\_rulers\_to\_image
```python theme={"system"}
def _add_rulers_to_image(image_bytes: bytes, tick_interval: int = 100):
```
Add rulers with tick marks to an image (like a real measuring ruler).
Adds horizontal ruler at the top and vertical ruler on the left side,
with multi-level tick marks like a real ruler:
* Every 100 pixels: longest tick + number label
* Every 50 pixels: long tick (no label)
* Every 10 pixels: medium tick
* Every 5 pixels: short tick
**Parameters:**
* **image\_bytes**: The original image as bytes.
* **tick\_interval**: Major interval for number labels (default: 100). (default: 100)
**Returns:**
The modified image with rulers as bytes.
## SheetCell
```python theme={"system"}
class SheetCell(TypedDict):
```
Type definition for a sheet cell input.
## HybridBrowserToolkit
```python theme={"system"}
class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
```
A hybrid browser toolkit that combines non-visual, DOM-based browser
automation with visual, screenshot-based capabilities.
This toolkit now uses TypeScript implementation with Playwright's
\_snapshotForAI functionality for enhanced AI integration.
### **init**
```python theme={"system"}
def __init__(self):
```
Initialize the HybridBrowserToolkit.
**Parameters:**
* **headless** (bool): Whether to run browser in headless mode. Defaults to True.
* **user\_data\_dir** (Optional\[str]): Directory for user data persistence. Defaults to None.
* **stealth** (bool): Whether to enable stealth mode. Defaults to False.
* **cache\_dir** (str): Directory for caching. Defaults to "tmp/". (default: `"tmp/"`)
* **enabled\_tools** (Optional\[List\[str]]): List of enabled tools. Defaults to None.
* **browser\_log\_to\_file** (bool): Whether to log browser actions to file. Defaults to False.
* **log\_dir** (Optional\[str]): Custom directory path for log files. If None, defaults to "browser\_log". Defaults to None.
* **session\_id** (Optional\[str]): Session identifier. Defaults to None.
* **default\_start\_url** (str): Default URL to start with. Defaults to "[https://google.com/](https://google.com/)".
* **default\_timeout** (Optional\[int]): Default timeout in milliseconds. Defaults to None.
* **short\_timeout** (Optional\[int]): Short timeout in milliseconds. Defaults to None.
* **navigation\_timeout** (Optional\[int]): Navigation timeout in milliseconds. Defaults to None.
* **network\_idle\_timeout** (Optional\[int]): Network idle timeout in milliseconds. Defaults to None.
* **screenshot\_timeout** (Optional\[int]): Screenshot timeout in milliseconds. Defaults to None.
* **page\_stability\_timeout** (Optional\[int]): Page stability timeout in milliseconds. Defaults to None.
* **dom\_content\_loaded\_timeout** (Optional\[int]): DOM content loaded timeout in milliseconds. Defaults to None.
* **download\_timeout** (Optional\[int]): Download timeout in milliseconds. Defaults to None.
* **viewport\_limit** (bool): Whether to filter page snapshot elements to only those visible in the current viewport. When True, only elements within the current viewport bounds will be included in snapshots. When False (default), all elements on the page are included. Defaults to False.
* **connect\_over\_cdp** (bool): Whether to connect to an existing browser via Chrome DevTools Protocol. Defaults to False.
* **cdp\_url** (Optional\[str]): WebSocket endpoint URL for CDP connection (e.g., 'ws\://localhost:9222/devtools/browser/...'). Required when connect\_over\_cdp is True. Defaults to None.
* **cdp\_keep\_current\_page** (bool): When True and using CDP mode, won't create new pages but use the existing one. Defaults to False.
* **full\_visual\_mode** (bool): When True, browser actions like click, browser\_open, visit\_page, etc. will not return snapshots. Defaults to False.
* **download\_dir** (Optional\[str]): Directory path where downloaded files will be saved when using browser\_download\_file tool. Defaults to None.
### **del**
```python theme={"system"}
def __del__(self):
```
Cleanup browser resources on garbage collection.
### cache\_dir
```python theme={"system"}
def cache_dir(self):
```
Get the cache directory.
### \_build\_error\_response
```python theme={"system"}
def _build_error_response(self, error_message: str, include_note: bool = True):
```
Build a standardized error response.
**Parameters:**
* **error\_message**: The error message to include.
* **include\_note**: Whether to include the note field.
**Returns:**
A standardized error response dictionary.
### \_trim\_sheet\_content
```python theme={"system"}
def _trim_sheet_content(self, content: str):
```
Trim sheet content and add row/column labels.
Remove all empty rows and columns, then add:
* Column headers: A, B, C, D...
* Row numbers: 0, 1, 2, 3...
**Parameters:**
* **content** (str): Raw sheet content with tabs and newlines.
**Returns:**
str: Trimmed content with row/column labels.
### clone\_for\_new\_session
```python theme={"system"}
def clone_for_new_session(self, new_session_id: Optional[str] = None):
```
Create a new instance of HybridBrowserToolkit with a unique
session.
**Parameters:**
* **new\_session\_id**: Optional new session ID. If None, a UUID will be generated.
**Returns:**
A new HybridBrowserToolkit instance with the same configuration
but a different session.
### \_create\_mode\_wrapper
```python theme={"system"}
def _create_mode_wrapper(
self,
method: Callable[..., Any],
tool_name: str,
pixel_mode: bool
):
```
Create a wrapper with mode-specific signature and docstring.
**Parameters:**
* **method**: The original method to wrap.
* **tool\_name**: Name of the tool.
* **pixel\_mode**: If True, create pixel-coordinate wrapper. If False, create ref-based wrapper.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Get available function tools based on enabled\_tools configuration.
In full\_visual\_mode:
* Tools requiring ref with no pixel alternative are excluded
* browser\_click and browser\_type use pixel coordinates instead of ref
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.installer
## find\_command
```python theme={"system"}
def find_command(
cmd_base: str,
windows_variants: Optional[list] = None,
unix_variant: Optional[str] = None
):
```
Find command across platforms.
## create\_command\_not\_found\_error
```python theme={"system"}
def create_command_not_found_error(command: str, error: Optional[Exception] = None):
```
## create\_npm\_command\_error
```python theme={"system"}
def create_npm_command_error(command: str, error: Exception):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.snapshot
## PageSnapshot
```python theme={"system"}
class PageSnapshot:
```
Utility for capturing YAML-like page snapshots and diff-only
variants.
### **init**
```python theme={"system"}
def __init__(self, page: 'Page'):
```
### \_format\_snapshot
```python theme={"system"}
def _format_snapshot(text: str):
```
### \_compute\_diff
```python theme={"system"}
def _compute_diff(old: str, new: str):
```
### \_detect\_priorities
```python theme={"system"}
def _detect_priorities(self, snapshot_yaml: str):
```
Return sorted list of priorities present (1,2,3).
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.stealth_config
Stealth configuration for browser automation to avoid bot detection.
This module contains all the configuration needed to make the browser
appear as a regular user browser rather than an automated one.
## StealthConfig
```python theme={"system"}
class StealthConfig:
```
Configuration class for stealth browser settings.
### get\_launch\_args
```python theme={"system"}
def get_launch_args():
```
**Returns:**
List\[str]: Chrome command line arguments to avoid detection.
### get\_context\_options
```python theme={"system"}
def get_context_options():
```
**Returns:**
Dict\[str, Any]: Browser context configuration options.
### get\_http\_headers
```python theme={"system"}
def get_http_headers():
```
**Returns:**
Dict\[str, str]: HTTP headers to appear more like a real browser.
### get\_all\_config
```python theme={"system"}
def get_all_config():
```
**Returns:**
Dict\[str, Any]: Complete stealth configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit.ws_wrapper
## \_create\_memory\_aware\_error
```python theme={"system"}
def _create_memory_aware_error(base_msg: str):
```
## action\_logger
```python theme={"system"}
def action_logger(func):
```
Decorator to add logging to action methods.
Skips logging if already inside a high-level action to avoid
logging internal calls.
## high\_level\_action
```python theme={"system"}
def high_level_action(func):
```
Decorator for high-level actions that should suppress low-level logging.
When a function is decorated with this, all low-level action\_logger
decorated functions called within it will skip logging. This decorator
itself will log the high-level action.
## WebSocketBrowserWrapper
```python theme={"system"}
class WebSocketBrowserWrapper:
```
Python wrapper for the TypeScript hybrid browser
toolkit implementation using WebSocket.
### **init**
```python theme={"system"}
def __init__(self, config: Optional[Dict[str, Any]] = None):
```
Initialize the wrapper.
**Parameters:**
* **config**: Configuration dictionary for the browser toolkit
### \_ensure\_ref\_prefix
```python theme={"system"}
def _ensure_ref_prefix(self, ref: str):
```
Ensure ref has proper prefix
### \_process\_refs\_in\_params
```python theme={"system"}
def _process_refs_in_params(self, params: Dict[str, Any]):
```
Process parameters to ensure all refs have 'e' prefix.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit_py.actions
## ActionExecutor
```python theme={"system"}
class ActionExecutor:
```
Executes high-level actions (click, type …) on a Playwright Page.
### **init**
```python theme={"system"}
def __init__(
self,
page: 'Page',
session: Optional[Any] = None,
default_timeout: Optional[int] = None,
short_timeout: Optional[int] = None,
max_scroll_amount: Optional[int] = None
):
```
### \_valid\_coordinates
```python theme={"system"}
def _valid_coordinates(self, x_coord: float, y_coord: float):
```
Validate given coordinates against viewport bounds.
### should\_update\_snapshot
```python theme={"system"}
def should_update_snapshot(action: Dict[str, Any]):
```
Determine if an action requires a snapshot update.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit_py.agent
## PlaywrightLLMAgent
```python theme={"system"}
class PlaywrightLLMAgent:
```
High-level orchestration: snapshot ↔ LLM ↔ action executor.
### **init**
```python theme={"system"}
def __init__(self):
```
### \_get\_chat\_agent
```python theme={"system"}
def _get_chat_agent(self):
```
Get or create the ChatAgent instance.
### \_safe\_parse\_json
```python theme={"system"}
def _safe_parse_json(self, content: str):
```
Safely parse JSON from LLM response with multiple fallback
strategies.
### \_get\_fallback\_response
```python theme={"system"}
def _get_fallback_response(self, error_msg: str):
```
Generate a fallback response structure.
### \_llm\_call
```python theme={"system"}
def _llm_call(
self,
prompt: str,
snapshot: str,
is_initial: bool,
history: Optional[List[Dict[str, Any]]] = None
):
```
Call the LLM (via CAMEL ChatAgent) to get plan & next action.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit_py.browser_session
## TabIdGenerator
```python theme={"system"}
class TabIdGenerator:
```
Monotonically increasing tab ID generator.
## HybridBrowserSession
```python theme={"system"}
class HybridBrowserSession:
```
Lightweight wrapper around Playwright for
browsing with multi-tab support.
It provides multiple *Page* instances plus helper utilities (snapshot &
executor). Multiple toolkits or agents can reuse this class without
duplicating Playwright setup code.
This class is a singleton per event-loop and session-id combination.
### **new**
```python theme={"system"}
def __new__(cls):
```
### **init**
```python theme={"system"}
def __init__(self):
```
### \_load\_stealth\_script
```python theme={"system"}
def _load_stealth_script(self):
```
Load the stealth JavaScript script from file.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit_py.config_loader
Configuration for browser automation including stealth mode and timeouts.
This module contains all the configuration needed to make the browser
appear as a regular user browser and configure action timeouts.
## BrowserConfig
```python theme={"system"}
class BrowserConfig:
```
Configuration class for browser settings including stealth mode and
timeouts.
### get\_timeout\_config
```python theme={"system"}
def get_timeout_config():
```
**Returns:**
Dict\[str, int]: Timeout configuration in milliseconds.
### get\_action\_limits
```python theme={"system"}
def get_action_limits():
```
**Returns:**
Dict\[str, int]: Action limits configuration.
### get\_log\_limits
```python theme={"system"}
def get_log_limits():
```
**Returns:**
Dict\[str, int]: Console Log limits configuration.
### get\_action\_timeout
```python theme={"system"}
def get_action_timeout(override: Optional[int] = None):
```
Get action timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_short\_timeout
```python theme={"system"}
def get_short_timeout(override: Optional[int] = None):
```
Get short timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_navigation\_timeout
```python theme={"system"}
def get_navigation_timeout(override: Optional[int] = None):
```
Get navigation timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_network\_idle\_timeout
```python theme={"system"}
def get_network_idle_timeout(override: Optional[int] = None):
```
Get network idle timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_max\_scroll\_amount
```python theme={"system"}
def get_max_scroll_amount(override: Optional[int] = None):
```
Get maximum scroll amount with optional override.
**Parameters:**
* **override**: Optional scroll amount override value in pixels.
**Returns:**
int: Maximum scroll amount in pixels.
### get\_max\_log\_limit
```python theme={"system"}
def get_max_log_limit(override: Optional[int] = None):
```
Get maximum log limit with optional override.
**Parameters:**
* **override**: Optional log limit override value.
**Returns:**
int: Maximum log limit.
### get\_screenshot\_timeout
```python theme={"system"}
def get_screenshot_timeout(override: Optional[int] = None):
```
Get screenshot timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_page\_stability\_timeout
```python theme={"system"}
def get_page_stability_timeout(override: Optional[int] = None):
```
Get page stability timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_dom\_content\_loaded\_timeout
```python theme={"system"}
def get_dom_content_loaded_timeout(override: Optional[int] = None):
```
Get DOM content loaded timeout with optional override.
**Parameters:**
* **override**: Optional timeout override value in milliseconds.
**Returns:**
int: Timeout value in milliseconds.
### get\_launch\_args
```python theme={"system"}
def get_launch_args():
```
**Returns:**
List\[str]: Chrome command line arguments to avoid detection.
### get\_context\_options
```python theme={"system"}
def get_context_options():
```
**Returns:**
Dict\[str, Any]: Browser context configuration options.
### get\_http\_headers
```python theme={"system"}
def get_http_headers():
```
**Returns:**
Dict\[str, str]: HTTP headers to appear more like a real browser.
### get\_stealth\_config
```python theme={"system"}
def get_stealth_config():
```
**Returns:**
Dict\[str, Any]: Complete stealth configuration.
### get\_all\_config
```python theme={"system"}
def get_all_config():
```
**Returns:**
Dict\[str, Any]: Complete browser configuration.
## ConfigLoader
```python theme={"system"}
class ConfigLoader:
```
Legacy wrapper for BrowserConfig - maintained for backward
compatibility.
### get\_browser\_config
```python theme={"system"}
def get_browser_config(cls):
```
Get the BrowserConfig class.
### get\_stealth\_config
```python theme={"system"}
def get_stealth_config(cls):
```
Get the StealthConfig class (alias).
### get\_timeout\_config
```python theme={"system"}
def get_timeout_config(cls):
```
Get timeout configuration.
### get\_action\_timeout
```python theme={"system"}
def get_action_timeout(cls, override: Optional[int] = None):
```
Get action timeout with optional override.
### get\_short\_timeout
```python theme={"system"}
def get_short_timeout(cls, override: Optional[int] = None):
```
Get short timeout with optional override.
### get\_navigation\_timeout
```python theme={"system"}
def get_navigation_timeout(cls, override: Optional[int] = None):
```
Get navigation timeout with optional override.
### get\_network\_idle\_timeout
```python theme={"system"}
def get_network_idle_timeout(cls, override: Optional[int] = None):
```
Get network idle timeout with optional override.
### get\_max\_scroll\_amount
```python theme={"system"}
def get_max_scroll_amount(cls, override: Optional[int] = None):
```
Get maximum scroll amount with optional override.
### get\_max\_log\_limit
```python theme={"system"}
def get_max_log_limit(cls, override: Optional[int] = None):
```
Get maximum log limit with optional override.
### get\_screenshot\_timeout
```python theme={"system"}
def get_screenshot_timeout(cls, override: Optional[int] = None):
```
Get screenshot timeout with optional override.
### get\_page\_stability\_timeout
```python theme={"system"}
def get_page_stability_timeout(cls, override: Optional[int] = None):
```
Get page stability timeout with optional override.
### get\_dom\_content\_loaded\_timeout
```python theme={"system"}
def get_dom_content_loaded_timeout(cls, override: Optional[int] = None):
```
Get DOM content loaded timeout with optional override.
## get\_browser\_config
```python theme={"system"}
def get_browser_config():
```
Get BrowserConfig class.
## get\_stealth\_config
```python theme={"system"}
def get_stealth_config():
```
Get StealthConfig class.
## get\_timeout\_config
```python theme={"system"}
def get_timeout_config():
```
Get timeout configuration.
## get\_action\_timeout
```python theme={"system"}
def get_action_timeout(override: Optional[int] = None):
```
Get action timeout with optional override.
## get\_short\_timeout
```python theme={"system"}
def get_short_timeout(override: Optional[int] = None):
```
Get short timeout with optional override.
## get\_navigation\_timeout
```python theme={"system"}
def get_navigation_timeout(override: Optional[int] = None):
```
Get navigation timeout with optional override.
## get\_network\_idle\_timeout
```python theme={"system"}
def get_network_idle_timeout(override: Optional[int] = None):
```
Get network idle timeout with optional override.
## get\_max\_scroll\_amount
```python theme={"system"}
def get_max_scroll_amount(override: Optional[int] = None):
```
Get maximum scroll amount with optional override.
## get\_max\_log\_limit
```python theme={"system"}
def get_max_log_limit(override: Optional[int] = None):
```
Get maximum log limit with optional override.
## get\_screenshot\_timeout
```python theme={"system"}
def get_screenshot_timeout(override: Optional[int] = None):
```
Get screenshot timeout with optional override.
## get\_page\_stability\_timeout
```python theme={"system"}
def get_page_stability_timeout(override: Optional[int] = None):
```
Get page stability timeout with optional override.
## get\_dom\_content\_loaded\_timeout
```python theme={"system"}
def get_dom_content_loaded_timeout(override: Optional[int] = None):
```
Get DOM content loaded timeout with optional override.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit_py.hybrid_browser_toolkit
## HybridBrowserToolkit
```python theme={"system"}
class HybridBrowserToolkit(BaseToolkit, RegisteredAgentToolkit):
```
A hybrid browser toolkit that combines non-visual, DOM-based browser
automation with visual, screenshot-based capabilities.
This toolkit exposes a set of actions as CAMEL FunctionTools for agents
to interact with web pages. It can operate in headless mode and supports
both programmatic control of browser actions (like clicking and typing)
and visual analysis of the page layout through screenshots with marked
interactive elements.
### **init**
```python theme={"system"}
def __init__(self):
```
Initialize the HybridBrowserToolkit.
**Parameters:**
* **headless** (bool): Whether to run the browser in headless mode. Defaults to `True`.
* **user\_data\_dir** (Optional\[str]): Path to a directory for storing browser data like cookies and local storage. Useful for maintaining sessions across runs. Defaults to `None` (a temporary directory is used).
* **stealth** (bool): Whether to run the browser in stealth mode to avoid bot detection. When enabled, hides WebDriver characteristics, spoofs navigator properties, and implements various anti-detection measures. Highly recommended for production use and when accessing sites with bot detection. Defaults to `False`.
* **web\_agent\_model** (Optional\[BaseModelBackend]): The language model backend to use for the high-level `solve_task` agent. This is required only if you plan to use `solve_task`. Defaults to `None`.
* **cache\_dir** (str): The directory to store cached files, such as screenshots. Defaults to `"tmp/"`.
* **enabled\_tools** (Optional\[List\[str]]): List of tool names to enable. If None, uses DEFAULT\_TOOLS. Available tools: browser\_open, browser\_close, browser\_visit\_page, browser\_back, browser\_forward, browser\_get\_page\_snapshot, browser\_get\_som\_screenshot, browser\_get\_page\_links, browser\_click, browser\_type, browser\_select, browser\_scroll, browser\_enter, browser\_wait\_user, browser\_solve\_task. Defaults to `None`.
* **browser\_log\_to\_file** (bool): Whether to save detailed browser action logs to file. When enabled, logs action inputs/outputs, execution times, and page loading times. Logs are saved to an auto-generated timestamped file. Defaults to `False`.
* **log\_dir** (Optional\[str]): Custom directory path for log files. If None, defaults to "browser\_log". Defaults to `None`.
* **session\_id** (Optional\[str]): A unique identifier for this browser session. When multiple HybridBrowserToolkit instances are used concurrently, different session IDs prevent them from sharing the same browser session and causing conflicts. If None, a default session will be used. Defaults to `None`.
* **default\_start\_url** (str): The default URL to navigate to when open\_browser() is called without a start\_url parameter or with None. Defaults to `"https://google.com/"`.
* **default\_timeout** (Optional\[int]): Default timeout in milliseconds for browser actions. If None, uses environment variable HYBRID\_BROWSER\_DEFAULT\_TIMEOUT or defaults to 3000ms. Defaults to `None`.
* **short\_timeout** (Optional\[int]): Short timeout in milliseconds for quick browser actions. If None, uses environment variable HYBRID\_BROWSER\_SHORT\_TIMEOUT or defaults to 1000ms. Defaults to `None`.
* **navigation\_timeout** (Optional\[int]): Custom navigation timeout in milliseconds. If None, uses environment variable HYBRID\_BROWSER\_NAVIGATION\_TIMEOUT or defaults to 10000ms. Defaults to `None`.
* **network\_idle\_timeout** (Optional\[int]): Custom network idle timeout in milliseconds. If None, uses environment variable HYBRID\_BROWSER\_NETWORK\_IDLE\_TIMEOUT or defaults to 5000ms. Defaults to `None`.
* **screenshot\_timeout** (Optional\[int]): Custom screenshot timeout in milliseconds. If None, uses environment variable HYBRID\_BROWSER\_SCREENSHOT\_TIMEOUT or defaults to 15000ms. Defaults to `None`.
* **page\_stability\_timeout** (Optional\[int]): Custom page stability timeout in milliseconds. If None, uses environment variable HYBRID\_BROWSER\_PAGE\_STABILITY\_TIMEOUT or defaults to 1500ms. Defaults to `None`.
* **dom\_content\_loaded\_timeout** (Optional\[int]): Custom DOM content loaded timeout in milliseconds. If None, uses environment variable HYBRID\_BROWSER\_DOM\_CONTENT\_LOADED\_TIMEOUT or defaults to 5000ms. Defaults to `None`.
* **viewport\_limit** (bool): When True, only return snapshot results visible in the current viewport. When False, return all elements on the page regardless of visibility. Defaults to `False`.
### web\_agent\_model
```python theme={"system"}
def web_agent_model(self):
```
Get the web agent model.
### web\_agent\_model
```python theme={"system"}
def web_agent_model(self, value: Optional[BaseModelBackend]):
```
Set the web agent model.
### cache\_dir
```python theme={"system"}
def cache_dir(self):
```
Get the cache directory.
### **del**
```python theme={"system"}
def __del__(self):
```
Cleanup browser resources on garbage collection.
### \_load\_unified\_analyzer
```python theme={"system"}
def _load_unified_analyzer(self):
```
Load the unified analyzer JavaScript script.
### \_validate\_ref
```python theme={"system"}
def _validate_ref(self, ref: str, method_name: str):
```
Validate ref parameter.
### \_truncate\_if\_needed
```python theme={"system"}
def _truncate_if_needed(self, content: Any):
```
Truncate content if max\_log\_length is set.
### action\_logger
```python theme={"system"}
def action_logger(func: Callable[..., Any]):
```
Decorator to add logging to action methods.
### \_convert\_analysis\_to\_rects
```python theme={"system"}
def _convert_analysis_to_rects(self, analysis_data: Dict[str, Any]):
```
Convert analysis data to rect format for visual marking.
### \_add\_set\_of\_mark
```python theme={"system"}
def _add_set_of_mark(self, image, rects):
```
Add visual marks to the image.
### \_format\_snapshot\_from\_analysis
```python theme={"system"}
def _format_snapshot_from_analysis(self, analysis_data: Dict[str, Any]):
```
Format analysis data into snapshot string.
### \_ensure\_agent
```python theme={"system"}
def _ensure_agent(self):
```
Create PlaywrightLLMAgent on first use.
### get\_log\_summary
```python theme={"system"}
def get_log_summary(self):
```
Get a summary of logged actions.
### clear\_logs
```python theme={"system"}
def clear_logs(self):
```
Clear the log buffer.
### clone\_for\_new\_session
```python theme={"system"}
def clone_for_new_session(self, new_session_id: Optional[str] = None):
```
Create a new instance of HybridBrowserToolkit with a unique
session.
**Parameters:**
* **new\_session\_id**: Optional new session ID. If None, a UUID will be generated.
**Returns:**
A new HybridBrowserToolkit instance with the same configuration
but a different session.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Get available function tools
based on enabled\_tools configuration.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.hybrid_browser_toolkit_py.snapshot
## PageSnapshot
```python theme={"system"}
class PageSnapshot:
```
Utility for capturing YAML-like page snapshots and diff-only
variants.
### **init**
```python theme={"system"}
def __init__(self, page: 'Page'):
```
### \_format\_snapshot
```python theme={"system"}
def _format_snapshot(text: str):
```
### \_compute\_diff
```python theme={"system"}
def _compute_diff(old: str, new: str):
```
### \_detect\_priorities
```python theme={"system"}
def _detect_priorities(self, snapshot_yaml: str):
```
Return sorted list of priorities present (1,2,3).
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.image_analysis_toolkit
## ImageAnalysisToolkit
```python theme={"system"}
class ImageAnalysisToolkit(BaseToolkit):
```
A toolkit for comprehensive image analysis and understanding.
The toolkit uses vision-capable language models to perform these tasks.
### **init**
```python theme={"system"}
def __init__(
self,
model: Optional[BaseModelBackend] = None,
timeout: Optional[float] = None
):
```
Initialize the ImageAnalysisToolkit.
**Parameters:**
* **model** (Optional\[BaseModelBackend]): The model backend to use for image analysis tasks. This model should support processing images for tasks like image description and visual question answering. If None, a default model will be created using ModelFactory. (default: :obj:`None`)
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### image\_to\_text
```python theme={"system"}
def image_to_text(self, image_path: str, sys_prompt: Optional[str] = None):
```
Generates textual description of an image with optional custom
prompt.
**Parameters:**
* **image\_path** (str): Local path or URL to an image file.
* **sys\_prompt** (Optional\[str]): Custom system prompt for the analysis. (default: :obj:`None`)
**Returns:**
str: Natural language description of the image.
### ask\_question\_about\_image
```python theme={"system"}
def ask_question_about_image(
self,
image_path: str,
question: str,
sys_prompt: Optional[str] = None
):
```
Answers image questions with optional custom instructions.
**Parameters:**
* **image\_path** (str): Local path or URL to an image file.
* **question** (str): Query about the image content.
* **sys\_prompt** (Optional\[str]): Custom system prompt for the analysis. (default: :obj:`None`)
**Returns:**
str: Detailed answer based on visual understanding
### \_load\_image
```python theme={"system"}
def _load_image(self, image_path: str):
```
Loads an image from either local path or URL.
**Parameters:**
* **image\_path** (str): Local path or URL to image.
**Returns:**
Image.Image: Loaded PIL Image object.
### \_analyze\_image
```python theme={"system"}
def _analyze_image(
self,
image_path: str,
prompt: str,
system_message: BaseMessage
):
```
Core analysis method handling image loading and processing.
**Parameters:**
* **image\_path** (str): Image location.
* **prompt** (str): Analysis query/instructions.
* **system\_message** (BaseMessage): Custom system prompt for the analysis.
**Returns:**
str: Analysis result or error message.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.image_generation_toolkit
## ImageGenToolkit
```python theme={"system"}
class ImageGenToolkit(BaseToolkit):
```
A class toolkit for image generation using Grok and OpenAI models.
### **init**
```python theme={"system"}
def __init__(
self,
model: Optional[Literal['gpt-image-1', 'dall-e-3', 'dall-e-2', 'grok-2-image', 'grok-2-image-latest', 'grok-2-image-1212']] = 'dall-e-3',
timeout: Optional[float] = None,
api_key: Optional[str] = None,
url: Optional[str] = None,
size: Optional[Literal['256x256', '512x512', '1024x1024', '1536x1024', '1024x1536', '1792x1024', '1024x1792', 'auto']] = '1024x1024',
quality: Optional[Literal['auto', 'low', 'medium', 'high', 'standard', 'hd']] = 'standard',
response_format: Optional[Literal['url', 'b64_json']] = 'b64_json',
background: Optional[Literal['transparent', 'opaque', 'auto']] = 'auto',
style: Optional[Literal['vivid', 'natural']] = None,
working_directory: Optional[str] = 'image_save'
):
```
Initializes a new instance of the ImageGenToolkit class.
**Parameters:**
* **api\_key** (Optional\[str]): The API key for authenticating with the image model service. (default: :obj:`None`)
* **url** (Optional\[str]): The url to the image model service. (default: :obj:`None`)
* **model** (Optional\[str]): The model to use. (default: :obj:`"dall-e-3"`)
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`) size (Optional\[Literal\["256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "1792x1024", "1024x1792", "auto"]]): The size of the image to generate. (default: :obj:`"1024x1024"`) quality (Optional\[Literal\["auto", "low", "medium", "high", "standard", "hd"]]):The quality of the image to generate. Different models support different values. (default: :obj:`"standard"`)
* **response\_format** (`Optional[Literal["url", "b64_json"]]`): The format of the response.(default: :obj:`"b64_json"`)
* **background** (`Optional[Literal["transparent", "opaque", "auto"]]`): The background of the image.(default: :obj:`"auto"`)
* **style** (`Optional[Literal["vivid", "natural"]]`): The style of the image.(default: :obj:`None`)
* **working\_directory** (Optional\[str]): The path to save the generated image.(default: :obj:`"image_save"`)
### base64\_to\_image
```python theme={"system"}
def base64_to_image(self, base64_string: str):
```
Converts a base64 encoded string into a PIL Image object.
**Parameters:**
* **base64\_string** (str): The base64 encoded string of the image.
**Returns:**
Optional\[Image.Image]: The PIL Image object or None if conversion
fails.
### \_build\_base\_params
```python theme={"system"}
def _build_base_params(self, prompt: str, n: Optional[int] = None):
```
Build base parameters dict for Image Model API calls.
**Parameters:**
* **prompt** (str): The text prompt for the image operation.
* **n** (Optional\[int]): The number of images to generate.
**Returns:**
dict: Parameters dictionary with non-None values.
### \_handle\_api\_response
```python theme={"system"}
def _handle_api_response(
self,
response,
image_name: Union[str, List[str]],
operation: str
):
```
Handle API response from image operations.
**Parameters:**
* **response**: The response object from image model API.
* **image\_name** (Union\[str, List\[str]]): Name(s) for the saved image file(s). If str, the same name is used for all images (will cause error for multiple images). If list, must have exactly the same length as the number of images generated.
* **operation** (str): Operation type for success message ("generated").
**Returns:**
str: Success message with image path/URL or error message.
### generate\_image
```python theme={"system"}
def generate_image(
self,
prompt: str,
image_name: Union[str, List[str]] = 'image.png',
n: int = 1
):
```
Generate an image using image models.
The generated image will be saved locally (for `__INLINE_CODE_0__` response
formats) or an image URL will be returned (for `__INLINE_CODE_1__` response
formats).
**Parameters:**
* **prompt** (str): The text prompt to generate the image.
* **image\_name** (Union\[str, List\[str]]): The name(s) of the image(s) to save. The image name must end with `.png`. If str: same name used for all images (causes error if n > 1). If list: must match the number of images being generated (n parameter). (default: :obj:`"image.png"`)
* **n** (int): The number of images to generate. (default: :obj:`1`) (default: 1)
**Returns:**
str: the content of the model response or format of the response.
### get\_grok\_credentials
```python theme={"system"}
def get_grok_credentials(self, url, api_key):
```
Get API credentials for the specified Grok model.
**Parameters:**
* **url** (str): The base URL for the Grok API.
* **api\_key** (str): The API key for the Grok API.
**Returns:**
tuple: (api\_key, base\_url)
### get\_openai\_credentials
```python theme={"system"}
def get_openai_credentials(self, url, api_key):
```
Get API credentials for the specified OpenAI model.
**Parameters:**
* **url** (str): The base URL for the OpenAI API.
* **api\_key** (str): The API key for the OpenAI API.
**Returns:**
Tuple\[str, str | None]: (api\_key, base\_url)
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.imap_mail_toolkit
## IMAP\_RETURN\_STATUS
```python theme={"system"}
class IMAP_RETURN_STATUS(Enum):
```
IMAP operation return status codes.
## IMAPMailToolkit
```python theme={"system"}
class IMAPMailToolkit(BaseToolkit):
```
A toolkit for IMAP email operations.
This toolkit provides comprehensive email functionality including:
* Fetching emails with filtering options
* Retrieving specific emails by ID
* Sending emails via SMTP
* Replying to emails
* Moving emails to folders
* Deleting emails
The toolkit implements connection pooling with automatic idle timeout
to prevent resource leaks when used by LLM agents.
**Parameters:**
* **imap\_server** (str, optional): IMAP server hostname. If not provided, will be obtained from environment variables.
* **imap\_port** (int, optional): IMAP server port. Defaults to 993. (default: 993)
* **smtp\_server** (str, optional): SMTP server hostname. If not provided, will be obtained from environment variables.
* **smtp\_port** (int, optional): SMTP server port. Defaults to 587. (default: 587)
* **username** (str, optional): Email username. If not provided, will be obtained from environment variables.
* **password** (str, optional): Email password. If not provided, will be obtained from environment variables.
* **timeout** (Optional\[float]): The timeout for the toolkit operations.
* **connection\_idle\_timeout** (float): Maximum idle time (in seconds) before auto-closing connections. Defaults to 300 (5 minutes).
### **init**
```python theme={"system"}
def __init__(
self,
imap_server: Optional[str] = None,
imap_port: int = 993,
smtp_server: Optional[str] = None,
smtp_port: int = 587,
username: Optional[str] = None,
password: Optional[str] = None,
timeout: Optional[float] = None,
connection_idle_timeout: float = 300.0
):
```
Initialize the IMAP Mail Toolkit.
**Parameters:**
* **imap\_server**: IMAP server hostname (default: :obj:`None`)
* **imap\_port**: IMAP server port (default: :obj:`993`) (default: 993)
* **smtp\_server**: SMTP server hostname (default: :obj:`None`)
* **smtp\_port**: SMTP server port (default: :obj:`587`) (default: 587)
* **username**: Email username (default: :obj:`None`)
* **password**: Email password (default: :obj:`None`)
* **timeout**: Timeout for operations (default: :obj:`None`)
* **connection\_idle\_timeout**: Max idle time before auto-close (default: :obj:`300` seconds)
### \_get\_imap\_connection
```python theme={"system"}
def _get_imap_connection(self):
```
**Returns:**
imaplib.IMAP4\_SSL: Connected IMAP client
### \_get\_smtp\_connection
```python theme={"system"}
def _get_smtp_connection(self):
```
**Returns:**
smtplib.SMTP: Connected SMTP client
### \_ensure\_imap\_ok
```python theme={"system"}
def _ensure_imap_ok(self, status: str, action: str):
```
Ensure IMAP status is OK, otherwise raise a ConnectionError.
### fetch\_emails
```python theme={"system"}
def fetch_emails(
self,
folder: Literal['INBOX'] = 'INBOX',
limit: int = 10,
unread_only: bool = False,
sender_filter: Optional[str] = None,
subject_filter: Optional[str] = None
):
```
Fetch emails from a folder with optional filtering.
**Parameters:**
* **folder** (`Literal["INBOX"]`): Email folder to search in (default: :obj:`"INBOX"`)
* **limit** (int): Maximum number of emails to retrieve (default: :obj:`10`)
* **unread\_only** (bool): If True, only fetch unread emails (default: :obj:`False`)
* **sender\_filter** (str, optional): Filter emails by sender email address (default: :obj:`None`)
* **subject\_filter** (str, optional): Filter emails by subject content (default: :obj:`None`)
**Returns:**
List\[Dict]: List of email dictionaries with metadata
### get\_email\_by\_id
```python theme={"system"}
def get_email_by_id(self, email_id: str, folder: Literal['INBOX'] = 'INBOX'):
```
Retrieve a specific email by ID with full metadata.
**Parameters:**
* **email\_id** (str): ID of the email to retrieve
* **folder** (`Literal["INBOX"]`): Folder containing the email (default: :obj:`"INBOX"`)
**Returns:**
Dict: Email dictionary with complete metadata
### send\_email
```python theme={"system"}
def send_email(
self,
to_recipients: List[str],
subject: str,
body: str,
cc_recipients: Optional[List[str]] = None,
bcc_recipients: Optional[List[str]] = None,
html_body: Optional[str] = None
):
```
Send an email via SMTP.
**Parameters:**
* **to\_recipients** (List\[str]): List of recipient email addresses
* **subject** (str): Email subject line
* **body** (str): Plain text email body
* **cc\_recipients** (List\[str], optional): List of CC recipient email addresses
* **bcc\_recipients** (List\[str], optional): List of BCC recipient email addresses
* **html\_body** (str, optional): HTML version of email body
* **extra\_headers** (Dict\[str, str], optional): Additional email headers
**Returns:**
str: Success message
### reply\_to\_email
```python theme={"system"}
def reply_to_email(
self,
original_email_id: str,
reply_body: str,
folder: Literal['INBOX'] = 'INBOX',
html_body: Optional[str] = None
):
```
Send a reply to an existing email.
**Parameters:**
* **original\_email\_id** (str): ID of the email to reply to
* **reply\_body** (str): Reply message body
* **folder** (`Literal["INBOX"]`): Folder containing the original email (default: :obj:`"INBOX"`)
* **html\_body** (str, optional): HTML version of reply body (default: :obj:`None`)
**Returns:**
str: Success message
### move\_email\_to\_folder
```python theme={"system"}
def move_email_to_folder(
self,
email_id: str,
target_folder: str,
source_folder: Literal['INBOX'] = 'INBOX'
):
```
Move an email to a different folder.
**Parameters:**
* **email\_id** (str): ID of the email to move
* **target\_folder** (str): Destination folder name
* **source\_folder** (`Literal["INBOX"]`): Source folder name (default: :obj:`"INBOX"`)
**Returns:**
str: Success message
### delete\_email
```python theme={"system"}
def delete_email(
self,
email_id: str,
folder: Literal['INBOX'] = 'INBOX',
permanent: bool = False
):
```
Delete an email.
**Parameters:**
* **email\_id** (str): ID of the email to delete
* **folder** (`Literal["INBOX"]`): Folder containing the email (default: :obj:`"INBOX"`)
* **permanent** (bool): If True, permanently delete the email (default: :obj:`False`)
**Returns:**
str: Success message
### \_extract\_email\_body
```python theme={"system"}
def _extract_email_body(self, email_message: email.message.Message):
```
Extract plain text and HTML body from email message.
**Parameters:**
* **email\_message**: Email message object
**Returns:**
Dict\[str, str]: Dictionary with 'plain' and 'html' body content
### close
```python theme={"system"}
def close(self):
```
Close all open connections.
This method should be called when the toolkit is no longer needed
to properly clean up network connections.
### **del**
```python theme={"system"}
def __del__(self):
```
Destructor to ensure connections are closed.
### **enter**
```python theme={"system"}
def __enter__(self):
```
**Returns:**
IMAPMailToolkit: Self instance
### **exit**
```python theme={"system"}
def __exit__(
self,
exc_type,
exc_val,
exc_tb
):
```
Context manager exit, ensuring connections are closed.
**Parameters:**
* **exc\_type**: Exception type if an exception occurred
* **exc\_val**: Exception value if an exception occurred
* **exc\_tb**: Exception traceback if an exception occurred
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available tools
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.jina_reranker_toolkit
## JinaRerankerToolkit
```python theme={"system"}
class JinaRerankerToolkit(BaseToolkit):
```
A class representing a toolkit for reranking documents
using Jina Reranker.
This class provides methods for reranking documents (text or images)
based on their relevance to a given query using the Jina Reranker model.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
model_name: str = 'jinaai/jina-reranker-m0',
device: Optional[str] = None,
use_api: bool = True
):
```
Initializes a new instance of the JinaRerankerToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
* **model\_name** (str): The reranker model name. (default: :obj:`"jinaai/jina-reranker-m0"`)
* **device** (Optional\[str]): Device to load the model on. If None, will use CUDA if available, otherwise CPU. Only effective when use\_api=False. (default: :obj:`None`)
* **use\_api** (bool): A flag to switch between local model and API. (default: :obj:`True`)
### \_sort\_documents
```python theme={"system"}
def _sort_documents(self, documents: List[str], scores: List[float]):
```
Sort documents by their scores in descending order.
**Parameters:**
* **documents** (List\[str]): List of documents to sort.
* **scores** (List\[float]): Corresponding scores for each document.
**Returns:**
List\[Dict\[str, object]]: Sorted list of (document, score) pairs.
### \_call\_jina\_api
```python theme={"system"}
def _call_jina_api(self, data: Dict[str, Any]):
```
Makes a call to the JINA API for reranking.
**Parameters:**
* **data** (Dict\[str]): The data to be passed into the api body.
**Returns:**
List\[Dict\[str, object]]: A list of dictionary containing
the reranked documents and their relevance scores.
### rerank\_text\_documents
```python theme={"system"}
def rerank_text_documents(
self,
query: str,
documents: List[str],
max_length: int = 1024
):
```
Reranks text documents based on their relevance to a text query.
**Parameters:**
* **query** (str): The text query for reranking.
* **documents** (List\[str]): List of text documents to be reranked.
* **max\_length** (int): Maximum token length for processing. (default: :obj:`1024`)
**Returns:**
List\[Dict\[str, object]]: A list of dictionary containing
the reranked documents and their relevance scores.
### rerank\_image\_documents
```python theme={"system"}
def rerank_image_documents(
self,
query: str,
documents: List[str],
max_length: int = 2048
):
```
Reranks image documents based on their relevance to a text query.
**Parameters:**
* **query** (str): The text query for reranking.
* **documents** (List\[str]): List of image URLs or paths to be reranked.
* **max\_length** (int): Maximum token length for processing. (default: :obj:`2048`)
**Returns:**
List\[Dict\[str, object]]: A list of dictionary containing
the reranked image URLs/paths and their relevance scores.
### image\_query\_text\_documents
```python theme={"system"}
def image_query_text_documents(
self,
image_query: str,
documents: List[str],
max_length: int = 2048
):
```
Reranks text documents based on their relevance to an image query.
**Parameters:**
* **image\_query** (str): The image URL or path used as query.
* **documents** (List\[str]): List of text documents to be reranked.
* **max\_length** (int): Maximum token length for processing. (default: :obj:`2048`)
**Returns:**
List\[Dict\[str, object]]: A list of dictionary containing
the reranked documents and their relevance scores.
### image\_query\_image\_documents
```python theme={"system"}
def image_query_image_documents(
self,
image_query: str,
documents: List[str],
max_length: int = 2048
):
```
Reranks image documents based on their relevance to an image query.
**Parameters:**
* **image\_query** (str): The image URL or path used as query.
* **documents** (List\[str]): List of image URLs or paths to be reranked.
* **max\_length** (int): Maximum token length for processing. (default: :obj:`2048`)
**Returns:**
List\[Dict\[str, object]]: A list of dictionary containing
the reranked image URLs/paths and their relevance scores.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.klavis_toolkit
## KlavisToolkit
```python theme={"system"}
class KlavisToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with Klavis API.
This class provides methods for interacting with Klavis MCP server
instances, retrieving server information, managing tools, and handling
authentication.
**Parameters:**
* **api\_key** (str): The API key for authenticating with Klavis API.
* **base\_url** (str): The base URL for Klavis API endpoints.
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the KlavisToolkit with API client. The API key is
retrieved from environment variables.
### \_request
```python theme={"system"}
def _request(
self,
method: str,
endpoint: str,
payload: Optional[Dict[str, Any]] = None,
additional_headers: Optional[Dict[str, str]] = None
):
```
Make an HTTP request to the Klavis API.
**Parameters:**
* **method** (str): HTTP method (e.g., 'GET', 'POST', 'DELETE').
* **endpoint** (str): API endpoint path.
* **payload** (Optional\[Dict\[str, Any]]): JSON payload for POST requests.
* **additional\_headers** (Optional\[Dict\[str, str]]): Additional headers to include in the request.
**Returns:**
Dict\[str, Any]: The JSON response from the API or an error
dict.
### create\_server\_instance
```python theme={"system"}
def create_server_instance(
self,
server_name: str,
user_id: str,
platform_name: str
):
```
Create a Server-Sent Events (SSE) URL for a specified MCP server.
**Parameters:**
* **server\_name** (str): The name of the target MCP server.
* **user\_id** (str): The ID for the user requesting the server URL.
* **platform\_name** (str): The name of the platform associated with the user.
**Returns:**
Dict\[str, Any]: Response containing the server instance details.
### get\_server\_instance
```python theme={"system"}
def get_server_instance(self, instance_id: str):
```
Get details of a specific server connection instance.
**Parameters:**
* **instance\_id** (str): The ID of the connection instance whose status is being checked.
**Returns:**
Dict\[str, Any]: Details about the server instance.
### delete\_auth\_data
```python theme={"system"}
def delete_auth_data(self, instance_id: str):
```
Delete authentication metadata for a specific server
connection instance.
**Parameters:**
* **instance\_id** (str): The ID of the connection instance to delete auth for.
**Returns:**
Dict\[str, Any]: Status response for the operation.
### delete\_server\_instance
```python theme={"system"}
def delete_server_instance(self, instance_id: str):
```
Completely removes a server connection instance.
**Parameters:**
* **instance\_id** (str): The ID of the connection instance to delete.
**Returns:**
Dict\[str, Any]: Status response for the operation.
### get\_all\_servers
```python theme={"system"}
def get_all_servers(self):
```
**Returns:**
Dict\[str, Any]: Information about all available MCP servers.
### set\_auth\_token
```python theme={"system"}
def set_auth_token(self, instance_id: str, auth_token: str):
```
Sets an authentication token for a specific instance.
**Parameters:**
* **instance\_id** (str): The ID for the connection instance.
* **auth\_token** (str): The authentication token to save.
**Returns:**
Dict\[str, Any]: Status response for the operation.
### list\_tools
```python theme={"system"}
def list_tools(self, server_url: str):
```
Lists all tools available for a specific remote MCP server.
**Parameters:**
* **server\_url** (str): The full URL for connecting to the MCP server via Server-Sent Events (SSE).
**Returns:**
Dict\[str, Any]: Response containing the list of tools or an error.
### call\_tool
```python theme={"system"}
def call_tool(
self,
server_url: str,
tool_name: str,
tool_args: Optional[Dict[str, Any]] = None
):
```
Calls a remote MCP server tool directly using the provided server
URL.
**Parameters:**
* **server\_url** (str): The full URL for connecting to the MCP server via Server-Sent Events (SSE).
* **tool\_name** (str): The name of the tool to call.
* **tool\_args** (Optional\[Dict\[str, Any]]): The input parameters for the tool. Defaults to None, which might be treated as empty args by the server. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: Response containing the result of the tool call
or an error.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.lark_toolkit
## LarkToolkit
```python theme={"system"}
class LarkToolkit(BaseToolkit):
```
A toolkit for Lark (Feishu) chat operations.
### **init**
```python theme={"system"}
def __init__(
self,
app_id: Optional[str] = None,
app_secret: Optional[str] = None,
use_feishu: bool = False,
timeout: Optional[float] = None
):
```
Initializes the LarkToolkit.
**Parameters:**
* **app\_id** (Optional\[str]): The Lark application ID. If not provided, uses LARK\_APP\_ID environment variable.
* **app\_secret** (Optional\[str]): The Lark application secret. If not provided, uses LARK\_APP\_SECRET environment variable.
* **use\_feishu** (bool): Set to True to use Feishu (China) API endpoints instead of Lark (international). (default: :obj:`False`)
* **timeout** (Optional\[float]): Request timeout in seconds.
### \_get\_tenant\_http\_headers
```python theme={"system"}
def _get_tenant_http_headers(self):
```
**Returns:**
Dict\[str, str]: Headers dict with Content-Type and Authorization.
### \_convert\_timestamp
```python theme={"system"}
def _convert_timestamp(self, ts: Any):
```
Convert millisecond timestamp to readable datetime string.
**Parameters:**
* **ts**: Timestamp value (can be string or int, in milliseconds).
**Returns:**
str: ISO format datetime string, or original value if conversion
fails.
### \_process\_message\_items
```python theme={"system"}
def _process_message_items(self, items: List[Dict[str, Any]]):
```
Process message items to agent-friendly format.
**Parameters:**
* **items**: List of message items from API response.
**Returns:**
List\[Dict\[str, Any]]: Simplified items with only essential fields.
### lark\_list\_chats
```python theme={"system"}
def lark_list_chats(
self,
sort_type: Literal['ByCreateTimeAsc', 'ByActiveTimeDesc'] = 'ByCreateTimeAsc',
page_size: int = 20,
page_token: Optional[str] = None
):
```
Lists chats and groups that the user belongs to.
Use this method to discover available chats and obtain chat\_id values.
**Parameters:**
* **sort\_type** (str): Sort order for chats. Options: - "ByCreateTimeAsc" (default) - "ByActiveTimeDesc"
* **page\_size** (int): Number of chats to return per page (max 100). (default: :obj:`20`)
* **page\_token** (Optional\[str]): Token for pagination. Use the page\_token from previous response to get next page.
**Returns:**
Dict\[str, object]: A dictionary containing:
* chats: List of chat objects with chat\_id and name
* has\_more: Whether there are more chats to fetch
* page\_token: Token to fetch the next page
### lark\_get\_chat\_messages
```python theme={"system"}
def lark_get_chat_messages(
self,
container_id: str,
container_id_type: Literal['chat', 'thread'] = 'chat',
start_time: Optional[str] = None,
end_time: Optional[str] = None,
sort_type: Literal['ByCreateTimeAsc', 'ByCreateTimeDesc'] = 'ByCreateTimeAsc',
page_size: int = 20,
page_token: Optional[str] = None
):
```
Gets message history from a chat with optional time filtering.
Retrieves messages from a specific chat. Requires the bot to be a
member of the chat.
**Parameters:**
* **container\_id** (str): The container ID to retrieve messages from.
* **container\_id\_type** (str): The container type. Options: - "chat": Chat (p2p or group) - "thread": Thread
* **start\_time** (Optional\[str]): Start time filter (Unix timestamp in seconds, e.g., "1609459200"). Messages created after this time. Not supported for "thread" container type.
* **end\_time** (Optional\[str]): End time filter (Unix timestamp in seconds). Messages created before this time. Not supported for "thread" container type.
* **sort\_type** (str): Sort order for messages. Options: - "ByCreateTimeAsc": Oldest first (default) - "ByCreateTimeDesc": Newest first
* **page\_size** (int): Number of messages to return per page (max 50). (default: :obj:`20`)
* **page\_token** (Optional\[str]): Token for pagination. Use the page\_token from previous response to get next page.
**Returns:**
Dict\[str, object]: A dictionary containing:
* messages: List of processed message objects with fields:
* message\_id: Message identifier
* msg\_type: Message type (text, image, file, etc.)
* text: Extracted message text content
* time: Human-readable timestamp (UTC)
* sender\_id: Sender's user ID
* sender\_type: Type of sender
* has\_more: Whether there are more messages to fetch
* page\_token: Token to fetch the next page
### lark\_send\_message
```python theme={"system"}
def lark_send_message(
self,
receive_id: str,
text: str,
receive_id_type: Literal['open_id', 'user_id', 'union_id', 'email', 'chat_id'] = 'chat_id'
):
```
Sends a message to a user or chat. If send message to
a chat, use lark\_list\_chats to get chat\_id first, if send
message to a user, need user provide open\_id, user\_id,
union\_id or email.
**Parameters:**
* **receive\_id** (str): The recipient identifier.
* **text** (str): The text message content.
* **receive\_id\_type** (str): The recipient ID type. Options: - "open\_id" - "user\_id" - "union\_id" - "email" - "chat\_id" (default)
**Returns:**
Dict\[str, object]: A dictionary containing:
* message\_id: The sent message ID
* chat\_id: The chat ID the message belongs to
* msg\_type: Message type (text)
### lark\_get\_message\_resource
```python theme={"system"}
def lark_get_message_resource(
self,
message_id: str,
file_key: str,
resource_type: Literal['image', 'file']
):
```
Obtains resource files in messages, including audios, videos,
images, and files. Emoji resources cannot be downloaded, and the
resource files for download cannot exceed 100 MB.
**Parameters:**
* **message\_id** (str): The message ID containing the resource.
* **file\_key** (str): The resource file key from message content.
* **resource\_type** (str): Resource type, either "image" or "file".
**Returns:**
Dict\[str, object]: A dictionary containing:
* content\_type: Response Content-Type header value
* path: File path where content was saved
* size: Content size in bytes
### lark\_get\_message\_resource\_key
```python theme={"system"}
def lark_get_message_resource_key(self, message_id: str):
```
Gets the resource key from a message's content.
**Parameters:**
* **message\_id** (str): The message ID to fetch.
**Returns:**
Dict\[str, object]: A dictionary containing:
* key: The resource key from message content
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.linkedin_toolkit
## LinkedInToolkit
```python theme={"system"}
class LinkedInToolkit(BaseToolkit):
```
A class representing a toolkit for LinkedIn operations.
This class provides methods for creating a post, deleting a post, and
retrieving the authenticated user's profile information.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
### create\_post
```python theme={"system"}
def create_post(self, text: str):
```
Creates a post on LinkedIn for the authenticated user.
**Parameters:**
* **text** (str): The content of the post to be created.
**Returns:**
dict: A dictionary containing the post ID and the content of
the post. If the post creation fails, the values will be None.
### delete\_post
```python theme={"system"}
def delete_post(self, post_id: str):
```
Deletes a LinkedIn post with the specified ID
for an authorized user.
This function sends a DELETE request to the LinkedIn API to delete
a post with the specified ID. Before sending the request, it
prompts the user to confirm the deletion.
**Parameters:**
* **post\_id** (str): The ID of the post to delete.
**Returns:**
str: A message indicating the result of the deletion. If the
deletion was successful, the message includes the ID of the
deleted post. If the deletion was not successful, the message
includes an error message.
Reference:
[https://docs.microsoft.com/en-us/linkedin/marketing/integrations/community-management/shares/ugc-post-api](https://docs.microsoft.com/en-us/linkedin/marketing/integrations/community-management/shares/ugc-post-api)
### get\_profile
```python theme={"system"}
def get_profile(self, include_id: bool = False):
```
Retrieves the authenticated user's LinkedIn profile info.
This function sends a GET request to the LinkedIn API to retrieve the
authenticated user's profile information. Optionally, it also returns
the user's LinkedIn ID.
**Parameters:**
* **include\_id** (bool): Whether to include the LinkedIn profile ID in the response.
**Returns:**
dict: A dictionary containing the user's LinkedIn profile
information. If `include_id` is True, the dictionary will also
include the profile ID.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
### \_get\_access\_token
```python theme={"system"}
def _get_access_token(self):
```
**Returns:**
str: The OAuth 2.0 access token or warming message if the
environment variable `LINKEDIN_ACCESS_TOKEN` is not set or is
empty.
Reference:
You can apply for your personal LinkedIn API access token through
the link below:
[https://www.linkedin.com/developers/apps](https://www.linkedin.com/developers/apps)
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.markitdown_toolkit
## MarkItDownToolkit
```python theme={"system"}
class MarkItDownToolkit(BaseToolkit):
```
A class representing a toolkit for MarkItDown.
.. deprecated::
MarkItDownToolkit is deprecated. Use FileToolkit instead, which now
includes the same functionality through its read\_file method that
supports both single files and multiple files.
Example migration:
# Old way
from camel.toolkits import MarkItDownToolkit
toolkit = MarkItDownToolkit()
content = toolkit.read\_files(\['file1.pdf', 'file2.docx'])
# New way
from camel.toolkits import FileToolkit
toolkit = FileToolkit()
content = toolkit.read\_file(\['file1.pdf', 'file2.docx'])
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
### read\_files
```python theme={"system"}
def read_files(self, file_paths: List[str]):
```
Scrapes content from a list of files and converts it to Markdown.
This function takes a list of local file paths, attempts to convert
each file into Markdown format, and returns the converted content.
The conversion is performed in parallel for efficiency.
Supported file formats include:
* PDF (.pdf)
* Microsoft Office: Word (.doc, .docx), Excel (.xls, .xlsx),
PowerPoint (.ppt, .pptx)
* EPUB (.epub)
* HTML (.html, .htm)
* Images (.jpg, .jpeg, .png) for OCR
* Audio (.mp3, .wav) for transcription
* Text-based formats (.csv, .json, .xml, .txt)
* ZIP archives (.zip)
**Parameters:**
* **file\_paths** (List\[str]): A list of local file paths to be converted.
**Returns:**
Dict\[str, str]: A dictionary where keys are the input file paths
and values are the corresponding content in Markdown format.
If conversion of a file fails, the value will contain an
error message.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.math_toolkit
## MathToolkit
```python theme={"system"}
class MathToolkit(BaseToolkit):
```
A class representing a toolkit for mathematical operations.
This class provides methods for basic mathematical operations such as
addition, subtraction, multiplication, division, and rounding.
### math\_add
```python theme={"system"}
def math_add(self, a: float, b: float):
```
Adds two numbers.
**Parameters:**
* **a** (float): The first number to be added.
* **b** (float): The second number to be added.
**Returns:**
float: The sum of the two numbers.
### math\_subtract
```python theme={"system"}
def math_subtract(self, a: float, b: float):
```
Do subtraction between two numbers.
**Parameters:**
* **a** (float): The minuend in subtraction.
* **b** (float): The subtrahend in subtraction.
**Returns:**
float: The result of subtracting :obj:`b` from :obj:`a`.
### math\_multiply
```python theme={"system"}
def math_multiply(
self,
a: float,
b: float,
decimal_places: int = 2
):
```
Multiplies two numbers.
**Parameters:**
* **a** (float): The multiplier in the multiplication.
* **b** (float): The multiplicand in the multiplication.
* **decimal\_places** (int, optional): The number of decimal places to round to. Defaults to 2.
**Returns:**
float: The product of the two numbers.
### math\_divide
```python theme={"system"}
def math_divide(
self,
a: float,
b: float,
decimal_places: int = 2
):
```
Divides two numbers.
**Parameters:**
* **a** (float): The dividend in the division.
* **b** (float): The divisor in the division.
* **decimal\_places** (int, optional): The number of decimal places to round to. Defaults to 2.
**Returns:**
float: The result of dividing :obj:`a` by :obj:`b`.
### math\_round
```python theme={"system"}
def math_round(self, a: float, decimal_places: int = 0):
```
Rounds a number to a specified number of decimal places.
**Parameters:**
* **a** (float): The number to be rounded.
* **decimal\_places** (int, optional): The number of decimal places to round to. Defaults to 0.
**Returns:**
float: The rounded number.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
### add
```python theme={"system"}
def add(self, *args, **kwargs):
```
Deprecated: Use math\_add instead.
### sub
```python theme={"system"}
def sub(self, *args, **kwargs):
```
Deprecated: Use math\_subtract instead.
### multiply
```python theme={"system"}
def multiply(self, *args, **kwargs):
```
Deprecated: Use math\_multiply instead.
### divide
```python theme={"system"}
def divide(self, *args, **kwargs):
```
Deprecated: Use math\_divide instead.
### round
```python theme={"system"}
def round(self, *args, **kwargs):
```
Deprecated: Use math\_round instead. Note: This was shadowing
Python's built-in round().
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.mcp_toolkit
## MCPConnectionError
```python theme={"system"}
class MCPConnectionError(Exception):
```
Raised when MCP connection fails.
## MCPToolError
```python theme={"system"}
class MCPToolError(Exception):
```
Raised when MCP tool execution fails.
## ensure\_strict\_json\_schema
```python theme={"system"}
def ensure_strict_json_schema(schema: dict[str, Any]):
```
Mutates the given JSON schema to ensure it conforms to the
`strict` standard that the OpenAI API expects.
## \_ensure\_strict\_json\_schema
```python theme={"system"}
def _ensure_strict_json_schema(json_schema: object):
```
## resolve\_ref
```python theme={"system"}
def resolve_ref():
```
## is\_dict
```python theme={"system"}
def is_dict(obj: object):
```
## is\_list
```python theme={"system"}
def is_list(obj: object):
```
## has\_more\_than\_n\_keys
```python theme={"system"}
def has_more_than_n_keys(obj: dict[str, object], n: int):
```
## MCPToolkit
```python theme={"system"}
class MCPToolkit(BaseToolkit):
```
MCPToolkit provides a unified interface for managing multiple
MCP server connections and their tools.
This class handles the lifecycle of multiple MCP server connections and
offers a centralized configuration mechanism for both local and remote
MCP services. The toolkit manages multiple :obj:`MCPClient` instances and
aggregates their tools into a unified interface compatible with the CAMEL
framework.
Connection Lifecycle:
There are three ways to manage the connection lifecycle:
1. Using the async context manager (recommended):
.. code-block:: python
async with MCPToolkit(config\_path="config.json") as toolkit:
# Toolkit is connected here
tools = toolkit.get\_tools()
# Toolkit is automatically disconnected here
2. Using the factory method:
.. code-block:: python
toolkit = await MCPToolkit.create(config\_path="config.json")
# Toolkit is connected here
tools = toolkit.get\_tools()
# Don't forget to disconnect when done!
await toolkit.disconnect()
3. Using explicit connect/disconnect:
.. code-block:: python
toolkit = MCPToolkit(config\_path="config.json")
await toolkit.connect()
# Toolkit is connected here
tools = toolkit.get\_tools()
# Don't forget to disconnect when done!
await toolkit.disconnect()
**Parameters:**
* **clients** (Optional\[List\[MCPClient]], optional): List of :obj:`MCPClient` instances to manage. (default: :obj:`None`)
* **config\_path** (Optional\[str], optional): Path to a JSON configuration file defining MCP servers. The file should contain server configurations in the standard MCP format. (default: :obj:`None`)
* **config\_dict** (Optional\[Dict\[str, Any]], optional): Dictionary containing MCP server configurations in the same format as the config file. This allows for programmatic configuration without file I/O. (default: :obj:`None`)
* **timeout** (Optional\[float], optional): Timeout for connection attempts in seconds. This timeout applies to individual client connections. (default: :obj:`None`)
* **clients** (List\[MCPClient]): List of :obj:`MCPClient` instances being managed by this toolkit.
### **init**
```python theme={"system"}
def __init__(
self,
clients: Optional[List[MCPClient]] = None,
config_path: Optional[str] = None,
config_dict: Optional[Dict[str, Any]] = None,
timeout: Optional[float] = None
):
```
### is\_connected
```python theme={"system"}
def is_connected(self):
```
**Returns:**
bool: True if the toolkit is connected to all MCP servers,
False otherwise.
### connect\_sync
```python theme={"system"}
def connect_sync(self):
```
Synchronously connect to all MCP servers.
### disconnect\_sync
```python theme={"system"}
def disconnect_sync(self):
```
Synchronously disconnect from all MCP servers.
### **enter**
```python theme={"system"}
def __enter__(self):
```
Synchronously enter the async context manager.
### **exit**
```python theme={"system"}
def __exit__(
self,
exc_type,
exc_val,
exc_tb
):
```
Synchronously exit the async context manager.
### create\_sync
```python theme={"system"}
def create_sync(
cls,
clients: Optional[List[MCPClient]] = None,
config_path: Optional[str] = None,
config_dict: Optional[Dict[str, Any]] = None,
timeout: Optional[float] = None
):
```
Synchronously create and connect to all MCP servers.
### \_load\_clients\_from\_config
```python theme={"system"}
def _load_clients_from_config(self, config_path: str):
```
Load clients from configuration file.
### \_load\_clients\_from\_dict
```python theme={"system"}
def _load_clients_from_dict(self, config: Dict[str, Any]):
```
Load clients from configuration dictionary.
### \_create\_client\_from\_config
```python theme={"system"}
def _create_client_from_config(self, name: str, cfg: Dict[str, Any]):
```
Create a single MCP client from configuration.
### \_ensure\_strict\_tool\_schema
```python theme={"system"}
def _ensure_strict_tool_schema(self, tool: FunctionTool):
```
Ensure a tool has a strict schema compatible with
OpenAI's requirements.
Strategy:
* Ensure parameters exist with at least an empty properties object
(OpenAI requirement).
* Try converting parameters to strict using ensure\_strict\_json\_schema.
* If conversion fails, mark function.strict = False and
keep best-effort parameters.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: Combined list of all available function tools
from all connected MCP servers with strict schemas. Returns an
empty list if no clients are connected or if no tools are
available.
### get\_text\_tools
```python theme={"system"}
def get_text_tools(self):
```
**Returns:**
str: A string containing the descriptions of all tools.
### call\_tool\_sync
```python theme={"system"}
def call_tool_sync(self, tool_name: str, tool_args: Dict[str, Any]):
```
Synchronously call a tool.
### list\_available\_tools
```python theme={"system"}
def list_available_tools(self):
```
**Returns:**
Dict\[str, List\[str]]: Dictionary mapping client indices to tool
names.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.memory_toolkit
## MemoryToolkit
```python theme={"system"}
class MemoryToolkit(BaseToolkit):
```
A toolkit that provides methods for saving, loading, and clearing a
ChatAgent's memory.
These methods are exposed as FunctionTool objects for
function calling. Internally, it calls:
* agent.save\_memory(path)
* agent.load\_memory(new\_memory\_obj)
* agent.load\_memory\_from\_path(path)
* agent.clear\_memory()
**Parameters:**
* **agent** (ChatAgent): The chat agent whose memory will be managed.
* **timeout** (Optional\[float], optional): Maximum execution time allowed for toolkit operations in seconds. If None, no timeout is applied. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, agent: 'ChatAgent', timeout: Optional[float] = None):
```
### save
```python theme={"system"}
def save(self, path: str):
```
Saves the agent's current memory to a JSON file.
**Parameters:**
* **path** (str): The file path to save the memory to.
**Returns:**
str: Confirmation message.
### load
```python theme={"system"}
def load(self, memory_json: str):
```
Loads memory into the agent from a JSON string.
**Parameters:**
* **memory\_json** (str): A JSON string containing memory records.
**Returns:**
str: Confirmation or error message.
### load\_from\_path
```python theme={"system"}
def load_from_path(self, path: str):
```
Loads the agent's memory from a JSON file.
**Parameters:**
* **path** (str): The file path to load the memory from.
**Returns:**
str: Confirmation message.
### clear\_memory
```python theme={"system"}
def clear_memory(self):
```
**Returns:**
str: Confirmation message.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
list\[FunctionTool]: List of FunctionTool objects.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.meshy_toolkit
## MeshyToolkit
```python theme={"system"}
class MeshyToolkit(BaseToolkit):
```
A class representing a toolkit for 3D model generation using Meshy.
This class provides methods that handle text/image to 3D model
generation using Meshy.
Call the generate\_3d\_model\_complete method to generate a refined 3D model.
Ref:
[https://docs.meshy.ai/api-text-to-3d-beta#create-a-text-to-3d-preview-task](https://docs.meshy.ai/api-text-to-3d-beta#create-a-text-to-3d-preview-task)
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the MeshyToolkit with the API key from the
environment.
### generate\_3d\_preview
```python theme={"system"}
def generate_3d_preview(
self,
prompt: str,
art_style: str,
negative_prompt: str
):
```
Generates a 3D preview using the Meshy API.
**Parameters:**
* **prompt** (str): Description of the object.
* **art\_style** (str): Art style for the 3D model.
* **negative\_prompt** (str): What the model should not look like.
**Returns:**
Dict\[str, Any]: The result property of the response contains the
task id of the newly created Text to 3D task.
### refine\_3d\_model
```python theme={"system"}
def refine_3d_model(self, preview_task_id: str):
```
Refines a 3D model using the Meshy API.
**Parameters:**
* **preview\_task\_id** (str): The task ID of the preview to refine.
**Returns:**
Dict\[str, Any]: The response from the Meshy API.
### get\_task\_status
```python theme={"system"}
def get_task_status(self, task_id: str):
```
Retrieves the status or result of a specific 3D model generation
task using the Meshy API.
**Parameters:**
* **task\_id** (str): The ID of the task to retrieve.
**Returns:**
Dict\[str, Any]: The response from the Meshy API.
### wait\_for\_task\_completion
```python theme={"system"}
def wait_for_task_completion(
self,
task_id: str,
polling_interval: int = 10,
timeout: int = 3600
):
```
Waits for a task to complete by polling its status.
**Parameters:**
* **task\_id** (str): The ID of the task to monitor.
* **polling\_interval** (int): Seconds to wait between status checks. (default: :obj:`10`)
* **timeout** (int): Maximum seconds to wait before timing out. (default: :obj:`3600`)
**Returns:**
Dict\[str, Any]: Final response from the API when task completes.
### generate\_3d\_model\_complete
```python theme={"system"}
def generate_3d_model_complete(
self,
prompt: str,
art_style: str,
negative_prompt: str
):
```
Generates a complete 3D model by handling preview and refinement
stages
**Parameters:**
* **prompt** (str): Description of the object.
* **art\_style** (str): Art style for the 3D model.
* **negative\_prompt** (str): What the model should not look like.
**Returns:**
Dict\[str, Any]: The final refined 3D model response.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.message_agent_toolkit
## AgentMessage
```python theme={"system"}
class AgentMessage(BaseMessage):
```
Represents a message between agents, extending BaseMessage.
This class extends the standard CAMEL BaseMessage with additional
attributes needed for inter-agent communication.
### **init**
```python theme={"system"}
def __init__(
self,
message_id: str,
sender_id: str,
receiver_id: str,
content: str,
timestamp: float,
reply_to: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None
):
```
## AgentCommunicationToolkit
```python theme={"system"}
class AgentCommunicationToolkit(BaseToolkit):
```
A toolkit for agent-to-agent communication in multi-agent systems.
Enables agents to send messages to each other with message history tracking
and integration with the CAMEL workforce system.
**Parameters:**
* **agents** (Optional\[Dict\[str, ChatAgent]]): Dictionary mapping agent IDs to ChatAgent instances. (default: :obj:`None`)
* **timeout** (Optional\[float]): Maximum execution time for operations in seconds. (default: :obj:`None`)
* **max\_message\_history** (int): Maximum messages to keep per agent. (default: :obj:`100`)
* **get\_response** (bool): Whether to get responses from receiving agents by default. (default: :obj:`False`)
### **init**
```python theme={"system"}
def __init__(
self,
agents: Optional[Dict[str, 'ChatAgent']] = None,
timeout: Optional[float] = None,
max_message_history: int = 100,
get_response: bool = False
):
```
### register\_agent
```python theme={"system"}
def register_agent(self, agent_id: str, agent: 'ChatAgent'):
```
Register a new agent for communication.
**Parameters:**
* **agent\_id** (str): Unique identifier for the agent.
* **agent** (ChatAgent): The ChatAgent instance to register.
**Returns:**
str: Confirmation message with registration details.
### \_find\_agent\_id
```python theme={"system"}
def _find_agent_id(self, agent_id: str):
```
Find agent ID with flexible matching (case-insensitive, partial
matches).
### send\_message
```python theme={"system"}
def send_message(
self,
message: str,
receiver_id: str,
sender_id: str = 'system',
reply_to: Optional[str] = None,
metadata_json: Optional[str] = None
):
```
Sends a message to a specific agent.
This function allows one agent to communicate directly with another by
sending a message. The toolkit's get\_response setting determines
whether to get an immediate response or just send a notification. To
get the `receiver_id` of the agent you want to communicate with, you
can use the `list_available_agents` tool.
**Parameters:**
* **message** (str): The content of the message to send.
* **receiver\_id** (str): The unique identifier of the agent to receive the message. Use `list_available_agents()` to find the ID of the agent you want to talk to.
* **sender\_id** (str): The unique identifier of the agent sending the message. This is typically your agent's ID. (default: :obj:`"system"`)
* **reply\_to** (Optional\[str]): The ID of a previous message this new message is a reply to. This helps create conversation threads. (default: :obj:`None`)
* **metadata\_json** (Optional\[str]): A JSON string containing extra information about the message. (default: :obj:`None`)
**Returns:**
str: A confirmation that the message was sent. If the toolkit's
get\_response setting is True, includes the response from the
receiving agent.
### \_deliver\_message
```python theme={"system"}
def _deliver_message(self, message: AgentMessage, get_response: bool):
```
Deliver a message to the target agent, optionally getting a
response.
### broadcast\_message
```python theme={"system"}
def broadcast_message(
self,
message: str,
sender_id: str = 'system',
exclude_agents: Optional[List[str]] = None
):
```
Sends a message to all other agents in the system.
This function is useful for making announcements or sending information
that every agent needs. The message will be sent to all registered
agents except for the sender and any agents specified in the
`exclude_agents` list.
**Parameters:**
* **message** (str): The content of the message to broadcast.
* **sender\_id** (str): The unique identifier of the agent sending the message. This is typically your agent's ID. (default: :obj:`"system"`)
* **exclude\_agents** (Optional\[List\[str]]): A list of agent IDs to exclude from the broadcast. The sender is automatically excluded. (default: :obj:`None`)
**Returns:**
str: A summary of the broadcast, showing which agents received the
message and their responses.
### get\_message\_history
```python theme={"system"}
def get_message_history(self, agent_id: str, limit: Optional[int] = None):
```
Retrieves the message history for a specific agent.
This function allows you to see the messages sent and received by a
particular agent, which can be useful for understanding past
conversations. To get the `agent_id` for another agent, use the
`list_available_agents` tool. You can also use this tool to get
your own message history by providing your agent ID.
**Parameters:**
* **agent\_id** (str): The unique identifier of the agent whose message history you want to retrieve. Use `list_available_agents()` to find available agent IDs.
* **limit** (Optional\[int]): The maximum number of recent messages to return. If not specified, it will return all messages up to the system's limit. (default: :obj:`None`)
**Returns:**
str: A formatted string containing the message history for the
specified agent, or an error if the agent is not found.
### get\_conversation\_thread
```python theme={"system"}
def get_conversation_thread(self, message_id: str):
```
Retrieves a full conversation thread based on a message ID.
When you send a message that is a reply to another, it creates a
conversation thread. This function lets you retrieve all messages
that are part of that thread. You can find message IDs in the
message history or from the output of the `send_message` tool.
**Parameters:**
* **message\_id** (str): The unique identifier of any message within the conversation thread you want to retrieve.
**Returns:**
str: A formatted string containing all messages in the
conversation, sorted by time, or an error if the thread is
not found.
### list\_available\_agents
```python theme={"system"}
def list_available_agents(self):
```
**Returns:**
str: A formatted string listing the IDs and status of all
available agents.
### remove\_agent
```python theme={"system"}
def remove_agent(self, agent_id: str):
```
Remove an agent from the communication registry.
**Parameters:**
* **agent\_id** (str): Unique identifier of the agent to remove.
**Returns:**
str: Confirmation message with cleanup details.
### get\_toolkit\_status
```python theme={"system"}
def get_toolkit_status(self):
```
**Returns:**
str: Detailed status information including metrics and queue state.
### \_add\_to\_history
```python theme={"system"}
def _add_to_history(self, message: AgentMessage):
```
Add a message to the history with size management.
### \_update\_conversation\_thread
```python theme={"system"}
def _update_conversation_thread(self, parent_id: str, new_id: str):
```
Update conversation threading.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Returns a list of FunctionTool objects representing the
communication functions in the toolkit.
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects for agent
communication and management.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.message_integration
## ToolkitMessageIntegration
```python theme={"system"}
class ToolkitMessageIntegration:
```
### **init**
```python theme={"system"}
def __init__(
self,
message_handler: Optional[Callable] = None,
extract_params_callback: Optional[Callable[[dict], tuple]] = None
):
```
Initialize the toolkit message integration.
**Parameters:**
* **message\_handler** (Optional\[Callable]): Custom message handler function. If not provided, uses the built-in send\_message\_to\_user. (default: :obj:`None`)
* **extract\_params\_callback** (Optional\[Callable]): Function to extract parameters from kwargs for the custom message handler. Should return a tuple of arguments to pass to the message handler. If not provided, uses default extraction for built-in handler. (default: :obj:`None`)
### \_default\_extract\_params
```python theme={"system"}
def _default_extract_params(self, kwargs: dict):
```
Default parameter extraction for built-in message handler.
### send\_message\_to\_user
```python theme={"system"}
def send_message_to_user(
self,
message_title: str,
message_description: str,
message_attachment: str = ''
):
```
Built-in message handler that sends tidy messages to the user.
This one-way tool keeps the user informed about agent progress,
decisions, or actions. It does not require a response.
**Parameters:**
* **message\_title** (str): The title of the message.
* **message\_description** (str): The short description message.
* **message\_attachment** (str): The additional attachment of the message, which can be a file path or a URL.
**Returns:**
str: Confirmation that the message was successfully sent.
### get\_message\_tool
```python theme={"system"}
def get_message_tool(self):
```
**Returns:**
FunctionTool: The message sending tool.
### register\_toolkits
```python theme={"system"}
def register_toolkits(self, toolkit: BaseToolkit):
```
Add messaging capabilities to all toolkit methods.
This method modifies a toolkit so that all its tools can send
status messages to users while executing their primary function.
The tools will accept optional messaging parameters:
* message\_title: Title of the status message
* message\_description: Description of what the tool is doing
* message\_attachment: Optional file path or URL
**Parameters:**
* **toolkit**: The toolkit to add messaging capabilities to
**Returns:**
The same toolkit instance with messaging capabilities added to
all methods.
### \_create\_bound\_method\_wrapper
```python theme={"system"}
def _create_bound_method_wrapper(self, enhanced_func: Callable, toolkit_instance):
```
Create a wrapper that mimics a bound method for \_clone\_tools.
This wrapper preserves the toolkit instance reference while maintaining
the enhanced messaging functionality.
### register\_functions
```python theme={"system"}
def register_functions(
self,
functions: Union[List[FunctionTool], List[Callable]],
function_names: Optional[List[str]] = None
):
```
Add messaging capabilities to a list of functions or FunctionTools.
This method enhances functions so they can send status messages to
users while executing. The enhanced functions will accept optional
messaging parameters that trigger status updates.
**Parameters:**
* **functions** (Union\[List\[FunctionTool], List\[Callable]]): List of FunctionTool objects or callable functions to enhance.
* **function\_names** (Optional\[List\[str]]): List of specific function names to modify. If None, messaging is added to all functions.
**Returns:**
List\[FunctionTool]: List of enhanced FunctionTool objects
### \_add\_messaging\_to\_tool
```python theme={"system"}
def _add_messaging_to_tool(self, func: Callable):
```
Add messaging parameters to a tool function.
This internal method modifies the function signature and docstring
to include optional messaging parameters that trigger status updates.
### \_find\_docstring\_insert\_point
```python theme={"system"}
def _find_docstring_insert_point(self, lines: List[str]):
```
Find where to insert parameters in a docstring.
### \_get\_docstring\_indent
```python theme={"system"}
def _get_docstring_indent(self, lines: List[str], insert_idx: int):
```
Get the proper indentation for docstring parameters.
### \_get\_base\_indent
```python theme={"system"}
def _get_base_indent(self, lines: List[str]):
```
Get the base indentation level of the docstring.
### \_extract\_param\_docs\_from\_handler
```python theme={"system"}
def _extract_param_docs_from_handler(self):
```
Extract parameter documentation from the custom handler's
docstring.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.mineru_toolkit
## MinerUToolkit
```python theme={"system"}
class MinerUToolkit(BaseToolkit):
```
Toolkit for extracting and processing document content
using MinerU API.
Provides comprehensive document processing capabilities including content
extraction from URLs and files, with support for OCR, formula recognition,
and table detection through the MinerU API service.
**Note:**
* Maximum file size: 200MB per file
* Maximum pages: 600 pages per file
* Daily quota: 2000 pages for high-priority parsing
* Network restrictions may affect certain URLs (e.g., GitHub, AWS)
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
api_url: Optional[str] = 'https://mineru.net/api/v4',
is_ocr: bool = False,
enable_formula: bool = False,
enable_table: bool = True,
layout_model: str = 'doclayout_yolo',
language: str = 'en',
wait: bool = True,
timeout: float = 300
):
```
Initialize the MinerU document processing toolkit.
**Parameters:**
* **api\_key** (Optional\[str]): Authentication key for MinerU API access. If not provided, uses MINERU\_API\_KEY environment variable. (default: :obj:`None`)
* **api\_url** (Optional\[str]): Base endpoint URL for MinerU API service. (default: :obj:`"https://mineru.net/api/v4"`)
* **is\_ocr** (bool): Enable Optical Character Recognition for image-based text extraction. (default: :obj:`False`)
* **enable\_formula** (bool): Enable mathematical formula detection and recognition. (default: :obj:`False`)
* **enable\_table** (bool): Enable table structure detection and extraction. (default: :obj:`True`)
* **layout\_model** (str): Document layout analysis model selection. Available options: 'doclayout\_yolo', 'layoutlmv3'. (default: :obj:`"doclayout_yolo"`)
* **language** (str): Primary language of the document for processing. (default: :obj:`"en"`)
* **wait** (bool): Block execution until processing completion. (default: :obj:`True`)
* **timeout** (float): Maximum duration in seconds to wait for task completion. (default: :obj:`300`)
### extract\_from\_urls
```python theme={"system"}
def extract_from_urls(self, urls: str | List[str]):
```
Process and extract content from one or multiple URLs.
**Parameters:**
* **urls** (str | List\[str]): Target URL or list of URLs for content extraction. Supports both single URL string and multiple URLs in a list.
**Returns:**
Dict: Response containing either completed task results when wait
is True, or task/batch identifiers for status tracking when
wait is False.
### get\_task\_status
```python theme={"system"}
def get_task_status(self, task_id: str):
```
Retrieve current status of an individual extraction task.
**Parameters:**
* **task\_id** (str): Unique identifier for the extraction task to check.
**Returns:**
Dict: Status information and results (if task is completed) for
the specified task.
**Note:**
This is a low-level status checking method. For most use cases,
prefer using extract\_from\_url with wait=True for automatic
completion handling.
### get\_batch\_status
```python theme={"system"}
def get_batch_status(self, batch_id: str):
```
Retrieve current status of a batch extraction task.
**Parameters:**
* **batch\_id** (str): Unique identifier for the batch extraction task to check.
**Returns:**
Dict: Comprehensive status information and results for all files
in the batch task.
**Note:**
This is a low-level status checking method. For most use cases,
prefer using batch\_extract\_from\_urls with wait=True for automatic
completion handling.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: Collection of FunctionTool objects representing
the available document processing functions in this toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.minimax_mcp_toolkit
## MinimaxMCPToolkit
```python theme={"system"}
class MinimaxMCPToolkit(BaseToolkit):
```
MinimaxMCPToolkit provides an interface for interacting with
MiniMax AI services using the MiniMax MCP server.
This toolkit enables access to MiniMax's multimedia generation
capabilities including text-to-audio, voice cloning, video generation,
image generation, music generation, and voice design.
This toolkit can be used as an async context manager for automatic
connection management:
# Using explicit API key
async with MinimaxMCPToolkit(api\_key="your-key") as toolkit:
tools = toolkit.get\_tools()
# Toolkit is automatically disconnected when exiting
# Using environment variables (recommended for security)
# Set MINIMAX\_API\_KEY=your-key in environment
async with MinimaxMCPToolkit() as toolkit:
tools = toolkit.get\_tools()
Environment Variables:
MINIMAX\_API\_KEY: MiniMax API key for authentication
MINIMAX\_API\_HOST: API host URL (default: [https://api.minimax.io](https://api.minimax.io))
MINIMAX\_MCP\_BASE\_PATH: Base path for output files
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
api_key: Optional[str] = None,
api_host: str = 'https://api.minimax.io',
base_path: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initializes the MinimaxMCPToolkit.
**Parameters:**
* **api\_key** (Optional\[str]): MiniMax API key for authentication. If None, will attempt to read from MINIMAX\_API\_KEY environment variable. (default: :obj:`None`)
* **api\_host** (str): MiniMax API host URL. Can be either "[https://api.minimax.io](https://api.minimax.io)" (global) or "[https://api.minimaxi.com](https://api.minimaxi.com)" (mainland China). Can also be read from MINIMAX\_API\_HOST environment variable. (default: :obj:`"https://api.minimax.io"`)
* **base\_path** (Optional\[str]): Base path for output files. If None, uses current working directory. Can also be read from MINIMAX\_MCP\_BASE\_PATH environment variable. (default: :obj:`None`)
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
### is\_connected
```python theme={"system"}
def is_connected(self):
```
**Returns:**
bool: True if connected, False otherwise.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available MiniMax AI tools.
### get\_text\_tools
```python theme={"system"}
def get_text_tools(self):
```
**Returns:**
str: A string containing the descriptions of all MiniMax tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.networkx_toolkit
## NetworkXToolkit
```python theme={"system"}
class NetworkXToolkit(BaseToolkit):
```
### \_get\_nx
```python theme={"system"}
def _get_nx(cls):
```
Lazily import networkx module when needed.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
graph_type: Literal['graph', 'digraph', 'multigraph', 'multidigraph'] = 'graph'
):
```
Initializes the NetworkX graph client.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### add\_node
```python theme={"system"}
def add_node(self, node_id: str, **attributes: Any):
```
Adds a node to the graph.
**Parameters:**
* **node\_id** (str): The ID of the node.
* **attributes** (dict): Additional node attributes.
### add\_edge
```python theme={"system"}
def add_edge(
self,
source: str,
target: str,
**attributes: Any
):
```
Adds an edge to the graph.
**Parameters:**
* **source** (str): Source node ID.
* **target** (str): Target node ID.
* **attributes** (dict): Additional edge attributes.
### get\_nodes
```python theme={"system"}
def get_nodes(self):
```
**Returns:**
List\[str]: A list of node IDs.
### get\_edges
```python theme={"system"}
def get_edges(self):
```
**Returns:**
List\[Tuple\[str, str]]: A list of edges as (source, target).
### get\_shortest\_path
```python theme={"system"}
def get_shortest_path(
self,
source: str,
target: str,
weight: Optional[Union[str, Callable]] = None,
method: Literal['dijkstra', 'bellman-ford'] = 'dijkstra'
):
```
Finds the shortest path between two nodes.
**Parameters:**
* **method** (`Literal['dijkstra', 'bellman-ford'], optional`): Algorithm to compute the path. Ignored if weight is None. (default: :obj:`'dijkstra'`)
**Returns:**
List\[str]: A list of nodes in the shortest path.
### compute\_centrality
```python theme={"system"}
def compute_centrality(self):
```
**Returns:**
Dict\[str, float]: Centrality values for each node.
### serialize\_graph
```python theme={"system"}
def serialize_graph(self):
```
**Returns:**
str: The serialized graph in JSON format.
### deserialize\_graph
```python theme={"system"}
def deserialize_graph(self, data: str):
```
Loads a graph from a serialized JSON string.
**Parameters:**
* **data** (str): The JSON string representing the graph.
### export\_to\_file
```python theme={"system"}
def export_to_file(self, file_path: str):
```
Exports the graph to a file in JSON format.
**Parameters:**
* **file\_path** (str): The file path to save the graph.
### import\_from\_file
```python theme={"system"}
def import_from_file(self, file_path: str):
```
Imports a graph from a JSON file.
**Parameters:**
* **file\_path** (str): The file path to load the graph from.
### clear\_graph
```python theme={"system"}
def clear_graph(self):
```
Clears the current graph.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects for the
toolkit methods.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.non_visual_browser_toolkit.actions
## ActionExecutor
```python theme={"system"}
class ActionExecutor:
```
Executes high-level actions (click, type …) on a Playwright Page.
### **init**
```python theme={"system"}
def __init__(self, page: 'Page'):
```
### should\_update\_snapshot
```python theme={"system"}
def should_update_snapshot(action: Dict[str, Any]):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.non_visual_browser_toolkit.agent
## PlaywrightLLMAgent
```python theme={"system"}
class PlaywrightLLMAgent:
```
High-level orchestration: snapshot ↔ LLM ↔ action executor.
### **init**
```python theme={"system"}
def __init__(self):
```
### \_get\_chat\_agent
```python theme={"system"}
def _get_chat_agent(self):
```
Get or create the ChatAgent instance.
### \_safe\_parse\_json
```python theme={"system"}
def _safe_parse_json(self, content: str):
```
Safely parse JSON from LLM response with multiple fallback
strategies.
### \_llm\_call
```python theme={"system"}
def _llm_call(
self,
prompt: str,
snapshot: str,
is_initial: bool,
history: Optional[List[Dict[str, Any]]] = None
):
```
Call the LLM (via CAMEL ChatAgent) to get plan & next action.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.non_visual_browser_toolkit.browser_non_visual_toolkit
## BrowserNonVisualToolkit
```python theme={"system"}
class BrowserNonVisualToolkit(BaseToolkit):
```
A lightweight, *non-visual* browser toolkit exposing primitive
Playwright actions as CAMEL `FunctionTool`s.
### **init**
```python theme={"system"}
def __init__(self):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Best-effort cleanup when toolkit is garbage collected.
1. We *avoid* running during the Python interpreter shutdown phase
(`sys.is_finalizing()`), because the import machinery and/or event
loop may already be torn down which leads to noisy exceptions such
as `ImportError: sys.meta_path is None` or
`RuntimeError: Event loop is closed`.
2. We protect all imports and event-loop operations with defensive
`try/except` blocks. This ensures that, even if cleanup cannot be
carried out, we silently ignore the failure instead of polluting
stderr on program exit.
### \_validate\_ref
```python theme={"system"}
def _validate_ref(self, ref: str, method_name: str):
```
Validate that ref parameter is a non-empty string.
### \_ensure\_agent
```python theme={"system"}
def _ensure_agent(self):
```
Create PlaywrightLLMAgent on first use if `web_agent_model`
provided.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.non_visual_browser_toolkit.nv_browser_session
## HybridBrowserSession
```python theme={"system"}
class HybridBrowserSession:
```
Lightweight wrapper around Playwright for non-visual (headless)
browsing.
It provides a single *Page* instance plus helper utilities (snapshot &
executor). Multiple toolkits or agents can reuse this class without
duplicating Playwright setup code.
This class is a singleton per event-loop.
### **new**
```python theme={"system"}
def __new__(cls):
```
### **init**
```python theme={"system"}
def __init__(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.non_visual_browser_toolkit.snapshot
## PageSnapshot
```python theme={"system"}
class PageSnapshot:
```
Utility for capturing YAML-like page snapshots and diff-only
variants.
### **init**
```python theme={"system"}
def __init__(self, page: 'Page'):
```
### \_format\_snapshot
```python theme={"system"}
def _format_snapshot(text: str):
```
### \_compute\_diff
```python theme={"system"}
def _compute_diff(old: str, new: str):
```
### \_detect\_priorities
```python theme={"system"}
def _detect_priorities(self, snapshot_yaml: str):
```
Return sorted list of priorities present (1,2,3).
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.note_taking_toolkit
## NoteTakingToolkit
```python theme={"system"}
class NoteTakingToolkit(BaseToolkit):
```
A toolkit for managing and interacting with markdown note files.
This toolkit provides tools for creating, reading, appending to, and
listing notes. All notes are stored as `.md` files in a dedicated working
directory and are tracked in a registry.
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initialize the NoteTakingToolkit.
**Parameters:**
* **working\_directory** (str, optional): The directory path where notes will be stored. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.
* **timeout** (Optional\[float]): The timeout for the toolkit.
### append\_note
```python theme={"system"}
def append_note(self, note_name: str, content: str):
```
Appends content to a note.
If the note does not exist, it will be created with the given content.
If the note already exists, the new content will be added to the end of
the note.
**Parameters:**
* **note\_name** (str): The name of the note (without the .md extension).
* **content** (str): The content to append to the note.
**Returns:**
str: A message confirming that the content was appended or the note
was created.
### \_load\_registry
```python theme={"system"}
def _load_registry(self):
```
Load the note registry from file.
### \_save\_registry
```python theme={"system"}
def _save_registry(self):
```
Save the note registry to file using atomic write.
### \_register\_note
```python theme={"system"}
def _register_note(self, note_name: str):
```
Register a new note in the registry with thread-safe operations.
### create\_note
```python theme={"system"}
def create_note(
self,
note_name: str,
content: str,
overwrite: bool = False
):
```
Creates a new note with a unique name.
This function will create a new file for your note.
By default, you must provide a `note_name` that does not already exist.
If you want to add content to an existing note, use the `append_note`
function instead. If you want to overwrite an existing note, set
`overwrite=True`.
**Parameters:**
* **note\_name** (str): The name for your new note (without the .md extension). This name must be unique unless overwrite is True.
* **content** (str): The initial content to write in the note.
* **overwrite** (bool): Whether to overwrite an existing note. Defaults to False.
**Returns:**
str: A message confirming the creation of the note or an error if
the note name is not valid or already exists
(when overwrite=False).
### list\_note
```python theme={"system"}
def list_note(self):
```
**Returns:**
str: A string containing a list of available notes and their sizes,
or a message indicating that no notes have been created yet.
### read\_note
```python theme={"system"}
def read_note(self, note_name: Optional[str] = 'all_notes'):
```
Reads the content of a specific note or all notes.
You can use this function in two ways:
1. **Read a specific note:** Provide the `note_name` (without the .md
extension) to get the content of that single note.
2. **Read all notes:** Use `note_name="all_notes"` (default), and this
function will return the content of all your notes, concatenated
together.
**Parameters:**
* **note\_name** (str, optional): The name of the note you want to read. Defaults to "all\_notes" which reads all notes.
**Returns:**
str: The content of the specified note(s), or an error message if
a note cannot be read.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.notion_mcp_toolkit
## NotionMCPToolkit
```python theme={"system"}
class NotionMCPToolkit(MCPToolkit):
```
NotionMCPToolkit provides an interface for interacting with Notion
through the Model Context Protocol (MCP).
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
**Note:**
Currently only supports asynchronous operation mode.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the NotionMCPToolkit.
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available tools.
### \_build\_notion\_tool\_schema
```python theme={"system"}
def _build_notion_tool_schema(self, mcp_tool, original_build_schema):
```
Build tool schema with Notion-specific fixes.
### \_fix\_notion\_schema\_recursively
```python theme={"system"}
def _fix_notion_schema_recursively(self, obj: Any):
```
Recursively fix Notion MCP schema issues.
### \_fix\_dict\_schema
```python theme={"system"}
def _fix_dict_schema(self, obj: Dict[str, Any]):
```
Fix dictionary schema issues.
### \_fix\_missing\_type\_with\_properties
```python theme={"system"}
def _fix_missing_type_with_properties(self, obj: Dict[str, Any]):
```
Fix objects with properties but missing type field.
### \_fix\_object\_with\_properties
```python theme={"system"}
def _fix_object_with_properties(self, obj: Dict[str, Any]):
```
Fix objects with type="object" and properties.
### \_get\_required\_properties
```python theme={"system"}
def _get_required_properties(self, properties: Dict[str, Any], conservative: bool = False):
```
Get list of required properties from a properties dict.
### \_is\_property\_required
```python theme={"system"}
def _is_property_required(self, prop_schema: Dict[str, Any]):
```
Check if a property should be marked as required.
### \_process\_nested\_structures
```python theme={"system"}
def _process_nested_structures(self, obj: Dict[str, Any]):
```
Process all nested structures in a schema object.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.notion_toolkit
## get\_plain\_text\_from\_rich\_text
```python theme={"system"}
def get_plain_text_from_rich_text(rich_text: List[dict]):
```
Extracts plain text from a list of rich text elements.
**Parameters:**
* **rich\_text**: A list of dictionaries representing rich text elements. Each dictionary should contain a key named "plain\_text" with the plain text content.
**Returns:**
str: A string containing the combined plain text from all elements,
joined together.
## get\_media\_source\_text
```python theme={"system"}
def get_media_source_text(block: dict):
```
Extracts the source URL and optional caption from a
Notion media block.
**Parameters:**
* **block**: A dictionary representing a Notion media block.
**Returns:**
A string containing the source URL and caption (if available),
separated by a colon.
## NotionToolkit
```python theme={"system"}
class NotionToolkit(BaseToolkit):
```
A toolkit for retrieving information from the user's notion pages.
**Parameters:**
* **notion\_token** (Optional\[str], optional): The notion\_token used to interact with notion APIs. (default: :obj:`None`)
* **notion\_client** (module): The notion module for interacting with the notion APIs.
### **init**
```python theme={"system"}
def __init__(
self,
notion_token: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initializes the NotionToolkit.
**Parameters:**
* **notion\_token** (Optional\[str], optional): The optional notion\_token used to interact with notion APIs.(default: :obj:`None`)
### list\_all\_users
```python theme={"system"}
def list_all_users(self):
```
**Returns:**
List\[dict]: A list of user objects with type, name, and workspace.
### list\_all\_pages
```python theme={"system"}
def list_all_pages(self):
```
**Returns:**
List\[dict]: A list of page objects with title and id.
### get\_notion\_block\_text\_content
```python theme={"system"}
def get_notion_block_text_content(self, block_id: str):
```
Retrieves the text content of a Notion block.
**Parameters:**
* **block\_id** (str): The ID of the Notion block to retrieve.
**Returns:**
str: The text content of a Notion block, containing all
the sub blocks.
### get\_text\_from\_block
```python theme={"system"}
def get_text_from_block(self, block: dict):
```
Extracts plain text from a Notion block based on its type.
**Parameters:**
* **block** (dict): A dictionary representing a Notion block.
**Returns:**
str: A string containing the extracted plain text and block type.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.open_api_toolkit
## OpenAPIToolkit
```python theme={"system"}
class OpenAPIToolkit:
```
A class representing a toolkit for interacting with OpenAPI APIs.
This class provides methods for interacting with APIs based on OpenAPI
specifications. It dynamically generates functions for each API operation
defined in the OpenAPI specification, allowing users to make HTTP requests
to the API endpoints.
### parse\_openapi\_file
```python theme={"system"}
def parse_openapi_file(self, openapi_spec_path: str):
```
Load and parse an OpenAPI specification file.
This function utilizes the `prance.ResolvingParser` to parse and
resolve the given OpenAPI specification file, returning the parsed
OpenAPI specification as a dictionary.
**Parameters:**
* **openapi\_spec\_path** (str): The file path or URL to the OpenAPI specification.
**Returns:**
Optional\[Dict\[str, Any]]: The parsed OpenAPI specification
as a dictionary. :obj:`None` if the package is not installed.
### openapi\_spec\_to\_openai\_schemas
```python theme={"system"}
def openapi_spec_to_openai_schemas(self, api_name: str, openapi_spec: Dict[str, Any]):
```
Convert OpenAPI specification to OpenAI schema format.
This function iterates over the paths and operations defined in an
OpenAPI specification, filtering out deprecated operations. For each
operation, it constructs a schema in a format suitable for OpenAI,
including operation metadata such as function name, description,
parameters, and request bodies. It raises a ValueError if an operation
lacks a description or summary.
**Parameters:**
* **api\_name** (str): The name of the API, used to prefix generated function names.
* **openapi\_spec** (Dict\[str, Any]): The OpenAPI specification as a dictionary.
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries, each representing a
function in the OpenAI schema format, including details about
the function's name, description, and parameters.
**Note:**
This function assumes that the OpenAPI specification
follows the 3.0+ format.
Reference:
[https://swagger.io/specification/](https://swagger.io/specification/)
### openapi\_function\_decorator
```python theme={"system"}
def openapi_function_decorator(
self,
api_name: str,
base_url: str,
path: str,
method: str,
openapi_security: List[Dict[str, Any]],
sec_schemas: Dict[str, Dict[str, Any]],
operation: Dict[str, Any]
):
```
Decorate a function to make HTTP requests based on OpenAPI
specification details.
This decorator dynamically constructs and executes an API request based
on the provided OpenAPI operation specifications, security
requirements, and parameters. It supports operations secured with
`apiKey` type security schemes and automatically injects the necessary
API keys from environment variables. Parameters in `path`, `query`,
`header`, and `cookie` are also supported.
**Parameters:**
* **api\_name** (str): The name of the API, used to retrieve API key names and URLs from the configuration.
* **base\_url** (str): The base URL for the API.
* **path** (str): The path for the API endpoint, relative to the base URL.
* **method** (str): The HTTP method (e.g., 'get', 'post') for the request.
* **openapi\_security** (List\[Dict\[str, Any]]): The global security definitions as specified in the OpenAPI specs.
* **sec\_schemas** (Dict\[str, Dict\[str, Any]]): Detailed security schemes.
* **operation** (Dict\[str, Any]): A dictionary containing the OpenAPI operation details, including parameters and request body definitions.
**Returns:**
Callable: A decorator that, when applied to a function, enables the
function to make HTTP requests based on the provided OpenAPI
operation details.
### generate\_openapi\_funcs
```python theme={"system"}
def generate_openapi_funcs(self, api_name: str, openapi_spec: Dict[str, Any]):
```
Generates a list of Python functions based on
OpenAPI specification.
This function dynamically creates a list of callable functions that
represent the API operations defined in an OpenAPI specification
document. Each function is designed to perform an HTTP request
corresponding to an API operation (e.g., GET, POST) as defined in
the specification. The functions are decorated with
`openapi_function_decorator`, which configures them to construct and
send the HTTP requests with appropriate parameters, headers, and body
content.
**Parameters:**
* **api\_name** (str): The name of the API, used to prefix generated function names.
* **openapi\_spec** (Dict\[str, Any]): The OpenAPI specification as a dictionary.
**Returns:**
List\[Callable]: A list containing the generated functions. Each
function, when called, will make an HTTP request according to
its corresponding API operation defined in the OpenAPI
specification.
### apinames\_filepaths\_to\_funs\_schemas
```python theme={"system"}
def apinames_filepaths_to_funs_schemas(self, apinames_filepaths: List[Tuple[str, str]]):
```
Combines functions and schemas from multiple OpenAPI
specifications, using API names as keys.
This function iterates over tuples of API names and OpenAPI spec file
paths, parsing each spec to generate callable functions and schema
dictionaries, all organized by API name.
**Parameters:**
* **apinames\_filepaths** (List\[Tuple\[str, str]]): A list of tuples, where each tuple consists of: - The API name (str) as the first element. - The file path (str) to the API's OpenAPI specification file as the second element.
**Returns:**
Tuple\[List\[Callable], List\[Dict\[str, Any]]]:: one of callable
functions for API operations, and another of dictionaries
representing the schemas from the specifications.
### generate\_apinames\_filepaths
```python theme={"system"}
def generate_apinames_filepaths(self):
```
**Returns:**
List\[Tuple\[str, str]]: A list of tuples where each tuple contains
two elements. The first element of each tuple is a string
representing the name of an API, and the second element is a
string that specifies the file path to that API's OpenAPI
specification file.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.openai_image_toolkit
## OpenAIImageToolkit
```python theme={"system"}
class OpenAIImageToolkit(BaseToolkit):
```
A class toolkit for image generation using OpenAI's
Image Generation API.
### **init**
```python theme={"system"}
def __init__(
self,
model: Optional[Literal['gpt-image-1', 'dall-e-3', 'dall-e-2']] = 'gpt-image-1',
timeout: Optional[float] = None,
api_key: Optional[str] = None,
url: Optional[str] = None,
size: Optional[Literal['256x256', '512x512', '1024x1024', '1536x1024', '1024x1536', '1792x1024', '1024x1792', 'auto']] = '1024x1024',
quality: Optional[Literal['auto', 'low', 'medium', 'high', 'standard', 'hd']] = 'standard',
response_format: Optional[Literal['url', 'b64_json']] = 'b64_json',
background: Optional[Literal['transparent', 'opaque', 'auto']] = 'auto',
style: Optional[Literal['vivid', 'natural']] = None,
working_directory: Optional[str] = 'image_save'
):
```
Initializes a new instance of the OpenAIImageToolkit class.
**Parameters:**
* **api\_key** (Optional\[str]): The API key for authenticating with the OpenAI service. (default: :obj:`None`)
* **url** (Optional\[str]): The url to the OpenAI service. (default: :obj:`None`)
* **model** (Optional\[str]): The model to use. (default: :obj:`"dall-e-3"`)
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`) size (Optional\[Literal\["256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "1792x1024", "1024x1792", "auto"]]): The size of the image to generate. (default: :obj:`"1024x1024"`) quality (Optional\[Literal\["auto", "low", "medium", "high", "standard", "hd"]]):The quality of the image to generate. Different models support different values. (default: :obj:`"standard"`)
* **response\_format** (`Optional[Literal["url", "b64_json"]]`): The format of the response.(default: :obj:`"b64_json"`)
* **background** (`Optional[Literal["transparent", "opaque", "auto"]]`): The background of the image.(default: :obj:`"auto"`)
* **style** (`Optional[Literal["vivid", "natural"]]`): The style of the image.(default: :obj:`None`)
* **working\_directory** (Optional\[str]): The path to save the generated image.(default: :obj:`"image_save"`)
### base64\_to\_image
```python theme={"system"}
def base64_to_image(self, base64_string: str):
```
Converts a base64 encoded string into a PIL Image object.
**Parameters:**
* **base64\_string** (str): The base64 encoded string of the image.
**Returns:**
Optional\[Image.Image]: The PIL Image object or None if conversion
fails.
### \_build\_base\_params
```python theme={"system"}
def _build_base_params(self, prompt: str, n: Optional[int] = None):
```
Build base parameters dict for OpenAI API calls.
**Parameters:**
* **prompt** (str): The text prompt for the image operation.
* **n** (Optional\[int]): The number of images to generate.
**Returns:**
dict: Parameters dictionary with non-None values.
### \_handle\_api\_response
```python theme={"system"}
def _handle_api_response(
self,
response,
image_name: Union[str, List[str]],
operation: str
):
```
Handle API response from OpenAI image operations.
**Parameters:**
* **response**: The response object from OpenAI API.
* **image\_name** (Union\[str, List\[str]]): Name(s) for the saved image file(s). If str, the same name is used for all images (will cause error for multiple images). If list, must have exactly the same length as the number of images generated.
* **operation** (str): Operation type for success message ("generated").
**Returns:**
str: Success message with image path/URL or error message.
### generate\_image
```python theme={"system"}
def generate_image(
self,
prompt: str,
image_name: Union[str, List[str]] = 'image.png',
n: int = 1
):
```
Generate an image using OpenAI's Image Generation models.
The generated image will be saved locally (for `__INLINE_CODE_0__` response
formats) or an image URL will be returned (for `__INLINE_CODE_1__` response
formats).
**Parameters:**
* **prompt** (str): The text prompt to generate the image.
* **image\_name** (Union\[str, List\[str]]): The name(s) of the image(s) to save. The image name must end with `.png`. If str: same name used for all images (causes error if n > 1). If list: must match the number of images being generated (n parameter). (default: :obj:`"image.png"`)
* **n** (int): The number of images to generate. (default: :obj:`1`) (default: 1)
**Returns:**
str: the content of the model response or format of the response.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.openbb_toolkit
## OpenBBToolkit
```python theme={"system"}
class OpenBBToolkit(BaseToolkit):
```
A toolkit for accessing financial data and analysis through OpenBB
Platform.
This toolkit provides methods for retrieving and analyzing financial market
data, including stocks, ETFs, cryptocurrencies, economic indicators, and
more through the OpenBB Platform SDK. For credential configuration, please
refer to the OpenBB documentation
[https://my.openbb.co/app/platform/credentials](https://my.openbb.co/app/platform/credentials) .
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the OpenBBToolkit.
This method sets up the OpenBB client and initializes the OpenBB
Hub account system.
### \_handle\_api\_error
```python theme={"system"}
def _handle_api_error(
self,
error: Exception,
operation: str,
log_level: str = 'warning',
**format_args
):
```
Handle API operation errors consistently.
**Parameters:**
* **error** (Exception): The caught exception.
* **operation** (str): Description of the failed operation (e.g., "get\_historical\_data").
* **log\_level** (str): Logging level to use ("warning" or "error").
* **format\_args**: Additional format arguments for the error message .
**Returns:**
List: List with error message.
### search\_equity
```python theme={"system"}
def search_equity(self, query: str, provider: Literal['intrinio', 'sec'] = 'sec'):
```
Search for equity symbols and company information.
For SEC provider, an empty query ("") returns the complete list of
companies sorted by market cap.
**Parameters:**
* **query** (str): Search query (company name or symbol), use "" for complete SEC list.
* **provider** (`Literal["intrinio", "sec"]`): Data provider. Available
* **options**: - sec: SEC EDGAR Database (sorted by market cap) - intrinio: Intrinio Financial Data
**Returns:**
List: Search results.
### search\_institution
```python theme={"system"}
def search_institution(self, query: str):
```
Search for financial institutions in SEC database.
**Parameters:**
* **query** (str): Institution name to search (e.g., "Berkshire Hathaway").
**Returns:**
List: Institution search results.
### search\_filings
```python theme={"system"}
def search_filings(
self,
symbol: str,
provider: Literal['fmp', 'intrinio', 'sec'] = 'sec',
form_type: Optional[str] = None
):
```
Search for SEC filings by CIK or ticker symbol.
**Parameters:**
* **symbol** (str): Symbol to get data for (e.g., "MAXD").
* **provider** (`Literal["fmp", "intrinio", "sec"]`): Data provider. (default: :obj:`sec`)
* **form\_type** (Optional\[str]): Filter by form type. Check the data provider for available types. Multiple comma separated items allowed for provider(s): sec. (default: :obj:`None`)
**Returns:**
List: Filing search results.
### search\_etf
```python theme={"system"}
def search_etf(self, query: str, provider: Literal['fmp', 'intrinio'] = 'fmp'):
```
Search for ETF information.
**Parameters:**
* **query** (str): Search query (ETF name or symbol).
* **provider** (`Literal["fmp", "intrinio"]`): Data provider. (default: :obj:`fmp`)
**Returns:**
List: ETF search results.
### screen\_market
```python theme={"system"}
def screen_market(
self,
provider: Literal['fmp', 'yfinance'] = 'fmp',
country: Optional[str] = None,
exchange: Optional[str] = None,
sector: Optional[str] = None,
industry: Optional[str] = None,
mktcap_min: Optional[float] = None,
mktcap_max: Optional[float] = None,
beta_min: Optional[float] = None,
beta_max: Optional[float] = None
):
```
Screen stocks based on market and fundamental criteria.
**Parameters:**
* **provider** (`Literal["fmp", "yfinance"]`): Data provider. (default: :obj:`fmp`)
* **country** (Optional\[str]): Two-letter ISO country code (e.g., 'US', 'IN', 'CN'). (default: :obj:`None`)
* **exchange** (Optional\[str]): Stock exchange code (e.g., 'NYSE', 'AMEX', 'NSE'). (default: :obj:`None`)
* **sector** (Optional\[str]): Market sector (e.g., 'Financial Services', 'Healthcare). (default: :obj:`None`)
* **industry** (Optional\[str]): Industry within sector (e.g., 'Banks—Regional','Drug Manufacturers'). (default: :obj:`None`)
* **mktcap\_min** (Optional\[float]): Minimum market cap in USD. (default: :obj:`None`)
* **mktcap\_max** (Optional\[float]): Maximum market cap in USD. (default: :obj:`None`)
* **beta\_min** (Optional\[float]): Minimum beta value. (default: :obj:`None`)
* **beta\_max** (Optional\[float]): Maximum beta value. (default: :obj:`None`)
**Returns:**
List: Screened stocks.
### get\_available\_indices
```python theme={"system"}
def get_available_indices(self, provider: Literal['fmp', 'yfinance'] = 'fmp'):
```
Get list of available market indices.
**Parameters:**
* **provider** (`Literal["fmp", "yfinance"]`): Data provider. (default: :obj:`fmp`)
**Returns:**
List: Available indices.
### get\_stock\_quote
```python theme={"system"}
def get_stock_quote(
self,
symbol: str,
provider: Literal['fmp', 'intrinio', 'yfinance'] = 'fmp'
):
```
Get current stock quote for a given symbol.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.)
* **provider** (`Literal["fmp", "intrinio", "yfinance"]`): Data source. (default: :obj:`fmp`)
**Returns:**
List: Stock quote data in requested format
### get\_historical\_data
```python theme={"system"}
def get_historical_data(
self,
symbol: str,
provider: Literal['fmp', 'polygon', 'tiingo', 'yfinance'] = 'fmp',
asset_type: Literal['equity', 'currency', 'crypto'] = 'equity',
start_date: Optional[str] = None,
end_date: Optional[str] = None,
interval: Literal['1m', '5m', '15m', '30m', '1h', '4h', '1d'] = '1d'
):
```
Retrieves historical market data from OpenBB Platform providers.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.).
* **provider** (`Literal["fmp", "polygon", "tiingo", "yfinance"]`): Data source. (default: :obj:`fmp`)
* **asset\_type** (`Literal["equity", "currency", "crypto"]`): Asset type. (default: :obj:`equity`)
* **start\_date**: Start date in YYYY-MM-DD format. If None, uses provider's default lookback. (default: :obj:`None`)
* **end\_date**: End date in YYYY-MM-DD format. If None, uses current date. (default: :obj:`None`)
* **interval**: Data frequency/timeframe. (default: :obj:`1d`) (default: 1d)
**Returns:**
List: Historical market data.
### get\_market\_data
```python theme={"system"}
def get_market_data(
self,
category: Literal['gainers', 'losers', 'active'] = 'active'
):
```
Get market movers data.
**Parameters:**
* **category** (`Literal["gainers", "losers", "active"]`): Type of market data. Must be 'gainers', 'losers', or 'active'. (default: :obj:`active`)
**Returns:**
List: Market movers data.
### get\_earnings\_calendar
```python theme={"system"}
def get_earnings_calendar(
self,
start_date: Optional[str] = None,
end_date: Optional[str] = None
):
```
Get company earnings calendar with filtering and sorting options.
**Parameters:**
* **start\_date** (Optional\[str]): Start date in YYYY-MM-DD format. (default: :obj:`None`)
* **end\_date** (Optional\[str]): End date in YYYY-MM-DD format. (default: :obj:`None`)
**Returns:**
List: Earnings calendar.
### get\_dividend\_calendar
```python theme={"system"}
def get_dividend_calendar(
self,
start_date: Optional[str] = None,
end_date: Optional[str] = None
):
```
Get dividend calendar with optional yield calculations.
**Parameters:**
* **start\_date** (Optional\[str]): Start date in YYYY-MM-DD format. (default: :obj:`None`)
* **end\_date** (Optional\[str]): End date in YYYY-MM-DD format. (default: :obj:`None`)
**Returns:**
List: Dividend calendar.
### get\_ipo\_calendar
```python theme={"system"}
def get_ipo_calendar(
self,
start_date: Optional[str] = None,
end_date: Optional[str] = None
):
```
Get IPO/SPO calendar with comprehensive filtering options.
**Parameters:**
* **start\_date** (Optional\[str]): Start date in YYYY-MM-DD format. (default: :obj:`None`)
* **end\_date** (Optional\[str]): End date in YYYY-MM-DD format. (default: :obj:`None`)
**Returns:**
List: IPO/SPO calendar.
### get\_available\_indicators
```python theme={"system"}
def get_available_indicators(self, provider: Literal['econdb', 'imf'] = 'econdb'):
```
Get list of available economic indicators.
**Parameters:**
* **provider** (`Literal["econdb", "imf"]`): Data provider. (default: :obj:`econdb`)
**Returns:**
List: Available indicators.
### get\_indicator\_data
```python theme={"system"}
def get_indicator_data(
self,
symbol: str,
country: str,
provider: Literal['econdb', 'imf'] = 'econdb'
):
```
Get detailed metadata for an economic indicator.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.).
* **country** (str): Country code (e.g., 'US' for United States).
* **provider** (`Literal["econdb", "imf"]`): Data provider. (default: :obj:`econdb`)
**Returns:**
List: Indicator data.
### get\_financial\_metrics
```python theme={"system"}
def get_financial_metrics(
self,
symbol: str,
provider: Literal['fmp', 'intrinio', 'yfinance'] = 'fmp',
period: Literal['annual', 'quarter'] = 'annual',
limit: int = 5
):
```
Get company financial metrics and ratios.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.).
* **provider** (`Literal["fmp", "intrinio", "yfinance"]`): Data source. (default: :obj:`fmp`)
* **period** (`Literal["annual", "quarter"]`): Reporting period, "annual": Annual metrics, "quarter": Quarterly metrics. (default: :obj:`annual`)
* **limit** (int): Number of periods to return. (default: :obj:`5`) (default: 5)
**Returns:**
List: Financial metric.
### get\_company\_profile
```python theme={"system"}
def get_company_profile(
self,
symbol: str,
provider: Literal['fmp', 'intrinio', 'yfinance'] = 'fmp'
):
```
Get company profile information.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.).
* **provider** (`Literal["fmp", "intrinio", "yfinance"]`): Data provider. (default: :obj:`fmp`)
**Returns:**
List: Company profile.
### get\_financial\_statement
```python theme={"system"}
def get_financial_statement(
self,
symbol: str,
provider: Literal['fmp', 'intrinio', 'polygon', 'yfinance'] = 'fmp',
statement_type: Literal['balance', 'income', 'cash'] = 'balance',
period: Literal['annual', 'quarter'] = 'annual',
limit: int = 5
):
```
Get company financial statements.
Access balance sheet, income statement, or cash flow statement data.
Data availability and field names vary by provider and company type.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.).
* **provider** (`Literal["fmp", "intrinio", "polygon", "yfinance"]`): Data provider. (default: :obj:`fmp`)
* **statement\_type** (`Literal["balance", "income", "cash"]`): Type of financial statement, "balance": Balance sheet, "income": Income statement, "cash": Cash flow statement. (default: :obj:`balance`)
* **period** (`Literal["annual", "quarter"]`): Reporting period, "annual": Annual reports, "quarter": Quarterly reports. (default: :obj:`annual`)
* **limit** (int): Number of periods to return. (default: :obj:`5`) (default: 5)
**Returns:**
List: Financial statement data.
### get\_financial\_attributes
```python theme={"system"}
def get_financial_attributes(
self,
symbol: str,
tag: str,
frequency: Literal['daily', 'weekly', 'monthly', 'quarterly', 'yearly'] = 'yearly'
):
```
Get historical values for a specific financial attribute.
**Parameters:**
* **symbol** (str): Stock symbol (e.g., 'AAPL' for Apple Inc.).
* **tag** (str): Financial attribute tag (use search\_financial\_attributes to find tags). frequency (Literal\["daily", "weekly", "monthly", "quarterly", "yearly"]): Data frequency, "daily", "weekly", "monthly", "quarterly", "yearly". (default: :obj:`yearly`)
**Returns:**
List: Historical values.
### search\_financial\_attributes
```python theme={"system"}
def search_financial_attributes(self, query: str):
```
Search for available financial attributes/tags.
**Parameters:**
* **query** (str): Search term (e.g., "marketcap", "revenue", "assets").
**Returns:**
List: Matching attributes.
### get\_economic\_calendar
```python theme={"system"}
def get_economic_calendar(
self,
provider: Literal['fmp', 'tradingeconomics'] = 'fmp',
start_date: Optional[str] = None,
end_date: Optional[str] = None
):
```
Get economic calendar events.
**Parameters:**
* **provider** (`Literal["fmp", "tradingeconomics"]`): Data provider. (default: :obj:`fmp`)
* **start\_date** (Optional\[str]): Start date in YYYY-MM-DD format. (default: :obj:`None`)
* **end\_date** (Optional\[str]): End date in YYYY-MM-DD format. (default: :obj:`None`)
**Returns:**
List: Economic calendar.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.origene_mcp_toolkit
## OrigeneToolkit
```python theme={"system"}
class OrigeneToolkit(MCPToolkit):
```
OrigeneToolkit provides an interface for interacting with
Origene MCP server.
This toolkit can be used as an async context manager for automatic
connection management:
async with OrigeneToolkit(config\_dict=config) as toolkit:
tools = toolkit.get\_tools()
# Toolkit is automatically disconnected when exiting
**Parameters:**
* **config\_dict** (Dict): Configuration dictionary for MCP servers.
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
config_dict: Optional[Dict] = None,
timeout: Optional[float] = None
):
```
Initializes the OrigeneToolkit.
**Parameters:**
* **config\_dict** (Optional\[Dict]): Configuration dictionary for MCP servers. If None, raises ValueError as configuration is required. (default: :obj:`None`)
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.playwright_mcp_toolkit
## PlaywrightMCPToolkit
```python theme={"system"}
class PlaywrightMCPToolkit(MCPToolkit):
```
PlaywrightMCPToolkit provides an interface for interacting with web
browsers using the Playwright automation library through the Model Context
Protocol (MCP).
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
* **additional\_args** (Optional\[List\[str]]): Additional command-line arguments to pass to the Playwright MCP server. For example, `["--cdp-endpoint=http://localhost:9222"]`. (default: :obj:`None`)
**Note:**
Currently only supports asynchronous operation mode.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
additional_args: Optional[List[str]] = None
):
```
Initializes the PlaywrightMCPToolkit.
**Parameters:**
* **timeout** (Optional\[float]): Connection timeout in seconds. (default: :obj:`None`)
* **additional\_args** (Optional\[List\[str]]): Additional command-line arguments to pass to the Playwright MCP server. For example, `["--cdp-endpoint=http://localhost:9222"]`. (default: :obj:`None`)
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.pptx_toolkit
## PPTXToolkit
```python theme={"system"}
class PPTXToolkit(BaseToolkit):
```
A toolkit for creating and writing PowerPoint presentations (PPTX
files).
This class provides cross-platform support for creating PPTX files with
title slides, content slides, text formatting, and image embedding.
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initialize the PPTXToolkit.
**Parameters:**
* **working\_directory** (str, optional): The default directory for output files. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.
* **timeout** (Optional\[float]): The timeout for the toolkit. (default: :obj:`None`)
### \_resolve\_filepath
```python theme={"system"}
def _resolve_filepath(self, file_path: str):
```
Convert the given string path to a Path object.
If the provided path is not absolute, it is made relative to the
default output directory. The filename part is sanitized to replace
spaces and special characters with underscores, ensuring safe usage
in downstream processing.
**Parameters:**
* **file\_path** (str): The file path to resolve.
**Returns:**
Path: A fully resolved (absolute) and sanitized Path object.
### \_sanitize\_filename
```python theme={"system"}
def _sanitize_filename(self, filename: str):
```
Sanitize a filename by replacing special characters and spaces.
**Parameters:**
* **filename** (str): The filename to sanitize.
**Returns:**
str: The sanitized filename.
### \_format\_text
```python theme={"system"}
def _format_text(
self,
frame_paragraph,
text: str,
set_color_to_white = False
):
```
Apply bold and italic formatting while preserving the original
word order.
**Parameters:**
* **frame\_paragraph**: The paragraph to format.
* **text** (str): The text to format.
* **set\_color\_to\_white** (bool): Whether to set the color to white. (default: :obj:`False`)
### \_add\_bulleted\_items
```python theme={"system"}
def _add_bulleted_items(
self,
text_frame: 'TextFrame',
flat_items_list: List[Tuple[str, int]],
set_color_to_white: bool = False
):
```
Add a list of texts as bullet points and apply formatting.
**Parameters:**
* **text\_frame** (TextFrame): The text frame where text is to be displayed.
* **flat\_items\_list** (List\[Tuple\[str, int]]): The list of items to be displayed.
* **set\_color\_to\_white** (bool): Whether to set the font color to white. (default: :obj:`False`)
### \_get\_flat\_list\_of\_contents
```python theme={"system"}
def _get_flat_list_of_contents(self, items: List[Union[str, List[Any]]], level: int):
```
Flatten a hierarchical list of bullet points to a single list.
**Parameters:**
* **items** (List\[Union\[str, List\[Any]]]): A bullet point (string or list).
* **level** (int): The current level of hierarchy.
**Returns:**
List\[Tuple\[str, int]]: A list of (bullet item text, hierarchical
level) tuples.
### \_get\_slide\_width\_height\_inches
```python theme={"system"}
def _get_slide_width_height_inches(self, presentation: 'presentation.Presentation'):
```
Get the dimensions of a slide in inches.
**Parameters:**
* **presentation** (presentation.Presentation): The presentation object.
**Returns:**
Tuple\[float, float]: The width and height in inches.
### \_write\_pptx\_file
```python theme={"system"}
def _write_pptx_file(
self,
file_path: Path,
content: List[Dict[str, Any]],
template: Optional[str] = None
):
```
Write text content to a PPTX file with enhanced formatting.
**Parameters:**
* **file\_path** (Path): The target file path.
* **content** (List\[Dict\[str, Any]]): The content to write to the PPTX file. Must be a list of dictionaries where: - First element: Title slide with keys 'title' and 'subtitle' - Subsequent elements: Content slides with keys 'title', 'text'
* **template** (Optional\[str]): The name of the template to use. If not provided, the default template will be used. (default: :obj: `None`)
### create\_presentation
```python theme={"system"}
def create_presentation(
self,
content: str,
filename: str,
template: Optional[str] = None
):
```
Create a PowerPoint presentation (PPTX) file.
**Parameters:**
* **content** (str): The content to write to the PPTX file as a JSON string. Must represent a list of dictionaries with the following structure: - First dict: title slide `{"title": str, "subtitle": str}` - Other dicts: content slides, which can be one of: \* Bullet/step slides: `{"heading": str, "bullet_points": list of str or nested lists, "img_keywords": str (optional)}` - If any bullet point starts with '>> ', it will be rendered as a step-by-step process. - "img\_keywords" can be a URL or search keywords for an image (optional). \* Table slides: `{"heading": str, "table": {"headers": list of str, "rows": list of list of str}}`
* **filename** (str): The name or path of the file. If a relative path is supplied, it is resolved to self.working\_directory.
* **template** (Optional\[str]): The path to the template PPTX file. Initializes a presentation from a given template file Or PPTX file. (default: :obj:`None`)
**Returns:**
str: A success message indicating the file was created.
### \_handle\_default\_display
```python theme={"system"}
def _handle_default_display(
self,
presentation: 'presentation.Presentation',
slide_json: Dict[str, Any]
):
```
Display a list of text in a slide.
**Parameters:**
* **presentation** (presentation.Presentation): The presentation object.
* **slide\_json** (Dict\[str, Any]): The content of the slide as JSON data.
### \_handle\_display\_image\_\_in\_foreground
```python theme={"system"}
def _handle_display_image__in_foreground(
self,
presentation: 'presentation.Presentation',
slide_json: Dict[str, Any]
):
```
Create a slide with text and image using a picture placeholder
layout.
**Parameters:**
* **presentation** (presentation.Presentation): The presentation object.
* **slide\_json** (Dict\[str, Any]): The content of the slide as JSON data.
**Returns:**
bool: True if the slide has been processed.
### \_handle\_table
```python theme={"system"}
def _handle_table(
self,
presentation: 'presentation.Presentation',
slide_json: Dict[str, Any]
):
```
Add a table to a slide.
**Parameters:**
* **presentation** (presentation.Presentation): The presentation object.
* **slide\_json** (Dict\[str, Any]): The content of the slide as JSON data.
### \_handle\_step\_by\_step\_process
```python theme={"system"}
def _handle_step_by_step_process(
self,
presentation: 'presentation.Presentation',
slide_json: Dict[str, Any],
slide_width_inch: float,
slide_height_inch: float
):
```
Add shapes to display a step-by-step process in the slide.
**Parameters:**
* **presentation** (presentation.Presentation): The presentation object.
* **slide\_json** (Dict\[str, Any]): The content of the slide as JSON data.
* **slide\_width\_inch** (float): The width of the slide in inches.
* **slide\_height\_inch** (float): The height of the slide in inches.
### \_remove\_slide\_number\_from\_heading
```python theme={"system"}
def _remove_slide_number_from_heading(self, header: str):
```
Remove the slide number from a given slide header.
**Parameters:**
* **header** (str): The header of a slide.
**Returns:**
str: The header without slide number.
### \_get\_slide\_placeholders
```python theme={"system"}
def _get_slide_placeholders(self, slide: 'Slide'):
```
Return the index and name of all placeholders present in a slide.
**Parameters:**
* **slide** (Slide): The slide.
**Returns:**
List\[Tuple\[int, str]]: A list containing placeholders (idx, name)
tuples.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.pubmed_toolkit
## PubMedToolkit
```python theme={"system"}
class PubMedToolkit(BaseToolkit):
```
A toolkit for interacting with PubMed's E-utilities API to access
MEDLINE data.
This toolkit provides functionality to search and retrieve papers from the
PubMed database, including abstracts, citations, and other metadata.
**Parameters:**
* **timeout** (Optional\[float]): The timeout for API requests in seconds. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the PubMedToolkit.
### \_make\_request
```python theme={"system"}
def _make_request(
self,
endpoint: str,
params: Dict[str, Union[str, int]],
retries: int = 3
):
```
Makes a request to the PubMed/MEDLINE API with error handling and
retries.
**Parameters:**
* **endpoint** (str): The API endpoint to call.
* **params** (Dict\[str, Union\[str, int]]): Query parameters.
* **retries** (int, optional): Number of retry attempts. (default: :obj:`3`)
**Returns:**
Optional\[Dict\[str, Any]]: JSON response if successful, else None.
### search\_papers
```python theme={"system"}
def search_papers(
self,
query: str,
max_results: int = 10,
sort: str = 'relevance',
date_range: Optional[Dict[str, str]] = None,
publication_type: Optional[List[str]] = None
):
```
Search for biomedical papers in MEDLINE via PubMed with advanced
filtering options.
**Parameters:**
* **query** (str): The search query string.
* **max\_results** (int, optional): Maximum number of results to return. (default: :obj:`10`)
* **sort** (str, optional): Sort order - 'relevance' or 'date'. (default: :obj:`"relevance"`)
* **date\_range** (Optional\[Dict\[str, str]], optional): Date range filter with 'from' and 'to' dates in YYYY/MM/DD format. (default: :obj:`None`)
* **publication\_type** (Optional\[List\[str]], optional): Filter by publication types (e.g., \["Journal Article", "Review"]). (default: :obj:`None`)
**Returns:**
List\[Dict\[str, str]]: List of papers with their metadata.
### get\_paper\_details
```python theme={"system"}
def get_paper_details(
self,
paper_id: Union[str, int],
include_references: bool = False
):
```
Get detailed information about a specific biomedical paper from
MEDLINE/PubMed.
**Parameters:**
* **paper\_id** (Union\[str, int]): PubMed ID of the paper.
* **include\_references** (bool, optional): Whether to include referenced papers. (default: :obj:`False`)
**Returns:**
Optional\[Dict\[str, Any]]: Paper details including title, authors,
abstract, etc., or None if retrieval fails.
### get\_abstract
```python theme={"system"}
def get_abstract(self, paper_id: Union[str, int]):
```
Get the abstract of a specific biomedical paper from MEDLINE/
PubMed.
**Parameters:**
* **paper\_id** (Union\[str, int]): PubMed ID of the paper.
**Returns:**
str: The abstract text.
### get\_citation\_count
```python theme={"system"}
def get_citation_count(self, paper_id: Union[str, int]):
```
Get the number of citations for a biomedical paper in MEDLINE/
PubMed.
**Parameters:**
* **paper\_id** (Union\[str, int]): PubMed ID of the paper.
**Returns:**
int: Number of citations, or 0 if retrieval fails.
### get\_related\_papers
```python theme={"system"}
def get_related_papers(self, paper_id: Union[str, int], max_results: int = 10):
```
Get biomedical papers related to a specific paper in MEDLINE/
PubMed.
**Parameters:**
* **paper\_id** (Union\[str, int]): PubMed ID of the paper.
* **max\_results** (int, optional): Maximum number of results to return. (default: :obj:`10`)
**Returns:**
List\[Dict\[str, Any]]: List of related papers with their metadata.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.pulse_mcp_search_toolkit
## PulseMCPSearchToolkit
```python theme={"system"}
class PulseMCPSearchToolkit(BaseToolkit):
```
A toolkit for searching MCP servers using the PulseMCP API.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
### search\_mcp\_servers
```python theme={"system"}
def search_mcp_servers(
self,
query: Optional[str] = None,
top_k: Optional[int] = 5,
package_registry: Optional[str] = None,
count_per_page: int = 5000,
offset: int = 0
):
```
Search for MCP servers using the PulseMCP API.
**Parameters:**
* **query** (Optional\[str]): The query to search for. (default: :obj:`None`)
* **top\_k** (Optional\[int]): After sorting, return only the top\_k servers. (default: :obj:`5`)
* **package\_registry** (Optional\[str]): The package registry to search for. (default: :obj:`None`)
* **count\_per\_page** (int): The number of servers to return per page. (default: :obj:`5000`)
* **offset** (int): The offset to start the search from. (default: :obj:`0`)
**Returns:**
Dict\[str, Any]: A dictionary containing the search results or
an error message.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.pyautogui_toolkit
## PyAutoGUIToolkit
```python theme={"system"}
class PyAutoGUIToolkit(BaseToolkit):
```
A toolkit for automating GUI interactions using PyAutoGUI.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
screenshots_dir: str = 'tmp'
):
```
Initializes the PyAutoGUIToolkit with optional timeout.
**Parameters:**
* **timeout** (Optional\[float]): Timeout for API requests in seconds. (default: :obj:`None`)
* **screenshots\_dir** (str): Directory to save screenshots. (default: :obj:`"tmp"`)
### \_get\_safe\_coordinates
```python theme={"system"}
def _get_safe_coordinates(self, x: int, y: int):
```
Ensure coordinates are within safe boundaries to prevent triggering
failsafe.
**Parameters:**
* **x** (int): Original x-coordinate
* **y** (int): Original y-coordinate
**Returns:**
Tuple\[int, int]: Safe coordinates
### mouse\_move
```python theme={"system"}
def mouse_move(self, x: int, y: int):
```
Move mouse pointer to specified coordinates.
**Parameters:**
* **x** (int): X-coordinate to move to.
* **y** (int): Y-coordinate to move to.
**Returns:**
str: Success or error message.
### mouse\_click
```python theme={"system"}
def mouse_click(
self,
button: Literal['left', 'middle', 'right'] = 'left',
clicks: int = 1,
x: Optional[int] = None,
y: Optional[int] = None
):
```
Performs a mouse click at the specified coordinates or current
position.
**Parameters:**
* **button** (`Literal["left", "middle", "right"]`): The mouse button to click. - "left": Typically used for selecting items, activating buttons, or placing the cursor. - "middle": Often used for opening links in a new tab or specific application functions. - "right": Usually opens a context menu providing options related to the clicked item or area. (default: :obj:`"left"`)
* **clicks** (int): The number of times to click the button. - 1: A single click, the most common action. - 2: A double-click, often used to open files/folders or select words. (default: :obj:`1`)
* **x** (Optional\[int]): The x-coordinate on the screen to move the mouse to before clicking. If None, clicks at the current mouse position. (default: :obj:`None`)
* **y** (Optional\[int]): The y-coordinate on the screen to move the mouse to before clicking. If None, clicks at the current mouse position. (default: :obj:`None`)
**Returns:**
str: A message indicating the action performed, e.g.,
"Clicked left button 1 time(s) at coordinates (100, 150)."
or "Clicked right button 2 time(s) at current position."
### get\_mouse\_position
```python theme={"system"}
def get_mouse_position(self):
```
**Returns:**
str: Current mouse X and Y coordinates.
### take\_screenshot
```python theme={"system"}
def take_screenshot(self):
```
**Returns:**
str: Path to the saved screenshot or error message.
### mouse\_drag
```python theme={"system"}
def mouse_drag(
self,
start_x: int,
start_y: int,
end_x: int,
end_y: int,
button: Literal['left', 'middle', 'right'] = 'left'
):
```
Drag mouse from start position to end position.
**Parameters:**
* **start\_x** (int): Starting x-coordinate.
* **start\_y** (int): Starting y-coordinate.
* **end\_x** (int): Ending x-coordinate.
* **end\_y** (int): Ending y-coordinate.
* **button** (`Literal["left", "middle", "right"]`): Mouse button to use ('left', 'middle', 'right'). (default: :obj:`'left'`)
**Returns:**
str: Success or error message.
### scroll
```python theme={"system"}
def scroll(
self,
scroll_amount: int,
x: Optional[int] = None,
y: Optional[int] = None
):
```
Scroll the mouse wheel.
**Parameters:**
* **scroll\_amount** (int): Amount to scroll. Positive values scroll up, negative values scroll down.
* **x** (Optional\[int]): X-coordinate to scroll at. If None, uses current position. (default: :obj:`None`)
* **y** (Optional\[int]): Y-coordinate to scroll at. If None, uses current position. (default: :obj:`None`)
**Returns:**
str: Success or error message.
### keyboard\_type
```python theme={"system"}
def keyboard_type(self, text: str, interval: float = 0.0):
```
Type text on the keyboard.
**Parameters:**
* **text** (str): Text to type.
* **interval** (float): Seconds to wait between keypresses. (default: :obj:`0.0`)
**Returns:**
str: Success or error message.
### press\_key
```python theme={"system"}
def press_key(self, key: Union[str, List[str]]):
```
Press a key on the keyboard.
**Parameters:**
* **key** (Union\[str, List\[str]]): The key to be pressed. Can also be a list of such strings. Valid key names include: - Basic characters: a-z, 0-9, and symbols like !, @, #, etc. - Special keys: enter, esc, space, tab, backspace, delete - Function keys: f1-f24 - Navigation: up, down, left, right, home, end, pageup, pagedown - Modifiers: shift, ctrl, alt, command, option, win - Media keys: volumeup, volumedown, volumemute, playpause
**Returns:**
str: Success or error message.
### hotkey
```python theme={"system"}
def hotkey(self, keys: List[str]):
```
Press keys in succession and release in reverse order.
**Parameters:**
* **keys** (List\[str]): The series of keys to press, in order. This can be either: - Multiple string arguments, e.g., hotkey('ctrl', 'c') - A single list of strings, e.g., hotkey(\['ctrl', 'c'])
**Returns:**
str: Success or error message.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of PyAutoGUI functions.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.reddit_toolkit
## RedditToolkit
```python theme={"system"}
class RedditToolkit(BaseToolkit):
```
A class representing a toolkit for Reddit operations.
This toolkit provides methods to interact with the Reddit API, allowing
users to collect top posts, perform sentiment analysis on comments, and
track keyword discussions across multiple subreddits.
**Parameters:**
* **retries** (int): Number of retries for API requests in case of failure.
* **delay** (float): Delay between retries in seconds.
* **reddit** (Reddit): An instance of the Reddit client.
### **init**
```python theme={"system"}
def __init__(
self,
retries: int = 3,
delay: float = 0.0,
timeout: Optional[float] = None
):
```
Initializes the RedditToolkit with the specified number of retries
and delay.
**Parameters:**
* **retries** (int): Number of times to retry the request in case of failure. Defaults to `3`.
* **delay** (int): Time in seconds to wait between retries. Defaults to `0`.
* **timeout** (float): Timeout for API requests in seconds. Defaults to `None`.
### collect\_top\_posts
```python theme={"system"}
def collect_top_posts(
self,
subreddit_name: str,
post_limit: int = 5,
comment_limit: int = 5
):
```
Collects the top posts and their comments from a specified
subreddit.
**Parameters:**
* **subreddit\_name** (str): The name of the subreddit to collect posts from.
* **post\_limit** (int): The maximum number of top posts to collect. Defaults to `5`.
* **comment\_limit** (int): The maximum number of top comments to collect per post. Defaults to `5`.
**Returns:**
Union\[List\[Dict\[str, Any]], str]: A list of dictionaries, each
containing the post title and its top comments if success.
String warming if credentials are not set.
### perform\_sentiment\_analysis
```python theme={"system"}
def perform_sentiment_analysis(self, data: List[Dict[str, Any]]):
```
Performs sentiment analysis on the comments collected from Reddit
posts.
**Parameters:**
* **data** (List\[Dict\[str, Any]]): A list of dictionaries containing Reddit post data and comments.
**Returns:**
List\[Dict\[str, Any]]: The original data with an added 'Sentiment
Score' for each comment.
### track\_keyword\_discussions
```python theme={"system"}
def track_keyword_discussions(
self,
subreddits: List[str],
keywords: List[str],
post_limit: int = 10,
comment_limit: int = 10,
sentiment_analysis: bool = False
):
```
Tracks discussions about specific keywords in specified subreddits.
**Parameters:**
* **subreddits** (List\[str]): A list of subreddit names to search within.
* **keywords** (List\[str]): A list of keywords to track in the subreddit discussions.
* **post\_limit** (int): The maximum number of top posts to collect per subreddit. Defaults to `10`.
* **comment\_limit** (int): The maximum number of top comments to collect per post. Defaults to `10`.
* **sentiment\_analysis** (bool): If True, performs sentiment analysis on the comments. Defaults to `False`.
**Returns:**
Union\[List\[Dict\[str, Any]], str]: A list of dictionaries
containing the subreddit name, post title, comment body, and
upvotes for each comment that contains the specified keywords
if success. String warming if credentials are not set.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects for the
toolkit methods.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.resend_toolkit
## ResendToolkit
```python theme={"system"}
class ResendToolkit(BaseToolkit):
```
A toolkit for sending emails using the Resend API.
This toolkit provides functionality to send emails using Resend's
Python SDK.It supports sending both HTML and plain text emails,
with options for multiple recipients, CC, BCC, reply-to
addresses, and custom headers.
### send\_email
```python theme={"system"}
def send_email(
self,
to: List[str],
subject: str,
from_email: str,
html: Optional[str] = None,
text: Optional[str] = None,
cc: Optional[List[str]] = None,
bcc: Optional[List[str]] = None,
reply_to: Optional[str] = None,
tags: Optional[List[Dict[str, str]]] = None,
headers: Optional[Dict[str, str]] = None
):
```
Send an email using the Resend API.
**Parameters:**
* **to** (List\[str]): List of recipient email addresses.
* **subject** (str): The email subject line.
* **from\_email** (str): The sender email address. Must be from a verified domain.
* **html** (Optional\[str]): The HTML content of the email. Either html or text must be provided. (default: :obj:`None`)
* **text** (Optional\[str]): The plain text content of the email. Either html or text must be provided. (default: :obj:`None`)
* **cc** (Optional\[List\[str]]): List of CC recipient email addresses. (default: :obj:`None`)
* **bcc** (Optional\[List\[str]]): List of BCC recipient email addresses. (default: :obj:`None`)
* **reply\_to** (Optional\[str]): The reply-to email address. (default: :obj:`None`)
* **tags** (Optional\[List\[Dict\[str, str]]]): List of tags to attach to the email. Each tag should be a dict with 'name' and 'value' keys. (default: :obj:`None`)
* **headers** (Optional\[Dict\[str, str]]): Custom headers to include in the email.(default: :obj:`None`)
**Returns:**
str: A success message with the email ID if sent successfully,
or an error message if the send failed.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.retrieval_toolkit
## RetrievalToolkit
```python theme={"system"}
class RetrievalToolkit(BaseToolkit):
```
A class representing a toolkit for information retrieval.
This class provides methods for retrieving information from a local vector
storage system based on a specified query.
### **init**
```python theme={"system"}
def __init__(
self,
auto_retriever: Optional[AutoRetriever] = None,
timeout: Optional[float] = None
):
```
Initializes a new instance of the RetrievalToolkit class.
### information\_retrieval
```python theme={"system"}
def information_retrieval(
self,
query: str,
contents: Union[str, List[str]],
top_k: int = Constants.DEFAULT_TOP_K_RESULTS,
similarity_threshold: float = Constants.DEFAULT_SIMILARITY_THRESHOLD
):
```
Retrieves information from a local vector storage based on the
specified query. This function connects to a local vector storage
system and retrieves relevant information by processing the input
query. It is essential to use this function when the answer to a
question requires external knowledge sources.
**Parameters:**
* **query** (str): The question or query for which an answer is required.
* **contents** (Union\[str, List\[str]]): Local file paths, remote URLs or string contents.
* **top\_k** (int, optional): The number of top results to return during retrieve. Must be a positive integer. Defaults to 1.
* **similarity\_threshold** (float, optional): The similarity threshold for filtering results. Defaults to 0.7.
**Returns:**
str: The information retrieved in response to the query, aggregated
and formatted as a string.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.screenshot_toolkit
## ScreenshotToolkit
```python theme={"system"}
class ScreenshotToolkit(BaseToolkit, RegisteredAgentToolkit):
```
A toolkit for taking screenshots.
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initializes the ScreenshotToolkit.
**Parameters:**
* **working\_directory** (str, optional): The directory path where notes will be stored. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `camel_working_dir`.
* **timeout** (Optional\[float]): Timeout for API requests in seconds. (default: :obj:`None`)
### read\_image
```python theme={"system"}
def read_image(self, image_path: str, instruction: str = ''):
```
Analyzes an image from a local file path.
This function enables you to "see" and interpret an image from a
file. It's useful for tasks where you need to understand visual
information, such as reading a screenshot of a webpage or a diagram.
**Parameters:**
* **image\_path** (str): The local file path to the image. For example: 'screenshots/login\_page.png'.
* **instruction** (str, optional): Specific instructions for what to look for or what to do with the image. For example: "What is the main headline on this page?" or "Find the 'Submit' button.".
**Returns:**
str: The response after analyzing the image, which could be a
description, an answer, or a confirmation of an action.
### take\_screenshot\_and\_read\_image
```python theme={"system"}
def take_screenshot_and_read_image(
self,
filename: str,
save_to_file: bool = True,
read_image: bool = True,
instruction: Optional[str] = None
):
```
Captures a screenshot of the entire screen.
This function can save the screenshot to a file and optionally analyze
it. It's useful for capturing the current state of the UI for
documentation, analysis, or to guide subsequent actions.
**Parameters:**
* **filename** (str): The name for the screenshot file (e.g., "homepage.png"). The file is saved in a `screenshots` subdirectory within the working directory. Must end with `.png`. (default: :obj:`None`)
* **save\_to\_file** (bool, optional): If `True`, saves the screenshot to a file. (default: :obj:`True`)
* **read\_image** (bool, optional): If `True`, the agent will analyze the screenshot. `save_to_file` must also be `True`. (default: :obj:`True`)
* **instruction** (Optional\[str], optional): A specific question or command for the agent regarding the screenshot, used only if `read_image` is `True`. For example: "Confirm that the user is logged in.".
**Returns:**
str: A confirmation message indicating success or failure,
including the file path if saved, and the agent's response
if `read_image` is `True`.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of screenshot functions.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.search_toolkit
## SearchToolkit
```python theme={"system"}
class SearchToolkit(BaseToolkit):
```
A class representing a toolkit for web search.
This class provides methods for searching information on the web using
search engines like Google, DuckDuckGo, Wikipedia and Wolfram Alpha, Brave.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
exclude_domains: Optional[List[str]] = None
):
```
Initializes the SearchToolkit.
**Parameters:**
* **timeout** (float): Timeout for API requests in seconds. (default: :obj:`None`)
* **exclude\_domains** (Optional\[List\[str]]): List of domains to exclude from search results. Currently only supported by the `search_google` function. (default: :obj:`None`)
### search\_serper
```python theme={"system"}
def search_serper(
self,
query: str,
page: int = 10,
location: str = 'United States'
):
```
Use Serper.dev API to perform Google search.
**Parameters:**
* **query** (str): The search query.
* **page** (int): The page number of results to retrieve. (default: :obj:`10`)
* **location** (str): The location for the search results. (default: :obj:`"United States"`)
**Returns:**
Dict\[str, Any]: The search result dictionary containing 'organic',
'peopleAlsoAsk', etc.
### search\_wiki
```python theme={"system"}
def search_wiki(self, entity: str):
```
Search the entity in WikiPedia and return the summary of the
required page, containing factual information about
the given entity.
**Parameters:**
* **entity** (str): The entity to be searched.
**Returns:**
str: The search result. If the page corresponding to the entity
exists, return the summary of this entity in a string.
### search\_linkup
```python theme={"system"}
def search_linkup(
self,
query: str,
depth: Literal['standard', 'deep'] = 'standard',
output_type: Literal['searchResults', 'sourcedAnswer', 'structured'] = 'searchResults',
structured_output_schema: Optional[str] = None
):
```
Search for a query in the Linkup API and return results in various
formats.
**Parameters:**
* **query** (str): The search query.
* **depth** (`Literal["standard", "deep"]`): The depth of the search. "standard" for a straightforward search, "deep" for a more comprehensive search.
* **output\_type** (`Literal["searchResults", "sourcedAnswer", "structured"]`): The type of output: - "searchResults" for raw search results, - "sourcedAnswer" for an answer with supporting sources, - "structured" for output based on a provided schema.
* **structured\_output\_schema** (Optional\[str]): If `output_type` is "structured", specify the schema of the output. Must be a string representing a valid object JSON schema.
**Returns:**
Dict\[str, Any]: A dictionary representing the search result. The
structure depends on the `output_type`. If an error occurs,
returns an error message.
### search\_duckduckgo
```python theme={"system"}
def search_duckduckgo(
self,
query: str,
source: str = 'text',
number_of_result_pages: int = 10
):
```
Use DuckDuckGo search engine to search information for
the given query.
This function queries the DuckDuckGo API for related topics to
the given search term. The results are formatted into a list of
dictionaries, each representing a search result.
**Parameters:**
* **query** (str): The query to be searched.
* **source** (str): The type of information to query (e.g., "text", "images", "videos"). Defaults to "text".
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries where each dictionary
represents a search result.
### search\_brave
```python theme={"system"}
def search_brave(
self,
q: str,
country: str = 'US',
search_lang: str = 'en',
ui_lang: str = 'en-US',
offset: int = 0,
safesearch: str = 'moderate',
freshness: Optional[str] = None,
text_decorations: bool = True,
spellcheck: bool = True,
result_filter: Optional[str] = None,
goggles_id: Optional[str] = None,
units: Optional[str] = None,
extra_snippets: Optional[bool] = None,
summary: Optional[bool] = None,
number_of_result_pages: int = 10
):
```
This function queries the Brave search engine API and returns a
dictionary, representing a search result.
See [https://api.search.brave.com/app/documentation/web-search/query](https://api.search.brave.com/app/documentation/web-search/query)
for more details.
**Parameters:**
* **q** (str): The user's search query term. Query cannot be empty. Maximum of 400 characters and 50 words in the query.
* **country** (str): The search query country where results come from. The country string is limited to 2 character country codes of supported countries. For a list of supported values, see Country Codes. (default: :obj:`US `)
* **search\_lang** (str): The search language preference. Use ONLY these exact values, NOT standard ISO codes: 'ar', 'eu', 'bn', 'bg', 'ca', 'zh-hans', 'zh-hant', 'hr', 'cs', 'da', 'nl', 'en', 'en-gb', 'et', 'fi', 'fr', 'gl', 'de', 'gu', 'he', 'hi', 'hu', 'is', 'it', 'jp', 'kn', 'ko', 'lv', 'lt', 'ms', 'ml', 'mr', 'nb', 'pl', 'pt-br', 'pt-pt', 'pa', 'ro', 'ru', 'sr', 'sk', 'sl', 'es', 'sv', 'ta', 'te', 'th', 'tr', 'uk', 'vi'.
* **ui\_lang** (str): User interface language preferred in response.
* **Format**: '``-``'. Common examples: 'en-US', 'en-GB', 'jp-JP', 'zh-hans-CN', 'zh-hant-TW', 'de-DE', 'fr-FR', 'es-ES', 'pt-BR', 'ru-RU', 'ko-KR'.
* **offset** (int): The zero based offset that indicates number of search results per page (count) to skip before returning the result. The maximum is 9. The actual number delivered may be less than requested based on the query. In order to paginate results use this parameter together with count. For example, if your user interface displays 20 search results per page, set count to 20 and offset to 0 to show the first page of results. To get subsequent pages, increment offset by 1 (e.g. 0, 1, 2). The results may overlap across multiple pages.
* **safesearch** (str): Filters search results for adult content. The following values are supported: - 'off': No filtering is done. - 'moderate': Filters explicit content, like images and videos, but allows adult domains in the search results. - 'strict': Drops all adult content from search results.
* **freshness** (Optional\[str]): Filters search results by when they were
* **discovered**: - 'pd': Discovered within the last 24 hours. - 'pw': Discovered within the last 7 Days. - 'pm': Discovered within the last 31 Days. - 'py': Discovered within the last 365 Days. - 'YYYY-MM-DDtoYYYY-MM-DD': Timeframe is also supported by specifying the date range e.g. '2022-04-01to2022-07-30'.
* **text\_decorations** (bool): Whether display strings (e.g. result snippets) should include decoration markers (e.g. highlighting characters).
* **spellcheck** (bool): Whether to spellcheck provided query. If the spellchecker is enabled, the modified query is always used for search. The modified query can be found in altered key from the query response model.
* **result\_filter** (Optional\[str]): A comma delimited string of result types to include in the search response. Not specifying this parameter will return back all result types in search response where data is available and a plan with the corresponding option is subscribed. The response always includes query and type to identify any query modifications and response type respectively. Available result filter values are: - 'discussions' - 'faq' - 'infobox' - 'news' - 'query' - 'summarizer' - 'videos' - 'web' - 'locations'
* **goggles\_id** (Optional\[str]): Goggles act as a custom re-ranking on top of Brave's search index. For more details, refer to the Goggles repository.
* **units** (Optional\[str]): The measurement units. If not provided, units are derived from search country. Possible values are: - 'metric': The standardized measurement system - 'imperial': The British Imperial system of units.
* **extra\_snippets** (Optional\[bool]): A snippet is an excerpt from a page you get as a result of the query, and extra\_snippets allow you to get up to 5 additional, alternative excerpts. Only available under Free AI, Base AI, Pro AI, Base Data, Pro Data and Custom plans.
* **summary** (Optional\[bool]): This parameter enables summary key generation in web search results. This is required for summarizer to be enabled.
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
Dict\[str, Any]: A dictionary representing a search result.
### search\_google
```python theme={"system"}
def search_google(
self,
query: str,
search_type: str = 'web',
number_of_result_pages: int = 10,
start_page: int = 1
):
```
Use Google search engine to search information for the given query.
**Parameters:**
* **query** (str): The query to be searched.
* **search\_type** (str): The type of search to perform. Must be either "web" for web pages or "image" for image search. Any other value will raise a ValueError. (default: "web")
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Must be a positive integer between 1 and 10. Google Custom Search API limits results to 10 per request. If a value greater than 10 is provided, it will be capped at 10 with a warning. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
* **start\_page** (int): The result page to start from. Must be a positive integer (`>= 1`). Use this for pagination - e.g., start\_page=1 for results 1-10, start\_page=11 for results 11-20, etc. This allows agents to check initial results and continue searching if needed. (default: :obj:`1`)
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries where each dictionary
represents a search result.
For web search, each dictionary contains:
* 'result\_id': A number in order.
* 'title': The title of the website.
* 'description': A brief description of the website.
* 'long\_description': More detail of the website.
* 'url': The URL of the website.
For image search, each dictionary contains:
* 'result\_id': A number in order.
* 'title': The title of the image.
* 'image\_url': The URL of the image.
* 'display\_link': The website hosting the image.
* 'context\_url': The URL of the page containing the image.
* 'width': Image width in pixels (if available).
* 'height': Image height in pixels (if available).
Example web result:
`\{
'result_id': 1,
'title': 'OpenAI',
'description': 'An organization focused on ensuring that
artificial general intelligence benefits all of humanity.',
'long_description': 'OpenAI is a non-profit artificial
intelligence research company. Our goal is to advance
digital intelligence in the way that is most likely to
benefit humanity as a whole',
'url': 'https://www.openai.com'
\}`
Example image result:
`\{
'result_id': 1,
'title': 'Beautiful Sunset',
'image_url': 'https://example.com/image.jpg',
'display_link': 'example.com',
'context_url': 'https://example.com/page.html',
'width': 800,
'height': 600
\}`
### search\_tavily
```python theme={"system"}
def search_tavily(
self,
query: str,
number_of_result_pages: int = 10,
**kwargs
):
```
Use Tavily Search API to search information for the given query.
**Parameters:**
* **query** (str): The query to be searched.
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`) \*\*kwargs: Additional optional parameters supported by Tavily's API: - search\_depth (str): "basic" or "advanced" search depth. - topic (str): The search category, e.g., "general" or "news." - days (int): Time frame in days for news-related searches. - max\_results (int): Max number of results to return (overrides `num_results`). See [https://docs.tavily.com/docs/python-sdk/tavily-search/](https://docs.tavily.com/docs/python-sdk/tavily-search/) api-reference for details.
**Returns:**
List\[Dict\[str, Any]]: A list of dictionaries representing search
results. Each dictionary contains:
* 'result\_id' (int): The result's index.
* 'title' (str): The title of the result.
* 'description' (str): A brief description of the result.
* 'long\_description' (str): Detailed information, if available.
* 'url' (str): The URL of the result.
* 'content' (str): Relevant content from the search result.
* 'images' (list): A list of related images (if
`include_images` is True).
* 'published\_date' (str): Publication date for news topics
(if available).
### search\_bocha
```python theme={"system"}
def search_bocha(
self,
query: str,
freshness: str = 'noLimit',
summary: bool = False,
page: int = 1,
number_of_result_pages: int = 10
):
```
Query the Bocha AI search API and return search results.
**Parameters:**
* **query** (str): The search query.
* **freshness** (str): Time frame filter for search results. Default is "noLimit". Options include: - 'noLimit': no limit (default). - 'oneDay': past day. - 'oneWeek': past week. - 'oneMonth': past month. - 'oneYear': past year.
* **summary** (bool): Whether to include text summaries in results. Default is False.
* **page** (int): Page number of results. Default is 1.
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
Dict\[str, Any]: A dictionary containing search results, including
web pages, images, and videos if available. The structure
follows the Bocha AI search API response format.
### search\_baidu
```python theme={"system"}
def search_baidu(self, query: str, number_of_result_pages: int = 10):
```
Search Baidu using web scraping to retrieve relevant search
results. This method queries Baidu's search engine and extracts search
results including titles, descriptions, and URLs.
**Parameters:**
* **query** (str): Search query string to submit to Baidu.
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
Dict\[str, Any]: A dictionary containing search results or error
message.
### search\_bing
```python theme={"system"}
def search_bing(self, query: str, number_of_result_pages: int = 10):
```
Use Bing search engine to search information for the given query.
This function queries the Chinese version of Bing search engine (cn.
bing.com) using web scraping to retrieve relevant search results. It
extracts search results including titles, snippets, and URLs. This
function is particularly useful when the query is in Chinese or when
Chinese search results are desired.
**Parameters:**
* **query** (str): The search query string to submit to Bing. Works best with Chinese queries or when Chinese results are preferred.
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
Dict (\[str, Any]): A dictionary containing either:
* 'results': A list of dictionaries, each with:
* 'result\_id': The index of the result.
* 'snippet': A brief description of the search result.
* 'title': The title of the search result.
* 'link': The URL of the search result.
* or 'error': An error message if something went wrong.
### search\_exa
```python theme={"system"}
def search_exa(
self,
query: str,
search_type: Literal['auto', 'neural', 'keyword'] = 'auto',
category: Optional[Literal['company', 'research paper', 'news', 'pdf', 'github', 'tweet', 'personal site', 'linkedin profile', 'financial report']] = None,
include_text: Optional[List[str]] = None,
exclude_text: Optional[List[str]] = None,
use_autoprompt: bool = True,
text: bool = False,
number_of_result_pages: int = 10
):
```
Use Exa search API to perform intelligent web search with optional
content extraction.
**Parameters:**
* **query** (str): The search query string.
* **search\_type** (`Literal["auto", "neural", "keyword"]`): The type of search to perform. "auto" automatically decides between keyword and neural search. (default: :obj:`"auto"`)
* **category** (Optional\[Literal]): Category to focus the search on, such as "research paper" or "news". (default: :obj:`None`)
* **include\_text** (Optional\[List\[str]]): Strings that must be present in webpage text. Limited to 1 string of up to 5 words. (default: :obj:`None`)
* **exclude\_text** (Optional\[List\[str]]): Strings that must not be present in webpage text. Limited to 1 string of up to 5 words. (default: :obj:`None`)
* **use\_autoprompt** (bool): Whether to use Exa's autoprompt feature to enhance the query. (default: :obj:`True`)
* **text** (bool): Whether to include webpage contents in results. (default: :obj:`False`)
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Must be between 1 and 100. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
Dict\[str, Any]: A dict containing search results and metadata:
* requestId (str): Unique identifier for the request
* autopromptString (str): Generated autoprompt if enabled
* autoDate (str): Timestamp of autoprompt generation
* resolvedSearchType (str): The actual search type used
* results (List\[Dict]): List of search results with metadata
* searchType (str): The search type that was selected
* costDollars (Dict): Breakdown of API costs
### search\_alibaba\_tongxiao
```python theme={"system"}
def search_alibaba_tongxiao(
self,
query: str,
time_range: Literal['OneDay', 'OneWeek', 'OneMonth', 'OneYear', 'NoLimit'] = 'NoLimit',
industry: Optional[Literal['finance', 'law', 'medical', 'internet', 'tax', 'news_province', 'news_center']] = None,
return_main_text: bool = False,
return_markdown_text: bool = True,
enable_rerank: bool = True,
number_of_result_pages: int = 10
):
```
Query the Alibaba Tongxiao search API and return search results.
A powerful search API optimized for Chinese language queries with
features:
* Enhanced Chinese language understanding
* Industry-specific filtering (finance, law, medical, etc.)
* Structured data with markdown formatting
* Result reranking for relevance
* Time-based filtering
**Parameters:**
* **query** (str): The search query string (`length >= 1 and <= 100`).
* **time\_range** (`Literal["OneDay", "OneWeek", "OneMonth", "OneYear", "NoLimit"]`): Time frame filter for search results. (default: :obj:`"NoLimit"`)
* **industry** (`Optional[Literal["finance", "law", "medical", "internet", "tax", "news_province", "news_center"]]`): Industry-specific search filter. When specified, only returns results from sites in the specified industries. Multiple industries can be comma-separated. (default: :obj:`None`)
* **return\_main\_text** (bool): Whether to include the main text of the webpage in results. (default: :obj:`True`)
* **return\_markdown\_text** (bool): Whether to include markdown formatted content in results. (default: :obj:`True`)
* **enable\_rerank** (bool): Whether to enable result reranking. If response time is critical, setting this to False can reduce response time by approximately 140ms. (default: :obj:`True`)
* **number\_of\_result\_pages** (int): The number of result pages to retrieve. Adjust this based on your task - use fewer results for focused searches and more for comprehensive searches. (default: :obj:`10`)
**Returns:**
Dict\[str, Any]: A dictionary containing either search results with
'requestId' and 'results' keys, or an 'error' key with error
message. Each result contains title, snippet, url and other
metadata.
### search\_metaso
```python theme={"system"}
def search_metaso(
self,
query: str,
page: int = 1,
include_summary: bool = False,
include_raw_content: bool = False,
concise_snippet: bool = False,
scope: Literal['webpage', 'document', 'scholar', 'image', 'video', 'podcast'] = 'webpage'
):
```
Perform a web search using the metaso.cn API.
**Parameters:**
* **query** (str): The search query string.
* **page** (int): Page number. (default: :obj:`1`) (default: 1)
* **include\_summary** (bool): Whether to include summary in the result. (default: :obj:`False`)
* **include\_raw\_content** (bool): Whether to include raw content in the result. (default: :obj:`False`)
* **concise\_snippet** (bool): Whether to return concise snippet. (default: :obj:`False`) scope (Literal\["webpage", "document", "scholar", "image", "video", "podcast"]): Search scope. (default: :obj:`"webpage"`)
**Returns:**
Dict\[str, Any]: Search results or error information.
### search\_serpapi
```python theme={"system"}
def search_serpapi(
self,
query: str,
engine: str = 'google',
location: str = 'Austin,Texas',
google_domain: str = 'google.com',
gl: str = 'us',
search_lang: str = 'en',
device: str = 'desktop',
number_of_result_pages: int = 1,
safe: str = 'off',
filter: int = 0,
custom_params: Optional[Dict[str, Any]] = None
):
```
Use SerpApi search engine to search information for the given query.
SerpApi provides real-time search engine results from multiple search engines
including Google, Bing, Yahoo, DuckDuckGo, Baidu, Yandex, and more.
**Parameters:**
* **query** (str): The search query string.
* **engine** (str): Search engine to use. Supported engines include: 'google', 'bing', 'yahoo', 'duckduckgo', 'baidu', 'yandex', 'youtube', 'ebay', 'amazon', etc. (default: :obj:`"google"`)
* **location** (str): Location for localized search results. Can be a city, state, country, or coordinates. (default: :obj:`"Austin,Texas"`)
* **google\_domain** (str): Google domain to use (e.g., 'google.com', 'google.co.uk'). Only applicable for Google engine. (default: :obj:`"google.com"`)
* **gl** (str): Country code for localized results (e.g., 'us', 'uk', 'ca'). Only applicable for Google engine. (default: :obj:`"us"`)
* **search\_lang** (str): Language code for results (e.g., 'en', 'es', 'fr'). Only applicable for Google engine. (default: :obj:`"en"`)
* **device** (str): Device type: 'desktop', 'tablet', or 'mobile'. (default: :obj:`"desktop"`)
* **number\_of\_result\_pages** (int): Number of organic results to return. Adjust based on task needs. (default: :obj:`1`)
* **safe** (str): Safe search level: 'off', 'medium', 'high', 'active'. (default: :obj:`"off"`)
* **filter** (int): Filter results: 0 (no filter), 1 (filter similar results). (default: :obj:`0`)
* **custom\_params** (Optional\[Dict\[str, Any]]): Additional custom parameters to pass to SerpApi. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: A dictionary containing search results:
* 'results': List of organic search results, each containing:
* 'title': The title of the search result
* 'link': The URL of the search result
* 'snippet': The description snippet
* 'keywords': Highlighted keywords in the snippet
* 'source': The source of the result
* 'error: Error if any
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
### tavily\_search
```python theme={"system"}
def tavily_search(self, *args, **kwargs):
```
Deprecated: Use search\_tavily instead for consistency with other search methods.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.searxng_toolkit
## SearxNGToolkit
```python theme={"system"}
class SearxNGToolkit(BaseToolkit):
```
A toolkit for performing web searches using SearxNG search engine.
This toolkit provides methods to search the web using SearxNG,
a privacy-respecting metasearch engine. It supports customizable
search parameters and safe search levels.
**Parameters:**
* **searxng\_host** (str): The URL of the SearxNG instance to use for searches. Must be a valid HTTP/HTTPS URL.
* **language** (str, optional): Search language code for results. (default: :obj:`"en"`)
* **categories** (List\[str], optional): List of search categories to use. (default: :obj:`None`)
* **time\_range** (str, optional): Time range filter for search results.Valid values are "day", "week", "month", "year". (default: :obj:`None`)
* **safe\_search** (int, optional): Safe search level (0: None, 1: Moderate, 2: Strict). (default: :obj:`1`)
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
searxng_host: str,
language: str = 'en',
categories: Optional[List[str]] = None,
time_range: Optional[str] = None,
safe_search: int = 1,
timeout: Optional[float] = None
):
```
### \_validate\_searxng\_host
```python theme={"system"}
def _validate_searxng_host(self, url: str):
```
Validate if the given URL is a proper HTTP/HTTPS URL.
**Parameters:**
* **url** (str): The URL to validate.
### \_validate\_safe\_search
```python theme={"system"}
def _validate_safe_search(self, level: int):
```
Validate if the safe search level is valid.
**Parameters:**
* **level** (int): The safe search level to validate.
### \_validate\_time\_range
```python theme={"system"}
def _validate_time_range(self, time_range: str):
```
Validate if the time range is valid.
**Parameters:**
* **time\_range** (str): The time range to validate.
### search
```python theme={"system"}
def search(
self,
query: str,
num_results: int = 10,
category: Optional[str] = None
):
```
Perform a web search using the configured SearxNG instance.
**Parameters:**
* **query** (str): The search query string to execute.
* **num\_results** (int, optional): Maximum number of results to return. (default: :obj:`10`)
* **category** (str, optional): Specific search category to use. If not provided, uses the first category from self.categories. (default: :obj:`None`)
**Returns:**
List\[Dict\[str, str]]: List of search results, where each result is
dictionary containing 'title', 'link', and 'snippet' keys.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
available functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.semantic_scholar_toolkit
## SemanticScholarToolkit
```python theme={"system"}
class SemanticScholarToolkit(BaseToolkit):
```
A toolkit for interacting with the Semantic Scholar
API to fetch paper and author data.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the SemanticScholarToolkit.
### fetch\_paper\_data\_title
```python theme={"system"}
def fetch_paper_data_title(self, paper_title: str, fields: Optional[List[str]] = None):
```
Fetches a SINGLE paper from the Semantic Scholar
API based on a paper title.
**Parameters:**
* **paper\_title** (str): The title of the paper to fetch.
* **fields** (Optional\[List\[str]], optional): The fields to include in the response (default: :obj:`None`). If not provided defaults to \["title", "abstract", "authors", "year", "citationCount", "publicationTypes", "publicationDate", "openAccessPdf"].
**Returns:**
dict: The response data from the API or error information if the
request fails.
### fetch\_paper\_data\_id
```python theme={"system"}
def fetch_paper_data_id(self, paper_id: str, fields: Optional[List[str]] = None):
```
Fetches a SINGLE paper from the Semantic Scholar
API based on a paper ID.
**Parameters:**
* **paper\_id** (str): The ID of the paper to fetch.
* **fields** (Optional\[List\[str]], optional): The fields to include in the response (default: :obj:`None`). If not provided defaults to \["title", "abstract", "authors", "year", "citationCount", "publicationTypes", "publicationDate", "openAccessPdf"].
**Returns:**
dict: The response data from the API or error information
if the request fails.
### fetch\_bulk\_paper\_data
```python theme={"system"}
def fetch_bulk_paper_data(
self,
query: str,
year: str = '2023-',
fields: Optional[List[str]] = None
):
```
Fetches MULTIPLE papers at once from the Semantic Scholar
API based on a related topic.
**Parameters:**
* **query** (str): The text query to match against the paper's title and abstract. For example, you can use the following operators and techniques to construct your query: Example 1: ((cloud computing) | virtualization) +security -privacy This will match papers whose title or abstract contains "cloud" and "computing", or contains the word "virtualization". The papers must also include the term "security" but exclude papers that contain the word "privacy".
* **year** (str, optional): The year filter for papers (default: :obj:`"2023-"`).
* **fields** (Optional\[List\[str]], optional): The fields to include in the response (default: :obj:`None`). If not provided defaults to \["title", "url", "publicationTypes", "publicationDate", "openAccessPdf"].
**Returns:**
dict: The response data from the API or error information if the
request fails.
### fetch\_recommended\_papers
```python theme={"system"}
def fetch_recommended_papers(
self,
positive_paper_ids: List[str],
negative_paper_ids: List[str],
fields: Optional[List[str]] = None,
limit: int = 500,
save_to_file: bool = False
):
```
Fetches recommended papers from the Semantic Scholar
API based on the positive and negative paper IDs.
**Parameters:**
* **positive\_paper\_ids** (list): A list of paper IDs (as strings) that are positively correlated to the recommendation.
* **negative\_paper\_ids** (list): A list of paper IDs (as strings) that are negatively correlated to the recommendation.
* **fields** (Optional\[List\[str]], optional): The fields to include in the response (default: :obj:`None`). If not provided defaults to \["title", "url", "citationCount", "authors", "publicationTypes", "publicationDate", "openAccessPdf"].
* **limit** (int, optional): The maximum number of recommended papers to return (default: :obj:`500`).
* **save\_to\_file** (bool, optional): If True, saves the response data to a file (default: :obj:`False`).
**Returns:**
dict: A dictionary containing recommended papers sorted by
citation count.
### fetch\_author\_data
```python theme={"system"}
def fetch_author_data(
self,
ids: List[str],
fields: Optional[List[str]] = None,
save_to_file: bool = False
):
```
Fetches author information from the Semantic Scholar
API based on author IDs.
**Parameters:**
* **ids** (list): A list of author IDs (as strings) to fetch data for.
* **fields** (Optional\[List\[str]], optional): The fields to include in the response (default: :obj:`None`). If not provided defaults to \["name", "url", "paperCount", "hIndex", "papers"].
* **save\_to\_file** (bool, optional): Whether to save the results to a file (default: :obj:`False`).
**Returns:**
dict: The response data from the API or error information if
the request fails.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.skill_toolkit
## SkillToolkit
```python theme={"system"}
class SkillToolkit(BaseToolkit):
```
Toolkit for loading SKILL.md content.
Skills are discovered from filesystem roots and loaded on-demand.
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
timeout: Optional[float] = None
):
```
### \_build\_description
```python theme={"system"}
def _build_description(self):
```
### \_get\_skills
```python theme={"system"}
def _get_skills(self):
```
### clear\_cache
```python theme={"system"}
def clear_cache(self):
```
Clear the cached skills to force rescanning on next access.
### \_scan\_skills
```python theme={"system"}
def _scan_skills(self):
```
**Returns:**
Dict\[str, Dict\[str, str]]: Mapping of skill name to metadata.
### \_skill\_roots
```python theme={"system"}
def _skill_roots(self):
```
**Returns:**
List\[Tuple\[str, Path]]: List of (scope, path) tuples.
### \_is\_hidden\_path
```python theme={"system"}
def _is_hidden_path(self, path: Path, root: Path):
```
Check if a path contains hidden directories (starting with dot).
**Parameters:**
* **path** (Path): The path to check.
* **root** (Path): The root directory to compute relative path from.
**Returns:**
bool: True if the path contains hidden directories.
### \_parse\_skill
```python theme={"system"}
def _parse_skill(self, path: Path):
```
Parse a SKILL.md file and extract metadata.
**Parameters:**
* **path** (Path): Path to the SKILL.md file.
**Returns:**
Optional\[Dict\[str, str]]: Parsed skill data with name,
description, and body. Returns None if parsing fails.
### \_split\_frontmatter
```python theme={"system"}
def _split_frontmatter(self, contents: str):
```
Split YAML frontmatter from the body of a SKILL.md file.
**Parameters:**
* **contents** (str): The full contents of the file.
**Returns:**
Tuple\[Optional\[str], str]: A tuple of (frontmatter, body).
frontmatter is None if no valid frontmatter delimiter is found.
### list\_skills
```python theme={"system"}
def list_skills(self):
```
**Returns:**
List\[Dict\[str, str]]: Skill metadata entries including name,
description, path, and scope.
### list\_skill\_files
```python theme={"system"}
def list_skill_files(self, name: str):
```
List files and directories in a skill folder.
**Parameters:**
* **name** (str): The skill identifier.
**Returns:**
str: Formatted list of files/directories, or error message.
### \_load\_single\_skill
```python theme={"system"}
def _load_single_skill(self, name: str):
```
Load a single skill by name.
**Parameters:**
* **name** (str): The skill identifier.
**Returns:**
str: The skill content, or error message if not found.
### load\_skill
```python theme={"system"}
def load_skill(self, name: Union[str, List[str]]):
```
Load one or more skills by name.
**Parameters:**
* **name** (Union\[str, List\[str]]): A single skill name or list of names.
**Returns:**
str: The skill content(s), or error message if not found.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Return the skill tools with injected available skills.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.slack_toolkit
## SlackToolkit
```python theme={"system"}
class SlackToolkit(BaseToolkit):
```
A class representing a toolkit for Slack operations.
This class provides methods for Slack operations such as creating a new
channel, joining an existing channel, leaving a channel.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes a new instance of the SlackToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### \_login\_slack
```python theme={"system"}
def _login_slack(
self,
slack_token: Optional[str] = None,
ssl: Optional[SSLContext] = None
):
```
Authenticate using the Slack API.
**Parameters:**
* **slack\_token** (str, optional): The Slack API token. If not provided, it attempts to retrieve the token from the environment variable SLACK\_BOT\_TOKEN or SLACK\_USER\_TOKEN.
* **ssl** (SSLContext, optional): SSL context for secure connections. Defaults to `None`.
**Returns:**
WebClient: A WebClient object for interacting with Slack API.
### create\_slack\_channel
```python theme={"system"}
def create_slack_channel(self, name: str, is_private: Optional[bool] = True):
```
Creates a new slack channel, either public or private.
**Parameters:**
* **name** (str): Name of the public or private channel to create.
* **is\_private** (bool, optional): Whether to create a private channel instead of a public one. Defaults to `True`.
**Returns:**
str: JSON string containing information about Slack
channel created.
### join\_slack\_channel
```python theme={"system"}
def join_slack_channel(self, channel_id: str):
```
Joins an existing Slack channel. When use this function you must
call `get_slack_channel_information` function first to get the
`channel id`.
**Parameters:**
* **channel\_id** (str): The ID of the Slack channel to join.
**Returns:**
str: A string containing the API response from Slack.
### leave\_slack\_channel
```python theme={"system"}
def leave_slack_channel(self, channel_id: str):
```
Leaves an existing Slack channel. When use this function you must
call `get_slack_channel_information` function first to get the
`channel id`.
**Parameters:**
* **channel\_id** (str): The ID of the Slack channel to leave.
**Returns:**
str: A string containing the API response from Slack.
### get\_slack\_channel\_information
```python theme={"system"}
def get_slack_channel_information(self):
```
**Returns:**
str: A JSON string representing a list of channels. Each channel
object in the list contains 'id', 'name', 'created', and
'num\_members'. Returns an error message string on failure.
### get\_slack\_channel\_message
```python theme={"system"}
def get_slack_channel_message(self, channel_id: str):
```
Retrieve messages from a Slack channel. When use this function you
must call `get_slack_channel_information` function first to get the
`channel id`.
**Parameters:**
* **channel\_id** (str): The ID of the Slack channel to retrieve messages from.
**Returns:**
str: A JSON string representing a list of messages. Each message
object contains 'user', 'text', and 'ts' (timestamp).
### send\_slack\_message
```python theme={"system"}
def send_slack_message(
self,
message: str,
channel_id: str,
file_path: Optional[str] = None,
user: Optional[str] = None
):
```
Send a message to a Slack channel. When use this function you must
call `get_slack_channel_information` function first to get the
`channel id`. If use user, you must use `get_slack_user_list`
function first to get the user id.
**Parameters:**
* **message** (str): The message to send.
* **channel\_id** (str): The ID of the channel to send the message to.
* **file\_path** (Optional\[str]): The local path of a file to upload with the message.
* **user** (Optional\[str]): The ID of a user to send an ephemeral message to (visible only to that user).
**Returns:**
str: A confirmation message indicating success or an error
message.
### delete\_slack\_message
```python theme={"system"}
def delete_slack_message(self, time_stamp: str, channel_id: str):
```
Delete a message from a Slack channel. When use this function you
must call `get_slack_channel_information` function first to get the
`channel id`.
**Parameters:**
* **time\_stamp** (str): The 'ts' value of the message to be deleted. You can get this from the `get_slack_channel_message` function.
* **channel\_id** (str): The ID of the channel where the message is. Use `get_slack_channel_information` to find the `channel_id`.
**Returns:**
str: A string containing the API response from Slack.
### get\_slack\_user\_list
```python theme={"system"}
def get_slack_user_list(self):
```
**Returns:**
str: A JSON string representing a list of users. Each user
object contains 'id', 'name'.
### get\_slack\_user\_info
```python theme={"system"}
def get_slack_user_info(self, user_id: str):
```
Retrieve information about a specific user in the Slack workspace.
normally, you don't need to use this method, when you need to get a
user's detailed information, use this method. Use `get_slack_user_list`
function first to get the user id.
**Parameters:**
* **user\_id** (str): The ID of the user to retrieve information about.
**Returns:**
str: A JSON string representing the user's information.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.sql_toolkit
## SQLToolkit
```python theme={"system"}
class SQLToolkit(BaseToolkit):
```
A toolkit for executing SQL queries against various SQL databases.
This toolkit provides functionality to execute SQL queries with support
for read-only and read-write modes. It currently supports DuckDB and
SQLite, with extensibility for MySQL and other SQL databases.
**Parameters:**
* **database\_path** (Optional\[str]): Path to the database file. If None, uses an in-memory database. For DuckDB and SQLite, use ":memory:" for in-memory or a file path for persistent storage. (default: :obj:`None`)
* **database\_type** (`Literal["duckdb", "sqlite"]`): Type of database to use. Currently supports "duckdb" and "sqlite". (default: :obj:`"duckdb"`)
* **read\_only** (bool, optional): If True, only SELECT queries are allowed. Write operations (INSERT, UPDATE, DELETE, etc.) will be rejected. (default: :obj:`False`)
* **timeout** (Optional\[float], optional): The timeout for database operations in seconds. Defaults to 180 seconds if not specified. (default: :obj:`180.0`)
### **init**
```python theme={"system"}
def __init__(
self,
database_path: Optional[str] = None,
database_type: Literal['duckdb', 'sqlite'] = 'duckdb',
read_only: bool = False,
timeout: Optional[float] = 180.0
):
```
### \_validate\_database\_type
```python theme={"system"}
def _validate_database_type(self, database_type: str):
```
Validate if the database type is supported.
**Parameters:**
* **database\_type** (str): The database type to validate.
### \_create\_connection
```python theme={"system"}
def _create_connection(self):
```
**Returns:**
Union\[duckdb.DuckDBPyConnection, sqlite3.Connection]: A database
connection object.
### \_is\_write\_query
```python theme={"system"}
def _is_write_query(self, query: str):
```
Check if a SQL query is a write operation.
This method analyzes the query string to determine if it contains
any write operations. It handles comments and case-insensitive
matching.
**Parameters:**
* **query** (str): The SQL query to check.
**Returns:**
bool: True if the query is a write operation, False otherwise.
### \_quote\_identifier
```python theme={"system"}
def _quote_identifier(self, identifier: str):
```
Safely quote a SQL identifier (table name, column name, etc.).
This method validates and quotes SQL identifiers to prevent SQL
injection. For DuckDB, identifiers are quoted with double quotes. Any
double quotes within the identifier are escaped by doubling them.
**Parameters:**
* **identifier** (str): The identifier to quote (e.g., table name, column name).
**Returns:**
str: The safely quoted identifier.
### execute\_query
```python theme={"system"}
def execute_query(
self,
query: str,
params: Optional[Union[List[Union[str, int, float, bool, None]], Dict[str, Union[str, int, float, bool, None]]]] = None
):
```
Execute a SQL query and return results.
This method executes a SQL query against the configured database and
returns the results. For SELECT queries, returns a list of dictionaries
where each dictionary represents a row. For write operations (INSERT,
UPDATE, DELETE, etc.), returns a status dictionary with execution info.
**Parameters:**
* **query** (str): The SQL query to execute. params (Optional\[Union\[List\[Union\[str, int, float, bool, None]], Dict\[str, Union\[str, int, float, bool, None]]]], optional): Parameters for parameterized queries. Can be a list for positional parameters (with ? placeholders) or a dict for named parameters. Values can be strings, numbers, booleans, or None. Note: tuples are also accepted at runtime but should be passed as lists for type compatibility. (default: :obj:`None`)
**Returns:**
Union\[List\[Dict\[str, Any]], Dict\[str, Any], str]:
* For SELECT queries: List of dictionaries with column names as
keys and row values as values.
* For write operations (INSERT, UPDATE, DELETE, CREATE, etc.):
A dictionary with 'status', 'message', and optionally
'rows\_affected' keys.
* For errors: An error message string starting with "Error:".
### list\_tables
```python theme={"system"}
def list_tables(self):
```
**Returns:**
Union\[List\[str], str]: A list of table names in the database,
or an error message string if the operation fails.
### \_get\_table\_schema
```python theme={"system"}
def _get_table_schema(self, table_name: str):
```
Internal helper method to get table schema information.
**Parameters:**
* **table\_name** (str): The name of the table to describe.
**Returns:**
Union\[Dict\[str, Any], str]: A dictionary containing 'columns',
'primary\_keys', and 'foreign\_keys', or an error message string
if the operation fails.
### get\_table\_info
```python theme={"system"}
def get_table_info(self, table_name: Optional[str] = None):
```
Get comprehensive information about table(s) in the database.
This method provides a summary of table information including schema,
primary keys, foreign keys, and row counts. If table\_name is provided,
returns info for that specific table. Otherwise, returns info for all
tables.
**Parameters:**
* **table\_name** (Optional\[str], optional): Name of a specific table to get info for. If None, returns info for all tables. (default: :obj:`None`)
**Returns:**
Union\[Dict\[str, Any], str]: A dictionary containing table
information, or an error message string if the operation fails.
If table\_name is provided, returns info for that table with
keys: 'table\_name', 'columns', 'primary\_keys', 'foreign\_keys',
'row\_count'. Otherwise, returns a dictionary mapping table
names to their info dictionaries.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
available functions in the toolkit.
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up database connection on deletion.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.stripe_toolkit
## StripeToolkit
```python theme={"system"}
class StripeToolkit(BaseToolkit):
```
A class representing a toolkit for Stripe operations.
This toolkit provides methods to interact with the Stripe API,
allowing users to operate stripe core resources, including Customer,
Balance, BalanceTransaction, Payment, Refund
Use the Developers Dashboard [https://dashboard.stripe.com/test/apikeys](https://dashboard.stripe.com/test/apikeys) to
create an API keys as STRIPE\_API\_KEY.
**Parameters:**
* **logger** (Logger): a logger to write logs.
### **init**
```python theme={"system"}
def __init__(self, retries: int = 3, timeout: Optional[float] = None):
```
### customer\_get
```python theme={"system"}
def customer_get(self, customer_id: str):
```
Retrieve a customer by ID.
**Parameters:**
* **customer\_id** (str): The ID of the customer to retrieve.
**Returns:**
str: The customer data as a str.
### customer\_list
```python theme={"system"}
def customer_list(self, limit: int = 100):
```
List customers.
**Parameters:**
* **limit** (int, optional): Number of customers to retrieve. (default: :obj:`100`)
**Returns:**
str: An output str if successful, or an error message string if
failed.
### balance\_get
```python theme={"system"}
def balance_get(self):
```
**Returns:**
str: A str containing the account balance if successful, or an
error message string if failed.
### balance\_transaction\_list
```python theme={"system"}
def balance_transaction_list(self, limit: int = 100):
```
List your balance transactions.
**Parameters:**
* **limit** (int, optional): Number of balance transactions to retrieve. (default::obj:`100`)
**Returns:**
str: A list of balance transaction data if successful, or an error
message string if failed.
### payment\_get
```python theme={"system"}
def payment_get(self, payment_id: str):
```
Retrieve a payment by ID.
**Parameters:**
* **payment\_id** (str): The ID of the payment to retrieve.
**Returns:**
str:The payment data as a str if successful, or an error message
string if failed.
### payment\_list
```python theme={"system"}
def payment_list(self, limit: int = 100):
```
List payments.
**Parameters:**
* **limit** (int, optional): Number of payments to retrieve. (default::obj:`100`)
**Returns:**
str: A list of payment data if successful, or an error message
string if failed.
### refund\_get
```python theme={"system"}
def refund_get(self, refund_id: str):
```
Retrieve a refund by ID.
**Parameters:**
* **refund\_id** (str): The ID of the refund to retrieve.
**Returns:**
str: The refund data as a str if successful, or an error message
string if failed.
### refund\_list
```python theme={"system"}
def refund_list(self, limit: int = 100):
```
List refunds.
**Parameters:**
* **limit** (int, optional): Number of refunds to retrieve. (default::obj:`100`)
**Returns:**
str: A list of refund data as a str if successful, or an error
message string if failed.
### handle\_exception
```python theme={"system"}
def handle_exception(self, func_name: str, error: Exception):
```
Handle exceptions by logging and returning an error message.
**Parameters:**
* **func\_name** (str): The name of the function where the exception occurred.
* **error** (Exception): The exception instance.
**Returns:**
str: An error message string.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects for the
toolkit methods.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.sympy_toolkit
## SymPyToolkit
```python theme={"system"}
class SymPyToolkit(BaseToolkit):
```
A toolkit for performing symbolic computations using SymPy.
This includes methods for Algebraic manipulation calculus
and Linear Algebra.
### **init**
```python theme={"system"}
def __init__(
self,
default_variable: str = 'x',
timeout: Optional[float] = None
):
```
Initializes the toolkit with a default variable and logging.
**Parameters:**
* **default\_variable** (str): The default variable for operations (default: :obj:`x`)
### simplify\_expression
```python theme={"system"}
def simplify_expression(self, expression: str):
```
Simplifies a mathematical expression.
**Parameters:**
* **expression** (str): The mathematical expression to simplify, provided as a string.
**Returns:**
str: JSON string containing the simplified mathematical
expression in the `"result"` field. If an error occurs,
the `"status"` field will be set to `"error"` with a
corresponding `"message"`.
### expand\_expression
```python theme={"system"}
def expand_expression(self, expression: str):
```
Expands an algebraic expression.
**Parameters:**
* **expression** (str): The algebraic expression to expand, provided as a string.
**Returns:**
str: JSON string containing the expanded algebraic expression
in the `"result"` field. If an error occurs, the JSON
string will include an `"error"` field with the corresponding
error message.
### factor\_expression
```python theme={"system"}
def factor_expression(self, expression: str):
```
Factors an algebraic expression.
**Parameters:**
* **expression** (str): The algebraic expression to factor, provided as a string.
**Returns:**
str: JSON string containing the factored algebraic expression
in the `"result"` field. If an error occurs, the JSON string
will include an `"error"` field with the corresponding error
message.
### solve\_linear\_system
```python theme={"system"}
def solve_linear_system(self, equations: List[str], variables: List[str]):
```
Solves a system of linear equations.
**Parameters:**
* **equations** (List\[str]): A list of strings representing the linear equations to be solved.
* **variables** (List\[str]): A list of strings representing the variables involved in the equations.
**Returns:**
str: JSON string containing the solution to the system of equations
in the `"result"` field. Each solution is represented as
a tuple of values corresponding to the variables. If an
error occurs, the JSON string will include an `"error"`
field with the corresponding error message.
### solve\_nonlinear\_system
```python theme={"system"}
def solve_nonlinear_system(self, sympy_equations: List[str], variables: List[str]):
```
Solves a system of nonlinear equations.
**Parameters:**
* **sympy\_equations** (List\[str]): A list of strings representing the nonlinear equations to be solved. The equation to solve, must be compatible with SymPy, provided as a string.
* **variables** (List\[str]): A list of strings representing the variables involved in the equations.
**Returns:**
str: JSON string containing the solutions to the system of
equations in the `"result"` field. Each solution is
represented as a tuple of values corresponding to the
variables. If an error occurs, the JSON string will
include an `"error"` field with the corresponding
error message.
### solve\_univariate\_inequality
```python theme={"system"}
def solve_univariate_inequality(self, inequality: str, variable: str):
```
Solves a single-variable inequality.
**Parameters:**
* **inequality** (str): A string representing the inequality to be solved.
* **variable** (str): The variable in the inequality.
**Returns:**
str: JSON string containing the solution to the inequality in the
`"result"` field. The solution is represented in a symbolic
format (e.g., intervals or expressions). If an error occurs,
the JSON string will include an `"error"` field with the
corresponding error message.
### reduce\_inequalities
```python theme={"system"}
def reduce_inequalities(self, inequalities: List[str]):
```
Reduces a system of inequalities.
**Parameters:**
* **inequalities** (List\[str]): A list of strings representing the inequalities to be reduced.
**Returns:**
str: JSON string containing the reduced system of inequalities
in the `"result"` field. The solution is represented in
a symbolic format (e.g., combined intervals or expressions).
If an error occurs, the JSON string will include an `"error"`
field with the corresponding error message.
### polynomial\_representation
```python theme={"system"}
def polynomial_representation(self, expression: str, variable: str):
```
Represents an expression as a polynomial.
**Parameters:**
* **expression** (str): The mathematical expression to represent as a polynomial, provided as a string.
* **variable** (str): The variable with respect to which the polynomial representation will be created.
**Returns:**
str: JSON string containing the polynomial representation of the
expression in the `"result"` field. The polynomial is returned
in a symbolic format. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### polynomial\_degree
```python theme={"system"}
def polynomial_degree(self, expression: str, variable: str):
```
Returns the degree of a polynomial.
**Parameters:**
* **expression** (str): The polynomial expression for which the degree is to be determined, provided as a string.
* **variable** (str): The variable with respect to which the degree of the polynomial is calculated.
**Returns:**
str: JSON string containing the degree of the polynomial in the
`"result"` field. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### polynomial\_coefficients
```python theme={"system"}
def polynomial_coefficients(self, expression: str, variable: str):
```
Returns the coefficients of a polynomial.
**Parameters:**
* **expression** (str): The polynomial expression from which the coefficients are to be extracted, provided as a string.
* **variable** (str): The variable with respect to which the polynomial coefficients are determined.
**Returns:**
str: JSON string containing the list of coefficients of the
polynomial in the `"result"` field. The coefficients are
ordered from the highest degree term to the constant term.
If an error occurs, the JSON string will include an \`"error"
field with the corresponding error message.
### solve\_equation
```python theme={"system"}
def solve_equation(self, sympy_equation: str, variable: Optional[str] = None):
```
Solves an equation for a specific variable.
**Parameters:**
* **sympy\_equation** (str): The equation to solve, must be compatible with SymPy, provided as a string.
* **variable** (str, optional): The variable to solve for. If not specified, the function will use the default variable.
**Returns:**
str: JSON string containing the solutions to the equation in the
`"result"` field. Each solution is represented as a string.
If an error occurs, the JSON string will include an `"error"`
field with the corresponding error message.
### find\_roots
```python theme={"system"}
def find_roots(self, expression: str):
```
Finds the roots of a polynomial or algebraic equation.
**Parameters:**
* **expression** (str): The polynomial or algebraic equation for which the roots are to be found, provided as a string.
**Returns:**
str: JSON string containing the roots of the expression in the
`"result"` field. The roots are represented as a list of
solutions. If an error occurs, the JSON string will include
a `"status"` field set to `"error"` and a `"message"` field
with the corresponding error description.
### differentiate
```python theme={"system"}
def differentiate(self, expression: str, variable: Optional[str] = None):
```
Differentiates an expression with respect to a variable.
**Parameters:**
* **expression** (str): The mathematical expression to differentiate, provided as a string.
* **variable** (str, optional): The variable with respect to which the differentiation is performed. If not specified, the default variable is used.
**Returns:**
str: JSON string containing the derivative of the expression in the
`"result"` field. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### integrate
```python theme={"system"}
def integrate(self, expression: str, variable: Optional[str] = None):
```
Integrates an expression with respect to a variable.
**Parameters:**
* **expression** (str): The mathematical expression to integrate, provided as a string.
* **variable** (str, optional): The variable with respect to which the integration is performed. If not specified, the default variable is used.
**Returns:**
str: JSON string containing the integral of the expression in the
`"result"` field. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### definite\_integral
```python theme={"system"}
def definite_integral(
self,
expression: str,
variable: str,
lower: float,
upper: float
):
```
Computes the definite integral of an expression within given
bounds.
**Parameters:**
* **expression** (str): The mathematical expression to integrate, provided as a string.
* **variable** (str): The variable with respect to which the definite integration is performed.
* **lower** (float): The lower limit of the integration.
* **upper** (float): The upper limit of the integration.
**Returns:**
str: JSON string containing the result of the definite integral
in the `"result"` field. If an error occurs, the JSON string
will include an `"error"` field with the corresponding error
message.
### series\_expansion
```python theme={"system"}
def series_expansion(
self,
expression: str,
variable: str,
point: float,
order: int
):
```
Expands an expression into a Taylor series around a given point up
to a specified order.
**Parameters:**
* **expression** (str): The mathematical expression to expand, provided as a string.
* **variable** (str): The variable with respect to which the series expansion is performed.
* **point** (float): The point around which the Taylor series is expanded.
* **order** (int): The order up to which the series expansion is computed.
**Returns:**
str: JSON string containing the Taylor series expansion of the
expression in the `"result"` field. If an error occurs,
the JSON string will include an `"error"` field with the
corresponding error message.
### compute\_limit
```python theme={"system"}
def compute_limit(
self,
expression: str,
variable: str,
point: float
):
```
Computes the limit of an expression as a variable approaches
a point.
**Parameters:**
* **expression** (str): The mathematical expression for which the limit is to be computed, provided as a string.
* **variable** (str): The variable with respect to which the limit is computed.
* **point** (float): The point that the variable approaches.
**Returns:**
str: JSON string containing the computed limit of the expression
in the `"result"` field. If an error occurs, the JSON string
will include an `"error"` field with the corresponding error
message.
### find\_critical\_points
```python theme={"system"}
def find_critical_points(self, expression: str, variable: str):
```
Finds the critical points of an expression by setting its
derivative to zero.
**Parameters:**
* **expression** (str): The mathematical expression for which critical points are to be found, provided as a string.
* **variable** (str): The variable with respect to which the critical points are determined.
**Returns:**
str: JSON string containing the critical points of the expression
in the `"result"` field. The critical points are returned as a
list of values corresponding to the variable. If an error
occurs, the JSON string will include an `"error"` field with
the corresponding error message.
### check\_continuity
```python theme={"system"}
def check_continuity(
self,
expression: str,
variable: str,
point: float
):
```
Checks if an expression is continuous at a given point.
**Parameters:**
* **expression** (str): The mathematical expression to check for continuity, provided as a string.
* **variable** (str): The variable with respect to which continuity is checked.
* **point** (float): The point at which the continuity of the expression is checked.
**Returns:**
str: JSON string containing the result of the continuity check in
the `"result"` field. The result will be `"True"` if the
expression is continuous at the given point, otherwise
`"False"`. If an error occurs, the JSON string will include
an `"error"` field with the corresponding error message.
### compute\_determinant
```python theme={"system"}
def compute_determinant(self, matrix: List[List[float]]):
```
Computes the determinant of a matrix.
**Parameters:**
* **matrix** (List\[List\[float]]): A two-dimensional list representing the matrix for which the determinant is to be computed.
**Returns:**
str: JSON string containing the determinant of the matrix in the
`"result"` field. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### compute\_inverse
```python theme={"system"}
def compute_inverse(self, matrix: List[List[float]]):
```
Computes the inverse of a matrix.
**Parameters:**
* **matrix** (List\[List\[float]]): A two-dimensional list representing the matrix for which the inverse is to be computed.
**Returns:**
str: JSON string containing the inverse of the matrix in the
`"result"` field. The inverse is represented in a symbolic
matrix format. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### compute\_eigenvalues
```python theme={"system"}
def compute_eigenvalues(self, matrix: List[List[float]]):
```
Computes the eigenvalues of a matrix.
**Parameters:**
* **matrix** (List\[List\[float]]): A two-dimensional list representing the matrix for which the eigenvalues are to be computed.
**Returns:**
str: JSON string containing the eigenvalues of the matrix in the
`"result"` field. The eigenvalues are represented as a
dictionary where keys are the eigenvalues (as strings) and
values are their multiplicities (as strings). If an error
occurs, the JSON string will include an `"error"` field
with the corresponding error message.
### compute\_eigenvectors
```python theme={"system"}
def compute_eigenvectors(self, matrix: List[List[float]]):
```
Computes the eigenvectors of a matrix.
**Parameters:**
* **matrix** (List\[List\[float]]): A two-dimensional list representing the matrix for which the eigenvectors are to be computed.
**Returns:**
str: JSON string containing the eigenvectors of the matrix in the
`"result"` field. Each eigenvalue is represented as a
dictionary with the following keys:
* `"eigenvalue"`: The eigenvalue (as a string).
* `"multiplicity"`: The multiplicity of the eigenvalue
(as an integer).
* `"eigenvectors"`: A list of eigenvectors
(each represented as a string).
If an error occurs, the JSON string will include an `"error"`
field with the corresponding error message.
### compute\_nullspace
```python theme={"system"}
def compute_nullspace(self, matrix: List[List[float]]):
```
Computes the null space of a matrix.
**Parameters:**
* **matrix** (List\[List\[float]]): A two-dimensional list representing the matrix for which the null space is to be computed.
**Returns:**
str: JSON string containing the null space of the matrix in the
`"result"` field. The null space is represented as a list of
basis vectors, where each vector is given as a string in
symbolic format. If an error occurs, the JSON string will
include an `"error"` field with the corresponding error
message.
### compute\_rank
```python theme={"system"}
def compute_rank(self, matrix: List[List[float]]):
```
Computes the rank of a matrix.
**Parameters:**
* **matrix** (List\[List\[float]]): A two-dimensional list representing the matrix for which the rank is to be computed.
**Returns:**
str: JSON string containing the rank of the matrix in the
`"result"` field. The rank is represented as an integer.
If an error occurs,the JSON string will include an
`"error"` field with the corresponding error message.
### compute\_inner\_product
```python theme={"system"}
def compute_inner_product(self, vector1: List[float], vector2: List[float]):
```
Computes the inner (dot) product of two vectors.
**Parameters:**
* **vector1** (List\[float]): The first vector as a list of floats.
* **vector2** (List\[float]): The second vector as a list of floats.
**Returns:**
str: JSON string containing the inner product in the `"result"`
field. If an error occurs, the JSON string will include an
`"error"` field with the corresponding error message.
### handle\_exception
```python theme={"system"}
def handle_exception(self, func_name: str, error: Exception):
```
Handles exceptions by logging and returning error details.
**Parameters:**
* **func\_name** (str): The name of the function where the exception occurred.
* **error** (Exception): The exception object containing details about the error.
**Returns:**
str: JSON string containing the error details.
The JSON includes:
* `"status"`: Always set to `"error"`.
* `"message"`: A string representation of the
exception message.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of `FunctionTool` objects representing
the toolkit's methods, making them accessible to the agent.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.task_planning_toolkit
## TaskPlanningToolkit
```python theme={"system"}
class TaskPlanningToolkit(BaseToolkit):
```
A toolkit for task decomposition and re-planning.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the TaskPlanningToolkit.
**Parameters:**
* **timeout** (Optional\[float]): The timeout for the toolkit. (default: :obj:`None`)
### decompose\_task
```python theme={"system"}
def decompose_task(
self,
original_task_content: str,
sub_task_contents: List[str],
original_task_id: Optional[str] = None
):
```
Use the tool to decompose an original task into several sub-tasks.
It creates new Task objects from the provided original task content,
used when the original task is complex and needs to be decomposed.
**Parameters:**
* **original\_task\_content** (str): The content of the task to be decomposed.
* **sub\_task\_contents** (List\[str]): A list of strings, where each string is the content for a new sub-task.
* **original\_task\_id** (Optional\[str]): The id of the task to be decomposed. If not provided, a new id will be generated. (default: :obj:`None`)
**Returns:**
List\[Task]: A list of newly created sub-task objects.
### replan\_tasks
```python theme={"system"}
def replan_tasks(
self,
original_task_content: str,
sub_task_contents: List[str],
original_task_id: Optional[str] = None
):
```
Use the tool to re\_decompose a task into several subTasks.
It creates new Task objects from the provided original task content,
used when the decomposed tasks are not good enough to help finish
the task.
**Parameters:**
* **original\_task\_content** (str): The content of the task to be decomposed.
* **sub\_task\_contents** (List\[str]): A list of strings, where each string is the content for a new sub-task.
* **original\_task\_id** (Optional\[str]): The id of the task to be decomposed. (default: :obj:`None`)
**Returns:**
List\[Task]: Reordered or modified tasks.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.terminal_toolkit
## TerminalToolkit
```python theme={"system"}
class TerminalToolkit(BaseToolkit):
```
A toolkit for terminal operations across multiple operating systems.
This toolkit provides a set of functions for terminal operations such as
searching for files by name or content, executing shell commands, and
managing terminal sessions.
**Parameters:**
* **timeout** (Optional\[float]): The timeout for terminal operations. (default: :obj:`20.0`)
* **shell\_sessions** (Optional\[Dict\[str, Any]]): A dictionary to store shell session information. If :obj:`None`, an empty dictionary will be used. (default: :obj:`None`)
* **working\_directory** (Optional\[str]): The working directory for operations. If not provided, it will be determined by the `CAMEL_WORKDIR` environment variable (if set). If the environment variable is not set, it defaults to `./workspace`. All execution and write operations will be restricted to this directory. Read operations can access paths outside this directory. (default: :obj:`None`)
* **need\_terminal** (bool): Whether to create a terminal interface. (default: :obj:`True`)
* **use\_shell\_mode** (bool): Whether to use shell mode for command execution. (default: :obj:`True`)
* **clone\_current\_env** (bool): Whether to clone the current Python environment. (default: :obj:`False`)
* **safe\_mode** (bool): Whether to enable safe mode to restrict operations. (default: :obj:`True`)
* **interactive** (bool): Whether to use interactive mode for shell commands, connecting them to the terminal's standard input. This is useful for commands that require user input, like `ssh`. Interactive mode is only supported on macOS and Linux. (default: :obj:`False`)
* **log\_dir** (Optional\[str]): Custom directory path for log files. If None, logs are saved to the current working directory. (default: :obj:`None`)
**Note:**
Most functions are compatible with Unix-based systems (macOS, Linux).
For Windows compatibility, additional implementation details are
needed.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = 20.0,
shell_sessions: Optional[Dict[str, Any]] = None,
working_directory: Optional[str] = None,
need_terminal: bool = True,
use_shell_mode: bool = True,
clone_current_env: bool = False,
safe_mode: bool = True,
interactive: bool = False,
log_dir: Optional[str] = None
):
```
### \_setup\_file\_output
```python theme={"system"}
def _setup_file_output(self):
```
Set up file output to replace GUI, using a fixed file to simulate
terminal.
### \_clone\_current\_environment
```python theme={"system"}
def _clone_current_environment(self):
```
Create a new Python virtual environment.
### \_is\_uv\_environment
```python theme={"system"}
def _is_uv_environment(self):
```
Detect whether the current Python runtime is managed by uv.
### \_ensure\_uv\_available
```python theme={"system"}
def _ensure_uv_available(self):
```
**Returns:**
bool: True if uv is available (either already installed or
successfully installed), False otherwise.
### \_prepare\_initial\_environment
```python theme={"system"}
def _prepare_initial_environment(self):
```
Prepare initial environment with Python 3.10, pip, and other
essential tools.
### \_setup\_initial\_env\_with\_uv
```python theme={"system"}
def _setup_initial_env_with_uv(self):
```
Set up initial environment using uv.
### \_setup\_initial\_env\_with\_venv
```python theme={"system"}
def _setup_initial_env_with_venv(self):
```
Set up initial environment using standard venv.
### \_check\_nodejs\_availability
```python theme={"system"}
def _check_nodejs_availability(self):
```
Check if Node.js is available without modifying the system.
### \_create\_terminal
```python theme={"system"}
def _create_terminal(self):
```
Create a terminal GUI. If GUI creation fails, fallback
to file output.
### \_update\_terminal\_output
```python theme={"system"}
def _update_terminal_output(self, output: str):
```
Update terminal output and send to agent.
**Parameters:**
* **output** (str): The output to be sent to the agent
### \_is\_path\_within\_working\_dir
```python theme={"system"}
def _is_path_within_working_dir(self, path: str):
```
Check if the path is within the working directory.
**Parameters:**
* **path** (str): The path to check
**Returns:**
bool: Returns True if the path is within the working directory,
otherwise returns False
### \_enforce\_working\_dir\_for\_execution
```python theme={"system"}
def _enforce_working_dir_for_execution(self, path: str):
```
Enforce working directory restrictions, return error message
if execution path is not within the working directory.
**Parameters:**
* **path** (str): The path to be used for executing operations
**Returns:**
Optional\[str]: Returns error message if the path is not within
the working directory, otherwise returns None
### \_copy\_external\_file\_to\_workdir
```python theme={"system"}
def _copy_external_file_to_workdir(self, external_file: str):
```
Copy external file to working directory.
**Parameters:**
* **external\_file** (str): The path of the external file
**Returns:**
Optional\[str]: New path after copying to the working directory,
returns None on failure
### \_sanitize\_command
```python theme={"system"}
def _sanitize_command(self, command: str, exec_dir: str):
```
Check and modify command to ensure safety.
**Parameters:**
* **command** (str): The command to check
* **exec\_dir** (str): The directory to execute the command in
**Returns:**
Tuple: (is safe, modified command or error message)
### shell\_exec
```python theme={"system"}
def shell_exec(self, id: str, command: str):
```
Executes a shell command in a specified session.
This function creates and manages shell sessions to execute commands,
simulating a real terminal. The behavior depends on the toolkit's
interactive mode setting. Each session is identified by a unique ID.
If a session with the given ID does not exist, it will be created.
**Parameters:**
* **id** (str): A unique identifier for the shell session. This is used to manage multiple concurrent shell processes.
* **command** (str): The shell command to be executed.
**Returns:**
str: The standard output and standard error from the command. If an
error occurs during execution, a descriptive error message is
returned.
**Note:**
When the toolkit is initialized with interactive mode, commands may
block if they require input. In safe mode, some commands that are
considered dangerous are restricted.
### shell\_view
```python theme={"system"}
def shell_view(self, id: str):
```
View the full output history of a specified shell session.
Retrieves the accumulated output (both stdout and stderr) generated by
commands in the specified session since its creation. This is useful
for checking the complete history of a session, especially after a
command has finished execution.
**Parameters:**
* **id** (str): The unique identifier of the shell session to view.
**Returns:**
str: The complete output history of the shell session. Returns an
error message if the session is not found.
### shell\_wait
```python theme={"system"}
def shell_wait(self, id: str, seconds: Optional[int] = None):
```
Wait for a command to finish in a specified shell session.
Blocks execution and waits for the running process in a shell session
to complete. This is useful for ensuring a long-running command has
finished before proceeding.
**Parameters:**
* **id** (str): The unique identifier of the target shell session.
* **seconds** (Optional\[int], optional): The maximum time to wait, in seconds. If `None`, it waits indefinitely. (default: :obj:`None`)
**Returns:**
str: A message indicating that the process has completed, including
the final output. If the process times out, it returns a
timeout message.
### shell\_write\_to\_process
```python theme={"system"}
def shell_write_to_process(
self,
id: str,
input: str,
press_enter: bool
):
```
Write input to a running process in a specified shell session.
Sends a string of text to the standard input of a running process.
This is useful for interacting with commands that require input. This
function cannot be used with a command that was started in
interactive mode.
**Parameters:**
* **id** (str): The unique identifier of the target shell session.
* **input** (str): The text to write to the process's stdin.
* **press\_enter** (bool): If `True`, a newline character (`\n`) is appended to the input, simulating pressing the Enter key.
**Returns:**
str: A status message indicating whether the input was sent, or an
error message if the operation fails.
### shell\_kill\_process
```python theme={"system"}
def shell_kill_process(self, id: str):
```
Terminate a running process in a specified shell session.
Forcibly stops a command that is currently running in a shell session.
This is useful for ending processes that are stuck, running too long,
or need to be cancelled.
**Parameters:**
* **id** (str): The unique identifier of the shell session containing the process to be terminated.
**Returns:**
str: A status message indicating that the process has been
terminated, or an error message if the operation fails.
### ask\_user\_for\_help
```python theme={"system"}
def ask_user_for_help(self, id: str):
```
Pause the agent and ask a human for help with a command.
This function should be used when the agent is stuck and requires
manual intervention, such as solving a CAPTCHA or debugging a complex
issue. It pauses the agent's execution and allows a human to take
control of a specified shell session. The human can execute one
command to resolve the issue, and then control is returned to the
agent.
**Parameters:**
* **id** (str): The identifier of the shell session for the human to interact with. If the session does not exist, it will be created.
**Returns:**
str: A status message indicating that the human has finished,
including the number of commands executed. If the takeover
times out or fails, an error message is returned.
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up resources when the object is being destroyed.
Terminates all running processes and closes any open file handles.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.terminal_toolkit.terminal_toolkit
## \_to\_plain
```python theme={"system"}
def _to_plain(text: str):
```
Convert ANSI text to plain text using rich if available.
## TerminalToolkit
```python theme={"system"}
class TerminalToolkit(BaseToolkit):
```
A toolkit for LLM agents to execute and interact with terminal commands
in either a local or a sandboxed Docker environment.
**Parameters:**
* **timeout** (Optional\[float]): The default timeout in seconds for blocking commands. Defaults to 20.0.
* **working\_directory** (Optional\[str]): The base directory for operations. For the local backend, this acts as a security sandbox. For the Docker backend, this sets the working directory inside the container. If not specified, defaults to "./workspace" for local and "/workspace" for Docker.
* **use\_docker\_backend** (bool): If True, all commands are executed in a Docker container. Defaults to False.
* **docker\_container\_name** (Optional\[str]): The name of the Docker container to use. Required if use\_docker\_backend is True.
* **session\_logs\_dir** (Optional\[str]): The directory to store session logs. Defaults to a 'terminal\_logs' subfolder in the working directory.
* **safe\_mode** (bool): Whether to apply security checks to commands. Defaults to True.
* **allowed\_commands** (Optional\[List\[str]]): List of allowed commands when safe\_mode is True. If None, uses default safety rules.
* **clone\_current\_env** (bool): Whether to clone the current Python environment for local execution. Defaults to False.
* **install\_dependencies** (List): A list of user specified libraries to install.
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = 20.0,
working_directory: Optional[str] = None,
use_docker_backend: bool = False,
docker_container_name: Optional[str] = None,
session_logs_dir: Optional[str] = None,
safe_mode: bool = True,
allowed_commands: Optional[List[str]] = None,
clone_current_env: bool = False,
install_dependencies: Optional[List[str]] = None
):
```
### \_setup\_cloned\_environment
```python theme={"system"}
def _setup_cloned_environment(self):
```
Set up a cloned Python environment.
### \_install\_dependencies
```python theme={"system"}
def _install_dependencies(self):
```
Install user specified dependencies in the current environment.
### \_setup\_initial\_environment
```python theme={"system"}
def _setup_initial_environment(self):
```
Set up an initial environment with Python 3.10.
### \_get\_venv\_path
```python theme={"system"}
def _get_venv_path(self):
```
Get the virtual environment path if available.
### \_write\_to\_log
```python theme={"system"}
def _write_to_log(self, log_file: str, content: str):
```
Write content to log file with optional ANSI stripping.
**Parameters:**
* **log\_file** (str): Path to the log file
* **content** (str): Content to write
### \_sanitize\_command
```python theme={"system"}
def _sanitize_command(self, command: str):
```
A comprehensive command sanitizer for both local and
Docker backends.
### \_start\_output\_reader\_thread
```python theme={"system"}
def _start_output_reader_thread(self, session_id: str):
```
Starts a thread to read stdout from a non-blocking process.
### \_collect\_output\_until\_idle
```python theme={"system"}
def _collect_output_until_idle(
self,
id: str,
idle_duration: float = 0.5,
max_wait: float = 5.0
):
```
Collects output from a session until it's idle or a max wait time
is reached.
**Parameters:**
* **id** (str): The session ID.
* **idle\_duration** (float): How long the stream must be empty to be considered idle.(default: 0.5)
* **max\_wait** (float): The maximum total time to wait for the process to go idle. (default: 5.0)
**Returns:**
str: The collected output. If max\_wait is reached while
the process is still outputting, a warning is appended.
### shell\_exec
```python theme={"system"}
def shell_exec(
self,
id: str,
command: str,
block: bool = True,
timeout: float = 20.0
):
```
Executes a shell command in blocking or non-blocking mode.
**Parameters:**
* **id** (str): A unique identifier for the command's session. This ID is used to interact with non-blocking processes.
* **command** (str): The shell command to execute.
* **block** (bool, optional): Determines the execution mode. Defaults to True. If `True` (blocking mode), the function waits for the command to complete and returns the full output. Use this for most commands. If `False` (non-blocking mode), the function starts the command in the background. Use this only for interactive sessions or long-running tasks, or servers.
* **timeout** (float, optional): The maximum time in seconds to wait for the command to complete in blocking mode. If the command does not complete within the timeout, it will be converted to a tracked background session (process keeps running without restart). You can then use `shell_view(id)` to check output, or `shell_kill_process(id)` to terminate it. This parameter is ignored in non-blocking mode. (default: :obj:`20`)
**Returns:**
str: The output of the command execution, which varies by mode.
In blocking mode, returns the complete standard output and
standard error from the command.
In non-blocking mode, returns a confirmation message with the
session `id`. To interact with the background process, use
other functions: `shell_view(id)` to see output,
`shell_write_to_process(id, "input")` to send input, and
`shell_kill_process(id)` to terminate.
### shell\_write\_to\_process
```python theme={"system"}
def shell_write_to_process(self, id: str, command: str):
```
This function sends command to a running non-blocking
process and returns the resulting output after the process
becomes idle again. A newline \n is automatically appended
to the input command.
**Parameters:**
* **id** (str): The unique session ID of the non-blocking process.
* **command** (str): The text to write to the process's standard input.
**Returns:**
str: The output from the process after the command is sent.
### shell\_view
```python theme={"system"}
def shell_view(self, id: str):
```
Retrieves new output from a non-blocking session.
This function returns only NEW output since the last call. It does NOT
wait or block - it returns immediately with whatever is available.
**Parameters:**
* **id** (str): The unique session ID of the non-blocking process.
**Returns:**
str: New output if available, or a status message.
### shell\_kill\_process
```python theme={"system"}
def shell_kill_process(self, id: str):
```
This function forcibly terminates a running non-blocking process.
**Parameters:**
* **id** (str): The unique session ID of the process to kill.
**Returns:**
str: A confirmation message indicating the process was terminated.
### shell\_ask\_user\_for\_help
```python theme={"system"}
def shell_ask_user_for_help(self, id: str, prompt: str):
```
This function pauses execution and asks a human for help
with an interactive session.
This method can handle different scenarios:
1. If session exists: Shows session output and allows interaction
2. If session doesn't exist: Creates a temporary session for help
**Parameters:**
* **id** (str): The session ID of the interactive process needing help. Can be empty string for general help without session context.
* **prompt** (str): The question or instruction from the LLM to show the human user (e.g., "The program is asking for a filename. Please enter 'config.json'.").
**Returns:**
str: The output from the shell session after the user's command has
been executed, or help information for general queries.
### shell\_write\_content\_to\_file
```python theme={"system"}
def shell_write_content_to_file(self, content: str, file_path: str):
```
Writes the specified content to a file at the given path.
**Parameters:**
* **content** (str): The content to write to the file.
* **file\_path** (str): The path to the file where the content should be written. Can be absolute or relative to working\_dir.
**Returns:**
str: A confirmation message indicating success or an error message.
### **enter**
```python theme={"system"}
def __enter__(self):
```
Context manager entry.
### **exit**
```python theme={"system"}
def __exit__(
self,
exc_type,
exc_val,
exc_tb
):
```
Context manager exit - clean up all sessions.
### cleanup
```python theme={"system"}
def cleanup(self):
```
Clean up all active sessions.
### **del**
```python theme={"system"}
def __del__(self):
```
Fallback cleanup in destructor.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing the
functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.terminal_toolkit.utils
## check\_command\_safety
```python theme={"system"}
def check_command_safety(command: str, allowed_commands: Optional[Set[str]] = None):
```
Check if a command (potentially with chaining) is safe to execute.
**Parameters:**
* **command** (str): The command string to check
* **allowed\_commands** (Optional\[Set\[str]]): Set of allowed commands (whitelist mode)
**Returns:**
Tuple\[bool, str]: (is\_safe, reason)
## sanitize\_command
```python theme={"system"}
def sanitize_command(
command: str,
use_docker_backend: bool = False,
safe_mode: bool = True,
working_dir: Optional[str] = None,
allowed_commands: Optional[Set[str]] = None
):
```
A comprehensive command sanitizer for both local and Docker backends.
**Parameters:**
* **command** (str): The command to sanitize
* **use\_docker\_backend** (bool): Whether using Docker backend
* **safe\_mode** (bool): Whether to apply security checks
* **working\_dir** (Optional\[str]): Working directory for path validation
* **allowed\_commands** (Optional\[Set\[str]]): Set of allowed commands
**Returns:**
Tuple\[bool, str]: (is\_safe, message\_or\_command)
## is\_uv\_environment
```python theme={"system"}
def is_uv_environment():
```
Detect whether the current Python runtime is managed by uv.
## ensure\_uv\_available
```python theme={"system"}
def ensure_uv_available(update_callback = None):
```
Ensure uv is available, installing it if necessary.
**Parameters:**
* **update\_callback**: Optional callback function to receive status updates
**Returns:**
Tuple\[bool, Optional\[str]]: (success, uv\_path)
## setup\_initial\_env\_with\_uv
```python theme={"system"}
def setup_initial_env_with_uv(
env_path: str,
uv_path: str,
working_dir: str,
update_callback = None
):
```
Set up initial environment using uv.
## setup\_initial\_env\_with\_venv
```python theme={"system"}
def setup_initial_env_with_venv(env_path: str, working_dir: str, update_callback = None):
```
Set up initial environment using standard venv.
## clone\_current\_environment
```python theme={"system"}
def clone_current_environment(env_path: str, working_dir: str, update_callback = None):
```
Clone the current Python environment to a new virtual environment.
This function creates a new virtual environment with the same Python
version as the current environment and installs all packages from
the current environment.
**Parameters:**
* **env\_path**: Path where the new environment will be created.
* **working\_dir**: Working directory for subprocess commands.
* **update\_callback**: Optional callback for status updates.
**Returns:**
True if the environment was created successfully, False otherwise.
## check\_nodejs\_availability
```python theme={"system"}
def check_nodejs_availability(update_callback = None):
```
Check if Node.js is available without modifying the system.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.thinking_toolkit
## ThinkingToolkit
```python theme={"system"}
class ThinkingToolkit(BaseToolkit):
```
A toolkit for recording thoughts during reasoning processes.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initialize the ThinkingToolkit.
**Parameters:**
* **timeout** (Optional\[float]): The timeout for the toolkit. (default: :obj:`None`)
### plan
```python theme={"system"}
def plan(self, plan: str):
```
Use the tool to create a plan or strategy.
This tool is for outlining the approach or steps to be taken before
starting the actual thinking process.
**Parameters:**
* **plan** (str): A forward-looking plan or strategy.
**Returns:**
str: The recorded plan.
### hypothesize
```python theme={"system"}
def hypothesize(self, hypothesis: str):
```
Use the tool to form a hypothesis or make a prediction.
This tool is for making educated guesses or predictions based on
the plan, before detailed thinking.
**Parameters:**
* **hypothesis** (str): A hypothesis or prediction to test.
**Returns:**
str: The recorded hypothesis.
### think
```python theme={"system"}
def think(self, thought: str):
```
Use the tool to think about something.
It will not obtain new information or change the database, but just
append the thought to the log. Use it for initial thoughts and
observations during the execution of the plan.
**Parameters:**
* **thought** (str): A thought to think about.
**Returns:**
str: The recorded thought.
### contemplate
```python theme={"system"}
def contemplate(self, contemplation: str):
```
Use the tool to deeply contemplate an idea or concept.
This tool is for deeper, more thorough exploration of thoughts,
considering multiple perspectives and implications. It's more
comprehensive than basic thinking but more focused than reflection.
**Parameters:**
* **contemplation** (str): A deeper exploration of thoughts or concepts.
**Returns:**
str: The recorded contemplation.
### critique
```python theme={"system"}
def critique(self, critique: str):
```
Use the tool to critically evaluate current thoughts.
This tool is for identifying potential flaws, biases, or
weaknesses in the current thinking process.
**Parameters:**
* **critique** (str): A critical evaluation of current thoughts.
**Returns:**
str: The recorded critique.
### synthesize
```python theme={"system"}
def synthesize(self, synthesis: str):
```
Use the tool to combine and integrate various thoughts.
This tool is for bringing together different thoughts, contemplations,
and critiques into a coherent understanding.
**Parameters:**
* **synthesis** (str): An integration of multiple thoughts and insights.
**Returns:**
str: The recorded synthesis.
### reflect
```python theme={"system"}
def reflect(self, reflection: str):
```
Use the tool to reflect on the entire process.
This tool is for final evaluation of the entire thinking process,
including plans, hypotheses, thoughts, contemplations, critiques,
and syntheses.
**Parameters:**
* **reflection** (str): A comprehensive reflection on the process.
**Returns:**
str: The recorded reflection.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.twitter_toolkit
## create\_tweet
```python theme={"system"}
def create_tweet(
text: str,
poll_options: Optional[List[str]] = None,
poll_duration_minutes: Optional[int] = None,
quote_tweet_id: Optional[Union[int, str]] = None
):
```
Creates a new tweet, optionally including a poll or a quote tweet,
or simply a text-only tweet.
This function sends a POST request to the Twitter API to create a new
tweet. The tweet can be a text-only tweet, or optionally include a poll
or be a quote tweet. A confirmation prompt is presented to the user
before the tweet is created.
**Parameters:**
* **text** (str): The text of the tweet. The Twitter character limit for a single tweet is 280 characters.
* **poll\_options** (Optional\[List\[str]]): A list of poll options for a tweet with a poll.
* **poll\_duration\_minutes** (Optional\[int]): Duration of the poll in minutes for a tweet with a poll. This is only required if the request includes poll\_options.
* **quote\_tweet\_id** (Optional\[Union\[int, str]]): Link to the tweet being quoted.
**Returns:**
str: A message indicating the success of the tweet creation,
including the tweet ID and text. If the request to the
Twitter API is not successful, the return is an error message.
**Note:**
You can only provide either the `quote_tweet_id` parameter or
the pair of `poll_duration_minutes` and `poll_options` parameters,
not both.
Reference:
[https://developer.x.com/en/docs/x-api/tweets/manage-tweets/api-reference/post-tweets](https://developer.x.com/en/docs/x-api/tweets/manage-tweets/api-reference/post-tweets)
## delete\_tweet
```python theme={"system"}
def delete_tweet(tweet_id: str):
```
Deletes a tweet with the specified ID for an authorized user.
This function sends a DELETE request to the Twitter API to delete
a tweet with the specified ID. Before sending the request, it
prompts the user to confirm the deletion.
**Parameters:**
* **tweet\_id** (str): The ID of the tweet to delete.
**Returns:**
str: A message indicating the result of the deletion. If the
deletion was successful, the message includes the ID of the
deleted tweet. If the deletion was not successful, the message
includes an error message.
Reference:
[https://developer.x.com/en/docs/x-api/tweets/manage-tweets/api-reference/delete-tweets-id](https://developer.x.com/en/docs/x-api/tweets/manage-tweets/api-reference/delete-tweets-id)
## get\_my\_user\_profile
```python theme={"system"}
def get_my_user_profile():
```
**Returns:**
str: A formatted report of the authenticated user's Twitter profile
information. This includes their ID, name, username,
description, location, most recent tweet ID, profile image URL,
account creation date, protection status, verification type,
public metrics, and pinned tweet information. If the request to
the Twitter API is not successful, the return is an error message.
Reference:
[https://developer.x.com/en/docs/x-api/users/lookup/api-reference/get-users-me](https://developer.x.com/en/docs/x-api/users/lookup/api-reference/get-users-me)
## get\_user\_by\_username
```python theme={"system"}
def get_user_by_username(username: str):
```
Retrieves one user's Twitter profile info by username (handle).
This function sends a GET request to the Twitter API to retrieve the
user's profile information, including their pinned tweet.
It then formats this information into a readable report.
**Parameters:**
* **username** (str): The username (handle) of the user to retrieve.
**Returns:**
str: A formatted report of the user's Twitter profile information.
This includes their ID, name, username, description, location,
most recent tweet ID, profile image URL, account creation date,
protection status, verification type, public metrics, and
pinned tweet information. If the request to the Twitter API is
not successful, the return is an error message.
Reference:
[https://developer.x.com/en/docs/x-api/users/lookup/api-reference/get-users-by-username-username](https://developer.x.com/en/docs/x-api/users/lookup/api-reference/get-users-by-username-username)
## \_get\_user\_info
```python theme={"system"}
def _get_user_info(username: Optional[str] = None):
```
Generates a formatted report of the user information from the
JSON response.
**Parameters:**
* **username** (Optional\[str], optional): The username of the user to retrieve. If None, the function retrieves the authenticated user's profile information. (default: :obj:`None`)
**Returns:**
str: A formatted report of the user's Twitter profile information.
## \_handle\_http\_error
```python theme={"system"}
def _handle_http_error(response: requests.Response):
```
Handles the HTTP response by checking the status code and
returning an appropriate message if there is an error.
**Parameters:**
* **response** (requests.Response): The HTTP response to handle.
**Returns:**
str: A string describing the error, if any. If there is no error,
the function returns an "Unexpected Exception" message.
Reference:
[https://github.com/tweepy/tweepy/blob/master/tweepy/client.py#L64](https://github.com/tweepy/tweepy/blob/master/tweepy/client.py#L64)
## TwitterToolkit
```python theme={"system"}
class TwitterToolkit(BaseToolkit):
```
A class representing a toolkit for Twitter operations.
This class provides methods for creating a tweet, deleting a tweet, and
getting the authenticated user's profile information.
References:
[https://developer.x.com/en/portal/dashboard](https://developer.x.com/en/portal/dashboard)
**Note:**
To use this toolkit, you need to set the following environment
variables:
* TWITTER\_CONSUMER\_KEY: The consumer key for the Twitter API.
* TWITTER\_CONSUMER\_SECRET: The consumer secret for the Twitter API.
* TWITTER\_ACCESS\_TOKEN: The access token for the Twitter API.
* TWITTER\_ACCESS\_TOKEN\_SECRET: The access token secret for the Twitter
API.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.vertex_ai_veo_toolkit
## VertexAIVeoToolkit
```python theme={"system"}
class VertexAIVeoToolkit(BaseToolkit):
```
A toolkit for interacting with Google Vertex AI Veo video generation.
This toolkit provides methods for generating videos using Google's Veo,
supporting both text-to-video and image-to-video generation with various
customization options.
### **init**
```python theme={"system"}
def __init__(
self,
project_id: Optional[str] = None,
location: str = 'us-central1',
model_id: str = 'veo-2.0-generate-001',
output_storage_uri: Optional[str] = None,
timeout: Optional[float] = None
):
```
Initialize the Vertex AI Veo toolkit.
**Parameters:**
* **project\_id** (Optional\[str]): Google Cloud project ID. If not provided, will use the default project from environment. (default: :obj:`None`)
* **location** (str): Google Cloud location for the API calls. (default: :obj:`"us-central1"`)
* **model\_id** (str): The Veo model ID to use. Options include "veo-2.0-generate-001" or "veo-3.0-generate-preview". (default: :obj:`"veo-2.0-generate-001"`)
* **output\_storage\_uri** (Optional\[str]): Cloud Storage URI to save output videos. If not provided, returns video bytes. (default: :obj:`None`)
* **timeout** (Optional\[float]): Request timeout in seconds. (default: :obj:`None`)
### generate\_video\_from\_text
```python theme={"system"}
def generate_video_from_text(
self,
text_prompt: str,
response_count: int = 1,
duration: int = 5,
aspect_ratio: str = '16:9',
negative_prompt: Optional[str] = None,
person_generation: str = 'allow_adult'
):
```
Generate video from text prompt using Vertex AI Veo.
**Parameters:**
* **text\_prompt** (str): The text prompt to guide video generation.
* **response\_count** (int): Number of videos to generate (1-4). (default: :obj:`1`)
* **duration** (int): Video duration in seconds (5-8). (default: :obj:`5`)
* **aspect\_ratio** (str): Video aspect ratio. Options: "16:9", "9:16". (default: :obj:`"16:9"`)
* **negative\_prompt** (Optional\[str]): What to avoid in the video. (default: :obj:`None`)
* **person\_generation** (str): Person safety setting. Options: "allow\_adult", "dont\_allow". (default: :obj:`"allow_adult"`)
**Returns:**
Dict\[str, Any]:
A dictionary containing:
* 'success' (bool): Whether the operation was successful
* 'videos' (List\[Dict]): List of generated video data
* 'metadata' (Dict): Additional metadata from the response
* 'error' (str): Error message if operation failed
### generate\_video\_from\_image
```python theme={"system"}
def generate_video_from_image(
self,
image_path: str,
text_prompt: str,
response_count: int = 1,
duration: int = 5,
aspect_ratio: str = '16:9',
negative_prompt: Optional[str] = None,
person_generation: str = 'allow_adult'
):
```
Generate video from image and text prompt using Vertex AI Veo.
**Parameters:**
* **image\_path** (str): Path to the input image file (local or GCS URI).
* **text\_prompt** (str): The text prompt to guide video generation.
* **response\_count** (int): Number of videos to generate (1-4). (default: :obj:`1`)
* **duration** (int): Video duration in seconds (5-8). (default: :obj:`5`)
* **aspect\_ratio** (str): Video aspect ratio. Options: "16:9", "9:16". (default: :obj:`"16:9"`)
* **negative\_prompt** (Optional\[str]): What to avoid in the video. (default: :obj:`None`)
* **person\_generation** (str): Person safety setting. (default: :obj:`"allow_adult"`)
**Returns:**
Dict\[str, Any]:
A dictionary containing:
* 'success' (bool): Whether the operation was successful
* 'videos' (List\[Dict]): List of generated video data
* 'metadata' (Dict): Additional metadata from the response
* 'error' (str): Error message if operation failed
### extend\_video
```python theme={"system"}
def extend_video(
self,
video_uri: str,
text_prompt: str,
duration: int = 5,
aspect_ratio: str = '16:9',
negative_prompt: Optional[str] = None
):
```
Extend an existing video using Vertex AI Veo.
**Parameters:**
* **video\_uri** (str): Cloud Storage URI of the video to extend.
* **text\_prompt** (str): The text prompt to guide video extension.
* **duration** (int): Duration to extend in seconds (5-8). (default: :obj:`5`)
* **aspect\_ratio** (str): Video aspect ratio. (default: :obj:`"16:9"`)
* **negative\_prompt** (Optional\[str]): What to avoid in the extension. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]:
A dictionary containing:
* 'success' (bool): Whether the operation was successful
* 'videos' (List\[Dict]): List of extended video data
* 'metadata' (Dict): Additional metadata from the response
* 'error' (str): Error message if operation failed
### \_process\_image
```python theme={"system"}
def _process_image(self, image_path: str):
```
Process image file and return base64 encoded data and MIME type.
### \_parse\_video\_response
```python theme={"system"}
def _parse_video_response(self, response: Any):
```
Parse the video generation response.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available function tools.
### get\_async\_tools
```python theme={"system"}
def get_async_tools(self):
```
**Returns:**
List\[FunctionTool]: List of available async function tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.video_analysis_toolkit
## VideoAnalysisToolkit
```python theme={"system"}
class VideoAnalysisToolkit(BaseToolkit):
```
A class for analysing videos with vision-language model.
**Parameters:**
* **working\_directory** (Optional\[str], optional): The directory where the video will be downloaded to. If not provided, video will be stored in a temporary directory and will be cleaned up after use. (default: :obj:`None`)
* **model** (Optional\[BaseModelBackend], optional): The model to use for visual analysis. (default: :obj:`None`)
* **use\_audio\_transcription** (bool, optional): Whether to enable audio transcription using OpenAI's audio models. Requires a valid OpenAI API key. When disabled, video analysis will be based solely on visual content. (default: :obj:`False`)
* **use\_ocr** (bool, optional): Whether to enable OCR for extracting text from video frames. (default: :obj:`False`)
* **frame\_interval** (float, optional): Interval in seconds between frames to extract from the video. (default: :obj:`4.0`)
* **output\_language** (str, optional): The language for output responses. (default: :obj:`"English"`)
* **cookies\_path** (Optional\[str]): The path to the cookies file for the video service in Netscape format. (default: :obj:`None`)
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
model: Optional[BaseModelBackend] = None,
use_audio_transcription: bool = False,
use_ocr: bool = False,
frame_interval: float = 4.0,
output_language: str = 'English',
cookies_path: Optional[str] = None,
timeout: Optional[float] = None
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Clean up temporary directories and files when the object is
destroyed.
### \_extract\_text\_from\_frame
```python theme={"system"}
def _extract_text_from_frame(self, frame: Image.Image):
```
Extract text from a video frame using OCR.
**Parameters:**
* **frame** (Image.Image): PIL image frame to process.
**Returns:**
str: Extracted text from the frame.
### \_process\_extracted\_text
```python theme={"system"}
def _process_extracted_text(self, text: str):
```
Clean and format OCR-extracted text.
**Parameters:**
* **text** (str): Raw extracted OCR text.
**Returns:**
str: Cleaned and formatted text.
### \_extract\_audio\_from\_video
```python theme={"system"}
def _extract_audio_from_video(self, video_path: str, output_format: str = 'mp3'):
```
Extract audio from the video.
**Parameters:**
* **video\_path** (str): The path to the video file.
* **output\_format** (str): The format of the audio file to be saved. (default: :obj:`"mp3"`)
**Returns:**
str: The path to the audio file.
### \_transcribe\_audio
```python theme={"system"}
def _transcribe_audio(self, audio_path: str):
```
Transcribe the audio of the video.
### \_extract\_keyframes
```python theme={"system"}
def _extract_keyframes(self, video_path: str):
```
Extract keyframes from a video based on scene changes and
regular intervals,and return them as PIL.Image.Image objects.
**Parameters:**
* **video\_path** (str): Path to the video file.
**Returns:**
List\[Image.Image]: A list of PIL.Image.Image objects representing
the extracted keyframes.
### \_normalize\_frames
```python theme={"system"}
def _normalize_frames(self, frames: List[Image.Image], target_width: int = 512):
```
Normalize the size of extracted frames.
**Parameters:**
* **frames** (List\[Image.Image]): List of frames to normalize.
* **target\_width** (int): Target width for normalized frames.
**Returns:**
List\[Image.Image]: List of normalized frames.
### ask\_question\_about\_video
```python theme={"system"}
def ask_question_about_video(self, video_path: str, question: str):
```
Ask a question about the video.
**Parameters:**
* **video\_path** (str): The path to the video file. It can be a local file or a URL (such as Youtube website).
* **question** (str): The question to ask about the video.
**Returns:**
str: The answer to the question.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.video_download_toolkit
## \_capture\_screenshot
```python theme={"system"}
def _capture_screenshot(video_file: str, timestamp: float):
```
Capture a screenshot from a video file at a specific timestamp.
**Parameters:**
* **video\_file** (str): The path to the video file.
* **timestamp** (float): The time in seconds from which to capture the screenshot.
**Returns:**
Image.Image: The captured screenshot in the form of Image.Image.
## VideoDownloaderToolkit
```python theme={"system"}
class VideoDownloaderToolkit(BaseToolkit):
```
A class for downloading videos and optionally splitting them into
chunks.
**Parameters:**
* **working\_directory** (Optional\[str], optional): The directory where the video will be downloaded to. If not provided, video will be stored in a temporary directory and will be cleaned up after use. (default: :obj:`None`)
* **cookies\_path** (Optional\[str], optional): The path to the cookies file for the video service in Netscape format. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
cookies_path: Optional[str] = None,
timeout: Optional[float] = None
):
```
### **del**
```python theme={"system"}
def __del__(self):
```
Deconstructor for the VideoDownloaderToolkit class.
Cleans up the downloaded video if they are stored in a temporary
directory.
### download\_video
```python theme={"system"}
def download_video(self, url: str):
```
Download the video and optionally split it into chunks.
yt-dlp will detect if the video is downloaded automatically so there
is no need to check if the video exists.
**Parameters:**
* **url** (str): The URL of the video to download.
**Returns:**
str: The path to the downloaded video file.
### get\_video\_bytes
```python theme={"system"}
def get_video_bytes(self, video_path: str):
```
Download video by the path, and return the content in bytes.
**Parameters:**
* **video\_path** (str): The path to the video file.
**Returns:**
bytes: The video file content in bytes.
### get\_video\_screenshots
```python theme={"system"}
def get_video_screenshots(self, video_path: str, amount: int):
```
Capture screenshots from the video at specified timestamps or by
dividing the video into equal parts if an integer is provided.
**Parameters:**
* **video\_path** (str): The local path or URL of the video to take screenshots.
* **amount** (int): the amount of evenly split screenshots to capture.
**Returns:**
List\[Image.Image]: A list of screenshots as Image.Image.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.weather_toolkit
## WeatherToolkit
```python theme={"system"}
class WeatherToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with weather data.
This class provides methods for fetching weather data for a given city
using the OpenWeatherMap API.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes a new instance of the WeatherToolkit class.
**Parameters:**
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### get\_openweathermap\_api\_key
```python theme={"system"}
def get_openweathermap_api_key(self):
```
**Returns:**
str: The OpenWeatherMap API key.
### get\_weather\_data
```python theme={"system"}
def get_weather_data(
self,
city: str,
temp_units: Literal['kelvin', 'celsius', 'fahrenheit'] = 'kelvin',
wind_units: Literal['meters_sec', 'miles_hour', 'knots', 'beaufort'] = 'meters_sec',
visibility_units: Literal['meters', 'miles'] = 'meters',
time_units: Literal['unix', 'iso', 'date'] = 'unix'
):
```
Fetch and return a comprehensive weather report for a given city
as a string. The report includes current weather conditions,
temperature, wind details, visibility, and sunrise/sunset times,
all formatted as a readable string.
The function interacts with the OpenWeatherMap API to
retrieve the data.
**Parameters:**
* **city** (str): The name of the city for which the weather information is desired. Format "City, CountryCode" (e.g., "Paris, FR" for Paris, France). If the country code is not provided, the API will search for the city in all countries, which may yield incorrect results if multiple cities with the same name exist.
* **temp\_units** (`Literal['kelvin', 'celsius', 'fahrenheit']`): Units for temperature. (default: :obj:`kelvin`) wind\_units (Literal\['meters\_sec', 'miles\_hour', 'knots', 'beaufort']): Units for wind speed. (default: :obj:`meters_sec`)
* **visibility\_units** (`Literal['meters', 'miles']`): Units for visibility distance. (default: :obj:`meters`)
* **time\_units** (`Literal['unix', 'iso', 'date']`): Format for sunrise and sunset times. (default: :obj:`unix`)
**Returns:**
str: A string containing the fetched weather data, formatted in a
readable manner. If an error occurs, a message indicating the
error will be returned instead.
Example of return string:
"Weather in Paris, FR: 15°C, feels like 13°C. Max temp: 17°C,
Min temp : 12°C.
Wind: 5 m/s at 270 degrees. Visibility: 10 kilometers.
Sunrise at 05:46:05 (UTC), Sunset at 18:42:20 (UTC)."
**Note:**
Please ensure that the API key is valid and has permissions
to access the weather data.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.web_deploy_toolkit
## WebDeployToolkit
```python theme={"system"}
class WebDeployToolkit(BaseToolkit):
```
A simple toolkit for initializing React projects and deploying web.
This toolkit provides core functionality to:
* Initialize new React projects
* Build React applications
* Deploy HTML content to local server
* Serve static websites locally
### **init**
```python theme={"system"}
def __init__(
self,
timeout: Optional[float] = None,
add_branding_tag: bool = True,
logo_path: str = '../camel/misc/favicon.png',
tag_text: str = 'Created by CAMEL',
tag_url: str = 'https://github.com/camel-ai/camel',
remote_server_ip: Optional[str] = None,
remote_server_port: int = 8080
):
```
Initialize the WebDeployToolkit.
**Parameters:**
* **timeout** (Optional\[float]): Command timeout in seconds. (default: :obj:`None`)
* **add\_branding\_tag** (bool): Whether to add brand tag to deployed pages. (default: :obj:`True`)
* **logo\_path** (str): Path to custom logo file (SVG, PNG, JPG, ICO). (default: :obj:`../camel/misc/favicon.png`)
* **tag\_text** (str): Text to display in the tag. (default: :obj:`Created by CAMEL`)
* **tag\_url** (str): URL to open when tag is clicked. (default: :obj:`https://github.com/camel-ai/camel`)
* **remote\_server\_ip** (Optional\[str]): Remote server IP for deployment. (default: :obj:`None` - use local deployment)
* **remote\_server\_port** (int): Remote server port. (default: :obj:`8080`)
### \_validate\_ip\_or\_domain
```python theme={"system"}
def _validate_ip_or_domain(self, address: str):
```
Validate IP address or domain name format.
### \_validate\_port
```python theme={"system"}
def _validate_port(self, port: int):
```
Validate port number.
### \_sanitize\_text
```python theme={"system"}
def _sanitize_text(self, text: str):
```
Sanitize text to prevent XSS.
### \_validate\_url
```python theme={"system"}
def _validate_url(self, url: str):
```
Validate URL format.
### \_validate\_subdirectory
```python theme={"system"}
def _validate_subdirectory(self, subdirectory: Optional[str]):
```
Validate subdirectory to prevent path traversal.
### \_is\_port\_available
```python theme={"system"}
def _is_port_available(self, port: int):
```
Check if a port is available for binding.
### \_load\_server\_registry
```python theme={"system"}
def _load_server_registry(self):
```
Load server registry from persistent storage.
### \_save\_server\_registry
```python theme={"system"}
def _save_server_registry(self):
```
Save server registry to persistent storage.
### \_is\_process\_running
```python theme={"system"}
def _is_process_running(self, pid: int):
```
Check if a process with given PID is still running.
### \_build\_custom\_url
```python theme={"system"}
def _build_custom_url(self, domain: str, subdirectory: Optional[str] = None):
```
Build custom URL with optional subdirectory.
**Parameters:**
* **domain** (str): Custom domain
* **subdirectory** (Optional\[str]): Subdirectory path
**Returns:**
str: Complete custom URL
### \_load\_logo\_as\_data\_uri
```python theme={"system"}
def _load_logo_as_data_uri(self, logo_path: str):
```
Load a local logo file and convert it to data URI.
**Parameters:**
* **logo\_path** (str): Path to the logo file
**Returns:**
str: Data URI of the logo file
### \_get\_default\_logo
```python theme={"system"}
def _get_default_logo(self):
```
**Returns:**
str: Default logo data URI
### deploy\_html\_content
```python theme={"system"}
def deploy_html_content(
self,
html_content: Optional[str] = None,
html_file_path: Optional[str] = None,
file_name: str = 'index.html',
port: int = 8000,
domain: Optional[str] = None,
subdirectory: Optional[str] = None
):
```
Deploy HTML content to a local server or remote server.
**Parameters:**
* **html\_content** (Optional\[str]): HTML content to deploy. Either this or html\_file\_path must be provided.
* **html\_file\_path** (Optional\[str]): Path to HTML file to deploy. Either this or html\_content must be provided.
* **file\_name** (str): Name for the HTML file when using html\_content. (default: :obj:`index.html`)
* **port** (int): Port to serve on. (default: :obj:`8000`) (default: 8000)
* **domain** (Optional\[str]): Custom domain to access the content. (e.g., :obj:`example.com`)
* **subdirectory** (Optional\[str]): Subdirectory path for multi-user deployment. (e.g., :obj:`user123`)
**Returns:**
Dict\[str, Any]: Deployment result with server URL and custom domain
info.
### \_deploy\_to\_remote\_server
```python theme={"system"}
def _deploy_to_remote_server(
self,
html_content: str,
subdirectory: Optional[str] = None,
domain: Optional[str] = None
):
```
Deploy HTML content to remote server via API.
**Parameters:**
* **html\_content** (str): HTML content to deploy
* **subdirectory** (Optional\[str]): Subdirectory path for deployment
* **domain** (Optional\[str]): Custom domain
**Returns:**
Dict\[str, Any]: Deployment result
### \_deploy\_to\_local\_server
```python theme={"system"}
def _deploy_to_local_server(
self,
html_content: str,
file_name: str,
port: int,
domain: Optional[str],
subdirectory: Optional[str]
):
```
Deploy HTML content to local server (original functionality).
**Parameters:**
* **html\_content** (str): HTML content to deploy
* **file\_name** (str): Name for the HTML file
* **port** (int): Port to serve on (default: 8000) (default: 8000)
* **domain** (Optional\[str]): Custom domain
* **subdirectory** (Optional\[str]): Subdirectory path
**Returns:**
Dict\[str, Any]: Deployment result
### \_serve\_static\_files
```python theme={"system"}
def _serve_static_files(self, directory: str, port: int):
```
Serve static files from a directory using a local HTTP server
(as a background process).
**Parameters:**
* **directory** (str): Directory to serve files from
* **port** (int): Port to serve on (default: 8000) (default: 8000)
**Returns:**
Dict\[str, Any]: Server information
### deploy\_folder
```python theme={"system"}
def deploy_folder(
self,
folder_path: str,
port: int = 8000,
domain: Optional[str] = None,
subdirectory: Optional[str] = None
):
```
Deploy a folder containing web files.
**Parameters:**
* **folder\_path** (str): Path to the folder to deploy.
* **port** (int): Port to serve on. (default: :obj:`8000`) (default: 8000)
* **domain** (Optional\[str]): Custom domain to access the content. (e.g., :obj:`example.com`)
* **subdirectory** (Optional\[str]): Subdirectory path for multi-user deployment. (e.g., :obj:`user123`)
**Returns:**
Dict\[str, Any]: Deployment result with custom domain info.
### \_deploy\_folder\_to\_local\_server
```python theme={"system"}
def _deploy_folder_to_local_server(
self,
folder_path: str,
port: int,
domain: Optional[str],
subdirectory: Optional[str]
):
```
Deploy folder to local server (original functionality).
**Parameters:**
* **folder\_path** (str): Path to the folder to deploy
* **port** (int): Port to serve on
* **domain** (Optional\[str]): Custom domain
* **subdirectory** (Optional\[str]): Subdirectory path
**Returns:**
Dict\[str, Any]: Deployment result
### \_deploy\_folder\_to\_remote\_server
```python theme={"system"}
def _deploy_folder_to_remote_server(
self,
folder_path: str,
subdirectory: Optional[str] = None,
domain: Optional[str] = None
):
```
Deploy folder to remote server via API.
**Parameters:**
* **folder\_path** (str): Path to the folder to deploy
* **subdirectory** (Optional\[str]): Subdirectory path for deployment
* **domain** (Optional\[str]): Custom domain
**Returns:**
Dict\[str, Any]: Deployment result
### stop\_server
```python theme={"system"}
def stop_server(self, port: int):
```
Stop a running server on the specified port.
**Parameters:**
* **port** (int): Port of the server to stop.
**Returns:**
Dict\[str, Any]: Result of stopping the server.
### list\_running\_servers
```python theme={"system"}
def list_running_servers(self):
```
**Returns:**
Dict\[str, Any]: Information about running servers
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Get all available tools from the WebDeployToolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.wechat_official_toolkit
## \_get\_wechat\_access\_token
```python theme={"system"}
def _get_wechat_access_token():
```
**Returns:**
str: The valid access token.
**Raises:**
* **ValueError**: If credentials are missing or token retrieval fails.
* **References**:
* **https**: //developers.weixin.qq.com/doc/offiaccount/Basic\_Information/Get\_access\_token.html
## \_make\_wechat\_request
```python theme={"system"}
def _make_wechat_request(method: Literal['GET', 'POST'], endpoint: str, **kwargs):
```
Makes a request to WeChat API with proper error handling.
**Parameters:**
* **method** (`Literal["GET", "POST"]`): HTTP method ('GET' or 'POST').
* **endpoint** (str): API endpoint path. \*\*kwargs: Additional arguments for requests.
**Returns:**
Dict\[str, Any]: API response data.
**Raises:**
* **requests.exceptions.RequestException**: If request fails.
* **ValueError**: If API returns an error.
## WeChatOfficialToolkit
```python theme={"system"}
class WeChatOfficialToolkit(BaseToolkit):
```
A toolkit for WeChat Official Account operations.
This toolkit provides methods to interact with the WeChat Official Account
API, allowing users to send messages, manage users, and handle media files.
References:
* Documentation: [https://developers.weixin.qq.com/doc/offiaccount/Getting\_Started/Overview.html](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)
* Test Account: [https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login](https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login)
**Note:**
Set environment variables: WECHAT\_APP\_ID, WECHAT\_APP\_SECRET
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the WeChatOfficialToolkit.
### send\_customer\_message
```python theme={"system"}
def send_customer_message(
self,
openid: str,
content: str,
msgtype: Literal['text', 'image', 'voice', 'video'] = 'text'
):
```
Sends a customer service message to a WeChat user.
**Parameters:**
* **openid** (str): The user's OpenID.
* **content** (str): Message content or media\_id for non-text messages.
* **msgtype** (str): Message type: "text", "image", "voice", "video".
**Returns:**
str: Success or error message.
References:
[https://developers.weixin.qq.com/doc/offiaccount/Message\_Management/Service\_Center\_messages.html](https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Service_Center_messages.html)
### get\_user\_info
```python theme={"system"}
def get_user_info(self, openid: str, lang: str = 'zh_CN'):
```
Retrieves WeChat user information.
**Parameters:**
* **openid** (str): The user's OpenID.
* **lang** (str): Response language. Common values: "zh\_CN", "zh\_TW", "en". (default: "zh\_CN")
**Returns:**
Dict\[str, Any]: User information as dictionary or error
information.
References:
[https://developers.weixin.qq.com/doc/offiaccount/User\_Management/](https://developers.weixin.qq.com/doc/offiaccount/User_Management/)
Getting\_user\_basic\_information.html
### get\_followers\_list
```python theme={"system"}
def get_followers_list(self, next_openid: str = ''):
```
Retrieves list of followers' OpenIDs.
**Parameters:**
* **next\_openid** (str): Starting OpenID for pagination. (default: "") (default: `""`)
**Returns:**
Dict\[str, Any]: Followers list as dictionary or error information.
References:
[https://developers.weixin.qq.com/doc/offiaccount/User\_Management/](https://developers.weixin.qq.com/doc/offiaccount/User_Management/)
Getting\_a\_list\_of\_followers.html
### upload\_wechat\_media
```python theme={"system"}
def upload_wechat_media(
self,
media_type: Literal['image', 'voice', 'video', 'thumb'],
file_path: str,
permanent: bool = False,
description: Optional[str] = None
):
```
Uploads media file to WeChat.
**Parameters:**
* **media\_type** (str): Media type: "image", "voice", "video", "thumb".
* **file\_path** (str): Local file path.
* **permanent** (bool): Whether to upload as permanent media. (default: :obj:`False`)
* **description** (Optional\[str]): Video description in JSON format for permanent upload. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: Upload result with media\_id or error information.
References:
* Temporary: [https://developers.weixin.qq.com/doc/offiaccount/](https://developers.weixin.qq.com/doc/offiaccount/)
Asset\_Management/Adding\_Temporary\_Assets.html
* Permanent: [https://developers.weixin.qq.com/doc/offiaccount/](https://developers.weixin.qq.com/doc/offiaccount/)
Asset\_Management/Adding\_Permanent\_Assets.html
### get\_media\_list
```python theme={"system"}
def get_media_list(
self,
media_type: Literal['image', 'voice', 'video', 'news'],
offset: int = 0,
count: int = 20
):
```
Gets list of permanent media files.
**Parameters:**
* **media\_type** (str): Media type: "image", "voice", "video", "news".
* **offset** (int): Starting position. (default: :obj:`0`) (default: 0)
* **count** (int): Number of items (1-20). (default: :obj:`20`) (default: 20)
**Returns:**
Dict\[str, Any]: Media list as dictionary or error information.
References:
[https://developers.weixin.qq.com/doc/offiaccount/Asset\_Management/](https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/)
Get\_the\_list\_of\_all\_materials.html
### send\_mass\_message\_to\_all
```python theme={"system"}
def send_mass_message_to_all(
self,
content: str,
msgtype: Literal['text', 'image', 'voice', 'video'] = 'text',
clientmsgid: Optional[str] = None,
send_ignore_reprint: Optional[int] = 0,
batch_size: int = 10000
):
```
Sends a mass message to all followers (by OpenID list).
This method paginates all follower OpenIDs and calls the
mass-send API in batches.
**Parameters:**
* **content** (str): For text, the message content; for non-text, the media\_id.
* **msgtype** (`Literal["text","image","voice","video"]`): Message type. For "video", the mass API expects "mpvideo" internally.
* **clientmsgid** (Optional\[str]): Idempotency key to avoid duplicate mass jobs.
* **send\_ignore\_reprint** (Optional\[int]): Whether to continue when a news article is judged as a reprint (reserved; applies to news/mpnews).
* **batch\_size** (int): Max OpenIDs per request (WeChat limit is up to 10000 per batch).
**Returns:**
Dict\[str, Any]: Aggregated result including counts and
each batch response.
References:
* Mass send by OpenID list:
[https://developers.weixin.qq.com/doc/service/api/notify/message/](https://developers.weixin.qq.com/doc/service/api/notify/message/)
api\_masssend.html
### get\_tools
```python theme={"system"}
def get_tools(self):
```
Returns toolkit functions as tools.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.whatsapp_toolkit
## WhatsAppToolkit
```python theme={"system"}
class WhatsAppToolkit(BaseToolkit):
```
A class representing a toolkit for WhatsApp operations.
This toolkit provides methods to interact with the WhatsApp Business API,
allowing users to send messages, retrieve message templates, and get
business profile information.
**Parameters:**
* **retries** (int): Number of retries for API requests in case of failure.
* **delay** (int): Delay between retries in seconds.
* **base\_url** (str): Base URL for the WhatsApp Business API.
* **version** (str): API version.
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
Initializes the WhatsAppToolkit.
### send\_message
```python theme={"system"}
def send_message(self, to: str, message: str):
```
Sends a text message to a specified WhatsApp number.
**Parameters:**
* **to** (str): The recipient's WhatsApp number in international format.
* **message** (str): The text message to send.
**Returns:**
Union\[Dict\[str, Any], str]: A dictionary containing
the API response if successful, or an error message string if
failed.
### get\_message\_templates
```python theme={"system"}
def get_message_templates(self):
```
**Returns:**
Union\[List\[Dict\[str, Any]], str]: A list of dictionaries containing
template information if successful, or an error message string
if failed.
### get\_business\_profile
```python theme={"system"}
def get_business_profile(self):
```
**Returns:**
Union\[Dict\[str, Any], str]: A dictionary containing the business
profile information if successful, or an error message string
if failed.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects for the
toolkit methods.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.wolfram_alpha_toolkit
## WolframAlphaToolkit
```python theme={"system"}
class WolframAlphaToolkit(BaseToolkit):
```
A class representing a toolkit for WolframAlpha.
Wolfram|Alpha is an answer engine developed by Wolfram Research.
It is offered as an online service that answers factual queries
by computing answers from externally sourced data.
### query\_wolfram\_alpha
```python theme={"system"}
def query_wolfram_alpha(self, query: str):
```
Queries Wolfram|Alpha and returns the result as a simple answer.
**Parameters:**
* **query** (str): The query to send to Wolfram Alpha.
**Returns:**
str: The result from Wolfram Alpha as a simple answer.
### query\_wolfram\_alpha\_step\_by\_step
```python theme={"system"}
def query_wolfram_alpha_step_by_step(self, query: str):
```
Queries Wolfram|Alpha and returns detailed results with
step-by-step solution.
**Parameters:**
* **query** (str): The query to send to Wolfram Alpha.
**Returns:**
Dict\[str, Any]: A dictionary with detailed information including
step-by-step solution.
### query\_wolfram\_alpha\_llm
```python theme={"system"}
def query_wolfram_alpha_llm(self, query: str):
```
Sends a query to the Wolfram|Alpha API optimized for language
model usage.
**Parameters:**
* **query** (str): The query to send to Wolfram Alpha LLM.
**Returns:**
str: The result from Wolfram Alpha as a string.
### \_parse\_wolfram\_result
```python theme={"system"}
def _parse_wolfram_result(self, result):
```
Parses a Wolfram Alpha API result into a structured dictionary
format.
**Parameters:**
* **result**: The API result returned from a Wolfram Alpha query, structured with multiple pods, each containing specific information related to the query.
**Returns:**
Dict\[str, Any]: A structured dictionary with the original query
and the final answer.
### \_get\_wolframalpha\_step\_by\_step\_solution
```python theme={"system"}
def _get_wolframalpha_step_by_step_solution(self, app_id: str, query: str):
```
Retrieve a step-by-step solution from the Wolfram Alpha API for a
given query.
**Parameters:**
* **app\_id** (str): Your Wolfram Alpha API application ID.
* **query** (str): The mathematical or computational query to solve.
**Returns:**
dict: The step-by-step solution response text from the Wolfram
Alpha API.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects
representing the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.toolkits.zapier_toolkit
## ZapierToolkit
```python theme={"system"}
class ZapierToolkit(BaseToolkit):
```
A class representing a toolkit for interacting with Zapier's NLA API.
This class provides methods for executing Zapier actions through natural
language commands, allowing integration with various web services and
automation of workflows through the Zapier platform.
**Parameters:**
* **api\_key** (str): The API key for authenticating with Zapier's API.
* **base\_url** (str): The base URL for Zapier's API endpoints.
* **timeout** (Optional\[float]): The timeout value for API requests in seconds. If None, no timeout is applied. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(self, timeout: Optional[float] = None):
```
### list\_actions
```python theme={"system"}
def list_actions(self):
```
**Returns:**
Dict\[str, Any]: A dictionary containing the list of available
actions.
### execute\_action
```python theme={"system"}
def execute_action(self, action_id: str, instructions: str):
```
Execute a specific Zapier action using natural language
instructions.
**Parameters:**
* **action\_id** (str): The ID of the Zapier action to execute.
* **instructions** (str): Natural language instructions for executing the action. For example: "Send an email to [john@example.com](mailto:john@example.com) with subject 'Hello' and body 'How are you?'"
**Returns:**
Dict\[str, Any]: The result of the action execution, including
status and any output data.
### preview\_action
```python theme={"system"}
def preview_action(self, action_id: str, instructions: str):
```
Preview a specific Zapier action using natural language
instructions.
**Parameters:**
* **action\_id** (str): The ID of the Zapier action to preview.
* **instructions** (str): Natural language instructions for previewing the action. For example: "Send an email to [john@example.com](mailto:john@example.com) with subject 'Hello' and body 'How are you?'"
**Returns:**
Dict\[str, Any]: The preview result showing what parameters would
be used if the action were executed.
### get\_execution\_result
```python theme={"system"}
def get_execution_result(self, execution_id: str):
```
Get the execution result of a Zapier action.
**Parameters:**
* **execution\_id** (str): The execution ID returned from execute\_action.
**Returns:**
Dict\[str, Any]: The execution result containing status, logs,
and any output data from the action execution.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of FunctionTool objects representing
the functions in the toolkit.
# null
Source: https://docs.camel-ai.org/reference/camel.types.agents.tool_calling_record
## ToolCallingRecord
```python theme={"system"}
class ToolCallingRecord(BaseModel):
```
Historical records of tools called in the conversation.
**Parameters:**
* **func\_name** (str): The name of the tool being called.
* **args** (Dict\[str, Any]): The dictionary of arguments passed to the tool.
* **result** (Any): The execution result of calling this tool.
* **tool\_call\_id** (str): The ID of the tool call, if available.
* **images** (Optional\[List\[str]]): List of base64-encoded images returned by the tool, if any.
### **str**
```python theme={"system"}
def __str__(self):
```
**Returns:**
str: Modified string to represent the tool calling.
### as\_dict
```python theme={"system"}
def as_dict(self):
```
**Returns:**
dict\[str, Any]: The tool calling record as a dictionary.
# null
Source: https://docs.camel-ai.org/reference/camel.types.enums
## ModelType
```python theme={"system"}
class ModelType(UnifiedModelType, Enum):
```
### **str**
```python theme={"system"}
def __str__(self):
```
### **repr**
```python theme={"system"}
def __repr__(self):
```
### **new**
```python theme={"system"}
def __new__(cls, value: Union['ModelType', str]):
```
### from\_name
```python theme={"system"}
def from_name(cls, name: str):
```
Returns the ModelType enum value from a string.
### value\_for\_tiktoken
```python theme={"system"}
def value_for_tiktoken(self):
```
### support\_native\_structured\_output
```python theme={"system"}
def support_native_structured_output(self):
```
### support\_native\_tool\_calling
```python theme={"system"}
def support_native_tool_calling(self):
```
### is\_openai
```python theme={"system"}
def is_openai(self):
```
Returns whether this type of models is an OpenAI-released model.
### is\_amd
```python theme={"system"}
def is_amd(self):
```
Returns whether this type of models is a AMD model.
### is\_aws\_bedrock
```python theme={"system"}
def is_aws_bedrock(self):
```
Returns whether this type of models is an AWS Bedrock model.
### is\_azure\_openai
```python theme={"system"}
def is_azure_openai(self):
```
Returns whether this type of models is an OpenAI-released model
from Azure.
### is\_zhipuai
```python theme={"system"}
def is_zhipuai(self):
```
Returns whether this type of models is a ZhipuAI model.
### is\_anthropic
```python theme={"system"}
def is_anthropic(self):
```
**Returns:**
bool: Whether this type of models is anthropic.
### is\_groq
```python theme={"system"}
def is_groq(self):
```
Returns whether this type of models is served by Groq.
### is\_cerebras
```python theme={"system"}
def is_cerebras(self):
```
Returns whether this type of models is served by Cerebras.
### is\_nebius
```python theme={"system"}
def is_nebius(self):
```
Returns whether this type of models is served by Nebius AI
Studio.
### is\_cometapi
```python theme={"system"}
def is_cometapi(self):
```
Returns whether this type of models is served by CometAPI.
### is\_openrouter
```python theme={"system"}
def is_openrouter(self):
```
Returns whether this type of models is served by OpenRouter.
### is\_lmstudio
```python theme={"system"}
def is_lmstudio(self):
```
Returns whether this type of models is served by LMStudio.
### is\_together
```python theme={"system"}
def is_together(self):
```
Returns whether this type of models is served by Together AI.
### is\_sambanova
```python theme={"system"}
def is_sambanova(self):
```
Returns whether this type of model is served by SambaNova AI.
### is\_mistral
```python theme={"system"}
def is_mistral(self):
```
Returns whether this type of models is served by Mistral.
### is\_nvidia
```python theme={"system"}
def is_nvidia(self):
```
Returns whether this type of models is a NVIDIA model.
### is\_gemini
```python theme={"system"}
def is_gemini(self):
```
**Returns:**
bool: Whether this type of models is gemini.
### is\_reka
```python theme={"system"}
def is_reka(self):
```
**Returns:**
bool: Whether this type of models is Reka.
### is\_cohere
```python theme={"system"}
def is_cohere(self):
```
**Returns:**
bool: Whether this type of models is Cohere.
### is\_yi
```python theme={"system"}
def is_yi(self):
```
**Returns:**
bool: Whether this type of models is Yi.
### is\_qwen
```python theme={"system"}
def is_qwen(self):
```
### is\_deepseek
```python theme={"system"}
def is_deepseek(self):
```
### is\_netmind
```python theme={"system"}
def is_netmind(self):
```
### is\_ppio
```python theme={"system"}
def is_ppio(self):
```
### is\_internlm
```python theme={"system"}
def is_internlm(self):
```
### is\_modelscope
```python theme={"system"}
def is_modelscope(self):
```
### is\_moonshot
```python theme={"system"}
def is_moonshot(self):
```
### is\_sglang
```python theme={"system"}
def is_sglang(self):
```
### is\_siliconflow
```python theme={"system"}
def is_siliconflow(self):
```
### is\_watsonx
```python theme={"system"}
def is_watsonx(self):
```
### is\_qianfan
```python theme={"system"}
def is_qianfan(self):
```
### is\_novita
```python theme={"system"}
def is_novita(self):
```
### is\_crynux
```python theme={"system"}
def is_crynux(self):
```
### is\_aiml
```python theme={"system"}
def is_aiml(self):
```
### is\_atlascloud
```python theme={"system"}
def is_atlascloud(self):
```
Returns whether this type of models is served by AtlasCloud.
### token\_limit
```python theme={"system"}
def token_limit(self):
```
**Returns:**
int: The maximum token limit for the given model.
## EmbeddingModelType
```python theme={"system"}
class EmbeddingModelType(Enum):
```
### is\_openai
```python theme={"system"}
def is_openai(self):
```
Returns whether this type of models is an OpenAI-released model.
### is\_jina
```python theme={"system"}
def is_jina(self):
```
Returns whether this type of models is an Jina model.
### is\_mistral
```python theme={"system"}
def is_mistral(self):
```
Returns whether this type of models is an Mistral-released
model.
### is\_gemini
```python theme={"system"}
def is_gemini(self):
```
Returns whether this type of models is an Gemini-released model.
### output\_dim
```python theme={"system"}
def output_dim(self):
```
## GeminiEmbeddingTaskType
```python theme={"system"}
class GeminiEmbeddingTaskType(str, Enum):
```
Task types for Gemini embedding models.
For more information, please refer to:
[https://ai.google.dev/gemini-api/docs/embeddings#task-types](https://ai.google.dev/gemini-api/docs/embeddings#task-types)
## VectorDistance
```python theme={"system"}
class VectorDistance(Enum):
```
Distance metrics used in a vector database.
## OpenAIImageType
```python theme={"system"}
class OpenAIImageType(Enum):
```
Image types supported by OpenAI vision model.
## ModelPlatformType
```python theme={"system"}
class ModelPlatformType(Enum):
```
### from\_name
```python theme={"system"}
def from_name(cls, name):
```
Returns the ModelPlatformType enum value from a string.
### is\_openai
```python theme={"system"}
def is_openai(self):
```
Returns whether this platform is openai.
### is\_aws\_bedrock
```python theme={"system"}
def is_aws_bedrock(self):
```
Returns whether this platform is aws-bedrock.
### is\_azure
```python theme={"system"}
def is_azure(self):
```
Returns whether this platform is azure.
### is\_anthropic
```python theme={"system"}
def is_anthropic(self):
```
Returns whether this platform is anthropic.
### is\_groq
```python theme={"system"}
def is_groq(self):
```
Returns whether this platform is groq.
### is\_openrouter
```python theme={"system"}
def is_openrouter(self):
```
Returns whether this platform is openrouter.
### is\_lmstudio
```python theme={"system"}
def is_lmstudio(self):
```
Returns whether this platform is lmstudio.
### is\_ollama
```python theme={"system"}
def is_ollama(self):
```
Returns whether this platform is ollama.
### is\_vllm
```python theme={"system"}
def is_vllm(self):
```
Returns whether this platform is vllm.
### is\_sglang
```python theme={"system"}
def is_sglang(self):
```
Returns whether this platform is sglang.
### is\_together
```python theme={"system"}
def is_together(self):
```
Returns whether this platform is together.
### is\_litellm
```python theme={"system"}
def is_litellm(self):
```
Returns whether this platform is litellm.
### is\_zhipuai
```python theme={"system"}
def is_zhipuai(self):
```
Returns whether this platform is zhipu.
### is\_mistral
```python theme={"system"}
def is_mistral(self):
```
Returns whether this platform is mistral.
### is\_openai\_compatible\_model
```python theme={"system"}
def is_openai_compatible_model(self):
```
Returns whether this is a platform supporting openai
compatibility
### is\_gemini
```python theme={"system"}
def is_gemini(self):
```
Returns whether this platform is Gemini.
### is\_reka
```python theme={"system"}
def is_reka(self):
```
Returns whether this platform is Reka.
### is\_samba
```python theme={"system"}
def is_samba(self):
```
Returns whether this platform is Samba Nova.
### is\_cohere
```python theme={"system"}
def is_cohere(self):
```
Returns whether this platform is Cohere.
### is\_yi
```python theme={"system"}
def is_yi(self):
```
Returns whether this platform is Yi.
### is\_qwen
```python theme={"system"}
def is_qwen(self):
```
Returns whether this platform is Qwen.
### is\_nvidia
```python theme={"system"}
def is_nvidia(self):
```
Returns whether this platform is Nvidia.
### is\_deepseek
```python theme={"system"}
def is_deepseek(self):
```
Returns whether this platform is DeepSeek.
### is\_netmind
```python theme={"system"}
def is_netmind(self):
```
Returns whether this platform is Netmind.
### is\_ppio
```python theme={"system"}
def is_ppio(self):
```
Returns whether this platform is PPIO.
### is\_internlm
```python theme={"system"}
def is_internlm(self):
```
Returns whether this platform is InternLM.
### is\_moonshot
```python theme={"system"}
def is_moonshot(self):
```
Returns whether this platform is Moonshot model.
### is\_modelscope
```python theme={"system"}
def is_modelscope(self):
```
Returns whether this platform is ModelScope model.
### is\_siliconflow
```python theme={"system"}
def is_siliconflow(self):
```
Returns whether this platform is SiliconFlow.
### is\_aiml
```python theme={"system"}
def is_aiml(self):
```
Returns whether this platform is AIML.
### is\_volcano
```python theme={"system"}
def is_volcano(self):
```
Returns whether this platform is volcano.
### is\_novita
```python theme={"system"}
def is_novita(self):
```
Returns whether this platform is Novita.
### is\_watsonx
```python theme={"system"}
def is_watsonx(self):
```
Returns whether this platform is WatsonX.
### is\_crynux
```python theme={"system"}
def is_crynux(self):
```
Returns whether this platform is Crynux.
### is\_aihubmix
```python theme={"system"}
def is_aihubmix(self):
```
Returns whether this platform is AihubMix.
### is\_minimax
```python theme={"system"}
def is_minimax(self):
```
Returns whether this platform is Minimax M2.
### is\_cerebras
```python theme={"system"}
def is_cerebras(self):
```
Returns whether this platform is Cerebras.
### is\_atlascloud
```python theme={"system"}
def is_atlascloud(self):
```
Returns whether this platform is AtlasCloud.
## AudioModelType
```python theme={"system"}
class AudioModelType(Enum):
```
### is\_openai
```python theme={"system"}
def is_openai(self):
```
Returns whether this type of audio models is an OpenAI-released
model.
## VoiceType
```python theme={"system"}
class VoiceType(Enum):
```
### is\_openai
```python theme={"system"}
def is_openai(self):
```
Returns whether this type of voice is an OpenAI-released voice.
## JinaRerankerModelType
```python theme={"system"}
class JinaRerankerModelType(str, Enum):
```
Model types for Jina AI Reranker.
These models are available through the Jina AI Reranker API for
re-ranking documents based on their relevance to a query.
For more information, please refer to:
[https://jina.ai/reranker/](https://jina.ai/reranker/)
# null
Source: https://docs.camel-ai.org/reference/camel.types.mcp_registries
## MCPRegistryType
```python theme={"system"}
class MCPRegistryType(Enum):
```
Enum for different types of MCP registries.
## BaseMCPRegistryConfig
```python theme={"system"}
class BaseMCPRegistryConfig(BaseModel):
```
Base configuration for an MCP registry.
**Parameters:**
* **type** (MCPRegistryType): The type of the registry.
* **os** (`Literal["darwin", "linux", "windows"]`): The operating system. It is automatically set to "darwin" for MacOS, "linux" for Linux, and "windows" for Windows.
* **api\_key** (Optional\[str]): API key for the registry.
### get\_config
```python theme={"system"}
def get_config(self):
```
**Returns:**
Dict\[str, Any]: The complete configuration for the registry.
### set\_default\_os
```python theme={"system"}
def set_default_os(cls, values: Dict):
```
Set the default OS based on the current platform if not provided.
**Parameters:**
* **values** (Dict): The values dictionary from the model validation.
**Returns:**
Dict: The updated values dictionary with the OS set.
### \_prepare\_command\_args
```python theme={"system"}
def _prepare_command_args(self, command: str, args: List[str]):
```
Prepare command and arguments based on OS.
**Parameters:**
* **command** (str): The base command to run.
* **args** (List\[str]): The arguments for the command.
**Returns:**
Dict\[str, Any]: Command configuration with OS-specific adjustments.
## SmitheryRegistryConfig
```python theme={"system"}
class SmitheryRegistryConfig(BaseMCPRegistryConfig):
```
Configuration for Smithery registry.
### get\_config
```python theme={"system"}
def get_config(self):
```
**Returns:**
Dict\[str, Any]: The complete configuration for the registry.
## ACIRegistryConfig
```python theme={"system"}
class ACIRegistryConfig(BaseMCPRegistryConfig):
```
Configuration for ACI registry.
### get\_config
```python theme={"system"}
def get_config(self):
```
**Returns:**
Dict\[str, Any]: The complete configuration for the registry.
# null
Source: https://docs.camel-ai.org/reference/camel.types.unified_model_type
## UnifiedModelType
```python theme={"system"}
class UnifiedModelType(str):
```
Class used for support both :obj:`ModelType` and :obj:`str` to be used
to represent a model type in a unified way. This class is a subclass of
:obj:`str` so that it can be used as string seamlessly.
**Parameters:**
* **value** (Union\[ModelType, str]): The value of the model type.
### **new**
```python theme={"system"}
def __new__(cls, value: Union['ModelType', str]):
```
### **init**
```python theme={"system"}
def __init__(self, value: Union['ModelType', str]):
```
### **repr**
```python theme={"system"}
def __repr__(self):
```
### **str**
```python theme={"system"}
def __str__(self):
```
### value\_for\_tiktoken
```python theme={"system"}
def value_for_tiktoken(self):
```
Returns the model name for TikToken.
### token\_limit
```python theme={"system"}
def token_limit(self):
```
Returns the context window size for the model.
For unknown model types not defined in ModelType enum, this returns
a default value of 999\_999\_999 tokens.
### is\_openai
```python theme={"system"}
def is_openai(self):
```
Returns whether the model is an OpenAI model.
### is\_aws\_bedrock
```python theme={"system"}
def is_aws_bedrock(self):
```
Returns whether the model is an AWS Bedrock model.
### is\_anthropic
```python theme={"system"}
def is_anthropic(self):
```
Returns whether the model is an Anthropic model.
### is\_azure\_openai
```python theme={"system"}
def is_azure_openai(self):
```
Returns whether the model is an Azure OpenAI model.
### is\_groq
```python theme={"system"}
def is_groq(self):
```
Returns whether the model is a Groq served model.
### is\_nebius
```python theme={"system"}
def is_nebius(self):
```
Returns whether the model is a Nebius AI Studio served model.
### is\_openrouter
```python theme={"system"}
def is_openrouter(self):
```
Returns whether the model is a OpenRouter served model.
### is\_atlascloud
```python theme={"system"}
def is_atlascloud(self):
```
Returns whether the model is a AtlasCloud served model.
### is\_lmstudio
```python theme={"system"}
def is_lmstudio(self):
```
Returns whether the model is a LMStudio served model.
### is\_ppio
```python theme={"system"}
def is_ppio(self):
```
Returns whether the model is a PPIO served model.
### is\_zhipuai
```python theme={"system"}
def is_zhipuai(self):
```
Returns whether the model is a Zhipuai model.
### is\_gemini
```python theme={"system"}
def is_gemini(self):
```
Returns whether the model is a Gemini model.
### is\_mistral
```python theme={"system"}
def is_mistral(self):
```
Returns whether the model is a Mistral model.
### is\_netmind
```python theme={"system"}
def is_netmind(self):
```
Returns whether the model is a Netmind model.
### is\_reka
```python theme={"system"}
def is_reka(self):
```
Returns whether the model is a Reka model.
### is\_cohere
```python theme={"system"}
def is_cohere(self):
```
Returns whether the model is a Cohere model.
### is\_cometapi
```python theme={"system"}
def is_cometapi(self):
```
Returns whether the model is a CometAPI served model.
### is\_yi
```python theme={"system"}
def is_yi(self):
```
Returns whether the model is a Yi model.
### is\_qwen
```python theme={"system"}
def is_qwen(self):
```
Returns whether the model is a Qwen model.
### is\_internlm
```python theme={"system"}
def is_internlm(self):
```
Returns whether the model is a InternLM model.
### is\_modelscope
```python theme={"system"}
def is_modelscope(self):
```
Returns whether the model is a ModelScope serverd model.
### is\_moonshot
```python theme={"system"}
def is_moonshot(self):
```
Returns whether this platform is Moonshot model.
### is\_novita
```python theme={"system"}
def is_novita(self):
```
Returns whether the model is a Novita served model.
### is\_watsonx
```python theme={"system"}
def is_watsonx(self):
```
Returns whether the model is a WatsonX served model.
### is\_qianfan
```python theme={"system"}
def is_qianfan(self):
```
Returns whether the model is a Qianfan served model.
### is\_crynux
```python theme={"system"}
def is_crynux(self):
```
Returns whether the model is a Crynux served model.
### is\_minimax
```python theme={"system"}
def is_minimax(self):
```
Returns whether the model is a Minimax served model.
### support\_native\_structured\_output
```python theme={"system"}
def support_native_structured_output(self):
```
Returns whether the model supports native structured output.
### support\_native\_tool\_calling
```python theme={"system"}
def support_native_tool_calling(self):
```
Returns whether the model supports native tool calling.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.agent_context
## set\_current\_agent\_id
```python theme={"system"}
def set_current_agent_id(agent_id: str):
```
Set the current agent ID in context-local storage.
This is safe to use in both sync and async contexts.
In async contexts, each coroutine maintains its own value.
**Parameters:**
* **agent\_id** (str): The agent ID to set.
## get\_current\_agent\_id
```python theme={"system"}
def get_current_agent_id():
```
**Returns:**
Optional\[str]: The agent ID if set, None otherwise.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.async_func
## sync\_funcs\_to\_async
```python theme={"system"}
def sync_funcs_to_async(funcs: list[FunctionTool]):
```
Convert a list of Python synchronous functions to Python
asynchronous functions.
**Parameters:**
* **funcs** (list\[FunctionTool]): List of Python synchronous functions in the :obj:`FunctionTool` format.
**Returns:**
list\[FunctionTool]: List of Python asynchronous functions
in the :obj:`FunctionTool` format.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.chunker.base
## BaseChunker
```python theme={"system"}
class BaseChunker(ABC):
```
An abstract base class for all CAMEL chunkers.
### chunk
```python theme={"system"}
def chunk(self, content: Any):
```
Chunk the given content
# null
Source: https://docs.camel-ai.org/reference/camel.utils.chunker.code_chunker
## CodeChunker
```python theme={"system"}
class CodeChunker(BaseChunker):
```
A class for chunking code or text while respecting structure
and token limits.
This class ensures that structured elements such as functions,
classes, and regions are not arbitrarily split across chunks.
It also handles oversized lines and Base64-encoded images.
**Parameters:**
* **chunk\_size** (int, optional): The maximum token size per chunk. (default: :obj:`8192`)
* **remove\_image**: (bool, optional): If the chunker should skip the images.
* **model\_name** (str, optional): The tokenizer model name used for token counting. (default: :obj:`"cl100k_base"`)
### **init**
```python theme={"system"}
def __init__(
self,
chunk_size: int = 8192,
model_name: str = 'cl100k_base',
remove_image: Optional[bool] = True
):
```
### count\_tokens
```python theme={"system"}
def count_tokens(self, text: str):
```
Counts the number of tokens in the given text.
**Parameters:**
* **text** (str): The input text to be tokenized.
**Returns:**
int: The number of tokens in the input text.
### \_split\_oversized
```python theme={"system"}
def _split_oversized(self, line: str):
```
Splits an oversized line into multiple chunks based on token limits
**Parameters:**
* **line** (str): The oversized line to be split.
**Returns:**
List\[str]: A list of smaller chunks after splitting the
oversized line.
### chunk
```python theme={"system"}
def chunk(self, content: List[str]):
```
Splits the content into smaller chunks while preserving
structure and adhering to token constraints.
**Parameters:**
* **content** (List\[str]): The content to be chunked.
**Returns:**
List\[str]: A list of chunked text segments.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.chunker.uio_chunker
## UnstructuredIOChunker
```python theme={"system"}
class UnstructuredIOChunker(BaseChunker):
```
A class for chunking text while respecting structure and
character limits.
This class ensures that structured elements, such as document sections
and titles, are not arbitrarily split across chunks. It utilizes the
`UnstructuredIO` class to process and segment elements while maintaining
readability and coherence. The chunking method can be adjusted based on
the provided `chunk_type` parameter.
**Parameters:**
* **chunk\_type** (str, optional): The method used for chunking text. (default: :obj:`"chunk_by_title"`)
* **max\_characters** (int, optional): The maximum number of characters allowed per chunk. (default: :obj:`500`)
* **metadata\_filename** (Optional\[str], optional): An optional filename for storing metadata related to chunking. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
chunk_type: str = 'chunk_by_title',
max_characters: int = 500,
metadata_filename: Optional[str] = None
):
```
### chunk
```python theme={"system"}
def chunk(self, content: List['Element']):
```
Splits the content into smaller chunks while preserving
structure and adhering to token constraints.
**Parameters:**
* **content** (List\[Element]): The content to be chunked.
**Returns:**
List\[Element]: A list of chunked text segments.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.commons
## print\_text\_animated
```python theme={"system"}
def print_text_animated(text, delay: float = 0.02, end: str = ''):
```
Prints the given text with an animated effect.
**Parameters:**
* **text** (str): The text to print.
* **delay** (float, optional): The delay between each character printed. (default: :obj:`0.02`)
* **end** (str, optional): The end character to print after each character of text. (default: :obj:`""`)
## get\_prompt\_template\_key\_words
```python theme={"system"}
def get_prompt_template_key_words(template: str):
```
Given a string template containing curly braces \{}, return a set of
the words inside the braces.
**Parameters:**
* **template** (str): A string containing curly braces.
**Returns:**
List\[str]: A list of the words inside the curly braces.
## get\_first\_int
```python theme={"system"}
def get_first_int(string: str):
```
Returns the first integer number found in the given string.
If no integer number is found, returns None.
**Parameters:**
* **string** (str): The input string.
**Returns:**
int or None: The first integer number found in the string, or None if
no integer number is found.
## download\_tasks
```python theme={"system"}
def download_tasks(task: TaskType, folder_path: str):
```
Downloads task-related files from a specified URL and extracts them.
This function downloads a zip file containing tasks based on the specified
`task` type from a predefined URL, saves it to `folder_path`, and then
extracts the contents of the zip file into the same folder. After
extraction, the zip file is deleted.
**Parameters:**
* **task** (TaskType): An enum representing the type of task to download.
* **folder\_path** (str): The path of the folder where the zip file will be downloaded and extracted.
## get\_task\_list
```python theme={"system"}
def get_task_list(task_response: str):
```
Parse the response of the Agent and return task list.
**Parameters:**
* **task\_response** (str): The string response of the Agent.
**Returns:**
List\[str]: A list of the string tasks.
## check\_server\_running
```python theme={"system"}
def check_server_running(server_url: str):
```
Check whether the port referred by the URL to the server
is open.
**Parameters:**
* **server\_url** (str): The URL to the server running LLM inference service.
**Returns:**
bool: Whether the port is open for packets (server is running).
## dependencies\_required
```python theme={"system"}
def dependencies_required(*required_modules: str):
```
A decorator to ensure that specified Python modules
are available before a function executes.
**Parameters:**
* **required\_modules** (str): The required modules to be checked for availability.
**Returns:**
Callable\[\[F], F]: The original function with the added check for
required module dependencies.
**Raises:**
* **ImportError**: If any of the required modules are not available.
## is\_module\_available
```python theme={"system"}
def is_module_available(module_name: str):
```
Check if a module is available for import.
**Parameters:**
* **module\_name** (str): The name of the module to check for availability.
**Returns:**
bool: True if the module can be imported, False otherwise.
## api\_keys\_required
```python theme={"system"}
def api_keys_required(param_env_list: List[Tuple[Optional[str], str]]):
```
A decorator to check if the required API keys are provided in the
environment variables or as function arguments.
**Parameters:**
* **param\_env\_list** (List\[Tuple\[Optional\[str], str]]): A list of tuples where each tuple contains a function argument name (as the first element, or None) and the corresponding environment variable name (as the second element) that holds the API key.
**Returns:**
Callable\[\[F], F]: The original function wrapped with the added check
for the required API keys.
**Raises:**
* **ValueError**: If any of the required API keys are missing, either
## get\_system\_information
```python theme={"system"}
def get_system_information():
```
**Returns:**
dict: A dictionary containing various pieces of OS information.
## to\_pascal
```python theme={"system"}
def to_pascal(snake: str):
```
Convert a snake\_case string to PascalCase.
**Parameters:**
* **snake** (str): The snake\_case string to be converted.
**Returns:**
str: The converted PascalCase string.
## get\_pydantic\_major\_version
```python theme={"system"}
def get_pydantic_major_version():
```
**Returns:**
int: The major version number of Pydantic if installed, otherwise 0.
## get\_pydantic\_object\_schema
```python theme={"system"}
def get_pydantic_object_schema(pydantic_params: Type[BaseModel]):
```
Get the JSON schema of a Pydantic model.
**Parameters:**
* **pydantic\_params** (Type\[BaseModel]): The Pydantic model class to retrieve the schema for.
**Returns:**
dict: The JSON schema of the Pydantic model.
## func\_string\_to\_callable
```python theme={"system"}
def func_string_to_callable(code: str):
```
Convert a function code string to a callable function object.
**Parameters:**
* **code** (str): The function code as a string.
**Returns:**
Callable\[..., Any]: The callable function object extracted from the
code string.
## json\_to\_function\_code
```python theme={"system"}
def json_to_function_code(json_obj: Dict):
```
Generate a Python function code from a JSON schema.
**Parameters:**
* **json\_obj** (dict): The JSON schema object containing properties and required fields, and json format is follow openai tools schema
**Returns:**
str: The generated Python function code as a string.
## text\_extract\_from\_web
```python theme={"system"}
def text_extract_from_web(url: str):
```
Get the text information from given url.
**Parameters:**
* **url** (str): The website you want to search.
**Returns:**
str: All texts extract from the web.
## create\_chunks
```python theme={"system"}
def create_chunks(text: str, n: int):
```
Returns successive n-sized chunks from provided text. Split a text
into smaller chunks of size n".
**Parameters:**
* **text** (str): The text to be split.
* **n** (int): The max length of a single chunk.
**Returns:**
List\[str]: A list of split texts.
## is\_docker\_running
```python theme={"system"}
def is_docker_running():
```
**Returns:**
bool: True if the Docker daemon is running, False otherwise.
## agentops\_decorator
```python theme={"system"}
def agentops_decorator(func):
```
Decorator that records the execution of a function if ToolEvent is
available.
**Parameters:**
* **func** (callable): The function to be decorated.
**Returns:**
callable: The wrapped function which records its execution details.
## AgentOpsMeta
```python theme={"system"}
class AgentOpsMeta(type):
```
Metaclass that automatically decorates all callable attributes with
the agentops\_decorator,
except for the 'get\_tools' method.
Methods:
**new**(cls, name, bases, dct):
Creates a new class with decorated methods.
### **new**
```python theme={"system"}
def __new__(
cls,
name,
bases,
dct
):
```
## track\_agent
```python theme={"system"}
def track_agent(*args, **kwargs):
```
Mock track agent decorator for AgentOps.
## handle\_http\_error
```python theme={"system"}
def handle_http_error(response: requests.Response):
```
Handles the HTTP errors based on the status code of the response.
**Parameters:**
* **response** (requests.Response): The HTTP response from the API call.
**Returns:**
str: The error type, based on the status code.
## retry\_on\_error
```python theme={"system"}
def retry_on_error(max_retries: int = 3, initial_delay: float = 1.0):
```
Decorator to retry function calls on exception with exponential
backoff.
**Parameters:**
* **max\_retries** (int): Maximum number of retry attempts
* **initial\_delay** (float): Initial delay between retries in seconds
**Returns:**
Callable: Decorated function with retry logic
## BatchProcessor
```python theme={"system"}
class BatchProcessor:
```
Handles batch processing with dynamic sizing and error handling based
on system load.
### **init**
```python theme={"system"}
def __init__(
self,
max_workers: Optional[int] = None,
initial_batch_size: Optional[int] = None,
monitoring_interval: float = 5.0,
cpu_threshold: float = 80.0,
memory_threshold: float = 85.0
):
```
Initialize the BatchProcessor with dynamic worker allocation.
**Parameters:**
* **max\_workers**: Maximum number of workers. If None, will be determined dynamically based on system resources. (default: :obj:`None`)
* **initial\_batch\_size**: Initial size of each batch. If `None`, defaults to `10`. (default: :obj:`None`)
* **monitoring\_interval**: Interval in seconds between resource checks. (default: :obj:`5.0`)
* **cpu\_threshold**: CPU usage percentage threshold for scaling down. (default: :obj:`80.0`)
* **memory\_threshold**: Memory usage percentage threshold for scaling down. (default: :obj:`85.0`)
### \_calculate\_optimal\_workers
```python theme={"system"}
def _calculate_optimal_workers(self):
```
Calculate optimal number of workers based on system resources.
### \_update\_resource\_metrics
```python theme={"system"}
def _update_resource_metrics(self):
```
Update current resource usage metrics.
### \_should\_check\_resources
```python theme={"system"}
def _should_check_resources(self):
```
Determine if it's time to check resource usage again.
### adjust\_batch\_size
```python theme={"system"}
def adjust_batch_size(self, success: bool, processing_time: Optional[float] = None):
```
Adjust batch size based on success/failure and system resources.
**Parameters:**
* **success** (bool): Whether the last batch completed successfully
* **processing\_time** (Optional\[float]): Time taken to process the last batch. (default: :obj:`None`)
### get\_performance\_metrics
```python theme={"system"}
def get_performance_metrics(self):
```
**Returns:**
Dict containing performance metrics including:
* total\_processed: Total number of batches processed
* error\_rate: Percentage of failed batches
* avg\_processing\_time: Average time per batch
* current\_batch\_size: Current batch size
* current\_workers: Current number of workers
* current\_cpu: Current CPU usage percentage
* current\_memory: Current memory usage percentage
## download\_github\_subdirectory
```python theme={"system"}
def download_github_subdirectory(
repo: str,
subdir: str,
data_dir: Path,
branch = 'main'
):
```
Download subdirectory of the Github repo of
the benchmark.
This function downloads all files and subdirectories from a
specified subdirectory of a GitHub repository and
saves them to a local directory.
**Parameters:**
* **repo** (str): The name of the GitHub repository in the format "owner/repo".
* **subdir** (str): The path to the subdirectory within the repository to download.
* **data\_dir** (Path): The local directory where the files will be saved.
* **branch** (str, optional): The branch of the repository to use. Defaults to "main".
## generate\_prompt\_for\_structured\_output
```python theme={"system"}
def generate_prompt_for_structured_output(response_format: Optional[Type[BaseModel]], user_message: str):
```
This function generates a prompt based on the provided Pydantic model and
user message.
**Parameters:**
* **response\_format** (Type\[BaseModel]): The Pydantic model class.
* **user\_message** (str): The user message to be used in the prompt.
**Returns:**
str: A prompt string for the LLM.
## safe\_extract\_parsed
```python theme={"system"}
def safe_extract_parsed(response: 'ChatAgentResponse', schema: Type[T]):
```
Safely extract a parsed structured output from a ChatAgentResponse.
Handles the common cases where `__INLINE_CODE_0____INLINE_CODE_1____INLINE_CODE_2__` (empty or
multi-message response) or `__INLINE_CODE_3____INLINE_CODE_4____INLINE_CODE_5__` (model failed to
produce valid structured output). When the parsed value is a dict, it
attempts to construct the schema from it.
**Parameters:**
* **response** (ChatAgentResponse): The agent response to extract from.
* **schema** (Type\[T]): The expected Pydantic model class.
**Returns:**
Optional\[T]: The parsed and validated result, or `__INLINE_CODE_0__` if
extraction fails for any reason.
## with\_timeout
```python theme={"system"}
def with_timeout(timeout = None):
```
Decorator that adds timeout functionality to functions.
Executes functions with a specified timeout value. Returns a timeout
message if execution time is exceeded.
**Parameters:**
* **timeout** (float, optional): The timeout duration in seconds. If None, will try to get timeout from the instance's timeout attribute. (default: :obj:`None`)
## browser\_toolkit\_save\_auth\_cookie
```python theme={"system"}
def browser_toolkit_save_auth_cookie(cookie_json_path: str, url: str, wait_time: int = 60):
```
Saves authentication cookies and browser storage state to a JSON file.
This function launches a browser window and navigates to the specified URL,
allowing the user to manually authenticate (log in) during a 60-second
wait period.After authentication, it saves all cookies, localStorage, and
sessionStorage data to the specified JSON file path, which can be used
later to maintain authenticated sessions without requiring manual login.
**Parameters:**
* **cookie\_json\_path** (str): Path where the authentication cookies and storage state will be saved as a JSON file. If the file already exists, it will be loaded first and then overwritten with updated state. The function checks if this file exists before attempting to use it.
* **url** (str): The URL to navigate to for authentication (e.g., a login page).
* **wait\_time** (int): The time in seconds to wait for the user to manually authenticate.
* **Usage**: 1. The function opens a browser window and navigates to the specified URL 2. User manually logs in during the wait\_time wait period 3. Browser storage state (including auth cookies) is saved to the specified file 4. The saved state can be used in subsequent browser sessions to maintain authentication
**Note:**
The wait\_time sleep is intentional to give the user enough time to
complete the manual authentication process before the storage state
is captured.
## run\_async
```python theme={"system"}
def run_async(func: Callable[..., Any]):
```
Helper function to run async functions in synchronous context.
**Parameters:**
* **func** (Callable\[..., Any]): The async function to wrap.
**Returns:**
Callable\[..., Any]: A synchronous wrapper for the async function.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.context_utils
## WorkflowSummary
```python theme={"system"}
class WorkflowSummary(BaseModel):
```
Pydantic model for structured workflow summaries.
This model defines the schema for workflow memories that can be reused
by future agents for similar tasks.
### get\_instruction\_prompt
```python theme={"system"}
def get_instruction_prompt(cls):
```
**Returns:**
str: The instruction prompt that guides agents to produce
structured output matching this schema.
## ContextUtility
```python theme={"system"}
class ContextUtility:
```
Utility class for context management and file operations.
This utility provides generic functionality for managing context files,
markdown generation, and session management that can be used by
context-related features.
Key features:
* Session-based directory management
* Generic markdown file operations
* Text-based search through files
* File metadata handling
* Agent memory record retrieval
* Shared session management for workforce workflows
### **init**
```python theme={"system"}
def __init__(
self,
working_directory: Optional[str] = None,
session_id: Optional[str] = None,
create_folder: bool = True,
use_session_subfolder: bool = True
):
```
Initialize the ContextUtility.
**Parameters:**
* **working\_directory** (str, optional): The directory path where files will be stored. If not provided, a default directory will be used.
* **session\_id** (str, optional): The session ID to use. If provided, this instance will use the same session folder as other instances with the same session\_id. If not provided, a new session ID will be generated.
* **create\_folder** (bool): Whether to create the session folder immediately. If False, the folder will be created only when needed (e.g., when saving files). Default is True for backward compatibility.
* **use\_session\_subfolder** (bool): Whether to append session\_id as a subfolder. If False, files are saved directly to working\_directory without session subfolder. Use False for role-based organization. Default is True for backward compatibility.
### \_setup\_storage
```python theme={"system"}
def _setup_storage(
self,
working_directory: Optional[str],
session_id: Optional[str] = None,
create_folder: bool = True,
use_session_subfolder: bool = True
):
```
Initialize session-specific storage paths and optionally create
directory structure for context file management.
### \_generate\_session\_id
```python theme={"system"}
def _generate_session_id(self):
```
Create timestamp-based unique identifier for isolating
current session files from other sessions.
### sanitize\_workflow\_filename
```python theme={"system"}
def sanitize_workflow_filename(name: str, max_length: Optional[int] = None):
```
Sanitize a name string for use as a workflow filename.
Converts the input string to a safe filename by:
* converting to lowercase
* replacing spaces with underscores
* removing special characters (keeping only alphanumeric and
underscores)
* truncating to maximum length if specified
**Parameters:**
* **name** (str): The name string to sanitize (e.g., role\_name or task\_title).
* **max\_length** (Optional\[int]): Maximum length for the sanitized filename. If None, uses MAX\_WORKFLOW\_FILENAME\_LENGTH. (default: :obj:`None`)
**Returns:**
str: Sanitized filename string suitable for filesystem use.
Returns "agent" if sanitization results in empty string.
### \_ensure\_directory\_exists
```python theme={"system"}
def _ensure_directory_exists(self):
```
Ensure the working directory exists, creating it if necessary.
### \_create\_or\_update\_note
```python theme={"system"}
def _create_or_update_note(self, note_name: str, content: str):
```
Write content to markdown file, creating new file or
overwriting existing one with UTF-8 encoding.
**Parameters:**
* **note\_name** (str): Name of the note (without .md extension).
* **content** (str): Content to write to the note.
**Returns:**
str: Success message.
### save\_markdown\_file
```python theme={"system"}
def save_markdown_file(
self,
filename: str,
content: str,
title: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None
):
```
Generic method to save any markdown content to a file.
**Parameters:**
* **filename** (str): Name without .md extension.
* **content** (str): Main content to save.
* **title** (str, optional): Title for the markdown file.
* **metadata** (Dict, optional): Additional metadata to include.
**Returns:**
str: "success" on success, error message starting with "Error:"
on failure.
### structured\_output\_to\_markdown
```python theme={"system"}
def structured_output_to_markdown(
self,
structured_data: BaseModel,
metadata: Optional[Dict[str, Any]] = None,
title: Optional[str] = None,
field_mappings: Optional[Dict[str, str]] = None,
exclude_fields: Optional[List[str]] = None
):
```
Convert any Pydantic BaseModel instance to markdown format.
**Parameters:**
* **structured\_data**: Any Pydantic BaseModel instance
* **metadata**: Optional metadata to include in the markdown
* **title**: Optional custom title, defaults to model class name (default: model class name)
* **field\_mappings**: Optional mapping of field names to custom section titles
* **exclude\_fields**: Optional list of field names to exclude from the markdown output
**Returns:**
str: Markdown formatted content
### load\_markdown\_file
```python theme={"system"}
def load_markdown_file(self, filename: str):
```
Generic method to load any markdown file.
**Parameters:**
* **filename** (str): Name without .md extension.
**Returns:**
str: File content or empty string if not found.
### file\_exists
```python theme={"system"}
def file_exists(self, filename: str):
```
Verify presence of markdown file in current session directory.
**Parameters:**
* **filename** (str): Name without .md extension.
**Returns:**
bool: True if file exists, False otherwise.
### list\_markdown\_files
```python theme={"system"}
def list_markdown_files(self):
```
**Returns:**
List\[str]: List of filenames without .md extension.
### get\_agent\_memory\_records
```python theme={"system"}
def get_agent_memory_records(self, agent: 'ChatAgent'):
```
Retrieve conversation history from agent's memory system.
**Parameters:**
* **agent** (ChatAgent): The agent to extract memory records from.
**Returns:**
List\[MemoryRecord]: List of memory records from the agent.
### format\_memory\_as\_conversation
```python theme={"system"}
def format_memory_as_conversation(self, memory_records: List['MemoryRecord']):
```
Transform structured memory records into human-readable
conversation format with role labels and message content.
**Parameters:**
* **memory\_records** (List\[MemoryRecord]): Memory records to format.
**Returns:**
str: Formatted conversation text.
### create\_session\_directory
```python theme={"system"}
def create_session_directory(
self,
base_dir: Optional[str] = None,
session_id: Optional[str] = None
):
```
Create a session-specific directory.
**Parameters:**
* **base\_dir** (str, optional): Base directory. If None, uses current working directory.
* **session\_id** (str, optional): Custom session ID. If None, generates new one.
**Returns:**
Path: The created session directory path.
### get\_session\_metadata
```python theme={"system"}
def get_session_metadata(
self,
workflow_version: int = 1,
created_at: Optional[str] = None
):
```
Collect comprehensive session information including identifiers,
timestamps, and directory paths for tracking and reference.
**Parameters:**
* **workflow\_version** (int): Version number of the workflow. Defaults to 1 for new workflows. (default: :obj:`1`)
* **created\_at** (Optional\[str]): ISO timestamp when workflow was first created. If None, uses current timestamp for new workflows. (default: :obj:`None`)
**Returns:**
Dict\[str, Any]: Session metadata including ID, timestamp,
directory, version, and update timestamp.
### list\_sessions
```python theme={"system"}
def list_sessions(self, base_dir: Optional[str] = None):
```
Discover all available session directories for browsing
historical conversations and context files.
**Parameters:**
* **base\_dir** (str, optional): Base directory to search. If None, uses parent of working directory.
**Returns:**
List\[str]: List of session directory names.
### search\_in\_file
```python theme={"system"}
def search_in_file(
self,
file_path: Path,
keywords: List[str],
top_k: int = 4
):
```
Perform keyword-based search through file sections,
ranking results by keyword frequency and returning top matches.
**Parameters:**
* **file\_path** (Path): Path to the file to search.
* **keywords** (List\[str]): Keywords to search for.
* **top\_k** (int): Maximum number of results to return.
**Returns:**
str: Formatted search results.
### get\_working\_directory
```python theme={"system"}
def get_working_directory(self):
```
**Returns:**
Path: The working directory path.
### get\_session\_id
```python theme={"system"}
def get_session_id(self):
```
**Returns:**
str: The session ID.
### set\_session\_id
```python theme={"system"}
def set_session_id(self, session_id: str):
```
Set a new session ID and update the working directory accordingly.
This allows sharing session directories between multiple ContextUtility
instances by using the same session\_id.
**Parameters:**
* **session\_id** (str): The session ID to use.
### load\_markdown\_context\_to\_memory
```python theme={"system"}
def load_markdown_context_to_memory(
self,
agent: 'ChatAgent',
filename: str,
include_metadata: bool = False
):
```
Load context from a markdown file and append it to agent memory.
**Parameters:**
* **agent** (ChatAgent): The agent to append context to.
* **filename** (str): Name of the markdown file (without .md extension).
* **include\_metadata** (bool): Whether to include metadata section in the loaded content. Defaults to False.
**Returns:**
str: Status message indicating success or failure with details.
### \_filter\_metadata\_from\_content
```python theme={"system"}
def _filter_metadata_from_content(self, content: str):
```
Filter out metadata section from markdown content.
**Parameters:**
* **content** (str): The full markdown content including metadata.
**Returns:**
str: Content with metadata section removed.
### extract\_workflow\_info
```python theme={"system"}
def extract_workflow_info(self, file_path: str):
```
Extract info from a workflow markdown file.
This method reads only the essential info from a workflow file
(title, description, tags) for use in workflow selection without
loading the entire workflow content.
**Parameters:**
* **file\_path** (str): Full path to the workflow markdown file.
**Returns:**
Dict\[str, Any]: Workflow info including title, description,
tags, and file\_path. Returns empty dict on error.
### get\_all\_workflows\_info
```python theme={"system"}
def get_all_workflows_info(self, session_id: Optional[str] = None):
```
Get info from all workflow files in workforce\_workflows.
This method scans the workforce\_workflows directory for workflow
markdown files and extracts their info for use in workflow
selection.
**Parameters:**
* **session\_id** (Optional\[str]): If provided, only return workflows from this specific session. If None, returns workflows from all sessions.
**Returns:**
List\[Dict\[str, Any]]: List of workflow info dicts, sorted
by session timestamp (newest first).
### get\_workforce\_shared
```python theme={"system"}
def get_workforce_shared(cls, session_id: Optional[str] = None):
```
Get or create shared workforce context utility with lazy init.
.. note::
Session-based workflow storage will be deprecated in a future
version. Consider using :meth:`get_workforce_shared_by_role` for
role-based organization instead.
This method provides a centralized way to access shared context
utilities for workforce workflows, ensuring all workforce components
use the same session directory.
**Parameters:**
* **session\_id** (str, optional): Custom session ID. If None, uses the default workforce session.
**Returns:**
ContextUtility: Shared context utility instance for workforce.
### get\_workforce\_shared\_by\_role
```python theme={"system"}
def get_workforce_shared_by_role(cls, role_identifier: str):
```
Get or create shared workforce context utility based on role.
This method provides role-based context utilities for workforce
workflows, organizing workflows by agent role instead of session ID.
**Parameters:**
* **role\_identifier** (str): Role identifier (e.g., role\_name or agent\_title). Will be sanitized for filesystem use.
**Returns:**
ContextUtility: Shared context utility instance for the role.
### reset\_shared\_sessions
```python theme={"system"}
def reset_shared_sessions(cls):
```
Reset shared sessions (useful for testing).
This method clears all shared session instances, forcing new ones
to be created on next access. Primarily used for testing to ensure
clean state between tests.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.deduplication
## DeduplicationResult
```python theme={"system"}
class DeduplicationResult(BaseModel):
```
The result of deduplication.
**Parameters:**
* **original\_texts** (List\[str]): The original texts.
* **unique\_ids** (List\[int]): A list of ids that are unique (not duplicates).
* **unique\_embeddings\_dict** (Dict\[int, List\[float]]): A mapping from the index of each unique text to its embedding.
* **duplicate\_to\_target\_map** (Dict\[int, int]): A mapping from the index of the duplicate text to the index of the text it is considered a duplicate of.
## deduplicate\_internally
```python theme={"system"}
def deduplicate_internally(
texts: List[str],
threshold: float = 0.65,
embedding_instance: Optional[BaseEmbedding[str]] = None,
embeddings: Optional[List[List[float]]] = None,
strategy: Literal['top1', 'llm-supervise'] = 'top1',
batch_size: int = 1000
):
```
Deduplicate a list of strings based on their cosine similarity.
You can either:
1. Provide a CAMEL `BaseEmbedding` instance via `embedding_instance` to let
this function handle the embedding internally, OR
2. Directly pass a list of pre-computed embeddings to `embeddings`.
If both `embedding_instance` and `embeddings` are provided, the function
will raise a ValueError to avoid ambiguous usage.
strategy is used to specify different strategies, where 'top1' selects the
one with highest similarity, and 'llm-supervise' uses LLM to determine if
texts are duplicates (not yet implemented).
**Parameters:**
* **texts** (List\[str]): The list of texts to be deduplicated.
* **threshold** (float, optional): The similarity threshold for considering two texts as duplicates. (default: :obj:`0.65`)
* **embedding\_instance** (Optional\[BaseEmbedding\[str]], optional): A CAMEL embedding instance for automatic embedding. (default: :obj:`None`)
* **embeddings** (Optional\[List\[List\[float]]], optional): Pre-computed embeddings of `texts`. Each element in the list corresponds to the embedding of the text in the same index of `texts`. (default: :obj:`None`)
* **strategy** (`Literal["top1", "llm-supervise"], optional`): The strategy to use for deduplication. (default: :obj:`"top1"`)
* **batch\_size** (int, optional): The size of the batch to use for calculating cosine similarities. (default: :obj:`1000`)
**Returns:**
DeduplicationResult: An object that contains:
* `original_texts`: The original texts.
* `unique_ids`: The unique ids after deduplication.
* `unique_embeddings_dict`: A dict mapping from (unique) text id
to its embedding.
* `duplicate_to_target_map`: A dict mapping from the id of a
duplicate text to the id of the text it is considered a duplicate
of.
**Raises:**
* **NotImplementedError**: If the strategy is not "top1".
* **ValueError**: If neither embeddings nor embedding\_instance is provided,
* **ValueError**: If the length of `embeddings` does not match the length of
# null
Source: https://docs.camel-ai.org/reference/camel.utils.filename
## sanitize\_filename
```python theme={"system"}
def sanitize_filename(
url_name: str,
default: str = 'index',
max_length: int = MAX_FILENAME_LENGTH
):
```
Sanitize a URL path into a safe filename that is safe for
most platforms.
**Parameters:**
* **url\_name** (str): The URL path to sanitize.
* **default** (str): Default name if sanitization results in empty string. (default: :obj:`"index"`)
* **max\_length** (int): Maximum length of the filename. (default: :obj:`MAX_FILENAME_LENGTH`)
**Returns:**
str: A sanitized filename safe for most platforms.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.langfuse
## configure\_langfuse
```python theme={"system"}
def configure_langfuse(
public_key: Optional[str] = None,
secret_key: Optional[str] = None,
host: Optional[str] = None,
debug: Optional[bool] = None,
enabled: Optional[bool] = None
):
```
Configure Langfuse for CAMEL models.
**Parameters:**
* **public\_key** (Optional\[str]): Langfuse public key. Can be set via LANGFUSE\_PUBLIC\_KEY. (default: :obj:`None`)
* **secret\_key** (Optional\[str]): Langfuse secret key. Can be set via LANGFUSE\_SECRET\_KEY. (default: :obj:`None`)
* **host** (Optional\[str]): Langfuse host URL. Can be set via LANGFUSE\_HOST. (default: :obj:`https://cloud.langfuse.com`)
* **debug** (Optional\[bool]): Enable debug mode. Can be set via LANGFUSE\_DEBUG. (default: :obj:`None`)
* **enabled** (Optional\[bool]): Enable/disable tracing. Can be set via LANGFUSE\_ENABLED. (default: :obj:`None`)
**Note:**
This function configures the native langfuse\_context which works with
@observe() decorators. Set enabled=False to disable all tracing.
## is\_langfuse\_available
```python theme={"system"}
def is_langfuse_available():
```
Check if Langfuse is configured.
## set\_current\_agent\_session\_id
```python theme={"system"}
def set_current_agent_session_id(session_id: str):
```
Set the session ID for the current agent in context-local storage.
This is safe to use in both sync and async contexts.
In async contexts, each coroutine maintains its own value.
**Parameters:**
* **session\_id** (str): The session ID to set for the current agent.
## get\_current\_agent\_session\_id
```python theme={"system"}
def get_current_agent_session_id():
```
**Returns:**
Optional\[str]: The session ID for the current agent.
## update\_langfuse\_trace
```python theme={"system"}
def update_langfuse_trace(
session_id: Optional[str] = None,
user_id: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
tags: Optional[List[str]] = None
):
```
Update the current Langfuse trace with session ID and metadata.
**Parameters:**
* **session\_id** (Optional\[str]): Optional session ID to use. If :obj:`None` uses the current agent's session ID. (default: :obj:`None`)
* **user\_id** (Optional\[str]): Optional user ID for the trace. (default: :obj:`None`)
* **metadata** (Optional\[Dict\[str, Any]]): Optional metadata dictionary. (default: :obj:`None`)
* **tags** (Optional\[List\[str]]): Optional list of tags. (default: :obj:`None`)
**Returns:**
bool: True if update was successful, False otherwise.
## update\_current\_observation
```python theme={"system"}
def update_current_observation(
input: Optional[Dict[str, Any]] = None,
output: Optional[Dict[str, Any]] = None,
model: Optional[str] = None,
model_parameters: Optional[Dict[str, Any]] = None,
usage_details: Optional[Dict[str, Any]] = None,
**kwargs
):
```
Update the current Langfuse observation with input, output,
model, model\_parameters, and usage\_details.
**Parameters:**
* **input** (Optional\[Dict\[str, Any]]): Optional input dictionary. (default: :obj:`None`)
* **output** (Optional\[Dict\[str, Any]]): Optional output dictionary. (default: :obj:`None`)
* **model** (Optional\[str]): Optional model name. (default: :obj:`None`)
* **model\_parameters** (Optional\[Dict\[str, Any]]): Optional model parameters dictionary. (default: :obj:`None`)
* **usage\_details** (Optional\[Dict\[str, Any]]): Optional usage details dictionary. (default: :obj:`None`)
**Returns:**
None
## get\_langfuse\_status
```python theme={"system"}
def get_langfuse_status():
```
**Returns:**
Dict\[str, Any]: Status information including configuration state.
## observe
```python theme={"system"}
def observe(*args, **kwargs):
```
# null
Source: https://docs.camel-ai.org/reference/camel.utils.mcp
## \_is\_pydantic\_serializable
```python theme={"system"}
def _is_pydantic_serializable(type_annotation: Any):
```
Check if a type annotation is Pydantic serializable.
**Parameters:**
* **type\_annotation**: The type annotation to check
**Returns:**
Tuple\[bool, str]: (is\_serializable, error\_message)
## \_validate\_function\_types
```python theme={"system"}
def _validate_function_types(func: Callable[..., Any]):
```
Validate function parameter and return types are Pydantic serializable.
**Parameters:**
* **func** (Callable\[..., Any]): The function to validate.
**Returns:**
List\[str]: List of error messages for incompatible types.
## MCPServer
```python theme={"system"}
class MCPServer:
```
Decorator class for registering functions of a class as tools in an MCP
(Model Context Protocol) server.
This class is typically used to wrap a toolkit or service class and
automatically register specified methods (or methods derived from
`BaseToolkit`) with a FastMCP server.
**Parameters:**
* **function\_names** (Optional\[list\[str]]): A list of method names to expose via the MCP server. If not provided and the class is a subclass of `BaseToolkit`, method names will be inferred from the tools returned by `get_tools()`.
* **server\_name** (Optional\[str]): A name for the MCP server. If not provided, the class name of the decorated object is used.
### **init**
```python theme={"system"}
def __init__(
self,
function_names: Optional[List[str]] = None,
server_name: Optional[str] = None
):
```
### make\_wrapper
```python theme={"system"}
def make_wrapper(self, func: Callable[..., Any]):
```
Wraps a function (sync or async) to preserve its signature and
metadata.
This is used to ensure the MCP server can correctly call and introspect
the method.
**Parameters:**
* **func** (Callable\[..., Any]): The function to wrap.
**Returns:**
Callable\[..., Any]: The wrapped function, with preserved signature
and async support.
### **call**
```python theme={"system"}
def __call__(self, cls):
```
Decorates a class by injecting an MCP server instance and
registering specified methods.
**Parameters:**
* **cls** (type): The class being decorated.
**Returns:**
type: The modified class with MCP integration.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.mcp_client
Unified MCP Client
This module provides a unified interface for connecting to MCP servers
using different transport protocols (stdio, sse, streamable-http, websocket).
The client can automatically detect the transport type based on configuration.
## TransportType
```python theme={"system"}
class TransportType(str, Enum):
```
Supported transport types.
## ServerConfig
```python theme={"system"}
class ServerConfig(BaseModel):
```
### validate\_config
```python theme={"system"}
def validate_config(self):
```
Validate that either command or url is provided.
### transport\_type
```python theme={"system"}
def transport_type(self):
```
Automatically detect transport type based on configuration.
## MCPClient
```python theme={"system"}
class MCPClient:
```
Unified MCP client that automatically detects and connects to servers
using the appropriate transport protocol.
This client provides a unified interface for connecting to Model Context
Protocol (MCP) servers using different transport protocols including STDIO,
HTTP/HTTPS, WebSocket, and Server-Sent Events (SSE). The client
automatically detects the appropriate transport type based on the
configuration provided.
The client should be used as an async context manager for automatic
connectionmanagement.
**Parameters:**
* **config** (Union\[ServerConfig, Dict\[str, Any]]): Server configuration as either a :obj:`ServerConfig` object or a dictionary that will be converted to a :obj:`ServerConfig`. The configuration determines the transport type and connection parameters.
* **client\_info** (Optional\[types.Implementation], optional): Client implementation information to send to the server during initialization. (default: :obj:`None`)
* **timeout** (Optional\[float], optional): Timeout for waiting for messages from the server in seconds. (default: :obj:`10.0`)
* **config** (ServerConfig): The server configuration object.
* **client\_info** (Optional\[types.Implementation]): Client implementation information.
* **read\_timeout\_seconds** (timedelta): Timeout for reading from the server.
### **init**
```python theme={"system"}
def __init__(
self,
config: Union[ServerConfig, Dict[str, Any]],
client_info: Optional[types.Implementation] = None,
timeout: Optional[float] = 10.0
):
```
### transport\_type
```python theme={"system"}
def transport_type(self):
```
Get the detected transport type.
### \_simplify\_connection\_error
```python theme={"system"}
def _simplify_connection_error(self, error: Exception):
```
Convert complex MCP connection errors to simple, understandable
messages.
### session
```python theme={"system"}
def session(self):
```
Get the current session if connected.
### is\_connected
```python theme={"system"}
def is_connected(self):
```
Check if the client is currently connected.
### list\_mcp\_tools\_sync
```python theme={"system"}
def list_mcp_tools_sync(self):
```
**Returns:**
ListToolsResult: Result containing available MCP tools.
### generate\_function\_from\_mcp\_tool
```python theme={"system"}
def generate_function_from_mcp_tool(self, mcp_tool: types.Tool):
```
Dynamically generates a Python callable function corresponding to
a given MCP tool.
**Parameters:**
* **mcp\_tool** (types.Tool): The MCP tool definition received from the MCP server.
**Returns:**
Callable: A dynamically created Python function that wraps
the MCP tool and works in both sync and async contexts.
### \_build\_tool\_schema
```python theme={"system"}
def _build_tool_schema(self, mcp_tool: types.Tool):
```
Build tool schema for OpenAI function calling format.
### get\_tools
```python theme={"system"}
def get_tools(self):
```
**Returns:**
List\[FunctionTool]: A list of :obj:`FunctionTool` objects
representing the available tools from the MCP server. Returns
an empty list if the client is not connected.
**Note:**
This method requires an active connection to the MCP server.
If the client is not connected, an empty list will be returned.
### get\_text\_tools
```python theme={"system"}
def get_text_tools(self):
```
**Returns:**
str: Text description of tools
### call\_tool\_sync
```python theme={"system"}
def call_tool_sync(self, tool_name: str, arguments: Dict[str, Any]):
```
Synchronously call a tool by name with the provided arguments.
**Parameters:**
* **tool\_name** (str): The name of the tool to call.
* **arguments** (Dict\[str, Any]): A dictionary of arguments to pass to the tool.
**Returns:**
Any: The result returned by the tool execution.
## create\_mcp\_client
```python theme={"system"}
def create_mcp_client(config: Union[Dict[str, Any], ServerConfig], **kwargs: Any):
```
Create an MCP client from configuration.
Factory function that creates an :obj:`MCPClient` instance from various
configuration formats. This is the recommended way to create MCP clients
as it handles configuration validation and type conversion automatically.
**Parameters:**
* **config** (Union\[Dict\[str, Any], ServerConfig]): Server configuration as either a dictionary or a :obj:`ServerConfig` object. If a dictionary is provided, it will be automatically converted to
* **a**: obj:`ServerConfig`. \*\*kwargs: Additional keyword arguments passed to the :obj:`MCPClient` constructor, such as :obj:`client_info`, :obj:`timeout`.
**Returns:**
MCPClient: A configured :obj:`MCPClient` instance ready for use as
an async context manager.
## create\_mcp\_client\_from\_config\_file
```python theme={"system"}
def create_mcp_client_from_config_file(config_path: Union[str, Path], server_name: str, **kwargs: Any):
```
Create an MCP client from a configuration file.
**Parameters:**
* **config\_path** (Union\[str, Path]): Path to configuration file (JSON).
* **server\_name** (str): Name of the server in the config. \*\*kwargs: Additional arguments passed to MCPClient constructor.
**Returns:**
MCPClient: MCPClient instance as an async context manager.
Example config file:
`\{
"mcpServers": \{
"filesystem": \{
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path"
]
\},
"remote-server": \{
"url": "https://api.example.com/mcp",
"headers": \{"Authorization": "Bearer token"\}
\}
\}
\}`
Usage:
.. code-block:: python
async with create\_mcp\_client\_from\_config\_file(
"config.json", "filesystem"
) as client:
tools = client.get\_tools()
# null
Source: https://docs.camel-ai.org/reference/camel.utils.message_summarizer
## MessageSummary
```python theme={"system"}
class MessageSummary(BaseModel):
```
Schema for structured message summaries.
**Parameters:**
* **summary** (str): A brief, one-sentence summary of the conversation.
* **participants** (List\[str]): The roles of participants involved.
* **key\_topics\_and\_entities** (List\[str]): Important topics, concepts, and entities discussed.
* **decisions\_and\_outcomes** (List\[str]): Key decisions, conclusions, or outcomes reached.
* **action\_items** (List\[str]): A list of specific tasks or actions to be taken, with assignees if mentioned.
* **progress\_on\_main\_task** (str): A summary of progress made on the primary task.
## MessageSummarizer
```python theme={"system"}
class MessageSummarizer:
```
Utility class for generating structured summaries of chat messages.
**Parameters:**
* **model\_backend** (Optional\[BaseModelBackend], optional): The model backend to use for summarization. If not provided, a default model backend will be created.
### **init**
```python theme={"system"}
def __init__(self, model_backend: Optional[BaseModelBackend] = None):
```
### summarize
```python theme={"system"}
def summarize(self, messages: List[BaseMessage]):
```
Generate a structured summary of the provided messages.
**Parameters:**
* **messages** (List\[BaseMessage]): List of messages to summarize.
**Returns:**
MessageSummary: Structured summary of the conversation.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.response_format
## get\_pydantic\_model
```python theme={"system"}
def get_pydantic_model(input_data: Union[str, Type[BaseModel], Callable]):
```
A multi-purpose function that can be used as a normal function,
a class decorator, or a function decorator.
**Parameters:**
* **input\_data** (Union\[str, type, Callable]): - If a string is provided, it should be a JSON-encoded string that will be converted into a BaseModel. - If a function is provided, it will be decorated such that its arguments are converted into a BaseModel. - If a BaseModel class is provided, it will be returned directly.
**Returns:**
Type\[BaseModel]: The BaseModel class that will be used to
structure the input data.
## model\_from\_json\_schema
```python theme={"system"}
def model_from_json_schema(name: str, schema: Dict[str, Any]):
```
Create a Pydantic model from a JSON schema.
**Parameters:**
* **name** (str): The name of the model.
* **schema** (Dict\[str, Any]): The JSON schema to create the model from.
**Returns:**
Type\[BaseModel]: The Pydantic model.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.token_counting
## get\_model\_encoding
```python theme={"system"}
def get_model_encoding(value_for_tiktoken: str):
```
Get model encoding from tiktoken.
**Parameters:**
* **value\_for\_tiktoken**: Model value for tiktoken.
**Returns:**
tiktoken.Encoding: Model encoding.
## BaseTokenCounter
```python theme={"system"}
class BaseTokenCounter(ABC):
```
Base class for token counters of different kinds of models.
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Count number of tokens in the provided message list.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
int: Number of tokens in the messages.
### encode
```python theme={"system"}
def encode(self, text: str):
```
Encode text into token IDs.
**Parameters:**
* **text** (str): The text to encode.
**Returns:**
List\[int]: List of token IDs.
### decode
```python theme={"system"}
def decode(self, token_ids: List[int]):
```
Decode token IDs back to text.
**Parameters:**
* **token\_ids** (List\[int]): List of token IDs to decode.
**Returns:**
str: Decoded text.
## OpenAITokenCounter
```python theme={"system"}
class OpenAITokenCounter(BaseTokenCounter):
```
### **init**
```python theme={"system"}
def __init__(self, model: UnifiedModelType):
```
Constructor for the token counter for OpenAI models.
**Parameters:**
* **model** (UnifiedModelType): Model type for which tokens will be counted.
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Count number of tokens in the provided message list with the
help of package tiktoken.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
int: Number of tokens in the messages.
### \_count\_tokens\_from\_image
```python theme={"system"}
def _count_tokens_from_image(self, image: Image.Image, detail: OpenAIVisionDetailType):
```
Count image tokens for OpenAI vision model. An :obj:`"auto"`
resolution model will be treated as :obj:`"high"`. All images with
:obj:`"low"` detail cost 85 tokens each. Images with :obj:`"high"` detail
are first scaled to fit within a 2048 x 2048 square, maintaining their
aspect ratio. Then, they are scaled such that the shortest side of the
image is 768px long. Finally, we count how many 512px squares the image
consists of. Each of those squares costs 170 tokens. Another 85 tokens are
always added to the final total. For more details please refer to [OpenAI
vision docs](https://platform.openai.com/docs/guides/vision)
**Parameters:**
* **image** (PIL.Image.Image): Image to count number of tokens.
* **detail** (OpenAIVisionDetailType): Image detail type to count number of tokens.
**Returns:**
int: Number of tokens for the image given a detail type.
### encode
```python theme={"system"}
def encode(self, text: str):
```
Encode text into token IDs.
**Parameters:**
* **text** (str): The text to encode.
**Returns:**
List\[int]: List of token IDs.
### decode
```python theme={"system"}
def decode(self, token_ids: List[int]):
```
Decode token IDs back to text.
**Parameters:**
* **token\_ids** (List\[int]): List of token IDs to decode.
**Returns:**
str: Decoded text.
## AnthropicTokenCounter
```python theme={"system"}
class AnthropicTokenCounter(BaseTokenCounter):
```
### **init**
```python theme={"system"}
def __init__(
self,
model: str,
api_key: Optional[str] = None,
base_url: Optional[str] = None
):
```
Constructor for the token counter for Anthropic models.
**Parameters:**
* **model** (str): The name of the Anthropic model being used.
* **api\_key** (Optional\[str], optional): The API key for authenticating with the Anthropic service. If not provided, it will use the ANTHROPIC\_API\_KEY environment variable. (default: :obj:`None`)
* **base\_url** (Optional\[str], optional): The URL of the Anthropic service. If not provided, it will use the default Anthropic URL. (default: :obj:`None`)
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Count number of tokens in the provided message list using
loaded tokenizer specific for this type of model.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
int: Number of tokens in the messages.
### encode
```python theme={"system"}
def encode(self, text: str):
```
Encode text into token IDs.
**Parameters:**
* **text** (str): The text to encode.
**Returns:**
List\[int]: List of token IDs.
### decode
```python theme={"system"}
def decode(self, token_ids: List[int]):
```
Decode token IDs back to text.
**Parameters:**
* **token\_ids** (List\[int]): List of token IDs to decode.
**Returns:**
str: Decoded text.
## LiteLLMTokenCounter
```python theme={"system"}
class LiteLLMTokenCounter(BaseTokenCounter):
```
### **init**
```python theme={"system"}
def __init__(self, model_type: UnifiedModelType):
```
Constructor for the token counter for LiteLLM models.
**Parameters:**
* **model\_type** (UnifiedModelType): Model type for which tokens will be counted.
### token\_counter
```python theme={"system"}
def token_counter(self):
```
### completion\_cost
```python theme={"system"}
def completion_cost(self):
```
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Count number of tokens in the provided message list using
the tokenizer specific to this type of model.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in LiteLLM API format.
**Returns:**
int: Number of tokens in the messages.
### calculate\_cost\_from\_response
```python theme={"system"}
def calculate_cost_from_response(self, response: dict):
```
Calculate the cost of the given completion response.
**Parameters:**
* **response** (dict): The completion response from LiteLLM.
**Returns:**
float: The cost of the completion call in USD.
### encode
```python theme={"system"}
def encode(self, text: str):
```
Encode text into token IDs.
**Parameters:**
* **text** (str): The text to encode.
**Returns:**
List\[int]: List of token IDs.
### decode
```python theme={"system"}
def decode(self, token_ids: List[int]):
```
Decode token IDs back to text.
**Parameters:**
* **token\_ids** (List\[int]): List of token IDs to decode.
**Returns:**
str: Decoded text.
## MistralTokenCounter
```python theme={"system"}
class MistralTokenCounter(BaseTokenCounter):
```
### **init**
```python theme={"system"}
def __init__(self, model_type: ModelType):
```
Constructor for the token counter for Mistral models.
**Parameters:**
* **model\_type** (ModelType): Model type for which tokens will be counted.
### count\_tokens\_from\_messages
```python theme={"system"}
def count_tokens_from_messages(self, messages: List[OpenAIMessage]):
```
Count number of tokens in the provided message list using
loaded tokenizer specific for this type of model.
**Parameters:**
* **messages** (List\[OpenAIMessage]): Message list with the chat history in OpenAI API format.
**Returns:**
int: Total number of tokens in the messages.
### \_convert\_response\_from\_openai\_to\_mistral
```python theme={"system"}
def _convert_response_from_openai_to_mistral(self, openai_msg: OpenAIMessage):
```
Convert an OpenAI message to a Mistral ChatCompletionRequest.
**Parameters:**
* **openai\_msg** (OpenAIMessage): An individual message with OpenAI format.
**Returns:**
ChatCompletionRequest: The converted message in Mistral's request
format.
### encode
```python theme={"system"}
def encode(self, text: str):
```
Encode text into token IDs.
**Parameters:**
* **text** (str): The text to encode.
**Returns:**
List\[int]: List of token IDs.
### decode
```python theme={"system"}
def decode(self, token_ids: List[int]):
```
Decode token IDs back to text.
**Parameters:**
* **token\_ids** (List\[int]): List of token IDs to decode.
**Returns:**
str: Decoded text.
# null
Source: https://docs.camel-ai.org/reference/camel.utils.tool_result
## ToolResult
```python theme={"system"}
class ToolResult:
```
Special result type for tools that can return images along with text.
This class is used by ChatAgent to detect when a tool returns visual
content that should be included in the conversation context.
### **init**
```python theme={"system"}
def __init__(self, text: str, images: Optional[List[str]] = None):
```
Initialize a tool result.
**Parameters:**
* **text** (str): The text description or result of the tool operation.
* **images** (Optional\[List\[str]]): List of base64-encoded images to include in the conversation context. Images should be encoded as "data:image/\{format};base64,\{data}" format.
### **str**
```python theme={"system"}
def __str__(self):
```
Return the text representation of the result.
### **repr**
```python theme={"system"}
def __repr__(self):
```
Return a detailed representation of the result.
# null
Source: https://docs.camel-ai.org/reference/camel.verifiers.base
## BaseVerifier
```python theme={"system"}
class BaseVerifier(ABC):
```
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
max_parallel: Optional[int] = None,
timeout: Optional[float] = None,
max_retries: int = 3,
retry_delay: float = 1.0,
initial_batch_size: Optional[int] = None,
cpu_threshold: float = 80.0,
memory_threshold: float = 85.0,
**kwargs
):
```
Initialize the verifier with configuration parameters.
**Parameters:**
* **max\_parallel**: Maximum number of parallel verifications. If None, determined dynamically based on system resources. (default: :obj:`None`)
* **timeout**: Timeout in seconds for each verification. (default: :obj:`None`)
* **max\_retries**: Maximum number of retry attempts. (default: :obj:`3`) (default: 3)
* **retry\_delay**: Delay between retries in seconds. (default: :obj:`1.0`)
* **initial\_batch\_size**: Initial size for batch processing. If None, defaults to 10. (default: :obj:`None`)
* **cpu\_threshold**: CPU usage percentage threshold for scaling down. (default: :obj:`80.0`)
* **memory\_threshold**: Memory usage percentage threshold for scaling down. (default: :obj:`85.0`) \*\*kwargs: Additional verifier parameters.
# null
Source: https://docs.camel-ai.org/reference/camel.verifiers.math_verifier
## MathVerifier
```python theme={"system"}
class MathVerifier(BaseVerifier):
```
Verifier for mathematical expressions using Math-Verify.
Features:
* Supports LaTeX and plain mathematical expressions
* Handles complex numbers, matrices, and sets
* Configurable precision for floating-point comparisons
* Optional LaTeX wrapping to ensure proper parsing and rendering
* Comprehensive error handling and logging
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
timeout: Optional[float] = 30.0,
float_rounding: int = 6,
numeric_precision: int = 15,
enable_wrapping: Optional[bool] = False,
**kwargs
):
```
Initializes the MathVerifier.
**Parameters:**
* **extractor** (Optional\[BaseExtractor], optional): The extractor to use for extracting code from the solution. (default: :obj:`None`)
* **timeout** (Optional\[float], optional): The execution timeout in seconds. (default: :obj:`30.0`)
* **float\_rounding** (int, optional): The number of decimal places to round floating-point numbers. (default: :obj:`6`)
* **numeric\_precision** (int, optional): The numeric precision for floating-point comparisons. (default: :obj:`15`)
* **enable\_wrapping** (Optional\[bool], optional): Whether to wrap LaTeX expressions in math mode delimiters. (default: :obj:`False`)
### \_latex\_wrapping
```python theme={"system"}
def _latex_wrapping(s: str):
```
Wrap a LaTeX expression in math mode delimiters.
This function checks whether the input string is already in a LaTeX
math environment (e.g., \$, \[, \begin\{}, etc.). If not, it wraps the
expression in $...$ to ensure proper parsing and rendering as a
mathematical expression.
**Parameters:**
* **s** (str): The input LaTeX string.
**Returns:**
str: The LaTeX string wrapped in math mode if necessary.
# null
Source: https://docs.camel-ai.org/reference/camel.verifiers.models
## VerificationOutcome
```python theme={"system"}
class VerificationOutcome(Enum):
```
Enum representing the status of a verification.
### **bool**
```python theme={"system"}
def __bool__(self):
```
Only VerificationOutcome.SUCCESS is truthy; others are falsy.
## VerificationResult
```python theme={"system"}
class VerificationResult(BaseModel):
```
Structured result from a verification.
## VerifierConfig
```python theme={"system"}
class VerifierConfig(BaseModel):
```
Configuration for verifier behavior.
# null
Source: https://docs.camel-ai.org/reference/camel.verifiers.physics_verifier
## UnitParser
```python theme={"system"}
class UnitParser:
```
Class for handling unit parsing and manipulation operations.
### **init**
```python theme={"system"}
def __init__(self):
```
### \_load\_sympy\_units
```python theme={"system"}
def _load_sympy_units():
```
**Returns:**
Dict\[str, Any]: Dictionary mapping unit names to their
corresponding sympy Quantity objects.
### \_add\_si\_prefixes
```python theme={"system"}
def _add_si_prefixes(self):
```
Add SI prefixed units (like km, MHz, etc.) to the allowed units.
### parse\_unit
```python theme={"system"}
def parse_unit(self, unit_str: str):
```
Parse a unit string into a SymPy expression using the appropriate
method.
**Parameters:**
* **unit\_str** (str): The unit string to parse.
**Returns:**
Optional\[Any]: SymPy expression representing the unit, or None
if parsing fails or the unit is dimensionless.
### parse\_unit\_with\_latex
```python theme={"system"}
def parse_unit_with_latex(self, unit_str: str):
```
Parse a unit string using SymPy's LaTeX parser.
**Parameters:**
* **unit\_str** (str): The unit string in LaTeX format.
**Returns:**
Any: SymPy expression representing the unit, or the
original string if parsing fails.
### detect\_scaling\_factor
```python theme={"system"}
def detect_scaling_factor(self, unit_expr: Any):
```
Detect a scaling factor in the unit expression.
**Parameters:**
* **unit\_expr** (Any): The unit expression.
**Returns:**
Tuple\[Union\[int, float, Any], Any]: Tuple of scale
factor and base unit.
### preprocess\_unit\_string
```python theme={"system"}
def preprocess_unit_string(unit_str: str):
```
Preprocess a unit string to replace '^' with '\*\*' for
exponentiation.
**Parameters:**
* **unit\_str** (str): The unit string to preprocess.
**Returns:**
str: Preprocessed unit string.
### unit\_is\_none
```python theme={"system"}
def unit_is_none(unit_str: Optional[str]):
```
Check if a unit string represents 'no unit' or is empty.
**Parameters:**
* **unit\_str** (Optional\[str]): The unit string to check.
**Returns:**
bool: True if the unit is None or represents 'no unit'.
### extract\_value\_and\_unit
```python theme={"system"}
def extract_value_and_unit(expr: Any):
```
Extract numerical value and unit components from a SymPy
expression.
**Parameters:**
* **expr** (Any): SymPy expression with units.
**Returns:**
Tuple\[Union\[int, float, Any], Any]: Numerical
value and unit expression.
### detect\_unit\_args
```python theme={"system"}
def detect_unit_args(unit_expr: Any):
```
Extract the base units from a composite SymPy unit expression.
**Parameters:**
* **unit\_expr** (Any): SymPy expression representing a composite unit.
**Returns:**
List\[Any]: List of SymPy base unit components.
## PhysicsSolutionComparator
```python theme={"system"}
class PhysicsSolutionComparator:
```
Class for compare solutions and reference answers that contains value
and units.
**Parameters:**
* **solution** (str): The output from running the solution code.
* **reference\_answer** (str): The reference answer to compare against.
* **float\_tolerance** (Optional\[float], optional): The tolerance for floating point comparisons. (default: :obj:`None`)
### **init**
```python theme={"system"}
def __init__(
self,
solution: str,
reference_answer: str,
float_tolerance: Optional[float] = None
):
```
### \_split\_value\_unit
```python theme={"system"}
def _split_value_unit(s: str):
```
Split a string into value and unit components.
Handles LaTeX-style units enclosed in dollar signs.
**Parameters:**
* **s** (str): The input string.
**Returns:**
Tuple\[str, str]: Tuple of (value, unit) as strings.
### \_clean\_answer
```python theme={"system"}
def _clean_answer(raw_answer: str):
```
Clean a raw answer string by removing LaTeX formatting.
**Parameters:**
* **raw\_answer** (str): The raw answer string potentially containing LaTeX formatting.
**Returns:**
str: The cleaned answer string without LaTeX formatting.
### \_parse\_expression
```python theme={"system"}
def _parse_expression(expr: Any):
```
Parse an expression into a SymPy expression.
**Parameters:**
* **expr** (Any): Expression to parse, can be a string, number, or other type.
**Returns:**
Any: Parsed SymPy expression.
### \_is\_number
```python theme={"system"}
def _is_number(s: Any):
```
Check if a value can be converted to a number.
**Parameters:**
* **s** (Any): Value to check.
**Returns:**
bool: True if the value can be converted to a number.
### \_detect\_tolerance
```python theme={"system"}
def _detect_tolerance(default_tolerance: float, value: str):
```
### \_convert\_units
```python theme={"system"}
def _convert_units(self):
```
Convert the solution units to match gt units
### verify\_unit
```python theme={"system"}
def verify_unit(sol_unit_expr: Any, gt_unit_expr: Any):
```
### compare\_solution\_to\_reference
```python theme={"system"}
def compare_solution_to_reference(self):
```
**Returns:**
VerificationResult with comparison status.
### \_get\_value\_unit\_pairs
```python theme={"system"}
def _get_value_unit_pairs(self):
```
### \_compare\_numeric\_values
```python theme={"system"}
def _compare_numeric_values(self):
```
Compare numerical values, with unit conversion if needed.
### \_compare\_symbolic\_values
```python theme={"system"}
def _compare_symbolic_values(self):
```
Compare symbolic expressions for equivalence.
## PhysicsVerifier
```python theme={"system"}
class PhysicsVerifier(PythonVerifier):
```
The PhysicsVerifier inherits PythonVerifier and makes it able to
compare and convert units.
**Parameters:**
* **extractor** (Optional\[BaseExtractor]): The extractor to use for extracting code from messages. (default: :obj:`None`)
* **timeout** (Optional\[float]): The timeout for code execution in seconds. (default: :obj:`30.0`)
* **required\_packages** (Optional\[List\[str]]): The required packages for code execution. (default: :obj:`None`)
* **float\_tolerance** (Optional\[float]): The relative tolerance used to compare numerical values. (default: :obj:`None`) \*\*kwargs: Additional keyword arguments to pass to the parent class.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
timeout: Optional[float] = 30.0,
required_packages: Optional[List[str]] = None,
float_tolerance: Optional[float] = None,
**kwargs
):
```
# null
Source: https://docs.camel-ai.org/reference/camel.verifiers.python_verifier
## PythonVerifier
```python theme={"system"}
class PythonVerifier(BaseVerifier):
```
The PythonVerifier class verifies Python-based implementations
by executing them in an isolated virtual environment.
Features:
* Creates a virtual environment with a specified Python version.
* Installs required packages before executing the provided script.
* Executes the script and compares the output against a ground truth,
if supplied.
* Automatically cleans up the virtual environment after execution.
The verification process ensures that the code runs in a controlled
environment, minimizing external dependencies and conflicts.
### **init**
```python theme={"system"}
def __init__(
self,
extractor: Optional[BaseExtractor] = None,
timeout: Optional[float] = 30.0,
required_packages: Optional[List[str]] = None,
float_tolerance: Optional[float] = None,
**kwargs
):
```
Initializes the PythonVerifier.
**Parameters:**
* **extractor** (Optional\[BaseExtractor], optional): The extractor to use for extracting code from the solution. (default: :obj:`None`)
* **timeout** (Optional\[float], optional): The execution timeout in seconds. (default: :obj:`30.0`)
* **required\_packages** (Optional\[List\[str]], optional): A list of packages to install in the virtual environment. (default: :obj:`None`)
* **float\_tolerance** (Optional\[float], optional): The tolerance for floating point comparisons. (default: :obj:`None`)
### \_cleanup\_venv
```python theme={"system"}
def _cleanup_venv(self):
```
Clean up the virtual environment if it exists.
### \_is\_uv\_environment
```python theme={"system"}
def _is_uv_environment(self):
```
Detect whether the current Python runtime is managed by uv.
### \_setup\_with\_uv
```python theme={"system"}
def _setup_with_uv(self):
```
Create virtual environment and install packages using uv.
### \_is\_expression
```python theme={"system"}
def _is_expression(self, code: str):
```
Determines whether a given string of code is a single expression.
This utility uses Python's AST module to parse the code and checks if
it consists of a single expression node.
**Parameters:**
* **code** (str): The Python code to analyze.
**Returns:**
bool: True if the code is a single expression, False otherwise.
### \_is\_equal\_with\_tolerance
```python theme={"system"}
def _is_equal_with_tolerance(self, a: Any, b: Any):
```
Compares two Python objects for equality with optional float
tolerance.
This method recursively compares nested structures (lists, tuples,
sets, and dictionaries) and applies floating point tolerance when
comparing numerical values. If no float tolerance is set, a runtime
error is raised.
**Parameters:**
* **a** (Any): First value to compare.
* **b** (Any): Second value to compare.
**Returns:**
bool: True if the values are considered equal within the
specified float tolerance; False otherwise.
# API Reference
Source: https://docs.camel-ai.org/reference/index
Complete API documentation for CAMEL-AI framework
# CAMEL-AI API Reference
Welcome to the comprehensive API reference for CAMEL-AI, a powerful framework for building multi-agent systems and AI applications.
## Overview
CAMEL-AI provides a rich set of modules and components to help you build sophisticated AI agents and multi-agent systems. This API reference covers all the core modules, utilities, and tools available in the framework.
## Core Modules
### 🤖 [Agents](/reference/camel.agents.base)
Build and manage AI agents with various capabilities including chat agents, critic agents, and specialized tool agents.
### 🧠 [Models](/reference/camel.models.base_model)
Interface with various language models from different providers including OpenAI, Anthropic, Google, and more.
### 💬 [Messages](/reference/camel.messages.base)
Handle message formatting, conversion, and management for agent communications.
### 🧩 [Prompts](/reference/camel.prompts.base)
Access pre-built prompt templates and create custom prompts for different use cases.
### 🔧 [Toolkits](/reference/camel.toolkits.base)
Extend agent capabilities with a comprehensive collection of tools for web search, file operations, APIs, and more.
## Data & Storage
### 📊 [Datasets](/reference/camel.datasets.base_generator)
Generate and manage datasets for training and evaluation purposes.
### 🗄️ [Storage](/reference/camel.storages.vectordb_storages.base)
Store and retrieve data using various storage backends including vector databases, key-value stores, and object storage.
### 🔍 [Retrievers](/reference/camel.retrievers.base)
Implement retrieval-augmented generation (RAG) with various retrieval strategies.
### 📝 [Memory](/reference/camel.memories.base)
Manage agent memory and context for long-running conversations.
## Advanced Features
### 🏢 [Societies](/reference/camel.societies.role_playing)
Create multi-agent societies with role-playing capabilities and complex interactions.
### ⚙️ [Runtime](/reference/camel.runtime.base)
Execute code and manage runtime environments for agent operations.
### 🔌 [Interpreters](/reference/camel.interpreters.base)
Run code in various environments including Python, Docker, and cloud platforms.
### 📥 [Loaders](/reference/camel.loaders.base_io)
Load and process data from various sources including web pages, documents, and APIs.
## Configuration & Types
### ⚙️ [Configs](/reference/camel.configs.base_config)
Configure models and services with provider-specific settings.
### 🏷️ [Types](/reference/camel.types.enums)
Type definitions and enumerations used throughout the framework.
### 📐 [Schemas](/reference/camel.schemas.base)
Define and validate data structures for structured outputs.
## Utilities & Extensions
### 🛠️ [Utilities](/reference/camel.utils.commons)
Common utility functions for various operations.
### 🔍 [Verifiers](/reference/camel.verifiers.base)
Verify and validate outputs from agents and models.
### 🏁 [Terminators](/reference/camel.terminators.base)
Control when conversations and processes should end.
### 🌐 [Environments](/reference/camel.environments.models)
Simulate environments for agent interactions and testing.
## Specialized Components
### 🤖 [Bots](/reference/camel.bots.telegram_bot)
Deploy agents as bots on various platforms like Discord, Slack, and Telegram.
### 📊 [Benchmarks](/reference/camel.benchmarks.base)
Evaluate agent performance using standardized benchmarks.
### 🎭 [Personas](/reference/camel.personas.persona)
Create and manage agent personas for role-playing scenarios.
### 🔄 [Data Generation](/reference/camel.datagen.cot_datagen)
Generate synthetic data for training and evaluation.
### 📚 [Data Collector](/reference/camel.data_collector.base)
Collect and process data from various sources.
### 🏢 [Datahubs](/reference/camel.datahubs.base)
Manage data repositories and hubs.
### 🧩 [Extractors](/reference/camel.extractors.base)
Extract structured information from unstructured data.
### 🔗 [Embeddings](/reference/camel.embeddings.base)
Generate and work with text embeddings from various providers.
## Getting Started
1. **Choose your use case**: Browse the modules above to find components relevant to your project
2. **Check examples**: Each module page includes usage examples and code snippets
3. **Explore integrations**: See how different modules work together in the [Cookbooks](/cookbooks)
4. **Join the community**: Get help and share your projects on our [Discord](https://discord.camel-ai.org)
## Need Help?
* 📖 **Documentation**: Start with our [Getting Started](/get_started/installation) guide
* 🍳 **Cookbooks**: Check out practical examples in our [Cookbooks](/cookbooks) section
* 💬 **Community**: Join our [Discord community](https://discord.camel-ai.org) for support
* 🐛 **Issues**: Report bugs on [GitHub](https://github.com/camel-ai/camel/issues)
***
*This API reference is automatically generated from the CAMEL-AI codebase. For the latest updates, visit our [GitHub repository](https://github.com/camel-ai/camel).*