"""Framework-neutral MATH actor-facing interface helpers."""

from __future__ import annotations

from typing import Any


def environment_description() -> str:
    """Return the factual, label-free single-attempt environment contract."""

    return (
        "MATH is a single-attempt mathematics problem-solving environment. The current "
        "observation contains one problem statement. Submit exactly one complete final "
        "answer string in the answer field. The server grades the submitted answer against "
        "a hidden reference answer and terminates immediately. Either the answer matches or "
        "it does not; there is no partial credit and no retry. Answer as a bare value (for "
        "example a number, expression, or set), without explanation, in plain text or "
        "LaTeX."
    )


def build_task_prompt(instruction: str) -> str:
    """Build the actor-facing MATH prompt from a frozen task record.

    The actor sees only the problem statement. Official class and difficulty are post-hoc
    metadata and must never reach the solver.
    """
    return (
        "# Problem\n"
        f"{instruction}\n\n"
        "# Task\n"
        "Solve the problem and provide only the final answer. Return the answer string in "
        "the action object's `answer` field."
    )


def extract_answer(value: Any) -> str:
    """Return the submitted answer string, stripping an outer fenced block if present."""
    text = str(value).strip()
    if text.startswith("```"):
        # strip one optional language tag + fences
        lines = text.splitlines()
        lines = lines[1:] if lines and not lines[0].startswith("```answer") else [lines[0]] + lines[1:]
        lines = [line for line in lines if not line.strip().startswith("```")]
        text = "\n".join(lines).strip()
    return text