Changeset 0.28.0.1 (#173)
This commit is contained in:
204
docs/ICD/personas.md
Normal file
204
docs/ICD/personas.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# Personas
|
||||
|
||||
A **Persona** is the unit of access control and AI identity: system
|
||||
prompt + model + provider config + KB bindings + grant scoping. Users
|
||||
interact with Personas, not raw provider configs. Admins curate which
|
||||
Personas are available; team admins create team-scoped Personas.
|
||||
|
||||
**Model inheritance:** A Persona inherits all properties of its
|
||||
underlying model. This includes context window size, max output
|
||||
tokens, supported capabilities (thinking, tools, vision, streaming),
|
||||
input/output pricing, and provider status. When the frontend displays
|
||||
a Persona, it resolves the underlying model's capabilities and shows
|
||||
the same pills/badges (e.g. thinking, tools, 200k context) that the
|
||||
raw model would show. The Persona adds identity (name, avatar, system
|
||||
prompt, KB bindings) on top of the model's capabilities — it never
|
||||
masks or reduces them.
|
||||
|
||||
Three scopes, three route namespaces, one domain:
|
||||
|
||||
| Scope | Routes | Who manages |
|
||||
|-------|--------|-------------|
|
||||
| Personal | `GET/POST/PUT/DELETE /personas` | The user |
|
||||
| Team | `GET/POST/PUT/DELETE /teams/:teamId/personas` | Team admin |
|
||||
| Global (admin) | `GET/POST/PUT/DELETE /admin/personas` | Platform admin |
|
||||
|
||||
All three return the same Persona object shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Code Reviewer",
|
||||
"description": "Reviews code for bugs and style",
|
||||
"system_prompt": "You are a senior code reviewer...",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"provider_config_id": "uuid|null",
|
||||
"scope": "personal|team|global",
|
||||
"owner_id": "uuid|null",
|
||||
"is_default": false,
|
||||
"is_active": true,
|
||||
"avatar_url": "/api/v1/personas/uuid/avatar?v=123",
|
||||
"inherited": {
|
||||
"context_window": 200000,
|
||||
"max_output_tokens": 8192,
|
||||
"supports_vision": true,
|
||||
"supports_tools": true,
|
||||
"supports_thinking": true,
|
||||
"supports_streaming": true,
|
||||
"input_price_per_m": 3.00,
|
||||
"output_price_per_m": 15.00,
|
||||
"provider_status": "healthy|degraded|down|null"
|
||||
},
|
||||
"created_at": "...",
|
||||
"updated_at": "..."
|
||||
}
|
||||
```
|
||||
|
||||
The `inherited` block is populated by the backend from the resolved
|
||||
model capabilities at response time — it is not stored on the persona.
|
||||
If the underlying model's capabilities change (e.g. provider upgrades
|
||||
context window), the persona inherits the new values automatically.
|
||||
The frontend uses `inherited` to render capability pills and context
|
||||
size badges identical to the raw model.
|
||||
|
||||
### Personal Personas
|
||||
|
||||
Gated by `allow_user_personas` policy.
|
||||
|
||||
```
|
||||
GET /personas → { "personas": [...] }
|
||||
POST /personas ← { "name", "description", "system_prompt", "model", ... }
|
||||
PUT /personas/:id ← partial update
|
||||
DELETE /personas/:id
|
||||
```
|
||||
|
||||
### Team Personas
|
||||
|
||||
```
|
||||
GET /teams/:teamId/personas → { "personas": [...] }
|
||||
POST /teams/:teamId/personas ← same shape
|
||||
PUT /teams/:teamId/personas/:id
|
||||
DELETE /teams/:teamId/personas/:id
|
||||
```
|
||||
|
||||
### Admin (Global) Personas
|
||||
|
||||
```
|
||||
GET /admin/personas → { "personas": [...] }
|
||||
POST /admin/personas ← same shape
|
||||
PUT /admin/personas/:id
|
||||
DELETE /admin/personas/:id
|
||||
```
|
||||
|
||||
### Persona KB Bindings
|
||||
|
||||
A Persona can have Knowledge Bases bound to it. When a channel uses
|
||||
that Persona, the bound KBs are automatically scoped into `kb_search`
|
||||
tool calls. Users never see or manage the underlying KBs directly —
|
||||
they talk to the Persona.
|
||||
|
||||
**Get bindings:**
|
||||
|
||||
```
|
||||
GET /personas/:id/knowledge-bases → { "data": [KB objects] }
|
||||
GET /teams/:teamId/personas/:id/knowledge-bases → { "data": [...] }
|
||||
GET /admin/personas/:id/knowledge-bases → { "data": [...] }
|
||||
```
|
||||
|
||||
**Set bindings** (replace all):
|
||||
|
||||
```
|
||||
PUT /personas/:id/knowledge-bases
|
||||
PUT /teams/:teamId/personas/:id/knowledge-bases
|
||||
PUT /admin/personas/:id/knowledge-bases
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"kb_ids": ["kb-uuid-1", "kb-uuid-2"],
|
||||
"auto_search": {
|
||||
"kb-uuid-1": true,
|
||||
"kb-uuid-2": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`auto_search`: when `true`, the KB is always searched (prepended to
|
||||
context). When `false`, it's available via the `kb_search` tool but
|
||||
not auto-injected.
|
||||
|
||||
### Persona Avatars
|
||||
|
||||
```
|
||||
POST /personas/:id/avatar ← multipart/form-data (field: "avatar")
|
||||
DELETE /personas/:id/avatar
|
||||
POST /admin/personas/:id/avatar
|
||||
DELETE /admin/personas/:id/avatar
|
||||
```
|
||||
|
||||
### Persona Tool Grants
|
||||
|
||||
Control which tools a persona can use during completions. The completion
|
||||
handler applies tool grants as a second-pass allowlist.
|
||||
|
||||
```
|
||||
GET /personas/:id/tool-grants → { "grants": ["web_search", "kb_search", ...] }
|
||||
PUT /personas/:id/tool-grants ← { "tool_ids": ["web_search", "calculator"] }
|
||||
```
|
||||
|
||||
Admin equivalents:
|
||||
|
||||
```
|
||||
GET /admin/personas/:id/tool-grants
|
||||
PUT /admin/personas/:id/tool-grants
|
||||
```
|
||||
|
||||
When a workflow version is published, persona tool grants at that moment
|
||||
are frozen into the version snapshot.
|
||||
|
||||
### Persona Groups
|
||||
|
||||
Saved roster templates. A persona group is a named set of personas that
|
||||
can be stamped onto new conversations.
|
||||
|
||||
```
|
||||
GET /persona-groups → { "data": [...] }
|
||||
POST /persona-groups ← { "name", "description", "scope", "team_id" }
|
||||
GET /persona-groups/:id → group with members
|
||||
PUT /persona-groups/:id ← partial update
|
||||
DELETE /persona-groups/:id
|
||||
```
|
||||
|
||||
**Members:**
|
||||
|
||||
```
|
||||
POST /persona-groups/:id/members ← { "persona_id", "is_leader": false, "sort_order": 0 }
|
||||
DELETE /persona-groups/:id/members/:memberId
|
||||
```
|
||||
|
||||
`is_leader`: the leader persona responds when no @mention is present in
|
||||
a group channel. Only one leader per group.
|
||||
|
||||
**Persona Group Object:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Support Team",
|
||||
"description": "...",
|
||||
"owner_id": "uuid",
|
||||
"scope": "personal|team|global",
|
||||
"team_id": "uuid|null",
|
||||
"members": [
|
||||
{ "id": "uuid", "persona_id": "uuid", "is_leader": true, "sort_order": 0 }
|
||||
],
|
||||
"created_at": "...",
|
||||
"updated_at": "..."
|
||||
}
|
||||
```
|
||||
|
||||
### Resource Grants
|
||||
|
||||
See [teams.md](teams.md) §15.3 for the grant system. Personas use grants
|
||||
to control who can see and use them beyond their base scope.
|
||||
|
||||
Reference in New Issue
Block a user