# `Cyclium.Conversations`
[🔗](https://github.com/Cyclium/cyclium_ex/blob/main/lib/cyclium/conversations.ex#L1)

Context module for managing interactive conversations.
Provides start, claim, resolve, abandon, and query operations.

# `abandon`

```elixir
@spec abandon(binary(), binary()) ::
  {:ok, Cyclium.Schemas.Conversation.t()} | {:error, term()}
```

# `check_constraints`

```elixir
@spec check_constraints(Cyclium.Schemas.Conversation.t()) ::
  :ok | {:warn, :last_turn} | {:error, :budget_exceeded}
```

# `claim`

```elixir
@spec claim(binary(), map()) ::
  {:ok, Cyclium.Schemas.Conversation.t()}
  | {:error, :already_claimed | :not_found}
```

Claim a conversation (for :pool and :any audience modes).
Sets the principal and transitions status to :open.

# `get`

```elixir
@spec get(binary()) :: Cyclium.Schemas.Conversation.t() | nil
```

# `get!`

```elixir
@spec get!(binary()) :: Cyclium.Schemas.Conversation.t()
```

# `increment_turn`

```elixir
@spec increment_turn(binary(), non_neg_integer()) ::
  {:ok, Cyclium.Schemas.Conversation.t()} | {:error, :not_found}
```

# `list_awaiting`

```elixir
@spec list_awaiting(keyword()) :: [Cyclium.Schemas.Conversation.t()]
```

# `list_for_actor`

```elixir
@spec list_for_actor(
  binary() | atom(),
  keyword()
) :: [Cyclium.Schemas.Conversation.t()]
```

# `list_for_principal`

```elixir
@spec list_for_principal(
  binary(),
  keyword()
) :: [Cyclium.Schemas.Conversation.t()]
```

# `resolve`

```elixir
@spec resolve(binary(), binary(), map()) ::
  {:ok, Cyclium.Schemas.Conversation.t()} | {:error, term()}
```

Resolve a conversation with an outcome and result.

# `start`

```elixir
@spec start(map()) ::
  {:ok, Cyclium.Schemas.Conversation.t()} | {:error, Ecto.Changeset.t()}
```

Start a new conversation.

## Required fields
  - `:actor_id` — which interactive actor handles this conversation
  - `:name` — display name

## Optional fields
  - `:principal` — map with "type", "id", "label"
  - `:goal` — GoalSpec map (JSON-encoded on write)
  - `:origin` — Origin map
  - `:audience_target` — AudienceTarget map

# `timeout`

```elixir
@spec timeout(binary()) :: {:ok, Cyclium.Schemas.Conversation.t()} | {:error, term()}
```

# `update_collected_fields`

```elixir
@spec update_collected_fields(binary(), map()) ::
  {:ok, Cyclium.Schemas.Conversation.t()} | {:error, term()}
```

---

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