<?php

declare(strict_types=1);

namespace UseCases\Chat;

// @responsibility: Interface for retrieving chat session data

use Domain\Entity\ChatMessage;
use Domain\Entity\ChatSession;

interface GetChatSessionUseCaseInterface
{
    /**
     * Get session by UUID.
     */
    public function getSession(string $uuid): ?ChatSession;

    /**
     * Get all sessions as entities.
     *
     * @return array<int, ChatSession>
     */
    public function getAllSessions(int $limit = 50): array;

    /**
     * Get all sessions with stats as arrays.
     *
     * @return array<int, array<string, mixed>>
     */
    public function getAllSessionsWithStats(int $limit = 50): array;

    /**
     * Get messages for a session.
     *
     * @return array<int, ChatMessage>
     */
    public function getMessages(int $sessionId): array;

    /**
     * Get author profiles.
     *
     * @return array<int, array<string, mixed>>
     */
    public function getAuthorProfiles(): array;

    /**
     * Get system prompts.
     *
     * @return array<int, array<string, mixed>>
     */
    public function getSystemPrompts(): array;

    /**
     * Get output structures.
     *
     * @return array<int, array<string, mixed>>
     */
    public function getOutputStructures(): array;

    /**
     * Get a single structure by ID.
     *
     * @return array<string, mixed>|null
     */
    public function getStructure(int $id): ?array;

    /**
     * Get available collections.
     *
     * @return array<int, array<string, mixed>>
     */
    public function getAvailableCollections(): array;

    /**
     * Get default system prompt.
     */
    public function getDefaultSystemPrompt(): string;
}