import Link from 'next/link'

# Code Execution

You can execute code using the notebook module, using the `execCell` method. The method takes a string of code as an argument and returns an object with the results of the execution.

<CodeGroup isRunnable={false}>
```js
import { CodeInterpreter } from '@e2b/code-interpreter'

const code = 'print("Hello, World!")'

const sandbox = CodeInterpreter.create()
const execution = await sandbox.notebook.execCell(code)
```

```python
from e2b_code_interpreter import CodeInterpreter

code = "print('Hello, World!')"

sandbox = CodeInterpreter.create()
execution = sandbox.notebook.exec_cell(code)
```
</CodeGroup>

The `execCell` method also accepts following optional arguments:
- `kernel id`: The ID of the kernel to execute the code on. If not provided, the default kernel is used. See <Link href="/code-interpreter/kernels">here</Link> for more info on kernels.
- `on stdout`: A callback function to handle standard output messages from the code execution.
- `on_stderr`: A callback function to handle standard error messages from the code execution.
- `on_result`: A callback function to handle the result and display calls of the code execution.

## Streaming response

You can use the `on_*` callbacks to handle the output of the code execution as it happens. This is useful for long-running code. You can stream the output to the user as it is generated.

## Execution object

The object returned by the `exec cell` method is little bit more complex, it's based on Jupyter. Here's an detailed explanation in the [Jupyter documentation](https://jupyter-client.readthedocs.io/en/stable/messaging.html).

It contains the following fields:

- `results`: A list containing result of the cell (interactively interpreted last line) and display calls (e.g. matplotlib plots).
- `logs`: Logs printed to stdout and stderr during execution.
- `error`: An error message, if there was an error during execution of the cell. It works only for Python code, not for system (`!` e.g `!pip install e2b`) commands.

### Result object

This object can be created in two different ways:
- Evaluation of the last line: If the last line of the code is an expression, the result is the value of that expression. As you would expect in REPL environments.
- Display calls: Calls to display functions, which can be used to display rich output in the notebook. E.g. [`img.show()`](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.show.html), [`display(img)`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html), etc.

Represents the data to be displayed as a result of executing a cell in a Jupyter notebook.
The result is similar to the structure returned by [ipython kernel](https://ipython.readthedocs.io/en/stable/development/execution.html#execution-semantics)

The result can contain multiple types of data, such as text, images, plots, etc. Each type of data is represented
as a string, and the result can contain multiple types of data. The display calls don't have to have text representation, it's always present for the actual result,
the other representations are optional.

The result has those basic data types:

#### Text types:
- `text`: text representation of the result
- `html`: html representation of the result
- `markdown`: markdown representation of the result
- `latex`: latex representation of the result

#### Image types:
 - `png`: "base64 encoded png image",
 - `jpeg`: "base64 encoded jpeg image",
 - `svg`": "svg image",

#### Other types:
 - `json`: "json representation",
 - `javascript`: "javascript representation",
 - `pdf`: "base64 encoded pdf"

<Note>
  If you want to integrate your own display formats or how to implement them for your classes, you can read more in [here](https://github.com/ipython/ipython/blob/main/examples/IPython%20Kernel/Custom%20Display%20Logic.ipynb)
</Note>

### Logs object

Logs printed to stdout and stderr during execution. Examples of logs are print statements, warnings, subprocess output, etc.

It contains two fields:
- `stdout`: List of strings, each string is a line printed to stdout.
- `stderr`: List of strings, each string is a line printed to stderr.

### Error object

An error message, if there was an error during execution of the cell.
<Note>
  It works only for Python code, not for system (e.g. `!pip install non_existent_package`) commands. The system commands are executed in a separate process and the output is in stdout/stderr.
</Note>

It contains three fields:
- `name`: Name of the error, e.g. `NameError`, `ValueError`, etc.
- `value`: Value of the error, e.g. `name 'non_existent_variable' is not defined`, etc.
- `traceback`: Traceback of the error.


## Example how to interpret the results to LLM

Here's an example how to return the results to LLM:

<CodeGroup isRunnable={false}>
```js
const code = '<CODE GENERATED BY LLM>'
const execution = await sandbox.notebook.execCell(code)

// There was an error during execution, return the error and its traceback
if (execution.error) {
  return `There was an error during execution: ${execution.error.name}: ${execution.error.value}.\n
  ${execution.error.traceback}`
}

// The execution has some result, summarize to LLM, what are the results
if (execution.results.length > 0) {
  let message = 'These are results of the execution:\n'
  let counter = 1
  for (const result of execution.results) {
    message += `Result ${counter++}:\n`
    if (result.isMainResult) {
      message += `[Main result]: ${result.text}\n`
    } else {
      message += `[Display data]: ${result.text}\n`
    }
    if (result.formats().length > 0) {
      message += `It has following formats: ${result.formats()}\n`
    }
  }

  return message
}

// There were no results, check if there was something is stdout/err
if (
  execution.logs.stdout.length > 0 ||
  execution.logs.stderr.length > 0
) {
  let message = 'There was no result of the execution, but here are the logs:\n'
  if (execution.logs.stdout.length > 0) {
    message += `Stdout: ${execution.logs.stdout.join('\n')}\n`
  }
  if (execution.logs.stderr.length > 0) {
    message += `Stderr: ${execution.logs.stderr.join('\n')}\n`
  }

  return message
}

return 'There was no output of the execution.'
```

```python
code = "<CODE GENERATED BY LLM>"
execution = sandbox.notebook.exec_cell(code)

# There was an error during execution, return the error and its traceback
if execution.error:
    return (
        f"There was an error during execution: {execution.error.name}: {execution.error.value}.\n"
        f"{execution.error.traceback}"
    )

# The execution has some result, summarize to LLM, what are the results
if execution.results:
    message = "These are results of the execution:\n"
    for i, result in enumerate(execution.results):
        message += f"Result {i + 1}:\n"
        if result.is_main_result:
            message += f"[Main result]: {result.text}\n"
        else:
            message += f"[Display data]: {result.text}\n"

        if result.formats():
            message += f"It has also following formats: {result.formats()}\n"

    return message

# There were no results, check if there was something is stdout/err
if execution.logs.stdout or execution.logs.stderr:
    message = "There was no result of the execution, but here are the logs:\n"
    if execution.logs.stdout:
        message += "Stdout: " + "\n".join(execution.logs.stdout) + "\n"

    if execution.logs.stderr:
        message += "Stderr: " + "\n".join(execution.logs.stderr) + "\n"

    return message

return "There was no output of the execution."
```
</CodeGroup>
