%% @doc Top-level supervisor for macula_neuroevolution.
%%
%% This supervisor manages the neuroevolution server instances.
%% It provides a simple_one_for_one strategy to allow dynamic
%% creation of training sessions.
%%
%% == Usage ==
%%
%% Use the API functions to start and stop neuroevolution servers:
%%
%% ```
%% Config = #neuro_config{...},
%% {ok, Pid} = macula_neuroevolution_sup:start_server(Config),
%% macula_neuroevolution_sup:stop_server(Pid).
%% '''
%%
%% @author Macula.io
%% @copyright 2025 Macula.io
-module(macula_neuroevolution_sup).
-behaviour(supervisor).

-include("neuroevolution.hrl").

%% API
-export([
    start_link/0,
    start_server/1,
    start_server/2,
    stop_server/1
]).

%% Supervisor callbacks
-export([init/1]).

-define(SUPERVISOR, ?MODULE).

%%% ============================================================================
%%% API Functions
%%% ============================================================================

%% @doc Start the supervisor.
-spec start_link() -> {ok, pid()} | {error, term()}.
start_link() ->
    supervisor:start_link({local, ?SUPERVISOR}, ?MODULE, []).

%% @doc Start a neuroevolution server with given configuration.
-spec start_server(Config) -> {ok, pid()} | {error, term()} when
    Config :: neuro_config().
start_server(Config) ->
    start_server(Config, []).

%% @doc Start a neuroevolution server with configuration and options.
-spec start_server(Config, Options) -> {ok, pid()} | {error, term()} when
    Config :: neuro_config(),
    Options :: proplists:proplist().
start_server(Config, Options) ->
    supervisor:start_child(?SUPERVISOR, [Config, Options]).

%% @doc Stop a neuroevolution server.
-spec stop_server(Pid) -> ok | {error, term()} when
    Pid :: pid().
stop_server(Pid) ->
    supervisor:terminate_child(?SUPERVISOR, Pid).

%%% ============================================================================
%%% Supervisor Callbacks
%%% ============================================================================

%% @private
init([]) ->
    %% Initialize the local event system
    neuroevolution_events_local:start(),

    SupFlags = #{
        strategy => simple_one_for_one,
        intensity => 5,
        period => 10
    },

    ChildSpec = #{
        id => neuroevolution_server,
        start => {neuroevolution_server, start_link, []},
        restart => temporary,
        shutdown => 5000,
        type => worker,
        modules => [neuroevolution_server]
    },

    {ok, {SupFlags, [ChildSpec]}}.