from SimpleLLMFunc.hooks import ReactOutput, ResponseYield, EventYield

ReactOutput = ResponseYield | EventYield

@dataclass
class ResponseYield:
    response: Any                    # str, Pydantic model, or raw dict
    messages: NormalizedMessageList   # Updated conversation history

@dataclass
class EventYield:
    event: ReActEvent       # One of 14+ event types
    origin: EventOrigin     # Source identification

@dataclass
class EventOrigin:
    session_id: str
    agent_call_id: str
    event_seq: int
    parent_agent_call_id: str | None = None
    fork_id: str | None = None
    fork_depth: int = 0
    fork_seq: int | None = None
    selfref_instance_id: str | None = None
    source_memory_key: str | None = None
    memory_key: str | None = None
    tool_name: str | None = None
    tool_call_id: str | None = None

from SimpleLLMFunc.hooks import is_response_yield, is_event_yield

is_response_yield(output: ReactOutput) -> bool
is_event_yield(output: ReactOutput) -> bool

from SimpleLLMFunc.hooks import responses_only, events_only, filter_events

# Only ResponseYield items
async for resp in responses_only(agent_stream):
    print(resp.response)

# Only EventYield items
async for evt in events_only(agent_stream):
    handle(evt.event)

# Only specific event types
async for evt in filter_events(agent_stream, LLMChunkArriveEvent):
    print(evt.event.accumulated_content)

@dataclass
class ReactStartEvent:
    event_type: ReActEventType = ReActEventType.REACT_START

@dataclass
class ReactIterationStartEvent:
    iteration: int
    event_type: ReActEventType = ReActEventType.REACT_ITERATION_START

@dataclass
class ReactIterationEndEvent:
    iteration: int
    event_type: ReActEventType = ReActEventType.REACT_ITERATION_END

@dataclass
class ReactEndEvent:
    final_messages: NormalizedMessageList
    response: Any
    event_type: ReActEventType = ReActEventType.REACT_END

@dataclass
class LLMCallStartEvent:
    messages: NormalizedMessageList   # What the LLM will see
    event_type: ReActEventType = ReActEventType.LLM_CALL_START

@dataclass
class LLMChunkArriveEvent:
    chunk: LLMStreamChunk             # Provider chunk object
    accumulated_content: str          # Content accumulated so far
    chunk_index: int
    event_type: ReActEventType = ReActEventType.LLM_CHUNK_ARRIVE

@dataclass
class LLMCallEndEvent:
    response: Any
    messages: NormalizedMessageList
    tool_calls: list[Any]
    execution_time: float
    content: str = ""
    usage: Optional[Dict[str, int]] = None
    event_type: ReActEventType = ReActEventType.LLM_CALL_END

@dataclass
class LLMCallErrorEvent:
    error: Exception
    event_type: ReActEventType = ReActEventType.LLM_CALL_ERROR

@dataclass
class ToolCallsBatchStartEvent:
    tool_calls: List[Dict[str, Any]]  # All calls in this batch
    event_type: ReActEventType = ReActEventType.TOOL_CALLS_BATCH_START

@dataclass
class ToolCallStartEvent:
    tool_name: str
    tool_call_id: str
    arguments: Dict[str, Any]
    event_type: ReActEventType = ReActEventType.TOOL_CALL_START

@dataclass
class ToolCallArgumentsDeltaEvent:
    tool_name: str
    tool_call_id: str
    argname: str
    argcontent_delta: str             # Streaming argument fragment
    event_type: ReActEventType = ReActEventType.TOOL_CALL_ARGUMENTS_DELTA

@dataclass
class ToolCallEndEvent:
    tool_name: str
    tool_call_id: str
    arguments: Dict[str, Any]
    result: Any
    execution_time: float
    success: bool
    event_type: ReActEventType = ReActEventType.TOOL_CALL_END

@dataclass
class ToolCallErrorEvent:
    tool_name: str
    tool_call_id: str
    error: str
    event_type: ReActEventType = ReActEventType.TOOL_CALL_ERROR

@dataclass
class ToolCallsBatchEndEvent:
    event_type: ReActEventType = ReActEventType.TOOL_CALLS_BATCH_END

@dataclass
class CustomEvent:
    event_name: str              # e.g., "kernel_stdout", "selfref_fork_spawn"
    data: Dict[str, Any]         # Event payload
    tool_call_id: Optional[str]  # Which tool emitted this
    event_type: ReActEventType = ReActEventType.CUSTOM

from SimpleLLMFunc.hooks import ToolEventEmitter

emitter = ToolEventEmitter()

# Inside a tool implementation:
await emitter.emit(CustomEvent(
    event_name="progress",
    data={"percent": 50},
    tool_call_id=current_tool_call_id,
))

from SimpleLLMFunc.hooks import NoOpEventEmitter

from SimpleLLMFunc.hooks import with_event_observer

@with_event_observer(my_observer_fn)
@llm_chat(...)
async def agent(...):
    ...

def my_observer(event: ReActEvent, origin: EventOrigin) -> None:
    ...

from SimpleLLMFunc.hooks import AbortSignal, ABORT_SIGNAL_PARAM

signal = AbortSignal()
signal.abort("reason")      # Trigger abort
signal.is_aborted           # bool
signal.reason               # str | None