# `Codex.Realtime.Model`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.1/lib/codex/realtime/model.ex#L1)

Behaviour for realtime model implementations.

This behaviour defines the interface for connecting to a realtime model
and sending/receiving events. Implementations can include WebSocket-based
connections to OpenAI's Realtime API or mock implementations for testing.

## Implementing a Model

To implement a custom realtime model, use this behaviour and implement
all callbacks:

    defmodule MyCustomModel do
      @behaviour Codex.Realtime.Model

      @impl true
      def connect(config) do
        # Establish connection
        :ok
      end

      @impl true
      def add_listener(listener) do
        # Add event listener
        :ok
      end

      # ... implement other callbacks
    end

## Listeners

Listeners can be either a pid or a function. When an event is received,
it is forwarded to all registered listeners:

  * If the listener is a pid, the event is sent as `{:model_event, event}`
  * If the listener is a function, it is called with the event

# `listener`

```elixir
@type listener() :: pid() | (Codex.Realtime.ModelEvents.t() -> :ok)
```

# `add_listener`

```elixir
@callback add_listener(listener()) :: :ok
```

Add a listener for model events.

Listeners receive all events from the model connection.

# `close`

```elixir
@callback close() :: :ok
```

Close the model connection.

Cleans up resources and closes any WebSocket connections.

# `connect`

```elixir
@callback connect(config :: Codex.Realtime.Config.ModelConfig.t()) ::
  :ok | {:error, term()}
```

Establish a connection to the model.

Called when the session starts. The config contains API keys, URLs,
and initial model settings.

# `remove_listener`

```elixir
@callback remove_listener(listener()) :: :ok
```

Remove a listener for model events.

# `send_event`

```elixir
@callback send_event(event :: Codex.Realtime.ModelInputs.send_event()) ::
  :ok | {:error, term()}
```

Send an event to the model.

Events include user input, audio data, tool outputs, and session updates.

---

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