"""AI transparency helpers.

Provides utilities to mark content as AI-generated and to detect whether a
communication participant is an AI agent. This is the transparency layer
required by the AI governance framework: any content produced by an AI agent
must be identifiable as such.

Used by:
- ``app/plugins/builtins/kommunikation`` — marking AI agent messages
- ``app/ai/agent_loop.py`` — tagging final outputs as AI-generated
"""

from __future__ import annotations

from datetime import UTC, datetime
from typing import Any

# Participant types that represent an AI agent (not a human user).
AI_PARTICIPANT_TYPES = ("agent", "ai", "system_ai")


def mark_as_ai_generated(content: str, metadata: dict[str, Any] | None = None) -> dict[str, Any]:
    """Add AI transparency metadata to content.

    Args:
        content: The AI-generated content.
        metadata: Optional dict with ``model`` and ``provider`` keys plus any
            additional context to record.

    Returns:
        A dict with the original content plus an ``ai_generated`` flag and an
        ``ai_metadata`` block containing model, provider, timestamp, and any
        extra metadata passed in.
    """
    metadata = metadata or {}
    return {
        "content": content,
        "ai_generated": True,
        "ai_metadata": {
            "model": metadata.get("model", "unknown"),
            "provider": metadata.get("provider", "unknown"),
            "timestamp": datetime.now(UTC).isoformat(),
            **metadata,
        },
    }


def is_ai_participant(participant_id: str, participant_type: str) -> bool:
    """Check if a participant is an AI agent.

    Args:
        participant_id: The participant's ID (unused for the check, kept for
            API symmetry and future heuristics).
        participant_type: The participant type string (e.g. ``user``,
            ``agent``, ``ai``, ``system_ai``).

    Returns:
        ``True`` if the participant type is an AI agent type.
    """
    return participant_type in AI_PARTICIPANT_TYPES