app/api/kb_admin.py

from fastapi import APIRouter, HTTPException, Query
from pydantic import BaseModel

from app.services.rag.rag_engine import rag_engine
from app.services.rag.vector_store import vector_store

router = APIRouter(prefix="/kb", tags=["kb-admin"])


class KbDocumentInput(BaseModel):
    title: str
    content: str


@router.get("/search")
async def search_kb(q: str, top_k: int = 3):
    """
    Interrogates the underlying Retrieval-Augmented Generation (RAG) knowledge base for semantic similarities.
    Accepts text queries and vector-embeds them utilizing the natively configured embedding parameters.
    Retrieves the topmost relevant corporate document snippets utilizing optimized cosine similarity algorithms.
    Returns a structured array of related textual contexts to synthesize or debug LLM contextual injections.
    """
    return {"results": rag_engine.search(q, top_k=top_k)}


@router.post("/documents")
async def add_document(payload: KbDocumentInput):
    """
    Ingests authoritative organizational documents permanently embedding them into the vector index space.
    Requires structured title and content pairings to partition distinct semantic knowledge representations.
    Executes automated embedding generation sequences to populate the local or remote semantic structures.
    Returns boolean confirmation markers signaling the successful propagation and indexing of the data chunks.
    """
    if not payload.title.strip() or not payload.content.strip():
        raise HTTPException(status_code=400, detail="title/content مطلوبين")
    return rag_engine.add_document(payload.title, payload.content)


@router.get("/documents")
async def list_documents(limit: int = 50, offset: int = 0):
    """
    Lists documents currently indexed in the knowledge base.
    Supports basic pagination via limit and offset parameters.
    """
    return {"documents": rag_engine.list_documents(limit=limit, offset=offset)}


@router.delete("/documents/{doc_id}")
async def delete_document(doc_id: str):
    """
    Removes a document from the active vector index.
    Requires the unique UUID of the target document.
    """
    success = rag_engine.delete_document(doc_id)
    if not success:
        raise HTTPException(status_code=404, detail="Document not found or could not be deleted")
    return {"deleted": True, "id": doc_id}


@router.get("/stats")
async def kb_stats():
    """
    Returns operational statistics about the underlying vector database.
    Useful for health checks and capacity monitoring.
    """
    return {"vector_store": vector_store.get_collection_info()}


@router.post("/refresh")
async def refresh_kb():
    """
    Forces a synchronous refresh operation against the local disk storage or remote vector representation indexes.
    Commands the RAG singleton engine to reload memory-mapped chunks directly from persistent state directory architectures.
    Essential tool for ensuring high consistency following batched corporate knowledge base uploads via the admin portal.
    Returns a simple acknowledgment flag dictating the flush cycle and data reloading methodologies have successfully terminated.
    """
    rag_engine.refresh_index()
    return {"refreshed": True}