<?php

declare(strict_types=1);

namespace Domain\Repository;

// @responsibility: Interface für Semantik-Suche und Graph-Daten

interface SemanticSearchRepositoryInterface
{
    /**
     * Holt Gesamtstatistiken über Entitäten, Relationen, Taxonomie, Ontologie, Semantik.
     *
     * @return array{entities: int, relations: int, taxonomy: int, ontology: int, semantics: int}
     */
    public function getSemanticStats(): array;

    /**
     * Holt Entitäten mit Bedeutungen/Beschreibungen (gefiltert).
     *
     * @return array<int, array{id: int, name: string, type: string, description: ?string, chunk_id: ?int, chunk_index: ?int, document_id: ?int, filename: ?string}>
     */
    public function findEntitySemantics(string $search = '', string $type = '', int $limit = 50, int $offset = 0): array;

    /**
     * Zählt Entitäten mit Bedeutungen (gefiltert).
     */
    public function countEntitySemantics(string $search = '', string $type = ''): int;

    /**
     * Holt Graph-Daten für D3.js Visualisierung.
     *
     * @return array{nodes: array, links: array, stats: array}
     */
    public function getGraphData(): array;
}