<?php
declare(strict_types=1);
namespace Domain\Repository;
// @responsibility: Interface für Chunk-Explorer-Operationen (Chunks mit Taxonomie/Entities)
interface ChunkExplorerRepositoryInterface
{
/**
* Get chunk statistics.
*
* @return array{total: int, tokens: int, analyzed: int, synced: int}
*/
public function getChunkStats(): array;
/**
* Count chunks with filters.
*/
public function countChunksFiltered(string $category = '', string $status = '', string $search = ''): int;
/**
* Get chunks with filters and pagination.
*
* @return array<array<string, mixed>>
*/
public function getChunksFilteredPaginated(
string $category = '',
string $status = '',
string $search = '',
int $limit = 50,
int $offset = 0
): array;
/**
* Get recent chunks.
*
* @return array<array<string, mixed>>
*/
public function getRecentChunks(int $limit = 5): array;
/**
* Get chunk by ID with decoded JSON fields.
*
* @return array<string, mixed>|null
*/
public function getChunk(int $id): ?array;
/**
* Get chunks for a document (simple).
*
* @return array<array<string, mixed>>
*/
public function getChunksForDokument(int $dokumentId): array;
/**
* Get detailed chunks for a document (all fields).
*
* @return array<array<string, mixed>>
*/
public function getChunksDetailedForDokument(int $dokumentId): array;
/**
* Get chunk by document ID and index.
*
* @return array<string, mixed>|null
*/
public function getChunkByDokumentAndIndex(int $dokumentId, int $index): ?array;
/**
* Get distinct taxonomy categories.
*
* @return array<string>
*/
public function getDistinctCategories(): array;
/**
* Get top taxonomy categories with counts.
*
* @return array<array{taxonomy_category: string, count: int}>
*/
public function getTopTaxonomyCategories(int $limit = 10): array;
/**
* Get categories with chunk and token counts.
*
* @return array<array{taxonomy_category: string, chunk_count: int, token_count: int}>
*/
public function getCategoriesWithStats(): array;
/**
* Get top keywords aggregated from chunks.
*
* @return array<string, int>
*/
public function getTopKeywords(int $limit = 30): array;
/**
* Get top entities as raw key=>count format.
*
* @return array<string, int>
*/
public function getTopEntitiesRaw(int $limit = 30): array;
/**
* Get entities grouped by type.
*
* @return array{entities: array, by_type: array<string, array>, total: int}
*/
public function getEntitiesGrouped(int $limit = 100): array;
}