arkaos 3.0.0 → 3.2.0

package/VERSION

@@ -1 +1 @@
-3.0.0
+3.2.0

package/core/agents/draft_builder.py

@@ -0,0 +1,156 @@
+"""AI-powered agent draft builder (PR82b v3.1.0).
+
+Given a free-text description (and optionally a name/role/department),
+produce a full agent draft: behavioural DNA, expertise, mental models,
+and communication block — all in one LLM call.
+
+Used by `POST /api/agents/draft` to power the "AI draft from
+description" textarea on `/agents/new`. The operator then reviews and
+edits the generated draft before clicking Create.
+
+Provider-agnostic: callers can inject a fake `LLMProvider` in tests.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+from core.runtime.llm_provider import LLMProvider, LLMUnavailable, get_llm_provider
+
+
+_SYSTEM = """You design behavioural-DNA profiles for AI agents. Read the
+operator's description carefully, then emit a single JSON object that
+follows this exact schema. Use ONLY the JSON keys listed — no prose,
+no markdown fences, no extra fields.
+
+{
+  "behavioral_dna": {
+    "disc": {
+      "primary": "D|I|S|C",
+      "secondary": "D|I|S|C",
+      "communication_style": "<one sentence>",
+      "under_pressure": "<one sentence>",
+      "motivator": "<one sentence>"
+    },
+    "enneagram": {
+      "type": 1-9,
+      "wing": 1-9,
+      "core_motivation": "<one sentence>",
+      "core_fear": "<one sentence>",
+      "subtype": "self-preservation|social|sexual"
+    },
+    "big_five": {
+      "openness": 0-100,
+      "conscientiousness": 0-100,
+      "extraversion": 0-100,
+      "agreeableness": 0-100,
+      "neuroticism": 0-100
+    },
+    "mbti": "<4-letter type>"
+  },
+  "expertise": {
+    "domains": ["<domain>", ...],
+    "frameworks": ["<framework>", ...],
+    "depth": "intermediate|advanced|expert|master",
+    "years_equivalent": <int>
+  },
+  "mental_models": {
+    "primary": ["<model>", ...],
+    "secondary": ["<model>", ...]
+  },
+  "communication": {
+    "tone": "<adjective list>",
+    "vocabulary_level": "lay|specialist|expert",
+    "preferred_format": "<format hint>",
+    "language": "<two-letter code, e.g. en>",
+    "avoid": ["<phrase>", ...]
+  }
+}
+
+Rules:
+- DISC primary MUST differ from secondary.
+- Pick concrete frameworks (e.g. "Porter's Five Forces") not abstract verbs.
+- Provide 4-8 expertise.domains, 4-8 expertise.frameworks, 3-6 mental_models.primary.
+- Keep all string values terse and concrete."""
+
+
+class DraftError(RuntimeError):
+    """LLM produced unusable output or could not be reached."""
+
+
+@dataclass(frozen=True)
+class DraftResult:
+    draft: dict
+    provider_name: str
+
+
+def draft_agent(
+    description: str,
+    *,
+    name: str = "",
+    role: str = "",
+    department: str = "",
+    tier: int = 2,
+    provider: LLMProvider | None = None,
+) -> DraftResult:
+    """Return a full agent draft inferred from a free-text description."""
+    description = (description or "").strip()
+    if len(description) < 20:
+        raise DraftError("description must be at least 20 characters")
+    llm = provider or get_llm_provider()
+    prompt = _build_prompt(description, name, role, department, tier)
+    try:
+        resp = llm.complete(prompt, max_tokens=2000, system=_SYSTEM)
+    except LLMUnavailable as exc:
+        raise DraftError(str(exc)) from exc
+    draft = _parse(resp.text)
+    _validate(draft)
+    return DraftResult(draft=draft, provider_name=llm.name())
+
+
+def _build_prompt(description: str, name: str, role: str, department: str, tier: int) -> str:
+    lines = ["Design an agent profile from this description:", "", description.strip(), ""]
+    if name:
+        lines.append(f"Name: {name}")
+    if role:
+        lines.append(f"Role: {role}")
+    if department:
+        lines.append(f"Department: {department}")
+    lines.append(f"Tier: {tier}")
+    lines.append("")
+    lines.append("Return ONLY the JSON object — no prose, no markdown fences.")
+    return "\n".join(lines)
+
+
+def _parse(text: str) -> dict:
+    cleaned = re.sub(r"^```(?:json)?\s*|\s*```$", "", text.strip(), flags=re.MULTILINE)
+    cleaned = cleaned.strip()
+    try:
+        data = json.loads(cleaned)
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise DraftError(f"LLM returned non-JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise DraftError("LLM returned a non-object JSON value")
+    return data
+
+
+def _validate(draft: dict) -> None:
+    """Sanity-check the LLM payload — catches the common failure modes
+    before the operator sees a half-broken form."""
+    dna = draft.get("behavioral_dna")
+    if not isinstance(dna, dict):
+        raise DraftError("missing behavioral_dna block")
+    disc = dna.get("disc") or {}
+    if disc.get("primary") and disc.get("primary") == disc.get("secondary"):
+        raise DraftError("DISC primary and secondary must differ")
+    valid_disc = {"D", "I", "S", "C"}
+    if disc.get("primary") and str(disc["primary"]).upper() not in valid_disc:
+        raise DraftError(f"invalid DISC primary: {disc.get('primary')!r}")
+    if disc.get("secondary") and str(disc["secondary"]).upper() not in valid_disc:
+        raise DraftError(f"invalid DISC secondary: {disc.get('secondary')!r}")
+    big_five = dna.get("big_five") or {}
+    for axis, value in big_five.items():
+        if not isinstance(value, (int, float)) or not 0 <= value <= 100:
+            raise DraftError(f"big_five.{axis} must be 0..100, got {value!r}")

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/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/pages/agents/new.vue

@@ -88,6 +88,83 @@ const draft = ref<AgentDraft>({
 
 const saving = ref(false)
 
+// PR82b v3.1.0 — AI draft from description.
+const description = ref('')
+const drafting = ref(false)
+
+async function draftFromDescription() {
+  const desc = description.value.trim()
+  if (desc.length < 20) {
+    toast.add({
+      title: 'Add more detail',
+      description: 'Describe the agent in at least a sentence or two.',
+      color: 'warning',
+    })
+    return
+  }
+  drafting.value = true
+  try {
+    const res = await $fetch<{
+      draft: any
+      provider_name: string
+      error?: string
+    }>(`${apiBase}/api/agents/draft`, {
+      method: 'POST',
+      body: {
+        description: desc,
+        name: draft.value.name,
+        role: draft.value.role,
+        department: draft.value.department,
+        tier: draft.value.tier,
+      },
+    })
+    if (res.error) throw new Error(res.error)
+    applyDraft(res.draft)
+    toast.add({
+      title: 'Draft generated',
+      description: `via ${res.provider_name} — review and edit before creating.`,
+      color: 'success',
+      icon: 'i-lucide-sparkles',
+    })
+  } catch (err) {
+    toast.add({
+      title: 'Draft failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    drafting.value = false
+  }
+}
+
+function applyDraft(d: any) {
+  const dna = d?.behavioral_dna ?? {}
+  const disc = dna.disc ?? {}
+  const enn = dna.enneagram ?? {}
+  const bf = dna.big_five ?? {}
+  if (disc.primary) draft.value.disc_primary = String(disc.primary).toUpperCase()
+  if (disc.secondary) draft.value.disc_secondary = String(disc.secondary).toUpperCase()
+  if (enn.type) draft.value.enneagram_type = Number(enn.type)
+  if (enn.wing) draft.value.enneagram_wing = Number(enn.wing)
+  if (dna.mbti) draft.value.mbti = String(dna.mbti).toUpperCase()
+  for (const key of ['openness', 'conscientiousness', 'extraversion', 'agreeableness', 'neuroticism'] as const) {
+    if (typeof bf[key] === 'number') draft.value.big_five[key] = bf[key]
+  }
+  const exp = d?.expertise ?? {}
+  if (Array.isArray(exp.domains)) draft.value.expertise_domains = exp.domains.map(String)
+  if (Array.isArray(exp.frameworks)) draft.value.frameworks = exp.frameworks.map(String)
+  if (exp.depth) draft.value.expertise_depth = String(exp.depth)
+  if (typeof exp.years_equivalent === 'number') draft.value.expertise_years = exp.years_equivalent
+  const mm = d?.mental_models ?? {}
+  if (Array.isArray(mm.primary)) draft.value.mental_models_primary = mm.primary.map(String)
+  const comm = d?.communication ?? {}
+  if (comm.tone) draft.value.comm_tone = String(comm.tone)
+  if (comm.vocabulary_level) draft.value.comm_vocab = String(comm.vocabulary_level)
+  if (comm.preferred_format) draft.value.comm_format = String(comm.preferred_format)
+  if (comm.language) draft.value.comm_language = String(comm.language)
+  if (Array.isArray(comm.avoid)) draft.value.comm_avoid = comm.avoid.map(String)
+}
+
 const departmentOptions = [
   'dev', 'marketing', 'brand', 'finance', 'strategy', 'ecom', 'kb', 'ops',
   'pm', 'saas', 'landing', 'content', 'community', 'sales', 'leadership', 'org',
@@ -125,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) {
@@ -134,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',
@@ -173,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}`,
@@ -298,6 +379,40 @@ const bigFiveKeys = ['openness', 'conscientiousness', 'extraversion', 'agreeable
 
     <template #body>
       <div class="max-w-4xl mx-auto py-2 space-y-6">
+        <section class="rounded-xl border border-primary/30 bg-primary/5 p-4 space-y-3">
+          <div class="flex items-center justify-between gap-3">
+            <div>
+              <h3 class="text-sm font-semibold uppercase tracking-wide text-primary flex items-center gap-2">
+                <UIcon name="i-lucide-sparkles" class="size-4" />
+                Draft with AI
+              </h3>
+              <p class="text-xs text-muted mt-0.5">
+                Describe the agent in plain text — the LLM fills the whole form below.
+                You can still edit everything before saving.
+              </p>
+            </div>
+            <UButton
+              label="Generate draft"
+              icon="i-lucide-wand"
+              color="primary"
+              :loading="drafting"
+              :disabled="description.trim().length < 20"
+              @click="draftFromDescription"
+            />
+          </div>
+          <UTextarea
+            v-model="description"
+            placeholder="A senior strategist who decides fast, demands evidence, and is allergic to fluff. Spent 10 years at McKinsey covering CPG..."
+            :rows="3"
+            class="w-full"
+          />
+          <p class="text-xs text-muted">
+            Tip: fill in <span class="font-mono">Name</span> /
+            <span class="font-mono">Role</span> /
+            <span class="font-mono">Department</span> below first for more precise output.
+          </p>
+        </section>
+
         <section class="space-y-3">
           <h3 class="text-sm font-semibold uppercase tracking-wide text-muted">Identity</h3>
           <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
@@ -442,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.0.0",
+  "version": "3.2.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.0.0"
+version = "3.2.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,42 @@ def _build_agent_yaml(
     return payload
 
 
+# --- AI agent draft from description (PR82b v3.1.0) ---
+
+@app.post("/api/agents/draft")
+def agents_draft(body: dict):
+    """Generate a full agent draft from a free-text description.
+
+    Body: {
+        "description": "...",   # min 20 chars
+        "name": "Lucas",         # optional
+        "role": "Market Analyst",# optional
+        "department": "strategy",# optional
+        "tier": 2                # optional, default 2
+    }
+    Returns: {"draft": {...behavioral_dna, expertise, mental_models,
+    communication...}, "provider_name": "..."}
+    """
+    from core.agents.draft_builder import DraftError, draft_agent
+
+    description = (body.get("description") or "").strip()
+    try:
+        tier = int(body.get("tier") or 2)
+    except (TypeError, ValueError):
+        tier = 2
+    try:
+        res = draft_agent(
+            description,
+            name=(body.get("name") or "").strip(),
+            role=(body.get("role") or "").strip(),
+            department=(body.get("department") or "").strip(),
+            tier=tier,
+        )
+    except DraftError as exc:
+        return {"error": str(exc)}
+    return {"draft": res.draft, "provider_name": res.provider_name}
+
+
 # --- AI list-field suggester (PR81 v2.99.0) ---
 
 @app.post("/api/agents/suggest")