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

# Personas

> Configure audience personas for personalized chat and optional login gating

## Overview

Personas describe **who is asking** — for example "CEO of a small enterprise" or "Freelancer".
They are separate from [Assistants](/admin-guide/assistants), which define **which agent** runs the
conversation. A user picks a persona once (or per conversation) so the report writer receives
name, email, profile free text, and optional structured gating answers.

Navigate to **Admin > Settings > Personas**.

<Note>
  Personas are **off by default**. Turn them on under [System Settings](/admin-guide/system-settings)
  before end users see any persona UI. Admin CRUD remains available while the feature is off so you
  can seed personas first.
</Note>

## Feature flags

Two settings in **Admin > Settings > System Settings > CORE** control rollout:

| Setting             | Default | Effect                                                                                                                                             |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PERSONAS_ENABLED`  | `False` | **Master switch.** Off hides all end-user persona UI, skips persona graph steps, and blocks persona REST updates. Admin Personas CRUD still works. |
| `REQUIRED_PERSONAS` | `False` | When master is on, show a **login gate** until the user selects a persona. Ignored when master is off.                                             |

<Warning>
  If a deployment already has `REQUIRED_PERSONAS=True` from an earlier config, you must also set
  `PERSONAS_ENABLED=True` or the feature stays dark.
</Warning>

### Behavior matrix

|                                                    | Master off |       Master on, required off       |   Master on, required on  |
| -------------------------------------------------- | :--------: | :---------------------------------: | :-----------------------: |
| Login persona gate                                 |     No     |                  No                 | Yes (if no persona saved) |
| Profile picker & composer toggle                   |     No     |                 Yes                 |            Yes            |
| Identity in report writer (name, email, free text) |     No     |                 Yes                 |            Yes            |
| Persona gating graph & Cypher steering             |     No     | Only when conversation toggle is on |            Same           |

When the per-conversation **Use persona** toggle is off, identity still injects but persona gating
nodes and the persona memory blob do not run.

## Permissions

Persona admin routes require **AI Managers** (`access_ai_admin`) write access for create, update,
delete, and gating-form generation. Any authenticated user may call **`GET /api/personas/choices/`**
when `PERSONAS_ENABLED` is on — the response uses a slim serializer (no operator-only fields).

## Creating a persona

| Field                   | Description                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| **Name**                | Display name shown on selection cards and the header badge                                        |
| **Slug**                | Stable identifier for URLs and idempotent seeding                                                 |
| **Description**         | Short summary on the selection card                                                               |
| **Gating prompt**       | Bullet list of information to collect; used to **Generate form**                                  |
| **Gating questions**    | Structured JSON form (`GatingFormSchema`); usually produced by generation, editable in JSON mode  |
| **Free text prompt**    | Label for the optional open-ended box (e.g. "Anything else about you?")                           |
| **Graph node name**     | Name of the matching Persona node in the knowledge graph; required before Cypher steering applies |
| **Cypher instructions** | Optional hand-written hints appended to generated Cypher steering                                 |
| **Order**               | Sort order in the user picker (lower first)                                                       |
| **Active**              | Whether the persona appears in `/personas/choices/`                                               |

### Gating form workflow

1. Write a **Gating prompt** describing what to ask (checklist style works well).
2. Click **Generate form** — an LLM builds structured `gating_questions`.
3. Preview the form in the drawer before saving.
4. Regenerate after changing the prompt; a stale-form warning appears if the prompt drifted during generation.

<Warning>
  A persona can be **active with an empty gating form** (`{}`) if you never generate one or the gating
  prompt is blank (generation returns 400). Users can still select it; they only see the free-text field
  and any empty question list. Generate the form before requiring personas at login.
</Warning>

### Graph steering

When **`graph_node_name`** is set and the conversation has persona pipeline enabled, Cypher
generation receives steering text for that node. If **`graph_node_name`** is blank, no steering
snippet is injected — even if **`cypher_instructions`** is set. Set the graph node name only after
matching Persona nodes exist in your graph ontology.

## Deployment checklist

<Steps>
  <Step title="Run migrations">
    Apply Django migrations so `PERSONAS_ENABLED` and `REQUIRED_PERSONAS` exist in the config table
    (`common.0020_enable_persona_dashboard_settings`).
  </Step>

  <Step title="Seed configuration">
    Run `npm run config:seed` (or add both keys in Django admin) so the flags appear in System Settings.
  </Step>

  <Step title="Create personas">
    Add at least one **active** persona and generate gating forms where needed.
  </Step>

  <Step title="Enable master flag">
    Set `PERSONAS_ENABLED=True` in **System Settings > CORE**.
  </Step>

  <Step title="Optional: require at login">
    Set `REQUIRED_PERSONAS=True` only after personas exist and forms are ready.
  </Step>
</Steps>

## Related documentation

* [System Settings — CORE flags](/admin-guide/system-settings#core-settings)
* [Settings & Preferences — user profile persona](/user-guide/settings-and-preferences#persona-profile)
* [Assistants — assistant-level gating](/admin-guide/assistants#gating) (separate from persona gating)