package de.neitzel.roleplay.business;

import de.neitzel.roleplay.fascade.model.CreateSessionRequest;
import de.neitzel.roleplay.fascade.model.SessionResponse;
import de.neitzel.roleplay.fascade.model.TurnRequest;
import de.neitzel.roleplay.fascade.model.TurnResponse;
import de.neitzel.roleplay.fascade.model.UpdateSessionRequest;

import java.util.Optional;

/**
 * Defines the contract for managing role-play sessions. Implementations are
 * responsible for session lifecycle (creation, retrieval, turn processing) and
 * state persistence.
 */
public interface SessionService {

    /**
     * Creates a new role-play session based on the provided request. Runs the
     * two-call Ollama pattern to produce an opening narrative and initial state.
     *
     * @param request the session creation parameters
     * @return the full initial session state including opening narrative and suggestions
     */
    SessionResponse createSession(CreateSessionRequest request);

    /**
     * Retrieves the current state of an existing session.
     *
     * @param sessionId the unique session identifier
     * @return an {@link Optional} containing the session response, or empty if not found
     */
    Optional<SessionResponse> getSession(String sessionId);

    /**
     * Partially updates an existing session (situation and/or characters).
     * Omitted fields in the request are left unchanged.
     *
     * @param sessionId the unique session identifier
     * @param request   the update payload; may be null or have null fields
     * @return an {@link Optional} containing the updated session, or empty if not found
     */
    Optional<SessionResponse> updateSession(String sessionId, UpdateSessionRequest request);

    /**
     * Processes a user's turn within an existing session. Runs the two-call
     * Ollama pattern and returns the resulting narrative with updated state.
     *
     * @param sessionId   the unique session identifier
     * @param turnRequest the user action and optional recommendation
     * @return an {@link Optional} containing the turn response, or empty if session not found
     */
    Optional<TurnResponse> submitTurn(String sessionId, TurnRequest turnRequest);
}