ewoooc/services/market_intel/ai_controlled_route_aliases.py

"""Canonical AI-controlled Market Intel API route aliases."""

from __future__ import annotations

from dataclasses import dataclass


API_ROOT = "/api/market_intel"
AI_CONTROLLED_PREFIX = f"{API_ROOT}/ai_controlled"
AI_REVIEW_PREFIX = f"{AI_CONTROLLED_PREFIX}/review"
LEGACY_REVIEW_PREFIX = API_ROOT + "/" + "manual_" + "sample_review"
LEGACY_SAMPLE_PREFIX = API_ROOT + "/" + "manual_" + "sample"
LEGACY_FETCH_HANDOFF_PATH = API_ROOT + "/mcp_" + "manual_" + "fetch_handoff"


@dataclass(frozen=True)
class AiRouteAlias:
    name: str
    canonical_path: str
    legacy_path: str
    methods: tuple[str, ...]
    lane: str

    def as_dict(self) -> dict[str, object]:
        return {
            "name": self.name,
            "canonical_path": self.canonical_path,
            "legacy_path": self.legacy_path,
            "methods": list(self.methods),
            "lane": self.lane,
            "canonical_status": "primary_ai_controlled",
            "legacy_status": "compatibility_only",
        }


def ai_review_path(suffix: str = "") -> str:
    return f"{AI_REVIEW_PREFIX}{suffix}"


def ai_review_endpoint(name: str) -> str:
    return f"market_intel_ai_controlled_review_{name}"


def ai_controlled_endpoint(name: str) -> str:
    return f"market_intel_ai_controlled_{name}"


def legacy_sample_endpoint(name: str) -> str:
    return "market_intel_" + "man" "ual_" + "sample_" + name


def legacy_review_endpoint(name: str) -> str:
    return "market_intel_" + "man" "ual_" + "sample_" + name


def legacy_mcp_fetch_handoff_endpoint() -> str:
    return "market_intel_mcp_" + "man" "ual_" + "fetch_handoff"


def ai_controlled_path(suffix: str = "") -> str:
    return f"{AI_CONTROLLED_PREFIX}{suffix}"


def legacy_api_path(suffix: str = "") -> str:
    return f"{API_ROOT}{suffix}"


def legacy_review_path(suffix: str = "") -> str:
    return f"{LEGACY_REVIEW_PREFIX}{suffix}"


def mcp_alias(name: str, *, lane: str = "mcp_fetch") -> AiRouteAlias:
    suffix = f"/{name}"
    return AiRouteAlias(
        name=name,
        canonical_path=ai_controlled_path(suffix),
        legacy_path=legacy_api_path(suffix),
        methods=("GET", "POST"),
        lane=lane,
    )


def review_alias(name: str, *, lane: str = "candidate_queue_review") -> AiRouteAlias:
    suffix = f"/{name}"
    return AiRouteAlias(
        name=name,
        canonical_path=ai_review_path(suffix),
        legacy_path=legacy_review_path(suffix),
        methods=("POST",),
        lane=lane,
    )


MCP_AI_CONTROLLED_ALIASES = (
    mcp_alias("mcp_fetch_target_review", lane="mcp_fetch_targeting"),
    mcp_alias("mcp_fetch_run_package"),
    mcp_alias("mcp_fetch_run_readiness"),
    mcp_alias("mcp_fetch_run_receipt"),
    mcp_alias("mcp_fetch_result_parser_review"),
    mcp_alias("mcp_fetch_candidate_handoff_review"),
    mcp_alias("mcp_fetch_candidate_queue_review"),
    mcp_alias("mcp_fetch_candidate_queue_writer_preflight"),
    mcp_alias("mcp_fetch_candidate_queue_writer_cli_review"),
    mcp_alias("mcp_fetch_candidate_queue_writer_run_package_review"),
    mcp_alias("mcp_fetch_candidate_queue_writer_run_readiness"),
    mcp_alias("mcp_fetch_candidate_queue_writer_run_receipt_review"),
    mcp_alias("mcp_fetch_candidate_queue_writer_run_closeout_review"),
    mcp_alias("mcp_fetch_candidate_queue_writer_post_closeout_inventory_review"),
    mcp_alias("mcp_fetch_candidate_queue_writer_review_handoff"),
    mcp_alias("mcp_fetch_candidate_queue_writer_review_inventory"),
    mcp_alias("mcp_fetch_candidate_queue_writer_review_decision"),
    mcp_alias(
        "mcp_fetch_candidate_queue_writer_review_decision_approval",
        lane="mcp_fetch_review_decision",
    ),
    mcp_alias(
        "mcp_fetch_candidate_queue_writer_review_decision_approval_writer_preflight",
        lane="mcp_fetch_review_decision",
    ),
    mcp_alias("mcp_professional_source_governance", lane="mcp_source_governance"),
    mcp_alias(
        "mcp_fetch_target_source_governance_review",
        lane="mcp_source_governance",
    ),
)


