> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Component (genai.chat)

> One model call over a conversation, through a model provider.

One model call over a conversation. The component, labelled **Generative AI Chat** in the editor, takes a system
message, the history and the current message, sends them to the model its provider runs, and outputs the model's answer
as one message. Its `model` port takes a [`genai.model`](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model), which
holds the model, its credentials and its sampling settings.

```mermaid theme={null}
flowchart LR
    system["system"] --> chat
    history["history"] --> chat
    current["current"] --> chat
    model["genai.model"] -->|model| chat["genai.chat"]
    chat -->|output| answer["One assistant message"]
```

## Ports

The component has a flow input and two flow outputs, the routes `success` and `failure`. A failed call takes the
`failure` route.

| Route | Category | Value | Notes |
| - | - | - | - |
| `model` | Provider input | a `genai.model` | Required. The model it runs must do `chat`: a catalog model without that capability is an error in the provider's `model` port. |
| `system` | Data input | `message` | Sent first, with its role set to `system`. The editor fills in an empty text message. |
| `history` | Data input | `messages` | The conversation so far, sent after `system`. |
| `current` | Data input | `message` | Sent last. The editor fills in an empty text message with the role `user`. |
| `output_role` | Data input | `text` | The role of the output message. Defaults to `assistant`. |
| `response_format` | Data input | `choice`: `text`, `json`, `json_schema` | Labelled Text, JSON and JSON schema. Defaults to `text`. |
| `response_schema` | Data input | `message` | The schema the answer follows when `response_format` is `json_schema`. |
| `output` | Data output | `message` | The model's answer. |

The sampling settings, including `stop_sequences`, are the provider's, not the chat's: they sit on the `genai.model`
([Settings](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#settings)), and a run can replace them for one run
([Choosing a Model per Run](https://docs.blobhub.io/blob-types/workflow/workflows/choosing-a-model.md)). The models the provider offers are
listed in [The catalog](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#the-catalog), and the credential each
vendor needs in
[Vendors and credentials](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#vendors-and-credentials).

## The conversation sent

The messages go to the model in this order: `system`, with its role set to `system`; then every message of `history`;
then `current`. A message whose role is not `system`, `user` or `assistant` is sent as `user`. With no message at all,
the node posts the error `No input messages provided` and fails.

The chat is text only. A message holding any content block other than `text` fails the node with
`unsupported_content_block: <type>`, so a file or a JSON block is refused rather than dropped.

## The answer format

`response_format` asks the model for text, for JSON, or for JSON that follows `response_schema`. Each vendor takes it in
its own way:

| Vendor | `json` | `json_schema` |
| - | - | - |
| OpenAI | `response_format` of type `json_object` | `response_format` of type `json_schema`, holding the whole `response_schema` envelope |
| Anthropic | not supported | not supported |
| Gemini | `response_mime_type` of `application/json` | `application/json`, with the `schema` of the `response_schema` envelope |

Anthropic answers text whatever the format, and with `json` or `json_schema` the call posts the warning
`"response_format" is specified but is not currently supported`. With `json_schema` and an empty `response_schema`, the
node fails with `schema_required_in_json_schema_mode` for OpenAI and Gemini.

## The output

The `output` is one message, with the role `assistant` unless `output_role` says otherwise, holding text blocks:

* OpenAI: the text of the first choice.
* Anthropic: the text blocks of the answer. Thinking and every other block are left out.
* Gemini: the text parts of the first candidate. Parts marked as thoughts are left out.

Three refusals fail the call, and the error names why: an Anthropic answer that stops as a refusal fails with
`refusal: <category>`, or `refusal` alone when the vendor gives no category; a Gemini prompt the vendor blocks fails
with `refusal: <reason>`; and a Gemini reply with no candidate and no reason fails with `no_candidates`. Other refusals
arrive as an empty or partial answer on `success`: an OpenAI answer with no text or stopped by its content filter, and a
Gemini answer stopped for `SAFETY`.

## Events

A call posts one `processor.output` event. Its `attributes.model` names the model that ran, as `{"id", "chosen_by"}`,
and its `data` holds:

* `request`: the arguments sent to the vendor's API;
* `response`: the vendor's answer as JSON;
* `usage`: `input_tokens` and `output_tokens`.

Before it, the provider posts a `processor.warning` for each setting it left out, for a model a run named that the
catalog does not list, and for a format the vendor ignored. A failed call posts a `processor.error`
([When the call fails](https://docs.blobhub.io/blob-types/workflow/workflows/component-genai-model.md#when-the-call-fails)). How to read which
model a run used is in [Choosing a Model per Run](https://docs.blobhub.io/blob-types/workflow/workflows/choosing-a-model.md#which-model-ran).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.