# `Nous.PubSub`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/pubsub.ex#L1)

Thin PubSub abstraction for Nous.

Wraps Phoenix.PubSub with graceful fallback when it's not available.
Provides application-level configuration so users don't need to pass
`pubsub: MyApp.PubSub` to every AgentServer.

## Configuration

    # In config/config.exs
    config :nous, pubsub: MyApp.PubSub

## Usage

    # Subscribe (no-op if PubSub unavailable)
    Nous.PubSub.subscribe(MyApp.PubSub, "agent:session_123")

    # Broadcast (no-op if PubSub unavailable)
    Nous.PubSub.broadcast(MyApp.PubSub, "agent:session_123", {:agent_delta, "Hello"})

    # Use configured PubSub
    pubsub = Nous.PubSub.configured_pubsub()

# `agent_topic`

```elixir
@spec agent_topic(String.t()) :: String.t()
```

Build an agent topic for the given session ID.

    iex> Nous.PubSub.agent_topic("abc123")
    "nous:agent:abc123"

# `approval_topic`

```elixir
@spec approval_topic(String.t()) :: String.t()
```

Build an approval topic for the given session ID.

    iex> Nous.PubSub.approval_topic("abc123")
    "nous:approval:abc123"

# `available?`

```elixir
@spec available?() :: boolean()
```

Checks if PubSub is available (Phoenix.PubSub loaded and a module configured).

# `available?`

```elixir
@spec available?(module() | nil) :: boolean()
```

Checks if PubSub is available for the given module.

Returns `true` if Phoenix.PubSub is loaded and `pubsub` is not nil.

# `broadcast`

```elixir
@spec broadcast(module() | nil, String.t() | nil, term()) :: :ok | {:error, term()}
```

Broadcast a message on a topic.

No-op if PubSub is unavailable.

# `configured_pubsub`

```elixir
@spec configured_pubsub() :: module() | nil
```

Returns the application-configured PubSub module.

Reads from `Application.get_env(:nous, :pubsub)`.
Returns `nil` if not configured.

# `research_topic`

```elixir
@spec research_topic(String.t()) :: String.t()
```

Build a research topic for the given session ID.

    iex> Nous.PubSub.research_topic("abc123")
    "nous:research:abc123"

# `subscribe`

```elixir
@spec subscribe(module() | nil, String.t()) :: :ok | {:error, term()}
```

Subscribe the calling process to a topic.

No-op if PubSub is unavailable.

---

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