# `PhoenixAI.Store.TelemetryHandler`
[🔗](https://github.com/franciscpd/phoenix-ai-store/blob/v0.1.0/lib/phoenix_ai/store/telemetry_handler.ex#L1)

Plain module (not a GenServer) with handler functions for automatic
PhoenixAI telemetry event capture.

Listens to `[:phoenix_ai, :chat, :stop]` and `[:phoenix_ai, :tool_call, :stop]`
events and asynchronously records cost and logs events through the Store.

## Usage

    # Attach (usually done by HandlerGuardian or in application start)
    TelemetryHandler.attach()

    # Detach
    TelemetryHandler.detach()

## Context Propagation

The handler reads `Logger.metadata()[:phoenix_ai_store]` to get
`%{conversation_id: ..., user_id: ...}` for attributing events to
the correct conversation.

# `attach`

```elixir
@spec attach(keyword()) :: :ok | {:error, :already_exists}
```

Attaches the telemetry handler to PhoenixAI events.

# `detach`

```elixir
@spec detach() :: :ok
```

Detaches the telemetry handler.

# `handle_event`

```elixir
@spec handle_event([atom()], map(), map(), keyword()) :: :ok
```

Handles a telemetry event.

For `:chat` stop events, asynchronously records cost and logs a
`:response_received` event. For `:tool_call` stop events, logs
a `:tool_called` event.

All persistence is async via `Task.start/1`. Never crashes —
all errors are caught and logged.

# `handler_id`

```elixir
@spec handler_id() :: atom()
```

Returns the deterministic handler ID.

---

*Consult [api-reference.md](api-reference.md) for complete listing*