"""Helpers for granular Langfuse traces (LLM generations + tool spans)."""
from __future__ import annotations

from typing import Any


def make_callback_handler():
    """LangChain CallbackHandler that nests generations under the current observation."""
    from langfuse.langchain import CallbackHandler

    return CallbackHandler()


def llm_invoke_config(
    *,
    handler: Any,
    turn: int,
    episode_id: str | None = None,
    extra_metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
    meta = {"turn": turn}
    if episode_id:
        meta["episode_id"] = episode_id
    if extra_metadata:
        meta.update(extra_metadata)
    return {
        "callbacks": [handler],
        "run_name": f"llm-turn-{turn}",
        "tags": ["deepagents-rl", "llm", f"turn-{turn}"],
        "metadata": meta,
    }