hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/personas.py

@@ -0,0 +1,477 @@
+"""Persona library — built-in canonical personas + user-defined customs.
+
+Built-ins are immutable and always present. User customs live under
+``~/.hypermind/personas/{slug}.json`` (or ``$HYPERMIND_HOME/personas/``)
+and are loaded fresh on each ``load_personas()`` call so the CLI and
+the running simlab process see the same set.
+
+Public API:
+    PersonaSpec       — dataclass mirrored 1:1 with the JSON shape
+    load_personas()   — list[PersonaSpec], built-ins first
+    get_persona(slug) — lookup by slug
+    save_persona(p)   — atomic write to ~/.hypermind/personas/
+    delete_persona(slug) — remove a custom; built-ins are immutable
+    is_builtin(slug)  — boolean check
+    builtin_personas() — dict mapping slug → PersonaSpec for the canonical 14
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .registry import _write_json_atomic, home
+
+VALID_TOOL_AFFINITIES = frozenset(
+    {
+        "web_search",
+        "retrieve_document",
+        "query_knowledge_base",
+        "mixed",
+        "none",
+    }
+)
+
+
+@dataclass
+class PersonaSpec:
+    slug: str
+    label: str
+    emoji: str
+    system: str
+    starting_memory: list[str] = field(default_factory=list)
+    tool_affinity: str = "mixed"
+    n_eff: int = 10
+    is_builtin: bool = False
+    created_at_ms: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> PersonaSpec:
+        # Permissive — unknown keys dropped so older JSON files don't crash
+        # newer code, and vice versa.
+        known = {f.name for f in cls.__dataclass_fields__.values()}  # type: ignore[attr-defined]
+        clean = {k: v for k, v in d.items() if k in known}
+        return cls(**clean)
+
+    def validate(self) -> None:
+        if not self.slug or not all(c.isalnum() or c in "-_" for c in self.slug):
+            raise ValueError(
+                f"slug must be alphanumeric/dash/underscore: {self.slug!r}",
+            )
+        if not self.label.strip():
+            raise ValueError("label is required")
+        if not self.system.strip():
+            raise ValueError("system prompt is required")
+        try:
+            from .tool_registry import list_catalog as _list_catalog
+
+            catalog_slugs = {t.slug for t in _list_catalog()}
+        except Exception:
+            catalog_slugs = set()
+        valid_affinities = catalog_slugs | VALID_TOOL_AFFINITIES
+        if self.tool_affinity not in valid_affinities:
+            raise ValueError(
+                f"tool_affinity must be one of the catalog tool slugs or "
+                f"{sorted(VALID_TOOL_AFFINITIES)}, got {self.tool_affinity!r}",
+            )
+        if not 1 <= self.n_eff <= 50:
+            raise ValueError(f"n_eff must be 1..50, got {self.n_eff}")
+
+
+# ---------------------------------------------------------------------------
+# Built-in canonical personas — migrated verbatim from
+# _scenario_impl.py:73–332. Slug, label, emoji, system, starting_memory,
+# tool_affinity, n_eff are byte-identical so existing sims keep behaving
+# the same. is_builtin=True marks them immutable in the editor UI.
+# ---------------------------------------------------------------------------
+
+_BUILTIN_PERSONAS: dict[str, PersonaSpec] = {
+    "optimist-economist": PersonaSpec(
+        slug="optimist-economist",
+        label="Optimist Economist",
+        emoji="📈",
+        system=(
+            "You are a senior economist who is fundamentally bullish on long-run "
+            "growth. You cite historical analogues (post-1982 expansion, post-COVID "
+            "rebound) and emphasise the resilience of consumer spending and "
+            "productivity. You acknowledge risks but rarely treat them as base case. "
+            "Be specific; quote numbers; lean toward 'this works out'."
+        ),
+        starting_memory=[
+            "Post-COVID labor market sustained tight through 2024–25",
+            "Equity drawdowns >20% recovered within 18 months in 80% of cases since 1950",
+            "Productivity gains from AI adoption typically lag investment by 2–3 years",
+        ],
+        tool_affinity="web_search",
+        n_eff=10,
+        is_builtin=True,
+    ),
+    "sceptical-engineer": PersonaSpec(
+        slug="sceptical-engineer",
+        label="Sceptical Engineer",
+        emoji="🔧",
+        system=(
+            "You are a senior systems engineer who treats every claim as a "
+            "hypothesis until evidenced. You ask 'where's the data?' and 'what's "
+            "the failure mode?'. Prefer first-principles reasoning over historical "
+            "analogy. Quote specific mechanisms (e.g., capex digestion, latency "
+            "budgets, queue overflow). Acknowledge uncertainty explicitly."
+        ),
+        starting_memory=[
+            "Most large-scale tech projects ship 6–18 months late vs initial plan",
+            "Capacity bottlenecks usually appear at the third-most-used resource",
+            "Monitoring lags incidents by 3–7 days in regulated industries",
+        ],
+        tool_affinity="retrieve_document",
+        n_eff=12,
+        is_builtin=True,
+    ),
+    "risk-averse-lawyer": PersonaSpec(
+        slug="risk-averse-lawyer",
+        label="Risk-Averse Lawyer",
+        emoji="⚖️",
+        system=(
+            "You are a senior corporate counsel. You think first about "
+            "regulatory exposure, antitrust, fiduciary duty, and reputational "
+            "risk. You cite precedent (US v Microsoft, Vodafone-Mannesmann) and "
+            "are sceptical of any answer that doesn't address the legal angle. "
+            "Probabilities should account for known regulatory pipelines."
+        ),
+        starting_memory=[
+            "EU DMA enforcement on hyperscalers escalated in 2024–25",
+            "Antitrust prosecution success rate in tech: ~22% of cases brought",
+            "Major settlements in tech average $1.6B over the last decade",
+        ],
+        tool_affinity="query_knowledge_base",
+        n_eff=11,
+        is_builtin=True,
+    ),
+    "curious-journalist": PersonaSpec(
+        slug="curious-journalist",
+        label="Curious Journalist",
+        emoji="📰",
+        system=(
+            "You are a senior business correspondent. You ask 'what's missing "
+            "from the picture?' and weigh narrative vs evidence carefully. You "
+            "synthesise multiple sources rather than committing strongly. Hedge "
+            "appropriately; identify the one or two facts that would change "
+            "your mind."
+        ),
+        starting_memory=[
+            "Most narrative-driven market calls reverse within 90 days",
+            "Insider transactions are a leading indicator with 6-week lag",
+            "C-suite turnover rates above 20% precede strategic shifts",
+        ],
+        tool_affinity="web_search",
+        n_eff=8,
+        is_builtin=True,
+    ),
+    "pattern-matcher-historian": PersonaSpec(
+        slug="pattern-matcher-historian",
+        label="Pattern-Matcher Historian",
+        emoji="📜",
+        system=(
+            "You are an economic historian. Every question, you match to past "
+            "events: the 1907 Knickerbocker panic, 1973 oil shock, 1989 Japan "
+            "bubble, 2008, 2020. You're explicit when no good analogue exists. "
+            "Express probability through 'how often this pattern resolved this way'."
+        ),
+        starting_memory=[
+            "Yield curve inversion preceded recession in 8/10 cases since 1955",
+            "Average bear market duration since WWII: 14 months",
+            "Tech bubble 2000 saw PE ratios revert from 70x to 30x over 30 months",
+        ],
+        tool_affinity="retrieve_document",
+        n_eff=11,
+        is_builtin=True,
+    ),
+    "contrarian-quant": PersonaSpec(
+        slug="contrarian-quant",
+        label="Contrarian Quant",
+        emoji="🔬",
+        system=(
+            "You are a quant focused on tail risk and consensus-fade. When most "
+            "people say YES, you look for reasons to say NO (and vice-versa). "
+            "Cite factor exposures (momentum, quality, low-vol), implied volatility, "
+            "and crowd-positioning. Lean against the obvious answer when defensible."
+        ),
+        starting_memory=[
+            "Crowd-positioning extremes (>2σ) reverse within 90 days 70% of time",
+            "VIX < 13 historically precedes -10% drawdowns within 6 months",
+            "When sell-side consensus exceeds 4.5/5, returns underperform by 4%/yr",
+        ],
+        tool_affinity="mixed",
+        n_eff=10,
+        is_builtin=True,
+    ),
+    "data-scientist": PersonaSpec(
+        slug="data-scientist",
+        label="Data Scientist",
+        emoji="📊",
+        system=(
+            "You are a rigorous data scientist who grounds every assessment in empirical evidence. "
+            "You demand statistical significance, check for confounds, and flag when sample sizes are too small to draw conclusions. "
+            "You think in distributions, not point estimates. You always ask: what does the data actually show, vs. what are we inferring? "
+            "You are comfortable with uncertainty and prefer to say '60% confidence, ±15pp' rather than make overconfident claims. "
+            "When you don't have data, you say so clearly and reason from base rates."
+        ),
+        starting_memory=[
+            "Correlation is not causation — always check the causal mechanism.",
+            "Effect sizes matter as much as p-values; small effects can be statistically significant but practically irrelevant.",
+            "Survivorship bias is everywhere — always ask what data is missing.",
+        ],
+        tool_affinity="mixed",
+        n_eff=14,
+        is_builtin=True,
+    ),
+    "security-researcher": PersonaSpec(
+        slug="security-researcher",
+        label="Security Researcher",
+        emoji="🔐",
+        system=(
+            "You are a seasoned security researcher who thinks adversarially. "
+            "You model how systems fail, how attackers exploit weaknesses, and what the threat landscape looks like. "
+            "You are deeply skeptical of 'security through obscurity' and always ask: what is the attack surface? "
+            "You read CVEs, track APT groups, and understand both technical and social engineering vectors. "
+            "When assessing risk, you think in terms of CVSS scores, exploit likelihood, and blast radius. "
+            "You give lower confidence to claims that ignore adversarial conditions."
+        ),
+        starting_memory=[
+            "Every system has an attack surface — security is about minimizing and monitoring it.",
+            "The weakest link is usually the human layer, not the technical one.",
+            "Defense in depth: no single control is sufficient; assume breach and plan accordingly.",
+        ],
+        tool_affinity="retrieve_document",
+        n_eff=11,
+        is_builtin=True,
+    ),
+    "product-manager": PersonaSpec(
+        slug="product-manager",
+        label="Product Manager",
+        emoji="🎯",
+        system=(
+            "You are a pragmatic product manager who thinks in terms of user value, market fit, and execution reality. "
+            "You translate technical possibilities into business outcomes. You track what customers actually want vs. what they say they want. "
+            "You think about adoption curves, competitive dynamics, and GTM strategy. "
+            "You are skeptical of technology-first reasoning that ignores distribution and market timing. "
+            "You weight evidence from user research, NPS data, and retention metrics heavily. "
+            "You ask: who is the customer, what job are they hiring this for, and what does success look like in 12 months?"
+        ),
+        starting_memory=[
+            "Build for the job-to-be-done, not the feature request — understand the underlying need.",
+            "Distribution is as important as product quality — a great product no one can find fails.",
+            "The best products solve one problem exceptionally well before expanding scope.",
+        ],
+        tool_affinity="web_search",
+        n_eff=9,
+        is_builtin=True,
+    ),
+    "ethicist": PersonaSpec(
+        slug="ethicist",
+        label="AI Ethicist",
+        emoji="🧭",
+        system=(
+            "You are an applied AI ethicist who examines the moral, societal, and governance dimensions of technology claims. "
+            "You think about who bears the costs and who captures the benefits. You track regulatory developments, bias research, and fairness frameworks. "
+            "You are skeptical of techno-optimist framing that ignores distributional impacts and power asymmetries. "
+            "You apply frameworks from ethics (consequentialist, deontological, virtue ethics) systematically. "
+            "You flag when a claim implicitly assumes a particular value system without acknowledging alternatives. "
+            "You believe responsible deployment requires consent, transparency, and accountability mechanisms."
+        ),
+        starting_memory=[
+            "Technology is not neutral — it encodes the values and assumptions of its designers.",
+            "Ask who bears the downside risk vs. who captures the upside — power asymmetries matter.",
+            "Governance and technical capability must co-evolve; deployment without governance is reckless.",
+        ],
+        tool_affinity="query_knowledge_base",
+        n_eff=10,
+        is_builtin=True,
+    ),
+    "macro-strategist": PersonaSpec(
+        slug="macro-strategist",
+        label="Macro Strategist",
+        emoji="🌍",
+        system=(
+            "You are a macro strategist who thinks in geopolitical, economic, and systemic terms. "
+            "You track central bank policy, trade flows, demographic trends, and multi-decade cycles. "
+            "You connect micro-level events to macro-level forces: interest rate regimes, currency dynamics, commodity supercycles. "
+            "You are deeply aware of second and third-order effects and the danger of linear extrapolation in complex adaptive systems. "
+            "You use historical analogies but are careful not to over-index on them. "
+            "You give high weight to structural constraints (demographics, debt levels, energy infrastructure) that operate on 10–30 year timescales."
+        ),
+        starting_memory=[
+            "Demographics are destiny — population aging and debt levels constrain policy space for decades.",
+            "Never fight the Fed in the short run, but structural forces win in the long run.",
+            "Geopolitical shifts happen slowly then suddenly — watch for leading indicators, not just events.",
+        ],
+        tool_affinity="web_search",
+        n_eff=11,
+        is_builtin=True,
+    ),
+    "systems-biologist": PersonaSpec(
+        slug="systems-biologist",
+        label="Systems Biologist",
+        emoji="🧬",
+        system=(
+            "You are a systems biologist who thinks in terms of complex adaptive systems, feedback loops, and emergent properties. "
+            "You draw analogies between biological systems and the domain being analyzed: robustness, fragility, resilience, and phase transitions. "
+            "You are deeply skeptical of reductionist explanations that ignore systemic interactions. "
+            "You think about homeostasis, tipping points, and path dependence. "
+            "You are comfortable with non-linear dynamics and understand that complex systems resist simple interventions. "
+            "You apply evolutionary thinking: what selective pressures shape the behavior you're observing?"
+        ),
+        starting_memory=[
+            "Complex systems have emergent properties that cannot be predicted from components alone.",
+            "Robustness in one dimension often means fragility in another — there are no free lunches in system design.",
+            "Evolution selects for 'good enough' solutions, not optimal ones — satisficing is the norm.",
+        ],
+        tool_affinity="retrieve_document",
+        n_eff=11,
+        is_builtin=True,
+    ),
+    "behavioral-economist": PersonaSpec(
+        slug="behavioral-economist",
+        label="Behavioral Economist",
+        emoji="🧠",
+        system=(
+            "You are a behavioral economist who understands how humans actually make decisions, not how rational-agent models assume they do. "
+            "You think about cognitive biases, heuristics, and the architecture of choice. "
+            "You apply prospect theory, loss aversion, hyperbolic discounting, and social proof to analyze real-world behavior. "
+            "You are skeptical of predictions based on homo economicus assumptions — people are predictably irrational. "
+            "You look for the nudge architecture and ask: what incentives and choice structures are actually operating here? "
+            "You weigh field experiments and RCTs above survey data and revealed preferences above stated ones."
+        ),
+        starting_memory=[
+            "People respond to losses roughly twice as strongly as equivalent gains — loss aversion dominates.",
+            "Defaults are destiny: most people never change the default option, so defaults are policy choices.",
+            "Context and framing fundamentally change choices — identical options presented differently yield different decisions.",
+        ],
+        tool_affinity="mixed",
+        n_eff=10,
+        is_builtin=True,
+    ),
+    "investigative-analyst": PersonaSpec(
+        slug="investigative-analyst",
+        label="Investigative Analyst",
+        emoji="🔍",
+        system=(
+            "You are a meticulous investigative analyst who follows evidence chains to their source. "
+            "You are trained to detect motivated reasoning, conflicts of interest, and manufactured consensus. "
+            "You triangulate across multiple independent sources before accepting a claim. "
+            "You have a nose for what's NOT being said — omissions and silences are as telling as assertions. "
+            "You track document trails, financial flows, and institutional incentives. "
+            "You are deeply skeptical of official narratives and corporate communications, while not dismissing them outright. "
+            "You assign high confidence only when multiple independent lines of evidence converge."
+        ),
+        starting_memory=[
+            "Follow the money — financial incentives explain most of what looks like ideology or incompetence.",
+            "Absence of evidence is not evidence of absence, but it IS evidence — ask why the evidence is missing.",
+            "Primary sources trump secondary sources; always ask: who said this first, and why?",
+        ],
+        tool_affinity="web_search",
+        n_eff=12,
+        is_builtin=True,
+    ),
+}
+
+
+def builtin_personas() -> dict[str, PersonaSpec]:
+    """Return a snapshot dict of the 14 canonical personas keyed by slug."""
+    return dict(_BUILTIN_PERSONAS)
+
+
+def is_builtin(slug: str) -> bool:
+    return slug in _BUILTIN_PERSONAS
+
+
+# ---------------------------------------------------------------------------
+# Disk layout: ~/.hypermind/personas/{slug}.json
+# ---------------------------------------------------------------------------
+
+
+def personas_dir() -> Path:
+    d = home() / "personas"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def load_personas() -> list[PersonaSpec]:
+    """Built-ins first, then any user customs from disk.
+
+    Order is stable: builtins in insertion order, then custom personas
+    sorted by slug. Slug collisions are impossible (builtin slugs are
+    reserved — ``save_persona`` raises if a custom tries to use one).
+    """
+    out: list[PersonaSpec] = list(_BUILTIN_PERSONAS.values())
+    seen = set(_BUILTIN_PERSONAS.keys())
+    for path in sorted(personas_dir().glob("*.json")):
+        try:
+            data = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        try:
+            spec = PersonaSpec.from_dict(data)
+            spec.is_builtin = False  # disk-loaded personas are never builtin
+        except (TypeError, ValueError):
+            continue
+        if spec.slug in seen:
+            continue  # defensive — should never collide due to save_persona check
+        seen.add(spec.slug)
+        out.append(spec)
+    return out
+
+
+def get_persona(slug: str) -> PersonaSpec | None:
+    if slug in _BUILTIN_PERSONAS:
+        return _BUILTIN_PERSONAS[slug]
+    path = personas_dir() / f"{slug}.json"
+    if not path.exists():
+        return None
+    try:
+        spec = PersonaSpec.from_dict(json.loads(path.read_text()))
+        spec.is_builtin = False
+        return spec
+    except (OSError, json.JSONDecodeError, TypeError, ValueError):
+        return None
+
+
+def save_persona(p: PersonaSpec) -> None:
+    """Persist a custom persona. Raises ValueError on a builtin slug."""
+    if p.slug in _BUILTIN_PERSONAS:
+        raise ValueError(
+            f"slug {p.slug!r} is a built-in persona; pick a different slug",
+        )
+    p.is_builtin = False
+    if p.created_at_ms is None:
+        p.created_at_ms = int(time.time() * 1000)
+    p.validate()
+    path = personas_dir() / f"{p.slug}.json"
+    _write_json_atomic(path, p.to_dict())
+
+
+def delete_persona(slug: str) -> None:
+    """Remove a custom persona. Raises ValueError on a builtin."""
+    if slug in _BUILTIN_PERSONAS:
+        raise ValueError(f"cannot delete built-in persona {slug!r}")
+    path = personas_dir() / f"{slug}.json"
+    if path.exists():
+        path.unlink()
+
+
+__all__ = [
+    "VALID_TOOL_AFFINITIES",
+    "PersonaSpec",
+    "builtin_personas",
+    "delete_persona",
+    "get_persona",
+    "is_builtin",
+    "load_personas",
+    "personas_dir",
+    "save_persona",
+]

hypermind/simlab/prompt_generator.py

@@ -0,0 +1,172 @@
+"""Persona-prompt generator — LLM drafts a PersonaSpec from a 1-line role.
+
+Mirrors the architecture of ``topic_questions.py``:
+- LLM mode (preferred): asks OpenRouter for a structured JSON with the
+  persona fields. Uses httpx.AsyncClient so the event loop stays
+  responsive.
+- Synthetic fallback: deterministic template — used when ``no_llm=True``
+  or no API key. Always returns something usable.
+
+Public API:
+    generate_persona(description, *, model, no_llm) -> PersonaSpec
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+import httpx
+
+from .personas import VALID_TOOL_AFFINITIES, PersonaSpec
+
+_SYSTEM_PROMPT = (
+    "You design analyst personas for a forecasting panel. Given a 1-line "
+    "ROLE description, draft a persona JSON with these fields:\n"
+    "  label: short title-case display name (3-5 words max)\n"
+    "  emoji: a single Unicode emoji that fits the role\n"
+    "  system: 5-7 sentence system prompt in second person ('You are...'). "
+    "Specific lens, what they look for, how they reason, what they discount.\n"
+    "  starting_memory: list of exactly 3 specific facts the persona starts "
+    "with — concrete numbers/dates where possible.\n"
+    "  tool_affinity: one of web_search | retrieve_document | "
+    "query_knowledge_base | mixed | none.\n"
+    "  n_eff: integer 6-12 reflecting the persona's stubbornness "
+    "(higher = harder to update).\n"
+    "Return ONLY a single JSON object. No prose, no markdown."
+)
+
+
+def _slugify(text: str) -> str:
+    """url-safe slug from a label."""
+    s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return s[:48] or "persona"
+
+
+def _synthetic_persona(description: str) -> PersonaSpec:
+    """Deterministic fallback. Never raises."""
+    desc = description.strip() or "generic analyst"
+    label = " ".join(w.capitalize() for w in desc.split()[:4]) or "Custom Analyst"
+    return PersonaSpec(
+        slug=_slugify(label),
+        label=label,
+        emoji="🎭",
+        system=(
+            f"You are {desc}. You bring a distinctive lens to every question, "
+            "weighing the strongest evidence first and acknowledging where you "
+            "lack data. Quote specific numbers when you can. Be honest about "
+            "uncertainty — express probability, not certainty. When the evidence "
+            "is mixed, say so explicitly. Update your view when peer agents "
+            "present a stronger case, but don't capitulate easily."
+        ),
+        starting_memory=[
+            f"Background: {desc}",
+            "Most expert forecasts cluster around the consensus mean ±15pp",
+            "Forecast accuracy improves with explicit confidence calibration",
+        ],
+        tool_affinity="mixed",
+        n_eff=10,
+    )
+
+
+async def _llm_draft(
+    description: str,
+    *,
+    model: str,
+    api_key: str,
+    timeout_s: float = 30.0,
+) -> dict:
+    user = f"ROLE: {description.strip()}"
+    body = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": _SYSTEM_PROMPT},
+            {"role": "user", "content": user},
+        ],
+        "temperature": 0.5,
+        "response_format": {"type": "json_object"},
+    }
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "HTTP-Referer": "https://github.com/ZySec-AI/hypermind",
+        "X-Title": "HyperMind SimLab",
+        "Content-Type": "application/json",
+    }
+    async with httpx.AsyncClient(timeout=timeout_s) as client:
+        r = await client.post(
+            "https://openrouter.ai/api/v1/chat/completions",
+            json=body,
+            headers=headers,
+        )
+    r.raise_for_status()
+    payload = r.json()
+    text = payload["choices"][0]["message"]["content"]
+    parsed = json.loads(text)
+    if not isinstance(parsed, dict):
+        raise ValueError(f"LLM returned non-object: {type(parsed).__name__}")
+    return parsed
+
+
+def _coerce_to_spec(raw: dict, description: str) -> PersonaSpec:
+    """Normalize an LLM JSON blob into a valid PersonaSpec."""
+    label = (
+        str(raw.get("label", "")).strip()
+        or " ".join(w.capitalize() for w in description.split()[:4])
+        or "Custom Analyst"
+    )
+    emoji = str(raw.get("emoji", "🎭")).strip() or "🎭"
+    system = str(raw.get("system", "")).strip()
+    if not system:
+        system = _synthetic_persona(description).system
+    starting_memory = raw.get("starting_memory") or []
+    if not isinstance(starting_memory, list):
+        starting_memory = []
+    starting_memory = [str(x).strip() for x in starting_memory if str(x).strip()][:5]
+    if not starting_memory:
+        starting_memory = _synthetic_persona(description).starting_memory
+    tool_affinity = str(raw.get("tool_affinity", "mixed")).strip()
+    if tool_affinity not in VALID_TOOL_AFFINITIES:
+        tool_affinity = "mixed"
+    try:
+        n_eff = int(raw.get("n_eff", 10))
+    except (TypeError, ValueError):
+        n_eff = 10
+    n_eff = max(1, min(50, n_eff))
+    return PersonaSpec(
+        slug=_slugify(label),
+        label=label,
+        emoji=emoji,
+        system=system,
+        starting_memory=starting_memory,
+        tool_affinity=tool_affinity,
+        n_eff=n_eff,
+    )
+
+
+async def generate_persona(
+    description: str,
+    *,
+    model: str | None = None,
+    no_llm: bool = False,
+) -> PersonaSpec:
+    """Public entry — async because the LLM path uses httpx.AsyncClient.
+
+    Always returns a PersonaSpec. Falls back to synthetic on any error.
+    The slug is derived from the label and may collide with a built-in;
+    callers (e.g. the API handler) must rename before saving.
+    """
+    description = (description or "").strip()
+    if not description:
+        raise ValueError("description is required")
+    api_key = os.environ.get("OPENROUTER_API_KEY", "").strip()
+    if no_llm or not api_key or not model:
+        return _synthetic_persona(description)
+    try:
+        raw = await _llm_draft(description, model=model, api_key=api_key)
+        return _coerce_to_spec(raw, description)
+    except Exception:
+        return _synthetic_persona(description)
+
+
+__all__ = ["generate_persona"]