ei-tui 0.1.25 → 0.2.0

package/src/prompts/human/person-match.ts

@@ -0,0 +1,65 @@
+import type { PromptOutput } from "./types.js";
+
+export interface PersonMatchPromptData {
+  candidate_name: string;
+  candidate_description: string;
+  candidate_relationship: string;
+  existing_people: Array<{
+    id: string;
+    name: string;
+    description: string;
+    relationship?: string;
+  }>;
+}
+
+export function buildPersonMatchPrompt(data: PersonMatchPromptData): PromptOutput {
+  if (!data.candidate_name) {
+    throw new Error("buildPersonMatchPrompt: candidate_name is required");
+  }
+
+  const system = `# Task
+
+You are checking if a PERSON already exists in our database.
+
+## Matching Rules
+
+1. **Exact match**: Same person by name or clear identity → return their ID
+2. **Similar match**: Same person referred to differently ("Mom" vs "Carol", "my boss" vs "Trumble") → return their ID
+3. **No match**: Genuinely new person → return "new"
+
+Be conservative. If you're unsure, return "new" — a duplicate is worse than a gap.
+
+# Existing People
+
+\`\`\`json
+${JSON.stringify(data.existing_people, null, 2)}
+\`\`\`
+
+# Response Format
+
+Return ONLY the ID of the matching entry, or "new".
+
+\`\`\`json
+{
+  "matched_guid": "uuid-of-matching-entry" | "new"
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const user = `# Candidate Person
+
+Name: ${data.candidate_name}
+Description: ${data.candidate_description}
+Relationship: ${data.candidate_relationship}
+
+Find the best match in existing people, or return "new" if this is a genuinely new person.
+
+\`\`\`json
+{
+  "matched_guid": "..." | "new"
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/human/person-scan.ts

@@ -8,72 +8,64 @@ export function buildHumanPersonScanPrompt(data: PersonScanPromptData): PromptOu
 
   const personaName = data.persona_name;
 
-  const taskFragment = `# Task
-
-You are scanning a conversation to quickly identify PEOPLE of interest TO the HUMAN USER. Your ONLY job is to spot mentions of PEOPLE. Do NOT analyze them deeply. Just detect and flag.`;
-
-  const specificNeedsFragment = `## Specific Needs
-
-Your job is to quickly identify:
-1. Which PEOPLE were mentioned or relevant
-    a. Only flag PEOPLE that were actually discussed, not just tangentially related
-    b. Be CONSERVATIVE - only suggest genuinely important, long-term relevant PEOPLE
-        i. Ignore: greetings, small talk, one-off mentions, jokes
-    c. Be CLEAR - state your \`reason\` for including this PERSON with any evidence you used`;
-
-  const guidelinesFragment = `## Guidelines
-
-1. **Unknown Types and Names of PEOPLE**
-    a. In some conversations, it may be impossible to identify which "Brother" or which "Bob" the user is referring to.
-        - Use "Unknown" for the missing field and explain in the \`reason\`
-        - This will trigger a later validation step to get more information!
-    b. If you're adding a NEW PERSON, be as specific as you can, for example:
-        - { "type_of_person": "Unknown", "name_of_person": "Alice from work", "reason": "Mentioned but relationship unclear" }
-        - { "type_of_person": "Sibling", "name_of_person": "Name Unknown", "reason": "Mentioned a sibling, name not given" }
-
-**A PERSON Is**
-* Immediate Family: Father, Husband, Son, Brother, Mother, Wife, Daughter, Sister (and step/in-law variants)
-* Extended Family: Grandfather, Grandmother, Aunt, Uncle, Cousin, Niece, Nephew
-* Close Acquaintance
-* Friend
-* Lover / Love Interest
-* Fiance / Spouse
-* Coworker
-* AI Persona (use \`type_of_person: "Persona"\`)
-
-**A PERSON Is NOT**
-- Biographical data: Birthday, Location, Job, Marital Status, Gender, Eye Color, Hair Color
-- Other unchangeable Data: Wedding Day, Allergies
-- Trait: Personality patterns, communication style, behavioral tendencies
-- General Topic: Interests, Hobbies, General subjects
-- Characters: Fictitious entities from books, movies, stories, media, etc.`;
-  const criticalFragment = `# CRITICAL INSTRUCTIONS
-
-ONLY ANALYZE the "Most Recent Messages" in the following conversation. The "Earlier Conversation" is provided for your context and has already been processed!
-
-The JSON format is:
+  const system = `# Task
+
+You are scanning a conversation to quickly identify PEOPLE in the HUMAN USER's life.
+
+Detect and flag. Do NOT analyze deeply — that happens later.
+
+## What to Capture
+
+Flag a PERSON when they were meaningfully discussed — not just mentioned in passing.
+
+Be **conservative**: ignore one-off mentions, greetings, small talk, or jokes. Only flag people who matter to the human user's life.
+
+## What a PERSON Is
+
+Someone in the human user's world. Use the relationship as the primary classifier:
+
+**Immediate Family**: Father, Mother, Son, Daughter, Brother, Sister, Husband, Wife, Partner (and step/in-law variants)
+
+**Extended Family**: Grandfather, Grandmother, Aunt, Uncle, Cousin, Niece, Nephew
+
+**Social**: Friend, Close Acquaintance, Lover, Love Interest, Fiance, Spouse
+
+**Professional**: Coworker, Manager, Report, Mentor, Client
+
+**AI**: Persona (use \`relationship: "AI Persona"\` for AI companions and assistants)
+
+**NOT a PERSON:**
+- The user themselves
+- Biographical facts, topics, or hobbies
+- Fictional characters from books, movies, or media
+- Public figures only mentioned in passing (celebrities, politicians) — unless the user has a real relationship with them
+
+## When Identity Is Unclear
+
+If you can't identify which "Bob" or which "Brother" the user means, use "Unknown" and explain in the reason field. This triggers a later step to resolve ambiguity.
+
+Examples:
+- name: "Alice from work", relationship: "Coworker", description: "Mentioned but not described further", reason: "User referenced a work colleague named Alice"
+- name: "Unknown", relationship: "Sibling", description: "User mentioned a sibling but did not give a name", reason: "User said 'my brother' without further context"
+
+## Output Format
 
 \`\`\`json
 {
   "people": [
     {
-        "type_of_person": "The relationship from the list above",
-        "name_of_person": "The person's name",
-        "reason": "The justification of including this specific person"
+      "name": "The person's name, or 'Unknown' if not given",
+      "description": "1-2 sentences: who this person is and their role in the user's life",
+      "relationship": "Relationship type from the list above",
+      "reason": "Evidence from the conversation that justified flagging this person"
     }
   ]
 }
 \`\`\`
 
-**Return JSON only.**`;
-
-  const system = `${taskFragment}
-
-${specificNeedsFragment}
-
-${guidelinesFragment}
+**Return JSON only.**
 
-${criticalFragment}`;
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.`;
 
   const earlierSection = data.messages_context.length > 0
     ? `## Earlier Conversation
@@ -90,16 +82,17 @@ ${earlierSection}${recentSection}
 
 ---
 
-Scan the "Most Recent Messages" for PEOPLE mentioned by the human user.
+Scan the "Most Recent Messages" for PEOPLE in the human user's life.
 
 **Return JSON:**
 \`\`\`json
 {
   "people": [
     {
-        "type_of_person": "The relationship from the list above",
-        "name_of_person": "The person's name",
-        "reason": "The justification of including this specific person"
+      "name": "The person's name, or 'Unknown' if not given",
+      "description": "1-2 sentences: who this person is and their role in the user's life",
+      "relationship": "Relationship type from the list above",
+      "reason": "Evidence from the conversation that justified flagging this person"
     }
   ]
 }

package/src/prompts/human/person-update.ts

@@ -0,0 +1,241 @@
+import type { PromptOutput } from "./types.js";
+import type { Person, Message } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export interface PersonUpdatePromptData {
+  existing_item: Person | null;
+  new_person_name?: string;
+  new_person_description?: string;
+  new_person_relationship?: string;
+  messages_context: Message[];
+  messages_analyze: Message[];
+  persona_name: string;
+}
+
+function formatExistingPerson(person: Person): string {
+  return JSON.stringify({
+    name: person.name,
+    description: person.description,
+    sentiment: person.sentiment,
+    relationship: person.relationship,
+    exposure_current: person.exposure_current,
+    exposure_desired: person.exposure_desired,
+  }, null, 2);
+}
+
+export function buildPersonUpdatePrompt(data: PersonUpdatePromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildPersonUpdatePrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const nameSection = `The person's actual name, or the clearest available identifier.
+
+Only update when you learn something more specific.
+
+Examples: "Unknown woman" → "Carol", "Mom" → "Carol (Mom)", "David" → "David Kim"`;
+
+  const descriptionSection = `A concise summary of who this person is and how they relate to the HUMAN USER. Personas use this to recognize this person and engage meaningfully when they come up.
+
+## CRITICAL: Synthesize, don't accumulate
+
+Every update must **rewrite** the description as a current-state summary. Never append to it.
+
+**Good description**: "Borfinda, partner of 12 years. Former marine biologist, now stay-at-home parent. Tends to ground the user when they spiral; dry sense of humor. Two kids together."
+
+**Bad description**: "Borfinda was mentioned when the user talked about moving. In a later conversation she came up again during the work stress discussion. Most recently the user said she was supportive."
+
+The description should:
+- Capture who this person IS — their role, characteristics, relationship texture
+- Include what the HUMAN USER has revealed about them over time
+- Be useful to a persona who's never heard this person's name before
+- Read as a brief, confident summary — not a log of when they were mentioned
+
+The description should NOT:
+- Append "Most recently:", "Latest mention:", or any temporal marker
+- Accumulate a session-by-session history of every time this person came up
+- Speculate about the person based on thin evidence
+- Exceed 3-4 sentences under any circumstances
+
+**ABSOLUTELY VITAL**: Do **NOT** embellish — personas use their own voice. Record what the user actually said or demonstrated, not your interpretation of its emotional significance.`;
+
+  const relationshipSection = `## Relationship (\`relationship\`)
+
+How the HUMAN USER is currently related to this PERSON.
+
+Once known, this field changes infrequently — a "Father" may later be clarified to "Step-Father", but is unlikely to become "Uncle".
+
+Keep it concise and specific. Avoid vague labels.
+
+Examples: "Unknown" → "Coworker", "Mother" → "Step-Mother", "Fiance" → "Spouse", "AI Persona" → "AI Companion"`;
+
+  const exposureSection = `## Desired Exposure (\`exposure_desired\`)
+
+How much the HUMAN USER wants to talk about this PERSON.
+
+Scale of 0.0 to 1.0:
+- 0.0: Never wants to hear about this PERSON again
+- 0.5: Average amount of engagement
+- 1.0: This PERSON is the sole focus of their existence
+
+Do not make micro-adjustments. Close enough is OK.
+
+## Exposure Impact (\`exposure_impact\`)
+
+Not in the current data — but include it in your response.
+
+How much this conversation should count toward exposure tracking:
+- "high": Long, detailed conversation exclusively about this PERSON
+- "medium": Long OR detailed conversation about this PERSON
+- "low": The conversation touched on this PERSON briefly
+- "none": Only alluded to or hinted at`;
+
+  const currentDetailsSection = data.existing_item
+    ? `\`\`\`json
+${formatExistingPerson(data.existing_item)}
+\`\`\`
+
+You are UPDATING an existing PERSON.`
+    : `**NEW PERSON — NOT YET IN SYSTEM**
+
+You are CREATING a new PERSON from what was discovered:
+\`\`\`json
+{
+  "name": "${data.new_person_name ?? "Unknown"}",
+  "description": "${data.new_person_description ?? "Details unknown"}",
+  "relationship": "${data.new_person_relationship ?? "Unknown"}"
+}
+\`\`\`
+
+Return all fields based on what you find in the conversation.`;
+
+  const jsonTemplate = `{
+    "name": "...",
+    "description": "...",
+    "sentiment": 0.0,
+    "relationship": "Mother|Friend|Coworker|AI Companion|etc.",
+    "exposure_desired": 0.5,
+    "exposure_impact": "high|medium|low|none",
+    "quotes": [
+      {
+        "text": "exact phrase from message",
+        "reason": "why this matters"
+      }
+    ]
+  }`;
+
+  const system = `# Task
+
+You are scanning a conversation to deeply understand a PERSON in the HUMAN USER's life.
+
+Your job is to take that analysis and apply it to the record we already have **IF DOING SO WILL PROVIDE THE HUMAN USER WITH A BETTER EXPERIENCE IN THE FUTURE**.
+
+This means detail you add should:
+1. Be meaningful, accurate, or still true to the HUMAN USER in six months or more
+2. **NOT** already be present in the description or name of the PERSON
+
+This PERSON will be recorded in the HUMAN USER's profile for agents and personas to later reference.
+
+# Field Definitions
+
+## Name (\`name\`)
+${nameSection}
+
+## Description (\`description\`)
+${descriptionSection}
+
+## Sentiment (\`sentiment\`)
+
+How the HUMAN USER feels about this PERSON overall.
+
+Scale of -1.0 to 1.0:
+- -1.0: No PERSON is more despised
+- -0.5: Disliked or complicated relationship, but not without value
+- 0: Neutral or unknown
+- 0.5: Liked and valued
+- 1.0: The most important person in their life
+
+Do not make micro-adjustments. Close enough is OK.
+
+${relationshipSection}
+
+${exposureSection}
+
+## Quotes
+
+In addition to updating the PERSON, identify any **memorable, funny, important, or stand-out phrases** from the Most Recent Messages that relate to this PERSON.
+
+### What Makes a Quote Worth Preserving
+
+**Prioritize:**
+- Humor, wit, colorful language, creative profanity
+- Emotional outbursts (positive or negative) — the raw stuff
+- Phrases that reveal how the HUMAN USER feels about this PERSON
+- Things you'd quote back to them later to make them laugh or think
+- Unique expressions or turns of phrase about or from this PERSON
+- Quotable moments from EITHER speaker — humans AND AI personas both say memorable things
+
+**NEVER extract these — they are NOT quotes:**
+- Technical identifiers: ARNs, URLs, file paths, UUIDs, config keys
+- AI agent self-talk: "I notice I'm in Plan Mode", "I'll start by...", status updates
+- AI apologies or acknowledgments: "You're absolutely right", "I apologize for that"
+- Generic statements that could apply to anyone
+- Credentials, secrets, connection strings, or anything that looks like an access token
+
+**The litmus test**: Would you bring this up at a bar with a friend? Would it make someone laugh, think, or feel something?
+- "She's the only person who can make me feel simultaneously stupid and brilliant" → YES.
+- "Borfinda was mentioned in the context of the Minnesota discussion" → NO. That's a note, not a quote.
+
+**When in doubt, leave it out.** An empty quotes array is always acceptable.
+
+**CRITICAL**: Return the EXACT text as it appears in the message. **WE CAN ONLY USE IT IF WE FIND IT IN THE TEXT.**
+
+# CRITICAL INSTRUCTIONS
+
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.
+
+\`\`\`json
+${jsonTemplate}
+\`\`\`
+
+When returning a record, **ALWAYS** include \`name\`, \`description\`, and \`sentiment\`.
+
+If you find **NO EVIDENCE** of this PERSON in the "Most Recent Messages", respond with: \`{}\`
+
+If **NO CHANGES** are required, respond with: \`{}\`
+
+An empty object is the MOST COMMON expected response.
+
+# Current Details of PERSON
+
+${currentDetailsSection}
+`;
+
+  const earlierSection =
+    data.messages_context.length > 0
+      ? `## Earlier Conversation
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+      : "";
+
+  const recentSection = `## Most Recent Messages
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Analyze the Most Recent Messages and update the PERSON if warranted.
+
+**Return JSON:**
+\`\`\`json
+${jsonTemplate}
+\`\`\`
+
+If no changes are needed, respond with: \`{}\``;
+
+  return { system, user };
+}

package/src/prompts/human/topic-match.ts

@@ -0,0 +1,65 @@
+import type { PromptOutput } from "./types.js";
+
+export interface TopicMatchPromptData {
+  candidate_name: string;
+  candidate_description: string;
+  candidate_category: string;
+  existing_topics: Array<{
+    id: string;
+    name: string;
+    description: string;
+    category?: string;
+  }>;
+}
+
+export function buildTopicMatchPrompt(data: TopicMatchPromptData): PromptOutput {
+  if (!data.candidate_name) {
+    throw new Error("buildTopicMatchPrompt: candidate_name is required");
+  }
+
+  const system = `# Task
+
+You are checking if a TOPIC already exists in our database.
+
+## Matching Rules
+
+1. **Exact match**: Same name or concept → return its ID
+2. **Similar match**: Clearly the same topic with different wording → return its ID
+3. **No match**: Genuinely new information → return "new"
+
+Be conservative. If you're unsure, return "new" — a duplicate is worse than a gap.
+
+# Existing Topics
+
+\`\`\`json
+${JSON.stringify(data.existing_topics, null, 2)}
+\`\`\`
+
+# Response Format
+
+Return ONLY the ID of the matching entry, or "new".
+
+\`\`\`json
+{
+  "matched_guid": "uuid-of-matching-entry" | "new"
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const user = `# Candidate Topic
+
+Name: ${data.candidate_name}
+Description: ${data.candidate_description}
+Category: ${data.candidate_category}
+
+Find the best match in existing topics, or return "new" if this is genuinely new.
+
+\`\`\`json
+{
+  "matched_guid": "..." | "new"
+}
+\`\`\``;
+
+  return { system, user };
+}