# Chat, tool and generation types (/docs/reference/core/messages)

Part of the [`@tensorpass/aiconnect` reference](/docs/reference/core). The tables are generated from the package's TypeScript source each time the docs are built. Open a row to see its full type.

## Chat types [#chat-types]

The chat format the site and the wallet share. The wallet translates it to each provider's own format and back. `ChatMessage` is a union of four messages, one per `role`:

### ChatMessagesByRole

| Prop        | Type               | Description |
| ----------- | ------------------ | ----------- |
| `assistant` | `AssistantMessage` |             |
| `system`    | `SystemMessage`    |             |
| `tool`      | `ToolMessage`      |             |
| `user`      | `UserMessage`      |             |

### SystemMessage [#systemmessage]

### SystemMessage

| Prop      | Type       | Description |
| --------- | ---------- | ----------- |
| `role`    | `"system"` |             |
| `content` | `string`   |             |

### UserMessage [#usermessage]

### UserMessage

| Prop      | Type                      | Description |
| --------- | ------------------------- | ----------- |
| `role`    | `"user"`                  |             |
| `content` | `string \| ContentPart[]` |             |

`content` is a string, or a list of parts when the message carries images.

### AssistantMessage [#assistantmessage]

### AssistantMessage

| Prop         | Type                      | Description |
| ------------ | ------------------------- | ----------- |
| `role`       | `"assistant"`             |             |
| `content`    | `string`                  |             |
| `toolCalls?` | `ToolCall[] \| undefined` |             |

### ToolMessage [#toolmessage]

### ToolMessage

| Prop         | Type     | Description |
| ------------ | -------- | ----------- |
| `role`       | `"tool"` |             |
| `toolCallId` | `string` |             |
| `name`       | `string` |             |
| `content`    | `string` |             |

A `ToolMessage` answers the `ToolCall` whose `id` it carries in `toolCallId`.

### ToolCall [#toolcall]

### ToolCall

| Prop        | Type                      | Description |
| ----------- | ------------------------- | ----------- |
| `id`        | `string`                  |             |
| `name`      | `string`                  |             |
| `arguments` | `Record<string, unknown>` |             |

### ContentPart [#contentpart]

A union of two parts, one per `type`:

### ContentPartsByType

| Prop    | Type        | Description |
| ------- | ----------- | ----------- |
| `image` | `ImagePart` |             |
| `text`  | `TextPart`  |             |

### TextPart [#textpart]

### TextPart

| Prop   | Type     | Description |
| ------ | -------- | ----------- |
| `type` | `"text"` |             |
| `text` | `string` |             |

### ImagePart [#imagepart]

### ImagePart

| Prop   | Type      | Description |
| ------ | --------- | ----------- |
| `type` | `"image"` |             |
| `url`  | `string`  |             |

`url` is a `data:` URL, or an https URL for the providers that fetch images themselves.

```ts
const messages: ChatMessage[] = [
  { role: 'system', content: 'You recommend books from this site\'s catalog.' },
  { role: 'user', content: 'A calm book for tonight' },
  { role: 'assistant', content: '', toolCalls: [{ id: 'call_1', name: 'search_books', arguments: { mood: 'calm' } }] },
  { role: 'tool', toolCallId: 'call_1', name: 'search_books', content: '[{"title":"Piranesi"}]' },
];

const cover: ContentPart[] = [
  { type: 'text', text: 'Which book has this cover?' },
  { type: 'image', url: 'https://example.com/covers/piranesi.jpg' },
];
messages.push({ role: 'user', content: cover });
```

## Tool types [#tool-types]

The tools a site offers. Any object that implements `ToolSource` can feed `runConversation` and `useAiChat`.

### ToolDefinition [#tooldefinition]

### ToolDefinition

| Prop          | Type         | Description |
| ------------- | ------------ | ----------- |
| `name`        | `string`     |             |
| `description` | `string`     |             |
| `inputSchema` | `JsonSchema` |             |

### ToolSource [#toolsource]

### ToolSource

| Prop        | Type                                                               | Description |
| ----------- | ------------------------------------------------------------------ | ----------- |
| `listTools` | `() => Promise<ToolDefinition[]>`                                  |             |
| `callTool`  | `(name: string, args: Record<string, unknown>) => Promise<string>` |             |

### JsonSchema [#jsonschema]

The type of `inputSchema`, a JSON Schema object:

### JsonSchemaShape

| Prop         | Type                        | Description |
| ------------ | --------------------------- | ----------- |
| `JsonSchema` | `{ [x: string]: unknown; }` |             |

```ts
const empty: JsonSchema = { type: 'object', properties: {} };

const clock: ToolSource = {
  listTools: async () => [{
    name: 'current_time',
    description: 'The current time of the visitor\'s computer, in UTC, as an ISO 8601 string.',
    inputSchema: empty,
  }],
  callTool: async () => new Date().toISOString(),
};
```

## GenerationOptions [#generationoptions]

What the site asks of the answer, in `ChatRequest.options`.

### GenerationOptions

| Prop              | Type                          | Description |
| ----------------- | ----------------------------- | ----------- |
| `maxTokens?`      | `number \| undefined`         |             |
| `temperature?`    | `number \| undefined`         |             |
| `topP?`           | `number \| undefined`         |             |
| `stop?`           | `string[] \| undefined`       |             |
| `toolChoice?`     | `ToolChoice \| undefined`     |             |
| `responseFormat?` | `ResponseFormat \| undefined` |             |

`maxTokens`, `temperature`, `topP` and `stop` are hints: the account's connector leaves out those its provider refuses. `toolChoice` and `responseFormat` always reach the provider.

### GenerationHint [#generationhint]

The names of the hints, each with the type of its option:

### GenerationHints

| Prop          | Type       | Description |
| ------------- | ---------- | ----------- |
| `maxTokens`   | `number`   |             |
| `stop`        | `string[]` |             |
| `temperature` | `number`   |             |
| `topP`        | `number`   |             |

### ToolChoice [#toolchoice]

Whether the model may answer in text, must call a tool, or must call the named one. A tool choice is one of these strings:

### ToolChoiceStrings

| Prop       | Type         | Description |
| ---------- | ------------ | ----------- |
| `auto`     | `"auto"`     |             |
| `none`     | `"none"`     |             |
| `required` | `"required"` |             |

Or an object that names the tool:

### NamedToolChoice

| Prop   | Type     | Description |
| ------ | -------- | ----------- |
| `name` | `string` |             |

### ResponseFormat [#responseformat]

An answer in JSON, held to `schema` when one is given. `strict` asks the providers that offer it to refuse any schema they cannot enforce exactly.

### ResponseFormat

| Prop      | Type                      | Description |
| --------- | ------------------------- | ----------- |
| `type`    | `"json"`                  |             |
| `schema?` | `JsonSchema \| undefined` |             |
| `name?`   | `string \| undefined`     |             |
| `strict?` | `boolean \| undefined`    |             |

```ts
const { message, finishReason } = await state.session.chat({
  messages: [{ role: 'user', content: 'Three calm books, as JSON.' }],
  options: {
    maxTokens: 400,
    toolChoice: 'none',
    responseFormat: {
      type: 'json',
      name: 'books',
      schema: { type: 'object', properties: { titles: { type: 'array', items: { type: 'string' } } } },
    },
  },
});
const { titles } = JSON.parse(message.content) as { titles: string[] };

// The hints a ChatGPT plan account refuses, which its connector leaves out of every call.
const refusedByChatGpt: GenerationHint[] = ['maxTokens', 'temperature', 'topP'];
```
