# AI Configuration

> Configuration settings are exclusively visible to **YouDesign Models admins** within your organization.

This page describes how administrators enable and configure the AI assistant features of YouDesign Models. End-user documentation lives in the [AI Assistant](/models/work-in-the-app/ai.md) section.

## Overview

AI is **disabled by default.** To turn it on, an admin needs to:

1. Register an **AI provider** (API key, base URL, model whitelist) in ServiceNow.
2. Enable AI in the **global settings** and select a default model.
3. Ensure users have the roles required to use AI features in the editor.

All configuration happens inside ServiceNow — there is no separate admin portal or external cloud console.

## 1. Register an AI Provider

Provider credentials live in the `x_inpi_yd_ai_provider` table. Each record represents one AI provider that YouDesign Models can route requests to.

Create a new record with the following fields:

| Field             | Description                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `type`            | Provider identifier (e.g., OpenAI, Anthropic, Azure OpenAI). The codebase is provider-agnostic. |
| `api_key`         | The API key for the provider. Stored encrypted in ServiceNow.                                   |
| `base_url`        | Base endpoint URL for the provider's API.                                                       |
| `allowed_models`  | The list of models that users in your organization are permitted to use.                        |
| `default_model`   | The model used by default when a user does not select one.                                      |
| `request_timeout` | How long a single AI request is allowed to run before timing out.                               |

> **Important:** Treat `api_key` as sensitive. Use your ServiceNow platform's standard controls to limit who can read and modify records in this table.

### Supported Providers

YouDesign Models is built to be **provider-agnostic**. Providers that work with the standard protocols used by the application include:

* OpenAI
* Anthropic
* Azure OpenAI

Check with your ins-pi representative for the latest list of certified providers.

### Endpoint Overrides

For self-hosted or enterprise deployments that expose an OpenAI-compatible endpoint, set the `base_url` field on the provider record to your custom URL. There is no separate UI panel for endpoint overrides — it's configured directly on the provider record.

## 2. Enable AI in Global Settings

AI is toggled via the global setting `x_inpi_yd.gl.ai_config`. The value is a JSON object:

```json
{
  "enabled": true,
  "model": "default-model-id",
  "models": [ "model-id-1", "model-id-2" ]
}
```

| Field     | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| `enabled` | Master on/off switch for AI features. Users see the AI button only when `true`. |
| `model`   | The default model offered to users.                                             |
| `models`  | Optional list of models the user may choose from.                               |

> **Note:** `x_inpi_yd.gl.ai_config` is currently edited through the **raw** global-settings editor — it is not yet exposed in the categorized admin UI. See [Global Settings](/models/admin/global-settings.md) for how to access the raw editor.

### Verifying the Configuration

After saving `ai_config` with `enabled: true`:

1. Open any board in the editor as a regular (non-admin) user.
2. Confirm the **AI Chat** button appears in the top-right toolbar.
3. Open the panel and send a short prompt (for example, *"Add a single rectangle labelled Test"*).
4. Confirm the AI responds with a preview.

If the button doesn't appear, re-check that `enabled` is `true` and the user's session has been refreshed.

## 3. Role Requirements

Access to the YouDesign Models admin settings (where AI is configured) requires the **YouDesign Models Admin** role.

End-user access to AI features in the editor is gated by `ai_config.enabled` — any user who can open the editor will see AI controls when the feature is enabled. If you need finer-grained control (e.g., only a subset of users), restrict at the ServiceNow role level rather than in YouDesign Models.

## 4. Model Selection at Runtime

The frontend loads available models from the endpoint `/api/x_inpi_yd/v1/ai/get_capabilities`, which reads the active provider's `allowed_models` plus any `models` list from `ai_config`. Users only see models you've whitelisted.

## What's Not Admin-Configurable Today

The following items are fixed in the application and cannot be changed through the admin UI in v26. If you have a requirement for one of these, contact ins-pi support:

* **Prompt templates** used by the AI (the instructions YouDesign Models sends alongside user input) are registered server-side in `AiPromptRegistry`.
* **Rate limits** are enforced by the upstream AI provider, not by YouDesign Models. Use your provider's rate-limit controls if you need to cap usage.
* **Per-user usage quotas** — not available through the YouDesign Models admin UI.

## Data Flow Summary

1. A user sends a prompt from the AI Chat panel.
2. YouDesign Models packages the prompt, the relevant diagram context, and any attached images.
3. The request is sent directly from ServiceNow to the AI provider using the `api_key` and `base_url` from the provider record.
4. The provider's response is returned to the user's browser and displayed as a preview.

No diagram data is sent to any intermediary server operated by ins-pi. The AI provider may log requests according to its own retention policy — consult your provider's terms.

## Troubleshooting

| Symptom                                                     | Likely Cause & Fix                                                                                                         |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Users don't see the AI Chat button                          | `ai_config.enabled` is `false`, or users have not reloaded since the change.                                               |
| AI requests fail with an authentication error               | API key on the provider record is missing, expired, or lacks permission for the chosen model. Rotate and re-save.          |
| AI requests succeed but models list is empty for the user   | `allowed_models` on the provider record is empty, or `ai_config.models` doesn't include any of the provider's allowed IDs. |
| Requests time out on large diagrams                         | Increase `request_timeout` on the provider record, or ask users to narrow scope with `@mentions`.                          |
| A specific model works in the provider console but not here | The model ID is not in `allowed_models`. Add it and re-save.                                                               |

## Related

* [Global Settings](/models/admin/global-settings.md) – Where `ai_config` lives
* [AI Assistant (end-user guide)](/models/work-in-the-app/ai.md) – What users see when AI is enabled
* [Data Privacy & Transparency](/models/work-in-the-app/ai/privacy.md) – What data leaves your organization


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ins-pi.com/models/admin/ai-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.