"""Shared machine-readable fields for RAG and GraphRAG tool responses.

Completeness describes retrieval, not correctness or answerability. RAG is a
ranked selection and cannot promise exhaustive coverage of the wiki.
"""
from __future__ import annotations

import sqlite3
from typing import Any, Literal, Sequence

from neo4j.exceptions import Neo4jError, ServiceUnavailable, SessionExpired
from pydantic import BaseModel, ConfigDict, Field


RetrievalStatus = Literal['ok', 'no_answer', 'ambiguous', 'error']


class RetrievalSource(BaseModel):
    model_config = ConfigDict(extra='allow')

    source_id: str
    document_path: str
    source_url: str | None = None
    title: str | None = None


class RetrievalResponse(BaseModel):
    status: RetrievalStatus = 'ok'
    reason: str | None = None
    sources: list[RetrievalSource] = Field(default_factory=list)
    index_version: dict[str, Any] | None = None
    complete: bool | None = Field(default=None, description=(
        'Úplnosť vyhľadania v rozsahu nástroja: true=úplné, false=neúplné, '
        'null=nemožno zaručiť. Nevyjadruje pravdivosť odpovede.'))
    truncated: bool = False
    truncation_reasons: list[str] = Field(default_factory=list)


class RetrievalErrorResponse(RetrievalResponse):
    status: Literal['error'] = 'error'
    detail: Any = None


def source_references(rows: list[dict]) -> list[dict]:
    """Stable citation shape; never invent a URL or a document title."""
    return [{
        'source_id': f'S{number}', 'document_path': row['document_path'],
        'source_url': row.get('source_url'), 'title': row.get('title'),
    } for number, row in enumerate(rows, 1)]


def result_fields(*, status: RetrievalStatus, sources: list[dict], reason: str | None = None,
                  complete: bool | None = None, truncation_reasons: Sequence[str] = (),
                  index_version: dict | None = None) -> dict:
    reasons = list(dict.fromkeys(truncation_reasons))
    return {
        'status': status, 'reason': reason, 'sources': sources,
        'index_version': index_version,
        'complete': False if reasons or status in {'error', 'ambiguous'} else complete,
        'truncated': bool(reasons), 'truncation_reasons': reasons,
    }


def error_reason(error: Exception) -> str:
    if isinstance(error, ValueError):
        return 'invalid_query'
    if isinstance(error, (FileNotFoundError, sqlite3.Error, RuntimeError,
                          Neo4jError, ServiceUnavailable, SessionExpired)):
        return 'retrieval_unavailable'
    return 'internal_error'


def error_result(error: Exception | None = None, *, reason: str | None = None) -> dict:
    # Raw exception messages can contain credentials, SQL or private paths.
    return result_fields(status='error', sources=[], complete=False,
                         reason=reason or error_reason(error))