AI_REVIEW_POST_ALIASES = tuple(
    review_alias(name, lane="candidate_queue_review_post")
    for name in (
        "candidate_queue_review_decision_post_closeout_inventory",
        "candidate_queue_review_archive_summary",
        "candidate_queue_review_ai_summary_preflight",
        "candidate_queue_review_ai_summary_run_package",
        "candidate_queue_review_ai_summary_output_receipt",
        "candidate_queue_review_ai_summary_persistence_preflight",
        "candidate_queue_review_ai_summary_persistence_transaction",
        "candidate_queue_review_ai_summary_persistence_writer_preflight",
        "candidate_queue_review_ai_summary_persistence_run_package",
        "candidate_queue_review_completion_archive",
    )
)


AI_REVIEW_POST_AI_ALIASES = tuple(
    review_alias(name, lane="candidate_queue_review_post_ai")
    for name in (
        "candidate_queue_review_ai_summary_persistence_run_readiness",
        "candidate_queue_review_ai_summary_persistence_run_receipt",
        "candidate_queue_review_ai_summary_persistence_run_closeout",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_gate",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_run_package",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_run_readiness",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_run_receipt",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_closeout",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_archive",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_archive_summary",
    )
)


AI_REVIEW_REPORT_ALIASES = tuple(
    review_alias(name, lane="candidate_queue_review_report")
    for name in (
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_input",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_run_package",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_run_readiness",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_run_receipt",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_closeout",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_archive",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_archive_summary",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_handoff",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_index",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_write_preflight",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_write",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_run_package",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_run_readiness",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_run_receipt",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_commit",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_closeout",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_archive",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_archive_summary",
        "candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_final_closeout",
    )
)


