DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""
PersonaService
==============
Loads user-authored PERSONA.md files from ``data/user/workspace/personas/``.
Personas belong to the account, not to a content workspace: a response style
is part of how the learner is talked to, and it is the same in every
workspace. Personas that were once written inside a workspace are adopted
into the account on first access.
A persona is a behaviour/voice preset ("teacher", "peer", …) the user picks
for a conversation. Unlike capability skills (see
:mod:`deeptutor.services.skill`), a persona must shape the model's voice from
the very first token, so the selected persona's body is injected verbatim
into the system prompt — eagerly, never on demand. Exactly one persona can
be active per turn.
Each persona lives in its own directory:
data/user/workspace/personas/<name>/PERSONA.md
The file starts with a YAML frontmatter block holding ``name`` and
``description``, followed by the Markdown body that becomes the system-prompt
block when the persona is active.
Legacy migration: persona-type entries that historically lived in the skills
workspace (``peer`` / ``teacher`` / ``research-assistant``) are moved into the
personas root on first service access for a workspace.
"""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
import re
import shutil
from typing import Any
import yaml
from deeptutor.multi_user.paths import get_account_path_service
_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
PERSONA_FILE = "PERSONA.md"
# Bundled default personas shipped inside the package (see
# ``pyproject.toml`` package-data ``**/*.md``). Seeded into the admin workspace
# on first run so fresh installs expose them as read-only presets (issue #659).
PRESETS_DIR = Path(__file__).resolve().parent / "presets"
# Product-seeded persona skills that predate the persona/skill split. Only
# these well-known names are migrated automatically — arbitrary user skills
# cannot be classified safely and stay where they are.
LEGACY_PERSONA_SKILLS: tuple[str, ...] = ("peer", "teacher", "research-assistant")
@dataclass(slots=True)
class PersonaInfo:
name: str
description: str
source: str = "user" # "user" | "admin"
def to_dict(self) -> dict[str, Any]:
return {
"name": self.name,
"description": self.description,
"source": self.source,
"read_only": self.source != "user",
}
@dataclass(slots=True)
class PersonaDetail:
name: str
description: str
content: str
source: str = "user"
def to_dict(self) -> dict[str, Any]:
return {
"name": self.name,
"description": self.description,
"content": self.content,
"source": self.source,
"read_only": self.source != "user",
}
class PersonaNotFoundError(Exception):
pass
class PersonaExistsError(Exception):
pass
class InvalidPersonaNameError(Exception):
pass
class PersonaService:
"""CRUD + context rendering for PERSONA.md files under one workspace."""
def __init__(self, root: Path | None = None) -> None:
self._root = root or (get_account_path_service().get_workspace_dir() / "personas")
@property
def root(self) -> Path:
return self._root
# ── path helpers ────────────────────────────────────────────────────
def _validate_name(self, name: str) -> str:
candidate = (name or "").strip().lower()
if not _NAME_RE.match(candidate):
raise InvalidPersonaNameError("Persona name must match ^[a-z0-9][a-z0-9-]{0,63}$")
return candidate
def _persona_dir(self, name: str) -> Path:
return self._root / self._validate_name(name)
def _persona_file(self, name: str) -> Path:
return self._persona_dir(name) / PERSONA_FILE
# ── parsing ─────────────────────────────────────────────────────────
@staticmethod
def _parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
match = _FRONTMATTER_RE.match(content)
if not match:
return {}, content
raw = match.group(1)
body = content[match.end() :]
try:
data = yaml.safe_load(raw) or {}
except yaml.YAMLError:
data = {}
if not isinstance(data, dict):
data = {}
return data, body
@staticmethod
def _render_frontmatter(name: str, description: str) -> str:
header = yaml.safe_dump(
{"name": name, "description": description.strip()},
sort_keys=False,
allow_unicode=True,
).strip()
return f"---\n{header}\n---"
def _normalize_content(self, name: str, description: str, content: str) -> str:
"""Ensure the saved file carries exactly ``name`` + ``description`` frontmatter."""
_, body = self._parse_frontmatter(content or "")
header = self._render_frontmatter(name, description)
return f"{header}\n\n{body.lstrip()}".rstrip() + "\n"
# ── public read API ─────────────────────────────────────────────────
def list_personas(self) -> list[PersonaInfo]:
if not self._root.exists():
return []
out: list[PersonaInfo] = []
for entry in sorted(self._root.iterdir()):
if not entry.is_dir():
continue
file = entry / PERSONA_FILE
if not file.exists():
continue
try:
text = file.read_text(encoding="utf-8")
except OSError:
continue
meta, _ = self._parse_frontmatter(text)
out.append(
PersonaInfo(
name=entry.name,
description=str(meta.get("description") or "").strip(),
)
)
return out
def get_detail(self, name: str) -> PersonaDetail:
file = self._persona_file(name)
if not file.exists():
raise PersonaNotFoundError(name)
text = file.read_text(encoding="utf-8")
meta, _ = self._parse_frontmatter(text)
return PersonaDetail(
name=self._validate_name(name),
description=str(meta.get("description") or "").strip(),
content=text,
)
def load_for_context(self, name: str) -> str:
"""Render the selected persona into the system-prompt block.
Returns ``""`` when the persona doesn't exist or has an empty body —
a missing persona must never break the turn.
"""
if not name:
return ""
try:
detail = self.get_detail(name)
except (PersonaNotFoundError, InvalidPersonaNameError):
return ""
_, body = self._parse_frontmatter(detail.content)
body = body.strip()
if not body:
return ""
# The scope sentence has to name capability playbooks, because they are
# what a persona actually competes with. Mastery Path's playbook runs
# 600 words and prescribes its own tone ("be warm and encouraging"),
# sits above this block, and is plainly not a "generic style default" —
# so a persona claiming only those was read as the weaker instruction
# and the tutor stayed a stock teacher no matter what was written (#793).
return (
"## Active Persona\n"
"Embody the persona below for this entire conversation. It sets your "
"voice and outranks any tone a mode above prescribes; carry out that "
"mode's steps in this voice.\n\n"
f"### Persona: {detail.name}\n\n{body}"
)
# ── public write API ────────────────────────────────────────────────
def create(self, name: str, description: str, content: str) -> PersonaInfo:
slug = self._validate_name(name)
target_dir = self._persona_dir(slug)
if target_dir.exists():
raise PersonaExistsError(slug)
body = self._normalize_content(slug, description, content)
target_dir.mkdir(parents=True, exist_ok=False)
self._persona_file(slug).write_text(body, encoding="utf-8")
return PersonaInfo(name=slug, description=description.strip())
def update(
self,
name: str,
*,
description: str | None = None,
content: str | None = None,
rename_to: str | None = None,
) -> PersonaInfo:
slug = self._validate_name(name)
target_dir = self._persona_dir(slug)
if not target_dir.exists():
raise PersonaNotFoundError(slug)
current = self.get_detail(slug)
new_description = description if description is not None else current.description
new_body_source = content if content is not None else current.content
if rename_to and rename_to != slug:
new_slug = self._validate_name(rename_to)
new_dir = self._persona_dir(new_slug)
if new_dir.exists():
raise PersonaExistsError(new_slug)
target_dir.rename(new_dir)
slug = new_slug
text = self._normalize_content(slug, new_description, new_body_source)
self._persona_file(slug).write_text(text, encoding="utf-8")
return PersonaInfo(name=slug, description=new_description.strip())
def delete(self, name: str) -> None:
slug = self._validate_name(name)
target_dir = self._persona_dir(slug)
if not target_dir.exists():
raise PersonaNotFoundError(slug)
shutil.rmtree(target_dir)
# ── default-preset seeding ──────────────────────────────────────────
def seed_presets(self) -> list[str]:
"""Copy bundled default personas into this root for any missing name.
Idempotent and non-destructive: a persona that already exists (a user
edit or a prior seed) is never overwritten. Seeding the admin workspace
makes ``peer`` / ``teacher`` / ``research-assistant`` appear as
read-only presets on fresh installs (issue #659). Returns seeded names.
"""
if not PRESETS_DIR.is_dir():
return []
seeded: list[str] = []
for preset_dir in sorted(PRESETS_DIR.iterdir()):
source_file = preset_dir / PERSONA_FILE
if not preset_dir.is_dir() or not source_file.exists():
continue
try:
name = self._validate_name(preset_dir.name)
except InvalidPersonaNameError:
continue
if self._persona_dir(name).exists():
continue
try:
text = source_file.read_text(encoding="utf-8")
except OSError:
continue
target_dir = self._persona_dir(name)
target_dir.mkdir(parents=True, exist_ok=True)
self._persona_file(name).write_text(text, encoding="utf-8")
seeded.append(name)
return seeded
# ── legacy migration ────────────────────────────────────────────────
def migrate_legacy_skills(self, skills_root: Path) -> list[str]:
"""Move product-seeded persona skills out of the skills workspace.
For each well-known legacy name: ``skills/<name>/SKILL.md`` becomes
``personas/<name>/PERSONA.md`` with frontmatter reduced to
``name`` + ``description`` (legacy ``triggers``/``tags`` keys are
dropped — keyword routing is retired). Idempotent: names that are
absent in the skills root or already present in the personas root
are skipped.
Returns the list of migrated names.
"""
migrated: list[str] = []
for name in LEGACY_PERSONA_SKILLS:
source_file = skills_root / name / "SKILL.md"
if not source_file.exists():
continue
if self._persona_dir(name).exists():
continue
try:
text = source_file.read_text(encoding="utf-8")
except OSError:
continue
meta, body = self._parse_frontmatter(text)
description = str(meta.get("description") or "").strip()
self._root.mkdir(parents=True, exist_ok=True)
target_dir = self._persona_dir(name)
target_dir.mkdir(parents=True, exist_ok=True)
self._persona_file(name).write_text(
self._normalize_content(name, description, body),
encoding="utf-8",
)
shutil.rmtree(source_file.parent)
migrated.append(name)
return migrated
_instances: dict[str, PersonaService] = {}
def _adopt_workspace_personas(root: Path) -> None:
"""Personas were once stored per workspace; bring them into the account once.
A name the account already uses keeps the account's persona; the workspace
copy is left where it was rather than overwritten or lost.
"""
from deeptutor.services.workspace import get_content_workspace_service
from deeptutor.services.workspace.context import workspace_context
from deeptutor.services.workspace.models import WorkspaceError
for row in get_content_workspace_service().list_workspaces():
if row["kind"] != "workspace" or row["status"] != "ready":
continue
try:
with workspace_context(row["workspace_id"]):
from deeptutor.multi_user.paths import get_current_path_service
legacy = get_current_path_service().get_workspace_dir() / "personas"
except WorkspaceError:
continue
if legacy.resolve() == root or not legacy.is_dir():
continue
for directory in legacy.iterdir():
if directory.is_dir() and not (root / directory.name).exists():
root.mkdir(parents=True, exist_ok=True)
shutil.move(str(directory), str(root / directory.name))
def get_persona_service() -> PersonaService:
"""Return the PersonaService for the active account.
First access for an account also runs the one-shot legacy migrations:
persona-type skills (see :meth:`PersonaService.migrate_legacy_skills`) and
personas written inside a content workspace. Both are idempotent.
"""
workspace = get_account_path_service().get_workspace_dir()
root = (workspace / "personas").resolve()
key = str(root)
if key not in _instances:
service = PersonaService(root=root)
service.migrate_legacy_skills(workspace / "skills")
_adopt_workspace_personas(root)
_instances[key] = service
return _instances[key]
def load_visible_for_context(
name: str,
*,
workspace: PersonaService | None = None,
admin: PersonaService | None = None,
) -> str:
"""Render a persona from the account, then admin presets.
Admin presets are a read-only overlay visible to every role — including an
admin whose own ``personas/`` directory is empty.
"""
if not name:
return ""
text = (workspace or get_persona_service()).load_for_context(name)
if text:
return text
if admin is None:
from deeptutor.multi_user.paths import get_admin_path_service
admin = PersonaService(root=get_admin_path_service().get_workspace_dir() / "personas")
return admin.load_for_context(name)
__all__ = [
"InvalidPersonaNameError",
"LEGACY_PERSONA_SKILLS",
"PERSONA_FILE",
"PersonaDetail",
"PersonaExistsError",
"PersonaInfo",
"PersonaNotFoundError",
"PersonaService",
"get_persona_service",
"load_visible_for_context",
]