from __future__ import annotations

from typing import Any


def run_started(*, run_id: str) -> dict[str, Any]:
    return {"type": "run.started", "run_id": run_id}


def stage_completed(
    *, run_id: str, stage: str, usage: dict[str, Any] | None = None
) -> dict[str, Any]:
    event: dict[str, Any] = {
        "type": "stage.completed",
        "run_id": run_id,
        "stage": stage,
    }
    if usage is not None:
        event["usage"] = usage
    return event


def run_completed(*, run_id: str, output: str, usage: dict[str, Any]) -> dict[str, Any]:
    return {
        "type": "run.completed",
        "run_id": run_id,
        "output": output,
        "usage": usage,
    }


def run_failed(*, run_id: str, error: str) -> dict[str, Any]:
    return {
        "type": "run.failed",
        "run_id": run_id,
        "error": error,
    }
