308 lines
12 KiB
Markdown
308 lines
12 KiB
Markdown
# Personas (Unified Agent Profiles)
|
|
|
|
[Top](../README.md) | [MMA](guide_mma.md) | [Tools & IPC](guide_tools.md) | [Architecture](guide_architecture.md)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
A **Persona** is a unified agent profile that consolidates the model choice, system prompt, tool preset, bias profile, context preset, and aggregation strategy into a single named, reusable entity. Personas eliminate the need to configure these settings individually per session or per Tier — the developer names a persona, and the entire configuration is applied atomically.
|
|
|
|
Personas are persisted in TOML files with **scope-based inheritance** (Global vs Project). The PersonaManager merges both scopes at load time, with project-level entries overriding global entries of the same name.
|
|
|
|
This guide covers:
|
|
|
|
1. **Data Model** — The `Persona` schema and its fields
|
|
2. **Storage & Scope** — Global and project TOML files, merge rules
|
|
3. **PersonaManager** — CRUD operations
|
|
4. **MMA Integration** — How personas are applied to workers
|
|
5. **Editor Modal** — The GUI for creating and editing personas
|
|
6. **Testing** — Test areas for persona behavior
|
|
|
|
---
|
|
|
|
## Data Model
|
|
|
|
### `Persona` (`src/models.py:704`)
|
|
|
|
```python
|
|
class Persona:
|
|
name: str
|
|
preferred_models: List[Dict[str, Any]] = field(default_factory=list)
|
|
system_prompt: str = ''
|
|
tool_preset: Optional[str] = None
|
|
bias_profile: Optional[str] = None
|
|
context_preset: Optional[str] = None
|
|
aggregation_strategy: Optional[str] = None
|
|
```
|
|
|
|
| Field | Type | Purpose |
|
|
|---|---|---|
|
|
| `name` | `str` | Unique identifier. Used as the key in TOML. |
|
|
| `preferred_models` | `List[Dict]` | Ordered list of `{provider, model, temperature, top_p, max_output_tokens}` dicts. The first entry is the initial model; subsequent entries are escalation targets. |
|
|
| `system_prompt` | `str` | Replaces the default system prompt when this persona is active. |
|
|
| `tool_preset` | `Optional[str]` | Name of a `ToolPreset` to apply. See [guide_tools.md](guide_tools.md). |
|
|
| `bias_profile` | `Optional[str]` | Name of a `BiasProfile` to apply. See [guide_tools.md](guide_tools.md). |
|
|
| `context_preset` | `Optional[str]` | Name of a `ContextPreset` to apply for file selection. |
|
|
| `aggregation_strategy` | `Optional[str]` | One of `auto`, `full`, `summarize`, `skeleton`. Drives how files are aggregated for this persona. |
|
|
|
|
**Convenience Properties**:
|
|
|
|
```python
|
|
@property
|
|
def provider(self) -> Optional[str]:
|
|
if not self.preferred_models: return None
|
|
return self.preferred_models[0].get("provider")
|
|
|
|
@property
|
|
def model(self) -> Optional[str]:
|
|
if not self.preferred_models: return None
|
|
return self.preferred_models[0].get("model")
|
|
|
|
@property
|
|
def temperature(self) -> Optional[float]:
|
|
if not self.preferred_models: return None
|
|
return self.preferred_models[0].get("temperature")
|
|
|
|
# Similar: top_p, max_output_tokens
|
|
```
|
|
|
|
These read from `preferred_models[0]` (the primary model). The full escalation list is used by `multi_agent_conductor.run_worker_lifecycle` for retry-based model escalation.
|
|
|
|
### `preferred_models` Schema
|
|
|
|
Each entry in the list is a dict with optional keys:
|
|
|
|
```python
|
|
{
|
|
"provider": "gemini", # Required
|
|
"model": "gemini-3.1-pro-preview", # Required
|
|
"temperature": 0.0, # Optional, defaults to 0.0
|
|
"top_p": 1.0, # Optional, defaults to 1.0
|
|
"max_output_tokens": 8192, # Optional, defaults to provider default
|
|
}
|
|
```
|
|
|
|
The list is ordered: index 0 is the first attempt, index 1 is the first escalation, etc. The ConductorEngine's model escalation logic iterates this list on retry.
|
|
|
|
---
|
|
|
|
## Storage & Scope
|
|
|
|
### File Locations
|
|
|
|
| Scope | Path | Configured By |
|
|
|---|---|---|
|
|
| Global | `<user_config>/personas.toml` | `src/paths.py:get_global_personas_path()` |
|
|
| Project | `<project_root>/personas.toml` | `src/paths.py:get_project_personas_path(project_root)` |
|
|
|
|
Both files use the same TOML schema:
|
|
|
|
```toml
|
|
[personas.<name>]
|
|
preferred_models = [
|
|
{ provider = "gemini", model = "gemini-3.1-pro-preview", temperature = 0.0 },
|
|
{ provider = "gemini", model = "gemini-3-flash-preview", temperature = 0.0 },
|
|
]
|
|
system_prompt = "You are a senior backend engineer with deep knowledge of Python asyncio."
|
|
tool_preset = "read_only"
|
|
bias_profile = "discovery_heavy"
|
|
context_preset = "codebase_full"
|
|
aggregation_strategy = "summarize"
|
|
```
|
|
|
|
### Scope Inheritance
|
|
|
|
`PersonaManager.load_all()` merges global and project personas:
|
|
|
|
1. Load global personas first.
|
|
2. If `project_root` is set, load project personas and **overwrite** entries with matching names.
|
|
3. Return the merged dict.
|
|
|
|
**Example**: If `personas.toml` (global) has a `code_reviewer` persona and `personas.toml` (project) also has a `code_reviewer` persona, the project version wins. This allows projects to override global defaults without losing the global fallback.
|
|
|
|
### Scope Lookup
|
|
|
|
`get_persona_scope(name)` returns `"global"` or `"project"` based on which file contains the persona. Used by the editor modal to show the user where a persona is defined.
|
|
|
|
### Save / Delete
|
|
|
|
- `save_persona(persona, scope="project")` writes the persona to the specified scope's TOML file.
|
|
- `delete_persona(name, scope="project")` removes the entry.
|
|
- The default scope for both is `"project"`. Use `"global"` for application-wide personas.
|
|
|
|
---
|
|
|
|
## PersonaManager
|
|
|
|
`PersonaManager` is the CRUD interface.
|
|
|
|
```python
|
|
from src.personas import PersonaManager
|
|
from src.models import Persona
|
|
|
|
manager = PersonaManager(project_root=Path("/path/to/project"))
|
|
all_personas = manager.load_all() # Merged global + project
|
|
manager.save_persona(my_persona, scope="project")
|
|
manager.delete_persona("old_persona", scope="project")
|
|
scope = manager.get_persona_scope("code_reviewer")
|
|
```
|
|
|
|
### `load_all()`
|
|
|
|
Returns a `Dict[str, Persona]` mapping name to Persona. Project entries override global entries of the same name.
|
|
|
|
### `save_persona(persona, scope)`
|
|
|
|
Writes a Persona to the specified scope's TOML file. If the file doesn't exist, it's created (parent directories included). If the file exists, the entry is added or updated; other entries are preserved.
|
|
|
|
### `delete_persona(name, scope)`
|
|
|
|
Removes the named entry from the specified scope's TOML file. If the entry doesn't exist, the operation is a no-op.
|
|
|
|
### `get_persona_scope(name)`
|
|
|
|
Returns `"global"` or `"project"` based on which file contains the persona. Returns `"project"` if neither (effectively saying "would be saved to project if you save").
|
|
|
|
### Internal Helpers
|
|
|
|
- `_load_file(path) -> Dict[str, Any]`: Reads a TOML file, returns `{}` on error or missing file.
|
|
- `_save_file(path, data)`: Writes a TOML file using `tomli_w`. Creates parent directories as needed.
|
|
|
|
---
|
|
|
|
## MMA Integration
|
|
|
|
When a `Ticket` has `persona_id` set, or when a Tier has a default persona, the ConductorEngine applies the persona to the worker. See [guide_mma.md#persona-application](guide_mma.md#persona-application) for the full integration details.
|
|
|
|
**Application order** (in `run_worker_lifecycle`):
|
|
|
|
1. **Model selection**:
|
|
- `ticket.model_override` (if set) — used unconditionally
|
|
- Persona `preferred_models[0]` (if persona applied) — initial model
|
|
- Default tier model — fallback
|
|
2. **System prompt**: `ai_client.set_custom_system_prompt(persona.system_prompt)` replaces the default.
|
|
3. **Bias profile**: `ai_client.set_bias_profile(persona.bias_profile)` applies semantic nudging.
|
|
4. **Tool preset**: `ai_client.set_tool_preset(persona.tool_preset)` configures enabled tools.
|
|
5. **Aggregation strategy**: Used by the `aggregate.py` pipeline to choose `full`/`summarize`/`skeleton`.
|
|
|
|
**Failure handling**: If the persona fails to load (file not found, parse error, missing fields), the worker logs a warning and falls back to the default model list. The persona is **not** a hard failure point.
|
|
|
|
### Tier-Scoped vs Ticket-Scoped Personas
|
|
|
|
- **Tier-scoped**: Set in `tier_usage[<tier>]["persona"]`. Applied to every worker for that tier when no ticket-level persona is set.
|
|
- **Ticket-scoped**: Set in `ticket.persona_id`. Overrides tier-level for that specific ticket.
|
|
|
|
---
|
|
|
|
## Editor Modal
|
|
|
|
The GUI provides a Persona Editor modal (`src/gui_2.py:_render_persona_editor_modal` or similar) for creating and editing personas without manually editing TOML.
|
|
|
|
**Fields exposed in the modal**:
|
|
- Name (text input, required)
|
|
- Preferred Models (editable list, with provider/model/temperature/top_p/max_output_tokens per entry)
|
|
- System Prompt (multi-line text input)
|
|
- Tool Preset (dropdown of available presets)
|
|
- Bias Profile (dropdown)
|
|
- Context Preset (dropdown)
|
|
- Aggregation Strategy (radio buttons: auto / full / summarize / skeleton)
|
|
- Scope (radio: Global / Project)
|
|
|
|
**Actions**:
|
|
- **Save** — Writes the persona to the selected scope.
|
|
- **Delete** — Removes the persona (with confirmation).
|
|
- **Duplicate** — Creates a copy with a new name.
|
|
- **Cancel** — Discards changes.
|
|
|
|
The modal validates the name (must be unique, must be a valid TOML key) and the model entries (provider and model are required) before allowing save.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Personas are project-scoped (or global) configuration. There is no central `config.toml` setting for personas themselves; they're standalone TOML files.
|
|
|
|
**Related settings** (in `manual_slop.toml` or `config.toml`):
|
|
|
|
```toml
|
|
[mma]
|
|
default_personas = {
|
|
"Tier 1": "orchestrator",
|
|
"Tier 2": "tech_lead",
|
|
"Tier 3": "code_worker",
|
|
"Tier 4": "qa_reviewer",
|
|
}
|
|
```
|
|
|
|
This sets the default persona for each tier. Tickets without `persona_id` use the tier's default.
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### Unit Tests
|
|
|
|
- `tests/test_persona_manager.py` — `PersonaManager` CRUD, scope merging, file I/O
|
|
- `tests/test_persona_models.py` — `Persona` serialization/deserialization
|
|
- `tests/test_persona_id.py` — `Persona` ID validation and uniqueness
|
|
|
|
### Integration Tests
|
|
|
|
- `tests/test_mma_prompts.py` — Verifies persona-derived prompts are constructed correctly
|
|
- `tests/test_bias_efficacy.py` — Verifies bias profile integration
|
|
|
|
### Test Pattern
|
|
|
|
```python
|
|
def test_persona_scope_overrides(tmp_path):
|
|
# Global persona
|
|
global_path = tmp_path / "global_personas.toml"
|
|
global_path.write_text("""
|
|
[personas.coder]
|
|
system_prompt = "Global: code only."
|
|
""")
|
|
|
|
# Project persona (override)
|
|
project_path = tmp_path / "personas.toml"
|
|
project_path.write_text("""
|
|
[personas.coder]
|
|
system_prompt = "Project: code only, focus on our domain."
|
|
""")
|
|
|
|
manager = PersonaManager(project_root=tmp_path, ...)
|
|
# Patch paths module to return the test paths
|
|
with patch("src.paths.get_global_personas_path", return_value=global_path), \
|
|
patch("src.paths.get_project_personas_path", return_value=project_path):
|
|
all_personas = manager.load_all()
|
|
|
|
assert "coder" in all_personas
|
|
assert all_personas["coder"].system_prompt == "Project: code only, focus on our domain."
|
|
```
|
|
|
|
---
|
|
|
|
## Limitations
|
|
|
|
1. **No Versioning**: Personas are stored in TOML. Changes are not versioned unless the project uses git (which most do, but the persona changes are buried in diffs). Consider a "persona history" feature for future.
|
|
|
|
2. **No Inheritance Chains**: A persona cannot reference another persona as a base. If a project wants to share settings across multiple personas, it must duplicate them.
|
|
|
|
3. **No Validation of Referenced Names**: A persona can name a `tool_preset` that doesn't exist. The error surfaces only when the worker tries to apply the persona.
|
|
|
|
4. **No Live Reload**: Changing a persona TOML file does not take effect until the application is restarted (or `PersonaManager.load_all()` is called again).
|
|
|
|
5. **No Conflict Resolution UI**: If a project and global define different personas with the same name, the project wins silently. The user must check the editor modal to see the actual definition.
|
|
|
|
---
|
|
|
|
## Future Work
|
|
|
|
- **Persona Composition** — Allow a persona to reference another as a base, with override semantics.
|
|
- **Live Reload** — Watch the persona TOML files and reload on change.
|
|
- **Persona History** — Track changes over time, allow rollback.
|
|
- **Conflict Resolution UI** — When global and project both define a persona, show both in the editor with a "use global" / "use project" / "merge" choice.
|
|
- **Persona Templates** — Pre-built personas for common roles (code reviewer, test writer, doc writer) that users can clone.
|
|
|
|
See [guide_mma.md#persona-application](guide_mma.md#persona-application) for the worker-side integration.
|