arkaos 3.1.0 → 3.3.0

package/VERSION

@@ -1 +1 @@
-3.1.0
+3.3.0

package/core/agents/field_suggester.py

@@ -27,6 +27,8 @@ _VALID_FIELDS: tuple[str, ...] = (
     "mental_models",
     "frameworks",
     "expertise_domains",
+    "communication_avoid",
+    "key_quotes",
 )
 _MAX_COUNT = 12
 _DEFAULT_COUNT = 5
@@ -40,6 +42,23 @@ _FIELD_LABELS: dict[str, str] = {
     "mental_models": "mental models",
     "frameworks": "frameworks",
     "expertise_domains": "expertise domains",
+    "communication_avoid": "phrases this profile should AVOID using",
+    "key_quotes": "verbatim or paraphrased key quotes",
+}
+
+# Field-specific length hints — different fields want different item shapes.
+_FIELD_LENGTH_HINT: dict[str, str] = {
+    "mental_models": "Return a JSON array of short strings (2-5 words each).",
+    "frameworks": "Return a JSON array of short strings (2-5 words each).",
+    "expertise_domains": "Return a JSON array of short strings (2-5 words each).",
+    "communication_avoid": (
+        "Return a JSON array of short phrases (2-6 words each) that the "
+        "profile would never say or write."
+    ),
+    "key_quotes": (
+        "Return a JSON array of full sentences (8-25 words each), each "
+        "phrased as if the person said it. No attribution prefixes."
+    ),
 }
 
 
@@ -94,10 +113,8 @@ def _build_prompt(field: str, context: dict, count: int) -> str:
             + ", ".join(current)
             + "."
         )
-    lines.append(
-        "Return a JSON array of short strings (2-5 words each). "
-        "No explanations, no numbering, no surrounding object."
-    )
+    lines.append(_FIELD_LENGTH_HINT[field])
+    lines.append("No explanations, no numbering, no surrounding object.")
     return "\n".join(lines)
 
 

package/core/personas/description_drafter.py