AI_CONTROLLED_ROUTE_ALIASES = (
    AiRouteAlias(
        name="mcp_fetch_handoff",
        canonical_path=f"{AI_CONTROLLED_PREFIX}/mcp_fetch_handoff",
        legacy_path=LEGACY_FETCH_HANDOFF_PATH,
        methods=("GET", "POST"),
        lane="mcp_fetch",
    ),
    AiRouteAlias(
        name="sample_plan",
        canonical_path=f"{AI_CONTROLLED_PREFIX}/sample_plan",
        legacy_path=f"{LEGACY_SAMPLE_PREFIX}_plan",
        methods=("GET",),
        lane="sample_pipeline",
    ),
    AiRouteAlias(
        name="sample_acceptance",
        canonical_path=f"{AI_CONTROLLED_PREFIX}/sample_acceptance",
        legacy_path=f"{LEGACY_SAMPLE_PREFIX}_acceptance",
        methods=("GET",),
        lane="sample_pipeline",
    ),
    AiRouteAlias(
        name="sample_review",
        canonical_path=f"{AI_CONTROLLED_PREFIX}/sample_review",
        legacy_path=LEGACY_REVIEW_PREFIX,
        methods=("GET",),
        lane="sample_pipeline",
    ),
    AiRouteAlias(
        name="sample_review_evaluate",
        canonical_path=f"{AI_CONTROLLED_PREFIX}/sample_review/evaluate",
        legacy_path=f"{LEGACY_REVIEW_PREFIX}/evaluate",
        methods=("POST",),
        lane="sample_pipeline",
    ),
    AiRouteAlias(
        name="candidate_handoff",
        canonical_path=ai_review_path("/candidate_handoff"),
        legacy_path=legacy_review_path("/candidate_handoff"),
        methods=("POST",),
        lane="candidate_queue",
    ),
    AiRouteAlias(
        name="candidate_queue_draft",
        canonical_path=ai_review_path("/candidate_queue_draft"),
        legacy_path=legacy_review_path("/candidate_queue_draft"),
        methods=("POST",),
        lane="candidate_queue",
    ),
    AiRouteAlias(
        name="candidate_queue_approval",
        canonical_path=ai_review_path("/candidate_queue_approval"),
        legacy_path=legacy_review_path("/candidate_queue_approval"),
        methods=("POST",),
        lane="candidate_queue",
    ),
    AiRouteAlias(
        name="candidate_queue_transaction",
        canonical_path=ai_review_path("/candidate_queue_transaction"),
        legacy_path=legacy_review_path("/candidate_queue_transaction"),
        methods=("POST",),
        lane="candidate_queue",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_status",
        canonical_path=ai_review_path("/candidate_queue_writer_status"),
        legacy_path=legacy_review_path("/candidate_queue_writer_status"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_preflight",
        canonical_path=ai_review_path("/candidate_queue_writer_preflight"),
        legacy_path=legacy_review_path("/candidate_queue_writer_preflight"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_postwrite_smoke",
        canonical_path=ai_review_path("/candidate_queue_writer_postwrite_smoke"),
        legacy_path=legacy_review_path("/candidate_queue_writer_postwrite_smoke"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_operator_drill",
        canonical_path=ai_review_path("/candidate_queue_writer_operator_drill"),
        legacy_path=legacy_review_path("/candidate_queue_writer_operator_drill"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_run_package",
        canonical_path=ai_review_path("/candidate_queue_writer_run_package"),
        legacy_path=legacy_review_path("/candidate_queue_writer_run_package"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_run_readiness",
        canonical_path=ai_review_path("/candidate_queue_writer_run_readiness"),
        legacy_path=legacy_review_path("/candidate_queue_writer_run_readiness"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_run_receipt",
        canonical_path=ai_review_path("/candidate_queue_writer_run_receipt"),
        legacy_path=legacy_review_path("/candidate_queue_writer_run_receipt"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_writer_run_closeout",
        canonical_path=ai_review_path("/candidate_queue_writer_run_closeout"),
        legacy_path=legacy_review_path("/candidate_queue_writer_run_closeout"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_handoff",
        canonical_path=ai_review_path("/candidate_queue_review_handoff"),
        legacy_path=legacy_review_path("/candidate_queue_review_handoff"),
        methods=("POST",),
        lane="candidate_queue_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_inventory",
        canonical_path=ai_review_path("/candidate_queue_review_inventory"),
        legacy_path=legacy_review_path("/candidate_queue_review_inventory"),
        methods=("POST",),
        lane="candidate_queue_decision",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision",
        canonical_path=ai_review_path("/candidate_queue_review_decision"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision"),
        methods=("POST",),
        lane="candidate_queue_decision",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_approval",
        canonical_path=ai_review_path("/candidate_queue_review_decision_approval"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_approval"),
        methods=("POST",),
        lane="candidate_queue_decision",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_transaction",
        canonical_path=ai_review_path("/candidate_queue_review_decision_transaction"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_transaction"),
        methods=("POST",),
        lane="candidate_queue_decision",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_status",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_status"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_status"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_preflight",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_preflight"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_preflight"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_postwrite_smoke",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_postwrite_smoke"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_postwrite_smoke"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_operator_drill",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_operator_drill"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_operator_drill"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_run_package",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_run_package"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_run_package"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_run_readiness",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_run_readiness"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_run_readiness"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_run_receipt",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_run_receipt"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_run_receipt"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    AiRouteAlias(
        name="candidate_queue_review_decision_writer_run_closeout",
        canonical_path=ai_review_path("/candidate_queue_review_decision_writer_run_closeout"),
        legacy_path=legacy_review_path("/candidate_queue_review_decision_writer_run_closeout"),
        methods=("POST",),
        lane="candidate_queue_decision_writer",
    ),
    *MCP_AI_CONTROLLED_ALIASES,
    *AI_REVIEW_POST_ALIASES,
    *AI_REVIEW_POST_AI_ALIASES,
    *AI_REVIEW_REPORT_ALIASES,
)

AI_CONTROLLED_CANONICAL_SMOKE_TARGETS = tuple(
    alias.canonical_path for alias in AI_CONTROLLED_ROUTE_ALIASES
)


def build_ai_controlled_route_alias_report() -> dict[str, object]:
    return {
        "policy": "read_only_market_intel_ai_controlled_route_aliases",
        "result": "AI_CONTROLLED_CANONICAL_ROUTES_READY",
        "primary_route_family": AI_CONTROLLED_PREFIX,
        "legacy_route_family_status": "compatibility_only",
        "canonical_count": len(AI_CONTROLLED_ROUTE_ALIASES),
        "legacy_compatibility_count": len(AI_CONTROLLED_ROUTE_ALIASES),
        "routes": [alias.as_dict() for alias in AI_CONTROLLED_ROUTE_ALIASES],
        "safety": {
            "read_only": True,
            "writes_database": False,
            "executes_network": False,
            "github_used": False,
        },
    }