-module(pig@agent@effect).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/pig/agent/effect.gleam").
-export_type([effect/1]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Effect types for the sans-IO agent core.\n"
    "\n"
    " Effects are declarations of intent — the core describes what it wants\n"
    " done, and a runtime interprets these effects against the real world.\n"
    "\n"
    " Two effects cover the entire agent loop:\n"
    "   `CallProvider`  — send messages to the LLM\n"
    "   `ExecuteTools`  — run tool calls\n"
    "\n"
    " The `on_response` / `on_results` callbacks wrap results into the\n"
    " core's message type, closing the loop without the core knowing\n"
    " how the effects were executed.\n"
).

-type effect(INH) :: {call_provider,
        list(pig_protocol@message:message()),
        list(pig_protocol@tool_definition:tool_definition()),
        fun(({ok, pig_protocol@inference:inference_result()} |
            {error, pig_protocol@error:ai_error()}) -> INH)} |
    {execute_tools,
        list(pig_protocol@message:tool_call()),
        fun((list({pig_protocol@message:tool_call(),
            {ok, gleam@json:json()} | {error, pig@tool:tool_error()}})) -> INH)}.