import asyncio
import inspect
import logging
import threading
from collections.abc import Callable
from datetime import UTC, datetime
from typing import Any

from fastapi import (
    APIRouter,
    BackgroundTasks,
    Depends,
    FastAPI,
    HTTPException,
    Request,
    status,
)
from fastapi.middleware.cors import CORSMiddleware
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.errors import RateLimitExceeded
from slowapi.util import get_remote_address
from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.responses import Response

from reflexio.models.api_schema.braintrust_schema import (
    BraintrustStatusResponse,
    ConnectBraintrustRequest,
    ConnectBraintrustResponse,
    SelectProjectsRequest,
    SelectProjectsResponse,
    SyncBraintrustResponse,
)
from reflexio.models.api_schema.eval_overview_schema import (
    GetEvaluationOverviewRequest,
    GetEvaluationOverviewResponse,
    GetRecentShadowComparisonsResponse,
    GradeOnDemandRequest,
    GradeOnDemandResponse,
    RegenerateFailure,
    RegenerateRequest,
    RegenerateStartResponse,
    RegenerateStatusResponse,
)
from reflexio.models.api_schema.retriever_schema import (
    GetAgentPlaybooksRequest,
    GetAgentPlaybooksViewResponse,
    GetAgentSuccessEvaluationResultsRequest,
    GetDashboardStatsRequest,
    GetDashboardStatsResponse,
    GetEvaluationResultsViewResponse,
    GetInteractionsRequest,
    GetInteractionsViewResponse,
    GetPlaybookApplicationStatsRequest,
    GetPlaybookApplicationStatsResponse,
    GetProfileStatisticsResponse,
    GetProfilesViewResponse,
    GetRequestsRequest,
    GetRequestsViewResponse,
    GetUserPlaybooksRequest,
    GetUserPlaybooksViewResponse,
    GetUserProfilesRequest,
    ProfileChangeLogViewResponse,
    RequestDataView,
    RerankUserProfilesRequest,
    SearchAgentPlaybookRequest,
    SearchAgentPlaybooksViewResponse,
    SearchInteractionRequest,
    SearchInteractionsViewResponse,
    SearchProfilesViewResponse,
    SearchUserPlaybookRequest,
    SearchUserPlaybooksViewResponse,
    SearchUserProfileRequest,
    SessionView,
    SetConfigResponse,
    StorageStatsRequest,
    StorageStatsResponse,
    UnifiedSearchRequest,
    UnifiedSearchViewResponse,
    UpdateAgentPlaybookRequest,
    UpdateAgentPlaybookResponse,
    UpdatePlaybookStatusRequest,
    UpdatePlaybookStatusResponse,
    UpdateUserPlaybookRequest,
    UpdateUserPlaybookResponse,
    UpdateUserProfileRequest,
    UpdateUserProfileResponse,
)
from reflexio.models.api_schema.service_schemas import (
    AddAgentPlaybookRequest,
    AddAgentPlaybookResponse,
    AddUserPlaybookRequest,
    AddUserPlaybookResponse,
    AddUserProfileRequest,
    AddUserProfileResponse,
    AdminInvalidateCacheRequest,
    AdminInvalidateCacheResponse,
    BulkDeleteResponse,
    CancelOperationRequest,
    CancelOperationResponse,
    ClearUserDataRequest,
    ClearUserDataResponse,
    DeleteAgentPlaybookRequest,
    DeleteAgentPlaybookResponse,
    DeleteAgentPlaybooksByIdsRequest,
    DeleteProfilesByIdsRequest,
    DeleteRequestRequest,
    DeleteRequestResponse,
    DeleteRequestsByIdsRequest,
    DeleteSessionRequest,
    DeleteSessionResponse,
    DeleteUserInteractionRequest,
    DeleteUserInteractionResponse,
    DeleteUserPlaybookRequest,
    DeleteUserPlaybookResponse,
    DeleteUserPlaybooksByIdsRequest,
    DeleteUserProfileRequest,
    DeleteUserProfileResponse,
    DowngradeProfilesRequest,
    DowngradeProfilesResponse,
    DowngradeUserPlaybooksRequest,
    DowngradeUserPlaybooksResponse,
    GetOperationStatusRequest,
    GetOperationStatusResponse,
    ManualPlaybookGenerationRequest,
    ManualPlaybookGenerationResponse,
    ManualProfileGenerationRequest,
    ManualProfileGenerationResponse,
    MyConfigResponse,
    PlaybookAggregationChangeLogResponse,
    PublishUserInteractionRequest,
    PublishUserInteractionResponse,
    RerunPlaybookGenerationRequest,
    RerunPlaybookGenerationResponse,
    RerunProfileGenerationRequest,
    RerunProfileGenerationResponse,
    RunPlaybookAggregationRequest,
    RunPlaybookAggregationResponse,
    Status,
    UpgradeProfilesRequest,
    UpgradeProfilesResponse,
    UpgradeUserPlaybooksRequest,
    UpgradeUserPlaybooksResponse,
    WhoamiResponse,
)
from reflexio.models.api_schema.ui.converters import (
    to_agent_playbook_view,
    to_evaluation_result_view,
    to_interaction_view,
    to_profile_change_log_view,
    to_profile_view,
    to_user_playbook_view,
)
from reflexio.models.config_schema import (
    SINGLETON_AGENT_SUCCESS_EVALUATION_NAME,
    Config,
)
from reflexio.server._auth import DEFAULT_ORG_ID, default_get_org_id
from reflexio.server.api_endpoints import (
    account_api,
    health_api,
    pending_tool_call_api,
    publisher_api,
    stall_state_api,
)
from reflexio.server.cache.reflexio_cache import (
    get_reflexio,
    invalidate_reflexio_cache,
)
from reflexio.server.correlation import correlation_id_var, generate_correlation_id
from reflexio.server.operation_limiter import (
    OperationName,
    limiter_http_exception,
    run_with_operation_limit,
)
from reflexio.server.services.agent_success_evaluation.group_evaluation_runner import (
    run_group_evaluation,
)
from reflexio.server.services.agent_success_evaluation.regen_jobs import (
    REGEN_JOBS,
    run_regen,
)

logger = logging.getLogger(__name__)

# Re-exported for backwards compatibility — callers that did
# ``from reflexio.server.api import default_get_org_id`` or ``DEFAULT_ORG_ID``
# continue to work.
__all__ = ["DEFAULT_ORG_ID", "create_app", "default_get_org_id"]

# Bot protection configuration
REQUEST_TIMEOUT_SECONDS = 60
SYNC_REQUEST_TIMEOUT_SECONDS = (
    600  # Longer timeout for synchronous processing (wait_for_response=true)
)
SUSPICIOUS_USER_AGENTS = ["bot", "crawler", "spider", "scraper", "curl", "wget"]
ALLOWED_EMPTY_UA_PATHS = ["/health", "/"]  # Paths that allow empty user agents


def get_rate_limit_key(request: Request) -> str:
    """Get rate limit key based on IP address.

    Args:
        request (Request): The incoming request

    Returns:
        str: Rate limit key (IP address)
    """
    return get_remote_address(request)


# Initialize rate limiter
limiter = Limiter(key_func=get_rate_limit_key)


def _run_limited_api[T](
    org_id: str,
    operation: OperationName,
    fn: Callable[[], T],
) -> T:
    try:
        return run_with_operation_limit(
            org_id=org_id,
            operation=operation,
            fn=fn,
        )
    except TimeoutError as exc:
        http_exc = limiter_http_exception(operation)
        raise http_exc from exc


def configure_rate_limiter(key_func: Callable[..., str]) -> None:
    """
    Replace the rate limiter's key function.

    This is the supported way to override the default IP-based key function
    (e.g. with an org-scoped or token-scoped variant in the enterprise layer).

    Args:
        key_func: A callable that accepts a Request and returns a string key.
    """
    limiter._key_func = key_func  # type: ignore[reportAttributeAccessIssue]


