defmodule RodarPython do
  @moduledoc """
  Python script engine adapter for [Rodar](https://github.com/rodar-project/rodar).

  Enables Python scripts in BPMN ScriptTask elements by implementing the
  `Rodar.Expression.ScriptEngine` behaviour via [Erlport](https://github.com/erlport/erlport).

  ## How It Works

  When Rodar encounters a ScriptTask with `scriptFormat="python"`, it looks up
  the registered engine in `Rodar.Expression.ScriptRegistry` and delegates to
  `RodarPython.Engine.eval/2`. The engine:

  1. JSON-encodes the process data bindings
  2. Sends the script and data to a Python interpreter via Erlport
  3. Executes the script with the `data` variable available
  4. Reads the `result` variable and decodes it back to an Elixir term

  ## Registration

  Register the engine at application startup:

      Rodar.Expression.ScriptRegistry.register("python", RodarPython.Engine)

  ## BPMN Usage

  The engine receives the current process data as the `data` variable in Python
  and stores the script's `result` value in the process context under the
  `:script_result` key (or a custom key when the task specifies `output_variable`):

      <scriptTask id="task1" name="Calculate" scriptFormat="python">
        <script>result = data["count"] + 1</script>
      </scriptTask>

  ## Modules

  - `RodarPython.Engine` — core engine implementing the `Rodar.Expression.ScriptEngine`
    behaviour with `eval/2`

  ## Guides

  - [Getting Started](guides/getting_started.md) — installation and setup
  - [Architecture](guides/architecture.md) — runtime design and component overview
  - [Data Marshalling](guides/data_marshalling.md) — type mapping between Elixir and Python
  - [Sandboxing](guides/sandboxing.md) — restricting untrusted scripts
  """
end