camel.interpreters package

Submodules

camel.interpreters.base module

class camel.interpreters.base.BaseInterpreter

Bases: ABC

An abstract base class for code interpreters.

abstract run(code: str, code_type: str) → 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:

The result of the code execution. If the execution fails, this

should include sufficient information to diagnose and correct the issue.

Return type:

str

Raises:

InterpreterError – If the code execution encounters errors that could be resolved by modifying or regenerating the code.

abstract supported_code_types() → List[str]

Provides supported code types by the interpreter.

abstract update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter

camel.interpreters.docker_interpreter module

class camel.interpreters.docker_interpreter.DockerInterpreter(require_confirm: bool = True, print_stdout: bool = False, print_stderr: bool = True)

Bases: 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.

run(code: str, code_type: str) → str

Executes the given code in the conatiner 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’).

Returns:

A string containing the captured stdout and stderr of the

executed code.

Return type:

str

Raises:

InterpreterError – If the user declines to run the code, or the code type is unsupported, or there is an error in the docker API/container

supported_code_types() → List[str]

Provides supported code types by the interpreter.

update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter

camel.interpreters.internal_python_interpreter module

class camel.interpreters.internal_python_interpreter.InternalPythonInterpreter(action_space: Dict[str, Any] | None = None, import_white_list: List[str] | None = None, unsafe_mode: bool = False, raise_error: bool = False)

Bases: 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.

This class is adapted from the hugging face implementation python_interpreter.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

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 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 action_space is derived from EmbodiedAgent, representing the actions that an agent is capable of performing. If None, set to empty dict. (default: 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 (). (default: None)

• unsafe_mode (bool, optional) – If True, the interpreter runs the code by eval() without any security check. (default: False)

• raise_error (bool, optional) – Raise error if the interpreter fails. (default: False)

clear_state() → None

Initialize state and fuzz_state.

execute(code: str, state: Dict[str, Any] | None = None, fuzz_state: Dict[str, Any] | None = None, keep_state: bool = True) → Any

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: 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 fuzz_state has a variable image, the generated code can use input_image to access it. (default: None)

• keep_state (bool, optional) – If True, state and fuzz_state will be kept for later execution. Otherwise, they will be cleared. (default: True)

Returns:

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.

Return type:

Any

run(code: str, code_type: str) → str

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() 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

• types (supported code)

Returns:

The string representation of the output of the executed code.

Return type:

str

Raises:

InterpreterError – If the code_type is not supported or if any runtime error occurs during the execution of the code.

supported_code_types() → List[str]

Provides supported code types by the interpreter.

update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter.

camel.interpreters.interpreter_error module

exception camel.interpreters.interpreter_error.InterpreterError

Bases: Exception

Exception raised for errors that can be solved by regenerating code

camel.interpreters.ipython_interpreter module

class camel.interpreters.ipython_interpreter.JupyterKernelInterpreter(require_confirm: bool = True, print_stdout: bool = False, print_stderr: bool = True)

Bases: 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.

run(code: str, code_type: str) → str

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’).

Returns:

A string containing the captured result of the

executed code.

Return type:

str

Raises:

InterpreterError – If there is an error when doing code execution.

supported_code_types() → List[str]

Provides supported code types by the interpreter.

Returns:

Supported code types.

Return type:

List[str]

update_action_space(action_space: Dict[str, Any]) → None

Updates the action space for the interpreter.

Parameters:

action_space (Dict[str, Any]) – A dictionary representing the new or updated action space.

Raises:

RuntimeError – Always raised because JupyterKernelInterpreter does not support updating the action space.

camel.interpreters.subprocess_interpreter module

class camel.interpreters.subprocess_interpreter.SubprocessInterpreter(require_confirm: bool = True, print_stdout: bool = False, print_stderr: bool = True)

Bases: 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: True)

• print_stdout (bool, optional) – If True, print the standard output of the executed code. (default: False)

• print_stderr (bool, optional) – If True, print the standard error of the executed code. (default: True)

run(code: str, code_type: str) → 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:

A string containing the captured stdout and stderr of the

executed code.

Return type:

str

Raises:

InterpreterError – If the user declines to run the code or if the code type is unsupported.

run_file(file: Path, code_type: str) → str

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’).

Returns:

A string containing the captured stdout and stderr of the

executed code.

Return type:

str

Raises:

• RuntimeError – If the provided file path does not point to a file.

