from __future__ import annotations

import enum
from dataclasses import dataclass
from typing import Any


class StreamEventType(enum.StrEnum):
    """Types of events yielded during a streaming LLM conversation."""

    CONTENT = "content"
    REASONING = "reasoning"
    TOOL_CALL = "tool_call"
    TOOL_RESULT = "tool_result"
    DONE = "done"


@dataclass
class StreamEvent:
    """A single event in a streaming conversation with an LLM.

    Attributes:
        type: The kind of event (content, reasoning, tool_call, etc.).
        text: Text content for CONTENT or REASONING events.
        tool_name: The name of the tool being called or whose result is returned.
        tool_args: The arguments passed to the tool call.
        tool_result: The result returned by executing the tool.
    """

    type: StreamEventType
    text: str | None = None
    tool_name: str | None = None
    tool_args: dict[str, Any] | None = None
    tool_result: Any | None = None