@@ -0,0 +1,111 @@
+"""AI-powered persona draft from a free-text description (PR83a v3.3.0).
+
+Sibling to `core/personas/builder.PersonaBuilder` but does NOT require
+indexed content. Useful when:
+
+- The operator wants to model a persona quickly without ingesting sources
+- A YouTuber / author isn't yet in the knowledge base
+- The persona is a synthetic archetype rather than a real person
+
+Reuses the same JSON schema and parsing as the vector-driven builder so
+the resulting Persona is interchangeable.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from core.personas.builder import (
+    _PERSONA_SYSTEM_PROMPT,
+    _extract_json_object,
+)
+from core.personas.schema import (
+    Persona,
+    PersonaBigFive,
+    PersonaCommunication,
+    PersonaDISC,
+    PersonaEnneagram,
+)
+from core.runtime.llm_provider import LLMProvider, LLMUnavailable, get_llm_provider
+
+
+_DESCRIPTION_MIN_CHARS = 20
+
+
+class PersonaDraftError(RuntimeError):
+    """LLM produced unusable output or could not be reached."""
+
+
+@dataclass(frozen=True)
+class PersonaDraftResult:
+    persona: Persona
+    provider_name: str
+    raw_response: str
+
+
+def draft_persona_from_description(
+    description: str,
+    *,
+    name: str,
+    source_label: str = "",
+    provider: LLMProvider | None = None,
+) -> PersonaDraftResult:
+    """Generate a Persona draft from a free-text description."""
+    description = (description or "").strip()
+    if not name or not name.strip():
+        raise PersonaDraftError("name must not be empty")
+    if len(description) < _DESCRIPTION_MIN_CHARS:
+        raise PersonaDraftError(
+            f"description must be at least {_DESCRIPTION_MIN_CHARS} characters"
+        )
+    llm = provider or get_llm_provider()
+    prompt = _build_prompt(name.strip(), description)
+    try:
+        resp = llm.complete(prompt, max_tokens=3000, system=_PERSONA_SYSTEM_PROMPT)
+    except LLMUnavailable as exc:
+        raise PersonaDraftError(str(exc)) from exc
+    persona = _parse(name.strip(), source_label.strip() or name.strip(), resp.text)
+    return PersonaDraftResult(
+        persona=persona, provider_name=llm.name(), raw_response=resp.text,
+    )
+
+
+def _build_prompt(name: str, description: str) -> str:
+    return (
+        f"Person: {name}\n\n"
+        f"Description provided by the operator:\n{description}\n\n"
+        "Build the persona purely from the description above. If a field is "
+        "not implied, choose the closest neutral default rather than "
+        "fabricating. NEVER invent quotes — leave key_quotes empty if no "
+        "quotes are present in the description."
+    )
+
+
+def _parse(name: str, source_label: str, raw: str) -> Persona:
+    data = _extract_json_object(raw)
+    if data is None:
+        raise PersonaDraftError(
+            f"LLM did not return a JSON object; raw response: {raw[:200]!r}"
+        )
+    try:
+        return Persona(
+            id=str(uuid.uuid4()),
+            name=name,
+            title=str(data.get("title") or ""),
+            tagline=str(data.get("tagline") or ""),
+            source=source_label,
+            disc=PersonaDISC(**(data.get("disc") or {})),
+            enneagram=PersonaEnneagram(**(data.get("enneagram") or {})),
+            big_five=PersonaBigFive(**(data.get("big_five") or {})),
+            mbti=str(data.get("mbti") or "").upper() or "INTJ",
+            mental_models=[str(x) for x in (data.get("mental_models") or [])],
+            expertise_domains=[str(x) for x in (data.get("expertise_domains") or [])],
+            frameworks=[str(x) for x in (data.get("frameworks") or [])],
+            key_quotes=[str(x) for x in (data.get("key_quotes") or [])],
+            communication=PersonaCommunication(**(data.get("communication") or {})),
+            created_at=datetime.now(timezone.utc).isoformat(),
+        )
+    except (TypeError, ValueError) as exc:
+        raise PersonaDraftError(f"persona schema mismatch: {exc}") from exc

package/dashboard/app/components/AgentEditDrawer.vue

@@ -111,7 +111,8 @@ function csvToList(value: string): string[] {
 }
 
 // PR81 v2.99.0 — AI list-field suggester.
-type SuggestField = 'mental_models_primary' | 'frameworks' | 'expertise_domains'
+// PR82c v3.2.0 — extended with 'communication_avoid'.
+type SuggestField = 'mental_models_primary' | 'frameworks' | 'expertise_domains' | 'communication_avoid'
 const suggestingField = ref<SuggestField | null>(null)
 
 async function suggest(field: SuggestField) {
@@ -122,7 +123,9 @@ async function suggest(field: SuggestField) {
       ? draft.value.mental_models.primary
       : field === 'frameworks'
         ? draft.value.frameworks
-        : draft.value.expertise_domains
+        : field === 'expertise_domains'
+          ? draft.value.expertise_domains
+          : draft.value.communication.avoid
   suggestingField.value = field
   try {
     const res = await $fetch<{
@@ -159,8 +162,10 @@ async function suggest(field: SuggestField) {
       draft.value.mental_models.primary = merged
     } else if (field === 'frameworks') {
       draft.value.frameworks = merged
-    } else {
+    } else if (field === 'expertise_domains') {
       draft.value.expertise_domains = merged
+    } else {
+      draft.value.communication.avoid = merged
     }
     markDirty()
     toast.add({
@@ -437,6 +442,18 @@ const vocabOptions = [
               </UFormField>
             </div>
             <UFormField label="Avoid (phrases)" help="comma-separated">
+              <template #hint>
+                <UButton
+                  label="Suggest with AI"
+                  icon="i-lucide-sparkles"
+                  size="xs"
+                  color="primary"
+                  variant="soft"
+                  :loading="suggestingField === 'communication_avoid'"
+                  :disabled="suggestingField !== null"
+                  @click="suggest('communication_avoid')"
+                />
+              </template>
               <UInput
                 :model-value="listToCsv(draft.communication.avoid)"
                 @update:model-value="(v: string) => { if (draft) { draft.communication.avoid = csvToList(v); markDirty() } }"

package/dashboard/app/components/PersonaWizard.vue

@@ -37,6 +37,12 @@ const sourceLineCount = computed(() =>
     .length,
 )
 
+// PR83a v3.3.0 — Mode 3: build from a free-text description (no chunks).
+type Mode = 'sources' | 'existing' | 'description'
+const mode = ref<Mode>('sources')
+const description = ref('')
+const descriptionLength = computed(() => description.value.trim().length)
+
 // ─── Step 2 state ────────────────────────────────────────────────────────
 const ingestJobs = ref<Array<{
   source: string
@@ -81,7 +87,14 @@ const tierOptions = [
 
 
 async function startIngest() {
-  if (skipIngest.value) {
+  if (mode.value === 'description') {
+    // PR83a — no ingest, no chunks. Build directly from description.
+    if (descriptionLength.value < 20 || !name.value.trim()) return
+    step.value = 3
+    await runDescriptionBuild()
+    return
+  }
+  if (mode.value === 'existing' || skipIngest.value) {
     // Jump straight to step 3 — operator says content is already indexed.
     step.value = 3
     await runBuild()
@@ -166,6 +179,36 @@ onBeforeUnmount(() => {
 // ─── Step 3: build the persona draft ────────────────────────────────────
 
 
+async function runDescriptionBuild() {
+  building.value = true
+  buildError.value = null
+  draft.value = null
+  try {
+    const res = await $fetch<{ persona: Persona, provider_name: string, error?: string }>(
+      `${apiBase}/api/personas/draft`,
+      {
+        method: 'POST',
+        body: {
+          name: name.value.trim(),
+          description: description.value.trim(),
+          source_label: sourceLabel.value.trim() || name.value.trim(),
+        },
+      },
+    )
+    if ('error' in res && typeof (res as any).error === 'string') {
+      throw new Error((res as any).error)
+    }
+    draft.value = res.persona
+    chunksUsed.value = 0
+    step.value = 4
+  } catch (err) {
+    buildError.value = err instanceof Error ? err.message : 'unknown error'
+  } finally {
+    building.value = false
+  }
+}
+
+
 async function runBuild() {
   building.value = true
   buildError.value = null
@@ -308,7 +351,28 @@ function backToStep1() {
         />
       </UFormField>
 
+      <UFormField label="How should we generate this persona?">
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-2">
+          <button
+            v-for="m in ([
+              { key: 'sources',     title: 'Ingest sources',  desc: 'YouTube, articles, PDFs — best fidelity' },
+              { key: 'existing',    title: 'Existing chunks', desc: 'Use what is already indexed' },
+              { key: 'description', title: 'From description', desc: 'No sources — pure description' },
+            ] as const)"
+            :key="m.key"
+            type="button"
+            class="text-left rounded-lg border p-3 transition-colors"
+            :class="mode === m.key ? 'border-primary bg-primary/5' : 'border-default hover:border-primary/40'"
+            @click="mode = m.key"
+          >
+            <p class="text-sm font-semibold">{{ m.title }}</p>
+            <p class="text-xs text-muted mt-1">{{ m.desc }}</p>
+          </button>
+        </div>
+      </UFormField>
+
       <UFormField
+        v-if="mode === 'sources'"
         label="Sources (one URL per line)"
         help="YouTube videos, articles, PDFs, blog posts about this person. The builder will search the indexed chunks and synthesise their behavioural DNA. Up to 50 sources per batch."
       >
@@ -317,28 +381,56 @@ function backToStep1() {
           :rows="6"
           placeholder="https://www.youtube.com/watch?v=...&#10;https://example.com/article&#10;https://example.com/paper.pdf"
           class="w-full font-mono text-sm"
-          :disabled="skipIngest"
         />
       </UFormField>
 
-      <div class="flex items-center justify-between text-xs text-muted">
-        <span>{{ sourceLineCount }} source{{ sourceLineCount === 1 ? '' : 's' }} detected</span>
-        <UCheckbox
-          v-model="skipIngest"
-          label="Skip ingest — content for this person is already in the knowledge base"
+      <UFormField
+        v-else-if="mode === 'description'"
+        label="Description"
+        help="Plain-text description of the person — their style, beliefs, what they do, how they talk. The LLM uses this verbatim. Minimum 20 characters."
+      >
+        <UTextarea
+          v-model="description"
+          :rows="6"
+          placeholder="A direct-response copywriter who treats offers as the only true growth lever. Punchy, allergic to fluff. Loves Hormozi-style hooks."
+          class="w-full"
         />
+      </UFormField>
+
+      <div
+        v-if="mode === 'sources'"
+        class="flex items-center justify-between text-xs text-muted"
+      >
+        <span>{{ sourceLineCount }} source{{ sourceLineCount === 1 ? '' : 's' }} detected</span>
+      </div>
+
+      <div v-else-if="mode === 'existing'" class="text-xs text-muted">
+        We will search the vector DB for chunks tagged with this name and synthesise from what we find. Make sure you've ingested content for this person first.
+      </div>
+
+      <div v-else-if="mode === 'description'" class="text-xs text-muted">
+        {{ descriptionLength }} character{{ descriptionLength === 1 ? '' : 's' }} ·
+        {{ descriptionLength >= 20 ? 'ready' : `${20 - descriptionLength} more needed` }}
       </div>
 
       <div class="flex justify-end gap-2 pt-4">
         <UButton
-          :label="skipIngest ? 'Generate from existing knowledge' : `Index ${sourceLineCount} source${sourceLineCount === 1 ? '' : 's'} & build`"
+          :label="(
+            mode === 'sources' ? `Index ${sourceLineCount} source${sourceLineCount === 1 ? '' : 's'} & build`
+            : mode === 'existing' ? 'Generate from existing knowledge'
+            : 'Generate from description'
+          )"
           icon="i-lucide-arrow-right"
-          :disabled="!name.trim() || (!skipIngest && sourceLineCount === 0) || sourceLineCount > 50"
+          :disabled="(
+            !name.trim()
+            || (mode === 'sources' && (sourceLineCount === 0 || sourceLineCount > 50))
+            || (mode === 'description' && descriptionLength < 20)
+          )"
           size="md"
           @click="startIngest"
         />
       </div>
-      <p v-if="sourceLineCount > 50" class="text-xs text-red-400">
+      <p v-if="mode === 'sources' && sourceLineCount > 50" class="text-xs text-red-400">
         Over the 50-source cap. Trim the list before continuing.
       </p>
     </div>

package/dashboard/app/pages/agents/new.vue

@@ -202,7 +202,8 @@ function csvToList(value: string): string[] {
 }
 
 // PR81 suggest wiring — three list fields.
-type SuggestField = 'mental_models' | 'frameworks' | 'expertise_domains'
+// PR82c v3.2.0 — extended with 'communication_avoid'.
+type SuggestField = 'mental_models' | 'frameworks' | 'expertise_domains' | 'communication_avoid'
 const suggestingField = ref<SuggestField | null>(null)
 
 async function suggest(field: SuggestField) {
@@ -211,7 +212,9 @@ async function suggest(field: SuggestField) {
       ? draft.value.mental_models_primary
       : field === 'frameworks'
         ? draft.value.frameworks
-        : draft.value.expertise_domains
+        : field === 'expertise_domains'
+          ? draft.value.expertise_domains
+          : draft.value.comm_avoid
   if (!draft.value.name.trim() || !draft.value.role.trim()) {
     toast.add({
       title: 'Add a name and role first',
@@ -250,7 +253,8 @@ async function suggest(field: SuggestField) {
     const merged = [...current, ...additions]
     if (field === 'mental_models') draft.value.mental_models_primary = merged
     else if (field === 'frameworks') draft.value.frameworks = merged
-    else draft.value.expertise_domains = merged
+    else if (field === 'expertise_domains') draft.value.expertise_domains = merged
+    else draft.value.comm_avoid = merged
     toast.add({
       title: `Added ${additions.length} suggestion${additions.length === 1 ? '' : 's'}`,
       description: `via ${res.provider_name}`,
@@ -553,6 +557,18 @@ const bigFiveKeys = ['openness', 'conscientiousness', 'extraversion', 'agreeable
             </UFormField>
           </div>
           <UFormField label="Avoid (phrases)" help="comma-separated">
+            <template #hint>
+              <UButton
+                label="Suggest with AI"
+                icon="i-lucide-sparkles"
+                size="xs"
+                color="primary"
+                variant="soft"
+                :loading="suggestingField === 'communication_avoid'"
+                :disabled="suggestingField !== null"
+                @click="suggest('communication_avoid')"
+              />
+            </template>
             <UInput
               :model-value="listToCsv(draft.comm_avoid)"
               @update:model-value="(v: string) => { draft.comm_avoid = csvToList(v) }"

package/dashboard/app/pages/personas/[id].vue

@@ -222,12 +222,16 @@ function csvToList(value: string): string[] {
 }
 
 // PR81 v2.99.0 — AI list-field suggester for personas.
-type SuggestField = 'mental_models' | 'frameworks' | 'expertise_domains'
+// PR82c v3.2.0 — extended with 'communication_avoid' and 'key_quotes'.
+type SuggestField = 'mental_models' | 'frameworks' | 'expertise_domains' | 'communication_avoid' | 'key_quotes'
 const suggestingField = ref<SuggestField | null>(null)
 
 async function suggest(field: SuggestField) {
   if (!draft.value || !detail.value) return
-  const current = (draft.value as any)[field] as string[]
+  const current
+    = field === 'communication_avoid'
+      ? (draft.value.communication.avoid ?? [])
+      : ((draft.value as any)[field] as string[] ?? [])
   suggestingField.value = field
   try {
     const res = await $fetch<{
@@ -258,7 +262,12 @@ async function suggest(field: SuggestField) {
       })
       return
     }
-    ;(draft.value as any)[field] = [...current, ...additions]
+    const merged = [...current, ...additions]
+    if (field === 'communication_avoid') {
+      draft.value.communication.avoid = merged
+    } else {
+      ;(draft.value as any)[field] = merged
+    }
     markDirty()
     toast.add({
       title: `Added ${additions.length} suggestion${additions.length === 1 ? '' : 's'}`,
@@ -751,6 +760,52 @@ const vocabOptions = [
                         <USelect v-model="draft.communication.vocabulary_level" :items="vocabOptions" class="w-full" @update:model-value="markDirty" />
                       </UFormField>
                     </div>
+                    <UFormField label="Avoid (phrases)" help="comma-separated">
+                      <template #hint>
+                        <UButton
+                          label="Suggest with AI"
+                          icon="i-lucide-sparkles"
+                          size="xs"
+                          color="primary"
+                          variant="soft"
+                          :loading="suggestingField === 'communication_avoid'"
+                          :disabled="suggestingField !== null"
+                          @click="suggest('communication_avoid')"
+                        />
+                      </template>
+                      <UInput
+                        :model-value="listToCsv(draft.communication.avoid)"
+                        @update:model-value="(v: string) => { if (draft) { draft.communication.avoid = csvToList(v); markDirty() } }"
+                        class="w-full"
+                      />
+                    </UFormField>
+                  </section>
+
+                  <section class="space-y-3">
+                    <div class="flex items-center justify-between">
+                      <h3 class="text-xs font-semibold uppercase tracking-wider text-muted">Key quotes</h3>
+                      <UButton
+                        label="Suggest with AI"
+                        icon="i-lucide-sparkles"
+                        size="xs"
+                        color="primary"
+                        variant="soft"
+                        :loading="suggestingField === 'key_quotes'"
+                        :disabled="suggestingField !== null"
+                        @click="suggest('key_quotes')"
+                      />
+                    </div>
+                    <UTextarea
+                      :model-value="(draft.key_quotes ?? []).join('\n')"
+                      :rows="4"
+                      placeholder="One quote per line. Verbatim or paraphrased."
+                      @update:model-value="(v: string) => { if (draft) { draft.key_quotes = v.split('\n').map((q) => q.trim()).filter(Boolean); markDirty() } }"
+                      class="w-full"
+                    />
+                    <p class="text-xs text-muted">
+                      {{ (draft.key_quotes ?? []).length }} quote{{ (draft.key_quotes ?? []).length === 1 ? '' : 's' }}.
+                      One per line.
+                    </p>
                   </section>
                 </div>
 

package/dashboard/app/types/index.d.ts

@@ -209,9 +209,11 @@ export interface Persona {
   mental_models: string[]
   expertise_domains: string[]
   frameworks: string[]
+  key_quotes?: string[]
   communication: {
     tone: string
     vocabulary_level: string
+    avoid?: string[]
   }
   cloned_to_agents: string[]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.1.0"
+version = "3.3.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/dashboard-api.py

@@ -1827,6 +1827,43 @@ def _build_agent_yaml(
     return payload
 
 
+# --- AI persona draft from description (PR83a v3.3.0) ---
+
+@app.post("/api/personas/draft")
+def personas_draft(body: dict):
+    """Generate a Persona draft from a free-text description (no vector DB).
+
+    Body: {
+        "description": "...",    # min 20 chars
+        "name": "Alex Carter",   # required
+        "source_label": "..."    # optional
+    }
+    Returns: {"persona": {...}, "provider_name": "..."}
+
+    Sibling to /api/personas/build (which requires indexed chunks). Useful
+    when the operator wants a quick draft without ingesting sources first.
+    The result is NOT saved — operator reviews + POSTs to /api/personas.
+    """
+    from core.personas.description_drafter import (
+        PersonaDraftError,
+        draft_persona_from_description,
+    )
+
+    description = (body.get("description") or "").strip()
+    name = (body.get("name") or "").strip()
+    source_label = (body.get("source_label") or "").strip()
+    try:
+        res = draft_persona_from_description(
+            description, name=name, source_label=source_label,
+        )
+    except PersonaDraftError as exc:
+        return {"error": str(exc)}
+    return {
+        "persona": res.persona.model_dump(),
+        "provider_name": res.provider_name,
+    }
+
+
 # --- AI agent draft from description (PR82b v3.1.0) ---
 
 @app.post("/api/agents/draft")