• InterpreterError – If the code type provided is not supported.

supported_code_types() → List[str]

Provides supported code types by the interpreter.

update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter

Module contents

class camel.interpreters.BaseInterpreter

Bases: ABC

An abstract base class for code interpreters.

abstract run(code: str, code_type: str) → 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:

The result of the code execution. If the execution fails, this

should include sufficient information to diagnose and correct the issue.

Return type:

str

Raises:

InterpreterError – If the code execution encounters errors that could be resolved by modifying or regenerating the code.

abstract supported_code_types() → List[str]

Provides supported code types by the interpreter.

abstract update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter

class camel.interpreters.DockerInterpreter(require_confirm: bool = True, print_stdout: bool = False, print_stderr: bool = True)

Bases: 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.

run(code: str, code_type: str) → str

Executes the given code in the conatiner 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’).

Returns:

A string containing the captured stdout and stderr of the

executed code.

Return type:

str

Raises:

InterpreterError – If the user declines to run the code, or the code type is unsupported, or there is an error in the docker API/container

supported_code_types() → List[str]

Provides supported code types by the interpreter.

update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter

class camel.interpreters.InternalPythonInterpreter(action_space: Dict[str, Any] | None = None, import_white_list: List[str] | None = None, unsafe_mode: bool = False, raise_error: bool = False)

Bases: 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.

This class is adapted from the hugging face implementation python_interpreter.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

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 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 action_space is derived from EmbodiedAgent, representing the actions that an agent is capable of performing. If None, set to empty dict. (default: 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 (). (default: None)

• unsafe_mode (bool, optional) – If True, the interpreter runs the code by eval() without any security check. (default: False)

• raise_error (bool, optional) – Raise error if the interpreter fails. (default: False)

clear_state() → None

Initialize state and fuzz_state.

execute(code: str, state: Dict[str, Any] | None = None, fuzz_state: Dict[str, Any] | None = None, keep_state: bool = True) → Any

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: 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 fuzz_state has a variable image, the generated code can use input_image to access it. (default: None)

• keep_state (bool, optional) – If True, state and fuzz_state will be kept for later execution. Otherwise, they will be cleared. (default: True)

Returns:

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.

Return type:

Any

run(code: str, code_type: str) → str

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() 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

• types (supported code)

Returns:

The string representation of the output of the executed code.

Return type:

str

Raises:

InterpreterError – If the code_type is not supported or if any runtime error occurs during the execution of the code.

supported_code_types() → List[str]

Provides supported code types by the interpreter.

update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter.

exception camel.interpreters.InterpreterError

Bases: Exception

Exception raised for errors that can be solved by regenerating code

class camel.interpreters.JupyterKernelInterpreter(require_confirm: bool = True, print_stdout: bool = False, print_stderr: bool = True)

Bases: 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.

run(code: str, code_type: str) → str

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’).

Returns:

A string containing the captured result of the

executed code.

Return type:

str

Raises:

InterpreterError – If there is an error when doing code execution.

supported_code_types() → List[str]

Provides supported code types by the interpreter.

Returns:

Supported code types.

Return type:

List[str]

update_action_space(action_space: Dict[str, Any]) → None

Updates the action space for the interpreter.

Parameters:

action_space (Dict[str, Any]) – A dictionary representing the new or updated action space.

Raises:

RuntimeError – Always raised because JupyterKernelInterpreter does not support updating the action space.

class camel.interpreters.SubprocessInterpreter(require_confirm: bool = True, print_stdout: bool = False, print_stderr: bool = True)

Bases: 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: True)

• print_stdout (bool, optional) – If True, print the standard output of the executed code. (default: False)

• print_stderr (bool, optional) – If True, print the standard error of the executed code. (default: True)

run(code: str, code_type: str) → 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:

A string containing the captured stdout and stderr of the

executed code.

Return type:

str

Raises:

InterpreterError – If the user declines to run the code or if the code type is unsupported.

run_file(file: Path, code_type: str) → str

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’).

Returns:

A string containing the captured stdout and stderr of the

executed code.

Return type:

str

Raises:

• RuntimeError – If the provided file path does not point to a file.

• InterpreterError – If the code type provided is not supported.

supported_code_types() → List[str]

Provides supported code types by the interpreter.

update_action_space(action_space: Dict[str, Any]) → None

Updates action space for python interpreter