# 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_list",
method="GET",
path="/tools/deepsearch/list",
summary="List the user's past DeepSearch sessions",
description=(
"Returns the signed-in user's deep research session history, newest first, each "
"with its uid, query, status and created_at."
),
params=(),
requires_auth=True,
),
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=True,
),
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=True,
),
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=True,
),
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 analysis history, newest first, each with its grade, "
"category, status and report_url."
),
params=(),
requires_auth=True,
),
)
Reference in New Issue View Git Blame Copy Permalink