class BotProtectionMiddleware(BaseHTTPMiddleware):
    """Middleware to detect and block suspicious bot-like requests."""

    async def dispatch(
        self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        """Process request and block suspicious patterns.

        Args:
            request (Request): The incoming request
            call_next (RequestResponseEndpoint): Next middleware/handler in chain

        Returns:
            Response: The response from the next handler or a 403 JSON response
        """
        from starlette.responses import JSONResponse

        user_agent = request.headers.get("user-agent", "").lower()
        path = request.url.path

        # Allow health check and root without user agent
        if path not in ALLOWED_EMPTY_UA_PATHS:
            # Block requests with no user agent
            if not user_agent:
                return JSONResponse(
                    status_code=status.HTTP_403_FORBIDDEN,
                    content={"detail": "Forbidden: Missing user agent"},
                )

            # Block requests with suspicious user agents
            for suspicious in SUSPICIOUS_USER_AGENTS:
                if suspicious in user_agent:
                    return JSONResponse(
                        status_code=status.HTTP_403_FORBIDDEN,
                        content={"detail": "Forbidden: Suspicious user agent"},
                    )

        return await call_next(request)


class TimeoutMiddleware(BaseHTTPMiddleware):
    """Middleware to enforce request timeout."""

    async def dispatch(
        self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        """Process request with timeout enforcement.

        Args:
            request (Request): The incoming request
            call_next (RequestResponseEndpoint): Next middleware/handler in chain

        Returns:
            Response: The response from the next handler or a 504 JSON response
        """
        from starlette.responses import JSONResponse

        # Use longer timeout for synchronous processing requests
        timeout = REQUEST_TIMEOUT_SECONDS
        if request.query_params.get("wait_for_response", "").lower() == "true":
            timeout = SYNC_REQUEST_TIMEOUT_SECONDS

        try:
            return await asyncio.wait_for(call_next(request), timeout=timeout)
        except TimeoutError:
            return JSONResponse(
                status_code=status.HTTP_504_GATEWAY_TIMEOUT,
                content={"detail": "Request timeout"},
            )


class CorrelationIdMiddleware(BaseHTTPMiddleware):
    """Middleware that assigns a unique correlation ID to each request.

    The ID is stored in a ContextVar so it propagates to log records
    (via CorrelationIdFilter) and to ThreadPoolExecutor workers when
    ``contextvars.copy_context()`` is used.
    """

    async def dispatch(
        self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        cid = generate_correlation_id()
        correlation_id_var.set(cid)
        response = await call_next(request)
        response.headers["X-Correlation-ID"] = cid
        return response


core_router = APIRouter()


@core_router.get("/")
def root() -> dict[str, str]:
    return {
        "service": "Reflexio API",
        "docs": "/docs",
        "health": "/health",
    }


@core_router.get("/health")
def health_check() -> dict[str, str]:
    """Health check endpoint for ECS/container orchestration."""
    return {"status": "healthy"}


@core_router.get(
    "/api/whoami",
    response_model=WhoamiResponse,
    response_model_exclude_none=True,
)
def whoami_endpoint(
    org_id: str = Depends(default_get_org_id),
) -> WhoamiResponse:
    """Return the caller's org and masked storage routing.

    Powers ``reflexio status``. Safe to call unauthenticated in
    self-host mode; the enterprise server wraps this in Bearer auth.
    """
    return account_api.whoami(org_id=org_id)


@core_router.get(
    "/api/my_config",
    response_model=MyConfigResponse,
    response_model_exclude_none=True,
)
def my_config_endpoint(
    request: Request,
    org_id: str = Depends(default_get_org_id),
) -> MyConfigResponse:
    """Return raw storage credentials for the caller's org.

    Enablement is controlled by two independent opt-ins so the endpoint
    is closed by default on unauthenticated self-host deployments:

    - ``request.app.state.my_config_enabled`` — set to True by
      :func:`create_app` when the host wires in a Bearer-auth
      ``get_org_id`` dependency, so enterprise callers are always
      authenticated before they reach this route.
    - ``REFLEXIO_ALLOW_MY_CONFIG=true`` — OS self-host escape hatch.

    If neither is set we return a closed response instead of a 404 so
    the CLI can display an actionable hint.
    """
    app_state_enabled = bool(getattr(request.app.state, "my_config_enabled", False))
    if not (app_state_enabled or account_api.my_config_allowed()):
        return MyConfigResponse(
            success=False,
            message=(
                "GET /api/my_config is disabled. Set "
                "REFLEXIO_ALLOW_MY_CONFIG=true to enable."
            ),
        )
    return account_api.my_config(org_id=org_id)


@core_router.post(
    "/api/publish_interaction",
    response_model=PublishUserInteractionResponse,
    response_model_exclude_none=True,
)
@limiter.limit("60/minute")  # Rate limit for write operations
def publish_user_interaction(
    request: Request,
    payload: PublishUserInteractionRequest,
    background_tasks: BackgroundTasks,
    org_id: str = Depends(default_get_org_id),
    wait_for_response: bool = False,
) -> PublishUserInteractionResponse:
    if wait_for_response:
        # Process synchronously so the caller gets the real result
        return _run_limited_api(
            org_id,
            "publish",
            lambda: publisher_api.add_user_interaction(org_id=org_id, request=payload),
        )

    def _limited_publish_task() -> None:
        try:
            run_with_operation_limit(
                org_id=org_id,
                operation="publish",
                fn=lambda: publisher_api.add_user_interaction(
                    org_id=org_id, request=payload
                ),
            )
        except TimeoutError:
            logger.warning(
                "Dropped queued publish for org %s because publish limiter is saturated",
                org_id,
            )

    # Run in background — caller gets immediate acknowledgement
    background_tasks.add_task(_limited_publish_task)
    return PublishUserInteractionResponse(
        success=True, message="Interaction queued for processing"
    )


@core_router.post(
    "/api/add_user_playbook",
    response_model=AddUserPlaybookResponse,
    response_model_exclude_none=True,
)
@limiter.limit("60/minute")  # Rate limit for write operations
def add_user_playbook_endpoint(
    request: Request,
    payload: AddUserPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> AddUserPlaybookResponse:
    """Add user playbook directly to storage.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (AddUserPlaybookRequest): The request containing user playbooks
        org_id (str): Organization ID

    Returns:
        AddUserPlaybookResponse: Response containing success status, message, and added count
    """
    return publisher_api.add_user_playbook(org_id=org_id, request=payload)


@core_router.post(
    "/api/add_agent_playbook",
    response_model=AddAgentPlaybookResponse,
    response_model_exclude_none=True,
)
@limiter.limit("60/minute")  # Rate limit for write operations
def add_agent_playbook_endpoint(
    request: Request,
    payload: AddAgentPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> AddAgentPlaybookResponse:
    """Add agent playbook directly to storage.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (AddAgentPlaybookRequest): The request containing agent playbooks
        org_id (str): Organization ID

    Returns:
        AddAgentPlaybookResponse: Response containing success status, message, and added count
    """
    return publisher_api.add_agent_playbook(org_id=org_id, request=payload)


@core_router.post(
    "/api/add_user_profile",
    response_model=AddUserProfileResponse,
    response_model_exclude_none=True,
)
@limiter.limit("60/minute")  # Rate limit for write operations
def add_user_profile_endpoint(
    request: Request,
    payload: AddUserProfileRequest,
    org_id: str = Depends(default_get_org_id),
) -> AddUserProfileResponse:
    """Add user profile directly to storage, bypassing inference.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (AddUserProfileRequest): The request containing user profiles
        org_id (str): Organization ID

    Returns:
        AddUserProfileResponse: Response containing success status, message, and added count
    """
    return publisher_api.add_user_profile(org_id=org_id, request=payload)


@core_router.post(
    "/api/search_profiles",
    response_model=SearchProfilesViewResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")  # Rate limit for read operations
def search_user_profiles(
    request: Request,
    payload: SearchUserProfileRequest,
    org_id: str = Depends(default_get_org_id),
) -> SearchProfilesViewResponse:
    response = _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).search_user_profiles(payload),
    )
    return SearchProfilesViewResponse(
        success=response.success,
        user_profiles=[to_profile_view(p) for p in response.user_profiles],
        msg=response.msg,
    )


@core_router.post(
    "/api/rerank_user_profiles",
    response_model=SearchProfilesViewResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")  # Rate limit for read operations
def rerank_user_profiles(
    request: Request,
    payload: RerankUserProfilesRequest,
    org_id: str = Depends(default_get_org_id),
) -> SearchProfilesViewResponse:
    """Rerank a list of profile ids by query relevance using a cross-encoder.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (RerankUserProfilesRequest): The rerank request
        org_id (str): Organization ID

    Returns:
        SearchProfilesViewResponse: Reranked profiles, top_k entries.
    """
    response = _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).rerank_user_profiles(payload),
    )
    return SearchProfilesViewResponse(
        success=response.success,
        user_profiles=[to_profile_view(p) for p in response.user_profiles],
        msg=response.msg,
    )


@core_router.get(
    "/api/storage_stats",
    response_model=StorageStatsResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")  # Rate limit for read operations
def storage_stats(
    request: Request,
    user_id: str,
    org_id: str = Depends(default_get_org_id),
) -> StorageStatsResponse:
    """Return lightweight metadata about a user's profiles and playbooks.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        user_id (str): Target user id, passed as a query parameter so this is
            a cacheable, idempotent GET.
        org_id (str): Organization ID

    Returns:
        StorageStatsResponse: Counts and timestamp range for the user.
    """
    return _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).storage_stats(
            StorageStatsRequest(user_id=user_id)
        ),
    )


@core_router.post(
    "/api/search_interactions",
    response_model=SearchInteractionsViewResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")  # Rate limit for read operations
def search_interactions(
    request: Request,
    payload: SearchInteractionRequest,
    org_id: str = Depends(default_get_org_id),
) -> SearchInteractionsViewResponse:
    response = _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).search_interactions(payload),
    )
    return SearchInteractionsViewResponse(
        success=response.success,
        interactions=[to_interaction_view(i) for i in response.interactions],
        msg=response.msg,
    )


@core_router.post(
    "/api/search_user_playbooks",
    response_model=SearchUserPlaybooksViewResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")  # Rate limit for read operations
def search_user_playbooks_endpoint(
    request: Request,
    payload: SearchUserPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> SearchUserPlaybooksViewResponse:
    """Search user playbooks with semantic search and advanced filtering.

    Supports filtering by user_id (via request_id linkage), agent_version,
    playbook_name, datetime range, and status.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (SearchUserPlaybookRequest): The search request
        org_id (str): Organization ID

    Returns:
        SearchUserPlaybooksViewResponse: Response containing matching user playbooks
    """
    response = _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).search_user_playbooks(payload),
    )
    return SearchUserPlaybooksViewResponse(
        success=response.success,
        user_playbooks=[to_user_playbook_view(rf) for rf in response.user_playbooks],
        msg=response.msg,
    )


@core_router.post(
    "/api/search_agent_playbooks",
    response_model=SearchAgentPlaybooksViewResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")  # Rate limit for read operations
def search_agent_playbooks_endpoint(
    request: Request,
    payload: SearchAgentPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> SearchAgentPlaybooksViewResponse:
    """Search agent playbooks with semantic search and advanced filtering.

    Supports filtering by agent_version, playbook_name, datetime range,
    status_filter, and playbook_status_filter.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (SearchAgentPlaybookRequest): The search request
        org_id (str): Organization ID

    Returns:
        SearchAgentPlaybooksViewResponse: Response containing matching agent playbooks
    """
    response = _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).search_agent_playbooks(payload),
    )
    return SearchAgentPlaybooksViewResponse(
        success=response.success,
        agent_playbooks=[to_agent_playbook_view(fb) for fb in response.agent_playbooks],
        msg=response.msg,
    )


@core_router.post(
    "/api/search",
    response_model=UnifiedSearchViewResponse,
    response_model_exclude_none=True,
)
@limiter.limit("120/minute")
def unified_search_endpoint(
    request: Request,
    payload: UnifiedSearchRequest,
    org_id: str = Depends(default_get_org_id),
) -> UnifiedSearchViewResponse:
    """Search across all entity types (profiles, agent playbooks, user playbooks).

    Runs query rewriting and embedding generation in parallel, then searches
    all entity types in parallel. Query rewriting is gated behind the
    enable_reformulation request param.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (UnifiedSearchRequest): The unified search request
        org_id (str): Organization ID

    Returns:
        UnifiedSearchViewResponse: Combined search results
    """
    response = _run_limited_api(
        org_id,
        "search",
        lambda: get_reflexio(org_id=org_id).unified_search(payload, org_id=org_id),
    )
    return UnifiedSearchViewResponse(
        success=response.success,
        profiles=[to_profile_view(p) for p in response.profiles],
        agent_playbooks=[to_agent_playbook_view(fb) for fb in response.agent_playbooks],
        user_playbooks=[to_user_playbook_view(rf) for rf in response.user_playbooks],
        reformulated_query=response.reformulated_query,
        msg=response.msg,
        agent_trace=response.agent_trace,
        rehydrated_text=response.rehydrated_text,
    )


@core_router.get("/api/profile_change_log", response_model=ProfileChangeLogViewResponse)
def get_profile_change_log(
    org_id: str = Depends(default_get_org_id),
) -> ProfileChangeLogViewResponse:
    response = get_reflexio(org_id=org_id).get_profile_change_logs()
    return ProfileChangeLogViewResponse(
        success=response.success,
        profile_change_logs=[
            to_profile_change_log_view(log) for log in response.profile_change_logs
        ],
    )


@core_router.get(
    "/api/playbook_aggregation_change_logs",
    response_model=PlaybookAggregationChangeLogResponse,
)
def get_playbook_aggregation_change_logs(
    playbook_name: str,
    agent_version: str,
    org_id: str = Depends(default_get_org_id),
) -> PlaybookAggregationChangeLogResponse:
    return get_reflexio(org_id=org_id).get_playbook_aggregation_change_logs(
        playbook_name=playbook_name,
        agent_version=agent_version,
    )


@core_router.delete(
    "/api/delete_profile",
    response_model=DeleteUserProfileResponse,
    response_model_exclude_none=True,
)
def delete_profile(
    request: DeleteUserProfileRequest,
    org_id: str = Depends(default_get_org_id),
) -> DeleteUserProfileResponse:
    return publisher_api.delete_user_profile(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_interaction",
    response_model=DeleteUserInteractionResponse,
    response_model_exclude_none=True,
)
def delete_interaction(
    request: DeleteUserInteractionRequest,
    org_id: str = Depends(default_get_org_id),
) -> DeleteUserInteractionResponse:
    return publisher_api.delete_user_interaction(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_request",
    response_model=DeleteRequestResponse,
    response_model_exclude_none=True,
)
def delete_request(
    request: DeleteRequestRequest,
    org_id: str = Depends(default_get_org_id),
) -> DeleteRequestResponse:
    return publisher_api.delete_request(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_session",
    response_model=DeleteSessionResponse,
    response_model_exclude_none=True,
)
def delete_session(
    request: DeleteSessionRequest,
    org_id: str = Depends(default_get_org_id),
) -> DeleteSessionResponse:
    return publisher_api.delete_session(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_agent_playbook",
    response_model=DeleteAgentPlaybookResponse,
    response_model_exclude_none=True,
)
def delete_agent_playbook(
    request: DeleteAgentPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> DeleteAgentPlaybookResponse:
    return publisher_api.delete_agent_playbook(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_user_playbook",
    response_model=DeleteUserPlaybookResponse,
    response_model_exclude_none=True,
)
def delete_user_playbook(
    request: DeleteUserPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> DeleteUserPlaybookResponse:
    return publisher_api.delete_user_playbook(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_requests_by_ids",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_requests_by_ids(
    request: DeleteRequestsByIdsRequest,
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete multiple requests by their IDs.

    Args:
        request (DeleteRequestsByIdsRequest): Request containing list of request IDs to delete
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_requests_by_ids(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_profiles_by_ids",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_profiles_by_ids(
    request: DeleteProfilesByIdsRequest,
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete multiple profiles by their IDs.

    Args:
        request (DeleteProfilesByIdsRequest): Request containing list of profile IDs to delete
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_profiles_by_ids(org_id=org_id, request=request)


@core_router.delete(
    "/api/delete_agent_playbooks_by_ids",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_agent_playbooks_by_ids(
    request: DeleteAgentPlaybooksByIdsRequest,
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete multiple agent playbooks by their IDs.

    Args:
        request (DeleteAgentPlaybooksByIdsRequest): Request containing list of agent playbook IDs to delete
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_agent_playbooks_by_ids_bulk(
        org_id=org_id, request=request
    )


@core_router.delete(
    "/api/delete_user_playbooks_by_ids",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_user_playbooks_by_ids(
    request: DeleteUserPlaybooksByIdsRequest,
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete multiple user playbooks by their IDs.

    Args:
        request (DeleteUserPlaybooksByIdsRequest): Request containing list of user playbook IDs to delete
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_user_playbooks_by_ids_bulk(
        org_id=org_id, request=request
    )


@core_router.delete(
    "/api/delete_all_interactions",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_all_interactions(
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete all requests and their associated interactions.

    Args:
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_all_interactions_bulk(org_id=org_id)


@core_router.delete(
    "/api/delete_all_profiles",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_all_profiles(
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete all profiles.

    Args:
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_all_profiles_bulk(org_id=org_id)


@core_router.delete(
    "/api/delete_all_playbooks",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_all_playbooks(
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete all playbooks (both user and agent).

    Args:
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_all_playbooks_bulk(org_id=org_id)


@core_router.delete(
    "/api/delete_all_user_playbooks",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_all_user_playbooks(
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete all user playbooks (user only, not agent).

    Args:
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_all_user_playbooks_bulk(org_id=org_id)


@core_router.delete(
    "/api/delete_all_agent_playbooks",
    response_model=BulkDeleteResponse,
    response_model_exclude_none=True,
)
def delete_all_agent_playbooks(
    org_id: str = Depends(default_get_org_id),
) -> BulkDeleteResponse:
    """Delete all agent playbooks (agent only, not user).

    Args:
        org_id (str): Organization ID

    Returns:
        BulkDeleteResponse: Response containing success status and deleted count
    """
    return publisher_api.delete_all_agent_playbooks_bulk(org_id=org_id)


@core_router.post(
    "/api/clear_user_data",
    response_model=ClearUserDataResponse,
    response_model_exclude_none=True,
)
def clear_user_data(
    request: ClearUserDataRequest,
    org_id: str = Depends(default_get_org_id),
) -> ClearUserDataResponse:
    """Delete all rows scoped to a single ``user_id``.

    Removes the user's interactions, user playbooks, profiles, and
    requests. Does NOT touch ``agent_playbooks`` — they are
    intentionally shared cross-project. Used by paired-protocol
    harnesses (e.g. SWE-bench) to isolate per-task data on a shared
    backend without one task's clear-all nuking another in-flight
    task's rows.

    Args:
        request (ClearUserDataRequest): Request containing the target user_id
        org_id (str): Organization ID

    Returns:
        ClearUserDataResponse: Response with per-entity deletion counts
    """
    return publisher_api.clear_user_data(org_id=org_id, request=request)


@core_router.post(
    "/api/get_interactions",
    response_model=GetInteractionsViewResponse,
    response_model_exclude_none=True,
)
def get_interactions(
    request: GetInteractionsRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetInteractionsViewResponse:
    response = get_reflexio(org_id=org_id).get_interactions(request)
    return GetInteractionsViewResponse(
        success=response.success,
        interactions=[to_interaction_view(i) for i in response.interactions],
        msg=response.msg,
    )


@core_router.get(
    "/api/get_all_interactions",
    response_model=GetInteractionsViewResponse,
    response_model_exclude_none=True,
)
def get_all_interactions(
    limit: int = 100,
    org_id: str = Depends(default_get_org_id),
) -> GetInteractionsViewResponse:
    """Get all user interactions across all users.

    Args:
        limit (int, optional): Maximum number of interactions to return. Defaults to 100.
        org_id (str): Organization ID

    Returns:
        GetInteractionsViewResponse: Response containing all user interactions
    """
    reflexio = get_reflexio(org_id=org_id)
    response = reflexio.get_all_interactions(limit=limit)
    return GetInteractionsViewResponse(
        success=response.success,
        interactions=[to_interaction_view(i) for i in response.interactions],
        msg=response.msg,
    )


@core_router.post(
    "/api/get_requests",
    response_model=GetRequestsViewResponse,
    response_model_exclude_none=True,
)
def get_requests_endpoint(
    request: GetRequestsRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetRequestsViewResponse:
    """Get requests with their associated interactions.

    Args:
        request (GetRequestsRequest): The get request
        org_id (str): Organization ID

    Returns:
        GetRequestsViewResponse: Response containing requests with their interactions
    """
    internal_response = get_reflexio(org_id=org_id).get_requests(request)
    return GetRequestsViewResponse(
        success=internal_response.success,
        sessions=[
            SessionView(
                session_id=s.session_id,
                requests=[
                    RequestDataView(
                        request=rd.request,
                        interactions=[to_interaction_view(i) for i in rd.interactions],
                    )
                    for rd in s.requests
                ],
            )
            for s in internal_response.sessions
        ],
        has_more=internal_response.has_more,
        msg=internal_response.msg,
    )


@core_router.post(
    "/api/get_profiles",
    response_model=GetProfilesViewResponse,
    response_model_exclude_none=True,
)
def get_profiles(
    request: GetUserProfilesRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetProfilesViewResponse:
    response = get_reflexio(org_id=org_id).get_profiles(request)
    return GetProfilesViewResponse(
        success=response.success,
        user_profiles=[to_profile_view(p) for p in response.user_profiles],
        msg=response.msg,
    )


@core_router.get(
    "/api/get_all_profiles",
    response_model=GetProfilesViewResponse,
    response_model_exclude_none=True,
)
def get_all_profiles(
    limit: int = 100,
    status_filter: str | None = None,
    org_id: str = Depends(default_get_org_id),
) -> GetProfilesViewResponse:
    """Get all user profiles across all users.

    Args:
        limit (int, optional): Maximum number of profiles to return. Defaults to 100.
        status_filter (str, optional): Filter by profile status. Can be "current", "pending", or "archived".
        org_id (str): Organization ID

    Returns:
        GetProfilesViewResponse: Response containing all user profiles
    """
    reflexio = get_reflexio(org_id=org_id)

    # Map status_filter string to Status list
    status_filter_list = None
    if status_filter == "current":
        status_filter_list = [None]
    elif status_filter == "pending":
        status_filter_list = [Status.PENDING]
    elif status_filter == "archived":
        status_filter_list = [Status.ARCHIVED]

    response = reflexio.get_all_profiles(limit=limit, status_filter=status_filter_list)  # type: ignore[reportArgumentType]
    return GetProfilesViewResponse(
        success=response.success,
        user_profiles=[to_profile_view(p) for p in response.user_profiles],
        msg=response.msg,
    )


@core_router.get(
    "/api/get_profile_statistics",
    response_model=GetProfileStatisticsResponse,
    response_model_exclude_none=True,
)
def get_profile_statistics(
    org_id: str = Depends(default_get_org_id),
) -> GetProfileStatisticsResponse:
    """Get efficient profile statistics using storage layer queries.

    Args:
        org_id (str): Organization ID

    Returns:
        GetProfileStatisticsResponse: Response containing profile counts by status
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Get profile statistics using Reflexio's method
    return reflexio.get_profile_statistics()


@core_router.post(
    "/api/run_playbook_aggregation",
    response_model=RunPlaybookAggregationResponse,
    response_model_exclude_none=True,
)
@limiter.limit("10/minute")  # Strict limit for expensive operations
def run_playbook_aggregation(
    request: Request,
    payload: RunPlaybookAggregationRequest,
    org_id: str = Depends(default_get_org_id),
) -> RunPlaybookAggregationResponse:
    return _run_limited_api(
        org_id,
        "aggregation",
        lambda: publisher_api.run_playbook_aggregation(org_id=org_id, request=payload),
    )


@core_router.post("/api/set_config")
def set_config(
    config: dict[str, Any],
    org_id: str = Depends(default_get_org_id),
) -> SetConfigResponse:
    """Set configuration for the organization.

    Args:
        config (Config): The configuration to set
        org_id (str): Organization ID

    Returns:
        dict: Response containing success status and message
    """
    # Create Reflexio instance to access the configurator through request_context
    reflexio = get_reflexio(org_id=org_id)

    # Set the config using Reflexio's set_config method
    response = reflexio.set_config(config)

    # Invalidate cache on successful config change to ensure fresh instance next request
    if response.success:
        invalidate_reflexio_cache(org_id=org_id)

    return response


@core_router.post("/api/update_config")
def update_config(
    partial: dict[str, Any],
    org_id: str = Depends(default_get_org_id),
) -> SetConfigResponse:
    """Apply a partial update to the org's config (PATCH semantics).

    Performs a **top-level shallow merge** of *partial* over the existing
    config and round-trips through ``Config(**merged)`` so Pydantic
    validates the result and rejects bogus top-level fields.

    .. warning::
       Nested objects (e.g. ``storage_config``, ``profile_extractor_config``,
       ``user_playbook_extractor_config``) are **replaced wholesale**.
       Deep merging is intentionally not supported -- the discriminator on
       ``storage_config`` would be lost on partial updates, and merging nested
       dicts has ambiguous semantics.

       To update a field inside an extractor config you must resend that
       extractor object fully populated (including ``extractor_name``,
       ``extraction_definition_prompt``, etc.). For one-off mutations prefer
       ``GET /api/get_config`` followed by ``POST /api/set_config`` with the
       modified full config.

    Unlike :func:`set_config`, callers do not need to re-send the full
    config (including required fields like ``storage_config``) just to
    flip a single top-level boolean. The merge happens server-side
    atomically within the request, eliminating the read-modify-write
    race a client would otherwise hit.

    Args:
        partial: Top-level fields to overlay on the existing config.
        org_id: Organization ID resolved by the auth layer.

    Returns:
        SetConfigResponse: Success status and message from
        :meth:`Reflexio.set_config`.
    """
    from pydantic import ValidationError

    reflexio = get_reflexio(org_id=org_id)
    existing = reflexio.request_context.configurator.get_config().model_dump(
        mode="python"
    )
    merged = {**existing, **partial}
    # Pydantic validates the merged shape and rejects unknown / malformed
    # fields here, before storage validation in reflexio.set_config.
    # Convert ValidationError into 422 so callers passing a partial that
    # would replace a nested extractor object with an incomplete dict (e.g.
    # {"user_playbook_extractor_config": {"aggregation_config": {...}}})
    # get a clean client-error response instead of a 500.
    try:
        merged_config = Config(**merged)
    except ValidationError as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
            detail={
                "error": "Invalid partial config (top-level shallow merge)",
                "hint": (
                    "Nested objects (e.g. user_playbook_extractor_config) "
                    "are replaced wholesale, not deep-merged. To mutate a "
                    "single nested field, fetch the full config via "
                    "/api/get_config, edit, and POST it back via "
                    "/api/set_config."
                ),
                "validation_errors": exc.errors(),
            },
        ) from exc
    response = reflexio.set_config(merged_config)
    if response.success:
        invalidate_reflexio_cache(org_id=org_id)
    return response


@core_router.post("/api/admin/cache/invalidate")
def admin_invalidate_cache(
    payload: AdminInvalidateCacheRequest,
    org_id: str = Depends(default_get_org_id),
) -> AdminInvalidateCacheResponse:
    """Explicitly evict the per-org Reflexio cache entry.

    Necessary when the running config has been mutated through a
    channel the server can't observe — e.g. another replica wrote to
    the shared DB, or an operator hand-edited a self-host config file
    on a backend that doesn't support cheap version probing. The
    file-mtime check (Phase 1) and DB version check (Phase 3) cover
    most cases automatically; this endpoint is the manual escape hatch.

    Auth uses the same dependency as ``/api/set_config`` — callers
    can only invalidate their own org's cache. If the request body
    supplies ``org_id`` it must match the dep-resolved value;
    cross-org invalidation is intentionally NOT exposed here.

    Args:
        payload: Optional ``org_id`` (verification only — must match
            the caller's authenticated org if provided).
        org_id: Organization ID resolved by the auth layer.

    Returns:
        AdminInvalidateCacheResponse: ``invalidated`` is True iff an
        entry was evicted (False is a successful no-op when nothing
        was cached).

    Raises:
        HTTPException: 403 when the body's ``org_id`` differs from the
            caller's authenticated org.
    """
    if payload.org_id is not None and payload.org_id != org_id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail=(
                "Cross-org cache invalidation is not supported; "
                "omit org_id or pass your own."
            ),
        )
    invalidated = invalidate_reflexio_cache(org_id=org_id)
    return AdminInvalidateCacheResponse(invalidated=invalidated, org_id=org_id)


@core_router.get("/api/get_config")
def get_config(
    org_id: str = Depends(default_get_org_id),
) -> dict[str, Any]:
    """Get configuration for the organization.

    Args:
        org_id (str): Organization ID

    Returns:
        Config: The current configuration
    """
    # Create Reflexio instance to access the configurator through request_context
    reflexio = get_reflexio(org_id=org_id)

    return reflexio.request_context.configurator.get_config_for_response()


@core_router.post(
    "/api/get_user_playbooks",
    response_model=GetUserPlaybooksViewResponse,
    response_model_exclude_none=True,
)
def get_user_playbooks(
    request: GetUserPlaybooksRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetUserPlaybooksViewResponse:
    """Get user playbooks with internal fields filtered out.

    Args:
        request (GetUserPlaybooksRequest): The get request
        org_id (str): Organization ID

    Returns:
        GetUserPlaybooksViewResponse: Response containing user playbooks without internal fields
    """
    reflexio = get_reflexio(org_id=org_id)
    response = reflexio.get_user_playbooks(request)
    return GetUserPlaybooksViewResponse(
        success=response.success,
        user_playbooks=[to_user_playbook_view(rf) for rf in response.user_playbooks],
        msg=response.msg,
    )


@core_router.post(
    "/api/get_agent_playbooks",
    response_model=GetAgentPlaybooksViewResponse,
    response_model_exclude_none=True,
)
def get_agent_playbooks(
    request: GetAgentPlaybooksRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetAgentPlaybooksViewResponse:
    """Get agent playbooks with internal fields filtered out.

    Args:
        request (GetAgentPlaybooksRequest): The get request
        org_id (str): Organization ID

    Returns:
        GetAgentPlaybooksViewResponse: Response containing agent playbooks without internal fields
    """
    reflexio = get_reflexio(org_id=org_id)
    response = reflexio.get_agent_playbooks(request)
    return GetAgentPlaybooksViewResponse(
        success=response.success,
        agent_playbooks=[to_agent_playbook_view(fb) for fb in response.agent_playbooks],
        msg=response.msg,
    )


@core_router.post(
    "/api/get_agent_success_evaluation_results",
    response_model=GetEvaluationResultsViewResponse,
    response_model_exclude_none=True,
)
def get_agent_success_evaluation_results(
    request: GetAgentSuccessEvaluationResultsRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetEvaluationResultsViewResponse:
    """Get agent success evaluation results.

    Args:
        request (GetAgentSuccessEvaluationResultsRequest): The get request
        org_id (str): Organization ID

    Returns:
        GetEvaluationResultsViewResponse: Response containing agent success evaluation results
    """
    reflexio = get_reflexio(org_id=org_id)
    response = reflexio.get_agent_success_evaluation_results(request)
    return GetEvaluationResultsViewResponse(
        success=response.success,
        agent_success_evaluation_results=[
            to_evaluation_result_view(r)
            for r in response.agent_success_evaluation_results
        ],
        msg=response.msg,
    )


@core_router.put(
    "/api/update_agent_playbook_status",
    response_model=UpdatePlaybookStatusResponse,
    response_model_exclude_none=True,
)
def update_agent_playbook_status_endpoint(
    request: UpdatePlaybookStatusRequest,
    org_id: str = Depends(default_get_org_id),
) -> UpdatePlaybookStatusResponse:
    """Update the status of a specific playbook.

    Args:
        request (UpdatePlaybookStatusRequest): The update request
        org_id (str): Organization ID

    Returns:
        UpdatePlaybookStatusResponse: Response containing success status and message
    """
    return publisher_api.update_agent_playbook_status(org_id=org_id, request=request)


@core_router.put(
    "/api/update_agent_playbook",
    response_model=UpdateAgentPlaybookResponse,
    response_model_exclude_none=True,
)
def update_agent_playbook_endpoint(
    request: UpdateAgentPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> UpdateAgentPlaybookResponse:
    """Update editable fields of a specific agent playbook.

    Args:
        request (UpdateAgentPlaybookRequest): The update request
        org_id (str): Organization ID

    Returns:
        UpdateAgentPlaybookResponse: Response containing success status and message
    """
    return publisher_api.update_agent_playbook(org_id=org_id, request=request)


@core_router.put(
    "/api/update_user_playbook",
    response_model=UpdateUserPlaybookResponse,
    response_model_exclude_none=True,
)
def update_user_playbook_endpoint(
    request: UpdateUserPlaybookRequest,
    org_id: str = Depends(default_get_org_id),
) -> UpdateUserPlaybookResponse:
    """Update editable fields of a specific user playbook.

    Args:
        request (UpdateUserPlaybookRequest): The update request
        org_id (str): Organization ID

    Returns:
        UpdateUserPlaybookResponse: Response containing success status and message
    """
    return publisher_api.update_user_playbook(org_id=org_id, request=request)


@core_router.put(
    "/api/update_user_profile",
    response_model=UpdateUserProfileResponse,
    response_model_exclude_none=True,
)
def update_user_profile_endpoint(
    request: UpdateUserProfileRequest,
    org_id: str = Depends(default_get_org_id),
) -> UpdateUserProfileResponse:
    """Apply a partial update to an existing user profile.

    Args:
        request (UpdateUserProfileRequest): The update request
        org_id (str): Organization ID

    Returns:
        UpdateUserProfileResponse: Response containing success status and message
    """
    return publisher_api.update_user_profile(org_id=org_id, request=request)


@core_router.post(
    "/api/get_dashboard_stats",
    response_model=GetDashboardStatsResponse,
    response_model_exclude_none=True,
)
def get_dashboard_stats(
    request: GetDashboardStatsRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetDashboardStatsResponse:
    """Get comprehensive dashboard statistics including counts and time-series data.

    Args:
        request (GetDashboardStatsRequest): Request containing days_back and granularity
        org_id (str): Organization ID

    Returns:
        GetDashboardStatsResponse: Response containing dashboard statistics
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Get dashboard stats using Reflexio's method
    return reflexio.get_dashboard_stats(request)


@core_router.post(
    "/api/get_playbook_application_stats",
    response_model=GetPlaybookApplicationStatsResponse,
    response_model_exclude_none=True,
)
def get_playbook_application_stats(
    request: GetPlaybookApplicationStatsRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetPlaybookApplicationStatsResponse:
    """Get per-rule citation counts aggregated from interactions.

    Returns one row per cited (kind, real_id) over the look-back window,
    sorted by applied_count descending. Lets the dashboard show users a
    per-rule "track record" — how often each playbook or profile has been
    applied and when it last fired.

    Args:
        request (GetPlaybookApplicationStatsRequest): Request containing
            days_back.
        org_id (str): Organization ID.

    Returns:
        GetPlaybookApplicationStatsResponse: Response containing aggregated
            stats.
    """
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.get_playbook_application_stats(request)


# ============================================================================
# Braintrust connector (Plan C-backend)
# ============================================================================


@core_router.post(
    "/api/braintrust/connect",
    response_model=ConnectBraintrustResponse,
    response_model_exclude_none=True,
)
@limiter.limit("10/minute")
def braintrust_connect(
    request: Request,
    payload: ConnectBraintrustRequest,
    org_id: str = Depends(default_get_org_id),
) -> ConnectBraintrustResponse:
    """Step 1: validate the Braintrust API key and list workspaces/projects.

    Persists nothing — call `/api/braintrust/select_projects` to commit.

    Args:
        request (Request): The HTTP request object for rate limiting.
        payload (ConnectBraintrustRequest): Customer's Braintrust API key.
        org_id (str): Resolved by auth dependency.

    Returns:
        ConnectBraintrustResponse: Workspaces tree on success; `success=False`
            with a message when the key is rejected.
    """
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.braintrust_connect(payload)


@core_router.post(
    "/api/braintrust/select_projects",
    response_model=SelectProjectsResponse,
    response_model_exclude_none=True,
)
@limiter.limit("10/minute")
def braintrust_select_projects(
    request: Request,
    payload: SelectProjectsRequest,
    org_id: str = Depends(default_get_org_id),
) -> SelectProjectsResponse:
    """Step 2: commit the Braintrust connection with selected projects.

    The API key is encrypted at rest. Subsequent syncs use the persisted
    connection until the customer calls DELETE /api/braintrust/connection.
    """
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.braintrust_select_projects(payload)


@core_router.get(
    "/api/braintrust/status",
    response_model=BraintrustStatusResponse,
    response_model_exclude_none=True,
)
def braintrust_status(
    org_id: str = Depends(default_get_org_id),
) -> BraintrustStatusResponse:
    """Return Braintrust connection state. Never echoes the API key."""
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.braintrust_status()


@core_router.delete("/api/braintrust/connection")
@limiter.limit("10/minute")
def braintrust_disconnect(
    request: Request,
    org_id: str = Depends(default_get_org_id),
) -> dict:
    """Delete the persisted Braintrust connection for the org.

    Args:
        org_id (str): Resolved by auth dependency.

    Returns:
        dict: ``{"success": True}`` on completion.
    """
    reflexio = get_reflexio(org_id=org_id)
    reflexio.braintrust_disconnect()
    return {"success": True}


@core_router.post(
    "/api/braintrust/sync",
    response_model=SyncBraintrustResponse,
    response_model_exclude_none=True,
)
@limiter.limit("10/minute")
def braintrust_sync(
    request: Request,
    org_id: str = Depends(default_get_org_id),
) -> SyncBraintrustResponse:
    """Trigger a one-shot sync of Braintrust scorer outputs.

    Scheduled (cron) sync is a follow-up; for now the endpoint exists so
    operators can drive a manual import.
    """
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.braintrust_sync()


@core_router.post(
    "/api/get_evaluation_overview",
    response_model=GetEvaluationOverviewResponse,
    response_model_exclude_none=True,
)
def get_evaluation_overview(
    request: GetEvaluationOverviewRequest,
    org_id: str = Depends(default_get_org_id),
) -> GetEvaluationOverviewResponse:
    """Return the redesigned /evaluations page payload.

    Aggregates hero state, four context tiles with deltas, top rule
    attribution, and a corrections-per-session distribution into a single
    response shaped exactly as the frontend renders it.

    Args:
        request (GetEvaluationOverviewRequest): Window + bucket granularity.
        org_id (str): Organization ID resolved by the auth dependency.

    Returns:
        GetEvaluationOverviewResponse: Full overview payload.
    """
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.get_evaluation_overview(request)


# ---------------------------------------------------------------------------
# /api/evaluations/regenerate — replay the LLM judge over a window
# ---------------------------------------------------------------------------


@core_router.post(
    "/api/evaluations/regenerate",
    response_model=RegenerateStartResponse,
    response_model_exclude_none=True,
)
def start_regenerate(
    payload: RegenerateRequest,
    org_id: str = Depends(default_get_org_id),
) -> RegenerateStartResponse:
    """Start a singleton regenerate job over a time window.

    Args:
        payload (RegenerateRequest): Window bounds plus optional legacy evaluator name.
        org_id (str): Organization ID resolved by the auth dependency.

    Returns:
        RegenerateStartResponse: ``job_id`` to poll/cancel and ``total``
            tuples queued.

    Raises:
        HTTPException: 409 when a regenerate for the same org is already
            running. 503 when storage is not configured.
    """
    reflexio = get_reflexio(org_id=org_id)
    storage = reflexio.request_context.storage
    if storage is None:
        raise HTTPException(status_code=503, detail="Storage not configured")
    descriptors = storage.get_session_ids_in_window(
        from_ts=payload.from_ts, to_ts=payload.to_ts
    )
    try:
        job = REGEN_JOBS.create(
            org_id=org_id,
            from_ts=payload.from_ts,
            to_ts=payload.to_ts,
            total=len(descriptors),
        )
    except RuntimeError as e:
        raise HTTPException(status_code=409, detail=str(e)) from e
    threading.Thread(
        target=run_regen,
        kwargs={
            "job": job,
            "request_context": reflexio.request_context,
            "llm_client": reflexio.llm_client,
        },
        daemon=True,
    ).start()
    return RegenerateStartResponse(job_id=job.job_id, total=job.total)


@core_router.get(
    "/api/evaluations/regenerate/{job_id}",
    response_model=RegenerateStatusResponse,
    response_model_exclude_none=True,
)
def get_regenerate_status(
    job_id: str,
    org_id: str = Depends(default_get_org_id),
) -> RegenerateStatusResponse:
    """Poll the status of a regenerate job.

    Args:
        job_id (str): Opaque handle returned by POST /api/evaluations/regenerate.
        org_id (str): Organization ID resolved by the auth dependency.

    Returns:
        RegenerateStatusResponse: Counters, status, and failure list.

    Raises:
        HTTPException: 404 when ``job_id`` is unknown or belongs to a
            different org.
    """
    job = REGEN_JOBS.get(job_id)
    if job is None or job.org_id != org_id:
        raise HTTPException(status_code=404, detail="Unknown job_id")
    return RegenerateStatusResponse(
        job_id=job.job_id,
        status=job.status,
        total=job.total,
        completed=job.completed,
        failed=job.failed,
        failures=[
            RegenerateFailure(session_id=f.session_id, reason=f.reason)
            for f in job.failures
        ],
        started_at=job.started_at,
        finished_at=job.finished_at,
        # F3 informational counters — surface sampler + concurrency facts
        # so the dashboard can render "n_sampled / total_candidates" and
        # the configured worker cap without a second round-trip.
        total_candidates=job.total_candidates,
        sampled_count=job.sampled_count,
        concurrency_limit=job.concurrency_limit,
    )


@core_router.delete("/api/evaluations/regenerate/{job_id}")
def cancel_regenerate(
    job_id: str,
    org_id: str = Depends(default_get_org_id),
) -> dict[str, str]:
    """Request cancellation of a running regenerate job.

    Sets the worker's cancel event; the worker checks the flag between
    sessions and transitions to ``"cancelled"`` on its next iteration.

    Args:
        job_id (str): Opaque handle returned by POST /api/evaluations/regenerate.
        org_id (str): Organization ID resolved by the auth dependency.

    Returns:
        dict[str, str]: ``{"status": "cancelled"}`` on successful flag set.

    Raises:
        HTTPException: 404 when ``job_id`` is unknown or belongs to a
            different org.
    """
    job = REGEN_JOBS.get(job_id)
    if job is None or job.org_id != org_id:
        raise HTTPException(status_code=404, detail="Unknown job_id")
    REGEN_JOBS.cancel(job_id)
    return {"status": "cancelled"}


# ---------------------------------------------------------------------------
# /api/evaluations/grade_on_demand — single-session click-through grading
# ---------------------------------------------------------------------------
#
# F3 sampling means most sessions in a regen window are NEVER graded —
# the sampler keeps cost predictable by capping each (day, group) stratum
# at ``Config.eval_sample_n_per_stratum``. Plan 3 (F1) surfaces a
# bounded list of sessions in the UI; when a customer clicks one that
# wasn't in the sampled subset, the frontend hits this endpoint to grade
# it on demand. The 24h cache prevents repeated clicks from triggering
# redundant LLM calls.

_GRADE_ON_DEMAND_CACHE_TTL_SECONDS = 24 * 60 * 60
_GRADE_ON_DEMAND_CACHE_KEY_PREFIX = "grade_on_demand"


def _grade_on_demand_cache_key(
    org_id: str, session_id: str, agent_version: str, evaluation_name: str
) -> str:
    """Build the operation_state key for the on-demand grading cache.

    The key embeds every active singleton dimension that could change the
    verdict: org_id (multi-tenant scope), session_id (the unit of work),
    agent_version (eval results are versioned), and evaluation_name (kept as a
    compatibility/readback discriminator for historical multi-evaluator rows).

    Args:
        org_id (str): Tenant identifier from the auth context.
        session_id (str): Target session.
        agent_version (str): Agent version filter.
        evaluation_name (str): Evaluator/result namespace to isolate cache rows.
    Returns:
        str: A namespaced key suitable for ``storage.upsert_operation_state``.
    """
    return (
        f"{_GRADE_ON_DEMAND_CACHE_KEY_PREFIX}::{org_id}::{session_id}"
        f"::{agent_version}::{evaluation_name}"
    )


def _read_grade_on_demand_cache(
    storage: Any, cache_key: str, *, now: int
) -> int | None:
    """Return the cached ``result_id`` if a valid entry exists, else None.

    Returns None on three conditions: no entry, malformed entry, or entry
    whose ``last_graded_at`` is older than the 24h TTL. Keeps the handler
    body focused on the happy path.

    Args:
        storage: The request's storage backend.
        cache_key (str): Key produced by ``_grade_on_demand_cache_key``.
        now (int): Current Unix-seconds wall-clock timestamp.

    Returns:
        int | None: Cached result_id when fresh, else None.
    """
    cached_state = storage.get_operation_state(cache_key)
    if not cached_state:
        return None
    state = cached_state.get("operation_state")
    if not isinstance(state, dict):
        return None
    last_graded_at = state.get("last_graded_at")
    if not isinstance(last_graded_at, int):
        return None
    if (now - last_graded_at) >= _GRADE_ON_DEMAND_CACHE_TTL_SECONDS:
        return None
    cached_result_id = state.get("result_id")
    return cached_result_id if isinstance(cached_result_id, int) else None


def _resolve_session_user_id(storage: Any, session_id: str) -> str | None:
    """Look up the user_id that owns a session_id without requiring it as input.

    Uses ``get_sessions(session_id=...)`` because it's the only storage
    method on ``BaseStorage`` that accepts session_id alone — every other
    request-fetcher requires a user_id paired with it. Returns None when
    the session has no requests, signalling NO_REQUESTS to the caller.

    Args:
        storage: The request's storage backend.
        session_id (str): The target session whose owner to resolve.

    Returns:
        str | None: The user_id of the earliest request in the session,
        or None when no requests exist.
    """
    sessions = storage.get_sessions(session_id=session_id, top_k=100)
    rows = sessions.get(session_id) or []
    if not rows:
        return None
    earliest = min(rows, key=lambda r: r.request.created_at)
    return earliest.request.user_id


def _find_fresh_result_id(
    storage: Any,
    *,
    session_id: str,
    agent_version: str,
    evaluation_name: str,
    previous_result_ids: set[int],
) -> int | None:
    """Locate the result_id written by the most-recent grade for this session.

    The runner writes rows but doesn't return the id. Reading back through
    ``get_agent_success_evaluation_results`` matches the pattern used by
    the regen worker's prior-row capture (group_evaluation_runner step 5).

    Args:
        storage: The request's storage backend.
        session_id (str): The graded session.
        agent_version (str): The version dimension.
        evaluation_name (str): Evaluator/result namespace to isolate readback.
        previous_result_ids (set[int]): Matching rows observed before grading.

    Returns:
        int | None: result_id of the latest matching row, or None if the
        runner wrote nothing.
    """
    rows = storage.get_agent_success_evaluation_results(
        limit=1000, agent_version=agent_version
    )
    matched = [
        r
        for r in rows
        if r.session_id == session_id
        and r.evaluation_name == evaluation_name
        and r.result_id not in previous_result_ids
    ]
    if not matched:
        return None
    latest = max(matched, key=lambda r: r.created_at)
    return latest.result_id


@core_router.post(
    "/api/evaluations/grade_on_demand",
    response_model=GradeOnDemandResponse,
    response_model_exclude_none=False,
)
def grade_on_demand(
    payload: GradeOnDemandRequest,
    org_id: str = Depends(default_get_org_id),
) -> GradeOnDemandResponse:
    """Grade a single session synchronously; serve cached results within 24h.

    Flow:
      1. Read the operation_state cache; if a fresh entry exists, return it
         with ``cached=True``.
      2. Resolve the session's user_id from storage (skip with ``NO_REQUESTS``
         when the session is unknown — surfaced as 200 + ``skipped_reason``
         so the frontend's bounded-list click-through can handle stale ids
         locally without polluting 5xx telemetry).
      3. Invoke ``run_group_evaluation(force_regenerate=True)`` so the
         "already evaluated" short-circuit doesn't suppress a customer's
         explicit click.
      4. Find the freshly-written result_id and persist it in the cache
         with ``last_graded_at`` so future calls within 24h short-circuit.

    Args:
        payload (GradeOnDemandRequest): Session + version plus optional legacy evaluator name.
        org_id (str): Tenant identifier resolved by the auth dependency.

    Returns:
        GradeOnDemandResponse: Echoes ``session_id`` and carries either
            a fresh ``result_id`` (``cached=False``), a cached one
            (``cached=True``), or a ``skipped_reason`` (NO_REQUESTS).

    Raises:
        HTTPException: 503 when storage is not configured.
    """
    reflexio = get_reflexio(org_id=org_id)
    storage = reflexio.request_context.storage
    if storage is None:
        raise HTTPException(status_code=503, detail="Storage not configured")

    evaluation_name = payload.evaluation_name or SINGLETON_AGENT_SUCCESS_EVALUATION_NAME
    cache_key = _grade_on_demand_cache_key(
        org_id,
        payload.session_id,
        payload.agent_version,
        evaluation_name,
    )
    now = int(datetime.now(UTC).timestamp())

    cached_result_id = _read_grade_on_demand_cache(storage, cache_key, now=now)
    if cached_result_id is not None:
        return GradeOnDemandResponse(
            session_id=payload.session_id,
            result_id=cached_result_id,
            cached=True,
            skipped_reason=None,
        )

    user_id = _resolve_session_user_id(storage, payload.session_id)
    if user_id is None:
        return GradeOnDemandResponse(
            session_id=payload.session_id,
            result_id=None,
            cached=False,
            skipped_reason="NO_REQUESTS",
        )

    previous_result_ids = {
        r.result_id
        for r in storage.get_agent_success_evaluation_results(
            limit=1000, agent_version=payload.agent_version
        )
        if r.session_id == payload.session_id and r.evaluation_name == evaluation_name
    }

    # Two operation_state rows are intentionally written for this session:
    #   1) `grade_on_demand::{org_id}::{session_id}::{agent_version}::{evaluation_name}`
    #      — our 24h cache, set below after the result_id is resolved.
    #   2) `agent_success_group_eval::{org_id}::{user_id}::{session_id}`
    #      — the runner's own "evaluated" marker, written by
    #      run_group_evaluation. Future background runs without
    #      force_regenerate will skip this session as a result.
    # The cache key namespaces are distinct so the two markers do not
    # interfere; the explicit force_regenerate=True here is what makes
    # an on-demand grade always do real work on a cache miss.
    run_group_evaluation(
        org_id=org_id,
        user_id=user_id,
        session_id=payload.session_id,
        agent_version=payload.agent_version,
        source=None,
        request_context=reflexio.request_context,
        llm_client=reflexio.llm_client,
        force_regenerate=True,
    )

    result_id = _find_fresh_result_id(
        storage,
        session_id=payload.session_id,
        agent_version=payload.agent_version,
        evaluation_name=evaluation_name,
        previous_result_ids=previous_result_ids,
    )

    storage.upsert_operation_state(
        cache_key,
        {"last_graded_at": now, "result_id": result_id},
    )

    return GradeOnDemandResponse(
        session_id=payload.session_id,
        result_id=result_id,
        cached=False,
        skipped_reason=None,
    )


# ---------------------------------------------------------------------------
# /api/evaluations/shadow_comparisons/recent — F1 drawer + Top 10 widget
# ---------------------------------------------------------------------------
#
# Powers two surfaces on /evaluations:
#   1. The drawer triggered from the per-turn comparison tile — shows the
#      N most recent verdicts so customers can spot-check the judge.
#   2. The "Top 10 disagreements" widget — fetches a wider pool and the
#      frontend filters to ``is_significantly_better=True`` losses to surface
#      actionable rule-correction candidates.
#
# Filtering is restricted to the org's currently pinned
# ``shadow_comparison_judge_prompt_version`` so verdicts from an older rubric
# never mix into the drawer. The 30-day lookback is a defensive cap that lets
# the storage layer use an index range scan instead of a full table read.

_RECENT_SHADOW_COMPARISONS_LOOKBACK_SECONDS = 30 * 24 * 60 * 60
_RECENT_SHADOW_COMPARISONS_MAX_LIMIT = 100


@core_router.get(
    "/api/evaluations/shadow_comparisons/recent",
    response_model=GetRecentShadowComparisonsResponse,
)
def get_recent_shadow_comparisons(
    limit: int = 10,
    org_id: str = Depends(default_get_org_id),
) -> GetRecentShadowComparisonsResponse:
    """Return the N most recent shadow comparison verdicts for the pinned rubric.

    Filters to the org's currently pinned
    ``Config.shadow_comparison_judge_prompt_version`` so verdicts produced
    under an older rubric do not mix into the drawer or the Top 10
    disagreements widget. Storage returns verdicts in ascending ``created_at``
    order; we reverse to "newest first" and cap at ``limit``.

    Args:
        limit (int): Max verdicts to return. Clamped to ``[1, 100]``.
            Default 10 — matches the size of the drawer and Top 10 widget.
        org_id (str): Tenant identifier resolved by the auth dependency.

    Returns:
        GetRecentShadowComparisonsResponse: Verdicts in newest-first order.
            Empty list when the backend does not support the
            ``shadow_comparison_verdicts`` storage feature, when no verdicts
            exist in the 30-day window, or when no verdicts match the pinned
            prompt version.

    Raises:
        HTTPException: 503 when storage is not configured.
    """
    clamped_limit = max(1, min(int(limit), _RECENT_SHADOW_COMPARISONS_MAX_LIMIT))
    reflexio = get_reflexio(org_id=org_id)
    storage = reflexio.request_context.storage
    if storage is None:
        raise HTTPException(status_code=503, detail="Storage not configured")

    config = reflexio.request_context.configurator.get_config()
    pinned_version = (
        config.shadow_comparison_judge_prompt_version
        if config is not None
        else "v1.0.0"
    )

    now = int(datetime.now(UTC).timestamp())
    try:
        verdicts = storage.get_shadow_comparison_verdicts(
            from_ts=now - _RECENT_SHADOW_COMPARISONS_LOOKBACK_SECONDS,
            to_ts=now,
            judge_prompt_version=pinned_version,
        )
    except NotImplementedError:
        # Backends that don't support shadow verdicts (e.g., Disk) should
        # quietly return empty rather than 5xx — the surface degrades to
        # "no data yet" in the UI.
        return GetRecentShadowComparisonsResponse(verdicts=[])

    # Storage contract returns ascending — flip to "newest first" and cap.
    newest_first = list(reversed(verdicts))[:clamped_limit]
    return GetRecentShadowComparisonsResponse(verdicts=newest_first)


@core_router.post(
    "/api/rerun_profile_generation",
    response_model=RerunProfileGenerationResponse,
    response_model_exclude_none=True,
)
@limiter.limit("5/minute")  # Strict limit for expensive operations
def rerun_profile_generation_endpoint(
    request: Request,
    payload: RerunProfileGenerationRequest,
    background_tasks: BackgroundTasks,
    org_id: str = Depends(default_get_org_id),
) -> RerunProfileGenerationResponse:
    """Rerun profile generation for a user with filtered interactions.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (RerunProfileGenerationRequest): Request containing user_id, time filters, and source
        background_tasks (BackgroundTasks): Background task runner
        org_id (str): Organization ID

    Returns:
        RerunProfileGenerationResponse: Response containing success status and profiles generated count
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Run the long-running task in the background to avoid proxy timeout
    # Client polls get_operation_status for progress
    background_tasks.add_task(reflexio.rerun_profile_generation, payload)

    return RerunProfileGenerationResponse(
        success=True, msg="Profile generation started"
    )


@core_router.post(
    "/api/manual_profile_generation",
    response_model=ManualProfileGenerationResponse,
    response_model_exclude_none=True,
)
@limiter.limit("5/minute")  # Strict limit for expensive operations
def manual_profile_generation_endpoint(
    request: Request,
    payload: ManualProfileGenerationRequest,
    org_id: str = Depends(default_get_org_id),
) -> ManualProfileGenerationResponse:
    """Manually trigger profile generation with window-sized interactions and CURRENT output.

    Runs with auto_run=False, which bypasses the regular stride/should_run
    gates. Only profile extraction is triggered. Each extractor uses its own
    window_size_override when present, falling back to the global window_size.
    Output is CURRENT profiles only.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (ManualProfileGenerationRequest): Request containing user_id, source, and extractor_names
        org_id (str): Organization ID

    Returns:
        ManualProfileGenerationResponse: Response containing success status and profiles generated count
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Call manual_profile_generation
    return reflexio.manual_profile_generation(payload)


@core_router.post(
    "/api/rerun_playbook_generation",
    response_model=RerunPlaybookGenerationResponse,
    response_model_exclude_none=True,
)
@limiter.limit("5/minute")  # Strict limit for expensive operations
def rerun_playbook_generation_endpoint(
    request: Request,
    payload: RerunPlaybookGenerationRequest,
    background_tasks: BackgroundTasks,
    org_id: str = Depends(default_get_org_id),
) -> RerunPlaybookGenerationResponse:
    """Rerun playbook generation with filtered interactions.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (RerunPlaybookGenerationRequest): Request containing agent_version, time filters, and optional playbook_name
        background_tasks (BackgroundTasks): Background task runner
        org_id (str): Organization ID

    Returns:
        RerunPlaybookGenerationResponse: Response containing success status and playbooks generated count
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Run the long-running task in the background to avoid proxy timeout
    # Client polls get_operation_status for progress
    background_tasks.add_task(reflexio.rerun_playbook_generation, payload)

    return RerunPlaybookGenerationResponse(
        success=True, msg="Playbook generation started"
    )


@core_router.post(
    "/api/manual_playbook_generation",
    response_model=ManualPlaybookGenerationResponse,
    response_model_exclude_none=True,
)
@limiter.limit("5/minute")  # Strict limit for expensive operations
def manual_playbook_generation_endpoint(
    request: Request,
    payload: ManualPlaybookGenerationRequest,
    org_id: str = Depends(default_get_org_id),
) -> ManualPlaybookGenerationResponse:
    """Manually trigger playbook generation with window-sized interactions and CURRENT output.

    Runs with auto_run=False, which bypasses the regular stride/should_run
    gates. Only playbook extraction is triggered. Each extractor uses its own
    window_size_override when present, falling back to the global window_size.
    Output is CURRENT playbooks only.

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (ManualPlaybookGenerationRequest): Request containing agent_version, source, and playbook_name
        org_id (str): Organization ID

    Returns:
        ManualPlaybookGenerationResponse: Response containing success status and playbooks generated count
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Call manual_playbook_generation
    return reflexio.manual_playbook_generation(payload)


@core_router.post(
    "/api/upgrade_all_profiles",
    response_model=UpgradeProfilesResponse,
    response_model_exclude_none=True,
)
def upgrade_all_profiles_endpoint(
    request: UpgradeProfilesRequest,
    org_id: str = Depends(default_get_org_id),
) -> UpgradeProfilesResponse:
    """Upgrade all profiles by deleting old ARCHIVED, archiving CURRENT, and promoting PENDING.

    This operation performs three atomic steps:
    1. Delete all ARCHIVED profiles (old archived profiles from previous upgrades)
    2. Archive all CURRENT profiles → ARCHIVED (save current state for potential rollback)
    3. Promote all PENDING profiles → CURRENT (activate new profiles)

    Args:
        request (UpgradeProfilesRequest): The upgrade request with only_affected_users parameter
        org_id (str): Organization ID

    Returns:
        UpgradeProfilesResponse: Response containing success status and counts
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Call upgrade_all_profiles with request
    return reflexio.upgrade_all_profiles(request=request)


@core_router.post(
    "/api/downgrade_all_profiles",
    response_model=DowngradeProfilesResponse,
    response_model_exclude_none=True,
)
def downgrade_all_profiles_endpoint(
    request: DowngradeProfilesRequest,
    org_id: str = Depends(default_get_org_id),
) -> DowngradeProfilesResponse:
    """Downgrade all profiles by demoting CURRENT to PENDING and restoring ARCHIVED.

    This operation performs two atomic steps:
    1. Demote all CURRENT profiles → PENDING
    2. Restore all ARCHIVED profiles → CURRENT

    Args:
        request (DowngradeProfilesRequest): The downgrade request with only_affected_users parameter
        org_id (str): Organization ID

    Returns:
        DowngradeProfilesResponse: Response containing success status and counts
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Call downgrade_all_profiles with request
    return reflexio.downgrade_all_profiles(request=request)


@core_router.post(
    "/api/upgrade_all_user_playbooks",
    response_model=UpgradeUserPlaybooksResponse,
    response_model_exclude_none=True,
)
def upgrade_all_user_playbooks_endpoint(
    request: UpgradeUserPlaybooksRequest,
    org_id: str = Depends(default_get_org_id),
) -> UpgradeUserPlaybooksResponse:
    """Upgrade all user playbooks by deleting old ARCHIVED, archiving CURRENT, and promoting PENDING.

    This operation performs three atomic steps:
    1. Delete all ARCHIVED user playbooks (old archived from previous upgrades)
    2. Archive all CURRENT user playbooks → ARCHIVED (save current state for potential rollback)
    3. Promote all PENDING user playbooks → CURRENT (activate new user playbooks)

    Args:
        request (UpgradeUserPlaybooksRequest): The upgrade request with optional agent_version and playbook_name filters
        org_id (str): Organization ID

    Returns:
        UpgradeUserPlaybooksResponse: Response containing success status and counts
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Call upgrade_all_user_playbooks with request
    return reflexio.upgrade_all_user_playbooks(request=request)


@core_router.post(
    "/api/downgrade_all_user_playbooks",
    response_model=DowngradeUserPlaybooksResponse,
    response_model_exclude_none=True,
)
def downgrade_all_user_playbooks_endpoint(
    request: DowngradeUserPlaybooksRequest,
    org_id: str = Depends(default_get_org_id),
) -> DowngradeUserPlaybooksResponse:
    """Downgrade all user playbooks by archiving CURRENT and restoring ARCHIVED.

    This operation performs three atomic steps:
    1. Mark all CURRENT user playbooks → ARCHIVE_IN_PROGRESS (temporary status)
    2. Restore all ARCHIVED user playbooks → CURRENT
    3. Move all ARCHIVE_IN_PROGRESS user playbooks → ARCHIVED

    Args:
        request (DowngradeUserPlaybooksRequest): The downgrade request with optional agent_version and playbook_name filters
        org_id (str): Organization ID

    Returns:
        DowngradeUserPlaybooksResponse: Response containing success status and counts
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Call downgrade_all_user_playbooks with request
    return reflexio.downgrade_all_user_playbooks(request=request)


@core_router.get(
    "/api/get_operation_status",
    response_model=GetOperationStatusResponse,
    response_model_exclude_none=True,
)
def get_operation_status_endpoint(
    service_name: str = "profile_generation",
    org_id: str = Depends(default_get_org_id),
) -> GetOperationStatusResponse:
    """Get the status of an operation (e.g., profile generation rerun or manual).

    Args:
        service_name (str): The service name to query. Defaults to "profile_generation"
        org_id (str): Organization ID

    Returns:
        GetOperationStatusResponse: Response containing operation status info
    """
    # Create Reflexio instance
    reflexio = get_reflexio(org_id=org_id)

    # Get operation status
    request = GetOperationStatusRequest(service_name=service_name)
    return reflexio.get_operation_status(request)


@core_router.post(
    "/api/cancel_operation",
    response_model=CancelOperationResponse,
    response_model_exclude_none=True,
)
@limiter.limit("10/minute")
def cancel_operation_endpoint(
    request: Request,
    payload: CancelOperationRequest,
    org_id: str = Depends(default_get_org_id),
) -> CancelOperationResponse:
    """Cancel an in-progress operation (rerun or manual generation).

    Args:
        request (Request): The HTTP request object (for rate limiting)
        payload (CancelOperationRequest): Request containing optional service_name
        org_id (str): Organization ID

    Returns:
        CancelOperationResponse: Response with list of services that were cancelled
    """
    reflexio = get_reflexio(org_id=org_id)
    return reflexio.cancel_operation(payload)


# Paths that should remain publicly accessible (no lock icon in Swagger)
_PUBLIC_PATHS = frozenset(
    {"/", "/health", "/meta/version", "/token", "/docs", "/openapi.json"}
)
_PUBLIC_PATH_PREFIXES = ("/api/register", "/api/registration-config", "/api/auth/")


def _add_openapi_security(app: FastAPI) -> None:
    """Inject Bearer auth security scheme into the OpenAPI spec.

    Overrides the default openapi() method to add a global HTTPBearer security
    requirement while exempting public endpoints (login, register, health, etc.).
    """
    original_openapi = app.openapi

    def custom_openapi() -> dict:  # type: ignore[type-arg]
        if app.openapi_schema:
            return app.openapi_schema

        schema = original_openapi()

        # Add security scheme
        schema.setdefault("components", {}).setdefault("securitySchemes", {})
        schema["components"]["securitySchemes"]["BearerAuth"] = {
            "type": "http",
            "scheme": "bearer",
            "description": "API key or JWT token. Pass as: Authorization: Bearer <token>",
        }

        # Apply security globally, then remove from public endpoints
        for path, methods in schema.get("paths", {}).items():
            is_public = path in _PUBLIC_PATHS or any(
                path.startswith(prefix) for prefix in _PUBLIC_PATH_PREFIXES
            )
            for method_detail in methods.values():
                if isinstance(method_detail, dict):
                    if is_public:
                        method_detail["security"] = []
                    else:
                        method_detail.setdefault("security", [{"BearerAuth": []}])

        app.openapi_schema = schema
        return schema

    app.openapi = custom_openapi  # type: ignore[method-assign]


def create_app(
    get_org_id: Callable[..., str] | None = None,
    additional_routers: list[APIRouter] | None = None,
    middleware_config: dict | None = None,
    require_auth: bool = False,
) -> FastAPI:
    """Factory to create a FastAPI app.

    Args:
        get_org_id: Custom dependency for resolving org_id (e.g., from JWT auth).
            When provided, overrides the default_get_org_id dependency globally.
        additional_routers: Extra APIRouter instances (e.g., enterprise login/oauth).
        middleware_config: Optional middleware overrides (not used yet, reserved for future).
        require_auth: When True, declares a Bearer security scheme in the OpenAPI spec
            so Swagger UI shows lock icons and the Authorize button works.

    Returns:
        Configured FastAPI application.
    """
    from collections.abc import AsyncIterator
    from contextlib import asynccontextmanager

    from reflexio.server._auth import default_get_org_id
    from reflexio.server.api_endpoints.request_context import RequestContext
    from reflexio.server.llm.model_defaults import validate_llm_availability
    from reflexio.server.services.extraction.resume_scheduler import (
        maybe_start_resume_scheduler,
    )

    def _lifespan_org_id() -> str:
        if get_org_id is None:
            return default_get_org_id()
        try:
            signature = inspect.signature(get_org_id)
        except (TypeError, ValueError):
            return default_get_org_id()
        if signature.parameters:
            return default_get_org_id()
        try:
            return str(get_org_id())
        except Exception:
            logger.exception("Failed to resolve lifespan org_id; using default org")
            return default_get_org_id()

    @asynccontextmanager
    async def lifespan(app: FastAPI) -> AsyncIterator[None]:  # noqa: ARG001
        validate_llm_availability()
        bootstrap_org_id = _lifespan_org_id()
        bootstrap_context = RequestContext(org_id=bootstrap_org_id)
        retrieval_floor = bootstrap_context.configurator.get_config().retrieval_floor
        if retrieval_floor.enabled:
            from reflexio.server.llm.rerank import prewarm as _prewarm_cross_encoder

            _prewarm_cross_encoder()
        else:
            logger.info(
                "Cross-encoder pre-warm skipped because retrieval_floor.enabled=false"
            )
        # The scheduler discovers every org with resumable work each tick and
        # drives a per-org worker with org-scoped claims, so it is not limited
        # to the bootstrap org. The bootstrap org is only used to read config
        # and to seed cross-org discovery.
        scheduler = maybe_start_resume_scheduler(
            lambda org_id: RequestContext(org_id=org_id),
            bootstrap_org_id=bootstrap_org_id,
        )
        try:
            yield
        finally:
            if scheduler is not None:
                scheduler.stop()

    app = FastAPI(docs_url="/docs", lifespan=lifespan)

    if require_auth:
        _add_openapi_security(app)

    @app.get("/meta/version")
    def get_version_info() -> dict[str, str]:
        from importlib.metadata import PackageNotFoundError, version

        try:
            server_version = version("reflexio")
        except PackageNotFoundError:
            server_version = "0.0.0-dev"
        return {
            "server_version": server_version,
            "api_version": "v1",
            "min_client_version": "0.1.0",
        }

    # Configure rate limiter
    app.state.limiter = limiter
    app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)  # type: ignore[reportArgumentType]

    # CORS
    origins = ["*"]
    app.add_middleware(
        CORSMiddleware,
        allow_origins=origins,
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )

    # Timeout middleware
    app.add_middleware(TimeoutMiddleware)

    # Bot protection
    app.add_middleware(BotProtectionMiddleware)

    # Correlation ID — added last so it runs outermost (Starlette reverses order)
    app.add_middleware(CorrelationIdMiddleware)

    # Override get_org_id dependency if custom one provided
    if get_org_id is not None:
        app.dependency_overrides[default_get_org_id] = get_org_id

    # When a custom get_org_id is provided together with require_auth,
    # auth is enforced on every route — mark this app instance so the
    # token-gated my_config endpoint becomes reachable. Using
    # ``app.state`` instead of a module-level global keeps the gate
    # scoped to this FastAPI instance, so multiple apps (e.g. tests,
    # multi-tenant embeddings) can coexist without leaking state.
    app.state.my_config_enabled = bool(get_org_id is not None and require_auth)

    # Include core routes
    app.include_router(core_router)

    # Include stall_state routes
    app.include_router(stall_state_api.router)

    # Include pending tool call routes
    app.include_router(pending_tool_call_api.router)

    # Include additional routers
    for router in additional_routers or []:
        app.include_router(router)

    # Health/observability endpoint (per-worker metrics for recycling)
    health_api.install(app)

    return app


# Default standalone app (no auth)
app = create_app()
