# retoor <retoor@molodetz.nl>

from __future__ import annotations

from ..spec import Action
from ._shared import body, path


TOOLS_ACTIONS: tuple[Action, ...] = (
    Action(
        name="seo_diagnostics",
        method="POST",
        path="/tools/seo/run",
        summary="Run an SEO audit on a URL or sitemap",
        description=(
            "Queues a background SEO diagnostics job and returns {uid, status_url}. Poll the "
            "status_url with seo_status until status is 'done', then share the score, grade and "
            "report_url. mode='url' audits a single page; mode='sitemap' crawls up to max_pages."
        ),
        params=(
            body("url", "The page URL or sitemap.xml URL to audit.", required=True),
            body("mode", "'url' for a single page or 'sitemap' to crawl a sitemap."),
            body("max_pages", "Maximum pages to crawl in sitemap mode (1-50)."),
        ),
        requires_auth=False,
    ),
    Action(
        name="seo_status",
        method="GET",
        path="/tools/seo/{uid}",
        summary="Check an SEO audit and obtain its score once finished",
        description=(
            "Returns the audit status. When status is 'done', score, grade and report_url are "
            "populated; while 'pending' or 'running', poll again shortly."
        ),
        params=(path("uid", "SEO job uid returned by seo_diagnostics."),),
        requires_auth=False,
    ),
    Action(
        name="seo_report",
        method="GET",
        path="/tools/seo/{uid}/report",
        summary="Read a finished SEO audit report",
        description=(
            "Returns the full audit for a finished SEO job: overall score and grade, per-category "
            "scores, per-check results, per-page details, and site-wide checks. Use it after "
            "seo_status reports status 'done' to explain what passed, what failed, and how to improve."
        ),
        params=(path("uid", "SEO job uid returned by seo_diagnostics."),),
        requires_auth=False,
    ),
    Action(
        name="seo_meta_status",
        method="GET",
        path="/tools/seo-meta/{target_type}/{target_uid}",
        summary="Read the SEO metadata generated for a content item",
        description=(
            "Returns the clean SEO title, description and keywords for a published content "
            "item. target_type is one of post, project, gist, news or issue and target_uid "
            "is its uid (or issue number). When the AI value is not ready yet a plain-content "
            "default is returned with status 'pending'."
        ),
        params=(
            path("target_type", "One of post, project, gist, news or issue."),
            path("target_uid", "The content uid (or issue number)."),
        ),
        requires_auth=False,
    ),
    Action(
        name="deepsearch",
        method="POST",
        path="/tools/deepsearch/run",
        summary="Start a deep multi-agent web research job",
        description=(
            "Queues a background DeepSearch job and returns {uid, status_url}. Poll the "
            "status_url with deepsearch_status until status is 'done', then share the "
            "score, confidence and session_url. depth (1-4) and max_pages (1-30) control "
            "how widely it crawls."
        ),
        params=(
            body("query", "The research question to investigate.", required=True),
            body("depth", "Research depth 1-4 (default 2)."),
            body("max_pages", "Maximum sources to crawl 1-30 (default 12)."),
        ),
        requires_auth=False,
    ),
    Action(
        name="deepsearch_status",
        method="GET",
        path="/tools/deepsearch/{uid}",
        summary="Check a DeepSearch job and obtain its metrics once finished",
        description=(
            "Returns the research status. When status is 'done', score, confidence, "
            "source_diversity and session_url are populated; otherwise poll again shortly."
        ),
        params=(path("uid", "DeepSearch job uid returned by deepsearch."),),
        requires_auth=False,
    ),
    Action(
        name="deepsearch_session",
        method="GET",
        path="/tools/deepsearch/{uid}/session",
        summary="Read a finished DeepSearch report",
        description=(
            "Returns the full cited report for a finished DeepSearch: summary, findings, "
            "gaps, sources and metrics."
        ),
        params=(path("uid", "DeepSearch job uid returned by deepsearch."),),
        requires_auth=False,
    ),
    Action(
        name="deepsearch_pause",
        method="POST",
        path="/tools/deepsearch/{uid}/pause",
        summary="Pause a running DeepSearch job",
        params=(path("uid", "DeepSearch job uid returned by deepsearch."),),
        requires_auth=False,
    ),
    Action(
        name="deepsearch_resume",
        method="POST",
        path="/tools/deepsearch/{uid}/resume",
        summary="Resume a paused DeepSearch job",
        params=(path("uid", "DeepSearch job uid returned by deepsearch."),),
        requires_auth=False,
    ),
    Action(
        name="deepsearch_cancel",
        method="POST",
        path="/tools/deepsearch/{uid}/cancel",
        summary="Cancel a running or paused DeepSearch job",
        params=(path("uid", "DeepSearch job uid returned by deepsearch."),),
        requires_auth=False,
    ),
    Action(
        name="isslop",
        method="POST",
        path="/tools/isslop/run",
        summary="Classify a repository or website as AI slop or human work",
        description=(
            "Queues a background AI Usage Analyzer job and returns {uid, status_url, report_url}. "
            "Poll the status with isslop_status until status is 'completed', then share the "
            "authenticity grade, category, human/AI split and report_url. Accepts http(s), "
            "git and ssh source URLs."
        ),
        params=(
            body("url", "Repository or website URL to classify.", required=True),
        ),
        requires_auth=False,
    ),
    Action(
        name="isslop_status",
        method="GET",
        path="/tools/isslop/{uid}",
        summary="Check a AI usage analysis and obtain its verdict once finished",
        description=(
            "Returns the analysis status. When status is 'completed', grade, category, "
            "human_percent, ai_percent and report_url are populated; while 'pending' or "
            "'running', poll again shortly."
        ),
        params=(path("uid", "Analysis uid returned by isslop."),),
        requires_auth=False,
    ),
    Action(
        name="isslop_report",
        method="GET",
        path="/tools/isslop/{uid}/report",
        summary="Read a finished AI usage analysis report",
        description=(
            "Returns the full report for a finished analysis: authenticity grade, human/AI "
            "split, markdown findings, per-file scores with signals, the image review and the "
            "embeddable badge snippets. Use it after isslop_status reports status 'completed'."
        ),
        params=(path("uid", "Analysis uid returned by isslop."),),
        requires_auth=False,
    ),
    Action(
        name="isslop_list",
        method="GET",
        path="/tools/isslop/list",
        summary="List the user's AI usage analyses",
        description=(
            "Returns the signed-in user's (or guest's) analysis history, newest first, each "
            "with its grade, category, status and report_url."
        ),
        params=(),
        requires_auth=False,
    ),
)
