from __future__ import annotations

from datetime import datetime, timezone
from typing import Any

Confidence = str


def utc_now_iso() -> str:
    return datetime.now(timezone.utc).isoformat()


def evidence(
    value: Any,
    *,
    source: str,
    url: str | None = None,
    confidence: Confidence = "medium",
    retrieved_at: str | None = None,
    raw: Any | None = None,
) -> dict[str, Any]:
    """Wrap a data value with provenance.

    The MCP deliberately returns evidence records rather than editorial recommendations.
    Hermes or another client remains responsible for interpreting and presenting the data.
    """
    record: dict[str, Any] = {
        "value": value,
        "source": source,
        "url": url,
        "retrieved_at": retrieved_at or utc_now_iso(),
        "confidence": confidence,
    }
    if raw is not None:
        record["raw"] = raw
    return record


def empty_result(query: str, tool: str, reason: str) -> dict[str, Any]:
    return {
        "query": query,
        "tool": tool,
        "retrieved_at": utc_now_iso(),
        "status": "no_data",
        "reason": reason,
        "records": [],
    }