from __future__ import annotations

from typing import Any

from yera.opaque.base import OpaqueCallable
from yera.yil.tracing.markdown_tracing import MarkdownTracingContext


class Markdown(OpaqueCallable):
    """Trace-only opaque callable for markdown blocks.

    This is a YIL-first API surface for markdown. It is intended to be used
    *only* inside a tracing context. Calling it directly in normal Python
    execution is an error.
    """

    @property
    def name(self) -> str:
        """Get the name of the opaque callable."""
        return "markdown"

    def __call__(self, content: Any | None = None) -> MarkdownTracingContext:
        """Call markdown during tracing to create MarkdownInit operations.

        When called inside a tracing context:
        - Delegates to tracing module to create MarkdownInit operation
        - Returns a MarkdownTracingContext representing the markdown block

        When called outside a tracing context:
        - Raises RuntimeError (trace-only contract)

        Args:
            content: Content for the markdown block (can be Tracer, literal, or None).
                    If None, creates a markdown block with no initial content.

        Returns:
            MarkdownTracingContext representing the markdown block (in tracing context)
            or raises RuntimeError (outside tracing context)

        """
        from yera.yil.tracing.markdown_tracing import trace_markdown

        return trace_markdown(content)


# Trace-only markdown implementation for OpGraph.
#
# This is used during tracing to create MarkdownInit/MarkdownAppend operations.
# In the future, this will be the only markdown implementation (chat/blocks/markdown.py
# will be removed), and execution will happen via OpGraph executor.
#
# For now, this exists alongside yera.chat.markdown which provides direct execution
# for MVP demos. This implementation ONLY works in a tracing context.
markdown = Markdown()


__all__ = ["Markdown", "markdown"]
